Showcase: tiered diagnostics with the index-memory fixes merged in

AGENTS.md

@@ -16,6 +16,16 @@ Build & test (development)
 # V struct JSON attributes
 - Use `@[json]` attributes only when a field name does not exactly match the JSON name.
 
+# Rewording a commit that is not HEAD
+- Do not use `git rebase -i`: this host runs the sequence editor through `sh`, so
+  `%1` never expands and the rebase dies with "there was a problem with the editor".
+- The reliable path is a temp branch plus a replay, which needs no force-push:
+  `git checkout -b tmp <sha>`, `git commit --amend -F msg.txt` there, then
+  `git rebase --onto tmp <old-sha> feat/<branch>` and `git branch -D tmp`.
+- Always run `git add` and `git commit` sequentially, never as parallel tool calls:
+  two parallel calls race and one commit ends up holding both tracks' files, which
+  then needs the reword above. After grouping, verify with `git log --stat -1`.
+
 Mandatory guardrails (enforced for all agent work)
  - Add `2>&1` to commands so all output is captured.
  - Keep `.md` lines ≤ 100 characters.

COMPARISON.md

@@ -0,0 +1,92 @@
+# Language-server comparison: gopls, rust-analyzer, zls vs vls
+
+Why these three: Go is V's syntactic parent, Rust is the
+aspirational maturity target, Zig is the closest lifecycle
+peer (young systems language, breaking compiler).
+
+## Architecture
+
+- gopls: per-package summaries, persistent file cache,
+  pruned invalidation (skip importers when exports
+  unchanged). Two-tier diagnostics (instant + deferred vet).
+- rust-analyzer: Salsa queries over ItemTree/DefMap/Body;
+  laziness first, incrementality second; proc-macros and
+  flycheck out-of-process; per-request cancellation.
+- zls: per-file `std.zig.Ast` + heuristic semantics (no
+  full comptime); strict 1:1 version lock with Zig; custom
+  build runner; opt-in build-on-save via a `check` step.
+- vls: per-file token index + full project re-check;
+  shell-free compiler argv + overlay; scheduler + pool
+  of max 3 diagnostic servers; index-first fallbacks.
+
+## Feature gap summary
+
+Measured against the tree as of the last pass over it. What this
+branch closed is marked; what stands is kept as it was found.
+
+- Incrementality: all three peers beat vls (export
+  summaries / Salsa / per-module units vs full re-check).
+  Still open — a change confined to a function body now
+  checks that file's module rather than the whole tree,
+  and a slow check is reused from a per-program
+  fingerprint cache, but the unit of re-check is still a
+  program, not an item.
+- Diagnostics tiers: peers split fast/slow. **Closed** —
+  each edit schedules a fast index-only check (150ms
+  debounce) and the full compiler check (800ms idle),
+  and the slow answer replaces the fast one.
+- Refactors: gopls and rust-analyzer offer extract/inline/
+  fill/struct assists with safety checks; vls has 2 actions
+  (remove unknown import, contiguous organizeImports).
+  **Closed** — ten actions, all gated on a kind filter and
+  a shape check: quick fixes for a diagnostic, organize
+  imports, fill struct literal, extract or inline a
+  variable, extract function, add an import, implement
+  missing members, move a declaration to a module of its
+  own, and structural search and replace.
+- Rename safety: gopls checks shadowing + interface
+  satisfaction; vls refuses on incomplete scope only.
+  **Closed** — rename refuses names that shadow a binding
+  or break an interface, and renames an interface's
+  members across its implementors.
+- Config: zls layers editor > `zls.json` (+ schema) >
+  per-build file; vls relies on `VLS_V_COMMAND`/`VFLAGS`.
+  **Closed** — editor settings > project `vls.json` >
+  `VLS_DEFINES`, with the schema published and defines
+  salted into the diagnostics fingerprint.
+- Compat: zls chose lockstep; vls probes compiler modes
+  (`unknown/direct/compat/missing`) for a version range.
+  Still true, and the missing-compat case is reported
+  rather than answered emptily.
+
+## Criticism (what to fix, in roadmap order)
+
+1. No real incrementality — the cached answer is per
+   program and per fingerprint, not per item.
+2. One-tier diagnostics — **closed** by the two-tier
+   scheduler above.
+3. Index masks compiler gaps instead of measuring them —
+   still open.
+4. Refactors are text edits, not semantic operations —
+   still open for the text edits; the structural replace
+   is deliberately scope-negative and refuses rather than
+   guesses, and rename now checks the scope it moves into.
+5. Config is env-var folklore (`VFLAGS`-in-shell) —
+   **closed** by layered configuration.
+6. Dispatched stubs (inlineValue literals-only,
+   same-line linkedEditing, empty onTypeFormatting) —
+   **closed**; all three are implemented and advertised.
+7. No perf budget or observability story — partly closed:
+   `VLS_PERF_LOG=1` logs a per-stage breakdown of a slow
+   check, first measurement being the compiler run at 97
+   percent of it. A budget is still undecided.
+
+## Sources
+
+- https://go.dev/gopls/ and /features/, /workspace/, /settings/
+- https://go.dev/blog/gopls-scalability
+- https://rust-analyzer.github.io/book/ (features, assists,
+  diagnostics, architecture, non_cargo_based_projects)
+- https://github.com/zigtools/zls and https://zigtools.org/zls/
+- vls tree: index.v, interop.v, diagnostics_scheduler.v,
+  diagnostics_server.v, handlers.v, main.v, v3_line_info.v

