fapony 0.4.0 → 0.6.0

package/src/analyze/types.ts

@@ -0,0 +1,44 @@
+// src/analyze/types.ts — shared types for the analyze graph + diagnosis.
+//
+// Pure types only, no imports — every analyze module depends on this one,
+// nothing here depends back (same shape as src/install/types.ts).
+
+export interface ImportGraph {
+  /** Relative POSIX paths scanned. */
+  files: string[];
+  /** file → files it imports. */
+  deps: Map<string, Set<string>>;
+  /** file → files that import it (reverse). */
+  dependents: Map<string, Set<string>>;
+  /** Imports that could not be resolved (bare specifier / alias / builtin). */
+  /** Imports that may hide a real edge: relative misses, path aliases, bare
+   * package names, and files too broken to read. Worth warning about. */
+  unresolved: number;
+  /** `node:` / `bun:` builtins — never an edge between two project files, so
+   * counting them as "unresolved" only inflates the warning. */
+  external: number;
+  /** Files that only re-export (`export ... from`) — they hide the real importer. */
+  barrels: Set<string>;
+}
+
+export type FindingKind =
+  | "hub-untested"
+  | "orphan"
+  | "cycle"
+  | "changed-untested";
+
+export interface Finding {
+  kind: FindingKind;
+  file: string;
+  /** Human sentence — the thing people read. */
+  detail: string;
+  /** How to re-check it yourself (file names, cycle path). */
+  evidence: string;
+}
+
+export interface BlastEntry {
+  dependents: number;
+  tested: boolean;
+  /** Dependents of dependents, transitively (cycle-safe, excludes the file itself). */
+  transitive: number;
+}

package/src/conventions-seed.ts

@@ -14,7 +14,11 @@
 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 {
+  collectSourceFiles,
+  isSkippedDir,
+  isTestFile,
+} from "./analyze/index.js";
 import { CONVENTIONS_FILE, FAPONY_DIR } from "./core/config.js";
 import { extractBody, extractExports } from "./map.js";
 
@@ -300,7 +304,7 @@ function detectWrappers(root: string): SeedRow[] {
     } catch {
       continue;
     }
