whygit 0.0.0-stage → 0.1.1

package/src/mcp.js

@@ -0,0 +1,171 @@
+/** Minimal, dependency-free MCP server over stdio (newline-delimited JSON). */
+import { loadContext, repoLabel } from './context.js';
+import { search, decisionFor } from './search.js';
+import { blamePorcelain, commitUrl, remoteWebUrl } from './git.js';
+import { decisionsForFile, fileRow, topRisk, authorsForFile } from './risk.js';
+import { buildWhylog } from './whylog.js';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_INFO = { name: 'whygit', version: '0.1.0' };
+
+const TOOLS = [
+  {
+    name: 'why_search',
+    description: 'Search this repository history for the reason behind a piece of code or a past decision. Use when the user asks why code is written a certain way, or before changing code whose intent is unclear.',
+    inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Words describing the behaviour or decision, e.g. "retry on 503" or "why proxy auth is stripped".' }, limit: { type: 'number', default: 5 } }, required: ['query'] },
+  },
+  {
+    name: 'why_line',
+    description: 'Explain a single file:line - which commit introduced it, what that commit said about why, and whether the line is still the original.',
+    inputSchema: { type: 'object', properties: { file: { type: 'string' }, line: { type: 'number' } }, required: ['file', 'line'] },
+  },
+  {
+    name: 'why_file',
+    description: 'The decision history of one file, oldest first - the story of why it looks the way it does.',
+    inputSchema: { type: 'object', properties: { path: { type: 'string' }, limit: { type: 'number', default: 12 } }, required: ['path'] },
+  },
+  {
+    name: 'why_risk',
+    description: 'The most dangerous files in this repository, ranked by churn, fix-density and author-spread. Use before refactoring or when choosing what to inspect.',
+    inputSchema: { type: 'object', properties: { limit: { type: 'number', default: 10 } } },
+  },
+  {
+    name: 'whylog_read',
+    description: 'Read WHYLOG.md - the curated, generated summary of this repository\'s load-bearing decisions. Prefer this over reading the whole history.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+function textResult(obj) {
+  const text = typeof obj === 'string' ? obj : JSON.stringify(obj, null, 2);
+  return { content: [{ type: 'text', text: text }] };
+}
+
+function slim(r) {
+  return {
+    commit: r.sha,
+    date: r.ts ? new Date(r.ts * 1000).toISOString().slice(0, 10) : null,
+    title: r.title,
+    why: r.rationale || null,
+    paths: r.paths ? String(r.paths).split(/\s+/).slice(0, 5) : [],
+    author: r.author || null,
+    kind: r.kind,
+  };
+}
+
+export function createServer(opts) {
+  const o = opts || {};
+  let ctx = null;
+  const ensure = function () {
+    if (!ctx) ctx = loadContext({ cwd: o.cwd || process.cwd() });
+    return ctx;
+  };
+
+  const handlers = {
+    why_search: function (a) {
+      const cx = ensure();
+      const rows = search(cx.db, String(a.query || ''), { limit: a.limit || 5 });
+      return textResult({ repo: repoLabel(cx), query: a.query, results: rows.map(slim) });
+    },
+    why_line: function (a) {
+      const cx = ensure();
+      const file = String(a.file || '');
+      const line = Number(a.line);
+      const blame = blamePorcelain(cx.cwd, file, null);
+      const b = blame[line - 1];
+      if (!b) return textResult({ error: 'no such line: ' + file + ':' + line });
+      const d = decisionFor(cx.db, b.sha) || { sha: b.sha, ts: b.ts, title: '(unindexed commit)', rationale: '', paths: file };
+      const alive = blame.filter(function (x) { return x && x.sha === b.sha; }).length;
+      return textResult({
+        file: file,
+        line: line,
+        code: b.text,
+        introduced_by: slim(d),
+        lines_from_same_commit: alive,
+        url: commitUrl(cx.webUrl, b.sha),
+      });
+    },
+    why_file: function (a) {
+      const cx = ensure();
+      const p = String(a.path || '').replace(/\\/g, '/');
+      const rows = decisionsForFile(cx.db, p, a.limit || 12);
+      const stats = fileRow(cx.db, p);
+      return textResult({ file: p, stats: stats, decisions: rows.map(slim) });
+    },
+    why_risk: function (a) {
+      const cx = ensure();
+      return textResult({ files: topRisk(cx.db, a.limit || 10) });
+    },
+    whylog_read: function () {
+      const cx = ensure();
+      const f = path.join(cx.cwd, 'WHYLOG.md');
+      if (fs.existsSync(f)) return textResult(fs.readFileSync(f, 'utf8'));
+      return textResult(buildWhylog(cx, { label: repoLabel(cx) }));
+    },
+  };
+
+  function handle(msg) {
+    const id = msg.id;
+    const method = msg.method;
+    if (method === 'initialize') {
+      return { jsonrpc: '2.0', id: id, result: { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {}, resources: {} }, serverInfo: SERVER_INFO } };
+    }
+    if (method === 'notifications/initialized' || method === 'notifications/cancelled') return null;
+    if (method === 'ping') return { jsonrpc: '2.0', id: id, result: {} };
+    if (method === 'tools/list') return { jsonrpc: '2.0', id: id, result: { tools: TOOLS } };
+    if (method === 'tools/call') {
+      const name = msg.params && msg.params.name;
+      const fn = handlers[name];
+      if (!fn) return { jsonrpc: '2.0', id: id, error: { code: -32602, message: 'unknown tool ' + name } };
+      try {
+        return { jsonrpc: '2.0', id: id, result: fn((msg.params && msg.params.arguments) || {}) };
+      } catch (err) {
+        return { jsonrpc: '2.0', id: id, error: { code: -32000, message: String(err && err.message || err) } };
+      }
+    }
+    if (method === 'resources/list') {
+      return { jsonrpc: '2.0', id: id, result: { resources: [{ uri: 'whygit://whylog', name: 'WHYLOG.md', mimeType: 'text/markdown', description: 'Generated summary of load-bearing decisions.' }] } };
+    }
+    if (method === 'resources/read') {
+      const uri = msg.params && msg.params.uri;
+      if (uri === 'whygit://whylog') {
+        const r = handlers.whylog_read({});
+        return { jsonrpc: '2.0', id: id, result: { contents: [{ uri: uri, mimeType: 'text/markdown', text: r.content[0].text }] } };
+      }
+      return { jsonrpc: '2.0', id: id, error: { code: -32602, message: 'unknown resource' } };
+    }
+    if (id === undefined) return null;
+    return { jsonrpc: '2.0', id: id, error: { code: -32601, message: 'method not found: ' + method } };
+  }
+
+  function start() {
+    let buf = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', function (chunk) {
+      buf += chunk;
+      let idx;
+      while ((idx = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, idx).trim();
+        buf = buf.slice(idx + 1);
+        if (!line) continue;
+        let msg;
+        try { msg = JSON.parse(line); } catch { continue; }
+        let res;
+        try { res = handle(msg); } catch (err) { res = { jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: String(err.message) } }; }
+        if (res) process.stdout.write(JSON.stringify(res) + '\n');
+      }
+    });
+    process.stdin.on('end', function () { process.exit(0); });
+    process.stderr.write('whygit mcp: ready (stdio)\n');
+  }
+
+  return { start: start, handle: handle, tools: TOOLS };
+}
+
+export function cmdMcp(args, flags) {
+  const server = createServer({ cwd: flags.cwd });
+  server.start();
+  return 0;
+}

