@akanjs/devkit 2.4.1-rc.3 → 2.4.1-rc.5

package/frontendBuild/fontOptimizer.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+import { FontOptimizer } from "./fontOptimizer";
+
+const SOURCE_FONT = path.resolve(import.meta.dir, "../../../../libs/shared/public/fonts/Assistant-Regular.woff2");
+
+const tempRoots: string[] = [];
+
+const makeApp = async (layoutSource: string) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-font-"));
+  tempRoots.push(root);
+  const cwdPath = path.join(root, "apps/demo");
+  await mkdir(path.join(cwdPath, "page"), { recursive: true });
+  await mkdir(path.join(cwdPath, "public/fonts"), { recursive: true });
+  await writeFile(path.join(cwdPath, "page/_layout.tsx"), layoutSource);
+  await Bun.write(path.join(cwdPath, "public/fonts/Assistant-Regular.woff2"), Bun.file(SOURCE_FONT));
+  const app = {
+    cwdPath,
+    dist: { cwdPath: path.join(root, "dist/apps/demo") },
+    workspace: { workspaceRoot: root },
+    getPageKeys: async () => ["./_layout.tsx"],
+    verbose: () => undefined,
+    logger: { warn: () => undefined },
+  } as unknown as App;
+  return { app, cwdPath };
+};
+
+const layoutWith = (extra = "") => `
+export const fonts = [
+  {
+    name: "Assistant",${extra}
+    paths: [{ src: "/fonts/Assistant-Regular.woff2", weight: 400 }],
+  },
+];
+export default function Layout() {
+  return null;
+}
+`;
+
+const optimize = (app: App) => new FontOptimizer(app, "start").optimize();
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("FontOptimizer cache", () => {
+  test("reuses subset output instead of resubsetting an unchanged font", async () => {
+    const { app } = await makeApp(layoutWith());
+
+    const first = await optimize(app);
+    expect(first.files).toHaveLength(1);
+    expect(first.css).toContain("@font-face");
+    const writtenAt = (await stat(first.files[0])).mtimeMs;
+
+    const second = await optimize(app);
+    expect(second.files).toEqual(first.files);
+    expect(second.css).toBe(first.css);
+    expect(second.fonts).toEqual(first.fonts);
+    // The output was reused, not rewritten — the whole point of the cache.
+    expect((await stat(second.files[0])).mtimeMs).toBe(writtenAt);
+  });
+
+  test("resubsets when the source font file changes", async () => {
+    const { app, cwdPath } = await makeApp(layoutWith());
+    const first = await optimize(app);
+    const firstBytes = await Bun.file(first.files[0]).bytes();
+
+    // Swapped for a different real font rather than corrupted, so the resubset itself still succeeds.
+    const sourcePath = path.join(cwdPath, "public/fonts/Assistant-Regular.woff2");
+    await Bun.write(sourcePath, Bun.file(path.resolve(path.dirname(SOURCE_FONT), "Assistant-Bold.woff2")));
+
+    const second = await optimize(app);
+    expect(second.files).toEqual(first.files);
+    expect(await Bun.file(second.files[0]).bytes()).not.toEqual(firstBytes);
+  });
+
+  test("resubsets when a config field changes without changing the output filename", async () => {
+    const { app, cwdPath } = await makeApp(layoutWith());
+    const first = await optimize(app);
+    const writtenAt = (await stat(first.files[0])).mtimeMs;
+
+    // `className` never feeds the output filename hash, so only the cache key can catch it.
+    await writeFile(path.join(cwdPath, "page/_layout.tsx"), layoutWith(`\n    className: "font-brand",`));
+
+    const second = await optimize(app);
+    expect(second.files).toEqual(first.files);
+    expect(second.css).not.toBe(first.css);
+    expect(second.css).toContain(".font-brand");
+    expect((await stat(second.files[0])).mtimeMs).not.toBe(writtenAt);
+  });
+
+  test("ignores a cache whose output file is gone", async () => {
+    const { app } = await makeApp(layoutWith());
+    const first = await optimize(app);
+    await rm(first.files[0]);
+
+    const second = await optimize(app);
+    expect(second.files).toEqual(first.files);
+    expect(await Bun.file(second.files[0]).exists()).toBe(true);
+  });
+
+  test("skips route files that never mention fonts", async () => {
+    const { app } = await makeApp("export default function Layout() {\n  return null;\n}\n");
+    const result = await optimize(app);
+    expect(result.fonts).toEqual([]);
+    expect(result.files).toEqual([]);
+  });
+});

