the importer asks the engine what a capability is (#1522) #1528
No reviewers
Labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
jaylouisw/packetforge!1528
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "fix/1522-import-devices-capabilities"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What was wrong
scripts/import-devices.jskept its own copy of the capability vocabulary — 17 tokens against the engine's 15 — and then stripped any token it did not recognise intospec.role. Three of the five tokens it did not recognise (vlan,lacp,stp) are capabilities the engine does implement, so declaring 802.1Q, LACP or STP made a device poorer and the run reported success.Reproduced before the fix
Fixture: a switch declaring
["l2-forward","l3-forward","cli","vlan","lacp","stp"], imported withPF_INCOMING/PF_DEVICESpointed at a throwaway catalogue.Written spec (
devices/acme/sw-24g.json) — three capabilities gone, filed under a field nothing reads:Same fixture after the fix
And a spec declaring a token the engine does not implement is now named rather than counted:
What changed
const { CAPABILITIES } = require('../engine').engine/index.jsalready re-exported it, so nothing had to be added to the engine surface. A future change toengine/device.jsnow reaches the importer with no second edit.vlan,lacpandstpsurvive, because the engine says they are capabilities.test/import-devices-capabilities.test.jsasserts the importer's accepted set is the engine's set at runtime (set equality and object identity, so an equal-looking copy cannot creep back).CAPABILITY_ALIASESmust be a token the engine lists, so renaming an engine token fails here instead of silently turning every aliased spec into an unknown.CAPABILITIESand is not a near-miss of one is a description the engine has no concept of. It stays inspec.capabilitiesexactly as the source declared it, and the run prints the token and the model. A near-miss is still a typo and still rejected.capabilitiesLost(declared, written)compares what the validator says the source declared against what is about to be written; a difference refuses the spec and exits non-zero. It cannot fire today — which is the point, it is the check that did not exist when the strip was silent."N spec(s) had minor warnings (still imported)"was the line that made the original loss invisible; it now lists each model and each message.scripts/import-devices.jsexportsvalidateSpec,CAPABILITIES,CAPABILITY_ALIASES,normaliseCapabilities,capabilitiesLostandeditDistance(main still runs only underrequire.main === module), so the test can measure the real pipeline rather than a copy of it.docs/DEVICE_SCHEMA.mdcapability tables now derive fromengine/device.jsand document the kept-and-named rule;docs/MAINTAINING.mdstep 3 says the importer never drops a declared capability.The honest choice on
vlan/lacp/stp#1526 notes that no code branches on the three tokens and that zero specs use them. That is an argument for #1526 (wire them, or remove them from
CAPABILITIES— and if removed there, this script loses them automatically, which is exactly the coupling wanted). It is not an argument for one script deleting a token the engine publishes. Until #1526 decides, the importer keeps what the engine lists: the fix here is that the importer stops having an opinion, not that it gains a different one.Related: the field the tokens were moved to is dead. Top-level
spec.roleis read by nothing (engine/device.jsroleis an interface field —'wan' | 'lan'), so the strip did not even preserve the description it claimed to preserve; 79 catalogue specs carry arolearray that no code reads. Nothing underdevices/is edited here.Tokens that are not capabilities
Deriving from the engine means the importer now reports the power descriptors it used to accept in silence. Keeping them (rather than dropping them) is deliberate: dropping a fact the datasheet declares is the same data loss this issue is about. Census of
devices/at this commit — 2,039 specs, 18 distinct capability tokens:CAPABILITIES?passive-poe802.3af802.3at802.3btpoe-injectorwifi-apwireless588 specs carry at least one of those, so they now produce a named warning on re-import. That is a true statement about the catalogue, and the fix belongs in
CAPABILITIES(if the token should grant behaviour) or in a catalogue sweep — not in a second list inside this script. No file underdevices/orcatalogue/is touched by this PR; if Jay wants the descriptors to become real capabilities, or to be swept out of the catalogue, that is a separate decision and a separate PR.How many copies of a capability token list are in
scripts/Grepped every token-list shape in
scripts/:scripts/import-devices.js:38, the bug. Now removed.capabilities: [...]literal arrays in 3 files:scripts/merge-research.js(42 device records with hand-written token lists),scripts/missing-devices.js:243(['host']placeholder for an unresearched stub),scripts/request-queue.js:142([]placeholder). Those are uses of the vocabulary, not a copy of it, so they are out of scope here — butmerge-research.jswrites 42 specs with hand-picked tokens and is the next place this class of drift will show up.Tests
New
test/import-devices-capabilities.test.js, 29 assertions:rolekey;require('../engine').CAPABILITIES(not to a hardcoded list), plus identity, plus "every alias lands on a real token";--json, keeps the tokens, and does not warn aboutpoe-pse;capabilitiesLostunit-tested in both directions; a near-miss typo still rejected.npm test: 248 suites, 9,137 assertions, 0 failed before → 249 suites, 9,166 assertions, 0 failed after.npm run syntax: 319 files OK.Contradictions with the issue text
devices/holds 2,039 specs and 18 distinct tokens at this commit. The engine-side claim is exact: 12 of the engine's 15 tokens are used by some spec, andvlan/lacp/stpby none.labelanddescription, so the run printed no warning line at all. The loss is the same, and it is quieter than the issue says.Fixes #1522