fapony 0.5.0 → 0.6.1

package/src/analyze/criteria.ts

@@ -0,0 +1,81 @@
+// src/analyze/criteria.ts — "is this file tested?" criteria shared by
+// diagnose, blast radius, and review-seed.
+//
+// Same regex collect.ts has always used for test detection — single source of
+// truth now (collect.ts imports isTestFile from here). Do NOT diverge.
+
+import type { ImportGraph } from "./types.js";
+
+// Word-boundary aware: "test"/"spec" match only as whole path segments, not as
+// substrings of other words (e.g. testing.ts, contest.ts, vitest/ do NOT match).
+export const TEST_PATH_RE =
+  /(?:^|[/._-])(?:test|spec)(?:$|[/._-])|__tests__|\.test\.|\.spec\./i;
+
+export function isTestFile(p: string): boolean {
+  return TEST_PATH_RE.test(p);
+}
+
+// A file whose entire body is `export ... from "..."`. Detected because a test
+// importing a barrel is still a test importing everything behind it — without
+// this, every module under src/db/index.ts or src/stats.ts reads as untested.
+const EXPORT_FROM_RE =
+  /export\s+(?:\*|\{[^}]*\}|type\s+\*|type\s+\{[^}]*\})(?:\s+as\s+[\w$]+)?\s+from\s*["'][^"']+["']\s*;?/g;
+
+export function isBarrelSource(content: string, rel?: string): boolean {
+  if (rel?.endsWith("__init__.py") || rel?.endsWith("__init__.pyi")) {
+    // A Python barrel re-exports instead of defining: every logical line is
+    // an import, a from-import, or the `__all__` assignment. Docstrings are
+    // stripped first (nearly every `__init__.py` has one); `#` is cut per
+    // line, which is safe here because import/`__all__` lines carry no `#`
+    // inside strings — only identifiers, dots, commas, and parens.
+    const code = content.replace(/"""[\s\S]*?"""|'''[\s\S]*?'''/g, "");
+    const logical: string[] = [];
+    let buf = "";
+    let open = 0;
+    const push = () => {
+      const t = buf.trim();
+      if (t) logical.push(t);
+      buf = "";
+      open = 0;
+    };
+    for (const rawLine of code.split("\n")) {
+      const line = rawLine.split("#")[0].trim();
+      if (!line) continue;
+      buf += (buf ? " " : "") + line;
+      open +=
+        (line.match(/[[(]/g) ?? []).length -
+        (line.match(/[\])]/g) ?? []).length;
+      if (!line.endsWith("\\") && open <= 0 && !line.endsWith(",")) push();
+    }
+    push();
+    if (logical.length === 0) return false;
+    return logical.every((l) =>
+      /^(?:import\s+[\w.]+|from\s+\.*[\w.]*\s+import\s+\S|__all__\s*=)/.test(l),
+    );
+  }
+  const code = content
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/^[ \t]*\/\/.*$/gm, "");
+  if (!/\bexport\b/.test(code)) return false;
+  EXPORT_FROM_RE.lastIndex = 0;
+  return code.replace(EXPORT_FROM_RE, "").trim() === "";
+}
+
+// Is any test file an importer of `file`, walking *through* barrels only?
+// Barrels can nest (db/*.ts → db/index.ts → db.ts), so recurse, but never
+// through a normal module — that would make every file in a tested repo
+// count as tested and kill the signal entirely.
+export function isTestedThroughBarrels(
+  graph: ImportGraph,
+  file: string,
+  seen = new Set<string>(),
+): boolean {
+  if (seen.has(file)) return false;
+  seen.add(file);
+  for (const dep of graph.dependents.get(file) ?? []) {
+    if (isTestFile(dep)) return true;
+    if (graph.barrels.has(dep) && isTestedThroughBarrels(graph, dep, seen))
+      return true;
+  }
+  return false;
+}

package/src/analyze/diagnose.ts

