@akanjs/devkit 3.2.0-rc.0 → 3.2.0-rc.10

package/frontendBuild/csrDevModuleCompiler.ts

@@ -1,10 +1,18 @@
 import path from "node:path";
 import type { BunPlugin } from "bun";
 import type { App } from "../commandDecorators";
+import { loaderFor } from "../transforms/moduleSyntax";
 import { CsrDevFactoryCheck } from "./csrDevFactoryCheck";
 import { CsrDevPaths } from "./csrDevPaths";
 import { CsrDevResolver } from "./csrDevResolver";
-import type { CsrDevCompiledModule, CsrDevContext, CsrDevSharedHelpers } from "./csrDevTypes";
+import type {
+  CsrDevBarrelStamp,
+  CsrDevCompiledModule,
+  CsrDevContext,
+  CsrDevNarrowedImport,
+  CsrDevSharedHelpers,
+} from "./csrDevTypes";
+import { DevBarrelImports } from "./devBarrelImports";
 import { RouteClientBuilder } from "./routeClientBuilder";
 
 interface OutputMetafile {
@@ -38,6 +46,7 @@ export interface CsrDevCompileResult {
   modules: CsrDevCompiledModule[];
   refusedVendors: string[];
   unresolved: string[];
+  barrels?: Record<string, CsrDevBarrelStamp>;
 }
 
 //* Every module becomes its own CJS factory: one Bun.build with each import external, so a save re-runs only the
@@ -58,6 +67,8 @@ export class CsrDevModuleCompiler {
   readonly #outDir: string;
   readonly #routePrefix: string;
   readonly #assets = new Set<string>();
+  #barrels: Promise<DevBarrelImports | null> | null = null;
+  readonly #narrowed = new Map<string, Record<string, CsrDevNarrowedImport>>();
 
   constructor({ app, paths, resolver, context, outDir, routePrefix }: CsrDevModuleCompilerOptions) {
     this.#app = app;
@@ -109,7 +120,14 @@ export class CsrDevModuleCompiler {
       this.#app.verbose(
         `[csr-dev] ${fallbacks.size} import(s) outside the browser build's graph resolved with Bun's runtime resolver: ${[...fallbacks].slice(0, 5).join(", ")}${fallbacks.size > 5 ? ", ..." : ""}`,
       );
-    return { modules: [...compiled.values()], refusedVendors: [], unresolved: [] };
+    const modules = [...compiled.values()];
+    return { modules, refusedVendors: [], unresolved: [], barrels: await this.#barrelStamps(modules) };
+  }
+
+  async #barrelStamps(modules: CsrDevCompiledModule[]): Promise<Record<string, CsrDevBarrelStamp>> {
+    const barrels = new Set(modules.flatMap((module) => Object.keys(module.narrowed ?? {})));
+    const barrelImports = barrels.size > 0 ? await this.#barrelImports() : null;
+    return barrelImports ? await barrelImports.stamps(barrels, (file) => this.#paths.idOf(file)) : {};
   }
 
   async #compileRound(files: string[]): Promise<Omit<BuildRound, "tangled">> {
@@ -197,6 +215,7 @@ export class CsrDevModuleCompiler {
         continue;
       }
       const sourceMap = sourceMaps.get(`${artifact.path}.map`);
+      const narrowed = this.#narrowed.get(file);
       modules.push({
         id,
         file,
@@ -206,6 +225,7 @@ export class CsrDevModuleCompiler {
         deps: this.#emittedDeps(code),
         mtimeMs: mtimes.get(file) ?? CsrDevPaths.mtimeOf(file),
         hash: hashes.get(file) ?? "",
+        ...(narrowed && Object.keys(narrowed).length > 0 ? { narrowed } : {}),
       });
     }
     return { modules, misses, tangled };
@@ -302,13 +322,17 @@ export class CsrDevModuleCompiler {
           });
         }
         if (!vendor)
-          build.onLoad({ filter: /\.tsx$/ }, async (args) => {
+          build.onLoad({ filter: /\.(?:tsx?|jsx?)$/ }, async (args) => {
             if (CsrDevPaths.isVendorFile(args.path)) return undefined;
-            const normalized = RouteClientBuilder.normalizeNamedDefaultFunctionForFastRefresh(
-              await Bun.file(args.path).text(),
-              { path: args.path },
-            );
-            return normalized ? { contents: normalized, loader: "tsx" } : undefined;
+            const source = await Bun.file(args.path).text();
+            const rewrite = await (await this.#barrelImports())?.rewrite(source, args.path);
+            if (rewrite) this.#narrowed.set(CsrDevPaths.realpath(args.path), rewrite.narrowed);
+            const narrowed = rewrite?.contents ?? source;
+            const normalized = args.path.endsWith(".tsx")
+              ? RouteClientBuilder.normalizeNamedDefaultFunctionForFastRefresh(narrowed, { path: args.path })
+              : null;
+            const contents = normalized ?? narrowed;
+            return contents === source ? undefined : { contents, loader: loaderFor(args.path) };
           });
         build.onResolve({ filter: /.*/ }, (args) => {
           if (args.kind === "entry-point-build" || !args.importer) return undefined;
@@ -334,6 +358,11 @@ export class CsrDevModuleCompiler {
     };
   }
 
+  #barrelImports(): Promise<DevBarrelImports | null> {
+    this.#barrels ??= DevBarrelImports.create(this.#app, this.#context.barrelImports ?? []);
+    return this.#barrels;
+  }
+
   //? Bun writes sources relative to the working directory; the page shows them by workspace path instead. A package
   //? barrel inlined into its importer (react-icons) would carry its whole text into every importer's map.
   #rebaseSourceMap(text: string): string {

package/frontendBuild/csrDevPatcher.test.ts

@@ -119,12 +119,25 @@ describe("CsrDevPatcher", () => {
         workspace: { workspaceRoot: root },
         cwdPath: path.join(root, "apps/demo"),
         verbose: () => undefined,
+        getTsConfig: async () => ({ compilerOptions: { paths: tsPaths } }),
       };
       super(app as unknown as App, { dirName: "registry", routePrefix: "/_akan/registry/", library: true });
       this.#entry = entry;
     }
+    barrels: string[] = [];
     async context() {
-      return context;
+      return { ...context, barrelImports: this.barrels };
+    }
+    fingerprints = 0;
+    override async barrelImports(barrelContext: CsrDevContext) {
+      const barrelImports = await super.barrelImports(barrelContext);
+      if (!barrelImports) return null;
+      const fingerprint = barrelImports.fingerprint.bind(barrelImports);
+      barrelImports.fingerprint = async (barrel, names) => {
+        this.fingerprints += 1;
+        return await fingerprint(barrel, names);
+      };
+      return barrelImports;
     }
     async writeEntries() {
       return { files: { "": this.#entry }, changed: [] };
@@ -145,13 +158,22 @@ describe("CsrDevPatcher", () => {
     }
   }
 
-  const movedRegistry = async (files: Record<string, string>, { roots = [] }: { roots?: string[] } = {}) => {
+  const tsPaths = { "@apps/*": ["./apps/*"] };
+  const movedRegistry = async (
+    files: Record<string, string>,
+    { roots = [], barrels = [] }: { roots?: string[]; barrels?: string[] } = {},
+  ) => {
     const root = await mkdtemp(path.join(os.tmpdir(), "akan-csr-dev-move-"));
     dirs.push(root);
     const file = (relative: string) => path.join(CsrDevPaths.realpath(root), "apps/demo", relative);
     for (const [relative, text] of Object.entries(files)) await Bun.write(file(relative), text);
+    await Bun.write(
+      path.join(root, "tsconfig.json"),
+      JSON.stringify({ compilerOptions: { baseUrl: ".", paths: tsPaths } }),
+    );
     const bundler = new MovedRegistry(root, file("entry.ts"));
     bundler.extraRoots = roots.map((relative) => file(relative));
+    bundler.barrels = barrels;
     expect(await bundler.update([])).toMatchObject({ generation: 1, reload: true, first: true });
     const patcher = new CsrDevPatcher(bundler, { resident: true });
     expect(await patcher.update([])).toEqual({ kind: "unchanged" });
@@ -562,6 +584,71 @@ describe("CsrDevPatcher", () => {
     expect(await app()).toContain('__akan.define("apps/demo/ui/Foo.tsx"');
   });
 
+  test("an export moved to another file of a narrowed barrel compiles the importers of that name, also after a restart", async () => {
+    const { bundler, patcher, file, app, changedIds } = await movedRegistry(
+      {
+        "ui/index.ts": 'export * from "./Foo";\n',
+        "ui/Foo.tsx": 'export const Foo = () => "foo";\nexport const Bar = () => "bar";\n',
+        "page.ts": 'import { Foo } from "@apps/demo/ui";\nexport const page = Foo;\n',
+        "entry.ts":
+          'import { Bar } from "@apps/demo/ui";\nimport { page } from "./page";\nexport const run = () => Bar() + page();\n',
+      },
+      { barrels: ["@apps/demo/ui"] },
+    );
+    const factoryOf = (text: string, id: string) =>
+      text.slice(text.indexOf(`__akan.define("${id}"`)).split("__akan.define(")[1];
+
+    await Bun.write(file("ui/Foo.tsx"), 'export const Foo = () => "foo v2";\nexport const Bar = () => "bar";\n');
+    expect(changedIds(await patcher.update([file("ui/Foo.tsx")]))).toEqual(["apps/demo/ui/Foo.tsx"]);
+    expect(bundler.fingerprints).toBe(0);
+
+    await Bun.write(file("ui/Foo.tsx"), 'export const Foo = () => "foo";\n');
+    await Bun.write(file("ui/Bar.tsx"), 'export const Bar = () => "bar moved";\n');
+    await Bun.write(file("ui/index.ts"), 'export * from "./Bar";\nexport * from "./Foo";\n');
+    const moved = await patcher.update([file("ui/Foo.tsx"), file("ui/Bar.tsx"), file("ui/index.ts")]);
+    expect(changedIds(moved)).toEqual(["apps/demo/entry.ts", "apps/demo/ui/Bar.tsx", "apps/demo/ui/Foo.tsx"]);
+    expect(bundler.fingerprints).toBe(2);
+    expect(factoryOf(await app(), "apps/demo/entry.ts")).toContain('require("akan-module:apps/demo/ui/Bar.tsx")');
+
+    patcher.forget();
+    await Bun.write(file("ui/Foo.tsx"), 'export const Foo = () => "foo";\nexport const Bar = () => "bar back";\n');
+    await Bun.write(file("ui/Bar.tsx"), "export const Gone = 1;\n");
+    const restarted = await bundler.update([]);
+    expect(restarted?.changedIds.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual([
+      "apps/demo/entry.ts",
+      "apps/demo/ui/Bar.tsx",
+      "apps/demo/ui/Foo.tsx",
+    ]);
+    expect(factoryOf(await app(), "apps/demo/entry.ts")).toContain('require("akan-module:apps/demo/ui/Foo.tsx")');
+    expect(await new CsrDevPatcher(bundler).update([])).toEqual({ kind: "unchanged" });
+  });
+
+  test("a move whose compile fails leaves the barrel's stamps on disk, so the next save reads it again", async () => {
+    const { bundler, file, app, changedIds } = await movedRegistry(
+      {
+        "ui/index.ts": 'export * from "./Foo";\n',
+        "ui/Foo.tsx": 'export const Foo = () => "foo";\nexport const Bar = () => "bar";\n',
+        "entry.ts": 'import { Bar } from "@apps/demo/ui";\nexport const run = Bar;\n',
+      },
+      { barrels: ["@apps/demo/ui"] },
+    );
+    const barrelsOnDisk = async () => (await bundler.writer.readJson<CsrDevGraph>("graph.json"))?.barrels;
+    const before = await barrelsOnDisk();
+
+    await Bun.write(file("ui/Foo.tsx"), 'export const Foo = () => "foo";\n');
+    await Bun.write(file("ui/Bar.tsx"), 'import "./Missing";\nexport const Bar = () => "bar moved";\n');
+    await Bun.write(file("ui/index.ts"), 'export * from "./Bar";\nexport * from "./Foo";\n');
+    const saved = [file("ui/Foo.tsx"), file("ui/Bar.tsx"), file("ui/index.ts")];
+    await expect(new CsrDevPatcher(bundler).update(saved)).rejects.toThrow();
+    expect(await barrelsOnDisk()).toEqual(before);
+
+    await Bun.write(file("ui/Bar.tsx"), 'export const Bar = () => "bar moved";\n');
+    const fixed = await new CsrDevPatcher(bundler).update([file("ui/Bar.tsx")]);
+    expect(changedIds(fixed)).toEqual(["apps/demo/entry.ts", "apps/demo/ui/Bar.tsx", "apps/demo/ui/Foo.tsx"]);
+    expect(await app()).toContain('"bar moved"');
+    expect(await barrelsOnDisk()).not.toEqual(before);
+  });
+
   test("a registry with no manifest is a first build, which no tab holds a module of", async () => {
     const { bundler, dir } = await makeRegistry("same");
     await rm(path.join(dir, CSR_DEV_MANIFEST_FILE), { force: true });

package/frontendBuild/csrDevPatcher.ts

@@ -4,7 +4,7 @@ import { appGenerationOf, CSR_DEV_MANIFEST_FILE, type CsrDevManifest } from "aka
 import type { CsrDevCompileResult } from "./csrDevModuleCompiler";
 import { CsrDevPaths } from "./csrDevPaths";
 import { CsrDevResolver } from "./csrDevResolver";
-import type { CsrDevCode, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import type { CsrDevBarrelStamp, CsrDevCode, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
 import type { CsrDevUpdate, CsrDevUpdateOptions, DevRegistryBundler } from "./devRegistryBundler";
 
 interface CsrDevPatcherState {
@@ -109,6 +109,7 @@ export class CsrDevPatcher {
     const present = CsrDevPatcher.#presence(changedFiles);
     const forgotten = this.#forgetDeletedModules(state, present);
     const changed = onlyRoots ? new Set<string>() : await this.#changedModules(graph, changedFiles, present);
+    const restamped = onlyRoots ? null : await this.#renarrowed(context, graph, changedFiles, changed);
     for (const id of this.#withoutFactory(state, present)) changed.add(id);
     for (const file of entries.changed) changed.add(paths.idOf(file));
     const rootFiles = [...Object.values(entries.files), ...roots.filter((file) => fs.existsSync(file))];
@@ -121,6 +122,8 @@ export class CsrDevPatcher {
       this.#bundler.reloadsOnEntryChange &&
       (entries.changed.length > 0 || JSON.stringify(entryIds) !== JSON.stringify(graph.entries));
     if (changed.size === 0) {
+      //? No importer moved (none compiles), so the restamped barrels already hold.
+      if (restamped) graph.barrels = { ...graph.barrels, ...restamped };
       if (carried.length === 0) return { kind: "unchanged" };
       return await this.#retryCarried(context, state, carried, { announce, allowWholeAppBuilds });
     }
@@ -188,15 +191,11 @@ export class CsrDevPatcher {
       forgotten.push(id);
     }
     graph.pending = graph.pending.filter((id) => !orphans.includes(id));
-    this.#bundler.merge(graph, resolver, compiled);
+    this.#bundler.merge(graph, resolver, compiled, { ...restamped, ...result.barrels });
     if (!this.#resident) delete graph.failed;
     for (const module of compiled) this.#delegated.delete(module.id);
     graph.entries = entryIds;
-    for (const module of compiled) {
-      if (module.vendor || !code) continue;
-      code.modules.set(module.id, module.factory);
-      if (module.helpers) code.helpers.set(module.helpers.hash, module.helpers.definition);
-    }
+    if (code) CsrDevPatcher.#remember(code, compiled);
     const changedIds = compiled.filter((module) => !module.vendor).map((module) => module.id);
     const constantId = changedIds.find((id) => id.endsWith(".constant.ts"));
     // A model class swapped under live store state would mix old and new instances; reload instead.
@@ -359,6 +358,7 @@ export class CsrDevPatcher {
       modules: [...result.modules, ...more.modules],
       refusedVendors: [...result.refusedVendors, ...more.refusedVendors],
       unresolved: [...result.unresolved, ...more.unresolved],
+      barrels: { ...result.barrels, ...more.barrels },
     };
   }
 
@@ -508,6 +508,46 @@ export class CsrDevPatcher {
     return changed;
   }
 
+  //? The new stamps go into the graph with the compile that follows (`merge`), never ahead of it: a round that fails or
+  //? is handed back must leave the barrel stale for the next one.
+  async #renarrowed(
+    context: CsrDevContext,
+    graph: CsrDevGraph,
+    changedFiles: string[],
+    changed: Set<string>,
+  ): Promise<Record<string, CsrDevBarrelStamp>> {
+    const { paths } = this.#bundler;
+    const saved = new Set(changedFiles.map((file) => paths.idOf(file)));
+    const stale = Object.entries(graph.barrels ?? {})
+      .filter(([, { read }]) =>
+        Object.entries(read).some(
+          ([id, mtimeMs]) => saved.has(id) || CsrDevPaths.mtimeOf(paths.fileOf(id)) !== mtimeMs,
+        ),
+      )
+      .map(([barrel]) => barrel);
+    const barrelImports = stale.length > 0 ? await this.#bundler.barrelImports(context) : null;
+    if (!barrelImports) return {};
+    const barrels = await barrelImports.stamps(stale, (file) => paths.idOf(file));
+    const moved = stale.filter((barrel) => barrels[barrel]?.digest !== graph.barrels?.[barrel]?.digest);
+    for (const [id, module] of Object.entries(graph.modules)) {
+      for (const barrel of moved) {
+        const narrowed = module.narrowed?.[barrel];
+        if (!narrowed || (await barrelImports.fingerprint(barrel, narrowed.names)) === narrowed.hash) continue;
+        changed.add(id);
+        break;
+      }
+    }
+    return barrels;
+  }
+
+  static #remember(code: CsrDevCode, compiled: CsrDevCompileResult["modules"]) {
+    for (const module of compiled) {
+      if (module.vendor) continue;
+      code.modules.set(module.id, module.factory);
+      if (module.helpers) code.helpers.set(module.helpers.hash, module.helpers.definition);
+    }
+  }
+
   //? A new file can take over a relative import another module already resolved (`Foo.tsx` created beside
   //? `Foo/index.tsx`), with no change to that module's own text: it compiles again, and resolves against the disk.
   #shadowedImporters(graph: CsrDevGraph, changedFiles: string[]): string[] {

package/frontendBuild/csrDevTypes.ts

@@ -1,11 +1,24 @@
 import type { PageEntry } from "../artifact/implicitRootLayout";
 
+export interface CsrDevNarrowedImport {
+  names: string[];
+  hash: string;
+}
+
+export interface CsrDevBarrelStamp {
+  /** The mtime of each file and directory the barrel's analysis read, by id. */
+  read: Record<string, number>;
+  /** Each export name with the file it resolves to, hashed: what every importer's narrowing reads. */
+  digest: string;
+}
+
 export interface CsrDevGraphModule {
   vendor: boolean;
   mtimeMs: number;
   hash: string;
   deps: string[];
   helpers?: string;
+  narrowed?: Record<string, CsrDevNarrowedImport>;
 }
 
 export interface CsrDevGraph {
@@ -22,6 +35,7 @@ export interface CsrDevGraph {
   failed?: { roots: string[]; files: Record<string, string> };
   /** The stamp of the signal and dictionary sources the last whole build inlined; see `RegistryMetadataFingerprint`. */
   metadata?: string;
+  barrels?: Record<string, CsrDevBarrelStamp>;
 }
 
 export interface CsrDevContext {
@@ -35,6 +49,7 @@ export interface CsrDevContext {
   refreshFile: string | null;
   /** Bare specifiers the page already loads (an SSR page's import map): required as `vendor:<specifier>`, not compiled. */
   externals?: readonly string[];
+  barrelImports?: readonly string[];
 }
 
 export interface CsrDevSharedHelpers {
@@ -52,6 +67,7 @@ export interface CsrDevCompiledModule {
   deps: string[];
   mtimeMs: number;
   hash: string;
+  narrowed?: Record<string, CsrDevNarrowedImport>;
 }
 
 /** Module factories by id and helper definitions by hash, kept in memory so app.js is written without a pass over the disk. */

package/frontendBuild/cssCompiler.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import { declaredCustomProperties } from "./cssCompiler";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { CssCompiler, declaredCustomProperties } from "./cssCompiler";
+
+const makeTempRoot = tempDirs("akan-css-compiler-");
 
 describe("declaredCustomProperties", () => {
   test("names what the regex-based version named", () => {
@@ -51,3 +55,61 @@ describe("declaredCustomProperties", () => {
     }
   });
 });
+
+describe("CssCompiler.discoverCssAndSources", () => {
+  test("scans the files a page reaches through a client barrel's narrowed imports, never the barrel's other modules", async () => {
+    const root = await makeTempRoot();
+    const paths = { "@apps/*": ["./apps/*"], "@libs/*": ["./libs/*"] };
+    const writeSys = async (dir: string, modules: string[]) => {
+      await write(
+        path.join(dir, "client.ts"),
+        [
+          'export * as cnst from "./lib/cnst";',
+          'export { msg, usePage } from "./lib/useClient";',
+          'export { st, RootStore } from "./lib/st";',
+          ...modules.map((name) => `export { ${name} } from "./lib/${name.toLowerCase()}";`),
+          "",
+        ].join("\n"),
+      );
+      await write(path.join(dir, "lib/cnst.ts"), "export const Sample = 1;\n");
+      await write(path.join(dir, "lib/useClient.ts"), "export const msg = 1;\nexport const usePage = () => msg;\n");
+      for (const name of modules) {
+        await write(
+          path.join(dir, `lib/${name.toLowerCase()}/index.ts`),
+          `import * as Zone from "./${name}.Zone";\nexport const ${name} = { Zone };\n`,
+        );
+        await write(path.join(dir, `lib/${name.toLowerCase()}/${name}.Zone.tsx`), 'export const Card = () => "p-4";\n');
+      }
+    };
+    const appDir = path.join(root, "apps/demo");
+    await writeSys(appDir, ["Memo", "Other"]);
+    await writeSys(path.join(root, "libs/kit"), ["Widget"]);
+    await write(path.join(root, "libs/kit/lib/st.ts"), "export class RootStore {}\nexport const st = {};\n");
+    await write(
+      path.join(appDir, "lib/st.ts"),
+      'import { RootStore as kit } from "@libs/kit/client";\nexport class RootStore {}\nexport const st = { kit };\n',
+    );
+    await write(
+      path.join(appDir, "page/_index.tsx"),
+      'import { Memo, st } from "@apps/demo/client";\nexport default function Page() { return [Memo, st]; }\n',
+    );
+    const app = {
+      cwdPath: appDir,
+      workspace: { workspaceRoot: root },
+      getTsConfig: async () => ({ compilerOptions: { paths } }),
+      getConfig: async () => ({ barrelImports: ["@apps/demo/client", "@libs/kit/client"] }),
+    };
+
+    const { sourcePaths } = await new CssCompiler(app as never).discoverCssAndSources({ pageKeys: ["_index.tsx"] });
+
+    expect(sourcePaths.map((file) => path.relative(root, file)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual([
+      "apps/demo/lib/memo/Memo.Zone.tsx",
+      "apps/demo/lib/memo/index.ts",
+      "apps/demo/lib/st.ts",
+      "apps/demo/lib/useClient.ts",
+      "apps/demo/page/_index.tsx",
+      "libs/kit/lib/st.ts",
+      "libs/kit/lib/useClient.ts",
+    ]);
+  });
+});

package/frontendBuild/devBarrelImports.ts

@@ -0,0 +1,132 @@
+import path from "node:path";
+import type { App } from "../commandDecorators";
+import { BarrelAnalyzer, type PackageEntry } from "../transforms/barrelAnalyzer";
+import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
+import { CsrDevPaths } from "./csrDevPaths";
+import type { CsrDevBarrelStamp, CsrDevNarrowedImport } from "./csrDevTypes";
+
+export interface DevBarrelRewrite {
+  contents: string | null;
+  narrowed: Record<string, CsrDevNarrowedImport>;
+}
+
+//* Targets are written as relative paths, which resolve against the disk with no resolution build: a save that adds a
+//* barrel import stays a patch.
+export class DevBarrelImports {
+  readonly #barrels: string[];
+  readonly #resolvePackage: (pkgName: string) => Promise<PackageEntry | null>;
+  readonly #analyzer: BarrelAnalyzer;
+  readonly #packages = new Map<string, Promise<PackageEntry | null>>();
+
+  constructor(barrels: readonly string[], resolvePackage: (pkgName: string) => Promise<PackageEntry | null>) {
+    this.#barrels = [...barrels];
+    this.#resolvePackage = resolvePackage;
+    this.#analyzer = new BarrelAnalyzer({ resolvePackage });
+  }
+
+  static async create(app: App, barrels: readonly string[]): Promise<DevBarrelImports | null> {
+    if (barrels.length === 0) return null;
+    return new DevBarrelImports(barrels, await createTsconfigPackageResolver(app));
+  }
+
+  async rewrite(source: string, importer: string): Promise<DevBarrelRewrite | null> {
+    const named = this.#barrels.filter((barrel) => source.includes(barrel));
+    if (named.length === 0) return null;
+    const packages = await this.#packagesOf(named);
+    const from = path.dirname(CsrDevPaths.realpath(importer));
+    const names = new Map<string, Set<string>>();
+    const contents = await rewriteBarrelImports(source, named, this.#analyzer, {
+      keepLines: true,
+      specifierOf: (subpath) => DevBarrelImports.#relative(subpath, from, packages),
+      onImport: (barrel, imported) => names.set(barrel, new Set([...(names.get(barrel) ?? []), ...imported])),
+    });
+    const narrowed = await Promise.all(
+      [...names].map(async ([barrel, set]) => {
+        const sorted = [...set].sort();
+        return [barrel, { names: sorted, hash: await this.fingerprint(barrel, sorted) }] as const;
+      }),
+    );
+    return { contents, narrowed: Object.fromEntries(narrowed) };
+  }
+
+  //? Hashes what an import of these names alone narrows to, with each target as the file it resolves to: the same
+  //? names in another importer narrow to the same files, and only a moved export or a moved file changes it.
+  async fingerprint(barrel: string, names: string[]): Promise<string> {
+    const packages = await this.#packagesOf([barrel]);
+    const aliased = names.map((name, index) => `${name} as _${index}`).join(", ");
+    const narrowed = await rewriteBarrelImports(
+      `import { ${aliased} } from ${JSON.stringify(barrel)};`,
+      [barrel],
+      this.#analyzer,
+      { specifierOf: (subpath) => DevBarrelImports.#fileOf(subpath, packages) ?? subpath },
+    );
+    return Bun.hash(narrowed ?? "").toString(36);
+  }
+
+  async stamps(barrels: Iterable<string>, idOf: (file: string) => string): Promise<Record<string, CsrDevBarrelStamp>> {
+    const stamped = await Promise.all(
+      [...barrels].map(async (barrel) => {
+        const files = await this.#analyzer.filesOf(barrel);
+        const read = [...new Set([...files, ...files.map((file) => path.dirname(file))])];
+        const stamp: CsrDevBarrelStamp = {
+          read: Object.fromEntries(read.map((file) => [idOf(file), CsrDevPaths.mtimeOf(file)])),
+          digest: await this.#digest(barrel),
+        };
+        return [barrel, stamp] as const;
+      }),
+    );
+    return Object.fromEntries(stamped);
+  }
+
+  //? Every input of an importer's fingerprint: an importer is hashed again only once this moves, so a save that
+  //? changes a component's body costs one analysis of its barrel, whatever the number of importers.
+  async #digest(barrel: string): Promise<string> {
+    const map = await this.#analyzer.analyze(barrel);
+    const packages = await this.#packagesOf([barrel]);
+    const files = new Map<string, string>();
+    const fileOf = (subpath: string) => {
+      let file = files.get(subpath);
+      if (file === undefined) {
+        file = DevBarrelImports.#fileOf(subpath, packages) ?? subpath;
+        files.set(subpath, file);
+      }
+      return file;
+    };
+    const exports = [...(map ?? [])]
+      .map(([name, target]) => [name, target.originalName, !!target.namespace, fileOf(target.subpath)] as const)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return Bun.hash(JSON.stringify([fileOf(barrel), map === null, exports])).toString(36);
+  }
+
+  async #packagesOf(barrels: string[]): Promise<PackageEntry[]> {
+    return (await Promise.all(barrels.map((barrel) => this.#packageOf(barrel))))
+      .filter((pkg): pkg is PackageEntry => pkg !== null)
+      .sort((a, b) => b.pkgName.length - a.pkgName.length);
+  }
+
+  #packageOf(barrel: string): Promise<PackageEntry | null> {
+    let pkg = this.#packages.get(barrel);
+    if (!pkg) {
+      pkg = this.#resolvePackage(barrel);
+      this.#packages.set(barrel, pkg);
+    }
+    return pkg;
+  }
+
+  static #fileOf(subpath: string, packages: PackageEntry[]): string | null {
+    const pkg = packages.find(({ pkgName }) => subpath === pkgName || subpath.startsWith(`${pkgName}/`));
+    if (!pkg) return null;
+    const file = CsrDevPaths.resolveOnDisk(path.join(pkg.pkgDir, subpath.slice(pkg.pkgName.length)));
+    return file ? CsrDevPaths.realpath(file) : null;
+  }
+
+  static #relative(subpath: string, from: string, packages: PackageEntry[]): string {
+    const file = DevBarrelImports.#fileOf(subpath, packages);
+    if (!file) return subpath;
+    const relative = path.relative(from, file);
+    //? A target on another Windows drive has no relative path: `path.relative` returns it absolute.
+    if (path.isAbsolute(relative)) return file.split(path.sep).join("/");
+    const posix = relative.split(path.sep).join("/");
+    return posix.startsWith("../") ? posix : `./${posix}`;
+  }
+}

package/frontendBuild/devRegistryBundler.ts

@@ -7,7 +7,8 @@ import { CsrDevModuleCompiler } from "./csrDevModuleCompiler";
 import { CsrDevPatcher } from "./csrDevPatcher";
 import { CsrDevPaths } from "./csrDevPaths";
 import { CsrDevResolver } from "./csrDevResolver";
-import type { CsrDevCompiledModule, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import type { CsrDevBarrelStamp, CsrDevCompiledModule, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import { DevBarrelImports } from "./devBarrelImports";
 import { RegistryMetadataFingerprint } from "./registryMetadataFingerprint";
 import { WatchRootResolver } from "./watchRootResolver";
 
@@ -131,7 +132,7 @@ export abstract class DevRegistryBundler {
     const resolver = new CsrDevResolver({ paths: this.paths, context, entryFiles: roots });
     await resolver.prepass();
     const compiler = this.compiler(context, resolver);
-    const { modules: compiled } = await compiler.compile(
+    const { modules: compiled, barrels } = await compiler.compile(
       [...roots, ...(context.refreshFile ? [context.refreshFile] : [])],
       new Set(),
     );
@@ -147,7 +148,7 @@ export abstract class DevRegistryBundler {
       pending: [],
       metadata,
     };
-    this.merge(graph, resolver, compiled);
+    this.merge(graph, resolver, compiled, barrels);
     await this.writer.markBuilding();
     await this.writer.writeModules(compiled);
     const vendorFile = await this.writer.writeVendor(graph);
@@ -170,7 +171,16 @@ export abstract class DevRegistryBundler {
     });
   }
 
-  merge(graph: CsrDevGraph, resolver: CsrDevResolver, compiled: CsrDevCompiledModule[]): void {
+  async barrelImports(context: CsrDevContext): Promise<DevBarrelImports | null> {
+    return await DevBarrelImports.create(this.app, context.barrelImports ?? []);
+  }
+
+  merge(
+    graph: CsrDevGraph,
+    resolver: CsrDevResolver,
+    compiled: CsrDevCompiledModule[],
+    barrels: Record<string, CsrDevBarrelStamp> = {},
+  ): void {
     for (const module of compiled)
       graph.modules[module.id] = {
         vendor: module.vendor,
@@ -178,7 +188,12 @@ export abstract class DevRegistryBundler {
         hash: module.hash,
         deps: module.deps.map((dep) => (CsrDevPaths.isStub(dep) ? dep : this.paths.idOf(dep))),
         ...(module.helpers ? { helpers: module.helpers.hash } : {}),
+        ...(module.narrowed ? { narrowed: module.narrowed } : {}),
       };
+    const narrowing = new Set(Object.values(graph.modules).flatMap((module) => Object.keys(module.narrowed ?? {})));
+    graph.barrels = Object.fromEntries(
+      Object.entries({ ...graph.barrels, ...barrels }).filter(([barrel]) => narrowing.has(barrel)),
+    );
     //? Only what this round compiled leaves pending: a root another route's check failed on stays for its retry.
     const compiledIds = new Set(compiled.map((module) => module.id));
     graph.pending = graph.pending.filter((id) => !compiledIds.has(id));