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

package/dist/graph/cards.js

@@ -0,0 +1,280 @@
+/**
+ * Tier-2 "wiring cards" — the passive-channel surface of the wiring graph.
+ *
+ * The wiring graph itself lives as machine-only JSON in `graft/.graph/wiring.json`
+ * (nodes + edges), which an agent never greps or reads. This module projects its
+ * NODES up into markdown: one small card per source file, mirroring the source
+ * tree under `graft/` (e.g. `graft/src/ai/providers.md`). Each card lists the
+ * file's symbols with their `L<start>-L<end>` spans and a one-line description, so
+ * a `grep <symbol>` / `find <name>` / `cat` lands on the card and the agent reads
+ * ~150 tokens instead of the whole source file. Edges stay in the JSON — you can't
+ * grep a traversal — and are reached through `graft ask`.
+ *
+ * Cards are a pure projection: no LLM work here. The one-liner is the node's LLM
+ * `summary` when present (after `graft build --deep`), else its deterministic
+ * `signature`, so cards are useful even in a $0 structure-only build.
+ */
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { relPosix } from "../util/paths.js";
+import { matter } from "../util/front-matter.js";
+import { CACHE_DIR, readNodes } from "../context/node-file.js";
+import { GRAPH_DIR } from "./write.js";
+import { inBrand } from "../brand.js";
+const INDEX_FILE = "INDEX.md";
+/** Where a root-level file card goes when `graft/<stem>.md` is already a concept
+ * node (same stem as a slug — Laravel `server.php` vs a "Server" concept). */
+const ROOT_CARD_DIR = "_root";
+function writeIfChanged(path, content) {
+    if (existsSync(path) && readFileSync(path, "utf8") === content)
+        return;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+}
+/** True when `path` is an existing concept node (frontmatter carries `slug`). */
+function isConceptNodeFile(path) {
+    if (!existsSync(path))
+        return false;
+    try {
+        const fm = matter(readFileSync(path, "utf8")).data;
+        return fm.slug != null && String(fm.slug).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** The card path for a source path: mirror the tree, swap the extension for .md.
+ * Root-level sources share `graft/` with concept nodes. If that filename is
+ * already a concept, park the file card under `_root/` instead of clobbering it. */
+function cardPathFor(outDir, sourcePath) {
+    const md = sourcePath.replace(/\.[^./]+$/, "") + ".md";
+    const primary = join(outDir, md);
+    if (sourcePath.includes("/"))
+        return primary;
+    if (isConceptNodeFile(primary))
+        return join(outDir, ROOT_CARD_DIR, md);
+    return primary;
+}
+/** Starting line of an "L43-L55" span, for stable ordering (0 if unparseable). */
+function spanStart(span) {
+    const m = /^L(\d+)/.exec(span);
+    return m ? Number(m[1]) : 0;
+}
+/** First line of a node's meaning: LLM summary if ready, else its signature. */
+function oneLiner(node) {
+    const s = node.summary?.trim();
+    if (s)
+        return s.split("\n")[0].trim();
+    return node.signature?.trim() ?? "";
+}
+/** path → concept-node slugs that cite it as a source (for the up-links). */
+function conceptsByPath(outDir) {
+    const map = new Map();
+    for (const node of readNodes(outDir)) {
+        for (const src of node.sources) {
+            const list = map.get(src.path) ?? [];
+            list.push(node.slug);
+            map.set(src.path, list);
+        }
+    }
+    return map;
+}
+/** Render one file's card. `fileNode` may be absent for parse-only fragments. */
+function renderCard(sourcePath, fileNode, symbols, conceptSlugs) {
+    const uplinks = conceptSlugs
+        .sort()
+        .map((s) => `[[${s}]]`)
+        .join(" ");
+    const head = uplinks ? `# ${sourcePath} · ${uplinks}` : `# ${sourcePath}`;
+    const lines = [head, ""];
+    const fileSummary = fileNode ? oneLiner(fileNode) : "";
+    if (fileSummary)
+        lines.push(fileSummary, "");
+    const sorted = [...symbols].sort((a, b) => spanStart(a.span) - spanStart(b.span) || a.name.localeCompare(b.name));
+    for (const n of sorted) {
+        const desc = oneLiner(n);
+        const tail = desc ? ` — ${desc}` : "";
+        lines.push(`- ${n.name} · ${n.kind} · ${n.span}${tail}`);
+    }
+    if (sorted.length === 0)
+        lines.push("_No extracted symbols in this file._");
+    return lines.join("\n") + "\n";
+}
+/** Every existing card file (`.md` inside subdirs of outDir; not concept nodes). */
+function listExistingCards(outDir) {
+    const out = [];
+    const walk = (dir) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            if (e.isDirectory()) {
+                if (dir === outDir && (e.name === CACHE_DIR || e.name === GRAPH_DIR))
+                    continue;
+                walk(join(dir, e.name));
+            }
+            else if (e.isFile() && e.name.endsWith(".md")) {
+                out.push(join(dir, e.name));
+            }
+        }
+    };
+    for (const e of readdirSync(outDir, { withFileTypes: true })) {
+        // Concept nodes and INDEX.md are top-level files — skip. Cards live in
+        // subdirs (`src/…`, and `_root/` when a root card would collide with a concept).
+        if (e.isDirectory() && e.name !== CACHE_DIR && e.name !== GRAPH_DIR) {
+            walk(join(outDir, e.name));
+        }
+    }
+    return out;
+}
+/** Remove now-empty directories under outDir (bottom-up), skipping .cache/.graph. */
+function pruneEmptyDirs(outDir) {
+    const visit = (dir) => {
+        // returns true if dir is empty after visiting children
+        let empty = true;
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            if (dir === outDir && (e.name === CACHE_DIR || e.name === GRAPH_DIR)) {
+                empty = false;
+                continue;
+            }
+            const child = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (visit(child))
+                    rmSync(child, { recursive: true, force: true });
+                else
+                    empty = false;
+            }
+            else {
+                empty = false;
+            }
+        }
+        return empty;
+    };
+    if (existsSync(outDir))
+        visit(outDir);
+}
+/**
+ * Write one wiring card per source file into `outDir`, mirroring the source tree,
+ * and prune cards whose source no longer exists. Returns what changed.
+ */
+export function writeCards(graph, outDir) {
+    const byPath = new Map();
+    for (const n of graph.nodes) {
+        const list = byPath.get(n.path) ?? [];
+        list.push(n);
+        byPath.set(n.path, list);
+    }
+    const concepts = conceptsByPath(outDir);
+    const written = new Set();
+    const files = [];
+    for (const [sourcePath, group] of byPath) {
+        const fileNode = group.find((n) => n.kind === "file");
+        const symbols = group.filter((n) => n.kind !== "file");
+        const cardPath = cardPathFor(outDir, sourcePath);
+        writeIfChanged(cardPath, renderCard(sourcePath, fileNode, symbols, concepts.get(sourcePath) ?? []));
+        written.add(cardPath);
+        files.push({ card: relPosix(outDir, cardPath), path: sourcePath, symbols: symbols.length });
+    }
+    let pruned = 0;
+    for (const existing of listExistingCards(outDir)) {
+        if (!written.has(existing)) {
+            rmSync(existing);
+            pruned++;
+        }
+    }
+    pruneEmptyDirs(outDir);
+    files.sort((a, b) => a.card.localeCompare(b.card));
+    return { written: written.size, pruned, files };
+}
+/**
+ * Write `graft/INDEX.md` — the roster an agent `cat`s to orient. Lists the concept
+ * nodes on disk and the per-file cards. Deterministic order; no timestamps.
+ */
+export function writeIndex(outDir, files) {
+    // Spelled by the name that built it: a trail-only machine has no `graft` to run.
+    const lines = [
+        "# graft — repo map",
+        "",
+        "Small markdown nodes summarising this repo. `grep` any term, symbol, or",
+        'filename here, or run `graft ask "<task>"`. Each node carries prose plus exact',
+        "`file:line`; open a source file only to edit the named span.",
+        "",
+        // Whoever reads this file has already decided to look at graft, so this is the
+        // one place a pointer to the richer surface is welcome rather than noise. Stated
+        // as what exists, not as an instruction — see `mcp/instructions.ts` for why.
+        "The same graph is queryable as MCP tools (`graft_find_code`, `graft_find_all`,",
+        "`graft_trace_calls`, `graft_file_api`, `graft_repo_map`) where a host exposes them, and",
+        "as the `graft` CLI everywhere else. Edges — who calls what — live only in the",
+        "graph, not in these files: `graft callers <symbol>` is the only way to read them.",
+        "",
+    ].map((l) => inBrand(l));
+    const concepts = readNodes(outDir).sort((a, b) => a.slug.localeCompare(b.slug));
+    if (concepts.length) {
+        lines.push("## Concepts", "");
+        for (const c of concepts) {
+            const srcs = c.sources.map((s) => s.path).join(", ");
+            const tail = srcs ? ` · ${srcs}` : "";
+            lines.push(`- [${c.slug}](${c.slug}.md) — ${c.name || c.slug}${tail}`);
+        }
+        lines.push("");
+    }
+    if (files.length) {
+        const withSymbols = files.filter((f) => f.symbols > 0).length;
+        lines.push("## Files", "");
+        lines.push(`${files.length} per-file wiring cards mirror the source tree under \`graft/\` ` +
+            `(${withSymbols} carry extracted symbols). They are deliberately not enumerated here —`, "`grep` a symbol or `find`/`ls` a filename under `graft/` to land on the card for that file.", "");
+    }
+    writeIfChanged(join(outDir, INDEX_FILE), lines.join("\n"));
+}
+/**
+ * Backfill each concept node's frontmatter with a `covers:` list — the symbols
+ * (and their exact `file:line`) it spans, read from the wiring graph. This is the
+ * explicit OKF↔Wiring link: it doubles as grep bait (a `grep <symbol>` lands on
+ * the prose node, not just its card) and lets an agent read the span straight
+ * from the node without ever opening `wiring.json`.
+ *
+ * A surgical frontmatter patch: the generated body and every other key are
+ * preserved verbatim; only `covers` is added/replaced. Concept nodes are the
+ * top-level `.md` files that carry a `slug` (cards live in subdirs, or at the
+ * top level without a slug when they mirror a root source; INDEX.md is skipped).
+ * On a $0 structure-only build there are no concept nodes, so this is a no-op.
+ * Returns the number of nodes enriched.
+ */
+export function writeCovers(graph, outDir) {
+    if (!existsSync(outDir))
+        return 0;
+    const symbolsByPath = new Map();
+    for (const n of graph.nodes) {
+        if (n.kind === "file")
+            continue;
+        const list = symbolsByPath.get(n.path) ?? [];
+        list.push(n);
+        symbolsByPath.set(n.path, list);
+    }
+    for (const list of symbolsByPath.values()) {
+        list.sort((a, b) => spanStart(a.span) - spanStart(b.span) || a.name.localeCompare(b.name));
+    }
+    let enriched = 0;
+    for (const entry of readdirSync(outDir)) {
+        if (!entry.endsWith(".md") || entry === INDEX_FILE)
+            continue;
+        const full = join(outDir, entry);
+        const parsed = matter(readFileSync(full, "utf8"));
+        // Root-level file cards have no concept slug; stamping `covers: []` onto
+        // them made readNodes treat them as concept nodes (#261).
+        if (parsed.data.slug == null || String(parsed.data.slug).length === 0)
+            continue;
+        const sources = Array.isArray(parsed.data.sources)
+            ? parsed.data.sources
+            : [];
+        const covers = [];
+        for (const path of [...new Set(sources.map((s) => s.path ?? ""))].sort()) {
+            for (const n of symbolsByPath.get(path) ?? []) {
+                covers.push({ symbol: n.name, kind: n.kind, at: `${n.path}:${n.span}` });
+            }
+        }
+        // Re-stringify with covers appended last, so re-runs produce a stable diff.
+        const { covers: _prev, ...rest } = parsed.data;
+        writeIfChanged(full, matter.stringify(parsed.content, { ...rest, covers }));
+        enriched++;
+    }
+    return enriched;
+}
+//# sourceMappingURL=cards.js.map

