@opengsd/gsd-core 1.11.0 → 1.13.0

package/scripts/lint-docs-guard-registration.cjs

@@ -0,0 +1,495 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-docs-guard-registration.cjs — every test file that READS a docs/ path
+ * (via a real filesystem read call, not merely a string mention) must either
+ * be named in the docs-guard lane registry, or carry an explicit
+ * `// docs-guard-exempt: <reason>` marker.
+ *
+ * Exported pure function `checkDocsGuardRegistration({ testsDir, registry })`
+ * so tests can drive it against a synthetic fixture directory; also runnable
+ * as a CLI against the real tree (`node scripts/lint-docs-guard-registration.cjs`).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { assertWithinAllowlist } = require('./lib/allowlist-ratchet.cjs');
+const { assertNoSuiteCollision } = require('./docs-guard-registry.cjs');
+const {
+  DOCS_GUARD_EXEMPT_BASELINE,
+  DOCS_GUARD_EXEMPT_DOCS_PATHS,
+} = require('./lint-docs-guard-registration.exempt-baseline.cjs');
+
+/**
+ * The lint's registry MUST derive from scripts/docs-guard-registry.cjs's
+ * `DOCS_GUARD_TESTS` export — not from a second, hand-maintained list.
+ * #3753 found exactly that split: this file used to carry its own
+ * DOCS_GUARD_REGISTRY literal (20 entries) while the list that actually
+ * drives the CI lane only had 10, so the lint reported "registered and
+ * fine" for ten guards the lane never ran — the silent gap #3753 exists to
+ * close, rebuilt one level down. Two lists holding one shared fact are free
+ * to drift; one list read from two places cannot.
+ *
+ * Returns basenames (test files all live flat under tests/), matching the
+ * shape `checkDocsGuardRegistration` expects.
+ */
+function deriveDocsGuardRegistry() {
+  const { DOCS_GUARD_TEST_FILES } = require('./docs-guard-registry.cjs');
+  if (!Array.isArray(DOCS_GUARD_TEST_FILES) || DOCS_GUARD_TEST_FILES.length === 0) {
+    throw new Error(
+      'lint-docs-guard-registration: scripts/docs-guard-registry.cjs exported an empty or ' +
+      'missing DOCS_GUARD_TEST_FILES — cannot derive a registry. An empty registry would either flag ' +
+      'every docs-reading test as unregistered, or (with an empty comparison set) silently pass ' +
+      'with zero coverage. Fix the registry rather than defaulting this to [].',
+    );
+  }
+  // Redundant with docs-guard-registry.cjs's own module-load-time self-check
+  // (both consumers of that module — this lint and the docs-required.yml
+  // derivation step — must independently reject a suite-token collision per
+  // #3753's security follow-up FIX 3), but kept explicit here rather than
+  // relying solely on the shared module's require()-time throw: this call
+  // makes the guard visible and independently testable from this file's own
+  // exports, instead of depending on an implicit side effect of another
+  // module's load.
+  assertNoSuiteCollision(DOCS_GUARD_TEST_FILES);
+  return DOCS_GUARD_TEST_FILES.map(t => path.basename(t));
+}
+
+// Real filesystem read calls we treat as "this file reads a path". A docs/
+// path appearing only inside a string literal handed to something else
+// (e.g. assert.equal(msg, 'see docs/foo.md')) must NOT trip this.
+//
+// Detector 1 (segment-shaped): `fs.readFileSync(path.join(ROOT, 'docs', 'x.md'))`.
+// The docs/ path is built from separate path-segment arguments to a known
+// Node fs read function, so it looks for a bare `'docs'` (or `"docs"`/`` `docs` ``)
+// segment, or a `'docs/...'` literal, inside the parenthesized argument list
+// of one of READ_FN_NAMES.
+const READ_FN_NAMES = ['readFileSync', 'readFile', 'readdirSync', 'readdir', 'createReadStream'];
+const READ_CALL_RE = new RegExp(
+  `\\b(?:${READ_FN_NAMES.join('|')})\\s*\\(([^()]*(?:\\([^()]*\\)[^()]*)*)\\)`,
+  'g',
+);
+const DOCS_QUOTED_PATH_RE = /(['"`])\/?docs\/[^'"`]*\1/;
+const DOCS_QUOTED_SEGMENT_RE = /(['"`])docs\1/;
+
+// Detector 2 (single-string-shaped, #3753): `readShipped('docs/how-to/x.md')`.
+// Detector 1 is blind to this spelling — the docs/ path is a single string
+// literal, not a `path.join('docs', ...)` segment, and it is not always
+// handed straight to a bare `fs.read*` call. This is exactly how
+// tests/ui-spec-inventory-provenance.test.cjs reads — the guard whose
+// unregistered drift broke `next` on dacae9273 and motivated #3753 in the
+// first place — so a lint that cannot see its own motivating case's spelling
+// is not a fix.
+//
+// A naive "flag any 'docs/...' string literal" rule produces 59 hits on the
+// real tree (most are mention-only, e.g. assert messages), which is enough
+// false-positive noise that the lint gets disabled rather than obeyed. This
+// heuristic instead requires the docs/ literal to be an argument to a call
+// whose CALLEE NAME looks like a reader (contains read/load/parse/shipped/
+// content/file/doc, case-insensitively) — e.g. `readShipped`, `readRepoFile`,
+// `loadDoc`, `parseContent`. That name-shape restriction is what keeps the
+// count at 6 new hits instead of 59, at the cost of also matching a few
+// call sites (e.g. `groupFilesBySubrepo('docs/x.md', ...)`) whose name
+// happens to contain one of those substrings without actually reading a
+// file — those get `// docs-guard-exempt:` markers instead of registration.
+//
+// Detector 3 (co-occurrence, #3753 correctness follow-up — DEFECT B): the
+// two detectors above only catch a docs/ PATH EXPRESSION passed INLINE, as
+// an argument, to a call in the same statement. The dominant real idiom in
+// this repo builds the path first (`const P = path.join(ROOT, 'docs',
+// 'X.md');`) and reads it later (`fs.readFileSync(P);`) — a two-step form
+// neither detector above can see, along with template-literal
+// (`` `${ROOT}/docs/X.md` ``) and string-concat (`ROOT + '/docs/X.md'`)
+// paths. This detector decouples "does the file build a docs/ path" from
+// "does the file perform a read call" and flags the file when BOTH are true
+// anywhere in it, regardless of whether they share a call site. This trades
+// precision for recall deliberately: a false positive costs one
+// `// docs-guard-exempt:` marker with a reason; a false negative is the
+// #3753 bug shipping again.
+//
+// A docs/ path EXPRESSION is: a quoted 'docs/...' / "docs/..." literal
+// (optionally with a leading slash, for the `ROOT + '/docs/x.md'`
+// string-concat form), a backtick template literal containing `docs/`
+// anywhere inside it (covers both a bare `` `docs/x.md` `` literal and an
+// interpolated `` `${ROOT}/docs/x.md` `` prefix), or a bare `'docs'` segment
+// passed as one of the arguments to a `path.join(...)` call anywhere in the
+// file (not just when that call is itself an argument to a read function).
+const DOCS_TEMPLATE_LITERAL_RE = /`[^`]*\bdocs\/[^`]*`/;
+const PATH_JOIN_CALL_RE = /\bpath\s*\.\s*join\s*\(([^()]*(?:\([^()]*\)[^()]*)*)\)/g;
+
+function pathJoinHasDocsSegment(content) {
+  let match;
+  PATH_JOIN_CALL_RE.lastIndex = 0;
+  while ((match = PATH_JOIN_CALL_RE.exec(content)) !== null) {
+    if (DOCS_QUOTED_SEGMENT_RE.test(match[1]) || DOCS_QUOTED_PATH_RE.test(match[1])) return true;
+  }
+  return false;
+}
+
+function hasDocsPathExpression(content) {
+  return DOCS_QUOTED_PATH_RE.test(content) ||
+    DOCS_TEMPLATE_LITERAL_RE.test(content) ||
+    pathJoinHasDocsSegment(content);
+}
+
+// A "real read" for the co-occurrence detector: any call to a known Node fs
+// read function, ANYWHERE in the file — deliberately not requiring its
+// argument to look like a docs/ path here (that pairing is what
+// hasDocsPathExpression establishes separately). Does not include
+// `existsSync`: a pure existence check with no content read is exactly the
+// "incidental" case this lint's exemption path exists for, not a guard.
+const READ_CALL_PRESENT_RE = new RegExp(`\\b(?:${READ_FN_NAMES.join('|')})\\s*\\(`);
+
+// Detector 2 (single-string-shaped, #3753): `readShipped('docs/how-to/x.md')`.
+// Detector 1 is blind to this spelling — the docs/ path is a single string
+// literal, not a `path.join('docs', ...)` segment, and it is not always
+// handed straight to a bare `fs.read*` call. This is exactly how
+// tests/ui-spec-inventory-provenance.test.cjs reads — the guard whose
+// unregistered drift broke `next` on dacae9273 and motivated #3753 in the
+// first place — so a lint that cannot see its own motivating case's spelling
+// is not a fix.
+//
+// A naive "flag any 'docs/...' string literal" rule produces 59 hits on the
+// real tree (most are mention-only, e.g. assert messages), which is enough
+// false-positive noise that the lint gets disabled rather than obeyed. This
+// heuristic instead requires the docs/ literal to be an argument to a call
+// whose CALLEE NAME looks like a reader (contains read/load/parse/shipped/
+// content/file/doc, case-insensitively) — e.g. `readShipped`, `readRepoFile`,
+// `loadDoc`, `parseContent`. The callee-name test is applied to the WHOLE
+// captured identifier (never requiring a non-keyword prefix before it — see
+// DEFECT A, #3753 correctness follow-up: a prior version of this regex wove
+// the keyword alternation into the SAME character class as a mandatory
+// leading identifier-start character, which made it structurally impossible
+// for the keyword to start at index 0 and silently missed every bare `read(`,
+// `load(`, `parse(`, `content(`, `file(`, and `doc(` callee — this repo's
+// most common reader-helper name among them), at the cost of also matching a
+// few call sites (e.g. `groupFilesBySubrepo('docs/x.md', ...)`) whose name
+// happens to contain one of those substrings without actually reading a
+// file — those get `// docs-guard-exempt:` markers instead of registration.
+const READER_NAME_KEYWORDS_RE = /read|load|parse|shipped|content|file|doc/i;
+const READER_CALL_RE = /\b([A-Za-z_$][\w$]*)\s*\(\s*[^)]{0,60}?["'`]docs\//gi;
+
+function readerNameCallHasDocsPath(content) {
+  let match;
+  READER_CALL_RE.lastIndex = 0;
+  while ((match = READER_CALL_RE.exec(content)) !== null) {
+    if (READER_NAME_KEYWORDS_RE.test(match[1])) return true;
+  }
+  return false;
+}
+
+// Neither detector can see every spelling a docs read could take (e.g. a
+// path built through an indirect helper with a read-agnostic name whose call
+// site never contains a real fs read call in the same file). This registry
+// is a curated, best-effort net with known holes, not an exhaustive static
+// analysis.
+function argsReadDocsPath(args) {
+  return DOCS_QUOTED_PATH_RE.test(args) || DOCS_QUOTED_SEGMENT_RE.test(args);
+}
+
+function readsDocsPath(content) {
+  let match;
+  READ_CALL_RE.lastIndex = 0;
+  while ((match = READ_CALL_RE.exec(content)) !== null) {
+    if (argsReadDocsPath(match[1])) return true;
+  }
+  if (readerNameCallHasDocsPath(content)) return true;
+  return hasDocsPathExpression(content) && READ_CALL_PRESENT_RE.test(content);
+}
+
+// Only scan the file's HEADER — the first EXEMPTION_SCAN_LINES lines. Scanning
+// the whole file lets a `// docs-guard-exempt:`-shaped string embedded in a
+// fixture/template literal (this lint's own test file writes exactly such
+// strings to synthesize fixtures) exempt the entire real file it appears in.
+// A header marker convention closes that hole while still finding every
+// genuine exemption comment, which by convention sits near the top of the
+// file next to its module docstring.
+const EXEMPTION_SCAN_LINES = 20;
+
+// DEFECT C (#3753 correctness follow-up): a marker is only honored when the
+// line it appears on is an actual COMMENT, not merely a line whose text
+// contains the marker shape. Probed pre-fix: a string literal like
+//   const s = "// docs-guard-exempt: whatever";
+// self-exempted the file with zero signal — the header-window narrowing
+// (EXEMPTION_SCAN_LINES) constrains WHERE the marker may appear but never
+// constrained WHAT KIND of line it must be, so relocating the marker inside
+// a string literal anywhere in the header window still worked. Requiring
+// the line, after trimming leading whitespace, to actually START with a
+// comment token (`//`, `/*`, or a JSDoc-block `*` continuation line) closes
+// this without narrowing the legitimate cases: every real marker in this
+// repo's tests/ sits at column 0 as a full-line `//` comment (verified
+// against every current `docs-guard-exempt:` occurrence in tests/).
+const EXEMPTION_LINE_IS_COMMENT_RE = /^(?:\/\/|\/\*|\*)/;
+
+// Security follow-up FIX 4: a marker line inside a multi-line template
+// literal in the header window (e.g. `const F = \`\n// docs-guard-exempt: x\n\`;`)
+// still exempted the file pre-fix — the line, taken on its own, starts with
+// `//` and so passed EXEMPTION_LINE_IS_COMMENT_RE even though it is actually
+// backtick-string CONTENT, not a real comment. Track backtick parity across
+// lines: a line whose entire span is inside an open template literal (i.e.
+// the literal was already open when the line STARTED) is never honored as a
+// comment, no matter what its own text looks like.
+function findExemption(content) {
+  const lines = content.split(/\r?\n/).slice(0, EXEMPTION_SCAN_LINES);
+  let inTemplateLiteral = false;
+  let inBlockComment = false;
+  for (const line of lines) {
+    const lineStartedInTemplateLiteral = inTemplateLiteral;
+    // Count unescaped backticks on this line to toggle template-literal state.
+    const backtickCount = (line.match(/\\`|`/g) || []).filter((tok) => tok === '`').length;
+    if (backtickCount % 2 === 1) inTemplateLiteral = !inTemplateLiteral;
+    if (lineStartedInTemplateLiteral) continue;
+
+    // Track (real) /* ... */ block-comment state across lines: a line that
+    // is genuinely CONTENT inside an open, unterminated block comment is
+    // still a real comment (JS syntax), so it stays eligible — this state is
+    // tracked only so a future check can distinguish "inside a real block
+    // comment" from "inside a template literal" rather than conflating them.
+    const opensBlockComment = /\/\*/.test(line);
+    const closesBlockComment = /\*\//.test(line);
+    if (!inBlockComment && opensBlockComment && !closesBlockComment) {
+      inBlockComment = true;
+    } else if (inBlockComment && closesBlockComment) {
+      inBlockComment = false;
+    }
+
+    if (!EXEMPTION_LINE_IS_COMMENT_RE.test(line.trimStart())) continue;
+    const m = /\/\/\s*docs-guard-exempt:(.*)$/.exec(line);
+    if (m) return { present: true, reason: m[1].trim() };
+  }
+  return { present: false, reason: '' };
+}
+
+/**
+ * Security follow-up FIX 3: the exempt ratchet gated on file IDENTITY only —
+ * a baselined file that later STARTS genuinely reading shipped docs/ content
+ * stayed exempt with zero signal (probed: a baselined file doing
+ * `fs.readFileSync('docs/foo.md')` still reported `ok=true, violations=[]`).
+ * This extracts every distinct `docs/...` path TOKEN referenced anywhere in
+ * an exempted file's content, so the baseline can pin a per-file fingerprint
+ * of what it references and fail loudly when that set changes — forcing a
+ * human to re-confirm the exemption still holds. Deliberately broader than
+ * "only tokens passed to a read call" (this module's readsDocsPath heuristics
+ * above): the fingerprint's job is to catch ANY drift in what docs/ paths an
+ * exempted file mentions, not just the ones already read-call-shaped, since
+ * a mention today can become a read call tomorrow without changing the
+ * mention text at all.
+ */
+const DOCS_PATH_TOKEN_RE = /\/?docs\/[A-Za-z0-9_./-]*[A-Za-z0-9_-]/g;
+
+/**
+ * @param {string} content
+ * @returns {string[]} sorted, deduped list of docs/ path tokens referenced —
+ *   a readable, diffable fingerprint (never an opaque hash) so a reviewer can
+ *   see exactly what changed.
+ */
+function extractDocsPathReferences(content) {
+  const set = new Set();
+  let m;
+  DOCS_PATH_TOKEN_RE.lastIndex = 0;
+  while ((m = DOCS_PATH_TOKEN_RE.exec(content)) !== null) {
+    set.add(m[0].replace(/^\//, ''));
+  }
+  return [...set].sort();
+}
+
+/**
+ * Compare each currently-exempted file's live docs-path fingerprint against
+ * its pinned baseline fingerprint. A file present in `current` whose sorted
+ * path list differs from the baseline's (paths added OR removed) is a
+ * violation: the exemption's premise ("this file doesn't really guard
+ * shipped docs content") may no longer hold and a human must re-confirm it.
+ *
+ * @param {Record<string, string[]>} current - file -> live sorted docs/ path list.
+ * @param {Record<string, string[]>} baseline - file -> pinned sorted docs/ path list.
+ * @returns {Array<{ file: string, reason: string }>}
+ */
+function checkExemptFingerprints(current, baseline) {
+  const violations = [];
+  for (const [file, paths] of Object.entries(current)) {
+    const baselinePaths = baseline[file];
+    if (!baselinePaths) continue; // identity ratchet (checkExemptBaseline) already flags a novel exemption
+    const currentJoined = paths.join('\n');
+    const baselineJoined = [...baselinePaths].sort().join('\n');
+    if (currentJoined !== baselineJoined) {
+      violations.push({
+        file,
+        reason:
+          `the docs paths referenced by ${file} changed; re-confirm the exemption still holds and ` +
+          `update the baseline in ${EXEMPT_BASELINE_FILE}:${EXEMPT_BASELINE_DOCS_PATHS_CONST}. ` +
+          `was: [${baselinePaths.join(', ') || '(none)'}], now: [${paths.join(', ') || '(none)'}]`,
+      });
+    }
+  }
+  return violations;
+}
+
+/**
+ * File referenced in this module's own remedy messages below (kept as a
+ * named constant so the CLI path and the message text cannot drift).
+ */
+const EXEMPT_BASELINE_FILE = 'scripts/lint-docs-guard-registration.exempt-baseline.cjs';
+const EXEMPT_BASELINE_CONST = 'DOCS_GUARD_EXEMPT_BASELINE';
+const EXEMPT_BASELINE_DOCS_PATHS_CONST = 'DOCS_GUARD_EXEMPT_DOCS_PATHS';
+
+/**
+ * Ratchet the `// docs-guard-exempt:` marker on file identity, mirroring
+ * scripts/lint-allow-test-rule-refs.cjs's `allow-test-rule` identity ratchet
+ * (scripts/lib/allowlist-ratchet.cjs, ADR-456's pattern): a NEW exemption not
+ * already in the pinned baseline fails the lint, and a baseline entry whose
+ * file no longer carries a real marker (removed, renamed, or the marker was
+ * deleted) is reported STALE and must be pruned — the baseline only ever
+ * moves by deliberate edit, never silently grows or goes stale unnoticed.
+ *
+ * Unlike the sibling gate's generic "do not just add to the allowlist"
+ * framing (which fits an offender-tracking allowlist), the correct remedy
+ * for a genuinely-warranted new docs-guard exemption really is to add it to
+ * the baseline — so the novel-entry case gets its own explicit remedy line
+ * here rather than reusing that wording verbatim.
+ *
+ * @param {string[]} exemptedFiles - basenames with a present, non-empty
+ *   `docs-guard-exempt:` marker, found in the current tree.
+ * @param {string[]} baseline - the pinned baseline (DOCS_GUARD_EXEMPT_BASELINE).
+ * @returns {Array<{ file: string, reason: string }>}
+ */
+function checkExemptBaseline(exemptedFiles, baseline) {
+  const violations = [];
+  const { novel } = assertWithinAllowlist({
+    label: 'docs-guard-exempt',
+    current: exemptedFiles,
+    known: baseline,
+    fail: (msg) => violations.push({ file: '(docs-guard-exempt baseline)', reason: msg }),
+    pruneHint:
+      `its file was removed, renamed, or no longer carries a docs-guard-exempt marker — ` +
+      `prune it from the baseline in ${EXEMPT_BASELINE_FILE}:${EXEMPT_BASELINE_CONST}`,
+  });
+  if (novel.length > 0) {
+    violations.push({
+      file: '(docs-guard-exempt baseline)',
+      reason:
+        `${novel.length} NEW docs-guard-exempt marker(s) not in the pinned baseline: ` +
+        `${novel.join(', ')} — if this exemption is correct, add it to the baseline in ` +
+        `${EXEMPT_BASELINE_FILE}:${EXEMPT_BASELINE_CONST}`,
+    });
+  }
+  return violations;
+}
+
+/**
+ * @param {{ testsDir: string, registry: string[], exemptBaseline?: string[] }} opts
+ *   `exemptBaseline`, when provided, ratchets the docs-guard-exempt marker on
+ *   file identity against that pinned list (see `checkExemptBaseline`).
+ *   Omitted entirely by callers (e.g. isolated fixture-only tests) that do
+ *   not want the ratchet applied.
+ * @returns {{ ok: boolean, violations: Array<{ file: string, reason: string }>, exemptedFiles: string[] }}
+ */
+function checkDocsGuardRegistration({ testsDir, registry, exemptBaseline, exemptDocsPathsBaseline }) {
+  const violations = [];
+  const exemptedFiles = [];
+  const exemptedDocsPaths = {};
+
+  for (const entry of registry) {
+    const full = path.join(testsDir, entry);
+    if (!fs.existsSync(full)) {
+      violations.push({ file: entry, reason: `registry entry does not exist on disk: ${full}` });
+    }
+  }
+
+  const registrySet = new Set(registry);
+  let files;
+  try {
+    files = fs.readdirSync(testsDir).filter(f => f.endsWith('.test.cjs'));
+  } catch (err) {
+    // A guard that cannot read its own input must never report success.
+    // Probed pre-fix: checkDocsGuardRegistration({testsDir:'/nonexistent',
+    // registry:[]}) returned {ok:true, violations:[]} — a green check that
+    // guarded nothing. Treat an unreadable testsDir as a HARD VIOLATION.
+    return {
+      ok: false,
+      violations: [
+        {
+          file: '(testsDir)',
+          reason: `cannot read testsDir ${testsDir}: ${err.message} — a docs-guard registration ` +
+            'lint that cannot read its own input must fail, never silently report zero violations',
+        },
+      ],
+      exemptedFiles: [],
+    };
+  }
+
+  for (const file of files) {
+    const full = path.join(testsDir, file);
+    let content;
+    try {
+      content = fs.readFileSync(full, 'utf8');
+    } catch (err) {
+      // Same class: a directory or broken symlink named `*.test.cjs` (or any
+      // other read failure) must be a hard violation, not a silent skip.
+      violations.push({
+        file,
+        reason: `cannot read candidate test file ${full}: ${err.message} — an unreadable ` +
+          'docs-guard candidate must fail the lint, not be silently skipped',
+      });
+      continue;
+    }
+
+    const exemption = findExemption(content);
+    if (exemption.present) {
+      if (exemption.reason.length === 0) {
+        violations.push({ file, reason: 'docs-guard-exempt marker present with no reason' });
+      } else {
+        exemptedFiles.push(file);
+        exemptedDocsPaths[file] = extractDocsPathReferences(content);
+      }
+      continue;
+    }
+
+    if (readsDocsPath(content) && !registrySet.has(file)) {
+      violations.push({
+        file,
+        reason: 'reads a docs/ path but is not registered in the docs-guard lane and carries no docs-guard-exempt marker',
+      });
+    }
+  }
+
+  if (exemptBaseline) {
+    violations.push(...checkExemptBaseline(exemptedFiles, exemptBaseline));
+  }
+
+  if (exemptDocsPathsBaseline) {
+    violations.push(...checkExemptFingerprints(exemptedDocsPaths, exemptDocsPathsBaseline));
+  }
+
+  return { ok: violations.length === 0, violations, exemptedFiles, exemptedDocsPaths };
+}
+
+module.exports = {
+  checkDocsGuardRegistration,
+  checkExemptBaseline,
+  checkExemptFingerprints,
+  extractDocsPathReferences,
+  deriveDocsGuardRegistry,
+  EXEMPT_BASELINE_FILE,
+  EXEMPT_BASELINE_CONST,
+  EXEMPT_BASELINE_DOCS_PATHS_CONST,
+};
+
+if (require.main === module) {
+  const ROOT = path.join(__dirname, '..');
+  const result = checkDocsGuardRegistration({
+    testsDir: path.join(ROOT, 'tests'),
+    registry: deriveDocsGuardRegistry(),
+    exemptBaseline: DOCS_GUARD_EXEMPT_BASELINE,
+    exemptDocsPathsBaseline: DOCS_GUARD_EXEMPT_DOCS_PATHS,
+  });
+  if (!result.ok) {
+    process.stderr.write(`lint-docs-guard-registration: ${result.violations.length} violation(s)\n`);
+    for (const v of result.violations) {
+      process.stderr.write(`  ${v.file}: ${v.reason}\n`);
+    }
+    process.exitCode = 1;
+  } else {
+    console.log('ok lint-docs-guard-registration: 0 violations');
+  }
+}