@mmerterden/multi-agent-pipeline 17.1.0 → 17.4.0

package/pipeline/scripts/verify-citations.mjs

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+
+/**
+ * @file verify-citations.mjs  -  a `file:line` that nothing resolves is a guess.
+ *
+ * Two surfaces in this pipeline require a citation and neither has ever checked
+ * one. `reviewer-output.schema.json` makes `file` and `line` required on every
+ * finding; `analysis-spec.schema.json` carries `repoEvidence` entries of
+ * `{name, file, line, tag}` and `analysis/locked.md` (Locked 37) asks for
+ * `repo/file:line` on every current-behaviour row. The only check that existed
+ * was `validate-analysis-doc.mjs`'s `/:\d+\b/` - a test that the row LOOKS like
+ * a citation, satisfied by `Foo.swift:9999` in a repo with no Foo.swift.
+ *
+ * The judgement is moved out of the model and into git. A path is resolved at a
+ * commit, not on the working tree, so a run that cites a file deleted three
+ * commits ago fails instead of passing on whatever happens to be checked out.
+ *
+ * Inputs:
+ *   <file>              JSON or markdown to read. `-` reads stdin.
+ *   --repo <path>       Repository root. Default: cwd
+ *   --rev <sha>         Commit to resolve against. Default: HEAD
+ *   --worktree          Resolve against the CHECKOUT instead of a commit. For
+ *                       Phase 4, where a reviewer cites lines the dev has not
+ *                       committed yet and a commit-pinned check would call
+ *                       every one of them invented.
+ *   --json              Machine-readable report
+ *   --quiet             Exit code only
+ *
+ * Accepted shapes, detected rather than declared, so one script serves both
+ * callers and neither has to say which it is:
+ *   - reviewer output   `{findings: [{file, line, ...}]}`
+ *   - triage output     `{accepted|deferred|rejected: [{file, line, ...}]}`
+ *   - analysis spec     `{evidence: {repoEvidence: {<repo>: {buckets: ...}}}}`
+ *   - markdown          every `path/to/file.ext:123` in the prose
+ *
+ * Exit codes:
+ *   0   -  every citation resolved, or there were none to resolve
+ *   1   -  at least one citation did not resolve
+ *   2   -  the input could not be read or is not a repository
+ *   64  -  usage error
+ *
+ * @module pipeline/scripts/verify-citations
+ */
+
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { resolve as resolvePath, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+
+/**
+ * Reject a path before it reaches git.
+ *
+ * `git show <rev>:<path>` happily resolves `../` out of the tree and an
+ * absolute path against the filesystem, so a citation could name something the
+ * repository does not contain and still "resolve". The guard is here rather
+ * than in the caller because every caller would otherwise need it.
+ *
+ * @param {string} p
+ * @returns {string|null} the reason it is unsafe, or null
+ */
+export function unsafePath(p) {
+  if (!p) return "empty path";
+  if (p.startsWith("/")) return "absolute path";
+  if (p.includes("\\")) return "backslash in path";
+  const parts = p.split("/");
+  if (parts.includes("..")) return "path escapes the repository";
+  if (parts.includes(".git")) return "path reaches into .git";
+  return null;
+}
+
+/**
+ * Pull `{file, line}` pairs out of whatever was handed over.
+ *
+ * @param {string} raw
+ * @returns {{file: string, line: number|null, where: string}[]}
+ */
+export function extract(raw) {
+  const out = [];
+  const push = (file, line, where) => {
+    if (typeof file === "string" && file.trim()) {
+      out.push({ file: file.trim(), line: Number.isFinite(line) ? line : null, where });
+    }
+  };
+
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    doc = null;
+  }
+
+  if (doc && typeof doc === "object") {
+    for (const key of ["findings", "accepted", "deferred", "rejected"]) {
+      for (const [i, f] of (doc[key] || []).entries()) {
+        if (f && typeof f === "object") push(f.file, Number(f.line), `${key}[${i}]`);
+      }
+    }
+    const repoEvidence = doc?.evidence?.repoEvidence || doc?.analysisSpec?.evidence?.repoEvidence;
+    if (repoEvidence && typeof repoEvidence === "object") {
+      for (const [repo, body] of Object.entries(repoEvidence)) {
+        for (const [bucket, rows] of Object.entries(body?.buckets || {})) {
+          for (const [i, r] of (rows || []).entries()) {
+            if (r && typeof r === "object") {
+              push(r.file, Number(r.line), `repoEvidence.${repo}.${bucket}[${i}]`);
+            }
+          }
+        }
+      }
+    }
+    return out;
+  }
+
+  // Markdown. A citation is a path with an extension followed by a line number.
+  //
+  // Two things that look exactly like one and are not:
+  //
+  //   - a URL with a port. `https://wiki.example.com:8443/x` hands
+  //     `wiki.example.com:8443` to the matcher, and an analysis document is
+  //     full of Confluence, Jira and Figma links. Left in, this gate blocked
+  //     dispatch on every real document and reported "absolute path" as the
+  //     reason, which is not even the right complaint. URLs are removed first.
+  //   - a dotted number. `v1.2:30` has an "extension" of `2`, so the extension
+  //     must START with a letter. No source file is named `.2`.
+  //
+  // Fenced blocks are skipped for the same class of reason: a code sample that
+  // happens to contain `foo.js:12` is an illustration, not a claim about this
+  // repository.
+  let fenced = false;
+  raw.split("\n").forEach((line, i) => {
+    if (/^\s*```/.test(line)) {
+      fenced = !fenced;
+      return;
+    }
+    if (fenced) return;
+    const cleaned = line.replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, " ");
+    for (const m of cleaned.matchAll(/([A-Za-z0-9_./-]+\.[A-Za-z][A-Za-z0-9]*):(\d+)/g)) {
+      push(m[1], Number(m[2]), `line ${i + 1}`);
+    }
+  });
+  return out;
+}
+
+/**
+ * Resolve one citation at a commit, or in the checkout when `rev` is null.
+ *
+ * @param {string} repo
+ * @param {string|null} rev
+ * @param {{file: string, line: number|null}} c
+ * @param {Map<string, number|null>} lineCache
+ * @returns {string|null} the reason it failed, or null
+ */
+export function resolveOne(repo, rev, c, lineCache) {
+  const unsafe = unsafePath(c.file);
+  if (unsafe) return unsafe;
+
+  if (!lineCache.has(c.file)) {
+    lineCache.set(c.file, rev === null ? worktreeLines(repo, c.file) : revLines(repo, rev, c.file));
+  }
+
+  const lines = lineCache.get(c.file);
+  const at = rev === null ? "in the working tree" : `at ${rev.slice(0, 12)}`;
+  if (lines === null) return `no such file ${at}`;
+  if (c.line === null) return null;
+  if (c.line < 1) return `line ${c.line} is not a line number`;
+  if (c.line > lines) return `line ${c.line} is past the end of the file (${lines} lines)`;
+  return null;
+}
+
+/**
+ * Line count of a blob at a commit, or null when the path is not a file there.
+ *
+ * @param {string} repo
+ * @param {string} rev
+ * @param {string} file
+ * @returns {number|null}
+ */
+function revLines(repo, rev, file) {
+  const t = spawnSync("git", ["-C", repo, "cat-file", "-t", `${rev}:${file}`], {
+    encoding: "utf-8",
+  });
+  if (t.status !== 0 || t.stdout.trim() !== "blob") return null;
+  const show = spawnSync("git", ["-C", repo, "show", `${rev}:${file}`], {
+    encoding: "utf-8",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return countLines(show.status === 0 ? show.stdout : "");
+}
+
+/**
+ * Line count in the checkout, or null when there is no such file.
+ *
+ * `unsafePath` cannot see a symlink: `docs/out -> /etc` is a relative path with
+ * no `..` in it, and git never followed it because git reads blobs rather than
+ * the filesystem. In worktree mode the filesystem IS the source, so containment
+ * is re-checked after the path is resolved.
+ *
+ * @param {string} repo
+ * @param {string} file
+ * @returns {number|null}
+ */
+function worktreeLines(repo, file) {
+  let real;
+  let root;
+  try {
+    root = realpathSync(repo);
+    real = realpathSync(resolvePath(root, file));
+  } catch {
+    return null;
+  }
+  if (real !== root && !real.startsWith(root + sep)) return null;
+  try {
+    if (!statSync(real).isFile()) return null;
+    return countLines(readFileSync(real, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A file with no trailing newline still has its last line.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function countLines(text) {
+  if (text.length === 0) return 0;
+  return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+}
+
+/**
+ * @param {object} params
+ * @returns {{checked: number, unresolved: object[], rev: string}}
+ */
+export function verify({ raw, repo, rev }) {
+  const citations = extract(raw);
+  const lineCache = new Map();
+  const unresolved = [];
+  for (const c of citations) {
+    const reason = resolveOne(repo, rev, c, lineCache);
+    if (reason) unresolved.push({ ...c, reason });
+  }
+  return { checked: citations.length, unresolved, rev };
+}
+
+const VALUE_FLAGS = new Set(["--repo", "--rev"]);
+
+/**
+ * One pass, positionally. `argv.indexOf(a)` finds the FIRST occurrence of a
+ * string, so `--repo . file .` would have mis-identified which `.` was the
+ * target; walking the list is both simpler and correct.
+ *
+ * @param {string[]} argv
+ * @returns {{target: string|null, repo: string|null, rev: string|null}}
+ */
+export function parseArgs(argv) {
+  let target = null;
+  let repo = null;
+  let rev = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (VALUE_FLAGS.has(a)) {
+      const v = argv[i + 1];
+      if (v !== undefined && !v.startsWith("--")) {
+        if (a === "--repo") repo = v;
+        else rev = v;
+        i++;
+      }
+      continue;
+    }
+    if (a.startsWith("--")) continue;
+    if (target === null) target = a;
+  }
+  return { target, repo, rev };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const parsed = parseArgs(argv);
+  const target = parsed.target;
+  if (!target) {
+    console.error(
+      "usage: verify-citations.mjs <file|-> [--repo <path>] [--rev <sha>|--worktree] [--json] [--quiet]",
+    );
+    process.exit(64);
+  }
+
+  const repo = parsed.repo || process.cwd();
+  const worktree = argv.includes("--worktree");
+  if (worktree && parsed.rev) {
+    console.error("verify-citations: --worktree and --rev name two different trees; pick one");
+    process.exit(64);
+  }
+  const rev = parsed.rev || "HEAD";
+  const json = argv.includes("--json");
+  const quiet = argv.includes("--quiet");
+
+  let raw;
+  try {
+    raw = target === "-" ? readFileSync(0, "utf-8") : readFileSync(target, "utf-8");
+  } catch (e) {
+    console.error(`verify-citations: cannot read ${target}: ${e.message}`);
+    process.exit(2);
+  }
+
+  const top = spawnSync("git", ["-C", repo, "rev-parse", "--show-toplevel"], { encoding: "utf-8" });
+  if (top.status !== 0) {
+    console.error(`verify-citations: ${repo} is not a git repository`);
+    process.exit(2);
+  }
+  let sha = null;
+  if (!worktree) {
+    const head = spawnSync("git", ["-C", repo, "rev-parse", rev], { encoding: "utf-8" });
+    if (head.status !== 0) {
+      console.error(`verify-citations: ${rev} is not a commit in ${repo}`);
+      process.exit(2);
+    }
+    sha = head.stdout.trim();
+  }
+
+  const report = verify({ raw, repo, rev: sha });
+  const where = sha === null ? "in the working tree" : `at ${sha.slice(0, 12)}`;
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else if (!quiet) {
+    if (report.unresolved.length === 0) {
+      console.log(`verify-citations: ${report.checked} citation(s) resolve ${where}`);
+    } else {
+      console.log(
+        `verify-citations: ${report.unresolved.length} of ${report.checked} citation(s) do not resolve ${where}:`,
+      );
+      for (const u of report.unresolved) {
+        console.log(`  ${u.where}: ${u.file}${u.line === null ? "" : `:${u.line}`} - ${u.reason}`);
+      }
+      // The cheap way to make this exit 0 is to delete the line number, which
+      // turns a wrong claim into an unfalsifiable one. Said here because this
+      // is the moment someone is deciding what to do about it.
+      console.log("  Re-search and correct the citation; never drop the line number to pass.");
+    }
+  }
+
+  process.exit(report.unresolved.length === 0 ? 0 : 1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}