@@ -0,0 +1,113 @@
+// src/analyze/diagnose.ts — `diagnose()`: hub-untested / orphan / cycle /
+// changed-untested findings over a built graph.
+
+import { isTestedThroughBarrels, isTestFile } from "./criteria.js";
+import { isEntryPoint } from "./discover.js";
+import type { Finding, FindingKind, ImportGraph } from "./types.js";
+
+function findCycles(graph: ImportGraph): string[][] {
+  const cycles: string[][] = [];
+  const seen = new Set<string>();
+  const color = new Map<string, number>(); // 1 = on stack, 2 = done
+  const stack: string[] = [];
+
+  function visit(node: string): void {
+    if (cycles.length >= 20) return; // bound work, display caps at 5 anyway
+    color.set(node, 1);
+    stack.push(node);
+    for (const next of graph.deps.get(node) ?? []) {
+      if (cycles.length >= 20) break;
+      const c = color.get(next) ?? 0;
+      if (c === 1) {
+        const cycle = stack.slice(stack.indexOf(next));
+        const key = [...cycle].sort().join("|");
+        if (!seen.has(key)) {
+          seen.add(key);
+          cycles.push(cycle);
+        }
+      } else if (c === 0) {
+        visit(next);
+      }
+    }
+    stack.pop();
+    color.set(node, 2);
+  }
+
+  for (const f of graph.files) {
+    if ((color.get(f) ?? 0) === 0) visit(f);
+  }
+  return cycles;
+}
+
+const KIND_RANK: Record<FindingKind, number> = {
+  cycle: 0,
+  "hub-untested": 1,
+  "changed-untested": 2,
+  orphan: 3,
+};
+
+export function diagnose(
+  graph: ImportGraph,
+  changed: string[] = [],
+): Finding[] {
+  const findings: Finding[] = [];
+  const filesSet = new Set(graph.files);
+
+  for (const cycle of findCycles(graph)) {
+    findings.push({
+      kind: "cycle",
+      file: cycle.join(" ↔ "),
+      detail: "circular imports — refactoring either side breaks the other",
+      evidence: [...cycle, cycle[0]].join(" → "),
+    });
+  }
+
+  const hubUntested: { file: string; n: number }[] = [];
+  for (const f of graph.files) {
+    const deps = graph.dependents.get(f) ?? new Set<string>();
+    if (deps.size === 0) {
+      if (!isEntryPoint(f) && !graph.entries?.has(f) && !isTestFile(f)) {
+        findings.push({
+          kind: "orphan",
+          file: f,
+          detail:
+            "no one imports it and it is not an entry point — dead code candidate",
+          evidence: "0 dependents",
+        });
+      }
+    } else if (deps.size >= 3 && !isTestedThroughBarrels(graph, f)) {
+      hubUntested.push({ file: f, n: deps.size });
+    }
+  }
+  hubUntested.sort((a, b) => b.n - a.n || (a.file < b.file ? -1 : 1));
+  for (const { file, n } of hubUntested) {
+    const deps = [...(graph.dependents.get(file) ?? [])].sort();
+    const shown = deps.slice(0, 3).join(", ");
+    const rest = n > 3 ? ` … (+${n - 3})` : "";
+    findings.push({
+      kind: "hub-untested",
+      file,
+      detail: `${n} files depend on it; no test imports it — edit here and nothing catches the break`,
+      evidence: `dependents: ${shown}${rest}`,
+    });
+  }
+
+  for (const c of changed) {
+    if (!filesSet.has(c)) continue;
+    const deps = graph.dependents.get(c) ?? new Set<string>();
+    if (!isTestedThroughBarrels(graph, c)) {
+      findings.push({
+        kind: "changed-untested",
+        file: c,
+        detail: `recently changed but no test depends on it (${deps.size} dependent) — nothing catches it if it breaks`,
+        evidence:
+          deps.size > 0
+            ? `dependents: ${[...deps].sort().join(", ")}`
+            : "0 dependents",
+      });
+    }
+  }
+
+  findings.sort((a, b) => KIND_RANK[a.kind] - KIND_RANK[b.kind]);
+  return findings;
+}

package/src/analyze/discover.ts

