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

package/dist/viz/export.js

@@ -0,0 +1,98 @@
+/**
+ * `graft viz --export <dir>`: the same viewer, as one self-contained HTML file.
+ *
+ * This exists so a PR comment has somewhere real to point. A Mermaid diagram in a
+ * comment can hold about five circles before it stops being readable, and it can
+ * never hold the thing a reviewer actually wants next — click an area, see its
+ * dependent symbols at exact `file:line`. Every other tool in this space solved
+ * that the same way: keep a small table in the comment and link out to a hosted
+ * view. Exporting rather than hosting keeps graft's promise intact — no account, no
+ * server, no telemetry; the artifact is a file you can open with `file://`, publish
+ * to GitHub Pages, or attach to a build.
+ *
+ * The output inlines the CSS, the bundled JS and both graphs, because a file served
+ * from a Pages subdirectory cannot rely on absolute asset paths (`/app.js` resolves
+ * to the domain root, not the PR's folder) and a reader must not need a web server.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { assembleContextGraph } from "./assemble.js";
+/** The wiring graph as the viewer's endpoint would have served it, or null. */
+function codeGraph(contextDir) {
+    const file = join(contextDir, ".graph", "wiring.json");
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return parsed?.meta?.version === 1 ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * JSON safe to drop inside a `<script>` element.
+ *
+ * `</script>` anywhere in the data — a summary quoting HTML, a symbol named after a
+ * tag — would close the element and spill the rest of the graph into the page as
+ * text. `<` is escaped as a unicode sequence, which is still valid JSON to the
+ * parser and inert to the HTML tokenizer.
+ */
+function inlineJson(value) {
+    return JSON.stringify(value ?? null)
+        .replace(/</g, "\\u003c")
+        // Line and paragraph separators are legal in a JSON string and illegal in a
+        // JavaScript source line, so an unescaped one is a syntax error at load time.
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}
+/** The two tags this exporter rewrites, verbatim from viewer/index.html. */
+const LINK_TAG = '<link rel="stylesheet" href="/style.css">';
+const SCRIPT_TAG = '<script type="module" src="/app.js"></script>';
+export function exportViz(opts) {
+    const html = readFileSync(join(opts.viewerDir, "index.html"), "utf8");
+    // Checked on the SOURCE, before anything is inlined. Checking the assembled page
+    // instead looks equivalent and is not: a stylesheet comment or a bundled string
+    // containing one of these tags would fail an export that was in fact correct.
+    if (!html.includes(LINK_TAG) || !html.includes(SCRIPT_TAG)) {
+        throw new Error("viz export: viewer/index.html no longer matches the asset tags this exporter rewrites");
+    }
+    const css = readFileSync(join(opts.viewerDir, "style.css"), "utf8");
+    const js = readFileSync(join(opts.viewerDir, "app.js"), "utf8");
+    const context = opts.contextGraph ?? assembleContextGraph(opts.contextDir);
+    const tabs = opts.tabs ?? ["context", "code", "outline"];
+    // Both remaining tabs read the wiring graph, so dropping them drops the payload
+    // as well — the point of the option, not a side effect of it.
+    const wanted = tabs.includes("code") || tabs.includes("outline");
+    const code = wanted ? codeGraph(opts.contextDir) : null;
+    // Which tab to open on. The viewer starts on Context, which only a `--deep` build
+    // fills: a structural build writes wiring cards (no frontmatter, so nothing to
+    // assemble) and INDEX.md, and INDEX alone assembles to a single node. Since the
+    // PR path is now structural by design, opening on Context would show a canvas
+    // with one dot while the whole wiring graph sat behind an unadvertised tab.
+    const codeNodes = code?.nodes?.length ?? 0;
+    // A supplied graph is the caller's whole point, so it is always the landing tab.
+    const defaultTab = opts.contextGraph || context.nodes.length > 1 || codeNodes === 0 ? "context" : "code";
+    const contextGraph = {
+        ...context,
+        meta: { ...context.meta, repoName: opts.repoName, subtitle: opts.subtitle, defaultTab, tabs },
+    };
+    const data = [
+        "<script>window.__GRAFT_DATA__ = {",
+        `  contextGraph: ${inlineJson(contextGraph)},`,
+        `  codeGraph: ${inlineJson(code)}`,
+        "};</script>",
+    ].join("\n");
+    // Replacer FUNCTIONS, not replacement strings: `$&`, `$\'` and friends are
+    // substitution patterns inside a replacement string, and a minified bundle is
+    // full of them — the first version of this put the original `<script src>` tag
+    // back into the page via a stray `$&` in app.js. A function is taken verbatim.
+    const page = html
+        .replace(LINK_TAG, () => `<style>\n${css}\n</style>`)
+        .replace(SCRIPT_TAG, () => `${data}\n<script type="module">\n${js}\n</script>`);
+    mkdirSync(opts.outDir, { recursive: true });
+    const file = join(opts.outDir, "index.html");
+    writeFileSync(file, page);
+    return { file, bytes: Buffer.byteLength(page), contextNodes: contextGraph.nodes.length, codeNodes, defaultTab, tabs };
+}
+//# sourceMappingURL=export.js.map

package/dist/viz/export.js.map

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

package/dist/viz/serve.d.ts

@@ -0,0 +1,13 @@
+export interface VizServerOptions {
+    contextDir: string;
+    viewerDir: string;
+    port: number;
+    repoName: string;
+    wiringOverride?: string;
+}
+export interface VizServer {
+    url: string;
+    close(): Promise<void>;
+}
+export declare function startVizServer(opts: VizServerOptions): Promise<VizServer>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/viz/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/viz/serve.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA+BD,wBAAsB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CA4F/E"}

package/dist/viz/serve.js

@@ -0,0 +1,130 @@
+/**
+ * The `graft viz` local server. Zero runtime dependencies: node:http serves
+ * the prebuilt viewer bundle, two JSON endpoints, and an SSE channel that
+ * pings the browser whenever the context dir changes on disk.
+ *
+ *   GET /                  viewer (index.html, app.js, style.css from viewerDir)
+ *   GET /api/context-graph assembled from .context/*.md on every request
+ *   GET /api/code-graph    .context/graph.json passthrough (404 until generated)
+ *   GET /events            SSE; fs.watch on the context dir, debounced 300ms
+ */
+import { createServer } from "node:http";
+import { readFileSync, existsSync, watch } from "node:fs";
+import { join } from "node:path";
+import { assembleContextGraph } from "./assemble.js";
+import { cmd } from "../brand.js";
+const PORT_ATTEMPTS = 10;
+const WATCH_DEBOUNCE_MS = 300;
+const STATIC_FILES = {
+    "/": { file: "index.html", type: "text/html; charset=utf-8" },
+    "/index.html": { file: "index.html", type: "text/html; charset=utf-8" },
+    "/app.js": { file: "app.js", type: "text/javascript; charset=utf-8" },
+    "/style.css": { file: "style.css", type: "text/css; charset=utf-8" },
+};
+function sendJson(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify(body));
+}
+function listen(server, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            if (err.code === "EADDRINUSE")
+                resolve(false);
+            else
+                reject(err);
+        };
+        server.once("error", onError);
+        server.listen(port, "127.0.0.1", () => {
+            server.removeListener("error", onError);
+            resolve(true);
+        });
+    });
+}
+export async function startVizServer(opts) {
+    const sseClients = new Set();
+    const server = createServer((req, res) => {
+        const path = (req.url ?? "/").split("?")[0];
+        const asset = STATIC_FILES[path];
+        if (asset) {
+            const file = join(opts.viewerDir, asset.file);
+            if (!existsSync(file)) {
+                res.writeHead(404, { "content-type": "text/plain" });
+                res.end("viewer bundle missing — run the package build");
+                return;
+            }
+            res.writeHead(200, { "content-type": asset.type });
+            res.end(readFileSync(file));
+            return;
+        }
+        if (path === "/api/context-graph") {
+            const graph = assembleContextGraph(opts.contextDir);
+            sendJson(res, 200, { ...graph, meta: { ...graph.meta, repoName: opts.repoName } });
+            return;
+        }
+        if (path === "/api/code-graph") {
+            const file = join(opts.contextDir, ".graph", "wiring.json");
+            const wiringFile = opts.wiringOverride ?? file;
+            if (!existsSync(file)) {
+                sendJson(res, 404, { error: `no wiring graph in this context dir — run \`${cmd("graft build")}\` first` });
+                return;
+            }
+            try {
+                const parsed = JSON.parse(readFileSync(wiringFile, "utf8"));
+                if (parsed?.meta?.version !== 1) {
+                    sendJson(res, 404, { error: `wiring.json has an unsupported version — regenerate with \`${cmd("graft build")}\`` });
+                    return;
+                }
+                sendJson(res, 200, parsed);
+            }
+            catch {
+                sendJson(res, 404, { error: `wiring.json is unreadable — regenerate with \`${cmd("graft build")}\`` });
+            }
+            return;
+        }
+        if (path === "/events") {
+            res.writeHead(200, {
+                "content-type": "text/event-stream",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+            });
+            res.write(": connected\n\n");
+            sseClients.add(res);
+            req.on("close", () => sseClients.delete(res));
+            return;
+        }
+        res.writeHead(404, { "content-type": "text/plain" });
+        res.end("not found");
+    });
+    let port = opts.port;
+    let bound = false;
+    for (let i = 0; i < PORT_ATTEMPTS && !bound; i++) {
+        port = opts.port + i;
+        bound = await listen(server, port);
+    }
+    if (!bound) {
+        throw new Error(`no free port in ${opts.port}–${opts.port + PORT_ATTEMPTS - 1}`);
+    }
+    let watcher;
+    let debounce;
+    if (existsSync(opts.contextDir)) {
+        watcher = watch(opts.contextDir, () => {
+            clearTimeout(debounce);
+            debounce = setTimeout(() => {
+                for (const client of sseClients)
+                    client.write("data: change\n\n");
+            }, WATCH_DEBOUNCE_MS);
+        });
+    }
+    return {
+        url: `http://127.0.0.1:${port}`,
+        close() {
+            clearTimeout(debounce);
+            watcher?.close();
+            for (const client of sseClients)
+                client.end();
+            sseClients.clear();
+            return new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
+        },
+    };
+}
+//# sourceMappingURL=serve.js.map

