@vizalice/codegraph 1.5.0

package/scripts/build-kernel.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+#
+# Build the native extraction kernel (codegraph-kernel) and stage the .node
+# where the TS loader (src/extraction/kernel/loader.ts) finds it for
+# from-source runs and tests:
+#
+#   codegraph-kernel/prebuilds/<platform>-<arch>/codegraph-kernel.node
+#
+# The kernel is OPTIONAL everywhere: when the .node is absent the extraction
+# path falls back to the wasm pipeline. This script needs a Rust toolchain
+# (rustup.rs); nothing else in the repo does.
+#
+# Usage:
+#   scripts/build-kernel.sh                 # host platform
+#   scripts/build-kernel.sh --target <rust-triple> [--platform <plat-arch>]
+#
+# The cross-compile form is what the release workflow uses (e.g.
+# --target x86_64-apple-darwin --platform darwin-x64 on a macos-arm runner).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CRATE="$ROOT/codegraph-kernel"
+
+TARGET=""
+PLATFORM=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --target)   TARGET="$2"; shift 2 ;;
+    --platform) PLATFORM="$2"; shift 2 ;;
+    *) echo "unknown arg: $1" >&2; exit 1 ;;
+  esac
+done
+
+# Map a rust triple (or the host) to the bundle-target naming used across the
+# release pipeline (darwin-arm64, linux-x64, win32-arm64, ...).
+if [ -z "$PLATFORM" ]; then
+  if [ -n "$TARGET" ]; then
+    case "$TARGET" in
+      aarch64-apple-darwin)         PLATFORM="darwin-arm64" ;;
+      x86_64-apple-darwin)          PLATFORM="darwin-x64" ;;
+      x86_64-unknown-linux-gnu)     PLATFORM="linux-x64" ;;
+      aarch64-unknown-linux-gnu)    PLATFORM="linux-arm64" ;;
+      x86_64-pc-windows-msvc)       PLATFORM="win32-x64" ;;
+      aarch64-pc-windows-msvc)      PLATFORM="win32-arm64" ;;
+      *) echo "cannot map rust target '$TARGET' to a platform name; pass --platform" >&2; exit 1 ;;
+    esac
+  else
+    case "$(uname -s)-$(uname -m)" in
+      Darwin-arm64)  PLATFORM="darwin-arm64" ;;
+      Darwin-x86_64) PLATFORM="darwin-x64" ;;
+      Linux-x86_64)  PLATFORM="linux-x64" ;;
+      Linux-aarch64) PLATFORM="linux-arm64" ;;
+      MINGW*-x86_64|MSYS*-x86_64)   PLATFORM="win32-x64" ;;
+      MINGW*-aarch64|MSYS*-aarch64) PLATFORM="win32-arm64" ;;
+      *) echo "unrecognized host $(uname -s)-$(uname -m); pass --platform" >&2; exit 1 ;;
+    esac
+  fi
+fi
+
+echo "[kernel] building codegraph-kernel for ${PLATFORM}${TARGET:+ (target $TARGET)}"
+cd "$CRATE"
+if [ -n "$TARGET" ]; then
+  rustup target add "$TARGET" >/dev/null 2>&1 || true
+  cargo build --release --target "$TARGET"
+  OUTDIR="$CRATE/target/$TARGET/release"
+else
+  cargo build --release
+  OUTDIR="$CRATE/target/release"
+fi
+
+# cdylib name differs per OS; the staged name is always codegraph-kernel.node.
+case "$PLATFORM" in
+  darwin-*) LIB="$OUTDIR/libcodegraph_kernel.dylib" ;;
+  linux-*)  LIB="$OUTDIR/libcodegraph_kernel.so" ;;
+  win32-*)  LIB="$OUTDIR/codegraph_kernel.dll" ;;
+esac
+[ -f "$LIB" ] || { echo "[kernel] error: built library not found at $LIB" >&2; exit 1; }
+
+DEST="$CRATE/prebuilds/$PLATFORM"
+mkdir -p "$DEST"
+# rm first so the copy lands on a FRESH inode: overwriting a signed dylib in
+# place leaves macOS's per-inode signature cache stale, and every process
+# that then dlopens the staged .node is SIGKILLed at load (the on-disk
+# signature still verifies, which makes it maddening to diagnose).
+rm -f "$DEST/codegraph-kernel.node"
+cp "$LIB" "$DEST/codegraph-kernel.node"
+echo "[kernel] staged $DEST/codegraph-kernel.node ($(du -h "$DEST/codegraph-kernel.node" | cut -f1))"

