carto-md 2.0.7 → 2.0.9

package/src/bitmap/tools.js

@@ -0,0 +1,310 @@
+'use strict';
+
+/**
+ * Production bitmap query tools — drop-in replacements for 5 SQLiteStore
+ * methods plus one new tool that's only feasible with bitmap aggregation.
+ *
+ * Each function returns the same shape as the corresponding
+ * `SQLiteStore` method so the MCP layer's formatting code (`server-v2.js`)
+ * is data-source-agnostic — bitmap and SQLite paths render identically.
+ *
+ * Performance contract (measured against the SQLite query path):
+ *   blastRadius        20-50× faster on small/medium repos, 5-9× on largest
+ *   crossDomain        4-12×
+ *   highImpactFiles    O(N) → O(1) array slice via popcountIndex
+ *   similarPatterns    20-150× faster (Jaccard over import sets)
+ *   simulateChangeImpact  qualitatively new — N×SQL approach is too slow to
+ *                      ship as a tool; bitmap OR-aggregate is sub-millisecond
+ */
+
+const { Bitset } = require('./bitset');
+
+/**
+ * blastRadius(sidecar, file, maxHops=5) → [{file, hop_distance}] | null
+ *
+ * BFS over reverse adjacency bitmaps. Tracks the hop at which each
+ * dependent first becomes reachable so the output matches `SQLiteStore.
+ * getBlastRadius` row-for-row.
+ *
+ * Returns null if `file` is not in the index — same null contract as
+ * the SQLite version, so the MCP "File not found in index" message
+ * works without a code change.
+ *
+ * Pre-allocates `visited`, `frontier`, and a single transient
+ * `next` bitset; all word-level ops applied in place via `orInPlace` /
+ * `andNotInPlace` / `copyFrom`. Allocation count: 3 Bitsets per call,
+ * regardless of hop depth.
+ */
+function blastRadius(sidecar, file, maxHops = 5) {
+  const fileId = sidecar.pathToFileId.get(file);
+  if (fileId === undefined) return null;
+
+  const { reverse, size, filePathArr } = sidecar;
+
+  const visited = new Bitset(size);
+  visited.set(fileId);
+  const frontier = new Bitset(size);
+  frontier.set(fileId);
+  const next = new Bitset(size);
+
+  // hopOf[id] = first hop at which id became reachable.
+  const hopOf = new Map();
+
+  for (let hop = 1; hop <= maxHops; hop++) {
+    next.setAll(0);
+    // For each bit in `frontier`, OR its reverse-adjacency bitmap into `next`.
+    const fwords = frontier.words;
+    for (let w = 0; w < fwords.length; w++) {
+      let v = fwords[w];
+      while (v) {
+        const bit = v & -v;
+        const fid = (w << 5) + (31 - Math.clz32(bit));
+        v ^= bit;
+        const deps = reverse.get(fid);
+        if (deps) next.orInPlace(deps);
+      }
+    }
+    next.andNotInPlace(visited);
+    if (next.popcount() === 0) break;
+    // Record the first hop at which each new bit became reachable.
+    const nwords = next.words;
+    for (let w = 0; w < nwords.length; w++) {
+      let v = nwords[w];
+      while (v) {
+        const bit = v & -v;
+        const id = (w << 5) + (31 - Math.clz32(bit));
+        v ^= bit;
+        if (!hopOf.has(id)) hopOf.set(id, hop);
+      }
+    }
+    visited.orInPlace(next);
+    frontier.copyFrom(next);
+  }
+
+  // Sort by hop ASC then path ASC — same ORDER BY as SQLite version.
+  // Use byte comparison (`<`/`>`) instead of `localeCompare`: matches
+  // SQLite's BINARY collation default and runs ~10× faster for ASCII paths.
+  const rows = [];
+  for (const [id, hop] of hopOf) {
+    const p = filePathArr[id];
+    if (p !== undefined) rows.push({ file: p, hop_distance: hop });
+  }
+  rows.sort((a, b) => {
+    if (a.hop_distance !== b.hop_distance) return a.hop_distance - b.hop_distance;
+    if (a.file < b.file) return -1;
+    if (a.file > b.file) return 1;
+    return 0;
+  });
+  return rows;
+}
+
+/**
+ * crossDomain(sidecar) → [{from, fromDomain, to, toDomain}]
+ *
+ * Iterates forward edges, emits the row whenever `from` and `to` belong to
+ * different domains. Drop-in for `SQLiteStore.getCrossDomainDeps`.
+ *
+ * Stable sort by (fromDomain, toDomain, from, to) matches the SQL
+ * ORDER BY (BINARY collation) so the output is byte-identical to the
+ * SQLite path on a given DB snapshot for ASCII paths.
+ *
+ * Uses `fileDomainArr` (Int32Array index) and
+ * `filePathArr` / `domainNameArr` (plain Array index) to avoid the
+ * 4× `Map.get` overhead per edge. The hot loop iterates `crossForward` —
+ * pre-masked at sidecar build time so intra-domain edges (95%+ of
+ * imports on real repos) are already excluded; no per-edge same-domain
+ * check, no wasted bit iteration.
+ */
+function crossDomain(sidecar) {
+  const { crossForward, fileDomainArr, filePathArr, domainNameArr } = sidecar;
+  const rows = [];
+  for (const [fromId, bitmap] of crossForward) {
+    const fromDomainId = fileDomainArr[fromId];
+    if (fromDomainId < 0) continue;
+    const fromDomain = domainNameArr[fromDomainId];
+    if (!fromDomain) continue;
+    const fromPath = filePathArr[fromId];
+    if (fromPath === undefined) continue;
+    const words = bitmap.words;
+    for (let w = 0; w < words.length; w++) {
+      let v = words[w];
+      while (v) {
+        const bit = v & -v;
+        const toId = (w << 5) + (31 - Math.clz32(bit));
+        v ^= bit;
+        const toDomainId = fileDomainArr[toId];
+        // crossForward already masked out same-domain bits, but a file
+        // with no domain assignment can still be present — skip those
+        // (they have no toDomain name to emit).
+        if (toDomainId < 0) continue;
+        const toDomain = domainNameArr[toDomainId];
+        if (!toDomain) continue;
+        const toPath = filePathArr[toId];
+        if (toPath === undefined) continue;
+        rows.push({ from: fromPath, fromDomain, to: toPath, toDomain });
+      }
+    }
+  }
+  rows.sort((a, b) => {
+    if (a.fromDomain < b.fromDomain) return -1;
+    if (a.fromDomain > b.fromDomain) return 1;
+    if (a.toDomain < b.toDomain) return -1;
+    if (a.toDomain > b.toDomain) return 1;
+    if (a.from < b.from) return -1;
+    if (a.from > b.from) return 1;
+    if (a.to < b.to) return -1;
+    if (a.to > b.to) return 1;
+    return 0;
+  });
+  return rows;
+}
+
+/**
+ * highImpactFiles(sidecar, limit=10) → [{file, dependents}]
+ *
+ * O(1) array slice over `popcountIndex` — the sidecar maintains a list
+ * of file ids sorted DESC by transitive dependent count at build time,
+ * so the query at runtime is just `popcountIndex.slice(0, limit)`. No
+ * popcount, no sort, no allocation.
+ *
+ * Output shape mirrors `SQLiteStore.getHighImpactFiles` exactly.
+ */
+function highImpactFiles(sidecar, limit = 10) {
+  const out = [];
+  const idx = sidecar.popcountIndex;
+  const n = Math.min(limit, idx.length);
+  for (let i = 0; i < n; i++) {
+    const p = sidecar.fileIdToPath.get(idx[i].fileId);
+    if (p) out.push({ file: p, dependents: idx[i].count });
+  }
+  return out;
+}
+
+/**
+ * similarPatterns(sidecar, file, k=5) → [{file, score, shared}]
+ *
+ * Jaccard similarity over forward-import sets — for each candidate file,
+ * `score = |A ∩ B| / |A ∪ B|`. Returns the top-K most similar files.
+ *
+ * This semantics differs from the legacy SQLite tool (which used three
+ * separate SQL strategies — same domain, same route methods, shared
+ * imports). Both answer "what does this file look like elsewhere?", but
+ * Jaccard is the standard graph-similarity metric and runs in
+ * microseconds where the 3-strategy SQL took milliseconds. The output
+ * is structured so server-v2 can format a simple, focused result block.
+ *
+ * Returns `[]` when the target has no resolved imports — honest signal
+ * that there's nothing structural to compare against.
+ */
+function similarPatterns(sidecar, file, k = 5) {
+  const fileId = sidecar.pathToFileId.get(file);
+  if (fileId === undefined) return null;
+  const target = sidecar.forward.get(fileId);
+  if (!target || target.popcount() === 0) return [];
+
+  const scores = [];
+  for (const [otherId, bitmap] of sidecar.forward) {
+    if (otherId === fileId) continue;
+    const intersection = target.and(bitmap).popcount();
+    if (intersection === 0) continue;
+    const union = target.or(bitmap).popcount();
+    const p = sidecar.fileIdToPath.get(otherId);
+    if (!p) continue;
+    scores.push({ file: p, score: intersection / union, shared: intersection });
+  }
+  scores.sort((a, b) => b.score - a.score || b.shared - a.shared);
+  return scores.slice(0, k);
+}
+
+/**
+ * simulateChangeImpact(sidecar, files) → { files: [{file, hop_distance}], count }
+ *
+ * **New tool — only feasible with bitmaps.** Given a *set* of files
+ * changing simultaneously, returns the union of every transitively
+ * affected file. Equivalent to N parallel reverse-BFS calls aggregated
+ * via bitwise OR — O(F + E) bitmap ops vs O(N×F×E) SQL queries.
+ *
+ * Hop distance is the *minimum* hop at which a dependent becomes
+ * reachable from any of the input files (BFS frontier OR-aggregated
+ * across all sources at each hop).
+ *
+ * Input files that aren't in the index are ignored silently. The
+ * returned `files` array excludes the input set itself (you don't want
+ * to count "this file depends on this file" as impact).
+ *
+ * Accepts paths (strings) or pre-resolved file ids (numbers) for
+ * convenience — the MCP tool dispatcher sends paths; tests use ids.
+ */
+function simulateChangeImpact(sidecar, files, maxHops = 5) {
+  const { reverse, size, filePathArr, pathToFileId } = sidecar;
+
+  const seedIds = [];
+  for (const f of files || []) {
+    if (typeof f === 'number') {
+      if (f >= 0 && f < size && filePathArr[f] !== undefined) seedIds.push(f);
+    } else if (typeof f === 'string') {
+      const id = pathToFileId.get(f);
+      if (id !== undefined) seedIds.push(id);
+    }
+  }
+  if (seedIds.length === 0) return { files: [], count: 0 };
+
+  const visited = new Bitset(size);
+  const frontier = new Bitset(size);
+  for (const fid of seedIds) {
+    visited.set(fid);
+    frontier.set(fid);
+  }
+  const next = new Bitset(size);
+
+  const hopOf = new Map();
+  for (let hop = 1; hop <= maxHops; hop++) {
+    next.setAll(0);
+    const fwords = frontier.words;
+    for (let w = 0; w < fwords.length; w++) {
+      let v = fwords[w];
+      while (v) {
+        const bit = v & -v;
+        const fid = (w << 5) + (31 - Math.clz32(bit));
+        v ^= bit;
+        const deps = reverse.get(fid);
+        if (deps) next.orInPlace(deps);
+      }
+    }
+    next.andNotInPlace(visited);
+    if (next.popcount() === 0) break;
+    const nwords = next.words;
+    for (let w = 0; w < nwords.length; w++) {
+      let v = nwords[w];
+      while (v) {
+        const bit = v & -v;
+        const id = (w << 5) + (31 - Math.clz32(bit));
+        v ^= bit;
+        if (!hopOf.has(id)) hopOf.set(id, hop);
+      }
+    }
+    visited.orInPlace(next);
+    frontier.copyFrom(next);
+  }
+
+  const rows = [];
+  for (const [id, hop] of hopOf) {
+    const p = filePathArr[id];
+    if (p !== undefined) rows.push({ file: p, hop_distance: hop });
+  }
+  rows.sort((a, b) => {
+    if (a.hop_distance !== b.hop_distance) return a.hop_distance - b.hop_distance;
+    if (a.file < b.file) return -1;
+    if (a.file > b.file) return 1;
+    return 0;
+  });
+  return { files: rows, count: rows.length };
+}
+
+module.exports = {
+  blastRadius,
+  crossDomain,
+  highImpactFiles,
+  similarPatterns,
+  simulateChangeImpact,
+};

