@davesheffer/hunch 1.8.0 → 1.8.1

package/README.md

@@ -49,6 +49,8 @@ Hunch creates a local graph of:
 - **Constraints** — the invariants a change must not violate.
 - **Bug lineage** — the root cause behind fixes, recurrences, and regression guards.
 - **Architecture** — symbols, components, dependencies, blast radius, and fragility.
+  Deep code-structure parsing covers **TypeScript, JavaScript, and Python** (via a language
+  registry — each new language is one entry); the "why" layer works for any language.
 
 It then puts that context where work happens: MCP tools, the CLI, a VS Code Change Gate, git hooks,
 and an optional pull-request guard.

package/dist/extractors/diff.js

@@ -16,12 +16,24 @@ const DECL_PATTERNS = [
     { kind: "type", re: /^\s*(?:export\s+)?type\s+([A-Za-z_$][\w$]*)\s*[=<]/ },
     { kind: "const", re: /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/ },
     { kind: "const", re: /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?function/ },
+    { kind: "function", re: /^\s*(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/ },
+    // No Python-specific class pattern needed: the generic TS `class` pattern above has no
+    // trailing-syntax requirement (no `{`/`:`), so it already matches Python's
+    // `class Foo(Bar):` header too, and — since declOf() returns on the first match —
+    // always wins for Python class lines before any Python-specific pattern would run.
 ];
+import { languageFor } from "./languages.js";
 const IMPORT_RE = /^\s*import\s+(?:[^'"]*from\s+)?['"]([^'"]+)['"]/;
 const CONT_IMPORT_RE = /^\s*\}?\s*from\s+['"]([^'"]+)['"]/; // multi-line: "} from 'x'"
 const REQUIRE_RE = /\brequire\(\s*['"]([^'"]+)['"]\s*\)/;
-const CODE_EXT = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
-const isCode = (p) => !!p && CODE_EXT.test(p);
+// "import os" / "import a.b.c" / "import os as o" / "import os, sys" / trailing "# comment".
+// Anchored to the END of the line (optional "as alias", comma-separated modules, comment)
+// so it matches a COMPLETE Python import statement only — this deliberately rejects
+// TypeScript's `import Foo = Bar.Baz;` (import-equals), which would otherwise falsely
+// look like a Python "import Foo" prefix match.
+const PY_IMPORT_RE = /^\s*import\s+([A-Za-z_][\w.]*)(?:\s+as\s+\w+)?(?:\s*,\s*[A-Za-z_][\w.]*(?:\s+as\s+\w+)?)*\s*(?:#.*)?$/;
+const PY_FROM_IMPORT_RE = /^\s*from\s+([.\w]+)\s+import\s+/; // "from os import path" / "from . import x"
+const isCode = (p) => !!p && languageFor(p) !== null;
 function declOf(line) {
     for (const { kind, re } of DECL_PATTERNS) {
         const m = re.exec(line);
@@ -31,7 +43,11 @@ function declOf(line) {
     return null;
 }
 function importOf(line) {
-    const m = IMPORT_RE.exec(line) ?? CONT_IMPORT_RE.exec(line) ?? REQUIRE_RE.exec(line);
+    const m = IMPORT_RE.exec(line) ??
+        CONT_IMPORT_RE.exec(line) ??
+        REQUIRE_RE.exec(line) ??
+        PY_FROM_IMPORT_RE.exec(line) ??
+        PY_IMPORT_RE.exec(line);
     return m ? m[1] : null;
 }
 function stripAB(p) {

package/dist/extractors/indexer.js

@@ -8,14 +8,14 @@
  * then runs HunchStore.reindex() to refresh the SQLite index.
  */
 import { readFileSync, statSync, readdirSync } from "node:fs";
-import { join, relative, posix } from "node:path";
+import { join, relative, dirname, posix } from "node:path";
 import { parseSource, attributeCalls } from "./parse.js";
 import { symbolId, componentId, edgeId, sha1 } from "../core/ids.js";
 import { externalImportNodeId, externalPackage } from "../core/externalImports.js";
 import { resolveRelativeImport } from "../core/relativeImports.js";
 import { extracted, inferred } from "../core/types.js";
 import { isGitRepo, trackedFiles, fileGitMetrics } from "./git.js";
-const CODE_EXTS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+import { CODE_EXTENSIONS, languageFor } from "./languages.js";
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".hunch", "coverage", ".next", "out"]);
 export function indexRepo(store, root, opts = {}) {
     const files = listCodeFiles(root);
@@ -84,9 +84,19 @@ export function indexRepo(store, root, opts = {}) {
         perFileImports.push({ file: rel, imports: parsed.imports });
     }
     const byId = new Map(symbols.map((s) => [s.id, s]));
+    // Language-aware import resolution, shared by the call-resolution "was this
+    // name actually imported?" gate (below) and the depends_on edge derivation
+    // (pass 3): a Python cross-file call/import must resolve through the same
+    // relative/absolute Python rules as everything else, not silently fail the
+    // JS/TS resolver and look unimported.
+    const hasSrcLayout = [...fileSymbols.keys()].some((f) => f.startsWith("src/"));
+    const pyRoots = hasSrcLayout ? ["", "src"] : [""];
+    const resolveImportTarget = (file, spec) => languageFor(file)?.id === "python"
+        ? resolvePythonImport(file, spec, fileSymbols, pyRoots)
+        : resolveImport(file, spec, fileSymbols);
     const importedFiles = new Map(perFileImports.map(({ file, imports }) => [
         file,
-        new Set(imports.map((specifier) => resolveImport(file, specifier, fileSymbols)).filter((target) => !!target)),
+        new Set(imports.map((specifier) => resolveImportTarget(file, specifier)).filter((target) => !!target)),
     ]));
     // ---- pass 2: resolve calls -> symbol-level edges -------------------------
     const edges = [];
@@ -151,7 +161,7 @@ export function indexRepo(store, root, opts = {}) {
         if (!fromCmp)
             continue;
         for (const spec of imports) {
-            const target = resolveImport(file, spec, fileSymbols);
+            const target = resolveImportTarget(file, spec);
             if (target) {
                 const toCmp = fileToComponent.get(target);
                 if (!toCmp || toCmp === fromCmp)
@@ -213,7 +223,7 @@ function listCodeFiles(root) {
     if (isGitRepo(root)) {
         // Apply SKIP_DIRS to the git-tracked list too: a repo that (accidentally)
         // tracks node_modules/ or dist/ must not flood the graph with vendored symbols.
-        const tracked = trackedFiles(root, CODE_EXTS)
+        const tracked = trackedFiles(root, CODE_EXTENSIONS)
             .filter((f) => !f.split(/[\\/]/).some((seg) => SKIP_DIRS.has(seg)))
             .map((f) => join(root, f));
         if (tracked.length > 0)
@@ -228,7 +238,7 @@ function listCodeFiles(root) {
             const st = statSync(abs);
             if (st.isDirectory())
                 walk(abs);
-            else if (CODE_EXTS.some((e) => name.endsWith(e)))
+            else if (languageFor(name) !== null)
                 out.push(abs);
         }
     };
@@ -255,6 +265,55 @@ function resolveName(name, file, importedFiles, nameIndex, byId) {
 function resolveImport(fromFile, spec, fileSymbols) {
     return resolveRelativeImport(fromFile, spec, fileSymbols.keys()).path;
 }
+/** First of `${modulePath}.py` / `${modulePath}/__init__.py` that's a tracked file,
+ *  or null — the shared "module file vs. package __init__" candidate check used by
+ *  both resolvePythonImport branches below. */
+function firstExistingPyModule(modulePath, fileSymbols) {
+    const candidates = [`${modulePath}.py`, `${modulePath}/__init__.py`];
+    for (const c of candidates)
+        if (fileSymbols.has(c))
+            return c;
+    return null;
+}
+/** Resolve a Python import specifier (relative or absolute) to a concrete tracked
+ *  file path. Sibling to resolveImport() — Python's leading dot means "N levels up
+ *  from the importing module's own directory," not "a relative file-path fragment"
+ *  the way JS/TS's `./`/`../` does. Absolute imports are resolved best-effort
+ *  against `pyRoots` (repo root, plus a top-level `src/` layout if one exists) —
+ *  no sys.path/PYTHONPATH emulation. A module's own package directory is always
+ *  its containing directory, so relative resolution needs no repo-wide
+ *  package-root search — only dot-counting from `fromFile`'s own location. */
+function resolvePythonImport(fromFile, spec, fileSymbols, pyRoots) {
+    if (!spec.startsWith(".")) {
+        const specPath = spec.split(".").join("/");
+        for (const root of pyRoots) {
+            const modulePath = root ? `${root}/${specPath}` : specPath;
+            const found = firstExistingPyModule(modulePath, fileSymbols);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    const level = spec.length - spec.replace(/^\.+/, "").length;
+    const tail = spec.slice(level);
+    const dir = toPosix(dirname(fromFile));
+    const segments = dir === "." ? [] : dir.split("/");
+    const pop = level - 1;
+    if (pop > segments.length)
+        return null; // import points above the repo root — don't guess
+    const baseSegments = pop > 0 ? segments.slice(0, segments.length - pop) : segments;
+    const baseDir = baseSegments.join("/");
+    if (!tail) {
+        // bare `.`/`..`/etc — `from . import x` only ever resolves to the package's
+        // own __init__.py (we track the module path, never the imported name itself,
+        // matching resolveImport()'s granularity for JS/TS named imports).
+        const initPy = baseDir ? `${baseDir}/__init__.py` : "__init__.py";
+        return fileSymbols.has(initPy) ? initPy : null;
+    }
+    const tailPath = tail.split(".").join("/");
+    const modulePath = baseDir ? `${baseDir}/${tailPath}` : tailPath;
+    return firstExistingPyModule(modulePath, fileSymbols);
+}
 /** 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) {

package/dist/extractors/languages.js

@@ -0,0 +1,114 @@
+/**
+ * Language registry: one LanguageSpec per supported language, consumed by
+ * parse.ts (tree-sitter grammar/query dispatch), indexer.ts / diff.ts /
+ * synthesize.ts ("is this a code file?"). Adding a language is a new entry
+ * here (+ a new tree-sitter-* dependency), not edits scattered across those
+ * four files.
+ */
+import { loadNativeTreeSitter } from "./nativeTreeSitter.js";
+const TS_QUERY = `
+  (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 TS_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",
+]);
+const TS_SHARED = {
+    id: "typescript",
+    query: TS_QUERY,
+    defNodeTypes: new Set([
+        "function_declaration", "generator_function_declaration", "method_definition",
+        "class_declaration", "interface_declaration", "type_alias_declaration", "variable_declarator",
+    ]),
+    defKindOf: {
+        "fn.def": "function", "method.def": "method", "class.def": "class",
+        "iface.def": "interface", "type.def": "type", "arrow.def": "function",
+    },
+    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",
+    },
+    builtinMethods: TS_BUILTIN_METHODS,
+};
+const TYPESCRIPT = {
+    ...TS_SHARED,
+    extensions: [".ts", ".mts", ".cts", ".js", ".mjs", ".cjs"],
+    grammarKey: "ts",
+    loadGrammar: () => loadNativeTreeSitter().typescript,
+};
+/** .tsx/.jsx use the TSX grammar variant; everything else in the TS spec uses
+ *  the plain typescript grammar. Both share the same query/def maps/builtins,
+ *  so this is a second LanguageSpec entry with a distinct grammarKey/loadGrammar
+ *  only — not a second `id` (languageFor callers only care about extension match). */
+const TSX = {
+    ...TS_SHARED,
+    extensions: [".tsx", ".jsx"],
+    grammarKey: "tsx",
+    loadGrammar: () => loadNativeTreeSitter().tsx,
+};
+const PY_QUERY = `
+  (class_definition
+    name: (identifier) @class.name
+    body: (block
+      [
+        (function_definition name: (identifier) @method.name) @method.def
+        (decorated_definition definition: (function_definition name: (identifier) @method.name) @method.def)
+      ])) @class.def
+  (function_definition name: (identifier) @fn.name) @fn.def
+  (import_statement name: (dotted_name) @import.src)
+  (import_statement name: (aliased_import name: (dotted_name) @import.src))
+  (import_from_statement module_name: (dotted_name) @import.src)
+  (import_from_statement module_name: (relative_import) @import.src)
+  (call function: (identifier) @call.id)
+  (call function: (attribute attribute: (identifier) @call.member))
+`;
+const PY_BUILTIN_METHODS = new Set([
+    "get", "set", "keys", "values", "items", "pop", "popitem", "update", "setdefault", "copy", "clear",
+    "append", "extend", "insert", "remove", "reverse", "sort", "count", "index",
+    "add", "discard", "union", "intersection", "difference",
+    "format", "join", "split", "rsplit", "splitlines", "strip", "lstrip", "rstrip",
+    "startswith", "endswith", "replace", "find", "rfind", "lower", "upper", "title", "capitalize",
+    "encode", "decode", "isdigit", "isalpha", "isalnum", "isspace",
+    "read", "write", "close", "open", "readline", "readlines",
+    "run", "wait", "poll", "communicate",
+]);
+const PYTHON = {
+    id: "python",
+    extensions: [".py", ".pyi"],
+    grammarKey: "python",
+    loadGrammar: () => loadNativeTreeSitter().python,
+    query: PY_QUERY,
+    defNodeTypes: new Set(["function_definition", "class_definition"]),
+    defKindOf: { "fn.def": "function", "method.def": "method", "class.def": "class" },
+    nameToDef: { "fn.name": "fn.def", "method.name": "method.def", "class.name": "class.def" },
+    builtinMethods: PY_BUILTIN_METHODS,
+};
+export const LANGUAGES = [TYPESCRIPT, TSX, PYTHON];
+export const CODE_EXTENSIONS = [...new Set(LANGUAGES.flatMap((l) => l.extensions))];
+export function languageFor(file) {
+    for (const lang of LANGUAGES) {
+        if (lang.extensions.some((ext) => file.endsWith(ext)))
+            return lang;
+    }
+    return null;
+}
+//# sourceMappingURL=languages.js.map

package/dist/extractors/nativeTreeSitter.js

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 const runtimeRequire = createRequire(import.meta.url);
 const COPY_PREFIX = "hunch-tree-sitter-";
-const NATIVE_PACKAGES = ["tree-sitter", "tree-sitter-typescript"];
+const NATIVE_PACKAGES = ["tree-sitter", "tree-sitter-typescript", "tree-sitter-python"];
 let runtime = null;
 function processIsAlive(pid) {
     if (pid === process.pid)
@@ -56,14 +56,15 @@ function copyNativeBinding(packageName, copyRoot, nodeGypBuild) {
     copyFileSync(source, destination);
     return packageCopy;
 }
-/** Load both native tree-sitter addons from process-owned temp copies. Windows
- * keeps loaded `.node` files locked for the process lifetime; redirecting the
- * upstream loaders means npm can replace the installed package during an active
- * MCP session without killing that session or falling back to a stale binary. */
+/** Load all native tree-sitter addons (the parser runtime + every grammar) from
+ * process-owned temp copies. Windows keeps loaded `.node` files locked for the
+ * process lifetime; redirecting the upstream loaders means npm can replace the
+ * installed package during an active MCP session without killing that session
+ * or falling back to a stale binary. */
 export function loadNativeTreeSitter() {
     if (runtime)
         return runtime;
-    const preloaded = Object.keys(runtimeRequire.cache).filter((path) => /tree-sitter(?:-typescript)?\.node$/.test(path)
+    const preloaded = Object.keys(runtimeRequire.cache).filter((path) => /tree-sitter(?:-typescript|-python)?\.node$/.test(path)
         && !new RegExp(`(?:^|[\\\\/])${COPY_PREFIX}\\d+-`).test(path));
     if (preloaded.length) {
         throw new Error(`tree-sitter native addon was loaded before Hunch could isolate it: ${preloaded.join(", ")}`);
@@ -80,7 +81,8 @@ export function loadNativeTreeSitter() {
         }
         const Parser = runtimeRequire("tree-sitter");
         const languages = runtimeRequire("tree-sitter-typescript");
-        runtime = { Parser, typescript: languages.typescript, tsx: languages.tsx };
+        const python = runtimeRequire("tree-sitter-python");
+        runtime = { Parser, typescript: languages.typescript, tsx: languages.tsx, python };
     }
     catch (error) {
         try {

package/dist/extractors/parse.js

@@ -1,62 +1,25 @@
+import { languageFor } from "./languages.js";
 import { loadNativeTreeSitter } from "./nativeTreeSitter.js";
-const { Parser, typescript, tsx } = loadNativeTreeSitter();
-/** 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 { Parser } = loadNativeTreeSitter();
 const cache = new Map();
-function bundleFor(lang, key) {
-    let b = cache.get(key);
+function bundleFor(spec) {
+    let b = cache.get(spec.grammarKey);
     if (!b) {
         const parser = new Parser();
-        parser.setLanguage(lang);
-        const query = new Parser.Query(lang, QUERY_SRC);
+        const grammar = spec.loadGrammar();
+        parser.setLanguage(grammar);
+        const query = new Parser.Query(grammar, spec.query);
         b = { parser, query };
-        cache.set(key, b);
+        cache.set(spec.grammarKey, 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)
+    const spec = languageFor(file);
+    if (!spec)
         return null;
-    const { parser, query } = bundleFor(picked.lang, picked.key);
+    const { parser, query } = bundleFor(spec);
     // 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.
@@ -73,29 +36,27 @@ export function parseSource(file, source) {
     // 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 });
+            // Keep the FIRST classification a node id receives: a query may have
+            // several patterns matching the same node at different specificity
+            // (e.g. a Python method inside a class body matches both a class-nested
+            // "method.def" pattern and a general "fn.def" pattern — Task 4 relies on
+            // this to classify methods correctly without special-casing Python here).
+            if (!pendingDefs.has(node.id))
+                pendingDefs.set(node.id, { kind: spec.defKindOf[cname], def: node });
         }
-        else if (nameToDef[cname]) {
+        else if (spec.nameToDef[cname]) {
             // name capture: find its parent def node id by walking up to the def type
-            const defNode = ascendToDef(node);
+            const defNode = ascendToDef(node, spec.defNodeTypes);
             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 });
+                    pendingDefs.set(defNode.id, { kind: spec.defKindOf[spec.nameToDef[cname]], def: defNode, name: node.text });
             }
         }
         else if (cname === "import.src") {
@@ -106,7 +67,7 @@ export function parseSource(file, source) {
         }
         else if (cname === "call.member") {
             // skip builtin method names to avoid false edges to similarly-named symbols
-            if (!BUILTIN_METHODS.has(node.text))
+            if (!spec.builtinMethods.has(node.text))
                 calls.push({ callee: node.text, atByte: node.startIndex, endByte: node.endIndex, member: true });
         }
     }
@@ -123,15 +84,11 @@ export function parseSource(file, source) {
     symbols.sort((a, b) => a.startByte - b.startByte);
     return { symbols, imports, calls, parseable: !tree.rootNode.hasError };
 }
-/** 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",
-    ]);
+/** Walk up to the nearest node whose type is a definition this language recognizes. */
+function ascendToDef(node, defNodeTypes) {
     let cur = node.parent;
     while (cur) {
-        if (defTypes.has(cur.type))
+        if (defNodeTypes.has(cur.type))
             return cur;
         cur = cur.parent;
     }

package/dist/integrations/claudemd.js

@@ -35,7 +35,8 @@ export function renderHunchSection(store, root) {
     lines.push("- `hunch_context(target_or_task)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST.**");
     lines.push("- `hunch_structure(target?)` — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.");
     lines.push("- `hunch_runbook(task)` — the proven steps for a recurring task, before re-deriving them.");
-    lines.push("- `hunch now` (CLI) — recent decisions + the live roadmap.");
+    lines.push("- `hunch_escalations()` — the decisions only the HUMAN can make (topic conflicts, candidate/proposed rules, repaired rules needing a re-prove). Normally empty; when it isn't, ASK the user inline — an entry is a question, never an approval.");
+    lines.push("- `hunch now` (CLI) — recent decisions + the live roadmap; `hunch log` — the memory-move timeline (every capture/adopt/supersede/prune/repair, each revertable).");
     lines.push("");
     lines.push("**Before designing / choosing an approach:**");
     lines.push("- `hunch_why(target)` — why a file/symbol is shaped this way (decisions, bugs, constraints) — including what was already REJECTED.");

package/dist/synthesis/synthesize.js

@@ -5,12 +5,23 @@ import { decisionId, bugId, constraintId } from "../core/ids.js";
 import { commitCoveredBy } from "../core/dupdetect.js";
 import { pathMatchesGlob } from "../core/glob.js";
 import { draftTripwires, knownRepoDeps } from "./tripwires.js";
-const CODE_RE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
-const SKIP_SUBJECT = /^(merge|revert|bump|chore\(deps\)|format|lint|wip)\b/i;
+import { languageFor } from "../extractors/languages.js";
+// "chore(deps):" is anchored separately (not via \b) because \b requires a
+// word/non-word transition, and the character after the closing ")" is ":" or a
+// space — both non-word — so no boundary ever fires there.
+const SKIP_SUBJECT = /^(merge|revert|bump|format|lint|wip)\b|^chore\(deps\):/i;
 // Below this many changed code lines, a commit with no structural change and no
 // explanatory body isn't worth a paid LLM call. Tunable via HUNCH_SIG_MIN_LINES.
 const SIG_MIN_LINES = Number(process.env.HUNCH_SIG_MIN_LINES) || 12;
 const SIG_MIN_BODY = 40;
+/** Trivial-subject commits (merge/revert/bump/format/...) are noise UNLESS the body
+ *  carries real content — a squash/PR description often lands there, not on the
+ *  subject. Gated on body length ALONE (not the full isSignificant() heuristic): a
+ *  large auto-generated reformat or dependency-bump diff with no narrative must stay
+ *  skipped even though it would trip isSignificant()'s line/file/structural checks. */
+export function isTrivialSubject(meta) {
+    return SKIP_SUBJECT.test(meta.subject) && meta.body.trim().length < SIG_MIN_BODY;
+}
 /** Is a commit substantive enough to spend a paid LLM synthesis call on? Pure and
  *  deterministic. Any structural change (symbol/dependency delta), non-trivial
  *  churn, several files, OR an explanatory commit body signals a real decision
@@ -37,9 +48,9 @@ export async function syncCommit(store, root, sha, opts = {}) {
     const meta = commitMeta(target, root);
     if (!meta)
         return { status: "skipped", reason: "commit not found" };
-    if (SKIP_SUBJECT.test(meta.subject))
+    if (isTrivialSubject(meta))
         return { status: "skipped", reason: `trivial subject: ${meta.subject}` };
-    const codeFiles = meta.files.filter((f) => CODE_RE.test(f));
+    const codeFiles = meta.files.filter((f) => languageFor(f) !== null);
     if (codeFiles.length === 0)
         return { status: "skipped", reason: "no code files changed" };
     // Seed the id from the COMMIT (stable across runs), not the LLM-generated title

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Architectural Conformance for AI-generated code: a git-native graph that deterministically blocks AI changes which break your architecture — the semantic invariants (layering, must-reach, dependency direction) pattern-SAST can't express — grounded in the decisions and bugs behind each rule, across any MCP assistant (Claude Code, Cursor, Copilot, Windsurf, Antigravity, Codex).",
@@ -58,6 +58,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^15.0.0",
     "tree-sitter": "0.21.1",
+    "tree-sitter-python": "^0.23.2",
     "tree-sitter-typescript": "^0.23.2",
     "zod": "^4.4.3"
   },