docs(CLI): the four-echo loss transcript is the one the console prints #1840

Merged
jaylouisw merged 1 commit from docs/1117-1216 into main 2026-11-17 13:41:41 +00:00
Owner

docs/CLI.md answered "four echoes are one statement about the path" with a block that begins !!!! and then says Success rate is 0 percent (0/4) - a glyph that reports four replies received over a sentence that reports none - and without the Type escape sequence to abort. / Sending 4, ... header lines a box prints.

Reproduced against a lab where the pinged peer has Gi0/0/0 shut:

r1> ping 10.0.0.10 4
Type escape sequence to abort.
Sending 4, 100-byte ICMP Echos to 10.0.0.10, timeout is 2 seconds:
....
Success rate is 0 percent (0/4)
Request timed out (seq 0)
Request timed out (seq 1)
Request timed out (seq 2)
Request timed out (seq 3)
% Echoes lost: 4 drops ("peer port shut (r2 Gi0/0/0)" x4)

The glyph is . per lost echo, the two header lines are printed, and the reason is quoted - which is the rule the paragraph directly below the block already states ("A reason that brings its own brackets is quoted"). The block contradicted the code and its own neighbouring sentence.

No engine change: the console is right, the page was not. Gates: syntax-check 385 files OK; docs-cli-transcript 4/0, docs-show-commands 7/0, help-completeness 8/0, no-form-help-key 81/0, help-key-works-in-every-prompt 10/0 - all unchanged.

`docs/CLI.md` answered "four echoes are one statement about the path" with a block that begins `!!!!` and then says `Success rate is 0 percent (0/4)` - a glyph that reports four replies received over a sentence that reports none - and without the `Type escape sequence to abort.` / `Sending 4, ...` header lines a box prints. Reproduced against a lab where the pinged peer has Gi0/0/0 shut: ``` r1> ping 10.0.0.10 4 Type escape sequence to abort. Sending 4, 100-byte ICMP Echos to 10.0.0.10, timeout is 2 seconds: .... Success rate is 0 percent (0/4) Request timed out (seq 0) Request timed out (seq 1) Request timed out (seq 2) Request timed out (seq 3) % Echoes lost: 4 drops ("peer port shut (r2 Gi0/0/0)" x4) ``` The glyph is `.` per lost echo, the two header lines are printed, and the reason is quoted - which is the rule the paragraph directly below the block already states ("A reason that brings its own brackets is quoted"). The block contradicted the code and its own neighbouring sentence. No engine change: the console is right, the page was not. Gates: syntax-check 385 files OK; docs-cli-transcript 4/0, docs-show-commands 7/0, help-completeness 8/0, no-form-help-key 81/0, help-key-works-in-every-prompt 10/0 - all unchanged.
docs(CLI): the four-echo loss transcript is the one the console prints (#1840)
Some checks failed
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 16s
CI / Server smoke test (pull_request) Successful in 9s
CI / Docker build (pull_request) Successful in 25s
CI / Test (Node 18) (pull_request) Failing after 58s
CI / Test (Node 20) (pull_request) Failing after 52s
CI / Test (Node 22) (pull_request) Failing after 53s
CI / Arm auto-merge (pull_request) Successful in 2s
3fc7b8e736
The block answered 'four echoes are one statement' with `!!!!` above `Success rate is 0 percent (0/4)`: a glyph that says all four replies- came back over a sentence that says none did, and neither header line a box prints. Reproduced against a lab where the peer's Gi0/0/0 is shut:

  r1> ping 10.0.0.10 4
  Type escape sequence to abort.
  Sending 4, 100-byte ICMP Echos to 10.0.0.10, timeout is 2 seconds:
  ....
  Success rate is 0 percent (0/4)
  ...
  % Echoes lost: 4 drops ("peer port shut (r2 Gi0/0/0)" x4)

so the glyph is '.' per lost echo, the two header lines are printed, and the reason is quoted because it brings its own brackets - the rule the paragraph below the block already states.
jaylouisw force-pushed docs/1117-1216 from 3fc7b8e736
Some checks failed
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 16s
CI / Server smoke test (pull_request) Successful in 9s
CI / Docker build (pull_request) Successful in 25s
CI / Test (Node 18) (pull_request) Failing after 58s
CI / Test (Node 20) (pull_request) Failing after 52s
CI / Test (Node 22) (pull_request) Failing after 53s
CI / Arm auto-merge (pull_request) Successful in 2s
to 6567effe67
Some checks failed
CI / Classify the change (pull_request) Successful in 9s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 6s
CI / Server smoke test (pull_request) Has been skipped
CI / Docker build (pull_request) Has been skipped
CI / Test (Node 20) (pull_request) Failing after 56s
CI / Test (Node 18) (pull_request) Failing after 1m6s
CI / Test (Node 22) (pull_request) Failing after 1m2s
CI / Arm auto-merge (pull_request) Successful in 5s
2026-11-17 12:25:57 +00:00
Compare
Author
Owner

Blocked by an over-broad test guard, not by the doc.

All three Node jobs fail on one assertion: test/ping-default-count.test.js:122 — doc.indexOf('Sending 4,') === -1. That was written to catch leftover count-4 defaults, but it rejects any Sending 4, on the page, including an example that explicitly types the count (ping 10.0.0.10 4).

Run on this PR's tree (two generic-routers joined Gi0/0–Gi0/0, r2's Gi0/0 shut, ping 10.0.0.10 4 from r1), the console prints the transcript this PR documents:

