homegraph 1.1.2 → 1.1.3

package/package.json

@@ -1,57 +1,58 @@
-{
-  "name": "homegraph",
-  "version": "1.1.2",
-  "description": "Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "homegraph": "./dist/bin/homegraph.js"
-  },
-  "files": [
-    "dist",
-    "scripts",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc && npm run copy-assets && node -e \"require('fs').chmodSync('dist/bin/homegraph.js', 0o755)\"",
-    "preuninstall": "node dist/bin/uninstall.js",
-    "copy-assets": "node -e \"const fs=require('fs');fs.mkdirSync('dist/db',{recursive:true});fs.copyFileSync('src/db/schema.sql','dist/db/schema.sql');fs.mkdirSync('dist/extraction/wasm',{recursive:true});fs.readdirSync('src/extraction/wasm').filter(f=>f.endsWith('.wasm')).forEach(f=>fs.copyFileSync('src/extraction/wasm/'+f,'dist/extraction/wasm/'+f))\"",
-    "dev": "tsc --watch",
-    "cli": "npm run build && node dist/bin/homegraph.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:eval": "vitest run __tests__/evaluation/",
-    "eval": "npm run build && npx tsx __tests__/evaluation/runner.ts",
-    "clean": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true})\""
-  },
-  "keywords": [
-    "code-intelligence",
-    "knowledge-graph",
-    "static-analysis"
-  ],
-  "author": "",
-  "license": "MIT",
-  "dependencies": {
-    "@clack/prompts": "^1.3.0",
-    "commander": "^14.0.2",
-    "fast-string-width": "^3.0.2",
-    "fast-wrap-ansi": "^0.2.0",
-    "ignore": "^7.0.5",
-    "jsonc-parser": "^3.3.1",
-    "picomatch": "^4.0.3",
-    "sisteransi": "^1.0.5",
-    "tree-sitter-wasms": "^0.1.11",
-    "web-tree-sitter": "^0.25.3"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.0",
-    "@types/node": "^20.19.30",
-    "@types/picomatch": "^4.0.2",
-    "arkanalyzer": "^1.0.90",
-    "typescript": "^5.0.0",
-    "vitest": "^2.1.9"
-  },
-  "engines": {
-    "node": ">=20.0.0 <25.0.0"
-  }
-}
+{
+  "name": "homegraph",
+  "version": "1.1.3",
+  "description": "Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "homegraph": "./dist/bin/homegraph.js"
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && npm run copy-assets && node -e \"require('fs').chmodSync('dist/bin/homegraph.js', 0o755)\"",
+    "preuninstall": "node dist/bin/uninstall.js",
+    "copy-assets": "node -e \"const fs=require('fs');fs.mkdirSync('dist/db',{recursive:true});fs.copyFileSync('src/db/schema.sql','dist/db/schema.sql');fs.mkdirSync('dist/spec/db',{recursive:true});fs.copyFileSync('src/spec/db/schema.sql','dist/spec/db/schema.sql');fs.mkdirSync('dist/extraction/wasm',{recursive:true});fs.readdirSync('src/extraction/wasm').filter(f=>f.endsWith('.wasm')).forEach(f=>fs.copyFileSync('src/extraction/wasm/'+f,'dist/extraction/wasm/'+f))\"",
+    "dev": "tsc --watch",
+    "cli": "npm run build && node dist/bin/homegraph.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:eval": "vitest run __tests__/evaluation/",
+    "eval": "npm run build && npx tsx __tests__/evaluation/runner.ts",
+    "clean": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true})\""
+  },
+  "keywords": [
+    "code-intelligence",
+    "knowledge-graph",
+    "static-analysis"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.3.0",
+    "commander": "^14.0.2",
+    "fast-string-width": "^3.0.2",
+    "fast-wrap-ansi": "^0.2.0",
+    "ignore": "^7.0.5",
+    "jsonc-parser": "^3.3.1",
+    "picomatch": "^4.0.3",
+    "sisteransi": "^1.0.5",
+    "tree-sitter-wasms": "^0.1.11",
+    "web-tree-sitter": "^0.25.3",
+    "openai": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^20.19.30",
+    "@types/picomatch": "^4.0.2",
+    "arkanalyzer": "^1.0.90",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=20.0.0 <25.0.0"
+  }
+}

