doctrina-cli 0.13.0 → 0.15.0

package/src/lib/doc-model.js

@@ -0,0 +1,287 @@
+// @ts-check
+// The one owner of the on-disk artifact grammar (audit item M3).
+//
+// `.doctrina/` is Doctrina's public API, and its specification had ten
+// homes. The ADR `Status:` grammar existed as ten regex literals across
+// three files, and they were NOT equivalent — some captured, one only
+// tested, two were anchored to end-of-line and so silently failed on a
+// trailing space. Section extraction was reimplemented six times under six
+// names: `extractSection` (twice), `sectionOf`, `sectionParagraph`,
+// `productSection`, and the sections map in `spec-ops`.
+//
+// This violates the framework's own design principle #1 — "single
+// ownership of every fact; no information has two homes."
+//
+// The contract here:
+//
+//   LENIENT ON READ.  `- **Status**: x` and `**Status:** x` both parse, and
+//     a non-canonical form is REPORTED (so `validate --fix` can repair it)
+//     rather than silently accepted or silently missed.
+//   STRICT ON WRITE.  One canonical form per artifact kind, always.
+
+// Artifact kinds and the header form each one canonically uses. Specs and
+// contracts use bare bold; ADRs, proposals, and the intake use list items.
+// Getting this backwards was a documented, recurring authoring mistake, so
+// the CLI now decides it rather than the author remembering.
+export const HEADER_STYLE = Object.freeze({
+  BARE: "bare",   // **Status:** active
+  LIST: "list",   // - **Status:** accepted
+});
+
+export const ARTIFACT_KIND = Object.freeze({
+  SPEC: "spec",
+  CONTRACT: "contract",
+  DECISION: "decision",
+  PROPOSAL: "proposal",
+  INTAKE: "intake",
+  PRODUCT: "product",
+  UNKNOWN: "unknown",
+});
+
+const STYLE_BY_KIND = {
+  [ARTIFACT_KIND.SPEC]: HEADER_STYLE.BARE,
+  [ARTIFACT_KIND.CONTRACT]: HEADER_STYLE.BARE,
+  [ARTIFACT_KIND.PRODUCT]: HEADER_STYLE.BARE,
+  [ARTIFACT_KIND.DECISION]: HEADER_STYLE.LIST,
+  [ARTIFACT_KIND.PROPOSAL]: HEADER_STYLE.LIST,
+  [ARTIFACT_KIND.INTAKE]: HEADER_STYLE.LIST,
+  [ARTIFACT_KIND.UNKNOWN]: HEADER_STYLE.BARE,
+};
+
+export function canonicalStyle(kind) {
+  return STYLE_BY_KIND[kind] ?? HEADER_STYLE.BARE;
+}
+
+// Infer the artifact kind from its path. Deterministic; never reads content.
+export function kindFromPath(relPathPosix) {
+  const p = String(relPathPosix).replace(/\\/g, "/");
+  if (/\/specs\/[^/]+\/spec\.md$/.test(p)) return ARTIFACT_KIND.SPEC;
+  if (/\/contracts\/[^/]+\.md$/.test(p)) return ARTIFACT_KIND.CONTRACT;
+  if (/\/decisions\/\d{4}-.*\.md$/.test(p)) return ARTIFACT_KIND.DECISION;
+  if (/\/changes\/.*\/proposal\.md$/.test(p)) return ARTIFACT_KIND.PROPOSAL;
+  if (/\/intake\.md$/.test(p)) return ARTIFACT_KIND.INTAKE;
+  if (/\/product\.md$/.test(p)) return ARTIFACT_KIND.PRODUCT;
+  return ARTIFACT_KIND.UNKNOWN;
+}
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// THE header grammar. One definition.
+//
+// Lenient by construction: the leading "- " is optional, the colon may sit
+// inside or outside the bold span (`**Status:**` or `**Status**:`), and the
+// value runs to end of line with surrounding space trimmed by the caller.
+// Anchoring to `$` without allowing trailing whitespace is what made two of
+// the old copies fail on files saved with a trailing space.
+// A metadata header REQUIRES a colon, inside or outside the bold span.
+// Without that, bold text used as a pseudo-heading in prose — the
+// `**Positive**` / `**Negative**` / `**Neutral**` blocks every ADR carries —
+// parses as a header and floods the conformance report.
+function headerPattern(name) {
+  const n = escapeRe(name);
+  return new RegExp(`^([ \\t]*)(-[ \\t]+)?\\*\\*${n}[ \\t]*(?::\\*\\*|\\*\\*[ \\t]*:)[ \\t]*(.*?)[ \\t]*$`, "m");
+}
+
+// Read one header. Returns { value, style, conforming, line } or null.
+/**
+ * @returns {{ value: string, style: string, indent: string, raw: string,
+ *             line: number, conforming: boolean } | null}
+ */
+export function readHeader(text, name) {
+  const m = headerPattern(name).exec(String(text));
+  if (!m) return null;
+  const [raw, indent, dash, value] = m;
+  const style = dash ? HEADER_STYLE.LIST : HEADER_STYLE.BARE;
+  // Canonical is exactly `**Name:** value` (or `- **Name:** value`).
+  const canonical = `${dash ? "- " : ""}**${name}:** ${value}`.replace(/\s+$/, "");
+  return {
+    value: value.trim(),
+    style,
+    indent,
+    raw,
+    line: text.slice(0, m.index).split("\n").length,
+    conforming: raw.trim() === canonical.trim(),
+  };
+}
+
+// The value only, or null. The replacement for specHeader/listHeader and
+// every ad-hoc `match(/^-\s+\*\*Status:\*\*.../)`.
+export function getHeader(text, name) {
+  return readHeader(text, name)?.value ?? null;
+}
+
+// Write a header in the canonical form for `style`, preserving the style
+// already present when the header exists. Returns the new text, or null
+// when the header is absent — a set that silently does nothing is exactly
+// the drift this prevents.
+/**
+ * @param {string} text
+ * @param {string} name
+ * @param {string} value
+ * @param {{ style?: string }} [opts] Force a header style; defaults to the
+ *   style already present, so a set never silently reformats the artifact.
+ */
+export function setHeader(text, name, value, opts = {}) {
+  const { style } = opts;
+  const existing = readHeader(text, name);
+  if (!existing) return null;
+  const useStyle = style ?? existing.style;
+  const prefix = useStyle === HEADER_STYLE.LIST ? "- " : "";
+  const replacement = `${existing.indent}${prefix}**${name}:** ${value}`.replace(/\s+$/, "");
+  return String(text).replace(headerPattern(name), replacement);
+}
+
+// The PREAMBLE: everything before the first `## ` section. Metadata headers
+// live there in every Doctrina artifact, and only there. Bold text ending in
+// a colon further down is a prose lead-in ("**Standing constraints lived in
+// agent memory:** ..."), not a header — scoping conformance to the preamble
+// is what tells the two apart without guessing.
+export function preamble(text) {
+  const s = String(text);
+  const m = /^##\s+/m.exec(s);
+  return m ? s.slice(0, m.index) : s;
+}
+
+// Every header in the document's preamble, in order, with conformance
+// recorded.
+export function readAllHeaders(fullText) {
+  const text = preamble(fullText);
+  const out = [];
+  const re = /^([ \t]*)(-[ \t]+)?\*\*([A-Za-z][A-Za-z .-]*?)[ \t]*(?::\*\*|\*\*[ \t]*:)[ \t]*(.*?)[ \t]*$/gm;
+  let m;
+  while ((m = re.exec(String(text)))) {
+    const [raw, indent, dash, name, value] = m;
+    const style = dash ? HEADER_STYLE.LIST : HEADER_STYLE.BARE;
+    const canonical = `${indent}${dash ? "- " : ""}**${name}:** ${value}`.replace(/\s+$/, "");
+    out.push({
+      name, value: value.trim(), style, indent,
+      line: String(text).slice(0, m.index).split("\n").length,
+      conforming: raw.replace(/\s+$/, "") === canonical,
+    });
+  }
+  return out;
+}
+
+// Headers whose written form is recognised but not canonical, optionally
+// also flagging the wrong style for a known artifact kind. This is what
+// `validate` reports and `validate --fix` repairs.
+/** @param {string} text @param {string} [kind] */
+export function nonConformingHeaders(text, kind = ARTIFACT_KIND.UNKNOWN) {
+  const want = canonicalStyle(kind);
+  const out = [];
+  for (const h of readAllHeaders(text)) {
+    const wrongStyle = kind !== ARTIFACT_KIND.UNKNOWN && h.style !== want;
+    if (!h.conforming || wrongStyle) {
+      out.push({ ...h, wrongStyle, expectedStyle: want });
+    }
+  }
+  return out;
+}
+
+// Rewrite every recognised header into the canonical form for `kind`.
+// Content is never touched — only the header's own punctuation and, when
+// the kind is known, its style.
+/** @param {string} text @param {string} [kind] */
+export function repairHeaders(text, kind = ARTIFACT_KIND.UNKNOWN) {
+  const want = canonicalStyle(kind);
+  const lines = String(text).split("\n");
+  // Repair only the PREAMBLE, and only lines that carry a colon — the same
+  // two constraints reading uses. Without them this rewrote ADR prose:
+  // `**Positive**` became `- **Positive:**`, and a bulleted definition list
+  // `- **dropped intent** — ...` became `- **dropped intent:** — ...`.
+  // A repair that edits prose is worse than the drift it fixes.
+  const firstSection = lines.findIndex((l) => /^##\s+/.test(l));
+  const limit = firstSection < 0 ? lines.length : firstSection;
+  let repaired = 0;
+  for (let i = 0; i < limit; i++) {
+    // Match against the line without its carriage return. On a CRLF
+    // checkout the trailing \r is not [ \t], so anchoring to $ silently
+    // matched nothing and repair became a no-op on exactly the files most
+    // likely to need it.
+    const line = lines[i].replace(/\r$/, "");
+    const eol = lines[i].endsWith("\r") ? "\r" : "";
+    const m = /^([ \t]*)(-[ \t]+)?\*\*([A-Za-z][A-Za-z .-]*?)[ \t]*(?::\*\*|\*\*[ \t]*:)[ \t]*(.*?)[ \t]*$/.exec(line);
+    if (!m) continue;
+    const [, indent, dash, name, value] = m;
+    const style = kind === ARTIFACT_KIND.UNKNOWN ? (dash ? HEADER_STYLE.LIST : HEADER_STYLE.BARE) : want;
+    const canonical = `${indent}${style === HEADER_STYLE.LIST ? "- " : ""}**${name}:** ${value}`.replace(/[ \t]+$/, "");
+    if (line.replace(/[ \t]+$/, "") !== canonical) {
+      // Preserve the file's existing line ending: repairing a header must
+      // not rewrite every line of a CRLF file as a side effect.
+      lines[i] = canonical + eol;
+      repaired += 1;
+    }
+  }
+  return { text: lines.join("\n"), repaired };
+}
+
+// ---------------------------------------------------------------- sections
+
+// The body of a `## <name>` section: lines after the heading, up to the
+// next heading of the same or higher level. Replaces six near-identical
+// helpers that disagreed about level handling and trailing whitespace.
+export function getSection(text, name, { level = 2 } = {}) {
+  const lines = String(text).split(/\r?\n/);
+  const head = new RegExp(`^#{${level}}\\s+${escapeRe(name)}\\b`, "i");
+  const boundary = new RegExp(`^#{1,${level}}\\s+`);
+  const out = [];
+  let inSection = false;
+  for (const line of lines) {
+    if (inSection && boundary.test(line)) break;
+    if (!inSection && head.test(line)) { inSection = true; continue; }
+    if (inSection) out.push(line);
+  }
+  return inSection ? out.join("\n") : "";
+}
+
+export function hasSection(text, name, { level = 2 } = {}) {
+  return new RegExp(`^#{${level}}\\s+${escapeRe(name)}\\b`, "im").test(String(text));
+}
+
+// The first non-empty, non-comment paragraph of a section — what `why` and
+// `skill suggest` actually wanted when they each rolled their own.
+export function getSectionParagraph(text, name, { level = 2 } = {}) {
+  const body = getSection(text, name, { level });
+  const para = [];
+  for (const line of body.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("<!--")) continue;
+    if (trimmed === "") {
+      if (para.length > 0) break;
+      continue;
+    }
+    para.push(trimmed);
+  }
+  return para.join(" ");
+}
+
+// Every `## ` heading in document order.
+export function listSections(text, { level = 2 } = {}) {
+  const re = new RegExp(`^#{${level}}\\s+(.+)$`, "gm");
+  const out = [];
+  let m;
+  while ((m = re.exec(String(text)))) out.push(m[1].trim());
+  return out;
+}
+
+// The document's H1 title, or null.
+export function getTitle(text) {
+  const m = /^#\s+(.+)$/m.exec(String(text));
+  return m ? m[1].trim() : null;
+}
+
+// One parse of an artifact: title, headers, section names. The shape
+// `parseArtifact` promises, so callers stop re-deriving it.
+export function parseArtifact(text, { kind = ARTIFACT_KIND.UNKNOWN } = {}) {
+  const headers = readAllHeaders(text);
+  return {
+    kind,
+    title: getTitle(text),
+    headers,
+    headerMap: new Map(headers.map((h) => [h.name, h.value])),
+    sections: listSections(text),
+    nonConforming: nonConformingHeaders(text, kind),
+  };
+}

