CLI.md: the show-form guard paragraph was a form and two refusals behind, and quoted the wrong command's refusal #1533

Merged
jaylouisw merged 1 commit from docs/1115-1945 into main 2026-11-15 19:52:25 +00:00
Owner

One item: the paragraph in docs/CLI.md that describes what test/docs-show-commands.test.js does.

What was untrue

  1. Counts. The paragraph pinned 46 forms, 92 commands and Fifty-six of the ninety-two answers are refusals. The guard prints its own census on every run; today it says 47 forms, 94 commands typed, and (58 refusals, all about the device rather than the syntax). The page gained a show row after #1480 wrote the numbers down and the paragraph never moved.
  2. Example refusal. It paired show ip ospf with the DHCP sentence (% This device is not a DHCP server (no "ip dhcp pool" configured)). Typed at a switch, show ip ospf answers % OSPF is not enabled (use "ospf router-id <ip>" in config mode) - so the quoted line belonged to a different command and could not be reproduced from the transcript described.

Evidence from the engine (engine/cli.js, via CliSession on the generic-switch and generic-router catalogue entries):

[r1] show ip ospf  -> % OSPF is not enabled (use "ospf router-id <ip>" in config mode)
[sw] show ip ospf  -> % OSPF is not enabled (use "ospf router-id <ip>" in config mode)

A router without ospf router-id answers the same way, so "a switch has no show ip ospf" was narrower than the code; the text now says "a box with no OSPF configured".

Checked reproducible before editing: the show spanning-trees failure transcript further down still yields % Invalid show command: spanning-trees on both devices.

Guards (all green before and after; the counts in the prose are not asserted by any guard, which is how they went stale):

  • node scripts/syntax-check.js - 321 files OK
  • docs-show-commands - 7 passed / 0 failed (47 forms, 94 commands, 58 refusals)
  • help-completeness - 8 passed / 0 failed (98 advertised commands, 18 mechanisms, 16 show)
  • doc-catalog-counts - 24 passed / 0 failed
  • help-key-works-in-every-prompt - 0 fail; repo-paths 8/0; canonical-urls 52/0
  • node scripts/check-control-bytes.js - no control bytes

Docs-only; no engine change, nothing pushed to main.

One item: the paragraph in `docs/CLI.md` that describes what `test/docs-show-commands.test.js` does. **What was untrue** 1. Counts. The paragraph pinned `46 forms, 92 commands` and `Fifty-six of the ninety-two answers are refusals`. The guard prints its own census on every run; today it says `47 forms`, `94 commands typed`, and `(58 refusals, all about the device rather than the syntax)`. The page gained a `show` row after #1480 wrote the numbers down and the paragraph never moved. 2. Example refusal. It paired `show ip ospf` with the DHCP sentence (`% This device is not a DHCP server (no "ip dhcp pool" configured)`). Typed at a switch, `show ip ospf` answers `% OSPF is not enabled (use "ospf router-id <ip>" in config mode)` - so the quoted line belonged to a different command and could not be reproduced from the transcript described. **Evidence from the engine** (`engine/cli.js`, via `CliSession` on the `generic-switch` and `generic-router` catalogue entries): ``` [r1] show ip ospf -> % OSPF is not enabled (use "ospf router-id <ip>" in config mode) [sw] show ip ospf -> % OSPF is not enabled (use "ospf router-id <ip>" in config mode) ``` A router without `ospf router-id` answers the same way, so "a switch has no show ip ospf" was narrower than the code; the text now says "a box with no OSPF configured". Checked reproducible before editing: the `show spanning-trees` failure transcript further down still yields `% Invalid show command: spanning-trees` on both devices. **Guards** (all green before and after; the counts in the prose are not asserted by any guard, which is how they went stale): - `node scripts/syntax-check.js` - 321 files OK - docs-show-commands - 7 passed / 0 failed (47 forms, 94 commands, 58 refusals) - help-completeness - 8 passed / 0 failed (98 advertised commands, 18 mechanisms, 16 `show`) - doc-catalog-counts - 24 passed / 0 failed - help-key-works-in-every-prompt - 0 fail; repo-paths 8/0; canonical-urls 52/0 - `node scripts/check-control-bytes.js` - no control bytes Docs-only; no engine change, nothing pushed to `main`.
CLI.md: the show-form guard's paragraph was one form and two refusals behind, and its example refusal was the wrong command's
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 21s
CI / Test (Node 20) (pull_request) Successful in 3m14s
CI / Test (Node 18) (pull_request) Successful in 3m29s
CI / Server smoke test (pull_request) Has been skipped
CI / Docker build (pull_request) Has been skipped
CI / Test (Node 22) (pull_request) Successful in 2m57s
a8c720e817
The section that explains test/docs-show-commands.test.js pinned the numbers it read off the page when the test was
written (#1480): 46 forms, 92 commands, 56 refusals. The test prints its own census on every run, and today it says
47 forms, 94 commands, 58 refusals - the page has gained a show row since, and the paragraph never moved.

It also illustrated a *legitimate* refusal by pairing `show ip ospf` with the DHCP server sentence. Typed at a switch
the command answers:

  % OSPF is not enabled (use "ospf router-id <ip>" in config mode)

so the quoted line came from a different command and could not be reproduced from the transcript the paragraph
describes. Quote the answer the command actually gives, and say 'a box with no OSPF configured' - a router without
'ospf router-id' answers the same way, so the switch/device framing was also narrower than the code.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-15 19:52:17 +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!1533
No description provided.