fapony 0.1.3 → 0.2.0

package/src/hook.ts

@@ -16,14 +16,192 @@
 //   cursor  {workspace_roots, conversation_id, loop_count, status} → {"followup_message"}
 //   (cursor: loop_count ≥ 1 = the hook already fired, status ≠ completed = allow)
 
-import { readFileSync, realpathSync, statSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
 import { homedir } from "node:os";
-import { basename, join, relative } from "node:path";
+import { basename, join, relative, resolve } from "node:path";
 import { collectSourceFiles, SCAN_EXTS } from "./analyze.js";
 import { openDb } from "./db/index.js";
 import { debtForFile, loadConventions } from "./debt.js";
 import { readMemLog } from "./memory.js";
 
+// --- Hint-fire log (PLAN-feedback-surface chunk 1) ---
+//
+// Append-only JSONL under state dir (<faponyDir>/hint-log/<key>.jsonl),
+// one file per worktree. Best-effort: every error swallowed — a hook that
+// cannot log must still annotate. Called at caller only (cmdHookReadHint +
+// opencode plugins), never inside readHintFor/readContextLines/commitHintFor
+// (test pollution: those functions are called ~20x in test/hook.test.ts
+// without setting FAPONY_STATE_DIR).
+
+const HINT_LOG_DIR = "hint-log";
+
+/** Stable filename key from an absolute worktree path. */
+export function worktreeKey(worktree: string): string {
+  return worktree.replace(/^\/+/, "").replace(/\//g, "--");
+}
+
+/** Directory holding one hint-fire log file per worktree. */
+function hintLogDir(): string {
+  const base =
+    process.env.FAPONY_STATE_DIR || join(homedir(), ".config", "fapony");
+  return join(base, HINT_LOG_DIR);
+}
+
+/** Absolute path of a worktree's hint-fire log — may not exist. */
+export function hintLogPath(worktree: string): string {
+  return join(hintLogDir(), `${worktreeKey(worktree)}.jsonl`);
+}
+
+export interface HintFireRow {
+  ts: string;
+  worktree: string;
+  surface: "read" | "debt" | "mem" | "commit";
+  file: string | null;
+  count: number;
+  ids?: string[];
+}
+
+/**
+ * Append a hint-fire log row. Best-effort: never throws, never blocks.
+ * Uses $FAPONY_STATE_DIR when set (tests, CI), otherwise ~/.config/fapony.
+ */
+export function recordHintFire(row: HintFireRow): void {
+  try {
+    const dir = hintLogDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    appendFileSync(
+      hintLogPath(row.worktree),
+      `${JSON.stringify(row)}\n`,
+      "utf-8",
+    );
+  } catch {
+    // best-effort — swallow
+  }
+}
+
+// --- Debt precision (PLAN-feedback-surface chunk 2) ---
+//
+// Reads the hint-fire log, re-runs debtForFile at HEAD for each file that
+// received debt hints, and counts which ids are no longer flagged. This is
+// deterministic (no proxy, no join with events) and answers: of the debt
+// lines fapony showed, how many is the repo now clean of?
+
+export interface HintImpact {
+  fired: number;
+  by_surface: { read: number; debt: number; mem: number; commit: number };
+  debt: { shown: number; resolved: number; unknown: number };
+  window: string | null;
+}
+
+/**
+ * Compute hint-fire impact from the log. `since` is an ISO date string;
+ * omit to scan all rows. `worktree` scopes to one project's log file (the
+ * `<key>.jsonl` naming makes this a filename comparison) — omit to merge
+ * every worktree. Returns zeroed counts (not null) when there are no rows —
+ * the caller decides how to present "no data" vs "zero".
+ */
+export function computeHintImpact(
+  since?: string,
+  worktree?: string,
+): HintImpact {
+  const dir = hintLogDir();
+  const impact: HintImpact = {
+    fired: 0,
+    by_surface: { read: 0, debt: 0, mem: 0, commit: 0 },
+    debt: { shown: 0, resolved: 0, unknown: 0 },
+    window: since ?? null,
+  };
+
+  if (!existsSync(dir)) return impact;
+
+  // Read the worktree's .jsonl when scoped, else every file in the dir.
+  let files: string[];
+  try {
+    const all = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+    files = worktree
+      ? all.filter((f) => f === `${worktreeKey(worktree)}.jsonl`)
+      : all;
+  } catch {
+    return impact;
+  }
+
+  // debtShown: Map<"worktree\tfile\tid", true> — unique debt ids per file.
+  const debtShown = new Map<string, true>();
+  // debtByFile: Map<"worktree\tfile", string[]> — all ids shown per file.
+  const debtByFile = new Map<string, string[]>();
+
+  for (const file of files) {
+    let content: string;
+    try {
+      content = readFileSync(join(dir, file), "utf-8");
+    } catch {
+      continue;
+    }
+    for (const line of content.split("\n")) {
+      if (!line) continue;
+      let row: HintFireRow;
+      try {
+        row = JSON.parse(line) as HintFireRow;
+      } catch {
+        continue;
+      }
+      if (since && row.ts < since) continue;
+      impact.fired++;
+      impact.by_surface[row.surface]++;
+
+      if (row.surface === "debt" && row.ids && row.file) {
+        const key = `${row.worktree}\t${row.file}`;
+        const existing = debtByFile.get(key) ?? [];
+        for (const id of row.ids) {
+          const dk = `${row.worktree}\t${row.file}\t${id}`;
+          if (!debtShown.has(dk)) {
+            debtShown.set(dk, true);
+            existing.push(id);
+          }
+        }
+        debtByFile.set(key, existing);
+      }
+    }
+  }
+
+  // Re-run debtForFile at HEAD for each file that had debt hints.
+  for (const [key, ids] of debtByFile) {
+    const [worktree, file] = key.split("\t");
+    const absFile = join(worktree, file);
+    let currentIds: Set<string>;
+    try {
+      if (!statSync(absFile).isFile()) {
+        // File deleted — all its debt ids are unknown.
+        impact.debt.unknown += ids.length;
+        continue;
+      }
+      const convs = debtForFile(worktree, absFile, loadConventions(worktree));
+      currentIds = new Set(convs.map((c) => c.id));
+    } catch {
+      impact.debt.unknown += ids.length;
+      continue;
+    }
+    for (const id of ids) {
+      impact.debt.shown++;
+      if (currentIds.has(id)) {
+        // still present — not resolved
+      } else {
+        impact.debt.resolved++;
+      }
+    }
+  }
+
+  return impact;
+}
+
 export interface RawStopPayload {
   // Claude Code
   cwd?: string;
@@ -319,6 +497,142 @@ export function readHintFor(opts: ReadHintInput): string | null {
   }
 }
 
+// --- Re-read tracking (mtime heuristic — annotate only) ---
+//
+// The size hint above fires on almost nothing real: measured 2026-09-20 over
+// 28,151 read parts across every project, only 2.3% had fileSize>=24KB with a
+// full bound, while 55.5% of read context came from files under 24KB and 19.5%
+// from re-reading a path already read this session (39.2% of context sits in
+// (session,path) pairs read >=2x). The cost is repetition, not one big file —
+// so the gate here is not size, it is "same file, unchanged, again".
+//
+// mtime is the whole mechanism: unchanged mtime since the previous read in
+// this session = the same bytes = annotate; mtime moved = someone edited it =
+// new content = silent. No Edit/Grep tracking — mtime already answers "did it
+// change", so no tool-sequence tagging is needed.
+//
+// Log lives beside hint-log but is separate — hint-log counts fires, this
+// records reads keyed by session (one file per session, so a hint never leaks
+// into the next session / rule 11). Same contract as the size hint: annotate
+// only, never block, every unknown → silent, best-effort. Called at the caller
+// only, never inside a pure function (test pollution — same reason
+// recordHintFire is caller-side).
+
+const READ_TRACK_DIR = "read-track";
+
+export interface ReadTrackRow {
+  ts: string;
+  path: string;
+  mtime: number;
+}
+
+/** Filename key for a session — basename of a transcript path or a raw id. */
+export function sessionKey(session: string): string {
+  const base = basename(session).replace(/\.[^.]+$/, "");
+  return base.replace(/[^A-Za-z0-9_-]/g, "-") || "unknown";
+}
+
+/** Directory holding one read log per session. */
+function readTrackDir(): string {
+  const base =
+    process.env.FAPONY_STATE_DIR || join(homedir(), ".config", "fapony");
+  return join(base, READ_TRACK_DIR);
+}
+
+/** Absolute path of a session's read log — may not exist. */
+export function readTrackPath(session: string): string {
+  return join(readTrackDir(), `${sessionKey(session)}.jsonl`);
+}
+
+function readTrackRows(session: string): ReadTrackRow[] {
+  const p = readTrackPath(session);
+  if (!existsSync(p)) return [];
+  const rows: ReadTrackRow[] = [];
+  for (const line of readFileSync(p, "utf-8").split("\n")) {
+    if (!line) continue;
+    try {
+      const r = JSON.parse(line) as ReadTrackRow;
+      if (typeof r.path === "string" && typeof r.mtime === "number") {
+        rows.push(r);
+      }
+    } catch {
+      // a torn line must not lose the rest of the log
+    }
+  }
+  return rows;
+}
+
+function appendReadTrackRow(session: string, row: ReadTrackRow): void {
+  const dir = readTrackDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  appendFileSync(readTrackPath(session), `${JSON.stringify(row)}\n`, "utf-8");
+}
+
+export interface RereadHintInput {
+  filePath: unknown;
+  offset?: unknown;
+  limit?: unknown;
+  cwd: string;
+  /** Session identity — transcript path (Claude) or session id (OpenCode). */
+  session?: unknown;
+}
+
+/**
+ * Annotate a full-file read of a path already read this session whose mtime
+ * has not moved, or null. Records every full read, so the returned count is
+ * the number of prior reads. Every unknown (kill switch on, no session, no
+ * path, bounded read, partial offset, missing file, read/write failure)
+ * resolves to null — a hint must never fire on a guess.
+ */
+export function rereadHintFor(opts: RereadHintInput): string | null {
+  try {
+    if (process.env.FAPONY_NO_REREAD_HINT === "1") return null;
+    if (typeof opts.session !== "string" || opts.session === "") return null;
+    if (typeof opts.filePath !== "string" || opts.filePath === "") return null;
+    // A bounded/partial read is already cheap — same line the size hint draws.
+    const offset = typeof opts.offset === "number" ? opts.offset : null;
+    if (offset !== null && offset !== 0) return null;
+    const limit = typeof opts.limit === "number" ? opts.limit : null;
+    if (limit !== null && limit < READ_HINT_MIN_LIMIT) return null;
+
+    const abs = (() => {
+      const p = opts.filePath.startsWith("/")
+        ? opts.filePath
+        : join(opts.cwd, opts.filePath);
+      try {
+        return realpathSync(p);
+      } catch {
+        return resolve(p);
+      }
+    })();
+    const st = statSync(abs);
+    if (!st.isFile()) return null;
+    const mtime = Math.round(st.mtimeMs);
+
+    const prior = readTrackRows(opts.session).filter((r) => r.path === abs);
+    const last = prior.at(-1);
+    appendReadTrackRow(opts.session, {
+      ts: new Date().toISOString(),
+      path: abs,
+      mtime,
+    });
+    if (!last || last.mtime !== mtime) return null;
+
+    // The hint feeds the agent's context — show the path *it* passed, relative
+    // to its own cwd, so a symlinked cwd (macOS /var → /private/var) does not
+    // turn a clean relative path into a resolved absolute one.
+    const rel = relative(opts.cwd, opts.filePath);
+    const shown = rel.startsWith("..") ? opts.filePath : rel;
+    return (
+      `fapony: already read ${shown} ${prior.length}\u00d7 this session — ` +
+      `content unchanged since the last read (mtime), grep the line range ` +
+      `you need instead of re-reading it`
+    );
+  } catch {
+    return null;
+  }
+}
+
 // --- Commit hint (tool.execute.after — annotate only, never block) ---
 //
 // OpenCode has no Stop hook (Cursor does — see cursor.ts hook-stop wiring)
@@ -417,6 +731,8 @@ export async function cmdHookReadHint(): Promise<void> {
   try {
     const raw = JSON.parse(await Bun.stdin.text()) as {
       cwd?: string;
+      transcript_path?: string;
+      session_id?: string;
       tool_input?: {
         file_path?: unknown;
         offset?: unknown;
@@ -424,16 +740,31 @@ export async function cmdHookReadHint(): Promise<void> {
       };
     };
     const cwd = raw.cwd ?? process.cwd();
+    const filePath = raw.tool_input?.file_path;
+    // One read log per session — transcript_path is the Claude session file,
+    // session_id the fallback when a client omits it.
+    const session = raw.transcript_path ?? raw.session_id;
     const parts: string[] = [];
     const hint = readHintFor({
-      filePath: raw.tool_input?.file_path,
+      filePath,
       offset: raw.tool_input?.offset,
       limit: raw.tool_input?.limit,
       cwd,
     });
     if (hint) parts.push(hint);
-    for (const line of readContextLines(raw.tool_input?.file_path, cwd)) {
-      parts.push(line);
+    const reread = rereadHintFor({
+      filePath,
+      offset: raw.tool_input?.offset,
+      limit: raw.tool_input?.limit,
+      cwd,
+      session,
+    });
+    if (reread) parts.push(reread);
+    const ctx = readContextData(filePath, cwd);
+    if (ctx) {
+      for (const line of [...ctx.debtLines, ...ctx.memLines]) {
+        parts.push(line);
+      }
     }
     if (parts.length > 0) {
       console.log(
@@ -445,6 +776,60 @@ export async function cmdHookReadHint(): Promise<void> {
         }),
       );
     }
+
+    // --- hint-fire log (PLAN-feedback-surface chunk 1) ---
+    // After output — best-effort, never block the hint.
+    const rel =
+      typeof filePath === "string"
+        ? (() => {
+            try {
+              const git = Bun.spawnSync(
+                ["git", "rev-parse", "--show-toplevel"],
+                { cwd, stdout: "pipe", stderr: "pipe" },
+              );
+              if (git.exitCode !== 0) return null;
+              const wt = realpathSync(git.stdout.toString().trim());
+              const abs = realpathSync(
+                filePath.startsWith("/") ? filePath : join(wt, filePath),
+              );
+              const r = relative(wt, abs).split("\\").join("/");
+              return r.startsWith("..") ? null : r;
+            } catch {
+              return null;
+            }
+          })()
+        : null;
+    const worktree = ctx?.worktree ?? null;
+    if (worktree) {
+      if (hint) {
+        recordHintFire({
+          ts: new Date().toISOString(),
+          worktree,
+          surface: "read",
+          file: rel,
+          count: 1,
+        });
+      }
+      if (ctx && ctx.debtIds.length > 0) {
+        recordHintFire({
+          ts: new Date().toISOString(),
+          worktree,
+          surface: "debt",
+          file: rel,
+          count: ctx.debtIds.length,
+          ids: ctx.debtIds,
+        });
+      }
+      if (ctx && ctx.memLines.length > 0) {
+        recordHintFire({
+          ts: new Date().toISOString(),
+          worktree,
+          surface: "mem",
+          file: rel,
+          count: ctx.memLines.length,
+        });
+      }
+    }
   } catch {
     // any failure = no hint; a hook must never block a read over a hint
   }
@@ -462,15 +847,26 @@ const DEBT_HINT_MAX = 3;
 const MEM_HINT_MAX = 2;
 const MEM_TEXT_MAX = 120;
 
-export function readContextLines(filePath: unknown, cwd: string): string[] {
+export interface ContextLineData {
+  worktree: string;
+  debtIds: string[];
+  debtLines: string[];
+  memLines: string[];
+}
+
+/** Structured data behind readContextLines — used by cmdHookReadHint for logging. */
+export function readContextData(
+  filePath: unknown,
+  cwd: string,
+): ContextLineData | null {
   try {
-    if (typeof filePath !== "string" || filePath === "") return [];
+    if (typeof filePath !== "string" || filePath === "") return null;
     const git = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
       cwd,
       stdout: "pipe",
       stderr: "pipe",
     });
-    if (git.exitCode !== 0) return [];
+    if (git.exitCode !== 0) return null;
     // macOS /var → /private/var: git reports the resolved root while callers
     // pass unresolved tmp paths — normalize both sides before comparing.
     const worktree = realpathSync(git.stdout.toString().trim());
@@ -478,9 +874,11 @@ export function readContextLines(filePath: unknown, cwd: string): string[] {
       filePath.startsWith("/") ? filePath : join(worktree, filePath),
     );
     const rel = relative(worktree, abs).split("\\").join("/");
-    if (rel.startsWith("..") || rel === "") return [];
+    if (rel.startsWith("..") || rel === "") return null;
 
-    const lines: string[] = [];
+    const debtIds: string[] = [];
+    const debtLines: string[] = [];
+    const memLines: string[] = [];
 
     // convention debt — source files only, fresh from the repo
     const dot = rel.lastIndexOf(".");
@@ -490,7 +888,8 @@ export function readContextLines(filePath: unknown, cwd: string): string[] {
         abs,
         loadConventions(worktree),
       ).slice(0, DEBT_HINT_MAX)) {
-        lines.push(`fapony debt: [${c.id}] ${c.rule}`);
+        debtIds.push(c.id);
+        debtLines.push(`fapony debt: [${c.id}] ${c.rule}`);
       }
     }
 
@@ -520,15 +919,24 @@ export function readContextLines(filePath: unknown, cwd: string): string[] {
         if (sameName !== 1) usableBase = [];
       }
       // direct hits (files[] / full path) outrank bare-basename hits
-      const memLines = [...direct, ...usableBase].slice(0, MEM_HINT_MAX);
-      for (const r of memLines) {
-        lines.push(
+      const memHits = [...direct, ...usableBase].slice(0, MEM_HINT_MAX);
+      for (const r of memHits) {
+        memLines.push(
           `fapony mem: ${r.ts.slice(0, 10)} ${r.kind} — ${r.text.slice(0, MEM_TEXT_MAX)}`,
         );
       }
     }
-    return lines.slice(0, DEBT_HINT_MAX + MEM_HINT_MAX);
+    return { worktree, debtIds, debtLines, memLines };
   } catch {
-    return [];
+    return null;
   }
 }
+
+export function readContextLines(filePath: unknown, cwd: string): string[] {
+  const data = readContextData(filePath, cwd);
+  if (!data) return [];
+  return [...data.debtLines, ...data.memLines].slice(
+    0,
+    DEBT_HINT_MAX + MEM_HINT_MAX,
+  );
+}