docs: five citations refreshed to the lines the code is on, and a call-site citation is no longer called stale #1664

Merged
jaylouisw merged 2 commits from fix/1116-1235 into main 2026-11-16 12:57:56 +00:00
Owner

Closes no issue: the open queue is 21 device requests plus #1507 (a host decision for Jay), and this is the #1481 class - a citation that points at code which has moved.

Five stale line numbers, refreshed. node scripts/check-doc-citations.js reported seven suspects; five were real, and each new number was checked against the symbol before committing:

doc symbol cited actually at
docs/BGP-POLICY.md:76 _help() cli.js:4305 cli.js:4863
docs/BGP-POLICY.md:819 _help() cli.js:4305 cli.js:4863
docs/SIMULATION.md:558 openFlow() simulator.js:3709 simulator.js:3826
docs/UPSTREAM-DESIGN.md:71 _deliver() simulator.js:2908 simulator.js:2976
docs/UPSTREAM-DESIGN.md:442 serialize() link.js:56 link.js:112
docs/UPSTREAM-DESIGN.md:821 setLinkLength() topology.js:592 topology.js:687

The seventh was the checker lying. docs/BGP-POLICY.md cites test/bgp.test.js:452 while naming mkPath(), and 452 is the line that calls mkPath() - defined at 49. judgeLine() only compared a citation to the definition, so a correct pointer was reported as "403 lines from mkPath() at line 49" on every run, and --strict could never pass. A citation whose cited range calls the symbol it names is now judged correct; a range that calls nothing still has to be within the 40-line drift window, so the check is not blunted.

test/doc-citations.test.js pins it: call-site accepted at 600 lines from the definition, no-call still a suspect at 590 lines, inside-drift and definition-line accepted, and the real BGP-POLICY citation judged against the real file.

Gates: syntax-check 350 files OK; check-control-bytes clean; check-doc-citations 351 citations, 16 judged, 0 suspects; test/doc-citations.test.js 11 passed; scripts/run-tests.js 280 suites, 9926 assertions, 1 failure - test/ping-count.test.js, which passes alone and is a concurrency artefact of --concurrency=4 (CI runs the default serial).

Closes no issue: the open queue is 21 device requests plus #1507 (a host decision for Jay), and this is the #1481 class - a citation that points at code which has moved. **Five stale line numbers, refreshed.** `node scripts/check-doc-citations.js` reported seven suspects; five were real, and each new number was checked against the symbol before committing: | doc | symbol | cited | actually at | |---|---|---|---| | docs/BGP-POLICY.md:76 | `_help()` | cli.js:4305 | cli.js:4863 | | docs/BGP-POLICY.md:819 | `_help()` | cli.js:4305 | cli.js:4863 | | docs/SIMULATION.md:558 | `openFlow()` | simulator.js:3709 | simulator.js:3826 | | docs/UPSTREAM-DESIGN.md:71 | `_deliver()` | simulator.js:2908 | simulator.js:2976 | | docs/UPSTREAM-DESIGN.md:442 | `serialize()` | link.js:56 | link.js:112 | | docs/UPSTREAM-DESIGN.md:821 | `setLinkLength()` | topology.js:592 | topology.js:687 | **The seventh was the checker lying.** docs/BGP-POLICY.md cites `test/bgp.test.js:452` while naming `mkPath()`, and 452 is the line that *calls* mkPath() - defined at 49. `judgeLine()` only compared a citation to the definition, so a correct pointer was reported as "403 lines from mkPath() at line 49" on every run, and `--strict` could never pass. A citation whose cited range calls the symbol it names is now judged correct; a range that calls nothing still has to be within the 40-line drift window, so the check is not blunted. `test/doc-citations.test.js` pins it: call-site accepted at 600 lines from the definition, no-call still a suspect at 590 lines, inside-drift and definition-line accepted, and the real BGP-POLICY citation judged against the real file. **Gates**: syntax-check 350 files OK; check-control-bytes clean; check-doc-citations 351 citations, 16 judged, 0 suspects; test/doc-citations.test.js 11 passed; scripts/run-tests.js 280 suites, 9926 assertions, 1 failure - `test/ping-count.test.js`, which passes alone and is a concurrency artefact of `--concurrency=4` (CI runs the default serial).
docs: refresh five citations the code had moved past, and stop the checker calling a call-site citation stale
All checks were successful
CI / Classify the change (pull_request) Successful in 13s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 19s
CI / Server smoke test (pull_request) Successful in 26s
CI / Docker build (pull_request) Successful in 34s
CI / Test (Node 18) (pull_request) Successful in 1m27s
CI / Test (Node 20) (pull_request) Successful in 1m32s
CI / Test (Node 22) (pull_request) Successful in 1m42s
03377e5cba
`node scripts/check-doc-citations.js` reported seven suspects. Five were real: the docs named
`_help()` (`cli.js`), `openFlow()` and `_deliver()` (`simulator.js`), `serialize()` (`link.js`) and
`setLinkLength()` (`topology.js`), and the number printed beside each had been overtaken by later
code - 558 lines in the worst case. Each is refreshed to the line the symbol is on now, verified
line by line before committing.

The seventh was not real. docs/BGP-POLICY.md cites `test/bgp.test.js:452` while naming `mkPath()`,
and line 452 is the line that *calls* mkPath(), which is defined at 49. judgeLine() compared a
citation only against the symbol's definition, so a correct pointer read as "403 lines from
mkPath() at line 49" on every run - permanently, and `--strict` could never pass while it did. A
citation whose cited range calls the symbol it names is now judged correct (distance 0); a line that
calls nothing still has to be within the 40-line drift window of the definition, so the check is not
blunted. test/doc-citations.test.js pins both directions, plus the real citation, against the real
file.

Before: 7 suspects. After: 351 citations, 16 judged, none more than 40 lines from the code they
name.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-16 12:57:47 +00:00
jaylouisw force-pushed fix/1116-1235 from 03377e5cba
All checks were successful
CI / Classify the change (pull_request) Successful in 13s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 19s
CI / Server smoke test (pull_request) Successful in 26s
CI / Docker build (pull_request) Successful in 34s
CI / Test (Node 18) (pull_request) Successful in 1m27s
CI / Test (Node 20) (pull_request) Successful in 1m32s
CI / Test (Node 22) (pull_request) Successful in 1m42s
to d671d9e4c2
All checks were successful
CI / Classify the change (pull_request) Successful in 13s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 12s
CI / Test (Node 18) (pull_request) Has been skipped
CI / Test (Node 20) (pull_request) Has been skipped
CI / Test (Node 22) (pull_request) Has been skipped
CI / Server smoke test (pull_request) Has been skipped
CI / Docker build (pull_request) Has been skipped
2026-11-16 12:57:50 +00:00
Compare
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1664
No description provided.