@davesheffer/hunch 1.14.0 → 1.16.0

package/dist/cli/index.js

@@ -14,7 +14,7 @@
  *   doctor    environment diagnostics
  */
 import "./preflight.js"; // MUST stay the first import — Node-version gate before node:sqlite loads
-import { chmodSync, existsSync, lstatSync, readFileSync, readlinkSync, writeFileSync, mkdirSync, mkdtempSync, realpathSync, rmSync, rmdirSync, symlinkSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, readFileSync, readdirSync, readlinkSync, writeFileSync, mkdirSync, mkdtempSync, realpathSync, rmSync, rmdirSync, symlinkSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
 import { join, relative, dirname, basename, resolve, isAbsolute } from "node:path";
 import { tmpdir } from "node:os";
@@ -70,7 +70,9 @@ import { computeDrift } from "../core/drift.js";
 import { renderCompilerScorecard, scoreCompilerCaseBank } from "../constitution/scorecard.js";
 import { generateWiki, wikiStatus, wikiPrompt, publicHome, privateHome, readWikiManifestAt, nowData } from "../wiki/wiki.js";
 import { adoptProsePrompt } from "../wiki/adopt.js";
-import { topicCollisions, isInForce } from "../core/topics.js";
+import { topicCollisions, isInForce, liveForTopic } from "../core/topics.js";
+import { ADR_DIR_CANDIDATES, ADR_FILE_RE, mapAdrCorpus } from "../extractors/adrImport.js";
+import { exportMadrCorpus, isRegenerableMadr } from "../integrations/madrExport.js";
 import { pendingEscalations, policyEscalations } from "../core/escalations.js";
 import { premiseEscalations } from "../core/premises.js";
 import { parseDocAnchors, renderDocGrounding } from "../core/docanchors.js";
@@ -2984,6 +2986,124 @@ program
         console.log(`  ↳ promoted constraint ${r.constraint.id} [${r.constraint.severity}]: ${r.constraint.statement}`);
     store.close();
 });
