@davesheffer/hunch 1.8.0 → 1.8.2

package/dist/cli/index.js

@@ -29,7 +29,7 @@ import { selectEmbedder } from "../store/embedder.js";
 import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
-import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, } from "../synthesis/provider.js";
+import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, normalizeProviderName, } from "../synthesis/provider.js";
 import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, workingFiles, commitFiles, asOfDate, stagedDiff, workingDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, revParse, commitAndPushHunch, pullHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree, mainWorktreeRoot, gitMemoryLog, memoryMoveDiff, revertMemoryMove, pushCurrentBranch, commitChanges } from "../extractors/git.js";
 import { parseMemoryLog } from "../core/memorylog.js";
 import { renamesOf, planRepair, repairDecision, repairConstraint } from "../core/repair.js";
@@ -85,7 +85,7 @@ import { movePublicMemoryToPrivate } from "../store/privateMigrate.js";
 import { ENTITY_KINDS } from "../core/types.js";
 import { planCompaction } from "../store/compact.js";
 import { repairDecisionReference } from "../core/refrepair.js";
-import { resolveInvocation } from "./invocation.js";
+import { resolveInvocation, dim, synthesisStatusLines, maybeWarnOllamaContext } from "./invocation.js";
 const program = new Command();
 program.name("hunch").description("Hunch — an Engineering Memory OS: a git-native reasoning graph for your codebase.").version(HUNCH_VERSION);
 let openStore = null;
@@ -272,8 +272,8 @@ program
     .option("--since <spec>", "how far back, e.g. 90d", "90d")
     .option("--max <n>", "max commits to process", "40")
     .option("--concurrency <n>", "commits to synthesize in parallel (the LLM call is the bottleneck)", "4")