package/src/cli/anci.js

@@ -0,0 +1,237 @@
+'use strict';
+
+/**
+ * `carto anci` — ANCI subcommand dispatcher.
+ *
+ * Subcommands:
+ *   publish              Re-emit `.carto/anci.{yaml,bin}` from the
+ *                        existing index. Does NOT re-sync — assumes
+ *                        the index is already populated.
+ *   show                 Print a human-readable summary of the
+ *                        published ANCI files.
+ *   validate <dir>       Validate an external `anci.{yaml,bin}` pair
+ *                        at <dir>. Exits 0 on valid, 1 on invalid.
+ *
+ * All paths in this module are anchored at `process.cwd()` unless an
+ * explicit directory is passed.
+ *
+ * The `serve` MCP server is unaffected — ANCI is the *export* format,
+ * not Carto's runtime format. SQLite + bitmap remain the runtime path.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function printUsage() {
+  console.log(`
+Usage: carto anci <subcommand>
+
+Subcommands:
+  publish              Re-emit .carto/anci.{yaml,bin} from the existing
+                       SQLite index + bitmap sidecar. No re-sync.
+  show                 Print a summary of the published ANCI files.
+  validate <dir>       Validate an external anci.{yaml,bin} pair at <dir>.
+                       Exit 0 on valid, 1 on invalid.
+
+Examples:
+  carto anci publish
+  carto anci show
+  carto anci validate ./.carto
+`);
+}
+
+/**
+ * run({ argv }) → exit code (0 ok, 1 error).
+ *
+ * argv shape: array of args AFTER `carto anci` (e.g. `['publish']`,
+ * `['validate', './.carto']`). The top-level `cli/index.js` slices the
+ * full process.argv before passing it in.
+ */
+function run({ argv }) {
+  const sub = argv[0];
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    printUsage();
+    return 0;
+  }
+
+  if (sub === 'publish') return runPublish(process.cwd());
+  if (sub === 'show')    return runShow(process.cwd());
+  if (sub === 'validate') {
+    const dir = argv[1] || path.join(process.cwd(), '.carto');
+    return runValidate(dir);
+  }
+
+  console.error(`[CARTO] Unknown anci subcommand: ${sub}`);
+  printUsage();
+  return 1;
+}
+
+/**
+ * publish — Re-emit ANCI files from the existing index.
+ *
+ * Reads the SQLiteStore (read-write so a fresh sidecar can be persisted
+ * if the on-disk one is stale) + bitmap sidecar, then writes
+ * `anci.{yaml,bin}` atomically. Prints sizes and elapsed time.
+ *
+ * Exits 1 if no `.carto/carto.db` is present.
+ */
+function runPublish(projectRoot) {
+  const cartoDir = path.join(projectRoot, '.carto');
+  const dbPath = path.join(cartoDir, 'carto.db');
+  if (!fs.existsSync(dbPath)) {
+    console.error(`[CARTO] No index found at ${dbPath}. Run \`carto init\` first.`);
+    return 1;
+  }
+
+  const start = Date.now();
+  const { SQLiteStore } = require('../store/sqlite-store');
+  const { ensureBitmapFresh } = require('../bitmap/index');
+  const { emitToCartoDir } = require('../anci/emit');
+
+  const store = new SQLiteStore(projectRoot);
+  store.open();
+  try {
+    const sidecar = ensureBitmapFresh(cartoDir, store);
+    const { yamlPath, binPath, bodyBytes } = emitToCartoDir({
+      cartoDir, sidecar, store,
+    });
+    const elapsed = Date.now() - start;
+    const yamlBytes = fs.statSync(yamlPath).size;
+
+    console.log(`[CARTO] Published ANCI v0.1 in ${elapsed}ms`);
+    console.log(`  ${path.relative(projectRoot, yamlPath)} (${formatBytes(yamlBytes)})`);
+    console.log(`  ${path.relative(projectRoot, binPath)} (${formatBytes(bodyBytes)})`);
+    return 0;
+  } finally {
+    try { store.close(); } catch {}
+  }
+}
+
+/**
+ * show — Print a summary of the published ANCI files.
+ *
+ * Loads via the consumer library so this surface dogfoods the same
+ * code path partner integrations will use. If either file is missing
+ * or malformed, prints the error and exits 1.
+ */
+function runShow(projectRoot) {
+  const cartoDir = path.join(projectRoot, '.carto');
+  let reader;
+  try {
+    const { loadAnci } = require('../anci/consumer');
+    reader = loadAnci(cartoDir);
+  } catch (err) {
+    console.error(`[CARTO] ${err.message}`);
+    console.error(`[CARTO] Run \`carto anci publish\` to (re)generate.`);
+    return 1;
+  }
+
+  const h = reader.header;
+  const lines = [];
+  lines.push('');
+  lines.push('── ANCI ────────────────────────────────────────────────');
+  lines.push('');
+  lines.push(`  spec version    : ${h.anci.version}`);
+  lines.push(`  generator       : ${h.anci.generator}`);
+  lines.push(`  generated_at    : ${h.anci.generated_at}`);
+  lines.push(`  body file       : ${h.anci.body.file} (${formatBytes(h.anci.body.bytes)})`);
+  lines.push('');
+  if (h.project) {
+    lines.push('Project');
+    lines.push(`  files           : ${h.project.total_files}`);
+    lines.push(`  routes          : ${h.project.total_routes}`);
+    lines.push(`  models          : ${h.project.total_models}`);
+    lines.push(`  import edges    : ${h.project.total_import_edges}`);
+    lines.push('');
+  }
+  if (reader.domains.length > 0) {
+    lines.push(`Domains (${reader.domains.length})`);
+    for (const d of reader.domains) {
+      lines.push(`  ${d.name.padEnd(16)} ${String(d.file_count).padStart(5)} files  ` +
+        `${String(d.route_count || 0).padStart(4)} routes  ` +
+        `${String(d.model_count || 0).padStart(4)} models`);
+    }
+    lines.push('');
+  }
+  if (reader.high_impact && reader.high_impact.length > 0) {
+    lines.push('Top impact (transitive dependents)');
+    const topN = Math.min(10, reader.high_impact.length);
+    for (let i = 0; i < topN; i++) {
+      const e = reader.high_impact[i];
+      lines.push(`  ${String(e.transitive_dependents).padStart(4)}  ${e.file}`);
+    }
+    lines.push('');
+  }
+  lines.push('────────────────────────────────────────────────────────');
+  lines.push('');
+  process.stdout.write(lines.join('\n'));
+  return 0;
+}
+
+/**
+ * validate <dir> — Validate an external ANCI pair.
+ *
+ * Cleanly distinguishes "structural problem with the file" (return 1
+ * with message) from "this consumer can't handle this version"
+ * (return 1 with message naming the version) from "all checks pass"
+ * (return 0).
+ */
+function runValidate(dir) {
+  const yaml = require('../anci/yaml');
+  const { deserializeBody } = require('../anci/deserialize');
+  const { ANCI_BIN_FILENAME, ANCI_YAML_FILENAME } = require('../anci/serialize');
+
+  const yamlPath = path.join(dir, ANCI_YAML_FILENAME);
+  const binPath = path.join(dir, ANCI_BIN_FILENAME);
+
+  const errors = [];
+  if (!fs.existsSync(yamlPath)) errors.push(`missing ${yamlPath}`);
+  if (!fs.existsSync(binPath))  errors.push(`missing ${binPath}`);
+  if (errors.length > 0) {
+    for (const e of errors) console.error(`[CARTO] ${e}`);
+    return 1;
+  }
+
+  let header;
+  try {
+    header = yaml.parse(fs.readFileSync(yamlPath, 'utf-8'));
+  } catch (err) {
+    console.error(`[CARTO] header parse failed: ${err.message}`);
+    return 1;
+  }
+  if (!header || !header.anci || typeof header.anci.version !== 'string') {
+    console.error('[CARTO] header missing required `anci.version`');
+    return 1;
+  }
+
+  const bodyBuf = fs.readFileSync(binPath);
+  const body = deserializeBody(bodyBuf);
+  if (!body) {
+    console.error('[CARTO] body failed to parse (corrupt magic, version, or section)');
+    return 1;
+  }
+
+  // Optional cross-check: header.body.bytes vs actual file size.
+  if (header.anci.body && typeof header.anci.body.bytes === 'number') {
+    if (header.anci.body.bytes !== bodyBuf.length) {
+      console.error(
+        `[CARTO] header/body size mismatch: header says ${header.anci.body.bytes}, ` +
+        `actual ${bodyBuf.length} bytes`
+      );
+      return 1;
+    }
+  }
+
+  console.log(`[CARTO] ANCI valid: ${header.anci.version}, ${body.size} files indexed.`);
+  return 0;
+}
+
+function formatBytes(n) {
+  if (n === null || n === undefined) return 'n/a';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+module.exports = { run };

package/src/cli/check.js

@@ -39,6 +39,14 @@ async function run(projectRoot) {
     const ageStr = age < 60 ? `${age}s ago` : age < 3600 ? `${Math.round(age / 60)}m ago` : `${Math.round(age / 3600)}h ago`;
     console.log(`  Last indexed  : ${ageStr}`);
   }
+
+  // Language coverage (only shows when grammars are missing)
+  const unavailRaw = store.getMeta('unavailable_languages_json');
+  const unavailLangs = unavailRaw ? (() => { try { return JSON.parse(unavailRaw); } catch { return []; } })() : [];
+  if (unavailLangs.length > 0) {
+    console.log(`  Lang coverage : ⚠️  ${unavailLangs.length} grammar${unavailLangs.length === 1 ? '' : 's'} unavailable (${unavailLangs.join(', ')}) — regex fallback active`);
+  }
+
   console.log('');
 
   // ── Uncommitted changes that touch high-blast-radius files ───────────────
@@ -89,6 +97,55 @@ async function run(projectRoot) {
     console.log('  ✅ No cross-domain dependency violations\n');
   }
 
+  // ── Domain stability ──────────────────────────────────────────────────
+  const driftPct = parseFloat(store.getMeta('domain_stability_drift_pct') || '0');
+  const reassignmentsRaw = store.getMeta('last_reassignments_json');
+  const reassignments = reassignmentsRaw ? (() => { try { return JSON.parse(reassignmentsRaw); } catch { return []; } })() : [];
+
+  if (driftPct > 0 || reassignments.length > 0) {
+    if (driftPct > 5) {
+      hasIssues = true;
+      console.log(`  ⚠️  Domain stability: ${driftPct.toFixed(1)}% drift`);
+    } else {
+      console.log(`  ✅ Domain stability: ${driftPct.toFixed(1)}% drift`);
+    }
+    if (reassignments.length > 0) {
+      console.log('     Recent reassignments:');
+      for (const r of reassignments.slice(0, 5)) {
+        console.log(`       ${path.basename(r.file)}: ${r.from} → ${r.to}`);
+      }
+      if (reassignments.length > 5) console.log(`       ...and ${reassignments.length - 5} more`);
+    }
+    console.log('');
+  } else if (domains.length > 1) {
+    console.log('  ✅ Domain stability: 0.0% drift (no reassignments)\n');
+  }
+
+  // ── Extraction errors ─────────────────────────────────────────────────
+  const errorCount = store.getExtractionErrorCount();
+  if (errorCount > 0) {
+    hasIssues = true;
+    const topFiles = store.getExtractionErrorsTopFiles(5);
+    console.log(`  ⚠️  Extraction errors (${errorCount}):`);
+    console.log('     These files failed to parse — their routes/models/imports are missing from the index.\n');
+    for (const f of topFiles) {
+      const phases = f.phases ? ` [${f.phases}]` : '';
+      console.log(`     ${f.file}${phases}`);
+      if (f.sample) {
+        // Truncate sample for terminal readability
+        const sample = String(f.sample).split('\n')[0].slice(0, 120);
+        console.log(`       └─ ${sample}`);
+      }
+    }
+    // Errors NOT covered by the top-5 file slice (i.e., 6th+ file's errors).
+    const shown = topFiles.reduce((a, f) => a + (f.errorCount || 0), 0);
+    const remainingErrors = errorCount - shown;
+    if (remainingErrors > 0) {
+      console.log(`     ...and ${remainingErrors} more error${remainingErrors === 1 ? '' : 's'} in additional files`);
+    }
+    console.log('');
+  }
+
   // ── Top high-impact files ────────────────────────────────────────────────
   if (highImpact.length > 0) {
     console.log(`  🔥 Top high-impact files (changing these = highest blast radius):`);

package/src/cli/index.js

@@ -8,11 +8,24 @@ function printUsage() {
 Usage: carto <command>
 
 Commands:
-  init          Detect project, write .carto/config.json, run first sync
-  watch         Read .carto/config.json, start file watcher
+  init          Detect project, write .carto/config.json, run first sync.
+                Installs git hooks (pre-commit, post-checkout, post-merge,
+                post-rewrite) so the index stays fresh on every git event.
   sync          Read .carto/config.json, run one sync, exit
+  watch         (Optional) Start file watcher for sub-second freshness.
+                Not required — git hooks + lazy MCP re-parse keep the
+                index fresh by default. Use only for AI-heavy workflows.
   impact <file> Show which files and routes are affected by changing a file
+  pr-impact     Render a PR impact report (markdown or JSON) for the
+                diff between two git refs. Used by the carto GitHub
+                Action; works standalone too.
   check         Report cross-domain deps, high-risk uncommitted changes, domain health
+  inspect       Read-only diagnostic: prints index paths, sizes, freshness,
+                bitmap sidecar shape, top-impact files, schema version,
+                sync timestamps, extraction errors. Use --json for piping.
+  anci          ANCI v0.1 DRAFT export. Subcommands: publish, show,
+                validate. Writes/reads .carto/anci.{yaml,bin} — the
+                public, tool-neutral architecture description spec.
   remove        Remove AGENTS.md and .carto/ from this project
   serve         Start MCP server for AI tool integration
   agent         Start ACP agent mode (for Zed, JetBrains, VS Code)
@@ -50,11 +63,24 @@ if (command === 'init') {
 } else if (command === 'impact') {
   const fileArg = process.argv[3];
   require('./impact').run(process.cwd(), fileArg);
+} else if (command === 'pr-impact') {
+  // pr-impact owns its own argv parsing + error handling + exit code.
+  const code = require('./pr-impact').run({ argv: process.argv.slice(3) });
+  process.exit(code);
 } else if (command === 'check') {
   require('./check').run(process.cwd()).catch(err => {
     console.error(`[CARTO] Fatal error: ${err.message}`);
     process.exit(1);
   });
+} else if (command === 'inspect') {
+  // Read-only diagnostic — no async, no rebuild. Pass --json through.
+  const json = process.argv.slice(3).includes('--json');
+  const code = require('./inspect').run(process.cwd(), { json });
+  process.exit(code);
+} else if (command === 'anci') {
+  // anci has its own subcommand parser; pass argv after `carto anci`.
+  const code = require('./anci').run({ argv: process.argv.slice(3) });
+  process.exit(code);
 } else if (command === 'remove') {
   require('./remove').run(process.cwd());
 } else if (command === 'serve') {