@akanjs/devkit 3.0.0-alpha.11 → 3.0.0-alpha.111

package/frontendBuild/fontOptimizer.test.ts

@@ -17,15 +17,16 @@ const makeApp = async (layoutSource: string) => {
   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 warnings: string[] = [];
   const app = {
     cwdPath,
     dist: { cwdPath: path.join(root, "dist/apps/demo") },
     workspace: { workspaceRoot: root },
     getPageKeys: async () => ["./_layout.tsx"],
     verbose: () => undefined,
-    logger: { warn: () => undefined },
+    logger: { warn: (message: string) => warnings.push(message) },
   } as unknown as App;
-  return { app, cwdPath };
+  return { app, cwdPath, warnings };
 };
 
 const layoutWith = (extra = "") => `
@@ -40,6 +41,22 @@ export default function Layout() {
 }
 `;
 
+const chainLayoutWith = (declaration: string) => `
+import { rootLayout } from "akanjs/client";
+
+export default rootLayout()
+  .fonts(${declaration})
+  .theme("dark")
+  .render(({ children }) => children);
+`;
+
+const chainFontEntry = (extra = "") => `{
+      name: "Assistant",${extra}
+      paths: [{ src: "/fonts/Assistant-Regular.woff2", weight: 400 }],
+    }`;
+
+const chainFontList = (extra = "") => `[\n    ${chainFontEntry(extra)},\n  ]`;
+
 const optimize = (app: App) => new FontOptimizer(app, "start").optimize();
 
 afterEach(async () => {
@@ -109,3 +126,59 @@ describe("FontOptimizer cache", () => {
     expect(result.files).toEqual([]);
   });
 });
+
+describe("FontOptimizer discovery", () => {
+  test("reads the .fonts() stage of a rootLayout() chain", async () => {
+    const { app, warnings } = await makeApp(chainLayoutWith(chainFontList()));
+
+    const result = await optimize(app);
+
+    expect(result.fonts.map((font) => font.name)).toEqual(["Assistant"]);
+    expect(result.files).toHaveLength(1);
+    expect(result.css).toContain("@font-face");
+    expect(warnings).toEqual([]);
+  });
+
+  test("keeps reading the legacy fonts export", async () => {
+    const { app } = await makeApp(layoutWith());
+    const result = await optimize(app);
+    expect(result.fonts.map((font) => font.name)).toEqual(["Assistant"]);
+    expect(result.files).toHaveLength(1);
+  });
+
+  test("picks up a config field the chain declares, so the cache key sees it", async () => {
+    const { app, cwdPath } = await makeApp(chainLayoutWith(chainFontList()));
+    const first = await optimize(app);
+
+    await writeFile(
+      path.join(cwdPath, "page/_layout.tsx"),
+      chainLayoutWith(chainFontList(`\n      className: "font-brand",`)),
+    );
+
+    const second = await optimize(app);
+    expect(second.css).not.toBe(first.css);
+    expect(second.css).toContain(".font-brand");
+  });
+
+  // A list the build cannot read subsets nothing while the runtime still preloads /_akan/fonts, so the 404s
+  // have to be announced at build time rather than found in a browser console.
+  test("warns when the chain is handed a font list it cannot read", async () => {
+    const { app, warnings } = await makeApp(chainLayoutWith("brandFonts"));
+
+    const result = await optimize(app);
+
+    expect(result.fonts).toEqual([]);
+    expect(result.files).toEqual([]);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("page/_layout.tsx");
+  });
+
+  test("warns about an entry it cannot read and keeps the ones it can", async () => {
+    const { app, warnings } = await makeApp(chainLayoutWith(`[...brandFonts, ${chainFontEntry()}]`));
+
+    const result = await optimize(app);
+
+    expect(result.fonts.map((font) => font.name)).toEqual(["Assistant"]);
+    expect(warnings).toHaveLength(1);
+  });
+});

package/frontendBuild/fontOptimizer.ts

