The docs pointed at code that had moved #1482

Merged
jaylouisw merged 1 commit from docs/citation-repair into main 2026-11-12 04:45:45 +00:00
Owner

What was wrong

The docs cite the implementation constantly. docs/SIMULATION.md says, of VLAN tagging:

Frames are really tagged on the wire: _emitFrame sets wireTagged/wireVid from classifyEgress … | engine/simulator.js:1666-1680

Line 1666 of engine/simulator.js is now BGP route application. _emitFrame's definition is hundreds of lines further down, and wireTagged lives at line 84 in the frame builder. The reader who follows that citation lands in the wrong subsystem and learns, correctly, that the prose cannot be checked.

What was measured

citations in docs:              348
  of which name a symbol:       150
  pointing >40 lines away:       28

Most are hundreds of lines off; the worst are near a thousand, because whole mechanisms landed above the cited functions and pushed them down. Two examples from the same page: portPvid() was cited at simulator.js:72-78 and is defined at 103; _emitFrame at 1666-1680 and defined at 2661.

What changed

28 citations now point at the line where the named function is actually defined:

doc was is symbol
SIMULATION.md engine/device.js:366-443 engine/device.js:816 routeTo()
SIMULATION.md engine/simulator.js:1666-1680 engine/simulator.js:2661 _emitFrame
SIMULATION.md engine/simulator.js:1392-1471 engine/simulator.js:2407 pingScion()
UPSTREAM-DESIGN.md media.js:562 media.js:894 derivePortHardware()
UPSTREAM-DESIGN.md validation.js:59 validation.js:152 SEVERITY_BY_CODE
… 23 more