@@ -0,0 +1,84 @@
+// src/analyze/discover.ts — file discovery: which files enter the graph.
+//
+// Manual walk, not Bun.Glob. Always skipped dirs are hardcoded — no config
+// (per plan: no .faponyignore in v1).
+
+import type { Dirent } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+export const SCAN_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".pyi"]);
+
+// "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. "cmdDone() instead of done(").
+const SKIP_DIRS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  "templates",
+  // A `.venv` holds thousands of third-party `.py` files — walking it would
+  // drown the graph the way node_modules would (which is skipped above).
+  // `__pycache__` needs no entry: it holds only `.pyc`, never scanned.
+  ".venv",
+]);
+
+// 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
+// single-directory pattern look like it repeats across two. `parentDir` is
+// required so this can be detected rather than guessed from the name: prefixes
+// like `wt-`/`cl-` are one person's convention, `.git` is the actual invariant
+// (a dir for a clone, a file for a worktree — existsSync covers both).
+export function isSkippedDir(name: string, parentDir: string): boolean {
+  if (SKIP_DIRS.has(name)) return true;
+  return existsSync(join(parentDir, name, ".git"));
+}
+
+export function isEntryPoint(rel: string): boolean {
+  const base = rel.slice(rel.lastIndexOf("/") + 1);
+  return base === "fapony.ts" || base === "index.ts" || base === "__main__.py";
+}
+
+export function collectSourceFiles(
+  absDir: string,
+  opts?: { skipHidden?: boolean },
+): string[] {
+  const out: string[] = [];
+  const stack: string[] = [absDir];
+  while (stack.length > 0) {
+    const dir = stack.pop() as string;
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue; // unreadable dir → skip, never throw
+    }
+    for (const e of entries) {
+      // Never follow symlinks — loop-proof without extra code.
+      if (e.isSymbolicLink()) continue;
+      if (e.isDirectory()) {
+        if (isSkippedDir(e.name, dir)) continue;
+        if (opts?.skipHidden && e.name.startsWith(".")) continue;
+        stack.push(join(dir, e.name));
+      } else if (e.isFile()) {
+        const dot = e.name.lastIndexOf(".");
+        if (dot >= 0 && SCAN_EXTS.has(e.name.slice(dot))) {
+          out.push(relative(absDir, join(dir, e.name)).split(sep).join("/"));
+        }
+      }
+    }
+  }
+  out.sort();
+  // Shadow rule: `x.py` wins over `x.pyi` — the stub is a fallback for
+  // stub-only distributions, never a second node (otherwise dependents
+  // double-count). The dropped `.pyi` still resolves via candidates.
+  if (out.some((f) => f.endsWith(".pyi"))) {
+    const has = new Set(out);
+    return out.filter((f) => !f.endsWith(".pyi") || !has.has(f.slice(0, -1)));
+  }
+  return out;
+}

package/src/analyze/format.ts

@@ -0,0 +1,38 @@
+// src/analyze/format.ts — CLI rendering (plain text only — no ANSI, pipes cleanly).
+
+import type { Finding, ImportGraph } from "./types.js";
+
+export function formatAnalyze(graph: ImportGraph, findings: Finding[]): string {
+  let imports = 0;
+  for (const s of graph.deps.values()) imports += s.size;
+  const lines: string[] = [];
+  lines.push(
+    `fapony analyze — ${graph.files.length} files scanned (.ts/.tsx/.js/.jsx/.py), ${imports} imports, ${graph.external} builtin, ${graph.unresolved} unresolved`,
+  );
+  lines.push("");
+
+  if (graph.files.length === 0) {
+    // Nothing read is not "healthy" — an unsupported-only repo used to get a clean bill here.
+    lines.push(
+      "no supported source files found — nothing analyzed (only .ts/.tsx/.js/.jsx/.py are read)",
+    );
+  } else if (findings.length === 0) {
+    lines.push("no findings — structure looks healthy");
+  } else {
+    for (const f of findings.slice(0, 5)) {
+      const icon = f.kind === "orphan" ? "·" : "⚠";
+      lines.push(`  ${icon}  ${f.file}`);
+      lines.push(`     ${f.detail}`);
+      lines.push(`     ${f.evidence}`);
+      lines.push("");
+    }
+    const rest = findings.length - Math.min(findings.length, 5);
+    if (rest > 0) lines.push(`… and ${rest} more`);
+    lines.push(
+      graph.unresolved > 0
+        ? `${findings.length} findings. ${graph.unresolved} unresolved imports (path alias / package name) — dependent counts may be lower than reality`
+        : `${findings.length} findings.`,
+    );
+  }
+  return lines.join("\n");
+}

