Skip to content

Commit 7eb3d75

Browse files
observerwobserverw
committed
feat(web): add draft doc
1 parent 344285d commit 7eb3d75

File tree

8 files changed

+292
-164
lines changed

8 files changed

+292
-164
lines changed

‎web/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"private": true,
66
"scripts": {
77
"dev": "vite",
8+
"predev": "mkdir -p public/docs && cp -r ../docs/schemas public/docs/",
89
"prebuild": "mkdir -p public/docs && cp -r ../docs/schemas public/docs/",
910
"build": "vite build",
1011
"preview": "vite preview"

‎web/public/docs/schemas/completion.md‎

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,12 @@ The Completion API (IntelliSense) provides context-aware code suggestions at a s
44

55
## CompletionRequest
66

7-
| Field | Type | Default | Description |
8-
| :-------------- | :------------------------------------------------------- | :------- | :------------------------------------------ |
9-
| `locate` | [`LocateText`](locate.md) \| [`LocateSymbol`](locate.md) | Required | Where to trigger the completion. |
10-
| `max_items` | `number \| null` | `15` | Maximum number of suggestions to return. |
11-
| `start_index` | `number` | `0` | Number of items to skip. |
12-
| `pagination_id` | `string \| null` | `null` | Token to retrieve the next page of results. |
13-
14-
> [!TIP]
15-
> To trigger completion after a dot (e.g., `user.`), use [`LocateText`](locate.md) with `find="user."` and `find_end="end"`.
7+
| Field | Type | Default | Description |
8+
| :-------------- | :------------------------ | :------- | :------------------------------------------ |
9+
| `locate` | [`Locate`](locate.md) | Required | Where to trigger the completion. |
10+
| `max_items` | `number \| null` | `15` | Maximum number of suggestions to return. |
11+
| `start_index` | `number` | `0` | Number of items to skip. |
12+
| `pagination_id` | `string \| null` | `null` | Token to retrieve the next page of results. |
1613

1714
## CompletionResponse
1815

@@ -33,6 +30,7 @@ The Completion API (IntelliSense) provides context-aware code suggestions at a s
3330
| `kind` | `string` | Type (Method, Property, Class, etc.). |
3431
| `detail` | `string?` | Short info like signature or type. |
3532
| `documentation` | `string?` | Full markdown documentation for the item. |
33+
| `insert_text` | `string?` | The actual snippet that would be inserted.|
3634

3735
## Example Usage
3836

@@ -44,9 +42,7 @@ The Completion API (IntelliSense) provides context-aware code suggestions at a s
4442
{
4543
"locate": {
4644
"file_path": "src/main.py",
47-
"line": 15,
48-
"find": "client.",
49-
"find_end": "end"
45+
"find": "client."
5046
},
5147
"max_items": 5
5248
}
@@ -70,6 +66,11 @@ Establishes a connection to the server using the configured credentials. Returns
7066

7167
---
7268

69+
> [!TIP]
70+
> More results available. Use `start_index` to fetch more.
71+
72+
---
73+
7374
> [!TIP]
7475
> Use these symbols to construct your next code edit. You can focus on a specific method to get more details.
7576
```
@@ -82,9 +83,7 @@ Establishes a connection to the server using the configured credentials. Returns
8283
{
8384
"locate": {
8485
"file_path": "src/api.py",
85-
"line": 42,
86-
"find": "response.",
87-
"find_end": "end"
86+
"find": "response."
8887
},
8988
"max_items": 10,
9089
"start_index": 0
@@ -116,6 +115,11 @@ Returns the response body parsed as JSON. Raises JSONDecodeError if invalid.
116115

117116
> [!TIP]
118117
> Use `pagination_id="abc123"` to fetch more suggestions.
118+
119+
---
120+
121+
> [!TIP]
122+
> Use these symbols to construct your next code edit. You can focus on a specific method to get more details.
119123
```
120124

121125
### Scenario 3: No completion suggestions available
@@ -126,9 +130,7 @@ Returns the response body parsed as JSON. Raises JSONDecodeError if invalid.
126130
{
127131
"locate": {
128132
"file_path": "src/main.py",
129-
"line": 100,
130-
"find": "unknown_var.",
131-
"find_end": "end"
133+
"find": "unknown_var."
132134
}
133135
}
134136
```

‎web/public/docs/schemas/locate.md‎

Lines changed: 100 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -2,70 +2,137 @@
22

33
The Locate API provides a unified way to specify a position or range in the codebase. It is used as a base for many other requests like [`SymbolRequest`](symbol.md), [`ReferenceRequest`](reference.md), and [`CallHierarchyRequest`](call_hierarchy.md).
44

5-
## LocateRequest
5+
## Locate
6+
7+
The `Locate` model uses a two-stage approach: **scope** (optional) → **find** (optional, but at least one required).
8+
9+
### Resolution Rules
10+
11+
1. **SymbolScope without find**: Returns the symbol declaration position (for references, rename)
12+
2. **With find containing marker**: Returns the marker position
13+
3. **With find only**: Returns the start of matched text
14+
4. **No scope + find**: Searches the entire file
15+
16+
### Locate Fields
17+
18+
| Field | Type | Default | Description |
19+
| :---------- | :-------------------------------------- | :--------- | :--------------------------------------------------------------- |
20+
| `file_path` | `string` | Required | Path to search in. |
21+
| `scope` | `LineScope` \| `SymbolScope` \| `null` | `null` | Optional: narrow search to symbol body or line range. |
22+
| `find` | `string` \| `null` | `null` | Text pattern with marker for exact position. |
23+
| `marker` | `string` | `"<HERE>"` | Position marker in find pattern. Change if source contains `"<HERE>"`. |
24+
25+
### LineScope
26+
27+
| Field | Type | Description |
28+
| :----- | :-------------------------------- | :----------------------------------- |
29+
| `line` | `number` \| `[number, number]` | Line number or (start, end) range (1-based). |
30+
31+
### SymbolScope
632

7-
One of `LocateText` or `LocateSymbol`.
33+
| Field | Type | Description |
34+
| :------------ | :--------- | :------------------------------------------------------- |
35+
| `symbol_path` | `string[]` | Symbol hierarchy, e.g., `["MyClass", "my_method"]`. |
836

9-
### LocateText
37+
## LocateRange
1038

11-
Finds a position based on a text search.
39+
For selecting a range of text instead of a point.
1240

13-
| Field | Type | Default | Description |
14-
| :---------- | :--------------------------- | :-------- | :-------------------------------------------- |
15-
| `file_path` | `string` | Required | Path to search in. |
16-
| `line` | `number \| [number, number]` | `null` | Specific line number or range `[start, end]`. |
17-
| `find` | `string` | Required | String snippet to find. |
18-
| `find_end` | `"start" \| "end"` | `"end"` | Match the start or end of the snippet. |
41+
| Field | Type | Default | Description |
42+
| :---------- | :-------------------------------------- | :--------- | :------------------------------------------------ |
43+
| `file_path` | `string` | Required | Path to search in. |
44+
| `scope` | `LineScope` \| `SymbolScope` \| `null` | `null` | Scope defines the range; if symbol, uses symbol's full range. |
45+
| `find` | `string` \| `null` | `null` | Text to match; matched text becomes the range. |
1946

20-
### LocateSymbol
47+
## LocateRequest
48+
49+
| Field | Type | Description |
50+
| :------- | :-------- | :---------------------------- |
51+
| `locate` | `Locate` | The location to find. |
2152

22-
Finds a position based on a symbol path.
53+
## LocateRangeRequest
2354

24-
| Field | Type | Default | Description |
25-
| :------------ | :--------- | :------- | :-------------------------------------------- |
26-
| `file_path` | `string` | Required | Path to search in. |
27-
| `symbol_path` | `string[]` | Required | Hierarchy list (e.g., `["Class", "Method"]`). |
55+
| Field | Type | Description |
56+
| :------- | :----------- | :---------------------------- |
57+
| `locate` | `LocateRange`| The range to locate. |
2858

2959
## LocateResponse
3060

31-
| Field | Type | Description |
32-
| :---------- | :--------- | :---------------------------------------------- |
33-
| `file_path` | `string` | Resolved file path. |
34-
| `position` | `Position` | The coordinates (line, character) of the match. |
61+
| Field | Type | Description |
62+
| :---------- | :--------- | :-------------------------------------------------------- |
63+
| `file_path` | `string` | Resolved file path. |
64+
| `position` | `Position` | The coordinates (line, character) of the match. |
3565

3666
## Common Types
3767

3868
### Position
3969

4070
| Field | Type | Description |
4171
| :---------- | :------- | :-------------------------- |
42-
| `line` | `number` | 0-indexed line number. |
43-
| `character` | `number` | 0-indexed character offset. |
72+
| `line` | `number` | 1-based line number. |
73+
| `character` | `number` | 1-based character offset. |
4474

4575
### Range
4676

47-
| Field | Type | Description |
48-
| :------ | :--------- | :-------------------------- |
49-
| `start` | `Position` | Start position (inclusive). |
50-
| `end` | `Position` | End position (exclusive). |
77+
| Field | Type | Description |
78+
| :------ | :--------- | :---------------------------- |
79+
| `start` | `Position` | Start position (inclusive). |
80+
| `end` | `Position` | End position (exclusive). |
5181

5282
## Example Usage
5383

54-
### Request (LocateText)
84+
### Scenario 1: Finding a symbol declaration
85+
86+
```json
87+
{
88+
"locate": {
89+
"file_path": "foo.py",
90+
"scope": {
91+
"symbol_path": ["MyClass"]
92+
}
93+
}
94+
}
95+
```
96+
97+
### Scenario 2: Completion trigger point (with marker)
98+
99+
```json
100+
{
101+
"locate": {
102+
"file_path": "foo.py",
103+
"find": "self.<HERE>"
104+
}
105+
}
106+
```
107+
108+
### Scenario 3: Using custom marker (when source contains "<HERE>")
109+
110+
```json
111+
{
112+
"locate": {
113+
"file_path": "foo.py",
114+
"find": "x = <|>value",
115+
"marker": "<|>"
116+
}
117+
}
118+
```
119+
120+
### Scenario 4: Finding a location within a specific symbol
55121

56122
```json
57123
{
58124
"locate": {
59-
"file_path": "src/main.py",
60-
"line": [10, 50],
61-
"find": "def my_func",
62-
"find_end": "start"
125+
"file_path": "foo.py",
126+
"scope": {
127+
"symbol_path": ["process"]
128+
},
129+
"find": "return <HERE>result"
63130
}
64131
}
65132
```
66133

67-
### Markdown Rendered for LLM
134+
#### Markdown Rendered for LLM
68135

69136
```markdown
70-
Located `src/main.py` at 12:5
137+
Located `foo.py` at 42:10
71138
```

‎web/public/docs/schemas/reference.md‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,21 @@ The Reference API finds all locations where a specific symbol is used across the
44

55
## ReferenceRequest
66

7-
| Field | Type | Default | Description |
8-
| :---------------- | :------------------------------------------------------- | :------- | :--------------------------------------------------- |
9-
| `locate` | [`LocateText`](locate.md) \| [`LocateSymbol`](locate.md) | Required | The symbol to find references for. |
10-
| `mode` | `"references" \| "implementations"` | `"references"` | Whether to find references or concrete implementations. |
11-
| `context_lines` | `number` | `2` | Number of lines around the match to include. |
12-
| `include_hover` | `boolean` | `true` | Whether to include docs for each reference. |
13-
| `include_code` | `boolean` | `true` | Whether to include code snippets for each reference. |
14-
| `max_items` | `number \| null` | `null` | Maximum number of references to return. |
15-
| `start_index` | `number` | `0` | Number of items to skip for pagination. |
16-
| `pagination_id` | `string \| null` | `null` | Token to retrieve the next page of results. |
7+
| Field | Type | Default | Description |
8+
| :---------------- | :-------------------------- | :------------ | :--------------------------------------------------- |
9+
| `locate` | [`Locate`](locate.md) | Required | The symbol to find references for. |
10+
| `mode` | `"references"` \| `"implementations"` | `"references"` | Whether to find references or concrete implementations. |
11+
| `context_lines` | `number` | `2` | Number of lines around the match to include. |
12+
| `max_items` | `number \| null` | `null` | Maximum number of references to return. |
13+
| `start_index` | `number` | `0` | Number of items to skip for pagination. |
14+
| `pagination_id` | `string \| null` | `null` | Token to retrieve the next page of results. |
1715

1816
## ReferenceResponse
1917

2018
| Field | Type | Description |
2119
| :-------------- | :------------------- | :------------------------------------------------ |
2220
| `request` | `ReferenceRequest` | The original request. |
23-
| `items` | `ReferenceItem[]` | List of locations where the symbol is referenced. |
21+
| `items` | `ReferenceItem[]` | List of locations where the symbol is referenced. |
2422
| `start_index` | `number` | Offset of the current page. |
2523
| `max_items` | `number?` | Number of items per page (if specified). |
2624
| `total` | `number?` | Total number of references (if available). |
@@ -33,7 +31,7 @@ The Reference API finds all locations where a specific symbol is used across the
3331
| :---------- | :----------------- | :------------------------------------------------------ |
3432
| `file_path` | `string` | Relative path to the file. |
3533
| `line` | `number` | 1-based line number. |
36-
| `code` | `string` | Surrounding code snippet. |
34+
| `code` | `string` | Surrounding code snippet. |
3735
| `symbol` | `SymbolInfo \| null`| The symbol containing this reference (optional). |
3836

3937
## Example Usage
@@ -46,7 +44,9 @@ The Reference API finds all locations where a specific symbol is used across the
4644
{
4745
"locate": {
4846
"file_path": "src/utils.py",
49-
"symbol_path": ["format_date"]
47+
"scope": {
48+
"symbol_path": ["format_date"]
49+
}
5050
},
5151
"max_items": 10
5252
}
@@ -88,7 +88,9 @@ return {"date": format_date(obj.created_at)}
8888
{
8989
"locate": {
9090
"file_path": "src/base.py",
91-
"symbol_path": ["DatabaseConnection", "connect"]
91+
"scope": {
92+
"symbol_path": ["DatabaseConnection", "connect"]
93+
}
9294
},
9395
"mode": "implementations",
9496
"max_items": 5

0 commit comments

Comments
 (0)