Each was repaired only when the symbol had exactly one definition in the cited file — a name with two definitions is overloaded, and guessing would replace one wrong number with another. Definitions were matched as definitions (function x(, x(…) {, const x =), never as call sites, because a call site is not the thing the sentence is about. Every changed line was read before it was kept, and one repair was reverted by hand: the DNS row cites two ranges for name resolution, and the only call-shaped symbol in the sentence (openFlow()) is not its subject — the original engine/simulator.js:137, engine/simulator.js:228-260 still points at resolveName() and stays.

Tool, and its limit

npm run check:citations lists suspects with the distance, the symbol and the line it found; -- --strict exits 1. It judges a citation only when the sentence names exactly one function as a call, gives exactly one citation, and that function has exactly one definition in the cited file — a citation may sit up to 40 lines away.

It is a diagnostic, not a CI gate, and its own output shows why. Today's single suspect is docs/BGP-POLICY.md:1090 citing test/bgp.test.js:452, which is a test body, while the sentence mentions mkPath() — a helper defined 400 lines above. A rule that flagged that would be wrong; a rule narrow enough to be right judges 15 of 348. Judging the rest needs a reader. So the tool narrows the search and a human decides, and docs/MAINTAINING.md says so in those words, including the false positive.

Full suite: 238 suites, 8848 assertions, 0 failed. Syntax 307 files OK.

Reviewer note: the repairs are mechanical but were read line by line; the one judgement call that the tool got wrong (the DNS row in SIMULATION.md) is called out above and was left at its original, correct citations. No code changed — only numbers inside docs, plus one script, one npm task and one MAINTAINING section.

## What was wrong The docs cite the implementation constantly. `docs/SIMULATION.md` says, of VLAN tagging: > Frames are really tagged on the wire: `_emitFrame` sets `wireTagged`/`wireVid` from `classifyEgress` … | `engine/simulator.js:1666-1680` Line 1666 of `engine/simulator.js` is now BGP route application. `_emitFrame`'s definition is hundreds of lines further down, and `wireTagged` lives at line 84 in the frame builder. The reader who follows that citation lands in the wrong subsystem and learns, correctly, that the prose cannot be checked. ## What was measured ``` citations in docs: 348 of which name a symbol: 150 pointing >40 lines away: 28 ``` Most are hundreds of lines off; the worst are near a thousand, because whole mechanisms landed *above* the cited functions and pushed them down. Two examples from the same page: `portPvid()` was cited at `simulator.js:72-78` and is defined at 103; `_emitFrame` at 1666-1680 and defined at 2661. ## What changed 28 citations now point at the line where the named function is actually defined: | doc | was | is | symbol | |---|---|---|---| | `SIMULATION.md` | `engine/device.js:366-443` | `engine/device.js:816` | `routeTo()` | | `SIMULATION.md` | `engine/simulator.js:1666-1680` | `engine/simulator.js:2661` | `_emitFrame` | | `SIMULATION.md` | `engine/simulator.js:1392-1471` | `engine/simulator.js:2407` | `pingScion()` | | `UPSTREAM-DESIGN.md` | `media.js:562` | `media.js:894` | `derivePortHardware()` | | `UPSTREAM-DESIGN.md` | `validation.js:59` | `validation.js:152` | `SEVERITY_BY_CODE` | | … | 23 more | | | Each was repaired only when the symbol had **exactly one definition** in the cited file — a name with two definitions is overloaded, and guessing would replace one wrong number with another. Definitions were matched as definitions (`function x(`, `x(…) {`, `const x =`), never as call sites, because a call site is not the thing the sentence is about. Every changed line was read before it was kept, and one repair was reverted by hand: the DNS row cites two ranges for name resolution, and the only call-shaped symbol in the sentence (`openFlow()`) is not its subject — the original `engine/simulator.js:137`, `engine/simulator.js:228-260` still points at `resolveName()` and stays. ## Tool, and its limit `npm run check:citations` lists suspects with the distance, the symbol and the line it found; `-- --strict` exits 1. It judges a citation only when the sentence names exactly one function as a call, gives exactly one citation, and that function has exactly one definition in the cited file — a citation may sit up to 40 lines away. **It is a diagnostic, not a CI gate, and its own output shows why.** Today's single suspect is `docs/BGP-POLICY.md:1090` citing `test/bgp.test.js:452`, which is a *test body*, while the sentence mentions `mkPath()` — a helper defined 400 lines above. A rule that flagged that would be wrong; a rule narrow enough to be right judges 15 of 348. Judging the rest needs a reader. So the tool narrows the search and a human decides, and `docs/MAINTAINING.md` says so in those words, including the false positive. Full suite: 238 suites, 8848 assertions, 0 failed. Syntax 307 files OK. Reviewer note: the repairs are mechanical but were read line by line; the one judgement call that the tool got wrong (the DNS row in `SIMULATION.md`) is called out above and was left at its original, correct citations. No code changed — only numbers inside docs, plus one script, one npm task and one MAINTAINING section.
The docs pointed at code that had moved (#1481)
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 13s
CI / Test (Node 20) (pull_request) Successful in 3m6s
CI / Test (Node 18) (pull_request) Successful in 3m19s
CI / Server smoke test (pull_request) Successful in 28s
CI / Docker build (pull_request) Successful in 45s
CI / Test (Node 22) (pull_request) Successful in 2m54s
57a2f32d88
The docs cite the implementation constantly. SIMULATION.md says, of VLAN
tagging, that "`_emitFrame` sets `wireTagged`/`wireVid` from `classifyEgress`"
and cites engine/simulator.js:1666-1680. Line 1666 is now BGP route
application; _emitFrame is defined at 2661 and wireTagged lives in the frame
builder at 84. A reader who follows that lands in the wrong subsystem and
learns, correctly, that the prose cannot be checked.

Measured: 348 citations, 150 naming a symbol, 28 of those more than 40 lines
from the code they name - most by hundreds, several by nearly a thousand,
because whole mechanisms landed above the cited functions.

  * 28 citations repaired to the line where the named function is actually
    defined, each only when the symbol had exactly one definition in that file
    (two definitions means the name is overloaded, and a guess would replace one
    wrong number with another). Definitions were matched as definitions, never
    as call sites. Every changed line was read; one repair was reverted by hand,
    because the DNS row's only call-shaped symbol is not its subject and its
    original pair of ranges still points at resolveName();
  * scripts/check-doc-citations.js + `npm run check:citations` list suspects
    with the distance, the symbol and the line found; `-- --strict` exits 1.
    It judges a citation only when the sentence names exactly one function as a
    call, gives exactly one citation, and that function has exactly one
    definition in the cited file, allowing 40 lines of drift;
  * docs/MAINTAINING.md states the rule and the tool's limit in its own output:
    today's single suspect cites a test body while the sentence mentions a
    helper defined 400 lines above. A rule that flagged that would be wrong; a
    rule narrow enough to be right judges 15 of 348. It is a diagnostic, not a
    gate, and the doc says so.

Suite 238 suites, 8848 assertions, 0 failed. Syntax 307 files OK.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-12 04:45:27 +00:00
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!1482
No description provided.