@mandujs/core 0.23.0 → 0.24.0

package/src/bundler/dev.ts

@@ -15,6 +15,11 @@ import type {
   HMRReplayEnvelope,
 } from "./hmr-types";
 import { MAX_REPLAY_BUFFER, REPLAY_MAX_AGE_MS } from "./hmr-types";
+import {
+  ReverseImportGraph,
+  scanFileImports,
+  DEFAULT_MAX_CLOSURE_DEPTH,
+} from "./reverse-import-graph";
 import path from "path";
 import fs from "fs";
 
@@ -312,6 +317,9 @@ export const _testOnly_DEFAULT_COMMON_DIRS = DEFAULT_COMMON_DIRS;
 /** Test-only accessor for the watch exclude segments (B1 coverage). */
 export const _testOnly_WATCH_EXCLUDE_SEGMENTS = WATCH_EXCLUDE_SEGMENTS;
 
+/** Test-only re-export for #189 reverse import-graph coverage. */
+export { ReverseImportGraph, scanFileImports } from "./reverse-import-graph";
+
 /**
  * Phase 7.0 R2 Agent D — classification helper mirroring the in-bundler
  * `classifyBatch` priority rules WITHOUT the project-specific maps
@@ -570,6 +578,99 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     await addCommonDir(dir);
   }
 
+  // #189 — reverse import-graph for transitive invalidation.
+  //
+  // Built-time index of `importee -> Set<importer>` edges for every
+  // known SSR / API / client / common-dir root. On an unknown-file
+  // change (a leaf utility that none of our sets recognize) we walk
+  // the transitive importer closure and re-dispatch the change
+  // against every ancestor that IS known — so a deep edit to
+  // `app/_utils/translations/ko.ts` still re-evaluates the barrel
+  // in `app/_utils/translations/index.ts` that imported it.
+  //
+  // The initial population is best-effort (filesystem scan may
+  // surface typed-only stubs that have no source yet); misses simply
+  // keep the legacy "silent drop" behavior so no project is made
+  // worse by turning this on.
+  const reverseGraph = new ReverseImportGraph();
+
+  /**
+   * Re-scan a single file's imports and update its row in the
+   * reverse graph. Called on startup for every known root, and
+   * again each time a file change is dispatched so the graph
+   * tracks refactors (an import being added / removed) in real
+   * time.
+   *
+   * Errors are swallowed — a missing file / permission issue must
+   * not break the HMR dispatch for the rest of the project.
+   */
+  const refreshReverseGraphEdges = async (filePath: string): Promise<void> => {
+    try {
+      const imports = await scanFileImports(filePath);
+      reverseGraph.update(filePath, imports);
+    } catch {
+      // scanFileImports already swallows fs errors; this extra guard
+      // catches anything pathological (e.g. a symlink loop).
+    }
+  };
+
+  /**
+   * Populate the reverse graph transitively from every known root.
+   *
+   * The BFS walks each root's outgoing imports, scans every
+   * discovered intermediate, and keeps going until the frontier is
+   * empty or we hit the depth cap. Without this transitive seed,
+   * a deep edit (root -> barrel -> leaf) would see
+   * `reverseGraph.directImporters(leaf) === {}` because only the
+   * root's edges got recorded — exactly the bug #189 describes.
+   *
+   * The walk is I/O-bound but bounded: each node is visited at most
+   * once (`visited` set) and we cap the seeding at
+   * `DEFAULT_MAX_CLOSURE_DEPTH` hops to keep startup cost predictable
+   * on projects with dense import graphs. Subsequent edits still
+   * extend the graph via `refreshReverseGraphEdges` in `_doBuild`.
+   */
+  const seedReverseGraph = async (): Promise<void> => {
+    const roots = new Set<string>();
+    for (const rootPath of serverModuleSet) roots.add(rootPath);
+    for (const rootPath of apiModuleSet) roots.add(rootPath);
+    for (const rootPath of clientModuleToRoute.keys()) roots.add(rootPath);
+
+    const visited = new Set<string>();
+    let frontier = Array.from(roots);
+
+    for (
+      let depth = 0;
+      depth < DEFAULT_MAX_CLOSURE_DEPTH && frontier.length > 0;
+      depth++
+    ) {
+      // Scan the current frontier in parallel — these are independent
+      // file reads. The scan returns the RESOLVED absolute importee
+      // paths, which become the next frontier.
+      const scans = await Promise.all(
+        frontier.map(async (filePath) => {
+          if (visited.has(filePath)) return [];
+          visited.add(filePath);
+          try {
+            const imports = await scanFileImports(filePath);
+            reverseGraph.update(filePath, imports);
+            return imports;
+          } catch {
+            return [];
+          }
+        }),
+      );
+
+      const next: string[] = [];
+      for (const group of scans) {
+        for (const dep of group) {
+          if (!visited.has(dep)) next.push(dep);
+        }
+      }
+      frontier = next;
+    }
+  };
+
   // 파일 감시 설정
   const watchers: fs.FSWatcher[] = [];
 
