What is wrong
We describe our supported rig conventions in three places, and nothing keeps them honest with each other:
- The header comment in
src/glb-canonicalize.js lists every convention the alias map handles.
CONVENTIONS in src/rig-report.js fingerprints conventions so Rig Doctor can name one on sight.- The Recognised rig conventions table in
docs/rig-doctor.md is what users read.
Add a convention and forget one of the three, and the product quietly lies to a user: it animates their rig but reports it as unrecognised, or it advertises support in the docs that the detector does not have. This has real cost, because the "Unrecognised joints" panel is how we find out which conventions to add next.
What to change
Write a drift test. Suggested home: a new tests/rig-conventions-drift.test.js, or add to tests/rig-report.test.js if it fits better there.
It should assert, mechanically:
- Every entry in
CONVENTIONS (except the unknown fallback) has a row in the docs/rig-doctor.md table. Match on the label string.
- Every row in that table corresponds to a real
CONVENTIONS entry, so a deleted detector cannot leave a stale doc row behind.
- Each convention's
evidence string is non-empty, since it is user-facing text.
Parse the Markdown table with a small regex over the file read from disk. Look at how tests/rig-report.test.js resolves repo paths (fileURLToPath plus join) and follow it.
Bonus, only if the first part lands cleanly: extend it to the header comment in glb-canonicalize.js. That is harder because the comment is prose, so a reasonable approach is a machine-readable list beside the prose rather than parsing English.
How to prove it worked
npx vitest run tests/rig-report.test.js
npm test
Then prove the test actually bites: temporarily delete a row from the docs table, watch it fail, put the row back. Paste both outputs in the PR. A drift guard that cannot fail is worse than no guard because it reads as coverage.
Why it is worth doing
The rig layer is the part of this project outside contributors touch most. Every convention added from now on is a chance for these three lists to diverge. This test is the thing that stops that happening silently.
Comment here to claim it.
What is wrong
We describe our supported rig conventions in three places, and nothing keeps them honest with each other:
src/glb-canonicalize.jslists every convention the alias map handles.CONVENTIONSinsrc/rig-report.jsfingerprints conventions so Rig Doctor can name one on sight.docs/rig-doctor.mdis what users read.Add a convention and forget one of the three, and the product quietly lies to a user: it animates their rig but reports it as unrecognised, or it advertises support in the docs that the detector does not have. This has real cost, because the "Unrecognised joints" panel is how we find out which conventions to add next.
What to change
Write a drift test. Suggested home: a new
tests/rig-conventions-drift.test.js, or add totests/rig-report.test.jsif it fits better there.It should assert, mechanically:
CONVENTIONS(except theunknownfallback) has a row in thedocs/rig-doctor.mdtable. Match on thelabelstring.CONVENTIONSentry, so a deleted detector cannot leave a stale doc row behind.evidencestring is non-empty, since it is user-facing text.Parse the Markdown table with a small regex over the file read from disk. Look at how
tests/rig-report.test.jsresolves repo paths (fileURLToPathplusjoin) and follow it.Bonus, only if the first part lands cleanly: extend it to the header comment in
glb-canonicalize.js. That is harder because the comment is prose, so a reasonable approach is a machine-readable list beside the prose rather than parsing English.How to prove it worked
npx vitest run tests/rig-report.test.js npm testThen prove the test actually bites: temporarily delete a row from the docs table, watch it fail, put the row back. Paste both outputs in the PR. A drift guard that cannot fail is worse than no guard because it reads as coverage.
Why it is worth doing
The rig layer is the part of this project outside contributors touch most. Every convention added from now on is a chance for these three lists to diverge. This test is the thing that stops that happening silently.
Comment here to claim it.