-    .option("--deep", "Deep Synthesis: ensemble every available subscription CLI per commit and reconcile their drafts (slower, higher-quality; advisory)")
-    .option("--verify", "Critic pass: audit each draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra subscription call; advisory)")
+    .option("--deep", "Deep Synthesis: ensemble every available LLM provider per commit and reconcile their drafts (slower, higher-quality; advisory)")
+    .option("--verify", "Critic pass: audit each draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra provider call; advisory)")
     .option("--samples <n>", "self-consistency depth when only one CLI is installed: sample it n times per commit and reconcile (default 2 under --deep)")
     .action(async (opts) => {
     const { store, root } = storeFor();
@@ -283,6 +283,15 @@ program
     const commits = logSince(opts.since, root, Number(opts.max));
     const conc = Math.max(1, Math.min(16, Number(opts.concurrency) || 4));
     console.log(`Backfilling from ${commits.length} commit(s) since ${opts.since} (concurrency ${conc})…`);
+    // Best-effort context-window advisory (issue #11): printed ONCE, before any
+    // commit is drafted — not per-commit, and not under --deep (an ensemble may
+    // fan out to several distinct workers, each with its own configuration).
+    if (!opts.deep && commits.length > 0) {
+        const ctxProvider = await selectProvider();
+        const ctxWarning = await maybeWarnOllamaContext(ctxProvider.name, process.env);
+        if (ctxWarning)
+            console.log(ctxWarning);
+    }
     let written = 0, skipped = 0, llm = 0, heuristic = 0;
     // The per-commit cost is the Claude synthesis spawn; run several at once. Safe:
     // each commit drafts independently and writes its OWN decision file atomically,
@@ -322,8 +331,8 @@ program
     .option("--overlay", "alias of --private")
     .option("--commit", "after a capture, also git add+commit the repo the decision landed in (default: follows auto-commit, ON unless opted out) — the overlay is also pushed; the public .hunch/ rides your next push")
     .option("--no-commit", "skip the auto-commit for this capture even when auto-commit is on")
-    .option("--deep", "Deep Synthesis: ensemble every available subscription CLI and reconcile their drafts (agreement-weighted, advisory). Slower; subscription-only")
-    .option("--verify", "Critic pass: audit the draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra subscription call; advisory)")
+    .option("--deep", "Deep Synthesis: ensemble every available LLM provider and reconcile their drafts (agreement-weighted, advisory). Slower; uses configured subscriptions/local endpoint")
+    .option("--verify", "Critic pass: audit the draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra provider call; advisory)")
     .option("--samples <n>", "self-consistency depth when only one CLI is installed: sample it n times and reconcile (default 2 under --deep)")
     .action(async (sha, opts) => {
     const { store, root } = storeFor();
@@ -2744,15 +2753,15 @@ program
     const next = writeConfig(paths, { firmness: level }).firmness;
     console.log(`✓ firmness set to ${next} (takes effect on the next agent edit — no restart needed).`);
 });
-// ---- provider (per-user synthesis subscription choice) -------------------
+// ---- provider (per-user synthesis provider choice) -----------------------
 program
     .command("provider")
-    .description("Show or set the local coding-assistant subscription Hunch may use for synthesis. Never changes team config.")
+    .description("Show or set the local LLM provider Hunch may use for synthesis. Never changes team config.")
     .argument("[name]", `auto | ${SYNTH_PREFERENCES.filter((p) => p !== "auto").join(" | ")} (omit to inspect)`)
     .action(async (value) => {
     const root = findRoot();
     if (value != null) {
-        const preference = value.trim();
+        const preference = normalizeProviderName(value.trim()) ?? value.trim();
         if (!SYNTH_PREFERENCES.includes(preference)) {
             return fail(`provider must be one of: ${SYNTH_PREFERENCES.join(", ")}`);
         }
@@ -2765,7 +2774,7 @@ program
         console.log(`✓ local synthesis preference set to ${preference} (gitignored; it never changes a teammate's billing choice).`);
     }
     const resolution = await resolveSynthesisProvider({ root });
-    const envValue = process.env.HUNCH_SYNTH_PROVIDER?.trim();
+    const envValue = normalizeProviderName(process.env.HUNCH_SYNTH_PROVIDER?.trim());
     const local = readSynthesisPreference(root);
     const hasValidEnv = !!envValue && SYNTH_PREFERENCES.includes(envValue);
     console.log(`selected:    ${resolution.provider.name} (${resolution.source})`);
@@ -2779,7 +2788,7 @@ program
     }
     if (resolution.source === "ambiguous") {
         const choices = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => `hunch provider ${s.name}`);
-        console.log(dim("Multiple subscription CLIs are available, so Hunch uses the free deterministic fallback rather than guessing which plan to spend."));
+        console.log(dim("Multiple LLM providers are available, so Hunch uses the free deterministic fallback rather than guessing which subscription or endpoint to use."));
         console.log(`choose one:  ${choices.join("  or  ")}`);
     }
     else if (resolution.source === "unavailable-preference") {
@@ -3313,7 +3322,7 @@ program
             console.log("✓ No drafts to auto-review.");
             return;
         }
-        // Delegate relevance to the harness (subscription CLI) — feature-detected.
+        // Delegate relevance to the configured LLM provider — feature-detected.
         // A dry-run may remain partial (missing verdicts are kept), but --apply is
         // all-or-nothing when judgment was requested: a provider outage must never
         // turn an incomplete batch into an apparently safe mutation plan.
@@ -3342,7 +3351,7 @@ program
                 }
             }
             else {
-                console.log(dim("No subscription CLI available — relevance judgment skipped (dedup + grounding only)."));
+                console.log(dim("No LLM synthesis provider available — relevance judgment skipped (dedup + grounding only)."));
                 judgmentFailures.push(...drafts.map((d) => ({ id: d.id, error: "no subscription relevance judge available" })));
             }
         }
@@ -3779,7 +3788,7 @@ program
 // ---- wiki (generated component wiki — a derived VIEW of the graph) ----------
 program
     .command("wiki")
-    .description("Generate a component wiki from the graph — pages are a derived VIEW (the graph stays the source of truth), pinned with hunch:topic anchors and freshness-hashed into a wiki-manifest. Stale pages surface as wiki-stale in `hunch drift`; --heal regenerates ONLY those. Prose via a subscription CLI when available; deterministic template otherwise. Default: PUBLIC-store records only, written to <repo>/wiki/. With --private: the FULL graph (overlay included), written into the private overlay repo — never committed here.")
+    .description("Generate a component wiki from the graph — pages are a derived VIEW (the graph stays the source of truth), pinned with hunch:topic anchors and freshness-hashed into a wiki-manifest. Stale pages surface as wiki-stale in `hunch drift`; --heal regenerates ONLY those. Prose via the configured LLM provider when available; deterministic template otherwise. Default: PUBLIC-store records only, written to <repo>/wiki/. With --private: the FULL graph (overlay included), written into the private overlay repo — never committed here.")
     .option("--dir <dir>", "output directory (default: wiki/, or the manifest's dir once adopted)")
     .option("--heal", "regenerate only new/stale pages (manifest hash mismatch) and remove orphans")
     .option("--check", "report stale pages and exit non-zero (CI gate); writes nothing")