@@ -974,9 +1075,157 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     perFileTimers.set(key, timer);
   };
 
+  /**
+   * #189 — dispatch an unknown-file change against every known root
+   * that transitively imports it.
+   *
+   * The reverse graph answers "which SSR / API / client modules end
+   * up depending on this file?" via a bounded BFS closure. Each
+   * matched root is re-dispatched through the SAME callbacks a
+   * direct change would fire (`onSSRChange`, `onAPIChange`, or an
+   * island rebuild), so downstream behavior is identical to a
+   * direct edit. This closes the "transitive ESM cache" gap
+   * described in issue #189 by making sure every ancestor that
+   * consumed the leaf gets its bundle rebuilt / handler re-
+   * registered.
+   *
+   * Returns the number of roots actually dispatched so the caller
+   * can decide whether to log a "no transitive importers" line or
+   * stay silent. Dispatch is idempotent — each root is touched at
+   * most once per change via the `dispatched` set.
+   */
+  const dispatchByTransitiveImporters = async (
+    changedFile: string,
+  ): Promise<number> => {
+    const absChanged = path.resolve(rootDir, changedFile);
+    // Refresh the changed file's OWN imports first. A leaf edit can
+    // legitimately add or remove imports (e.g. switching a barrel
+    // from `./en` to `./ko`); the reverse graph must track that so
+    // the NEXT unknown-file change uses the correct set.
+    await refreshReverseGraphEdges(absChanged);
+
+    const importers = reverseGraph.transitiveImporters(
+      absChanged,
+      DEFAULT_MAX_CLOSURE_DEPTH,
+    );
+    if (importers.size === 0) return 0;
+
+    // Partition importers by which known-root bucket they belong
+    // to. A single file can be in multiple buckets (e.g. a shared
+    // `.client.tsx` that is also referenced by a server module) —
+    // iterate in priority order: SSR first (heaviest signal), then
+    // API, then client islands.
+    const ssrRoots: string[] = [];
+    const apiRoots: string[] = [];
+    const islandRoots: Array<{ routeId: string; path: string }> = [];
+
+    for (const importerAbs of importers) {
+      if (serverModuleSet.has(importerAbs)) {
+        ssrRoots.push(importerAbs);
+        continue;
+      }
+      if (apiModuleSet.has(importerAbs)) {
+        apiRoots.push(importerAbs);
+        continue;
+      }
+      const islandRouteId = clientModuleToRoute.get(importerAbs);
+      if (islandRouteId) {
+        islandRoots.push({ routeId: islandRouteId, path: importerAbs });
+      }
+    }
+
+    const totalMatched = ssrRoots.length + apiRoots.length + islandRoots.length;
+    if (totalMatched === 0) return 0;
+
+    const relFile = path.relative(rootDir, absChanged).replace(/\\/g, "/");
+    console.log(
+      `\n🔄 ${path.basename(changedFile)} changed — invalidating ${totalMatched} transitive importer(s) (${relFile})`,
+    );
+
+    // SSR: fire once per distinct importer path.
+    if (onSSRChange) {
+      for (const ssrRoot of ssrRoots) {
+        try {
+          await Promise.resolve(onSSRChange(ssrRoot));
+        } catch (err) {
+          console.error(
+            "[Mandu HMR] transitive onSSRChange threw:",
+            err instanceof Error ? err.message : String(err),
+          );
+        }
+      }
+    }
+
+    // API: same pattern.
+    if (onAPIChange) {
+      for (const apiRoot of apiRoots) {
+        try {
+          await Promise.resolve(onAPIChange(apiRoot));
+        } catch (err) {
+          console.error(
+            "[Mandu HMR] transitive onAPIChange threw:",
+            err instanceof Error ? err.message : String(err),
+          );
+        }
+      }
+    }
+
+    // Islands: coalesce to a single build call when multiple routes
+    // share the changed file. `buildClientBundles` with a
+    // `targetRouteIds` list already dedupes internally.
+    if (islandRoots.length > 0) {
+      const targetIds = Array.from(new Set(islandRoots.map((r) => r.routeId)));
+      const startTime = performance.now();
+      try {
+        const result = await buildClientBundles(manifest, rootDir, {
+          minify: false,
+          sourcemap: true,
+          targetRouteIds: targetIds,
+        });
+        const buildTime = performance.now() - startTime;
+        if (result.success) {
+          console.log(
+            `✅ Rebuilt ${targetIds.length} island(s) in ${buildTime.toFixed(0)}ms`,
+          );
+          for (const targetId of targetIds) {
+            onRebuild?.({
+              routeId: targetId,
+              success: true,
+              buildTime,
+            });
+          }
+        } else {
+          console.error("❌ Transitive island rebuild failed:", result.errors);
+          for (const targetId of targetIds) {
+            onRebuild?.({
+              routeId: targetId,
+              success: false,
+              buildTime,
+              error: result.errors.join(", "),
+            });
+          }
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        console.error("❌ Transitive island rebuild error:", err.message);
+        for (const { routeId: targetId } of islandRoots) {
+          onError?.(err, targetId);
+        }
+      }
+    }
+
+    return totalMatched;
+  };
+
   const _doBuild = async (changedFile: string) => {
     const normalizedPath = normalizeFsPath(changedFile);
 
+    // #189 — refresh the changed file's imports so the reverse graph
+    // tracks refactors regardless of which dispatch path fires below.
+    // Fire-and-forget because the scan is I/O-bound and the dispatch
+    // path cannot stall on it.
+    void refreshReverseGraphEdges(path.resolve(rootDir, changedFile));
+
     // 공통 컴포넌트 디렉토리 변경 → Island만 재빌드 + SSR 레지스트리 invalidate (#184, #185)
     if (isInCommonDir(changedFile)) {
       console.log(`\n🔄 Common file changed: ${path.basename(changedFile)}`);
@@ -1053,12 +1302,16 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
       // SSR 모듈 변경 감지 (page.tsx, layout.tsx) — #151
       if (onSSRChange && serverModuleSet.has(normalizedPath)) {
         console.log(`\n🔄 SSR file changed: ${path.basename(changedFile)}`);
+        // Refresh the changed file's imports so the reverse graph
+        // tracks refactors (a new import added to an SSR module).
+        await refreshReverseGraphEdges(path.resolve(rootDir, changedFile));
         onSSRChange(normalizedPath);
         return;
       }
       // API 모듈 변경 감지 (route.ts)
       if (onAPIChange && apiModuleSet.has(normalizedPath)) {
         console.log(`\n🔄 API route changed: ${path.basename(changedFile)}`);
+        await refreshReverseGraphEdges(path.resolve(rootDir, changedFile));
         onAPIChange(normalizedPath);
         return;
       }
@@ -1070,7 +1323,23 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
       // reuse its existing `handleAPIChange` plumbing.
       if (onAPIChange && isRouteMiddlewareFile(normalizedPath)) {
         console.log(`\n🔄 Middleware changed: ${path.basename(changedFile)}`);
+        await refreshReverseGraphEdges(path.resolve(rootDir, changedFile));
         onAPIChange(normalizedPath);
+        return;
+      }
+      // #189 — reverse import-graph fallback.
+      //
+      // The changed file matched none of our direct dispatch sets.
+      // Before silently dropping (legacy behavior), walk the
+      // reverse graph to see which known roots transitively import
+      // this file and re-dispatch against each one. This is what
+      // makes a deep leaf edit (e.g. a barrel's static-map entry)
+      // propagate without a manual restart.
+      const dispatched = await dispatchByTransitiveImporters(changedFile);
+      if (dispatched === 0) {
+        // No known importer — preserve the legacy silent-drop path
+        // so truly unrelated file changes (editor backups, tmp
+        // files that slipped through the filter) stay cheap.
       }
       return;
     }
@@ -1078,6 +1347,12 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     const route = manifest.routes.find((r) => r.id === routeId);
     if (!route || !route.clientModule) return;
 
+    // #189 — refresh the client island's outgoing imports so the
+    // reverse graph tracks newly added / removed imports in the
+    // island file itself. Fire-and-forget so it cannot stall the
+    // rebuild.
+    void refreshReverseGraphEdges(path.resolve(rootDir, changedFile));
+
     console.log(`\n🔄 Rebuilding island: ${routeId}`);
     const startTime = performance.now();
 
@@ -1223,6 +1498,19 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     }
   }
 