-    const scan = extractExports(source);
+    const scan = extractExports(source, undefined, rel);
     if (scan.error) continue;
     for (const sym of scan.symbols) {
       if (sym.kind !== "const" && sym.kind !== "fn") continue;

package/src/core/hint-log.ts

@@ -30,7 +30,17 @@ export function hintLogPath(worktree: string): string {
 export interface HintFireRow {
   ts: string;
   worktree: string;
-  surface: "read" | "debt" | "mem" | "commit" | "edit";
+  surface:
+    | "read"
+    | "debt"
+    | "mem"
+    | "commit"
+    | "edit"
+    | "open-bug"
+    | "handoff-would-block"
+    | "handoff-pass"
+    | "commit-block"
+    | "bug-block";
   file: string | null;
   count: number;
   ids?: string[];
@@ -62,6 +72,11 @@ export interface HintImpact {
     mem: number;
     commit: number;
     edit: number;
+    "open-bug": number;
+    "handoff-would-block": number;
+    "handoff-pass": number;
+    "commit-block": number;
+    "bug-block": number;
   };
   debt: { shown: number; resolved: number; unknown: number };
   window: string | null;

package/src/core/mem-log.ts

@@ -22,8 +22,22 @@ export interface MemRow {
   ref?: string;
   /** Files the row is about — written by `mem add --files` (PLAN-convention-debt chunk 3). */
   files?: string[];
+  /** Problem identity, distinct from kind (action) and files[] (place) — written by `mem add --key` (PLAN-mem-keys chunk 1). */
+  key?: string;
+  /** Row schema version: 2 = may carry `key`; absent = v:1 legacy row, read as-is. */
+  v?: number;
 }
 
+/** One mem-row text budget for any hint/seed surface that shows a row (was context-data's private const). */
+export const MEM_TEXT_MAX = 120;
+
+/**
+ * The only accepted shape of a mem row `key` — problem identity, not action
+ * (kind) and not place (files[]). Lives here in core so CLI and MCP validate
+ * through one regex (PLAN-unify-mem-engine: one engine, both surfaces).
+ */
+export const KEY_RE = /^[a-z0-9-]{3,40}$/;
+
 interface RawMemRow {
   ts?: string;
   agent?: string;
@@ -33,6 +47,8 @@ interface RawMemRow {
   id?: string;
   ref?: string;
   files?: unknown;
+  key?: unknown;
+  v?: unknown;
 }
 
 /**
@@ -319,6 +335,8 @@ export function readMemLog(
         ...(Array.isArray(parsed.files)
           ? { files: parsed.files.filter((f) => typeof f === "string") }
           : {}),
+        ...(typeof parsed.key === "string" ? { key: parsed.key } : {}),
+        ...(typeof parsed.v === "number" ? { v: parsed.v } : {}),
       });
     }
   }

package/src/debt/cli.ts

@@ -13,7 +13,7 @@ import { ZONE_CAP } from "./types.js";
 
 const USAGE = `usage: fapony debt [path] [options]
   --files f1,f2     check specific files instead of scanning
-  --id <conv>       show only this convention
+  --id a,b          show only these conventions
   --where <path>    narrow scope to files under this path
   --all             show all zones (default: cap at ${ZONE_CAP})
   --json            output raw JSON
@@ -68,7 +68,7 @@ export function cmdDebt(args: string[]): void {
   let path: string | undefined;
   let filesMode: string[] | null = null;
   let json = false;
-  let filterId: string | undefined;
+  let filterIds: string[] = [];
   let wherePath: string | undefined;
   let showAll = false;
   for (let i = 0; i < args.length; i++) {
@@ -80,14 +80,17 @@ export function cmdDebt(args: string[]): void {
         process.exit(1);
       }
       i++;
-      filesMode = v
+      // Accumulate, never reassign: a repeated --files grows the set
+      // (PLAN-comma-x chunk 2 — last-wins was silent data loss).
+      const parts = v
         .split(",")
         .map((s) => s.trim())
         .filter(Boolean);
-      if (filesMode.length === 0) {
+      if (parts.length === 0) {
         console.error(`fapony debt: --files needs at least one path\n${USAGE}`);
         process.exit(1);
       }
+      filesMode = [...(filesMode ?? []), ...parts];
     } else if (a === "--id") {
       const v = args[i + 1];
       if (!v || v.startsWith("--")) {
@@ -95,7 +98,17 @@ export function cmdDebt(args: string[]): void {
         process.exit(1);
       }
       i++;
-      filterId = v;
+      // Comma list, same shape as --files: ids are slugs, an id can't hold
+      // a comma, so any comma splits (PLAN-comma-x). Repeats accumulate too.
+      const parts = v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (parts.length === 0) {
+        console.error(`fapony debt: --id needs a convention id\n${USAGE}`);
+        process.exit(1);
+      }
+      filterIds = [...filterIds, ...parts];
     } else if (a === "--where") {
       const v = args[i + 1];
       if (!v || v.startsWith("--")) {
@@ -171,12 +184,14 @@ export function cmdDebt(args: string[]): void {
   }
   const report = debtScan(worktree, loaded);
 
-  // --id filter: keep only the named convention
-  if (filterId) {
-    report.entries = report.entries.filter((e) => e.conv.id === filterId);
-    report.declared = report.declared.filter((c) => c.id === filterId);
+  // --id filter: keep only the named conventions (comma list allowed)
+  if (filterIds.length > 0) {
+    report.entries = report.entries.filter((e) =>
+      filterIds.includes(e.conv.id),
+    );
+    report.declared = report.declared.filter((c) => filterIds.includes(c.id));
     report.checkedCount = 0; // not relevant when filtering
-    report.dropped = report.dropped.filter((d) => d.id === filterId);
+    report.dropped = report.dropped.filter((d) => filterIds.includes(d.id));
   }
 
   // --where filter: narrow file lists to paths under the given prefix

package/src/debt/scan.ts

@@ -5,7 +5,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
-import { collectSourceFiles } from "../analyze.js";
+import { collectSourceFiles } from "../analyze/index.js";
 import {
   type Convention,
   DEBT_FILE_CAP,

package/src/hook.ts

@@ -7,6 +7,7 @@
 
 export {
   BUG_MARKERS,
+  bugDedupeKey,
   bugSignalFromTranscript,
   COMMIT_HINT_MIN_COMMITS,
   type CommitHintInput,
@@ -19,12 +20,15 @@ export {
   cmdHookStop,
   commitHintFor,
   computeHintImpact,
+  countTicks,
   cursorTranscriptPath,
+  decideHandoff,
   decideStop,
   type EditHintInput,
   type EditTrackRow,
   editHintFor,
   editTrackPath,
+  fileAtRevision,
   GIT_AUTONOMY_COMMIT_POLICY,
   GIT_AUTONOMY_PLUGIN_FILE,
   GIT_AUTONOMY_PLUGIN_NAME,
@@ -35,15 +39,24 @@ export {
   type GitAutonomyStatus,
   type GitAutonomyToolRewrite,
   gitAutonomyStatus,
+  type HandoffDecision,
+  type HandoffPlanFile,
   type HintFireRow,
   type HintImpact,
+  handoffBaseSha,
+  handoffBlockMessage,
+  handoffDedupeKey,
   hasBugMarker,
+  hasHandoffLiteral,
   hintLogDir,
   hintLogPath,
   hookTsMs,
   isBugfixCommit,
   isCodexPayload,
   isCursorPayload,
+  isPlanPath,
+  memHasHandoffForPlan,
+  mergeStopReasons,
   mvGuardDecision,
   type NormalizedStopInput,
   normalizeStopInput,
@@ -64,9 +77,11 @@ export {
   SESSION_START_MAX_CHARS,
   type StopClient,
   sessionKey,
+  sessionPlanFiles,
   sessionStartContext,
   stopBlockedBefore,
   stopBlockPath,
+  stopBlockSurface,
   stopOutput,
   utcStamp,
   worktreeKey,

package/src/install/antigravity.ts

@@ -5,9 +5,10 @@
 // Skills path). No hooks in the first phase — Antigravity's hook surface is
 // still evolving.
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { defaultCheckCmd } from "../setup.js";
 import { agentsSkillsDir, linkSkills, reportSkills } from "./skills.js";
 import {
   CURSOR_MCP_ENTRY,
@@ -33,7 +34,9 @@ function isFaponyEntry(entry: unknown): boolean {
 
 function readJsonObject(path: string): Record<string, unknown> | null {
   try {
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    const raw = readFileSync(path, "utf-8").trim();
+    if (!raw) return {};
+    const parsed: unknown = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return null;
     }
@@ -49,14 +52,20 @@ export function cmdInstallAntigravity(
 ): void {
   const exitFn = deps.exit ?? defaultExit;
   const getHome = deps.homedir ?? homedir;
-  const geminiDir = findGeminiDir(getHome);
+  const checkCmd = deps.checkCmd ?? defaultCheckCmd;
+  let geminiDir = findGeminiDir(getHome);
 
   if (!geminiDir) {
-    console.error(
-      `Antigravity not found — open Antigravity at least once to create ~/.gemini`,
-    );
-    exitFn(1);
-    return;
+    // Detect signal #2: the `agy` CLI on PATH — installed but never launched,
+    // so ~/.gemini doesn't exist yet; the write path below creates it.
+    if (!checkCmd("agy")) {
+      console.error(
+        `Antigravity not found — open Antigravity at least once to create ~/.gemini (or put the agy CLI on PATH)`,
+      );
+      exitFn(1);
+      return;
+    }
+    geminiDir = join(getHome(), ".gemini");
   }
 
   // --- 1. MCP server (mcpServers.fapony in ~/.gemini/config/mcp_config.json) ---
@@ -99,6 +108,10 @@ export function cmdInstallAntigravity(
         `── dry-run: would ${mcpIsNew ? "create" : "write"} ${mcpPath}${mcpIsNew ? "" : ` (mcpServers.${MCP_KEY})`} ──`,
       );
     } else {
+      // Escape hatch (plan §5): ~/.gemini/config may not exist yet — either
+      // the app never got as far as its config dir, or agy-on-PATH created
+      // nothing. Recursive mkdir is idempotent and non-destructive.
+      mkdirSync(configDir, { recursive: true });
       writeFileSync(mcpPath, `${JSON.stringify(after, null, 2)}\n`, "utf-8");
       console.error(`✓ added mcpServers.${MCP_KEY} to ${mcpPath}`);
       console.error(`  restart Antigravity to load the MCP server`);

package/src/install/detect.ts

@@ -1,7 +1,7 @@
 // src/install/detect.ts — detect which MCP clients are installed on this machine.
 //
 // Signal per client:
-//   antigravity = ~/.gemini exists (the app creates it on first run)
+//   antigravity = ~/.gemini exists (the app creates it on first run) OR `agy` on PATH
 //   claude      = `command -v claude` (CLI on PATH)
 //   cursor      = ~/.cursor exists (the app creates it on first run)
 //   opencode    = ~/.config/opencode/{opencode.json,opencode.jsonc} exists
@@ -28,14 +28,15 @@ export interface DetectedClient {
  * Returns one entry per platform, ordered: antigravity, claude, cursor, opencode, zcode, codex.
  *
  * Uses resolvers from each provider (file/dir-exists check) for
- * antigravity/cursor/opencode/zcode/codex, and `command -v claude` for claude — all
- * through injected deps for testability.
+ * antigravity/cursor/opencode/zcode/codex, and `command -v claude`/`command -v agy`
+ * for claude/antigravity — all through injected deps for testability.
  */
 export function detectClients(deps: InstallDeps = {}): DetectedClient[] {
   const getHome = deps.homedir ?? homedir;
   const checkCmd = deps.checkCmd ?? defaultCheckCmd;
 
   const claude = checkCmd("claude");
+  const agy = checkCmd("agy");
 
   const geminiDir = findGeminiDir(getHome);
   const cursorDir = findCursorDir(getHome);
@@ -46,10 +47,12 @@ export function detectClients(deps: InstallDeps = {}): DetectedClient[] {
   return [
     {
       platform: "antigravity",
-      installed: geminiDir !== null,
+      installed: geminiDir !== null || agy,
       why: geminiDir
         ? `dir at ${geminiDir}`
-        : "no ~/.gemini directory (open Antigravity once)",
+        : agy
+          ? "agy CLI on PATH"
+          : "no ~/.gemini directory (open Antigravity once)",
     },
     {
       platform: "claude",

package/src/install/opencode.ts

@@ -271,6 +271,9 @@ export const FaponyReadHint = async ({ directory }) => {
           if (ctx.memLines.length > 0) {
             recordHintFire({ ts: new Date().toISOString(), worktree: ctx.worktree, surface: "mem", file: rel, count: ctx.memLines.length });
           }
+          if (ctx.openBugIds.length > 0) {
+            recordHintFire({ ts: new Date().toISOString(), worktree: ctx.worktree, surface: "open-bug", file: rel, count: ctx.openBugIds.length, ids: ctx.openBugIds });
+          }
         }
       } catch {
         // a hint must never break a read
@@ -412,6 +415,9 @@ export const FaponyEditHint = async ({ directory }) => {
               if (ctx?.memLines?.length) {
                 recordHintFire({ ts: new Date().toISOString(), worktree, surface: "mem", file: rel, count: ctx.memLines.length });
               }
+              if (ctx?.openBugIds?.length) {
+                recordHintFire({ ts: new Date().toISOString(), worktree, surface: "open-bug", file: rel, count: ctx.openBugIds.length, ids: ctx.openBugIds });
+              }
             }
           } catch {
             // best-effort

package/src/install.ts

@@ -1,4 +1,4 @@
-// src/install.ts — `fapony install --platform opencode|claude|cursor|zcode|codex` command.
+// src/install.ts — `fapony install --platform antigravity|agy|opencode|claude|cursor|zcode|codex` command.
 // opencode: adds mcp.fapony config to ~/.config/opencode/opencode.json or opencode.jsonc.
 // claude: shells out to `claude mcp add` (never parses/writes ~/.claude.json directly).
 // cursor: writes mcpServers.fapony to ~/.cursor/mcp.json directly and merges the
@@ -59,7 +59,9 @@ export async function cmdInstall(
   args: string[],
   deps: InstallDeps = {},
 ): Promise<void> {
-  const platform = args.find((a) => !a.startsWith("--"));
+  const platformArg = args.find((a) => !a.startsWith("--"));
+  // `agy` = Antigravity's CLI name — alias, same provider.
+  const platform = platformArg === "agy" ? "antigravity" : platformArg;
   const dryRun = args.includes("--dry-run");
   const installAll = args.includes("--all");
   // Opt-in only: the git-autonomy rewrite is an opinion (commit-as-you-go),
@@ -96,10 +98,10 @@ export async function cmdInstall(
   }
   if (platform !== undefined) {
     console.error(
-      `usage: fapony install --platform antigravity|opencode|claude|cursor|zcode|codex [--dry-run] [--git-autonomy] [--plugins-only]`,
+      `usage: fapony install --platform antigravity|agy|opencode|claude|cursor|zcode|codex [--dry-run] [--git-autonomy] [--plugins-only]`,
     );
     console.error(
-      `  supported platforms: antigravity, opencode, claude, cursor, zcode, codex`,
+      `  supported platforms: antigravity (agy), opencode, claude, cursor, zcode, codex`,
     );
     (deps.exit ?? defaultExit)(1);
     return;

package/src/map.ts

@@ -167,10 +167,230 @@ function braceNames(
 
 const VAR_DECL_RE = /^export\s+(?:const|let|var)\b/;
 
+// --- Python exports (no parser: Bun.Transpiler can't read .py, and shelling
+// out to `python -c "import ast"` was cut — a subprocess per file blows the
+// measured budgets (buildGraph ~50ms/150 files, review-seed 0.31–0.51s
+// uncached) and breaks the Bun-only constraint. Line-based, top level only.)
+
+const PY_DEF_RE = /^(?:async\s+)?def\s+([A-Za-z_]\w*)/;
+const PY_CLASS_RE = /^class\s+([A-Za-z_]\w*)/;
+// `x = …` and `x: T = …` — `=(?!=)` keeps `==`/`!=`/`>=` comparisons out.
+const PY_ASSIGN_RE = /^([A-Za-z_]\w*)\s*(?::\s*[^=;#]+?)?=(?!=)/;
+const PY_FROM_RE = /^from\s+(\S+)\s+import\s+(.+)$/;
+const PY_ALL_RE = /^__all__\s*=/;
+
+// Walk one line tracking quote state; returns the code before a `#` comment.
+// Triple quotes are handled for the single-line case (`x = """a#b"""`) —
+// multi-line strings are skipped by the block tracker below, not here.
+function stripPyComment(line: string): string {
+  let quote: string | null = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === "\\") {
+        i++;
+        continue;
+      }
+      if (line.startsWith(quote, i)) {
+        i += quote.length - 1;
+        quote = null;
+      }
+      continue;
+    }
+    if (c === "#") return line.slice(0, i);
+    if (line.startsWith('"""', i) || line.startsWith("'''", i)) {
+      quote = line.slice(i, i + 3);
+      i += 2;
+    } else if (c === '"' || c === "'") {
+      quote = c;
+    }
+  }
+  return line;
+}
+
+// Blank out triple-quoted string blocks, preserving the line count, so a
+// line-based scan never reads code (`def`, `from .x import y`) out of a
+// docstring or a multi-line string. Code before an opening `"""` on the same
+// line is kept; the block itself and its closing line become empty. Single
+// source of truth for both the export scan (below) and analyze's import scan.
+// First triple quote that is NOT inside a single/double-quoted string on this
+// line — so `x = 'has """ inside'` never opens a block. `stripPyComment` walks
+// the same quote state; this reports where a block actually starts.
+function unquotedTriple(code: string): { at: number; q: string } | null {
+  let quote: string | null = null;
+  for (let i = 0; i < code.length; i++) {
+    const c = code[i];
+    if (quote) {
+      if (c === "\\") {
+        i++;
+        continue;
+      }
+      if (code.startsWith(quote, i)) {
+        i += quote.length - 1;
+        quote = null;
+      }
+      continue;
+    }
+    if (code.startsWith('"""', i) || code.startsWith("'''", i))
+      return { at: i, q: code.slice(i, i + 3) };
+    if (c === '"' || c === "'") quote = c;
+  }
+  return null;
+}
+
+export function maskPyBlocks(source: string): string {
+  const out: string[] = [];
+  let block: string | null = null;
+  for (const raw of source.split("\n")) {
+    if (block) {
+      const end = raw.indexOf(block);
+      if (end < 0) {
+        out.push("");
+        continue;
+      }
+      block = null;
+      out.push(raw.slice(end + 3));
+      continue;
+    }
+    const code = stripPyComment(raw);
+    const triple = unquotedTriple(code);
+    if (triple) {
+      const { at, q } = triple;
+      if (code.indexOf(q, at + 3) < 0) {
+        block = q;
+        out.push(code.slice(0, at));
+        continue;
+      }
+    }
+    out.push(raw);
+  }
+  return out.join("\n");
+}
+
+// String literals inside an `__all__ = [...]` (or `(...)`) assignment,
+// possibly spanning lines. Anything dynamic (`append`, `+=`, a variable)
+// yields nothing — the caller falls back to every top-level name.
+function pyAllNames(text: string): string[] {
+  const open =
+    text.indexOf("[") >= 0 ? "[" : text.indexOf("(") >= 0 ? "(" : null;
+  if (!open) return [];
+  const close = open === "[" ? "]" : ")";
+  const body = text.slice(text.indexOf(open) + 1);
+  if (!body.includes(close)) return [];
+  const out: string[] = [];
+  for (const m of body.matchAll(/["']([A-Za-z_]\w*)["']/g)) out.push(m[1]);
+  return out;
+}
+
+function pyFromNames(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 as = part.split(/\s+as\s+/);
+    const name = as[as.length - 1].trim();
+    if (/^[A-Za-z_]\w*$/.test(name)) out.push(name);
+  }
+  return out;
+}
+
+export function extractPythonExports(source: string): ExportScan {
+  // Blank docstrings/strings first, preserving line numbers — a `def` inside
+  // a docstring is sample text, the same blind spot the TS path closes with
+  // the parse gate.
+  const lines = maskPyBlocks(source).split("\n");
+  const found = new Map<string, { line: number; kind: ExportKind }>();
+  let allNames: string[] = [];
+  let allLine = 0;
+
+  const remember = (name: string, line: number, kind: ExportKind): void => {
+    if (!found.has(name)) found.set(name, { line, kind });
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const code = stripPyComment(raw).trimEnd();
+    if (code === "") continue;
+    if (/^\s/.test(raw)) continue; // indented — not top level
+    const t = code.trim();
+    let m: RegExpMatchArray | null;
+    if ((m = t.match(PY_DEF_RE))) {
+      remember(m[1], i + 1, "fn");
+      continue;
+    }
+    if ((m = t.match(PY_CLASS_RE))) {
+      remember(m[1], i + 1, "class");
+      continue;
+    }
+    if (PY_ALL_RE.test(t)) {
+      // `__all__` may span lines — join until the bracket closes (cap 20).
+      let joined = t;
+      let j = i;
+      while (!/[\])]/.test(joined) && j + 1 < lines.length && j - i < 20) {
+        j++;
+        joined += ` ${stripPyComment(lines[j]).trim()}`;
+      }
+      allNames = pyAllNames(joined);
+      allLine = i + 1;
+      i = j;
+      continue;
+    }
+    if ((m = t.match(PY_FROM_RE))) {
+      // Parenthesized lists often span lines — join until they close (cap 20),
+      // the same shape as the TS brace-block join above.
+      let rest = m[2];
+      let j = i;
+      const unbalanced = (s: string): boolean =>
+        (s.match(/\(/g) ?? []).length > (s.match(/\)/g) ?? []).length;
+      while (unbalanced(rest) && j + 1 < lines.length && j - i < 20) {
+        j++;
+        rest += ` ${stripPyComment(lines[j]).trim()}`;
+      }
+      for (const name of pyFromNames(rest)) remember(name, i + 1, "re-export");
+      i = j;
+      continue;
+    }
+    if (/^import\s+/.test(t)) continue; // graph data, not an export
+    if ((m = t.match(PY_ASSIGN_RE))) {
+      if (m[1] === "__all__") continue;
+      remember(m[1], i + 1, "const");
+    }
+  }
+
+  if (allNames.length > 0) {
+    // `__all__` is authoritative: undocumented underscore names listed there
+    // are public, and anything not listed is not — including real defs.
+    const out: ExportSymbol[] = [];
+    const seen = new Set<string>();
+    for (const name of allNames) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      const f = found.get(name);
+      out.push(
+        f
+          ? { name, line: f.line, kind: f.kind }
+          : { name, line: allLine, kind: "re-export" },
+      );
+    }
+    return { symbols: out, error: null };
+  }
+  // No `__all__`: underscore-prefixed names are private by convention.
+  return {
+    symbols: [...found]
+      .filter(([name]) => !name.startsWith("_"))
+      .map(([name, f]) => ({ name, line: f.line, kind: f.kind })),
+    error: null,
+  };
+}
+
 export function extractExports(
   source: string,
   scanner?: ExportScanner,
+  filename?: string,
 ): ExportScan {
+  if (filename?.endsWith(".py") || filename?.endsWith(".pyi"))
+    return extractPythonExports(source);
   const s = scanner ?? getDefaultScanner();
   const scanned = scanSource(source, s);
   if (scanned.error) return { symbols: [], error: scanned.error };