package/dist/viz/serve.js.map

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

package/package.json

@@ -1,6 +1,117 @@
 {
   "name": "trail-code",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.28.0-semantic.3",
+  "description": "Build a repo's context graph as a folder of linked markdown files: a local, regenerable cache that every query keeps in sync with your code. (fork of @trailhq/trail-code: semantic search, --include-md, knowledge repos)",
+  "keywords": [
+    "ai",
+    "agents",
+    "knowledge-graph",
+    "context",
+    "codebase",
+    "llm",
+    "graft"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jastorgalj/Trail-Code.git"
+  },
+  "homepage": "https://github.com/jastorgalj/Trail-Code#readme",
+  "bugs": {
+    "url": "https://github.com/jastorgalj/Trail-Code/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "graft": "dist/bin/graft.js",
+    "trail": "dist/bin/trail.js"
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p viewer/tsconfig.json && node scripts/build-viewer.mjs && node scripts/vendor-grammars.mjs",
+    "dev": "tsc -p tsconfig.json --watch",
+    "cli": "tsx src/cli.ts",
+    "test": "node scripts/run-tests.mjs",
+    "prepare": "npm run build && node scripts/stamp-telemetry-key.mjs",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "engines": {
+    "node": "^20.16.0 || >=22.3.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.133.0",
+    "@huggingface/transformers": "^3.0.0",
+    "better-sqlite3": "^13.0.3",
+    "sqlite-vec": "^0.1.9",
+    "commander": "^15.0.0",
+    "dotenv": "^18.0.7",
+    "gray-matter": "^4.0.3",
+    "openai": "^7.8.0",
+    "tree-sitter-wasm": "^2.0.4",
+    "vscode-jsonrpc": "^8.2.1",
+    "vscode-languageserver-protocol": "^3.18.2",
+    "web-tree-sitter": "^0.27.1",
+    "web-tree-sitter-depth": "npm:web-tree-sitter@0.22.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/d3-force": "^3.0.10",
+    "@types/node": "^26.1.0",
+    "d3-force": "^3.0.0",
+    "esbuild": "^0.28.1",
+    "node-gyp": "^12.4.0",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-go": "^0.23.4",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-kotlin": "^0.3.8",
+    "tree-sitter-php": "^0.23.4",
+    "tree-sitter-python": "^0.21.0",
+    "tree-sitter-r": "npm:@davisvaughan/tree-sitter-r@^1.3.0",
+    "tree-sitter-swift": "^0.7.1",
+    "tree-sitter-typescript": "^0.23.2",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  },
+  "allowScripts": {
+    "tree-sitter@0.21.1": true,
+    "tree-sitter-typescript@0.23.2": true,
+    "tree-sitter-python@0.21.0": true,
+    "tree-sitter-go@0.23.4": true,
+    "tree-sitter-javascript@0.23.1": true,
+    "tree-sitter-java@0.23.5": true,
+    "esbuild@0.28.2": true,
+    "fsevents@2.3.3": true,
+    "tree-sitter-kotlin@0.3.8": true,
+    "tree-sitter-php@0.23.12": true,
+    "@davisvaughan/tree-sitter-r@1.3.0": true,
+    "tree-sitter-swift@0.7.1": true,
+    "onnxruntime-node": true,
+    "protobufjs": true,
+    "better-sqlite3": true
+  },
+  "overrides": {
+    "tree-sitter-swift": {
+      "tree-sitter": "$tree-sitter"
+    },
+    "js-yaml": {
+      "argparse": "^2.0.1"
+    }
+  }
+}

package/scripts/build-grammar-wasm.mjs

@@ -0,0 +1,112 @@
+/**
+ * Compiles the depth-tier grammars whose npm package ships no .wasm into
+ * src/graph/grammars/, and records every depth grammar's .wasm in grammars.json.
+ *
+ * The depth tier parses on web-tree-sitter (src/graph/depth-parser.ts) with the
+ * exact grammar versions the native addons were built from. Most of those packages
+ * ship a .wasm next to the addon; python, kotlin and swift don't, so this builds
+ * theirs from the package's own src/ (parser.c and scanner.c, never regenerated
+ * from grammar.js) with the tree-sitter CLI. The output is committed, so a build
+ * needs no compiler: `npm run build` only copies it (scripts/vendor-grammars.mjs).
+ *
+ * swift's scanner relies on behaviour wasm32 doesn't share with the native addon,
+ * so its copy is patched first (PATCHES, below). Without the patches its parses
+ * go wrong after the first file.
+ *
+ * grammars.json pins the bytes test/depth-parity.ts last passed with: for each
+ * .wasm, the package version and the file's sha256 (and for a built one, the hash
+ * of the C it was built from). test/depth-grammars.test.ts fails when any of that
+ * drifts, so bumping a grammar package means running this, then the parity check
+ * against real repos.
+ *
+ * The build is reproducible: the same package and CLI give the same bytes. The CLI
+ * fetches wasi-sdk on first use (about 600 MB under ~/.cache/tree-sitter).
+ *
+ * Usage: node scripts/build-grammar-wasm.mjs            build all three, record all
+ *        node scripts/build-grammar-wasm.mjs --record   record only, build nothing
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { GRAMMARS } from "./vendor-grammars.mjs";
+
+/** The tree-sitter CLI that compiles them. */
+const CLI = "0.27.1";
+
+/** Source edits applied to the copy that is compiled, never to node_modules:
+ * [file under src/, exact text, replacement]. */
+export const PATCHES = {
+  "tree-sitter-swift": [
+    // The `!` operator's suppressor mask is bit 32 of a uint64_t; wasm32's
+    // `unsigned long` is 32 bits.
+    ["scanner.c", "1UL << FAKE_TRY_BANG", "1ULL << FAKE_TRY_BANG"],
+    // The mask is tested with `1 << suppressor`, an int shift past bit 31. The
+    // native addon is built at -O3, where that undefined shift vectorizes into a
+    // test that passes for every index: the addon drops the scanner's `!` whenever
+    // any symbol is valid, which is always, since `!` itself is. So `x!.y` parses
+    // its `!` with the grammar's own lexer. Dropping the test reproduces that.
+    ["scanner.c", "if (!(suppressing_symbols & 1 << suppressor)) {", "if (0) {"],
+    // calloc(0, …) may return NULL in wasm, and the scanner then keeps its state at
+    // address 0, where other writes clobber it.
+    ["scanner.c", "calloc(0, sizeof(struct ScannerState))", "calloc(1, sizeof(struct ScannerState))"],
+  ],
+};
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const builtDir = join(root, "src", "graph", "grammars");
+const require = createRequire(join(root, "package.json"));
+
+/** sha256 over a grammar's C sources as published, the part the .wasm is made of. */
+export function sourceHash(pkgDir) {
+  const h = createHash("sha256");
+  for (const f of ["parser.c", "scanner.c"]) {
+    const p = join(pkgDir, "src", f);
+    if (existsSync(p)) h.update(f).update(readFileSync(p));
+  }
+  return h.digest("hex");
+}
+
+export const sha256 = (path) => createHash("sha256").update(readFileSync(path)).digest("hex");
+
+function compile(module, pkg, file) {
+  // A copy, so neither the patches nor the CLI's build files touch node_modules.
+  const work = join(root, "node_modules", ".cache", "grammar-wasm", module);
+  rmSync(work, { recursive: true, force: true });
+  mkdirSync(work, { recursive: true });
+  for (const f of ["src", "grammar.js", "package.json", "tree-sitter.json"]) {
+    if (existsSync(join(pkg, f))) cpSync(join(pkg, f), join(work, f), { recursive: true });
+  }
+  for (const [name, from, to] of PATCHES[module] ?? []) {
+    const p = join(work, "src", name);
+    const text = readFileSync(p, "utf8");
+    if (!text.includes(from)) throw new Error(`${module}: patch target not found in src/${name}: ${from}`);
+    writeFileSync(p, text.replace(from, to));
+  }
+  execFileSync("npx", ["--yes", `tree-sitter-cli@${CLI}`, "build", "--wasm", "-o", join(builtDir, file), "."], {
+    cwd: work,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+  rmSync(work, { recursive: true, force: true });
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const recordOnly = process.argv.includes("--record");
+  const manifest = {};
+  for (const { module, files, built } of GRAMMARS) {
+    const pkg = dirname(require.resolve(`${module}/package.json`));
+    const { version } = require(`${module}/package.json`);
+    for (const file of files) {
+      if (built && !recordOnly) compile(module, pkg, file);
+      const path = built ? join(builtDir, file) : join(pkg, file);
+      manifest[file] = built
+        ? { module, version, cli: CLI, source: sourceHash(pkg), patches: (PATCHES[module] ?? []).length, sha256: sha256(path) }
+        : { module, version, sha256: sha256(path) };
+      console.log(`${built && !recordOnly ? "built" : "recorded"} ${file} (${module}@${version})`);
+    }
+  }
+  writeFileSync(join(builtDir, "grammars.json"), JSON.stringify(manifest, null, 2) + "\n");
+}

package/scripts/build-viewer.mjs

@@ -0,0 +1,44 @@
+/**
+ * Bundles the viewer into dist/viewer/ (app.js via esbuild + copied static
+ * assets). Runs as part of `npm run build`; the bundle ships in the package
+ * so `graft viz` needs no install or build step at runtime.
+ */
+import { build } from "esbuild";
+import { mkdirSync, copyFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const outDir = join(root, "dist", "viewer");
+mkdirSync(outDir, { recursive: true });
+
+await build({
+  entryPoints: [join(root, "viewer", "main.ts")],
+  bundle: true,
+  minify: true,
+  format: "esm",
+  target: "es2022",
+  outfile: join(outDir, "app.js"),
+});
+
+for (const asset of ["index.html", "style.css"]) {
+  copyFileSync(join(root, "viewer", asset), join(outDir, asset));
+}
+
+console.log("viewer bundle → dist/viewer/");
+
+// The generic (breadth) tier's tags.scm query files are runtime assets — tsc
+// doesn't emit non-TS files, so copy them into dist so the published package
+// (which ships `dist` only) can load them. generic.ts resolves dist/graph/queries
+// first, then falls back to src/graph/queries for local dev.
+const scmSrc = join(root, "src", "graph", "queries");
+const scmOut = join(root, "dist", "graph", "queries");
+mkdirSync(scmOut, { recursive: true });
+let scmCount = 0;
+for (const f of readdirSync(scmSrc)) {
+  if (f.endsWith(".scm")) {
+    copyFileSync(join(scmSrc, f), join(scmOut, f));
+    scmCount++;
+  }
+}
+console.log(`grammar queries → dist/graph/queries/ (${scmCount} .scm)`);

package/scripts/graph-quality.mjs

@@ -0,0 +1,117 @@
+/**
+ * Graph-quality report + invariant check for a built graph (`graft/.graph/wiring.json`).
+ *
+ *   node scripts/graph-quality.mjs <repo-dir-or-wiring.json> [--json] [--strict]
+ *
+ * Tier-0 of the quality strategy: needs no external oracle. Reports the graph's
+ * shape (nodes by kind/origin, edges by relation/confidence, resolution rate) and
+ * asserts structural INVARIANTS that must always hold:
+ *   - no dangling edge endpoints (every source is a node; every target is a node
+ *     or a deliberately-unresolved external string)
+ *   - valid spans (`Lx-Ly`, x<=y, within file line count where known)
+ *   - unique node ids; non-empty names; kinds in the allowed set
+ *   - no self-loop call edges
+ * Exits non-zero with --strict when any invariant fails (CI gate).
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const KINDS = new Set(["file","class","function","method","interface","type","enum","struct","module","constant","variable"]);
+const RELATIONS = new Set(["contains","calls","imports","references","implements","extends"]);
+const CONFIDENCE = new Set(["lsp_resolved","lsp_dispatch","extracted","inferred"]);
+
+const arg = process.argv[2] ?? ".";
+const json = process.argv.includes("--json");
+const strict = process.argv.includes("--strict");
+const wpath = arg.endsWith(".json") ? arg
+  : [join(arg, "graft", ".graph", "wiring.json"), join(arg, "graft", "wiring.json")].find(existsSync);
+if (!wpath || !existsSync(wpath)) { console.error(`no graph found at ${arg} (run \`graft build\` first)`); process.exit(2); }
+
+const g = JSON.parse(readFileSync(wpath, "utf8"));
+const nodes = g.nodes ?? [], edges = g.edges ?? [];
+const ids = new Set(nodes.map((n) => n.id));
+
+const bump = (m, k) => m.set(k, (m.get(k) ?? 0) + 1);
+const byKind = new Map(), byOrigin = new Map(), byRel = new Map(), byConf = new Map();
+for (const n of nodes) { bump(byKind, n.kind); bump(byOrigin, n.origin ?? "?"); }
+for (const e of edges) { bump(byRel, e.relation); bump(byConf, e.confidence); }
+
+// ── invariants ──
+const problems = [];
+const seen = new Set();
+for (const n of nodes) {
+  if (seen.has(n.id)) problems.push(`dup id: ${n.id}`); seen.add(n.id);
+  if (!n.name || !String(n.name).trim()) problems.push(`empty name: ${n.id}`);
+  if (!KINDS.has(n.kind)) problems.push(`bad kind '${n.kind}': ${n.id}`);
+  const m = /^L(\d+)-L(\d+)$/.exec(n.span ?? "");
+  if (!m) problems.push(`bad span '${n.span}': ${n.id}`);
+  else if (Number(m[1]) > Number(m[2])) problems.push(`inverted span ${n.span}: ${n.id}`);
+}
+// an edge target may be a node id OR a deliberately-unresolved external string
+// (import specifier / bare heritage name / unresolved Java annotation type);
+// only calls/contains must point at real nodes.
+let dangling = 0, selfLoops = 0, unresolvedExternal = 0;
+for (const e of edges) {
+  if (!RELATIONS.has(e.relation)) problems.push(`bad relation '${e.relation}'`);
+  if (!CONFIDENCE.has(e.confidence)) problems.push(`bad confidence '${e.confidence}'`);
+  if (!ids.has(e.source)) { problems.push(`dangling source: ${e.source}`); dangling++; }
+  const targetIsNode = ids.has(e.target);
+  if (!targetIsNode) {
+    if (e.relation === "imports" || e.relation === "extends" || e.relation === "implements" || e.relation === "references") unresolvedExternal++;
+    else { problems.push(`dangling ${e.relation} target: ${e.source} → ${e.target}`); dangling++; }
+  }
+  if (e.relation === "calls" && e.source === e.target) selfLoops++;
+}
+
+// ── resolution / connectivity metrics ──
+const calls = edges.filter((e) => e.relation === "calls");
+const resolvedCalls = calls.filter((e) => ids.has(e.target)).length;
+const withEdge = new Set();
+for (const e of edges) { if (e.relation !== "contains") { withEdge.add(e.source); if (ids.has(e.target)) withEdge.add(e.target); } }
+const symbolNodes = nodes.filter((n) => n.kind !== "file");
+const orphans = symbolNodes.filter((n) => !withEdge.has(n.id)).length;
+
+const report = {
+  graph: wpath,
+  nodes: nodes.length,
+  symbolNodes: symbolNodes.length,
+  edges: edges.length,
+  byKind: Object.fromEntries([...byKind].sort((a,b)=>b[1]-a[1])),
+  byOrigin: Object.fromEntries(byOrigin),
+  byRelation: Object.fromEntries(byRel),
+  byConfidence: Object.fromEntries(byConf),
+  resolution: {
+    calls: calls.length,
+    resolvedToNode: resolvedCalls,
+    resolvedPct: calls.length ? Math.round((resolvedCalls / calls.length) * 100) : null,
+    unresolvedExternalImports: unresolvedExternal,
+  },
+  connectivity: {
+    orphanSymbolNodes: orphans,
+    orphanPct: symbolNodes.length ? Math.round((orphans / symbolNodes.length) * 100) : null,
+  },
+  invariants: {
+    ok: problems.length === 0,
+    danglingEdges: dangling,
+    selfLoopCalls: selfLoops,
+    violations: problems.length,
+    sample: problems.slice(0, 15),
+  },
+};
+
+if (json) { console.log(JSON.stringify(report, null, 2)); }
+else {
+  const p = report;
+  console.log(`graph-quality — ${p.graph}`);
+  console.log(`  nodes ${p.nodes} (${p.symbolNodes} symbols) · edges ${p.edges}`);
+  console.log(`  kinds:      ${Object.entries(p.byKind).map(([k,v])=>`${k}=${v}`).join(" ")}`);
+  console.log(`  origin:     ${Object.entries(p.byOrigin).map(([k,v])=>`${k}=${v}`).join(" ")}`);
+  console.log(`  relations:  ${Object.entries(p.byRelation).map(([k,v])=>`${k}=${v}`).join(" ")}`);
+  console.log(`  confidence: ${Object.entries(p.byConfidence).map(([k,v])=>`${k}=${v}`).join(" ")}`);
+  console.log(`  calls resolved: ${p.resolution.resolvedToNode}/${p.resolution.calls} (${p.resolution.resolvedPct}%)`);
+  console.log(`  orphan symbols: ${p.connectivity.orphanSymbolNodes}/${p.symbolNodes} (${p.connectivity.orphanPct}%)`);
+  console.log(`  INVARIANTS: ${p.invariants.ok ? "OK ✓" : `FAIL ✗ (${p.invariants.violations} violations, ${p.invariants.danglingEdges} dangling)`}`);
+  if (!p.invariants.ok) for (const s of p.invariants.sample) console.log(`     - ${s}`);
+  if (p.invariants.selfLoopCalls) console.log(`  note: ${p.invariants.selfLoopCalls} self-loop calls`);
+}
+if (strict && !report.invariants.ok) process.exit(1);