README.md

@@ -2,6 +2,9 @@
 
 Build with: `v .`
 
+Or let the compiler install it for you: `v ls --install` (see `v help ls`
+for update and source-build options).
+
 Check the installed version with `vls --version` or `vls version`. Both print `VLS 0.0.3`
 and exit without starting the server. LSP `initialize` reports the same version in `serverInfo`.
 
@@ -76,39 +79,73 @@ also visualize line coverage; set `v.vls.coverage.enabled` to `false` to turn th
 ### Code behind a compile-time flag
 
 V compiles the code inside `$if flag ? { ... }` only when the program is built with `-d flag`.
-VLS runs the compiler without defines, so that code is not checked: it gets no errors, and hover
-and go-to-definition find little or nothing in it. V adds the options in the `VFLAGS` environment
-variable to every command, so set it where VLS runs to work on such a block. For example, close
-the editor and start it again from a shell:
+VLS runs the compiler without defines, so that code used to get no errors, and hover and
+go-to-definition found little or nothing in it. It now checks that code when the flag is given.
+
+Set `vls.defines` in the editor's settings for VLS, naming the flag the code uses:
+
+```json
+"vls.defines": ["-d", "flag"]
+```
+
+The joined spelling, `["-dflag"]`, is accepted too. To keep the flag with the project rather than
+in the editor, put a `vls.json` in the folder that holds the nearest `v.mod`:
+
+```json
+{ "defines": ["-d", "flag"] }
+```
+
+A `vls.json` may also set `inlayHints`, `diagnostics` and `coverageDirectory`. The settings
+the editor sends win over the project's file, and the file over `VLS_DEFINES` in the environment,
+which also works for an editor with no settings of its own. The nearest `vls.json` is read when a
+file of its project is opened, so its switches apply before the first check rather than after it.
+The keys the file accepts are listed in [`vls.schema.json`](vls.schema.json). The defines reach
+the checks only: `v fmt`, hover, go-to-definition and completion run without them. The code inside
+`$if !flag ? { ... }` is then the one left unchecked.
+
+### Generating tests for untested functions
+
+A coverage recording is what tells VLS which functions a test run never entered. Record one, then
+point the project at it:
 
 ```sh
-VFLAGS='-d flag' code .
+v -no-skip-unused -coverage vcov/ test ./
 ```
 
-In Sublime Text, add `"VFLAGS": "-d flag"` to the `env` of its server configuration. The code
-inside `$if !flag ? { ... }` is then the one left unchecked.
+```json
+{ "coverageDirectory": "vcov" }
+```
+
+`coverageDirectory` may also be sent by the editor as `vls.coverageDirectory`, which wins over the
+file. With it set, a `.v` file whose functions were never entered offers a code action per
+function: `Generate test for 'foo'`. The action runs `v cover --write-tests`, which appends one
+`test_foo()` beside the source with a zero-value call and a `// TODO:` line. It is a starting
+point, not a test: the generator cannot know what the function should return.
+
+`-no-skip-unused` belongs with the recording. Without it a function nothing calls is dropped from
+the build, so its coverage cannot be reported at all.
 
 ### Features
 
 #### Instant errors
 
-<img width="1932" height="432" alt="image" src="https://github.com/user-attachments/assets/a842e103-b3c2-427f-956f-fffff07970dc" />
+![image](https://github.com/user-attachments/assets/a842e103-b3c2-427f-956f-fffff07970dc)
 
 #### Go to definition
 
 https://github.com/user-attachments/assets/fb4ee6ff-4765-46b7-a21e-267691253d8e
 
 #### Autocomplete for module functions
 
-<img width="1246" height="592" alt="image" src="https://github.com/user-attachments/assets/0d4e1849-2e6c-47f8-9a45-322fe25d9bef" />
+![image](https://github.com/user-attachments/assets/0d4e1849-2e6c-47f8-9a45-322fe25d9bef)
 
 #### Information about function parameters
 
-<img width="1494" height="450" alt="image" src="https://github.com/user-attachments/assets/46cc391b-fcdc-4083-ab62-97edd815ddd9" />
+![image](https://github.com/user-attachments/assets/46cc391b-fcdc-4083-ab62-97edd815ddd9)
 
 #### Autocomplete for struct fields and methods
 
-<img width="1804" height="392" alt="image" src="https://github.com/user-attachments/assets/478bfd20-201a-476f-88cd-583fad52d6cc" />
+![image](https://github.com/user-attachments/assets/478bfd20-201a-476f-88cd-583fad52d6cc)
 
 ### Zed