1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
# Language intelligence in pardes
Three things landed together, and only the first two are permanent:
1. **An async execution model.** The core stays a state machine; slow work goes
to a worker and comes back as an event.
2. **A helix-exact keymap** for every LSP command.
3. **A seam** (`src/lsp.zig`) with exactly one function behind it, so competing
backends can be swapped, measured, and thrown away.
## The async model
There was none before this: every effect the core emitted was fire-and-forget
(`spawn`, `write`, `save_file`) or instantaneous. A language query is the first
thing pardes asks for that *answers later*, so it needed a request/response
shape — and got the smallest one that works.
```
core shell worker
| Effect .lsp{id,kind, | |
| pane,offset,arg} | |
|-------------------------->| |
| | snapshot path + content |
| |--------------------------->|
| | | lsp.query(...)
| | Event .lsp_resp{id,rows}|
|<--------------------------|<---------------------------|
| lspResponse -> jump, or open a results buffer |
```
The shell already ran this exact pattern for pty readers, so the async part is
about thirty lines per shell: `tty.zig` uses `io.concurrent` + the vaxis loop
queue, `gui.zig` uses a detached thread + the mutex queue it already had. The
web shell has no threads and no-ops the effect.
Three rules make it safe:
- **The worker never touches the core.** Path, source, arg and root are copied
into an `LspJob` before it starts (`tty.zig`). The user keeps typing while a
query is in flight; a borrowed slice would be a use-after-free the length of
one keystroke.
- **One query in flight, identified by a monotonic id.** A second press bumps
the id, which makes the older answer stale — `lspResponse` drops any id it is
not waiting for. This is also what makes a closed pane safe.
- **No rows is a legal answer.** A backend that cannot answer appends nothing,
which is indistinguishable from a language server still starting up, and the
core does nothing. There is no error path to render.
## Results are `+Search` rows
Every backend renders into one format:
```
/abs/path/to/file.zig:LINE:COL text
```
1-based line and column, absolute path. This is the format `look.zig` already
resolves, `runSearch` already produces and `n`/`N` already step — so:
- **one row from a goto** → jump straight there (`actOnSelection`)
- **several rows** → an output buffer, which `n`/`N` walk
which means helix's multi-result picker required **no picker code at all**. The
`+Search` buffer *is* the picker. Kinds whose answer is prose rather than
locations (`hover`, `code_action`, `format`, `rename`) open `+Hover`/`+Lsp`
instead and do not arm the stepper — `n` over a documentation blurb would step
to nowhere.
## The keymap is helix's, exactly
Verified against `helix-term/src/keymap/default.rs`, not from memory.
| keys | command | notes |
|---|---|---|
| `gd` | definition | jumps on a single result, lists on several |
| `gD` | declaration | |
| `gy` | type definition | |
| `gi` | implementation | |
| `gr` | references | |
| `SPC k` | hover | opens `+Hover` |
| `SPC r` | rename | tag input, like Find/Grep |
| `SPC a` | code action | |
| `SPC h` | select references | |
| `SPC s` / `SPC S` | document / workspace symbols | `S` takes a query |
| `SPC d` / `SPC D` | document / workspace diagnostics | |
| `]d` / `[d` | next / prev diagnostic | steps the list, asks for one if absent |
| `]D` / `[D` | last / first diagnostic | |
| `=` | format | |
`g` and `[`/`]` had **no conflicts** — `gd/gD/gy/gi/gr` and `]d/[d` were all
free. The `SPC` letters were not, so pardes's own builtins moved out of helix's
way rather than the reverse:
| builtin | was | now | why |
|---|---|---|---|
| Kill | `SPC k` | `SPC q` | `k` is hover; `q` is quit everywhere else |
| Del | `SPC d` | `SPC w c` | `d` is diagnostics; closing a pane IS a window op, and `c` is helix's own spelling for close in its window mode |
| Dump | `SPC s d` | `SPC f d` | `s` is symbols; writing a session file is a file operation |
| Restore | `SPC s r` | `SPC f r` | same |
| Tutor | `SPC h t` | `SPC T` | frees `h` for select-references |
A three-exception muscle-memory map is not a map. That is the whole argument.
`K` is **not** hover — in helix it is `keep_selections`. It was checked; do not
"fix" it.
## Writing a backend
`src/lsp.zig` is the seam. An implementation supplies three things and touches
nothing else:
```zig
pub fn query(gpa, arena, req: Req, out: *std.ArrayList(u8)) void
pub const supports: std.EnumSet(Kind)
pub const backend_name = "..."
```
`query` runs on a worker thread with no access to the core — everything it may
read is in `req` (`path`, `source` (NUL-terminated), `offset`, `arg`, `root`).
`arena` is freed wholesale on return; `gpa` owns only what goes into `out`.
Use `lsp.row()` to emit a location and `lsp.lineCol()` to convert an offset,
so every backend's rows are byte-identical in shape.
## How the implementations are judged
`zig build lspbench` — same harness, same corpus (pardes's own `src/`), same 17
probes, every backend.
- **Feature completeness.** Which kinds return rows, and whether the rows
contain what they should. The harness trusts *results*, not the `supports`
flag: a kind claimed but returning nothing is reported as `CLAIMED-EMPTY`,
and a kind that answers without claiming is `unclaimed-works`. Correctness
is a substring the rows must contain, so returning a confident wrong location
scores worse than returning nothing.
- **Latency.** `cold` (first query, index construction included) and `warm`
(median of 20). They differ by orders of magnitude for an indexing backend
and both matter: cold is what the first keypress costs, warm is what every
one after it costs.
- **Memory.** Peak RSS delta (`VmHWM`), so a backend that frees its index
before returning still pays for having built it.
- **Lines of code.** Not measured by the harness — it is `jj diff --stat`
against the base commit. Less is better, and vendoring a library is not free
but is charged in build time and dependency surface rather than in lines we
maintain.
Run `zig build lspbench -- --json` for machine-readable output.
|