Type escape sequence to abort.
Sending 4, 100-byte ICMP Echos to 10.0.0.10, timeout is 2 seconds:
....
Success rate is 0 percent (0/4)
Request timed out (seq 0)
... seq 1–3
% Echoes lost: 4 drops ("peer port shut (r2 Gi0/0)" x4)

The quoting is dropsSentence() (a reason carrying its own brackets is quoted, #1417) and the lowercase r2 is the stored device id. So the page is right and the guard is stale. (I did not verify the Gi0/0/0 port name in the doc's own example — my lab has Gi0/0 — but every format claim in the hunk is confirmed.)

The fix belongs to whoever owns test/: narrow line 122 to count-less invocations rather than rewriting this section, which is about four echoes collapsing into one loss line.

Needs Jay's (or the test loop's) decision — I do not edit test/ or docs/ as my own contribution. The PR is 6 lines, docs-only, and would go green on the next push once the guard is narrowed; it is also 3 commits behind main and will need a rebase after that.

**Blocked by an over-broad test guard, not by the doc.** All three Node jobs fail on one assertion: `test/ping-default-count.test.js:122` — `doc.indexOf('Sending 4,') === -1`. That was written to catch leftover count-4 *defaults*, but it rejects any `Sending 4,` on the page, including an example that explicitly types the count (`ping 10.0.0.10 4`). Run on this PR's tree (two generic-routers joined Gi0/0–Gi0/0, r2's Gi0/0 shut, `ping 10.0.0.10 4` from r1), the console prints the transcript this PR documents: ``` Type escape sequence to abort. Sending 4, 100-byte ICMP Echos to 10.0.0.10, timeout is 2 seconds: .... Success rate is 0 percent (0/4) Request timed out (seq 0) ... seq 1–3 % Echoes lost: 4 drops ("peer port shut (r2 Gi0/0)" x4) ``` The quoting is `dropsSentence()` (a reason carrying its own brackets is quoted, #1417) and the lowercase `r2` is the stored device id. So the page is right and the guard is stale. (I did not verify the `Gi0/0/0` port name in the doc's own example — my lab has Gi0/0 — but every format claim in the hunk is confirmed.) The fix belongs to whoever owns `test/`: narrow line 122 to count-less invocations rather than rewriting this section, which is about four echoes collapsing into one loss line. **Needs Jay's (or the test loop's) decision** — I do not edit `test/` or `docs/` as my own contribution. The PR is 6 lines, docs-only, and would go green on the next push once the guard is narrowed; it is also 3 commits behind main and will need a rebase after that.
Author
Owner

Re-verified on main 9fb6ecae (this branch is 4 behind, no conflicts). node test/ping-default-count.test.js -> 17 passed, 1 failed, the single failure still test/ping-default-count.test.js:122, doc.indexOf('Sending 4,') === -1.

One nuance worth recording, from rebuilding the lab both ways:

  • topology created through the canvas (auto ids d1/d2) -> % Echoes lost: 4 drops ("peer port shut (d2 Gi0/0/0)" x4)
  • topology carrying explicit ids r1/r2 -> % Echoes lost: 4 drops ("peer port shut (r2 Gi0/0/0)" x4)

engine/simulator.js:3168 builds the reason from peerDev.id, not the name, so this page's r2 is exact for the id convention the rest of docs/ already uses, and the canvas path is the one that reads oddly (d2). Nothing here changes the page: the quoting, the .... line, 0/4 and the four seq lines all match what I ran.

The blocker is filed as #1845 so the test/CI loop can narrow that guard - it is a substring test over the whole file, so it cannot tell an explicit count from a stale default. I don't edit test/. Needs Jay's or the test loop's call; this PR is otherwise clean and mergeable.

Re-verified on main `9fb6ecae` (this branch is 4 behind, no conflicts). `node test/ping-default-count.test.js` -> **17 passed, 1 failed**, the single failure still `test/ping-default-count.test.js:122`, `doc.indexOf('Sending 4,') === -1`. One nuance worth recording, from rebuilding the lab both ways: - topology created through the canvas (auto ids `d1`/`d2`) -> `% Echoes lost: 4 drops ("peer port shut (d2 Gi0/0/0)" x4)` - topology carrying explicit ids `r1`/`r2` -> `% Echoes lost: 4 drops ("peer port shut (r2 Gi0/0/0)" x4)` `engine/simulator.js:3168` builds the reason from `peerDev.id`, not the name, so this page's `r2` is exact for the id convention the rest of `docs/` already uses, and the canvas path is the one that reads oddly (`d2`). Nothing here changes the page: the quoting, the `....` line, `0/4` and the four `seq` lines all match what I ran. The blocker is filed as #1845 so the test/CI loop can narrow that guard - it is a substring test over the whole file, so it cannot tell an explicit count from a stale default. I don't edit `test/`. Needs Jay's or the test loop's call; this PR is otherwise clean and mergeable.
Author
Owner

The guard #1845 describes is narrowed in #1850 (test/ping-default-count.test.js): each Sending N, line is read against the command echoed above it, so a typed 4 is accepted and a bare 4 is still rejected. Checked with this branch's docs/CLI.md substituted in - 25 passed, 0 failed - so this PR is no longer blocked by that file.

The guard #1845 describes is narrowed in #1850 (`test/ping-default-count.test.js`): each `Sending N,` line is read against the command echoed above it, so a typed `4` is accepted and a bare `4` is still rejected. Checked with this branch's `docs/CLI.md` substituted in - 25 passed, 0 failed - so this PR is no longer blocked by that file.
jaylouisw force-pushed docs/1117-1216 from 6567effe67
Some checks failed
CI / Classify the change (pull_request) Successful in 9s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 6s
CI / Server smoke test (pull_request) Has been skipped
CI / Docker build (pull_request) Has been skipped
CI / Test (Node 20) (pull_request) Failing after 56s
CI / Test (Node 18) (pull_request) Failing after 1m6s
CI / Test (Node 22) (pull_request) Failing after 1m2s
CI / Arm auto-merge (pull_request) Successful in 5s
to 346cd89bec
All checks were successful
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 7s
CI / Classify the change (pull_request) Successful in 8s
CI / Server smoke test (pull_request) Has been skipped
CI / Docker build (pull_request) Has been skipped
CI / Test (Node 20) (pull_request) Successful in 49s
CI / Test (Node 22) (pull_request) Successful in 53s
CI / Test (Node 18) (pull_request) Successful in 56s
CI / Arm auto-merge (pull_request) Successful in 16s
2026-11-17 13:40:10 +00:00
Compare
Author
Owner

Merged as 6fc78b1e at 13:41Z after a rebase onto c0d92766 (8 commits behind, no conflicts).

The blocker was the guard, not this page: #1850 landed first (c0d92766), which now reads every Sending N, against the command above it. On the rebased branch test/ping-default-count.test.js is 25 passed, 0 failed; docs-cli-transcript, canonical-urls, doc-citations and docs-show-commands all green as well. Nothing in docs/CLI.md was changed by this rebase.

Merged as `6fc78b1e` at 13:41Z after a rebase onto `c0d92766` (8 commits behind, no conflicts). The blocker was the guard, not this page: `#1850` landed first (`c0d92766`), which now reads every `Sending N,` against the command above it. On the rebased branch `test/ping-default-count.test.js` is **25 passed, 0 failed**; `docs-cli-transcript`, `canonical-urls`, `doc-citations` and `docs-show-commands` all green as well. Nothing in `docs/CLI.md` was changed by this rebase.
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!1840
No description provided.