fapony 0.1.3 → 0.2.1

package/src/analyze.ts

@@ -1,15 +1,24 @@
 // src/analyze.ts — `fapony analyze`: structural health diagnosis for a TS/JS project.
 //
 // One file on purpose (plan cap: ≤1 new file in src/). Computes a file-level
-// import graph live with Bun.Transpiler.scan() — never persisted, no new table.
-// Read-only: never writes
-// into the analyzed directory.
+// import graph live with Bun.Transpiler.scan() — no new table. Read-only: never
+// writes into the analyzed directory. buildGraphCached additionally mirrors the
+// derived graph to the state dir (outside the worktree) as a best-effort cache
+// for callers that run as repeated short-lived processes (hooks) — see below.
 //
 // Same module also serves handoff_check / verification_report: blastRadius()
 // turns facts.files[] into per-file { dependents, tested } facts.
 
 import type { Dirent } from "node:fs";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import {
   dirname as posixDirname,
@@ -17,6 +26,7 @@ import {
   normalize as posixNormalize,
 } from "node:path/posix";
 
+import { faponyDir } from "./db/load.js";
 import { extractExports } from "./map.js";
 
 // --- Types (mirror SPEC-analyze-checkup.md) ---
@@ -132,7 +142,19 @@ export function isTestedThroughBarrels(
 export const SCAN_EXTS = new Set([".ts", ".tsx", ".js", ".jsx"]);
 
 // Always skipped, hardcoded — no config (per plan: no .faponyignore in v1).
-const SKIP_DIRS = new Set(["node_modules", "dist", "build", ".git"]);
+// "templates" for the same reason knip.json ignores templates/**: those files
+// ship as a template copied into other repos by `fapony init-mem` and never
+// have real importers here — scanning them produces false wrapper/orphan
+// signals (measured: conventions-seed flagged 8 "wrappers" that were all
+// src/mem/commands/*.ts helpers matched against unrelated identically-
+// named calls elsewhere in the repo, e.g. "cmdNow() instead of now(").
+const SKIP_DIRS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  "templates",
+]);
 
 // A nested checkout (clone or `git worktree add`) is a different project that
 // happens to live inside this one — walking it doubles the graph and makes every
@@ -322,6 +344,154 @@ export function buildGraph(dir: string): ImportGraph {
   return { files, deps, dependents, unresolved, external, barrels };
 }
 