+// ---- import-adr (MADR/Nygard corpus import — the MADR bridge, import half) --
+program
+    .command("import-adr")
+    .description("Import an existing MADR/Nygard ADR corpus (docs/adr etc.) into the decision graph — deterministic, no LLM. Re-running updates the same records (ids derive from file paths).")
+    .argument("[dir]", "ADR directory (default: probe docs/adr, docs/decisions, doc/adr, adr, docs/architecture/decisions)")
+    .option("--dry-run", "parse and report what would be imported without writing")
+    .option("--private", "write imported decisions into the private overlay instead of the committed store")
+    .action((dirArg, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const dir = dirArg
+            ? toPosixTarget(dirArg)
+            : ADR_DIR_CANDIDATES.find((c) => existsSync(join(root, c)) && readdirSync(join(root, c)).some((f) => ADR_FILE_RE.test(f)));
+        if (!dir || !existsSync(join(root, dir))) {
+            return fail(dirArg ? `ADR directory not found: ${dirArg}` : `no ADR corpus found (probed: ${ADR_DIR_CANDIDATES.join(", ")})`);
+        }
+        const files = readdirSync(join(root, dir)).filter((f) => ADR_FILE_RE.test(f)).sort();
+        if (!files.length)
+            return fail(`no NNNN-slug.md ADR files in ${dir}`);
+        const sources = files.map((f) => ({ relPath: `${dir}/${f}`, text: readFileSync(join(root, dir, f), "utf8") }));
+        const { decisions, warnings } = mapAdrCorpus(sources);
+        for (const w of warnings)
+            console.log(`  ⚠ ${w}`);
+        // Fail-safe topic anchoring: an import must never create a SECOND live
+        // decision on a topic the graph already anchors — drop the anchor, keep
+        // the record (visible, just not drift-anchored), and say so.
+        const existing = store.recs("decisions").filter((d) => !decisions.some((n) => n.id === d.id));
+        for (const d of decisions) {
+            if (d.status !== "accepted" || !d.topic)
+                continue;
+            if (liveForTopic(existing, d.topic).length) {
+                console.log(`  ⚠ topic ${d.topic} already has a live decision in the graph — importing ${d.id} un-anchored`);
+                d.topic = null;
+            }
+        }
+        if (opts.dryRun) {
+            for (const d of decisions) {
+                const window = d.valid_to ? `${d.valid_from ?? "?"} → ${d.valid_to}` : "in force";
+                console.log(`  ${d.id} [${d.status}] ${d.title} (${window})`);
+            }
+            console.log(`✓ dry run: ${decisions.length} ADR(s) parsed from ${dir}, nothing written`);
+            return;
+        }
+        store.json.ensureDirs();
+        let created = 0, updated = 0;
+        for (const d of decisions) {
+            if (store.getRec("decisions", d.id))
+                updated++;
+            else
+                created++;
+            store.putCapture("decisions", d, opts.private);
+        }
+        store.reindex();
+        const home = store.captureHome(!!opts.private);
+        if (home === "public" && !store.autoCommit)
+            refreshExistingGrounding(root, store);
+        const flush = flushCapture(store, hunchPaths(root).hunch, !!opts.private, `hunch: import ${decisions.length} ADR(s) from ${dir}`);
+        const live = decisions.filter((d) => d.status === "accepted").length;
+        console.log(`✓ imported ${decisions.length} ADR(s) from ${dir} (${created} new, ${updated} updated; ${live} live, ${decisions.length - live} historical)${opts.private ? " [private overlay]" : ""}`);
+        if (flush === "pushed")
+            console.log("  ↳ private memory committed + pushed");
+    }
+    finally {
+        store.close();
+    }
+});
+// ---- export-adr (MADR projection — the MADR bridge, export half) -----------
+program
+    .command("export-adr")
+    .description("Project the PUBLIC decision graph as a regenerated MADR 3.x corpus (a disposable build artifact — the graph stays the source of truth). Only files carrying the hunch:generated marker are ever overwritten.")
+    .argument("[dir]", "output directory (repo-relative)", "docs/adr")
+    .option("--dry-run", "render and report without writing")
+    .action((dirArg, opts) => {
+    const { store, root } = storeFor();
+    try {
+        const dir = toPosixTarget(dirArg);
+        // PUBLIC store only — an exported artifact is committable, so overlay
+        // records must never reach it (one-way privacy boundary).
+        const decisions = store.json.loadAll("decisions");
+        if (!decisions.length)
+            return fail("no public decisions to export");
+        const { files, backstageAnnotation } = exportMadrCorpus(decisions, dir);
+        const outDir = join(root, dir);
+        // The projection owns its directory outright: mixing generated output into
+        // a hand-written ADR corpus would duplicate numbering and corrupt every
+        // MADR reader of that dir. Any non-generated ADR-shaped file → refuse whole.
+        const existingGenerated = new Set();
+        if (existsSync(outDir)) {
+            for (const f of readdirSync(outDir)) {
+                if (!f.endsWith(".md"))
+                    continue;
+                const text = readFileSync(join(outDir, f), "utf8");
+                if (isRegenerableMadr(text))
+                    existingGenerated.add(f);
+                else if (ADR_FILE_RE.test(f)) {
+                    return fail(`${dir} holds a hand-written ADR corpus (${f} has no hunch:generated marker) — export to a different directory (e.g. \`hunch export-adr docs/adr-generated\`), or import it first with \`hunch import-adr ${dir}\``);
+                }
+            }
+        }
+        const stale = [...existingGenerated].filter((f) => !files.some((n) => n.name === f));
+        if (opts.dryRun) {
+            console.log(`✓ dry run: would write ${files.length} ADR(s) to ${dir}${stale.length ? `, remove ${stale.length} stale generated file(s)` : ""}`);
+            return;
+        }
+        mkdirSync(outDir, { recursive: true });
+        for (const f of files)
+            writeFileSync(join(outDir, f.name), f.text);
+        // A regeneration renumbers; previously generated files not in the new set
+        // are OURS (marker-verified) and stale — remove so the corpus stays coherent.
+        for (const f of stale)
+            rmSync(join(outDir, f));
+        console.log(`✓ exported ${files.length} ADR(s) to ${dir}${stale.length ? `; removed ${stale.length} stale generated file(s)` : ""}`);
+        console.log(`  ↳ Backstage: add to catalog-info.yaml metadata.annotations →  ${backstageAnnotation}`);
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- record-constraint (human-authored invariant) -------------------------
 program
     .command("record-constraint")

package/dist/extractors/adrImport.js

@@ -0,0 +1,286 @@
+/**
+ * MADR/Nygard ADR corpus import (roadmap: MADR bridge, import half).
+ *
+ * Deterministic, no-LLM: parse an existing `docs/adr`-style corpus into Decision
+ * records so an ADR-practicing repo gets a populated graph on day 1 instead of
+ * waiting for commit backfill. Mapping contract:
+ *   accepted            -> status accepted (live)
+ *   proposed/draft      -> status proposed
+ *   rejected            -> status rejected
+ *   superseded/deprecated -> status superseded, valid_to closed (bi-temporal)
+ *   "Considered Options" minus the chosen one -> alternatives_rejected
+ *   file slug           -> topic `adr.<slug>` (namespaced so an import can never
+ *                          collide with a live hand-captured topic; the CLI still
+ *                          drops the anchor entirely if a collision exists)
+ *   provenance          -> source "imported:madr", the ADR file as evidence
+ *
+ * Ids derive from the ADR's repo-relative path (decisionId("madr:<relPath>")),
+ * so re-importing an updated corpus is an idempotent per-record update, never a
+ * duplicate. Parsing is pure (string in, records out) — the CLI owns all IO.
+ */
+import { decisionId } from "../core/ids.js";
+/** Directories probed (in order) when no explicit dir is given — adr-tools'
+ *  default (doc/adr), MADR's (docs/decisions), and the common variants. */
+export const ADR_DIR_CANDIDATES = [
+    "docs/adr",
+    "docs/decisions",
+    "doc/adr",
+    "adr",
+    "docs/architecture/decisions",
+];
+/** An ADR file is NNNN-slug.md (adr-tools / MADR convention). Templates and
+ *  indexes (adr-template.md, README.md, index.md) never match. */
+export const ADR_FILE_RE = /^(\d{1,5})-([a-z0-9][a-z0-9._-]*)\.md$/i;
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+function frontmatterField(fm, key) {
+    const m = new RegExp(`^${key}:[ \\t]*(.+)$`, "mi").exec(fm);
+    if (!m)
+        return null;
+    return m[1].trim().replace(/^["']|["']$/g, "");
+}
+/** Split a markdown body into `## `-heading sections (heading -> body text).
+ *  `###` subsections stay inside their parent's body. */
+function sections(body) {
+    const out = new Map();
+    const lines = body.split(/\r?\n/);
+    let current = null;
+    let buf = [];
+    const flush = () => {
+        if (current !== null)
+            out.set(current.toLowerCase(), buf.join("\n").trim());
+        buf = [];
+    };
+    for (const line of lines) {
+        const h = /^##\s+(.+?)\s*$/.exec(line);
+        if (h && !line.startsWith("###")) {
+            flush();
+            current = h[1];
+        }
+        else if (current !== null) {
+            buf.push(line);
+        }
+    }
+    flush();
+    return out;
+}
+function sectionOf(secs, ...names) {
+    for (const n of names) {
+        const v = secs.get(n.toLowerCase());
+        if (v)
+            return v;
+    }
+    return "";
+}
+/** Top-level `- ` / `* ` list items of a section (MADR "Considered Options"). */
+function listItems(sectionText) {
+    const items = [];
+    for (const line of sectionText.split(/\r?\n/)) {
+        const m = /^[-*]\s+(.+)$/.exec(line.trim());
+        if (m)
+            items.push(stripMdLinks(m[1].trim()));
+    }
+    return items;
+}
+/** Consequences render either as a list or prose paragraphs; normalize to items. */
+function consequenceItems(sectionText) {
+    const items = listItems(sectionText);
+    if (items.length)
+        return items.map((i) => i.replace(/^(good|bad|neutral),\s*(because\s*)?/i, "").trim()).filter(Boolean);
+    const prose = sectionText.trim();
+    return prose ? [stripMdLinks(prose)] : [];
+}
+function stripMdLinks(s) {
+    return s.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").trim();
+}
+/** ADR cross-reference numbers in a status/frontmatter phrase, e.g.
+ *  "Superseded by [ADR-0007](0007-x.md)" or "supersedes 3". */
+function refNumbers(text) {
+    const out = [];
+    for (const m of text.matchAll(/(?:adr[-\s]?)?0*(\d{1,5})\b/gi))
+        out.push(Number(m[1]));
+    return out;
+}
+function mapStatus(raw) {
+    const s = raw.toLowerCase();
+    if (/supersed|deprecat/.test(s))
+        return "superseded";
+    if (/reject/.test(s))
+        return "rejected";
+    if (/accept|approv/.test(s))
+        return "accepted";
+    return "proposed";
+}
+/** Parse one ADR markdown file (MADR 3.x/4 frontmatter style or Nygard heading
+ *  style). Returns null when the filename doesn't follow NNNN-slug.md. */
+export function parseAdrMarkdown(text, relPath) {
+    const base = relPath.split("/").pop() ?? relPath;
+    const nameMatch = ADR_FILE_RE.exec(base);
+    if (!nameMatch)
+        return null;
+    const number = Number(nameMatch[1]);
+    const slug = nameMatch[2].toLowerCase();
+    const fmMatch = FRONTMATTER_RE.exec(text);
+    const fm = fmMatch ? fmMatch[1] : "";
+    const body = fmMatch ? text.slice(fmMatch[0].length) : text;
+    const titleMatch = /^#\s+(.+?)\s*$/m.exec(body);
+    // Nygard titles carry the number ("1. Record architecture decisions") — strip it.
+    const title = (titleMatch ? titleMatch[1] : slug.replace(/[-_]/g, " ")).replace(/^\d+\.\s*/, "").trim();
+    const secs = sections(body);
+    const statusSection = sectionOf(secs, "Status");
+    const statusRaw = frontmatterField(fm, "status") ?? statusSection.split(/\r?\n/).map((l) => l.trim()).filter(Boolean)[0] ?? "";
+    const status = mapStatus(statusRaw);
+    const date = frontmatterField(fm, "date");
+    // Cross-links live in the status phrase(s) and frontmatter supersede fields.
+    const statusText = `${statusRaw}\n${statusSection}`;
+    const supersededByNumbers = [];
+    const supersedesNumbers = [];
+    for (const line of statusText.split(/\r?\n/)) {
+        if (/superseded\s+by|deprecated\s+by|replaced\s+by/i.test(line))
+            supersededByNumbers.push(...refNumbers(line.replace(/.*?(?:by)/i, "")));
+        else if (/supersedes|replaces/i.test(line))
+            supersedesNumbers.push(...refNumbers(line.replace(/.*?(?:supersedes|replaces)/i, "")));
+    }
+    for (const key of ["superseded-by", "superseded_by"]) {
+        const v = frontmatterField(fm, key);
+        if (v)
+            supersededByNumbers.push(...refNumbers(v));
+    }
+    const fmSupersedes = frontmatterField(fm, "supersedes");
+    if (fmSupersedes)
+        supersedesNumbers.push(...refNumbers(fmSupersedes));
+    const decisionOutcome = sectionOf(secs, "Decision Outcome", "Decision");
+    const chosenMatch = /chosen option:\s*["“]?([^"”\n,]+)["”]?/i.exec(decisionOutcome);
+    const consideredOptions = listItems(sectionOf(secs, "Considered Options", "Options"));
+    // "### Consequences" nests inside Decision Outcome in MADR; Nygard has it top-level.
+    let consequencesText = sectionOf(secs, "Consequences");
+    if (!consequencesText) {
+        const nested = /###\s+Consequences\s*\r?\n([\s\S]*?)(?=\r?\n###\s|$)/i.exec(decisionOutcome);
+        if (nested)
+            consequencesText = nested[1].trim();
+    }
+    return {
+        relPath,
+        number,
+        slug,
+        title,
+        statusRaw,
+        status,
+        date,
+        context: stripMdLinks(sectionOf(secs, "Context and Problem Statement", "Context")).trim(),
+        decision: stripMdLinks(decisionOutcome.replace(/###\s+Consequences[\s\S]*$/i, "")).trim(),
+        consequences: consequenceItems(consequencesText),
+        consideredOptions,
+        chosenOption: chosenMatch ? chosenMatch[1].trim() : null,
+        supersedesNumbers: [...new Set(supersedesNumbers)],
+        supersededByNumbers: [...new Set(supersededByNumbers)],
+    };
+}
+export function adrDecisionId(relPath) {
+    return decisionId(`madr:${relPath}`);
+}
+/** Map a parsed corpus to Decision records. Pure: cross-links resolve by ADR
+ *  number WITHIN the given corpus only; unresolvable references become warnings,
+ *  never guessed ids. Bi-temporal closure: a superseded ADR's valid_to is its
+ *  successor's valid_from (falling back to the successor's date, then its own
+ *  date) so as-of queries see the corpus's real history. */
+export function mapAdrCorpus(sources) {
+    const warnings = [];
+    const parsed = [];
+    for (const src of sources) {
+        const p = parseAdrMarkdown(src.text, src.relPath);
+        if (!p) {
+            warnings.push(`${src.relPath}: filename does not follow NNNN-slug.md — skipped`);
+            continue;
+        }
+        parsed.push(p);
+    }
+    const byNumber = new Map();
+    for (const p of parsed) {
+        if (byNumber.has(p.number))
+            warnings.push(`duplicate ADR number ${p.number}: ${byNumber.get(p.number).relPath} and ${p.relPath} — cross-links resolve to the first`);
+        else
+            byNumber.set(p.number, p);
+    }
+    // Derive the missing half of each supersede link so a one-sided "Superseded by"
+    // still closes windows and sets both pointers.
+    for (const p of parsed) {
+        for (const n of p.supersedesNumbers) {
+            const target = byNumber.get(n);
+            if (!target) {
+                warnings.push(`${p.relPath}: supersedes ADR ${n}, which is not in the corpus`);
+                continue;
+            }
+            if (!target.supersededByNumbers.includes(p.number))
+                target.supersededByNumbers.push(p.number);
+        }
+        for (const n of p.supersededByNumbers) {
+            const successor = byNumber.get(n);
+            if (!successor) {
+                warnings.push(`${p.relPath}: superseded by ADR ${n}, which is not in the corpus`);
+                continue;
+            }
+            if (!successor.supersedesNumbers.includes(p.number))
+                successor.supersedesNumbers.push(p.number);
+        }
+    }
+    const decisions = parsed.map((p) => {
+        const successor = p.supersededByNumbers.map((n) => byNumber.get(n)).find(Boolean) ?? null;
+        const superseded = p.status === "superseded" || !!successor;
+        const validTo = superseded ? (successor?.date ?? p.date) : null;
+        const alternatives = p.consideredOptions.filter((o) => !p.chosenOption || o.toLowerCase() !== p.chosenOption.toLowerCase());
+        return {
+            id: adrDecisionId(p.relPath),
+            title: p.title,
+            topic: `adr.${p.slug}`,
+            status: superseded ? "superseded" : p.status,
+            context: p.context,
+            decision: p.decision || p.title,
+            consequences: p.consequences,
+            alternatives_rejected: alternatives,
+            rejected_tripwires: [],
+            related_components: [],
+            related_files: [p.relPath],
+            supersedes: p.supersedesNumbers.map((n) => byNumber.get(n)).filter(Boolean).map((t) => adrDecisionId(t.relPath))[0] ?? null,
+            superseded_by: successor ? adrDecisionId(successor.relPath) : null,
+            caused_by_bug: null,
+            commit: null,
+            valid_from: p.date ?? undefined,
+            valid_to: validTo,
+            retired: { symbols: [], deps: [] },
+            provenance: {
+                source: "imported:madr",
+                confidence: 0.75,
+                evidence: [p.relPath, `status: ${p.statusRaw || "(none)"}`],
+            },
+            date: p.date ?? new Date().toISOString(),
+        };
+    });
+    // A corpus must not import two LIVE decisions onto one topic (the store-wide
+    // one-live-per-topic invariant): keep the highest ADR number live, close the rest.
+    const liveByTopic = new Map();
+    for (const d of decisions) {
+        if (d.status === "accepted" && d.topic) {
+            const list = liveByTopic.get(d.topic) ?? [];
+            list.push(d);
+            liveByTopic.set(d.topic, list);
+        }
+    }
+    for (const [topic, list] of liveByTopic) {
+        if (list.length < 2)
+            continue;
+        list.sort((a, b) => adrNumberOf(a, parsed) - adrNumberOf(b, parsed));
+        const winner = list[list.length - 1];
+        for (const loser of list.slice(0, -1)) {
+            loser.status = "superseded";
+            loser.superseded_by = winner.id;
+            loser.valid_to = winner.valid_from ?? loser.date;
+            warnings.push(`topic ${topic}: two live ADRs — kept ${winner.id} live, closed ${loser.id}`);
+        }
+    }
+    return { decisions, warnings };
+}
+function adrNumberOf(d, parsed) {
+    const rel = d.related_files[0];
+    return parsed.find((p) => p.relPath === rel)?.number ?? 0;
+}
+//# sourceMappingURL=adrImport.js.map

package/dist/extractors/indexer.js

@@ -8,7 +8,8 @@
  * `indexRepo` persists that exact scan into the JSON source of truth; its caller
  * then runs HunchStore.reindex() to refresh the SQLite index.
  */
-import { dirname, posix } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, join, 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";
@@ -135,9 +136,15 @@ export function scanRepo(store, root, opts = {}) {
     // 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 goModule = readGoModulePath(root);
+    const resolveImportTarget = (file, spec) => {
+        const langId = languageFor(file)?.id;
+        if (langId === "python")
+            return resolvePythonImport(file, spec, fileSymbols, pyRoots);
+        if (langId === "go")
+            return resolveGoImport(spec, fileSymbols, goModule);
+        return resolveImport(file, spec, fileSymbols);
+    };
     const importedFiles = new Map(perFileImports.map(({ file, imports }) => [
         file,
         new Set(imports.map((specifier) => resolveImportTarget(file, specifier)).filter((target) => !!target)),
@@ -353,6 +360,48 @@ function resolvePythonImport(fromFile, spec, fileSymbols, pyRoots) {
     const modulePath = baseDir ? `${baseDir}/${tailPath}` : tailPath;
     return firstExistingPyModule(modulePath, fileSymbols);
 }
+/** The `module` path declared in the repo's go.mod, or null. A resolution HINT
+ *  only (it widens depends_on edge coverage); reading it best-effort from the
+ *  filesystem never gates a scan. */
+function readGoModulePath(root) {
+    try {
+        const match = /^module\s+(\S+)/m.exec(readFileSync(join(root, "go.mod"), "utf8"));
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Lexicographically-first tracked .go file whose directory is exactly `dir`
+ *  ("" = repo root) — a Go import names a PACKAGE (directory), so any file in it
+ *  identifies the right component for a depends_on edge. */
+function firstGoFileInDir(dir, fileSymbols) {
+    let best = null;
+    for (const f of fileSymbols.keys()) {
+        if (!f.endsWith(".go"))
+            continue;
+        const d = toPosix(dirname(f));
+        const matches = dir === "" ? d === "." : d === dir;
+        if (matches && (!best || f < best))
+            best = f;
+    }
+    return best;
+}
+/** Resolve a Go import path to a tracked file. Sibling to resolvePythonImport():
+ *  an in-module import is the go.mod module path plus the package directory, so
+ *  strip the declared module prefix and look the directory up exactly; with no
+ *  go.mod, try the path as a repo-relative directory. Anything else (stdlib,
+ *  external modules) resolves to null — no suffix guessing, a wrong depends_on
+ *  edge is worse than a missing one. */
+function resolveGoImport(spec, fileSymbols, goModule) {
+    if (goModule) {
+        if (spec === goModule)
+            return firstGoFileInDir("", fileSymbols);
+        if (spec.startsWith(`${goModule}/`))
+            return firstGoFileInDir(spec.slice(goModule.length + 1), fileSymbols);
+    }
+    return firstGoFileInDir(spec, 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

@@ -125,7 +125,55 @@ const PYTHON = {
     nameToDef: { "fn.name": "fn.def", "method.name": "method.def", "class.name": "class.def" },
     builtinMethods: PY_BUILTIN_METHODS,
 };
-export const LANGUAGES = [TYPESCRIPT, TSX, PYTHON];
+const GO_QUERY = `
+  (function_declaration name: (identifier) @fn.name) @fn.def
+  (method_declaration name: (field_identifier) @method.name) @method.def
+  ;; Specific type_spec shapes FIRST: parse.ts keeps the first classification a
+  ;; node id receives (same mechanism the Python class patterns rely on), so a
+  ;; struct/interface matches its specific pattern before the generic @type.def.
+  (type_spec name: (type_identifier) @struct.name type: (struct_type)) @struct.def
+  (type_spec name: (type_identifier) @iface.name type: (interface_type)) @iface.def
+  (type_spec name: (type_identifier) @type.name) @type.def
+  ;; \`type X = Y\` is a distinct type_alias node, not a type_spec.
+  (type_alias name: (type_identifier) @type.name) @type.def
+  (import_spec path: [(interpreted_string_literal) (raw_string_literal)] @import.src)
+  (call_expression function: (identifier) @call.id)
+  (call_expression function: (selector_expression field: (field_identifier) @call.member))
+`;
+/** In Go every package-qualified call (fmt.Println, strings.Split, t.Errorf) is a
+ *  selector_expression and therefore lands in @call.member — the DOMINANT call form.
+ *  This allowlist filters the highest-frequency stdlib/testing method+function names
+ *  so they never create false edges to same-named repo symbols; repo-specific member
+ *  calls (s.Run(), h.Handle()) pass through and resolve conservatively like TS/PY. */
+const GO_BUILTIN_METHODS = new Set([
+    "Error", "String", "Read", "Write", "Close", "Len", "Cap", "Reset", "Bytes", "Text",
+    "Scan", "Next", "Err", "Lock", "Unlock", "RLock", "RUnlock", "Done", "Add", "Wait",
+    "Print", "Printf", "Println", "Sprintf", "Fprintf", "Errorf", "Fatal", "Fatalf", "Fatalln",
+    "Log", "Logf", "Helper", "Run", "Parallel", "Skip", "Skipf", "Cleanup",
+    "Get", "Set", "Delete", "Load", "Store", "Range", "Value", "Context", "Deadline",
+    "Marshal", "Unmarshal", "Encode", "Decode", "Parse", "Format", "Sub", "Before", "After",
+    "Join", "Split", "Contains", "Replace", "ReplaceAll", "TrimSpace", "ToLower", "ToUpper",
+    "HasPrefix", "HasSuffix", "WriteString", "ReadString", "ReadAll", "Copy", "New", "Now",
+    "Since", "Sleep", "Unix", "Exec", "Query", "QueryRow", "Begin", "Commit", "Rollback",
+]);
+const GO = {
+    id: "go",
+    extensions: [".go"],
+    grammarKey: "go",
+    loadGrammar: () => loadNativeTreeSitter().go,
+    query: GO_QUERY,
+    defNodeTypes: new Set(["function_declaration", "method_declaration", "type_spec", "type_alias"]),
+    defKindOf: {
+        "fn.def": "function", "method.def": "method", "struct.def": "class",
+        "iface.def": "interface", "type.def": "type",
+    },
+    nameToDef: {
+        "fn.name": "fn.def", "method.name": "method.def", "struct.name": "struct.def",
+        "iface.name": "iface.def", "type.name": "type.def",
+    },
+    builtinMethods: GO_BUILTIN_METHODS,
+};
+export const LANGUAGES = [TYPESCRIPT, TSX, PYTHON, GO];
 export const CODE_EXTENSIONS = [...new Set(LANGUAGES.flatMap((l) => l.extensions))];
 export function languageFor(file) {
     for (const lang of LANGUAGES) {

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", "tree-sitter-python"];
+const NATIVE_PACKAGES = ["tree-sitter", "tree-sitter-typescript", "tree-sitter-python", "tree-sitter-go"];
 let runtime = null;
 function processIsAlive(pid) {
     if (pid === process.pid)
@@ -69,7 +69,7 @@ export function loadNativeTreeSitter() {
     // underscores (tree_sitter_runtime_binding.node, tree_sitter_python_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).
-    const preloaded = Object.keys(runtimeRequire.cache).filter((path) => /(?:tree-sitter(?:-typescript|-python)?|tree_sitter(?:_[a-z]+)*_binding)\.node$/.test(path)
+    const preloaded = Object.keys(runtimeRequire.cache).filter((path) => /(?:tree-sitter(?:-typescript|-python|-go)?|tree_sitter(?:_[a-z]+)*_binding)\.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(", ")}`);
@@ -87,7 +87,8 @@ export function loadNativeTreeSitter() {
         const Parser = runtimeRequire("tree-sitter");
         const languages = runtimeRequire("tree-sitter-typescript");
         const python = runtimeRequire("tree-sitter-python");
-        runtime = { Parser, typescript: languages.typescript, tsx: languages.tsx, python };
+        const go = runtimeRequire("tree-sitter-go");
+        runtime = { Parser, typescript: languages.typescript, tsx: languages.tsx, python, go };
     }
     catch (error) {
         try {

package/dist/integrations/madrExport.js

@@ -0,0 +1,109 @@
+export const MADR_EXPORT_MARKER = "<!-- hunch:generated madr-export — regenerated by `hunch export-adr`; edits will be overwritten -->";
+function slugify(title) {
+    const s = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60)
+        .replace(/-+$/, "");
+    return s || "decision";
+}
+function statusLine(d, nameOf) {
+    if (d.status === "superseded") {
+        const successor = d.superseded_by ? nameOf.get(d.superseded_by) : null;
+        return successor ? `superseded by [${successor}](${successor})` : "superseded";
+    }
+    return d.status;
+}
+/** Render one decision as a MADR 3.x document. Deterministic: content depends
+ *  only on the decision record and the corpus's name map. */
+export function renderMadr(d, nameOf) {
+    const lines = [];
+    lines.push("---");
+    lines.push(`status: ${statusLine(d, nameOf)}`);
+    const date = (d.valid_from ?? d.date).slice(0, 10);
+    lines.push(`date: ${date}`);
+    lines.push("---");
+    lines.push("");
+    lines.push(MADR_EXPORT_MARKER);
+    lines.push("");
+    lines.push(`# ${d.title}`);
+    if (d.context) {
+        lines.push("");
+        lines.push("## Context and Problem Statement");
+        lines.push("");
+        lines.push(d.context);
+    }
+    if (d.alternatives_rejected.length) {
+        lines.push("");
+        lines.push("## Considered Options");
+        lines.push("");
+        lines.push(`- ${d.title}`);
+        for (const alt of d.alternatives_rejected)
+            lines.push(`- ${alt}`);
+    }
+    lines.push("");
+    lines.push("## Decision Outcome");
+    lines.push("");
+    // Canonical MADR phrasing so the projection round-trips through import-adr:
+    // the "Chosen option:" line is what marks the winner among Considered Options.
+    if (d.alternatives_rejected.length) {
+        lines.push(`Chosen option: "${d.title}", because of the following.`);
+        if (d.decision) {
+            lines.push("");
+            lines.push(d.decision);
+        }
+    }
+    else {
+        lines.push(d.decision || d.title);
+    }
+    if (d.supersedes && nameOf.get(d.supersedes)) {
+        lines.push("");
+        lines.push(`Supersedes [${nameOf.get(d.supersedes)}](${nameOf.get(d.supersedes)}).`);
+    }
+    if (d.consequences.length) {
+        lines.push("");
+        lines.push("### Consequences");
+        lines.push("");
+        for (const c of d.consequences)
+            lines.push(`- ${c}`);
+    }
+    lines.push("");
+    lines.push(`<!-- source: ${d.id}${d.commit ? ` @ ${d.commit}` : ""} -->`);
+    lines.push("");
+    return lines.join("\n");
+}
+/** Project a PUBLIC decision list into a MADR corpus. Numbering is date order
+ *  (valid_from, then date, then id for determinism) and assigned per export —
+ *  the projection is disposable, links inside it are internally consistent. */
+export function exportMadrCorpus(decisions, dirForAnnotation) {
+    const sorted = [...decisions].sort((a, b) => {
+        const ka = `${a.valid_from ?? a.valid_to ?? a.date} ${a.valid_to ? 0 : 1} ${a.id}`;
+        const kb = `${b.valid_from ?? b.valid_to ?? b.date} ${b.valid_to ? 0 : 1} ${b.id}`;
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+    const nameOf = new Map();
+    const taken = new Set();
+    sorted.forEach((d, i) => {
+        let slug = slugify(d.title);
+        while (taken.has(slug))
+            slug = `${slug}-${d.id.slice(4, 10)}`;
+        taken.add(slug);
+        nameOf.set(d.id, `${String(i + 1).padStart(4, "0")}-${slug}.md`);
+    });
+    const files = sorted.map((d) => ({
+        name: nameOf.get(d.id),
+        text: renderMadr(d, nameOf),
+        decisionId: d.id,
+    }));
+    return {
+        files,
+        backstageAnnotation: `backstage.io/adr-location: ${dirForAnnotation}`,
+    };
+}
+/** True when an existing file may be overwritten by the export: only our own
+ *  generated output ever qualifies. */
+export function isRegenerableMadr(existingText) {
+    return existingText.includes(MADR_EXPORT_MARKER);
+}
+//# sourceMappingURL=madrExport.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -74,6 +74,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^15.0.0",
     "tree-sitter": "0.21.1",
+    "tree-sitter-go": "^0.23.4",
     "tree-sitter-python": "^0.23.2",
     "tree-sitter-typescript": "^0.23.2",
     "zod": "^4.4.3"

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://hunch-pi.vercel.app",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.14.0",
+      "version": "1.16.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {