docguard-cli 0.40.5 → 0.41.1

package/cli/scanners/js-ast.mjs

@@ -185,16 +185,104 @@ export function extractJsSchemaBodies(content, filename = 'file.ts') {
 // are middleware-ish; `all` is included (it IS a route), `use` is not.
 const HTTP_METHOD_NAMES = new Set(['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'all']);
 
-/** Extract a string path from a call's first arg: StringLiteral or TemplateLiteral. */
-function pathArgValue(node) {
+function topLevelStaticStrings(ast) {
+  const declarations = new Map();
+  const body = ast?.program?.body || [];
+  for (const statement of body) {
+    const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+    if (declaration?.type !== 'VariableDeclaration' || declaration.kind !== 'const') continue;
+    for (const item of declaration.declarations || []) {
+      if (item.id?.type !== 'Identifier' || !item.init) continue;
+      if (declarations.has(item.id.name)) declarations.set(item.id.name, null);
+      else declarations.set(item.id.name, item.init);
+    }
+  }
+  const resolved = new Map();
+  const resolveNode = (node, visiting = new Set()) => {
+    if (!node) return null;
+    if (node.type === 'StringLiteral') return node.value;
+    if (node.type === 'Identifier') {
+      if (resolved.has(node.name)) return resolved.get(node.name);
+      const init = declarations.get(node.name);
+      if (!init || visiting.has(node.name)) return null;
+      const value = resolveNode(init, new Set(visiting).add(node.name));
+      if (value !== null) resolved.set(node.name, value);
+      return value;
+    }
+    if (node.type === 'TemplateLiteral') {
+      let value = '';
+      for (let i = 0; i < node.quasis.length; i++) {
+        value += node.quasis[i]?.value?.cooked ?? '';
+        if (i < node.expressions.length) {
+          const expression = resolveNode(node.expressions[i], visiting);
+          if (expression === null) return null;
+          value += expression;
+        }
+      }
+      return value;
+    }
+    if (node.type === 'BinaryExpression' && node.operator === '+') {
+      const left = resolveNode(node.left, visiting);
+      const right = resolveNode(node.right, visiting);
+      return left === null || right === null ? null : left + right;
+    }
+    return null;
+  };
+  for (const name of declarations.keys()) resolveNode({ type: 'Identifier', name });
+  return resolved;
+}
+
+function expressRouteBindings(ast) {
+  const bindings = new Set(['app', 'router', 'server', 'fastify', 'hono']);
+  const factories = new Set(['express', 'express.Router', 'Router', 'createRouter', 'Fastify', 'Hono']);
+  walk(ast, node => {
+    if (node.type !== 'ImportDeclaration' || node.source?.value !== 'express') return;
+    for (const spec of node.specifiers || []) {
+      if (spec.type === 'ImportDefaultSpecifier') factories.add(spec.local.name);
+      if (spec.type === 'ImportSpecifier' && (spec.imported?.name || spec.imported?.value) === 'Router') {
+        factories.add(spec.local.name);
+      }
+    }
+  });
+  walk(ast, node => {
+    if (node.type !== 'VariableDeclarator' || node.id?.type !== 'Identifier' || node.init?.type !== 'CallExpression') return;
+    const factory = calleeName(node.init.callee);
+    if (factories.has(factory)) bindings.add(node.id.name);
+  });
+  return bindings;
+}
+
+function looksLikeRouteReceiver(name, bindings) {
+  return bindings.has(name) || /(?:app|server|router|routes)$/i.test(name);
+}
+
+/** Extract a statically knowable string path from a call argument. */
+function pathArgValue(node, constants = new Map(), dynamicPlaceholder = true) {
   if (!node) return null;
   if (node.type === 'StringLiteral') return node.value;
+  if (node.type === 'Identifier') return constants.get(node.name) ?? null;
   if (node.type === 'TemplateLiteral') {
     if (node.expressions.length === 0) return node.quasis[0]?.value?.cooked ?? null;
-    // `/users/${id}` → `/users/:param` so a dynamic segment still looks like a path.
-    return node.quasis
-      .map((q, i) => (q.value.cooked ?? '') + (i < node.expressions.length ? ':param' : ''))
-      .join('');
+    let value = '';
+    for (let i = 0; i < node.quasis.length; i++) {
+      value += node.quasis[i]?.value?.cooked ?? '';
+      if (i < node.expressions.length) {
+        const expression = node.expressions[i];
+        const staticValue = expression.type === 'Identifier' ? constants.get(expression.name) : null;
+        if (staticValue === undefined || staticValue === null) {
+          if (!dynamicPlaceholder) return null;
+          value += ':param';
+        } else {
+          value += staticValue;
+        }
+      }
+    }
+    return value;
+  }
+  if (node.type === 'BinaryExpression' && node.operator === '+') {
+    const left = pathArgValue(node.left, constants, false);
+    const right = pathArgValue(node.right, constants, false);
+    return left === null || right === null ? null : left + right;
   }
   return null;
 }
@@ -216,6 +304,8 @@ export function extractJsRouteCalls(content, filename = 'file.ts') {
   if (!ok || !ast) return null;
 
   const out = [];
+  const constants = topLevelStaticStrings(ast);
+  const routeBindings = expressRouteBindings(ast);
   walk(ast, (node) => {
     if (node.type !== 'CallExpression') return;
     const callee = node.callee;
@@ -224,13 +314,20 @@ export function extractJsRouteCalls(content, filename = 'file.ts') {
     if (!prop || prop.type !== 'Identifier') return;
     const method = prop.name.toLowerCase();
     if (!HTTP_METHOD_NAMES.has(method)) return;
-    const path = pathArgValue(node.arguments && node.arguments[0]);
+    // A route receiver must be a stable binding (`app.get`, `router.post`, …).
+    // Chained HTTP clients such as `request(app).get('/api/items')` also accept
+    // URL-shaped first arguments, but they issue requests rather than register
+    // routes. Treating their CallExpression receiver as a route used to let test
+    // calls contaminate the product API inventory.
+    if (!callee.object || callee.object.type !== 'Identifier') return;
+    if (!looksLikeRouteReceiver(callee.object.name, routeBindings)) return;
+    const path = pathArgValue(node.arguments && node.arguments[0], constants);
     if (!path || !(path.startsWith('/') || path === '*')) return;
     // `receiver` is the object the method was called on (`router` in
     // `router.get(...)`, `app` in `app.get(...)`). Mount-prefix resolution uses
     // it to apply a same-file `app.use('/api', router)` prefix ONLY to that
     // router's routes — never to sibling `app.get(...)` calls in the same file.
-    const receiver = callee.object && callee.object.type === 'Identifier' ? callee.object.name : null;
+    const receiver = callee.object.name;
     out.push({ method: method.toUpperCase(), path, start: node.start ?? 0, receiver });
   });
   return out;
@@ -394,13 +491,24 @@ export function extractJsMountsAndImports(content, filename = 'file.ts') {
   if (!ok || !ast) return null;
 
   const imports = {};
+  const importSymbols = {};
+  const exports = {};
   const mounts = [];
+  const constants = topLevelStaticStrings(ast);
+  const routeBindings = expressRouteBindings(ast);
 
   walk(ast, (node) => {
     // import X from 'spec' | import { X } from 'spec' | import * as X from 'spec'
     if (node.type === 'ImportDeclaration' && node.source && node.source.type === 'StringLiteral') {
       for (const spec of node.specifiers || []) {
-        if (spec.local && spec.local.name) imports[spec.local.name] = node.source.value;
+        if (spec.local && spec.local.name) {
+          imports[spec.local.name] = node.source.value;
+          importSymbols[spec.local.name] = spec.type === 'ImportDefaultSpecifier'
+            ? 'default'
+            : spec.type === 'ImportNamespaceSpecifier'
+              ? '*'
+              : (spec.imported?.name || spec.imported?.value || spec.local.name);
+        }
       }
       return;
     }
@@ -410,23 +518,53 @@ export function extractJsMountsAndImports(content, filename = 'file.ts') {
         && calleeName(node.init.callee) === 'require'
         && node.init.arguments[0] && node.init.arguments[0].type === 'StringLiteral') {
       imports[node.id.name] = node.init.arguments[0].value;
+      importSymbols[node.id.name] = 'default';
+      return;
+    }
+    if (node.type === 'ExportDefaultDeclaration' && node.declaration?.type === 'Identifier') {
+      exports.default = node.declaration.name;
+      return;
+    }
+    if (node.type === 'ExportNamedDeclaration') {
+      if (node.declaration?.type === 'VariableDeclaration') {
+        for (const item of node.declaration.declarations || []) {
+          if (item.id?.type === 'Identifier') {
+            exports[item.id.name] = item.init?.type === 'Identifier' ? item.init.name : item.id.name;
+          }
+        }
+      }
+      for (const spec of node.specifiers || []) {
+        const exported = spec.exported?.name || spec.exported?.value;
+        const local = spec.local?.name || spec.local?.value;
+        if (exported && local) exports[exported] = local;
+      }
       return;
     }
-    // <x>.use('/prefix', …, <routerIdent>) — the prefix is the first string-literal
-    // arg; the mounted router is the LAST identifier arg (skips middleware).
+    // <x>.use('/prefix', middleware, router) and pathless <x>.use(router).
+    // Return every identifier candidate; the filesystem-aware caller keeps
+    // only candidates whose target contains router registrations or mounts.
     if (node.type === 'CallExpression' && node.callee && node.callee.type === 'MemberExpression'
         && !node.callee.computed && node.callee.property && node.callee.property.name === 'use') {
       const args = node.arguments || [];
       const first = args[0];
-      const prefix = first && first.type === 'StringLiteral' ? first.value : null;
-      if (!prefix || !prefix.startsWith('/')) return;
-      let ident = null;
-      for (let i = args.length - 1; i >= 1; i--) {
-        if (args[i] && args[i].type === 'Identifier') { ident = args[i].name; break; }
+      const receiver = node.callee.object?.type === 'Identifier'
+        ? node.callee.object.name
+        : null;
+      if (!receiver || !looksLikeRouteReceiver(receiver, routeBindings)) return;
+      const explicitPrefix = pathArgValue(first, constants, false);
+      const hasPrefix = typeof explicitPrefix === 'string' && explicitPrefix.startsWith('/');
+      if (!hasPrefix && (first?.type !== 'Identifier' || args.length !== 1)) return;
+      const prefix = hasPrefix ? explicitPrefix : '';
+      const start = hasPrefix ? 1 : 0;
+      for (let i = start; i < args.length; i++) {
+        if (args[i]?.type === 'Identifier' && args[i].name !== receiver &&
+            (imports[args[i].name] || looksLikeRouteReceiver(args[i].name, routeBindings))) {
+          mounts.push({ prefix, ident: args[i].name, receiver });
+        }
       }
-      if (ident) mounts.push({ prefix, ident });
     }
   });
 
-  return { imports, mounts };
+  const routeReceivers = new Set(extractJsRouteCalls(content, filename)?.map(route => route.receiver) || []);
+  return { imports, importSymbols, exports, mounts, routeReceivers: [...routeReceivers] };
 }

package/cli/scanners/reconciliation.mjs

@@ -7,7 +7,7 @@
 
 import { execFileSync } from 'node:child_process';
 import { extname } from 'node:path';
-import { getDiffText, getHeadInfo } from '../shared-git.mjs';
+import { getDiffSnapshot, getHeadInfo } from '../shared-git.mjs';
 import { parseUnifiedDiff } from '../shared-diff.mjs';
 import { mechanicalSectionsForChanges } from '../shared-sync-scope.mjs';
 import { projectSpecRegistry } from './spec-registry.mjs';
@@ -64,7 +64,21 @@ function disposition(kind, linked, companionKinds, currentSpecs) {
   return { evidenceClass: 'unrelated', disposition: 'unrelated_change', confidence: 'high' };
 }
 
-export function buildReconciliationPlan(projectDir, config = {}, since) {
+function summarize(classifications) {
+  const count = key => Object.fromEntries([...classifications.reduce((map, item) => {
+    const value = item[key] || 'unknown';
+    map.set(value, (map.get(value) || 0) + 1);
+    return map;
+  }, new Map()).entries()].sort(([a], [b]) => a.localeCompare(b)));
+  return {
+    total: classifications.length,
+    byKind: count('kind'),
+    byDisposition: count('disposition'),
+    byConfidence: count('confidence'),
+  };
+}
+
+export function buildReconciliationPlan(projectDir, config = {}, since, runtime = {}) {
   if (!since) throw new Error('Reconcile requires --since <git-ref>.');
   const baseRevision = resolveRevision(projectDir, since);
   const head = getHeadInfo(projectDir);
@@ -80,14 +94,40 @@ export function buildReconciliationPlan(projectDir, config = {}, since) {
     };
   }
   const projection = projectSpecRegistry(projectDir, config);
-  const diff = parseUnifiedDiff(getDiffText(projectDir, since))
+  const readDiff = runtime.getDiffSnapshot || getDiffSnapshot;
+  // Use the already verified full commit ID for every subsequent Git call.
+  // This removes revision-option ambiguity from user-supplied `--since` text.
+  const snapshot = readDiff(projectDir, baseRevision);
+  if (snapshot.status !== 'ok') {
+    return {
+      schemaVersion: 1,
+      status: 'BLOCKED',
+      since,
+      baseRevision,
+      revision: head.commit,
+      dirty: head.dirty,
+      range: {
+        status: snapshot.status,
+        commitCount: snapshot.commitCount,
+        changedFileCount: snapshot.changedFiles.length,
+        patchBytes: snapshot.patchBytes,
+        limits: snapshot.limits,
+      },
+      coverage: { status: 'partial', reason: snapshot.reason },
+      summary: { total: 0, byKind: {}, byDisposition: {}, byConfidence: {} },
+      nodes: [], edges: [], classifications: [], writes: [], issues: projection.issues,
+    };
+  }
+  const diff = parseUnifiedDiff(snapshot.patch)
     .filter(file => ![file.oldPath, file.newPath].some(path => path?.split('/').includes('.local')));
-  const changed = diff.map(file => file.newPath || file.oldPath).filter(Boolean);
+  const changed = snapshot.changedFiles
+    .map(file => file.newPath || file.oldPath)
+    .filter(path => path && !path.split('/').includes('.local'));
   const textByPath = new Map(diff.map(file => [
     file.newPath || file.oldPath,
     file.hunks.flatMap(hunk => hunk.lines.filter(line => line.op !== ' ').map(line => line.text)).join('\n'),
   ]));
-  const preliminary = changed.map(path => ({
+  const preliminary = [...new Set(changed)].sort().map(path => ({
     path,
     kind: fileKind(path, projection.registry),
     specs: directSpecLinks(path, textByPath.get(path) || '', projection.registry),
@@ -124,6 +164,7 @@ export function buildReconciliationPlan(projectDir, config = {}, since) {
     confidence: 'high',
   })));
   const review = classifications.some(item => !['mechanical_fact_refresh', 'unrelated_change'].includes(item.disposition));
+  const summary = summarize(classifications);
   return {
     schemaVersion: 1,
     status: projection.issues.length ? 'BLOCKED' : review ? 'REVIEW' : 'READY',
@@ -131,11 +172,20 @@ export function buildReconciliationPlan(projectDir, config = {}, since) {
     baseRevision,
     revision: head.commit,
     dirty: head.dirty,
+    range: {
+      status: 'ok',
+      commitCount: snapshot.commitCount,
+      changedFileCount: changed.length,
+      patchBytes: snapshot.patchBytes,
+      limits: snapshot.limits,
+      aggregated: snapshot.commitCount > 50 || changed.length > 100,
+    },
     coverage: { status: 'complete', reason: null },
+    summary,
     nodes,
     edges,
     classifications,
-    writes: mechanicalSections.length ? [{ command: `docguard sync --since ${since} --write`, scope: 'mechanical_fact' }] : [],
+    writes: mechanicalSections.length ? [{ command: `docguard sync --since ${baseRevision} --write`, scope: 'mechanical_fact' }] : [],
     issues: projection.issues,
   };
 }

package/cli/scanners/routes.mjs

@@ -1,5 +1,6 @@
 /**
  * Deep Route Scanner
+ * @req docguard.adoption-workflow-integrity#FR-013
  * Parses actual route definitions from source code across frameworks.
  * Supports: Next.js (App Router + Pages), Express, Fastify, Hono, Django, FastAPI
  * 
@@ -87,13 +88,16 @@ export function scanRoutesDeep(dir, stack, docTools, opts = {}) {
   const seen = new Set();
   return routes.filter(r => {
     const key = `${r.method}:${r.path}`;
-    if (seen.has(key)) return false;
-    seen.add(key);
     if (r.file) {
       const rel = relPosix(dir, resolve(dir, r.file));
       if (isNonProductPath(rel, cfg)) return false;
       if (shouldIgnore(rel, cfg)) return false;
     }
+    // Filter non-product and ignored evidence before deduplication. Otherwise a
+    // test request can reserve the same method/path key as a real route, get
+    // filtered out, and silently remove the product route that appears later.
+    if (seen.has(key)) return false;
+    seen.add(key);
     return true;
   });
 }
@@ -292,10 +296,10 @@ function scanExpressRoutes(dir, roots = null) {
  *   - router is a LOCAL identifier    → the prefix applies only to that file's
  *     routes whose receiver matches (receiver: ident).
  *
- * Known limitations (documented, not silently wrong): transitive composition
- * (`app.use('/api', api)` then `api.use('/x', x)` does NOT yield `/api/x`), and
- * dynamic mount paths (non-string-literal prefixes) are skipped. Unmounted
- * files keep their bare paths — exactly the pre-mount-map behavior.
+ * Imported-router mounts are composed transitively, so
+ * `app.use('/api', api)` plus `api.use('/x', x)` yields `/api/x`. Dynamic mount
+ * paths (non-string-literal prefixes) are skipped. Unmounted files keep their
+ * bare paths — exactly the pre-mount-map behavior.
  */
 function buildExpressMountMap(files) {
   const map = new Map();
@@ -303,19 +307,90 @@ function buildExpressMountMap(files) {
     if (!map.has(absFile)) map.set(absFile, []);
     map.get(absFile).push({ receiver, prefix });
   };
+  const metadata = new Map();
   for (const { content, filePath } of files) {
     const mi = extractJsMountsAndImports(content, filePath);
+    if (mi) metadata.set(filePath, mi);
+  }
+
+  const edges = [];
+  for (const { filePath } of files) {
+    const mi = metadata.get(filePath);
     if (!mi) continue;
-    for (const { prefix, ident } of mi.mounts) {
+    for (const { prefix, ident, receiver } of mi.mounts) {
       const spec = mi.imports[ident];
       if (spec) {
         const target = resolveLocalImport(filePath, spec);
-        if (target) add(target, null, prefix);
+        const targetMeta = target ? metadata.get(target) : null;
+        if (!targetMeta) continue;
+        const importedSymbol = mi.importSymbols?.[ident];
+        const targetReceiver = importedSymbol === 'default'
+          ? (targetMeta.exports?.default ?? null)
+          : importedSymbol && importedSymbol !== '*'
+            ? (targetMeta.exports?.[importedSymbol] ?? importedSymbol)
+            : null;
+        const targetRouteReceivers = new Set(targetMeta.routeReceivers || []);
+        const targetMountReceivers = new Set((targetMeta.mounts || []).map(mount => mount.receiver));
+        if (targetReceiver !== null &&
+            !targetRouteReceivers.has(targetReceiver) &&
+            !targetMountReceivers.has(targetReceiver)) continue;
+        if (targetReceiver === null && targetRouteReceivers.size === 0 && targetMountReceivers.size === 0) continue;
+        edges.push({
+          from: { file: filePath, receiver },
+          to: { file: target, receiver: targetReceiver },
+          prefix,
+        });
       } else {
-        add(filePath, ident, prefix);
+        const routeReceivers = new Set(mi.routeReceivers || []);
+        const mountReceivers = new Set((mi.mounts || []).map(mount => mount.receiver));
+        if (!routeReceivers.has(ident) && !mountReceivers.has(ident)) continue;
+        edges.push({
+          from: { file: filePath, receiver },
+          to: { file: filePath, receiver: ident },
+          prefix,
+        });
       }
     }
   }
+
+  const nodeKey = node => `${node.file}\0${node.receiver ?? '*'}`;
+  const incoming = new Map();
+  const nodes = new Map();
+  for (const edge of edges) {
+    const key = nodeKey(edge.to);
+    nodes.set(key, edge.to);
+    if (!incoming.has(key)) incoming.set(key, []);
+    incoming.get(key).push(edge);
+  }
+  const memo = new Map();
+  const effectivePrefixes = (node, visiting = new Set(), depth = 0) => {
+    const key = nodeKey(node);
+    if (memo.has(key)) return memo.get(key);
+    if (visiting.has(key) || depth > 32) return [];
+    const nodeEdges = incoming.get(key) || [];
+    if (nodeEdges.length === 0) return [];
+    const nextVisiting = new Set(visiting).add(key);
+    const prefixes = new Set();
+    for (const edge of nodeEdges) {
+      const parentKey = nodeKey(edge.from);
+      const parentHasIncoming = (incoming.get(parentKey) || []).length > 0;
+      const parentPrefixes = parentHasIncoming
+        ? effectivePrefixes(edge.from, nextVisiting, depth + 1)
+        : [''];
+      for (const parentPrefix of parentPrefixes) {
+        prefixes.add(joinRoutePath(parentPrefix, edge.prefix));
+        if (prefixes.size >= 256) break;
+      }
+      if (prefixes.size >= 256) break;
+    }
+    const resolved = [...prefixes];
+    memo.set(key, resolved);
+    return resolved;
+  };
+
+  for (const node of nodes.values()) {
+    for (const prefix of effectivePrefixes(node)) add(node.file, node.receiver, prefix);
+  }
   return map;
 }
 

package/cli/scanners/spec-registry.mjs

@@ -214,6 +214,35 @@ export function readSpecRegistry(projectDir) {
   return loaded;
 }
 
+function trackedAndClean(projectDir, path) {
+  const tracked = spawnSync('git', ['ls-files', '--error-unmatch', '--', path], {
+    cwd: projectDir, stdio: 'ignore',
+  });
+  if (tracked.status !== 0) return false;
+  const working = spawnSync('git', ['diff', '--quiet', '--', path], { cwd: projectDir, stdio: 'ignore' });
+  const staged = spawnSync('git', ['diff', '--cached', '--quiet', '--', path], { cwd: projectDir, stdio: 'ignore' });
+  return working.status === 0 && staged.status === 0;
+}
+
+/** Reviewed lifecycle that may defer implementation-time traceability. */
+export function trustedSpecLifecycleIndex(projectDir) {
+  const trusted = new Map();
+  const loaded = readSpecRegistry(projectDir);
+  if (loaded.error || loaded.value?.schemaVersion !== SPEC_REGISTRY_SCHEMA_VERSION) return trusted;
+  if (!trackedAndClean(projectDir, SPEC_REGISTRY_PATH)) return trusted;
+  for (const entry of loaded.value.specs) {
+    if (!entry?.specId || !entry?.path || !trackedAndClean(projectDir, entry.path)) continue;
+    let content;
+    try { content = readFileSync(resolve(projectDir, entry.path), 'utf8'); } catch { continue; }
+    if (parseSpecId(content) !== entry.specId) continue;
+    const artifact = entry.observed?.artifacts?.find(item => item.path === entry.path);
+    if (!artifact || artifact.digest !== digest(content)) continue;
+    if (entry.reviewed?.lifecycle?.context !== 'current' || entry.reviewed.lifecycle.storage !== 'working_tree') continue;
+    trusted.set(`${entry.specId}\0${entry.path}`, entry.reviewed.lifecycle);
+  }
+  return trusted;
+}
+
 function taskCompletion(path) {
   if (!path || !existsSync(path)) return { checked: 0, total: 0 };
   const content = readFileSync(path, 'utf8');

package/cli/shared-git.mjs

@@ -8,6 +8,7 @@
  * "X commits since last doc update" counter — silently hiding drift.
  *
  * Zero NPM dependencies. Pure Node.js built-ins.
+ * @implements docguard.adoption-workflow-integrity#FR-004
  */
 
 import { execFileSync, execSync } from 'node:child_process';
@@ -172,6 +173,103 @@ export function getDiffText(dir, ref = 'HEAD~1', pathspec = null) {
   }
 }
 
+const DEFAULT_DIFF_LIMITS = Object.freeze({
+  maxPatchBytes: 5 * 1024 * 1024,
+  maxInventoryBytes: 5 * 1024 * 1024,
+  maxChangedFiles: 5_000,
+  timeoutMs: 30_000,
+});
+
+function diffFailure(error) {
+  if (error?.code === 'ENOBUFS' || /maxBuffer/i.test(error?.message || '')) return 'too-large';
+  if (error?.code === 'ETIMEDOUT' || error?.signal === 'SIGTERM') return 'timeout';
+  return 'error';
+}
+
+function parseNameStatus(raw) {
+  const tokens = raw.toString('utf8').split('\0');
+  if (tokens.at(-1) === '') tokens.pop();
+  const files = [];
+  for (let i = 0; i < tokens.length;) {
+    const status = tokens[i++];
+    if (!status) continue;
+    if (/^[RC]/.test(status)) {
+      const oldPath = tokens[i++];
+      const newPath = tokens[i++];
+      if (oldPath && newPath) files.push({ status, oldPath, newPath });
+    } else {
+      const path = tokens[i++];
+      if (path) files.push({ status, oldPath: status.startsWith('D') ? path : null, newPath: status.startsWith('D') ? null : path });
+    }
+  }
+  return files;
+}
+
+/**
+ * Read a reconciliation diff without converting overflow, timeout, or Git
+ * failure into an empty successful range. The path inventory is independent
+ * from patch text so binary files, deletes, and renames remain visible.
+ */
+export function getDiffSnapshot(dir, ref = 'HEAD~1', options = {}) {
+  const limits = { ...DEFAULT_DIFF_LIMITS, ...options };
+  const base = {
+    status: 'error', ref, commitCount: null, changedFiles: [], patch: '',
+    patchBytes: 0, limits, reason: null,
+  };
+  let inventory;
+  try {
+    inventory = execFileSync('git', [
+      'diff', '--name-status', '-z', '--no-color', '--no-ext-diff', '--no-textconv', ref, 'HEAD',
+    ], {
+      cwd: dir, encoding: 'buffer', stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: limits.maxInventoryBytes, timeout: limits.timeoutMs,
+    });
+  } catch (error) {
+    const status = diffFailure(error);
+    return { ...base, status, reason: status === 'too-large'
+      ? 'Changed-file inventory exceeded its byte budget.'
+      : status === 'timeout' ? 'Changed-file inventory timed out.' : 'Changed-file inventory could not be read.' };
+  }
+  const changedFiles = parseNameStatus(inventory);
+  if (changedFiles.length > limits.maxChangedFiles) {
+    return { ...base, status: 'too-large', changedFiles: changedFiles.slice(0, limits.maxChangedFiles),
+      reason: `Changed-file inventory exceeded the ${limits.maxChangedFiles}-path budget.` };
+  }
+  let commitCount;
+  try {
+    commitCount = Number(execFileSync('git', ['rev-list', '--count', `${ref}..HEAD`], {
+      cwd: dir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: limits.timeoutMs,
+    }).trim());
+    if (!Number.isSafeInteger(commitCount) || commitCount < 0) throw new Error('invalid commit count');
+  } catch (error) {
+    const status = diffFailure(error);
+    return { ...base, status, changedFiles, reason: status === 'timeout'
+      ? 'Commit-range inspection timed out.' : 'Commit range could not be inspected.' };
+  }
+  let patch;
+  try {
+    patch = execFileSync('git', [
+      'diff', '--no-color', '--no-ext-diff', '--no-textconv', ref, 'HEAD',
+    ], {
+      cwd: dir, encoding: 'buffer', stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: limits.maxPatchBytes, timeout: limits.timeoutMs,
+    });
+  } catch (error) {
+    const status = diffFailure(error);
+    return { ...base, status, commitCount, changedFiles, reason: status === 'too-large'
+      ? 'Patch exceeded its byte budget; use a newer --since revision.'
+      : status === 'timeout' ? 'Patch generation timed out; use a newer --since revision.' : 'Patch could not be read.' };
+  }
+  return {
+    ...base,
+    status: 'ok',
+    commitCount,
+    changedFiles,
+    patch: patch.toString('utf8'),
+    patchBytes: patch.length,
+  };
+}
+
 /**
  * Read a file's contents AS OF a given revision (e.g. the commit where a doc
  * was last touched), following the `<rev>:<path>` git addressing. Returns null

package/cli/shared-ignore.mjs

@@ -61,7 +61,7 @@ const ALWAYS_REJECT_PATH_RE =
  */
 export const DEFAULT_DETECTION_IGNORE_DIRS = new Set([
   'fixtures', '__fixtures__', 'test-fixtures', 'testfixtures', 'testdata',
-  'test', 'tests', '__tests__', 'spec', 'specs', '__mocks__', 'mocks',
+  'test', 'tests', '__tests__', 'test-helpers', 'spec', 'specs', '__mocks__', 'mocks',
   'examples', 'example', 'sample', 'samples',
 ]);