fapony 0.1.3 → 0.2.0

package/src/debt.ts

@@ -18,18 +18,16 @@
 //
 // Read-only stdout: no file writes, no state.db, no cache (rule 5b).
 
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { collectSourceFiles } from "./analyze.js";
 import { openDb } from "./db/index.js";
-import { type MemRow, readMemLog, resolveAppFaponyDir } from "./memory.js";
+import { readMemLog, resolveMemDir } from "./memory.js";
 
 // 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.
 const DEBT_FILE_CAP = 250;
-// Same cap for the file list printed per convention — a wall is not an answer.
-const LIST_SHOWN = 40;
 
 export interface Convention {
   id: string;
@@ -51,7 +49,10 @@ export interface Convention {
 // --- conventions.json resolution (same guess as the mem log, SPEC §2.1) ---
 
 export function resolveConventionsPath(worktree: string): string | null {
-  const base = resolveAppFaponyDir(worktree);
+  // 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");
   const app = join(base, "conventions.json");
   if (existsSync(app)) return app;
   // Monorepo where the app has not scaffolded .fapony/ yet, and single repos
@@ -295,7 +296,7 @@ export function debtScan(
         // 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 && c.okRe.test(content)) {
+      if (c.okRe?.test(content)) {
         moved.set(c.conv.id, (moved.get(c.conv.id) ?? 0) + 1);
       }
     }
@@ -509,41 +510,99 @@ export function formatPromotions(promotions: Promotion[]): string[] {
 
 // --- Formatting ---
 
-const WRAP_WIDTH = 88;
+// 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.
+const ZONE_DEPTH = 5;
+// Default cap on zones shown per convention — more than this is a wall, not an answer.
+const ZONE_CAP = 6;
+
+/** 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("/") || ".";
+}
 
-function wrapFiles(files: string[]): string[] {
-  const lines: string[] = [];
-  let cur = "";
+/** 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 piece = cur ? `${cur} · ${f}` : f;
-    if (piece.length > WRAP_WIDTH && cur) {
-      lines.push(`  ${cur}`);
-      cur = f;
-    } else {
-      cur = piece;
-    }
+    const zone = zoneOf(f, depth);
+    const cur = zones.get(zone) ?? [];
+    cur.push(f);
+    zones.set(zone, cur);
   }
-  if (cur) lines.push(`  ${cur}`);
-  return lines;
+  // 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): string {
+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 ? ` · moved ${e.movedCount}` : "";
-    lines.push(`\n${e.conv.id} — ${e.conv.rule} (where ${e.conv.where})`);
+    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}:`);
-    lines.push(...wrapFiles(e.files.slice(0, LIST_SHOWN)));
-    if (e.files.length > LIST_SHOWN) {
-      lines.push(`  … +${e.files.length - LIST_SHOWN} more files`);
+    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) {
@@ -565,27 +624,66 @@ export function formatDebt(report: DebtReport): string {
 
 // --- CLI ---
 
-const USAGE = "usage: fapony debt [path] [--files f1,f2] [--json]";
-
-function worktreeOf(arg: string | undefined): string {
+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) return p.stdout.toString().trim();
+    if (p.exitCode === 0) gitRoot = p.stdout.toString().trim() || null;
   } catch {
-    // fall through
+    // 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, ".fapony", "conventions.json"))) return dir;
+    if (boundary && real(dir) === boundary) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
   }
-  return base;
+  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") {
@@ -603,6 +701,24 @@ export function cmdDebt(args: string[]): void {
         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") {
@@ -653,6 +769,25 @@ export function cmdDebt(args: string[]): void {
     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(
@@ -663,7 +798,7 @@ export function cmdDebt(args: string[]): void {
     );
     return;
   }
-  console.log(formatDebt(report));
+  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/digest/collect.ts

@@ -13,6 +13,7 @@ import {
   planDir,
   type Run,
 } from "../db/index.js";
+import { computeHintImpact, type HintImpact, hintLogPath } from "../hook.js";
 import { type MemRow, readMemLog } from "../memory.js";
 import { isPassFamily, VERDICT_GRADES } from "../parse.js";
 import { imputeResult, loadPrices } from "../price/index.js";
@@ -83,6 +84,8 @@ export interface DigestData {
     /** % of those whose earliest in-period gate passed at round ≤ 1. */
     round1_pct: number;
   };
+  /** Hint-fire log counts for this worktree — null when no log exists. */
+  impact: HintImpact | null;
   skipped_malformed: number;
 }
 
@@ -586,6 +589,18 @@ export async function collectDigest(
     detail: verdictResult.detail,
   });
 
+  // 6. hint-fire log — annotate surface, this worktree only. A log that
+  // exists but fired 0 in the window is "0", not "no data" (done criteria 6).
+  const hasHintLog = existsSync(hintLogPath(worktree));
+  const impact = hasHintLog ? computeHintImpact(sinceIso, worktree) : null;
+  sources.push({
+    name: "hint-log",
+    ok: hasHintLog,
+    detail: impact
+      ? `${impact.fired} fired this window (${impact.debt.shown} debt shown)`
+      : "no hints recorded",
+  });
+
   // classify mem rows
   const decisions = mem.rows.filter((r) => r.kind === "decision");
   const notes = mem.rows.filter((r) => r.kind === "note");
@@ -620,6 +635,7 @@ export async function collectDigest(
       units_graded: verdictResult.units_graded,
       round1_pct: verdictResult.round1_pct,
     },
+    impact,
     skipped_malformed: skippedMalformed,
   };
 }

package/src/digest/text.ts

@@ -34,6 +34,23 @@ function fmtTokens(n: number): string {
   return String(Math.round(n));
 }
 
+function impactLines(i: NonNullable<DigestData["impact"]>): string[] {
+  const b = i.by_surface;
+  const out = [
+    `hints fired: ${i.fired} (read ${b.read} · debt ${b.debt} · mem ${b.mem} · commit ${b.commit})`,
+  ];
+  if (i.debt.shown > 0) {
+    const pct = Math.round((i.debt.resolved / i.debt.shown) * 100);
+    out.push(
+      `debt lines shown: ${i.debt.shown} · no longer present at HEAD: ${i.debt.resolved} (${pct}%) · unverifiable: ${i.debt.unknown}`,
+    );
+  }
+  out.push(
+    "note: counts what fapony showed and what the repo looks like now, not proof the agent acted because of the hint",
+  );
+  return out;
+}
+
 function costLine(c: CostRow): string {
   const name = c.provider ? `${c.provider}/${c.model}` : c.model;
   const costStr =
@@ -70,6 +87,14 @@ export function renderDigestText(d: DigestData): string {
   );
   lines.push("");
 
+  // 2b. fapony impact — what the annotate surfaces showed, not proof of use
+  lines.push(
+    section("FAPONY IMPACT", [
+      ...(d.impact ? impactLines(d.impact) : ["(no hints recorded)"]),
+    ]),
+  );
+  lines.push("");
+
   // 3. Decisions
   lines.push(
     section(`DECISIONS (${d.decisions.length})`, [