@davesheffer/hunch 0.1.0

package/dist/extractors/git.js

@@ -0,0 +1,136 @@
+/** Deterministic git introspection for the extractor + learning loop.
+ *  No LLM here — just parsing what git already knows. */
+import { execFileSync } from "node:child_process";
+function git(args, cwd) {
+    // stdio: capture stdout, silence stderr (so "no commits yet" etc. don't leak).
+    return execFileSync("git", args, {
+        cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+function gitSafe(args, cwd) {
+    try {
+        return git(args, cwd);
+    }
+    catch {
+        return "";
+    }
+}
+export function isGitRepo(cwd) {
+    return gitSafe(["rev-parse", "--is-inside-work-tree"], cwd) === "true";
+}
+export function headSha(cwd) {
+    return gitSafe(["rev-parse", "HEAD"], cwd);
+}
+/** Resolve any commit-ish (short sha / HEAD / branch) to a canonical full sha.
+ *  Returns the input unchanged if it can't be resolved (e.g. not a git repo). */
+export function revParse(ref, cwd) {
+    const r = ref.trim();
+    return gitSafe(["rev-parse", "--verify", "--quiet", r], cwd) || r;
+}
+/** Path to the hooks dir (honors core.hooksPath / worktrees). */
+export function hooksDir(cwd) {
+    const p = gitSafe(["rev-parse", "--git-path", "hooks"], cwd);
+    return p || ".git/hooks";
+}
+export function gitDir(cwd) {
+    return gitSafe(["rev-parse", "--git-dir"], cwd) || ".git";
+}
+/** Files changed in a single commit. `--root` makes the initial commit (which
+ *  has no parent) report its files as additions instead of returning nothing. */
+export function commitFiles(sha, cwd) {
+    const out = gitSafe(["diff-tree", "--no-commit-id", "--name-only", "-r", "--root", sha], cwd);
+    return out ? out.split("\n").filter(Boolean) : [];
+}
+/** Full metadata + changed files for a commit. */
+export function commitMeta(sha, cwd) {
+    const raw = gitSafe(["show", "-s", "--format=%H%x1f%h%x1f%s%x1f%b%x1f%an%x1f%aI", sha], cwd);
+    if (!raw)
+        return null;
+    const [full = "", short = "", subject = "", body = "", author = "", date = ""] = raw.split("\x1f");
+    return { sha: full, shortSha: short, subject, body, author, date, files: commitFiles(sha, cwd) };
+}
+/** Machine-generated paths that carry no design "why" — lockfiles, build output,
+ *  vendored deps, snapshots, source maps. Excluded from synthesis diffs via git
+ *  pathspec BEFORE git assembles/orders the patch: a huge lockfile sorts ahead of
+ *  src/ alphabetically and would otherwise eat the byte budget and truncate the
+ *  real code change away. Exclude-only pathspecs are valid; `**` (glob magic)
+ *  matches across directories AND at the repo root. (`*.lock` covers yarn / cargo
+ *  / poetry / composer / Gemfile lockfiles.) */
+const DIFF_NOISE = [
+    ":(exclude,glob)**/package-lock.json",
+    ":(exclude,glob)**/npm-shrinkwrap.json",
+    ":(exclude,glob)**/pnpm-lock.yaml",
+    ":(exclude,glob)**/go.sum",
+    ":(exclude,glob)**/*.lock",
+    ":(exclude,glob)**/dist/**",
+    ":(exclude,glob)**/build/**",
+    ":(exclude,glob)**/out/**",
+    ":(exclude,glob)**/coverage/**",
+    ":(exclude,glob)**/.next/**",
+    ":(exclude,glob)**/node_modules/**",
+    ":(exclude,glob)**/vendor/**",
+    // the Hunch's OWN machine-generated records — re-synthesizing a commit that
+    // wrote them would be circular noise, and they're large (JSON per record).
+    ":(exclude,glob)**/.hunch/**",
+    ":(exclude,glob)**/*.min.js",
+    ":(exclude,glob)**/*.map",
+    ":(exclude,glob)**/*.snap",
+    ":(exclude,glob)**/__snapshots__/**",
+    ":(exclude,glob)**/*.generated.*",
+];
+/** The unified diff for a commit, truncated to keep synthesis prompts bounded.
+ *  Machine-generated noise (see DIFF_NOISE) is excluded so the model spends its
+ *  budget on code that encodes intent, not on regenerated lockfiles/build output. */
+export function commitDiff(sha, cwd, maxBytes = 60_000) {
+    const out = gitSafe(["show", sha, "--no-color", "--format=", "--unified=2", "--", ...DIFF_NOISE], cwd);
+    return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
+}
+/** Number of commits touching a file in the last `days` (churn). */
+export function fileChurn(file, cwd, days = 90) {
+    const out = gitSafe(["log", `--since=${days}.days.ago`, "--oneline", "--", file], cwd);
+    return out ? out.split("\n").filter(Boolean).length : 0;
+}
+/** The most recent commit short-sha that touched a file. */
+export function lastCommitForFile(file, cwd) {
+    const sha = gitSafe(["log", "-1", "--format=%h", "--", file], cwd);
+    return sha ? `commit:${sha}` : "";
+}
+/** ISO author-date of the most recent commit touching a file ("" if none). */
+export function lastChangeDate(file, cwd) {
+    return gitSafe(["log", "-1", "--format=%aI", "--", file], cwd);
+}
+/** Files staged for commit (for `hunch check` pre-commit enforcement). */
+export function stagedFiles(cwd) {
+    const out = gitSafe(["diff", "--cached", "--name-only", "--diff-filter=ACMR"], cwd);
+    return out ? out.split("\n").filter(Boolean) : [];
+}
+/** Translate a backfill window spec into git-log window args.
+ *   "90d" / bare "90" -> last 90 days   |   "40c" -> last 40 commits
+ *   anything else      -> passed to --since as an approxidate/date string. */
+function windowArgs(spec, max) {
+    if (/^\d+c$/i.test(spec))
+        return ["-n", spec.replace(/c$/i, "")];
+    if (/^\d+d$/i.test(spec))
+        return [`--since=${spec.replace(/d$/i, "")} days ago`, "-n", String(max)];
+    if (/^\d+$/.test(spec))
+        return [`--since=${spec} days ago`, "-n", String(max)];
+    return [`--since=${spec}`, "-n", String(max)];
+}
+/** Recent commits (newest-first) for backfill. */
+export function logSince(spec, cwd, max = 200) {
+    const out = gitSafe(["log", ...windowArgs(spec, max), "--format=%H"], cwd);
+    return out ? out.split("\n").filter(Boolean) : [];
+}
+/** Commits that look like bug fixes (for backfill bug seeding). */
+export function fixCommits(spec, cwd, max = 200) {
+    const out = gitSafe(["log", ...windowArgs(spec, max), "--format=%H", "--grep=fix", "--grep=bug", "--grep=hotfix", "-i"], cwd);
+    return out ? out.split("\n").filter(Boolean) : [];
+}
+/** All tracked files matching the given extensions. */
+export function trackedFiles(cwd, exts) {
+    const out = gitSafe(["ls-files"], cwd);
+    const all = out ? out.split("\n").filter(Boolean) : [];
+    return all.filter((f) => exts.some((e) => f.endsWith(e)));
+}
+//# sourceMappingURL=git.js.map

package/dist/extractors/indexer.js

@@ -0,0 +1,271 @@
+/**
+ * The indexer (DESIGN.md §4 "File changes" row, and `hunch index`).
+ * Deterministic, no LLM: walk the repo, parse every TS/JS file into symbols,
+ * resolve a best-effort call graph + import dependency graph, derive components
+ * from the directory layout, and compute churn / fan-in / fan-out metrics.
+ *
+ * Writes Symbol/Edge/Component records to the JSON source of truth. The caller
+ * then runs HunchStore.reindex() to refresh the SQLite index.
+ */
+import { readFileSync, statSync, readdirSync } from "node:fs";
+import { join, relative, dirname, posix } from "node:path";
+import { parseSource, attributeCalls } from "./parse.js";
+import { symbolId, componentId, edgeId, sha1 } from "../core/ids.js";
+import { extracted, inferred } from "../core/types.js";
+import { isGitRepo, trackedFiles, fileChurn, lastCommitForFile } from "./git.js";
+const CODE_EXTS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".hunch", "coverage", ".next", "out"]);
+export function indexRepo(store, root, opts = {}) {
+    const files = listCodeFiles(root);
+    const useGit = isGitRepo(root);
+    // ---- pass 1: parse files -> symbols, remember per-file calls & imports ----
+    const symbols = [];
+    const nameIndex = new Map(); // symbol name -> [symbol ids]
+    const fileSymbols = new Map(); // file -> symbol ids (in-file resolution)
+    const fileStartByteId = new Map(); // file -> (symbol startByte -> id)
+    const perFileCalls = [];
+    const perFileImports = [];
+    const churnCache = new Map();
+    let skipped = 0;
+    for (const abs of files) {
+        const rel = toPosix(relative(root, abs));
+        let src;
+        try {
+            src = readFileSync(abs, "utf8");
+        }
+        catch {
+            skipped++;
+            continue;
+        }
+        // one bad/oversized file must never abort the whole index run
+        let parsed;
+        try {
+            parsed = parseSource(rel, src);
+        }
+        catch {
+            skipped++;
+            continue;
+        }
+        if (!parsed) {
+            skipped++;
+            continue;
+        }
+        const churn = opts.churn !== false && useGit ? (churnCache.get(rel) ?? fileChurn(rel, root)) : 0;
+        churnCache.set(rel, churn);
+        const last = useGit ? lastCommitForFile(rel, root) : "";
+        const idsInFile = [];
+        const startByteId = new Map();
+        const idCounts = new Map(); // disambiguate same (file,name,kind)
+        for (const ps of parsed.symbols) {
+            const base = symbolId(rel, ps.name, ps.kind);
+            const n = idCounts.get(base) ?? 0;
+            idCounts.set(base, n + 1);
+            // parse() returns symbols sorted by start byte, so the ordinal is stable
+            const id = n === 0 ? base : `${base}_${n}`;
+            idsInFile.push(id);
+            startByteId.set(ps.startByte, id);
+            (nameIndex.get(ps.name) ?? nameIndex.set(ps.name, []).get(ps.name)).push(id);
+            symbols.push({
+                id, file: rel, name: ps.name, kind: ps.kind,
+                signature_hash: sha1(ps.bodyText).slice(0, 16),
+                calls: [], called_by: [],
+                metrics: { loc: ps.loc, churn_90d: churn, bug_count: 0, fan_in: 0, fan_out: 0 },
+                last_changed: last,
+            });
+        }
+        fileSymbols.set(rel, idsInFile);
+        fileStartByteId.set(rel, startByteId);
+        perFileCalls.push({ file: rel, bySym: attributeCalls(parsed) });
+        perFileImports.push({ file: rel, imports: parsed.imports });
+    }
+    const byId = new Map(symbols.map((s) => [s.id, s]));
+    // ---- pass 2: resolve calls -> symbol-level edges -------------------------
+    const edges = [];
+    const edgeSeen = new Set();
+    const addEdge = (e) => {
+        if (edgeSeen.has(e.id))
+            return;
+        edgeSeen.add(e.id);
+        edges.push(e);
+    };
+    for (const { file, bySym } of perFileCalls) {
+        const sbToId = fileStartByteId.get(file) ?? new Map();
+        for (const [callerStartByte, callees] of bySym) {
+            // resolve caller by its stable byte-offset identity (not name)
+            const callerId = sbToId.get(callerStartByte);
+            if (!callerId)
+                continue;
+            const callerName = byId.get(callerId)?.name ?? "?";
+            for (const [calleeName, memberOnly] of callees) {
+                const calleeId = resolveName(calleeName, file, nameIndex, byId);
+                if (!calleeId || calleeId === callerId)
+                    continue;
+                // A member call `x.foo()` only yields an edge when `foo` resolves to a
+                // method or a same-file symbol — not a coincidentally-named top-level fn.
+                if (memberOnly) {
+                    const sym = byId.get(calleeId);
+                    if (!sym || (sym.kind !== "method" && sym.file !== file))
+                        continue;
+                }
+                addEdge({
+                    id: edgeId(callerId, calleeId, "calls"),
+                    from: callerId, to: calleeId, type: "calls",
+                    reason: `${callerName} calls ${calleeName}`, strength: 0.8,
+                    provenance: extracted(0.8, [file]),
+                });
+            }
+        }
+    }
+    // fan-in / fan-out from resolved call edges
+    for (const e of edges) {
+        if (e.type !== "calls")
+            continue;
+        const from = byId.get(e.from);
+        const to = byId.get(e.to);
+        if (from) {
+            from.metrics.fan_out++;
+            from.calls.push(e.to);
+        }
+        if (to) {
+            to.metrics.fan_in++;
+            to.called_by.push(e.from);
+        }
+    }
+    // ---- pass 3: components from directory layout + import dep edges ----------
+    const components = deriveComponents(symbols);
+    const fileToComponent = new Map();
+    for (const c of components)
+        for (const f of c._files)
+            fileToComponent.set(f, c.id);
+    for (const { file, imports } of perFileImports) {
+        const fromCmp = fileToComponent.get(file);
+        if (!fromCmp)
+            continue;
+        for (const spec of imports) {
+            const target = resolveImport(file, spec, fileSymbols);
+            if (!target)
+                continue;
+            const toCmp = fileToComponent.get(target);
+            if (!toCmp || toCmp === fromCmp)
+                continue;
+            addEdge({
+                id: edgeId(fromCmp, toCmp, "depends_on"),
+                from: fromCmp, to: toCmp, type: "depends_on",
+                reason: `${file} imports ${target}`, strength: 0.6,
+                provenance: extracted(0.9, [`${file}:imports:${spec}`]),
+            });
+        }
+    }
+    // persist
+    store.json.replaceAll("symbols", symbols);
+    store.json.replaceAll("edges", edges);
+    const compsOut = components.map(({ _files, ...c }) => c);
+    store.json.replaceAll("components", compsOut);
+    return { files: files.length, symbols: symbols.length, edges: edges.length, components: compsOut.length, skipped };
+}
+// ---- helpers --------------------------------------------------------------
+function listCodeFiles(root) {
+    if (isGitRepo(root)) {
+        const tracked = trackedFiles(root, CODE_EXTS).map((f) => join(root, f));
+        if (tracked.length > 0)
+            return tracked; // else fall through (nothing committed yet)
+    }
+    const out = [];
+    const walk = (dir) => {
+        for (const name of readdirSync(dir)) {
+            if (SKIP_DIRS.has(name))
+                continue;
+            const abs = join(dir, name);
+            const st = statSync(abs);
+            if (st.isDirectory())
+                walk(abs);
+            else if (CODE_EXTS.some((e) => name.endsWith(e)))
+                out.push(abs);
+        }
+    };
+    walk(root);
+    return out;
+}
+/** Resolve a callee name to a symbol id: prefer same-file, else unique global. */
+function resolveName(name, file, nameIndex, byId) {
+    const candidates = nameIndex.get(name);
+    if (!candidates || candidates.length === 0)
+        return null;
+    const sameFile = candidates.filter((id) => byId.get(id)?.file === file);
+    if (sameFile.length === 1)
+        return sameFile[0];
+    if (sameFile.length > 1)
+        return null; // ambiguous within the file — don't guess
+    if (candidates.length === 1)
+        return candidates[0];
+    // ambiguous across files — skip to avoid wrong edges (keeps the graph clean)
+    return null;
+}
+/** Resolve a relative import specifier to a concrete tracked file path. */
+function resolveImport(fromFile, spec, fileSymbols) {
+    if (!spec.startsWith("."))
+        return null; // external package
+    const base = toPosix(join(dirname(fromFile), spec));
+    // Prefer TS source rewrites over the literal `.js` specifier: in a TS repo an
+    // import of "./db.js" resolves to db.ts. Only fall back to the literal path.
+    const candidates = [
+        base.replace(/\.js$/, ".ts"),
+        base.replace(/\.js$/, ".tsx"),
+        base.replace(/\.jsx$/, ".tsx"),
+        base + ".ts",
+        base + ".tsx",
+        base,
+        base + ".js",
+        toPosix(join(base, "index.ts")),
+        toPosix(join(base, "index.tsx")),
+        toPosix(join(base, "index.js")),
+    ];
+    for (const c of candidates)
+        if (fileSymbols.has(c))
+            return c;
+    return null;
+}
+/** Derive components from the directory layout: the directory immediately under
+ *  `src/` (or the top-level dir) groups files into a module component. */
+function deriveComponents(symbols) {
+    const groups = new Map(); // dir key -> files
+    for (const s of symbols) {
+        const key = componentDir(s.file);
+        (groups.get(key) ?? groups.set(key, new Set()).get(key)).add(s.file);
+    }
+    const now = new Date().toISOString();
+    const out = [];
+    for (const [dir, fileSet] of groups) {
+        const name = dir.split("/").filter(Boolean).pop() ?? dir;
+        out.push({
+            id: componentId(dir),
+            kind: "module",
+            name: capitalize(name),
+            responsibility: "",
+            paths: [dir.endsWith("/") ? dir + "**" : dir + "/**"],
+            status: "active",
+            owners: [],
+            fragility: 0,
+            provenance: inferred(0.5, [dir]),
+            created_at: now,
+            updated_at: now,
+            _files: [...fileSet],
+        });
+    }
+    return out;
+}
+function componentDir(file) {
+    const parts = file.split("/");
+    if (parts[0] === "src" && parts.length > 2)
+        return `src/${parts[1]}`;
+    if (parts.length > 1)
+        return parts[0];
+    return ".";
+}
+function capitalize(s) {
+    return s.length ? s[0].toUpperCase() + s.slice(1) : s;
+}
+function toPosix(p) {
+    return p.split(/[\\/]/).join(posix.sep);
+}
+//# sourceMappingURL=indexer.js.map

package/dist/extractors/parse.js

@@ -0,0 +1,176 @@
+/**
+ * Deterministic tree-sitter parsing (no LLM). Extracts, per file:
+ *   - symbols: functions, methods, classes, interfaces, types, arrow-fn consts
+ *   - imports: module specifiers (for dependency edges)
+ *   - calls:   callee names + byte offset (mapped to the enclosing symbol)
+ *
+ * Uses NATIVE tree-sitter (synchronous, prebuilt for Node 20 — see decision in
+ * the commit history; web-tree-sitter's WASM grammars had an incompatible ABI).
+ */
+import Parser from "tree-sitter";
+import TS from "tree-sitter-typescript";
+const { typescript, tsx } = TS;
+/** Extremely common builtin/array/object/string/promise method names. Member
+ *  calls to these (e.g. `arr.map(...)`) must NOT create call edges to unrelated
+ *  repo symbols that happen to share the name (DESIGN: keep the graph clean). */
+const BUILTIN_METHODS = new Set([
+    "map", "filter", "forEach", "reduce", "find", "findIndex", "some", "every", "includes",
+    "push", "pop", "shift", "unshift", "slice", "splice", "concat", "join", "split", "flat", "flatMap",
+    "indexOf", "lastIndexOf", "keys", "values", "entries", "sort", "reverse", "fill", "at",
+    "get", "set", "has", "add", "delete", "clear",
+    "then", "catch", "finally", "all", "race", "resolve", "reject",
+    "toString", "valueOf", "toJSON", "hasOwnProperty",
+    "replace", "replaceAll", "trim", "trimStart", "trimEnd", "padStart", "padEnd", "startsWith", "endsWith",
+    "toLowerCase", "toUpperCase", "charAt", "charCodeAt", "substring", "substr", "repeat", "match", "matchAll",
+    "call", "apply", "bind", "test", "exec", "now", "parse", "stringify", "from", "of", "isArray", "assign",
+    "log", "error", "warn", "info", "debug",
+]);
+/** Tree-sitter query capturing every construct we care about in one pass. */
+const QUERY_SRC = `
+  (function_declaration name: (identifier) @fn.name) @fn.def
+  (generator_function_declaration name: (identifier) @fn.name) @fn.def
+  (method_definition name: (property_identifier) @method.name) @method.def
+  (class_declaration name: (type_identifier) @class.name) @class.def
+  (interface_declaration name: (type_identifier) @iface.name) @iface.def
+  (type_alias_declaration name: (type_identifier) @type.name) @type.def
+  (variable_declarator
+     name: (identifier) @arrow.name
+     value: [(arrow_function) (function_expression)]) @arrow.def
+  (import_statement source: (string) @import.src)
+  (call_expression function: (identifier) @call.id)
+  (call_expression function: (member_expression property: (property_identifier) @call.member))
+`;
+const cache = new Map();
+function bundleFor(lang, key) {
+    let b = cache.get(key);
+    if (!b) {
+        const parser = new Parser();
+        parser.setLanguage(lang);
+        const query = new Parser.Query(lang, QUERY_SRC);
+        b = { parser, query };
+        cache.set(key, b);
+    }
+    return b;
+}
+function pickLanguage(file) {
+    if (file.endsWith(".tsx") || file.endsWith(".jsx"))
+        return { lang: tsx, key: "tsx" };
+    if (file.endsWith(".ts") || file.endsWith(".mts") || file.endsWith(".cts"))
+        return { lang: typescript, key: "ts" };
+    if (file.endsWith(".js") || file.endsWith(".mjs") || file.endsWith(".cjs"))
+        return { lang: typescript, key: "ts" };
+    return null;
+}
+const STR_QUOTES = /^['"`]|['"`]$/g;
+export function parseSource(file, source) {
+    const picked = pickLanguage(file);
+    if (!picked)
+        return null;
+    const { parser, query } = bundleFor(picked.lang, picked.key);
+    // The native binding caps its scratch buffer at 32 KB unless bufferSize is
+    // given — without this, any source >= 32768 bytes throws "Invalid argument"
+    // and would abort the whole index run. Guard with try/catch as a backstop.
+    let tree;
+    try {
+        tree = parser.parse(source, undefined, { bufferSize: Math.max(32 * 1024, source.length * 2 + 1024) });
+    }
+    catch {
+        return null;
+    }
+    const symbols = [];
+    const imports = [];
+    const calls = [];
+    // group captures by their enclosing @*.def via a quick pass: we record names
+    // keyed by the def node, then emit a symbol per def.
+    const pendingDefs = new Map();
+    const defKind = {
+        "fn.def": "function", "method.def": "method", "class.def": "class",
+        "iface.def": "interface", "type.def": "type", "arrow.def": "function",
+    };
+    const nameToDef = {
+        "fn.name": "fn.def", "method.name": "method.def", "class.name": "class.def",
+        "iface.name": "iface.def", "type.name": "type.def", "arrow.name": "arrow.def",
+    };
+    for (const cap of query.captures(tree.rootNode)) {
+        const cname = cap.name;
+        const node = cap.node;
+        if (cname.endsWith(".def")) {
+            pendingDefs.set(node.id, { kind: defKind[cname], def: node });
+        }
+        else if (nameToDef[cname]) {
+            // name capture: find its parent def node id by walking up to the def type
+            const defNode = ascendToDef(node);
+            if (defNode) {
+                const existing = pendingDefs.get(defNode.id);
+                if (existing)
+                    existing.name = node.text;
+                else
+                    pendingDefs.set(defNode.id, { kind: defKind[nameToDef[cname]], def: defNode, name: node.text });
+            }
+        }
+        else if (cname === "import.src") {
+            imports.push(node.text.replace(STR_QUOTES, ""));
+        }
+        else if (cname === "call.id") {
+            calls.push({ callee: node.text, atByte: node.startIndex, member: false });
+        }
+        else if (cname === "call.member") {
+            // skip builtin method names to avoid false edges to similarly-named symbols
+            if (!BUILTIN_METHODS.has(node.text))
+                calls.push({ callee: node.text, atByte: node.startIndex, member: true });
+        }
+    }
+    for (const { kind, def, name } of pendingDefs.values()) {
+        if (!name)
+            continue;
+        const loc = def.endPosition.row - def.startPosition.row + 1;
+        symbols.push({
+            name, kind,
+            startByte: def.startIndex, endByte: def.endIndex, loc,
+            bodyText: def.text.slice(0, 4000),
+        });
+    }
+    symbols.sort((a, b) => a.startByte - b.startByte);
+    return { symbols, imports, calls };
+}
+/** Walk up to the nearest node whose type is a definition we recognize. */
+function ascendToDef(node) {
+    const defTypes = new Set([
+        "function_declaration", "generator_function_declaration", "method_definition",
+        "class_declaration", "interface_declaration", "type_alias_declaration", "variable_declarator",
+    ]);
+    let cur = node.parent;
+    while (cur) {
+        if (defTypes.has(cur.type))
+            return cur;
+        cur = cur.parent;
+    }
+    return null;
+}
+/** Map each call site to the innermost symbol whose byte-range contains it.
+ *  Keyed by the symbol's `startByte` (a stable per-symbol identity within the
+ *  file) rather than its name, so two same-named symbols in one file don't merge
+ *  their call sets. The value maps callee name -> `memberOnly` (true iff every
+ *  occurrence was a `x.foo()` member call, never a direct `foo()`), so the
+ *  indexer can resolve member calls conservatively. */
+export function attributeCalls(parsed) {
+    const out = new Map();
+    for (const call of parsed.calls) {
+        let best = null;
+        for (const s of parsed.symbols) {
+            if (call.atByte >= s.startByte && call.atByte < s.endByte) {
+                if (!best || s.endByte - s.startByte < best.endByte - best.startByte)
+                    best = s;
+            }
+        }
+        if (best && best.name !== call.callee) {
+            if (!out.has(best.startByte))
+                out.set(best.startByte, new Map());
+            const m = out.get(best.startByte);
+            const prev = m.get(call.callee);
+            m.set(call.callee, prev === undefined ? call.member : prev && call.member);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=parse.js.map

package/dist/integrations/claudemd.js

@@ -0,0 +1,77 @@
+/**
+ * Auto-maintained CLAUDE.md (DESIGN.md §7, integration layer 2: "ambient
+ * context loaded every session for free"). We own ONLY the region between the
+ * HUNCH markers — any user-authored content outside it is preserved verbatim.
+ */
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+const START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
+const END = "<!-- HUNCH:END -->";
+export function renderHunchSection(store) {
+    const constraints = store.json
+        .loadAll("constraints")
+        .sort((a, b) => sev(b.severity) - sev(a.severity))
+        .slice(0, 8);
+    const counts = {
+        decisions: store.json.loadAll("decisions").length,
+        bugs: store.json.loadAll("bugs").length,
+        constraints: store.json.loadAll("constraints").length,
+        components: store.json.loadAll("components").length,
+    };
+    const lines = [];
+    lines.push(START);
+    lines.push("## 🧠 Hunch (Engineering Memory)");
+    lines.push("");
+    lines.push("This repo has **Hunch** — a curated graph of *why* the code is the way it is " +
+        "(decisions, bug history, invariants). It currently holds " +
+        `**${counts.decisions} decisions, ${counts.bugs} bugs, ${counts.constraints} constraints, ${counts.components} components**.`);
+    lines.push("");
+    lines.push("**Before reasoning about or editing this codebase, consult Hunch via the `hunch_*` MCP tools:**");
+    lines.push("- `hunch_why(target)` — why a file/symbol is shaped this way (decisions, bugs, constraints).");
+    lines.push("- `hunch_check_constraints(scope)` — invariants you must not break. **Always run before editing.**");
+    lines.push("- `hunch_get_dependents(symbol)` — blast radius before a change.");
+    lines.push("- `hunch_bug_lineage(symptom)` — has this bug happened before? what was the root cause?");
+    lines.push("- `hunch_query(question)` — free-text search across all of Hunch.");
+    lines.push("- `hunch_record_decision(...)` — write back a decision after a non-trivial choice.");
+    if (constraints.length) {
+        lines.push("");
+        lines.push("### ⛔ Top invariants (do not break)");
+        for (const c of constraints) {
+            lines.push(`- **[${c.severity}]** ${c.statement} _(scope: ${c.scope.join(", ") || "repo"}; ${c.id})_`);
+        }
+    }
+    lines.push("");
+    lines.push("_Hunch updates itself from commits and test failures. Records carry provenance + confidence; treat low-confidence items as advisory._");
+    lines.push(END);
+    return lines.join("\n");
+}
+/** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
+export function updateClaudeMd(root, store) {
+    const file = join(root, "CLAUDE.md");
+    const section = renderHunchSection(store);
+    let content = existsSync(file) ? readFileSync(file, "utf8") : "";
+    const iStart = content.indexOf(START);
+    const iEnd = content.indexOf(END);
+    if (iStart >= 0 && iEnd > iStart) {
+        // clean both-marker case: replace in place, preserving surrounding content
+        content = content.slice(0, iStart) + section + content.slice(iEnd + END.length);
+    }
+    else if (iStart >= 0 || iEnd >= 0) {
+        // partial/corrupt markers (only one survived, or out of order): strip every
+        // stray marker line, then append ONE clean section — never duplicate.
+        const body = content.split("\n").filter((l) => !l.includes(START) && !l.includes(END)).join("\n").trimEnd();
+        content = body ? `${body}\n\n${section}\n` : `${section}\n`;
+    }
+    else if (content.trim()) {
+        content = `${content.trimEnd()}\n\n${section}\n`;
+    }
+    else {
+        content = `# ${root.split("/").pop()}\n\n${section}\n`;
+    }
+    writeFileSync(file, content);
+    return file;
+}
+function sev(s) {
+    return { blocking: 3, warning: 2, advisory: 1 }[s] ?? 0;
+}
+//# sourceMappingURL=claudemd.js.map