@davesheffer/hunch 0.11.3 → 0.12.0

package/dist/cli/index.js

@@ -24,12 +24,14 @@ import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { selectProvider } from "../synthesis/provider.js";
-import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff } from "../extractors/git.js";
+import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff } from "../extractors/git.js";
 import { analyzeDiff } from "../extractors/diff.js";
 import { isStrictBlocker } from "../core/strictgate.js";
+import { renderText, renderMarkdown, reportFailsStrict } from "../core/checkreport.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { ensureGitignore } from "../integrations/gitignore.js";
+import { writeCiWorkflow } from "../integrations/ciAction.js";
 import { updateClaudeMd } from "../integrations/claudemd.js";
 import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
 import { scaffoldProviders } from "../integrations/providers.js";
@@ -534,54 +536,76 @@ program
 // ---- check (constraint enforcement) ---------------------------------------
 program
     .command("check")
-    .description("Flag changes that touch a do-not-break invariant's scope (guardrail).")
+    .description("Flag changes that touch a do-not-break invariant — the local guardrail AND the CI/PR Constraint Guard.")
     .option("--staged", "check git staged files (default)")
     .option("--commit <sha>", "check a specific commit's files")
+    .option("--base <ref>", "check a PR/branch: files changed vs <ref> (e.g. origin/main) — for CI")
     .option("--strict", "exit non-zero ONLY on a direct, high-confidence, non-stale blocking invariant (near/stale/low-confidence stay advisory)")
