@davesheffer/hunch 1.8.2 → 1.9.2

package/dist/extractors/indexer.js

@@ -4,22 +4,51 @@
  * resolve a best-effort call graph + import dependency graph, derive components
  * from the directory layout, and compute churn / fan-in / fan-out metrics.
  *
- * Writes Symbol/Edge/Component records to the JSON source of truth. The caller
+ * `scanRepo` derives Symbol/Edge/Component records without mutating the store.
+ * `indexRepo` persists that exact scan into the JSON source of truth; its caller
  * then runs HunchStore.reindex() to refresh the SQLite index.
  */
-import { readFileSync, statSync, readdirSync } from "node:fs";
-import { join, relative, dirname, posix } from "node:path";
+import { dirname, posix } from "node:path";
 import { parseSource, attributeCalls } from "./parse.js";
 import { symbolId, componentId, edgeId, sha1 } from "../core/ids.js";
 import { externalImportNodeId, externalPackage } from "../core/externalImports.js";
 import { resolveRelativeImport } from "../core/relativeImports.js";
 import { extracted, inferred } from "../core/types.js";
-import { isGitRepo, trackedFiles, fileGitMetrics } from "./git.js";
-import { CODE_EXTENSIONS, languageFor } from "./languages.js";
-const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".hunch", "coverage", ".next", "out"]);
-export function indexRepo(store, root, opts = {}) {
-    const files = listCodeFiles(root);
+import { isGitRepo, fileGitMetrics, revExists } from "./git.js";
+import { languageFor } from "./languages.js";
+import { assertCleanIndexedCode, repoSourceInventory, } from "./repoSource.js";
+/** Read-only policy evaluators must never turn an omitted source file into a
+ * false satisfied receipt. Call this after scanRepo when the consumer cannot
+ * represent partial-graph uncertainty directly. */
+export function assertCompleteRepoScan(scan) {
+    if (!scan.issues.length)
+        return;
+    const sample = scan.issues.slice(0, 5)
+        .map((issue) => `${issue.path} [${issue.code}]`)
+        .join(", ");
+    const more = scan.issues.length > 5 ? ` (+${scan.issues.length - 5} more)` : "";
+    throw new Error(`incomplete semantic source scan rejected ${scan.issues.length} file(s): ${sample}${more}`);
+}
+/** Derive the current repository graph without writing JSON or rebuilding SQLite.
+ * Read-only gates use this so checking changed code can never rewrite or publish
+ * the durable graph merely by inspecting it. Existing public graph records remain
+ * inputs for the same churn/component enrichment semantics as a persisted index. */
+export function scanRepo(store, root, opts = {}) {
+    const inventory = repoSourceInventory(root, opts.source);
+    const files = inventory.entries;
     const useGit = isGitRepo(root);
+    // Fast scans intentionally skip the expensive 90-day history walk. Zero is
+    // not a fresh measurement, though: overwriting a previously measured value
+    // makes full and fast scans ping-pong symbols/index.json and can create an
+    // endless stream of memory-only commits. Churn is file-level, so retain the
+    // latest durable value for every still-indexed file; genuinely new files use
+    // the conservative zero default until the next full scan.
+    const preservedChurn = new Map();
+    if (opts.churn === false) {
+        for (const symbol of store.json.loadAll("symbols")) {
+            preservedChurn.set(symbol.file, Math.max(preservedChurn.get(symbol.file) ?? 0, symbol.metrics.churn_90d));
+        }
+    }
     // ---- pass 1: parse files -> symbols, remember per-file calls & imports ----
     const symbols = [];
     const nameIndex = new Map(); // symbol name -> [symbol ids]
@@ -29,19 +58,27 @@ export function indexRepo(store, root, opts = {}) {
     const perFileImports = [];
     // Batched per-file git metrics (churn + last commit) in TWO `git log` spawns
     // total, instead of two per file — the dominant cost of indexing a large repo.
-    const rels = files.map((abs) => toPosix(relative(root, abs)));
+    const rels = files.map((file) => file.path);
     const gitMeta = useGit ? fileGitMetrics(root, rels, opts.churn === false ? 0 : 90) : null;
     let skipped = 0;
-    for (const abs of files) {
-        const rel = toPosix(relative(root, abs));
-        let src;
-        try {
-            src = readFileSync(abs, "utf8");
+    const issues = [];
+    const sourceFingerprint = [];
+    for (const file of files) {
+        const rel = file.path;
+        const read = file.read();
+        if (read.absent) {
+            sourceFingerprint.push({ path: rel, mode: read.mode, content: "absent" });
+            continue;
         }
-        catch {
+        if (read.source === null) {
             skipped++;
+            const issue = read.issue ?? { path: rel, code: "read_failed", detail: `${rel} could not be read` };
+            issues.push(issue);
+            sourceFingerprint.push({ path: rel, mode: read.mode, content: read.contentHash ?? `skipped:${issue.code}` });
             continue;
         }
+        const src = read.source;
+        sourceFingerprint.push({ path: rel, mode: read.mode, content: read.contentHash });
         // one bad/oversized file must never abort the whole index run
         let parsed;
         try {
@@ -49,14 +86,21 @@ export function indexRepo(store, root, opts = {}) {
         }
         catch {
             skipped++;
+            issues.push({ path: rel, code: "parse_failed", detail: `${rel} could not be parsed` });
             continue;
         }
         if (!parsed) {
             skipped++;
+            issues.push({ path: rel, code: "parse_failed", detail: `${rel} has no supported parser` });
+            continue;
+        }
+        if (!parsed.parseable) {
+            skipped++;
+            issues.push({ path: rel, code: "parse_failed", detail: `${rel} contains syntax errors and cannot prove a complete semantic graph` });
             continue;
         }
         const m = gitMeta?.get(rel);
-        const churn = m?.churn ?? 0;
+        const churn = opts.churn === false ? (preservedChurn.get(rel) ?? 0) : (m?.churn ?? 0);
         const last = m?.lastCommit ?? "";
         const idsInFile = [];
         const startByteId = new Map();
@@ -189,9 +233,6 @@ export function indexRepo(store, root, opts = {}) {
             }
         }
     }
-    // persist
-    store.json.replaceAll("symbols", symbols);
-    store.json.replaceAll("edges", edges);
     // Components are derived-but-ENRICHED records: layout facts (paths, kind, name)
     // come from this scan, while curation/synthesis (responsibility, owners, status,
     // fragility from raiseFragility, upgraded provenance) lives only on the stored
@@ -215,36 +256,34 @@ export function indexRepo(store, root, opts = {}) {
         };
         return stamp(merged) === stamp(prev) ? prev : { ...merged, updated_at: draft.updated_at };
     });
-    store.json.replaceAll("components", compsOut);
-    return { files: files.length, symbols: symbols.length, edges: edges.length, components: compsOut.length, skipped };
-}
-// ---- helpers --------------------------------------------------------------
-function listCodeFiles(root) {
-    if (isGitRepo(root)) {
-        // Apply SKIP_DIRS to the git-tracked list too: a repo that (accidentally)
-        // tracks node_modules/ or dist/ must not flood the graph with vendored symbols.
-        const tracked = trackedFiles(root, CODE_EXTENSIONS)
-            .filter((f) => !f.split(/[\\/]/).some((seg) => SKIP_DIRS.has(seg)))
-            .map((f) => join(root, f));
-        if (tracked.length > 0)
-            return tracked; // else fall through (nothing committed yet)
-    }
-    const out = [];
-    const walk = (dir) => {
-        for (const name of readdirSync(dir)) {
-            if (SKIP_DIRS.has(name))
-                continue;
-            const abs = join(dir, name);
-            const st = statSync(abs);
-            if (st.isDirectory())
-                walk(abs);
-            else if (languageFor(name) !== null)
-                out.push(abs);
-        }
+    return {
+        result: { files: files.length, symbols: symbols.length, edges: edges.length, components: compsOut.length, skipped },
+        symbols,
+        edges,
+        components: compsOut,
+        source: { ...inventory.identity, content_hash: sha1(JSON.stringify(sourceFingerprint)) },
+        issues,
     };
-    walk(root);
-    return out;
 }
+/** Persist one pure scan into the Git-native source of truth. */
+export function indexRepo(store, root, opts = {}) {
+    if (opts.requireClean)
+        assertCleanIndexedCode(root);
+    // A clean preflight followed by a filesystem read still has a TOCTOU seam.
+    // Durable Git-backed publication therefore derives from immutable HEAD blobs;
+    // unborn and non-Git repositories retain the historical safe-filesystem path.
+    const source = opts.requireClean && isGitRepo(root) && revExists("HEAD", root)
+        ? { kind: "commit", ref: "HEAD" }
+        : opts.source;
+    const scan = scanRepo(store, root, { churn: opts.churn, source });
+    if (opts.requireComplete)
+        assertCompleteRepoScan(scan);
+    store.json.replaceAll("symbols", scan.symbols);
+    store.json.replaceAll("edges", scan.edges);
+    store.json.replaceAll("components", scan.components);
+    return scan.result;
+}
+// ---- helpers --------------------------------------------------------------
 /** Resolve a callee name to a symbol id: prefer same-file, otherwise require a
  * unique symbol in a statically imported local file. A unique repository-wide
  * name is not evidence of a binding: callback parameters and built-ins often

package/dist/extractors/repoSource.js

@@ -0,0 +1,390 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { TextDecoder } from "node:util";
+import { MAX_REPO_SOURCE_FILE_BYTES, createRepoFileBufferReader } from "../core/safeRepoFile.js";
+import { compareCodeUnits } from "../core/canonicalOrder.js";
+import { foreignRepoEnv, gitNullDevice } from "./git.js";
+import { languageFor } from "./languages.js";
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".hunch", "coverage", ".next", "out"]);
+const ORDINARY_BLOB_MODES = new Set(["100644", "100755"]);
+const GIT_MAX_LISTING_BYTES = 64 * 1024 * 1024;
+function rawContentHash(bytes) {
+    return `sha1:${createHash("sha1").update(bytes).digest("hex")}`;
+}
+function decodedSource(path, mode, bytes) {
+    const contentHash = rawContentHash(bytes);
+    try {
+        return { source: UTF8_DECODER.decode(bytes), mode, contentHash };
+    }
+    catch {
+        return {
+            source: null,
+            mode,
+            contentHash,
+            issue: { path, code: "invalid_encoding", detail: `${path} is not valid UTF-8 and cannot be parsed losslessly` },
+        };
+    }
+}
+function gitEnv(preserveInvocationIndex = false) {
+    const env = {
+        ...foreignRepoEnv(process.env),
+        GIT_CONFIG_NOSYSTEM: "1",
+        GIT_CONFIG_GLOBAL: gitNullDevice(),
+        GIT_NO_REPLACE_OBJECTS: "1",
+    };
+    // A partial/pre-commit workflow can intentionally select an alternate index.
+    // `foreignRepoEnv` must clear it for commit/replay work in another checkout,
+    // but staged/working source selection in the invocation repo has to use the
+    // same index as changed-file enumeration or the gate can inspect two worlds.
+    if (preserveInvocationIndex && process.env.GIT_INDEX_FILE) {
+        env.GIT_INDEX_FILE = process.env.GIT_INDEX_FILE;
+    }
+    return env;
+}
+function gitBuffer(root, args, maxBuffer = GIT_MAX_LISTING_BYTES, preserveInvocationIndex = false) {
+    return execFileSync("git", ["-C", root, ...args], {
+        encoding: "buffer",
+        env: gitEnv(preserveInvocationIndex),
+        maxBuffer,
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 15_000,
+    });
+}
+function gitText(root, args) {
+    return gitBuffer(root, args, 1024 * 1024).toString("utf8").trim();
+}
+function isGitRepository(root) {
+    try {
+        return gitText(root, ["rev-parse", "--is-inside-work-tree"]) === "true";
+    }
+    catch {
+        return false;
+    }
+}
+function isSafeRelativePath(path) {
+    const segments = path.split("/");
+    return !!path
+        && !path.startsWith("/")
+        && !path.includes("\\")
+        && !/^[A-Za-z]:/.test(path)
+        && segments.every((segment) => !!segment && segment !== "." && segment !== ".." && segment.toLowerCase() !== ".git");
+}
+function isSkippedPath(path) {
+    return path.split("/").some((segment) => SKIP_DIRS.has(segment));
+}
+export function isIndexedCodePath(path) {
+    return languageFor(path) !== null && !isSkippedPath(path);
+}
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+function nulRecords(bytes) {
+    const records = [];
+    let start = 0;
+    for (let end = bytes.indexOf(0, start); end !== -1; end = bytes.indexOf(0, start)) {
+        if (end > start)
+            records.push(bytes.subarray(start, end));
+        start = end + 1;
+    }
+    if (start < bytes.length)
+        records.push(bytes.subarray(start));
+    return records;
+}
+function decodeGitPath(bytes) {
+    try {
+        const path = UTF8_DECODER.decode(bytes);
+        return { path, invalidUtf8: false, indexedCode: isIndexedCodePath(path) };
+    }
+    catch {
+        // Git pathnames are arbitrary bytes on POSIX. Never collapse distinct byte
+        // sequences through U+FFFD: bind the raw bytes to a stable opaque label and
+        // make the semantic scan incomplete/fail-closed.
+        const fingerprint = createHash("sha256").update(bytes).digest("hex");
+        return { path: `<non-utf8-git-path:sha256:${fingerprint}>`, invalidUtf8: true, indexedCode: true };
+    }
+}
+function issueEntry(path, mode, code, detail) {
+    const issue = { path, code, detail };
+    return { path, mode, read: () => ({ source: null, mode, issue }) };
+}
+function filesystemEntry(root, path, allowMissing) {
+    const readFile = createRepoFileBufferReader(root);
+    return {
+        path,
+        mode: "filesystem",
+        read: () => {
+            const absolute = join(root, path);
+            let stat;
+            try {
+                stat = lstatSync(absolute);
+            }
+            catch (error) {
+                if (allowMissing && error.code === "ENOENT") {
+                    return { source: null, mode: "absent", absent: true };
+                }
+                return {
+                    source: null,
+                    mode: "filesystem",
+                    issue: { path, code: "read_failed", detail: `${path} disappeared or could not be inspected` },
+                };
+            }
+            if (stat.isSymbolicLink()) {
+                return { source: null, mode: "120000", issue: { path, code: "symlink", detail: `${path} is a symlink` } };
+            }
+            if (!stat.isFile()) {
+                return { source: null, mode: "non-regular", issue: { path, code: "non_regular", detail: `${path} is not a regular file` } };
+            }
+            const mode = stat.mode & 0o111 ? "100755" : "100644";
+            if (stat.size > MAX_REPO_SOURCE_FILE_BYTES) {
+                return { source: null, mode, issue: { path, code: "oversized", detail: `${path} exceeds the ${MAX_REPO_SOURCE_FILE_BYTES}-byte source limit` } };
+            }
+            const bytes = readFile(absolute);
+            return bytes === null
+                ? { source: null, mode, issue: { path, code: "read_failed", detail: `${path} changed identity or could not be read safely` } }
+                : decodedSource(path, mode, bytes);
+        },
+    };
+}
+function gitBlobEntry(root, path, mode, oid) {
+    return {
+        path,
+        mode,
+        read: () => {
+            try {
+                const type = gitText(root, ["cat-file", "-t", oid]);
+                const size = Number(gitText(root, ["cat-file", "-s", oid]));
+                if (type !== "blob" || !Number.isSafeInteger(size) || size < 0) {
+                    return { source: null, mode, issue: { path, code: "read_failed", detail: `${path} does not resolve to an ordinary blob` } };
+                }
+                if (size > MAX_REPO_SOURCE_FILE_BYTES) {
+                    return { source: null, mode, issue: { path, code: "oversized", detail: `${path} exceeds the ${MAX_REPO_SOURCE_FILE_BYTES}-byte source limit` } };
+                }
+                const bytes = gitBuffer(root, ["cat-file", "blob", oid], MAX_REPO_SOURCE_FILE_BYTES + 1);
+                if (bytes.length !== size) {
+                    return { source: null, mode, issue: { path, code: "read_failed", detail: `${path} blob length changed while scanning` } };
+                }
+                return decodedSource(path, mode, bytes);
+            }
+            catch {
+                return { source: null, mode, issue: { path, code: "read_failed", detail: `${path} blob could not be read` } };
+            }
+        },
+    };
+}
+function indexRows(root, preserveInvocationIndex = false) {
+    const raw = gitBuffer(root, ["ls-files", "--cached", "--stage", "-z"], GIT_MAX_LISTING_BYTES, preserveInvocationIndex);
+    const rows = [];
+    for (const record of nulRecords(raw)) {
+        const tab = record.indexOf(0x09);
+        if (tab < 0)
+            throw new Error("could not parse the Git index while selecting semantic source");
+        const match = record.subarray(0, tab).toString("ascii").match(/^([0-7]{6}) ([0-9a-f]{40,64}) ([0-3])$/i);
+        if (!match)
+            throw new Error("could not parse the Git index while selecting semantic source");
+        const decoded = decodeGitPath(record.subarray(tab + 1));
+        rows.push({
+            mode: match[1],
+            oid: match[2].toLowerCase(),
+            stage: Number(match[3]),
+            path: decoded.path,
+            invalidUtf8: decoded.invalidUtf8,
+            indexedCode: decoded.indexedCode,
+        });
+    }
+    return rows;
+}
+function normalizeCandidate(path, mode) {
+    if (!isIndexedCodePath(path))
+        return "skip";
+    if (!isSafeRelativePath(path))
+        return issueEntry(path, mode, "unsafe_path", `${path} is not a safe repository-relative source path`);
+    return null;
+}
+function stagedInventory(root) {
+    const grouped = new Map();
+    for (const row of indexRows(root, true)) {
+        const rows = grouped.get(row.path) ?? [];
+        rows.push(row);
+        grouped.set(row.path, rows);
+    }
+    const entries = [];
+    for (const path of [...grouped.keys()].sort(compareCodeUnits)) {
+        const rows = grouped.get(path);
+        if (rows.some((row) => row.invalidUtf8)) {
+            if (rows.some((row) => row.indexedCode)) {
+                entries.push(issueEntry(path, rows[0]?.mode ?? "index", "unsafe_path", `${path} is not valid UTF-8 and cannot be scanned losslessly`));
+            }
+            continue;
+        }
+        const preflight = normalizeCandidate(path, rows[0]?.mode ?? "index");
+        if (preflight === "skip")
+            continue;
+        if (preflight) {
+            entries.push(preflight);
+            continue;
+        }
+        if (rows.some((row) => row.stage !== 0)) {
+            entries.push(issueEntry(path, "conflicted", "conflicted", `${path} has unresolved Git index stages`));
+            continue;
+        }
+        const row = rows.find((candidate) => candidate.stage === 0);
+        if (!row) {
+            entries.push(issueEntry(path, "conflicted", "conflicted", `${path} has no stage-0 Git index blob`));
+        }
+        else if (!ORDINARY_BLOB_MODES.has(row.mode)) {
+            entries.push(issueEntry(path, row.mode, "unsafe_mode", `${path} uses unsupported Git mode ${row.mode}`));
+        }
+        else {
+            entries.push(gitBlobEntry(root, path, row.mode, row.oid));
+        }
+    }
+    return { identity: { kind: "staged" }, entries };
+}
+function exactCommit(root, ref) {
+    const revision = gitText(root, ["rev-parse", "--verify", `${ref}^{commit}`]).toLowerCase();
+    if (!/^[0-9a-f]{40,64}$/.test(revision))
+        throw new Error(`semantic source ref ${JSON.stringify(ref)} is not an exact commit`);
+    return revision;
+}
+function treeInventory(root, kind, ref) {
+    const revision = exactCommit(root, ref);
+    const raw = gitBuffer(root, ["ls-tree", "--full-tree", "-r", "-z", revision]);
+    const entries = [];
+    for (const record of nulRecords(raw)) {
+        const tab = record.indexOf(0x09);
+        if (tab < 0)
+            throw new Error(`could not parse exact ${kind} tree ${revision}`);
+        const match = record.subarray(0, tab).toString("ascii").match(/^([0-7]{6}) (blob|tree|commit) ([0-9a-f]{40,64})$/i);
+        if (!match)
+            throw new Error(`could not parse exact ${kind} tree ${revision}`);
+        const mode = match[1];
+        const type = match[2];
+        const oid = match[3].toLowerCase();
+        const decoded = decodeGitPath(record.subarray(tab + 1));
+        const path = decoded.path;
+        if (decoded.invalidUtf8) {
+            if (decoded.indexedCode)
+                entries.push(issueEntry(path, mode, "unsafe_path", `${path} is not valid UTF-8 and cannot be scanned losslessly`));
+            continue;
+        }
+        const preflight = normalizeCandidate(path, mode);
+        if (preflight === "skip")
+            continue;
+        if (preflight) {
+            entries.push(preflight);
+            continue;
+        }
+        if (type !== "blob" || !ORDINARY_BLOB_MODES.has(mode)) {
+            entries.push(issueEntry(path, mode, "unsafe_mode", `${path} uses unsupported Git ${type} mode ${mode}`));
+        }
+        else {
+            entries.push(gitBlobEntry(root, path, mode, oid));
+        }
+    }
+    entries.sort((left, right) => compareCodeUnits(left.path, right.path));
+    return { identity: { kind, revision }, entries };
+}
+function nulPaths(root, args, preserveInvocationIndex = false) {
+    return nulRecords(gitBuffer(root, args, GIT_MAX_LISTING_BYTES, preserveInvocationIndex)).map(decodeGitPath);
+}
+function filesystemInventory(root, kind) {
+    if (!isGitRepository(root))
+        return walkedInventory(root, kind);
+    const preserveInvocationIndex = kind === "working";
+    const rows = indexRows(root, preserveInvocationIndex);
+    const tracked = new Set(rows.filter((row) => !row.invalidUtf8).map((row) => row.path));
+    const conflicted = new Set(rows.filter((row) => !row.invalidUtf8 && row.stage !== 0).map((row) => row.path));
+    const untracked = kind === "working"
+        ? nulPaths(root, ["ls-files", "--others", "--exclude-standard", "-z"], true)
+        : [];
+    // Preserve historical checkout-index behavior: when an unborn repository has
+    // no tracked source, initialization scans the safe filesystem instead.
+    if (kind === "checkout" && rows.length === 0)
+        return walkedInventory(root, kind);
+    const paths = [...new Set([...tracked, ...untracked.filter((item) => !item.invalidUtf8).map((item) => item.path)])].sort(compareCodeUnits);
+    const entries = [];
+    const invalid = new Map();
+    for (const row of rows) {
+        if (row.invalidUtf8 && row.indexedCode)
+            invalid.set(row.path, row.mode);
+    }
+    for (const item of untracked) {
+        if (item.invalidUtf8 && item.indexedCode)
+            invalid.set(item.path, "filesystem");
+    }
+    for (const [path, mode] of [...invalid].sort(([left], [right]) => compareCodeUnits(left, right))) {
+        entries.push(issueEntry(path, mode, "unsafe_path", `${path} is not valid UTF-8 and cannot be scanned losslessly`));
+    }
+    for (const path of paths) {
+        const preflight = normalizeCandidate(path, "filesystem");
+        if (preflight === "skip")
+            continue;
+        if (preflight) {
+            entries.push(preflight);
+            continue;
+        }
+        if (conflicted.has(path)) {
+            entries.push(issueEntry(path, "conflicted", "conflicted", `${path} has unresolved Git index stages`));
+        }
+        else {
+            entries.push(filesystemEntry(root, path, tracked.has(path)));
+        }
+    }
+    return { identity: { kind }, entries };
+}
+function walkedInventory(root, kind) {
+    const paths = [];
+    const walk = (dir, prefix = "") => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                walk(join(dir, entry.name), path);
+            else if (languageFor(path))
+                paths.push(path);
+        }
+    };
+    walk(root);
+    return {
+        identity: { kind },
+        entries: paths.sort(compareCodeUnits).map((path) => filesystemEntry(root, path, false)),
+    };
+}
+export function repoSourceInventory(root, source = { kind: "checkout" }) {
+    if (source.kind === "staged") {
+        if (!isGitRepository(root))
+            throw new Error("staged semantic source requires a Git repository");
+        return stagedInventory(root);
+    }
+    if (source.kind === "commit") {
+        if (!isGitRepository(root))
+            throw new Error("commit semantic source requires a Git repository");
+        return treeInventory(root, "commit", source.ref);
+    }
+    if (source.kind === "base") {
+        if (!isGitRepository(root))
+            throw new Error("base semantic source requires a Git repository");
+        return treeInventory(root, "base", "HEAD");
+    }
+    return filesystemInventory(root, source.kind);
+}
+export function dirtyIndexedCodePaths(root) {
+    if (!isGitRepository(root))
+        return [];
+    const paths = [
+        ...nulPaths(root, ["diff", "--cached", "--no-ext-diff", "--no-textconv", "--name-only", "--no-renames", "--diff-filter=ACDMRTUXB", "-z", "--"], true),
+        ...nulPaths(root, ["diff", "--no-ext-diff", "--no-textconv", "--name-only", "--no-renames", "--diff-filter=ACDMRTUXB", "-z", "--"], true),
+        ...nulPaths(root, ["ls-files", "--others", "--exclude-standard", "-z"], true),
+    ];
+    return [...new Set(paths.filter((item) => item.indexedCode).map((item) => item.path))].sort(compareCodeUnits);
+}
+export function assertCleanIndexedCode(root) {
+    const dirty = dirtyIndexedCodePaths(root);
+    if (!dirty.length)
+        return;
+    const sample = dirty.slice(0, 5).join(", ");
+    const more = dirty.length > 5 ? ` (+${dirty.length - 5} more)` : "";
+    throw new Error(`refusing to persist a derived graph from dirty indexed code: ${sample}${more}; commit or stash code changes, then retry`);
+}
+//# sourceMappingURL=repoSource.js.map

package/dist/integrations/ciAction.js

@@ -8,6 +8,7 @@
  */
 import { mkdirSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
+import { HUNCH_VERSION } from "../core/version.js";
 // `\${{ … }}` keeps GitHub Actions expressions literal inside this template
 // literal (a bare `${` would be JS interpolation).
 export function ciWorkflowYaml() {
@@ -29,14 +30,21 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
+          # Check the actual PR head, not GitHub's synthetic merge commit. This
+          # lets repository readiness checks prove the branch contains its live
+          # base instead of passing merely because GitHub pre-merged it.
+          ref: \${{ github.event.pull_request.head.sha }}
           fetch-depth: 0 # full history: the guard diffs base...head and reads git log
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22.13.0
 
       - name: Install Hunch
-        run: npm install -g @davesheffer/hunch
+        # Pin the same release that generated this file so every assistant and CI
+        # evaluate the graph with identical semantics. Dependabot/Renovate (or a
+        # deliberate hunch-ci refresh) can advance this in a reviewed change.
+        run: npm install -g @davesheffer/hunch@${HUNCH_VERSION}
 
       - name: Fetch the PR base branch
         # checkout sets up no origin/<base> tracking ref; create it explicitly so