package/scripts/dump-graph.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * Dump a .codegraph/codegraph.db graph by NATURAL KEYS (no rowids, no
+ * timestamps), sorted — two dumps diff clean iff the graphs are semantically
+ * identical. The byte-identical gate used by every perf/kernel PR:
+ *
+ *   node scripts/dump-graph.mjs <repo-or-db> > a.dump
+ *   node scripts/dump-graph.mjs <repo-or-db> > b.dump
+ *   diff a.dump b.dump
+ *
+ * Volatile fields excluded: nodes.updated_at, files.modified_at/indexed_at/
+ * content_hash+size (environment-dependent), edges.id / unresolved_refs.id
+ * (insertion rowids), and unresolved_refs.status (resolution bookkeeping —
+ * kept, actually: status is deterministic given the same input; excluded only
+ * if it proves flaky. We keep status.)
+ */
+
+import { DatabaseSync } from 'node:sqlite';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const arg = process.argv[2];
+if (!arg) {
+  console.error('usage: dump-graph.mjs <repo-root-or-db-path>');
+  process.exit(2);
+}
+let dbPath = arg;
+if (fs.statSync(arg).isDirectory()) {
+  dbPath = path.join(arg, '.codegraph', 'codegraph.db');
+}
+const db = new DatabaseSync(dbPath, { readOnly: true });
+
+function dump(title, sql) {
+  const rows = db.prepare(sql).all();
+  const lines = rows.map((r) => JSON.stringify(r)).sort();
+  process.stdout.write(`== ${title} (${lines.length})\n`);
+  for (const l of lines) process.stdout.write(l + '\n');
+}
+
+dump(
+  'nodes',
+  `SELECT id, kind, name, qualified_name, file_path, language, start_line, end_line,
+          start_column, end_column, docstring, signature, visibility, is_exported,
+          is_async, is_static, is_abstract, decorators, type_parameters, return_type
+   FROM nodes`
+);
+dump(
+  'edges',
+  `SELECT source, target, kind, metadata, line, col, provenance FROM edges`
+);
+dump(
+  'refs',
+  `SELECT from_node_id, reference_name, reference_kind, line, col, candidates,
+          file_path, language, status, name_tail
+   FROM unresolved_refs`
+);
+dump('files', `SELECT path, language, node_count FROM files`);