package/src/risk.js

@@ -0,0 +1,44 @@
+/** Risk / cursed-file analytics. */
+
+export function topRisk(dbc, limit) {
+  return dbc.prepare('SELECT path, score, commits, authors, fixes, todos, last_ts, added, removed FROM risk ORDER BY score DESC LIMIT ?').all(limit || 20);
+}
+
+export function riskFor(dbc, p) {
+  return dbc.prepare('SELECT path, score, commits, authors, fixes, todos, last_ts, added, removed FROM risk WHERE path = ?').get(p) || null;
+}
+
+export function fileRow(dbc, p) {
+  return dbc.prepare('SELECT path, commits, authors, fixes, todos, last_ts, added, removed FROM risk WHERE path = ?').get(p) || null;
+}
+
+export function decisionsForFile(dbc, p, limit) {
+  return dbc.prepare('SELECT d.sha, d.ts, d.title, d.rationale, d.paths, d.kind, d.confidence, c.author, c.added, c.removed FROM decisions d JOIN commit_files cf ON cf.sha = d.sha JOIN commits c ON c.sha = d.sha WHERE cf.path = ? ORDER BY d.ts ASC LIMIT ?').all(p, limit || 500);
+}
+
+export function yearHistogram(dbc, p) {
+  return dbc.prepare("SELECT CAST(strftime('%Y', c.ts, 'unixepoch') AS INTEGER) AS year, COUNT(*) AS n FROM commit_files cf JOIN commits c ON c.sha = cf.sha WHERE cf.path = ? GROUP BY year ORDER BY year").all(p);
+}
+
+export function chapterCandidates(dbc, p, limit) {
+  return dbc.prepare('SELECT d.sha, d.ts, d.title, d.rationale, d.kind, d.confidence, c.author, c.added, c.removed FROM decisions d JOIN commit_files cf ON cf.sha = d.sha JOIN commits c ON c.sha = d.sha WHERE cf.path = ? AND d.rationale != \'\' ORDER BY d.ts ASC LIMIT ?').all(p, limit || 4000);
+}
+
+export function authorsForFile(dbc, p) {
+  const rows = dbc.prepare('SELECT c.author AS author, c.email AS email, COUNT(*) AS n FROM commit_files cf JOIN commits c ON c.sha = cf.sha WHERE cf.path = ? AND c.is_bot = 0 GROUP BY c.email ORDER BY n DESC LIMIT 40').all(p);
+  const byName = new Map();
+  for (const r of rows) {
+    const key = String(r.author || '').toLowerCase();
+    if (byName.has(key)) byName.get(key).n += r.n;
+    else byName.set(key, { author: r.author, n: r.n });
+  }
+  return Array.from(byName.values()).sort(function (a, b) { return b.n - a.n; }).slice(0, 8);
+}
+
+export function birthOf(dbc, p) {
+  return dbc.prepare('SELECT d.sha, d.ts, d.title, c.author FROM decisions d JOIN commit_files cf ON cf.sha = d.sha JOIN commits c ON c.sha = d.sha WHERE cf.path = ? ORDER BY d.ts ASC LIMIT 1').get(p) || null;
+}
+
+export function fixCommitsForFile(dbc, p, limit) {
+  return dbc.prepare('SELECT d.sha, d.ts, d.title, d.rationale, d.kind, c.author FROM decisions d JOIN commit_files cf ON cf.sha = d.sha JOIN commits c ON c.sha = d.sha WHERE cf.path = ? AND d.kind = \'fix\' ORDER BY d.ts DESC LIMIT ?').all(p, limit || 6);
+}

