fapony 0.2.1 → 0.3.3

package/src/debt/promotion.ts

@@ -0,0 +1,152 @@
+// src/debt/promotion.ts — promotion signal: "this recurred N times, time for a checker?"
+//
+// "I'll write eslint when I think of it" — the "think of it" moment is what goes
+// missing (SPEC §3) · fapony sees history across sessions (mem + verdicts), so it
+// can count how often the same thing was fixed, then put the question to a human —
+// it does not decide, does not write the eslint rule itself (SPEC §6 fail list)
+//
+// Matching "the same thing" — only as precise as the data allows (SPEC §7: old rows
+// lack files[], still undecided): a row with files[] must intersect the debt list ·
+// the text must mention a convention symbol (ok such as fmtMoney, or an identifier
+// ≥ 6 chars from stale such as toLocaleString/useMutation — "throw"/"Error" are too
+// short and don't count, to avoid over-matching)
+
+import { openDb } from "../db/index.js";
+import { readMemLog } from "../memory.js";
+import {
+  type Convention,
+  type DebtReport,
+  PROMOTION_MAX,
+  PROMOTION_THRESHOLD,
+  type Promotion,
+  WORD_MIN,
+} from "./types.js";
+
+export type { Promotion };
+
+function conventionWords(conv: Convention): string[] {
+  const words = new Set<string>();
+  for (const src of [conv.ok, conv.stale]) {
+    if (!src) continue;
+    for (const m of src.matchAll(/[A-Za-z_$][\w$]*/g)) {
+      if (m[0].length >= WORD_MIN) words.add(m[0]);
+    }
+  }
+  return [...words];
+}
+
+function rowMatchesConv(
+  hay: string,
+  files: string[] | undefined,
+  debtFiles: Set<string>,
+  words: string[],
+): boolean {
+  if (files && files.length > 0) {
+    if (files.some((f) => debtFiles.has(f))) return true;
+  }
+  const lower = hay.toLowerCase();
+  return words.some((w) => lower.includes(w.toLowerCase()));
+}
+
+interface EvidenceRow {
+  ts: string;
+  files?: string[];
+  hay: string;
+}
+
+function gatherEvidence(worktree: string): EvidenceRow[] {
+  const out: EvidenceRow[] = [];
+  try {
+    for (const r of readMemLog(worktree).rows) {
+      if (r.kind !== "bug" && r.kind !== "decision") continue;
+      out.push({ ts: r.ts, files: r.files, hay: `${r.text}\n${r.spec ?? ""}` });
+    }
+  } catch {
+    // mem missing — verdicts alone still count
+  }
+  try {
+    const db = openDb();
+    const events = db
+      .prepare(
+        `SELECT e.ts AS ts, e.data AS data FROM events e
+         JOIN runs r ON r.id = e.run_id
+         WHERE r.worktree = ? AND e.kind = 'gate' ORDER BY e.id`,
+      )
+      .all(worktree) as { ts: string; data: string | null }[];
+    for (const e of events) {
+      if (!e.data) continue;
+      try {
+        const d = JSON.parse(e.data) as {
+          verdict?: string;
+          reason_code?: string;
+          note?: string;
+          files?: string[];
+        };
+        const countsAsFix =
+          d.verdict === "fail" ||
+          d.reason_code === "scope_mismatch" ||
+          d.reason_code === "spec_gap";
+        if (!countsAsFix) continue;
+        out.push({ ts: e.ts, files: d.files, hay: d.note ?? "" });
+      } catch {}
+    }
+  } catch {
+    // no ledger yet — mem alone still counts
+  }
+  return out;
+}
+
+/** Repeated-fix questions for conventions that have no checker and no "no-checker" decision. */
+export function findPromotions(
+  worktree: string,
+  report: DebtReport,
+): Promotion[] {
+  const evidence = gatherEvidence(worktree);
+  if (evidence.length === 0) return [];
+  const out: Promotion[] = [];
+  for (const entry of report.entries) {
+    const { conv } = entry;
+    if (conv.checker || conv.decided === "no-checker") continue;
+    if (entry.files.length === 0) continue;
+    const debtFiles = new Set(entry.files);
+    const words = conventionWords(conv);
+    const hits = evidence.filter((r) =>
+      rowMatchesConv(r.hay, r.files, debtFiles, words),
+    );
+    if (hits.length < PROMOTION_THRESHOLD) continue;
+    const dates = [...new Set(hits.map((h) => h.ts.slice(0, 10)))].sort();
+    out.push({
+      convId: conv.id,
+      rule: conv.rule,
+      occurrences: hits.length,
+      dates,
+      debtCount: entry.files.length,
+    });
+  }
+  // Newest first, capped — three questions are already a conversation.
+  out.sort((a, b) => b.occurrences - a.occurrences);
+  return out.slice(0, PROMOTION_MAX);
+}
+
+export function formatPromotions(promotions: Promotion[]): string[] {
+  if (promotions.length === 0) return [];
+  const lines: string[] = [
+    "",
+    "promotion — repeated fixes on conventions with no checker:",
+  ];
+  for (const p of promotions) {
+    lines.push(
+      `\n"${p.convId}" (${p.debtCount} file(s) still wrong) came up ${p.occurrences}× ` +
+        `(${p.dates.slice(0, 3).join(", ")}${p.dates.length > 3 ? ", …" : ""})`,
+    );
+    lines.push(`  ${p.rule}`);
+    lines.push(
+      "  [1] make a checker — an agent drafts the eslint rule in this repo, you review",
+    );
+    lines.push(
+      '  [2] one-off, no checker — record "decided": "no-checker" on this entry, never asked again',
+    );
+    lines.push("  [3] later — ask again when this comes up a few more times");
+  }
+  return lines;
+}