+  // #189 — seed the reverse import-graph AFTER watchers are wired so
+  // any edit that lands during the scan still triggers `handleFileChange`.
+  // The scan is fire-and-forget; the initial build is already complete
+  // and the first user edit can't race the seed (first event goes
+  // through the 100 ms debounce, by which point the scan has finished
+  // for any realistic project size).
+  seedReverseGraph().catch((err) => {
+    console.warn(
+      "[Mandu HMR] reverse import-graph seed skipped:",
+      err instanceof Error ? err.message : String(err),
+    );
+  });
+
   return {
     initialBuild,
     close: () => {

package/src/bundler/reverse-import-graph.ts

@@ -0,0 +1,339 @@
+/**
+ * ReverseImportGraph — #189
+ *
+ * Tracks `importee -> Set<importer>` edges so the dev watcher can answer
+ * "which user modules transitively import this file?" when a file change
+ * misses every known root set (SSR / API / client / common-dir).
+ *
+ * # Why this exists
+ *
+ * Bun caches ES modules at the process level. When a common/shared file
+ * changes, `dev.ts` re-imports that file fresh, but intermediate modules
+ * that reference it transitively may retain their cached form. The three
+ * real-world patterns flagged in #189:
+ *
+ *   1. Barrel + static map — `index.ts` builds a lookup at module load,
+ *      so a new entry in a leaf `translations/ko.ts` never shows up until
+ *      the intermediate barrel is re-evaluated.
+ *   2. Deep re-export chain — `A -> B -> C -> D`. A single edit to `D`
+ *      requires every ancestor to be refreshed.
+ *   3. Module-level singletons / registries whose state is captured at
+ *      import time.
+ *
+ * The existing watcher dispatches only when the changed path itself is in
+ * `serverModuleSet` / `apiModuleSet` / `clientModuleToRoute` / a common
+ * dir. For files that live elsewhere — `app/lib/helper.ts`,
+ * `app/_utils/translations/ko.ts`, etc. — the event falls through and
+ * the user sees stale output until a manual restart.
+ *
+ * # Design
+ *
+ * - `edges: Map<importee -> Set<importer>>` — reverse index.
+ * - `forward: Map<importer -> Set<importee>>` — kept so that a
+ *   subsequent `update(importer, newImports)` can tear down stale edges
+ *   without iterating the full reverse map.
+ * - BFS closure for `transitiveImporters(file, maxDepth)` with an
+ *   explicit visited set and a defensive depth cap (default 10) to
+ *   prevent pathological full-graph walks on projects with dense
+ *   cyclic imports. Every node visited at depth d+1 is checked against
+ *   `visited` BEFORE enqueue so cycles terminate.
+ * - All keys are normalized OS-native absolute paths, lowercased on win32
+ *   so fs.watch events match regardless of drive-letter casing.
+ * - The scanner is a conservative regex over `import ... from "…"`,
+ *   `export ... from "…"`, and dynamic `import("…")`. We intentionally
+ *   skip a full AST parse — the goal is "catch the common case cheaply"
+ *   and the static table never drives code generation, only invalidation
+ *   routing. A false-negative means the change falls through the existing
+ *   silent-drop path (unchanged behavior); a false-positive triggers an
+ *   extra rebuild (acceptable cost).
+ * - Only first-party (relative / alias-resolvable) imports are recorded.
+ *   Bare `react`, `@mandujs/core`, etc. are skipped so the graph never
+ *   tracks node_modules.
+ *
+ * # What this does NOT do
+ *
+ * - Does not resolve TypeScript path aliases from `tsconfig.json`. A
+ *   future pass can wire the `compilerOptions.paths` map in, but the
+ *   relative-import case covers the scenarios in the issue.
+ * - Does not track CSS `@import` — the CSS-update path already has its
+ *   own mechanism in `dev.ts`.
+ * - Does not persist. In-memory only; rebuilt from scratch on dev-server
+ *   start.
+ */
+
+import fs from "fs";
+import path from "path";
+
+/**
+ * Default safety cap for `transitiveImporters` BFS. 10 hops is deep
+ * enough for any realistic barrel chain while stopping cold on
+ * degenerate graphs (e.g. a project with everything re-exporting
+ * everything).
+ */
+export const DEFAULT_MAX_CLOSURE_DEPTH = 10;
+
+/** Normalize an fs path to the form the watcher emits (forward slash, lowercase on win32). */
+function normalize(p: string): string {
+  const abs = path.resolve(p).replace(/\\/g, "/");
+  return process.platform === "win32" ? abs.toLowerCase() : abs;
+}
+
+/**
+ * Return true for a specifier that points at a first-party module we
+ * can resolve on disk. Bare specifiers (`react`, `@scope/pkg`) are
+ * filtered out so the graph never grows with node_modules edges.
+ */
+function isFirstPartySpecifier(spec: string): boolean {
+  if (spec.length === 0) return false;
+  // `./foo`, `../bar`, `/abs/path` — first-party for sure.
+  if (spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/")) {
+    return true;
+  }
+  // Windows absolute path. `fs.watch` never emits this shape, but a
+  // user file could in theory reference one — reject for the same
+  // reason we reject node_modules: the file isn't in the reactive tree.
+  if (/^[A-Za-z]:[\\/]/.test(spec)) return false;
+  // Everything else — bare module — is external.
+  return false;
+}
+
+/**
+ * Extensions we try (in order) when a specifier has no explicit
+ * extension. Mirrors the set Bun itself would walk for a relative
+ * import inside the monorepo.
+ */
+const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"] as const;
+
+/**
+ * Resolve a relative specifier from `fromFile`'s directory to an
+ * absolute on-disk path. Returns `null` when the target cannot be
+ * found (e.g. a typed-only stub, a file the user has not yet
+ * written). Callers treat `null` as "skip this edge".
+ *
+ * Exported for tests; production code uses it via `scanFileImports`.
+ */
+export function resolveRelativeImport(fromFile: string, specifier: string): string | null {
+  if (!isFirstPartySpecifier(specifier)) return null;
+  const fromDir = path.dirname(fromFile);
+  const base = path.resolve(fromDir, specifier);
+  // If the path already has a recognized extension, test it directly.
+  if (RESOLVE_EXTENSIONS.some((e) => base.endsWith(e))) {
+    return fs.existsSync(base) ? base : null;
+  }
+  // Try each extension + `/index.<ext>` so barrel directories resolve.
+  for (const ext of RESOLVE_EXTENSIONS) {
+    const candidate = base + ext;
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  for (const ext of RESOLVE_EXTENSIONS) {
+    const candidate = path.join(base, "index" + ext);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// Static-import, export-from, and dynamic import patterns. Written
+// conservatively: each regex consumes a single pair of matching quotes,
+// never spans newlines, and does not attempt to handle template literals
+// (dynamic `import(\`…\`)` with interpolation is inherently unresolvable
+// statically).
+const IMPORT_PATTERNS: readonly RegExp[] = [
+  // `import foo from "…"` / `import { x } from "…"` / `import "…"` / `import type { x } from "…"`
+  /\bimport\s+(?:type\s+)?(?:[^'"\n;]*?\bfrom\s+)?['"]([^'"\n]+)['"]/g,
+  // `export { x } from "…"` / `export * from "…"`
+  /\bexport\s+(?:\*|\{[^}]*\})\s+from\s+['"]([^'"\n]+)['"]/g,
+  // `import("…")` — dynamic. Template literals (`) intentionally excluded.
+  /\bimport\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g,
+];
+
+/**
+ * Scan a file's source text for first-party import specifiers. Returns
+ * the raw specifiers (not resolved). Callers usually pair this with
+ * `resolveRelativeImport` to get absolute paths.
+ *
+ * The parser is intentionally regex-based — we do not want to pay the
+ * cost of a full AST traverse on every file change. See the module
+ * header for the false-positive/negative trade-off.
+ */
+export function extractImportSpecifiers(source: string): string[] {
+  const out = new Set<string>();
+  for (const pattern of IMPORT_PATTERNS) {
+    // Reset lastIndex — the regex has `/g` so reuse across calls would
+    // otherwise skip matches in later invocations.
+    pattern.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(source)) !== null) {
+      const spec = match[1];
+      if (typeof spec === "string" && spec.length > 0) out.add(spec);
+    }
+  }
+  return Array.from(out);
+}
+
+/**
+ * Read a file from disk and return the absolute paths of every
+ * resolvable first-party import it contains. Non-existent files and
+ * unreadable files both return an empty array (treated as "no edges
+ * to record"). Async so the dev server can batch this work off the
+ * main event loop.
+ */
+export async function scanFileImports(filePath: string): Promise<string[]> {
+  let source: string;
+  try {
+    source = await fs.promises.readFile(filePath, "utf-8");
+  } catch {
+    return [];
+  }
+  const specifiers = extractImportSpecifiers(source);
+  const out: string[] = [];
+  for (const spec of specifiers) {
+    const resolved = resolveRelativeImport(filePath, spec);
+    if (resolved) out.push(resolved);
+  }
+  return out;
+}
+
+/**
+ * Reverse-import graph with a bounded BFS closure API. All public
+ * methods accept raw paths; normalization is applied internally.
+ */
+export class ReverseImportGraph {
+  /** importee -> set of direct importers. */
+  private readonly edges = new Map<string, Set<string>>();
+  /** importer -> set of direct importees. Kept so `update` is O(|old imports|). */
+  private readonly forward = new Map<string, Set<string>>();
+
+  /**
+   * Replace the outgoing edges for `importerFile`. Any prior importees
+   * that no longer appear drop the importer from their reverse set so
+   * the graph doesn't accumulate stale pointers.
+   */
+  update(importerFile: string, importeePaths: Iterable<string>): void {
+    const importer = normalize(importerFile);
+
+    // Tear down the previous forward entries.
+    const prev = this.forward.get(importer);
+    if (prev) {
+      for (const importee of prev) {
+        const back = this.edges.get(importee);
+        if (!back) continue;
+        back.delete(importer);
+        if (back.size === 0) this.edges.delete(importee);
+      }
+    }
+
+    // Build the new forward entry + reverse edges. We normalize inside
+    // the loop so the caller can pass unnormalized paths.
+    const next = new Set<string>();
+    for (const raw of importeePaths) {
+      const importee = normalize(raw);
+      // Self-edges would create a trivial cycle the BFS has to skip.
+      // Drop them at insert time so the visited-check is the only
+      // cycle defense we need downstream.
+      if (importee === importer) continue;
+      next.add(importee);
+      let back = this.edges.get(importee);
+      if (!back) {
+        back = new Set<string>();
+        this.edges.set(importee, back);
+      }
+      back.add(importer);
+    }
+    if (next.size === 0) {
+      this.forward.delete(importer);
+    } else {
+      this.forward.set(importer, next);
+    }
+  }
+
+  /** Forget a single importer. Reverse edges pointing at its importees are cleaned up. */
+  remove(importerFile: string): void {
+    const importer = normalize(importerFile);
+    const prev = this.forward.get(importer);
+    if (!prev) return;
+    for (const importee of prev) {
+      const back = this.edges.get(importee);
+      if (!back) continue;
+      back.delete(importer);
+      if (back.size === 0) this.edges.delete(importee);
+    }
+    this.forward.delete(importer);
+  }
+
+  /** Direct importers of `file` — the single-hop reverse lookup. */
+  directImporters(file: string): ReadonlySet<string> {
+    const set = this.edges.get(normalize(file));
+    return set ?? new Set<string>();
+  }
+
+  /**
+   * Transitive importers of `file`. Returns the normalized set
+   * excluding `file` itself. BFS with cycle detection; every node is
+   * visited at most once. Capped at `maxDepth` hops so a pathological
+   * graph cannot degrade a single file change into a full-project walk.
+   *
+   * Depth 0 is the changed file itself (not included in the result).
+   * Depth 1 is the set returned by `directImporters`. Depth N is the
+   * set of modules whose shortest path to `file` is exactly N hops.
+   */
+  transitiveImporters(
+    file: string,
+    maxDepth: number = DEFAULT_MAX_CLOSURE_DEPTH,
+  ): Set<string> {
+    const target = normalize(file);
+    const result = new Set<string>();
+    // Guard against 0 / negative depth — those are no-ops.
+    if (!Number.isFinite(maxDepth) || maxDepth <= 0) return result;
+
+    let frontier = new Set<string>([target]);
+    const visited = new Set<string>([target]);
+
+    for (let depth = 0; depth < maxDepth && frontier.size > 0; depth++) {
+      const next = new Set<string>();
+      for (const node of frontier) {
+        const directs = this.edges.get(node);
+        if (!directs) continue;
+        for (const importer of directs) {
+          if (visited.has(importer)) continue;
+          visited.add(importer);
+          result.add(importer);
+          next.add(importer);
+        }
+      }
+      frontier = next;
+    }
+    return result;
+  }
+
+  /** True if any edge points at `file`. Useful for fast "do we know this file?" checks. */
+  knows(file: string): boolean {
+    const key = normalize(file);
+    return this.edges.has(key) || this.forward.has(key);
+  }
+
+  /** Drop everything (dev-server restart). */
+  clear(): void {
+    this.edges.clear();
+    this.forward.clear();
+  }
+
+  /** Total number of tracked importer modules (for diagnostics). */
+  get size(): number {
+    return this.forward.size;
+  }
+
+  /**
+   * Dump the current state as plain JSON. Intended for debug
+   * assertions in unit tests, not for production hot paths.
+   */
+  _inspect(): {
+    forward: Record<string, string[]>;
+    reverse: Record<string, string[]>;
+  } {
+    const forward: Record<string, string[]> = {};
+    for (const [k, v] of this.forward) forward[k] = Array.from(v);
+    const reverse: Record<string, string[]> = {};
+    for (const [k, v] of this.edges) reverse[k] = Array.from(v);
+    return { forward, reverse };
+  }
+}