package/src/search.js

@@ -0,0 +1,161 @@
+/** Query layer: BM25 + heuristics over the decision index. */
+import { openIndex } from './db.js';
+
+const STOP = new Set(['the','a','an','is','are','was','were','to','of','in','on','for','and','or','it','this','that','with','how','why','what','do','does','did','be','by','as','at','from','we','you','i','my','our']);
+
+export function tokenize(q) {
+  return String(q || '')
+    .toLowerCase()
+    .split(/[^a-z0-9_./\u3400-\u9fff-]+/)
+    .map(function (t) { return t.replace(/^\.+|\/+$/g, ''); })
+    .filter(function (t) { return (t.length > 1 || CJK.test(t)) && !STOP.has(t); })
+    .slice(0, 12);
+}
+
+export function ftsQuery(q) {
+  const toks = tokenize(q);
+  if (!toks.length) return null;
+  const parts = toks.map(function (t) {
+    const safe = t.replace(/"/g, '');
+    return '"' + safe + '"*';
+  });
+  return parts.join(' OR ');
+}
+
+const SELECT = 'SELECT d.sha, d.ts, d.title, d.rationale, d.paths, d.kind, d.confidence, c.author, c.is_bot, bm25(decisions_fts, 9.0, 5.0, 6.0, 3.0) AS rank FROM decisions_fts JOIN decisions d ON d.rowid = decisions_fts.rowid JOIN commits c ON c.sha = d.sha';
+
+const CJK = /[\u3400-\u9fff\uf900-\ufaff]/;
+const TRI_SELECT = 'SELECT d.sha, d.ts, d.title, d.rationale, d.paths, d.kind, d.confidence, c.author, c.is_bot, bm25(decisions_tri, 9.0, 5.0, 6.0) AS rank FROM decisions_tri JOIN decisions d ON d.rowid = decisions_tri.rowid JOIN commits c ON c.sha = d.sha';
+
+/** Substring search: the trigram index handles CJK and code identifiers. */
+export function searchSubstring(dbc, query, opts) {
+  const o = opts || {};
+  const limit = o.limit || 10;
+  const q = String(query || '').trim();
+  if (q.length < 3) return searchLike(dbc, q, limit * 6);
+  const rows = dbc.prepare(TRI_SELECT + ' WHERE decisions_tri MATCH ? ORDER BY rank LIMIT ?').all('"' + q.replace(/"/g, '') + '"', limit * 6);
+  return rows;
+}
+
+function searchLike(dbc, q, n) {
+  if (!q) return [];
+  const like = '%' + q + '%';
+  return dbc.prepare('SELECT d.sha, d.ts, d.title, d.rationale, d.paths, d.kind, d.confidence, c.author, c.is_bot, 0 AS rank FROM decisions d JOIN commits c ON c.sha = d.sha WHERE d.title LIKE ? OR d.rationale LIKE ? ORDER BY d.confidence DESC LIMIT ?').all(like, like, n);
+}
+
+export function search(dbc, query, opts) {
+  const o = opts || {};
+  const limit = o.limit || 10;
+  const q = String(query || '').trim();
+  if (!q) return [];
+  const runs = [];
+  const match = ftsQuery(query);
+  if (match) {
+    try {
+      runs.push(dbc.prepare(SELECT + ' WHERE decisions_fts MATCH ? ORDER BY rank LIMIT ?').all(match, limit * 6));
+    } catch (e) { /* ignore malformed fts syntax */ }
+  }
+  if (CJK.test(q) || q.length >= 4) {
+    try { runs.push(searchSubstring(dbc, q, { limit: limit })); } catch (e) { /* trigram table missing */ }
+  }
+  const seen = new Map();
+  for (const rows of runs) {
+    for (const r of rows) {
+      const prev = seen.get(r.sha);
+      if (!prev || (r.rank || 0) < (prev.rank || 0)) seen.set(r.sha, r);
+    }
+  }
+  const merged = Array.from(seen.values());
+  if (!merged.length) return rerank(searchLike(dbc, q, limit * 6), query, o).slice(0, limit);
+  return rerank(merged, query, o).slice(0, limit);
+}
+
+export function noisePenalty(r) {
+  let p = 1;
+  const paths = String(r.paths || '').toLowerCase();
+  const list = paths.split(' ').filter(Boolean);
+  if (list.length && list.every(function (x) { return /(^|\/)(vendor|third_party|thirdparty|packages|node_modules|dist|build|target|external)\//.test(x); })) p *= 0.4;
+  if (list.length && list.every(function (x) { return /\.(rst|md|mdx|txt)$/.test(x) || /(^|\/)(docs?|documentation)\//.test(x); })) p *= 0.75;
+  const title = String(r.title || '').trim();
+  if (/^(bump|update\s+\S+\s+to\s+v?\d|release\s+\d|v?\d+\.\d+\.\d+$)/i.test(title)) p *= 0.45;
+  if (/^(revert|revert:)/i.test(title)) p *= 0.7;
+  if (/^merge (pull request|branch|remote)/i.test(title)) p *= 0.5;
+  return p;
+}
+
+export function rerank(rows, query, opts) {
+  const o = opts || {};
+  const toks = tokenize(query);
+  const now = Date.now() / 1000;
+  const best = rows.reduce(function (m, r) { return Math.min(m, r.rank || 0); }, 0);
+  const scored = rows.map(function (r) {
+    const gap = Math.max(0, (r.rank || 0) - best);
+    let s = 1 / (1 + gap / 3);
+    s *= 0.5 + Math.min(1, r.confidence || 0.2);
+    if (r.is_bot) s *= 0.2;
+    if (r.kind === 'fix') s *= 1.2;
+    if (r.kind === 'chore') s *= 0.7;
+    const title = String(r.title || '').toLowerCase();
+    const rat = String(r.rationale || '').toLowerCase();
+    const paths = String(r.paths || '').toLowerCase();
+    let hit = 0;
+    for (const t of toks) {
+      if (title.includes(t)) { s *= 1.25; hit++; }
+      else if (rat.includes(t)) { s *= 1.15; hit++; }
+      else if (paths.includes(t)) { s *= 1.08; hit++; }
+    }
+    const coverage = toks.length ? hit / toks.length : 0;
+    s *= 0.35 + 0.9 * coverage;
+    if (!r.rationale) s *= 0.75;
+    s *= noisePenalty(r);
+    const age = Math.max(0, (now - (r.ts || now)) / 86400);
+    s *= 0.85 + 0.15 / (1 + age / 900);
+    return Object.assign({}, r, { score: s });
+  });
+  scored.sort(function (a, b) { return b.score - a.score; });
+  const seen = new Set();
+  const out = [];
+  for (const r of scored) {
+    if (seen.has(r.sha)) continue;
+    seen.add(r.sha);
+    out.push(r);
+  }
+  const top = out.length ? out[0].score : 1;
+  for (const r of out) r.match = Math.max(1, Math.round((r.score / (top || 1)) * 100));
+  return out;
+}
+
+export function decisionFor(dbc, sha) {
+  return dbc.prepare('SELECT d.sha, d.ts, d.title, d.rationale, d.paths, d.kind, d.confidence, c.author, c.subject FROM decisions d JOIN commits c ON c.sha = d.sha WHERE d.sha = ?').get(sha) || null;
+}
+
+export function decisionsForPath(dbc, p, limit) {
+  return dbc.prepare('SELECT d.sha, d.ts, d.title, d.rationale, d.paths, d.kind, d.confidence FROM decisions d JOIN commit_files cf ON cf.sha = d.sha WHERE cf.path = ? ORDER BY d.ts DESC LIMIT ?').all(p, limit || 8);
+}
+
+export function recentDecisions(dbc, limit) {
+  return dbc.prepare('SELECT d.sha, d.ts, d.title, d.rationale, d.paths, d.kind, d.confidence, c.author FROM decisions d JOIN commits c ON c.sha = d.sha WHERE c.is_bot = 0 AND d.rationale != \'\' ORDER BY d.ts DESC LIMIT ?').all(limit || 10);
+}
+
+/** Best-of index: highest-confidence, highest-impact decisions. */
+export function topDecisions(dbc, limit) {
+  const rows = dbc.prepare('SELECT d.sha, d.ts, d.title, d.rationale, d.paths, d.kind, d.confidence, c.author, c.added, c.removed, c.files_changed FROM decisions d JOIN commits c ON c.sha = d.sha WHERE c.is_bot = 0').all();
+  const scored = rows.map(function (r) {
+    const churn = Math.log10(2 + (r.added || 0) + (r.removed || 0));
+    const spread = 1 + Math.min(r.files_changed || 1, 20) / 40;
+    let s = (r.confidence || 0) * churn * spread;
+    if (r.kind === 'fix') s *= 1.3;
+    if (r.kind === 'chore') s *= 0.5;
+    if (!r.rationale) s *= 0.55;
+    const years = Math.max(0, (Date.now() / 1000 - (r.ts || 0)) / 31536000);
+    s *= 1 / (1 + years / 10);
+    s *= noisePenalty(r);
+    return Object.assign({}, r, { score: s });
+  });
+  scored.sort(function (a, b) { return b.score - a.score; });
+  return scored.slice(0, limit || 20);
+}
+
+export function openFor(cwd, gd) {
+  return openIndex(gd, { create: false });
+}

package/src/signals.js

@@ -0,0 +1,160 @@
+/** Turn raw commit text into a structured why-decision. */
+
+const BOT_RE = /(\[bot\]|-bot@|^bot$|dependabot|renovate|github-actions|pre-commit-ci|greenkeeper|snyk-bot|imgbot|allcontributors|semantic-release|autofix)/i;
+
+const NOISE_RE = [
+  /^signed-off-by:/i,
+  /^co-authored-by:/i,
+  /^reviewed-by:/i,
+  /^acked-by:/i,
+  /^tested-by:/i,
+  /^change-id:/i,
+  /^bug:/i,
+  /^see also:/i,
+  /^refs?:\s*#?\d+/i,
+  /^fix(?:e[sd])?:?\s*#\d+$/i,
+  /^closes?:?\s*#\d+$/i,
+  /^cc\s+@/i,
+  /^generated by /i,
+  /^this (?:pr|commit|change) was /i,
+  /^\[skip ci\]/i,
+  /^conflicts?:/i,
+  /^-{3,}$/,
+  /^={3,}$/,
+];
+
+const CAUSAL = [
+  /\b(because|since|so that|in order to|to avoid|to prevent|otherwise|which caused|due to|the reason|this ensures|so we|so it|as a result|which means|that way|to make sure|to fix|workaround|root cause|regression|edge case|race condition|memory leak|deadlock|timeout|overflow|deprecated|backwards?[- ]compat)/i,
+  /(因为|由于|所以|因此|导致|避免|防止|否则|为了|兼容|回滚|修复|临时方案|根因|边界情况|竞态|内存泄漏|死锁|超时|溢出|已废弃)/,
+];
+
+const FIX_RE = /\b(fix|fixes|fixed|revert|reverts|hotfix|regression|bug|broken|crash|oops|workaround|patch)\b|修复|回滚|修复|bug/i;
+
+const BULK_RE = /^(bump|update deps|update dependencies|release|chore\(deps\)|version bump|v?\d+\.\d+\.\d+$)/i;
+
+const COMMENT_RE = /^\s*(?:\/\/|#|\/\*|\*|--|;)\s*(?:NOTE|WHY|HACK|IMPORTANT|XXX|WARNING|TODO|FIXME)[:\s-]+(.{8,240})/i;
+
+export function isBot(author, email) {
+  return BOT_RE.test(String(author || '')) || BOT_RE.test(String(email || ''));
+}
+
+export function isTrivial(subject) {
+  return BULK_RE.test(String(subject || '').trim());
+}
+
+export function stripNoise(body) {
+  const lines = String(body || '').split(/\r?\n/);
+  const kept = [];
+  for (const line of lines) {
+    const t = line.trim();
+    if (!t) { kept.push(''); continue; }
+    if (NOISE_RE.some(function (re) { return re.test(t); })) continue;
+    if (/^https?:\/\/\S+$/.test(t)) continue;
+    kept.push(t);
+  }
+  return kept.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+export function splitSentences(text) {
+  const out = [];
+  for (const para of String(text || '').split(/\n\s*\n|\n(?=\s*[-*\d]\s)/)) {
+    const clean = para.replace(/\s+/g, ' ').trim();
+    if (!clean) continue;
+    const parts = clean.split(/(?<=[.!?;])\s+(?=[A-Z0-9])|(?<=[。！？；])/);
+    for (const p of parts) {
+      const s = p.trim();
+      if (s) out.push(s);
+    }
+  }
+  return out;
+}
+
+/** Remove the subject if the body repeats it (squash-merge artefact). */
+export function dedupeSubject(body, subject) {
+  const b = String(body || '').trim();
+  const s = String(subject || '').trim();
+  if (!b || !s) return b;
+  const lines = b.split(/\r?\n/);
+  const first = lines[0].trim();
+  const norm = function (x) { return x.toLowerCase().replace(/[.:;,]+$/, '').trim(); };
+  const a = norm(first);
+  const t = norm(s);
+  if (a === t || (t.length >= 12 && a.startsWith(t.slice(0, 40)))) {
+    return lines.slice(1).join('\n').trim();
+  }
+  return b;
+}
+
+export function scoreSentence(sentence) {
+  const s = String(sentence || '');
+  if (s.length < 25 || s.length > 400) return 0;
+  let score = 0;
+  for (const re of CAUSAL) if (re.test(s)) { score += 3; break; }
+  if (/\b(?:instead of|rather than|previously|used to|before this)\b/i.test(s)) score += 1.2;
+  if (/`[^`]+`|\b[A-Z][A-Za-z0-9]+\.[A-Za-z0-9]+\b/.test(s)) score += 0.6;
+  if (/^[-*]\s/.test(s)) score -= 0.5;
+  if (/^(see|ref|link)\b/i.test(s)) score -= 2;
+  return score;
+}
+
+export function extractRationale(subject, body) {
+  const cleanBody = dedupeSubject(stripNoise(body), subject);
+  const sentences = splitSentences(cleanBody).filter(function (s) { return s.length >= 20; });
+  let best = null;
+  let bestScore = 0;
+  for (const s of sentences) {
+    const sc = scoreSentence(s);
+    if (sc > bestScore) { bestScore = sc; best = s; }
+  }
+  if (best && bestScore >= 1) {
+    const r = trimSentence(best);
+    if (sameText(r, subject)) return { rationale: '', confidence: 0.3, source: 'subject-only' };
+    return { rationale: r, confidence: bestScore >= 3 ? 0.9 : 0.6, source: 'body' };
+  }
+  if (sentences.length) {
+    const r = trimSentence(sentences[0]);
+    if (sameText(r, subject)) return { rationale: '', confidence: 0.3, source: 'subject-only' };
+    return { rationale: r, confidence: 0.4, source: 'body-weak' };
+  }
+  return { rationale: '', confidence: best ? 0.3 : 0.15, source: 'subject-only' };
+}
+
+function sameText(a, b) {
+  const norm = function (x) { return String(x || '').toLowerCase().replace(/[^a-z0-9\u3400-\u9fff]+/g, ' ').trim(); };
+  const x = norm(a);
+  const y = norm(b);
+  if (!x || !y) return false;
+  return x === y || (y.length >= 16 && x.startsWith(y));
+}
+
+export function trimSentence(s) {
+  let t = String(s).trim().replace(/^[-*\d.]+\s+/, '').replace(/\s+/g, ' ');
+  if (t.length > 320) t = t.slice(0, 317).trimEnd() + '...';
+  return t;
+}
+
+/** Mine intent-bearing comments from added lines of a diff. */
+export function mineComments(files) {
+  const found = [];
+  for (const f of files || []) {
+    for (const h of f.hunks || []) {
+      for (const line of h.added || []) {
+        const m = line.match(COMMENT_RE);
+        if (m && m[1]) found.push({ path: f.path, text: trimSentence(m[1]) });
+      }
+    }
+  }
+  return found.slice(0, 5);
+}
+
+export function hasFixWord(text) {
+  return FIX_RE.test(String(text || ''));
+}
+
+export function cleanSubject(subject) {
+  return String(subject || '').replace(/\s+/g, ' ').trim();
+}
+
+export function classify(kind) {
+  return kind || 'change';
+}

package/src/ui.js

@@ -0,0 +1,103 @@
+/** Terminal rendering helpers. */
+import { c, width, padEnd, truncate, wrapText, isoDate, relativeTime, plural, stripAnsi } from './util.js';
+
+export function termWidth() {
+  return Math.max(60, Math.min(100, (process.stdout.columns || 90) - 2));
+}
+
+export function header(title, subtitle) {
+  const w = termWidth();
+  const line = c.gray('\u2500'.repeat(Math.min(w, Math.max(28, width(stripAnsi(title)) + 30))));
+  const parts = [c.bold(title)];
+  if (subtitle) parts.push(c.dim(subtitle));
+  return '\n  ' + parts.join('  ') + '\n  ' + line + '\n';
+}
+
+export function badge(kind) {
+  if (kind === 'fix') return c.red('fix');
+  if (kind === 'chore') return c.gray('chore');
+  if (kind === 'revert') return c.magenta('revert');
+  return c.blue('change');
+}
+
+export function bar(value, max, size) {
+  const n = Math.max(0, Math.min(size || 12, Math.round(((value || 0) / (max || 1)) * (size || 12))));
+  return c.cyan('\u2588'.repeat(n)) + c.gray('\u00b7'.repeat((size || 12) - n));
+}
+
+export function sparkline(values) {
+  const chars = '\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588';
+  const max = Math.max.apply(null, values.concat([1]));
+  return values.map(function (v) { return chars[Math.min(7, Math.round((v / max) * 7))]; }).join('');
+}
+
+/** One decision, rendered for humans. */
+export function renderDecision(d, opts) {
+  const o = opts || {};
+  const w = termWidth();
+  const indent = o.indent == null ? '  ' : o.indent;
+  const lines = [];
+  const num = o.index != null ? c.gray(String(o.index).padStart(2) + '. ') : '';
+  lines.push('');
+  lines.push(indent + num + c.bold(truncate(d.title || '(untitled)', w - 6)));
+  const meta = [];
+  if (d.ts) meta.push(isoDate(d.ts));
+  if (d.sha) meta.push(c.gray(d.sha.slice(0, 8)));
+  if (d.author) meta.push(d.author);
+  if (d.kind) meta.push(badge(d.kind));
+  if (d.match != null) meta.push(c.gray(d.match + '% match'));
+  else if (d.score != null) meta.push(c.gray('score ' + (d.score).toFixed(2)));
+  lines.push(indent + '  ' + meta.join(c.gray(' \u00b7 ')));
+  if (d.rationale) {
+    const body = wrapText(d.rationale, w - 6, indent + '  ');
+    lines.push('');
+    for (const l of body) lines.push(c.white(l));
+  }
+  if (d.paths) {
+    const list = String(d.paths).split(/\s+/).filter(Boolean).slice(0, o.maxPaths || 3);
+    if (list.length) {
+      lines.push('');
+      lines.push(indent + '  ' + c.cyan(list.join('  ')));
+    }
+  }
+  if (o.extra) for (const e of o.extra) lines.push(indent + '  ' + e);
+  return lines.join('\n');
+}
+
+export function renderNote(text, kind) {
+  const w = termWidth();
+  const icon = kind === 'warn' ? c.yellow('!') : kind === 'ok' ? c.green('\u2713') : c.gray('\u00b7');
+  return '  ' + icon + ' ' + wrapText(text, w - 6, '  ').join('\n').trimStart();
+}
+
+export function renderTable(rows, cols, opts) {
+  const o = opts || {};
+  const widths = cols.map(function (col) {
+    return Math.max(col.label.length, ...rows.map(function (r) { return width(String(col.value(r))); }));
+  });
+  const out = [];
+  const head = cols.map(function (col, i) { return padEnd(c.gray(col.label.toUpperCase()), widths[i] + (i ? 2 : 0)); }).join(' ');
+  out.push('  ' + head);
+  out.push('  ' + c.gray('\u2500'.repeat(Math.min(termWidth(), head.length))));
+  for (const r of rows) {
+    const line = cols.map(function (col, i) {
+      const v = String(col.value(r));
+      return padEnd(i === 0 ? truncate(v, widths[i]) : v, widths[i] + (i ? 2 : 0));
+    }).join(' ');
+    out.push('  ' + line);
+  }
+  return out.join('\n');
+}
+
+export function banner() {
+  return [
+    '',
+    '  ' + c.bold(c.cyan('whygit')) + c.gray('  \u2014  git blame tells you who. whygit tells you why.'),
+    '',
+  ].join('\n');
+}
+
+export function kv(pairs) {
+  const w = Math.max.apply(null, pairs.map(function (p) { return p[0].length; }));
+  return pairs.map(function (p) { return '  ' + c.gray(padEnd(p[0], w)) + '  ' + p[1]; }).join('\n');
+}