@davesheffer/hunch 0.4.0 → 0.5.0

package/README.md

@@ -98,7 +98,8 @@ normally and Claude consults Hunch, or invoke the slash commands:
 | `/hunch-fragile` | a fragility report (the riskiest code, with evidence) |
 
 The MCP tools Claude calls under the hood: `hunch_why`, `hunch_query`,
-`hunch_check_constraints`, `hunch_get_dependents` (blast radius), `hunch_bug_lineage`,
+`hunch_check_constraints`, `hunch_get_dependents` (blast radius), `hunch_blast_radius`
+(dependent files + near-violations a change could break indirectly), `hunch_bug_lineage`,
 `hunch_context` (surgical minimal slice for a task), `hunch_record_decision` (write-back).
 
 **Through the CLI** — the same graph, from your terminal:

package/dist/cli/index.js

@@ -47,8 +47,8 @@ program
     .command("init")
     .description("Scaffold .hunch/, index the repo, install the git hook, and wire up Claude Code.")
     .option("--no-index", "skip the initial repo index")
-    .option("--enforce", "install an advisory pre-commit constraint guard")
-    .option("--enforce-strict", "install a pre-commit guard that FAILS the commit on a blocking invariant")
+    .option("--no-enforce", "do not install the advisory pre-commit constraint guard")
+    .option("--enforce-strict", "make the pre-commit guard FAIL the commit on a blocking invariant (direct or near)")
     .action((opts) => {
     const root = findRoot();
     const paths = hunchPaths(root);
@@ -70,9 +70,13 @@ program
         console.log(`  ✓ post-commit hook ${h.action} (learning loop)`);
         const m = installMergeDriver(root, inv.shell);
         console.log(`  ✓ team merge driver ${m.action}`);
-        if (opts.enforce || opts.enforceStrict) {
-            const p = installPreCommitHook(root, inv.shell, !!opts.enforceStrict);
-            console.log(`  ✓ pre-commit constraint guard ${p.action} (${opts.enforceStrict ? "strict — blocks on blocking invariants" : "advisory"})`);
+        // Auto-install the pre-commit guard by default (advisory: flags invariants
+        // touched directly OR via blast radius, never blocks). Opt out with
+        // --no-enforce; --enforce-strict makes blocking near/direct hits fail the commit.
+        if (opts.enforce !== false || opts.enforceStrict) {
+            const strict = !!opts.enforceStrict;
+            const p = installPreCommitHook(root, inv.shell, strict);
+            console.log(`  ✓ pre-commit constraint guard ${p.action} (${strict ? "strict — blocks on blocking invariants, direct or near" : "advisory — flags invariants in scope or blast radius"})`);
         }
     }
     else {

package/dist/mcp/server.js

@@ -38,6 +38,12 @@ function resolveSymbols(store, target) {
         return byName;
     return syms.filter((s) => s.file === target || s.file.endsWith(target));
 }
+/** Resolve a target to canonical indexed file path(s) (for file-granular blast
+ *  radius). Falls back to the literal target so direct-scope checks still run. */
+function resolveFiles(store, target) {
+    const files = new Set(resolveSymbols(store, target).map((s) => s.file));
+    return files.size ? [...files] : [target];
+}
 export function buildServer(root) {
     const store = new HunchStore(hunchPaths(root));
     // Ensure the SQLite index reflects the JSON source of truth on startup.
@@ -143,6 +149,35 @@ export function buildServer(root) {
         const lines = deps.slice(0, DEP_CAP).map((d) => `  • [depth ${d.depth}] ${d.via} (${d.id})`);
         return ok(`Blast radius of "${symbol}" — ${deps.length} dependent(s):\n${lines.join("\n")}${more(deps.length, DEP_CAP, "closest shown first")}`);
     });
+    // -- hunch_blast_radius (dependents + near-violations) --------------------
+    server.registerTool("hunch_blast_radius", {
+        title: "Blast radius + near-violations for a file",
+        description: "Given a file you're about to change, return its dependency blast radius (files whose code depends on it) AND any invariants reached THROUGH that radius — 'near-violations' you could break indirectly without touching their own scope. Call before editing a widely-depended-on file. Mirrors `hunch check --blast`.",
+        inputSchema: { target: z.string().describe("A file path (e.g. src/auth/jwt.ts) or symbol.") },
+    }, async ({ target }) => {
+        const parts = [];
+        for (const file of resolveFiles(store, target)) {
+            const blast = store.blastRadiusFiles(file);
+            const directIds = new Set(store.checkConstraints(file).map((c) => c.id));
+            const near = new Map();
+            for (const b of blast) {
+                for (const c of store.checkConstraints(b.file)) {
+                    if (directIds.has(c.id) || near.has(c.id))
+                        continue;
+                    near.set(c.id, { c, via: `${b.file} (${b.via}, depth ${b.depth})` });
+                }
+            }
+            const blastBody = blast.length
+                ? `:\n${blast.slice(0, DEP_CAP).map((b) => `  • [depth ${b.depth}] ${b.file} (via ${b.via})`).join("\n")}${more(blast.length, DEP_CAP, "closest first")}`
+                : "";
+            const nearArr = [...near.values()];
+            const nearBody = nearArr.length
+                ? `\n  NEAR-VIOLATIONS (invariants reachable via this radius — review before editing):\n${nearArr.map((n) => `    ⚠ ${n.c.id} [${n.c.severity}] ${n.c.statement}\n        via ${n.via}`).join("\n")}`
+                : "\n  No invariants in the blast radius.";
+            parts.push(`${file} → ${blast.length} dependent file(s)${blastBody}${nearBody}`);
+        }
+        return ok(`Blast radius for "${target}":\n\n${parts.join("\n\n")}`);
+    });
     // -- hunch_context (surgical retrieval) -----------------------------------
     server.registerTool("hunch_context", {
         title: "Assemble the minimal relevant Hunch slice for a task",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",