package/src/debt/scan.ts

@@ -0,0 +1,214 @@
+// src/debt/scan.ts — the scan (fresh every call — derive, never store).
+//
+// Debt is computed live every time, never written anywhere (same as analyze:
+// a cache is pure debt — a frozen list goes stale silently like MASTER.md).
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { collectSourceFiles } from "../analyze.js";
+import {
+  type Convention,
+  DEBT_FILE_CAP,
+  type DebtEntry,
+  type DebtReport,
+  type LoadedConventions,
+} from "./types.js";
+
+interface Compiled {
+  conv: Convention;
+  staleRe: RegExp | null;
+  okRe: RegExp | null;
+  guardRe: RegExp | null;
+  whereDir: string;
+}
+
+function compile(conv: Convention): { c: Compiled; error?: string } {
+  const re = (
+    src: string | null | undefined,
+    what: string,
+  ): { re: RegExp | null; error?: string } => {
+    if (!src) return { re: null };
+    try {
+      return { re: new RegExp(src) };
+    } catch (e) {
+      return {
+        re: null,
+        error: `${what} regex broken (${e instanceof Error ? e.message.split("\n")[0] : "?"})`,
+      };
+    }
+  };
+  const stale = re(conv.stale, `${conv.id}: stale`);
+  if (stale.error)
+    return {
+      c: {
+        conv,
+        staleRe: null,
+        okRe: null,
+        guardRe: null,
+        whereDir: conv.where,
+      },
+      error: stale.error,
+    };
+  const ok = re(conv.ok, `${conv.id}: ok`);
+  if (ok.error)
+    return {
+      c: {
+        conv,
+        staleRe: null,
+        okRe: null,
+        guardRe: null,
+        whereDir: conv.where,
+      },
+      error: ok.error,
+    };
+  const guard = re(conv.guard, `${conv.id}: guard`);
+  if (guard.error)
+    return {
+      c: {
+        conv,
+        staleRe: null,
+        okRe: null,
+        guardRe: null,
+        whereDir: conv.where,
+      },
+      error: guard.error,
+    };
+  return {
+    c: {
+      conv,
+      staleRe: stale.re,
+      okRe: ok.re,
+      guardRe: guard.re,
+      // where="src" must scope src/ and src/x/y.ts but not src-other/;
+      // where="." scopes everything.
+      whereDir: conv.where === "." ? "" : conv.where.replace(/\/+$/, ""),
+    },
+  };
+}
+
+function inScope(whereDir: string, file: string): boolean {
+  return whereDir === "" || file.startsWith(`${whereDir}/`);
+}
+
+export function debtScan(
+  worktree: string,
+  loaded: LoadedConventions,
+): DebtReport {
+  const t0 = performance.now();
+  const entries: DebtEntry[] = [];
+  const declared: Convention[] = [];
+  const dropped: { id: string; reason: string }[] = [];
+  let checkedCount = 0;
+
+  const compiled: Compiled[] = [];
+  for (const conv of loaded.convs) {
+    if (conv.checker) {
+      // Iron rule — fapony stays silent, leave it to the checker (SPEC §2)
+      checkedCount++;
+      continue;
+    }
+    if (!conv.stale) {
+      // The one slot a human fills (SPEC §2.2) — show it as pending, don't guess
+      declared.push(conv);
+      continue;
+    }
+    const { c, error } = compile(conv);
+    if (error || !c.staleRe) {
+      dropped.push({ id: conv.id, reason: error ?? "uncompilable" });
+      continue;
+    }
+    if (!existsSync(join(worktree, c.whereDir || "."))) {
+      dropped.push({
+        id: conv.id,
+        reason: `where: ${conv.where} does not exist`,
+      });
+      continue;
+    }
+    compiled.push(c);
+  }
+
+  const files = collectSourceFiles(worktree);
+  const debt: Map<string, string[]> = new Map(
+    compiled.map((c) => [c.conv.id, []]),
+  );
+  const moved: Map<string, number> = new Map(
+    compiled.map((c) => [c.conv.id, 0]),
+  );
+  const tooBroad: Map<string, number> = new Map();
+
+  for (const rel of files) {
+    let content: string;
+    try {
+      content = readFileSync(join(worktree, rel), "utf-8");
+    } catch {
+      continue;
+    }
+    for (const c of compiled) {
+      if (!c.staleRe) continue; // filtered at compile; narrows the type
+      if (!inScope(c.whereDir, rel)) continue;
+      if (c.guardRe && !c.guardRe.test(content)) continue;
+      if (c.staleRe.test(content)) {
+        const cur = debt.get(c.conv.id) ?? [];
+        cur.push(rel);
+        debt.set(c.conv.id, cur);
+        // Stop counting a runaway regex early — the entry will be dropped.
+        if (cur.length > DEBT_FILE_CAP) tooBroad.set(c.conv.id, cur.length);
+      }
+      if (c.okRe?.test(content)) {
+        moved.set(c.conv.id, (moved.get(c.conv.id) ?? 0) + 1);
+      }
+    }
+  }
+
+  for (const c of compiled) {
+    const n = tooBroad.get(c.conv.id);
+    if (n !== undefined) {
+      dropped.push({
+        id: c.conv.id,
+        reason: `stale regex matches ${n}+ files — too broad, entry dropped (narrow stale/where/guard)`,
+      });
+      continue;
+    }
+    entries.push({
+      conv: c.conv,
+      files: (debt.get(c.conv.id) ?? []).sort(),
+      movedCount: c.okRe ? (moved.get(c.conv.id) ?? 0) : null,
+    });
+  }
+
+  return {
+    worktree,
+    scannedFiles: files.length,
+    ms: Math.round(performance.now() - t0),
+    entries,
+    declared,
+    dropped,
+    checkedCount,
+  };
+}
+
+/** Per-file lookup (hook-read-hint + --files): which conventions flag this file. */
+export function debtForFile(
+  worktree: string,
+  absFile: string,
+  loaded: LoadedConventions,
+): Convention[] {
+  const rel = relative(worktree, absFile).split("\\").join("/");
+  if (rel.startsWith("..") || isAbsolute(rel)) return [];
+  let content: string;
+  try {
+    content = readFileSync(absFile, "utf-8");
+  } catch {
+    return [];
+  }
+  const out: Convention[] = [];
+  for (const conv of loaded.convs) {
+    if (conv.checker || !conv.stale) continue;
+    const { c, error } = compile(conv);
+    if (error || !c.staleRe) continue;
+    if (!inScope(c.whereDir, rel)) continue;
+    if (c.guardRe && !c.guardRe.test(content)) continue;
+    if (c.staleRe.test(content)) out.push(conv);
+  }
+  return out;
+}

