fapony 0.2.0 → 0.3.0

package/src/db/types.ts

@@ -55,9 +55,7 @@ export interface Config {
     // state dir override (default: $XDG_CONFIG_HOME/fapony or ~/.config/fapony).
     // $FAPONY_STATE_DIR env wins over this when set.
     stateDir?: string;
-    // plan/spec/memory layout inside each worktree (relative to worktree root).
-    planDir?: string;
-    specDir?: string;
+    // plan/spec live in .fapony/{plan,spec} — not configurable (gitignored = private).
     doneDir?: string;
     memDir?: string;
     evidenceFile?: string;

package/src/debt/cli.ts

@@ -0,0 +1,193 @@
+// src/debt/cli.ts — `fapony debt` CLI: arg parsing + worktree resolution.
+//
+// Read-only stdout: no file writes, no state.db, no cache (rule 5b).
+
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { CONVENTIONS_FILE } from "../db/defaults.js";
+import { formatDebt } from "./format.js";
+import { loadConventions } from "./load.js";
+import { findPromotions, formatPromotions } from "./promotion.js";
+import { debtForFile, debtScan } from "./scan.js";
+import { ZONE_CAP } from "./types.js";
+
+const USAGE = `usage: fapony debt [path] [options]
+  --files f1,f2     check specific files instead of scanning
+  --id <conv>       show only this convention
+  --where <path>    narrow scope to files under this path
+  --all             show all zones (default: cap at ${ZONE_CAP})
+  --json            output raw JSON
+  -h, --help        this help`;
+
+/**
+ * The dir `debt` measures: the nearest ancestor of `arg` (or cwd) that holds
+ * `.fapony/conventions.json`, bounded by the git root.
+ *
+ * Jumping straight to the git root was the bug: in a monorepo the root has no
+ * conventions.json and two apps have one each, so the mem resolver went
+ * ambiguous and `debt` said "nothing tracked yet" while
+ * apps/<x>/.fapony/conventions.json sat right there — and the positional path
+ * argument was silently ignored. Falling back to the git root keeps single
+ * repos run from a subdir scanning the whole repo.
+ */
+export function worktreeOf(arg: string | undefined): string {
+  const base = resolve(arg ?? ".");
+  let gitRoot: string | null = null;
+  try {
+    const p = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+      cwd: base,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (p.exitCode === 0) gitRoot = p.stdout.toString().trim() || null;
+  } catch {
+    // not a repo — base is all we have
+  }
+  // `git rev-parse` returns a physical path (/var → /private/var on macOS),
+  // so the boundary check compares realpaths, same as the mem resolver.
+  const real = (d: string): string => {
+    try {
+      return realpathSync(d);
+    } catch {
+      return d;
+    }
+  };
+  const boundary = gitRoot ? real(gitRoot) : null;
+  let dir = base;
+  while (true) {
+    if (existsSync(join(dir, CONVENTIONS_FILE))) return dir;
+    if (boundary && real(dir) === boundary) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return gitRoot ?? base;
+}
+
+export function cmdDebt(args: string[]): void {
+  let path: string | undefined;
+  let filesMode: string[] | null = null;
+  let json = false;
+  let filterId: string | undefined;
+  let wherePath: string | undefined;
+  let showAll = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--files") {
+      const v = args[i + 1];
+      if (!v || v.startsWith("--")) {
+        console.error(`fapony debt: --files needs a value\n${USAGE}`);
+        process.exit(1);
+      }
+      i++;
+      filesMode = v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (filesMode.length === 0) {
+        console.error(`fapony debt: --files needs at least one path\n${USAGE}`);
+        process.exit(1);
+      }
+    } else if (a === "--id") {
+      const v = args[i + 1];
+      if (!v || v.startsWith("--")) {
+        console.error(`fapony debt: --id needs a convention id\n${USAGE}`);
+        process.exit(1);
+      }
+      i++;
+      filterId = v;
+    } else if (a === "--where") {
+      const v = args[i + 1];
+      if (!v || v.startsWith("--")) {
+        console.error(`fapony debt: --where needs a path\n${USAGE}`);
+        process.exit(1);
+      }
+      i++;
+      wherePath = v;
+    } else if (a === "--all") {
+      showAll = true;
+    } else if (a === "--json") {
+      json = true;
+    } else if (a === "-h" || a === "--help") {
+      console.log(USAGE);
+      return;
+    } else if (!a.startsWith("--")) {
+      path = a;
+    } else {
+      console.error(`fapony debt: unknown argument "${a}"\n${USAGE}`);
+      process.exit(1);
+    }
+  }
+
+  const worktree = worktreeOf(path);
+  const loaded = loadConventions(worktree);
+
+  if (filesMode) {
+    const out = filesMode.map((f) => {
+      const abs = isAbsolute(f) ? f : resolve(worktree, f);
+      if (!existsSync(abs) || !statSync(abs).isFile()) {
+        return { file: f, debt: [], note: "not found" as const };
+      }
+      return { file: f, debt: debtForFile(worktree, abs, loaded) };
+    });
+    if (json) {
+      console.log(JSON.stringify({ worktree, files: out }, null, 2));
+      return;
+    }
+    let any = false;
+    for (const r of out) {
+      for (const c of r.debt) {
+        any = true;
+        console.log(`${r.file} — ${c.id}: ${c.rule}`);
+      }
+      if ("note" in r) console.log(`${r.file} — ${r.note}`);
+    }
+    if (!any && out.every((r) => r.debt.length === 0)) {
+      console.log("no convention debt in the given file(s)");
+    }
+    return;
+  }
+
+  if (loaded.path === null) {
+    // SPEC §6: no conventions.json = completely silent, no error, no prompt to create one
+    console.log(
+      `fapony debt — no conventions.json in ${worktree} (nothing tracked yet)`,
+    );
+    return;
+  }
+  const report = debtScan(worktree, loaded);
+
+  // --id filter: keep only the named convention
+  if (filterId) {
+    report.entries = report.entries.filter((e) => e.conv.id === filterId);
+    report.declared = report.declared.filter((c) => c.id === filterId);
+    report.checkedCount = 0; // not relevant when filtering
+    report.dropped = report.dropped.filter((d) => d.id === filterId);
+  }
+
+  // --where filter: narrow file lists to paths under the given prefix
+  if (wherePath) {
+    const prefix = wherePath.replace(/\/+$/, "");
+    for (const e of report.entries) {
+      e.files = e.files.filter(
+        (f) => f === prefix || f.startsWith(`${prefix}/`),
+      );
+    }
+  }
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { ...report, promotions: findPromotions(worktree, report) },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+  console.log(formatDebt(report, showAll));
+  for (const w of loaded.warnings) console.log(`⚠ ${w}`);
+  for (const l of formatPromotions(findPromotions(worktree, report))) {
+    console.log(l);
+  }
+}

