whygit 0.0.0-stage → 0.1.0

package/src/cli.js

@@ -0,0 +1,132 @@
+/** whygit command line. */
+import process from 'node:process';
+import { c, width } from './util.js';
+import { cmdWhy } from './cmd-why.js';
+import { cmdStory } from './cmd-story.js';
+import { cmdCursed } from './cmd-cursed.js';
+import { cmdCheck } from './cmd-check.js';
+import { cmdInit, cmdDoctor, cmdStatus } from './cmd-init.js';
+import { cmdMcp } from './mcp.js';
+import { cmdInstall } from './install.js';
+import { loadContext, repoLabel } from './context.js';
+import { buildWhylog, writeWhylog } from './whylog.js';
+import { header } from './ui.js';
+
+const VERSION = '0.1.0';
+
+const HELP = [
+  '',
+  '  ' + c.bold(c.cyan('whygit')) + c.gray('  git blame tells you who. whygit tells you why.'),
+  '',
+  c.bold('  USAGE'),
+  '    whygit <command> [options]',
+  '',
+  c.bold('  QUESTIONS'),
+  '    whygit why <words...>        search history for the reason behind a decision',
+  '    whygit why <file>:<line>     explain one line: who wrote it and why',
+  '    whygit story <file>          narrate one file from birth to HEAD',
+  '    whygit cursed                rank files by churn x fixes x authors',
+  '',
+  c.bold('  ARTIFACTS'),
+  '    whygit whylog [--write]      print or write WHYLOG.md',
+  '    whygit check [--base ref]    explanation coverage for a change set (CI gate)',
+  '',
+  c.bold('  AGENTS'),
+  '    whygit mcp                   run the MCP server on stdio',
+  '    whygit install [agent]       wire into claude / cursor / vscode / agents',
+  '',
+  c.bold('  HOUSEKEEPING'),
+  '    whygit init [--full]         build or refresh the index',
+  '    whygit doctor                diagnose the setup',
+  '    whygit status                what is indexed',
+  '',
+  c.bold('  OPTIONS'),
+  '    --json                       machine-readable output',
+  '    -n, --limit <n>              number of results',
+  '    --cwd <dir>                  run against another repository',
+  '    --base <ref>                 base for check (default origin/HEAD)',
+  '    --min <0..1>                 check threshold (default 0.5)',
+  '    --full                       reindex everything',
+  '    --local                      install: use the whygit binary, not npx',
+  '    -v, --version                print version',
+  '',
+  c.gray('  Every command accepts --json. Nothing leaves your machine.'),
+  '',
+].join('\n');
+
+export function parseArgs(argv) {
+  const flags = {};
+  const args = [];
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === '--') { args.push.apply(args, argv.slice(i + 1)); break; }
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      const key = eq > 0 ? a.slice(2, eq) : a.slice(2);
+      let val = eq > 0 ? a.slice(eq + 1) : null;
+      if (val == null && i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+        const maybe = argv[i + 1];
+        if (['json','full','local','quiet','write','help','version','no-color','all'].includes(key)) val = true;
+        else { val = maybe; i += 1; }
+      }
+      flags[key] = val == null ? true : val;
+      i += 1;
+      continue;
+    }
+    if (a === '-n' || a === '-q' || a === '-v' || a === '-h') {
+      if (a === '-n') { flags.limit = argv[i + 1]; i += 2; continue; }
+      if (a === '-q') { flags.quiet = true; i += 1; continue; }
+      if (a === '-v') { flags.version = true; i += 1; continue; }
+      if (a === '-h') { flags.help = true; i += 1; continue; }
+    }
+    args.push(a);
+    i += 1;
+  }
+  return { args: args, flags: flags };
+}
+
+function cmdWhylog(args, flags) {
+  const ctx = loadContext({ cwd: flags.cwd });
+  const label = repoLabel(ctx);
+  if (flags.write) {
+    const res = writeWhylog(ctx, { label: label, limit: Number(flags.limit) || 40 });
+    console.log('');
+    console.log('  ' + c.green('\u2713') + ' wrote ' + c.bold(res.file) + c.gray('  (' + res.decisions + ' decisions, ' + Math.round(res.bytes / 1024) + ' KB)'));
+    console.log('');
+    return 0;
+  }
+  process.stdout.write(buildWhylog(ctx, { label: label, limit: Number(flags.limit) || 40 }));
+  return 0;
+}
+
+export async function main(argv) {
+  const parsed = parseArgs(argv);
+  const flags = parsed.flags;
+  const args = parsed.args;
+  if (flags.version) { console.log(VERSION); return 0; }
+  if (flags.help) { console.log(HELP); return 0; }
+  const cmd = args[0];
+  const rest = args.slice(1);
+  if (flags['no-color']) process.env.NO_COLOR = '1';
+  switch (cmd) {
+    case undefined:
+      try { return cmdStatus([], flags); } catch (err) { console.log(HELP); return 0; }
+    case 'why': return cmdWhy(rest, flags);
+    case 'story': return cmdStory(rest, flags);
+    case 'cursed': return cmdCursed(rest, flags);
+    case 'whylog': return cmdWhylog(rest, flags);
+    case 'check': return cmdCheck(rest, flags);
+    case 'init': return cmdInit(rest, flags);
+    case 'doctor': return cmdDoctor(rest, flags);
+    case 'status': return cmdStatus(rest, flags);
+    case 'mcp': return cmdMcp(rest, flags);
+    case 'install': return cmdInstall(rest, flags);
+    case 'help': console.log(HELP); return 0;
+    case 'version': console.log(VERSION); return 0;
+    default:
+      console.error('whygit: unknown command ' + JSON.stringify(cmd));
+      console.log(HELP);
+      return 2;
+  }
+}