package/scripts/add-lang/bench.sh

@@ -1,60 +1,60 @@
-#!/usr/bin/env bash
-# Add-lang benchmark for ONE repo:
-#   clone -> wipe+index (with the homegraph on PATH) -> verify extraction ->
-#   with/without retrieval A/B (reuses scripts/agent-eval/run-all.sh).
-#
-# Assumes the homegraph dev build is already built + linked on PATH — the skill
-# runs `npm run build && ./scripts/local-install.sh` ONCE before looping repos.
-# The A/B is skipped if extraction fails its critical checks (don't burn $ on a
-# broken extractor); set FORCE_AB=1 to run it anyway.
-#
-# Usage: bench.sh <lang> <repo-name> <repo-url> "<question>" [headless|tmux|all]
-# Env:   CORPUS   corpus dir (default /tmp/homegraph-corpus, shared with agent-eval)
-set -uo pipefail
-
-LANG_TOKEN="${1:?usage: bench.sh <lang> <repo-name> <repo-url> \"<question>\" [mode]}"
-NAME="${2:?repo-name required}"
-URL="${3:?repo-url required}"
-Q="${4:?question required}"
-MODE="${5:-headless}"
-
-HARNESS="$(cd "$(dirname "$0")" && pwd)"
-AGENT_EVAL="$(cd "$HARNESS/../agent-eval" && pwd)"
-CORPUS="${CORPUS:-/tmp/homegraph-corpus}"
-REPO="$CORPUS/$NAME"
-
-command -v homegraph >/dev/null || { echo "no homegraph on PATH (build + ./scripts/local-install.sh first)"; exit 1; }
-
-echo "==================== add-lang bench: $NAME ($LANG_TOKEN) ===================="
-echo "homegraph: $(command -v homegraph) -> $(homegraph --version 2>/dev/null || echo '?')"
-
-# 1. Ensure the repo (shallow clone, reuse if present).
-mkdir -p "$CORPUS"
-if [ -d "$REPO/.git" ]; then
-  echo "→ reusing checkout: $REPO"
-else
-  echo "→ cloning $URL"
-  git clone --depth 1 "$URL" "$REPO" || { echo "git clone failed"; exit 1; }
-fi
-
-# 2. Wipe + index with the binary under test.
-echo "→ wiping .homegraph and indexing"
-rm -rf "$REPO/.homegraph"
-( cd "$REPO" && homegraph init -i ) || { echo "indexing failed"; exit 1; }
-
-# 3. Verify extraction (cheap guard before the paid A/B).
-echo "→ verifying extraction"
-node "$HARNESS/verify-extraction.mjs" "$REPO" "$LANG_TOKEN"
-VERIFY=$?
-
-# 4. Retrieval A/B (skipped if extraction is broken, unless FORCE_AB=1).
-if [ "$VERIFY" -ne 0 ] && [ "${FORCE_AB:-0}" != "1" ]; then
-  echo "→ SKIPPING A/B — extraction failed critical checks (set FORCE_AB=1 to override)"
-else
-  echo "→ retrieval A/B (mode=$MODE)"
-  bash "$AGENT_EVAL/run-all.sh" "$REPO" "$Q" "$MODE"
-fi
-
-echo "==================== bench complete: $NAME (verify exit=$VERIFY) ===================="
-# Exit reflects extraction: 0 = pass/warn, 1 = critical fail, 2 = couldn't read status.
-exit "$VERIFY"
+#!/usr/bin/env bash
+# Add-lang benchmark for ONE repo:
+#   clone -> wipe+index (with the homegraph on PATH) -> verify extraction ->
+#   with/without retrieval A/B (reuses scripts/agent-eval/run-all.sh).
+#
+# Assumes the homegraph dev build is already built + linked on PATH — the skill
+# runs `npm run build && ./scripts/local-install.sh` ONCE before looping repos.
+# The A/B is skipped if extraction fails its critical checks (don't burn $ on a
+# broken extractor); set FORCE_AB=1 to run it anyway.
+#
+# Usage: bench.sh <lang> <repo-name> <repo-url> "<question>" [headless|tmux|all]
+# Env:   CORPUS   corpus dir (default /tmp/homegraph-corpus, shared with agent-eval)
+set -uo pipefail
+
+LANG_TOKEN="${1:?usage: bench.sh <lang> <repo-name> <repo-url> \"<question>\" [mode]}"
+NAME="${2:?repo-name required}"
+URL="${3:?repo-url required}"
+Q="${4:?question required}"
+MODE="${5:-headless}"
+
+HARNESS="$(cd "$(dirname "$0")" && pwd)"
+AGENT_EVAL="$(cd "$HARNESS/../agent-eval" && pwd)"
+CORPUS="${CORPUS:-/tmp/homegraph-corpus}"
+REPO="$CORPUS/$NAME"
+
+command -v homegraph >/dev/null || { echo "no homegraph on PATH (build + ./scripts/local-install.sh first)"; exit 1; }
+
+echo "==================== add-lang bench: $NAME ($LANG_TOKEN) ===================="
+echo "homegraph: $(command -v homegraph) -> $(homegraph --version 2>/dev/null || echo '?')"
+
+# 1. Ensure the repo (shallow clone, reuse if present).
+mkdir -p "$CORPUS"
+if [ -d "$REPO/.git" ]; then
+  echo "→ reusing checkout: $REPO"
+else
+  echo "→ cloning $URL"
+  git clone --depth 1 "$URL" "$REPO" || { echo "git clone failed"; exit 1; }
+fi
+
+# 2. Wipe + index with the binary under test.
+echo "→ wiping .homegraph and indexing"
+rm -rf "$REPO/.homegraph"
+( cd "$REPO" && homegraph init -i ) || { echo "indexing failed"; exit 1; }
+
+# 3. Verify extraction (cheap guard before the paid A/B).
+echo "→ verifying extraction"
+node "$HARNESS/verify-extraction.mjs" "$REPO" "$LANG_TOKEN"
+VERIFY=$?
+
+# 4. Retrieval A/B (skipped if extraction is broken, unless FORCE_AB=1).
+if [ "$VERIFY" -ne 0 ] && [ "${FORCE_AB:-0}" != "1" ]; then
+  echo "→ SKIPPING A/B — extraction failed critical checks (set FORCE_AB=1 to override)"
+else
+  echo "→ retrieval A/B (mode=$MODE)"
+  bash "$AGENT_EVAL/run-all.sh" "$REPO" "$Q" "$MODE"
+fi
+
+echo "==================== bench complete: $NAME (verify exit=$VERIFY) ===================="
+# Exit reflects extraction: 0 = pass/warn, 1 = critical fail, 2 = couldn't read status.
+exit "$VERIFY"

