@davesheffer/hunch 1.46.0 → 1.47.0

package/dist/extractors/languages.d.ts

@@ -1,21 +1,22 @@
 import type { Edge } from "../core/types.js";
 export type ParsedSymbolKind = "function" | "method" | "class" | "interface" | "trait" | "enum" | "type" | "variable" | "file";
 export interface LanguageSpec {
-    /** Stable id, also used as the grammar-bundle cache key by parse.ts. */
+    /** Stable language id (`typescript`, `python`, `go`, `php`, `yaml`). */
     id: string;
+    /** File suffixes, leading dot included, that this spec handles. */
     extensions: string[];
-    /** Cache key parse.ts's bundleFor() uses (one grammar+query pair may serve
-     *  several extensions, e.g. tsx serves both .tsx and .jsx). */
+    /** Memoization key for the parser+query bundle. One grammar can serve several
+     *  extensions, and two specs may share an `id` yet differ here (TS vs TSX). */
     grammarKey: string;
-    /** Lazily returns the tree-sitter Language object for this spec. */
+    /** Lazily returns the tree-sitter Language object. */
     loadGrammar(): unknown;
-    /** Tree-sitter query source capturing every construct this language cares about. */
+    /** Tree-sitter query source capturing every construct of interest. */
     query: string;
-    /** Node types ascendToDef() walks up to when resolving a name capture's enclosing def. */
+    /** Node types the parser climbs to when attaching a name capture to its definition. */
     defNodeTypes: Set<string>;
-    /** Query capture-name (ending in ".def") -> the ParsedSymbolKind it represents. */
+    /** Symbol kind for each capture name ending in `.def`. */
     defKindOf: Record<string, ParsedSymbolKind>;
-    /** Query capture-name (ending in ".name") -> the matching ".def" capture-name. */
+    /** Maps each `.name` capture to the `.def` capture it belongs to. */
     nameToDef: Record<string, string>;
     /** Optional query binding a local name to an imported module, run with
      *  matches() so captures pair up: @bind.src (module specifier), @bind.local
@@ -32,21 +33,17 @@ export interface LanguageSpec {
         edgeType: Edge["type"];
         label: string;
     }>;
-    /** Common builtin/stdlib 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). */
+    /** Common builtin/stdlib method names. A member call whose property is in this
+     *  set never produces a call edge to a same-named repo symbol. */
     builtinMethods: Set<string>;
     /** Direct-call builtins for languages such as PHP. These never become repo
      * call edges merely because a project symbol shares the runtime name. */
     builtinFunctions?: Set<string>;
-    /** Edge type emitted for this language's calls-list entries (e.g. YAML's
-     *  alias->anchor references aren't function calls). Defaults to "calls"
-     *  when omitted — every language before YAML. */
+    /** Edge type emitted for this language's call-list entries; defaults to
+     *  `"calls"`. YAML sets it because alias-to-anchor links are references. */
     referenceEdgeType?: Edge["type"];
-    /** Fallback name for a ".def" capture with no paired ".name" capture (e.g.
-     *  a whole-file root symbol with no natural identifier of its own). Omit
-     *  for a language where every ".def" always has a name capture — parse.ts
-     *  then keeps dropping unnamed defs, the current behavior for TS/Python. */
+    /** Name for a `.def` capture that has no paired `.name` capture (a whole-file
+     *  root symbol, say). When omitted, unnamed defs are dropped. */
     fallbackDefName?: (file: string) => string;
     /** Ancestor shapes in which an ERROR node is a known limitation of THIS grammar
      *  rather than a real syntax error. parse.ts forgives an error only when some
@@ -64,30 +61,24 @@ export interface LanguageSpec {
      *  every captured value from the original source at the tree's unchanged
      *  offsets. Keep replacements syntax-equivalent outside the grammar defect. */
     parseErrorRecovery?: (source: string) => string;
-    /** Patterns whose presence anywhere in the source mean "this isn't actually
-     *  {id} text yet — it's a template that renders to {id} later" (Go/Jinja/Helm
-     *  delimiters in a .yaml file, e.g.). parse.ts still runs the real parse — a
-     *  genuine anchor/symbol elsewhere in the file is still extracted, same as any
-     *  other {id} file — but no longer lets the resulting ERROR nodes fail-close
-     *  the whole-repo scan completeness gate the way toleratedErrorScopes protects
-     *  narrower, per-grammar false positives (issue #33). Keep these narrow: a
-     *  pattern that also matches ordinary, always-valid {id} syntax (e.g. GitHub
-     *  Actions' `${{ }}` expressions) would silently disable the fail-closed
-     *  guarantee for files that were never templated at all. */
+    /** Patterns whose presence anywhere in a file's text means the file is a
+     *  template that renders into this language later (Go/Jinja/Helm delimiters in
+     *  YAML). The real parse still runs, but the resulting error nodes must not make
+     *  the file unparseable, so the whole-repo completeness gate does not fail
+     *  closed. Keep patterns narrow so they never match always-valid syntax such as
+     *  GitHub Actions `${{ }}` expressions. */
     templatingMarkers?: readonly RegExp[];
-    /** Extensions within this language where EVERY file is inherently a template
-     *  regardless of content — unlike templatingMarkers, this never content-sniffs.
-     *  The extension alone means "this file is a template, parseable must never
-     *  become false for it," matching Helm's `_helpers.tpl` convention where the
-     *  file may be pure Go-template text with no YAML structure of its own at all. */
+    /** Extensions where every file is a template regardless of content, with no
+     *  sniffing (Helm's `_helpers.tpl` convention). Such files are never reported
+     *  unparseable. */
     alwaysTemplatedExtensions?: readonly string[];
 }
 export declare const LANGUAGES: LanguageSpec[];