package/scripts/extract-release-notes.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * Extract a release-notes block from CHANGELOG.md for a given version
+ * (or unwrap text supplied on stdin), then join hard-wrapped paragraphs.
+ *
+ * Why: GitHub renders release-note Markdown with GFM hard breaks, so
+ * every `\n` becomes `<br>`. The CHANGELOG is hard-wrapped at ~75
+ * chars for readable diffs, which then renders as awkward visible
+ * line breaks on the release page. This script joins indented
+ * continuation lines into a single line per bullet so the GFM
+ * renderer produces clean paragraphs.
+ *
+ * Repo-level CHANGELOG.md viewing is unaffected (CommonMark treats
+ * newlines as spaces there).
+ *
+ * Usage:
+ *   extract-release-notes.mjs <version>     # read CHANGELOG.md
+ *   extract-release-notes.mjs --stdin       # read from stdin (any text)
+ */
+
+import { readFileSync } from 'fs';
+
+const arg = process.argv[2];
+if (!arg) {
+  console.error('usage: extract-release-notes.mjs <version> | --stdin');
+  process.exit(1);
+}
+
+let block;
+if (arg === '--stdin') {
+  block = readFileSync(0, 'utf8').replace(/\r\n?/g, '\n').split('\n');
+} else {
+  const version = arg;
+  const escaped = version.replace(/\./g, '\\.');
+  const headerRe = new RegExp(`^## \\[${escaped}\\]`);
+  const anyHeaderRe = /^## \[/;
+  const lines = readFileSync('CHANGELOG.md', 'utf8').split('\n');
+  const start = lines.findIndex((l) => headerRe.test(l));
+  if (start === -1) {
+    console.error(`no '## [${version}]' entry found in CHANGELOG.md`);
+    process.exit(1);
+  }
+  const after = lines.findIndex((l, i) => i > start && anyHeaderRe.test(l));
+  block = lines.slice(start, after === -1 ? lines.length : after);
+}
+
+// Track a stack of `{ indent: number }` frames so a continuation line
+// can attach to the right ancestor. Handles the post-nested-list
+// continuation pattern:
+//
+//     - top-level
+//         - nested
+//       back to top-level  <- 2-space indent, joins the top-level bullet
+const out = [];
+let buf = '';
+let stack = [];
+
+function flushBuf() {
+  if (buf !== '') {
+    out.push(buf);
+    buf = '';
+  }
+}
+
+function leadingSpaces(s) {
+  const m = s.match(/^(\s*)/);
+  return m ? m[1].length : 0;
+}
+
+// Bullets: `-`, `*`, `digit.` only. `+` is intentionally excluded — the
+// CHANGELOG uses literal `+` inline (`config + instructions`) and we
+// don't want to misread those as nested bullets.
+const listItemRe = /^(\s*)([-*]|\d+\.)\s+/;
+const fenceRe = /^\s*```/;
+
+let inFence = false;
+
+for (const line of block) {
+  // Fenced code blocks: pass through verbatim, no joining.
+  if (fenceRe.test(line)) {
+    flushBuf();
+    stack = [];
+    out.push(line);
+    inFence = !inFence;
+    continue;
+  }
+  if (inFence) {
+    out.push(line);
+    continue;
+  }
+  if (/^\s*$/.test(line)) {
+    flushBuf();
+    out.push('');
+    continue;
+  }
+  if (/^#/.test(line)) {
+    flushBuf();
+    stack = [];
+    out.push(line);
+    continue;
+  }
+  const itemMatch = line.match(listItemRe);
+  if (itemMatch) {
+    flushBuf();
+    const indent = itemMatch[1].length;
+    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+    stack.push({ indent });
+    buf = line;
+    continue;
+  }
+  if (/^\s/.test(line)) {
+    const indent = leadingSpaces(line);
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      flushBuf();
+      stack.pop();
+    }
+    const trimmed = line.replace(/^\s+/, '');
+    buf = buf === '' ? trimmed : `${buf} ${trimmed}`;
+    continue;
+  }
+  flushBuf();
+  stack = [];
+  out.push(line);
+}
+flushBuf();
+
+process.stdout.write(out.join('\n'));
+if (!out[out.length - 1]?.endsWith('\n')) process.stdout.write('\n');

package/scripts/kernel-parity.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * Kernel↔wasm extraction parity harness (R2/R3 of the kernel migration).
+ *
+ * Runs BOTH extraction paths over the given files/directories and diffs the
+ * per-file ExtractionResults as sets (nodes/edges/refs, canonicalized), so a
+ * behavioral gap in the native kernel shows up as a categorized diff instead
+ * of a graph-dump surprise later. This is the fast inner loop; the §5 gate's
+ * full-repo dump-diff still runs before any default-on.
+ *
+ * Usage:
+ *   node scripts/kernel-parity.mjs <file-or-dir>... [--lang typescript,tsx]
+ *        [--max-samples N] [--list-files] [--max-deferral 0.1]
+ *
+ * --max-deferral: the broken-kernel backstop (default 0.1). For C/C++ pass
+ * 0.5: macro-heavy C/C++ trees genuinely parse with errors at 10–40% file
+ * rates even after the preParse blanking family (git 19%, protobuf 26%, fmt
+ * 42% — measured 2026-07-17), and every erroring file defers BY POLICY, so
+ * the 10% bar calibrated on the 0–0.4% incidence of ts/java/py/go would fail
+ * healthy sweeps. A broken walker still trips 0.5 (it defers ~everything).
+ *
+ * Requires: npm run build (dist/) and a staged kernel (npm run build:kernel).
+ * Exit code: 0 = parity, 1 = diffs found, 2 = setup error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const dist = (p) => path.join(ROOT, 'dist', p);
+
+const args = process.argv.slice(2);
+const paths = [];
+let langFilter = null;
+let maxSamples = 5;
+let listFiles = false;
+let maxDeferral = 0.1;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--lang') langFilter = new Set(args[++i].split(','));
+  else if (args[i] === '--max-samples') maxSamples = Number(args[++i]);
+  else if (args[i] === '--list-files') listFiles = true;
+  else if (args[i] === '--max-deferral') maxDeferral = Number(args[++i]);
+  else paths.push(args[i]);
+}
+if (paths.length === 0) {
+  console.error('usage: kernel-parity.mjs <file-or-dir>... [--lang ts,tsx] [--max-samples N]');
+  process.exit(2);
+}
+
+const KERNEL_LANGS = new Set(['typescript', 'tsx', 'javascript', 'jsx', 'java', 'python', 'go', 'c', 'cpp', 'rust', 'csharp', 'ruby', 'php', 'swift', 'kotlin', 'r', 'lua', 'luau', 'scala', 'dart']);
+const EXTS = new Map([
+  ['.ts', 'typescript'], ['.mts', 'typescript'], ['.cts', 'typescript'],
+  ['.tsx', 'tsx'], ['.js', 'javascript'], ['.mjs', 'javascript'],
+  ['.cjs', 'javascript'], ['.jsx', 'jsx'], ['.java', 'java'], ['.py', 'python'], ['.pyw', 'python'], ['.go', 'go'],
+  // C/C++ (R7a). `.h` needs CONTENT sniffing (C vs C++) — resolved per file
+  // in the run loop via detectLanguage, matching the real indexer's routing.
+  ['.c', 'c'], ['.h', 'detect'],
+  ['.cpp', 'cpp'], ['.cc', 'cpp'], ['.cxx', 'cpp'], ['.hpp', 'cpp'], ['.hxx', 'cpp'],
+  ['.metal', 'cpp'], ['.cu', 'cpp'], ['.cuh', 'cpp'],
+  ['.rs', 'rust'], // R7b
+  ['.cs', 'csharp'], // R7b
+  ['.rb', 'ruby'], ['.rake', 'ruby'], // R7b
+  ['.php', 'php'], ['.module', 'php'], ['.install', 'php'], ['.theme', 'php'], ['.inc', 'php'], // R7b
+  ['.swift', 'swift'], // R7b
+  ['.kt', 'kotlin'], ['.kts', 'kotlin'], // R7b
+  ['.r', 'r'], // R7b batch 4 — real-world casing is `.R`; extname lowercased below
+  ['.lua', 'lua'], ['.luau', 'luau'], // R7b batch 4
+  ['.scala', 'scala'], ['.sc', 'scala'], // R7b batch 4
+  ['.dart', 'dart'], // R7b batch 4
+]);
+
+/** Collect candidate files. */
+function collect(p, out) {
+  let st;
+  try {
+    st = fs.statSync(p); // dangling symlinks (Linux-tree dtc fixtures) throw
+  } catch {
+    return;
+  }
+  if (st.isDirectory()) {
+    const base = path.basename(p);
+    if (base === 'node_modules' || base === '.git' || base === 'dist' || base === '.codegraph') return;
+    for (const e of fs.readdirSync(p)) collect(path.join(p, e), out);
+  } else if (EXTS.has(path.extname(p).toLowerCase())) {
+    // Lowercased to match the real indexer's routing (detectLanguage
+    // lowercases the extension — `.R` is the dominant real-world casing).
+    const lang = EXTS.get(path.extname(p).toLowerCase());
+    // 'detect' (.h) resolves per file in the run loop; under --lang it rides
+    // along whenever either C-family language is requested.
+    const passes =
+      !langFilter ||
+      (lang === 'detect' ? langFilter.has('c') || langFilter.has('cpp') : langFilter.has(lang));
+    if (passes) out.push({ file: p, lang });
+  }
+}
+
+const files = [];
+for (const p of paths) collect(path.resolve(p), files);
+if (files.length === 0) {
+  console.error('no matching files');
+  process.exit(2);
+}
+
+// --- load the built engine ---------------------------------------------------
+const { extractFromSource } = await import(dist('extraction/tree-sitter.js'));
+const { initGrammars, loadGrammarsForLanguages, detectLanguage } = await import(dist('extraction/grammars.js'));
+const kernel = await import(dist('extraction/kernel/index.js'));
+
+await initGrammars();
+await loadGrammarsForLanguages([...KERNEL_LANGS]);
+
+if (!kernel.getKernel()) {
+  console.error('kernel .node not found — run: npm run build:kernel');
+  process.exit(2);
+}
+
+// --- canonicalization ---------------------------------------------------------
+/**
+ * Node identity for cross-referencing edges/refs: the node id itself (both
+ * paths compute the same deterministic ids, and id embeds kind+name+line).
+ */
+function canonNode(n) {
+  const out = {
+    id: n.id, kind: n.kind, name: n.name, qualifiedName: n.qualifiedName,
+    filePath: n.filePath, language: n.language,
+    startLine: n.startLine, endLine: n.endLine,
+    startColumn: n.startColumn, endColumn: n.endColumn,
+  };
+  for (const k of ['docstring', 'signature', 'visibility', 'isExported', 'isAsync', 'isStatic', 'isAbstract', 'returnType']) {
+    if (n[k] !== undefined) out[k] = n[k];
+  }
+  if (n.decorators !== undefined) out.decorators = n.decorators;
+  if (n.typeParameters !== undefined) out.typeParameters = n.typeParameters;
+  return JSON.stringify(out);
+}
+
+function canonEdge(e) {
+  const out = { source: e.source, target: e.target, kind: e.kind };
+  if (e.line !== undefined) out.line = e.line;
+  if (e.column !== undefined) out.column = e.column;
+  if (e.provenance !== undefined) out.provenance = e.provenance;
+  if (e.metadata !== undefined) out.metadata = e.metadata;
+  return JSON.stringify(out);
+}
+
+function canonRef(r) {
+  // FULL object — a field only one path sets is a parity bug (the vitest
+  // parity suite caught decode.ts pre-filling filePath/language this way).
+  const out = {
+    from: r.fromNodeId, name: r.referenceName, kind: r.referenceKind,
+    line: r.line, column: r.column,
+  };
+  for (const k of ['filePath', 'language', 'candidates', 'rowId']) {
+    if (r[k] !== undefined) out[k] = r[k];
+  }
+  return JSON.stringify(out);
+}
+
+function diffSets(aList, bList) {
+  const a = new Map(); // canon -> count (multiset — duplicates matter)
+  const b = new Map();
+  for (const x of aList) a.set(x, (a.get(x) ?? 0) + 1);
+  for (const x of bList) b.set(x, (b.get(x) ?? 0) + 1);
+  const onlyA = [];
+  const onlyB = [];
+  for (const [k, c] of a) {
+    const d = c - (b.get(k) ?? 0);
+    for (let i = 0; i < d; i++) onlyA.push(k);
+  }
+  for (const [k, c] of b) {
+    const d = c - (a.get(k) ?? 0);
+    for (let i = 0; i < d; i++) onlyB.push(k);
+  }
+  return { onlyA, onlyB };
+}
+
+// --- run ----------------------------------------------------------------------
+const buckets = new Map(); // category -> {count, samples[]}
+function report(category, sample) {
+  let b = buckets.get(category);
+  if (!b) buckets.set(category, (b = { count: 0, samples: [] }));
+  b.count++;
+  if (b.samples.length < maxSamples) b.samples.push(sample);
+}
+
+let filesWithDiffs = 0;
+let filesOk = 0;
+let deferred = 0;
+let processed = 0; // collected files minus content-detect skips
+let totals = { nodes: 0, edges: 0, refs: 0 };
+
+process.env.CODEGRAPH_KERNEL_LANGS = 'all';
+
+for (const { file, lang: extLang } of files) {
+  const source = fs.readFileSync(file, 'utf8');
+  const rel = path.relative(ROOT, file);
+  // `.h` resolves C vs C++ by content — the same call the indexer makes.
+  const lang = extLang === 'detect' ? detectLanguage(rel, source) : extLang;
+  if (!KERNEL_LANGS.has(lang)) continue;
+  if (langFilter && !langFilter.has(lang)) continue;
+  processed++;
+
+  delete process.env.CODEGRAPH_KERNEL; // kernel path on
+  const kres = kernel.tryKernelExtract(rel, source, lang);
+  if (!kres) {
+    // Expected: files with parse errors defer to wasm (parity by
+    // construction — both arms run the same extractor). Counted, and
+    // guarded below so a broken kernel can't silently defer everything.
+    deferred++;
+    report('kernel-deferred', rel);
+    continue;
+  }
+  process.env.CODEGRAPH_KERNEL = '0'; // wasm path
+  const wres = extractFromSource(rel, source, lang);
+  delete process.env.CODEGRAPH_KERNEL;
+
+  totals.nodes += wres.nodes.length;
+  totals.edges += wres.edges.length;
+  totals.refs += wres.unresolvedReferences.length;
+
+  let fileHasDiff = false;
+  const tables = [
+    ['node', wres.nodes.map(canonNode), kres.nodes.map(canonNode)],
+    ['edge', wres.edges.map(canonEdge), kres.edges.map(canonEdge)],
+    ['ref', wres.unresolvedReferences.map(canonRef), kres.unresolvedReferences.map(canonRef)],
+  ];
+  for (const [table, wasm, kern] of tables) {
+    const { onlyA, onlyB } = diffSets(wasm, kern);
+    for (const x of onlyA) {
+      fileHasDiff = true;
+      const o = JSON.parse(x);
+      report(`${table}:missing-in-kernel:${o.kind ?? ''}`, `${rel}: ${x}`);
+    }
+    for (const x of onlyB) {
+      fileHasDiff = true;
+      const o = JSON.parse(x);
+      report(`${table}:extra-in-kernel:${o.kind ?? ''}`, `${rel}: ${x}`);
+    }
+    // ORDER matters too: identical multisets in a different emission order
+    // change DB rowids, and resolution iterates refs in rowid order — the
+    // full-index dump-diff would surface it as a downstream mystery. Catch it
+    // here instead.
+    if (onlyA.length === 0 && onlyB.length === 0) {
+      for (let i = 0; i < wasm.length; i++) {
+        if (wasm[i] !== kern[i]) {
+          fileHasDiff = true;
+          report(`${table}:order-mismatch`, `${rel}: index ${i}: wasm=${wasm[i]} kernel=${kern[i]}`);
+          break;
+        }
+      }
+    }
+  }
+  if (fileHasDiff) {
+    filesWithDiffs++;
+    if (listFiles) console.log(`DIFF ${rel}`);
+  } else {
+    filesOk++;
+  }
+}
+
+console.log(`\n=== kernel parity: ${filesOk}/${processed} files byte-parity` +
+  ` (${filesWithDiffs} with diffs, ${deferred} deferred-to-wasm)` +
+  ` | wasm totals: ${totals.nodes} nodes / ${totals.edges} edges / ${totals.refs} refs ===\n`);
+
+const sorted = [...buckets.entries()].sort((a, b) => b[1].count - a[1].count);
+for (const [cat, { count, samples }] of sorted) {
+  console.log(`--- ${cat}: ${count}`);
+  for (const s of samples) console.log(`    ${s.length > 400 ? s.slice(0, 400) + '…' : s}`);
+}
+
+// Deferrals are per-file parse-error routing (expected; rare for most
+// languages, routine for macro-heavy C/C++ — see --max-deferral above). A
+// rate past the threshold means the kernel is broken and hiding behind the
+// fallback — fail loudly.
+const deferralRate = deferred / Math.max(processed, 1);
+if (deferralRate > maxDeferral) {
+  console.error(
+    `deferral rate ${(deferralRate * 100).toFixed(1)}% exceeds ${(maxDeferral * 100).toFixed(0)}% — kernel likely broken`
+  );
+  process.exit(1);
+}
+process.exit(filesWithDiffs > 0 ? 1 : 0);

package/scripts/local-install.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Build the current branch and link it as the global `codegraph` for
+# hands-on testing. Replaces any existing global install for as long
+# as the symlink is in place.
+#
+# Usage:
+#   ./scripts/local-install.sh           # build + link
+#   ./scripts/local-install.sh --undo    # unlink + restore the published version
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+PKG=$(node -p "require('./package.json').name")
+VERSION=$(node -p "require('./package.json').version")
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+if [ "${1:-}" = "--undo" ]; then
+  echo "→ unlinking ${PKG}"
+  npm unlink -g "${PKG}" >/dev/null 2>&1 || true
+  echo "→ reinstalling published ${PKG}"
+  npm install -g "${PKG}"
+  echo "done: global codegraph -> $(command -v codegraph)"
+  exit 0
+fi
+
+echo "→ building ${PKG} ${VERSION} (${BRANCH})"
+npm run build
+
+echo "→ linking globally"
+npm link
+
+LINKED=$(command -v codegraph || echo "(not on PATH)")
+echo
+echo "✓ global codegraph now points to this branch"
+echo "  binary:  ${LINKED}"
+echo "  branch:  ${BRANCH}"
+echo "  version: ${VERSION}"
+echo
+echo "To restore the published version:"
+echo "  ./scripts/local-install.sh --undo"

package/scripts/npm-sdk.js

@@ -0,0 +1,75 @@
+'use strict';
+//
+// Programmatic / embedded SDK entry for @colbymchenry/codegraph (issue #354).
+//
+// The CLI/MCP `bin` (npm-shim.js) execs the per-platform bundle's OWN Node 24 so
+// the tool never depends on the user's runtime. Embedded library consumers are
+// the opposite case: they already run their own Node and just want the compiled
+// API — `require("@colbymchenry/codegraph")` returning the CodeGraph class et al.
+//
+// The compiled library + its production dependencies (web-tree-sitter,
+// tree-sitter-wasms, …) ship INSIDE the per-platform bundle, at
+//   @colbymchenry/codegraph-<platform>-<arch>/lib/dist/index.js
+// (with the deps in the sibling lib/node_modules). Re-exporting that bundle keeps
+// the main package thin — no second 50 MB copy of the grammars — while making the
+// SDK work in the consumer's process. Types are a separate concern: the main
+// package ships its own dist/**/*.d.ts tree (pointed at by `types`), built from
+// the same release so it can never skew from the runtime it re-exports.
+//
+// node:sqlite (Node >= 22.5) is required to OPEN a graph, but only lazily inside
+// the SQLite adapter — so loading this module is safe on older Node, and the
+// node:sqlite requirement surfaces with an actionable error only when a DB is
+// actually opened. Heavy extraction additionally wants the bundled launcher's
+// --liftoff-only flag (the WASM Zone-OOM guard, issues #293/#298); an embedded
+// host that drives large indexing should pass that flag to its own Node.
+
+var path = require('path');
+var os = require('os');
+var fs = require('fs');
+
+var target = process.platform + '-' + process.arch; // e.g. darwin-arm64, linux-x64
+var pkg = '@colbymchenry/codegraph-' + target;
+
+module.exports = require(resolveLibrary());
+
+// Locate the compiled library entry inside the installed per-platform bundle.
+// Throws an actionable error (rather than a bare MODULE_NOT_FOUND) when no bundle
+// is present, so an embedded consumer knows exactly what to install.
+function resolveLibrary() {
+  // 1) The npm-installed optional dependency — the normal case.
+  try {
+    return require.resolve(pkg + '/lib/dist/index.js');
+  } catch (e) {
+    /* fall through to the self-healed cache */
+  }
+
+  // 2) A bundle the CLI shim self-healed from GitHub Releases into the cache
+  //    (issue #303). Same node/lib/bin layout as the npm package. We only REUSE a
+  //    cached bundle here — unlike the CLI shim we never trigger a network
+  //    download from inside require(), which must stay synchronous and cheap.
+  var cached = cachedLibrary();
+  if (cached) return cached;
+
+  throw new Error(
+    'codegraph: the programmatic API is unavailable because the platform bundle\n' +
+    '(' + pkg + ') is not installed.\n' +
+    'The compiled library ships inside that per-platform optional dependency.\n' +
+    'Fixes:\n' +
+    '  - install from the official npm registry so the matching bundle is fetched:\n' +
+    '      npm i @colbymchenry/codegraph --registry=https://registry.npmjs.org\n' +
+    '  - or run the CLI once (e.g. `npx @colbymchenry/codegraph status`) to\n' +
+    '    self-heal the bundle into ~/.codegraph, then require() will find it.'
+  );
+}
+
+function cachedLibrary() {
+  try {
+    var version = require(path.join(__dirname, 'package.json')).version;
+    var base = process.env.CODEGRAPH_INSTALL_DIR || path.join(os.homedir(), '.codegraph');
+    var lib = path.join(base, 'bundles', target + '-' + version, 'lib', 'dist', 'index.js');
+    if (fs.existsSync(lib)) return lib;
+  } catch (e) {
+    /* no readable cache → caller reports the install guidance */
+  }
+  return null;
+}