package/dist/graph/cards.js.map

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

package/dist/graph/check.d.ts

@@ -0,0 +1,25 @@
+export interface GraphCheckResult {
+    ok: boolean;
+    /** True when there is no graph.json (a graph has never been built). */
+    missing: boolean;
+    added: string[];
+    removed: string[];
+    changed: string[];
+    stale: string[];
+    /** Nodes never summarized (reported for context; not counted as drift). */
+    pending: number;
+    /** Ids of pending nodes (capped when formatting) — so a stuck meaning pass
+     * names the files instead of only saying "run --deep" (#172). */
+    pendingIds: string[];
+    /** Committed nodes in total — the denominator that turns `pending` into a
+     * coverage figure. A deep build that lost most of its LLM calls (#127) is only
+     * distinguishable from a deliberate Tier-1 build by the SHARE that is missing. */
+    nodes: number;
+}
+export interface GraphCheckOptions {
+    contextDir?: string;
+}
+export declare function checkGraph(dir: string, opts?: GraphCheckOptions): Promise<GraphCheckResult>;
+/** Render a graph-check result as a human-readable report. */
+export declare function formatGraphCheckReport(r: GraphCheckResult): string;
+//# sourceMappingURL=check.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/graph/check.ts"],"names":[],"mappings":"AA+BA,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB;qEACiE;IACjE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;sFAEkF;IAClF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAiG3B;AAED,8DAA8D;AAC9D,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAkClE"}

