@akanjs/devkit 3.0.0-beta.2 → 3.0.0-beta.20

package/frontendBuild/themeValidator.ts

@@ -1,18 +1,4 @@
-/**
- * WCAG contrast checking over the semantic token pairs. No dependencies, pure functions, and no akanjs
- * runtime import — it has to run inside the lint path.
- *
- * The `--x` / `--x-foreground` pairing is what makes the check possible at all: it says which two values
- * are going to end up on top of each other. That is the guard against a generated palette shipping a site
- * nobody can read.
- *
- * Thresholds (WCAG 2.1):
- *   - body and primary surfaces (background, primary, secondary, accent, neutral, card, popover): 4.5:1,
- *     the AA floor for normal text
- *   - status and secondary pairs (info, success, warning, destructive, open, muted): 3:1, the AA floor for
- *     UI components and large text
- * The shipped light/dark palette in styles.css clears all of them.
- */
+// No akanjs runtime import: this runs inside the lint path.
 
 export interface ThemeContrastViolation {
   scope: string;
@@ -30,6 +16,7 @@ interface PairDef {
   threshold: number;
 }
 
+// WCAG 2.1 AA: 4.5:1 is the floor for normal text, 3:1 for UI components and large text.
 const PAIRS: PairDef[] = [
   { base: "background", fg: "foreground", threshold: 4.5 },
   { base: "primary", fg: "primary-foreground", threshold: 4.5 },
@@ -46,13 +33,11 @@ const PAIRS: PairDef[] = [
   { base: "open", fg: "open-foreground", threshold: 3 },
 ];
 
-// Only these scopes are paired up; tokens scoped to something else (`.campaign-x`, …) are left alone.
 const THEME_SCOPES = new Set([":root", '[data-theme="dark"]', '[data-theme="light"]']);
 
 export type ThemeTokensByScope = Record<string, Record<string, string>>;
 
 export class ThemeValidator {
-  /** Extracts tokens from the css text and checks every scope it recognizes. */
   validate(css: string): ThemeContrastViolation[] {
     const tokensByScope = ThemeValidator.parseThemeTokens(css);
     const violations: ThemeContrastViolation[] = [];
@@ -71,7 +56,7 @@ export class ThemeValidator {
       if (!bg || !front) continue;
       const bgRgb = ThemeValidator.parseHex(bg);
       const fgRgb = ThemeValidator.parseHex(front);
-      if (!bgRgb || !fgRgb) continue; // a var() or non-hex value has no ratio to compute
+      if (!bgRgb || !fgRgb) continue;
       const ratio = ThemeValidator.contrastRatio(bgRgb, fgRgb);
       if (ratio >= threshold) continue;
       violations.push({
@@ -87,15 +72,9 @@ export class ThemeValidator {
     return violations;
   }
 
-  /**
-   * Reads `--token: value` out of `:root` / `[data-theme="…"]` blocks. A grouped selector
-   * (`:root, [data-theme="dark"] { … }`) distributes the same tokens to each selector, and a scope that
-   * appears twice keeps the later value — so passing framework css first and the app's second reflects the
-   * app's overrides.
-   */
+  /** A scope declared twice keeps the later value, so pass the framework css before the app's. */
   static parseThemeTokens(css: string): ThemeTokensByScope {
     const result: ThemeTokensByScope = {};
-    // Flat rule blocks only; an at-rule (@theme, @keyframes) carries `@` in the selector and is skipped.
     const blockRe = /(?:^|})\s*([^{}@]+?)\s*\{([^{}]*)\}/g;
     for (const block of css.matchAll(blockRe)) {
       const selectors = block[1].split(",").map((s) => s.trim());
@@ -114,7 +93,6 @@ export class ThemeValidator {
   }
 
   static #normalizeScope(selector: string): string {
-    // Quote normalization: [data-theme=dark] / [data-theme='dark'] -> [data-theme="dark"]
     return selector.replace(/\[data-theme=['"]?([\w-]+)['"]?\]/g, '[data-theme="$1"]').trim();
   }
 

package/frontendBuild/watchRootResolver.test.ts

@@ -1,15 +1,14 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
+import { tempDirs } from "../testHelpers";
 import { WatchRootResolver } from "./watchRootResolver";
 
-const roots: string[] = [];
+const tempRoot = tempDirs("akan-watch-roots-");
 
 const makeWorkspace = async (dirs: string[]) => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-watch-roots-"));
-  roots.push(root);
+  const root = await tempRoot();
   await Promise.all(dirs.map((dir) => mkdir(path.join(root, dir), { recursive: true })));
   return root;
 };
@@ -25,24 +24,18 @@ interface AppStub {
   libDeps?: string[] | null;
 }
 
-const makeApp = (workspaceRoot: string, name: string, { paths = {}, libDeps = null }: AppStub = {}) =>
-  ({
-    cwdPath: path.join(workspaceRoot, "apps", name),
+const resolveRoots = (workspaceRoot: string, { paths = {}, libDeps = null }: AppStub = {}) =>
+  new WatchRootResolver({
+    cwdPath: path.join(workspaceRoot, "apps", "app1"),
     workspace: { workspaceRoot },
     getTsConfig: async () => ({ compilerOptions: { paths } }),
     getScanInfo: () => (libDeps ? { type: "app", libDeps } : null),
-  }) as unknown as App;
-
-afterEach(async () => {
-  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
+  } as unknown as App).resolve();
 
 describe("WatchRootResolver", () => {
   test("narrows the apps container to the app being served", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "apps/app2/page", "libs/util"]);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@apps/*": ["./apps/*"], "@libs/*": ["./libs/*"] } }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@apps/*": ["./apps/*"], "@libs/*": ["./libs/*"] } });
 
     expect(resolved).toContain(path.join(workspaceRoot, "apps/app1"));
     expect(resolved).not.toContain(path.join(workspaceRoot, "apps"));
@@ -51,9 +44,7 @@ describe("WatchRootResolver", () => {
 
   test("narrows the libs container to the app's own dependencies", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util", "libs/shared"]);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] }, libDeps: ["util"] }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@libs/*": ["./libs/*"] }, libDeps: ["util"] });
 
     expect(resolved).toContain(path.join(workspaceRoot, "libs/util"));
     expect(resolved).not.toContain(path.join(workspaceRoot, "libs"));
@@ -63,9 +54,7 @@ describe("WatchRootResolver", () => {
   test("drops the libs container entirely when the app depends on no lib", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util"]);
     await writeManifest(workspaceRoot, "apps/app1", []);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@libs/*": ["./libs/*"] } });
 
     expect(resolved).toEqual([path.join(workspaceRoot, "apps/app1/page")]);
   });
@@ -76,9 +65,7 @@ describe("WatchRootResolver", () => {
     await writeManifest(workspaceRoot, "libs/shared", ["util"]);
     await writeManifest(workspaceRoot, "libs/util", []);
     await writeManifest(workspaceRoot, "libs/unused", []);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@libs/*": ["./libs/*"] } });
 
     expect(resolved).toContain(path.join(workspaceRoot, "libs/shared"));
     expect(resolved).toContain(path.join(workspaceRoot, "libs/util"));
@@ -87,9 +74,7 @@ describe("WatchRootResolver", () => {
 
   test("keeps the libs container whole when the app manifest is missing", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util", "libs/shared"]);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@libs/*": ["./libs/*"] } });
 
     expect(resolved).toContain(path.join(workspaceRoot, "libs"));
   });
@@ -97,24 +82,20 @@ describe("WatchRootResolver", () => {
   test("keeps the libs container whole when a dependency lib is unsynced", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util", "libs/shared"]);
     await writeManifest(workspaceRoot, "apps/app1", ["shared"]);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@libs/*": ["./libs/*"] } });
 
     expect(resolved).toContain(path.join(workspaceRoot, "libs"));
   });
 
   test("resolves a package alias to its own directory, filename and glob stripped", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "pkgs/akanjs/base"]);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", {
-        paths: {
-          akanjs: ["./pkgs/akanjs/index.ts"],
-          "akanjs/*": ["./pkgs/akanjs/*"],
-          missing: ["./pkgs/nothing/index.ts"],
-        },
-      }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, {
+      paths: {
+        akanjs: ["./pkgs/akanjs/index.ts"],
+        "akanjs/*": ["./pkgs/akanjs/*"],
+        missing: ["./pkgs/nothing/index.ts"],
+      },
+    });
 
     expect(resolved).toContain(path.join(workspaceRoot, "pkgs/akanjs"));
     expect(resolved).not.toContain(path.join(workspaceRoot, "pkgs/nothing"));
@@ -122,7 +103,7 @@ describe("WatchRootResolver", () => {
 
   test("always watches the app's page tree", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page"]);
-    const resolved = await new WatchRootResolver(makeApp(workspaceRoot, "app1")).resolve();
+    const resolved = await resolveRoots(workspaceRoot);
 
     expect(resolved).toEqual([path.join(workspaceRoot, "apps/app1/page")]);
   });

package/frontendBuild/watchRootResolver.ts

@@ -3,23 +3,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
 
-/**
- * The directories one app's dev watcher follows, resolved from its tsconfig `paths`.
- *
- * Two aliases strip down to a workspace container rather than a package, and taking either verbatim puts
- * code the app never imports under the watcher — where a save rebuilds, restarts and reloads it for
- * nothing, and both builders rewrite the same generated barrels:
- *
- * - `@apps/*` becomes the `apps/` container. Apps are leaves of the workspace graph — never one another's
- *   dependencies — so it is replaced by this app's own directory.
- * - `@libs/*` becomes the `libs/` container. A lib is a dependency only if the app reaches it, so it is
- *   replaced by the app's own lib dependencies, transitively. The set is resolved once, at watcher
- *   install: a lib that becomes a dependency mid-session needs a fresh `akan start` anyway, because the
- *   import that made it one also needs a `sync`.
- *
- * Failing to resolve that set keeps the container whole, because a wrong narrowing is a dev server that
- * silently ignores edits.
- */
+/** Watch roots from tsconfig paths: `@apps/*` narrows to this app, `@libs/*` to its lib deps (whole when unknown). */
 export class WatchRootResolver {
   #app: App;
 
@@ -32,14 +16,15 @@ export class WatchRootResolver {
     const appDir = path.resolve(this.#app.cwdPath);
     const appsContainer = path.dirname(appDir);
     const libsContainer = path.resolve(this.#app.workspace.workspaceRoot, "libs");
-    const libRoots = await this.#resolveLibRoots(libsContainer);
+    const libRoots = (await this.#resolveLibDeps(libsContainer))
+      ?.map((name) => path.join(libsContainer, name))
+      .filter((dir) => fs.existsSync(dir));
     const set = new Set<string>();
     set.add(path.resolve(`${this.#app.cwdPath}/page`));
     for (const targets of Object.values(tsconfig.compilerOptions.paths ?? {})) {
       for (const target of targets) {
         if (!target) continue;
         if (path.isAbsolute(target)) continue;
-        // Strip the trailing filename and glob so we watch the package root dir.
         const cleaned = target.replace(/\/?\*+.*$/, "").replace(/\/[^/]+\.[^/]+$/, "");
         const resolved = path.resolve(this.#app.workspace.workspaceRoot, cleaned);
         if (resolved === libsContainer && libRoots) {
@@ -53,16 +38,9 @@ export class WatchRootResolver {
     return [...set];
   }
 
-  async #resolveLibRoots(libsContainer: string): Promise<string[] | null> {
-    const libDeps = await this.#resolveLibDeps(libsContainer);
-    if (!libDeps) return null;
-    return libDeps.map((name) => path.join(libsContainer, name)).filter((dir) => fs.existsSync(dir));
-  }
-
   async #resolveLibDeps(libsContainer: string): Promise<string[] | null> {
     const scanInfo = this.#app.getScanInfo({ allowEmpty: true });
-    // Already transitive, and present whenever this runs in a process that scanned. The builder and the
-    // idle watcher run in processes that did not, so they take the manifests `scan` wrote instead.
+    // Transitive, but only in a process that scanned; the builder and idle watcher read the synced manifests.
     if (scanInfo?.type === "app") return scanInfo.libDeps;
     const direct = await WatchRootResolver.#readManifestLibDeps(path.join(this.#app.cwdPath, "akan.app.json"));
     if (!direct) return null;

package/getRelatedCnsts.ts

@@ -40,9 +40,6 @@ const scanModuleSpecifiers = (source: string, filePath: string, includeExports:
   return importSpecifiers;
 };
 
-/**
- * TypeScript 설정 파일을 읽고 파싱하는 함수
- */
 export const parseTsConfig = (tsConfigPath: string = "./tsconfig.json") => {
   const configFile = ts.readConfigFile(tsConfigPath, (path) => {
     return ts.sys.readFile(path);
@@ -51,85 +48,36 @@ export const parseTsConfig = (tsConfigPath: string = "./tsconfig.json") => {
   return ts.parseJsonConfigFileContent(configFile.config, ts.sys, realpathSync(tsConfigPath).replace(/[^/\\]+$/, ""));
 };
 
-/**
- * 파일 내의 임포트를 기반으로 관련 파일을 수집하는 함수
- */
-export const collectImportedFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine) => {
+const collectFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine, includeExports: boolean) => {
   const allFilesToAnalyze = new Set<string>([constantFilePath]);
   const analyzedFiles = new Set<string>();
-  const spinner = ora("Collecting related files...");
+  const spinner = ora(includeExports ? "Collecting files from exports..." : "Collecting related files...");
   spinner.start();
-
-  function collectImported(filePath: string) {
+  const collect = (filePath: string) => {
     if (analyzedFiles.has(filePath)) return;
     analyzedFiles.add(filePath);
-
     const source = readFileSync(filePath, "utf-8");
-    for (const importPath of scanModuleSpecifiers(source, filePath, false)) {
+    for (const importPath of scanModuleSpecifiers(source, filePath, includeExports)) {
       if (!importPath.startsWith(".")) continue;
-
       const resolved = ts.resolveModuleName(importPath, filePath, parsedConfig.options, ts.sys).resolvedModule
         ?.resolvedFileName;
-
       if (resolved && !allFilesToAnalyze.has(resolved)) {
         allFilesToAnalyze.add(resolved);
-        // 재귀적으로 임포트된 파일의 임포트도 수집
-        collectImported(resolved);
+        collect(resolved);
       }
     }
-  }
-
-  // 임포트 기반 관련 파일 수집 실행
-  collectImported(constantFilePath);
-  spinner.succeed(`Found ${allFilesToAnalyze.size} related files.`);
-
-  return {
-    allFilesToAnalyze,
-    analyzedFiles,
   };
+  collect(constantFilePath);
+  spinner.succeed(`Found ${allFilesToAnalyze.size} related files${includeExports ? " from exports" : ""}.`);
+  return { allFilesToAnalyze, analyzedFiles };
 };
 
-/**
- * export 선언을 기반으로 관련 파일을 수집하는 함수
- */
-export const collectExportedFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine) => {
-  const allFilesToAnalyze = new Set<string>([constantFilePath]);
-  const analyzedFiles = new Set<string>();
-  const spinner = ora("Collecting files from exports...");
-  spinner.start();
-
-  function collectExported(filePath: string) {
-    if (analyzedFiles.has(filePath)) return;
-    analyzedFiles.add(filePath);
+export const collectImportedFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine) =>
+  collectFiles(constantFilePath, parsedConfig, false);
 
-    const source = readFileSync(filePath, "utf-8");
-    for (const importPath of scanModuleSpecifiers(source, filePath, true)) {
-      if (!importPath.startsWith(".")) continue;
+export const collectExportedFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine) =>
+  collectFiles(constantFilePath, parsedConfig, true);
 
-      const resolved = ts.resolveModuleName(importPath, filePath, parsedConfig.options, ts.sys).resolvedModule
-        ?.resolvedFileName;
-
-      if (resolved && !allFilesToAnalyze.has(resolved)) {
-        allFilesToAnalyze.add(resolved);
-        // 재귀적으로 export/import 연결 파일도 확인
-        collectExported(resolved);
-      }
-    }
-  }
-
-  // export 기반 관련 파일 수집 실행
-  collectExported(constantFilePath);
-  spinner.succeed(`Found ${allFilesToAnalyze.size} related files from exports.`);
-
-  return {
-    allFilesToAnalyze,
-    analyzedFiles,
-  };
-};
-
-/**
- * TypeScript 프로그램 생성 함수
- */
 export const createTsProgram = (filePaths: Set<string>, options: ts.CompilerOptions) => {
   const spinner = ora("Creating TypeScript program for all files...");
   spinner.start();
@@ -145,9 +93,6 @@ export const createTsProgram = (filePaths: Set<string>, options: ts.CompilerOpti
   };
 };
 
-/**
- * 심볼 캐싱 및 조회 함수 생성기
- */
 export const createSymbolCache = (checker: ts.TypeChecker) => {
   const symbolCache = new Map<string, ts.Symbol | undefined>();
 
@@ -162,9 +107,6 @@ export const createSymbolCache = (checker: ts.TypeChecker) => {
   };
 };
 
-/**
- * 파일 속성 분석 함수
- */
 export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Program, checker: ts.TypeChecker) => {
   const propertyMap = new Map<
     string,
@@ -185,7 +127,6 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
   const spinner = ora("Analyzing property relationships...");
   spinner.start();
 
-  // 파일 내 속성 분석 함수
   function analyzeFileProperties(filePath: string) {
     if (analyzedFiles.has(filePath)) return;
     analyzedFiles.add(filePath);
@@ -193,23 +134,19 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
     const source = program.getSourceFile(filePath);
     if (!source) return;
 
-    // 소스 라인 캐싱 (한 번만 분할)
     if (!sourceLineCache.has(filePath)) {
       sourceLineCache.set(filePath, source.getFullText().split("\n"));
     }
     const sourceLines = sourceLineCache.get(filePath);
 
-    // 속성 분석 함수
     function visit(node: ts.Node) {
       if (!source) return;
 
-      // 프로퍼티 접근 표현식 처리
       if (ts.isPropertyAccessExpression(node)) {
         const left = node.expression;
         const right = node.name;
         const { line } = ts.getLineAndCharacterOfPosition(source, node.getStart());
 
-        // 패턴 검색 로직 - 기존 문자열 기반 검색 유지
         if (
           ts.isIdentifier(left) &&
           sourceLines &&
@@ -219,14 +156,12 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
           (sourceLines[line]?.includes(`@Field.Prop(() => ${left.text}.${right.text}`) ||
             sourceLines[line].includes(`base.Filter(${left.text}.${right.text},`))
         ) {
-          // 캐싱된 심볼 사용
           const symbol = getCachedSymbol(right);
 
           if (symbol?.declarations && symbol.declarations.length > 0) {
             const key = symbol.declarations[0]?.getSourceFile().fileName.split("/").pop()?.split(".")[0] ?? "";
             const property = propertyMap.get(key);
             const isScalar = symbol.declarations[0]?.getSourceFile().fileName.includes("_") ?? false;
-            // 현재 작업 중인 디렉토리 이전은 제거
             const symbolFilePath = symbol.declarations[0]
               ?.getSourceFile()
               .fileName.replace(`${ts.sys.getCurrentDirectory()}/`, "");
@@ -254,7 +189,6 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
           }
         }
       } else if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
-        // 모듈 선언 표현식 처리
         const importPath = node.moduleSpecifier.text;
 
         if (importPath.startsWith(".")) {
@@ -276,15 +210,12 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
         }
       }
 
-      // 모든 자식 노드 처리
       ts.forEachChild(node, visit);
     }
 
-    // 파일 분석 시작
     visit(source);
   }
 
-  // 모든 파일의 속성 관계 분석
   for (const filePath of filesToAnalyze) {
     analyzeFileProperties(filePath);
   }
@@ -294,21 +225,10 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
   return propertyMap;
 };
 
-/**
- * 메인 함수: 상수 파일 관련 요소 분석
- */
 export const getRelatedCnsts = (constantFilePath: string) => {
-  // 1. TypeScript 설정 파일 읽기 및 파싱
   const parsedConfig = parseTsConfig();
-
-  // 2. 상수 파일 관련 파일 수집 (임포트 기반)
   const { allFilesToAnalyze } = collectImportedFiles(constantFilePath, parsedConfig);
-  // 3. TypeScript 프로그램 생성 및 타입 체커 설정
   const { program, checker } = createTsProgram(allFilesToAnalyze, parsedConfig.options);
-
-  // 4. 파일 속성 분석
   const propertyMap = analyzeProperties(allFilesToAnalyze, program, checker);
-
-  // 5. 결과 반환
   return Array.from(propertyMap.entries()).map(([key, value]) => ({ key, ...value }));
 };

package/incrementalBuilder/buildBatch.proc.ts

@@ -1,8 +1,7 @@
 import path from "node:path";
+import { ApplicationBuildReporter } from "@akanjs/devkit/applicationBuildReporter";
 import type { App } from "@akanjs/devkit/commandDecorators";
-// Subpath imports only, and as few as possible: this process is spawned once per generation, so every
-// eager import is paid on every save. Measured on a 177-route app: `executors` 24ms, `frontendBuild`
-// ~110ms, app config 5ms.
+// Subpath imports only, as few as possible: spawned per generation, this process pays every import on every save.
 import { AppExecutor, WorkspaceExecutor } from "@akanjs/devkit/executors";
 import {
   CsrArtifactBuilder,
@@ -15,19 +14,7 @@ import { Logger } from "akanjs/common";
 import type { BuilderMessage, BuildPhase } from "akanjs/server";
 import type { BuildBatchRequest, BuildBatchResult, OptimizedFonts, PagesBatchCssAssets } from "./buildBatchProtocol";
 
-/**
- * One generation of frontend build work, in a process that exits when it is done.
- *
- * This exists for one reason: `Bun.build` retains native bundler arenas that the process never returns
- * to the OS — `Bun.gc(true)` reclaims nothing and the JS heap stays flat while RSS climbs ~250MB per
- * save. Exit is the only mechanism that gives that memory back, so the work that scales per save lives
- * here rather than in the long-lived watcher.
- *
- * Nothing is cached here, by design. That costs less than it appears to: `CssCompiler` rebuilds its
- * tailwind compilers on every `compileCss` call, and the watcher always asked for `refresh: true`, so
- * there was no warm state to lose. What genuinely had to be preserved travels in the request — the
- * validated page keys and the previous font optimization.
- */
+// `Bun.build` keeps native bundler arenas that `Bun.gc(true)` cannot reclaim; only exiting returns them.
 class BuildBatch {
   #logger = new Logger("BuildBatch");
   #request: BuildBatchRequest;
@@ -40,29 +27,16 @@ class BuildBatch {
   }
 
   async run(): Promise<BuildBatchResult> {
-    // `base` arrives alone, from a builder that cannot serve anything until it finishes.
     if (this.#request.needs.includes("base")) await this.#buildBase();
-    // Ordered the way the watcher used to run them: csr before pages so a csr failure cannot delay the
-    // pages bundle the browser is waiting on, and css last because it depends on the rebuilt client.
+    // Order kept from the in-process build: csr before pages, css last because it depends on the rebuilt client.
     if (this.#request.needs.includes("csr")) await this.#buildCsr();
     if (this.#request.needs.includes("pages")) await this.#buildPages();
     if (this.#request.needs.includes("css")) await this.#buildCss();
     return this.#result;
   }
 
-  /**
-   * Broadcast as soon as a need finishes rather than when the batch does. The browser is waiting on the
-   * pages bundle; making it wait for the css compile behind it would add latency the in-process version
-   * never had, and it would move every artifact write into the window right before the watcher reports
-   * the generation complete — which is where a save issued immediately afterwards gets dropped by Bun's
-   * recursive `fs.watch` (`local/optimize-resource/06-watcher-dropped-event.md`).
-   *
-   * A bare `process.send` is safe here, unlike in the watcher, for one reason: this process ends by
-   * returning from `main`, and a natural exit flushes a pending ipc write (measured: 1MB delivered
-   * 20/20). It is `process.exit` that discards one — so adding an explicit exit to this file, at the end
-   * of `main` or anywhere after an emit, would silently start dropping `css-updated` payloads. Route
-   * sends through `BuilderChannel` if that ever becomes necessary.
-   */
+  // A bare `process.send` is safe only because this process exits by returning from `main`, which flushes ipc;
+  // an explicit `process.exit` after an emit would silently drop payloads (route through BuilderChannel then).
   #emit(message: BuilderMessage): void {
     process.send?.(message);
   }
@@ -80,11 +54,15 @@ class BuildBatch {
     });
   }
 
-  /**
-   * The boot build. Streams nothing: a builder is not serving yet, so there is no phase board to update
-   * and no browser to reload — the watcher learns the outcome from the batch result, and a failure there
-   * is what puts it into degraded watch mode.
-   */
+  // `Bun.build` rejects with an AggregateError whose own message is only "Bundle failed"; the reasons are nested.
+  #fail(need: keyof BuildBatchResult["errors"], label: string, err: unknown): void {
+    const message = ApplicationBuildReporter.formatError(err, this.#request.workspaceRoot);
+    this.#logger.error(`${label} failed: ${message}`);
+    this.#result.errors[need] = message;
+    if (need !== "base") this.#emitStatus(need, message);
+  }
+
+  // Streams nothing: the builder is not serving yet, so the watcher reads the outcome from the batch result.
   async #buildBase(): Promise<void> {
     const started = Date.now();
     try {
@@ -93,9 +71,7 @@ class BuildBatch {
       this.#result.optimizedFonts = optimizedFonts;
       this.#logger.verbose(`base-artifact ok buildId=${artifact.pagesBundleBuildId} (${Date.now() - started}ms)`);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      this.#logger.error(`base-artifact failed: ${message}`);
-      this.#result.errors.base = message;
+      this.#fail("base", "base-artifact", err);
     }
   }
 
@@ -106,10 +82,7 @@ class BuildBatch {
       this.#logger.verbose(`csr-rebundle ok (${Date.now() - started}ms)`);
       this.#emitStatus("csr");
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      this.#logger.error(`csr-rebundle failed: ${message}`);
-      this.#result.errors.csr = message;
-      this.#emitStatus("csr", message);
+      this.#fail("csr", "csr-rebundle", err);
     }
   }
 
@@ -129,10 +102,7 @@ class BuildBatch {
       this.#emitStatus("pages");
       this.#logger.verbose(`pages-rebundle ok buildId=${next.buildId} (${Date.now() - started}ms)`);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      this.#logger.error(`pages-rebundle failed: ${message}`);
-      this.#result.errors.pages = message;
-      this.#emitStatus("pages", message);
+      this.#fail("pages", "pages-rebundle", err);
     }
   }
 
@@ -174,14 +144,10 @@ class BuildBatch {
       });
       this.#logger.verbose(`css-compile ok assets=${Object.keys(cssAssets).length} (${Date.now() - started}ms)`);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      this.#logger.error(`css-rebuild failed: ${message}`);
-      this.#result.errors.css = message;
-      this.#emitStatus("css", message);
+      this.#fail("css", "css-rebuild", err);
     }
   }
 
-  /** Fonts are expensive and rarely change, so the previous result is reused unless this batch touched it. */
   async #optimizeFonts(): Promise<OptimizedFonts> {
     const previous = this.#request.optimizedFonts;
     if (previous && !BuildBatch.#shouldReoptimizeFonts(previous, this.#request.changedFiles)) {
@@ -196,7 +162,6 @@ class BuildBatch {
   }
 
   static #shouldReoptimizeFonts(previous: OptimizedFonts, changedFiles: string[]): boolean {
-    if (changedFiles.length === 0) return false;
     return changedFiles.some((file) => {
       const normalized = path.resolve(file);
       if (/\.(woff2?|ttf|otf)$/i.test(normalized)) return true;
@@ -213,15 +178,15 @@ class BuildBatch {
       repoName: request.repoName,
     });
     const app = AppExecutor.from(workspace, request.appName);
-    // Seeded rather than rediscovered: the watcher already globbed and validated every route source,
-    // and repeating that here would be the single largest cost of spawning this process.
+    // Seeded, not rediscovered: route discovery would be the largest cost of spawning this process.
     if (request.pageKeys) app.setPageKeys(request.pageKeys);
     const result = await new BuildBatch(request, app).run();
     process.send?.({ type: "build-batch-result", data: result });
   }
 }
 
-void BuildBatch.main().catch((err) => {
+// Awaited, not voided: on Windows Bun exits during a missing file's `Bun.file` read unless an entry await is pending.
+await BuildBatch.main().catch((err) => {
   console.error(err);
   process.exit(1);
 });