trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/graph/container.js

@@ -0,0 +1,191 @@
+/**
+ * Container tier — files that are not a language but a wrapper around one.
+ *
+ * A Vue SFC is the motivating case: `.vue` is HTML-shaped, and everything worth
+ * indexing lives inside its `<script>` block. Registering `tree-sitter-vue` as a
+ * breadth-tier language (generic.ts) would not help — that grammar parses the
+ * shell (`<template>` / `<script>` / `<style>`) and hands back the script body as
+ * one opaque `raw_text` node, so the cards would come out empty.
+ *
+ * So the container grammar is used only to answer "where does the embedded
+ * language start and end", and the block itself goes to the DEPTH-tier extractor
+ * (extract.ts). A `.vue` file therefore gets the same quality of extraction as a
+ * `.ts` file — bindings, imports, resolved calls — not the signature-only output
+ * the breadth tier would give.
+ *
+ * **The span shift is the whole risk here.** `extractFile` numbers its spans from
+ * the start of the string it was handed, so every node comes back pointing at a
+ * line in the script, not in the `.vue`. A span that is off by even one line is
+ * worse than not indexing the file at all: graft's promise is that its
+ * `file:line` is exact, and a plausible-but-wrong line silently sends the reader
+ * to the wrong place. `test/container-extract.test.ts` pins this against
+ * fixtures whose true line numbers are known.
+ */
+import { extractFile, mintId } from "./extract.js";
+import { extractGeneric, fallbackLangOf, loadWasmLanguage, parseWasm } from "./generic.js";
+import { depthReady, warmDepthGrammars } from "./depth-parser.js";
+import { contentHash } from "../util/id.js";
+/** The container registry. Svelte and Astro are the same shape and would be a
+ * row each, but they are left out until someone has a repo to verify them
+ * against — a wrong `body` node type would produce silently misplaced spans. */
+export const CONTAINER_LANGS = [
+    { name: "vue", exts: [".vue"], wasm: "vue", block: "script_element", body: "raw_text", inner: "typescript" },
+];
+const byExt = new Map();
+for (const l of CONTAINER_LANGS)
+    for (const e of l.exts)
+        byExt.set(e, l);
+/** The container language for a path, or null if none claims it. */
+export function containerLangOf(path) {
+    const lower = path.toLowerCase();
+    for (const [ext, l] of byExt)
+        if (lower.endsWith(ext))
+            return l;
+    return null;
+}
+/** Every file extension the container tier claims. */
+export function containerExtensions() {
+    return CONTAINER_LANGS.flatMap((l) => l.exts);
+}
+const loaded = new Map();
+/** Warm the container grammars this repo needs, and the depth grammar of each
+ * one's embedded language. Same contract as `warmGenericGrammars`: await once
+ * before the synchronous parse loop, and an unavailable grammar is skipped rather
+ * than fatal (its files then extract to a file node only, exactly as they do today). */
+export async function warmContainerGrammars(langNames) {
+    for (const name of new Set(langNames)) {
+        if (loaded.has(name))
+            continue;
+        const row = CONTAINER_LANGS.find((l) => l.name === name);
+        if (!row)
+            continue;
+        await warmDepthGrammars([row.inner]);
+        const language = await loadWasmLanguage(row.wasm);
+        if (language)
+            loaded.set(name, language);
+    }
+}
+/** True if a container grammar has been warmed (else extraction is file-only). */
+export function isContainerWarm(langName) {
+    return loaded.has(langName);
+}
+/** `L12-L20` shifted by n lines. The span format is produced in exactly two
+ * places (extract.ts and generic.ts) and is always this shape; anything else is
+ * returned untouched rather than guessed at. */
+function shiftSpan(span, lines) {
+    const m = /^L(\d+)-L(\d+)$/.exec(span);
+    if (!m)
+        return span;
+    return `L${Number(m[1]) + lines}-L${Number(m[2]) + lines}`;
+}
+/** The `.vue` file's own node. Deliberately describes the whole file — line
+ * count, hash and size of the SFC, not of the script block — because that is
+ * what a reader opening this path will see. */
+function containerFileNode(rel, source, residual) {
+    return {
+        id: rel,
+        name: rel.split("/").pop() ?? rel,
+        kind: "file",
+        path: rel,
+        span: `L1-L${Math.max(1, source.split("\n").length)}`,
+        signature: null,
+        exported: true,
+        // "ast", not "generic": the symbols under this file come from the depth-tier
+        // extractor with real bindings and specifiers. resolve.ts gates a
+        // guess-by-name fallback on `origin === "generic"`, and these nodes must not
+        // take it — they carry the information to resolve properly.
+        origin: "ast",
+        body_hash: contentHash(source),
+        chars: source.length,
+        body_text: residual,
+        summary_state: "pending",
+        summary: null,
+        crux: null,
+    };
+}
+/** Every embedded block in document order, as [bodyNode] — an SFC may legally
+ * carry two (`<script>` for options/exports plus `<script setup>`), and each
+ * needs its own offset. */
+function blocks(root, lang) {
+    const out = [];
+    const n = root.namedChildCount ?? 0;
+    for (let i = 0; i < n; i++) {
+        const child = root.namedChild?.(i);
+        if (!child || child.type !== lang.block)
+            continue;
+        const kids = child.namedChildCount ?? 0;
+        for (let j = 0; j < kids; j++) {
+            const body = child.namedChild?.(j);
+            // An empty `<script></script>` has no body child at all — skipped here, so
+            // the file still gets its file node and nothing else, which is the same
+            // shape as a file whose grammar is missing.
+            if (body && body.type === lang.body)
+                out.push(body);
+        }
+    }
+    return out;
+}
+/**
+ * Extract one container file. Synchronous; needs the grammar pre-warmed.
+ *
+ * Never throws: a missing grammar, an unparseable SFC or a script block the
+ * inner extractor chokes on all degrade to "fewer nodes", because a build must
+ * not fail over one component.
+ */
+export function extractContainer(rel, source, lang) {
+    const nodes = [];
+    const rawEdges = [];
+    const residuals = [];
+    const language = loaded.get(lang.name);
+    const root = language ? parseWasm(language, source) : null;
+    if (root) {
+        // Ids are minted per file by the inner extractor, so two script blocks that
+        // both define `setup` would collide. Threading one set across the blocks
+        // makes the second one `path#setup~2`, and the rename is applied to that
+        // block's edges too so nothing points at an id that no longer exists.
+        const minted = new Set([rel]);
+        for (const body of blocks(root, lang)) {
+            const script = source.slice(body.startIndex, body.endIndex);
+            let inner;
+            try {
+                // No grammar for the embedded language (see depth-parser.ts): its breadth
+                // stand-in gives the block's symbols, warmed by the build like any other.
+                inner = depthReady(lang.inner)
+                    ? extractFile(rel, script, lang.inner)
+                    : extractGeneric(rel, script, fallbackLangOf(lang.inner).name);
+            }
+            catch {
+                continue; // one bad block, not a bad build
+            }
+            // `raw_text` starts immediately after the `>` of the opening tag, so its
+            // row IS the tag's row and the slice begins with that line's newline.
+            // Script line 1 is therefore the tail of the tag line, and script line N
+            // lands on `.vue` line row + N — which is exactly "add the start row to a
+            // 1-based span". Taking the row from the tag node instead would look
+            // equivalent and be right only when the tag has no attributes.
+            const shift = body.startPosition.row;
+            // nodes[0] is the script's own file node: it describes the block, not the
+            // file, so it is dropped and its residual folded into the .vue file node.
+            const [scriptFile, ...symbols] = inner.nodes;
+            if (scriptFile?.body_text)
+                residuals.push(scriptFile.body_text);
+            const renamed = new Map();
+            for (const node of symbols) {
+                const id = mintId(node.id, minted);
+                if (id !== node.id)
+                    renamed.set(node.id, id);
+                nodes.push({ ...node, id, span: shiftSpan(node.span, shift) });
+            }
+            for (const edge of inner.rawEdges) {
+                const source_ = renamed.get(edge.source) ?? edge.source;
+                const targetId = edge.targetId === undefined ? undefined : (renamed.get(edge.targetId) ?? edge.targetId);
+                rawEdges.push({ ...edge, source: source_, ...(targetId === undefined ? {} : { targetId }) });
+            }
+        }
+    }
+    // Built last so it can carry the residual, but unshifted first so the file node
+    // stays at index 0 like every other tier's output.
+    nodes.unshift(containerFileNode(rel, source, residuals.join("\n")));
+    return { nodes, rawEdges };
+}
+//# sourceMappingURL=container.js.map

