fapony 0.4.0 → 0.6.0

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,111 @@
+// 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 { 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";
+
+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;
+
+  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);
+      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)))
+          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);
+    }
+  }
+
+  return { files, deps, dependents, unresolved, external, barrels };
+}

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";

package/src/analyze/python.ts

@@ -0,0 +1,411 @@
+// src/analyze/python.ts — Python import scanning + resolution.
+//
+// Line-based: Bun.Transpiler can't parse .py (see map.ts for why
+// `python -c "import ast"` is not the answer). The module part always sits on
+// the first line of a `from … import`, so a multi-line name list is a
+// non-issue for the edge itself; the imported names only matter to resolve a
+// submodule (`from . import sib` → `sib.py`), so a parenthesized list is
+// joined across lines before its names are read.
+
+import {
+  dirname as posixDirname,
+  join as posixJoin,
+  normalize as posixNormalize,
+} from "node:path/posix";
+
+import { maskPyBlocks } from "../map.js";
+
+export interface PyImport {
+  /** Leading dots (`from ..x import`) — null for absolute imports. */
+  dots: string | null;
+  /** Dotted module path after the dots ("" for `from . import y`). */
+  mod: string;
+  /** Names bound by a `from … import`; empty for a plain `import`. */
+  names: string[];
+}
+
+// Frozen at the CPython 3.12 stdlib top-level set
+// (https://docs.python.org/3.12/library/ — ~210 public names).
+// Anything outside = `unresolved` on purpose: without `sys.path` a
+// third-party package (`requests`) is indistinguishable from a miss.
+export const PY_STDLIB: Set<string> = new Set([
+  "__future__",
+  "abc",
+  "aifc",
+  "argparse",
+  "array",
+  "ast",
+  "asynchat",
+  "asyncio",
+  "asyncore",
+  "atexit",
+  "audioop",
+  "base64",
+  "bdb",
+  "binascii",
+  "binhex",
+  "bisect",
+  "builtins",
+  "bz2",
+  "calendar",
+  "cgi",
+  "cgitb",
+  "chunk",
+  "cmath",
+  "cmd",
+  "code",
+  "codecs",
+  "codeop",
+  "collections",
+  "colorsys",
+  "compileall",
+  "concurrent",
+  "configparser",
+  "contextlib",
+  "contextvars",
+  "copy",
+  "copyreg",
+  "cProfile",
+  "crypt",
+  "csv",
+  "ctypes",
+  "curses",
+  "dataclasses",
+  "datetime",
+  "dbm",
+  "decimal",
+  "difflib",
+  "dis",
+  "doctest",
+  "email",
+  "encodings",
+  "ensurepip",
+  "enum",
+  "errno",
+  "faulthandler",
+  "fcntl",
+  "filecmp",
+  "fileinput",
+  "fnmatch",
+  "fractions",
+  "ftplib",
+  "functools",
+  "gc",
+  "getopt",
+  "getpass",
+  "gettext",
+  "glob",
+  "graphlib",
+  "grp",
+  "gzip",
+  "hashlib",
+  "heapq",
+  "hmac",
+  "html",
+  "http",
+  "idlelib",
+  "imaplib",
+  "imghdr",
+  "imp",
+  "importlib",
+  "inspect",
+  "io",
+  "ipaddress",
+  "itertools",
+  "json",
+  "keyword",
+  "lib2to3",
+  "linecache",
+  "locale",
+  "logging",
+  "lzma",
+  "mailbox",
+  "mailcap",
+  "marshal",
+  "math",
+  "mimetypes",
+  "mmap",
+  "modulefinder",
+  "multiprocessing",
+  "netrc",
+  "nis",
+  "nntplib",
+  "numbers",
+  "operator",
+  "opcode",
+  "optparse",
+  "os",
+  "ossaudiodev",
+  "pathlib",
+  "pdb",
+  "pickle",
+  "pickletools",
+  "pipes",
+  "pkgutil",
+  "platform",
+  "plistlib",
+  "poplib",
+  "posix",
+  "pprint",
+  "profile",
+  "pstats",
+  "pty",
+  "pwd",
+  "py_compile",
+  "pyclbr",
+  "pydoc",
+  "pyexpat",
+  "queue",
+  "quopri",
+  "random",
+  "re",
+  "readline",
+  "reprlib",
+  "resource",
+  "rlcompleter",
+  "runpy",
+  "sched",
+  "secrets",
+  "select",
+  "selectors",
+  "shelve",
+  "shlex",
+  "shutil",
+  "signal",
+  "site",
+  "smtpd",
+  "smtplib",
+  "sndhdr",
+  "socket",
+  "socketserver",
+  "sqlite3",
+  "ssl",
+  "stat",
+  "statistics",
+  "string",
+  "stringprep",
+  "struct",
+  "subprocess",
+  "sunau",
+  "symtable",
+  "sys",
+  "sysconfig",
+  "syslog",
+  "tabnanny",
+  "tarfile",
+  "telnetlib",
+  "tempfile",
+  "termios",
+  "test",
+  "textwrap",
+  "threading",
+  "time",
+  "timeit",
+  "tkinter",
+  "token",
+  "tokenize",
+  "tomllib",
+  "trace",
+  "traceback",
+  "tracemalloc",
+  "tty",
+  "turtle",
+  "types",
+  "typing",
+  "unicodedata",
+  "unittest",
+  "urllib",
+  "uuid",
+  "venv",
+  "warnings",
+  "wave",
+  "weakref",
+  "webbrowser",
+  "wsgiref",
+  "xdrlib",
+  "xml",
+  "xmlrpc",
+  "zipapp",
+  "zipfile",
+  "zipimport",
+  "zlib",
+  "zoneinfo",
+]);
+
+/** Root segment of an absolute import (`os.path` → `os`). */
+export function pyRootSegment(mod: string): string {
+  const dot = mod.indexOf(".");
+  return dot === -1 ? mod : mod.slice(0, dot);
+}
+
+// Imported names, before any `as` alias — the submodule is the name on the
+// left, not the alias. `*` and non-identifiers are dropped.
+export function pyImportNames(rest: string): string[] {
+  const clean = rest.replace(/[()]/g, " ");
+  const out: string[] = [];
+  for (let part of clean.split(",")) {
+    part = part.trim().split("#")[0].trim();
+    if (!part || part === "*") continue;
+    const name = part.split(/\s+as\s+/)[0].trim();
+    if (/^[A-Za-z_]\w*$/.test(name)) out.push(name);
+  }
+  return out;
+}
+
+export function scanPythonImports(content: string): PyImport[] {
+  const out: PyImport[] = [];
+  // Blank strings/docstrings first — a `from .x import y` written inside one
+  // is sample text, not an edge.
+  const lines = maskPyBlocks(content).split("\n");
+  const unbalanced = (s: string): boolean =>
+    (s.match(/\(/g) ?? []).length > (s.match(/\)/g) ?? []).length;
+  for (let i = 0; i < lines.length; i++) {
+    // Safe to cut at the first `#`: import/from lines carry only
+    // identifiers, dots, commas, parens, `as`, and `*` — never a `#` string.
+    const line = lines[i].split("#")[0];
+    let m: RegExpMatchArray | null;
+    if ((m = line.match(/^[ \t]*from\s*(\.+)?([\w.]*)\s+import\s+(.+)/))) {
+      // A parenthesized name list often spans lines — join until it closes
+      // (cap 20), the same shape the export scan uses. Without this a
+      // `from . import (sub)` loses `sub` and the submodule reads as orphan.
+      let rest = m[3];
+      let j = i;
+      while (unbalanced(rest) && j + 1 < lines.length && j - i < 20) {
+        j++;
+        rest += ` ${lines[j].split("#")[0].trim()}`;
+      }
+      out.push({ dots: m[1] ?? null, mod: m[2], names: pyImportNames(rest) });
+      i = j;
+    } else if ((m = line.match(/^[ \t]*import\s+([\w.]+(?:\s*,\s*[\w.]+)*)/))) {
+      // Plain `import` is always absolute in Python 3 (relative needs `from`).
+      for (const part of m[1].split(",")) {
+        const name = part.trim().split(/\s+/)[0];
+        if (name) out.push({ dots: null, mod: name, names: [] });
+      }
+    }
+  }
+  return out;
+}
+
+// Dots count folder levels: 1 = the importer's own dir, 2 = its parent, and
+// so on. Each level then tries `x.py` and `x/__init__.py`.
+export function resolvePythonRelative(
+  importerRel: string,
+  dots: string,
+  mod: string,
+  filesSet: Set<string>,
+): string | null {
+  let dir = posixDirname(importerRel);
+  for (let i = 1; i < dots.length; i++) {
+    if (dir === ".") return null; // climbs above the scanned root
+    dir = posixDirname(dir);
+  }
+  const base = mod ? posixJoin(dir, ...mod.split(".")) : dir;
+  const norm = posixNormalize(base);
+  const candidates =
+    norm === "."
+      ? ["__init__.py", "__init__.pyi"]
+      : mod
+        ? [
+            `${norm}.py`,
+            `${norm}.pyi`,
+            `${norm}/__init__.py`,
+            `${norm}/__init__.pyi`,
+          ]
+        : [`${norm}/__init__.py`, `${norm}/__init__.pyi`];
+  for (const c of candidates) {
+    if (filesSet.has(c)) return c;
+  }
+  return null;
+}
+
+// Dotted module path → file, so an absolute `import pkg.mod` / `from pkg.mod
+// import x` resolves when the target is in this repo. A file is indexed under
+// each ancestor dir that is not itself a package (no `__init__.py`) — the repo
+// root and a `src`-style root both qualify, so `mypkg.core` finds
+// `src/mypkg/core.py` while a bare `core` never does. Shortest path wins a clash
+// (which also prefers `x.py` over `x.pyi` when both are present).
+export function buildPyModuleIndex(filesSet: Set<string>): Map<string, string> {
+  const index = new Map<string, string>();
+  const put = (mod: string, file: string): void => {
+    const prev = index.get(mod);
+    if (!prev || file.length < prev.length) index.set(mod, file);
+  };
+  for (const file of filesSet) {
+    const ext = file.endsWith(".pyi")
+      ? ".pyi"
+      : file.endsWith(".py")
+        ? ".py"
+        : null;
+    if (!ext) continue;
+    const parts = file.slice(0, -ext.length).split("/");
+    if (parts[parts.length - 1] === "__init__") parts.pop();
+    for (let start = 0; start < parts.length; start++) {
+      const rootDir = parts.slice(0, start).join("/");
+      const prefix = rootDir ? `${rootDir}/` : "";
+      if (
+        filesSet.has(`${prefix}__init__.py`) ||
+        filesSet.has(`${prefix}__init__.pyi`)
+      )
+        continue; // a package, not a root
+      put(parts.slice(start).join("."), file);
+    }
+  }
+  return index;
+}
+
+// Every file a single import reaches: the module itself, plus each imported
+// name that is a real submodule (`from . import sib` → `sib.py`; the package
+// `__init__.py` is imported too, so it stays an edge). Self-edges are dropped
+// — `from . import x` inside `__init__.py` must not point at itself.
+export function resolvePythonImport(
+  importerRel: string,
+  imp: PyImport,
+  filesSet: Set<string>,
+  moduleIndex: Map<string, string>,
+): Set<string> {
+  const hits = new Set<string>();
+  if (imp.dots) {
+    let dir = posixDirname(importerRel);
+    for (let i = 1; i < imp.dots.length; i++) {
+      if (dir === ".") return hits; // climbs above the scanned root
+      dir = posixDirname(dir);
+    }
+    const base = imp.mod
+      ? posixNormalize(posixJoin(dir, ...imp.mod.split(".")))
+      : dir;
+    for (const name of imp.names) {
+      for (const c of [
+        `${base}/${name}.py`,
+        `${base}/${name}.pyi`,
+        `${base}/${name}/__init__.py`,
+        `${base}/${name}/__init__.pyi`,
+      ]) {
+        if (filesSet.has(c)) hits.add(c);
+      }
+    }
+    const selfCands = imp.mod
+      ? [
+          `${base}.py`,
+          `${base}.pyi`,
+          `${base}/__init__.py`,
+          `${base}/__init__.pyi`,
+        ]
+      : [`${base}/__init__.py`, `${base}/__init__.pyi`];
+    for (const c of selfCands) {
+      if (filesSet.has(c)) {
+        hits.add(c);
+        break;
+      }
+    }
+  } else {
+    for (const name of imp.names) {
+      const hit = moduleIndex.get(imp.mod ? `${imp.mod}.${name}` : name);
+      if (hit) hits.add(hit);
+    }
+    const self = moduleIndex.get(imp.mod);
+    if (self) hits.add(self);
+  }
+  hits.delete(importerRel);
+  return hits;
+}

