docs(CLI): the converge citation was 101 lines off, and help still advertises the at form #1676

Merged
jaylouisw merged 2 commits from docs/1116-1445 into main 2026-11-16 14:57:37 +00:00
Owner

One piece of drift, from check-doc-citations.js.

What was untrue. docs/CLI.md (the converge - when is it up? section) cited engine/cli.js:2719 for _converge(). That line is now inside the NAT name-resolution code; the definition is at 2820, 101 lines away - flagged by node scripts/check-doc-citations.js as a suspect.

A second, subtler claim. The same paragraph said "This page and help both said converge [at &lt;ms&gt;]" - past tense. The page was corrected, the index was not: engine/cli.js:4978 still prints converge [at <ms>]. A reader who asks the box rather than the page is still taught the spelling that does nothing.

Evidence - re-typed on an Aruba 2540 switch with an STP control plane:

converge           -> row, no (pending) mark
converge 10000     -> row + "  (pending)"
converge at 10000  -> row, no (pending) mark        # the word `at` is swallowed

So the prose stood; only the pointer and the tense were wrong. Parser left alone - the real fix (take at the way link does) belongs in _converge(), and this stream is docs-only.

Guards. syntax-check 352 files OK; check-control-bytes clean; check-doc-citations 352 citations, suspects 3 -> 2; docs-show-commands 7/7 (49 forms, 98 commands, 62 refusals); help-completeness 8/8 (48 tokens, 98 advertised commands, 18 mechanisms, 16 show commands); doc-catalog-counts 43/43; document-stamp 31/31.

Note for a code-side follow-up: npm test at PF_TEST_CONCURRENCY=6 flaked 4 suites (board-id-is-a-name, ping-count, ping-instant, ping-surface); all four pass in isolation. Not touched here.

One piece of drift, from `check-doc-citations.js`. **What was untrue.** `docs/CLI.md` (the *converge - when is it up?* section) cited `engine/cli.js:2719` for `_converge()`. That line is now inside the NAT name-resolution code; the definition is at **2820**, 101 lines away - flagged by `node scripts/check-doc-citations.js` as a suspect. **A second, subtler claim.** The same paragraph said *"This page and `help` both said `converge [at &lt;ms&gt;]`"* - past tense. The page was corrected, the index was not: `engine/cli.js:4978` still prints ` converge [at <ms>]`. A reader who asks the box rather than the page is still taught the spelling that does nothing. **Evidence** - re-typed on an Aruba 2540 switch with an STP control plane: ``` converge -> row, no (pending) mark converge 10000 -> row + " (pending)" converge at 10000 -> row, no (pending) mark # the word `at` is swallowed ``` So the prose stood; only the pointer and the tense were wrong. Parser left alone - the real fix (take `at` the way `link` does) belongs in `_converge()`, and this stream is docs-only. **Guards.** syntax-check 352 files OK; check-control-bytes clean; check-doc-citations 352 citations, suspects 3 -> **2**; docs-show-commands 7/7 (49 forms, 98 commands, 62 refusals); help-completeness 8/8 (48 tokens, 98 advertised commands, 18 mechanisms, 16 `show` commands); doc-catalog-counts 43/43; document-stamp 31/31. Note for a code-side follow-up: `npm test` at `PF_TEST_CONCURRENCY=6` flaked 4 suites (`board-id-is-a-name`, `ping-count`, `ping-instant`, `ping-surface`); all four pass in isolation. Not touched here.
docs(CLI): converge's citation was 101 lines off, and help still advertises at
All checks were successful
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 18s
CI / Server smoke test (pull_request) Successful in 23s
CI / Docker build (pull_request) Successful in 32s
CI / Test (Node 18) (pull_request) Successful in 1m13s
CI / Test (Node 20) (pull_request) Successful in 1m17s
CI / Test (Node 22) (pull_request) Successful in 1m25s
330f0ce8bb
The converge section cited engine/cli.js:2719 for `_converge()`, which now
lands in the NAT resolver 101 lines above the definition (2820). The
section's own argument - that the instant takes no `at` keyword - was
still true, but it said "this page and `help` both said" the wrong form,
past tense, while `help` still prints it (engine/cli.js:4978). Re-typed
all three forms at an Aruba 2540: `converge` and `converge 10000` mark the
pending row, `converge at 10000` silently drops the mark.

check-doc-citations: suspects 3 -> 2.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-16 14:57:29 +00:00
jaylouisw force-pushed docs/1116-1445 from 330f0ce8bb
All checks were successful
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 18s
CI / Server smoke test (pull_request) Successful in 23s
CI / Docker build (pull_request) Successful in 32s
CI / Test (Node 18) (pull_request) Successful in 1m13s
CI / Test (Node 20) (pull_request) Successful in 1m17s
CI / Test (Node 22) (pull_request) Successful in 1m25s
to 86891946dd
All checks were successful
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 11s
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 14:57:33 +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!1676
No description provided.