package/dist/graph/container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.js","sourceRoot":"","sources":["../../src/graph/container.ts"],"names":[],"mappings":"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"}

package/dist/graph/depth-parser.d.ts

@@ -0,0 +1,61 @@
+import type { Language } from "./extract.js";
+export interface Point {
+    row: number;
+    column: number;
+}
+/** The syntax-node surface extract.ts and bindings.ts use. */
+export interface SyntaxNode {
+    readonly type: string;
+    readonly text: string;
+    /** Unique within one tree; compare `tree` too (extract.ts `sameSyntaxNode`). */
+    readonly id: number;
+    readonly tree: unknown;
+    readonly startIndex: number;
+    readonly endIndex: number;
+    readonly startPosition: Point;
+    readonly endPosition: Point;
+    readonly parent: SyntaxNode | null;
+    readonly children: SyntaxNode[];
+    readonly namedChildren: SyntaxNode[];
+    readonly previousNamedSibling: SyntaxNode | null;
+    childForFieldName(fieldName: string): SyntaxNode | null;
+}
+/** Each depth grammar's .wasm: the package it comes from and the file's name. A
+ * `built` one isn't shipped by its package; it is in src/graph/grammars/. */
+export declare const DEPTH_WASM: Record<Language, {
+    module: string;
+    file: string;
+    built?: true;
+}>;
+/** Languages that parse on their native addon instead. Empty: every depth
+ * language built the native graph exactly on WASM (test/depth-parity.ts). */
+export declare const NATIVE_ONLY: ReadonlySet<Language>;
+/** `lang`'s .wasm bytes: from dist/vendor/grammars/ in a build, else (run from
+ * src/) from src/graph/grammars/ or the grammar package in node_modules. */
+export declare function readDepthWasm(lang: Language, vendorDir?: string): Uint8Array;
+type Backend = "wasm" | "native";
+/** Load the grammars for `langs`. Await once before a synchronous parse loop.
+ * Never throws: a grammar that won't load leaves {@link depthReady} false. */
+export declare function warmDepthGrammars(langs: Iterable<Language>): Promise<void>;
+/** True when `lang`'s grammar is loaded and can parse. Never throws. */
+export declare function depthReady(lang: Language): boolean;
+/**
+ * Parse `source` as `lang` and hand the root to `use`. The tree lives only for the
+ * call: a WASM tree is freed when `use` returns, so nothing may keep a node.
+ * Throws when the grammar is unavailable: callers ask {@link depthReady} first and
+ * send the file to its breadth-tier stand-in instead.
+ */
+export declare function parseDepth<T>(lang: Language, source: string, use: (root: SyntaxNode) => T): T;
+/** The npm packages whose missing binary keeps these languages off a native
+ * parser. Only a {@link NATIVE_ONLY} language can have one: a WASM grammar has no
+ * install script for `--allow-scripts` to run. */
+export declare function missingDepthPackages(langs: Iterable<Language>): string[];
+/** Test seam: parse every depth language on `backend` (null restores the default
+ * per-language choice), and/or replace how a grammar's .wasm is read (a function
+ * that throws simulates a missing or corrupt file). Forgets every grammar loaded. */
+export declare function setDepthParsersForTest(opts: {
+    backend?: Backend | null;
+    readWasm?: ((lang: Language) => Uint8Array) | null;
+}): void;
+export {};
+//# sourceMappingURL=depth-parser.d.ts.map

