fapony 0.5.0 → 0.6.1

package/README.md

@@ -4,7 +4,7 @@
 
 # fapony
 
-[![npm](https://img.shields.io/npm/v/fapony.svg)](https://www.npmjs.com/package/fapony)
+[![npm](https://img.shields.io/npm/v/fapony.svg)](https://www.npmjs.com/package/fapony) [![GitHub](https://img.shields.io/github/stars/kire21b/fapony.svg)](https://github.com/kire21b/fapony)
 
 **See what your coding agents actually cost.** fapony reads the session logs Claude Code, Codex,
 OpenCode and ZCode already write, and puts them all on one yardstick — tokens, cost and time per
@@ -63,6 +63,8 @@ flowchart LR
     B[OpenCode] --> F
     C[ZCode] --> F
     D[Codex] --> F
+    E[Cursor] --> F
+    G[Antigravity] --> F
     F --> U[usage — tokens & cost]
     F --> M[mem log — what was decided here]
     F --> D[debt — how far the move has gone]
@@ -97,7 +99,11 @@ fapony install --all        # skip the prompt, wire everything detected
 # 4. Turn on the memory layer (per project you want it in)
 fapony init /path/to/your-worktree
 #    creates .fapony/ — .memory/ (the mem log the 3 MCP tools read and write)
-#    and conventions.json for `fapony debt` (shared rules: commit them)
+#    and conventions.json for `fapony debt` (shared rules: commit them),
+#    then offers to write the memory rules into CLAUDE.md / AGENTS.md
+#    (none yet = AGENTS.md + a CLAUDE.md that imports it) — agents only log
+#    what the rules they already read tell them to
+fapony init /path/to/your-worktree --rules --yes   # repo already set up: rules only, no prompt
 ```
 
 …or add it manually to any MCP client: `{ "mcpServers": { "fapony": { "command": "fapony", "args": ["mcp"] } } }`. Full protocol and adapter examples: [docs/mcp-handcheck.md](https://github.com/kire21b/fapony/blob/main/docs/mcp-handcheck.md).
@@ -119,26 +125,28 @@ Stated up front, because the gap between these two things is where most tooling
 
 ## What runs where
 
-`fapony install` wires five clients (Claude Code, OpenCode, Cursor, ZCode, Codex). MCP is the only
-piece all of them get — the hooks and in-process hints are per-client, and the read/edit hints
-arrive **before** the call on Claude Code but **after** it on OpenCode, whose only annotate channel
-is `tool.execute.after`. Nothing here is required: skip the hooks and every MCP tool still answers.
-
-| | Claude Code | OpenCode | Cursor | ZCode | Codex |
-|---|---|---|---|---|---|
-| MCP tools — `mem_find` `mem_add` `mem_close` | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Stop hook — refuse to end a turn with commits but no new mem row | ✅ | — | ✅ | — | ✅ after trust |
-| Read hint — big-file pointer + debt/mem lines | ✅ before | ✅ after | — | — | — |
-| Re-read hint — unchanged repeat read | ✅ before | ✅ after | — | — | — |
-| Edit hint — importer count before a shape change | ✅ before | ✅ after | — | — | — |
-| Commit hint — `git commit` → record-a-mem-row nudge | — | ✅ after | — | — | — |
-| Skills symlinked into `~/.claude/skills` | ✅ | ✅ | — | — | — |
-| Skills symlinked into `~/.agents/skills` | — | — | — | ✅ | ✅ |
-| `usage-scan` reads this client's session log | ✅ | ✅ | — | ✅ | ✅ |
+`fapony install` wires six clients (Claude Code, OpenCode, Cursor, ZCode, Codex, Antigravity). MCP is
+the only piece all of them get — the hooks and in-process hints are per-client, and the read/edit
+hints arrive **before** the call on Claude Code but **after** it on OpenCode, whose only annotate
+channel is `tool.execute.after`. Nothing here is required: skip the hooks and every MCP tool still
+answers.
+
+| | Claude Code | OpenCode | Cursor | ZCode | Codex | Antigravity |
+|---|---|---|---|---|---|---|
+| MCP tools — `mem_find` `mem_add` `mem_close` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Stop hook — refuse to end a turn with commits but no new mem row | ✅ | — | ✅ | — | ✅ after trust | — |
+| Read hint — big-file pointer + debt/mem lines | ✅ before | ✅ after | — | — | — | — |
+| Re-read hint — unchanged repeat read | ✅ before | ✅ after | — | — | — | — |
+| Edit hint — importer count before a shape change | ✅ before | ✅ after | — | — | — | — |
+| Commit hint — `git commit` → record-a-mem-row nudge | — | ✅ after | — | — | — | — |
+| Skills symlinked into `~/.claude/skills` | ✅ | ✅ | — | — | — | — |
+| Skills symlinked into `~/.agents/skills` | — | — | — | ✅ | ✅ | ✅ |
+| `usage-scan` reads this client's session log | ✅ | ✅ | — | ✅ | ✅ | — |
 
 `—` means not wired, not impossible. Codex hooks require trust via `/hooks` before they run —
-`fapony install` tells you when. The hints live on hooks rather than MCP on purpose — they must
-fire mid-turn without the agent deciding to call anything.
+`fapony install` tells you when. Antigravity gets MCP + skills now; its hook surface is still
+evolving, and `usage-scan` can't read its session log yet. The hints live on hooks rather than MCP
+on purpose — they must fire mid-turn without the agent deciding to call anything.
 
 ## The ledger — one habit, 3 tools
 
@@ -235,7 +243,7 @@ fapony price-scan                          # fetch model price table → prices.
 fapony usage-web [port]                    # usage comparison dashboard from cache
 
 # lookup (read-only, never touches state)
-fapony analyze [path]                      # live repo graph: hubs, orphans, cycles, changed-untested
+fapony analyze [path]                      # live repo graph: hubs, orphans, cycles, changed-untested (TS/JS + Python .py/.pyi; stdlib→external, no sys.path)
 fapony review-seed [--staged|--commit <sha>|--range <a...b>|--files f1,f2,dir|--plan <PLAN.md>]  # scope facts for a review
 fapony plan-seed <name> [--spec] [--scope <path>[,<path>]]...  # write PLAN (+SPEC): frontmatter, capped sections, prior-art list
 
@@ -297,8 +305,9 @@ vendor-neutral skills (anything that reads stdin) · opt-in telemetry, off by de
 ([TELEMETRY.md](https://github.com/kire21b/fapony/blob/main/TELEMETRY.md) lists exactly what
 leaves the machine) · Bun-only; run state in SQLite via `bun:sqlite` (WAL mode).
 
-**Not supported (yet):** PreToolUse hints on Cursor, ZCode or Codex — Cursor has no such hook and
-the other two expose no in-process hook surface for read/edit hints. A hosted or shared ledger —
+**Not supported (yet):** PreToolUse hints on Cursor, ZCode, Codex or Antigravity — Cursor has no
+such hook, the other two expose no in-process hook surface for read/edit hints, and Antigravity's
+hook surface is still evolving. A hosted or shared ledger —
 `FAPONY_STATE_DIR` on a synced folder works as an experiment only; SQLite's WAL mode does not
 tolerate concurrent writers over NFS/Dropbox/iCloud Drive and can corrupt the db under real
 contention.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Token usage across Claude Code, OpenCode, Codex & ZCode on one yardstick — plus a project mem log and convention-debt tracker agents query via 3 MCP tools. No server, your data stays local",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",

package/skill/plan-with-pony/SKILL.md

@@ -192,7 +192,9 @@ only place that ordering stays true.
 becomes a second copy of the plan, and then neither copy can be trusted. `fapony mem kickoff` reads the
 checkboxes in the **first `##` section only**, so section 6 stays detail rather than status.
 
-Section 6 — every step must be verifiable. Section 8 — must link back to anything it came from.
+Section 6 — every step must be verifiable. Section 8 — must link back to anything it came from. **A step that needs something the system does not store yet** ("the month the accountant has seen",
+"last synced") must say where it lives, who writes it, and who reads it — or the executing agent
+designs it alone, by exploring (measured: one such chunk burned ~250k tokens before a line of code).
 **Plan = what/why/order, spec = how in detail**: never paste API shapes, schemas, wireframes, or
 edge-case tables into section 7; link to the spec instead. Full template: `templates/PLAN.md`.
 

package/src/adapters/cli.ts

@@ -5,7 +5,7 @@
 // argv routing.
 
 import { existsSync } from "node:fs";
-import { cmdAnalyze } from "../analyze.js";
+import { cmdAnalyze } from "../analyze/index.js";
 import { renderUsage, suggestCommand } from "../commands.js";
 import { cmdDebt } from "../debt/cli.js";
 import { cmdDigest } from "../digest/cli.js";

package/src/adapters/hooks/bug-markers.ts

@@ -18,23 +18,33 @@
 // appear in every bug report and would fire on any turn that reads one — the
 // Stop hook blocks once per session on a match, so a false positive is costly.
 
-/** Free-text announcement phrases ("I found a bug"), never symptom words. */
+/** Free-text announcement phrases ("I found a bug"), never symptom words.
+ *  `g` flag is required — hasBugMarker walks every match (matchAll). */
 export const BUG_MARKERS: RegExp[] = [
-  /เจอบั๊ก/,
-  /พบบั๊ก/,
-  /\bfound (?:a |the )?bug\b/i,
-  /\b(?:this|that|it)(?:'s| is) a bug\b/i,
-  /\bbug\b\s*:/i,
+  /(?:เจอ|พบ)(?:ว่า)?(?:เป็น)?บั๊ก/g, // พบบั๊ก · พบว่าเป็นบั๊กจริง
+  /บั๊กที่(?:เจอ|พบ)/g,
+  /\bfound (?:a |the )?(?:real |actual )?bug\b/gi,
+  /\b(?:this|that|it)(?:'s| is) a (?:real )?bug\b/gi,
+  /\b(?:bug confirmed|confirmed (?:a |real )?bug)\b/gi,
+  /\bbug\b\s*(?:\([^)\n]{0,80}\))?\s*:/gi, // **Bug (cause…):**
 ];
 
+// Negation / hypothetical right before a match ("ไม่พบบั๊ก", "จะเจอบั๊ก",
+// "not a bug"). Bare "เป็นบั๊ก" is deliberately not a marker: "อาจเป็นบั๊ก" is
+// everywhere and a false fire costs a Stop-hook block.
+const NEGATED = /(?:ไม่|จะ|ถ้า|อาจ|\bnot\s|\bno\s|\bif\s)\s*$/i;
+
 /**
  * The matched marker phrase, or null. Returns the matched text so the caller
- * can quote it back to the agent (stop.ts does, in its block reason).
+ * can quote it back to the agent (stop.ts does, in its block reason). Every
+ * match is checked, so "ไม่พบบั๊กใหม่ แต่เจอบั๊กที่ X" still fires on the second.
  */
 export function hasBugMarker(text: string): string | null {
   for (const re of BUG_MARKERS) {
-    const m = text.match(re);
-    if (m) return m[0];
+    for (const m of text.matchAll(re)) {
+      const before = text.slice(Math.max(0, m.index - 15), m.index);
+      if (!NEGATED.test(before)) return m[0];
+    }
   }
   return null;
 }

package/src/adapters/hooks/context-data.ts

@@ -5,7 +5,7 @@
 
 import { realpathSync } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
-import { collectSourceFiles, SCAN_EXTS } from "../../analyze.js";
+import { collectSourceFiles, SCAN_EXTS } from "../../analyze/index.js";
 import { MEM_TEXT_MAX, readMemLog } from "../../core/mem-log.js";
 import { debtForFile, resolveDebtScope } from "../../debt/index.js";
 
@@ -19,6 +19,8 @@ export interface ContextLineData {
   memLines: string[];
   /** Ids of open bugs actually emitted as OPEN BUG lines above (for the fire log). */
   openBugIds: string[];
+  /** Ids of every mem row emitted in memLines (open bugs first) — joined to authors offline. */
+  memIds: string[];
 }
 
 /** Structured data behind readContextLines — used by cmdHookReadHint for logging. */
@@ -45,6 +47,7 @@ export function readContextData(
     const debtLines: string[] = [];
     const memLines: string[] = [];
     const openBugIds: string[] = [];
+    const memIds: string[] = [];
 
     // convention debt — source files only, fresh from the repo. The scope
     // pairs the git root (repo-relative `where`) with the nearest
@@ -112,13 +115,15 @@ export function readContextData(
         .filter((r) => !(r.id && emitted.has(r.id)))
         .slice(0, MEM_HINT_MAX - openLines.length);
       for (const line of openLines) memLines.push(line);
+      memIds.push(...openBugIds);
       for (const r of rest) {
+        if (r.id) memIds.push(r.id);
         memLines.push(
           `fapony mem: ${r.ts.slice(0, 10)} ${r.kind} — ${r.text.slice(0, MEM_TEXT_MAX)}`,
         );
       }
     }
-    return { worktree, debtIds, debtLines, memLines, openBugIds };
+    return { worktree, debtIds, debtLines, memLines, openBugIds, memIds };
   } catch {
     return null;
   }

package/src/adapters/hooks/edit-hint.ts

@@ -12,7 +12,7 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { join, relative, sep } from "node:path";
-import { buildGraphCached, SCAN_EXTS } from "../../analyze.js";
+import { buildGraphCached, SCAN_EXTS } from "../../analyze/index.js";
 import { recordHintFire } from "../../core/hint-log.js";
 import { sessionKey } from "../../core/hook-helpers.js";
 import { readContextData } from "./context-data.js";
@@ -184,6 +184,16 @@ export async function cmdHookEditHint(): Promise<void> {
             file: rel && !rel.startsWith("..") ? rel : null,
             count: 1,
           });
+          if (ctx && ctx.memLines.length > 0) {
+            recordHintFire({
+              ts: new Date().toISOString(),
+              worktree,
+              surface: "mem",
+              file: rel && !rel.startsWith("..") ? rel : null,
+              count: ctx.memLines.length,
+              ids: ctx.memIds,
+            });
+          }
           if (ctx && ctx.openBugIds.length > 0) {
             recordHintFire({
               ts: new Date().toISOString(),

package/src/adapters/hooks/read-hint.ts

@@ -13,7 +13,7 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { join, relative, resolve } from "node:path";
-import { SCAN_EXTS } from "../../analyze.js";
+import { SCAN_EXTS } from "../../analyze/index.js";
 import { recordHintFire } from "../../core/hint-log.js";
 import { sessionKey } from "../../core/hook-helpers.js";
 import { readMemLog } from "../../memory.js";
@@ -390,6 +390,7 @@ export async function cmdHookReadHint(): Promise<void> {
           surface: "mem",
           file: rel,
           count: ctx.memLines.length,
+          ids: ctx.memIds,
         });
       }
       if (ctx && ctx.openBugIds.length > 0) {

package/src/adapters/mcp/evidence.ts

@@ -156,9 +156,17 @@ function runCommand(
   timeoutMs: number,
 ): CommandOutcome {
   const start = Date.now();
+  // A bare `pytest` otherwise hits a global one whose editable install may
+  // point at another worktree — tests the wrong code, silently.
+  // ponytail: .venv only; poetry/uv/conda when someone asks.
+  const venvBin = join(worktree, ".venv", "bin");
+  const env = existsSync(venvBin)
+    ? { ...process.env, PATH: `${venvBin}:${process.env.PATH ?? ""}` }
+    : undefined;
   try {
     execSync(cmd, {
       cwd: worktree,
+      env,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
       timeout: timeoutMs,

package/src/adapters/mcp/primitives.ts

@@ -7,7 +7,7 @@
 // §0 rule: add-only — never remove or rename exported symbols.
 
 import { execSync } from "node:child_process";
-import type { BlastEntry } from "../../analyze.js";
+import type { BlastEntry } from "../../analyze/index.js";
 import { ROOT } from "../../update.js";
 
 // ─── Server build identity ─────────────────────────────────────────────

package/src/adapters/mcp/tools/check.ts

@@ -1,6 +1,6 @@
 // src/mcp/tools/check.ts — handoff_check tool
 
-import { blastRadiusForWorktree } from "../../../analyze.js";
+import { blastRadiusForWorktree } from "../../../analyze/index.js";
 import type { CheckResult } from "../primitives.js";
 import { errorResult, jsonResult, type ToolResult } from "../types.js";
 

package/src/adapters/mcp/tools/collect.ts

@@ -1,7 +1,7 @@
 // src/mcp/tools/collect.ts — handoff_collect tool
 
 import { execSync } from "node:child_process";
-import { isTestFile } from "../../../analyze.js";
+import { isTestFile } from "../../../analyze/index.js";
 import { errorResult, jsonResult, type ToolResult } from "../types.js";
 
 // --- Git helper ---

package/src/adapters/mcp/tools/report.ts

@@ -4,7 +4,7 @@
 // run metrics + verdict into a single VerificationReport.
 // Calls existing primitives — no duplicate parser/conformance logic.
 
-import { blastRadiusForWorktree } from "../../../analyze.js";
+import { blastRadiusForWorktree } from "../../../analyze/index.js";
 import { loadConfig } from "../../../core/config.js";
 import { getEvents, getRun, openDb } from "../../../db/store.js";
 import { parseGateEventData } from "../../../parse.js";

package/src/analyze/barrels.ts

@@ -0,0 +1,56 @@
+// src/analyze/barrels.ts — exports seen *through* barrels.
+//
+// `export * from "./x"` is reported by Bun.Transpiler.scan as an IMPORT edge and
+// never as an export, so a barrel file scans as having zero exports. Measured on
+// vela 2026-09-18: 211 barrels out of 1,996 source files, and `@innominix/ui`
+// alone is imported 462 times — the blind spot hides most of the cross-package
+// graph, which is why a wrapper reached through a barrel reads as unused. Named
+// re-exports (`export { x } from "./y"`) are already reported correctly; only the
+// star form needs this. Cost to close it: 1.9ms on a 17-export barrel. tsc answers
+// the same question type-accurately for 2,176ms — see SPEC-convention-debt.md §2.2
+// for why that 1,145x is not worth paying here.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { extractExports } from "../map.js";
+import { resolvePythonRelative } from "./python.js";
+import { resolveRelative } from "./resolve-ts.js";
+
+export const STAR_REEXPORT_RE =
+  /^[ \t]*export\s+\*\s+(?:as\s+[\w$]+\s+)?from\s*["'](\.[^"']+)["']/gm;
+
+// `from .x import *` — the Python shape of a star re-export. Absolute star
+// imports can't resolve (same bucket as TS bare specifiers), so only relative.
+export const PY_STAR_REEXPORT_RE =
+  /^[ \t]*from\s*(\.+)((?:[\w.]*))\s+import\s+\*/gm;
+
+export function exportsThroughBarrels(
+  absDir: string,
+  rel: string,
+  filesSet: Set<string>,
+  seen = new Set<string>(),
+): string[] {
+  if (seen.has(rel)) return []; // barrels re-export each other; stop the cycle
+  seen.add(rel);
+  let source: string;
+  try {
+    source = readFileSync(join(absDir, rel), "utf-8");
+  } catch {
+    return [];
+  }
+  const out = extractExports(source, undefined, rel)
+    .symbols.filter((s) => s.name !== "*")
+    .map((s) => s.name);
+  STAR_REEXPORT_RE.lastIndex = 0;
+  for (const m of source.matchAll(STAR_REEXPORT_RE)) {
+    const hit = resolveRelative(rel, m[1], filesSet);
+    if (hit) out.push(...exportsThroughBarrels(absDir, hit, filesSet, seen));
+  }
+  PY_STAR_REEXPORT_RE.lastIndex = 0;
+  for (const m of source.matchAll(PY_STAR_REEXPORT_RE)) {
+    const hit = resolvePythonRelative(rel, m[1], m[2], filesSet);
+    if (hit) out.push(...exportsThroughBarrels(absDir, hit, filesSet, seen));
+  }
+  return [...new Set(out)];
+}

package/src/analyze/blast.ts

@@ -0,0 +1,58 @@
+// src/analyze/blast.ts — `blastRadius()`: per-file { dependents, tested }
+// facts for handoff_check / verification_report.
+
+import { isTestedThroughBarrels } from "./criteria.js";
+import { buildGraph } from "./graph.js";
+import type { BlastEntry, ImportGraph } from "./types.js";
+
+// BFS over the reverse-edge map — one grep-and-recurse chain collapsed into
+// one walk. `seen` makes cycles a no-op instead of an infinite loop.
+function transitiveDependentsCount(graph: ImportGraph, file: string): number {
+  const seen = new Set<string>();
+  let frontier = graph.dependents.get(file) ?? new Set<string>();
+  while (frontier.size > 0) {
+    const next = new Set<string>();
+    for (const f of frontier) {
+      if (seen.has(f)) continue;
+      seen.add(f);
+      for (const dep of graph.dependents.get(f) ?? []) {
+        if (!seen.has(dep)) next.add(dep);
+      }
+    }
+    frontier = next;
+  }
+  // A cycle can walk back to `file` itself — it's not its own dependent.
+  seen.delete(file);
+  return seen.size;
+}
+
+export function blastRadius(
+  graph: ImportGraph,
+  files: string[],
+): Record<string, BlastEntry> {
+  const out: Record<string, BlastEntry> = {};
+  for (const f of files) {
+    const deps = graph.dependents.get(f) ?? new Set<string>();
+    out[f] = {
+      dependents: deps.size,
+      tested: isTestedThroughBarrels(graph, f),
+      transitive: transitiveDependentsCount(graph, f),
+    };
+  }
+  return out;
+}
+
+// Convenience for the MCP tools: graph the worktree live, map files[] to
+// blast radius. Null when there is nothing to map or the dir is unreadable —
+// callers render "no blast data", never throw.
+export function blastRadiusForWorktree(
+  worktree: string,
+  files: string[],
+): Record<string, BlastEntry> | null {
+  if (files.length === 0) return null;
+  try {
+    return blastRadius(buildGraph(worktree), files);
+  } catch {
+    return null;
+  }
+}

package/src/analyze/cache.ts

@@ -0,0 +1,162 @@
+// src/analyze/cache.ts — 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.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+
+import { faponyDir } from "../core/config.js";
+import { collectSourceFiles } from "./discover.js";
+import { buildGraph } from "./graph.js";
+import type { ImportGraph } from "./types.js";
+
+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;
+}

package/src/analyze/cli.ts

@@ -0,0 +1,28 @@
+// src/analyze/cli.ts — `fapony analyze` CLI entry.
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { diagnose } from "./diagnose.js";
+import { formatAnalyze } from "./format.js";
+import { buildGraph } from "./graph.js";
+import type { ImportGraph } from "./types.js";
+
+export function cmdAnalyze(args: string[]): void {
+  const dir = args[0] ?? ".";
+  const absDir = resolve(dir);
+  if (!existsSync(absDir)) {
+    console.error(`fapony analyze: "${dir}" does not exist`);
+    process.exit(1);
+  }
+  let graph: ImportGraph;
+  try {
+    graph = buildGraph(absDir);
+  } catch (e) {
+    console.error(
+      `fapony analyze: cannot scan "${dir}": ${e instanceof Error ? e.message : String(e)}`,
+    );
+    process.exit(1);
+  }
+  console.log(formatAnalyze(graph, diagnose(graph)));
+}