merge xref report: baseline, --check, self-test

1 files changed, 19 insertions, 28 deletions

diff --git a/TODO.md b/TODO.md
index 210b4a3..fcb4e88 100644
--- a/TODO.md
+++ b/TODO.md
@@ -416,34 +416,25 @@ of the open list.
   text); return; }`. open: whether the keyword handler can decline when the
   next token is not a string (so `test` stays usable as a name). diagnostics
   print `zc: line N:` with no file name.
-- compiler cross-reference report (`agents/xref-report`, one wip commit
-  e5d5136). done: `src/tools/xref.js` and `src/tools/xref.sh` (`--help`,
-  unknown option exits 2). the language server has no documentSymbol, so the
-  globals come from the tool's own parse of the joined compiler source (652
-  globals, 628 functions, nothing left unparsed); writers and readers come from
-  one zclsp references request per global over 4 parallel servers. one full run
-  finished in 11m53s (about 2.5 s per request, about 30 s per server to check
-  the document); its output is in the zip at `agents/xref-report/xref-out/`
-  (report.txt, report.json), not yet reviewed by a person. top 15 globals by
-  number of writer functions, read off that json by the coordinator: xty 29,
-  xbor 23, xfloat 22, lv 21, xaf 21, lvk 20, xvk 19, ltag 17, xzero 17,
-  lstate 16, sflag 16, effect_value 15, fslots 13, panic 13, chkabort 12 (these
-  are the first candidates for the "group the parallel arrays" item). 60
-  globals show no writer and 198 no reader (many are `_cap` twins); some of the
-  "no writer" ones are the known limits below, so check before trusting them.
-  written but never run: the `make xref` target, the README and ONBOARD.md
-  sections, the xref.sh entry in `tests/drivers/cli_help_test.py`. not done:
-  `tests/xref.baseline` (derive it from report.json, one line per global with
-  its sorted writers, or run `xref.sh --update` in the background), `--check`
-  and `--update` never run, the self-test (copy src/compiler to a scratch dir,
-  add one write to a global in another function, `xref.sh --compiler-dir DIR
-  --out SCRATCH --check` must exit 1), README says "minutes" where it should
-  say about 12 minutes. known limits: a store through a pointer (`*p = ...`),
-  an array written by a callee (`copy_w`, `memset`) and a global reached only
-  through its `_initial` array are not counted as writes. next: baseline,
-  `--check` (expect 0), self-test, `python3 tests/drivers/cli_help_test.py
-  --group scripts`, commit. a 12 minute run is too slow for every ci job; run
-  it nightly or only when `src/compiler/` changes.
+- compiler cross-reference report (`agent/xref-report`, cherry-picked onto
+  work/xref without conflicts). done: `src/tools/xref.js` and
+  `src/tools/xref.sh` (`--help`, unknown option exits 2), the `make xref`
+  target, the readme and onboard.md sections, and the xref.sh entry in
+  `tests/drivers/cli_help_test.py` (passes with `--group scripts`).
+  `tests/xref.baseline` is checked in, written by `xref.sh --update` (658
+  globals, 633 functions, one line per global with its sorted writers); a run
+  took about 10 s with 8 servers, not 12 minutes, so the readme now says tens
+  of seconds. `--check` against it exits 0, and exits 1 when one writer is
+  dropped from one baseline line. `src/tools/xref_selftest.sh [server]` does
+  both cases in a scratch directory and runs in the lsp section of
+  `tests/test.sh` next to the other node drivers (not in -q). known limits: a
+  store through a pointer (`*p = ...`), an array written by a callee
+  (`copy_w`, `memset`) and a global reached only through its `_initial` array
+  are not counted as writes. the baseline is not yet reviewed by a person;
+  the 60 "no writer" globals still need checking against those limits. open:
+  a self-test that adds a real write to a copy of src/compiler and runs
+  `--compiler-dir`, and deciding whether ci runs it on every job or only
+  when `src/compiler/` changes.
 
 ### decisions
 - no structs in zc0 (owner's call): zc0 stays the small trusted root of the