package/dist/graph/depth-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"depth-parser.d.ts","sourceRoot":"","sources":["../../src/graph/depth-parser.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAI7C,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,UAAU,EAAE,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,UAAU,GAAG,IAAI,CAAC;IACjD,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;CACzD;AAED;6EAC6E;AAC7E,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,QAAQ,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,IAAI,CAAA;CAAE,CAUvF,CAAC;AAEF;6EAC6E;AAC7E,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,QAAQ,CAAuB,CAAC;AAMtE;4EAC4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,SAAa,GAAG,UAAU,CAKhF;AAED,KAAK,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AA6BjC;8EAC8E;AAC9E,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhF;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAElD;AASD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,CAAC,GAAG,CAAC,CA0B7F;AAED;;kDAEkD;AAClD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,CAExE;AAED;;qFAEqF;AACrF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,KAAK,UAAU,CAAC,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAInI"}

package/dist/graph/depth-parser.js

@@ -0,0 +1,153 @@
+/**
+ * The depth tier's parsers: the grammars extract.ts walks, compiled to WASM, so
+ * installing the package compiles nothing.
+ *
+ * Both halves of a parse are what the native addons ran. The grammars are the same
+ * versions the addons were built from, not the breadth tier's bundle: a grammar
+ * version changes parse trees, and extract.ts is written against these exact
+ * trees. And they run on web-tree-sitter 0.22.2, the tree-sitter core the addons
+ * were built with (wasm-runtime.ts says why that matters). Most grammar packages
+ * ship their own .wasm next to the native binding; python, kotlin and swift don't,
+ * so scripts/build-grammar-wasm.mjs compiles theirs from the package's own src/
+ * and they are committed in src/graph/grammars/ (grammars.json records what each
+ * was built from; that script says why swift's scanner is patched). `npm run
+ * build` copies all of them into dist/vendor/grammars/ (scripts/vendor-grammars.mjs).
+ *
+ * The native addons (native.ts) stay behind the same interface for two reasons: a
+ * language listed in {@link NATIVE_ONLY} parses on its addon, and
+ * test/depth-parity.ts builds real repos on both and diffs the graphs. Either way
+ * extract.ts sees one node API, {@link SyntaxNode}, which both satisfy.
+ *
+ * Loading WASM is async and parsing is not, so a build awaits
+ * {@link warmDepthGrammars} once (build.ts `warmGrammarsFor` does) before its
+ * synchronous parse loop. A grammar that won't load sends its language's files to
+ * the breadth tier's stand-in (`fallbackLangOf` in generic.ts).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { missingNativePackages, nativeParser, nativeReady } from "./native.js";
+import { depthRuntime } from "./wasm-runtime.js";
+/** Each depth grammar's .wasm: the package it comes from and the file's name. A
+ * `built` one isn't shipped by its package; it is in src/graph/grammars/. */
+export const DEPTH_WASM = {
+    typescript: { module: "tree-sitter-typescript", file: "tree-sitter-typescript.wasm" },
+    tsx: { module: "tree-sitter-typescript", file: "tree-sitter-tsx.wasm" },
+    python: { module: "tree-sitter-python", file: "tree-sitter-python.wasm", built: true },
+    go: { module: "tree-sitter-go", file: "tree-sitter-go.wasm" },
+    r: { module: "tree-sitter-r", file: "tree-sitter-r.wasm" },
+    java: { module: "tree-sitter-java", file: "tree-sitter-java.wasm" },
+    kotlin: { module: "tree-sitter-kotlin", file: "tree-sitter-kotlin.wasm", built: true },
+    swift: { module: "tree-sitter-swift", file: "tree-sitter-swift.wasm", built: true },
+    php: { module: "tree-sitter-php", file: "tree-sitter-php.wasm" },
+};
+/** Languages that parse on their native addon instead. Empty: every depth
+ * language built the native graph exactly on WASM (test/depth-parity.ts). */
+export const NATIVE_ONLY = new Set();
+const nodeRequire = createRequire(import.meta.url);
+const VENDOR_DIR = fileURLToPath(new URL("../vendor/grammars/", import.meta.url));
+const BUILT_DIR = fileURLToPath(new URL("./grammars/", import.meta.url));
+/** `lang`'s .wasm bytes: from dist/vendor/grammars/ in a build, else (run from
+ * src/) from src/graph/grammars/ or the grammar package in node_modules. */
+export function readDepthWasm(lang, vendorDir = VENDOR_DIR) {
+    const { module, file, built } = DEPTH_WASM[lang];
+    const vendored = join(vendorDir, file);
+    if (existsSync(vendored))
+        return readFileSync(vendored);
+    return readFileSync(built ? join(BUILT_DIR, file) : nodeRequire.resolve(`${module}/${file}`));
+}
+let forced = null;
+let readWasm = (lang) => readDepthWasm(lang);
+function backendOf(lang) {
+    return forced ?? (NATIVE_ONLY.has(lang) ? "native" : "wasm");
+}
+const loaded = new Map();
+/** Shared by every grammar and set per parse; null until the runtime is up, or
+ * after a grammar trapped mid-parse. */
+let parser = null;
+let newParser = null;
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function loadWasm(lang) {
+    try {
+        const runtime = await depthRuntime();
+        newParser = runtime.newParser;
+        return { ok: true, language: await runtime.load(readWasm(lang)) };
+    }
+    catch (err) {
+        return { ok: false, error: message(err) };
+    }
+}
+/** Load the grammars for `langs`. Await once before a synchronous parse loop.
+ * Never throws: a grammar that won't load leaves {@link depthReady} false. */
+export async function warmDepthGrammars(langs) {
+    for (const lang of new Set(langs)) {
+        if (backendOf(lang) === "wasm" && !loaded.has(lang))
+            loaded.set(lang, await loadWasm(lang));
+    }
+}
+/** True when `lang`'s grammar is loaded and can parse. Never throws. */
+export function depthReady(lang) {
+    return backendOf(lang) === "native" ? nativeReady(lang) : loaded.get(lang)?.ok === true;
+}
+/** node tree-sitter's string `parse()` fails with "Invalid argument" on any input
+ * ≥ 32 KB, which silently dropped large files, often the most important ones. The
+ * callback form has no such limit as long as each returned chunk is under 32 KB,
+ * so the source always goes in <32 KB slices, on either backend. Code-unit
+ * indexing matches `String.slice`. */
+const PARSE_CHUNK = 16384;
+/**
+ * Parse `source` as `lang` and hand the root to `use`. The tree lives only for the
+ * call: a WASM tree is freed when `use` returns, so nothing may keep a node.
+ * Throws when the grammar is unavailable: callers ask {@link depthReady} first and
+ * send the file to its breadth-tier stand-in instead.
+ */
+export function parseDepth(lang, source, use) {
+    const input = (index) => source.slice(index, index + PARSE_CHUNK);
+    if (backendOf(lang) === "native")
+        return use(nativeParser(lang).parse(input).rootNode);
+    const grammar = loaded.get(lang);
+    if (!grammar?.ok) {
+        const why = grammar ? grammar.error : "not loaded (await warmDepthGrammars first)";
+        throw new Error(`the ${lang} parser is not available: ${why}`);
+    }
+    let tree;
+    try {
+        parser ??= newParser();
+        parser.setLanguage(grammar.language);
+        tree = parser.parse(input);
+    }
+    catch (err) {
+        // A trap inside the grammar can leave the parser mid-parse: the next file
+        // gets a fresh one.
+        parser = null;
+        throw new Error(`${lang} grammar threw: ${message(err)}`);
+    }
+    if (!tree)
+        throw new Error(`the ${lang} parser returned no tree`);
+    try {
+        return use(tree.rootNode);
+    }
+    finally {
+        tree.delete();
+    }
+}
+/** The npm packages whose missing binary keeps these languages off a native
+ * parser. Only a {@link NATIVE_ONLY} language can have one: a WASM grammar has no
+ * install script for `--allow-scripts` to run. */
+export function missingDepthPackages(langs) {
+    return missingNativePackages([...langs].filter((l) => backendOf(l) === "native"));
+}
+/** Test seam: parse every depth language on `backend` (null restores the default
+ * per-language choice), and/or replace how a grammar's .wasm is read (a function
+ * that throws simulates a missing or corrupt file). Forgets every grammar loaded. */
+export function setDepthParsersForTest(opts) {
+    if (opts.backend !== undefined)
+        forced = opts.backend;
+    if (opts.readWasm !== undefined)
+        readWasm = opts.readWasm ?? ((lang) => readDepthWasm(lang));
+    loaded.clear();
+}
+//# sourceMappingURL=depth-parser.js.map

