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

package/frontendBuild/devRegistryBundler.ts

@@ -0,0 +1,192 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isAkanRuntimeMetadataFile } from "akanjs/server/hmr/runtimeMetadataFile";
+import type { App } from "../commandDecorators";
+import { CsrDevArtifactWriter } from "./csrDevArtifactWriter";
+import { CsrDevModuleCompiler } from "./csrDevModuleCompiler";
+import { CsrDevPatcher } from "./csrDevPatcher";
+import { CsrDevPaths } from "./csrDevPaths";
+import { CsrDevResolver } from "./csrDevResolver";
+import type { CsrDevCompiledModule, CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import { RegistryMetadataFingerprint } from "./registryMetadataFingerprint";
+import { WatchRootResolver } from "./watchRootResolver";
+
+export interface CsrDevUpdate {
+  generation: number;
+  reload: boolean;
+  reason?: string;
+  patchUrl?: string;
+  changedIds: string[];
+  moduleCount: number;
+  epoch?: number;
+  /** The registry did not exist before this build, so no tab holds a module of it. */
+  first?: boolean;
+}
+
+export interface CsrDevUpdateOptions {
+  /** Called once an update exists: for a patch before app.js is rewritten, for a reload after everything is on disk. */
+  announce?: (update: CsrDevUpdate) => void;
+  /** Files the registry must hold once this update is done; the ones it lacks are compiled into it. */
+  roots?: string[];
+  /**
+   * Compile only the roots the registry lacks: a route build asks for its entries, and a file saved meanwhile is the
+   * save's own patch to make, with the hold only that patch knows.
+   */
+  onlyRoots?: boolean;
+}
+
+export interface DevRegistryTarget {
+  dirName: string;
+  routePrefix: string;
+  library: boolean;
+}
+
+//* A dev module registry under `.akan/artifact/<dirName>`: this owns the context, the entries and the full build;
+//* `CsrDevPatcher` owns the incremental path, which the resident builder keeps in memory between saves.
+export abstract class DevRegistryBundler {
+  readonly outDir: string;
+  readonly routePrefix: string;
+  readonly paths: CsrDevPaths;
+  readonly writer: CsrDevArtifactWriter;
+  protected readonly app: App;
+  protected readonly entryDir: string;
+  /** A CSR entry holds the route table, so moving one reloads the tab; an SSR root is one more module to hold. */
+  abstract readonly reloadsOnEntryChange: boolean;
+
+  constructor(app: App, { dirName, routePrefix, library }: DevRegistryTarget) {
+    this.app = app;
+    this.routePrefix = routePrefix;
+    this.paths = new CsrDevPaths(app.workspace.workspaceRoot);
+    this.outDir = path.join(app.cwdPath, ".akan/artifact", dirName);
+    this.entryDir = path.join(app.cwdPath, ".akan/generated", dirName);
+    this.writer = new CsrDevArtifactWriter(this.outDir, { routePrefix, library });
+  }
+
+  /** Null when there is nothing to build. */
+  abstract context(): Promise<CsrDevContext | null>;
+
+  abstract writeEntries(context: CsrDevContext): Promise<{ files: Record<string, string>; changed: string[] }>;
+
+  /** Every file a full build compiles from, the entries included. */
+  protected abstract rootFiles(entryFiles: string[]): Promise<string[]>;
+
+  // A build worker: a throwaway patcher that starts from the disk, and builds everything itself when it cannot patch.
+  async update(changedFiles: string[] = [], options: CsrDevUpdateOptions = {}): Promise<CsrDevUpdate | null> {
+    const result = await new CsrDevPatcher(this).update(changedFiles, { ...options, allowWholeAppBuilds: true });
+    if (result.kind === "unchanged") return null;
+    if (result.kind === "update") return result.update;
+    const built = await this.fullBuild(result.context, result.generation, result.reason);
+    const update = result.first ? { ...built, first: true } : built;
+    options.announce?.(update);
+    return update;
+  }
+
+  /** Of these files, the ones the registry still reaches from its roots through imports: those it keeps building. */
+  async wantedRoots(files: string[], graph: CsrDevGraph): Promise<Set<string>> {
+    const reached = await this.reachable(graph);
+    return new Set(files.filter((file) => reached.has(this.paths.idOf(file))));
+  }
+
+  /** The ids its roots reach through imports, the refresh runtime included. */
+  async reachable(graph: CsrDevGraph): Promise<Set<string>> {
+    const roots = await this.rootFiles(Object.values(graph.entries).map((id) => this.paths.fileOf(id)));
+    const reached = new Set<string>();
+    const stack = [graph.refresh, ...roots.map((file) => this.paths.idOf(file))];
+    for (let id = stack.pop(); id !== undefined; id = stack.pop()) {
+      if (reached.has(id)) continue;
+      reached.add(id);
+      stack.push(...(graph.modules[id]?.deps ?? []));
+    }
+    return reached;
+  }
+
+  async holds(files: string[]): Promise<boolean> {
+    const graph = await this.writer.readJson<CsrDevGraph>("graph.json");
+    return graph !== null && files.every((file) => graph.modules[this.paths.idOf(file)] !== undefined);
+  }
+
+  /** A save of one goes to a whole build: `lib/useClient.ts` inlines what they declare through macros. */
+  isMetadataFile(file: string): boolean {
+    return isAkanRuntimeMetadataFile(file);
+  }
+
+  async metadataFingerprint(): Promise<string> {
+    const libsContainer = path.resolve(this.app.workspace.workspaceRoot, "libs");
+    const roots = await new WatchRootResolver(this.app).resolve();
+    // The whole container comes back when the lib dependencies are unknown (before the first sync).
+    const libRoots = roots.includes(libsContainer)
+      ? fs.readdirSync(libsContainer).map((name) => path.join(libsContainer, name))
+      : roots.filter((root) => path.dirname(root) === libsContainer);
+    return await RegistryMetadataFingerprint.of([path.resolve(this.app.cwdPath), ...libRoots], (file) =>
+      this.isMetadataFile(file),
+    );
+  }
+
+  //? Compiled before anything is written: a build that fails (a module the user broke) leaves the registry the tabs
+  //? and the next patch read as it was, where clearing the directory first left no registry at all.
+  async fullBuild(context: CsrDevContext, generation: number, reason: string): Promise<CsrDevUpdate> {
+    const metadata = await this.metadataFingerprint();
+    const entries = await this.writeEntries(context);
+    const roots = await this.rootFiles(Object.values(entries.files));
+    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(
+      [...roots, ...(context.refreshFile ? [context.refreshFile] : [])],
+      new Set(),
+    );
+    const graph: CsrDevGraph = {
+      version: 1,
+      configKey: context.configKey,
+      refresh: context.refreshFile
+        ? this.paths.idOf(context.refreshFile)
+        : `${CsrDevPaths.vendorPrefix}react-refresh/runtime`,
+      entries: this.entryIds(entries.files),
+      modules: {},
+      resolution: {},
+      pending: [],
+      metadata,
+    };
+    this.merge(graph, resolver, compiled);
+    await this.writer.markBuilding();
+    await this.writer.writeModules(compiled);
+    const vendorFile = await this.writer.writeVendor(graph);
+    const epoch = Date.now();
+    await this.writer.writeApp(graph, { generation, vendorFile, epoch });
+    await this.writer.writeState(graph, { version: 1, generation, vendorFile, entries: graph.entries, epoch });
+    await this.writer.pruneAfterFullBuild(graph, vendorFile, { generation, assets: compiler.assets });
+    await this.writer.clearBuilding();
+    return { generation, reload: true, reason, changedIds: [], moduleCount: Object.keys(graph.modules).length, epoch };
+  }
+
+  compiler(context: CsrDevContext, resolver: CsrDevResolver): CsrDevModuleCompiler {
+    return new CsrDevModuleCompiler({
+      app: this.app,
+      paths: this.paths,
+      resolver,
+      context,
+      outDir: this.outDir,
+      routePrefix: this.routePrefix,
+    });
+  }
+
+  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 } : {}),
+      };
+    //? 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));
+    graph.resolution = resolver.serialize();
+    graph.runtimeResolved = resolver.serializeRuntimeResolved();
+  }
+
+  entryIds(files: Record<string, string>): Record<string, string> {
+    return Object.fromEntries(Object.entries(files).map(([key, file]) => [key, this.paths.idOf(file)]));
+  }
+}