+    .option("--format <fmt>", "output: text (default) | markdown (a PR comment)", "text")
     .option("--blast", "also print the dependency blast radius of the changed files")
     .action((opts) => {
-    if (opts.commit && opts.staged)
-        return fail("--staged and --commit are mutually exclusive");
+    const sources = [opts.commit && "--commit", opts.base && "--base", opts.staged && "--staged"].filter(Boolean);
+    if (sources.length > 1)
+        return fail(`pick one of --staged / --commit / --base (got ${sources.join(", ")})`);
+    const markdown = opts.format === "markdown";
+    const emptyReport = { fileCount: 0, strict: !!opts.strict, direct: [], near: [], regressions: [], strictBlockers: 0, regBlocking: 0 };
     const { store, root } = storeFor();
     store.reindex(); // blast radius walks the edge graph — make the index current
-    const files = opts.commit ? commitFiles(opts.commit, root) : stagedFiles(root);
+    const files = opts.commit ? commitFiles(opts.commit, root)
+        : opts.base ? rangeFiles(opts.base, root)
+            : stagedFiles(root);
     if (!files.length) {
-        console.log("No changed files to check.");
+        console.log(markdown ? renderMarkdown(emptyReport) : "No changed files to check.");
         store.close();
         return;
     }
-    const mark = (s) => (s === "blocking" ? "⛔" : s === "warning" ? "⚠" : "·");
     // 1) DIRECT — a changed file matches a constraint's scope.
     const direct = new Map();
-    for (const f of files) {
+    for (const f of files)
         for (const c of store.checkConstraints(f)) {
             const e = direct.get(c.id) ?? { c, files: [] };
             e.files.push(f);
             direct.set(c.id, e);
         }
-    }
-    // 2) NEAR — a changed file's blast radius reaches a file an invariant guards:
-    //    you didn't touch the invariant, but you touched something it depends on.
+    // 2) NEAR — reached only through the blast radius (a guarded dependency changed).
     const near = new Map();
-    for (const f of files) {
-        for (const b of store.blastRadiusFiles(f)) {
+    for (const f of files)
+        for (const b of store.blastRadiusFiles(f))
             for (const c of store.checkConstraints(b.file)) {
                 if (direct.has(c.id))
-                    continue; // already reported as a direct hit
+                    continue; // already a direct hit
                 const e = near.get(c.id) ?? { c, via: [] };
                 e.via.push(`${f} → ${b.file} (${b.via}, depth ${b.depth})`);
                 near.set(c.id, e);
             }
-        }
-    }
-    // 3) REGRESSION — does the diff RE-ADD something an in-force decision removed?
-    //    (e.g. re-introducing a symbol/dep that was deliberately deleted). Warn
-    //    always; only a blocking-linked resurrection fails the commit under strict.
-    const diff = opts.commit ? commitDiff(opts.commit, root) : stagedDiff(root);
+    // 3) REGRESSION — does the diff RE-ADD something an in-force decision retired?
+    const diff = opts.commit ? commitDiff(opts.commit, root) : opts.base ? rangeDiff(opts.base, root) : stagedDiff(root);
     const an = analyzeDiff(diff);
     const regHits = store.regressionHits({ symbols: an.addedSymbols.map((s) => s.name), deps: an.addedDeps }, files);
-    const regBlocking = regHits.filter((h) => h.blocking).length;
-    if (opts.blast) {
+    // Hardened strict gate (strictgate.ts): only DIRECT + high-confidence + non-stale
+    // can fail. near/stale/low-confidence stay advisory — safe on a shared repo / PR.
+    const staleConstraintIds = opts.strict
+        ? new Set(store.staleness((f) => lastChangeDate(f, root)).filter((s) => s.kind === "constraint").map((s) => s.id))
+        : new Set();
+    const directReport = [...direct.values()].map(({ c, files: fs }) => {
+        const stale = staleConstraintIds.has(c.id);
+        const strictBlocks = isStrictBlocker(c, stale);
+        return {
+            id: c.id, severity: c.severity ?? "advisory", statement: c.statement, rationale: c.rationale ?? "",
+            files: fs, strictBlocks,
+            downgrade: (c.severity === "blocking" && !strictBlocks ? (stale ? "stale" : "low-confidence") : undefined),
+        };
+    });
+    const report = {
+        fileCount: files.length,
+        strict: !!opts.strict,
+        direct: directReport,
+        near: [...near.values()].map(({ c, via }) => ({ id: c.id, severity: c.severity ?? "advisory", statement: c.statement, via })),
+        regressions: regHits.map((h) => ({ kind: h.kind, name: h.name, decision: h.decision, title: h.title, reason: h.reason, blocking: h.blocking })),
+        strictBlockers: directReport.filter((d) => d.strictBlocks).length,
+        regBlocking: regHits.filter((h) => h.blocking).length,
+    };
+    if (opts.blast && !markdown) {
         console.log(`Blast radius of ${files.length} changed file(s):`);
         for (const f of files) {
             const b = store.blastRadiusFiles(f);
@@ -590,58 +614,27 @@ program
         }
         console.log("");
     }
-    if (!direct.size && !near.size && !regHits.length) {
-        console.log(`✓ ${files.length} changed file(s) touch no recorded invariants (directly or via blast radius) and re-introduce nothing deliberately retired.`);
-        store.close();
-        return;
-    }
-    // --strict may FAIL a commit ONLY on a DIRECT, high-confidence, non-stale
-    // blocking invariant (see strictgate.ts) — never on a blast-radius ("near")
-    // guess or a stale/low-confidence record. Those weaker hits still print, as
-    // advisory, so strict mode is safe to enable on a shared repo.
-    const staleConstraintIds = opts.strict
-        ? new Set(store.staleness((f) => lastChangeDate(f, root)).filter((s) => s.kind === "constraint").map((s) => s.id))
-        : new Set();
-    let strictBlockers = 0;
-    if (direct.size) {
-        console.log(`Directly touches ${direct.size} invariant(s):\n`);
-        for (const { c, files: fs } of direct.values()) {
-            const blocks = isStrictBlocker(c, staleConstraintIds.has(c.id));
-            if (blocks)
-                strictBlockers++;
-            const note = opts.strict && c.severity === "blocking" && !blocks
-                ? staleConstraintIds.has(c.id) ? "  (advisory: stale)" : "  (advisory: low confidence)"
-                : "";
-            console.log(`  ${mark(c.severity)} [${c.severity}] ${c.statement}${note}\n      ${c.id} · in: ${fs.join(", ")}\n      rationale: ${c.rationale || "—"}`);
-        }
-    }
-    if (near.size) {
-        console.log(`${direct.size ? "\n" : ""}Near ${near.size} invariant(s) via blast radius (a guarded dependency changed — review; never blocks):\n`);
-        for (const { c, via } of near.values()) {
-            console.log(`  ${mark(c.severity)} [${c.severity}] ${c.statement}\n      ${c.id}\n      ${via.slice(0, 4).join("\n      ")}${via.length > 4 ? `\n      …+${via.length - 4} more path(s)` : ""}`);
-        }
-    }
-    if (regHits.length) {
-        console.log(`${direct.size || near.size ? "\n" : ""}Re-introduces ${regHits.length} deliberately-retired item(s):\n`);
-        for (const h of regHits) {
-            console.log(`  ${h.blocking ? "⛔" : "⚠"} re-adds ${h.kind} \`${h.name}\` — ${h.decision} removed it${h.blocking ? " (blocking-linked)" : ""}\n      “${h.title}”\n      ${h.reason}`);
-        }
-    }
-    if (opts.strict && (strictBlockers || regBlocking)) {
-        const reasons = [
-            strictBlockers ? `${strictBlockers} high-confidence blocking invariant(s) directly in scope` : "",
-            regBlocking ? `${regBlocking} blocking-linked regression(s)` : "",
-        ].filter(Boolean).join(" + ");
-        console.log(`\n✗ ${reasons} — review before committing.`);
+    console.log(markdown ? renderMarkdown(report) : renderText(report));
+    if (reportFailsStrict(report))
         process.exitCode = 1;
-    }
-    else if (opts.strict) {
-        console.log(`\nReview these — none are a direct, high-confidence, non-stale blocking invariant, so the commit is NOT blocked.`);
+    store.close();
+});
+// ---- ci (scaffold the CI Constraint Guard) --------------------------------
+program
+    .command("ci")
+    .description("Scaffold the CI Constraint Guard: a GitHub Action that runs `hunch check` on PRs, comments the result, and fails on a blocking invariant.")
+    .action(() => {
+    const root = findRoot();
+    const r = writeCiWorkflow(root);
+    if (r.action === "created") {
+        console.log(`✓ wrote ${rel(root, r.path)}`);
+        console.log("  Runs on every PR: comments the affected invariants/decisions and fails on a direct,");
+        console.log("  high-confidence, non-stale blocking invariant. Commit it, then (optionally) make");
+        console.log('  "Hunch Guard" a required status check in branch protection to enforce on merge.');
     }
     else {
-        console.log(`\nReview that these invariants still hold. (Advisory — run with --strict to fail on direct, high-confidence, non-stale blocking invariants.)`);
+        console.log(`· ${rel(root, r.path)} already exists — left untouched. Delete it to regenerate.`);
     }
-    store.close();
 });
 // ---- context (surgical retrieval) -----------------------------------------
 program

package/dist/core/checkreport.js

@@ -0,0 +1,113 @@
+/** Rendering for `hunch check` — pure, so the terminal output and the CI/PR
+ *  comment share one source of truth and stay unit-testable. The CLI builds a
+ *  CheckReport from the store (direct/near/regression + the hardened strict gate),
+ *  then renders it as text (terminal, unchanged) or markdown (a PR comment posted
+ *  by the GitHub Action). The exit-code decision lives with the caller. */
+export function reportIsClean(r) {
+    return r.direct.length === 0 && r.near.length === 0 && r.regressions.length === 0;
+}
+/** True when --strict should FAIL the commit/PR. */
+export function reportFailsStrict(r) {
+    return r.strict && (r.strictBlockers > 0 || r.regBlocking > 0);
+}
+const mark = (s) => (s === "blocking" ? "⛔" : s === "warning" ? "⚠" : "·");
+// ---------------------------------------------------------------------------
+// Terminal text (unchanged from the inline CLI output it replaces)
+// ---------------------------------------------------------------------------
+export function renderText(r) {
+    if (reportIsClean(r)) {
+        return `✓ ${r.fileCount} changed file(s) touch no recorded invariants (directly or via blast radius) and re-introduce nothing deliberately retired.`;
+    }
+    const out = [];
+    if (r.direct.length) {
+        out.push(`Directly touches ${r.direct.length} invariant(s):\n`);
+        for (const c of r.direct) {
+            const note = r.strict && c.severity === "blocking" && !c.strictBlocks
+                ? c.downgrade === "stale" ? "  (advisory: stale)" : "  (advisory: low confidence)"
+                : "";
+            out.push(`  ${mark(c.severity)} [${c.severity}] ${c.statement}${note}\n      ${c.id} · in: ${c.files.join(", ")}\n      rationale: ${c.rationale || "—"}`);
+        }
+    }
+    if (r.near.length) {
+        out.push(`${r.direct.length ? "\n" : ""}Near ${r.near.length} invariant(s) via blast radius (a guarded dependency changed — review; never blocks):\n`);
+        for (const c of r.near) {
+            out.push(`  ${mark(c.severity)} [${c.severity}] ${c.statement}\n      ${c.id}\n      ${c.via.slice(0, 4).join("\n      ")}${c.via.length > 4 ? `\n      …+${c.via.length - 4} more path(s)` : ""}`);
+        }
+    }
+    if (r.regressions.length) {
+        out.push(`${r.direct.length || r.near.length ? "\n" : ""}Re-introduces ${r.regressions.length} deliberately-retired item(s):\n`);
+        for (const h of r.regressions) {
+            out.push(`  ${h.blocking ? "⛔" : "⚠"} re-adds ${h.kind} \`${h.name}\` — ${h.decision} removed it${h.blocking ? " (blocking-linked)" : ""}\n      “${h.title}”\n      ${h.reason}`);
+        }
+    }
+    if (reportFailsStrict(r)) {
+        const reasons = [
+            r.strictBlockers ? `${r.strictBlockers} high-confidence blocking invariant(s) directly in scope` : "",
+            r.regBlocking ? `${r.regBlocking} blocking-linked regression(s)` : "",
+        ].filter(Boolean).join(" + ");
+        out.push(`\n✗ ${reasons} — review before committing.`);
+    }
+    else if (r.strict) {
+        out.push(`\nReview these — none are a direct, high-confidence, non-stale blocking invariant, so the commit is NOT blocked.`);
+    }
+    else {
+        out.push(`\nReview that these invariants still hold. (Advisory — run with --strict to fail on direct, high-confidence, non-stale blocking invariants.)`);
+    }
+    return out.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Markdown (a PR comment posted by the CI Constraint Guard)
+// ---------------------------------------------------------------------------
+export function renderMarkdown(r) {
+    const H = "## 🧠 Hunch — Engineering Memory Guard";
+    if (reportIsClean(r)) {
+        return `${H}\n\n✅ This PR touches **no recorded invariants** (directly or via blast radius) and re-introduces nothing deliberately retired across ${r.fileCount} changed file(s).`;
+    }
+    const out = [H, ""];
+    if (r.direct.length) {
+        out.push(`### ⛔ Invariants directly in scope`);
+        for (const c of r.direct) {
+            const note = r.strict && c.severity === "blocking" && !c.strictBlocks
+                ? c.downgrade === "stale" ? " _(advisory: record is stale)_" : " _(advisory: low confidence)_"
+                : "";
+            out.push(`- **[${c.severity}] ${c.statement}** — \`${c.id}\`${note}`);
+            out.push(`  - in: ${c.files.map((f) => `\`${f}\``).join(", ")}`);
+            if (c.rationale)
+                out.push(`  - _${c.rationale}_`);
+        }
+        out.push("");
+    }
+    if (r.near.length) {
+        out.push(`### ⚠ Near-invariants (reached via blast radius — review, never blocks)`);
+        for (const c of r.near) {
+            out.push(`- **[${c.severity}] ${c.statement}** — \`${c.id}\``);
+            out.push(`  - ${c.via.slice(0, 3).join("\n  - ")}${c.via.length > 3 ? `\n  - …+${c.via.length - 3} more path(s)` : ""}`);
+        }
+        out.push("");
+    }
+    if (r.regressions.length) {
+        out.push(`### ♻️ Re-introduces deliberately-retired code`);
+        for (const h of r.regressions) {
+            out.push(`- ${h.blocking ? "⛔" : "⚠"} re-adds ${h.kind} \`${h.name}\` — \`${h.decision}\` removed it${h.blocking ? " **(blocking-linked)**" : ""}`);
+            out.push(`  - _${h.title}_`);
+        }
+        out.push("");
+    }
+    out.push("---");
+    if (reportFailsStrict(r)) {
+        const reasons = [
+            r.strictBlockers ? `${r.strictBlockers} high-confidence blocking invariant(s) directly in scope` : "",
+            r.regBlocking ? `${r.regBlocking} blocking-linked regression(s)` : "",
+        ].filter(Boolean).join(" + ");
+        out.push(`❌ **This PR breaks ${reasons}.** Resolve or supersede the decision before merge.`);
+    }
+    else if (r.strict) {
+        out.push(`ℹ️ Nothing here is a direct, high-confidence, non-stale blocking invariant — **not blocking** this PR.`);
+    }
+    else {
+        out.push(`ℹ️ Advisory — review that these invariants still hold.`);
+    }
+    out.push(`\n<sub>🧠 Hunch · engineering memory · run \`hunch why <file>\` for the full reasoning.</sub>`);
+    return out.join("\n");
+}
+//# sourceMappingURL=checkreport.js.map

package/dist/extractors/git.js

@@ -153,6 +153,18 @@ export function stagedFiles(cwd) {
     const out = gitSafe(["diff", "--cached", "--name-only", "--diff-filter=ACMR"], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
+/** Files a PR/branch changes vs `base` (3-dot: changes on HEAD since the merge-base,
+ *  i.e. exactly the PR's own commits — the CI Constraint Guard's surface). */
+export function rangeFiles(base, cwd, head = "HEAD") {
+    const out = gitSafe(["diff", "--name-only", "--diff-filter=ACMR", `${base}...${head}`], cwd);
+    return out ? out.split("\n").filter(Boolean) : [];
+}
+/** The PR's unified diff vs `base` (3-dot), for the Regression Guard's structural
+ *  analysis. Same noise-exclusion + truncation budget as commit/staged diffs. */
+export function rangeDiff(base, cwd, head = "HEAD", maxBytes = 60_000) {
+    const out = gitSafe(["diff", "--no-color", "--unified=2", `${base}...${head}`, "--", ...DIFF_NOISE], cwd);
+    return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
+}
 /** Unified diff of the staged changes (for the Regression Guard's structural
  *  analysis). Excludes machine-generated noise and truncates at the SAME budget as
  *  commitDiff, so the staged and `--commit` guard paths can't diverge on big diffs. */

package/dist/integrations/ciAction.js

@@ -0,0 +1,81 @@
+/** The CI Constraint Guard — Hunch's enforcement edge. A GitHub Actions workflow
+ *  that runs `hunch check` over a pull request's diff, posts the result as a
+ *  sticky PR comment (citing the con_/dec_ ids), and FAILS the check on a direct,
+ *  high-confidence, non-stale blocking invariant (the hardened strict gate). This
+ *  turns the engineering memory from advisory into a merge gate — and it's
+ *  structurally uncopyable: it reasons over the diff PLUS the constraints
+ *  committed in the same git history. Idempotent: never clobbers a user's edits.
+ */
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+// `\${{ … }}` keeps GitHub Actions expressions literal inside this template
+// literal (a bare `${` would be JS interpolation).
+export function ciWorkflowYaml() {
+    return `# Hunch — CI Constraint Guard. Blocks a PR that breaks a recorded invariant,
+# re-adds deliberately-retired code, or contradicts an in-force decision, and
+# comments with the why (con_/dec_ ids). Make this a required check to enforce.
+name: Hunch Guard
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  hunch-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history: the guard diffs base...head and reads git log
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install Hunch
+        run: npm install -g @davesheffer/hunch
+
+      - name: Run Constraint Guard
+        id: guard
+        run: |
+          set +e
+          hunch check --base "origin/\${{ github.base_ref }}" --strict --format markdown > hunch-report.md
+          echo "exit=$?" >> "$GITHUB_OUTPUT"
+          set -e
+
+      - name: Comment on PR
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const body = fs.readFileSync('hunch-report.md', 'utf8').trim();
+            const marker = '<!-- hunch-guard -->';
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.pull_request.number;
+            const all = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number });
+            const existing = all.find(c => c.body && c.body.includes(marker));
+            const out = marker + '\\n' + body;
+            if (existing) await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body: out });
+            else await github.rest.issues.createComment({ owner, repo, issue_number, body: out });
+
+      - name: Enforce (fail on a blocking invariant)
+        if: always()
+        run: exit \${{ steps.guard.outputs.exit }}
+`;
+}
+/** Write .github/workflows/hunch-guard.yml. Never overwrites an existing file
+ *  (respects user edits) — reports "exists" instead. */
+export function writeCiWorkflow(root) {
+    const dir = join(root, ".github", "workflows");
+    const path = join(dir, "hunch-guard.yml");
+    if (existsSync(path))
+        return { path, action: "exists" };
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, ciWorkflowYaml());
+    return { path, action: "created" };
+}
+//# sourceMappingURL=ciAction.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.11.3",
+  "version": "0.12.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.",