The catalogue refuses two ports with one name, two files for one box, and nonsense templates (#1317) #1318

Merged
jaylouisw merged 1 commit from fix/catalogue-gates into main 2026-11-10 02:08:35 +00:00
Owner

The catalogue refuses two ports with one name, two files for one box, and nonsense templates.

Fixes #1317.

docs/DEVICE_SCHEMA.md already says:

name | required, unique in the spec. Two ports called ge1 are an error, not a typo to fix silently.

Duplicate spellings are refused. … two entries for one device make the palette look richer and the search
results wrong.

Neither was true at load — the importer enforced the second, loadCatalog() enforced neither. The tree is clean
today (0 duplicate port names, 0 duplicate model keys) and nothing kept it that way.

1. Two ports with one name: the spec describes 5, the device has 4

expandInterfaces(spec)   -> Gi1,Gi2,Gi3,Gi4,Gi2    (five ports)
device.interfaces.size   -> 4                      (four)

Ports are kept in a map keyed by name, so the later Gi2 silently replaced the earlier one. A 28-port switch written
with a clash became a 27-port switch — and the canvas, the inspector count and the port audit all agreed with each
other and all disagreed with the file.

2. Two files for one box

modelKey() squashes punctuation and is what the importer gates on (#60), but nothing re-checked it at load. A file
arriving by a rebase, a copy or a hand edit put two entries in the palette for one machine, and
POST /devices {model} took whichever sorted first.

3. A template prefix or start of the wrong type

prefix: 5 with start: "1" expanded to Gi10, Gi11, Gi12, Gi13 — numbering that begins at ten because start + i
concatenated a string.

Gates added

Each is a brokenSpec() entry naming the file — the existing convention, so a broken spec stays in the catalogue and
cannot be mistaken for a working device:

  • duplicate port name → port name "Gi2" is used 2 times - a device would keep 4 of the 5 ports the spec describes
  • a model another file declares → declares Cisco ASR1001-X, which asr1001x.json already declares
  • portTemplate.prefix must be a string, start a whole number ≥ 0

Enforced at load, not only at import, because import is not the only door.

Evidence

test/catalogue-hygiene.test.js — 25 checks. The shipped catalogue loads with 0 broken, no duplicate port names,
no duplicate model keys, every entry naming a vendor/model/category and every one with something to cable to — the
state, pinned. Then each gate, with the engine measured first (expandInterfaces gives 5, the device keeps 4) so
the rule is justified by what the engine does rather than by taste; ASR1001-X and ASR 1001-X are one box while two
vendors may share a model name; prefix 5, start "1" and start -1 all refused. And the other half of the rule:
four legitimate shapes all load — template-only (207 specs use it), template plus extra explicit ports (25 ports, not
24 and not 1), explicit only, and a template with no start.

With devices/registry.js reverted, 6 of the 25 fail — the clash loads happily as a 4-port device with no
message, and both files for one box load.

docs/DEVICE_SCHEMA.md: "What the loader refuses" — the table of reasons, and why the last two used to pass.

Suite: 174 suites, 6,970 assertions, 0 failed.

The catalogue refuses two ports with one name, two files for one box, and nonsense templates. Fixes #1317. `docs/DEVICE_SCHEMA.md` already says: > `name` | required, **unique in the spec**. Two ports called `ge1` are an error, not a typo to fix silently. > **Duplicate spellings are refused.** … two entries for one device make the palette look richer and the search > results wrong. Neither was true at load — the importer enforced the second, `loadCatalog()` enforced neither. The tree is clean today (0 duplicate port names, 0 duplicate model keys) and **nothing kept it that way**. ## 1. Two ports with one name: the spec describes 5, the device has 4 ``` expandInterfaces(spec) -> Gi1,Gi2,Gi3,Gi4,Gi2 (five ports) device.interfaces.size -> 4 (four) ``` Ports are kept in a map keyed by name, so the later `Gi2` silently replaced the earlier one. A 28-port switch written with a clash became a 27-port switch — and the canvas, the inspector count and the port audit all agreed with each other and all disagreed with the file. ## 2. Two files for one box `modelKey()` squashes punctuation and is what the importer gates on (#60), but nothing re-checked it at load. A file arriving by a rebase, a copy or a hand edit put two entries in the palette for one machine, and `POST /devices {model}` took whichever sorted first. ## 3. A template prefix or start of the wrong type `prefix: 5` with `start: "1"` expanded to `Gi10, Gi11, Gi12, Gi13` — numbering that begins at ten because `start + i` concatenated a string. ## Gates added Each is a `brokenSpec()` entry naming the file — the existing convention, so a broken spec stays in the catalogue and cannot be mistaken for a working device: * duplicate port name → `port name "Gi2" is used 2 times - a device would keep 4 of the 5 ports the spec describes` * a model another file declares → `declares Cisco ASR1001-X, which asr1001x.json already declares` * `portTemplate.prefix` must be a string, `start` a whole number ≥ 0 Enforced **at load, not only at import**, because import is not the only door. ## Evidence `test/catalogue-hygiene.test.js` — **25 checks**. The shipped catalogue loads with 0 broken, no duplicate port names, no duplicate model keys, every entry naming a vendor/model/category and every one with something to cable to — the state, pinned. Then each gate, with the engine measured **first** (`expandInterfaces` gives 5, the device keeps 4) so the rule is justified by what the engine does rather than by taste; `ASR1001-X` and `ASR 1001-X` are one box while two vendors may share a model name; `prefix 5`, `start "1"` and `start -1` all refused. And the other half of the rule: four legitimate shapes all load — template-only (207 specs use it), template plus extra explicit ports (25 ports, not 24 and not 1), explicit only, and a template with no `start`. With `devices/registry.js` reverted, **6 of the 25 fail** — the clash loads happily as a 4-port device with no message, and both files for one box load. `docs/DEVICE_SCHEMA.md`: "What the loader refuses" — the table of reasons, and why the last two used to pass. Suite: 174 suites, 6,970 assertions, 0 failed.
The catalogue refuses two ports with one name, two files for one box, and nonsense templates (#1317)
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 15s
CI / Test (Node 20) (pull_request) Successful in 3m3s
CI / Test (Node 18) (pull_request) Successful in 3m12s
CI / Server smoke test (pull_request) Successful in 40s
CI / Docker build (pull_request) Successful in 54s
CI / Test (Node 22) (pull_request) Successful in 2m43s
1e99a68f39
docs/DEVICE_SCHEMA.md already says "name | required, unique in the spec. Two ports called ge1 are an error, not a
typo to fix silently" and "Duplicate spellings are refused ... two entries for one device make the palette look
richer and the search results wrong". Neither was true at load: the importer enforced the second, loadCatalog()
enforced neither. The tree is clean today (0 duplicate port names, 0 duplicate model keys) and nothing kept it that
way.

1. Two ports with one name: the spec describes 5, the device has 4

  expandInterfaces(spec)   -> Gi1,Gi2,Gi3,Gi4,Gi2    (five ports)
  device.interfaces.size   -> 4                      (four)

Ports are kept in a map keyed by name, so the later Gi2 silently replaced the earlier one. A 28-port switch written
with a clash became a 27-port switch, and the canvas, the inspector count and the port audit all agreed with each
other and all disagreed with the file.

2. Two files for one box. modelKey() squashes punctuation and is what the importer gates on (#60), but nothing
re-checked it at load, so a file arriving by a rebase, a copy or a hand edit put two entries in the palette for one
machine - and POST /devices {model} took whichever sorted first.

3. A template prefix or start of the wrong type: prefix 5 with start "1" expanded to Gi10, Gi11, Gi12, Gi13 - port
numbering beginning at ten because start + i concatenated a string.

Gates added, each as a brokenSpec() entry naming the file (the existing convention, so a broken spec stays in the
catalogue and cannot be mistaken for a working device):
  * duplicate port name -> "port name "Gi2" is used 2 times - a device would keep 4 of the 5 ports the spec
    describes";
  * a model another file declares -> "declares Cisco ASR1001-X, which asr1001x.json already declares";
  * portTemplate.prefix must be a string, start a whole number >= 0.

Enforced at load, not only at import, because import is not the only door.

test/catalogue-hygiene.test.js: 25 checks. The shipped catalogue loads with 0 broken, no duplicate port names, no
duplicate model keys, every entry naming a vendor, model and category and every one with something to cable to -
the state, pinned. Then each gate: the engine is measured first (expandInterfaces gives 5, the device keeps 4) so
the rule is justified by what the engine does rather than by taste; a clash is refused with the arithmetic in the
message; ASR1001-X and ASR 1001-X are one box and the second file is refused while two vendors may share a model
name; prefix 5, start "1" and start -1 are all refused. And the other half of the rule: four legitimate shapes all
load - template-only (207 specs use it), template plus extra explicit ports (25 ports, not 24 and not 1), explicit
only, and a template with no start.

With devices/registry.js reverted, 6 of the 25 fail - the clash loads happily as a 4-port device, no message, and
both files for one box load.

docs/DEVICE_SCHEMA.md: "What the loader refuses" - the table of reasons, and why the last two used to pass.

Suite: 174 suites, 6,970 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-10 02:08:32 +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!1318
No description provided.