package/src/debt/types.ts

@@ -0,0 +1,79 @@
+// src/debt/types.ts — shared types + caps for `fapony debt`.
+//
+// One convention = pattern to use (ok) + pattern meaning not-yet-migrated
+// (stale) + scope (where) + file condition (guard). Iron rule: checker not
+// null = fapony never reports that debt item — reporting twice with eslint
+// is an abstraction with one implementation (rule 1).
+
+export interface Convention {
+  id: string;
+  rule: string;
+  /** Repo-relative dir scope ("." = whole repo). */
+  where: string;
+  /** Regex source: a match means the file still has the debt. null = not derivable (checker rows) or not filled in yet. */
+  stale: string | null;
+  /** Regex source: files that already moved (informational count). */
+  ok?: string;
+  /** Regex source a file must ALSO match to be in scope (e.g. "extends Base"). */
+  guard?: string;
+  /** Non-null = a checker (eslint rule / script) exists → fapony never reports this debt. */
+  checker?: string | null;
+  /** Human answered "no checker" on the promotion question — never ask again. */
+  decided?: "no-checker" | null;
+}
+
+export interface LoadedConventions {
+  path: string | null;
+  convs: Convention[];
+  /** Rows kept for display but not scannable, plus invalid rows — said out loud, never silent. */
+  warnings: string[];
+}
+
+export interface DebtEntry {
+  conv: Convention;
+  /** Files with the debt (stale match), sorted. */
+  files: string[];
+  /** Files that already moved (ok match) — null when ok is not set. */
+  movedCount: number | null;
+}
+
+export interface DebtReport {
+  worktree: string;
+  scannedFiles: number;
+  ms: number;
+  /** Scannable conventions with their debt list (checker rows never land here). */
+  entries: DebtEntry[];
+  /** Declared but not fillable by fapony: checker null + no stale — the human/agent fills `stale`. */
+  declared: Convention[];
+  /** Skipped-with-reason: checker rows are silent by design (not dropped), these are real drops. */
+  dropped: { id: string; reason: string }[];
+  /** Silent-by-design count: checker non-null — reported as a number, not a list. */
+  checkedCount: number;
+}
+
+export interface Promotion {
+  convId: string;
+  rule: string;
+  occurrences: number;
+  dates: string[];
+  debtCount: number;
+}
+
+// A stale regex matching more than this many files is not a convention — it is
+// a broken/wide regex (stale="e" would flag the repo). SPEC §6: drop the entry
+// and say so, never report 600 files.
+export const DEBT_FILE_CAP = 250;
+
+export const PROMOTION_THRESHOLD = 3;
+export const PROMOTION_MAX = 3;
+/** Identifiers shorter than this are too generic to match prose on ("throw", "Error"). */
+export const WORD_MIN = 6;
+
+// Zone grouping: a zone is a file's *directory*, capped at this many leading
+// segments — never a fixed-depth prefix of the path (which would cut into the
+// filename) and never the filename itself. SPEC §4 shows zones at depth 5
+// (`apps/mdl/src/server/services`) and depth 3 (`packages/cache/src`) in the
+// same report, so the cap must follow the directory, not a constant.
+export const ZONE_DEPTH = 5;
+// Default cap on zones shown per convention — more than this is a wall, not an answer.
+export const ZONE_CAP = 6;

