* test(#3762): failing-first roster gate for docs/INVENTORY.md rows
Anchors the human half of the inventory-drift rule: every entry in
docs/INVENTORY-MANIFEST.json must have a hand-written row in
docs/INVENTORY.md. Expected RED on this commit -- next carries 32
unrostered surfaces, which is the defect the gate exists to catch.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(#3762): enforce docs/INVENTORY.md roster rows, backfill 32 gaps
docs/INVENTORY.md calls itself the authoritative roster of every shipped
GSD surface, and CLAUDE.md's inventory-drift rule requires both a roster
row and a manifest regen. Only the manifest half was anchored, so a PR
could ship a surface, regenerate the manifest, omit the row, and stay
green -- as PR #3758 did with gsd-core/references/planner-coupling.md.
Adds the roster half to tests/inventory-manifest-sync.test.cjs, backed by
a pure matcher in tests/helpers/inventory-roster.cjs, and backfills the 32
surfaces already missing rows on next.
Fixes #3762
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* test(#3762): harden roster matcher against fenced blocks and trim exports
Skips fenced code regions when splitting level-2 sections so a documented
'## ' example inside a fence cannot truncate a family section (false red)
or contribute a phantom row (false pass); makes the heading pattern linear
rather than a backtracking lazy match; narrows the module surface to the
three names the gate consumes.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(#3762): close two false-RED gaps found in orthogonal review
Indented headings: CommonMark permits an ATX heading to carry 1-3 leading
spaces, and a ^##-anchored pattern read such a document as having no family
sections at all -- reporting all six missing, a structural red for zero real
drift. Reproduced, then fixed and pinned.
Link-wrapped cells: a row written as [`x.md`](../x.md) was not recognized,
though docs/INVENTORY.md already uses that form elsewhere. Unwrapping now
peels a whole-cell link and a whole-cell code span, and only layers that
wrap the cell entirely -- a file mentioned mid-prose is still not a row, so
the false red is not traded for a false pass.
Adds a second fast-check property over the commands source-link rule, the
one family whose matching rule differs from the other five.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* test(#3762): boundary trio for the fence-marker length limit
RULESET.TESTS.boundary-coverage — the matcher's only numeric limit is the
fence marker's {3,}. Exercises 2 (inline markup, swallows nothing), 3, and
4 characters, for both backtick and tilde delimiters.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* chore: remove stray pwned_cmdsub injection-test canary from the repo root
A zero-byte file committed by 0e6fa2e2c (#3124) while remediating the
#3118 command-substitution injection — the marker a test wrote into cwd to
prove a substitution had NOT executed, left behind when the run ended.
Nothing in the tree references it (verified by Grep across the repo),
package.json's files array excludes root-level files so it never shipped,
and lint-removed-but-needed confirms no surviving reference.
Found while auditing the repo root for #3762; fixed inline rather than
deferred, per CLAUDE.md's no-deferrals rule.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* docs: backfill changeset pr number to 3766
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
272
tests/helpers/inventory-roster.cjs
Normal file
272
tests/helpers/inventory-roster.cjs
Normal file
@@ -0,0 +1,272 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* inventory-roster.cjs — the pure half of the `docs/INVENTORY.md` roster gate (#3762).
|
||||
*
|
||||
* `docs/INVENTORY-MANIFEST.json` is anchored against the filesystem by
|
||||
* `tests/inventory-manifest-sync.test.cjs`. This module supplies the second
|
||||
* comparison that test runs: every manifest entry must also have a hand-written row
|
||||
* in `docs/INVENTORY.md`, which calls itself "Authoritative roster of every shipped
|
||||
* GSD surface" (`docs/INVENTORY.md:3`) and promises "a new file without a matching
|
||||
* row here will fail CI" (`docs/INVENTORY.md:681`). Until #3762 neither claim was
|
||||
* true: PR #3758 shipped `gsd-core/references/planner-coupling.md` with a manifest
|
||||
* entry, no roster row, and fully green CI.
|
||||
*
|
||||
* Everything here is PURE — text and the manifest object in, findings out, no
|
||||
* filesystem access — so the matcher is drivable by fixture. A drift guard that can
|
||||
* only be exercised against a clean repo proves nothing about its own comparison.
|
||||
*
|
||||
* ── SCOPE ──────────────────────────────────────────────────────────────────────
|
||||
*
|
||||
* IN: the SIX FLAT families — `agents`, `commands`, `workflows`, `references`,
|
||||
* `cli_modules`, `hooks`. `docs/INVENTORY.md:7` says the file "enumerates every
|
||||
* shipped surface across all six families", and each has its own `##` section.
|
||||
*
|
||||
* OUT: the two NESTED families — `workflow_steps`, `workflow_modes`.
|
||||
* `docs/INVENTORY.md` §"Workflow Sub-Files" is an explicit shipped decision that
|
||||
* these carry no hand-written per-file rows: "Adding a step or mode file requires no
|
||||
* hand-written row here … The per-file roster deliberately lives in
|
||||
* `docs/INVENTORY-MANIFEST.json` rather than being duplicated in this table — 60
|
||||
* rows that must be hand-maintained in lockstep with a generated artifact is the
|
||||
* drift this file exists to catch." Demanding rows there would override that
|
||||
* decision, not enforce the roster.
|
||||
*
|
||||
* ── WHAT COUNTS AS A ROW ───────────────────────────────────────────────────────
|
||||
*
|
||||
* Deliberately narrow, because this runs on every PR and must tolerate formatting it
|
||||
* has no business policing:
|
||||
*
|
||||
* • Each family is searched ONLY inside its own `##` section. A cell in another
|
||||
* family's section does not count — `smart-entry.md` (a workflow) and
|
||||
* `smart-entry.cjs` (a CLI module) are different surfaces. A MISSING section is
|
||||
* reported as one structural failure, never as one phantom row per entry.
|
||||
* • Matching is on a whole table CELL equal to the manifest entry after stripping
|
||||
* WRAPPING backticks — never a substring. The real roster's
|
||||
* `host-integration-adapters/imperative-hook-bus.cjs` row must not satisfy the
|
||||
* separate top-level `hook-bus.cjs` entry, which is genuinely unrostered.
|
||||
* • Subsections (`###`), column count, column order, CRLF, and trailing HTML
|
||||
* comments (`| … |<!-- gsd-allow-legacy-name -->`) are all irrelevant.
|
||||
* • COMMANDS MATCH ON THEIR SOURCE LINK, not their rendered name. Six namespace
|
||||
* routers deliberately render `/gsd-workflow` while sourcing
|
||||
* `commands/gsd/ns-workflow.md`; the display value is not the file identity.
|
||||
* `docs/INVENTORY.md:63` documents every command row as carrying "a link to the
|
||||
* source file", so the link is both the documented shape and the only
|
||||
* collision-free key.
|
||||
*
|
||||
* Restructuring `docs/INVENTORY.md`'s `##` headings, or dropping the command Source
|
||||
* column, is what ROSTER_SECTIONS below has to be updated for — in the same change.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Manifest family name → the level-2 heading in `docs/INVENTORY.md` that rosters it.
|
||||
* The two nested families are absent BY DESIGN (see above).
|
||||
*/
|
||||
const ROSTER_SECTIONS = Object.freeze({
|
||||
agents: 'Agents',
|
||||
commands: 'Commands',
|
||||
workflows: 'Workflows',
|
||||
references: 'References',
|
||||
cli_modules: 'CLI Modules',
|
||||
hooks: 'Hooks',
|
||||
});
|
||||
|
||||
/** A manifest `commands` entry (`/gsd-ns-workflow`) → its source basename (`ns-workflow.md`). */
|
||||
function commandSourceBasename(entry) {
|
||||
return entry.replace(/^\/gsd-/, '') + '.md';
|
||||
}
|
||||
|
||||
/**
|
||||
* Split `text` into a Map of `heading → lines[]` keyed by level-2 (`##`) heading.
|
||||
* Level-3 headings stay INSIDE their parent section, so a family's rows are found
|
||||
* regardless of which `###` subsection a contributor files them under. Split on
|
||||
* `\r?\n`: a Windows checkout is a supported working tree, and a `\n`-only split
|
||||
* would leave a trailing `\r` on every cell and red the whole gate there.
|
||||
*
|
||||
* Fenced code blocks (``` or ~~~) are skipped wholesale — neither their headings
|
||||
* nor their pipe-delimited lines participate. `docs/INVENTORY.md` carries no fence
|
||||
* today, which is exactly why this is worth writing down: the day someone documents
|
||||
* a `## ` example inside one, an unfenced scanner would silently truncate a family
|
||||
* section and red the gate on a document that is perfectly correct.
|
||||
*
|
||||
* The heading pattern is deliberately `(.*)` + trim rather than a lazy `(.+?)` with
|
||||
* a trailing `[ \t]*$`: the lazy form backtracks quadratically on a heading line
|
||||
* padded with thousands of spaces, and this gate parses a file any contributor can
|
||||
* write.
|
||||
*
|
||||
* Both the heading and the fence marker allow CommonMark's LEADING INDENT of up to
|
||||
* three spaces. Anchoring hard at `^##` looks harmless and is not: an author who
|
||||
* indents a heading by one space writes a perfectly valid document that this gate
|
||||
* would read as having NO family sections at all, reporting all six as missing —
|
||||
* a structural red for zero real drift.
|
||||
*/
|
||||
function splitLevel2Sections(text) {
|
||||
const sections = new Map();
|
||||
let current = null;
|
||||
let fence = null;
|
||||
for (const line of String(text).split(/\r?\n/)) {
|
||||
const fenceMark = /^ {0,3}(`{3,}|~{3,})/.exec(line);
|
||||
if (fenceMark) {
|
||||
if (fence === null) {
|
||||
fence = fenceMark[1][0];
|
||||
continue;
|
||||
}
|
||||
if (fenceMark[1][0] === fence) fence = null;
|
||||
continue;
|
||||
}
|
||||
if (fence !== null) continue;
|
||||
|
||||
const m = /^ {0,3}##[ \t]+(.*)$/.exec(line);
|
||||
if (m) {
|
||||
current = m[1].trim();
|
||||
if (!sections.has(current)) sections.set(current, []);
|
||||
continue;
|
||||
}
|
||||
if (current !== null) sections.get(current).push(line);
|
||||
}
|
||||
return sections;
|
||||
}
|
||||
|
||||
/**
|
||||
* Peel the presentation off a whole table cell, one layer at a time, and return
|
||||
* every form encountered — the raw text and each unwrapped result.
|
||||
*
|
||||
* Two layers are recognized, and only when they wrap the cell ENTIRELY:
|
||||
* • a code span: `` `x.md` `` → `x.md`
|
||||
* • a markdown link: `` [`x.md`](../x.md) `` → `` `x.md` `` → `x.md`
|
||||
*
|
||||
* ENTIRELY is the whole safety property. A role cell reading "superseded by
|
||||
* `ghost.md`" keeps its text intact, so a file merely MENTIONED in prose can never
|
||||
* masquerade as a row — which is the false PASS this gate exists to prevent, and is
|
||||
* strictly worse than the false red that motivated handling the link form. The link
|
||||
* text may not itself contain `]`, so a cell holding two links degrades to "no
|
||||
* unwrap" rather than to a garbled middle substring.
|
||||
*/
|
||||
function unwrapCellForms(cell) {
|
||||
const forms = [cell];
|
||||
let current = cell;
|
||||
// At most two peels: link → code span. Bounded, so no pathological input can
|
||||
// turn this into a loop.
|
||||
for (let i = 0; i < 2; i++) {
|
||||
const code = /^`(.+)`$/.exec(current);
|
||||
if (code) {
|
||||
current = code[1].trim();
|
||||
forms.push(current);
|
||||
continue;
|
||||
}
|
||||
const link = /^\[([^\]]+)\]\([^)]*\)$/.exec(current);
|
||||
if (link) {
|
||||
current = link[1].trim();
|
||||
forms.push(current);
|
||||
continue;
|
||||
}
|
||||
break;
|
||||
}
|
||||
return forms;
|
||||
}
|
||||
|
||||
/**
|
||||
* Every whole table cell in `lines`, trimmed, plus the unwrapped forms of each (see
|
||||
* `unwrapCellForms`). Only cells are collected — a line that is not a table row
|
||||
* contributes nothing.
|
||||
*/
|
||||
function tableCells(lines) {
|
||||
const cells = new Set();
|
||||
for (const line of lines) {
|
||||
if (!line.trimStart().startsWith('|')) continue;
|
||||
for (const raw of line.split('|')) {
|
||||
const trimmed = raw.trim();
|
||||
if (!trimmed) continue;
|
||||
for (const form of unwrapCellForms(trimmed)) cells.add(form);
|
||||
}
|
||||
}
|
||||
return cells;
|
||||
}
|
||||
|
||||
/**
|
||||
* Basenames of every `commands/gsd/<file>.md` markdown-link target in `lines`,
|
||||
* regardless of how many `../` hops the relative path takes or whether it carries a
|
||||
* `#anchor` / `?query`.
|
||||
*/
|
||||
function commandSourceLinks(lines) {
|
||||
const basenames = new Set();
|
||||
for (const line of lines) {
|
||||
const linkRe = /\]\(([^)\s]+)/g;
|
||||
let m;
|
||||
while ((m = linkRe.exec(line)) !== null) {
|
||||
const target = m[1].split('#')[0].split('?')[0];
|
||||
const hit = /(?:^|\/)commands\/gsd\/([^/]+\.md)$/.exec(target);
|
||||
if (hit) basenames.add(hit[1]);
|
||||
}
|
||||
}
|
||||
return basenames;
|
||||
}
|
||||
|
||||
/**
|
||||
* Compare `docs/INVENTORY.md`'s rows against the manifest's family arrays.
|
||||
*
|
||||
* @param {string} inventoryText contents of `docs/INVENTORY.md`
|
||||
* @param {object} families the manifest's `families` object
|
||||
* @returns {{missingSections: string[], missingRows: string[]}}
|
||||
* `missingRows` entries read `"<family>/<entry>"`, matching the phrasing the
|
||||
* manifest half of the gate already uses for additions/removals.
|
||||
*/
|
||||
function findMissingRosterRows(inventoryText, families) {
|
||||
const sections = splitLevel2Sections(inventoryText);
|
||||
const missingSections = [];
|
||||
const missingRows = [];
|
||||
|
||||
for (const [family, heading] of Object.entries(ROSTER_SECTIONS)) {
|
||||
const lines = sections.get(heading);
|
||||
if (lines === undefined) {
|
||||
missingSections.push(heading);
|
||||
continue;
|
||||
}
|
||||
const entries = (families || {})[family] || [];
|
||||
if (family === 'commands') {
|
||||
const links = commandSourceLinks(lines);
|
||||
for (const entry of entries) {
|
||||
if (!links.has(commandSourceBasename(entry))) missingRows.push(family + '/' + entry);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
const cells = tableCells(lines);
|
||||
for (const entry of entries) {
|
||||
if (!cells.has(entry)) missingRows.push(family + '/' + entry);
|
||||
}
|
||||
}
|
||||
|
||||
return { missingSections, missingRows };
|
||||
}
|
||||
|
||||
/** Human-readable remediation for a non-empty `findMissingRosterRows` result. */
|
||||
function formatRosterFailure({ missingSections, missingRows }) {
|
||||
return [
|
||||
missingSections.length
|
||||
? 'docs/INVENTORY.md is missing a "## <heading>" section this gate rosters against:\n' +
|
||||
missingSections.map((h) => ' ## ' + h).join('\n') +
|
||||
'\nIf the section was deliberately renamed or merged, update ROSTER_SECTIONS in\n' +
|
||||
'tests/helpers/inventory-roster.cjs in the same change.'
|
||||
: '',
|
||||
missingRows.length
|
||||
? 'Shipped surfaces in docs/INVENTORY-MANIFEST.json with NO row in docs/INVENTORY.md (#3762):\n' +
|
||||
missingRows.map((e) => ' ! ' + e).join('\n') +
|
||||
'\nAdd a row to the matching "## " section of docs/INVENTORY.md: the file name in a cell,\n' +
|
||||
'plus the one-line role that section\'s table asks for. For a command, the row\'s Source\n' +
|
||||
'column must link to ../commands/gsd/<file>.md — that link, not the rendered /gsd-name,\n' +
|
||||
'is what this gate reads. Regenerating the manifest does NOT satisfy this: the roster row\n' +
|
||||
'is hand-written by design, because a role sentence cannot be generated.'
|
||||
: '',
|
||||
].filter(Boolean).join('\n\n');
|
||||
}
|
||||
|
||||
// Only the three names the gate actually consumes are exported. The parsing
|
||||
// helpers above stay module-private on purpose: exporting them would create a
|
||||
// surface nothing calls, and every one of their behaviors is already pinned
|
||||
// through `findMissingRosterRows` by the fixture rows in
|
||||
// `tests/inventory-manifest-sync.test.cjs` — asserting them directly would test
|
||||
// the implementation instead of the contract.
|
||||
module.exports = {
|
||||
ROSTER_SECTIONS,
|
||||
findMissingRosterRows,
|
||||
formatRosterFailure,
|
||||
};
|
||||
@@ -1,10 +1,27 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* Asserts docs/INVENTORY-MANIFEST.json is in sync with the filesystem.
|
||||
* A stale manifest means a surface shipped without updating INVENTORY.md.
|
||||
* Fix by running: node scripts/gen-inventory-manifest.cjs --write
|
||||
* then adding the corresponding row(s) in docs/INVENTORY.md.
|
||||
* Anchors BOTH halves of the inventory-drift rule (`CLAUDE.md` → Inventory Drift:
|
||||
* "requires updating `docs/INVENTORY.md` AND running
|
||||
* `node scripts/gen-inventory-manifest.cjs --write`"):
|
||||
*
|
||||
* 1. `docs/INVENTORY-MANIFEST.json` matches the filesystem — the machine half.
|
||||
* Fix by running: node scripts/gen-inventory-manifest.cjs --write
|
||||
* 2. `docs/INVENTORY.md` carries a roster row for every manifest entry — the human
|
||||
* half (#3762). Fix by hand-writing the row.
|
||||
*
|
||||
* Until #3762 only half 1 existed, so a PR could ship a surface, regenerate the
|
||||
* manifest, omit the roster row, and pass CI green — while `docs/INVENTORY.md:3`
|
||||
* called itself "Authoritative roster of every shipped GSD surface" and
|
||||
* `docs/INVENTORY.md:681` promised "a new file without a matching row here will fail
|
||||
* CI". PR #3758 is the live instance: `gsd-core/references/planner-coupling.md`,
|
||||
* manifest entry present, roster row absent, CI 30 success / 0 failing.
|
||||
*
|
||||
* The roster comparison itself lives in `tests/helpers/inventory-roster.cjs` — read
|
||||
* its header for exactly which families are enforced, which two are deliberately
|
||||
* exempt, and what shapes a row may legally take. The fixture rows at the bottom of
|
||||
* this file drive that matcher directly, because the live assertion passes whenever
|
||||
* the repo is clean and therefore proves nothing about the comparison on its own.
|
||||
*/
|
||||
|
||||
const { test } = require('node:test');
|
||||
@@ -12,8 +29,16 @@ const assert = require('node:assert/strict');
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
|
||||
const fc = require('./helpers/fast-check-setup.cjs');
|
||||
const {
|
||||
ROSTER_SECTIONS,
|
||||
findMissingRosterRows,
|
||||
formatRosterFailure,
|
||||
} = require('./helpers/inventory-roster.cjs');
|
||||
|
||||
const ROOT = path.resolve(__dirname, '..');
|
||||
const MANIFEST_PATH = path.join(ROOT, 'docs', 'INVENTORY-MANIFEST.json');
|
||||
const INVENTORY_PATH = path.join(ROOT, 'docs', 'INVENTORY.md');
|
||||
|
||||
// #2996: FAMILIES and NESTED_FAMILIES are IMPORTED, never redeclared. This file used to
|
||||
// carry its own copy of the family table — the `DEFECT.GENERATIVE-FIX` divergence class:
|
||||
@@ -64,3 +89,387 @@ test('docs/INVENTORY-MANIFEST.json matches the filesystem', () => {
|
||||
|
||||
assert.ok(additions.length === 0 && removals.length === 0, msg);
|
||||
});
|
||||
|
||||
// ─── #3762: the roster half ──────────────────────────────────────────────────
|
||||
|
||||
test('docs/INVENTORY.md carries a roster row for every manifest entry', () => {
|
||||
const committed = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
|
||||
const inventory = fs.readFileSync(INVENTORY_PATH, 'utf8');
|
||||
const findings = findMissingRosterRows(inventory, committed.families);
|
||||
|
||||
assert.ok(
|
||||
findings.missingSections.length === 0 && findings.missingRows.length === 0,
|
||||
formatRosterFailure(findings),
|
||||
);
|
||||
});
|
||||
|
||||
// ─── Fixture rows: the gate must be able to FAIL, and only for the right reason ──
|
||||
|
||||
const FIXTURE_HEAD = '# Fixture\n\n';
|
||||
|
||||
/** Assemble a fixture document from `{heading: bodyText}`, optionally with CRLF endings. */
|
||||
function doc(sectionsBySpec, { crlf = false, indent = '' } = {}) {
|
||||
let out = FIXTURE_HEAD;
|
||||
for (const [heading, body] of Object.entries(sectionsBySpec)) {
|
||||
out += indent + '## ' + heading + '\n\n' + body + '\n\n';
|
||||
}
|
||||
return crlf ? out.replace(/\n/g, '\r\n') : out;
|
||||
}
|
||||
|
||||
/** Every in-scope section present and empty, so a row supplies only the table it cares about. */
|
||||
function emptySections(overrides = {}, opts) {
|
||||
const spec = {};
|
||||
for (const heading of Object.values(ROSTER_SECTIONS)) spec[heading] = '(no rows)';
|
||||
return doc({ ...spec, ...overrides }, opts);
|
||||
}
|
||||
|
||||
test('row 2 — the PR #3758 shape: a manifest reference with no roster row is reported', () => {
|
||||
// gsd-core/references/planner-coupling.md shipped in PR #3758 with a manifest entry,
|
||||
// all 19 tests/fixtures/install-tree/*.json updated, and no row in
|
||||
// §"Modular Planner Decomposition". That PR's CI was 30 success / 3 skipped / 0
|
||||
// failing. This row is the reason it would not be.
|
||||
const text = emptySections({
|
||||
References: '| Reference | Role |\n|---|---|\n| `checkpoints.md` | Checkpoint types. |',
|
||||
});
|
||||
const { missingSections, missingRows } = findMissingRosterRows(text, {
|
||||
references: ['checkpoints.md', 'planner-coupling.md'],
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(missingSections, []);
|
||||
assert.deepStrictEqual(missingRows, ['references/planner-coupling.md']);
|
||||
});
|
||||
|
||||
test('row 3 — adding the row clears the report', () => {
|
||||
const text = emptySections({
|
||||
References:
|
||||
'| Reference | Role |\n|---|---|\n| `checkpoints.md` | Checkpoint types. |\n' +
|
||||
'| `planner-coupling.md` | Planner coupling rules. |',
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { references: ['checkpoints.md', 'planner-coupling.md'] }).missingRows,
|
||||
[],
|
||||
);
|
||||
});
|
||||
|
||||
test('row 4 — a substring of a longer rostered cell is not a row', () => {
|
||||
// The real docs/INVENTORY.md rosters `host-integration-adapters/imperative-hook-bus.cjs`.
|
||||
// A substring match would report the separate, genuinely-unrostered top-level
|
||||
// `hook-bus.cjs` as satisfied — a false pass on a shipped module.
|
||||
const text = emptySections({
|
||||
'CLI Modules':
|
||||
'| Module | Responsibility |\n|---|---|\n' +
|
||||
'| `host-integration-adapters/imperative-hook-bus.cjs` | Imperative hook-bus adapter. |',
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, {
|
||||
cli_modules: ['host-integration-adapters/imperative-hook-bus.cjs', 'hook-bus.cjs'],
|
||||
}).missingRows,
|
||||
['cli_modules/hook-bus.cjs'],
|
||||
);
|
||||
});
|
||||
|
||||
test('row 5 — a row in another family section does not satisfy this family', () => {
|
||||
// `smart-entry.md` (a workflow) and `smart-entry.cjs` (a CLI module) are different
|
||||
// surfaces sharing a stem; an unscoped document-wide search conflates two families
|
||||
// the moment they ever do share a full name.
|
||||
const text = emptySections({
|
||||
'CLI Modules': '| Module | Responsibility |\n|---|---|\n| `smart-entry.md` | Wrong section. |',
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { workflows: ['smart-entry.md'] }).missingRows,
|
||||
['workflows/smart-entry.md'],
|
||||
);
|
||||
});
|
||||
|
||||
test('row 6 — a command row is matched on its Source link, not its display name', () => {
|
||||
const text = emptySections({
|
||||
Commands:
|
||||
'| Command | Role | Source |\n|---|---|---|\n' +
|
||||
'| `/gsd-workflow` | Phase pipeline router. | [commands/gsd/ns-workflow.md](../commands/gsd/ns-workflow.md) |',
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { commands: ['/gsd-ns-workflow'] }).missingRows,
|
||||
[],
|
||||
'the six namespace routers deliberately render a name that is not their file stem',
|
||||
);
|
||||
});
|
||||
|
||||
test('row 7 — a command row without a Source link is not a row', () => {
|
||||
const text = emptySections({
|
||||
Commands: '| Command | Role | Source |\n|---|---|---|\n| `/gsd-quick` | Quick task. | (todo) |',
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { commands: ['/gsd-quick'] }).missingRows,
|
||||
['commands//gsd-quick'],
|
||||
);
|
||||
});
|
||||
|
||||
test('row 8 — an unbackticked agent cell is a row', () => {
|
||||
// Agents is the one family whose identity column carries a bare, unbackticked name.
|
||||
const text = emptySections({
|
||||
Agents:
|
||||
'| Agent | Role | Spawned by | Primary doc |\n|---|---|---|---|\n' +
|
||||
'| gsd-planner | Creates executable phase plans. | `/gsd-plan-phase` | primary |',
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(findMissingRosterRows(text, { agents: ['gsd-planner'] }).missingRows, []);
|
||||
});
|
||||
|
||||
test('row 9 — trailing HTML comments and extra columns are tolerated', () => {
|
||||
const text = emptySections({
|
||||
'CLI Modules':
|
||||
'| Module | Responsibility | Extra |\n|---|---|---|\n' +
|
||||
'| `installer-migrations/003-rename.cjs` | Migration. | n/a |<!-- gsd-allow-legacy-name -->',
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { cli_modules: ['installer-migrations/003-rename.cjs'] }).missingRows,
|
||||
[],
|
||||
);
|
||||
});
|
||||
|
||||
test('row 10 — CRLF line endings are tolerated', () => {
|
||||
const spec = {};
|
||||
for (const heading of Object.values(ROSTER_SECTIONS)) spec[heading] = '(no rows)';
|
||||
spec.Hooks = '| Hook | Event | Purpose |\n|---|---|---|\n| `gsd-statusline.js` | `statusLine` | Statusline. |';
|
||||
const text = doc(spec, { crlf: true });
|
||||
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { hooks: ['gsd-statusline.js'] }).missingRows,
|
||||
[],
|
||||
'a \\n-only split leaves a trailing \\r on every cell and reds every Windows checkout',
|
||||
);
|
||||
});
|
||||
|
||||
test('row 10b — a fenced code block does not split a section or contribute cells', () => {
|
||||
// docs/INVENTORY.md carries no fence today. The day someone documents a `## `
|
||||
// example inside one, an unfenced scanner truncates the family section at that
|
||||
// line and reds a document that is perfectly correct — and a pipe-delimited line
|
||||
// inside the fence would count as a row it is not.
|
||||
const text = emptySections({
|
||||
References:
|
||||
'```\n## References\n| `imposter.md` | not a row |\n```\n\n' +
|
||||
'| Reference | Role |\n|---|---|\n| `real.md` | Real. |',
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { references: ['real.md', 'imposter.md'] }).missingRows,
|
||||
['references/imposter.md'],
|
||||
);
|
||||
});
|
||||
|
||||
// ─── Fence-length boundary: the matcher's only numeric limit is `{3,}` ──────────
|
||||
//
|
||||
// RULESET.TESTS.boundary-coverage — exercise limit-1 / limit / limit+1 on the fence
|
||||
// marker, for both delimiter characters. Two backticks is a plain inline code span
|
||||
// and must NOT swallow the rows beneath it; three and four must.
|
||||
|
||||
test('row 10f — a TWO-character run is not a fence, and swallows nothing (limit-1)', () => {
|
||||
for (const mark of ['``', '~~']) {
|
||||
const text = emptySections({
|
||||
References: mark + '\n| `kept.md` | Role. |\n' + mark,
|
||||
});
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { references: ['kept.md'] }).missingRows,
|
||||
[],
|
||||
'a two-' + mark[0] + ' run is inline markup, not a fence — treating it as one hides a real row',
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('row 10g — a THREE-character run opens and closes a fence (limit)', () => {
|
||||
for (const mark of ['```', '~~~']) {
|
||||
const text = emptySections({
|
||||
References: mark + '\n| `swallowed.md` | Role. |\n' + mark + '\n\n| `kept.md` | Role. |',
|
||||
});
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { references: ['kept.md', 'swallowed.md'] }).missingRows,
|
||||
['references/swallowed.md'],
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('row 10h — a FOUR-character run opens and closes a fence (limit+1)', () => {
|
||||
for (const mark of ['````', '~~~~']) {
|
||||
const text = emptySections({
|
||||
References: mark + '\n| `swallowed.md` | Role. |\n' + mark + '\n\n| `kept.md` | Role. |',
|
||||
});
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { references: ['kept.md', 'swallowed.md'] }).missingRows,
|
||||
['references/swallowed.md'],
|
||||
'a longer run is still a fence; only `{3,}` matters, not an exact count',
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('row 10c — a heading indented up to 3 spaces is still a heading (CommonMark)', (t) => {
|
||||
// Anchoring hard at /^##/ looks harmless and is not. CommonMark permits an ATX
|
||||
// heading to carry 1-3 leading spaces, so an author who indents one writes a
|
||||
// perfectly valid document that a `^##`-anchored scanner reads as having NO family
|
||||
// sections at all — all six reported missing, a structural red for zero real drift.
|
||||
const text = emptySections(
|
||||
{ References: '| Reference | Role |\n|---|---|\n| `only.md` | Only. |' },
|
||||
{ indent: ' ' },
|
||||
);
|
||||
const { missingSections, missingRows } = findMissingRosterRows(text, { references: ['only.md'] });
|
||||
|
||||
assert.deepStrictEqual(missingSections, [], 'a 3-space indent must not erase every family section');
|
||||
assert.deepStrictEqual(missingRows, [], 'rows under an indented heading are still rows');
|
||||
t.diagnostic('CommonMark 4.2: an ATX heading may be indented 0-3 spaces');
|
||||
});
|
||||
|
||||
test('row 10d — a cell that is a link wrapping a code span is a row', () => {
|
||||
// docs/INVENTORY.md already writes file references as [`docs/AGENTS.md`](AGENTS.md)
|
||||
// in prose. The first contributor who writes a FAMILY ROW that way gets an
|
||||
// inexplicable red on a row that plainly documents the file.
|
||||
const text = emptySections({
|
||||
References: '| Reference | Role |\n|---|---|\n| [`linked.md`](../references/linked.md) | Linked. |',
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(findMissingRosterRows(text, { references: ['linked.md'] }).missingRows, []);
|
||||
});
|
||||
|
||||
test('row 10e — a file merely MENTIONED in a role cell is still not a row', () => {
|
||||
// The guard on row 10d. Unwrapping presentation must peel only layers that wrap the
|
||||
// cell ENTIRELY; the moment a code span mentioned mid-prose counts, the gate has
|
||||
// traded a false red for a false pass, which is the strictly worse failure.
|
||||
const text = emptySections({
|
||||
References: '| Reference | Role |\n|---|---|\n| `real.md` | Superseded by `ghost.md` in the role prose. |',
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { references: ['real.md', 'ghost.md'] }).missingRows,
|
||||
['references/ghost.md'],
|
||||
);
|
||||
});
|
||||
|
||||
test('row 11 — a missing family section is reported as a section failure', () => {
|
||||
const text = '# Fixture\n\n## Agents\n\n| Agent |\n|---|\n| gsd-planner |\n';
|
||||
const { missingSections, missingRows } = findMissingRosterRows(text, {
|
||||
agents: ['gsd-planner'],
|
||||
cli_modules: ['a.cjs', 'b.cjs', 'c.cjs'],
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(missingSections, ['Commands', 'Workflows', 'References', 'CLI Modules', 'Hooks']);
|
||||
assert.deepStrictEqual(
|
||||
missingRows,
|
||||
[],
|
||||
'a missing section is ONE structural failure, not one phantom row per entry inside it',
|
||||
);
|
||||
});
|
||||
|
||||
test('row 12 — an empty family contributes nothing (limit-1)', () => {
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(emptySections(), { references: [] }),
|
||||
{ missingSections: [], missingRows: [] },
|
||||
);
|
||||
});
|
||||
|
||||
test('row 13 — exactly one entry, rostered (limit)', () => {
|
||||
const text = emptySections({ References: '| Reference | Role |\n|---|---|\n| `only.md` | Only. |' });
|
||||
assert.deepStrictEqual(findMissingRosterRows(text, { references: ['only.md'] }).missingRows, []);
|
||||
});
|
||||
|
||||
test('row 14 — one more entry than the roster carries is the one reported (limit+1)', () => {
|
||||
const text = emptySections({ References: '| Reference | Role |\n|---|---|\n| `only.md` | Only. |' });
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(text, { references: ['only.md', 'extra.md'] }).missingRows,
|
||||
['references/extra.md'],
|
||||
);
|
||||
});
|
||||
|
||||
test('row 16 — nested step/mode families are deliberately out of scope', () => {
|
||||
// docs/INVENTORY.md §"Workflow Sub-Files": "Adding a step or mode file requires no
|
||||
// hand-written row here". If that decision is ever reversed, this row is what has to
|
||||
// change first — deliberately and in the open, rather than by widening
|
||||
// ROSTER_SECTIONS and discovering 62 red rows.
|
||||
assert.deepStrictEqual(
|
||||
findMissingRosterRows(emptySections(), {
|
||||
workflow_steps: ['quick/steps/a.md', 'quick/steps/b.md'],
|
||||
workflow_modes: ['discuss-phase/modes/default.md'],
|
||||
}),
|
||||
{ missingSections: [], missingRows: [] },
|
||||
);
|
||||
});
|
||||
|
||||
test('the failure message names every missing path and the remedy that satisfies it', () => {
|
||||
const rendered = formatRosterFailure({
|
||||
missingSections: [],
|
||||
missingRows: ['references/planner-coupling.md', 'cli_modules/hook-bus.cjs'],
|
||||
});
|
||||
|
||||
assert.match(rendered, /references\/planner-coupling\.md/);
|
||||
assert.match(rendered, /cli_modules\/hook-bus\.cjs/);
|
||||
assert.match(
|
||||
rendered,
|
||||
/Regenerating the manifest does NOT satisfy this/,
|
||||
'the predictable wrong guess is "run the generator"; the message has to close that door',
|
||||
);
|
||||
});
|
||||
|
||||
test('property — a command is reported missing exactly when no Source link names its file', () => {
|
||||
// The cell-equality property below covers the five families that share one rule.
|
||||
// `commands` is the family with its OWN rule, and therefore the one where an
|
||||
// untested edge is most likely — so it gets its own property rather than riding on
|
||||
// the five hand-written command fixtures.
|
||||
const stemArb = fc.stringMatching(/^[a-z][a-z0-9-]{0,10}$/);
|
||||
|
||||
fc.assert(
|
||||
fc.property(
|
||||
fc.uniqueArray(stemArb, { minLength: 1, maxLength: 8 }),
|
||||
fc.uniqueArray(stemArb, { maxLength: 8 }),
|
||||
(linked, candidates) => {
|
||||
const absent = candidates.filter((c) => !linked.includes(c));
|
||||
// Render each row with a DISPLAY NAME that is deliberately not the file stem,
|
||||
// mirroring the six real namespace routers: if the matcher ever falls back to
|
||||
// the rendered name, this property fails.
|
||||
const rows = linked
|
||||
.map((s) => '| `/gsd-alias-' + s + '` | role | [src](../commands/gsd/' + s + '.md) |')
|
||||
.join('\n');
|
||||
const text = emptySections({ Commands: '| Command | Role | Source |\n|---|---|---|\n' + rows });
|
||||
|
||||
const { missingRows } = findMissingRosterRows(text, {
|
||||
commands: [...linked, ...absent].map((s) => '/gsd-' + s),
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(
|
||||
missingRows.slice().sort(),
|
||||
absent.map((s) => 'commands//gsd-' + s).sort(),
|
||||
);
|
||||
},
|
||||
),
|
||||
);
|
||||
});
|
||||
|
||||
test('property — an entry is reported missing exactly when no cell in its section equals it', () => {
|
||||
const nameArb = fc.stringMatching(/^[a-z][a-z0-9-]{0,10}\.md$/);
|
||||
|
||||
fc.assert(
|
||||
fc.property(
|
||||
fc.uniqueArray(nameArb, { minLength: 1, maxLength: 8 }),
|
||||
fc.uniqueArray(nameArb, { maxLength: 8 }),
|
||||
(rostered, candidates) => {
|
||||
// `candidates` may overlap `rostered`; the entries genuinely absent from the
|
||||
// table are exactly the set difference, and that is what the matcher must
|
||||
// return — no more (false red) and no fewer (false pass).
|
||||
const absent = candidates.filter((c) => !rostered.includes(c));
|
||||
const rows = rostered.map((n) => '| `' + n + '` | role |').join('\n');
|
||||
const text = emptySections({ References: '| Reference | Role |\n|---|---|\n' + rows });
|
||||
|
||||
const { missingRows } = findMissingRosterRows(text, {
|
||||
references: [...rostered, ...absent],
|
||||
});
|
||||
|
||||
assert.deepStrictEqual(
|
||||
missingRows.slice().sort(),
|
||||
absent.map((e) => 'references/' + e).sort(),
|
||||
);
|
||||
},
|
||||
),
|
||||
);
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user