fapony 0.2.0 → 0.3.0

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/digest/collect.ts

@@ -6,6 +6,7 @@ import { execSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import {
+  CONFIG_FILENAME,
   doneDir,
   type Event,
   loadConfig,
@@ -165,8 +166,8 @@ function readPlans(worktree: string): {
   ok: boolean;
   detail: string;
 } {
-  const config = loadConfig(join(worktree, "fapony.config.json"));
-  const pDir = join(worktree, planDir(config));
+  const config = loadConfig(join(worktree, CONFIG_FILENAME));
+  const pDir = join(worktree, planDir());
   const dDir = join(worktree, doneDir(config));
 
   if (!existsSync(pDir)) {