package/src/detect.ts

@@ -0,0 +1,92 @@
+// src/detect.ts — read a repo's package.json to detect its test runner.
+//
+// The Stop hook fires in every repo but used to hardcode fapony-specific
+// commands in its block message (bug class: setup.ts, hook.ts). Now the message
+// derives the command from the worktree at runtime — one source of truth, reused
+// by the hook (decideStop) and by install (what it reports).
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type TestRunner = "bun" | "npm" | "pnpm" | "yarn";
+
+export interface TestRunnerInfo {
+  runner: TestRunner;
+  testCmd: string;
+  typecheckCmd: string | null;
+  lockfile: string;
+}
+
+const RUNNER_LOCKFILE: Record<TestRunner, string> = {
+  bun: "bun.lock",
+  npm: "package-lock.json",
+  pnpm: "pnpm-lock.yaml",
+  yarn: "yarn.lock",
+};
+
+const RUNNER_TEST_CMD: Record<TestRunner, string> = {
+  bun: "bun test",
+  npm: "npm test",
+  pnpm: "pnpm test",
+  yarn: "yarn test",
+};
+
+const RUNNER_TYPECHECK_CMD: Record<TestRunner, string> = {
+  bun: "bun run typecheck",
+  npm: "npm run typecheck",
+  pnpm: "pnpm run typecheck",
+  yarn: "yarn run typecheck",
+};
+
+/**
+ * Detect a repo's test runner from its package.json + lockfile.
+ * Returns null when the worktree has no package.json or no recognizable runner.
+ *
+ * Priority: `packageManager` field (explicit) → lockfile presence (fallback).
+ * A repo with neither is foreign to us — the caller falls back to a generic
+ * "this repo's test suite" message rather than guessing.
+ */
+export function detectTestRunner(worktree: string): TestRunnerInfo | null {
+  const pkgPath = join(worktree, "package.json");
+  if (!existsSync(pkgPath)) return null;
+
+  let pkg: { packageManager?: string; scripts?: Record<string, string> };
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  } catch {
+    return null;
+  }
+
+  const runner = detectRunner(worktree, pkg);
+  if (!runner) return null;
+
+  const scripts = pkg.scripts ?? {};
+  const typecheckCmd =
+    "typecheck" in scripts ? RUNNER_TYPECHECK_CMD[runner] : null;
+
+  return {
+    runner,
+    testCmd: RUNNER_TEST_CMD[runner],
+    typecheckCmd,
+    lockfile: RUNNER_LOCKFILE[runner],
+  };
+}
+
+function detectRunner(
+  worktree: string,
+  pkg: { packageManager?: string },
+): TestRunner | null {
+  const pm = pkg.packageManager;
+  if (typeof pm === "string") {
+    if (pm.startsWith("bun@")) return "bun";
+    if (pm.startsWith("pnpm@")) return "pnpm";
+    if (pm.startsWith("yarn@")) return "yarn";
+    if (pm.startsWith("npm@")) return "npm";
+  }
+  if (existsSync(join(worktree, "bun.lock"))) return "bun";
+  if (existsSync(join(worktree, "bun.lockb"))) return "bun";
+  if (existsSync(join(worktree, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(worktree, "yarn.lock"))) return "yarn";
+  if (existsSync(join(worktree, "package-lock.json"))) return "npm";
+  return null;
+}

package/src/gate.ts

@@ -1,6 +1,6 @@
-// gateOnce is the core review-verdict logic — still live, called by the MCP
-// verdict_submit tool (src/mcp/tools/verdict.ts). The CLI wrapper (cmdGate)
-// was removed with the rest of the execute→review→fix loop (Wave 2).
+// gateOnce is the core review-verdict logic — still live, called by the CLI
+// wrapper (cmdGate) was removed with the rest of the execute→review→fix loop
+// (Wave 2). The MCP verdict_submit tool was removed in PLAN-verdict-to-mem.
 import {
   addEvent,
   getRun,