@davesheffer/hunch 1.1.1 → 1.2.2

package/dist/mcp/server.js

@@ -19,7 +19,7 @@ import { refreshExistingGrounding } from "../integrations/providers.js";
 import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, pullHunch } from "../extractors/git.js";
 import { flushCapture } from "../integrations/sync.js";
 import { ensureTeamOverlay } from "../integrations/team.js";
-import { formatContext } from "../core/format.js";
+import { formatContext, formatStructure } from "../core/format.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
 import { renderMarkdown, renderImpact, verdict } from "../core/checkreport.js";
@@ -29,6 +29,15 @@ import { issueCaptureToken as issueToken, consumeCaptureToken as consumeToken }
 import { randomUUID } from "node:crypto";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const err = (text) => ({ content: [{ type: "text", text }], isError: true });
+/** Honest auto-commit suffix: reports only what flushCapture ACTUALLY did. A skipped
+ *  commit (backstop/lock/nothing staged) says nothing — the record is on disk and the
+ *  next flush sweeps it up; claiming "auto-committed" there would be a lie. */
+const flushNote = (flush, home, mode) => flush === "pushed" ? ` (committed + pushed to the ${mode === "shared" ? "shared team store" : "private repo"})`
+    : flush === "committed"
+        ? home === "private"
+            ? " (committed to the overlay repo — push deferred: offline, no upstream, or merge conflict; the next capture or `hunch private --sync` retries)"
+            : " (auto-committed to .hunch/ — rides your next push)"
+        : "";
 // Read-side token budgets: every tool result is injected into a Claude Code
 // session, so an uncapped list pollutes the context window. Cap each list to its
 // highest-signal head (records are pre-sorted by severity/confidence) and tell the
@@ -422,8 +431,7 @@ export function buildServer(root) {
             // record commits+pushes its overlay repo; a public one commits .hunch/ in THIS repo
             // (commit only — it rides the user's next push, never auto-pushing their code branch).
             const flush = flushCapture(store, hunchPaths(root).hunch, !!decision.private, `hunch: capture ${id}`);
-            const flushed = flush === "pushed" ? ` (committed + pushed to the ${store.mode === "shared" ? "shared team store" : "private repo"})`
-                : flush === "committed" ? " (auto-committed to .hunch/ — rides your next push)" : "";
+            const flushed = flushNote(flush, home, store.mode);
             // Capture-session gate (staged deprecation, §9.3): a token proves an interview
             // preceded the write. No token still writes (non-breaking), but returns a nudge
             // toward /capture so the un-interviewed bypass is visible, not silent. A token
@@ -480,8 +488,7 @@ export function buildServer(root) {
             if (home === "public")
                 refreshExistingGrounding(root, store); // overlay rules never render into committed grounding
             const flush = flushCapture(store, hunchPaths(root).hunch, !!input.private, `hunch: capture ${rec.id}`);
-            const flushed = flush === "pushed" ? ` (committed + pushed to the ${store.mode === "shared" ? "shared team store" : "private repo"})`
-                : flush === "committed" ? " (auto-committed to .hunch/ — rides your next push)" : "";
+            const flushed = flushNote(flush, home, store.mode);
             const enforce = rec.severity === "blocking"
                 ? "blocks a DIRECT edit to its scope at strict firmness, and fails a PR whose diff touches that scope (CI guard); blast-radius hits and lower firmness stay advisory"
                 : "flags violating edits and PRs (advisory)";
@@ -528,6 +535,14 @@ export function buildServer(root) {
             return err(`Failed to compute merge verdict: ${e.message}`);
         }
     });
