sawbuck 0.1.10 → 0.1.12

package/README.md

@@ -42,11 +42,33 @@ sawbuck: gamed recorded on test.js       (the win came from editing the test, no
 | `sawbuck detach [--claude \| --user]` | remove it |
 | `sawbuck check [--base R --head R]` | verify a commit; record a regression or a gamed win |
 | `sawbuck context` · `sawbuck rank` | the ranked relevant history for the current change |
+| `sawbuck debt` | the whole-repo live suppression debt: what is still silenced in HEAD now, disabled tests first, heaviest files ranked |
 | `sawbuck run --attempt '<agent cmd>'` | thin harness: load context, run one attempt through the keep-if-verified gate |
 | `sawbuck trace` · `sawbuck doctor` · `detach --verify` | show the footprint; check the attachment resolves; prove a clean removal |
 
 Each repo needs a `promptwheel.config.json` saying what to measure (your tests, lint, coverage, or an eval).
 
+## Gate debt on pull requests
+
+`sawbuck debt --since <base>` shows only the suppression debt a branch adds. Fail the build when a PR adds the kind you care about:
+
+```yaml
+# .github/workflows/debt.yml
+name: debt
+on: pull_request
+jobs:
+  debt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }   # the base ref must be present to diff against
+      - run: npx -y sawbuck debt --since "origin/${{ github.base_ref }}" --fail-on undocumented
+```
+
+`--fail-on` takes `undocumented` (a bare `# type: ignore` / `# noqa` with no code), `test` (a newly disabled test), `any`, or a number of new suppressions. Exit 1 fails the check; add `--json` for the machine-readable delta. This repo is also a composite action: `uses: sawbuck-ai/sawbuck@v0` with `base` and `fail-on` inputs.
+
+Debt also rises on its own: once attached, the per-turn `context` hook surfaces the live suppression debt on the files your agent is touching when it is the suspect kind (undocumented, a disabled test, or on code that keeps breaking), so you do not have to run anything.
+
 ## The engines
 
 Sawbuck is thin glue over two tools it depends on:

package/debt.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// debt.mjs, Sawbuck's live-suppression-debt ledger: what is STILL silenced in HEAD right now,
+// split by severity (disabled/weakened tests vs lint/type/error suppressions), risk-ranked by how
+// fragile each file is (reverts/fix-bursts), and split by whether each suppression is DOCUMENTED (a
+// rule code or reason) or BARE (just the directive, nobody wrote why). The whole-repo view;
+// `sawbuck context` is the task-scoped one. The live state (git grep of HEAD, gated) is the
+// complete lens for CURRENT debt; the historical diff scan under-counts it.
+// Zero-dep. Usage: node debt.mjs [--repo P] [--top N] [--since REF] [--json]
+
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { basename, join, dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const engineBin = (envVar, pkgSubpath, devPath) => {
+  if (process.env[envVar]) return process.env[envVar];
+  const bare = pkgSubpath.replace(/\/bin\/[^/]*$/, '');
+  for (const spec of [pkgSubpath, bare]) { try { return require.resolve(spec); } catch {} }
+  return devPath;
+};
+const LB = engineBin('LB_BIN', '@promptwheel/logbook/bin/logbook.mjs', join(HERE, '..', 'logbook', 'bin', 'logbook.mjs'));
+
+const flag = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? (process.argv[i + 1] ?? true) : d; };
+const repo = resolve(flag('--repo', process.cwd()));
+const top = Math.max(1, parseInt(flag('--top', '12'), 10) || 12);
+const since = flag('--since', null);
+const failRaw = flag('--fail-on', null); // undocumented | test | any | <N>; bare --fail-on = undocumented
+const failMode = failRaw === true ? 'undocumented' : (failRaw ? String(failRaw).toLowerCase() : null);
+const asJson = process.argv.includes('--json');
+
+// A disabled/skipped/weakened TEST is a hidden-failure risk; a lint/type/error suppression is
+// usually mundane. Same split sawbuck's rank uses, so the two faces agree.
+const isTestSkip = (m) => /\bit\.skip\b|\btest\.skip\b|xit\(|xdescribe\(|\bdescribe\.skip\b|pytest\.mark\.skip|unittest\.skip|\bt\.Skip\b|@Disabled\b|@Ignore\b|^\[Ignore\b|^Skip\s*=|^#\[ignore|markTestSkipped|markTestIncomplete/.test(String(m).trim());
+// DOCUMENTED = a rule code or reason follows the directive (declared intent); BARE = just the
+// directive. Heuristic, a lead not a verdict, but bare is the suspect kind worth scrutinizing.
+const isDocumented = (c) => {
+  c = String(c || '');
+  if (/eslint-disable/.test(c)) return /eslint-disable(?:-next-line|-line)?\s+\S/.test(c); // a rule name follows
+  if (/@ts-ignore/.test(c)) return false;                                                  // inherently undocumented
+  if (/@ts-expect-error/.test(c)) return /@ts-expect-error\s+\S/.test(c);
+  if (/noqa/i.test(c)) return /noqa:\s*\w/i.test(c);                                        // # noqa: E501
+  if (/type:\s*ignore/i.test(c)) return /ignore\s*\[/.test(c);                              // # type: ignore[code]
+  return /\(\s*["']/.test(c) || /=\s*["']/.test(c);   // annotation reason/code: @Disabled("..."), Skip="...", #[ignore = "..."]
+};
+
+// events give fragility + fall-back dates. Best-effort.
+let events = [];
+try { events = execFileSync(process.execPath, [LB, 'query', '--json'], { cwd: repo, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 }).split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean); } catch {}
+
+let auditHead, SUPPRESS_PAT;
+try { ({ auditHead, SUPPRESS_PAT } = await import(pathToFileURL(LB).href)); } catch (e) { console.error(`sawbuck debt: cannot load logbook (${String(e.message).split('\n')[0]})`); process.exit(1); }
+
+let live;
+try { live = auditHead(repo, events); } catch (e) { console.error(`sawbuck debt: could not read the suppression ledger (${String(e.message).split('\n')[0]})`); process.exit(1); }
+
+// enrich each gated live suppression with its line content, so we can tell BARE from DOCUMENTED.
+// One extra HEAD grep; we only read content for lines auditHead already gated, so no gating drift.
+const grepAt = (ref) => { try { return execFileSync('git', ['-C', repo, 'grep', '-nP', SUPPRESS_PAT.source, ref], { encoding: 'utf8', maxBuffer: 512 * 1024 * 1024 }); } catch (e) { return (e.stdout || '').toString(); } };
+const parseGrep = (g, ref) => { const re = new RegExp('^' + ref.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ':(.+?):(\\d+):(.*)$'); const m = []; for (const row of g.split('\n')) { const x = re.exec(row); if (x) m.push({ file: x[1], line: +x[2], content: x[3] }); } return m; };
+const headRows = SUPPRESS_PAT ? parseGrep(grepAt('HEAD'), 'HEAD') : [];
+const contentAt = new Map(headRows.map((r) => [r.file + ':' + r.line, r.content]));
+for (const it of live) { it.content = contentAt.get(it.file + ':' + it.line) || ''; it.documented = it.content ? isDocumented(it.content) : false; }
+const bare = live.filter((it) => !it.documented && it.content).length;
+
+// --since REF: the DELTA. Suppressions in HEAD but not at REF = debt this branch/PR adds.
+if (since && typeof since === 'string') {
+  const norm = (s) => String(s).trim().replace(/\s+/g, ' ');
+  const base = new Set(parseGrep(grepAt(since), since).map((r) => r.file + '\u0000' + norm(r.content)));
+  const added = live.filter((it) => it.content && !base.has(it.file + '\u0000' + norm(it.content)));
+  const skips = added.filter((it) => isTestSkip(it.kind)).length, undoc = added.filter((it) => !it.documented).length;
+  // the gate: fail (exit 1) when the branch adds the kind of debt --fail-on names.
+  const fail = !failMode ? false
+    : /^\d+$/.test(failMode) ? added.length >= +failMode
+    : failMode === 'any' ? added.length > 0
+    : (failMode === 'test' || failMode === 'tests' || failMode === 'disabled') ? skips > 0
+    : undoc > 0; // default: undocumented
+  if (asJson) { console.log(JSON.stringify({ since, added: added.length, testSkips: skips, undocumented: undoc, failOn: failMode, fail, items: added.map((it) => ({ file: it.file, line: it.line, kind: String(it.kind).trim(), documented: it.documented })) }, null, 2)); process.exit(fail ? 1 : 0); }
+  if (!added.length) { console.log(`🐴 sawbuck: no new suppression debt since ${since} (clean).`); process.exit(0); }
+  const o = [`🐴 sawbuck: ${added.length} new suppression${added.length === 1 ? '' : 's'} since ${since}  ·  ${skips} disabled test${skips === 1 ? '' : 's'}  ·  ${undoc} undocumented (no code/reason)`];
+  for (const it of added.slice(0, Math.max(top, 20))) o.push(`     ${isTestSkip(it.kind) ? '🔴' : (it.documented ? '  ' : '✎ ')} ${it.file}:${it.line}  ${String(it.kind).trim()}${it.documented ? '' : '   (bare - no code/reason)'}`);
+  o.push(`\n   ✎ = bare/undocumented (the suspect kind); declare intent (a rule code or reason) or remove it.`);
+  if (failMode) o.push(fail ? `\n   ❌ debt gate FAILED (--fail-on ${failMode}): this branch adds debt that must be declared or removed.` : `\n   ✓ debt gate passed (--fail-on ${failMode}).`);
+  console.log(o.join('\n'));
+  process.exit(fail ? 1 : 0);
+}
+
+if (!live.length) { console.log(asJson ? '{"total":0,"testSkips":0,"codeSuppressions":0,"undocumented":0,"files":[]}' : '🐴 sawbuck: no live suppression debt in HEAD (nothing silenced in src/test/config). A clean tree.'); process.exit(0); }
+
+// Fragility: debt on code that keeps breaking (reverts, fix-bursts) is the debt that matters; debt
+// on stable code is mostly noise. One pass over the events builds per-file history; a file's debt
+// severity is multiplied by its fragility. Same signals rank.mjs uses.
+const DAY = 86400000;
+const resolveRename = (f) => f.replace(/\{[^}]*=>\s*([^}]*)\}/g, '$1').replace(/\/{2,}/g, '/');
+const histMap = new Map();
+for (const e of events) {
+  const rv = !!e.revert, fx = !!e.fix;
+  if (!rv && !fx) continue;
+  for (const raw of (e.files || [])) {
+    const f = resolveRename(raw);
+    const h = histMap.get(f) || { reverts: 0, fixes: 0, fixDates: [] };
+    if (rv) h.reverts++;
+    if (fx) { h.fixes++; if (e.date) h.fixDates.push(Date.parse(e.date)); }
+    histMap.set(f, h);
+  }
+}
+const fragilityOf = (file) => {
+  const h = histMap.get(file) || { reverts: 0, fixes: 0, fixDates: [] };
+  const fd = [...h.fixDates].sort((a, b) => a - b);
+  let burst = 0;
+  for (let i = 0; i + 2 < fd.length; i++) if (fd[i + 2] - fd[i] <= 30 * DAY) { burst = fd.filter((x) => x >= fd[i] && x <= fd[i] + 30 * DAY).length; break; }
+  const hot = burst >= 3;
+  const mult = 1 + Math.min(3, h.reverts * 0.75 + (hot ? 1 : 0) + h.fixes * 0.1);
+  return { reverts: h.reverts, fixes: h.fixes, hot, mult };
+};
+
+const byFile = new Map();
+let testSkips = 0, codeSup = 0;
+for (const it of live) {
+  const t = isTestSkip(it.kind); t ? testSkips++ : codeSup++;
+  const f = byFile.get(it.file) || { file: it.file, skips: 0, bareSup: 0, docSup: 0, kinds: new Set(), oldest: null };
+  if (t) f.skips++; else (it.documented ? f.docSup++ : f.bareSup++);
+  f.kinds.add(String(it.kind).trim());
+  if (it.date && (!f.oldest || it.date < f.oldest)) f.oldest = it.date;
+  byFile.set(it.file, f);
+}
+// RISK = severity (disabled test 3, bare suppression 1.5, documented 1) x file fragility.
+const files = [...byFile.values()].map((f) => {
+  const sup = f.bareSup + f.docSup;
+  const sev = f.skips * 3 + f.bareSup * 1.5 + f.docSup * 1;
+  const fr = fragilityOf(f.file);
+  return { file: f.file, n: f.skips + sup, skips: f.skips, sup, bareSup: f.bareSup, oldest: f.oldest, reverts: fr.reverts, fixes: fr.fixes, hot: fr.hot, risk: +(sev * fr.mult).toFixed(1) };
+}).sort((a, b) => b.risk - a.risk || b.n - a.n);
+const onFragile = files.filter((f) => f.reverts > 0 || f.hot).length;
+
+if (asJson) {
+  console.log(JSON.stringify({ total: live.length, testSkips, codeSuppressions: codeSup, undocumented: bare, filesOnFragileCode: onFragile, files: files.map((f) => ({ file: f.file, live: f.n, testSkips: f.skips, suppressions: f.sup, undocumented: f.bareSup, reverts: f.reverts, hot: f.hot, risk: f.risk, oldest: f.oldest })) }, null, 2));
+  process.exit(0);
+}
+
+const out = [];
+out.push(`🐴 sawbuck: live suppression debt in ${basename(repo)}`);
+out.push(`   ${live.length} still silenced in HEAD  ·  ${testSkips} disabled/weakened test${testSkips === 1 ? '' : 's'} (hidden-failure risk)  ·  ${codeSup} lint/type suppression${codeSup === 1 ? '' : 's'}  ·  ${bare} undocumented (no code/reason)`);
+if (onFragile) out.push(`   ${onFragile} of ${files.length} debt-carrying files sit on fragile code (reverts/hotspots); look there first`);
+out.push(`\n   highest-risk debt (severity x how fragile the file is):`);
+for (const f of files.slice(0, top)) {
+  const bits = [f.skips ? `${f.skips} test` : '', f.sup ? `${f.sup} lint/type${f.bareSup ? `, ${f.bareSup} bare` : ''}` : ''].filter(Boolean).join(' + ');
+  const frag = [f.reverts ? `${f.reverts} revert${f.reverts === 1 ? '' : 's'}` : '', f.hot ? 'fix-hotspot' : '', (!f.hot && f.fixes >= 3) ? `${f.fixes} fixes` : ''].filter(Boolean).join(', ');
+  out.push(`     ${f.reverts || f.hot ? '🔥 ' : '   '}${f.file}  ·  ${f.n} (${bits})${frag ? `  · ${frag}` : ''}  ·  risk ${f.risk}`);
+}
+const dated = live.filter((it) => it.date).sort((a, b) => String(a.date).localeCompare(String(b.date)));
+if (dated.length) {
+  out.push(`\n   oldest still-silenced (most stale):`);
+  for (const it of dated.slice(0, 5)) out.push(`     ${it.file}:${it.line}  ${String(it.kind).trim()}  (since ${it.date})`);
+}
+out.push(`\n   bare = no code/reason, the suspect kind. leads, not verdicts; full dated ledger: logbook audit`);
+console.log(out.join('\n'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Sign your agent to a contract so it does what you want: a deterministic, zero-LLM check that re-proves every win from the agent's source edits alone, so a green that came from editing the test is caught and reverted. A saddle for your coding harness.",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,7 @@
     "dispatch.mjs",
     "sawbuck-hook.mjs",
     "rank.mjs",
+    "debt.mjs",
     "run.mjs",
     "README.md",
     "GLOSSARY.md",

package/rank.mjs

@@ -90,22 +90,57 @@ const normMult = (p, kind) => {
   return Math.max(0.4, Math.min(1, REF / b));
 };
 
+// Classify a live suppression MARKER (disabled test = hidden-failure risk) and its line as
+// DOCUMENTED (a rule code/reason follows) vs BARE (just the directive, the suspect kind). Same
+// splits `sawbuck debt` uses, so the ambient surface and the ledger agree.
+const isTestSkip = (m) => /\bit\.skip\b|\btest\.skip\b|xit\(|xdescribe\(|\bdescribe\.skip\b|pytest\.mark\.skip|unittest\.skip|\bt\.Skip\b|@Disabled\b|@Ignore\b|^\[Ignore\b|^Skip\s*=|^#\[ignore|markTestSkipped|markTestIncomplete/.test(String(m).trim());
+const isDocumented = (c) => {
+  c = String(c || '');
+  if (/eslint-disable/.test(c)) return /eslint-disable(?:-next-line|-line)?\s+\S/.test(c);
+  if (/@ts-ignore/.test(c)) return false;
+  if (/@ts-expect-error/.test(c)) return /@ts-expect-error\s+\S/.test(c);
+  if (/noqa/i.test(c)) return /noqa:\s*\w/i.test(c);
+  if (/type:\s*ignore/i.test(c)) return /ignore\s*\[/.test(c);
+  return /\(\s*["']/.test(c) || /=\s*["']/.test(c);
+};
+// The "slider": debt rises on its own, but gently. A disabled test or an undocumented suppression
+// on a touched file always surfaces; a file that is churning (hot / reverted) surfaces any debt;
+// a stable file's routine documented suppressions stay quiet until they pile past DEBT_MIN. Tune
+// with SAWBUCK_DEBT_MIN. This is how debt rises by itself in the per-turn context, no command run.
+const DEBT_MIN = Math.max(1, +(process.env.SAWBUCK_DEBT_MIN) || 6);
+
 // Still-live filter (lead #4). A suppression on a path that is now CLEAN of suppressions is churn,
 // not current risk (the study: AutoMapper carries 4 live `[Ignore]` vs ~158/repo across C# history).
 // logbook's own SUPPRESS_PAT, git-grepped at HEAD but SCOPED to just the touched paths so the
 // per-turn hook stays cheap, tells us which still carry one. Imported so the pattern never drifts;
 // degrades to "treat all as live" if logbook cannot be imported. --raw turns it off.
 let liveSet = null;
+const liveDebt = new Map(); // path -> { n, skips, bare }: live suppressions in HEAD, for ambient surfacing
 if (!raw && paths.length) {
   try {
-    const { SUPPRESS_PAT } = await import(pathToFileURL(LB).href);
+    const { SUPPRESS_PAT, kindAllowedInFile, isMention } = await import(pathToFileURL(LB).href);
     if (SUPPRESS_PAT && SUPPRESS_PAT.source) {
+      // -nP (content), still scoped to the touched paths, so we can both weight AND surface the debt.
       let grep = '';
-      try { grep = execFileSync('git', ['-C', repo, 'grep', '-lP', SUPPRESS_PAT.source, 'HEAD', '--', ...paths], { encoding: 'utf8' }); }
+      try { grep = execFileSync('git', ['-C', repo, 'grep', '-nP', SUPPRESS_PAT.source, 'HEAD', '--', ...paths], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }); }
       catch (e) { grep = (e.stdout || '').toString(); } // git grep exits 1 when nothing matches
-      liveSet = new Set(grep.split('\n').filter(Boolean).map((l) => l.replace(/^HEAD:/, '')));
+      liveSet = new Set();
+      for (const row of grep.split('\n')) {
+        const m = /^HEAD:(.+?):\d+:(.*)$/.exec(row); if (!m) continue;
+        const file = m[1], content = m[2];
+        const re = new RegExp(SUPPRESS_PAT.source, 'g'); let mm;
+        while ((mm = re.exec(content))) {
+          if (kindAllowedInFile && !kindAllowedInFile(mm[0], file)) continue; // gate exactly like audit
+          if (isMention && isMention(content, mm.index, mm[0])) continue;      // a comment ABOUT it is not live
+          liveSet.add(file);
+          const d = liveDebt.get(file) || { n: 0, skips: 0, bare: 0 };
+          d.n++;
+          if (isTestSkip(mm[0])) d.skips++; else if (!isDocumented(content)) d.bare++;
+          liveDebt.set(file, d);
+        }
+      }
     }
-  } catch { liveSet = null; } // logbook unavailable -> skip the filter, do not crash the read face
+  } catch { liveSet = null; liveDebt.clear(); } // logbook unavailable -> skip, do not crash the read face
 }
 // a suppression on a still-silenced path keeps its weight; on a now-clean path it is near-zero.
 const stillLive = (p) => (liveSet === null || liveSet.has(p) ? 1 : 0.25);
@@ -140,6 +175,20 @@ const ranked = paths.map((p) => {
   let burst = 0;
   for (let i = 0; i + 2 < fixDates.length; i++) if (fixDates[i + 2] - fixDates[i] <= 30 * DAY) { burst = fixDates.filter((x) => x >= fixDates[i] && x <= fixDates[i] + 30 * DAY).length; break; }
   if (burst >= 3) { score += 4; hits.unshift({ date: new Date(fixDates[fixDates.length - 1]).toISOString().slice(0, 10), kind: `HOT: ${burst} fixes in 30 days`, subject: 'this file was actively on fire, verify carefully', w: 99 }); }
+  // ambient debt: the live suppression debt on this file rises on its own when it is the suspect kind
+  // (a disabled test or an undocumented suppression), when the file is fragile (hot/reverted), or when
+  // it piles past the slider. Routine documented suppressions on stable files stay quiet. The score
+  // bump lets a file with ONLY debt (no history) surface at all; `sawbuck debt` is the full ledger.
+  const dbt = liveDebt.get(p);
+  if (dbt) {
+    const fragile = burst >= 3 || hits.some((h) => /revert/.test(h.kind || ''));
+    if (dbt.skips || dbt.bare || (fragile && dbt.n) || dbt.n >= DEBT_MIN) {
+      const extra = [dbt.skips ? `${dbt.skips} disabled test${dbt.skips === 1 ? '' : 's'}` : '', dbt.bare ? `${dbt.bare} undocumented` : ''].filter(Boolean).join(', ');
+      const w = dbt.skips ? 2.6 : (dbt.bare ? 2.2 : 1.4);
+      score += w;
+      hits.push({ kind: 'live debt here', subject: `${dbt.n} suppression${dbt.n === 1 ? '' : 's'} still silenced${extra ? ` (${extra})` : ''}; sawbuck debt for the ledger`, w });
+    }
+  }
   hits.sort((a, b) => b.w - a.w);
   return { path: p, score: +score.toFixed(2), top: hits.slice(0, 3), hot: burst >= 3 };
 }).filter((r) => r.score > 0).sort((a, b) => b.score - a.score).slice(0, top);

package/sawbuck.mjs

@@ -85,6 +85,10 @@ Usage:
   sawbuck rank [--base R --head R] [--file P ...]
                             Show the relevant past findings for the paths a change touches
   sawbuck context [repo]    Ranked relevant history for your current working changes (the read face)
+  sawbuck debt [repo] [--since REF] [--fail-on undocumented|test|any|N]
+                            The whole-repo live suppression debt: what is still silenced in HEAD now,
+                            risk-ranked (severity x file fragility), undocumented flagged. --since REF
+                            shows only the debt a branch adds; --fail-on exits nonzero for a CI gate
   sawbuck run --attempt '<cmd>' [--loops N]
                             Thin harness: load context, run one attempt through the keep-if-verified gate
   sawbuck --help | --version
@@ -151,6 +155,12 @@ switch (cmd) {
     catch (e) { process.exit(e.status || 1); }
     break;
   }
+  case 'debt': {
+    // the whole-repo debt ledger: live suppressions still in HEAD, severity-split, worst-first.
+    try { execFileSync(process.execPath, [join(HERE, 'debt.mjs'), ...rest], { stdio: 'inherit' }); }
+    catch (e) { process.exit(e.status || 1); }
+    break;
+  }
   case 'context': {
     // the read face: ranked relevant history for what you're working on right now.
     const repo = repoArg();