package/src/cmd-check.js

@@ -0,0 +1,81 @@
+/** whygit check - explanation coverage for a change set (CI gate). */
+import { c, plural, pct } from './util.js';
+import { loadContext, repoLabel } from './context.js';
+import { diffHunks, blamePorcelain, mergeBase, revParse } from './git.js';
+import { decisionFor } from './search.js';
+import { header, renderNote } from './ui.js';
+
+export function cmdCheck(args, flags) {
+  const ctx = loadContext({ cwd: flags.cwd });
+  const base = flags.base || 'origin/HEAD';
+  let baseSha = revParse(ctx.cwd, base);
+  if (!baseSha) baseSha = mergeBase(ctx.cwd, 'HEAD', base);
+  if (!baseSha) {
+    console.log(renderNote('Cannot resolve base ' + base + '. Pass --base <ref>.', 'warn'));
+    return 2;
+  }
+  const files = diffHunks(ctx.cwd, baseSha, 'HEAD');
+  const blameCache = new Map();
+  const results = [];
+  let total = 0;
+  let explained = 0;
+  let newTodos = 0;
+  for (const f of files) {
+    if (f.isBinary) continue;
+    if (!blameCache.has(f.path)) blameCache.set(f.path, blamePorcelain(ctx.cwd, f.path, null));
+    const blame = blameCache.get(f.path);
+    let lines = 0;
+    let ok = 0;
+    for (const h of f.hunks) {
+      for (let i = 0; i < h.added.length; i++) {
+        const lineNo = h.newStart + i;
+        const b = blame[lineNo - 1];
+        lines += 1;
+        if (/\b(TODO|FIXME|HACK|XXX)\b/.test(h.added[i])) newTodos += 1;
+        if (!b) continue;
+        const d = decisionFor(ctx.db, b.sha);
+        if (d && d.confidence >= 0.5 && d.rationale) ok += 1;
+      }
+    }
+    if (!lines) continue;
+    total += lines;
+    explained += ok;
+    results.push({ path: f.path, lines: lines, explained: ok, ratio: ok / lines });
+  }
+  results.sort(function (a, b) { return a.ratio - b.ratio; });
+  const coverage = total ? explained / total : 1;
+  if (flags.json) {
+    console.log(JSON.stringify({ base: baseSha, coverage: coverage, lines: total, explained: explained, newTodos: newTodos, files: results }, null, 2));
+    return coverage >= (flags.min == null ? 0.5 : flags.min) ? 0 : 1;
+  }
+  console.log(header('check', repoLabel(ctx) + '  ' + base + '..HEAD'));
+  console.log('');
+  console.log('  ' + c.bold('explanation coverage') + '  ' + colorPct(coverage) + c.gray('  (' + explained + '/' + total + ' changed lines trace to a commit that said why)'));
+  console.log('');
+  const worst = results.filter(function (r) { return r.ratio < 0.5; }).slice(0, 8);
+  if (worst.length) {
+    console.log(c.gray('  thin explanations:'));
+    for (const r of worst) {
+      console.log('  ' + c.red((' ' + Math.round(r.ratio * 100) + '%').padStart(4)) + '  ' + r.path + c.gray('  ' + plural(r.lines, 'line')));
+    }
+    console.log('');
+    console.log(c.gray('  these lines trace back to commits that never said why.'));
+    console.log(c.gray('  fix: amend the message, or add a WHY: <reason> line to the commit body.'));
+  } else {
+    console.log(renderNote('Every changed line traces back to a stated reason. Nicely done.', 'ok'));
+  }
+  if (newTodos) {
+    console.log('');
+    console.log(renderNote(newTodos + ' new TODO/FIXME marker(s) added - they will outlive you.', 'warn'));
+  }
+  console.log('');
+  const min = flags.min == null ? 0.5 : flags.min;
+  return coverage >= min ? 0 : 1;
+}
+
+function colorPct(v) {
+  const s = Math.round(v * 100) + '%';
+  if (v >= 0.8) return c.green(s);
+  if (v >= 0.5) return c.yellow(s);
+  return c.red(s);
+}