+    // -- hunch_structure (graph-served orientation — the anti-grep) ------------
+    server.registerTool("hunch_structure", {
+        title: "The indexed shape of the repo / a dir / a file / a symbol",
+        description: "Orient WITHOUT grep/glob rounds: the graph already holds the repo's structure. No target → repo map (components + directories by symbol weight). A directory → its files with their symbols. A file → its outline (symbols, fan-in/out, callers). An exact symbol name → its definition site(s) with one-hop neighbors. Call this FIRST when exploring unfamiliar code — it tells you exactly which file to read, instead of searching for it.",
+        inputSchema: {
+            target: z.string().optional().describe("A directory, file path, or exact symbol name. Omit for the repo map."),
+        },
+    }, async ({ target }) => ok(formatStructure(store.structure(target))));
     // -- hunch_pr_impact (read-only impact surface — advisory, never gates) ----
     server.registerTool("hunch_pr_impact", {
         title: "PR impact: the dependency + memory surface of a change",

package/dist/store/hunchStore.js

@@ -705,6 +705,70 @@ export class HunchStore {
             decisions: [...decisions.values()],
         };
     }
+    /** Structure view (hunch_structure / hunch structure): serve the indexed shape of
+     *  the repo so an agent ORIENTS from the graph instead of running grep/glob rounds.
+     *  Resolution: no target -> repo map; a directory -> its files+symbols; a file ->
+     *  its outline; a symbol name -> exact definition site(s) with one-hop neighbors.
+     *  Deterministic, read-only, straight from the derived index. */
+    structure(target) {
+        if (!target || !target.trim()) {
+            const components = this.recs("components").map((c) => ({ id: c.id, name: c.name, responsibility: c.responsibility, paths: c.paths }));
+            const rows = this.db.prepare(`SELECT file, count(*) AS n FROM symbols GROUP BY file`).all();
+            const dirs = new Map();
+            for (const r of rows) {
+                const dir = r.file.includes("/") ? r.file.slice(0, r.file.lastIndexOf("/")) : ".";
+                const e = dirs.get(dir) ?? { files: 0, symbols: 0 };
+                e.files++;
+                e.symbols += r.n;
+                dirs.set(dir, e);
+            }
+            return {
+                kind: "repo",
+                components,
+                dirs: [...dirs.entries()].map(([dir, v]) => ({ dir, ...v })).sort((a, b) => b.symbols - a.symbols),
+            };
+        }
+        const t = toPosixTarget(target.trim()).replace(/\/+$/, "");
+        // FILE: exact path or unique suffix
+        const fileRows = this.db.prepare(`SELECT id, name, kind, loc, fan_in, fan_out FROM symbols WHERE file = ? ORDER BY fan_in DESC, name`).all(t);
+        const fileHit = fileRows.length ? t : this.db.prepare(`SELECT DISTINCT file FROM symbols WHERE file LIKE ?`).all(`%/${t}`).map((r) => r.file);
+        const file = typeof fileHit === "string" ? fileHit : fileHit.length === 1 ? fileHit[0] : null;
+        if (file) {
+            const syms = fileRows.length ? fileRows : this.db.prepare(`SELECT id, name, kind, loc, fan_in, fan_out FROM symbols WHERE file = ? ORDER BY fan_in DESC, name`).all(file);
+            return {
+                kind: "file",
+                file,
+                symbols: syms.map((r) => ({ ...r, callers: this.edgeNeighbors(r.id, "in", 5) })),
+            };
+        }
+        // DIRECTORY: any indexed file under the prefix
+        const dirFiles = this.db.prepare(`SELECT file, name, kind, fan_in FROM symbols WHERE file LIKE ? ORDER BY file, fan_in DESC`).all(`${t}/%`);
+        if (dirFiles.length) {
+            const byFile = new Map();
+            for (const r of dirFiles) {
+                const list = byFile.get(r.file) ?? [];
+                list.push({ name: r.name, kind: r.kind, fan_in: r.fan_in });
+                byFile.set(r.file, list);
+            }
+            return { kind: "dir", dir: t, files: [...byFile.entries()].map(([f, symbols]) => ({ file: f, symbols })) };
+        }
+        // SYMBOL: exact name
+        const named = this.db.prepare(`SELECT id, name, kind, file, fan_in, fan_out FROM symbols WHERE name = ? LIMIT 10`).all(t);
+        if (named.length) {
+            return {
+                kind: "symbol",
+                matches: named.map((m) => ({ ...m, callers: this.edgeNeighbors(m.id, "in", 6), callees: this.edgeNeighbors(m.id, "out", 6) })),
+            };
+        }
+        return { kind: "none", target: t };
+    }
+    /** Labelled one-hop edge neighbors of a node ("in" = who reaches it, "out" = what it reaches). */
+    edgeNeighbors(id, dir, limit) {
+        const sql = dir === "in"
+            ? `SELECT e."from" AS nb FROM edges e WHERE e."to" = ? AND e.type IN ('calls','depends_on','imports','contains') LIMIT ?`
+            : `SELECT e."to" AS nb FROM edges e WHERE e."from" = ? AND e.type IN ('calls','depends_on','imports','contains') LIMIT ?`;
+        return this.db.prepare(sql).all(id, limit).map((r) => this.nodeLabel(r.nb));
+    }
     /** Constraints whose scope glob matches a path/glob (hunch_check_constraints).
      *  By default only ACTIVE invariants are returned — a retired constraint is no
      *  longer enforced. Pass `{ asOf }` to instead return the invariants in force at

package/dist/synthesis/provider.js

@@ -197,6 +197,15 @@ class CliSynthProvider {
             throw new Error(`${this.name}: no usable bug JSON in output`);
         return draft;
     }
+    /** Grounded prose for the wiki. Same subscription-only run() path (API keys
+     *  stripped). Throws on empty output so the caller falls back to its
+     *  deterministic template page. */
+    async draftProse(prompt) {
+        const text = (await this.run(prompt)).trim();
+        if (!text)
+            throw new Error(`${this.name}: empty prose output`);
+        return text;
+    }
     /** The Critic pass: audit a draft against its commit. Same subscription-only
      *  run() path (API keys stripped), so this never bills the pay-per-token API.
      *  Throws on unusable output so verifyDecisionSafe degrades to the un-audited

package/dist/wiki/adopt.js

@@ -0,0 +1,97 @@
+/**
+ * Doc adoption — the wiki TAKES OVER a stale doc. When the specs ledger grades
+ * a doc "stale" (do-not-trust), `hunch wiki` copies it into `<wiki>/docs/` as a
+ * WIKI-MANAGED page and heals the COPY against the graph:
+ *
+ *   - every pin to a superseded decision is RE-PINNED to the current one,
+ *   - a "graph correction" callout is injected right after each healed pin,
+ *     quoting the current decision (and what it rejected) so the stale prose
+ *     below it can be read safely,
+ *   - non-pin issues (proposed-but-shipped, dead code refs) surface in a
+ *     banner at the top.
+ *
+ * The ORIGINAL file is never touched — "Hunch never rewrites prose" applies to
+ * the user's files; the adopted copy is a generated artifact (hunch:wiki
+ * header), so healing it is regeneration, not prose-rewriting. From adoption
+ * on, the ledger and component pages route readers to the wiki copy; the copy
+ * is freshness-hashed over its INPUTS (source content + the current decision
+ * per pinned topic + issues), so a source edit or a graph move re-heals it,
+ * and a source doc that becomes grounded again (human healed the original) or
+ * disappears retires the copy automatically.
+ *
+ * Deterministic by construction: same source + same graph → byte-identical
+ * copy. No LLM anywhere in this path.
+ */
+import { createHash } from "node:crypto";
+import { parseDocAnchors } from "../core/docanchors.js";
+import { currentForTopic, rejectedForTopic } from "../core/topics.js";
+/** Page slug for an adopted doc: full rel path, kebab-cased ("docs/api-v2.md" →
+ *  "docs-api-v2"). Kebab-casing can collide across DIFFERENT rels ("docs/api-v2.md"
+ *  vs "docs-api/v2.md"), so a `taken` set disambiguates with a short content hash
+ *  of the rel — deterministic, and wikiStatus is the single caller that assigns
+ *  slugs (renderers receive the resulting paths; they never re-derive). */
+export function adoptedSlug(rel, taken) {
+    let slug = rel.replace(/\.md$/i, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "doc";
+    if (taken.has(slug))
+        slug = `${slug}-${createHash("sha256").update(rel).digest("hex").slice(0, 6)}`;
+    taken.add(slug);
+    return slug;
+}
+const clip = (s, n) => (s.length > n ? s.slice(0, n - 1).trimEnd() + "…" : s);
+/** The freshness hash of an adopted copy: source content + what the graph
+ *  currently says for each pinned topic (everything the renderer quotes,
+ *  including rejected alternatives) + the grade's issues. Any of these moving
+ *  re-heals the copy; the copy's own bytes are never an input. */
+export function adoptionHash(content, decisions, doc) {
+    const topical = doc.topics.map((t) => {
+        const cur = currentForTopic(decisions, t);
+        return {
+            topic: t,
+            current: cur ? { id: cur.id, decision: cur.decision, title: cur.title } : null,
+            rejected: rejectedForTopic(decisions, t),
+        };
+    });
+    return createHash("sha256")
+        .update(JSON.stringify({ content, topical, issues: doc.issues }))
+        .digest("hex").slice(0, 16);
+}
+/** Render the wiki-managed copy of a stale doc, healed against the graph. */
+export function renderAdoptedDoc(doc, content, decisions) {
+    const byId = new Map(decisions.map((d) => [d.id, d]));
+    const lines = content.split("\n");
+    const out = [];
+    out.push(`<!-- hunch:wiki doc:${doc.rel} — ADOPTED wiki-managed copy of \`${doc.rel}\`, healed against the graph by \`hunch wiki\`. The original graded stale and is preserved untouched; treat THIS page as the readable version. Do not edit by hand — edit the graph (or heal the original), then \`hunch wiki --heal\`. -->`);
+    out.push(`> ⚠ **Wiki-managed copy.** The original \`${doc.rel}\` no longer matches the decision graph and was adopted here. Pins below are healed to CURRENT decisions; corrections are inline. Heal the original to release it back (the copy retires automatically).`);
+    // Every grading issue is listed — a dangling pin with NO current successor gets
+    // no inline correction below, so the banner is its only visible explanation.
+    for (const i of doc.issues)
+        out.push(`> - ${i}`);
+    out.push("");
+    const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    for (const raw of lines) {
+        // Heal EVERY stale pin on the line, and only inside its own marker — a bare
+        // decision id in the surrounding prose must never be rewritten.
+        let line = raw;
+        const corrections = [];
+        for (const a of parseDocAnchors(raw)) {
+            if (!a.pin)
+                continue;
+            const pinned = byId.get(a.pin);
+            const current = currentForTopic(decisions, a.topic);
+            const pinIsStale = (!pinned || pinned.status === "superseded" || !!pinned.superseded_by) && current && current.id !== a.pin;
+            if (!pinIsStale || !current)
+                continue;
+            line = line.replace(new RegExp(`(hunch:topic\\s+${escapeRe(a.topic)}\\s+)${escapeRe(a.pin)}(?![A-Za-z0-9])`), `$1${current.id}`);
+            corrections.push(`> **🧭 Graph correction** — this section was written against ${pinned ? `superseded \`${a.pin}\`` : `\`${a.pin}\`, which no longer exists`}. Current decision for \`${a.topic}\` is \`${current.id}\` — **${current.title}**: ${clip(current.decision, 400)}`);
+            const rejected = rejectedForTopic(decisions, a.topic);
+            if (rejected.length)
+                corrections.push(`> Rejected along the way: ${rejected.slice(0, 3).map((r) => clip(r, 120)).join("; ")}`);
+        }
+        out.push(line);
+        if (corrections.length)
+            out.push(...corrections, "");
+    }
+    out.push("", "---", "", `_Adopted from \`${doc.rel}\` — a derived, wiki-managed copy. Regenerate: \`hunch wiki --heal\`._`, "");
+    return out.join("\n");
+}
+//# sourceMappingURL=adopt.js.map