You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Sep 23, 2025. It is now read-only.
Enhance code walkthrough design with Dialect integration
**Major Design Improvements:**
**Location System:**
- Flexible Location type supporting search, range, findReferences, findDefinitions
- Directory search capability for multi-file comments
- Symbol-based commenting via LSP integration
**Dialect Program Integration:**
- Walkthroughs are now executable Dialect programs
- Dynamic IDE operations embedded in walkthrough JSON
- Context-aware and adaptive to current code state
**Enhanced Grammar:**
- Cleaner location specification syntax
- Support for IDE capabilities like symbol lookup
- More powerful and flexible than regex-only positioning
**Benefits:**
- ✅ Dynamic walkthroughs that adapt to code changes
- ✅ IDE-integrated symbol-based comments
- ✅ Multi-file directory search capabilities
- ✅ Leverages existing Dialect language infrastructure
Ready for implementation of enhanced walkthrough system.
"I was not sure what the name of this function should be. Please double check it!"
43
39
],
44
40
},
45
-
46
-
// A "warning" is used to bring something to the user's attention that may be wrong.
47
-
"warning": {
48
-
"file": "src/foo.rs",
49
-
"regex": "panic!()",
50
-
"comment": [
51
-
"This function does not accept negative numbers."
52
-
],
53
-
},
54
-
55
-
// A "note" is used to bring something to the user's attention in a less forceful fashion.
56
-
"note": {
57
-
"file": "src/foo.rs",
58
-
"regex": "",
59
-
"comment": [
60
-
"This is the most important part of the function."
61
-
],
62
-
}
63
41
}
64
42
],
65
43
@@ -116,4 +94,123 @@ We begin with examples before defining the full structure. A *walkthrough* is de
116
94
}
117
95
```
118
96
119
-
## Walkthrough format
97
+
## Interaction
98
+
99
+
When the MCP tool is triggered, the Socratic Shell pane renders the given walkthrough.
100
+
It also renders a "clear" button to clear the current code review.
101
+
102
+
### Rendering the walkthrough
103
+
104
+
Markdown and mermaid are rendered in the "obvious" way.
105
+
106
+
Users can click on comments to be taken to the source code line.
107
+
Comments are also added using vscode's comment API.
108
+
109
+
Comments use regex-based positioning to locate the relevant code. When a regex matches multiple locations, the system presents a QuickPick to let the user navigate and select the intended location. If a user clicks on an ambiguous comment again, they get a chance to reselect in case they made a mistake. If they choose differently, the comment will be moved in the comment controller to the new location.
110
+
111
+
When a walkthrough is cleared or a new walkthrough is loaded, all existing comments are removed from the comment controller.
112
+
113
+
"gitdiff" elements are rendered as a tree:
114
+
115
+
* "all commits" (only if there's more than one)
116
+
* "file1.rs" (+/-) -- see changes made to file1.rs across all commits
117
+
* "file2.rs" (+/-) -- see changes made to file2.rs across all commits
118
+
* "sha1"
119
+
* "file1.rs" (+/-) -- see changes made to file1.rs in in commit sha1
120
+
* "sha2"
121
+
* "file2.rs" (+/-) -- see changes made to file2.rs in in commit sha2
122
+
123
+
Files that have comments added elsewhere also have a "discussion" icon.
124
+
Clicking on the icon.
125
+
126
+
### Actions
127
+
128
+
When the user clicks the action button, the given text is sent to the LLM using the [Ask Socratic Shell](./ask-socratic-shell.md) mechanism and the terminal is selected. To avoid triggering action, newlines are stripped from the string and replaced with spaces. Users can press enter themselves.
129
+
130
+
### Responding to comments
131
+
132
+
Each comment has a button on it that says "Reply".
133
+
134
+
Clicking that button sends text to the LLM using the [Ask Socratic Shell](./ask-socratic-shell.md) mechanism:
135
+
136
+
```
137
+
<context>In reply to comment on file.rs?regex (line XXX).</context>
138
+
```
139
+
140
+
and selects the terminal so that user can continue typing.
141
+
142
+
## Walkthrough format
143
+
144
+
Walkthroughs are a JSON value that contains four (optional) parts:
145
+
146
+
```
147
+
Walkthrough = {
148
+
("introduction": List)?,
149
+
("highlights": List)?,
150
+
("changes": List)?,
151
+
("actions": List)?
152
+
}
153
+
```
154
+
155
+
Each `List` is in fact a [Dialect program](./dialect-language.md) that can be executed to yield up a list of content items for rendering.
156
+
Dialect allows them to embed references to [IDE operations](./ide-capabilities.md) like finding references or definitions of symbols.
157
+
The grammar is as follows:
158
+
159
+
```
160
+
// Lists are in fact Dialect programs that can be directly executed
161
+
// to yield the final result.
162
+
List = "Markdown text" // shorthand for ["Markdown text"]
163
+
| [ ListElement* ] // series of rows
164
+
165
+
ListElement = "Markdown text" // render as markdown
166
+
| { // render an action
167
+
"action": {
168
+
"content": List, // show user this markdown
169
+
"button": "button text / icon", // render a button with this text
170
+
("tell_agent": "string")? // message to send to agent when button is clicked
171
+
}
172
+
}
173
+
| { // render a set of diffs from git
174
+
"gitdiff": {
175
+
"range": "...",
176
+
("exclude": {
177
+
("unstaged": boolean)?,
178
+
("staged": boolean)?
179
+
})?
180
+
}
181
+
}
182
+
| {
183
+
"comment": {
184
+
"location": Location,
185
+
("icon": "icon")?,
186
+
content: List
187
+
}
188
+
}
189
+
190
+
// Locations are dialect functions that yield lists of positions or ranges.
191
+
// If exactly one match is found, then the comment is placed on that line.
192
+
// If multiple matches are found, users are prompted to disambiguate when they click on the comment.
193
+
Location = { "search": { "path": "path", "regex": "regex to search for" } // if `path` is a directory, search all files within
194
+
| { "range": { "path": "path", line: number, (column:number)? } } // a range of text
195
+
| { "findReferences": "MyClass" } // comment on reference(s) to MyClass
196
+
| { "findDefinitions": "MyClass" } // comment on definition(s) of MyClass
197
+
```
198
+
199
+
The final resulting datastructures in a List are as follows:
200
+
201
+
* Each list element is a Dialect value that evaluates to itself (e.g., `comment`).
202
+
* Locations are a list of *locations*, which is a JSON struct like `{file:"filename", line, column}`. They may have additional fields.
203
+
204
+
## Future Extensions
205
+
206
+
### Mermaid diagrams
207
+
208
+
Support for mermaid diagrams in walkthrough content:
209
+
210
+
```json
211
+
{
212
+
"mermaid": "graph TD; A-->B; B-->C;"
213
+
}
214
+
```
215
+
216
+
This would render interactive diagrams within walkthroughs for visualizing architecture, flows, or relationships.
0 commit comments