package/src/cmd-cursed.js

@@ -0,0 +1,38 @@
+/** whygit cursed - the files that keep coming back. */
+import { c, isoDate, truncate, plural } from './util.js';
+import { loadContext, repoLabel } from './context.js';
+import { topRisk } from './risk.js';
+import { header, bar, termWidth, renderNote } from './ui.js';
+import { lsFiles } from './git.js';
+
+export function cmdCursed(args, flags) {
+  const ctx = loadContext({ cwd: flags.cwd });
+  const n = Number(flags.limit || flags.n) || 15;
+  const alive = new Set(lsFiles(ctx.cwd));
+  const scored = topRisk(ctx.db, Math.max(n * 6, 120));
+  const rows = scored.filter(function (r) { return alive.has(r.path); }).slice(0, n);
+  if (flags.json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+  const max = Math.max.apply(null, rows.map(function (r) { return r.score; }).concat([1]));
+  console.log(header('cursed files', repoLabel(ctx) + '  ' + plural(ctx.stats.files, 'file') + ' tracked'));
+  console.log('');
+  const width = Math.max.apply(null, rows.map(function (r) { return r.path.length; }).concat([20]));
+  rows.forEach(function (r, i) {
+    const flame = '\ud83d\udd25'.repeat(Math.max(1, Math.min(5, Math.round((r.score / max) * 5))));
+    console.log(
+      '  ' + c.gray(String(i + 1).padStart(2)) + '  ' +
+      c.bold(truncate(r.path, Math.min(width, termWidth() - 46)).padEnd(Math.min(width, termWidth() - 46))) + '  ' +
+      bar(r.score, max, 14) + '  ' +
+      c.gray(String(Math.round(r.score * 10) / 10).padStart(5)) + '  ' +
+      c.gray(plural(r.commits, 'commit')) + c.gray(' \u00b7 ') + c.gray(r.authors + ' authors') + c.gray(' \u00b7 ') +
+      (r.fixes ? c.red(r.fixes + ' fixes') : c.gray('0 fixes'))
+    );
+  });
+  console.log('');
+  console.log(c.gray('  score = churn \u00d7 fix-density \u00d7 author-spread \u00d7 freshness. Not a judgement, a map.'));
+  console.log(c.gray('  Start here: ') + c.bold('whygit story <file>'));
+  console.log('');
+  return 0;
+}

package/src/cmd-init.js

@@ -0,0 +1,92 @@
+/** whygit init / doctor / status. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { c } from './util.js';
+import { loadContext, repoLabel, resolveRepo } from './context.js';
+import { gitDir, git, headSha, isShallow, revParse } from './git.js';
+import { buildIndex, computeRisk, scanMarkers, indexPathFor } from './indexer.js';
+import { getMeta, dbStats } from './db.js';
+import { header, kv, renderNote } from './ui.js';
+
+export function cmdInit(args, flags) {
+  const cwd = resolveRepo(flags.cwd);
+  const full = Boolean(flags.full) || !fs.existsSync(indexPathFor(gitDir(cwd)));
+  const t0 = Date.now();
+  const res = buildIndex({ cwd: cwd, full: full });
+  const ctx = loadContext({ cwd: cwd });
+  const files = computeRisk(ctx.db);
+  const markers = scanMarkers(ctx.db, cwd);
+  const stats = dbStats(ctx.db);
+  if (flags.json) {
+    console.log(JSON.stringify({ indexed: res, stats: stats, files: files, markers: markers }, null, 2));
+    return 0;
+  }
+  console.log(header('index', repoLabel(ctx)));
+  console.log('');
+  console.log(kv([
+    ['commits', stats.commits.toLocaleString('en-US') + c.gray('  (' + res.commits + ' new this run)')],
+    ['decisions', stats.decisions.toLocaleString('en-US')],
+    ['files', stats.files.toLocaleString('en-US')],
+    ['markers', markers.markers + c.gray(' TODO/FIXME in ' + markers.files + ' files')],
+    ['time', ((Date.now() - t0) / 1000).toFixed(2) + 's'],
+  ]));
+  console.log('');
+  if (isShallow(cwd)) console.log(renderNote('Shallow clone: history is partial. git fetch --unshallow for the full story.', 'warn'));
+  if (!stats.commits) console.log(renderNote('No commits indexed - is this a fresh repo?', 'warn'));
+  console.log(renderNote('Next: ' + c.bold('whygit why "timeout"') + ' or ' + c.bold('whygit cursed'), 'ok'));
+  return 0;
+}
+
+export function cmdDoctor(args, flags) {
+  const cwd = resolveRepo(flags.cwd);
+  const gd = gitDir(cwd);
+  const checks = [];
+  const add = function (name, ok, detail) { checks.push({ name: name, ok: ok, detail: detail }); };
+  add('git', Boolean(headSha(cwd)), (function () { try { return git(['--version'], { cwd: cwd }).trim(); } catch { return 'not found'; } })());
+  add('repository', true, cwd);
+  const idx = indexPathFor(gd);
+  const has = fs.existsSync(idx);
+  add('index', has, has ? idx + ' (' + Math.round(fs.statSync(idx).size / 1024) + ' KB)' : 'missing - run whygit init');
+  if (has) {
+    const ctx = loadContext({ cwd: cwd });
+    const head = headSha(cwd);
+    const meta = getMeta(ctx.db, 'head');
+    add('up to date', meta === head, meta === head ? 'indexed at ' + String(meta).slice(0, 8) : 'stale: indexed ' + String(meta).slice(0, 8) + ' vs HEAD ' + String(head).slice(0, 8));
+    add('shallow', !isShallow(cwd), isShallow(cwd) ? 'partial history' : 'full history');
+    const wl = path.join(cwd, 'WHYLOG.md');
+    add('whylog', fs.existsSync(wl), fs.existsSync(wl) ? 'WHYLOG.md present' : 'not written yet - whygit whylog --write');
+  }
+  if (flags.json) {
+    console.log(JSON.stringify(checks, null, 2));
+    return checks.every(function (x) { return x.ok; }) ? 0 : 1;
+  }
+  console.log(header('doctor', repoLabel({ cwd: cwd, webUrl: null })));
+  console.log('');
+  for (const ch of checks) {
+    console.log('  ' + (ch.ok ? c.green('\u2713') : c.red('\u2717')) + ' ' + ch.name.padEnd(12) + ' ' + c.gray(ch.detail));
+  }
+  console.log('');
+  return checks.every(function (x) { return x.ok; }) ? 0 : 1;
+}
+
+export function cmdStatus(args, flags) {
+  const ctx = loadContext({ cwd: flags.cwd });
+  if (flags.json) {
+    console.log(JSON.stringify({ repo: repoLabel(ctx), stats: ctx.stats, head: ctx.head, branch: ctx.branch }, null, 2));
+    return 0;
+  }
+  console.log(header('whygit', repoLabel(ctx)));
+  console.log('');
+  console.log(kv([
+    ['commits', ctx.stats.commits.toLocaleString('en-US')],
+    ['decisions', ctx.stats.decisions.toLocaleString('en-US')],
+    ['files', ctx.stats.files.toLocaleString('en-US')],
+    ['branch', ctx.branch || '(detached)'],
+    ['head', String(ctx.head || '').slice(0, 8)],
+    ['whylog', fs.existsSync(path.join(ctx.cwd, 'WHYLOG.md')) ? c.green('yes') : c.gray('no')],
+  ]));
+  console.log('');
+  console.log(c.gray('  whygit why <question>   \u00b7   whygit story <file>   \u00b7   whygit cursed'));
+  console.log('');
+  return 0;
+}

package/src/cmd-story.js

@@ -0,0 +1,85 @@
+/** whygit story - narrate one file's life. */
+import { c, isoDate, truncate, wrapText, plural, clamp } from './util.js';
+import { loadContext, repoLabel } from './context.js';
+import { decisionsForFile, fileRow, authorsForFile, birthOf, yearHistogram, chapterCandidates } from './risk.js';
+import { header, bar, termWidth, renderNote } from './ui.js';
+import { lsFiles } from './git.js';
+
+export function cmdStory(args, flags) {
+  const file = String(args[0] || '').replace(/\\/g, '/');
+  if (!file) {
+    console.error('usage: whygit story <path>');
+    return 2;
+  }
+  const ctx = loadContext({ cwd: flags.cwd });
+  let target = file;
+  if (!ctx.db.prepare('SELECT 1 FROM commit_files WHERE path = ? LIMIT 1').get(target)) {
+    const matches = lsFiles(ctx.cwd).filter(function (p) { return p.toLowerCase().includes(file.toLowerCase()); });
+    if (matches.length === 1) target = matches[0];
+    else if (matches.length > 1) {
+      console.log(renderNote('Multiple files match: ' + matches.slice(0, 6).join(', '), 'warn'));
+      return 0;
+    } else {
+      console.log(renderNote('No history for ' + file + ' - it may be untracked or never committed.', 'warn'));
+      return 0;
+    }
+  }
+  const rows = decisionsForFile(ctx.db, target, 4000);
+  const stats = fileRow(ctx.db, target);
+  const authors = authorsForFile(ctx.db, target);
+  const birth = birthOf(ctx.db, target) || rows[0];
+  if (flags.json) {
+    console.log(JSON.stringify({ file: target, stats: stats, birth: birth, authors: authors, decisions: rows }, null, 2));
+    return 0;
+  }
+  console.log(header('story', repoLabel(ctx) + '  ' + target));
+  if (birth) {
+    console.log(c.gray('  born ') + isoDate(birth.ts) + c.gray(' \u00b7 ') + c.bold(truncate(birth.title, 70)));
+  }
+  const hist = yearHistogram(ctx.db, target);
+  const years = new Map();
+  for (const h of hist) years.set(h.year, h.n);
+  const yKeys = Array.from(years.keys()).sort();
+  if (yKeys.length) {
+    const counts = yKeys.map(function (y) { return years.get(y); });
+    const max = Math.max.apply(null, counts);
+    console.log('');
+    const labelW = 6;
+    for (let i = 0; i < yKeys.length; i++) {
+      const s = String(yKeys[i]);
+      console.log('  ' + c.gray(s.padStart(labelW)) + '  ' + bar(counts[i], max, Math.min(40, termWidth() - 16)) + '  ' + c.gray(counts[i] + ''));
+    }
+  }
+  console.log('');
+  console.log(c.gray('  ' + (stats ? plural(stats.commits, 'commit') + ' \u00b7 ' + stats.authors + ' authors \u00b7 ' + (stats.fixes || 0) + ' fixes \u00b7 ' + (stats.todos || 0) + ' TODO markers' : '')));
+  const scored = chapterCandidates(ctx.db, target).map(function (r) {
+    const churn = Math.log10(2 + (r.added || 0) + (r.removed || 0));
+    const s = (0.25 + (r.confidence || 0)) * churn * (r.kind === 'fix' ? 1.4 : 1);
+    return Object.assign({}, r, { weight: s });
+  });
+  console.log(c.gray('  \u2500\u2500\u2500 the plot ' + '\u2500'.repeat(Math.max(0, Math.min(50, termWidth() - 20)))));
+  const top = scored.slice().sort(function (a, b) { return b.weight - a.weight; }).slice(0, 24);
+  const ordered = top.slice().sort(function (a, b) { return a.ts - b.ts; });
+  const pick = ordered.length > 8 ? sample(ordered, 8) : ordered;
+  for (const r of pick) {
+    console.log('');
+    console.log('  ' + c.gray(isoDate(r.ts)) + '  ' + c.bold(truncate(r.title, termWidth() - 16)));
+    if (r.rationale) {
+      const lines = wrapText(r.rationale, termWidth() - 10, '            ');
+      for (const l of lines) console.log(c.white(l));
+    }
+  }
+  if (authors.length) {
+    console.log('');
+    console.log(c.gray('  who kept it alive: ') + authors.slice(0, 5).map(function (a) { return a.author + ' (' + a.n + ')'; }).join(', '));
+  }
+  console.log('');
+  return 0;
+}
+
+function sample(arr, n) {
+  const out = [];
+  const step = Math.max(1, Math.floor(arr.length / n));
+  for (let i = 0; i < arr.length && out.length < n; i += step) out.push(arr[i]);
+  return out;
+}

package/src/cmd-why.js

@@ -0,0 +1,105 @@
+/** whygit why - the main question. */
+import { c, isoDate, truncate, wrapText, plural } from './util.js';
+import { parsePathLine } from './util.js';
+import { loadContext, repoLabel } from './context.js';
+import { search, decisionFor, decisionsForPath } from './search.js';
+import { renderDecision, header, termWidth, renderNote } from './ui.js';
+import { blamePorcelain, commitUrl, blameUrl, lsFiles } from './git.js';
+
+export function cmdWhy(args, flags) {
+  const query = args.join(' ').trim();
+  if (!query) {
+    console.error('usage: whygit why <words...> | <file>:<line>');
+    return 2;
+  }
+  const ctx = loadContext({ cwd: flags.cwd });
+  const started = Date.now();
+  const pl = parsePathLine(query);
+  const isLine = pl.line != null && /[./\\]/.test(pl.path);
+  let results = [];
+  let alias = null;
+  if (isLine) {
+    const target = resolvePath(ctx, pl.path);
+    if (!target) {
+      console.log(header('whygit', repoLabel(ctx)));
+      console.log(renderNote('No file named ' + c.bold(pl.path) + ' at HEAD. History may know it under another path.', 'warn'));
+      console.log(renderNote('Tip: ' + c.bold('whygit story <file>') + ' narrates one file from birth to HEAD.'));
+      return 0;
+    }
+    if (target !== pl.path) alias = target;
+    results = whyLine(ctx, target, pl.line);
+  } else {
+    results = whyQuery(ctx, query, flags);
+  }
+  if (flags.json) {
+    console.log(JSON.stringify(results, null, 2));
+    return 0;
+  }
+  if (!results.length) {
+    console.log(header('whygit', repoLabel(ctx)));
+    console.log(renderNote('No decision matched. Try fewer words, or a file path.', 'warn'));
+    console.log(renderNote('Tip: ' + c.bold('whygit story <file>') + ' narrates one file from birth to HEAD.'));
+    return 0;
+  }
+  console.log(header('whygit', repoLabel(ctx) + '  ' + ctx.stats.commits.toLocaleString('en-US') + ' commits'));
+  const max = flags.n || flags.limit || (isLine ? 4 : 5);
+  results.slice(0, max).forEach(function (d, i) {
+    const extra = [];
+    if (alias && i === 0) extra.push(c.gray('resolved ') + c.bold(alias) + c.gray(' (path moved; history kept)'));
+    if (d.alive != null) {
+      extra.push(c.gray('line ' + pl.line + ' is ') + c.cyan(d.alive + ' lines') + c.gray(' of this change, still in HEAD'));
+    }
+    if (ctx.webUrl && d.sha) {
+      const url = commitUrl(ctx.webUrl, d.sha);
+      if (url) extra.push(c.gray('\u2192 ') + c.underline(c.dim(url)));
+    }
+    console.log(renderDecision(d, { index: i + 1, extra: extra }));
+  });
+  const ms = Date.now() - started;
+  console.log('');
+  const shown = Math.min(results.length, max);
+  const label = results.length > shown ? shown + ' of ' + results.length + ' decisions' : plural(results.length, 'decision');
+  console.log(c.gray('  ' + label + ' \u00b7 ' + ms + 'ms \u00b7 whygit why "' + truncate(query, 40) + '"'));
+  console.log('');
+  return 0;
+}
+
+function whyQuery(ctx, query, flags) {
+  const rows = search(ctx.db, query, { limit: (flags.n || 5) * 3 });
+  return rows.map(function (r) {
+    return Object.assign({}, r, { ts: r.ts });
+  });
+}
+
+function resolvePath(ctx, p) {
+  const files = lsFiles(ctx.cwd);
+  const set = new Set(files);
+  if (set.has(p)) return p;
+  const bySuffix = files.filter(function (f) { return f.endsWith('/' + p) || f.endsWith(p); });
+  return bySuffix.length === 1 ? bySuffix[0] : null;
+}
+
+function whyLine(ctx, file, line) {
+  const blame = blamePorcelain(ctx.cwd, file, null);
+  const entry = blame[line - 1];
+  if (!entry) return [];
+  const d = decisionFor(ctx.db, entry.sha);
+  const out = [];
+  if (d) {
+    const same = blame.filter(function (b) { return b && b.sha === entry.sha; }).length;
+    out.push(Object.assign({}, d, { alive: same, lineText: entry.text }));
+  } else {
+    out.push({
+      sha: entry.sha,
+      ts: entry.ts,
+      title: '(commit not in index - run whygit init --full)',
+      rationale: '',
+      kind: 'change',
+      paths: file,
+      alive: 0,
+    });
+  }
+  const history = decisionsForPath(ctx.db, file, 6).filter(function (x) { return x.sha !== entry.sha; });
+  for (const h of history) out.push(Object.assign({}, h, { kind: h.kind }));
+  return out;
+}

package/src/context.js

@@ -0,0 +1,63 @@
+/** Shared command context: locate repo, open index, auto-build when missing. */
+import process from 'node:process';
+import { isRepo, repoRoot, gitDir, headSha, branchName, remoteWebUrl } from './git.js';
+import { openIndex, dbStats, getMeta } from './db.js';
+import { buildIndex, computeRisk } from './indexer.js';
+import { c, warn, die } from './util.js';
+
+export function resolveRepo(cwd) {
+  const start = cwd || process.cwd();
+  if (!isRepo(start)) die('not inside a git repository (run this from your project, or pass --cwd)');
+  return repoRoot(start);
+}
+
+export function loadContext(opts) {
+  const o = opts || {};
+  const cwd = resolveRepo(o.cwd);
+  const gd = gitDir(cwd);
+  let db = openIndex(gd, { create: false });
+  if (!db) {
+    if (o.noAuto) die('no index yet - run ' + c.bold('whygit init'));
+    process.stderr.write(c.dim('whygit: building index (first run, one pass over history)...\n'));
+    const res = buildIndex({ cwd: cwd, quiet: true });
+    process.stderr.write(c.dim('whygit: indexed ' + res.commits + ' commits in ' + (res.elapsed / 1000).toFixed(2) + 's\n'));
+    db = openIndex(gd, { create: false });
+  }
+  const head = headSha(cwd);
+  const indexedHead = getMeta(db, 'head');
+  const empty = dbStats(db).commits === 0;
+  if ((empty || (head && indexedHead && head !== indexedHead)) && o.refresh !== false) {
+    try {
+      buildIndex({ cwd: cwd, quiet: true });
+      db.close();
+      db = openIndex(gd, { create: false });
+    } catch (err) {
+      warn('could not refresh index: ' + err.message);
+    }
+  }
+  return {
+    cwd: cwd,
+    gitDir: gd,
+    db: db,
+    head: head,
+    branch: branchName(cwd),
+    webUrl: remoteWebUrl(cwd),
+    stats: dbStats(db),
+    root: getMeta(db, 'root') || cwd,
+  };
+}
+
+export function repoLabel(ctx) {
+  const web = ctx.webUrl;
+  if (web) {
+    const m = web.match(/^https?:\/\/[^/]+\/(.+)$/);
+    if (m) return m[1];
+  }
+  return ctx.cwd.split(/[\\/]/).pop();
+}
+
+export function ensureIndex(cwd, full) {
+  return buildIndex({ cwd: cwd, full: full });
+}
+
+export { computeRisk };

package/src/db.js

@@ -0,0 +1,76 @@
+/** SQLite storage for the whygit index. */
+import { DatabaseSync } from 'node:sqlite';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SCHEMA_VERSION = '2';
+
+const SCHEMA = [
+  "CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);",
+  "CREATE TABLE IF NOT EXISTS commits (sha TEXT PRIMARY KEY, ts INTEGER, iso TEXT, author TEXT, email TEXT, subject TEXT, body TEXT, parents TEXT, is_bot INTEGER DEFAULT 0, files_changed INTEGER DEFAULT 0, added INTEGER DEFAULT 0, removed INTEGER DEFAULT 0, paths TEXT DEFAULT '');",
+  "CREATE TABLE IF NOT EXISTS commit_files (sha TEXT, path TEXT, added INTEGER, removed INTEGER, status TEXT, PRIMARY KEY (sha, path));",
+  "CREATE INDEX IF NOT EXISTS idx_commit_files_path ON commit_files(path);",
+  "CREATE TABLE IF NOT EXISTS decisions (sha TEXT PRIMARY KEY, ts INTEGER, title TEXT, rationale TEXT, paths TEXT, kind TEXT, confidence REAL, evidence TEXT);",
+  "CREATE VIRTUAL TABLE IF NOT EXISTS decisions_fts USING fts5(title, rationale, paths, subject, tokenize='porter unicode61');",
+  "CREATE VIRTUAL TABLE IF NOT EXISTS decisions_tri USING fts5(title, rationale, paths, tokenize='trigram');",
+  "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY AUTOINCREMENT, path TEXT, line INTEGER, sha TEXT, body TEXT, ts INTEGER);",
+  "CREATE TABLE IF NOT EXISTS risk (path TEXT PRIMARY KEY, score REAL, commits INTEGER, authors INTEGER, fixes INTEGER, todos INTEGER, last_ts INTEGER, added INTEGER, removed INTEGER);",
+  "CREATE TABLE IF NOT EXISTS blame_cache (path TEXT, head TEXT, data TEXT, PRIMARY KEY (path, head));",
+].join(' ');
+
+export function indexPath(gitDirPath) {
+  return path.join(gitDirPath, 'whygit', 'index.db');
+}
+
+export function openIndex(gitDirPath, opts) {
+  const o = opts || {};
+  const file = indexPath(gitDirPath);
+  if (!o.create && !fs.existsSync(file)) return null;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const dbc = new DatabaseSync(file);
+  dbc.exec('PRAGMA journal_mode = WAL;');
+  dbc.exec('PRAGMA synchronous = NORMAL;');
+  dbc.exec('PRAGMA temp_store = MEMORY;');
+  dbc.exec(SCHEMA);
+  const v = getMeta(dbc, 'schema');
+  if (v && v !== SCHEMA_VERSION) {
+    for (const t of ['decisions_fts', 'decisions_tri', 'decisions', 'commits', 'commit_files', 'risk', 'blame_cache']) {
+      dbc.exec('DROP TABLE IF EXISTS ' + t + ';');
+    }
+    dbc.exec('DELETE FROM meta;');
+    dbc.exec(SCHEMA);
+  }
+  setMeta(dbc, 'schema', SCHEMA_VERSION);
+  return dbc;
+}
+
+export function getMeta(dbc, key) {
+  const row = dbc.prepare('SELECT value FROM meta WHERE key = ?').get(key);
+  return row ? row.value : null;
+}
+
+export function setMeta(dbc, key, value) {
+  dbc.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, String(value));
+}
+
+export function tx(dbc, fn) {
+  dbc.exec('BEGIN');
+  try {
+    const out = fn();
+    dbc.exec('COMMIT');
+    return out;
+  } catch (err) {
+    dbc.exec('ROLLBACK');
+    throw err;
+  }
+}
+
+export function dbStats(dbc) {
+  const one = function (sql) { const r = dbc.prepare(sql).get(); return r ? Object.values(r)[0] : 0; };
+  return {
+    commits: one('SELECT COUNT(*) FROM commits'),
+    decisions: one('SELECT COUNT(*) FROM decisions'),
+    files: one('SELECT COUNT(DISTINCT path) FROM commit_files'),
+    notes: one('SELECT COUNT(*) FROM notes'),
+  };
+}