package/dist/graph/check.js

@@ -0,0 +1,192 @@
+/**
+ * `checkGraph` — is the committed `graph.json` still in sync with the code?
+ *
+ * Deterministic and fast (tree-sitter only, no LLM, no network): it re-runs
+ * Tier-1 extraction and diffs the fresh node set against the committed graph by
+ * `id` and `body_hash`. Meant for CI — exit non-zero when a PR changed code but
+ * didn't rebuild the graph.
+ *
+ * Drift categories:
+ *   added    a definition exists in code but not in graph.json (run `graph`)
+ *   removed  a node in graph.json no longer exists in code       (run `graph`)
+ *   changed  a node's body_hash differs from the committed one   (run `graph`)
+ *   stale    a committed node's summary is flagged stale — its body changed
+ *            since it was last summarized                         (run `graft build --deep`)
+ *
+ * `added`/`removed`/`changed` are structural: the graph no longer describes the
+ * code. `stale` is a meaning-layer signal the last build already recorded.
+ * `pending` (never summarized) is not drift — it's a deliberate Tier-1-only build.
+ */
+import { resolve } from "node:path";
+import { relPosix } from "../util/paths.js";
+import { contextDirFor } from "../context/node-file.js";
+import { extractFile } from "./extract.js";
+import { extractGeneric } from "./generic.js";
+import { extractContainer } from "./container.js";
+import { listSourceFiles, tierOf, warmGrammarsFor } from "./build.js";
+import { readGraph, wiringPath } from "./write.js";
+import { readFingerprint } from "./fingerprint.js";
+import { readSourceFile } from "../util/source.js";
+import { cmd } from "../brand.js";
+// async: the breadth tier's WASM grammars load asynchronously and must be warmed
+// before the (synchronous) re-extraction below, exactly as buildGraph does — else
+// breadth-tier files (.rs, …) would re-extract as empty here and read as `removed`
+// against a graph that built them, so `graft check` would never report OK.
+export async function checkGraph(dir, opts = {}) {
+    const root = resolve(dir);
+    const outDir = contextDirFor(root, opts.contextDir);
+    const result = {
+        ok: false,
+        missing: false,
+        added: [],
+        removed: [],
+        changed: [],
+        stale: [],
+        pending: 0,
+        pendingIds: [],
+        nodes: 0,
+    };
+    const committed = readGraph(wiringPath(outDir));
+    if (!committed) {
+        result.missing = true;
+        return result;
+    }
+    // Freshly extract Tier-1 nodes from the code on disk (same file set as build).
+    // A `--only-dir` build records its whitelist in the fingerprint; read it back
+    // so `check` diffs the same limited set instead of flagging every excluded
+    // file as "added".
+    const fpOnlyDirs = readFingerprint(outDir)?.onlyDirs;
+    const onlyDirs = fpOnlyDirs && fpOnlyDirs.length > 0 ? new Set(fpOnlyDirs) : undefined;
+    const sourceFiles = listSourceFiles(root, outDir, undefined, onlyDirs);
+    // Container-tier grammars need the same warmup as the generic ones, for the same
+    // reason: extraction below is synchronous. Missing that is what made `graft
+    // check` report every `.vue` node as `removed` right after a clean build (#236)
+    // — the tier extracted fine, and then the check had no branch that could see it.
+    // The same call warms the WASM stand-in for a depth language whose native
+    // grammar didn't load, exactly as the build does.
+    await warmGrammarsFor(sourceFiles);
+    const current = new Map(); // id → body_hash
+    for (const file of sourceFiles) {
+        // The same dispatch `buildGraph` uses (`tierOf`). The two must stay in step: a
+        // tier the build extracts and the check cannot see reports as `removed`
+        // forever, and the `graft build` the check tells you to run can never repair it.
+        const { lang, container, generic } = tierOf(file);
+        let source;
+        try {
+            source = readSourceFile(file);
+        }
+        catch {
+            continue; // unreadable now → its nodes show up as `removed` below
+        }
+        if (source === null)
+            continue; // unsupported encoding (e.g. UTF-16BE)
+        const rel = relPosix(root, file);
+        try {
+            const extracted = lang
+                ? extractFile(rel, source, lang)
+                : container
+                    ? extractContainer(rel, source, container)
+                    : generic
+                        ? extractGeneric(rel, source, generic.name)
+                        : null;
+            // No tier claims this file. Spelled out rather than asserted away: the
+            // `generic!` that used to stand in this position threw a TypeError on a
+            // container-tier file, the catch below swallowed it as a parse failure, and
+            // a missing branch became a silent permanent `removed` (#236). Returning
+            // null here means the next tier graft gains fails loudly in the type
+            // checker instead.
+            if (extracted === null)
+                continue;
+            for (const n of extracted.nodes)
+                current.set(n.id, n.body_hash);
+        }
+        catch {
+            // parse failure → skip; the committed nodes for this file become `removed`.
+        }
+    }
+    const committedById = new Map(committed.nodes.map((n) => [n.id, n]));
+    result.nodes = committedById.size;
+    for (const [id, node] of committedById) {
+        const now = current.get(id);
+        if (now === undefined)
+            result.removed.push(id);
+        else if (now !== node.body_hash)
+            result.changed.push(id);
+        if (node.summary_state === "stale")
+            result.stale.push(id);
+        if (node.summary_state === "pending") {
+            result.pending++;
+            result.pendingIds.push(id);
+        }
+    }
+    for (const id of current.keys()) {
+        if (!committedById.has(id))
+            result.added.push(id);
+    }
+    for (const arr of [result.added, result.removed, result.changed, result.stale, result.pendingIds]) {
+        arr.sort();
+    }
+    result.ok =
+        result.added.length === 0 &&
+            result.removed.length === 0 &&
+            result.changed.length === 0 &&
+            result.stale.length === 0;
+    return result;
+}
+/** Render a graph-check result as a human-readable report. */
+export function formatGraphCheckReport(r) {
+    if (r.missing) {
+        return `graph check: NO GRAPH\n\nNo graft/.graph/wiring.json found. Run \`${cmd("graft build")}\` first.`;
+    }
+    if (r.ok) {
+        // A share, not a bare count: "1203 not yet summarized" reads the same whether
+        // the repo was never deep-built or a deep build failed most of its calls.
+        const pct = r.nodes > 0 ? Math.round(((r.nodes - r.pending) / r.nodes) * 100) : 0;
+        const note = r.pending ? ` (${formatPendingNote(r, pct)})` : "";
+        return `graph check: OK — the wiring graph is in sync with the code.${note}`;
+    }
+    const lines = ["graph check: STALE", ""];
+    const structural = r.added.length + r.removed.length + r.changed.length;
+    if (r.changed.length) {
+        lines.push(`changed (${r.changed.length}):`);
+        for (const id of r.changed)
+            lines.push(`  ~ ${id}`);
+    }
+    if (r.added.length) {
+        lines.push(`added (${r.added.length}):`);
+        for (const id of r.added)
+            lines.push(`  + ${id}`);
+    }
+    if (r.removed.length) {
+        lines.push(`removed (${r.removed.length}):`);
+        for (const id of r.removed)
+            lines.push(`  - ${id}`);
+    }
+    if (r.stale.length) {
+        lines.push(`stale summaries (${r.stale.length}):`);
+        for (const id of r.stale)
+            lines.push(`  ! ${id}`);
+    }
+    lines.push("");
+    if (structural)
+        lines.push(`Run \`${cmd("graft build")}\` to rebuild the structure, then commit graft/.`);
+    if (r.stale.length)
+        lines.push(`Run \`${cmd("graft build --deep")}\` to refresh stale summaries.`);
+    return lines.join("\n");
+}
+/** Cap how many pending ids the OK-note lists so a large Tier-1 graph stays readable. */
+const PENDING_SAMPLE = 8;
+function formatPendingNote(r, pct) {
+    const ids = r.pendingIds ?? [];
+    const sample = ids.slice(0, PENDING_SAMPLE);
+    const more = ids.length > PENDING_SAMPLE ? `, … +${ids.length - PENDING_SAMPLE} more` : "";
+    const named = sample.length ? `: ${sample.join(", ")}${more}` : "";
+    // Tier-1-only builds are supposed to leave everything pending — "run --deep"
+    // is the right next step. A deep build that still left them pending used to
+    // dead-end here (#172): re-running the same command never cleared empty/failed
+    // meaning replies, so name the nodes and point at the last build's errors.
+    return (`meaning tier ${pct}% complete — ${r.pending} of ${r.nodes} node(s) pending${named}. ` +
+        `Run \`${cmd("graft build --deep")}\` to summarize them; if a deep build already left these pending, ` +
+        `that meaning pass failed — see that build's errors (re-running alone will not clear them)`);
+}
+//# sourceMappingURL=check.js.map

