doctrina-cli 0.3.0 → 0.6.0

package/src/commands/validate.js

@@ -3,12 +3,16 @@ import process from "node:process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, lineCount, read, relPath, walk } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
+import { SCHEMA_VERSION } from "../lib/index-json.js";
+import { cliVersion } from "../lib/version.js";
+import { today } from "../lib/dates.js";
+import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { parseFrontmatter } from "./skill.js";
 import { checkEars, isEarsSpec } from "../lib/ears.js";
-import { specHeader, listHeader } from "../lib/scan.js";
+import { specHeader, listHeader, deriveIndex, indexesMatch, stableStringify } from "../lib/scan.js";
 
-export async function run(_positional, _flags) {
+export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   const errors = [];
   const warnings = [];
@@ -45,8 +49,36 @@ export async function run(_positional, _flags) {
   }
 
   if (index) {
-    if (index.$schema_version !== "0.1.0") {
-      warnings.push(`index.json $schema_version is "${index.$schema_version}" (expected "0.1.0")`);
+    // --fix (F5): regenerate the index from the tree before validating, so a
+    // drifted index is repaired rather than reported. A full rebuild — it also
+    // absorbs orphans and migrates the framework stamp, matching
+    // `index rebuild`. Subsequent checks then see the repaired index.
+    if (flagBool(flags, "fix", false)) {
+      const derived = deriveIndex(projectRoot, index);
+      const staleStamp = (index.framework_version ?? null) !== cliVersion();
+      if (!indexesMatch(derived, index) || staleStamp) {
+        derived.framework_version = cliVersion();
+        derived.last_updated = today();
+        idx.save(projectRoot, derived);
+        console.log(c.green("fixed") + " rebuilt .doctrina/index.json from the tree");
+        index = derived;
+      }
+    }
+
+    if (index.$schema_version !== SCHEMA_VERSION) {
+      warnings.push(`index.json $schema_version is "${index.$schema_version}" (expected "${SCHEMA_VERSION}")`);
+    }
+    // framework_version stamp divergence (3.6). The index records which CLI
+    // manages it; a stamp behind (or absent vs.) the running CLI means the
+    // tree may predate the current schema. `index rebuild` migrates it.
+    const runningVersion = cliVersion();
+    if (!index.framework_version) {
+      warnings.push(`index.json has no framework_version (run \`doctrina index rebuild\` to stamp it)`);
+    } else if (index.framework_version !== runningVersion) {
+      warnings.push(
+        `index.json framework_version is "${index.framework_version}" but the running CLI is ` +
+          `${runningVersion} (run \`doctrina index rebuild\` to stamp/migrate)`,
+      );
     }
     if (!index.artifacts) {
       errors.push("index.json missing artifacts object");
@@ -64,25 +96,38 @@ export async function run(_positional, _flags) {
         if (!exists(full)) errors.push(`index.json references missing artifact: ${rel}`);
       }
 
-      // 4b. Spec version drift — the Version: header inside each spec
-      //     must match the version recorded in index.json.
-      for (const s of index.artifacts.specs ?? []) {
-        const full = path.join(projectRoot, s.path);
-        if (!isFile(full)) continue;
-        const m = read(full).match(/^(?:-\s+)?\*\*Version:\*\*\s+(\S+)/m);
-        if (m && s.version && m[1] !== s.version) {
-          warnings.push(`${s.path} declares version ${m[1]} but index.json records ${s.version} (sync the index)`);
-        }
+      // 4b. Index metadata drift (F5 / review G5 / G7). validate is the single
+      //     source of truth about whether the project is OK, so an indexed
+      //     artifact whose recorded metadata (version, implementation, status,
+      //     ...) no longer matches its file is an ERROR here — not a
+      //     pass-with-warning that only `index rebuild --check` would catch
+      //     (the "validate says OK while next says drift" footgun). Presence
+      //     drift (orphan on disk / missing file) stays the orphan warning and
+      //     the missing-artifact error above; this targets the metadata that
+      //     silently lies. `validate --fix` (above) regenerates instead.
+      const derived = deriveIndex(projectRoot, index);
+      for (const line of metadataDrift(index, derived)) {
+        errors.push(`${line} — run \`doctrina validate --fix\` or \`doctrina index rebuild\``);
       }
     }
   }
 
   // 5. ADRs have parseable Status: header
   const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  // Track which files claim each NNNN so a merge-time collision (two branches
+  // both allocating the same number) becomes a loud error rather than one ADR
+  // silently shadowing the other (C2).
+  const adrByNumber = new Map();
   if (isDir(adrDir)) {
     for (const f of walk(adrDir)) {
       if (!f.endsWith(".md")) continue;
       const base = path.basename(f);
+      const numMatch = base.match(/^(\d{4})-/);
+      const num = numMatch ? numMatch[1] : null;
+      if (num) {
+        if (!adrByNumber.has(num)) adrByNumber.set(num, []);
+        adrByNumber.get(num).push(relPath(projectRoot, f));
+      }
       // ADR filenames must be NNNN-slug.md (four digits). The entire ADR
       // toolchain — decision new/accept/supersede, index derivation, and
       // the orphan check below — keys off this shape; a file like
@@ -105,33 +150,50 @@ export async function run(_positional, _flags) {
       // 5b. ADR evidence drift. A decision is only true if reality reflects
       //     it; an accepted ADR that points at nothing — or at a file that
       //     no longer exists — is the classic "ADR decrees X, the code
-      //     never did X". Only ADRs that adopt the **Evidence:** header are
-      //     checked, so legacy/process ADRs that opt out stay quiet.
+      //     never did X". Two header fields anchor a decision to reality:
+      //     **Evidence:** (cited at any point) and **Landed:** (the
+      //     non-mutating "this is now implemented and verified here" stamp,
+      //     written by `doctrina decision land`; 3.4). Both are checked for
+      //     dangling citations; an accepted ADR is only flagged bare when
+      //     BOTH are empty. ADRs that adopt neither header opt out entirely.
       const evidence = listHeader(text, "Evidence");
-      if (evidence !== null) {
-        const adrStatus = (listHeader(text, "Status") ?? "").toLowerCase();
-        const trimmed = evidence.trim();
-        const bare = trimmed === "—" || trimmed === "-" || trimmed === "";
-        if (bare) {
-          if (adrStatus === "accepted") {
+      const landed = listHeader(text, "Landed");
+      const isBare = (v) => {
+        const t = (v ?? "").trim();
+        return t === "" || t === "—" || t === "-";
+      };
+      for (const [field, value] of [["Evidence", evidence], ["Landed", landed]]) {
+        if (value === null || isBare(value)) continue;
+        for (const token of extractBacktickPaths(value)) {
+          const candidates = [path.resolve(path.dirname(f), token), path.resolve(projectRoot, token)];
+          if (!candidates.some(exists)) {
             warnings.push(
-              `${relPath(projectRoot, f)}: accepted ADR cites no implementation evidence ` +
-                `(link the file(s) that prove it, or note "n/a — <why>"); a decision with ` +
-                `nothing behind it may be drift waiting to be superseded`,
+              `${relPath(projectRoot, f)}: ${field} cites \`${token}\` which is missing on disk — ` +
+                `the decision may have drifted from the code (update it or supersede the ADR)`,
             );
           }
-        } else {
-          for (const token of extractBacktickPaths(evidence)) {
-            const candidates = [path.resolve(path.dirname(f), token), path.resolve(projectRoot, token)];
-            if (!candidates.some(exists)) {
-              warnings.push(
-                `${relPath(projectRoot, f)}: Evidence cites \`${token}\` which is missing on disk — ` +
-                  `the decision may have drifted from the code (update the evidence or supersede the ADR)`,
-              );
-            }
-          }
         }
       }
+      const adrStatus = (listHeader(text, "Status") ?? "").toLowerCase();
+      if (adrStatus === "accepted" && evidence !== null && isBare(evidence) && isBare(landed)) {
+        warnings.push(
+          `${relPath(projectRoot, f)}: accepted ADR cites no implementation evidence ` +
+            `(link the file(s) that prove it, run \`doctrina decision land ${num ?? "NNNN"}\` once ` +
+            `it ships, or note "n/a — <why>"); a decision with nothing behind it may be drift ` +
+            `waiting to be superseded`,
+        );
+      }
+    }
+
+    // 5c. Duplicate ADR numbers (C2).
+    for (const [num, files] of adrByNumber) {
+      if (files.length > 1) {
+        errors.push(
+          `ADR number ${num} is claimed by ${files.length} files (${files.join(", ")}) — ` +
+            `two branches likely allocated it concurrently; renumber all but one ` +
+            `(the index keys decisions by number, so duplicates silently shadow each other)`,
+        );
+      }
     }
   }
 
@@ -165,6 +227,7 @@ export async function run(_positional, _flags) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   if (isDir(specsDir)) {
     const { readdirSync } = await import("node:fs");
+    const KNOWN_SPEC_HEADERS = ["Capability", "Status", "Implementation", "Version", "Last updated", "Realizes"];
     for (const cap of readdirSync(specsDir)) {
       const specPath = path.join(specsDir, cap, "spec.md");
       if (isFile(specPath)) {
@@ -202,6 +265,26 @@ export async function run(_positional, _flags) {
             );
           }
         }
+
+        // 8d. Metadata-header shape (review G11). In the header block (before
+        //     the first `## ` section or `<!--` comment), a known key written
+        //     without the canonical `**Key:** value` form silently fails to
+        //     parse — the index then falls back to a default and drifts. Warn
+        //     with the fix rather than letting the mis-typed header vanish.
+        const headerLines = text.split(/\r?\n/);
+        for (let i = 0; i < headerLines.length; i++) {
+          if (/^\s*(##\s|<!--)/.test(headerLines[i])) break;
+          for (const key of KNOWN_SPEC_HEADERS) {
+            const attempt = new RegExp(`^\\s*-?\\s*\\**${key}\\**\\s*:`, "i");
+            const canonical = new RegExp(`^(?:-\\s+)?\\*\\*${key}:\\*\\*\\s+\\S`);
+            if (attempt.test(headerLines[i]) && !canonical.test(headerLines[i])) {
+              warnings.push(
+                `${relPath(projectRoot, specPath)}:${i + 1} metadata header "${key}" is not in ` +
+                  `canonical "**${key}:** value" form — it will not parse (G11)`,
+              );
+            }
+          }
+        }
       }
     }
   }
@@ -345,6 +428,29 @@ export async function run(_positional, _flags) {
   return errors.length === 0 ? 0 : 1;
 }
 
+// Per-entry metadata drift between the on-disk index and the tree-derived
+// one, for entries present in BOTH. Presence drift (an artifact on disk but
+// not indexed, or indexed but missing) is left to the orphan warning and the
+// missing-artifact error; this isolates the case the review hit — an indexed
+// artifact whose recorded metadata no longer matches its file.
+function metadataDrift(current, derived) {
+  const lines = [];
+  // Skills are deliberately excluded: their description has a dedicated
+  // reconciliation command (`doctrina skill sync`) and stays an advisory
+  // warning (see section 15), not a hard error.
+  const cats = ["specs", "decisions", "changes", "changes_archive", "contracts"];
+  for (const cat of cats) {
+    const cur = new Map((current.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
+    const der = new Map((derived.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
+    for (const [id, entry] of cur) {
+      if (der.has(id) && stableStringify(entry) !== stableStringify(der.get(id))) {
+        lines.push(`index.json: ${cat} "${id}" metadata differs from its file`);
+      }
+    }
+  }
+  return lines;
+}
+
 // Find AGENTS.md files below the root (the "nearest AGENTS.md wins"
 // hierarchy). Bounded walk: dependency, build, and VCS directories are
 // skipped so validate stays fast on large repositories.

package/src/commands/verify.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import process from "node:process";
+import { readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { exists, isFile, read, write, relPath } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 
@@ -32,6 +33,17 @@ export async function run(_positional, flags) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
   }
 
+  // --clean is the reproducibility lint (review G4): `verify` runs the
+  // declared checks against the *current* disk, so a repo that only works
+  // because a previous run generated a Prisma client or built a workspace's
+  // dist still passes — "verify green" ≠ "passes from a clean checkout".
+  // This is the static half of that gap: it flags the footguns that make a
+  // fresh `npm install` differ from the dirty machine, without doing a real
+  // (slow, package-manager-specific) clean install.
+  if (flagBool(flags, "clean", false)) {
+    return reproducibilityLint(projectRoot);
+  }
+
   const configPath = path.join(projectRoot, CONFIG_REL);
 
   // --init scaffolds a starter config so the gate is one edit away.
@@ -129,8 +141,142 @@ export async function run(_positional, flags) {
   return 1;
 }
 
+// Static reproducibility lint: walk the project's package.json files and
+// report the two "works on my machine" footguns the review hit — a package
+// whose entry points live in a build-output dir with nothing that builds it
+// on install, and a codegen dependency (Prisma) with no install hook that
+// generates. Returns 0 when clean, 1 when any risk is found. Pure read.
+function reproducibilityLint(projectRoot) {
+  const pkgPaths = findPackageJsons(projectRoot);
+  console.log(c.bold("doctrina verify --clean") + c.gray(" — reproducibility lint (static, not a real fresh install)"));
+  console.log("");
+
+  if (pkgPaths.length === 0) {
+    console.log(c.gray("no package.json found — nothing this lint can check (it knows Node/npm footguns)"));
+    return 0;
+  }
+
+  const findings = [];
+  for (const pkgPath of pkgPaths) {
+    const rel = relPath(projectRoot, pkgPath);
+    let pkg;
+    try {
+      pkg = JSON.parse(read(pkgPath));
+    } catch (err) {
+      findings.push(`${rel}: not valid JSON (${err.message})`);
+      continue;
+    }
+    const scripts = pkg.scripts ?? {};
+    const hasInstallBuild = typeof scripts.prepare === "string" || typeof scripts.prepack === "string";
+
+    // 1. Entry point into a build output with nothing to build it on install.
+    const built = entryIntoBuildDir(pkg);
+    if (built && !hasInstallBuild) {
+      findings.push(
+        `${rel}: ${built.field} → \`${built.value}\` is a build output, but no "prepare"/"prepack" ` +
+        `script builds it on install — a fresh install/clone won't have it (add a prepare script, or commit the output)`,
+      );
+    }
+
+    // 2. Codegen dependency with no install hook that generates.
+    const deps = {
+      ...pkg.dependencies, ...pkg.devDependencies,
+      ...pkg.peerDependencies, ...pkg.optionalDependencies,
+    };
+    for (const [dep, gen] of Object.entries(CODEGEN_DEPS)) {
+      if (!(dep in deps)) continue;
+      const installHook = `${scripts.postinstall ?? ""} ${scripts.prepare ?? ""}`;
+      if (!gen.test(installHook)) {
+        findings.push(
+          `${rel}: depends on "${dep}" but no "postinstall"/"prepare" runs its codegen ` +
+          `(\`${gen.source.replace(/\\s\+/g, " ")}\`) — a fresh install has no generated output`,
+        );
+      }
+    }
+  }
+
+  if (findings.length === 0) {
+    console.log(c.green("ok") + ` ${pkgPaths.length} package.json file${pkgPaths.length === 1 ? "" : "s"} — no reproducibility risks found`);
+    return 0;
+  }
+  for (const f of findings) console.log(`  ${c.yellow("!")} ${f}`);
+  console.log("");
+  console.log(c.red("fail") + ` ${findings.length} reproducibility risk${findings.length === 1 ? "" : "s"} — a clean checkout may not build`);
+  return 1;
+}
+
+// Known codegen dependencies → the command an install hook must run so a
+// fresh install produces their generated output.
+const CODEGEN_DEPS = {
+  "@prisma/client": /prisma\s+generate/,
+  "prisma": /prisma\s+generate/,
+};
+
+const BUILD_DIR_RE = /(?:^|\/)(?:dist|build|out)\//;
+
+// The first entry-point field that points into a build-output directory, or
+// null. Scans main/module/types/typings, bin (string or map), and exports
+// (recursively, string leaves only).
+function entryIntoBuildDir(pkg) {
+  for (const field of ["main", "module", "types", "typings"]) {
+    if (typeof pkg[field] === "string" && BUILD_DIR_RE.test(pkg[field])) {
+      return { field, value: pkg[field] };
+    }
+  }
+  if (typeof pkg.bin === "string" && BUILD_DIR_RE.test(pkg.bin)) return { field: "bin", value: pkg.bin };
+  if (pkg.bin && typeof pkg.bin === "object") {
+    for (const v of Object.values(pkg.bin)) {
+      if (typeof v === "string" && BUILD_DIR_RE.test(v)) return { field: "bin", value: v };
+    }
+  }
+  const fromExports = scanExports(pkg.exports);
+  if (fromExports) return { field: "exports", value: fromExports };
+  return null;
+}
+
+function scanExports(node) {
+  if (typeof node === "string") return BUILD_DIR_RE.test(node) ? node : null;
+  if (node && typeof node === "object") {
+    for (const v of Object.values(node)) {
+      const hit = scanExports(v);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+// Bounded walk for package.json files: skip dependency, build, and VCS
+// directories so the lint stays fast and ignores vendored manifests.
+const LINT_SKIP_DIRS = new Set([
+  ".git", "node_modules", "dist", "build", "out", "vendor", ".next",
+  "coverage", ".venv", "venv", "__pycache__", "target", ".doctrina",
+]);
+
+function findPackageJsons(projectRoot) {
+  const found = [];
+  const stack = [projectRoot];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!LINT_SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) stack.push(full);
+      } else if (entry.name === "package.json") {
+        found.push(full);
+      }
+    }
+  }
+  return found.sort();
+}
+
 export const help = `
-Usage: doctrina verify [--list] [--init] [--force]
+Usage: doctrina verify [--list] [--init] [--clean] [--force]
 
 Run the project-declared build/verify checks from ${CONFIG_REL} in order,
 streaming their output, and exit non-zero if any check fails. This is the
@@ -149,5 +295,9 @@ root, targets a sub-package in a monorepo):
 Flags:
   --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force)
   --list     Print the configured checks without running them
+  --clean    Don't run checks; lint the project's package.json files for
+             reproducibility footguns (entry points in a build dir with no
+             prepare/prepack; a Prisma dep with no generate on install) so
+             "verify green" can't hide a clean checkout that won't build.
   --force    With --init, overwrite an existing config
 `;