package/src/analyze/resolve-ts.ts

@@ -0,0 +1,39 @@
+// src/analyze/resolve-ts.ts — TS/JS import resolution.
+//
+// Bun.Transpiler.scan() finds static imports; the two regexes below cover its
+// blind spots (require() and `import type` are real edges — changing a type
+// still shakes dependents). No overlap with scan output — scan reports
+// neither form.
+
+import {
+  dirname as posixDirname,
+  join as posixJoin,
+  normalize as posixNormalize,
+} from "node:path/posix";
+
+export const REQUIRE_RE = /\brequire\(\s*["']([^"']+)["']\s*\)/g;
+export const IMPORT_TYPE_RE =
+  /\bimport\s+type\s+[^;]*?\bfrom\s*["']([^"']+)["']/g;
+
+const RESOLVE_EXTS = [".ts", ".tsx", ".js", ".jsx"];
+
+export function resolveRelative(
+  importerRel: string,
+  raw: string,
+  filesSet: Set<string>,
+): string | null {
+  const base = posixNormalize(posixJoin(posixDirname(importerRel), raw));
+  const candidates = new Set<string>([base, `${base}/index.ts`]);
+  for (const e of RESOLVE_EXTS) candidates.add(base + e);
+  // TS files import the compiled path ("./foo.js") — try the stem too.
+  const dot = base.lastIndexOf(".");
+  if (dot > base.lastIndexOf("/")) {
+    const stem = base.slice(0, dot);
+    for (const e of RESOLVE_EXTS) candidates.add(stem + e);
+    candidates.add(`${stem}/index.ts`);
+  }
+  for (const c of candidates) {
+    if (filesSet.has(c)) return c;
+  }
+  return null;
+}