@@ -43,7 +43,9 @@ export class FontOptimizer {
   #woff2Ready: Promise<void> | null = null;
 
   static #ksX1001Text: string | null = null;
-  static readonly #cacheVersion = 1;
+  // 2: the key moved to sha256 over a deterministically ordered `auto` text, so v1 entries cannot be
+  // compared against and their subsets were built from `page`/`ui` only.
+  static readonly #cacheVersion = 2;
 
   constructor(app: App, command: FontOptimizerCommand = "start") {
     this.#app = app;
@@ -96,9 +98,18 @@ export class FontOptimizer {
       }
       // `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()) });
+        sources.push({ autoSubsetText: this.#cacheDigest(await this.#collectAutoSubsetText()) });
     }
-    return this.#hashFontConfig({ version: FontOptimizer.#cacheVersion, fonts, sources });
+    return this.#cacheDigest({ version: FontOptimizer.#cacheVersion, fonts, sources });
+  }
+
+  /**
+   * Cache keys get a cryptographic digest, not the 32-bit FNV `#hashFontConfig` computes for filenames:
+   * a collision there serves a stale subset as if it were current, while a filename only has to be short
+   * and stable.
+   */
+  #cacheDigest(value: unknown) {
+    return new Bun.CryptoHasher("sha256").update(this.#stableStringify(value)).digest("hex");
   }
 
   async #fileStamp(filePath: string): Promise<{ mtimeMs: number; size: number } | null> {
@@ -141,7 +152,7 @@ export class FontOptimizer {
         const file = Bun.file(filePath);
         if (!(await file.exists())) return;
         const source = await file.text();
-        // A declaration named `fonts` cannot exist in text that never mentions it, and parsing the
+        // A `.fonts()` stage or a `fonts` declaration 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));
@@ -175,23 +186,75 @@ export class FontOptimizer {
     if (faceCss.length > 0) this.#cssParts.push(...faceCss, this.#buildRootVariableRule(font));
   }
 
+  /**
+   * The font list of a route file, from the `.fonts([…])` stage of its default-exported `rootLayout()` chain
+   * or from the legacy `export const fonts`. Only an inline literal is readable, because the build enumerates
+   * routes without evaluating them — and a list it cannot read is warned about rather than skipped in silence:
+   * the runtime still emits `/_akan/fonts` preloads for fonts nothing subset, and every one of them 404s.
+   */
   #extractFontsExport(source: string, filePath: string): ReactFont[] {
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-    const fonts: ReactFont[] = [];
+    const declaration = this.#findFontsDeclaration(sourceFile);
+    if (!declaration) return [];
+    const value = this.#literalToValue(declaration);
+    const entries: unknown[] = Array.isArray(value) ? value : [];
+    const fonts = entries.filter((entry): entry is ReactFont => this.#isReadableFont(entry));
+    if (fonts.length !== entries.length || !Array.isArray(value))
+      this.#app.logger.warn(
+        `[font] ${path.relative(this.#app.cwdPath, filePath)} declares fonts the build cannot read without evaluating the module — write the list inline, or nothing is subset for it and every /_akan/fonts request 404s`,
+      );
+    return fonts.map((font) => this.#withFontDefaults(font));
+  }
+
+  #isReadableFont(value: unknown): value is ReactFont {
+    if (!value || typeof value !== "object") return false;
+    const font = value as Partial<ReactFont>;
+    return typeof font.name === "string" && Array.isArray(font.paths);
+  }
+
+  #findFontsDeclaration(sourceFile: ts.SourceFile): ts.Expression | null {
     for (const statement of sourceFile.statements) {
+      if (ts.isExportAssignment(statement)) {
+        if (statement.isExportEquals) continue;
+        const stage = this.#findChainStageArgument(statement.expression, "fonts");
+        if (stage) return stage;
+        continue;
+      }
       if (!ts.isVariableStatement(statement)) continue;
       const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
-      const isExported = modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
-      if (!isExported) continue;
+      if (!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
       for (const declaration of statement.declarationList.declarations) {
         if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "fonts") continue;
-        const value = declaration.initializer ? this.#literalToValue(declaration.initializer) : null;
-        if (Array.isArray(value)) {
-          fonts.push(...(value as ReactFont[]).map((font) => this.#withFontDefaults(font)));
-        }
+        if (declaration.initializer) return declaration.initializer;
       }
     }
-    return fonts;
+    return null;
+  }
+
+  /** Walks a `rootLayout()` chain from its outermost call inward, so the stage that wins at runtime is the one read. */
+  #findChainStageArgument(expression: ts.Expression, stageName: string): ts.Expression | null {
+    let node = this.#unwrapExpression(expression);
+    let argument: ts.Expression | null = null;
+    while (node && ts.isCallExpression(node)) {
+      const callee = this.#unwrapExpression(node.expression);
+      if (!callee) return null;
+      if (ts.isIdentifier(callee)) return callee.text === "rootLayout" ? argument : null;
+      if (!ts.isPropertyAccessExpression(callee)) return null;
+      if (callee.name.text === stageName) argument ??= node.arguments[0] ?? null;
+      node = this.#unwrapExpression(callee.expression);
+    }
+    return null;
+  }
+
+  #unwrapExpression(expression?: ts.Expression): ts.Expression | undefined {
+    let current = expression;
+    while (
+      current &&
+      (ts.isAsExpression(current) || ts.isSatisfiesExpression(current) || ts.isParenthesizedExpression(current))
+    ) {
+      current = current.expression;
+    }
+    return current;
   }
 
   #literalToValue(node: ts.Node): unknown {
@@ -387,26 +450,34 @@ export class FontOptimizer {
     return "";
   }
 
+  /**
+   * Every source that can put a glyph on screen, concatenated in a **stable** order.
+   *
+   * The order is load-bearing even though a glyph set is not: `#buildCacheKey` hashes this string, so
+   * reading the roots concurrently and pushing as each file resolved made the key depend on i/o
+   * scheduling — measured 8 distinct keys over 8 runs against unchanged sources, which means the cache
+   * never hit and every build re-subset the fonts.
+   *
+   * `lib` is in the roots because that is where user-facing text actually lives: a dictionary's
+   * `[en, ko]` pairs are the Korean in the app, and a subset built from `page` and `ui` alone renders
+   * them as tofu — while hashing the same partial text also stopped a new label from invalidating.
+   */
   async #collectAutoSubsetText() {
     //* Synced lib pages hold app-visible text too, and a glob never crosses the symlink that mounts them.
     const libPageRoots = (await this.#app.getPageRoots()).filter((root) => root.keyPrefix).map((root) => root.dir);
-    const roots = [...["page", "ui"].map((dir) => path.join(this.#app.cwdPath, dir)), ...libPageRoots];
+    const roots = [...["page", "ui", "lib"].map((dir) => path.join(this.#app.cwdPath, dir)), ...libPageRoots];
     const glob = new Bun.Glob("**/*.{ts,tsx,js,jsx,html,md}");
     const parts: string[] = [];
-    await Promise.all(
-      roots.map(async (root) => {
-        if (
-          !(await stat(root).then(
-            (entry) => entry.isDirectory(),
-            () => false,
-          ))
-        )
-          return;
-        for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
-          parts.push(await Bun.file(filePath).text());
-        }
-      }),
-    );
+    for (const root of [...new Set(roots)].sort()) {
+      const isDir = await stat(root).then(
+        (entry) => entry.isDirectory(),
+        () => false,
+      );
+      if (!isDir) continue;
+      const filePaths: string[] = [];
+      for await (const filePath of glob.scan({ cwd: root, absolute: true })) filePaths.push(filePath);
+      for (const filePath of filePaths.sort()) parts.push(await Bun.file(filePath).text());
+    }
     return parts.join("");
   }
 

package/frontendBuild/fontPruner.test.ts

@@ -0,0 +1,220 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+import { FontPruner } from "./fontPruner";
+
+const tempRoots: string[] = [];
+
+interface Tree {
+  layout?: string;
+  publicFiles?: Record<string, string>;
+  artifactFiles?: Record<string, string>;
+  csrFiles?: Record<string, string>;
+}
+
+const write = async (root: string, files: Record<string, string>) => {
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(root, rel);
+    await mkdir(path.dirname(abs), { recursive: true });
+    await writeFile(abs, content);
+  }
+};
+
+const makeApp = async ({ layout = layoutWith(), publicFiles = {}, artifactFiles = {}, csrFiles = {} }: Tree = {}) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-font-prune-"));
+  tempRoots.push(root);
+  const cwdPath = path.join(root, "apps/demo");
+  const distPath = path.join(root, "dist/apps/demo");
+  await mkdir(path.join(cwdPath, "page"), { recursive: true });
+  await writeFile(path.join(cwdPath, "page/_layout.tsx"), layout);
+  await write(path.join(distPath, "public"), publicFiles);
+  await write(path.join(distPath, ".akan/artifact"), artifactFiles);
+  await write(path.join(distPath, "csr"), csrFiles);
+  const app = {
+    cwdPath,
+    dist: { cwdPath: distPath },
+    workspace: { workspaceRoot: root },
+    getPageKeys: async () => ["./_layout.tsx"],
+    getPageRoots: async () => [],
+    verbose: () => undefined,
+    logger: { info: () => undefined, warn: () => undefined },
+  } as unknown as App;
+  return { app, distPath };
+};
+
+const layoutWith = (extra = "") => `
+export const fonts = [
+  {
+    name: "pretendard",${extra}
+    paths: [{ src: "/libs/shared/fonts/Pretendard-Bold.woff2", weight: 700 }],
+  },
+];
+export default function Layout() {
+  return null;
+}
+`;
+
+const exists = (distPath: string, rel: string) => Bun.file(path.join(distPath, "public", rel)).exists();
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("FontPruner", () => {
+  test("drops a subset font's source and reports the bytes freed", async () => {
+    const { app, distPath } = await makeApp({
+      publicFiles: { "libs/shared/fonts/Pretendard-Bold.woff2": "x".repeat(2048) },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed.map(({ file }) => file)).toEqual(["libs/shared/fonts/Pretendard-Bold.woff2"]);
+    expect(result.freedBytes).toBe(2048);
+    expect(await exists(distPath, "libs/shared/fonts/Pretendard-Bold.woff2")).toBe(false);
+  });
+
+  test("drops a font no declaration and no surface mentions", async () => {
+    const { app, distPath } = await makeApp({
+      publicFiles: { "libs/shared/fonts/NotoSansKR.ttf": "x" },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed.map(({ file }) => file)).toEqual(["libs/shared/fonts/NotoSansKR.ttf"]);
+    expect(await exists(distPath, "libs/shared/fonts/NotoSansKR.ttf")).toBe(false);
+  });
+
+  test("keeps a font a stylesheet in public loads by url", async () => {
+    const { app, distPath } = await makeApp({
+      publicFiles: {
+        "libs/shared/fonts/Assistant-Bold.woff2": "x",
+        "libs/shared/excalidraw.css": '@font-face{src:url("/libs/shared/fonts/Assistant-Bold.woff2")}',
+      },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept).toEqual([
+      {
+        file: "libs/shared/fonts/Assistant-Bold.woff2",
+        bytes: 1,
+        reason: { kind: "referenced", referrer: "public/libs/shared/excalidraw.css" },
+      },
+    ]);
+    expect(await exists(distPath, "libs/shared/fonts/Assistant-Bold.woff2")).toBe(true);
+  });
+
+  test("keeps a font whose filename a referrer percent-encodes", async () => {
+    const { app } = await makeApp({
+      publicFiles: {
+        "fonts/Lemon Milk Pro Medium.otf": "x",
+        "brand.css": "@font-face{src:url(/fonts/Lemon%20Milk%20Pro%20Medium.otf)}",
+      },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept[0]?.reason).toEqual({ kind: "referenced", referrer: "public/brand.css" });
+  });
+
+  test("keeps the source of a font declared with optimize: false", async () => {
+    const { app, distPath } = await makeApp({
+      layout: layoutWith("\n    optimize: false,"),
+      publicFiles: { "libs/shared/fonts/Pretendard-Bold.woff2": "x" },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept[0]?.reason).toEqual({ kind: "unoptimized" });
+    expect(await exists(distPath, "libs/shared/fonts/Pretendard-Bold.woff2")).toBe(true);
+  });
+
+  test("keeps a font matched by an assets.keepFonts glob", async () => {
+    const { app, distPath } = await makeApp({
+      publicFiles: { "libs/shared/fonts/Assistant-Bold.woff2": "x" },
+    });
+
+    const result = await new FontPruner(app, { keepFonts: ["libs/shared/fonts/Assistant-*.woff2"] }).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept[0]?.reason).toEqual({ kind: "declared", glob: "libs/shared/fonts/Assistant-*.woff2" });
+    expect(await exists(distPath, "libs/shared/fonts/Assistant-Bold.woff2")).toBe(true);
+  });
+
+  test("ignores the declaration the build inlines into its own bundles", async () => {
+    const { app } = await makeApp({
+      artifactFiles: {
+        "server/pages-abc.js": 'const fonts=[{paths:[{src:"/libs/shared/fonts/Pretendard-Bold.woff2"}]}]',
+      },
+      csrFiles: { "index.html": '<script>src:"/libs/shared/fonts/Pretendard-Bold.woff2"</script>' },
+      publicFiles: { "libs/shared/fonts/Pretendard-Bold.woff2": "x" },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed.map(({ file }) => file)).toEqual(["libs/shared/fonts/Pretendard-Bold.woff2"]);
+  });
+
+  test("keeps a font a bundle loads that no declaration names", async () => {
+    const { app } = await makeApp({
+      artifactFiles: { "client/chunk-abc.js": 'new FontFace("x","url(/fonts/Runtime-Regular.woff2)")' },
+      publicFiles: { "fonts/Runtime-Regular.woff2": "x" },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept[0]?.reason).toEqual({ kind: "referenced", referrer: ".akan/artifact/client/chunk-abc.js" });
+  });
+
+  test("keeps a font the compiled stylesheet still points at", async () => {
+    const { app } = await makeApp({
+      artifactFiles: { "styles/root-abc.css": "@font-face{src:url(/libs/shared/fonts/Pretendard-Bold.woff2)}" },
+      publicFiles: { "libs/shared/fonts/Pretendard-Bold.woff2": "x" },
+    });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result.removed).toEqual([]);
+    expect(result.kept[0]?.reason).toEqual({
+      kind: "referenced",
+      referrer: ".akan/artifact/styles/root-abc.css",
+    });
+  });
+
+  test("leaves non-font assets alone", async () => {
+    const { app, distPath } = await makeApp({
+      publicFiles: { "logo.png": "x", "video.mp4": "x", "libs/shared/fonts/NotoSansKR.ttf": "x" },
+    });
+
+    await new FontPruner(app).prune();
+
+    expect(await exists(distPath, "logo.png")).toBe(true);
+    expect(await exists(distPath, "video.mp4")).toBe(true);
+    expect(await exists(distPath, "libs/shared/fonts/NotoSansKR.ttf")).toBe(false);
+  });
+
+  test("does nothing when the build shipped no public directory", async () => {
+    const { app } = await makeApp();
+    await rm(path.join(app.dist.cwdPath, "public"), { recursive: true, force: true });
+
+    const result = await new FontPruner(app).prune();
+
+    expect(result).toEqual({ removed: [], kept: [], freedBytes: 0 });
+  });
+
+  test("removes a directory the prune emptied", async () => {
+    const { app, distPath } = await makeApp({
+      publicFiles: { "libs/shared/fonts/NotoSansKR.ttf": "x" },
+    });
+
+    await new FontPruner(app).prune();
+
+    expect(await Bun.file(path.join(distPath, "public/libs/shared/fonts")).exists()).toBe(false);
+  });
+});