+/** Every registered extension, de-duplicated, in registry order. */
 export declare const CODE_EXTENSIONS: string[];
+/** First spec (registry order) with an extension the file name ends with. */
 export declare function languageFor(file: string): LanguageSpec | null;
-/** Prose formats worth drafting a decision from even though no LanguageSpec parses
- *  them — no grammar, no symbols/edges, just eligible input to synthesis (issue #12). */
+/** Prose formats eligible as synthesis input but never parsed. */
 export declare const PROSE_EXTENSIONS: string[];
-/** Broader than languageFor: "is this worth reasoning about" (synthesis input)
- *  rather than "can tree-sitter parse this" (symbol/dependency extraction). */
+/** True for parseable code or prose. Deliberately broader than parseability. */
 export declare function isSubstantive(file: string): boolean;

package/dist/extractors/languages.js

@@ -1,9 +1,8 @@
 /**
- * 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.
+ * The single language registry: one `LanguageSpec` per supported language. The
+ * parser reads grammar and query data from here, and the indexer, diff analysis
+ * and synthesis ask it "is this a code file?". Adding a language means adding an
+ * entry here plus a grammar dependency.
  */
 import { basename } from "node:path";
 import { loadNativeTreeSitter } from "./nativeTreeSitter.js";
@@ -53,23 +52,36 @@ const TS_BINDING_QUERY = `
      value: (await_expression (call_expression function: (import) arguments: (arguments . (string) @bind.src .))))
 `;
 const TS_BUILTIN_METHODS = new Set([
+    // arrays
     "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",
+    "push", "pop", "shift", "unshift", "slice", "splice", "concat", "join", "split", "flat",
+    "flatMap", "indexOf", "lastIndexOf", "keys", "values", "entries", "sort", "reverse", "fill", "at",
+    // Map / Set
     "get", "set", "has", "add", "delete", "clear",
+    // Promise
     "then", "catch", "finally", "all", "race", "resolve", "reject",
+    // object basics
     "toString", "valueOf", "toJSON", "hasOwnProperty",
-    "replace", "replaceAll", "trim", "trimStart", "trimEnd", "padStart", "padEnd", "startsWith", "endsWith",
-    "toLowerCase", "toUpperCase", "charAt", "charCodeAt", "substring", "substr", "repeat", "match", "matchAll",
+    // strings
+    "replace", "replaceAll", "trim", "trimStart", "trimEnd", "padStart", "padEnd", "startsWith",
+    "endsWith", "toLowerCase", "toUpperCase", "charAt", "charCodeAt", "substring", "substr",
+    "repeat", "match", "matchAll",
+    // Function / RegExp / JSON / Date / Array / Object statics
     "call", "apply", "bind", "test", "exec", "now", "parse", "stringify", "from", "of", "isArray", "assign",
+    // console
     "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",
+        "function_declaration",
+        "generator_function_declaration",
+        "method_definition",
+        "class_declaration",
+        "interface_declaration",
+        "type_alias_declaration",
+        "variable_declarator",
         "public_field_definition",
     ]),
     defKindOf: {
@@ -99,10 +111,9 @@ const TYPESCRIPT = {
     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). */
+/** TSX is a second entry that differs from TYPESCRIPT only in grammar and cache
+ *  key (the `id` is shared). It also overrides the query with TSX_QUERY, widens
+ *  the tolerated error scopes and adds a recovery pass. */
 const TSX = {
     ...TS_SHARED,
     extensions: [".tsx", ".jsx"],
@@ -124,13 +135,15 @@ const TSX = {
     parseErrorRecovery: (source) => source.replaceAll("&", "|"),
 };
 const PY_QUERY = `
+  ;; A class whose body directly holds a def (plain or decorated): the nested def is
+  ;; a method. parse.ts keeps the first classification per node, so the generic
+  ;; function pattern below does not reclassify it.
   (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
+     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
   ;; Every class, including one with no directly-nested def: dataclasses, Exception
   ;; subclasses, Enums, TypedDicts and pydantic models are method-less by design and
   ;; were invisible to the entire graph (no symbol, no component, no edges), so
@@ -141,20 +154,18 @@ const PY_QUERY = `
   (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)
+  (import_from_statement module_name: [(dotted_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",
+    "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",
@@ -282,7 +293,9 @@ const PHP = {
 const YAML_QUERY = `
   (block_node (anchor (anchor_name) @anchor.name)) @anchor.def
   (flow_node (anchor (anchor_name) @anchor.name)) @anchor.def
+  ;; An alias is a reference to its anchor.
   (alias (alias_name) @call.id)
+  ;; The whole document gets a root symbol (named via fallbackDefName).
   (stream) @doc.def
 `;
 const YAML = {
@@ -291,42 +304,30 @@ const YAML = {
     grammarKey: "yaml",
     loadGrammar: () => loadNativeTreeSitter().yaml,
     query: YAML_QUERY,
-    // Both block-style (`key: &x\n  ...`) and flow-style (`key: &x {...}`) anchors
-    // wrap only the sigil+name; ascendToDef climbs from anchor_name -> anchor ->
-    // this enclosing node to find the def whose byte range covers the full value.
     defNodeTypes: new Set(["block_node", "flow_node"]),
     defKindOf: { "anchor.def": "variable", "doc.def": "file" },
     nameToDef: { "anchor.name": "anchor.def" },
     builtinMethods: new Set(),
-    // Alias references aren't calls; label the edge accordingly (Task 5).
     referenceEdgeType: "references",
-    // Most aliases reference an anchor from OUTSIDE that anchor's own byte range
-    // (a sibling key, not a nested value) — without a whole-file fallback symbol,
-    // attributeCalls's containment check would silently drop them. See Task 4.
+    // Most aliases sit outside their anchor's byte range, so without a root symbol
+    // call attribution would drop them. The file's own name is the root.
     fallbackDefName: (file) => basename(file),
-    // Helm charts / templated CI configs are common .yaml content that only
-    // becomes valid YAML after a render step (issue #33). The negative lookbehind
-    // on "{{" excludes GitHub Actions' `${{ expression }}` syntax, which is
-    // ordinary, always-valid YAML — every workflow file in this repo uses it, so
-    // treating it as a templating marker would blanket-disable the fail-closed
-    // gate for .github/workflows/**.
-    templatingMarkers: [/(?<!\$)\{\{/, /\{%/],
+    // Go/Jinja/Helm delimiters make a file invalid YAML until rendered. A `{{` not
+    // preceded by `$` (GitHub Actions `${{ }}` is plain valid YAML) and a Jinja `{%`.
+    templatingMarkers: [/(?<!\$)\{\{/u, /\{%/u],
+    // `.tpl` files (Helm `_helpers.tpl`) are templates by convention, whatever they hold.
     alwaysTemplatedExtensions: [".tpl"],
 };
 export const LANGUAGES = [TYPESCRIPT, TSX, PYTHON, GO, PHP, YAML];
+/** Every registered extension, de-duplicated, in registry order. */
 export const CODE_EXTENSIONS = [...new Set(LANGUAGES.flatMap((l) => l.extensions))];
+/** First spec (registry order) with an extension the file name ends with. */
 export function languageFor(file) {
-    for (const lang of LANGUAGES) {
-        if (lang.extensions.some((ext) => file.endsWith(ext)))
-            return lang;
-    }
-    return null;
+    return LANGUAGES.find((l) => l.extensions.some((ext) => file.endsWith(ext))) ?? null;
 }
-/** Prose formats worth drafting a decision from even though no LanguageSpec parses
- *  them — no grammar, no symbols/edges, just eligible input to synthesis (issue #12). */
+/** Prose formats eligible as synthesis input but never parsed. */
 export const PROSE_EXTENSIONS = [".md"];
-/** Broader than languageFor: "is this worth reasoning about" (synthesis input)
- *  rather than "can tree-sitter parse this" (symbol/dependency extraction). */
+/** True for parseable code or prose. Deliberately broader than parseability. */
 export function isSubstantive(file) {
     return languageFor(file) !== null || PROSE_EXTENSIONS.some((ext) => file.endsWith(ext));
 }

package/dist/extractors/nativeTreeSitter.d.ts

@@ -32,10 +32,10 @@ export declare class NativeTreeSitterLoadError extends Error {
  *  a worker/IPC boundary keeps only its plain properties. The name check
  *  survives both. */
 export declare function isParserLoadError(e: unknown): boolean;
-/** Load all native tree-sitter addons (the parser runtime + every grammar) from
+/** Loads every native tree-sitter addon (the parser runtime and each grammar) from
  * content-addressed copies in a per-user temp cache — never from the installed
  * package. 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. */
+ * lifetime of the process, so pointing the upstream loaders at copies lets npm
+ * replace the installed package during a live MCP session without killing it and
+ * without ever loading a stale binary. */
 export declare function loadNativeTreeSitter(): NativeTreeSitterRuntime;

package/dist/extractors/nativeTreeSitter.js

@@ -10,13 +10,14 @@ const COPY_PREFIX = "hunch-tree-sitter-";
 const CACHE_PREFIX = "hunch-tree-sitter-cache-";
 /** A hash dir no process has used for this long is pruned. */
 const CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** npm packages whose native addons are loaded from isolated copies. */
 const NATIVE_PACKAGES = [
     "tree-sitter",
     "tree-sitter-typescript",
     "tree-sitter-python",
     "tree-sitter-go",
     "tree-sitter-php",
-    "@tree-sitter-grammars/tree-sitter-yaml",
+    "tree-sitter-yaml",
 ];
 let runtime = null;
 /** The parser runtime itself is unavailable — the addons could not be copied or
@@ -87,8 +88,11 @@ function removeStaleCopies() {
         }
     }
 }
+/** node-gyp-build keys the redirect on the package's own `name`, not the
+ *  specifier it was required by — the two differ for an npm alias. */
 function environmentKey(packageName) {
-    return `${packageName.toUpperCase().replaceAll("-", "_")}_PREBUILD`;
+    const { name } = runtimeRequire(`${packageName}/package.json`);
+    return `${name.toUpperCase().replaceAll("-", "_")}_PREBUILD`;
 }
 /** The per-user copy cache. A binary copied to a fresh path costs a first-load
  *  assessment (macOS checks every never-seen dylib: ~2s per addon, six addons)
@@ -197,12 +201,12 @@ function pruneCache(root, keep) {
         catch { /* in use or already gone */ }
     }
 }
-/** Load all native tree-sitter addons (the parser runtime + every grammar) from
+/** Loads every native tree-sitter addon (the parser runtime and each grammar) from
  * content-addressed copies in a per-user temp cache — never from the installed
  * package. 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. */
+ * lifetime of the process, so pointing the upstream loaders at copies lets npm
+ * replace the installed package during a live MCP session without killing it and
+ * without ever loading a stale binary. */
 export function loadNativeTreeSitter() {
     if (runtime)
         return runtime;
@@ -219,13 +223,12 @@ export function loadNativeTreeSitter() {
     }
 }
 function loadRuntime() {
-    // Three binding spellings: prebuilds ship as tree-sitter[-typescript|-python].node
-    // or, for a scoped package like @tree-sitter-grammars/tree-sitter-yaml, as
-    // @scope+name.node; from-source builds are named after the binding.gyp target
-    // with underscores (tree_sitter_runtime_binding.node, tree_sitter_python_binding.node,
-    // tree_sitter_yaml_binding.node, …). Missing the underscore names let an
-    // already-loaded source-built addon slip past this guard and defeat the
-    // file-lock isolation entirely (issue #52).
+    // Recognised addon file names: the prebuilt names of the runtime and of each
+    // grammar package, the `@scope+name` spelling that scoped packages use inside
+    // their prebuilds, and from-source builds, which are named after the
+    // binding.gyp target with underscores and end in `_binding`. Missing the
+    // underscore form once let an already-loaded source build slip past isolation
+    // (issue #52).
     const preloaded = Object.keys(runtimeRequire.cache).filter((path) => /(?:tree-sitter(?:-typescript|-python|-go|-php|-yaml)?|tree_sitter(?:_[a-z]+)*_binding)\.node$/.test(path)
         && !new RegExp(`(?:^|[\\\\/])(?:${COPY_PREFIX}\\d+-|${CACHE_PREFIX})`).test(path));
     if (preloaded.length) {
@@ -260,7 +263,7 @@ function loadRuntime() {
         const python = runtimeRequire("tree-sitter-python");
         const go = runtimeRequire("tree-sitter-go");
         const php = runtimeRequire("tree-sitter-php");
-        const yaml = runtimeRequire("@tree-sitter-grammars/tree-sitter-yaml");
+        const yaml = runtimeRequire("tree-sitter-yaml");
         runtime = { Parser, typescript: languages.typescript, tsx: languages.tsx, python, go, php: php.php, yaml };
     }
     finally {

package/dist/extractors/parse.d.ts

@@ -46,24 +46,18 @@ export interface ParsedFile {
     namespace: string | null;
     parseable: boolean;
 }
-/** Cap on a stored symbol's bodyText — large enough for review context, small
- *  enough that a huge function/file doesn't bloat every JSON symbol record. */
+/** Cap on stored symbol body text: enough context for review without bloating JSON records. */
 export declare const MAX_BODY_TEXT_CHARS = 4000;
 export declare function parseSource(file: string, source: string, opts?: {
     throwOnParseError?: boolean;
 }): ParsedFile | null;
 /** Map each call site to the innermost symbol whose byte-range contains it.
- *  Keyed by the symbol's position (index) in `parsed.symbols` — NOT its
- *  startByte, which is not a reliable per-symbol identity: a language whose
- *  extractor merges a synthetic whole-file symbol with independently-derived
- *  symbols (e.g. YAML's fallback-root synthetic symbol alongside Helm's
- *  regex-derived `define` blocks) can produce two distinct symbols that both
- *  start at byte 0. Indexing by array position is unique by construction,
- *  regardless of byte overlap — the caller must consume the exact same
- *  `parsed.symbols` array (or an equivalently-ordered copy) to look up a
- *  symbol by the index this function returns. 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. */
+ *  The result is keyed by the symbol's INDEX in `parsed.symbols`, not its start
+ *  byte: two distinct symbols can share a start byte (a synthetic whole-file root
+ *  beside others starting at byte 0), so callers must look symbols up in the same
+ *  array order. Each value maps callee name -> memberOnly, true iff every
+ *  occurrence of that callee inside the symbol was a member call, so the indexer
+ *  can resolve member calls conservatively. */
 export declare function attributeCalls(parsed: ParsedFile): Map<number, Map<string, boolean>>;
 /** Map each call bound to an imported module — `ns.fn()` through a module-object
  *  binding, or `g()` through an aliased member import — to the innermost symbol

package/dist/extractors/parse.js

@@ -20,28 +20,30 @@ function bundleFor(spec) {
     }
     return b;
 }
+/** Per-spec templating markers with g/y stripped, so `.test()` is stateless.
+ *  Built once per language spec rather than on every parseSource call. */
+const statelessMarkers = new WeakMap();
+function templatingMarkersFor(spec) {
+    let markers = statelessMarkers.get(spec);
+    if (!markers) {
+        markers = (spec.templatingMarkers ?? []).map((re) => new RegExp(re.source, re.flags.replace(/[gy]/g, "")));
+        statelessMarkers.set(spec, markers);
+    }
+    return markers;
+}
 const STR_QUOTES = /^['"`]|['"`]$/g;
-/** Cap on a stored symbol's bodyText — large enough for review context, small
- *  enough that a huge function/file doesn't bloat every JSON symbol record. */
+/** Cap on stored symbol body text: enough context for review without bloating JSON records. */
 export const MAX_BODY_TEXT_CHARS = 4000;
 export function parseSource(file, source, opts = {}) {
     const spec = languageFor(file);
     if (!spec)
         return null;
-    // Templated text (Helm chart / Jinja CI config) isn't {spec.id} yet — a real
-    // grammar correctly reports ERROR nodes for the delimiters. Still run the
-    // parse below (a well-formed anchor elsewhere in the file still contributes
-    // a real symbol, same as any other YAML file) — just don't let those
-    // expected errors fail-close the whole-repo scan on content that was never
-    // meant to stand alone (#33). Heavy top-level templating can break error
-    // recovery badly enough that even the whole-file root node never forms
-    // (root.type becomes "ERROR", not "stream") — the fallback-symbol synthesis
-    // below covers that case so the file doesn't vanish from the component graph.
-    // String.prototype.search ignores lastIndex (unlike RegExp.test with a /g or
-    // /y flag), so a future templatingMarkers entry can't introduce cross-call
-    // statefulness here even if it forgets to keep its pattern flag-free.
-    const templated = (spec.alwaysTemplatedExtensions?.some((ext) => file.endsWith(ext)) ?? false)
-        || (spec.templatingMarkers?.some((marker) => source.search(marker) !== -1) ?? false);
+    // Templated text is not valid language text until rendered. Still parse, so real
+    // anchors/symbols are extracted, but do not let the expected errors mark the file
+    // unparseable. Severe templating may stop even the root document node from
+    // forming; the fallback whole-file symbol below covers that case.
+    const templated = (spec.alwaysTemplatedExtensions ?? []).some((ext) => file.endsWith(ext))
+        || templatingMarkersFor(spec).some((re) => re.test(source));
     const { parser, query, bindingQuery } = 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"
@@ -94,15 +96,12 @@ export function parseSource(file, source, opts = {}) {
         const cname = cap.name;
         const node = cap.node;
         if (cname.endsWith(".def")) {
-            // 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).
+            // First classification wins: a node matched by several patterns keeps the
+            // kind it received first (Python nested methods, Go struct/interface specs).
             if (!pendingDefs.has(node.id))
                 pendingDefs.set(node.id, { kind: spec.defKindOf[cname], def: node });
         }
-        else if (spec.nameToDef[cname]) {
+        else if (Object.hasOwn(spec.nameToDef, cname)) {
             // name capture: find its parent def node id by walking up to the def type
             const defNode = ascendToDef(node, spec.defNodeTypes);
             if (defNode) {
@@ -168,29 +167,21 @@ export function parseSource(file, source, opts = {}) {
         }
     }
     for (const { kind, def, name } of pendingDefs.values()) {
-        const resolvedName = name ?? spec.fallbackDefName?.(file);
-        if (!resolvedName)
+        const symbolName = name ?? spec.fallbackDefName?.(file);
+        if (!symbolName)
             continue;
         const loc = def.endPosition.row - def.startPosition.row + 1;
         symbols.push({
-            name: resolvedName, kind,
+            name: symbolName, kind,
             startByte: def.startIndex, endByte: def.endIndex, loc,
             bodyText: originalText(def).slice(0, MAX_BODY_TEXT_CHARS),
         });
     }
-    // Every other successfully-parsed YAML file gets at least a file-root symbol
-    // (fallbackDefName). If templating broke error recovery badly enough that
-    // the doc.def capture never fired, synthesize the same fallback here rather
-    // than let the file silently drop out of the component graph. Push it before
-    // the sort below — parse()'s callers (indexer.ts) rely on symbols staying in
-    // start-byte order.
+    // Severe templating can stop the root node from forming; synthesize the whole-file symbol.
     if (templated && spec.fallbackDefName && !symbols.some((s) => s.kind === "file")) {
         symbols.push({
-            name: spec.fallbackDefName(file),
-            kind: "file",
-            startByte: 0,
-            endByte: source.length,
-            loc: source.split("\n").length,
+            name: spec.fallbackDefName(file), kind: "file",
+            startByte: 0, endByte: source.length, loc: source.split("\n").length,
             bodyText: source.slice(0, MAX_BODY_TEXT_CHARS),
         });
     }
@@ -241,7 +232,7 @@ function inToleratedScope(node, scopes) {
     }
     return false;
 }
-/** Walk up to the nearest node whose type is a definition this language recognizes. */
+/** Nearest ancestor of `node` whose type is a definition type, or null. */
 function ascendToDef(node, defNodeTypes) {
     let cur = node.parent;
     while (cur) {
@@ -252,17 +243,12 @@ function ascendToDef(node, defNodeTypes) {
     return null;
 }
 /** Map each call site to the innermost symbol whose byte-range contains it.
- *  Keyed by the symbol's position (index) in `parsed.symbols` — NOT its
- *  startByte, which is not a reliable per-symbol identity: a language whose
- *  extractor merges a synthetic whole-file symbol with independently-derived
- *  symbols (e.g. YAML's fallback-root synthetic symbol alongside Helm's
- *  regex-derived `define` blocks) can produce two distinct symbols that both
- *  start at byte 0. Indexing by array position is unique by construction,
- *  regardless of byte overlap — the caller must consume the exact same
- *  `parsed.symbols` array (or an equivalently-ordered copy) to look up a
- *  symbol by the index this function returns. 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. */
+ *  The result is keyed by the symbol's INDEX in `parsed.symbols`, not its start
+ *  byte: two distinct symbols can share a start byte (a synthetic whole-file root
+ *  beside others starting at byte 0), so callers must look symbols up in the same
+ *  array order. Each value maps callee name -> memberOnly, true iff every
+ *  occurrence of that callee inside the symbol was a member call, so the indexer
+ *  can resolve member calls conservatively. */
 export function attributeCalls(parsed) {
     const out = new Map();
     for (const call of parsed.calls) {
@@ -278,9 +264,11 @@ export function attributeCalls(parsed) {
             }
         }
         if (best && best.name !== call.callee) {
-            if (!out.has(bestIndex))
-                out.set(bestIndex, new Map());
-            const m = out.get(bestIndex);
+            let m = out.get(bestIndex);
+            if (!m) {
+                m = new Map();
+                out.set(bestIndex, m);
+            }
             const prev = m.get(call.callee);
             m.set(call.callee, prev === undefined ? call.member : prev && call.member);
         }

package/dist/integrations/claudemd.js

@@ -82,6 +82,7 @@ export function renderHunchSection(store, root) {
         bugs: store.json.loadAll("bugs").length,
         constraints: store.json.loadAll("constraints").length,
         components: store.json.loadAll("components").length,
+        // Public policies only: private-overlay policies must not change the committed block.
         policies: root ? new PolicyRepository(root, store).listPolicies({ publicOnly: true }).length : 0,
         findings: store.json.loadAll("findings").filter((f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled").length,
     };

package/dist/integrations/gitignore.js

@@ -32,12 +32,10 @@ const ENTRIES = [
     ".hunch/local.json",
     // The strict hook's append-only catch-log: clone-local, never a memory record.
     ".hunch/events.log",
-    // The post-merge hook's queue of detected-but-unconfirmed commit-provenance
-    // repairs — clone-local scratch state, never committed (`hunch repair-provenance
-    // --apply` confirms and clears it).
+    // The post-merge hook's clone-local queue of unconfirmed provenance repairs —
+    // never committed; cleared by `hunch repair-provenance --apply`.
     ".hunch/pending-commit-repairs.json",
-    // Tombstones for commit-repair matches a human rejected via `--drop` — clone-local
-    // scratch state, same discipline as the queue above.
+    // Tombstones for matches rejected via `--drop` — clone-local, never committed.
     ".hunch/dropped-commit-repairs.json",
     // A local PRIVATE overlay store (HUNCH_PRIVATE_DIR) for sensitive memory — never
     // committed. This is the conventional in-repo path; point the env elsewhere for a