docs: every page that states the catalogue total is written by the generator - README and CONNECTORS were 4 models and 164 sockets behind #1671

Merged
jaylouisw merged 3 commits from fix/1116-1335 into main 2026-11-16 14:16:40 +00:00
Owner

No open code issue this run (the queue is [Device]: requests plus #1507, which needs the host), so this is the defect the last two merges left in reach.

What was wrong

Only docs/DEVICE_REGISTRY.md had a generator and a test. README.md and docs/CONNECTORS.md state the same totals by hand, and both were stale:

page said truth
README.md:90 2,210 models across 252 vendors 2,214 across 252
docs/CONNECTORS.md:1023 2,210 models built from 867 distinct port shapes 2,214 / 869
docs/CONNECTORS.md:1030 (2210 models, 25016 sockets, 867 distinct port shapes) (2214 models, 25180 sockets, 869 distinct port shapes)

The drift is one afternoon old: #1665 (Zyxel GS1900, +7) and #1667 (D-Link DGS-1520, +4) each regenerated the registry page and nothing else, and nothing looked at the other two.

What changed

  • scripts/regen-registry-doc.js now owns every page that states a number: the registry headline + table (unchanged), README's **N models across M vendors** sentence, and CONNECTORS' prose sentence and pasted sweep output. --check reports all three; npm run regen:registry-doc fixes all three.
  • The port-shape rule moved to scripts/catalogue-shapes.js - it lived only in the faceplate sweep, and the generator needs the same definition, or the page quotes a number the suite does not print.
  • test/doc-catalog-counts.test.js asserts README and CONNECTORS against the directory, asserts every page equals what the generator would write, and proves a plausible wrong number on either page is caught and repaired in place without reflowing the paragraph.

Reproduce the failure first

Reverting README and the pasted block to their values from main gives 35 passed, 6 failed: the README count, the three pasted numbers, and both is current checks.

Gates

  • node scripts/syntax-check.js - 351 files, all OK
  • node scripts/check-control-bytes.js - clean; node scripts/audit-port-types.js - clean
  • node test/doc-catalog-counts.test.js - 41/41; node test/faceplate-catalogue.test.js - 14/14
  • full suite serial: 280 suites, 9,987 assertions, 0 failed (run in three letter-range chunks; a single foreground run is capped at 7 minutes in this harness, and --concurrency=2 is not trustworthy here - canonical-urls and another suite both edit README, which is a separate proposal)

Not done: #1507 still needs the host.

No open code issue this run (the queue is `[Device]:` requests plus #1507, which needs the host), so this is the defect the last two merges left in reach. ## What was wrong Only `docs/DEVICE_REGISTRY.md` had a generator and a test. `README.md` and `docs/CONNECTORS.md` state the same totals by hand, and both were stale: | page | said | truth | |---|---|---| | README.md:90 | **2,210 models** across 252 vendors | 2,214 across 252 | | docs/CONNECTORS.md:1023 | **2,210 models built from 867 distinct port shapes** | 2,214 / 869 | | docs/CONNECTORS.md:1030 | `(2210 models, 25016 sockets, 867 distinct port shapes)` | `(2214 models, 25180 sockets, 869 distinct port shapes)` | The drift is one afternoon old: #1665 (Zyxel GS1900, +7) and #1667 (D-Link DGS-1520, +4) each regenerated the registry page and nothing else, and nothing looked at the other two. ## What changed - `scripts/regen-registry-doc.js` now owns every page that states a number: the registry headline + table (unchanged), README's `**N models across M vendors**` sentence, and CONNECTORS' prose sentence and pasted sweep output. `--check` reports all three; `npm run regen:registry-doc` fixes all three. - The port-shape rule moved to `scripts/catalogue-shapes.js` - it lived only in the faceplate sweep, and the generator needs the same definition, or the page quotes a number the suite does not print. - `test/doc-catalog-counts.test.js` asserts README and CONNECTORS against the directory, asserts every page equals what the generator would write, and proves a plausible wrong number on either page is caught and repaired in place without reflowing the paragraph. ## Reproduce the failure first Reverting README and the pasted block to their values from `main` gives `35 passed, 6 failed`: the README count, the three pasted numbers, and both `is current` checks. ## Gates - `node scripts/syntax-check.js` - 351 files, all OK - `node scripts/check-control-bytes.js` - clean; `node scripts/audit-port-types.js` - clean - `node test/doc-catalog-counts.test.js` - 41/41; `node test/faceplate-catalogue.test.js` - 14/14 - full suite serial: **280 suites, 9,987 assertions, 0 failed** (run in three letter-range chunks; a single foreground run is capped at 7 minutes in this harness, and `--concurrency=2` is not trustworthy here - `canonical-urls` and another suite both edit README, which is a separate proposal) Not done: #1507 still needs the host.
docs: every page that states the catalogue total is written by the generator, and all three are current
All checks were successful
CI / Classify the change (pull_request) Successful in 16s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 13s
CI / Server smoke test (pull_request) Successful in 12s
CI / Test (Node 18) (pull_request) Successful in 1m31s
CI / Test (Node 20) (pull_request) Successful in 1m17s
CI / Docker build (pull_request) Successful in 27s
CI / Test (Node 22) (pull_request) Successful in 1m29s
0130b817ae
README and docs/CONNECTORS.md both state how big the catalogue is, and neither was written by
anything: only docs/DEVICE_REGISTRY.md had a generator (scripts/regen-registry-doc.js) and a test.
Two device pull requests landed this afternoon (#1665 Zyxel GS1900, #1667 D-Link DGS-1520), each ran
the generator for the registry page and nothing else, so the front page has been claiming 2,210
models against a catalogue of 2,214, and CONNECTORS has been quoting 2,210 models / 25,016 sockets /
867 shapes where the sweep prints 2,214 / 25,180 / 869. Nothing failed, because nothing looked.

So the generator now owns every page that states a number:

  * docs/DEVICE_REGISTRY.md - headline and largest-vendor/category table (unchanged behaviour);
  * README.md - the same "**N models across M vendors**" sentence, and nothing else on the page;
  * docs/CONNECTORS.md - the prose "**N models built from S distinct port shapes**" and the pasted
    output of test/faceplate-catalogue.test.js underneath it.

--check reports all three pages instead of one, and npm run regen:registry-doc fixes all three.

The shape rule moved to scripts/catalogue-shapes.js, because it was only in the faceplate sweep and
the generator needs the same definition; two copies of "what is a distinct shape" is how the page
and the suite come to disagree. test/doc-catalog-counts.test.js now asserts README's counts,
CONNECTORS' prose and pasted block, and that every page is what the generator would write - plus
that a plausible wrong number on either page is noticed and repaired in place without reflowing the
paragraph. Reverting README and the pasted block to their pre-run values fails six assertions.

Totals: 280 suites, 9,987 assertions, 0 failed (serial, run in three chunks because a foreground run
is capped at 7 minutes here); syntax-check 351 files OK; control bytes clean; port types clean.
Author
Owner

This branch conflicts with main, so it was not rebased:

README.md docs/CONNECTORS.md scripts/catalogue-shapes.js scripts/regen-registry-doc.js test/doc-catalog-counts.test.js test/faceplate-catalogue.test.js 

A conflict is a decision about behaviour rather than a mechanical fix, so this is left for a human. Rebasing by hand and force-pushing will let the automation pick it up again.

This branch conflicts with `main`, so it was not rebased: ``` README.md docs/CONNECTORS.md scripts/catalogue-shapes.js scripts/regen-registry-doc.js test/doc-catalog-counts.test.js test/faceplate-catalogue.test.js ``` A conflict is a decision about behaviour rather than a mechanical fix, so this is left for a human. Rebasing by hand and force-pushing will let the automation pick it up again.
docs: the wiki states the catalogue total too, so the generator covers its page and its template
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 16s
CI / Server smoke test (pull_request) Successful in 25s
CI / Docker build (pull_request) Successful in 38s
CI / Test (Node 18) (pull_request) Successful in 1m32s
CI / Test (Node 20) (pull_request) Successful in 1m34s
CI / Test (Node 22) (pull_request) Successful in 1m44s
5de61d2b3a
While this branch was open, #1668 landed on main fixing the same four numbers by hand in README,
docs/CONNECTORS.md, docs/wiki/Home.md and the template in scripts/build-wiki.js - which is the
argument for this change rather than a duplicate of it: a hand repair had to find five copies.

The merge from main brings the numbers current (2,216 models, 25,216 sockets, 870 shapes, after the
Netonix pair in #1669); on top of it the generator now also owns:

  * docs/wiki/Home.md      "**N device models from M vendors**"
  * scripts/build-wiki.js  the template that page is built from, which carries the same sentence

Both were stale at 2,210 this afternoon and both are fresh now, so `--check` still reports every page
current. PAGES is what test/doc-catalog-counts.test.js walks, so the new pair is covered by the same
assertion (43 checks, up from 41); staling the wiki line fails with "docs/wiki/Home.md is current".
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-16 14:16:31 +00:00
Author
Owner

Merged as 1ab9f597. Record of the final state after the merge from main:

  • node scripts/regen-registry-doc.js --check - all five pages current at 2,216 models across 252 vendors, 25,216 sockets, 870 distinct port shapes (main had moved twice while this was open: #1668 had to repair README + CONNECTORS + wiki Home + the build-wiki template by hand, and #1669 added the Netonix pair).
  • node test/doc-catalog-counts.test.js - 43/43; node test/faceplate-catalogue.test.js - 14/14; node test/catalogue-hygiene.test.js - 25/25.
  • full suite serial: 281 suites, 10,063 assertions, 0 failed; syntax-check 352 files OK; control bytes clean; port types clean.
  • Negative checks: staling README + the CONNECTORS block gives 35 passed, 6 failed; staling the wiki line gives 42 passed, 1 failed naming docs/wiki/Home.md.

Still open and not mine: #1507 (the 46 GB firmware repository) needs the host.

Merged as 1ab9f597. Record of the final state after the merge from main: - `node scripts/regen-registry-doc.js --check` - all five pages current at **2,216 models across 252 vendors, 25,216 sockets, 870 distinct port shapes** (main had moved twice while this was open: #1668 had to repair README + CONNECTORS + wiki Home + the build-wiki template by hand, and #1669 added the Netonix pair). - `node test/doc-catalog-counts.test.js` - **43/43**; `node test/faceplate-catalogue.test.js` - 14/14; `node test/catalogue-hygiene.test.js` - 25/25. - full suite serial: **281 suites, 10,063 assertions, 0 failed**; syntax-check 352 files OK; control bytes clean; port types clean. - Negative checks: staling README + the CONNECTORS block gives `35 passed, 6 failed`; staling the wiki line gives `42 passed, 1 failed` naming `docs/wiki/Home.md`. Still open and not mine: #1507 (the 46 GB firmware repository) needs the host.
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!1671
No description provided.