@@ -3844,8 +3853,8 @@ program
         // otherwise: drift says "remove with --heal", --heal refuses to run).
         if (!status.entries.length && !opts.heal)
             return fail("no active components in the graph — run `hunch index` first.");
-        // Prose is optional garnish on the deterministic skeleton: subscription CLI
-        // only (same rule as synthesis), feature-detected, and any failure degrades
+        // Prose is optional garnish on the deterministic skeleton: configured LLM
+        // provider only (same guards as synthesis), feature-detected, and any failure degrades
         // to a template page — generation never depends on a model being present.
         if (opts.proseHeal && opts.llm === false)
             return fail("--prose-heal needs the LLM — drop --no-llm.");
@@ -3854,13 +3863,13 @@ program
         if (opts.llm !== false) {
             const provider = await selectProvider({ root });
             if (provider.draftProse) {
-                console.log(`Prose via ${provider.name} (subscription); the drift-bearing skeleton stays deterministic.`);
+                console.log(`Prose via ${provider.name}; the drift-bearing skeleton stays deterministic.`);
                 prose = (pack, excerpts) => provider.draftProse(wikiPrompt(pack, excerpts));
                 if (opts.proseHeal)
                     adoptionProse = (doc, content) => provider.draftProse(adoptProsePrompt(doc, content, status.decisions));
             }
             else {
-                console.log(`No subscription CLI available — deterministic template pages${opts.proseHeal ? " (prose-heal skipped)" : ""}.`);
+                console.log(`No LLM synthesis provider available — deterministic template pages${opts.proseHeal ? " (prose-heal skipped)" : ""}.`);
             }
         }
         const res = await generateWiki(store, root, home, {
@@ -4087,22 +4096,16 @@ program
     const resolution = await resolveSynthesisProvider({ root });
     const provider = resolution.provider;
     console.log(`synthesis:  ${provider.name} (${resolution.source})`);
-    const selected = resolution.statuses.find((s) => s.name === provider.name);
-    if (selected?.subscription) {
-        console.log(`            ↳ LLM synthesis uses your ${selected.subscription}; provider API credentials are not used.`);
-    }
-    else if (resolution.source === "ambiguous") {
-        const names = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => s.name);
-        console.log(dim(`            ↳ ${names.join(", ")} are available; Hunch will not guess which subscription to spend.`));
-        console.log(dim(`              choose one locally: ${names.map((name) => `hunch provider ${name}`).join("  or  ")}`));
-    }
-    else if (resolution.source === "unavailable-preference") {
-        console.log(dim(`            ↳ ${resolution.preference} was selected but is unavailable; using the offline heuristic.`));
-    }
-    else {
-        console.log(dim(`            ↳ no assistant CLI found — synthesis uses the offline heuristic (advisory, low-confidence).`));
-        console.log(dim(`              install or log into Claude Code, Codex, or Cursor; then select one with \`hunch provider <name>\`.`));
-    }
+    // Synthesis uses the user's SUBSCRIPTION via a coding-assistant CLI or a
+    // configured local/self-hosted endpoint. Public remotes require the named
+    // metered opt-in. Surface which one — or what's missing (issue #9:
+    // openai-compat has no `subscription` and must not fall through to the
+    // "no assistant CLI found" branch).
+    for (const line of synthesisStatusLines(resolution, process.env))
+        console.log(line);
+    const ctxWarning = await maybeWarnOllamaContext(provider.name, process.env);
+    if (ctxWarning)
+        console.log(ctxWarning);
     const c = store.reindex().counts;
     console.log(`hunch:      ${c.symbols} symbols, ${c.edges} edges, ${c.components} components, ${c.decisions} decisions, ${c.bugs} bugs, ${c.constraints} constraints`);
     try {
@@ -4199,9 +4202,6 @@ function reportClaudeConfigHeal() {
     }
     console.log(dim(`  ↳ backup: ${res.backup}`));
 }
-function dim(s) {
-    return `\x1b[2m${s}\x1b[0m`;
-}
 function fail(msg) {
     console.error(`error: ${msg}`);
     process.exitCode = 1;

package/dist/cli/invocation.js

@@ -1,8 +1,61 @@
-/** Figures out how to re-invoke this CLI from a git hook / .mcp.json, working
- *  both when running the built dist (plain node) and in dev via tsx. */
+/** Side-effect-free shared CLI logic — safe for any module (including tests)
+ *  to import, unlike src/cli/index.ts, which runs the whole program at
+ *  import time. Holds: how to re-invoke this CLI from a git hook / .mcp.json
+ *  (working both when running the built dist and in dev via tsx), plus small
+ *  formatting helpers (dim(), doctor's synthesisStatusLines()) that need the
+ *  same import-safety to be unit-testable. */
 import { fileURLToPath } from "node:url";
+import { probeOllamaNumCtx } from "../synthesis/provider.js";
 /** Published package name — used for OS-agnostic invocations (see below). */
 const PKG = "@davesheffer/hunch";
+export function dim(s) {
+    return `\x1b[2m${s}\x1b[0m`;
+}
+/** The doctor command's synthesis-status line(s) for a resolved provider.
+ *  Exported for testing — the previous version (a bare provider-name switch,
+ *  before the resolveSynthesisProvider preference system existed) had zero
+ *  test coverage, which is how issue #8 (openai-compat misreported as "no
+ *  assistant CLI found") shipped unnoticed through three review passes. That
+ *  bug resurfaces here for the same reason: resolution.statuses carries a
+ *  `subscription` field for the CLI providers but openai-compat's is null (it
+ *  isn't a subscription), so it must be special-cased explicitly rather than
+ *  falling through to the "no assistant CLI" branch. */
+export function synthesisStatusLines(resolution, env) {
+    const provider = resolution.provider;
+    const selected = resolution.statuses.find((s) => s.name === provider.name);
+    if (selected?.subscription) {
+        return [`            ↳ LLM synthesis uses your ${selected.subscription}; provider API credentials are not used.`];
+    }
+    if (provider.name === "openai-compat") {
+        const base = env.HUNCH_SYNTH_BASE_URL ?? "(unset)";
+        const model = env.HUNCH_SYNTH_MODEL ?? "(unset)";
+        const keyNote = env.HUNCH_SYNTH_API_KEY ? " (HUNCH_SYNTH_API_KEY set)" : " (no API key)";
+        return [`            ↳ LLM synthesis via local/self-hosted endpoint ${base} (model: ${model})${keyNote}`];
+    }
+    if (resolution.source === "ambiguous") {
+        const names = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => s.name);
+        return [
+            dim(`            ↳ ${names.join(", ")} are available; Hunch will not guess which provider to use.`),
+            dim(`              choose one locally: ${names.map((name) => `hunch provider ${name}`).join("  or  ")}`),
+        ];
+    }
+    if (resolution.source === "unavailable-preference") {
+        return [dim(`            ↳ ${resolution.preference} was selected but is unavailable; using the offline heuristic.`)];
+    }
+    return [
+        dim(`            ↳ no assistant CLI found — synthesis uses the offline heuristic (advisory, low-confidence).`),
+        dim(`              install or log into Claude Code, Codex, or Cursor; then select one with \`hunch provider <name>\`.`),
+    ];
+}
+/** Gate + fetch the Ollama context-window advisory (issue #11): only relevant
+ *  for the openai-compat provider, so every other provider is a no-op. Kept
+ *  separate from synthesisStatusLines (sync, already fully covered) because
+ *  this one makes a best-effort network call. */
+export async function maybeWarnOllamaContext(providerName, env) {
+    if (providerName !== "openai-compat")
+        return null;
+    return probeOllamaNumCtx(env.HUNCH_SYNTH_BASE_URL ?? "", env.HUNCH_SYNTH_MODEL ?? "");
+}
 export function resolveInvocation() {
     const entry = fileURLToPath(import.meta.url).replace(/invocation\.(js|ts)$/, "index.$1");
     const isDev = entry.endsWith(".ts");

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 {