package/src/debt/format.ts

@@ -0,0 +1,107 @@
+// src/debt/format.ts — report rendering: zone grouping + text output.
+
+import { dirname } from "node:path";
+import { type DebtReport, ZONE_CAP, ZONE_DEPTH } from "./types.js";
+
+/** The zone of a file: its directory path, capped at `depth` segments. */
+function zoneOf(file: string, depth: number): string {
+  const parts = dirname(file)
+    .split("/")
+    .filter((p) => p && p !== ".");
+  return parts.slice(0, depth).join("/") || ".";
+}
+
+/** Group files by their directory zone (see `zoneOf`). */
+function groupFilesByZone(
+  files: string[],
+  depth: number,
+): Map<string, string[]> {
+  const zones = new Map<string, string[]>();
+  for (const f of files) {
+    const zone = zoneOf(f, depth);
+    const cur = zones.get(zone) ?? [];
+    cur.push(f);
+    zones.set(zone, cur);
+  }
+  // Sort zones by file count descending, then alphabetically
+  return new Map(
+    [...zones.entries()].sort((a, b) => {
+      const d = b[1].length - a[1].length;
+      return d !== 0 ? d : a[0].localeCompare(b[0]);
+    }),
+  );
+}
+
+/** Escape a regex source for use in a shell grep command. */
+function shellEscapeRe(src: string): string {
+  return src.replace(/'/g, "'\\''");
+}
+
+export function formatDebt(report: DebtReport, showAll = false): string {
+  const lines: string[] = [];
+  lines.push(
+    `fapony debt — ${report.entries.length + report.declared.length + report.checkedCount} convention(s), ` +
+      `${report.scannedFiles} files scanned, ${report.ms}ms — derived fresh, not stored`,
+  );
+  for (const e of report.entries) {
+    const moved =
+      e.movedCount !== null && e.files.length > 0
+        ? ` · moved ${e.movedCount} (${Math.round((e.movedCount / (e.files.length + e.movedCount)) * 100)}%)`
+        : e.movedCount !== null
+          ? ` · moved ${e.movedCount}`
+          : "";
+    lines.push(`\n${e.conv.id} — ${e.conv.rule}`);
+    // Show the patterns actually used
+    const patterns: string[] = [];
+    if (e.conv.stale) patterns.push(`stale: ${e.conv.stale}`);
+    if (e.conv.ok) patterns.push(`ok: ${e.conv.ok}`);
+    if (e.conv.guard) patterns.push(`guard: ${e.conv.guard}`);
+    patterns.push(`where ${e.conv.where}`);
+    lines.push(`  ${patterns.join("  ·  ")}`);
+    if (e.files.length === 0) {
+      lines.push(`  debt 0${moved} — clean`);
+      continue;
+    }
+    lines.push(`  debt ${e.files.length}${moved}`);
+    // Verify command derived from stale
+    if (e.conv.stale) {
+      lines.push(`  verify: grep -rn '${shellEscapeRe(e.conv.stale)}' <zone>`);
+    }
+    // Zone grouping
+    const zones = groupFilesByZone(e.files, ZONE_DEPTH);
+    const zoneEntries = [...zones.entries()];
+    const cap = showAll
+      ? zoneEntries.length
+      : Math.min(zoneEntries.length, ZONE_CAP);
+    let totalCapped = 0;
+    for (let i = 0; i < cap; i++) {
+      const [zone, zoneFiles] = zoneEntries[i];
+      const pad = " ".repeat(Math.max(0, 42 - zone.length));
+      lines.push(`\n  ${zone}${pad}${zoneFiles.length} ไฟล์`);
+      lines.push(`    ${zoneFiles.map((f) => f.split("/").pop()).join(" · ")}`);
+      totalCapped += zoneFiles.length;
+    }
+    if (zoneEntries.length > cap) {
+      const remaining = e.files.length - totalCapped;
+      const remainingZones = zoneEntries.length - cap;
+      lines.push(
+        `\n  … อีก ${remainingZones} โซน (${remaining} ไฟล์) — fapony debt --id ${e.conv.id} --all`,
+      );
+    }
+  }
+  for (const c of report.declared) {
+    lines.push(`\n${c.id} — ${c.rule} (where ${c.where})`);
+    lines.push(
+      `  declared, no checker, stale not filled in — fill "stale" in conventions.json`,
+    );
+  }
+  if (report.checkedCount > 0) {
+    lines.push(
+      `\n${report.checkedCount} convention(s) have a checker — fapony stays silent, the checker reports`,
+    );
+  }
+  for (const d of report.dropped) {
+    lines.push(`⚠ ${d.id}: ${d.reason}`);
+  }
+  return lines.join("\n");
+}

package/src/debt/index.ts

@@ -0,0 +1,19 @@
+// src/debt/index.ts — barrel for `fapony debt`: which files have not moved
+// to a shipped convention yet.
+//
+// The question nobody can answer: "which files have not moved" — rules files
+// (CLAUDE.md, Cursor rules) can only say "what the rule is" (layer 2) and
+// "which files were copied" (layer 1) — where the debt is (layer 3) lives in
+// the owner's head and vanishes when forgotten (SPEC-convention-debt §1)
+//
+// The convention definition lives in the measured repo — fapony does not know
+// React or Hono and must not. Layout mirrors src/mcp/: types + one file per
+// concern, CLI entry in cli.ts (fapony.ts imports that directly, same as
+// digest/cli.ts).
+
+export * from "./cli.js";
+export * from "./format.js";
+export * from "./load.js";
+export * from "./promotion.js";
+export * from "./scan.js";
+export * from "./types.js";

package/src/debt/load.ts

@@ -0,0 +1,92 @@
+// src/debt/load.ts — conventions.json resolution + parsing.
+//
+// The convention definition lives in the measured repo
+// (<repo>/.fapony/conventions.json — via the same resolver as the mem log).
+// Missing file = empty + no error.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  CONVENTIONS_FILE,
+  CONVENTIONS_FILENAME,
+  FAPONY_DIR,
+} from "../db/defaults.js";
+import { resolveMemDir } from "../memory.js";
+import type { Convention, LoadedConventions } from "./types.js";
+
+export function resolveConventionsPath(worktree: string): string | null {
+  // Conventions live in the same .fapony/ dir as the mem log — derive from
+  // the resolved mem dir so both resolvers cannot drift apart.
+  const memDir = resolveMemDir(worktree);
+  const base = memDir ? join(memDir, "..") : join(worktree, FAPONY_DIR);
+  const app = join(base, CONVENTIONS_FILENAME);
+  if (existsSync(app)) return app;
+  // Monorepo where the app has not scaffolded .fapony/ yet, and single repos
+  // that ran `fapony init` at the root — the root file still scopes fine
+  // because every `where` is repo-relative.
+  const root = join(worktree, CONVENTIONS_FILE);
+  return existsSync(root) ? root : null;
+}
+
+function asString(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/** Parses .fapony/conventions.json. Missing file = empty + no error (SPEC §6). */
+export function loadConventions(worktree: string): LoadedConventions {
+  const path = resolveConventionsPath(worktree);
+  if (!path) return { path: null, convs: [], warnings: [] };
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return {
+      path,
+      convs: [],
+      warnings: [`conventions.json unreadable: ${path}`],
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return {
+      path,
+      convs: [],
+      warnings: [
+        `conventions.json is not valid JSON — ${
+          e instanceof Error ? e.message.split("\n")[0] : "parse error"
+        }`,
+      ],
+    };
+  }
+  const rows: unknown[] = Array.isArray(parsed)
+    ? parsed
+    : Array.isArray((parsed as { conventions?: unknown }).conventions)
+      ? (parsed as { conventions: unknown[] }).conventions
+      : [];
+  const convs: Convention[] = [];
+  const warnings: string[] = [];
+  rows.forEach((r, i) => {
+    const o = r as Record<string, unknown>;
+    const id = asString(o.id);
+    const rule = asString(o.rule);
+    if (!id || !rule) {
+      warnings.push(
+        `conventions[${i}]: id and rule are required — row dropped`,
+      );
+      return;
+    }
+    convs.push({
+      id,
+      rule,
+      where: asString(o.where) ?? ".",
+      stale: asString(o.stale) ?? null,
+      ok: asString(o.ok),
+      guard: asString(o.guard),
+      checker: asString(o.checker) ?? null,
+      decided: o.decided === "no-checker" ? "no-checker" : null,
+    });
+  });
+  return { path, convs, warnings };
+}

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;
+}