package/dist/graph/check.js.map

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

package/dist/graph/container.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 { type ExtractResult, type Language } from "./extract.js";
+/** A container language: the wrapper grammar, the node that holds the embedded
+ * source, and which depth-tier extractor to hand that source to. */
+export interface ContainerLang {
+    name: string;
+    exts: string[];
+    /** wasm basename in tree-sitter-wasms/out/tree-sitter-<wasm>.wasm */
+    wasm: string;
+    /** Wrapper node that represents one embedded block (e.g. Vue's script_element). */
+    block: string;
+    /** Child of `block` holding the raw embedded source (e.g. Vue's raw_text). */
+    body: string;
+    /** Depth-tier grammar for the embedded language. TypeScript is a superset of
+     * JavaScript, so it parses both `<script>` and `<script lang="ts">`. */
+    inner: Language;
+}
+/** 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 declare const CONTAINER_LANGS: readonly ContainerLang[];
+/** The container language for a path, or null if none claims it. */
+export declare function containerLangOf(path: string): ContainerLang | null;
+/** Every file extension the container tier claims. */
+export declare function containerExtensions(): string[];
+/** 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 declare function warmContainerGrammars(langNames: Iterable<string>): Promise<void>;
+/** True if a container grammar has been warmed (else extraction is file-only). */
+export declare function isContainerWarm(langName: string): boolean;
+/**
+ * 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 declare function extractContainer(rel: string, source: string, lang: ContainerLang): ExtractResult;
+//# sourceMappingURL=container.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../src/graph/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAuB,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAgB,MAAM,cAAc,CAAC;AAMpG;oEACoE;AACpE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb;4EACwE;IACxE,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED;;gFAEgF;AAChF,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAEnD,CAAC;AAKF,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAIlE;AAED,sDAAsD;AACtD,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C;AAID;;;wFAGwF;AACxF,wBAAsB,qBAAqB,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAStF;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AA0DD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,aAAa,CA6DhG"}