package/frontendBuild/hmrWatcher.test.ts

@@ -49,6 +49,57 @@ afterEach(() => {
 const makeRoot = tempDirs("akan-hmr-watcher-");
 
 describe("HmrWatcher", () => {
+  test(
+    "marks when a batch's window opened and when it was handed over",
+    async () => {
+      const root = await makeRoot();
+      const source = await seed(root, "lib/a.ts");
+      const { batches } = await watch(root);
+
+      const writtenAt = Date.now();
+      await writeFile(source, "export const x = 2;\n");
+      await sleep(SETTLE_MS);
+
+      const trace = batches.filter((batch) => batch.files.includes(source)).at(-1)?.trace;
+      expect(trace?.eventAt).toBeGreaterThanOrEqual(writtenAt);
+      expect(trace?.flushAt).toBeGreaterThanOrEqual(trace?.eventAt ?? Number.POSITIVE_INFINITY);
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  test(
+    "takes its debounce window from AKAN_DEV_WATCH_DEBOUNCE_MS when no option names one",
+    async () => {
+      const previous = process.env.AKAN_DEV_WATCH_DEBOUNCE_MS;
+      process.env.AKAN_DEV_WATCH_DEBOUNCE_MS = "400";
+      try {
+        const root = await makeRoot();
+        const source = await seed(root, "lib/a.ts");
+        const batches: ChangeBatch[] = [];
+        // Without the verification scan, which would otherwise hand the batch over at 250ms.
+        const watcher = new HmrWatcher({
+          roots: [root],
+          logger: silentLogger,
+          verifyDelayMs: 0,
+          onBatch: (batch) => void batches.push(batch),
+        });
+        started.push(watcher);
+        await watcher.start();
+        await sleep(STREAM_WARMUP_MS);
+
+        await writeFile(source, "export const x = 3;\n");
+        await sleep(SETTLE_MS);
+
+        const trace = batches.find((batch) => batch.files.includes(source))?.trace;
+        expect((trace?.flushAt ?? 0) - (trace?.eventAt ?? 0)).toBeGreaterThanOrEqual(395);
+      } finally {
+        if (previous === undefined) delete process.env.AKAN_DEV_WATCH_DEBOUNCE_MS;
+        else process.env.AKAN_DEV_WATCH_DEBOUNCE_MS = previous;
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+
   test(
     "reports every file of a save-all",
     async () => {

package/frontendBuild/hmrWatcher.ts

@@ -31,6 +31,7 @@ export class HmrWatcher {
   readonly #index: SourceMtimeIndex;
   #timer: ReturnType<typeof setTimeout> | null = null;
   #verifyTimer: ReturnType<typeof setTimeout> | null = null;
+  #windowStartedAt: number | null = null;
   #stopped = false;
   #flushing = false;
   #unreportedChanges = 0;
@@ -39,7 +40,7 @@ export class HmrWatcher {
 
   constructor(opts: WatcherOptions) {
     this.#roots = [...new Set(opts.roots.map((r) => path.resolve(r)))];
-    this.#debounceMs = opts.debounceMs ?? 80;
+    this.#debounceMs = opts.debounceMs ?? HmrWatcher.#envDebounceMs() ?? 30;
     this.#verifyDelayMs = opts.verifyDelayMs ?? 250;
     this.#onBatch = opts.onBatch;
     this.#logger = opts.logger;
@@ -119,6 +120,7 @@ export class HmrWatcher {
   }
 
   #scheduleFlush(): void {
+    this.#windowStartedAt ??= Date.now();
     if (this.#flushing) return;
     if (this.#timer) clearTimeout(this.#timer);
     this.#timer = setTimeout(() => this.#flush(), this.#debounceMs);
@@ -135,13 +137,19 @@ export class HmrWatcher {
     try {
       while (!this.#stopped) {
         await this.#mergeDetectedChanges();
-        if (this.#pending.size === 0) break;
+        if (this.#pending.size === 0) {
+          this.#windowStartedAt = null;
+          break;
+        }
         const files = Array.from(this.#pending.keys());
         const kinds = new Set(this.#pending.values());
+        const flushAt = Date.now();
+        const trace = { eventAt: this.#windowStartedAt ?? flushAt, flushAt };
+        this.#windowStartedAt = null;
         this.#pending.clear();
         this.#hinted.clear();
         try {
-          await this.#onBatch({ files, kinds });
+          await this.#onBatch({ files, kinds, trace });
         } catch (e) {
           this.#logger.error(`[hmr] onBatch error: ${(e as Error).message}`);
         }
@@ -201,6 +209,12 @@ export class HmrWatcher {
     );
   }
 
+  static #envDebounceMs(): number | null {
+    const raw = process.env.AKAN_DEV_WATCH_DEBOUNCE_MS;
+    const ms = raw ? Number(raw) : Number.NaN;
+    return Number.isInteger(ms) && ms >= 0 ? ms : null;
+  }
+
   // A write in the same window as a delivered event raises no event of its own, so one scan follows each window.
   #scheduleVerify(): void {
     if (this.#stopped || this.#verifyDelayMs <= 0) return;

package/frontendBuild/index.ts

@@ -9,6 +9,7 @@ export * from "./cssCompiler";
 export * from "./cssImportResolver";
 export * from "./devChangePlanner";
 export * from "./devGeneratedIndexSync";
+export * from "./devRegistryBundler";
 export * from "./fontOptimizer";
 export * from "./fontPruner";
 export * from "./hmrChangeClassifier";
@@ -18,8 +19,10 @@ export * from "./pagesEntrySourceGenerator";
 export * from "./precompressArtifacts";
 export * from "./routeClientBuilder";
 export * from "./routesManifestArtifactSerializer";
+export * from "./serverGraphFile";
 export * from "./sourceMtimeIndex";
 export * from "./ssrBaseArtifactBuilder";
+export * from "./ssrDevBundler";
 export * from "./styleContract";
 export * from "./themeValidator";
 export * from "./vendorSpecifiers";

package/frontendBuild/pagesBundleBuilder.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import type { BunPlugin } from "bun";
 import type { PageEntry } from "../artifact/implicitRootLayout";
@@ -9,7 +10,9 @@ import { loaderFor } from "../transforms/moduleSyntax";
 import { transformUseClient } from "../transforms/rscUseClientTransform";
 import { createUseClientBundlePlugin } from "../transforms/useClientBundlePlugin";
 import { bundleDefine } from "./bundleDefine";
+import { CsrDevPaths } from "./csrDevPaths";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
+import { ServerGraphFile } from "./serverGraphFile";
 
 export interface BuildPagesBundleResult {
   bundlePath: string;
@@ -42,6 +45,13 @@ export class PagesBundleBuilder {
       this.#pageEntries ?? (await resolveSsrPageEntriesForApp(this.#app, await this.#app.getPageKeys()));
     const entrySource = PagesEntrySourceGenerator.generate(resolvedEntries);
     const workspaceRoot = this.#app.workspace.workspaceRoot;
+    const dev = this.#command === "start";
+    const clientExports: Record<string, string[]> = {};
+    const onClientModule = dev
+      ? (file: string, exports: string[]) => {
+          clientExports[CsrDevPaths.realpath(file)] = exports;
+        }
+      : undefined;
     const result = await Bun.build({
       entrypoints: [VIRTUAL_PAGES_ENTRY],
       outdir: `${this.#artifactDir}/server`,
@@ -55,6 +65,7 @@ export class PagesBundleBuilder {
         asset: "assets/[name]-[hash].[ext]",
       },
       define: bundleDefine(this.#app, this.#command, "ssr"),
+      metafile: dev,
       plugins: [
         PagesBundleBuilder.createPagesEntryPlugin(entrySource),
         PagesBundleBuilder.createCssStubPlugin(),
@@ -66,9 +77,10 @@ export class PagesBundleBuilder {
                 transformUseClient(source, {
                   path: args.path,
                   workspaceRoot,
+                  onClientModule,
                 }),
             })
-          : createUseClientBundlePlugin({ workspaceRoot }),
+          : createUseClientBundlePlugin({ workspaceRoot, onClientModule }),
       ],
     });
 
@@ -79,6 +91,8 @@ export class PagesBundleBuilder {
 
     const bundlePath = path.resolve(entryArtifact.path);
     const buildId = Date.now();
+    if (dev && result.metafile)
+      await ServerGraphFile.write(this.#artifactDir, this.#serverGraph(result.metafile, clientExports));
     const outputBytes = result.outputs.reduce((sum, output) => sum + output.size, 0);
     const chunkCount = result.outputs.filter((output) => output.kind === "chunk").length;
     this.#app.verbose(
@@ -95,6 +109,15 @@ export class PagesBundleBuilder {
     };
   }
 
+  #serverGraph(metafile: Bun.BuildMetafile, clientExports: Record<string, string[]>) {
+    const inputs = Object.keys(metafile.inputs)
+      .filter((input) => !input.includes("node_modules"))
+      .map((input) => path.resolve(input))
+      .filter((input) => fs.existsSync(input))
+      .map((input) => CsrDevPaths.realpath(input));
+    return { inputs, clientExports };
+  }
+
   get #artifactDir(): string {
     return `${this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath}/.akan/artifact`;
   }

package/frontendBuild/pagesEntrySourceGenerator.ts

@@ -2,12 +2,19 @@ import path from "node:path";
 import type { PageEntry } from "../artifact/implicitRootLayout";
 import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
 
+export interface PagesEntrySourceOptions {
+  /** Detects an async default export; a caller that outlives one generation keeps its own cache across saves. */
+  isAsyncDefault?: (moduleAbsPath: string) => Promise<boolean>;
+}
+
 export class PagesEntrySourceGenerator {
   #pageEntries: PageEntry[];
   readonly #asyncDefaults = new Map<string, Promise<boolean>>();
+  readonly #detect: (moduleAbsPath: string) => Promise<boolean>;
 
-  constructor(pageEntries: PageEntry[]) {
+  constructor(pageEntries: PageEntry[], { isAsyncDefault }: PagesEntrySourceOptions = {}) {
     this.#pageEntries = pageEntries;
+    this.#detect = isAsyncDefault ?? ((moduleAbsPath) => AsyncDefaultExportDetector.detect(moduleAbsPath));
   }
 
   static generate(pageEntries: PageEntry[]): string {
@@ -72,7 +79,7 @@ ${entries.join("\n")}
   #isAsyncDefault(moduleAbsPath: string): Promise<boolean> {
     const known = this.#asyncDefaults.get(moduleAbsPath);
     if (known) return known;
-    const detected = AsyncDefaultExportDetector.detect(moduleAbsPath);
+    const detected = this.#detect(moduleAbsPath);
     this.#asyncDefaults.set(moduleAbsPath, detected);
     return detected;
   }

package/frontendBuild/registryMetadataFingerprint.test.ts

@@ -0,0 +1,63 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { isAkanRuntimeMetadataFile } from "akanjs/server/hmr/runtimeMetadataFile";
+import { RegistryMetadataFingerprint } from "./registryMetadataFingerprint";
+
+describe("RegistryMetadataFingerprint", () => {
+  let root: string;
+  let later = Date.now() / 1000 + 60;
+  const file = (relative: string) => path.join(root, relative);
+  const touch = (relative: string) => {
+    later += 1;
+    fs.utimesSync(file(relative), later, later);
+  };
+  const ssrMetadata = (target: string) =>
+    isAkanRuntimeMetadataFile(target) && !target.endsWith(".dictionary.ts") && path.basename(target) !== "dict.ts";
+  const stamp = async (isMetadataFile = isAkanRuntimeMetadataFile) =>
+    await RegistryMetadataFingerprint.of([root], isMetadataFile);
+
+  beforeAll(async () => {
+    root = await mkdtemp(path.join(os.tmpdir(), "akan-registry-metadata-"));
+    for (const relative of [
+      "lib/sig.ts",
+      "lib/dict.ts",
+      "lib/useClient.ts",
+      "lib/user/user.signal.ts",
+      "lib/user/user.dictionary.ts",
+      "lib/user/User.Zone.tsx",
+      "lib/user/user.signal.test.ts",
+    ])
+      await Bun.write(file(relative), "export {};\n");
+  });
+
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test("moves with a signal save and stays with a component save", async () => {
+    const before = await stamp();
+    touch("lib/user/User.Zone.tsx");
+    touch("lib/user/user.signal.test.ts");
+    expect(await stamp()).toBe(before);
+    touch("lib/user/user.signal.ts");
+    expect(await stamp()).not.toBe(before);
+  });
+
+  test("a registry that inlines no dictionary is not moved by a dictionary save", async () => {
+    const ssrBefore = await stamp(ssrMetadata);
+    const csrBefore = await stamp();
+    touch("lib/user/user.dictionary.ts");
+    touch("lib/dict.ts");
+    expect(await stamp(ssrMetadata)).toBe(ssrBefore);
+    expect(await stamp()).not.toBe(csrBefore);
+  });
+
+  test("a root without a lib folder counts for nothing", async () => {
+    expect(await RegistryMetadataFingerprint.of([root, path.join(root, "lib/user")], isAkanRuntimeMetadataFile)).toBe(
+      await stamp(),
+    );
+  });
+});

package/frontendBuild/registryMetadataFingerprint.ts

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+
+//* The sources `lib/useClient.ts` reads through its macros, which no registry graph lists as a dependency. A registry
+//* records their stamp, so a builder that loads one built before a signal or dictionary save rebuilds it, whichever
+//* process saw that save (a builder restarted for it never finishes the rebuild it started).
+export class RegistryMetadataFingerprint {
+  static readonly #sources = new Bun.Glob("**/*.{signal,dictionary}.ts");
+  static readonly #libFiles = ["sig.ts", "dict.ts", "useClient.ts"];
+
+  /** `roots` are app and lib directories; only the metadata files under each one's `lib/` count. */
+  static async of(roots: string[], isMetadataFile: (file: string) => boolean): Promise<string> {
+    const stamps: string[] = [];
+    for (const root of new Set(roots)) {
+      const libDir = path.join(root, "lib");
+      if (!fs.existsSync(libDir)) continue;
+      const files = RegistryMetadataFingerprint.#libFiles.map((name) => path.join(libDir, name));
+      for await (const relative of RegistryMetadataFingerprint.#sources.scan({ cwd: libDir, onlyFiles: true }))
+        files.push(path.join(libDir, relative));
+      for (const file of files) {
+        if (!isMetadataFile(file)) continue;
+        const stat = fs.statSync(file, { throwIfNoEntry: false });
+        if (stat) stamps.push(`${file}:${stat.mtimeMs}:${stat.size}`);
+      }
+    }
+    return Bun.hash(stamps.sort((a, b) => a.localeCompare(b)).join("\n")).toString(36);
+  }
+}