@akanjs/devkit 3.0.0-beta.24 → 3.0.0-beta.25

package/frontendBuild/csrDevBundler.ts

@@ -1,66 +1,34 @@
-import fs from "node:fs";
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
-import { CSR_DEV_DIRNAME, CSR_DEV_MANIFEST_FILE, type CsrDevManifest } from "akanjs/server/hmr/csrDevManifest";
-import { isAkanRuntimeMetadataFile } from "akanjs/server/hmr/runtimeMetadataFile";
+import { CSR_DEV_DIRNAME, CSR_DEV_ROUTE_PREFIX } from "akanjs/server/hmr/csrDevManifest";
 import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
+import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
 import { bundleDefine } from "./bundleDefine";
-import { CsrArtifactBuilder } from "./csrArtifactBuilder";
-import { CsrDevArtifactWriter } from "./csrDevArtifactWriter";
-import { CsrDevModuleCompiler } from "./csrDevModuleCompiler";
 import { CsrDevPaths } from "./csrDevPaths";
-import { CsrDevResolver } from "./csrDevResolver";
-import type { CsrDevCompiledModule, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import type { CsrDevContext } from "./csrDevTypes";
+import { CsrEntryFiles } from "./csrEntryFiles";
+import { DevRegistryBundler } from "./devRegistryBundler";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 
-export interface CsrDevUpdate {
-  generation: number;
-  reload: boolean;
-  reason?: string;
-  patchUrl?: string;
-  changedIds: string[];
-  moduleCount: number;
-}
-
-//* Dev-only CSR as a module registry. The build worker is a fresh process per save, so the graph, every module's
-//* factory and the resolutions live on disk under `.akan/artifact/csr-dev`.
-export class CsrDevBundler {
+//* Dev-only CSR as a module registry, under `.akan/artifact/csr-dev`: one entry per basePath boots every page.
+export class CsrDevBundler extends DevRegistryBundler {
   static readonly #formatVersion = 3;
-  readonly #app: App;
-  readonly #paths: CsrDevPaths;
-  readonly #outDir: string;
-  readonly #entryDir: string;
-  readonly #writer: CsrDevArtifactWriter;
+  readonly reloadsOnEntryChange = true;
+  //? Detecting a page's async default parses it with TypeScript: on apps/akan every page each save cost ~100ms.
+  readonly #asyncDefaults = new Map<string, { mtimeMs: number; detected: Promise<boolean> }>();
 
   constructor(app: App) {
-    this.#app = app;
-    this.#paths = new CsrDevPaths(app.workspace.workspaceRoot);
-    this.#outDir = path.join(app.cwdPath, ".akan/artifact", CSR_DEV_DIRNAME);
-    this.#entryDir = path.join(app.cwdPath, ".akan/generated", CSR_DEV_DIRNAME);
-    this.#writer = new CsrDevArtifactWriter(this.#outDir);
+    super(app, { dirName: CSR_DEV_DIRNAME, routePrefix: CSR_DEV_ROUTE_PREFIX, library: false });
   }
 
-  async update(changedFiles: string[] = []): Promise<CsrDevUpdate | null> {
-    const context = await this.#context();
-    if (context.pageEntries.length === 0) return null;
-    const manifest = await this.#writer.readJson<CsrDevManifest>(CSR_DEV_MANIFEST_FILE);
-    const graph = await this.#writer.readJson<CsrDevGraph>("graph.json");
-    const generation = (manifest?.generation ?? 0) + 1;
-    if (!manifest || !graph || graph.version !== 1 || graph.configKey !== context.configKey)
-      return await this.#fullBuild(context, generation, manifest ? "the dev bundle config changed" : "first build");
-    const metadataFile = changedFiles.find(isAkanRuntimeMetadataFile);
-    // `lib/useClient.ts` inlines signal and dictionary metadata through a macro at build time.
-    if (metadataFile) return await this.#fullBuild(context, generation, `${path.basename(metadataFile)} changed`);
-    return await this.#incrementalBuild(context, graph, manifest, changedFiles, generation);
-  }
-
-  async #context(): Promise<CsrDevContext> {
-    const akanConfig = await this.#app.getConfig();
-    const pageEntries = await resolveSsrPageEntriesForApp(this.#app, await this.#app.getPageKeys());
+  async context(): Promise<CsrDevContext | null> {
+    const akanConfig = await this.app.getConfig();
+    const pageEntries = await resolveSsrPageEntriesForApp(this.app, await this.app.getPageKeys());
+    if (pageEntries.length === 0) return null;
     const basePaths = [...akanConfig.basePaths];
     const htmlBasePaths = basePaths.length > 0 ? basePaths : [""];
-    const define = bundleDefine(this.#app, "start", "csr");
+    const define = bundleDefine(this.app, "start", "csr");
     const optimizeImports = [...akanConfig.optimizeImports];
     const configKey = Bun.hash(
       JSON.stringify([CsrDevBundler.#formatVersion, Bun.version, define, optimizeImports, htmlBasePaths]),
@@ -76,152 +44,21 @@ export class CsrDevBundler {
     };
   }
 
-  #resolveRefreshRuntime(): string {
-    const akanWebkit = CsrDevPaths.tryResolve("akanjs/webkit", this.#app.cwdPath);
-    const bases = [
-      this.#app.cwdPath,
-      this.#paths.root,
-      ...(akanWebkit ? [path.dirname(path.dirname(akanWebkit))] : []),
-    ];
-    for (const base of bases) {
-      const resolved = CsrDevPaths.tryResolve("react-refresh/runtime", base);
-      if (resolved) return CsrDevPaths.realpath(resolved);
-    }
-    throw new Error(`[csr-dev] react-refresh/runtime is not resolvable from ${bases.join(", ")}`);
-  }
-
-  async #fullBuild(context: CsrDevContext, generation: number, reason: string): Promise<CsrDevUpdate> {
-    await this.#writer.reset();
-    const entries = await this.#writeEntries(context);
-    const entryFiles = Object.values(entries.files);
-    const resolver = new CsrDevResolver({ paths: this.#paths, context, entryFiles });
-    await resolver.prepass();
-    const compiled = await this.#compiler(context, resolver).compile([...entryFiles, context.refreshFile], new Set());
-    const graph: CsrDevGraph = {
-      version: 1,
-      configKey: context.configKey,
-      refresh: this.#paths.idOf(context.refreshFile),
-      entries: this.#entryIds(entries.files),
-      modules: {},
-      resolution: {},
-      pending: [],
-    };
-    this.#merge(graph, resolver, compiled);
-    await this.#writer.writeModules(compiled);
-    const vendorFile = await this.#writer.writeVendor(graph);
-    await this.#writer.writeApp(graph, generation);
-    await this.#writer.writeState(graph, { version: 1, generation, vendorFile, entries: graph.entries });
-    await this.#writer.prune(vendorFile, generation);
-    return { generation, reload: true, reason, changedIds: [], moduleCount: Object.keys(graph.modules).length };
-  }
-
-  async #incrementalBuild(
-    context: CsrDevContext,
-    graph: CsrDevGraph,
-    manifest: CsrDevManifest,
-    changedFiles: string[],
-    generation: number,
-  ): Promise<CsrDevUpdate | null> {
-    const entries = await this.#writeEntries(context);
-    const entryIds = this.#entryIds(entries.files);
-    await this.#forgetDeletedModules(graph);
-    const changed = await this.#changedModules(graph, changedFiles);
-    for (const file of entries.changed) changed.add(this.#paths.idOf(file));
-    const routesMoved = entries.changed.length > 0 || JSON.stringify(entryIds) !== JSON.stringify(graph.entries);
-    if (changed.size === 0) return null;
-
-    const resolver = new CsrDevResolver({
-      paths: this.#paths,
-      context,
-      entryFiles: Object.values(entries.files),
-      resolution: graph.resolution,
-    });
-    const known = new Set(Object.keys(graph.modules).map((id) => this.#paths.fileOf(id)));
-    let compiled: CsrDevCompiledModule[];
-    try {
-      compiled = await this.#compiler(context, resolver).compile(
-        [...changed].map((id) => this.#paths.fileOf(id)),
-        known,
-      );
-    } catch (error) {
-      graph.pending = [...changed];
-      await this.#writer.writeJson("graph.json", graph);
-      throw error;
-    }
-    const vendorJoined = compiled.some((module) => module.vendor && !graph.modules[module.id]);
-    this.#merge(graph, resolver, compiled);
-    graph.entries = entryIds;
-    await this.#writer.writeModules(compiled);
-    const vendorFile = vendorJoined ? await this.#writer.writeVendor(graph) : manifest.vendorFile;
-    await this.#writer.writeApp(graph, generation);
-    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.
-    const reason = vendorJoined
-      ? "an npm module joined the graph"
-      : routesMoved
-        ? "the route table changed"
-        : constantId
-          ? `${path.basename(constantId)} changed`
-          : undefined;
-    const patchUrl = reason
-      ? undefined
-      : await this.#writer.writePatch(
-          generation,
-          compiled.filter((module) => !module.vendor),
-        );
-    await this.#writer.writeState(graph, { ...manifest, generation, vendorFile, entries: entryIds });
-    await this.#writer.prune(vendorFile, generation);
-    return {
-      generation,
-      reload: !!reason,
-      reason,
-      patchUrl,
-      changedIds,
-      moduleCount: Object.keys(graph.modules).length,
-    };
-  }
-
-  async #changedModules(graph: CsrDevGraph, changedFiles: string[]): Promise<Set<string>> {
-    const changed = new Set<string>(graph.pending.filter((id) => graph.modules[id]));
-    for (const file of changedFiles) {
-      const id = this.#paths.idOf(file);
-      if (graph.modules[id]) changed.add(id);
-    }
-    // Stat, not trust: a save made while CSR was unarmed, or a build that failed, never reached this graph. The hash
-    // settles it because route discovery rewrites the generated layout wrappers, touching them on every call.
-    for (const [id, module] of Object.entries(graph.modules)) {
-      if (module.vendor || changed.has(id)) continue;
-      const file = this.#paths.fileOf(id);
-      if (CsrDevPaths.mtimeOf(file) === module.mtimeMs) continue;
-      if ((await CsrDevPaths.hashOf(file)) !== module.hash) changed.add(id);
-    }
-    return changed;
-  }
-
-  // A deleted module leaves the graph instead of being rebuilt: rebuilding a missing file fails every save after it.
-  // An importer that still names it fails on its own rebuild, with the resolution error that says why.
-  async #forgetDeletedModules(graph: CsrDevGraph): Promise<void> {
-    const deleted = Object.keys(graph.modules).filter(
-      (id) => !graph.modules[id]?.vendor && !fs.existsSync(this.#paths.fileOf(id)),
-    );
-    for (const id of deleted) delete graph.modules[id];
-    await this.#writer.forgetModules(deleted);
-  }
-
-  async #writeEntries(context: CsrDevContext): Promise<{ files: Record<string, string>; changed: string[] }> {
-    await mkdir(this.#entryDir, { recursive: true });
+  async writeEntries(context: CsrDevContext): Promise<{ files: Record<string, string>; changed: string[] }> {
+    await mkdir(this.entryDir, { recursive: true });
     const files: Record<string, string> = {};
     const changed: string[] = [];
     for (const basePath of context.htmlBasePaths) {
-      const file = path.join(this.#entryDir, CsrArtifactBuilder.entryFilename(basePath));
-      const entryPages = CsrArtifactBuilder.pageEntriesForBasePath(context.pageEntries, basePath, context.basePaths);
-      const generator = new PagesEntrySourceGenerator(entryPages);
-      const pages = await generator.generateStatic({ fromDir: this.#entryDir });
+      const file = path.join(this.entryDir, CsrEntryFiles.entryFilename(basePath));
+      const entryPages = CsrEntryFiles.pageEntriesForBasePath(context.pageEntries, basePath, context.basePaths);
+      const generator = new PagesEntrySourceGenerator(entryPages, {
+        isAsyncDefault: (moduleAbsPath) => this.#isAsyncDefault(moduleAbsPath),
+      });
+      const pages = await generator.generateStatic({ fromDir: this.entryDir });
       const hot = await generator.generateHotReplace({
-        fromDir: this.#entryDir,
-        ownerId: this.#paths.idOf(file),
-        moduleIds: entryPages.map(({ moduleAbsPath }) => this.#paths.idOf(moduleAbsPath)),
+        fromDir: this.entryDir,
+        ownerId: this.paths.idOf(file),
+        moduleIds: entryPages.map(({ moduleAbsPath }) => this.paths.idOf(moduleAbsPath)),
       });
       const source = `import * as akanWebkit from "akanjs/webkit";\n${pages}\nvoid akanWebkit.bootCsr(pages);\n${hot}`;
       const unchanged = (await Bun.file(file).exists()) && (await Bun.file(file).text()) === source;
@@ -233,24 +70,26 @@ export class CsrDevBundler {
     return { files, changed };
   }
 
-  #compiler(context: CsrDevContext, resolver: CsrDevResolver): CsrDevModuleCompiler {
-    return new CsrDevModuleCompiler({ app: this.#app, paths: this.#paths, resolver, context, outDir: this.#outDir });
+  protected async rootFiles(entryFiles: string[]): Promise<string[]> {
+    return entryFiles;
   }
 
-  #merge(graph: CsrDevGraph, resolver: CsrDevResolver, compiled: CsrDevCompiledModule[]): void {
-    for (const module of compiled)
-      graph.modules[module.id] = {
-        vendor: module.vendor,
-        mtimeMs: module.mtimeMs,
-        hash: module.hash,
-        deps: module.deps.map((dep) => (CsrDevPaths.isStub(dep) ? dep : this.#paths.idOf(dep))),
-        ...(module.helpers ? { helpers: module.helpers.hash } : {}),
-      };
-    graph.pending = [];
-    graph.resolution = resolver.serialize();
+  #isAsyncDefault(moduleAbsPath: string): Promise<boolean> {
+    const mtimeMs = CsrDevPaths.mtimeOf(moduleAbsPath);
+    const cached = this.#asyncDefaults.get(moduleAbsPath);
+    if (cached?.mtimeMs === mtimeMs) return cached.detected;
+    const detected = AsyncDefaultExportDetector.detect(moduleAbsPath);
+    this.#asyncDefaults.set(moduleAbsPath, { mtimeMs, detected });
+    return detected;
   }
 
-  #entryIds(files: Record<string, string>): Record<string, string> {
-    return Object.fromEntries(Object.entries(files).map(([basePath, file]) => [basePath, this.#paths.idOf(file)]));
+  #resolveRefreshRuntime(): string {
+    const akanWebkit = CsrDevPaths.tryResolve("akanjs/webkit", this.app.cwdPath);
+    const bases = [this.app.cwdPath, this.paths.root, ...(akanWebkit ? [path.dirname(path.dirname(akanWebkit))] : [])];
+    for (const base of bases) {
+      const resolved = CsrDevPaths.tryResolve("react-refresh/runtime", base);
+      if (resolved) return CsrDevPaths.realpath(resolved);
+    }
+    throw new Error(`[csr-dev] react-refresh/runtime is not resolvable from ${bases.join(", ")}`);
   }
 }

package/frontendBuild/csrDevModuleCompiler.ts

@@ -1,5 +1,4 @@
 import path from "node:path";
-import { CSR_DEV_ROUTE_PREFIX } from "akanjs/server/hmr/csrDevManifest";
 import type { BunPlugin } from "bun";
 import type { App } from "../commandDecorators";
 import { CsrDevPaths } from "./csrDevPaths";
@@ -23,6 +22,21 @@ export interface CsrDevModuleCompilerOptions {
   resolver: CsrDevResolver;
   context: CsrDevContext;
   outDir: string;
+  /** Where the dev server serves `outDir`: an imported asset's URL starts with it. */
+  routePrefix: string;
+}
+
+export interface CsrDevCompileOptions {
+  /** Stop before building an npm module the graph does not know yet, and name it instead. */
+  refuseNewVendor?: boolean;
+  /** Stop at an import no recorded resolution answers, instead of running the resolution build (a whole-app build). */
+  refusePrepass?: boolean;
+}
+
+export interface CsrDevCompileResult {
+  modules: CsrDevCompiledModule[];
+  refusedVendors: string[];
+  unresolved: string[];
 }
 
 //* Every module becomes its own CJS factory: one Bun.build with each import external, so a save re-runs only the
@@ -40,21 +54,37 @@ export class CsrDevModuleCompiler {
   readonly #resolver: CsrDevResolver;
   readonly #context: CsrDevContext;
   readonly #outDir: string;
+  readonly #routePrefix: string;
+  readonly #assets = new Set<string>();
 
-  constructor({ app, paths, resolver, context, outDir }: CsrDevModuleCompilerOptions) {
+  constructor({ app, paths, resolver, context, outDir, routePrefix }: CsrDevModuleCompilerOptions) {
     this.#app = app;
     this.#paths = paths;
     this.#resolver = resolver;
     this.#context = context;
     this.#outDir = outDir;
+    this.#routePrefix = routePrefix;
+  }
+
+  /** Every asset file this compiler wrote into the registry directory. */
+  get assets(): string[] {
+    return [...this.#assets];
   }
 
-  async compile(startFiles: string[], known: Set<string>): Promise<CsrDevCompiledModule[]> {
+  async compile(
+    startFiles: string[],
+    known: Set<string>,
+    { refuseNewVendor = false, refusePrepass = false }: CsrDevCompileOptions = {},
+  ): Promise<CsrDevCompileResult> {
     const compiled = new Map<string, CsrDevCompiledModule>();
     const seen = new Set([...known, ...startFiles]);
     let frontier = [...new Set(startFiles)];
     while (frontier.length > 0) {
+      const refusedVendors = refuseNewVendor ? frontier.filter((file) => CsrDevPaths.isVendorFile(file)) : [];
+      if (refusedVendors.length > 0) return { modules: [...compiled.values()], refusedVendors, unresolved: [] };
       const round = await this.#compileRound(frontier);
+      if (round.misses.length > 0 && !this.#resolver.prepassDone && refusePrepass)
+        return { modules: [...compiled.values()], refusedVendors: [], unresolved: round.misses };
       if (round.misses.length > 0 && !this.#resolver.prepassDone) {
         this.#app.verbose(`[csr-dev] ${round.misses.length} unresolved import(s); rerunning the resolution build`);
         await this.#resolver.prepass();
@@ -76,7 +106,7 @@ 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 [...compiled.values()];
+    return { modules: [...compiled.values()], refusedVendors: [], unresolved: [] };
   }
 
   async #compileRound(files: string[]): Promise<Omit<BuildRound, "tangled">> {
@@ -100,9 +130,12 @@ export class CsrDevModuleCompiler {
   }
 
   async #bunBuild(files: string[], vendor: boolean): Promise<BuildRound> {
-    const mtimes = new Map(files.map((file) => [file, CsrDevPaths.mtimeOf(file)]));
+    //? Keyed as the output is: by the disk's spelling, which a case-only rename leaves apart from the requested path.
+    const mtimes = new Map(files.map((file) => [CsrDevPaths.realpath(file), CsrDevPaths.mtimeOf(file)]));
     const hashes = new Map(
-      await Promise.all(files.map(async (file) => [file, vendor ? "" : await CsrDevPaths.hashOf(file)] as const)),
+      await Promise.all(
+        files.map(async (file) => [CsrDevPaths.realpath(file), vendor ? "" : await CsrDevPaths.hashOf(file)] as const),
+      ),
     );
     const misses: string[] = [];
     const result = await Bun.build({
@@ -113,7 +146,7 @@ export class CsrDevModuleCompiler {
       reactFastRefresh: !vendor,
       sourcemap: vendor ? "none" : "external",
       naming: { entry: "[dir]/[name].[ext]", asset: "assets/[name]-[hash].[ext]" },
-      publicPath: CSR_DEV_ROUTE_PREFIX,
+      publicPath: this.#routePrefix,
       metafile: true,
       env: "AKAN_PUBLIC_*",
       define: this.#context.define,
@@ -128,7 +161,9 @@ export class CsrDevModuleCompiler {
     const tangled: string[] = [];
     for (const artifact of result.outputs) {
       if (artifact.kind === "asset") {
-        await Bun.write(path.join(this.#outDir, artifact.path), artifact);
+        const assetPath = path.join(this.#outDir, artifact.path);
+        await Bun.write(assetPath, artifact);
+        this.#assets.add(assetPath);
         continue;
       }
       if (artifact.kind !== "entry-point") continue;
@@ -167,13 +202,20 @@ export class CsrDevModuleCompiler {
             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;
           });
         build.onResolve({ filter: /.*/ }, (args) => {
           if (args.kind === "entry-point-build" || !args.importer) return undefined;
+          if (this.#context.externals?.includes(args.path))
+            return { path: `${CsrDevPaths.vendorPrefix}${args.path}`, external: true };
           const importer = CsrDevPaths.realpath(args.importer);
-          const target = this.#resolver.resolve(importer, args.path);
+          const target = this.#resolver.resolve(
+            importer,
+            args.path,
+            args.kind === "require-call" ? "require" : "import",
+          );
           if (target === CsrDevResolver.inline) return undefined;
           if (target === null) {
             misses.push(`${args.path} from ${this.#paths.idOf(importer)}`);