docs(connectors): the code table omitted four codes RULES declares #2384

Merged
jaylouisw merged 1 commit from docs/1121-0647 into main 2026-11-21 07:11:49 +00:00
Owner

What was untrue

docs/CONNECTORS.md — section Error and warning codes — is headed "Everything the rules engine can emit, and where it comes from", and it listed 25 codes. RULES in engine/validation.js declares 28.

Missing rows: E_SERIAL_NO_CLOCK, E_SERIAL_TWO_CLOCKS, E_PROTOCOL_MISMATCH, W_SWITCHPORT_MISMATCH.

Evidence

Each has a {code, severity, description} entry in RULES (engine/validation.js:104, :109, :120, :187), and E_PROTOCOL_MISMATCH is emitted by the validator itself as well as passed through from media.canMate(). They entered RULES in f0f0ea8c (#1662), which corrected the paragraph under the table and added the two validateTopology rows but not these four — so the table has been short by four since that commit.

$ node -e "const v=require('./engine/validation'); v.RULES.map(r=>r.code).filter(c=>!/E_NO_PORT/.test(c))"
... E_SERIAL_NO_CLOCK, E_SERIAL_TWO_CLOCKS, E_PROTOCOL_MISMATCH, W_SWITCHPORT_MISMATCH

The change

Four rows added, wording taken from each description in RULES; placement follows the table's existing grouping (serial pair before E_CONSOLE_TO_DATA, E_PROTOCOL_MISMATCH beside the other canMate refusals, W_SWITCHPORT_MISMATCH after W_HYBRID_CORD). Docs-only: docs/CONNECTORS.md, one hunk, no code or test touched.

The table now holds 29 rows — the 28 in RULES plus E_COMBO_OCCUPIED, which the paragraph below already documents as the topology.js exception — and every row's severity matches the table the validator reads.

Gates

gate before after
node scripts/syntax-check.js 516 files, all OK 516 files, all OK
test/docs-cli-transcript.test.js 9 passed, 0 failed 9 passed, 0 failed
test/docs-show-commands.test.js 73 forms / 146 commands, 96 refusals, 7 passed same
test/no-form-help-key.test.js 81 passed 81 passed
test/help-completeness.test.js 8 passed (16 show views) 8 passed
test/validation.test.js / test/property-validator.test.js 22 / 25 passed 22 / 25 passed

Not done

The canMate()-only codes E_BAUD_MISMATCH, E_BIDI_MISMATCH and E_BIDI_SAME_WAVELENGTH are still absent from this table (one is described in prose further down the page, none is in RULES), and docs/PHYSICAL_LAYER.md section 4 is further behind RULES than this page was. Both are separate items; this PR fixes one table.

## What was untrue `docs/CONNECTORS.md` — section *Error and warning codes* — is headed **"Everything the rules engine can emit, and where it comes from"**, and it listed 25 codes. `RULES` in `engine/validation.js` declares 28. Missing rows: `E_SERIAL_NO_CLOCK`, `E_SERIAL_TWO_CLOCKS`, `E_PROTOCOL_MISMATCH`, `W_SWITCHPORT_MISMATCH`. ## Evidence Each has a `{code, severity, description}` entry in `RULES` (`engine/validation.js:104`, `:109`, `:120`, `:187`), and `E_PROTOCOL_MISMATCH` is emitted by the validator itself as well as passed through from `media.canMate()`. They entered `RULES` in f0f0ea8c (#1662), which corrected the paragraph under the table and added the two `validateTopology` rows but not these four — so the table has been short by four since that commit. ``` $ node -e "const v=require('./engine/validation'); v.RULES.map(r=>r.code).filter(c=>!/E_NO_PORT/.test(c))" ... E_SERIAL_NO_CLOCK, E_SERIAL_TWO_CLOCKS, E_PROTOCOL_MISMATCH, W_SWITCHPORT_MISMATCH ``` ## The change Four rows added, wording taken from each `description` in `RULES`; placement follows the table's existing grouping (serial pair before `E_CONSOLE_TO_DATA`, `E_PROTOCOL_MISMATCH` beside the other `canMate` refusals, `W_SWITCHPORT_MISMATCH` after `W_HYBRID_CORD`). Docs-only: `docs/CONNECTORS.md`, one hunk, no code or test touched. The table now holds 29 rows — the 28 in `RULES` plus `E_COMBO_OCCUPIED`, which the paragraph below already documents as the `topology.js` exception — and every row's severity matches the table the validator reads. ## Gates | gate | before | after | |---|---|---| | `node scripts/syntax-check.js` | 516 files, all OK | 516 files, all OK | | `test/docs-cli-transcript.test.js` | 9 passed, 0 failed | 9 passed, 0 failed | | `test/docs-show-commands.test.js` | 73 forms / 146 commands, 96 refusals, 7 passed | same | | `test/no-form-help-key.test.js` | 81 passed | 81 passed | | `test/help-completeness.test.js` | 8 passed (16 `show` views) | 8 passed | | `test/validation.test.js` / `test/property-validator.test.js` | 22 / 25 passed | 22 / 25 passed | ## Not done The `canMate()`-only codes `E_BAUD_MISMATCH`, `E_BIDI_MISMATCH` and `E_BIDI_SAME_WAVELENGTH` are still absent from this table (one is described in prose further down the page, none is in `RULES`), and `docs/PHYSICAL_LAYER.md` section 4 is further behind `RULES` than this page was. Both are separate items; this PR fixes one table.
docs(connectors): the code table omitted four codes RULES declares
All checks were successful
CI / Classify the change (pull_request) Successful in 14s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 11s
CI / Server smoke and Docker build (pull_request) Successful in 25s
CI / Test (Node 22) (pull_request) Successful in 1m3s
CI / Test (Node 18) (pull_request) Successful in 1m5s
CI / Test (Node 20) (pull_request) Successful in 1m6s
CI / Arm auto-merge (pull_request) Successful in 4s
2a6ed0d574
The table is headed "Everything the rules engine can emit", but four entries of
RULES (engine/validation.js) had no row: E_SERIAL_NO_CLOCK, E_SERIAL_TWO_CLOCKS,
E_PROTOCOL_MISMATCH and W_SWITCHPORT_MISMATCH. They entered RULES in f0f0ea8c,
which fixed the surrounding paragraph and added the two validateTopology rows but
not these four. 25 rows documented against 28 declared; now 29 rows (28 RULES
plus the documented E_COMBO_OCCUPIED exception), severities taken from the table
the validator uses.
forgejo-actions scheduled this pull request to auto merge when all checks succeed 2026-11-21 06:55:09 +00:00
jaylouisw deleted branch docs/1121-0647 2026-11-21 07:11:50 +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!2384
No description provided.