package/frontendBuild/fontOptimizer.ts

@@ -1,4 +1,4 @@
-import { mkdir } from "node:fs/promises";
+import { mkdir, stat } from "node:fs/promises";
 import path from "node:path";
 import type {
   ReactFont,
@@ -8,15 +8,7 @@ import type {
   ReactFontStyle,
   ReactFontSubset,
 } from "akanjs/client";
-import {
-  type FontCategory,
-  generateFontFace,
-  getMetricsForFamily,
-  readMetrics,
-  resolveCategoryFallbacks,
-} from "fontaine";
-import { createFont, woff2 } from "fonteditor-core";
-import subsetFont from "subset-font";
+import type { FontCategory } from "fontaine";
 import ts from "typescript";
 import type { App } from "../commandDecorators";
 
@@ -29,6 +21,17 @@ export interface OptimizeAppFontsResult {
   files: string[];
 }
 
+/**
+ * Lets a boot that changed nothing about its fonts skip re-subsetting them. `files` is stored relative
+ * to the artifact root so the `build` and `start` roots keep independent, relocatable caches.
+ */
+interface FontOptimizerCache {
+  version: number;
+  key: string;
+  css: string;
+  files: string[];
+}
+
 export type FontOptimizerCommand = "build" | "start";
 
 export class FontOptimizer {
@@ -40,6 +43,7 @@ export class FontOptimizer {
   #woff2Ready: Promise<void> | null = null;
 
   static #ksX1001Text: string | null = null;
+  static readonly #cacheVersion = 1;
 
   constructor(app: App, command: FontOptimizerCommand = "start") {
     this.#app = app;
@@ -49,13 +53,83 @@ export class FontOptimizer {
 
   async optimize(): Promise<OptimizeAppFontsResult> {
     const fonts = await this.discoverFonts();
+    const cacheKey = await this.#buildCacheKey(fonts);
+    const cached = cacheKey ? await this.#readCache(cacheKey) : null;
+    if (cached) {
+      this.#app.verbose(`[font] reused ${cached.files.length} cached file(s); skipped subsetting`);
+      return { css: cached.css, fonts, files: cached.files };
+    }
     for (const font of fonts) {
       if (!this.#isFontOptimizationEnabled(font)) continue;
       await this.#optimizeFont(font);
     }
     const fontUtilityCss = this.#buildFontUtilityRules(fonts);
     if (fontUtilityCss) this.#cssParts.push(fontUtilityCss);
-    return { css: this.#cssParts.join("\n"), fonts, files: this.#files };
+    const result = { css: this.#cssParts.join("\n"), fonts, files: this.#files };
+    if (cacheKey) await this.#writeCache(cacheKey, result);
+    return result;
+  }
+
+  get #cachePath() {
+    return path.join(this.#artifactRoot, "fontCache.json");
+  }
+
+  /**
+   * Null means "do not cache this run": a source we cannot stat is a source whose staleness we cannot
+   * detect, and the uncached path is also the one that warns about it.
+   */
+  async #buildCacheKey(fonts: ReactFont[]): Promise<string | null> {
+    const sources: unknown[] = [];
+    for (const font of fonts) {
+      if (!this.#isFontOptimizationEnabled(font)) continue;
+      for (const face of this.#getFontFaces(font)) {
+        const sourcePath = await this.#resolveFontSourcePath(face.src);
+        const stamp = sourcePath ? await this.#fileStamp(sourcePath) : null;
+        if (!stamp) return null;
+        sources.push({ optimizedSrc: face.optimizedSrc, ...stamp });
+      }
+      for (const filePath of font.subsetFiles ?? []) {
+        const abs = path.isAbsolute(filePath) ? filePath : path.join(this.#app.cwdPath, filePath);
+        const stamp = await this.#fileStamp(abs);
+        if (!stamp) return null;
+        sources.push({ subsetFile: filePath, ...stamp });
+      }
+      // `auto` derives the subset from app source text, which no font config hash can capture.
+      if (this.#getFontSubsets(font).includes("auto"))
+        sources.push({ autoSubsetText: this.#hashFontConfig(await this.#collectAutoSubsetText()) });
+    }
+    return this.#hashFontConfig({ version: FontOptimizer.#cacheVersion, fonts, sources });
+  }
+
+  async #fileStamp(filePath: string): Promise<{ mtimeMs: number; size: number } | null> {
+    try {
+      const stats = await stat(filePath);
+      return { mtimeMs: Math.round(stats.mtimeMs), size: stats.size };
+    } catch {
+      return null;
+    }
+  }
+
+  async #readCache(key: string): Promise<{ css: string; files: string[] } | null> {
+    const cache = (await Bun.file(this.#cachePath)
+      .json()
+      .catch(() => null)) as FontOptimizerCache | null;
+    if (cache?.version !== FontOptimizer.#cacheVersion || cache.key !== key) return null;
+    const files = cache.files.map((relativePath) => path.join(this.#artifactRoot, relativePath));
+    for (const filePath of files) {
+      if (!(await Bun.file(filePath).exists())) return null;
+    }
+    return { css: cache.css, files };
+  }
+
+  async #writeCache(key: string, result: OptimizeAppFontsResult): Promise<void> {
+    const cache: FontOptimizerCache = {
+      version: FontOptimizer.#cacheVersion,
+      key,
+      css: result.css,
+      files: result.files.map((filePath) => path.relative(this.#artifactRoot, filePath)),
+    };
+    await Bun.write(this.#cachePath, JSON.stringify(cache));
   }
 
   async discoverFonts(): Promise<ReactFont[]> {
@@ -66,7 +140,11 @@ export class FontOptimizer {
         const filePath = path.resolve(this.#app.cwdPath, "page", key);
         const file = Bun.file(filePath);
         if (!(await file.exists())) return;
-        fonts.push(...this.#extractFontsExport(await file.text(), filePath));
+        const source = await file.text();
+        // A declaration named `fonts` cannot exist in text that never mentions it, and parsing the
+        // route files that never declare one is what a cached optimize() otherwise spends its time on.
+        if (!source.includes("fonts")) return;
+        fonts.push(...this.#extractFontsExport(source, filePath));
       }),
     );
     return this.#dedupeFonts(fonts);
@@ -85,10 +163,7 @@ export class FontOptimizer {
       await mkdir(path.dirname(outputPath), { recursive: true });
 
       const sourceBuffer = Buffer.from(await Bun.file(sourcePath).arrayBuffer());
-      const outputBuffer =
-        font.subset === false
-          ? await this.#convertToWoff2(sourceBuffer, sourcePath)
-          : await subsetFont(sourceBuffer, await this.#getSubsetText(font), { targetFormat: "woff2" });
+      const outputBuffer = await this.#buildFontBuffer(font, sourceBuffer, sourcePath);
       await Bun.write(outputPath, outputBuffer);
       this.#files.push(outputPath);
 
@@ -255,14 +330,23 @@ export class FontOptimizer {
     return null;
   }
 
+  /** `subset-font`, `fonteditor-core` and `fontaine` are imported here rather than at module scope so a
+   * cache hit — the common case once the cache exists — loads none of them. */
+  async #buildFontBuffer(font: ReactFont, sourceBuffer: Buffer, sourcePath: string) {
+    if (font.subset === false) return this.#convertToWoff2(sourceBuffer, sourcePath);
+    const { default: subsetFont } = await import("subset-font");
+    return subsetFont(sourceBuffer, await this.#getSubsetText(font), { targetFormat: "woff2" });
+  }
+
   async #convertToWoff2(buffer: Buffer, sourcePath: string) {
+    const { createFont } = await import("fonteditor-core");
     await this.#initWoff2();
     const font = createFont(buffer, { type: this.#getFontType(sourcePath, buffer) });
     return font.write({ type: "woff2", toBuffer: true });
   }
 
   async #initWoff2() {
-    this.#woff2Ready ??= woff2.init().then(() => undefined);
+    this.#woff2Ready ??= import("fonteditor-core").then(({ woff2 }) => woff2.init()).then(() => undefined);
     return this.#woff2Ready;
   }
 
@@ -363,6 +447,7 @@ export class FontOptimizer {
 
   async #buildFontaineFallbackCss(font: ReactFont, face: ReactFontFace, outputPath: string) {
     if (font.adjustFontFallback === false) return "";
+    const { generateFontFace, getMetricsForFamily, readMetrics, resolveCategoryFallbacks } = await import("fontaine");
     const metrics = await readMetrics(outputPath).catch(() => null);
     if (!metrics) return "";
     const fallbacks = resolveCategoryFallbacks({

package/frontendBuild/hmrWatcher.test.ts

@@ -0,0 +1,191 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { Logger } from "akanjs/common";
+import { type ChangeBatch, HmrWatcher } from "./hmrWatcher";
+
+/**
+ * These run against the real Bun watcher rather than a fake, because the behaviour under test only
+ * exists there: Bun 1.3.14's recursive `fs.watch` reports about one path per ~200ms coalescing window and
+ * discards the rest (`local/optimize-resource/06-watcher-dropped-event.md`). A fake that delivered every
+ * event would pass no matter what the watcher did with them.
+ */
+const STREAM_WARMUP_MS = 600;
+const SETTLE_MS = 1_500;
+const TEST_TIMEOUT_MS = 15_000;
+
+const started: HmrWatcher[] = [];
+const roots: string[] = [];
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Every level `HmrWatcher` can reach, so adding a log line cannot fail a test for the wrong reason. */
+const silentLogger = {
+  trace: () => undefined,
+  verbose: () => undefined,
+  debug: () => undefined,
+  log: () => undefined,
+  info: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+} as unknown as Logger;
+
+const makeRoot = async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-hmr-watcher-"));
+  roots.push(root);
+  return root;
+};
+
+const seed = async (root: string, rel: string, content = "export const x = 1;\n") => {
+  const abs = path.join(root, rel);
+  await mkdir(path.dirname(abs), { recursive: true });
+  await writeFile(abs, content);
+  return abs;
+};
+
+/** Start watching and let the FSEvents stream come up; events raised before it does are not delivered. */
+const watch = async (root: string) => {
+  const batches: ChangeBatch[] = [];
+  const watcher = new HmrWatcher({
+    roots: [root],
+    logger: silentLogger,
+    onBatch: (batch) => void batches.push(batch),
+  });
+  started.push(watcher);
+  await watcher.start();
+  await sleep(STREAM_WARMUP_MS);
+  return { watcher, batches, seen: () => new Set(batches.flatMap((batch) => batch.files)) };
+};
+
+afterEach(async () => {
+  for (const watcher of started.splice(0)) watcher.stop();
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("HmrWatcher", () => {
+  test(
+    "reports every file of a save-all",
+    async () => {
+      const root = await makeRoot();
+      const files = await Promise.all([0, 1, 2, 3, 4].map((i) => seed(root, `lib/File${i}.ts`)));
+      const { batches, seen, watcher } = await watch(root);
+
+      // No gaps between writes, so they share one coalescing window and Bun names at most one of them.
+      for (const [i, abs] of files.entries()) await writeFile(abs, `export const x = ${i}00;\n`);
+      await sleep(SETTLE_MS);
+
+      expect(batches.length).toBeGreaterThan(0);
+      for (const abs of files) expect([...seen()]).toContain(abs);
+      // Not asserted as non-zero: the point is that the outcome above holds whether or not Bun drops
+      // events, so this suite keeps passing if the upstream defect is ever fixed. The counter is the
+      // signal for when the compensation can be removed.
+      expect(watcher.unreportedChanges).toBeGreaterThanOrEqual(0);
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  test(
+    "reports a save that lands in the same window as a build's artifact burst",
+    async () => {
+      const root = await makeRoot();
+      const source = await seed(root, "lib/a.ts");
+      const { seen, batches } = await watch(root);
+
+      // What every build ends with: a burst under `.akan/`, which the classifier ignores. Before this
+      // was handled, the burst was the one path Bun reported and the save right after it was invisible.
+      const artifactDir = path.join(root, ".akan", "artifact", "server");
+      await mkdir(artifactDir, { recursive: true });
+      for (let i = 0; i < 60; i++) await writeFile(path.join(artifactDir, `chunk-${i}.js`), "x".repeat(8192));
+      await writeFile(path.join(artifactDir, "pages.js"), "y".repeat(4 * 1024 * 1024));
+      await writeFile(source, "export const x = 999;\n");
+      await sleep(SETTLE_MS);
+
+      expect([...seen()]).toContain(source);
+      // Exactly one batch for one save. Bun does deliver a real event for some paths the scan has already
+      // emitted, and counting both produced a second generation and a second build for no change.
+      expect(batches.filter((batch) => batch.files.includes(source))).toHaveLength(1);
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  test(
+    "raises no batch for build output alone",
+    async () => {
+      const root = await makeRoot();
+      await seed(root, "lib/a.ts");
+      const { batches } = await watch(root);
+
+      const artifactDir = path.join(root, ".akan", "artifact");
+      await mkdir(artifactDir, { recursive: true });
+      for (let i = 0; i < 20; i++) await writeFile(path.join(artifactDir, `chunk-${i}.js`), "x".repeat(4096));
+      await sleep(SETTLE_MS);
+
+      // The verification scan is triggered by ignored paths, so it must not invent work from them either.
+      expect(batches).toEqual([]);
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  test(
+    "classifies a stylesheet edit as css and a config edit as config",
+    async () => {
+      const root = await makeRoot();
+      const style = await seed(root, "ui/app.css", ".a{color:red}\n");
+      const config = await seed(root, "akan.config.ts", "export default {};\n");
+      const { batches } = await watch(root);
+
+      await writeFile(style, ".a{color:blue}\n");
+      await sleep(400);
+      await writeFile(config, "export default { basePaths: [] };\n");
+      await sleep(SETTLE_MS);
+
+      const kinds = new Set(batches.flatMap((batch) => [...batch.kinds]));
+      expect(kinds.has("css")).toBe(true);
+      expect(kinds.has("config")).toBe(true);
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  test(
+    "stops reporting after stop()",
+    async () => {
+      const root = await makeRoot();
+      const source = await seed(root, "lib/a.ts");
+      const { watcher, batches } = await watch(root);
+
+      watcher.stop();
+      await writeFile(source, "export const x = 5;\n");
+      await sleep(SETTLE_MS);
+
+      expect(batches).toEqual([]);
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  test.skipIf(process.getuid?.() === 0)(
+    "warns at startup when part of the tree cannot be read",
+    async () => {
+      const root = await makeRoot();
+      const hidden = await seed(root, "locked/b.ts");
+      await chmod(path.dirname(hidden), 0o000);
+      const warnings: string[] = [];
+
+      const watcher = new HmrWatcher({
+        roots: [root],
+        logger: { ...silentLogger, warn: (msg: string) => void warnings.push(msg) } as unknown as Logger,
+        onBatch: () => undefined,
+      });
+      started.push(watcher);
+      await watcher.start();
+      // Restored before asserting, not after: a failed assertion would otherwise leave a directory `rm`
+      // cannot traverse, and the leak would fail the *next* test instead of this one.
+      await chmod(path.dirname(hidden), 0o755);
+
+      // At startup rather than at the first save, because an unreadable root means edits under it never
+      // rebuild — waiting for a save to reveal that means waiting for the save that silently does nothing.
+      expect(warnings).toHaveLength(1);
+      expect(warnings[0]).toContain("will not rebuild");
+      expect(warnings[0]).toContain("EACCES");
+    },
+    TEST_TIMEOUT_MS,
+  );
+});