package/dist/graph/depth-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"depth-parser.js","sourceRoot":"","sources":["../../src/graph/depth-parser.ts"],"names":[],"mappings":"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"}

package/dist/graph/enrich.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Tier-2 pass: attach the LLM meaning layer (`summary` + `crux`) to nodes.
+ *
+ * graph.json is its own cache — the committed file already holds every node's
+ * summary/crux from a prior run. So this pass is diff-driven:
+ *
+ *   - cache hit  — a prior node with the same id, same `body_hash`, and
+ *     `summary_state:"ready"` → carry its summary/crux over, no LLM call.
+ *   - stale      — a prior ready summary whose body has since changed → keep the
+ *     old text as a hint but mark it "stale". Recomputed only if an LLM is given.
+ *   - pending    — new or never-summarized node → one LLM call when an LLM is
+ *     given, otherwise left "pending".
+ *
+ * Passing no summarizer runs the cache/stale bookkeeping alone (no calls, no
+ * cost) — which is what a plain `graph` build does, so it never wipes the
+ * meaning layer a previous `--llm` run produced.
+ *
+ * The LLM returns line numbers into the slice it was shown; we consume them here,
+ * once, to cut `crux.code` verbatim from the source. `crux.span` is a pointer
+ * only and is never used to re-slice.
+ */
+import { type CruxSummarizer } from "../ai/crux.js";
+import type { NodeV1 } from "./types.js";
+export interface EnrichOptions {
+    /** When present, (re)compute meaning for stale/pending nodes. Absent → cache only. */
+    summarizer?: CruxSummarizer;
+    /** Max files summarized in parallel (each is one LLM call). Default {@link DEFAULT_CONCURRENCY}. */
+    concurrency?: number;
+    /** Progress is reported per file (one LLM call each), as files finish — not per node. */
+    onProgress?: (info: {
+        index: number;
+        total: number;
+        node: string;
+    }) => void;
+    /**
+     * Durability flush of the (partially) enriched graph, called from the per-file
+     * completion handler at most once every {@link CHECKPOINT_MS}. Without it, crux
+     * only reached wiring.json at build end, so an interrupted --deep run discarded
+     * every crux it had already computed and paid for (#128). Single-threaded, so it
+     * never interleaves with a node mutation.
+     */
+    checkpoint?: () => void;
+}
+export interface EnrichStats {
+    cached: number;
+    computed: number;
+    stale: number;
+    pending: number;
+    errors: string[];
+    /** Files whose LLM call failed outright. The count `errors` used to only imply —
+     * a caller has to be able to decide "this build is degraded" without parsing
+     * message strings (#127). */
+    failedFiles: number;
+    /** Files never attempted, because {@link EnrichStats.fatal} stopped the pass. */
+    skippedFiles: number;
+    /** Set when the pass gave up early: quota/auth rejection, or a run of
+     * provider failures. Content-quality misses (#235) count in `failedFiles` but
+     * do not set this. The reason is what `graft build --deep` exits non-zero with. */
+    fatal?: string;
+}
+export declare function enrichGraph(nodes: NodeV1[], prior: Map<string, NodeV1>, sources: Map<string, string>, opts?: EnrichOptions): Promise<EnrichStats>;
+//# sourceMappingURL=enrich.d.ts.map

package/dist/graph/enrich.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrich.d.ts","sourceRoot":"","sources":["../../src/graph/enrich.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAA2D,KAAK,cAAc,EAA+B,MAAM,eAAe,CAAC;AAE1I,OAAO,KAAK,EAAQ,MAAM,EAAE,MAAM,YAAY,CAAC;AAQ/C,MAAM,WAAW,aAAa;IAC5B,sFAAsF;IACtF,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5E;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AASD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;iCAE6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC;IACrB;;uFAEmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EAAE,EACf,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,WAAW,CAAC,CAgJtB"}