@davesheffer/hunch 1.1.1 → 1.2.0

package/README.md

@@ -131,6 +131,7 @@ cd your-repo
 hunch init                          # scaffold .hunch/, index, install hooks, wire up assistants
 hunch backfill --since 90d          # cold start: seed decisions from recent git history
 hunch why src/auth/session.ts       # …then ask your assistant: "why is X built this way?"
+hunch structure src/auth            # the map, from the graph — no grep rounds
 ```
 
 **Claude Code users — one-step plugin install** (MCP tools + `/hunch:capture`, `/hunch:heal`, `/hunch:why`, `/hunch:fix`, `/hunch:fragile`):

package/dist/cli/index.js

@@ -45,7 +45,7 @@ import { updateClaudeMd } from "../integrations/claudemd.js";
 import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
 import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding } from "../integrations/providers.js";
 import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
-import { formatContext } from "../core/format.js";
+import { formatContext, formatStructure } from "../core/format.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
@@ -1843,6 +1843,21 @@ program
         store.close();
     }
 });
+// ---- structure (graph-served orientation — the anti-grep) -------------------
+program
+    .command("structure")
+    .description("The indexed shape of the repo, a directory, a file, or a symbol — orient from the graph instead of grep rounds. No target: repo map. Read-only.")
+    .argument("[target]", "a directory, file path, or exact symbol name (omit for the repo map)")
+    .action((target) => {
+    const { store } = storeFor();
+    try {
+        store.reindex(); // reflect out-of-band JSON edits before reading the graph
+        console.log(formatStructure(store.structure(target)));
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- impact (PR impact — read-only, advisory) ------------------------------
 program
     .command("impact")

package/dist/core/format.js

@@ -43,4 +43,50 @@ export function formatContext(ctx) {
         trimmed = trimmed.slice(0, lastNl);
     return trimmed + "\n… (trimmed to budget)\n";
 }
+/** Render a StructureView as a compact orientation brief (hunch_structure). */
+export function formatStructure(v) {
+    const NL = "\n";
+    if (v.kind === "none")
+        return `Nothing indexed matches "${v.target}" — not a known file, directory, or symbol. Run hunch index if the repo changed, or hunch_query for fuzzy search.`;
+    if (v.kind === "repo") {
+        const out = [`# Repo structure (from the graph — no grep needed)`];
+        if (v.components.length) {
+            out.push(`${NL}## Components`);
+            for (const c of v.components)
+                out.push(`- ${c.name}: ${c.responsibility} (${c.paths.join(", ")})`);
+        }
+        out.push(`${NL}## Directories (by symbol count)`);
+        for (const d of v.dirs.slice(0, 20))
+            out.push(`- ${d.dir} — ${d.files} file(s), ${d.symbols} symbol(s)`);
+        if (v.dirs.length > 20)
+            out.push(`  …(+${v.dirs.length - 20} more)`);
+        return out.join(NL);
+    }
+    if (v.kind === "dir") {
+        const out = [`# ${v.dir}/ — ${v.files.length} indexed file(s)`];
+        for (const f of v.files) {
+            const syms = f.symbols.slice(0, 8).map((s) => `${s.name}${s.fan_in ? ` (fan-in ${s.fan_in})` : ""}`).join(", ");
+            out.push(`- ${f.file}: ${syms}${f.symbols.length > 8 ? ` …(+${f.symbols.length - 8})` : ""}`);
+        }
+        return out.join(NL);
+    }
+    if (v.kind === "file") {
+        const out = [`# ${v.file} — outline (${v.symbols.length} symbol(s))`];
+        for (const sy of v.symbols) {
+            out.push(`- ${sy.name} [${sy.kind}] loc ${sy.loc}, fan-in ${sy.fan_in}, fan-out ${sy.fan_out}`);
+            if (sy.callers.length)
+                out.push(`    called by: ${sy.callers.join("; ")}`);
+        }
+        return out.join(NL);
+    }
+    const out = [`# "${v.matches[0]?.name}" — ${v.matches.length} definition site(s)`];
+    for (const m of v.matches) {
+        out.push(`- ${m.name} [${m.kind}] @ ${m.file} (fan-in ${m.fan_in}, fan-out ${m.fan_out})`);
+        if (m.callers.length)
+            out.push(`    called by: ${m.callers.join("; ")}`);
+        if (m.callees.length)
+            out.push(`    reaches:   ${m.callees.join("; ")}`);
+    }
+    return out.join(NL);
+}
 //# sourceMappingURL=format.js.map

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";
@@ -528,6 +528,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Architectural Conformance for AI-generated code: a git-native graph that deterministically blocks AI changes which break your architecture — the semantic invariants (layering, must-reach, dependency direction) pattern-SAST can't express — grounded in the decisions and bugs behind each rule, across any MCP assistant (Claude Code, Cursor, Copilot, Windsurf, Codex).",