package/src/analyze/graph.ts

@@ -0,0 +1,170 @@
+// src/analyze/graph.ts — `buildGraph()`: file-level import graph, computed
+// live with Bun.Transpiler.scan() — no new table. Read-only: never writes
+// into the analyzed directory.
+//
+// Same module also serves handoff_check / verification_report: blastRadius()
+// (see blast.ts) turns facts.files[] into per-file { dependents, tested } facts.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { isBarrelSource } from "./criteria.js";
+import { collectSourceFiles } from "./discover.js";
+import {
+  buildPyModuleIndex,
+  PY_STDLIB,
+  pyRootSegment,
+  resolvePythonImport,
+  scanPythonImports,
+} from "./python.js";
+import { IMPORT_TYPE_RE, REQUIRE_RE, resolveRelative } from "./resolve-ts.js";
+import type { ImportGraph } from "./types.js";
+
+// Root pyproject.toml only: declared deps (normalized to import-name guesses)
+// and `[project.scripts]` targets. A dist whose import name differs
+// (scikit-learn → sklearn) stays unresolved — fail-safe toward "don't know".
+function readPyproject(absDir: string): {
+  deps: Set<string>;
+  scripts: string[];
+} {
+  const deps = new Set<string>();
+  const scripts: string[] = [];
+  const path = join(absDir, "pyproject.toml");
+  if (!existsSync(path)) return { deps, scripts };
+  let project: {
+    dependencies?: unknown;
+    "optional-dependencies"?: Record<string, unknown>;
+    scripts?: Record<string, unknown>;
+  };
+  try {
+    project =
+      (
+        Bun.TOML.parse(readFileSync(path, "utf-8")) as {
+          project?: typeof project;
+        }
+      ).project ?? {};
+  } catch {
+    return { deps, scripts };
+  }
+  const specs = [
+    project.dependencies,
+    ...Object.values(project["optional-dependencies"] ?? {}),
+  ].flatMap((v) => (Array.isArray(v) ? v : []));
+  for (const spec of specs) {
+    const name =
+      typeof spec === "string" && spec.match(/^\s*([A-Za-z0-9._-]+)/)?.[1];
+    if (name) deps.add(name.toLowerCase().replace(/[-.]/g, "_"));
+  }
+  for (const target of Object.values(project.scripts ?? {})) {
+    if (typeof target === "string") scripts.push(target.split(":")[0].trim());
+  }
+  return { deps, scripts };
+}
+
+const PY_MAIN_RE = /^if\s+__name__\s*==\s*["']__main__["']\s*:/m;
+
+export function buildGraph(dir: string): ImportGraph {
+  const absDir = resolve(dir);
+  const files = collectSourceFiles(absDir);
+  const filesSet = new Set(files);
+  const deps = new Map<string, Set<string>>();
+  const dependents = new Map<string, Set<string>>();
+  for (const f of files) dependents.set(f, new Set());
+  const barrels = new Set<string>();
+  let unresolved = 0;
+  let external = 0;
+  // Built lazily — a TS-only repo never pays for it.
+  let pyIndex: Map<string, string> | null = null;
+  let pyproject: ReturnType<typeof readPyproject> | null = null;
+  const entries = new Set<string>();
+
+  const transpiler = new Bun.Transpiler({ loader: "ts" });
+
+  for (const rel of files) {
+    let content: string;
+    try {
+      content = readFileSync(join(absDir, rel), "utf-8");
+    } catch {
+      unresolved++;
+      continue;
+    }
+    if (isBarrelSource(content, rel)) barrels.add(rel);
+    if (rel.endsWith(".py") || rel.endsWith(".pyi")) {
+      // No Transpiler here — it can't parse Python. Relative imports resolve
+      // against the importer's package; same-repo absolute imports resolve
+      // against the module index. An absolute miss whose root is in PY_STDLIB
+      // is external; a third-party package or a real miss stays unresolved.
+      pyIndex ??= buildPyModuleIndex(filesSet);
+      pyproject ??= readPyproject(absDir);
+      if (PY_MAIN_RE.test(content)) entries.add(rel);
+      const pyEdges = new Set<string>();
+      for (const imp of scanPythonImports(content)) {
+        const hits = resolvePythonImport(rel, imp, filesSet, pyIndex);
+        if (hits.size > 0) for (const h of hits) pyEdges.add(h);
+        else if (
+          !imp.dots &&
+          imp.mod &&
+          (PY_STDLIB.has(pyRootSegment(imp.mod)) ||
+            pyproject.deps.has(pyRootSegment(imp.mod).toLowerCase()))
+        )
+          external++;
+        else unresolved++;
+      }
+      deps.set(rel, pyEdges);
+      continue;
+    }
+    const raws: string[] = [];
+    try {
+      const scanned = transpiler.scan(content) as {
+        imports: { path: string }[];
+      };
+      for (const imp of scanned.imports) raws.push(imp.path);
+    } catch {
+      // Syntax-broken file: skip it, count once — never fail the whole run.
+      unresolved++;
+      continue;
+    }
+    // Transpiler.scan blind spots: require() and `import type` are real edges
+    // (changing a type still shakes dependents), so pick them up by regex.
+    // No overlap with scan output above — scan reports neither form.
+    REQUIRE_RE.lastIndex = 0;
+    IMPORT_TYPE_RE.lastIndex = 0;
+    for (const m of content.matchAll(REQUIRE_RE)) raws.push(m[1]);
+    for (const m of content.matchAll(IMPORT_TYPE_RE)) raws.push(m[1]);
+
+    const edges = new Set<string>();
+    for (const raw of raws) {
+      if (raw.startsWith(".")) {
+        const hit = resolveRelative(rel, raw, filesSet);
+        if (hit) edges.add(hit);
+        else unresolved++;
+      } else if (raw.startsWith("node:") || raw.startsWith("bun:")) {
+        // A builtin is never an edge between two project files, so it can
+        // never be the reason a dependent count came out low. Lumping it in
+        // made the warning fire on every repo — 311 of this one's 312 were
+        // builtins — and a warning that always fires is not read.
+        external++;
+      } else {
+        // Package name or path alias — out of scope in v1, and unlike a
+        // builtin this one CAN be a project edge (`@app/core` in a monorepo).
+        unresolved++;
+      }
+    }
+    deps.set(rel, edges);
+  }
+
+  for (const [file, edgeSet] of deps) {
+    for (const dep of edgeSet) {
+      dependents.get(dep)?.add(file);
+    }
+  }
+
+  if (pyIndex && pyproject) {
+    for (const mod of pyproject.scripts) {
+      const hit = pyIndex.get(mod);
+      if (hit) entries.add(hit);
+    }
+  }
+
+  return { files, deps, dependents, unresolved, external, barrels, entries };
+}

package/src/analyze/index.ts

@@ -0,0 +1,18 @@
+// src/analyze/index.ts — barrel for `fapony analyze`: structural health
+// diagnosis for a TS/JS project.
+//
+// Layout mirrors src/install/ and src/debt/: types + one file per concern,
+// CLI entry in cli.ts. Callers import this barrel directly (same as debt/).
+
+export * from "./barrels.js";
+export * from "./blast.js";
+export * from "./cache.js";
+export * from "./cli.js";
+export * from "./criteria.js";
+export * from "./diagnose.js";
+export * from "./discover.js";
+export * from "./format.js";
+export * from "./graph.js";
+export * from "./python.js";
+export * from "./resolve-ts.js";
+export * from "./types.js";