package/scripts/add-lang/check-grammar.mjs

@@ -1,75 +1,75 @@
-#!/usr/bin/env node
-// Verify a tree-sitter grammar wasm is HEALTHY under the project's web-tree-sitter
-// runtime BEFORE writing an extractor. Prints the ABI version and parses a valid
-// sample many times in a multi-grammar context, to catch heap-corruption bugs
-// that silently drop nodes on every parse after the first.
-//
-// Why this exists: the tree-sitter-wasms Lua grammar is ABI 13 and corrupts the
-// shared WASM heap under web-tree-sitter 0.25 — Lua extraction degraded on every
-// file after the first (nested calls/imports vanished). The fix was to vendor the
-// upstream ABI-15 wasm. Run this on any new grammar first; if it FAILs, vendor a
-// newer build instead of using the tree-sitter-wasms one.
-//
-// Usage: node scripts/add-lang/check-grammar.mjs <lang|wasm-path> <valid-sample> [iterations]
-// Exit: 0 healthy, 1 corruption / parse errors, 2 could not run.
-// NOTE: the sample must be SYNTACTICALLY VALID — a broken sample fails for the
-//       wrong reason.
-
-import { readFileSync, existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { Parser, Language } from 'web-tree-sitter';
-
-const require = createRequire(import.meta.url);
-const fail = (code, msg) => { console.error(`[check-grammar] ${msg}`); process.exit(code); };
-
-const [token, sample, iterArg] = process.argv.slice(2);
-if (!token || !sample) fail(2, 'usage: check-grammar.mjs <lang|wasm-path> <valid-sample> [iterations]');
-if (!existsSync(sample)) fail(2, `sample not found: ${sample}`);
-const iters = iterArg ? parseInt(iterArg, 10) : 20;
-
-const SPECIAL = { csharp: 'c_sharp', 'c#': 'c_sharp' };
-function resolveWasm(t) {
-  if (t.endsWith('.wasm')) return existsSync(t) ? t : fail(2, `wasm not found: ${t}`);
-  const base = SPECIAL[t.toLowerCase()] ?? t.toLowerCase();
-  try { return require.resolve(`tree-sitter-wasms/out/tree-sitter-${base}.wasm`); } catch { /* try vendored */ }
-  const vendored = `src/extraction/wasm/tree-sitter-${base}.wasm`;
-  if (existsSync(vendored)) return vendored;
-  return fail(2, `no grammar for "${t}" — not in tree-sitter-wasms and not vendored`);
-}
-
-const wasmPath = resolveWasm(token);
-const source = readFileSync(sample, 'utf8');
-
-try { await Parser.init(); }
-catch { await Parser.init({ locateFile: () => require.resolve('web-tree-sitter/tree-sitter.wasm') }); }
-
-// Load a second, known-good grammar — the corruption surfaces under the
-// multi-grammar runtime that real indexing uses, not a single grammar in isolation.
-try { await Language.load(require.resolve('tree-sitter-wasms/out/tree-sitter-python.wasm')); } catch { /* ok */ }
-
-let language;
-try { language = await Language.load(wasmPath); }
-catch (e) { fail(2, `failed to load ${wasmPath}: ${e.message}`); }
-
-const parser = new Parser();
-parser.setLanguage(language);
-
-let ok = 0, err = 0;
-for (let i = 0; i < iters; i++) {
-  const tree = parser.parse(source);
-  if (tree.rootNode.hasError) err++; else ok++;
-}
-
-console.log(`grammar: ${wasmPath.split('/').pop()}`);
-console.log(`  ABI version: ${language.abiVersion}`);
-console.log(`  parses: ${ok} clean / ${err} with errors (of ${iters})`);
-if (err > 0) {
-  console.log(
-    `RESULT: FAIL — ${err}/${iters} parses produced ERROR trees on a valid sample. ` +
-    `This grammar corrupts under web-tree-sitter; vendor a newer (ABI 14/15) wasm ` +
-    `(see SKILL.md "Find a grammar"). Confirm your sample is syntactically valid first.`
-  );
-  process.exit(1);
-}
-console.log('RESULT: PASS — grammar parses cleanly and reuses safely.');
-process.exit(0);
+#!/usr/bin/env node
+// Verify a tree-sitter grammar wasm is HEALTHY under the project's web-tree-sitter
+// runtime BEFORE writing an extractor. Prints the ABI version and parses a valid
+// sample many times in a multi-grammar context, to catch heap-corruption bugs
+// that silently drop nodes on every parse after the first.
+//
+// Why this exists: the tree-sitter-wasms Lua grammar is ABI 13 and corrupts the
+// shared WASM heap under web-tree-sitter 0.25 — Lua extraction degraded on every
+// file after the first (nested calls/imports vanished). The fix was to vendor the
+// upstream ABI-15 wasm. Run this on any new grammar first; if it FAILs, vendor a
+// newer build instead of using the tree-sitter-wasms one.
+//
+// Usage: node scripts/add-lang/check-grammar.mjs <lang|wasm-path> <valid-sample> [iterations]
+// Exit: 0 healthy, 1 corruption / parse errors, 2 could not run.
+// NOTE: the sample must be SYNTACTICALLY VALID — a broken sample fails for the
+//       wrong reason.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { Parser, Language } from 'web-tree-sitter';
+
+const require = createRequire(import.meta.url);
+const fail = (code, msg) => { console.error(`[check-grammar] ${msg}`); process.exit(code); };
+
+const [token, sample, iterArg] = process.argv.slice(2);
+if (!token || !sample) fail(2, 'usage: check-grammar.mjs <lang|wasm-path> <valid-sample> [iterations]');
+if (!existsSync(sample)) fail(2, `sample not found: ${sample}`);
+const iters = iterArg ? parseInt(iterArg, 10) : 20;
+
+const SPECIAL = { csharp: 'c_sharp', 'c#': 'c_sharp' };
+function resolveWasm(t) {
+  if (t.endsWith('.wasm')) return existsSync(t) ? t : fail(2, `wasm not found: ${t}`);
+  const base = SPECIAL[t.toLowerCase()] ?? t.toLowerCase();
+  try { return require.resolve(`tree-sitter-wasms/out/tree-sitter-${base}.wasm`); } catch { /* try vendored */ }
+  const vendored = `src/extraction/wasm/tree-sitter-${base}.wasm`;
+  if (existsSync(vendored)) return vendored;
+  return fail(2, `no grammar for "${t}" — not in tree-sitter-wasms and not vendored`);
+}
+
+const wasmPath = resolveWasm(token);
+const source = readFileSync(sample, 'utf8');
+
+try { await Parser.init(); }
+catch { await Parser.init({ locateFile: () => require.resolve('web-tree-sitter/tree-sitter.wasm') }); }
+
+// Load a second, known-good grammar — the corruption surfaces under the
+// multi-grammar runtime that real indexing uses, not a single grammar in isolation.
+try { await Language.load(require.resolve('tree-sitter-wasms/out/tree-sitter-python.wasm')); } catch { /* ok */ }
+
+let language;
+try { language = await Language.load(wasmPath); }
+catch (e) { fail(2, `failed to load ${wasmPath}: ${e.message}`); }
+
+const parser = new Parser();
+parser.setLanguage(language);
+
+let ok = 0, err = 0;
+for (let i = 0; i < iters; i++) {
+  const tree = parser.parse(source);
+  if (tree.rootNode.hasError) err++; else ok++;
+}
+
+console.log(`grammar: ${wasmPath.split('/').pop()}`);
+console.log(`  ABI version: ${language.abiVersion}`);
+console.log(`  parses: ${ok} clean / ${err} with errors (of ${iters})`);
+if (err > 0) {
+  console.log(
+    `RESULT: FAIL — ${err}/${iters} parses produced ERROR trees on a valid sample. ` +
+    `This grammar corrupts under web-tree-sitter; vendor a newer (ABI 14/15) wasm ` +
+    `(see SKILL.md "Find a grammar"). Confirm your sample is syntactically valid first.`
+  );
+  process.exit(1);
+}
+console.log('RESULT: PASS — grammar parses cleanly and reuses safely.');
+process.exit(0);

package/scripts/add-lang/dump-ast.mjs

@@ -1,103 +1,103 @@
-#!/usr/bin/env node
-// Dump the tree-sitter AST for a sample file so you can write a LanguageExtractor
-// mapping. Loads a grammar .wasm directly via web-tree-sitter (the same runtime
-// homegraph uses) — you do NOT need to register the language first.
-//
-// Usage:
-//   node scripts/add-lang/dump-ast.mjs <lang|wasm-path> <sample-file> [--depth=N] [--full]
-// Examples:
-//   node scripts/add-lang/dump-ast.mjs lua sample.lua
-//   node scripts/add-lang/dump-ast.mjs src/extraction/wasm/tree-sitter-zig.wasm a.zig --depth=4
-//
-// Output: an indented AST (named nodes, with field names) followed by a
-// node-type FREQUENCY table. The frequency table is the payoff — it tells you
-// which node types to map to functionTypes / classTypes / importTypes / etc.
-
-import { readFileSync, existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { Parser, Language } from 'web-tree-sitter';
-
-const require = createRequire(import.meta.url);
-const fail = (msg) => { console.error(`[dump-ast] ${msg}`); process.exit(1); };
-
-const argv = process.argv.slice(2);
-const positional = argv.filter((a) => !a.startsWith('--'));
-const [langOrWasm, sampleFile] = positional;
-const depthFlag = argv.find((a) => a.startsWith('--depth='));
-const showAll = argv.includes('--full'); // also print anonymous (token) nodes
-const maxDepth = depthFlag ? parseInt(depthFlag.split('=')[1], 10) : (showAll ? Infinity : 8);
-
-if (!langOrWasm || !sampleFile) {
-  fail('usage: dump-ast.mjs <lang|wasm-path> <sample-file> [--depth=N] [--full]');
-}
-if (!existsSync(sampleFile)) fail(`sample file not found: ${sampleFile}`);
-
-// Language tokens whose tree-sitter-wasms filename differs from the token.
-const WASM_SPECIAL = { csharp: 'c_sharp', 'c#': 'c_sharp' };
-
-function resolveWasm(token) {
-  if (token.endsWith('.wasm')) {
-    if (!existsSync(token)) fail(`wasm not found: ${token}`);
-    return token;
-  }
-  const base = WASM_SPECIAL[token.toLowerCase()] ?? token.toLowerCase();
-  try {
-    return require.resolve(`tree-sitter-wasms/out/tree-sitter-${base}.wasm`);
-  } catch {
-    /* not in tree-sitter-wasms — try a vendored copy */
-  }
-  const vendored = `src/extraction/wasm/tree-sitter-${base}.wasm`;
-  if (existsSync(vendored)) return vendored;
-  fail(
-    `no grammar for "${token}" — not in tree-sitter-wasms and not vendored at ` +
-      `${vendored}. Pass an explicit .wasm path, or vendor one (see SKILL.md "Find a grammar").`
-  );
-}
-
-const wasmPath = resolveWasm(langOrWasm);
-const source = readFileSync(sampleFile, 'utf8');
-
-try {
-  await Parser.init();
-} catch {
-  await Parser.init({ locateFile: () => require.resolve('web-tree-sitter/tree-sitter.wasm') });
-}
-
-let language;
-try {
-  language = await Language.load(wasmPath);
-} catch (e) {
-  fail(`failed to load grammar ${wasmPath}: ${e.message}`);
-}
-
-const parser = new Parser();
-parser.setLanguage(language);
-const tree = parser.parse(source);
-
-const freq = new Map();
-const snippet = (node) => {
-  const t = node.text.replace(/\s+/g, ' ').trim();
-  return t.length > 48 ? `${t.slice(0, 48)}…` : t;
-};
-
-function walk(node, depth, fieldName) {
-  if (node.isNamed) freq.set(node.type, (freq.get(node.type) || 0) + 1);
-  if ((node.isNamed || showAll) && depth <= maxDepth) {
-    const field = fieldName ? `${fieldName}: ` : '';
-    const leaf = node.childCount === 0 ? `  "${snippet(node)}"` : '';
-    console.log(`${'  '.repeat(depth)}${field}${node.type}  @${node.startPosition.row + 1}:${node.startPosition.column}${leaf}`);
-  }
-  for (let i = 0; i < node.childCount; i++) {
-    const child = node.child(i);
-    if (child) walk(child, depth + 1, node.fieldNameForChild(i));
-  }
-}
-
-console.log(`\n# AST for ${sampleFile}  (grammar: ${wasmPath.split('/').pop()})\n`);
-walk(tree.rootNode, 0, null);
-
-console.log('\n# Node-type frequency (named nodes) — map the relevant ones in your extractor:\n');
-[...freq.entries()]
-  .sort((a, b) => b[1] - a[1])
-  .forEach(([type, n]) => console.log(`  ${String(n).padStart(5)}  ${type}`));
-console.log();
+#!/usr/bin/env node
+// Dump the tree-sitter AST for a sample file so you can write a LanguageExtractor
+// mapping. Loads a grammar .wasm directly via web-tree-sitter (the same runtime
+// homegraph uses) — you do NOT need to register the language first.
+//
+// Usage:
+//   node scripts/add-lang/dump-ast.mjs <lang|wasm-path> <sample-file> [--depth=N] [--full]
+// Examples:
+//   node scripts/add-lang/dump-ast.mjs lua sample.lua
+//   node scripts/add-lang/dump-ast.mjs src/extraction/wasm/tree-sitter-zig.wasm a.zig --depth=4
+//
+// Output: an indented AST (named nodes, with field names) followed by a
+// node-type FREQUENCY table. The frequency table is the payoff — it tells you
+// which node types to map to functionTypes / classTypes / importTypes / etc.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { Parser, Language } from 'web-tree-sitter';
+
+const require = createRequire(import.meta.url);
+const fail = (msg) => { console.error(`[dump-ast] ${msg}`); process.exit(1); };
+
+const argv = process.argv.slice(2);
+const positional = argv.filter((a) => !a.startsWith('--'));
+const [langOrWasm, sampleFile] = positional;
+const depthFlag = argv.find((a) => a.startsWith('--depth='));
+const showAll = argv.includes('--full'); // also print anonymous (token) nodes
+const maxDepth = depthFlag ? parseInt(depthFlag.split('=')[1], 10) : (showAll ? Infinity : 8);
+
+if (!langOrWasm || !sampleFile) {
+  fail('usage: dump-ast.mjs <lang|wasm-path> <sample-file> [--depth=N] [--full]');
+}
+if (!existsSync(sampleFile)) fail(`sample file not found: ${sampleFile}`);
+
+// Language tokens whose tree-sitter-wasms filename differs from the token.
+const WASM_SPECIAL = { csharp: 'c_sharp', 'c#': 'c_sharp' };
+
+function resolveWasm(token) {
+  if (token.endsWith('.wasm')) {
+    if (!existsSync(token)) fail(`wasm not found: ${token}`);
+    return token;
+  }
+  const base = WASM_SPECIAL[token.toLowerCase()] ?? token.toLowerCase();
+  try {
+    return require.resolve(`tree-sitter-wasms/out/tree-sitter-${base}.wasm`);
+  } catch {
+    /* not in tree-sitter-wasms — try a vendored copy */
+  }
+  const vendored = `src/extraction/wasm/tree-sitter-${base}.wasm`;
+  if (existsSync(vendored)) return vendored;
+  fail(
+    `no grammar for "${token}" — not in tree-sitter-wasms and not vendored at ` +
+      `${vendored}. Pass an explicit .wasm path, or vendor one (see SKILL.md "Find a grammar").`
+  );
+}
+
+const wasmPath = resolveWasm(langOrWasm);
+const source = readFileSync(sampleFile, 'utf8');
+
+try {
+  await Parser.init();
+} catch {
+  await Parser.init({ locateFile: () => require.resolve('web-tree-sitter/tree-sitter.wasm') });
+}
+
+let language;
+try {
+  language = await Language.load(wasmPath);
+} catch (e) {
+  fail(`failed to load grammar ${wasmPath}: ${e.message}`);
+}
+
+const parser = new Parser();
+parser.setLanguage(language);
+const tree = parser.parse(source);
+
+const freq = new Map();
+const snippet = (node) => {
+  const t = node.text.replace(/\s+/g, ' ').trim();
+  return t.length > 48 ? `${t.slice(0, 48)}…` : t;
+};
+
+function walk(node, depth, fieldName) {
+  if (node.isNamed) freq.set(node.type, (freq.get(node.type) || 0) + 1);
+  if ((node.isNamed || showAll) && depth <= maxDepth) {
+    const field = fieldName ? `${fieldName}: ` : '';
+    const leaf = node.childCount === 0 ? `  "${snippet(node)}"` : '';
+    console.log(`${'  '.repeat(depth)}${field}${node.type}  @${node.startPosition.row + 1}:${node.startPosition.column}${leaf}`);
+  }
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) walk(child, depth + 1, node.fieldNameForChild(i));
+  }
+}
+
+console.log(`\n# AST for ${sampleFile}  (grammar: ${wasmPath.split('/').pop()})\n`);
+walk(tree.rootNode, 0, null);
+
+console.log('\n# Node-type frequency (named nodes) — map the relevant ones in your extractor:\n');
+[...freq.entries()]
+  .sort((a, b) => b[1] - a[1])
+  .forEach(([type, n]) => console.log(`  ${String(n).padStart(5)}  ${type}`));
+console.log();