+// --- Session-scoped graph cache ---
+//
+// buildGraph is cheap on this repo (~50ms/150 files) but the Edit hint calls it
+// on every Edit — and a Claude Code PreToolUse hook is a *fresh process per
+// tool call*, so an in-process cache alone never survives to the next edit. The
+// graph is therefore mirrored to <faponyDir>/graph-cache/<key>.json:
+//   - auto-build: every build is written through, best-effort (never blocks)
+//   - auto-invalidate: a fingerprint over the source-file set (rel path + size
+//     + mtimeMs) is stored beside the graph; a mismatch means rebuild
+//   - cost: the cache file is only stat-ed when there is one to validate, so a
+//     first-ever call pays build + write; later calls pay a walk + stat + parse,
+//     well under a rebuild on any repo large enough for this to matter
+// Everything here is derived state — an unreadable, corrupt, stale or
+// unwritable cache falls back to a live build and no code path trusts it.
+
+const GRAPH_CACHE_VERSION = 1;
+const GRAPH_CACHE_DIR = "graph-cache";
+
+interface SerializedGraph {
+  v: number;
+  fp: string;
+  files: string[];
+  deps: Record<string, string[]>;
+  dependents: Record<string, string[]>;
+  unresolved: number;
+  external: number;
+  barrels: string[];
+}
+
+let _graphCache: { dir: string; fp: string; graph: ImportGraph } | null = null;
+
+/** Drop the in-process graph cache (tests simulate a fresh hook process). */
+export function resetGraphCache(): void {
+  _graphCache = null;
+}
+
+/** Absolute path of a worktree's graph-cache file — may not exist. */
+export function graphCachePath(dir: string): string {
+  const abs = resolve(dir);
+  const slug = abs.replace(/[^A-Za-z0-9]+/g, "-").slice(0, 60);
+  return join(
+    faponyDir(),
+    GRAPH_CACHE_DIR,
+    `${slug}-${Bun.hash(abs).toString(36)}.json`,
+  );
+}
+
+// The graph changes only when the set of source files or their bytes change —
+// size/mtime/ctime catch that without reading any file. ctime rides the same
+// stat call for free and cannot be forged like mtime can (only the system
+// moves it), so an mtime-preserving rewrite still invalidates.
+function graphFingerprint(absDir: string): string {
+  const parts: string[] = [];
+  for (const rel of collectSourceFiles(absDir)) {
+    try {
+      const st = statSync(join(absDir, rel));
+      parts.push(
+        `${rel}\u0000${st.size}\u0000${st.mtimeMs}\u0000${st.ctimeMs}`,
+      );
+    } catch {
+      parts.push(`${rel}\u0000?\u0000?\u0000?`);
+    }
+  }
+  return Bun.hash(parts.join("\n")).toString(36);
+}
+
+function serializeGraph(graph: ImportGraph, fp: string): SerializedGraph {
+  const rec = (m: Map<string, Set<string>>): Record<string, string[]> => {
+    const out: Record<string, string[]> = {};
+    for (const [k, v] of m) out[k] = [...v];
+    return out;
+  };
+  return {
+    v: GRAPH_CACHE_VERSION,
+    fp,
+    files: graph.files,
+    deps: rec(graph.deps),
+    dependents: rec(graph.dependents),
+    unresolved: graph.unresolved,
+    external: graph.external,
+    barrels: [...graph.barrels],
+  };
+}
+
+function hydrateGraph(c: SerializedGraph): ImportGraph {
+  const toMap = (r: Record<string, string[]>): Map<string, Set<string>> => {
+    const m = new Map<string, Set<string>>();
+    for (const [k, v] of Object.entries(r)) m.set(k, new Set(v));
+    return m;
+  };
+  return {
+    files: c.files,
+    deps: toMap(c.deps),
+    dependents: toMap(c.dependents),
+    unresolved: c.unresolved,
+    external: c.external,
+    barrels: new Set(c.barrels),
+  };
+}
+
+function readCachedGraph(path: string, fp: string): ImportGraph | null {
+  try {
+    const cached = JSON.parse(readFileSync(path, "utf-8")) as SerializedGraph;
+    if (cached.v !== GRAPH_CACHE_VERSION || cached.fp !== fp) return null;
+    return hydrateGraph(cached);
+  } catch {
+    return null;
+  }
+}
+
+function writeCachedGraph(path: string, graph: ImportGraph, fp: string): void {
+  try {
+    if (!existsSync(join(faponyDir(), GRAPH_CACHE_DIR))) {
+      mkdirSync(join(faponyDir(), GRAPH_CACHE_DIR), { recursive: true });
+    }
+    // pid-suffixed temp + rename: a reader never sees a half-written file even
+    // when two hook processes race.
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(serializeGraph(graph, fp)), "utf-8");
+    renameSync(tmp, path);
+  } catch {
+    // best-effort — a cache that cannot be written must not break the caller
+  }
+}
+
+export function buildGraphCached(dir: string): ImportGraph {
+  const abs = resolve(dir);
+  // One walk per call: the fingerprint doubles as the in-process validity
+  // check, so a same-process second call after an edit rebuilds instead of
+  // serving the stale graph. A drift between this fp and the built graph
+  // self-heals — the next call recomputes and rebuilds again.
+  const fp = graphFingerprint(abs);
+  if (_graphCache?.dir === abs && _graphCache.fp === fp)
+    return _graphCache.graph;
+  const path = graphCachePath(abs);
+  if (existsSync(path)) {
+    const cached = readCachedGraph(path, fp);
+    if (cached) {
+      _graphCache = { dir: abs, fp, graph: cached };
+      return cached;
+    }
+  }
+  const graph = buildGraph(abs);
+  _graphCache = { dir: abs, fp, graph };
+  writeCachedGraph(path, graph, fp);
+  return graph;
+}
+
 // --- Diagnosis ---
 
 function findCycles(graph: ImportGraph): string[][] {

package/src/conventions-seed.ts

@@ -15,6 +15,7 @@ import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { pathToFileURL } from "node:url";
 import { collectSourceFiles, isSkippedDir, isTestFile } from "./analyze.js";
+import { CONVENTIONS_FILE, FAPONY_DIR } from "./db/index.js";
 import { extractBody, extractExports } from "./map.js";
 
 const RESTRICTED_RULES = new Set([
@@ -190,7 +191,6 @@ async function eslintRows(
   const rows: SeedRow[] = [];
   const configs: string[] = [];
   const skipped: string[] = [];
-  const seen = new Set<string>();
   for (const abs of findConfigFiles(root)) {
     let raw: string;
     try {
@@ -377,7 +377,7 @@ function detectWrappers(root: string): SeedRow[] {
 // --- entry ---
 
 export async function seedConventionsFile(target: string): Promise<SeedResult> {
-  const file = join(target, ".fapony", "conventions.json");
+  const file = join(target, CONVENTIONS_FILE);
   const base: SeedResult = {
     file,
     eslintRows: 0,
@@ -408,7 +408,7 @@ export async function seedConventionsFile(target: string): Promise<SeedResult> {
     // a wrapper scan failure is not an init failure
   }
   const payload = `${JSON.stringify({ conventions: rows }, null, 2)}\n`;
-  mkdirSync(join(target, ".fapony"), { recursive: true });
+  mkdirSync(join(target, FAPONY_DIR), { recursive: true });
   writeFileSync(file, payload);
   return {
     file,

package/src/db/defaults.ts

@@ -6,13 +6,21 @@ export const DEFAULT_SAFETY_DENY = [
   "checkout\\s+--\\s",
   "git\\s+stash",
 ];
-export const DEFAULT_PLAN_DIR = ".fapony/plan";
-export const DEFAULT_SPEC_DIR = ".fapony/spec";
+// --- .fapony/ layout (single source of truth — do not hardcode ".fapony" elsewhere) ---
+// plan/spec live in .fapony/ — not configurable (gitignored = private).
+export const FAPONY_DIR = ".fapony";
+export const CONFIG_FILENAME = "fapony.config.json";
+export const CONVENTIONS_FILENAME = "conventions.json";
+export const EVIDENCE_FILENAME = "evidence.json";
+export const CONVENTIONS_FILE = `${FAPONY_DIR}/${CONVENTIONS_FILENAME}`;
+// plan/spec live in .fapony/ — not configurable (gitignored = private).
+export const PLAN_DIR = `${FAPONY_DIR}/plan`;
+export const SPEC_DIR = `${FAPONY_DIR}/spec`;
 // Archive sits beside plan/, not inside it, so archiving never changes a file's
 // depth and its relative links survive the move untouched.
-export const DEFAULT_DONE_DIR = ".fapony/done";
-export const DEFAULT_MEMORY_ENTRY = ".fapony/.memory/mem.ts";
-export const DEFAULT_EVIDENCE_FILE = ".fapony/evidence.json";
+export const DEFAULT_DONE_DIR = `${FAPONY_DIR}/done`;
+export const DEFAULT_MEM_DIR = `${FAPONY_DIR}/.memory`;
+export const DEFAULT_EVIDENCE_FILE = `${FAPONY_DIR}/${EVIDENCE_FILENAME}`;
 
 export const DEFAULT_CONFIG: Config = {
   worktrees: {},

package/src/db/getters.ts

@@ -1,10 +1,10 @@
 import {
   DEFAULT_DONE_DIR,
   DEFAULT_EVIDENCE_FILE,
-  DEFAULT_MEMORY_ENTRY,
-  DEFAULT_PLAN_DIR,
+  DEFAULT_MEM_DIR,
   DEFAULT_SAFETY_DENY,
-  DEFAULT_SPEC_DIR,
+  PLAN_DIR,
+  SPEC_DIR,
 } from "./defaults.js";
 import type { Config } from "./types.js";
 
@@ -12,20 +12,22 @@ export function safetyDeny(config?: Config): string[] {
   return config?.safety?.deny ?? DEFAULT_SAFETY_DENY;
 }
 
-export function planDir(config?: Config): string {
-  return config?.paths?.planDir ?? DEFAULT_PLAN_DIR;
+/** Hardcoded — plan/spec live in .fapony/ (gitignored = private). */
+export function planDir(): string {
+  return PLAN_DIR;
 }
 
-export function specDir(config?: Config): string {
-  return config?.paths?.specDir ?? DEFAULT_SPEC_DIR;
+/** Hardcoded — plan/spec live in .fapony/ (gitignored = private). */
+export function specDir(): string {
+  return SPEC_DIR;
 }
 
 export function doneDir(config?: Config): string {
   return config?.paths?.doneDir ?? DEFAULT_DONE_DIR;
 }
 
-export function memoryEntry(config?: Config): string {
-  return config?.paths?.memoryEntry ?? DEFAULT_MEMORY_ENTRY;
+export function memoryDir(config?: Config): string {
+  return config?.paths?.memDir ?? DEFAULT_MEM_DIR;
 }
 
 export function evidenceFile(config?: Config): string {

package/src/db/load.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { DEFAULT_CONFIG } from "./defaults.js";
+import { CONFIG_FILENAME, DEFAULT_CONFIG } from "./defaults.js";
 import type { Config } from "./types.js";
 
 // XDG Base Directory convention (macOS ignores Apple's ~/Library/Application Support
@@ -20,7 +20,7 @@ function _dbPath(config?: Config): string {
 
 export function configFilePath(): string {
   if (process.env.FAPONY_CONFIG) return process.env.FAPONY_CONFIG;
-  return join(process.cwd(), "fapony.config.json");
+  return join(process.cwd(), CONFIG_FILENAME);
 }
 
 function freshDefaultConfig(): Config {

package/src/db/store.ts

@@ -135,48 +135,10 @@ export function addEvent(
   return Number(result.lastInsertRowid);
 }
 
-/**
- * Merge `patch` into an existing event's JSON data (keeps keys already set).
- * Used to complete a spawn row with bytes_out/usd after the agent finishes —
- * one row per spawn, timing (ts) stays at spawn start. No-op when the row
- * is missing or its data isn't a JSON object.
- */
-export function updateEventData(
-  db: Database,
-  eventId: number,
-  patch: Record<string, unknown>,
-): void {
-  const row = db
-    .prepare("SELECT data FROM events WHERE id = ?")
-    .get(eventId) as { data: string | null } | null;
-  if (!row) return;
-  let base: Record<string, unknown> = {};
-  try {
-    const parsed = JSON.parse(row.data ?? "null") as unknown;
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      base = parsed as Record<string, unknown>;
-    }
-  } catch {
-    return;
-  }
-  db.prepare("UPDATE events SET data = ? WHERE id = ?").run(
-    JSON.stringify({ ...base, ...patch }),
-    eventId,
-  );
-}
-
 export function getRun(db: Database, runId: number): Run | null {
   return db.prepare("SELECT * FROM runs WHERE id = ?").get(runId) as Run | null;
 }
 
-export function getActiveRuns(db: Database): Run[] {
-  return db
-    .prepare(
-      "SELECT * FROM runs WHERE status NOT IN ('passed', 'stopped') ORDER BY id",
-    )
-    .all() as Run[];
-}
-
 /**
  * Latest still-open run for a worktree+plan pair, or null.
  * Used by MCP verdict_submit to bind a round-2+ verdict to the original run
@@ -221,43 +183,6 @@ export function getEvents(db: Database, runId: number): Event[] {
     .all(runId) as Event[];
 }
 
-/**
- * Pulls the most recent unresolved "gate fail" note for a worktree+mem_id pair —
- * i.e. the review feedback the next `fapony run` should hand back to the executor.
- * Only looks at the latest run for that pair; if it already passed, returns null
- * (nothing to carry forward).
- */
-export function getPendingFeedback(
-  db: Database,
-  worktree: string,
-  memId: string,
-  excludeRunId?: number,
-): string | null {
-  const run = db
-    .prepare(
-      `SELECT * FROM runs WHERE worktree = ? AND mem_id = ? AND id != ? ORDER BY id DESC LIMIT 1`,
-    )
-    .get(worktree, memId, excludeRunId ?? -1) as Run | null;
-  if (run?.status !== "fixing") return null;
-
-  const event = db
-    .prepare(
-      `SELECT * FROM events WHERE run_id = ? AND kind = 'gate' ORDER BY id DESC LIMIT 1`,
-    )
-    .get(run.id) as Event | null;
-  if (!event?.data) return null;
-
-  try {
-    const parsed = JSON.parse(event.data) as {
-      verdict?: string;
-      note?: string;
-    };
-    return parsed.verdict === "fail" && parsed.note ? parsed.note : null;
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Merge extra fields into the most recent gate event's data JSON.
  * Used by MCP verdict_submit to add reason_code / source after gateOnce

package/src/db/types.ts

@@ -55,11 +55,9 @@ 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;
-    memoryEntry?: string;
+    memDir?: string;
     evidenceFile?: string;
   } | null;
   safety?: {