@mandujs/core 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/bundler/build.ts

@@ -16,6 +16,8 @@ import type {
 import { HYDRATION } from "../constants";
 import { safeBuild } from "./safe-build";
 import { fastRefreshPlugin } from "./fast-refresh-plugin";
+import { defaultBundlerPlugins } from "./plugins";
+import type { BunPlugin } from "bun";
 import { mark, measure } from "../perf";
 import { HMR_PERF } from "../perf/hmr-markers";
 import {
@@ -29,6 +31,24 @@ import {
 import path from "path";
 import fs from "fs/promises";
 
+/**
+ * Resolve Mandu's default bundler plugin set from a `BundlerOptions`
+ * object. Currently returns the `mandu:block-generated-imports` plugin
+ * unless `options.blockGeneratedImport === false`. Centralised here so
+ * every `safeBuild(...)` call-site can compose
+ * `[...manduDefaultPlugins(options), ...buildLocalPlugins]` and stay in
+ * sync as the default set grows.
+ */
+function manduDefaultPlugins(options: BundlerOptions): BunPlugin[] {
+  return defaultBundlerPlugins({
+    config: {
+      guard: {
+        blockGeneratedImport: options.blockGeneratedImport,
+      },
+    },
+  });
+}
+
 /**
  * Scan for *.island.tsx / *.island.ts files across hydrated route directories.
  *
@@ -121,7 +141,7 @@ async function buildPerIslandBundle(
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
       ...(isDev ? { reactFastRefresh: true } : {}),
-      plugins: isDev ? [fastRefreshPlugin()] : [],
+      plugins: [...manduDefaultPlugins(options), ...(isDev ? [fastRefreshPlugin()] : [])],
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: { "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"), ...options.define },
     });
@@ -1063,6 +1083,7 @@ if (typeof window !== 'undefined') {
       minify: false, // dev only
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
+      plugins: manduDefaultPlugins(options),
       // React를 인라인 번들링 (import map 없이도 독립 동작)
       // DevTools는 Shadow DOM 격리 → 앱 React와 충돌 없음
       define: {
@@ -1117,6 +1138,7 @@ async function buildRouterRuntime(
       minify: options.minify ?? process.env.NODE_ENV === "production",
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
+      plugins: manduDefaultPlugins(options),
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
         ...options.define,
@@ -1193,6 +1215,7 @@ async function buildRuntime(
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
       external: ["react", "react-dom", "react-dom/client"],
+      plugins: manduDefaultPlugins(options),
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
         ...options.define,
@@ -1482,6 +1505,7 @@ async function buildVendorShims(
         sourcemap: options.sourcemap ? "external" : "none",
         target: "browser",
         external: shimExternal,
+        plugins: manduDefaultPlugins(options),
         define: {
           "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
           ...options.define,
@@ -1590,7 +1614,7 @@ async function buildIsland(
       target: "browser",
       splitting: options.splitting ?? (process.env.NODE_ENV === "production"),
       ...(isDev ? { reactFastRefresh: true } : {}),
-      plugins: isDev ? [fastRefreshPlugin()] : [],
+      plugins: [...manduDefaultPlugins(options), ...(isDev ? [fastRefreshPlugin()] : [])],
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),

package/src/bundler/generate-static-params.ts

@@ -0,0 +1,290 @@
+/**
+ * Mandu — generateStaticParams contract
+ *
+ * Next.js-style `generateStaticParams` lets page modules enumerate which
+ * concrete parameter combinations should be prerendered at build time.
+ *
+ *   ```ts
+ *   // app/docs/[slug]/page.tsx
+ *   export async function generateStaticParams(): Promise<{ slug: string }[]> {
+ *     return [{ slug: "intro" }, { slug: "quickstart" }];
+ *   }
+ *   export default function Page({ params }: { params: { slug: string } }) { ... }
+ *   ```
+ *
+ * This module owns the *contract* side of that feature: introspecting a
+ * page module to invoke `generateStaticParams`, validating the shape of
+ * the returned param sets against the route's dynamic segments, and
+ * resolving each param set into a concrete URL path the prerender
+ * orchestrator can request.
+ *
+ * Router pattern → file-system mapping (kept in sync with
+ * `packages/core/src/router/fs-patterns.ts`):
+ *
+ *   - `[slug]`       → `:slug`    (single required segment)
+ *   - `[...slug]`    → `:slug*`   (catch-all, param value is `string[]`)
+ *   - `[[...slug]]`  → `:slug*?`  (optional catch-all, param value is
+ *                                  `string[]` — empty array resolves to
+ *                                  the prefix path with no trailing
+ *                                  segment)
+ *
+ * The prerender orchestrator in `prerender.ts` composes these helpers
+ * with a user-supplied fetch handler to materialize HTML on disk.
+ */
+
+// Using the same loose pattern vocabulary as the rest of the bundler.
+
+/**
+ * A single param set as returned from `generateStaticParams`. Scalar
+ * params map to a string; catch-all params map to a string array.
+ */
+export type StaticParamSet = Record<string, string | string[]>;
+
+/**
+ * A page module shape we care about. We deliberately avoid importing
+ * the full page-module type here — this module is invoked from the
+ * build orchestrator where modules are dynamic-imported, and the only
+ * thing we need is the optional `generateStaticParams` export.
+ */
+export interface PageModuleWithStaticParams {
+  generateStaticParams?: () => Promise<StaticParamSet[]> | StaticParamSet[];
+}
+
+/**
+ * Structured description of one dynamic segment extracted from a
+ * router pattern. Mirrors the `kind` alphabet we support on disk.
+ */
+export interface DynamicSegment {
+  name: string;
+  kind: "required" | "catchAll" | "optionalCatchAll";
+}
+
+/**
+ * Extract the dynamic segments from a router pattern.
+ *
+ * @example
+ *   extractDynamicSegments("/docs/:slug")        // [{name:"slug", kind:"required"}]
+ *   extractDynamicSegments("/[lang]/:slug")      // malformed, see below
+ *   extractDynamicSegments("/:lang/:slug")       // two required
+ *   extractDynamicSegments("/docs/:slug*")       // one catch-all
+ *   extractDynamicSegments("/docs/:slug*?")      // one optional catch-all
+ *
+ * Only router-style (`:name`, `:name*`, `:name*?`) patterns are
+ * recognized — the `[slug]` file-system syntax is normalized to router
+ * form at scan time (see `fs-patterns.ts`).
+ */
+export function extractDynamicSegments(pattern: string): DynamicSegment[] {
+  const segments: DynamicSegment[] = [];
+  // Match :<name><optional-star><optional-question>
+  const re = /:([A-Za-z_][A-Za-z0-9_]*)(\*)?(\?)?/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(pattern)) !== null) {
+    const [, name, star, question] = match;
+    let kind: DynamicSegment["kind"] = "required";
+    if (star && question) kind = "optionalCatchAll";
+    else if (star) kind = "catchAll";
+    segments.push({ name, kind });
+  }
+  return segments;
+}
+
+/** Whether a router pattern has any dynamic segments at all. */
+export function isDynamicPattern(pattern: string): boolean {
+  return extractDynamicSegments(pattern).length > 0;
+}
+
+/**
+ * Validate that a param set has the right keys and value kinds for a
+ * pattern. Returns a human-readable error message or `null` if OK.
+ *
+ * Rules:
+ *   - Every dynamic segment must have a corresponding key in params.
+ *     (Optional catch-all may be omitted or provided as `[]`.)
+ *   - `required` segments must map to a non-empty string.
+ *   - `catchAll`/`optionalCatchAll` segments must map to a `string[]`
+ *     (or, as a convenience, a single string — interpreted as one
+ *     segment). Required catch-all must be non-empty.
+ */
+export function validateParamSet(
+  pattern: string,
+  params: StaticParamSet
+): string | null {
+  const segments = extractDynamicSegments(pattern);
+  for (const segment of segments) {
+    const value = params[segment.name];
+    if (segment.kind === "required") {
+      if (typeof value !== "string" || value.length === 0) {
+        return `expected string for param "${segment.name}" in pattern "${pattern}", got ${describe(value)}`;
+      }
+      if (value.includes("/")) {
+        return `param "${segment.name}" in pattern "${pattern}" must not contain "/"; use a catch-all segment ([...${segment.name}])`;
+      }
+    } else if (segment.kind === "catchAll") {
+      if (value === undefined || value === null) {
+        return `param "${segment.name}" is required for catch-all pattern "${pattern}"`;
+      }
+      if (Array.isArray(value)) {
+        if (value.length === 0) {
+          return `catch-all param "${segment.name}" in pattern "${pattern}" must not be empty; use [[...${segment.name}]] for optional`;
+        }
+        if (!value.every((v) => typeof v === "string" && v.length > 0)) {
+          return `catch-all param "${segment.name}" must be a non-empty string[] (pattern "${pattern}")`;
+        }
+      } else if (typeof value !== "string" || value.length === 0) {
+        return `catch-all param "${segment.name}" in pattern "${pattern}" must be string[] or non-empty string`;
+      }
+    } else {
+      // optionalCatchAll — may be absent, `[]`, or a populated array.
+      if (value !== undefined && value !== null) {
+        if (Array.isArray(value)) {
+          if (!value.every((v) => typeof v === "string")) {
+            return `optional catch-all "${segment.name}" must be string[] (pattern "${pattern}")`;
+          }
+        } else if (typeof value !== "string") {
+          return `optional catch-all "${segment.name}" must be string[] or string (pattern "${pattern}")`;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve a router pattern + param set into a concrete URL path.
+ *
+ * @example
+ *   resolvePath("/docs/:slug", { slug: "intro" })
+ *     // "/docs/intro"
+ *   resolvePath("/:lang/:slug", { lang: "ko", slug: "intro" })
+ *     // "/ko/intro"
+ *   resolvePath("/docs/:path*", { path: ["guide", "advanced"] })
+ *     // "/docs/guide/advanced"
+ *   resolvePath("/docs/:path*?", { path: [] })
+ *     // "/docs"
+ *   resolvePath("/docs/:path*?", {})
+ *     // "/docs"
+ *
+ * Individual segments are URI-encoded, but slashes between catch-all
+ * segments are preserved.
+ */
+export function resolvePath(pattern: string, params: StaticParamSet): string {
+  let result = pattern;
+
+  // Resolve catch-all (optional + required) first because their regex
+  // (`:name*?`, `:name*`) is a superset of the `:name` pattern. Sort by
+  // longest first to be extra safe when names overlap.
+  const segments = [...extractDynamicSegments(pattern)].sort(
+    (a, b) => b.name.length - a.name.length
+  );
+
+  for (const segment of segments) {
+    const value = params[segment.name];
+
+    if (segment.kind === "optionalCatchAll") {
+      // Pattern is `/prefix/:name*?` — the leading slash belongs to the
+      // prefix and must be elided when the param is empty, otherwise
+      // we'd emit `/prefix/`.
+      const needle = `/:${segment.name}*?`;
+      if (value === undefined || value === null || (Array.isArray(value) && value.length === 0)) {
+        result = result.replace(needle, "");
+      } else {
+        const parts = Array.isArray(value) ? value : [value];
+        const encoded = parts.map(encodeURIComponent).join("/");
+        result = result.replace(needle, `/${encoded}`);
+      }
+      continue;
+    }
+
+    if (segment.kind === "catchAll") {
+      const parts = Array.isArray(value) ? value : [String(value)];
+      const encoded = parts.map(encodeURIComponent).join("/");
+      result = result.replace(`:${segment.name}*`, encoded);
+      continue;
+    }
+
+    // required — avoid accidentally matching `:slugs` when we wanted
+    // `:slug` by using a word-boundary style regex.
+    const requiredRe = new RegExp(`:${escapeRegex(segment.name)}(?![A-Za-z0-9_])`);
+    result = result.replace(requiredRe, encodeURIComponent(String(value)));
+  }
+
+  // Collapse any accidental double slashes (except the scheme — we have no scheme here).
+  result = result.replace(/\/{2,}/g, "/");
+  if (result.length > 1 && result.endsWith("/")) result = result.slice(0, -1);
+  if (!result.startsWith("/")) result = "/" + result;
+  return result;
+}
+
+/**
+ * Invoke `generateStaticParams` on a page module and return the list
+ * of resolved URL paths. Validates the shape of each param set against
+ * the pattern; invalid entries are collected in the `errors` array and
+ * *not* included in `paths`.
+ *
+ * The function never throws for contract-level problems (missing
+ * export, non-array return, invalid param shapes). It *does* propagate
+ * exceptions thrown from inside the user-supplied function, because
+ * those indicate a bug in the user code that the caller (the build
+ * orchestrator) should surface loudly.
+ */
+export async function collectStaticPaths(
+  pattern: string,
+  mod: PageModuleWithStaticParams
+): Promise<{ paths: string[]; errors: string[]; paramSets: StaticParamSet[] }> {
+  const errors: string[] = [];
+  const paths: string[] = [];
+  const paramSets: StaticParamSet[] = [];
+
+  if (typeof mod.generateStaticParams !== "function") {
+    return { paths, errors, paramSets };
+  }
+
+  const result = await mod.generateStaticParams();
+
+  if (!Array.isArray(result)) {
+    errors.push(
+      `generateStaticParams() for "${pattern}" returned ${describe(result)}; expected an array of param objects`
+    );
+    return { paths, errors, paramSets };
+  }
+
+  const seen = new Set<string>();
+  for (let i = 0; i < result.length; i++) {
+    const entry = result[i];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      errors.push(
+        `generateStaticParams()[${i}] for "${pattern}" is not a plain object (${describe(entry)})`
+      );
+      continue;
+    }
+    const validationError = validateParamSet(pattern, entry as StaticParamSet);
+    if (validationError) {
+      errors.push(`generateStaticParams()[${i}] for "${pattern}": ${validationError}`);
+      continue;
+    }
+    const resolved = resolvePath(pattern, entry as StaticParamSet);
+    if (seen.has(resolved)) {
+      // Duplicates are fine — just silently de-dupe. Users often return
+      // the same slug from multiple data sources during migrations.
+      continue;
+    }
+    seen.add(resolved);
+    paths.push(resolved);
+    paramSets.push(entry as StaticParamSet);
+  }
+
+  return { paths, errors, paramSets };
+}
+
+// ---------- Internals ----------
+
+function describe(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (Array.isArray(value)) return `array (length ${value.length})`;
+  return typeof value;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/bundler/index.ts

@@ -7,3 +7,4 @@ export * from "./types";
 export * from "./build";
 export * from "./dev";
 export * from "./css";
+export * from "./plugins";

package/src/bundler/plugins/__tests__/block-generated-imports.test.ts

@@ -0,0 +1,263 @@
+/**
+ * Regression tests for `mandu:block-generated-imports` (issue #207).
+ *
+ * Split into two sections:
+ *   A — pure unit tests on `ForbiddenGeneratedImportError` + helpers.
+ *   B — integration tests driving a real `Bun.build` with a synthetic
+ *       `__generated__/` import in a tmpdir, asserting the build fails
+ *       with the expected error text.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import path from "path";
+
+import {
+  ForbiddenGeneratedImportError,
+  blockGeneratedImports,
+  defaultAllowImporter,
+  DEFAULT_BLOCK_FILTER,
+  defaultBundlerPlugins,
+} from "../index";
+import { GENERATED_IMPORT_DOCS_URL } from "../../../guard/check";
+
+// ────────────────────────────────────────────────────────────────────
+// Section A — unit
+// ────────────────────────────────────────────────────────────────────
+
+describe("ForbiddenGeneratedImportError", () => {
+  test("captures specifier and importer fields", () => {
+    const err = new ForbiddenGeneratedImportError(
+      "./__generated__/routes",
+      "/repo/src/app.ts",
+    );
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(ForbiddenGeneratedImportError);
+    expect(err.specifier).toBe("./__generated__/routes");
+    expect(err.importer).toBe("/repo/src/app.ts");
+    expect(err.docsUrl).toBe(GENERATED_IMPORT_DOCS_URL);
+    expect(err.name).toBe("ForbiddenGeneratedImportError");
+  });
+
+  test("message includes specifier, importer, docs URL, and getGenerated() hint", () => {
+    const err = new ForbiddenGeneratedImportError(
+      "./__generated__/data",
+      "/repo/src/page.tsx",
+    );
+    expect(err.message).toContain("./__generated__/data");
+    expect(err.message).toContain("/repo/src/page.tsx");
+    expect(err.message).toContain(GENERATED_IMPORT_DOCS_URL);
+    expect(err.message).toContain("getGenerated");
+    expect(err.message).toContain('@mandujs/core/runtime');
+  });
+
+  test("message falls back to <unknown> importer when empty", () => {
+    const err = new ForbiddenGeneratedImportError("./__generated__/x", "");
+    expect(err.message).toContain("<unknown>");
+  });
+});
+
+describe("defaultAllowImporter", () => {
+  test("exempts packages/core/src/runtime/** paths", () => {
+    expect(
+      defaultAllowImporter("/repo/packages/core/src/runtime/registry.ts"),
+    ).toBe(true);
+  });
+
+  test("normalises Windows backslashes", () => {
+    expect(
+      defaultAllowImporter(
+        "C:\\repo\\packages\\core\\src\\runtime\\registry.ts",
+      ),
+    ).toBe(true);
+  });
+
+  test("does NOT exempt regular user code", () => {
+    expect(defaultAllowImporter("/repo/src/app.ts")).toBe(false);
+    expect(defaultAllowImporter("")).toBe(false);
+  });
+});
+
+describe("DEFAULT_BLOCK_FILTER", () => {
+  test("matches __generated__ specifiers", () => {
+    expect("./__generated__/foo").toMatch(DEFAULT_BLOCK_FILTER);
+    expect("../../src/__generated__/routes").toMatch(DEFAULT_BLOCK_FILTER);
+  });
+  test("does NOT match look-alikes without double underscores", () => {
+    expect("./generated/foo".match(DEFAULT_BLOCK_FILTER)).toBeNull();
+    expect("./src/generate/foo".match(DEFAULT_BLOCK_FILTER)).toBeNull();
+  });
+});
+
+describe("defaultBundlerPlugins", () => {
+  test("installs block-generated-imports by default", () => {
+    const plugins = defaultBundlerPlugins();
+    expect(plugins).toHaveLength(1);
+    expect(plugins[0]?.name).toBe("mandu:block-generated-imports");
+  });
+
+  test("respects opt-out via guard.blockGeneratedImport === false", () => {
+    const plugins = defaultBundlerPlugins({
+      config: { guard: { blockGeneratedImport: false } },
+    });
+    expect(plugins).toHaveLength(0);
+  });
+
+  test("treats undefined as default-on", () => {
+    const plugins = defaultBundlerPlugins({ config: { guard: {} } });
+    expect(plugins).toHaveLength(1);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────
+// Section B — integration against real Bun.build
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Integration tests invoke real `Bun.build`. On shards where the
+ * Windows `onResolve` panic is flaky, set `MANDU_SKIP_BUNDLER_TESTS=1`
+ * to skip — matches the convention used by `fast-refresh.test.ts`.
+ */
+const SKIP_BUNDLER = process.env.MANDU_SKIP_BUNDLER_TESTS === "1";
+
+describe.skipIf(SKIP_BUNDLER)("blockGeneratedImports — Bun.build integration", () => {
+  let tmpRoot: string;
+
+  beforeAll(async () => {
+    tmpRoot = await mkdtemp(path.join(tmpdir(), "mandu-block-gen-"));
+  });
+
+  afterAll(async () => {
+    await rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
+  });
+
+  test("Bun.build fails when source imports a __generated__ file", async () => {
+    const dir = path.join(tmpRoot, "scenario-block");
+    await mkdir(path.join(dir, "__generated__"), { recursive: true });
+    await writeFile(
+      path.join(dir, "__generated__/data.ts"),
+      "export const routes = [];\n",
+    );
+    await writeFile(
+      path.join(dir, "entry.ts"),
+      `import { routes } from "./__generated__/data";\nconsole.log(routes);\n`,
+    );
+
+    // Bun's plugin host surfaces a thrown onResolve error either as an
+    // exception from `Bun.build(...)` OR as an unsuccessful result whose
+    // logs contain the message. Accept either shape so the assertion is
+    // robust across Bun patch releases.
+    // Bun's plugin host surfaces a thrown onResolve error via multiple
+    // channels across patch releases: an exception from `Bun.build()`
+    // (with `AggregateError.errors[]` on recent versions), or an
+    // unsuccessful `result.logs[]`. Collect from every channel and assert
+    // the aggregated text.
+    const collected: string[] = [];
+    try {
+      const result = await Bun.build({
+        entrypoints: [path.join(dir, "entry.ts")],
+        outdir: path.join(dir, "out"),
+        target: "browser",
+        plugins: [blockGeneratedImports()],
+      });
+      expect(result.success).toBe(false);
+      for (const log of result.logs) {
+        collected.push(String(log?.message ?? log));
+      }
+    } catch (err) {
+      if (err instanceof Error) collected.push(err.message);
+      const maybeAgg = err as { errors?: unknown[] };
+      if (Array.isArray(maybeAgg.errors)) {
+        for (const inner of maybeAgg.errors) {
+          if (inner instanceof Error) collected.push(inner.message);
+          else collected.push(String(inner));
+        }
+      }
+    }
+
+    const message = collected.join("\n");
+    expect(message).toContain("__generated__");
+    expect(message).toContain(GENERATED_IMPORT_DOCS_URL);
+    expect(message).toContain("getGenerated");
+  });
+
+  test("Bun.build succeeds when opt-out is set (no plugin installed)", async () => {
+    const dir = path.join(tmpRoot, "scenario-optout");
+    await mkdir(path.join(dir, "__generated__"), { recursive: true });
+    await writeFile(
+      path.join(dir, "__generated__/data.ts"),
+      "export const routes = [];\n",
+    );
+    await writeFile(
+      path.join(dir, "entry.ts"),
+      `import { routes } from "./__generated__/data";\nconsole.log(routes);\n`,
+    );
+
+    // Simulate the opt-out path: defaultBundlerPlugins with the flag off
+    // returns an empty plugin list, so the build has nothing to reject it.
+    const plugins = defaultBundlerPlugins({
+      config: { guard: { blockGeneratedImport: false } },
+    });
+
+    const result = await Bun.build({
+      entrypoints: [path.join(dir, "entry.ts")],
+      outdir: path.join(dir, "out"),
+      target: "browser",
+      plugins,
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test("Bun.build succeeds when source has no __generated__ imports", async () => {
+    const dir = path.join(tmpRoot, "scenario-clean");
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      path.join(dir, "clean.ts"),
+      `export const value = 42;\n`,
+    );
+    await writeFile(
+      path.join(dir, "entry.ts"),
+      `import { value } from "./clean";\nconsole.log(value);\n`,
+    );
+
+    const result = await Bun.build({
+      entrypoints: [path.join(dir, "entry.ts")],
+      outdir: path.join(dir, "out"),
+      target: "browser",
+      plugins: [blockGeneratedImports()],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test("allowImporter lets whitelisted files import __generated__", async () => {
+    const dir = path.join(tmpRoot, "scenario-allow");
+    const runtimeDir = path.join(dir, "packages/core/src/runtime");
+    await mkdir(path.join(dir, "__generated__"), { recursive: true });
+    await mkdir(runtimeDir, { recursive: true });
+    await writeFile(
+      path.join(dir, "__generated__/data.ts"),
+      "export const routes = [];\n",
+    );
+    // Use a relative import so the filter can see `__generated__` in the
+    // specifier and invoke our hook — at which point the importer path
+    // matches the default allow-list.
+    await writeFile(
+      path.join(runtimeDir, "registry.ts"),
+      `import { routes } from "../../../../__generated__/data";\nexport { routes };\n`,
+    );
+
+    const result = await Bun.build({
+      entrypoints: [path.join(runtimeDir, "registry.ts")],
+      outdir: path.join(dir, "out"),
+      target: "browser",
+      plugins: [blockGeneratedImports()],
+    });
+
+    // The allow predicate lets the import fall through to Bun's default
+    // resolution, which succeeds because the file exists.
+    expect(result.success).toBe(true);
+  });
+});