sawbuck 0.1.9 → 0.1.11

package/README.md

@@ -42,6 +42,7 @@ 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 |
 

package/debt.mjs

@@ -0,0 +1,149 @@
+#!/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 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)));
+  if (asJson) { console.log(JSON.stringify({ since, added: added.length, testSkips: added.filter((it) => isTestSkip(it.kind)).length, undocumented: added.filter((it) => !it.documented).length, items: added.map((it) => ({ file: it.file, line: it.line, kind: String(it.kind).trim(), documented: it.documented })) }, null, 2)); process.exit(0); }
+  if (!added.length) { console.log(`🐴 sawbuck: no new suppression debt since ${since} (clean).`); process.exit(0); }
+  const skips = added.filter((it) => isTestSkip(it.kind)).length, undoc = added.filter((it) => !it.documented).length;
+  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.`);
+  console.log(o.join('\n'));
+  process.exit(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.9",
+  "version": "0.1.11",
   "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

@@ -14,7 +14,7 @@
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -61,6 +61,55 @@ const codeish = (p) => /\.(m?[jt]sx?|cjs|py|go|rs|rb|java|kt|c|cc|cpp|h|hpp|php|
 // eslint-disable). The relevance lead: sharpen the signal, don't flatten it.
 const isTest = (p) => /(^|\/)(tests?|__tests__|specs?)\//i.test(p) || /[._-](test|spec)\.[a-z0-9]+$/i.test(p) || /(^|\/)test_[^/]+\.py$/i.test(p);
 
+// Per-language suppression normalization. The 100-repo study (STUDY-100.md) found a suppression's
+// raw count is an idiom artifact, not a risk level: a `# noqa` is background noise in Python (141
+// markers/repo) but a `t.Skip` is notable in Go. So a hit is discounted by how ubiquitous its
+// idiom is in the FILE's language. Discount-only [0.4, 1]: common idioms shrink, rare ones stay at
+// full base weight, and the ordering floor holds (revert 3 > test-skip 2.5 > suppression 2).
+// Reverts are idiom-independent and never normalized. --raw turns this off.
+const raw = process.argv.includes('--raw');
+const langOf = (p) => {
+  const e = (p.match(/\.([a-z0-9]+)$/i) || [, ''])[1].toLowerCase();
+  if (/^tsx?$/.test(e)) return 'ts';
+  if (/^(m?jsx?|cjs)$/.test(e)) return 'js';
+  if (['py', 'go', 'rs', 'php', 'phtml'].includes(e)) return e === 'phtml' ? 'php' : e;
+  if (['java', 'kt', 'kts', 'scala', 'groovy'].includes(e)) return 'java';
+  if (['cs', 'fs', 'vb'].includes(e)) return 'cs';
+  return 'other';
+};
+// baseline = markers/repo for that language+kind, from the study's per-language table.
+const BASELINE = {
+  py: { code: 141, skip: 4.6 }, ts: { code: 89, skip: 19.1 }, js: { code: 37, skip: 10.5 },
+  go: { code: 1.6, skip: 21.6 }, java: { code: 0.5, skip: 13.9 }, rs: { code: 0.3, skip: 4.1 },
+  cs: { code: 0.5, skip: 158 }, php: { code: 0.5, skip: 15 }, other: { code: 20, skip: 10 },
+};
+const REF = 15; // a hit at or below ~15 markers/repo for its language+kind keeps full weight
+const normMult = (p, kind) => {
+  if (raw) return 1;
+  const b = Math.max((BASELINE[langOf(p)] || BASELINE.other)[kind], 0.5);
+  return Math.max(0.4, Math.min(1, REF / b));
+};
+
+// 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;
+if (!raw && paths.length) {
+  try {
+    const { SUPPRESS_PAT } = await import(pathToFileURL(LB).href);
+    if (SUPPRESS_PAT && SUPPRESS_PAT.source) {
+      let grep = '';
+      try { grep = execFileSync('git', ['-C', repo, 'grep', '-lP', SUPPRESS_PAT.source, 'HEAD', '--', ...paths], { encoding: 'utf8' }); }
+      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:/, '')));
+    }
+  } catch { liveSet = null; } // logbook unavailable -> skip the filter, 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);
+
 const DAY = 86400000;
 const ranked = paths.map((p) => {
   let score = 0; const hits = []; const fixDates = [];
@@ -72,8 +121,11 @@ const ranked = paths.map((p) => {
     // "weakened" only on a NET assertion drop (logbook's own rule: del > add + 2), 
     // a rewrite that removes some asserts but adds more is not a weakening.
     else if (codeish(p) && ((e.suppressions && e.suppressions.length) || ((e.del_asserts || 0) > (e.add_asserts || 0) + 2) || e.downgrades > 0)) {
-      if (isTest(p)) { w = 2.5; kind = 'test disabled / weakened'; }
-      else { w = 2; kind = 'suppression in source'; }
+      const hasSupp = e.suppressions && e.suppressions.length;
+      const tst = isTest(p);
+      const m = hasSupp ? normMult(p, tst ? 'skip' : 'code') * stillLive(p) : 1; // normalize by language x still-live; leave a pure assertion-drop at full weight
+      if (tst) { w = 2.5 * m; kind = 'test disabled / weakened'; }
+      else { w = 2 * m; kind = 'suppression in source'; }
     }
     else if (e.fix) { w = 1.2; kind = 'bugfix here'; }
     else continue;

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]
+                            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/PR adds vs REF
   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();