package/src/lib/docs-impact.js

@@ -0,0 +1,167 @@
+// @ts-check
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { isFile, read, walk } from "./fs-ops.js";
+import { COMMAND_NAMES } from "./commands.js";
+import { locateTemplatesDir } from "./templates.js";
+
+// "Docs ship inside the change, never after it" (audit item D2).
+//
+// A docs phase scheduled AFTER the work never happens. So a change that
+// alters a documented surface — a command, a flag, an exit code — must also
+// carry the documentation for it, checked at close time and refusable with
+// --force exactly like the archive verification gate.
+//
+// Both halves are deterministic: what the change says it touches is read
+// from its own artifacts, and whether docs moved is read from git. No
+// language understanding (ADR 0005).
+
+const DOC_PATHS = [/^docs\//, /^README\.md$/, /^README\.pt\.md$/];
+
+// Non-empty lines of the shipped change templates, so authored content can
+// be told apart from scaffold. Computed once; falls back to an empty set
+// when the templates cannot be located (unusual installs), which only makes
+// the gate more eager, never wrong about a real signal.
+// Ticking a scaffold checkbox rewrites "- [ ] ..." to "- [x] ...", which
+// would otherwise stop the line matching its own template and make every
+// completed change look authored. Compare with the box state normalised.
+function normaliseScaffoldLine(line) {
+  return line.trim().replace(/^-\s*\[[ xX]\]/, "- [ ]");
+}
+
+let scaffoldCache = null;
+function scaffoldLines() {
+  if (scaffoldCache) return scaffoldCache;
+  const lines = new Set();
+  try {
+    const changeTemplates = path.join(locateTemplatesDir(), "change");
+    for (const f of walk(changeTemplates)) {
+      for (const line of read(f).split(/\r?\n/)) {
+        const trimmed = normaliseScaffoldLine(line);
+        if (trimmed) lines.add(trimmed);
+      }
+    }
+  } catch { /* no templates dir — treat everything as authored */ }
+  scaffoldCache = lines;
+  return lines;
+}
+
+// Does this change alter something the documentation makes promises about?
+// Read from the change's own artifacts — the deltas it will merge into
+// specs, plus the proposal that states its shape. Returns the list of
+// signals found (empty when the change touches no documented surface).
+export function documentedSurfaceSignals(changeDir) {
+  const signals = [];
+  const known = new Set(COMMAND_NAMES);
+
+  // Read only what the AUTHOR wrote. The scaffold's own boilerplate names
+  // commands — the proposal's Verification checklist cites `doctrina verify`
+  // and `doctrina coverage` — so scanning the raw file made every change look
+  // like it touched a documented surface. A gate that fires on everything is
+  // a gate that gets ignored, so the template's lines are subtracted first.
+  const boilerplate = scaffoldLines();
+  const authored = (text) => text
+    .split(/\r?\n/)
+    .filter((line) => !boilerplate.has(normaliseScaffoldLine(line)))
+    .join("\n");
+
+  const sources = [];
+  const proposal = path.join(changeDir, "proposal.md");
+  if (isFile(proposal)) sources.push(authored(read(proposal)));
+  for (const p of walk(path.join(changeDir, "specs"))) {
+    if (p.endsWith("delta.md")) sources.push(authored(read(p)));
+  }
+  const text = sources.join("\n");
+  if (!text.trim()) return signals;
+
+  // Command references, from code context only, so prose about "the
+  // doctrina framework" is not a signal.
+  const chunks = [];
+  const outside = text.replace(/```[\s\S]*?```/g, (b) => { chunks.push(b); return "\n"; });
+  for (const m of outside.matchAll(/`[^`]+`/g)) chunks.push(m[0]);
+  const code = chunks.join("\n");
+
+  const commands = new Set();
+  for (const m of code.matchAll(/(?:npx\s+doctrina-cli|doctrina)\s+([a-z][a-z-]+)/g)) {
+    if (known.has(m[1])) commands.add(m[1]);
+  }
+  if (commands.size > 0) {
+    signals.push(`commands: ${[...commands].sort().join(", ")}`);
+  }
+
+  const flags = new Set();
+  for (const m of code.matchAll(/--([a-z][a-z0-9-]{2,})/g)) flags.add(`--${m[1]}`);
+  if (flags.size > 0) {
+    signals.push(`flags: ${[...flags].sort().slice(0, 8).join(", ")}`);
+  }
+
+  if (/\bexit\s+code|\bexits?\s+(?:with\s+)?[0-4]\b/i.test(text)) {
+    signals.push("exit codes");
+  }
+
+  return signals;
+}
+
+// Documentation paths touched by the work in flight. Union of the working
+// tree (uncommitted, the common agent case) and this branch's commits
+// against the default branch (the case where the agent already committed).
+// Returns [] outside a git repository — where the gate cannot see, it does
+// not accuse.
+//
+// KNOWN COARSENESS: this answers "did documentation move in this work?",
+// not "did documentation move FOR THIS CHANGE?". Closing several changes
+// from one uncommitted working tree, docs written for an earlier change
+// satisfy the gate for a later one. The gate is deliberately permissive
+// here — its job is to stop a change shipping with NO documentation at
+// all, and attributing a hunk to a change would need guesswork the rest of
+// the framework refuses to do (ADR 0005).
+export function docsTouched(projectRoot) {
+  const git = (args) => {
+    const r = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
+    if (r.error || r.status !== 0) return [];
+    return r.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+  };
+  const set = new Set();
+  for (const f of git(["diff", "--name-only", "HEAD"])) set.add(f);
+  for (const f of git(["ls-files", "--others", "--exclude-standard"])) set.add(f);
+  for (const base of ["main", "master"]) {
+    const mb = git(["merge-base", "HEAD", base]);
+    if (mb.length > 0) {
+      for (const f of git(["diff", "--name-only", `${mb[0]}..HEAD`])) set.add(f);
+      break;
+    }
+  }
+  return [...set]
+    .map((f) => f.replace(/\\/g, "/"))
+    .filter((f) => DOC_PATHS.some((re) => re.test(f)));
+}
+
+export function isGitRepo(projectRoot) {
+  const r = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+    cwd: projectRoot, encoding: "utf8",
+  });
+  return !r.error && r.status === 0;
+}
+
+// The gate itself: { ok, signals, touched, reason }. `ok` is true when the
+// change touches no documented surface, when documentation moved with it,
+// or when git cannot answer.
+export function checkDocsImpact(projectRoot, changeDir) {
+  const signals = documentedSurfaceSignals(changeDir);
+  if (signals.length === 0) {
+    return { ok: true, signals, touched: [], reason: "touches no documented surface" };
+  }
+  if (!isGitRepo(projectRoot)) {
+    return { ok: true, signals, touched: [], reason: "not a git repository — cannot tell what moved" };
+  }
+  const touched = docsTouched(projectRoot);
+  if (touched.length > 0) {
+    return { ok: true, signals, touched, reason: `documentation moved with it (${touched.length} file${touched.length === 1 ? "" : "s"})` };
+  }
+  return {
+    ok: false,
+    signals,
+    touched,
+    reason: "alters a documented surface but no docs/ or README change accompanies it",
+  };
+}

package/src/lib/ears.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Structural EARS checks for capability specs. The clarify command catches
 // word-level smells; this catches grammar-shape problems per EARS section.
 // All findings are warnings: specs evolve, validation should not block.

package/src/lib/exit-codes.js

@@ -0,0 +1,103 @@
+// @ts-check
+// The exit-code contract (audit item C7).
+//
+// Code 1 used to mean three different things, and an agent driving the
+// loop could not tell them apart:
+//
+//   "your change is not ready"       -> iterate and retry
+//   "this project is not configured" -> run a setup command first
+//   "this machine cannot run this"   -> stop
+//
+// All three returned 1. The first means keep working, the second means do
+// something else first, the third means give up — and an autonomous loop
+// that cannot distinguish them either spins on an unfixable failure or
+// abandons a fixable one.
+//
+// This is the smallest module in the CLI and the one a machine consumer
+// depends on most. Every command's exit path maps to a member here.
+
+export const EXIT = Object.freeze({
+  /** The command did what it was asked. Warnings are allowed. */
+  OK: 0,
+  /** A gate failed: the WORK is not ready. Fix the work and retry. */
+  GATE: 1,
+  /** The INVOCATION is wrong: unknown command, missing/malformed argument.
+   *  Do not retry unchanged. */
+  USAGE: 2,
+  /** A PRECONDITION is missing: the project is not set up for this yet.
+   *  Run the named setup command, then retry. */
+  PRECONDITION: 3,
+  /** The ENVIRONMENT cannot run this: git absent, unreadable tree, and
+   *  other conditions no amount of retrying fixes. Stop. */
+  ENVIRONMENT: 4,
+});
+
+// What each code means, for `--help`, the docs, and the tests that assert
+// the mapping. Keyed by numeric code so a consumer can look one up.
+export const EXIT_MEANINGS = Object.freeze({
+  [EXIT.OK]: {
+    name: "OK",
+    summary: "success (warnings allowed)",
+    agentAction: "continue",
+  },
+  [EXIT.GATE]: {
+    name: "GATE",
+    summary: "a gate failed — the work is not ready",
+    agentAction: "fix the work, then retry the same command",
+  },
+  [EXIT.USAGE]: {
+    name: "USAGE",
+    summary: "the invocation is wrong — unknown command or bad argument",
+    agentAction: "do not retry unchanged; correct the invocation",
+  },
+  [EXIT.PRECONDITION]: {
+    name: "PRECONDITION",
+    summary: "a precondition is missing — the project is not set up for this",
+    agentAction: "run the setup command named in the error, then retry",
+  },
+  [EXIT.ENVIRONMENT]: {
+    name: "ENVIRONMENT",
+    summary: "the environment cannot run this command",
+    agentAction: "stop; retrying will not help",
+  },
+});
+
+// The block `doctrina --help` prints, generated so help and contract
+// cannot drift.
+export function exitCodeHelp() {
+  return Object.entries(EXIT_MEANINGS)
+    .map(([code, m]) => `  ${code}  ${m.summary}`)
+    .join("\n");
+}
+
+// A precondition failure, thrown by a command whose project/config is not
+// ready. The entrypoint maps it to EXIT.PRECONDITION and prints the setup
+// command, so every "you need to run X first" path reports the same code.
+export class PreconditionError extends Error {
+  constructor(message, remedy) {
+    super(message);
+    this.name = "PreconditionError";
+    this.exitCode = EXIT.PRECONDITION;
+    this.remedy = remedy ?? null;
+  }
+}
+
+// An environment failure: the machine, not the project, is the problem.
+export class EnvironmentError extends Error {
+  constructor(message, remedy) {
+    super(message);
+    this.name = "EnvironmentError";
+    this.exitCode = EXIT.ENVIRONMENT;
+    this.remedy = remedy ?? null;
+  }
+}
+
+// "Not a Doctrina project" is the single most common precondition, raised
+// by nearly every command. One constructor so the message and the code
+// stay identical everywhere.
+export function notADoctrinaProject() {
+  return new PreconditionError(
+    "not a Doctrina project (no .doctrina/ in cwd)",
+    "doctrina init",
+  );
+}

package/src/lib/flag-catalog.js

@@ -0,0 +1,106 @@
+// @ts-check
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { COMMAND_NAMES } from "./commands.js";
+
+// One catalog of "which flags does command X accept", with two consumers:
+//
+//   - the static undeclared-flag test (C3), which asserts every flag a
+//     command READS is declared, so `parseArgs` never swallows a positional
+//     as an undeclared flag's value again; and
+//   - the docs accuracy gate (D1, `scripts/check-docs.js`), which asserts
+//     every flag the DOCS document against a command is declared.
+//
+// One invariant, two checks: source and prose are held to the same list, so
+// a renamed flag cannot stay green in either place. Both read a command
+// module's exported `flags` — the declaration lives WITH the command, not in
+// the entrypoint, which is why an added command no longer requires editing
+// `src/index.js` to make its flags parse (the structural half of C3).
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const commandsDir = path.join(here, "..", "commands");
+
+// Flags the entrypoint owns for every command; a command never redeclares them.
+export const GLOBAL_FLAGS = Object.freeze({
+  boolean: ["help", "h", "v", "debug"],
+  string: [],
+});
+
+// Command name -> module filename. Every command's module is `<name>.js`
+// except where this map says otherwise.
+const MODULE_OVERRIDES = { index: "index-rebuild.js" };
+
+export function moduleFileFor(commandName) {
+  return MODULE_OVERRIDES[commandName] ?? `${commandName}.js`;
+}
+
+export function modulePathFor(commandName) {
+  return path.join(commandsDir, moduleFileFor(commandName));
+}
+
+// The flag spec a command module exports, normalised to
+// { boolean: string[], string: string[] }. Returns null when the module
+// declares none — which the C3 test treats as a failure and the docs gate
+// treats as "not checkable yet", so the two can land independently.
+export async function loadFlagSpec(commandName) {
+  const mod = await import(pathToUrl(modulePathFor(commandName)));
+  const spec = mod.flags;
+  if (!spec) return null;
+  return {
+    boolean: [...(spec.boolean ?? [])],
+    string: [...(spec.string ?? [])],
+  };
+}
+
+// Every flag name a command accepts (own + global), as a Set. null when the
+// command declares no spec.
+export async function declaredFlags(commandName) {
+  const spec = await loadFlagSpec(commandName);
+  if (!spec) return null;
+  return new Set([
+    ...spec.boolean, ...spec.string,
+    ...GLOBAL_FLAGS.boolean, ...GLOBAL_FLAGS.string,
+  ]);
+}
+
+export async function loadAllFlagSpecs() {
+  const out = new Map();
+  for (const name of COMMAND_NAMES) out.set(name, await loadFlagSpec(name));
+  return out;
+}
+
+// Flag names a source file READS, by scanning its call sites:
+//   flagBool(flags, "x")  flagString(flags, "x")  flags.has("x")  flags.get("x")
+// Deterministic text scan, not execution — it sees every branch, including
+// the ones a given run never takes.
+export function scanFlagUsage(sourceText) {
+  const used = new Set();
+  const patterns = [
+    /flagBool\(\s*flags\s*,\s*["']([^"']+)["']/g,
+    /flagString\(\s*flags\s*,\s*["']([^"']+)["']/g,
+    /flags\.has\(\s*["']([^"']+)["']/g,
+    /flags\.get\(\s*["']([^"']+)["']/g,
+  ];
+  for (const re of patterns) {
+    for (const m of sourceText.matchAll(re)) used.add(m[1]);
+  }
+  return used;
+}
+
+export function readCommandSource(commandName) {
+  return readFileSync(modulePathFor(commandName), "utf8");
+}
+
+// Flags a command's `help` string documents: every `--flag` token in it.
+// The docs gate compares prose against this too, so help and reference
+// cannot drift apart from the declaration.
+export function scanHelpFlags(helpText) {
+  const out = new Set();
+  for (const m of String(helpText ?? "").matchAll(/--([a-z][a-z0-9-]*)/g)) out.add(m[1]);
+  return out;
+}
+
+function pathToUrl(p) {
+  return "file:///" + p.replace(/\\/g, "/");
+}

package/src/lib/fs-ops.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, renameSync, unlinkSync, rmdirSync } from "node:fs";
 import path from "node:path";