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

package/frontendBuild/cssCompiler.ts

@@ -1,13 +1,13 @@
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import { compile } from "tailwindcss";
+import { SOURCE_EXTS } from "../akanApp/devHostPolicy";
 import type { App } from "../commandDecorators";
 import { BarrelAnalyzer } from "../transforms/barrelAnalyzer";
 import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
 import { CssCandidateCache } from "./cssCandidateCache";
 import { CssImportResolver } from "./cssImportResolver";
 
-const SOURCE_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"] as const;
 const NON_SOURCE_EXT_RE = /\.(json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav)$/i;
 const NODE_MODULES_RE = /[\\/]node_modules[\\/]/;
 const AKANJS_NODE_MODULE_RE = /[\\/]node_modules[\\/]akanjs[\\/]/;
@@ -17,7 +17,6 @@ interface CssDiscovery {
   sourcePaths: string[];
 }
 
-/** One `@import` target and the custom properties it declares, which is what proves it arrived downstream. */
 export interface ImportedStylesheet {
   cssPath: string;
   declaredNames: string[];
@@ -32,32 +31,18 @@ export class CssCompiler {
     this.#app = app;
   }
 
-  /**
-   * Beside the sources rather than in `dist`, because the cache is keyed on source mtimes: a build and
-   * the dev server describe the same files, so they should share it rather than each pay the first scan.
-   */
+  // Beside the sources, not in `dist`: the build and the dev server scan the same files, so they share one cache.
   get #candidateCachePath() {
     return path.join(this.#app.cwdPath, ".akan/cache/cssCandidates.json");
   }
 
   #cssText: string | null = null;
   #cssTextByBasePath: Record<string, string> | null = null;
-  /**
-   * Import resolution memoised for the life of one compiler, which is one rebuild.
-   *
-   * The discovery BFS resolves the same specifier from every directory that imports it, and each miss
-   * costs up to 13 sequential `exists()` calls — the bare path, six extensions, six `index.*`. Nothing
-   * here outlives the rebuild, so there is no invalidation to get wrong.
-   */
+  // Memoised for one compiler, i.e. one rebuild: nothing outlives it, so there is nothing to invalidate.
   #fileExistsCache = new Map<string, Promise<boolean>>();
   #resolvedFileCache = new Map<string, Promise<string | null>>();
   #resolvedSpecifierCache = new Map<string, Promise<string | null>>();
-  /** Every stylesheet this compile reached, entry points and `@import` targets alike. */
   #discoveredCssPaths = new Set<string>();
-  /**
-   * `@import` targets per base path, so whoever writes the asset can check the file it actually wrote — the
-   * compiled text and the written artifact are two different places a declaration can go missing.
-   */
   importedStylesheetsByBasePath: Record<string, ImportedStylesheet[]> = {};
 
   #fileExists(absPath: string): Promise<boolean> {
@@ -107,41 +92,31 @@ export class CssCompiler {
     const pageKeys = await this.#app.getPageKeys({ refresh });
     const basePaths = [...akanConfig.basePaths];
     const rootPageKeys = pageKeys.filter((pageKey) => getPageKeyBasePath(pageKey, basePaths) === null);
+    const compileBasePath = async (basePath: string, basePathPageKeys: string[], label = basePath) => {
+      if (basePathPageKeys.length === 0) return [basePath, ""] as const;
+      const started = Date.now();
+      const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh, pageKeys: basePathPageKeys });
+      const { css, imported } = await this.#compileWithImports(cssPaths, sourcePaths);
+      this.importedStylesheetsByBasePath[basePath] = imported;
+      this.#logger.verbose(
+        `css base=${label} paths=${cssPaths.length} sources=${sourcePaths.length} in ${Date.now() - started}ms`,
+      );
+      return [basePath, css] as const;
+    };
     const cssEntries = await Promise.all([
-      (async () => {
-        if (rootPageKeys.length === 0) return ["", ""] as const;
-        const started = Date.now();
-        const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh, pageKeys: rootPageKeys });
-        const { css, imported } = await this.#compileWithImports(cssPaths, sourcePaths);
-        this.importedStylesheetsByBasePath[""] = imported;
-        this.#logger.verbose(
-          `css base=root paths=${cssPaths.length} sources=${sourcePaths.length} in ${Date.now() - started}ms`,
-        );
-        return ["", css] as const;
-      })(),
-      ...basePaths.map(async (basePath) => {
-        const basePathPageKeys = pageKeys.filter((pageKey) => getPageKeyBasePath(pageKey, basePaths) === basePath);
-        if (basePathPageKeys.length === 0) return [basePath, ""] as const;
-        const started = Date.now();
-        const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh, pageKeys: basePathPageKeys });
-        const { css, imported } = await this.#compileWithImports(cssPaths, sourcePaths);
-        this.importedStylesheetsByBasePath[basePath] = imported;
-        this.#logger.verbose(
-          `css base=${basePath} paths=${cssPaths.length} sources=${sourcePaths.length} in ${Date.now() - started}ms`,
-        );
-        return [basePath, css] as const;
-      }),
+      compileBasePath("", rootPageKeys, "root"),
+      ...basePaths.map((basePath) =>
+        compileBasePath(
+          basePath,
+          pageKeys.filter((pageKey) => getPageKeyBasePath(pageKey, basePaths) === basePath),
+        ),
+      ),
     ]);
     this.#cssTextByBasePath = Object.fromEntries(cssEntries);
     await this.#warnUnreachableStylesheets();
     return this.#cssTextByBasePath;
   }
 
-  /**
-   * A stylesheet under `page/` reaches the build only by being imported from a route source. One that nothing
-   * imports compiles to nothing and reports success, which is indistinguishable from an empty theme — so say it
-   * out loud once per compile rather than leaving it to be noticed as unstyled elements in the browser.
-   */
   async #warnUnreachableStylesheets() {
     const pageDir = path.join(this.#app.cwdPath, "page");
     const glob = new Bun.Glob("**/*.css");
@@ -225,11 +200,7 @@ export class CssCompiler {
     return { cssPaths, sourcePaths: [...sourceFiles] };
   }
 
-  /**
-   * `libs/<lib>/ui/tokens.css` of every lib the page graph reached, so a lib can own the fixed colours its own
-   * components need instead of each consuming app re-declaring them. Ordered ahead of the app's stylesheets:
-   * the app is the last word on any variable both declare.
-   */
+  // Lib tokens go ahead of the app's stylesheets, so the app has the last word on a variable both declare.
   async #libTokenStylesheets(sourceFiles: Set<string>): Promise<string[]> {
     const libsRoot = path.join(this.#app.workspace.workspaceRoot, "libs");
     const libNames = new Set<string>();
@@ -252,10 +223,7 @@ export class CssCompiler {
     return css;
   }
 
-  /**
-   * The collector is per compile rather than per compiler instance: `getCssByBasePath` compiles every base path
-   * concurrently, so instance state would mix one base path's imports into another's check.
-   */
+  // A per-compile collector: getCssByBasePath compiles base paths concurrently, so instance state would mix them.
   async #compileWithImports(
     cssPaths: string[],
     sourcePaths: string[],
@@ -279,7 +247,6 @@ export class CssCompiler {
 
     const sourceDirs = new Set<string>();
     for (const entry of compilers) {
-      if (!entry) continue;
       for (const s of entry.compiler.sources as { base: string }[]) sourceDirs.add(s.base);
     }
     const scanStarted = Date.now();
@@ -290,7 +257,6 @@ export class CssCompiler {
     const parts: string[] = [];
     const imported: ImportedStylesheet[] = [];
     for (const entry of compilers) {
-      if (!entry) continue;
       const part = entry.compiler.build(candidates);
       parts.push(part);
       for (const [cssPath, content] of entry.imported) {
@@ -317,28 +283,19 @@ export class CssCompiler {
     return { path: p, base: path.dirname(p), content };
   }
 
-  /**
-   * Every specifier is verified here, path-shaped ones included. An `@import` the pipeline cannot resolve is
-   * a build error and never a no-op: the vocabulary closure means a component whose token declaration failed
-   * to load renders unstyled, which nothing downstream can distinguish from a design choice.
-   */
+  // An unresolvable @import throws: under vocabulary closure a missing token file just renders unstyled.
   async #resolveCssImport(id: string, fromBase: string): Promise<string> {
     if (id.startsWith(".") || id.startsWith("/")) {
       const filePath = path.resolve(fromBase, id);
       if (await this.#fileExists(filePath)) return filePath;
       throw new Error(`[css] failed to resolve stylesheet import "${id}" from ${fromBase} (no file at ${filePath})`);
     }
-    const resolver = await this.#getCssImportResolver();
-    const resolved = await resolver.resolve(id, fromBase);
+    this.#cssImportResolver ??= await CssImportResolver.create(this.#app);
+    const resolved = await this.#cssImportResolver.resolve(id, fromBase);
     if (resolved) return resolved;
     throw new Error(`[css] failed to resolve stylesheet import "${id}" from ${fromBase}`);
   }
 
-  async #getCssImportResolver() {
-    if (this.#cssImportResolver) return this.#cssImportResolver;
-    this.#cssImportResolver = await CssImportResolver.create(this.#app);
-    return this.#cssImportResolver;
-  }
   async #loadModule(id: string, fromBase: string) {
     const p = require.resolve(id, { paths: [fromBase] });
     const mod = await import(p);
@@ -349,10 +306,7 @@ export class CssCompiler {
     fromBase: string,
     resolvePackage: Awaited<ReturnType<typeof createTsconfigPackageResolver>>,
   ): Promise<string | null> {
-    // Keyed by importer directory even for bare specifiers: the tsconfig resolver is
-    // directory-independent, but the `Bun.resolveSync` / `require.resolve` fallbacks below are not.
-    // The expensive part — the `exists()` probes — is deduplicated by absolute path instead, which is
-    // shared across every importer.
+    // Keyed by importer directory even for bare specifiers: the Bun/require fallbacks are directory-dependent.
     const cacheKey = `${fromBase}\0${id}`;
     let cached = this.#resolvedSpecifierCache.get(cacheKey);
     if (cached) return cached;
@@ -423,17 +377,14 @@ function resolveSourceWithRequire(id: string, fromBase: string): string | null {
 }
 
 function isSourceFile(filePath: string) {
-  return SOURCE_EXTS.includes(path.extname(filePath) as (typeof SOURCE_EXTS)[number]);
+  return SOURCE_EXTS.has(path.extname(filePath));
 }
 
 export function isIgnoredNodeModuleSource(filePath: string): boolean {
   return NODE_MODULES_RE.test(filePath) && !AKANJS_NODE_MODULE_RE.test(filePath);
 }
 
-/**
- * `@theme` blocks are stripped first: those variables are emitted only when a utility uses one, so their
- * absence from a build says nothing about whether the stylesheet arrived.
- */
+/** Skips `@theme` blocks: Tailwind emits those variables only when a utility uses one. */
 export function declaredCustomProperties(css: string): string[] {
   const withoutThemeBlocks = css.replace(/@theme[^{]*\{[^}]*\}/g, "");
   return [...new Set([...withoutThemeBlocks.matchAll(/(?:^|[\s;{])(--[\w-]+)\s*:/g)].map(([, name]) => name))].filter(

package/frontendBuild/cssImportResolver.ts

@@ -25,8 +25,8 @@ export class CssImportResolver {
   async resolve(id: string, fromBase: string): Promise<string | null> {
     for (const resolve of [
       () => this.#resolveWithTsconfig(id),
-      () => this.#resolveWithBun(id, fromBase),
-      () => this.#resolveWithRequire(id, fromBase),
+      () => this.#resolveCssWith(fromBase, (base) => Bun.resolveSync(id, base)),
+      () => this.#resolveCssWith(fromBase, (base) => require.resolve(id, { paths: [base] })),
       () => this.#resolvePackageStyle(id, fromBase),
     ]) {
       const resolved = await resolve();
@@ -35,22 +35,10 @@ export class CssImportResolver {
     return null;
   }
 
-  #resolveWithBun(id: string, fromBase: string): string | null {
+  #resolveCssWith(fromBase: string, resolveFrom: (base: string) => string): string | null {
     for (const base of this.#resolutionBases(fromBase)) {
       try {
-        const resolved = Bun.resolveSync(id, base);
-        if (CssImportResolver.isCssFile(resolved)) return resolved;
-      } catch {
-        // Try the next known package resolution root.
-      }
-    }
-    return null;
-  }
-
-  #resolveWithRequire(id: string, fromBase: string): string | null {
-    for (const base of this.#resolutionBases(fromBase)) {
-      try {
-        const resolved = require.resolve(id, { paths: [base] });
+        const resolved = resolveFrom(base);
         if (CssImportResolver.isCssFile(resolved)) return resolved;
       } catch {
         // Try the next known package resolution root.
@@ -111,8 +99,7 @@ export class CssImportResolver {
           ? exportValue
           : exportValue?.style || exportValue?.import || exportValue?.default;
       if (exportedEntry) return await this.#firstExisting(path.resolve(pkgDir, exportedEntry));
-      //* A subpath names a file inside the package, so it resolves literally. Falling back to the package's own
-      //* style entry here would load a different stylesheet than the author asked for and report success.
+      //* A subpath resolves literally: the package's own style entry would silently load a different stylesheet.
       if (subpath !== ".") return await this.#firstExisting(path.resolve(pkgDir, subpath));
       return await this.#firstExisting(path.resolve(pkgDir, pkg.exports?.["."]?.style || pkg.style || "index.css"));
     } catch {
@@ -135,7 +122,7 @@ export class CssImportResolver {
 
   async #firstExisting(basePath: string): Promise<string | null> {
     for (const suffix of CSS_IMPORT_EXTS) {
-      const candidate = `${basePath}${suffix}`;
+      const candidate = path.normalize(`${basePath}${suffix}`);
       if (await Bun.file(candidate).exists()) return candidate;
     }
     return null;

package/frontendBuild/devChangePlanner.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
 import type { ChangeKind, DevChangeAction, DevChangePlan, DevChangeRole } from "akanjs/server";
+import { SOURCE_EXTS } from "../akanApp/devHostPolicy";
 
-const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 const CONFIG_BASENAMES = new Set(["akan.config.ts", "bunfig.toml", "tsconfig.json", "package.json"]);
 const BARREL_FACETS = new Set(["common", "srvkit", "ui", "webkit", "plugin"]);
 const CLIENT_SUFFIXES = [".Template.tsx", ".Unit.tsx", ".Util.tsx", ".View.tsx", ".Zone.tsx", ".store.ts"];
@@ -93,15 +93,15 @@ export class DevChangePlanner {
       roles.add("barrel");
       reasons.add(isGenerated ? "generated-index" : "barrel-facet-child");
     }
-    if (isSource && this.#isServerBiased(abs, parts)) {
+    if (isSource && this.#isServerBiased(base, parts)) {
       roles.add("server");
       reasons.add("server-path");
     }
-    if (isSource && this.#isClientBiased(abs, parts)) {
+    if (isSource && this.#isClientBiased(base, parts)) {
       roles.add("client");
       reasons.add("client-path");
     }
-    if (isSource && this.#isSharedBiased(abs, parts)) {
+    if (isSource && this.#isSharedBiased(base, parts)) {
       roles.add("shared");
       reasons.add("shared-path");
     }
@@ -123,8 +123,7 @@ export class DevChangePlanner {
     return roles;
   }
 
-  #isServerBiased(abs: string, parts: string[]): boolean {
-    const base = path.basename(abs);
+  #isServerBiased(base: string, parts: string[]): boolean {
     return (
       parts.includes("srvkit") ||
       SERVER_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
@@ -133,8 +132,7 @@ export class DevChangePlanner {
     );
   }
 
-  #isClientBiased(abs: string, parts: string[]): boolean {
-    const base = path.basename(abs);
+  #isClientBiased(base: string, parts: string[]): boolean {
     return (
       parts.includes("ui") ||
       parts.includes("webkit") ||
@@ -143,8 +141,7 @@ export class DevChangePlanner {
     );
   }
 
-  #isSharedBiased(abs: string, parts: string[]): boolean {
-    const base = path.basename(abs);
+  #isSharedBiased(base: string, parts: string[]): boolean {
     return (
       parts.includes("common") ||
       SHARED_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||

package/frontendBuild/devGeneratedIndexSync.test.ts

@@ -1,16 +1,10 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { tempDirs } from "../testHelpers";
 import { DevGeneratedIndexSync } from "./devGeneratedIndexSync";
 
-const tempRoots: string[] = [];
-
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-generated-index-"));
-  tempRoots.push(root);
-  return root;
-};
+const makeTempRoot = tempDirs("akan-generated-index-");
 
 const seedFacet = async (root: string, facet: string, { files, dirs }: { files: string[]; dirs: string[] }) => {
   const dir = path.join(root, "libs", "util", facet);
@@ -28,23 +22,19 @@ const barrelFor = async (root: string, facet: string, seed: { files: string[]; d
   return readFile(path.join(dir, "index.ts"), "utf8");
 };
 
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
 describe("DevGeneratedIndexSync facet barrels", () => {
   test("camelCase facets export only clean camelCase names", async () => {
     const content = await barrelFor(await makeTempRoot(), "srvkit", {
       files: [
         "aes.ts",
         "cloudflareApi.ts",
-        "cloudflareApi.helper.ts", // dotted → skipped
-        "pushNotificationServer.type.ts", // dotted → skipped
-        "PushNotificationServer.ts", // PascalCase in camel facet → skipped
-        "my_snake.ts", // snake_case → skipped
-        "kebab-case.ts", // kebab-case → skipped
+        "cloudflareApi.helper.ts",
+        "pushNotificationServer.type.ts",
+        "PushNotificationServer.ts",
+        "my_snake.ts",
+        "kebab-case.ts",
       ],
-      dirs: ["storageApi", "BadDir"], // PascalCase dir → skipped
+      dirs: ["storageApi", "BadDir"],
       trigger: "aes.ts",
     });
     expect(content).toBe(`export * from "./aes";\nexport * from "./cloudflareApi";\nexport * from "./storageApi";\n`);
@@ -52,13 +42,8 @@ describe("DevGeneratedIndexSync facet barrels", () => {
 
   test("ui facet exports only clean PascalCase names", async () => {
     const content = await barrelFor(await makeTempRoot(), "ui", {
-      files: [
-        "Globe.tsx",
-        "AkanLogo.tsx",
-        "Globe_Dynamic.tsx", // underscore → skipped
-        "lowerStart.tsx", // camelCase in ui facet → skipped
-      ],
-      dirs: ["Code", "badDir"], // camelCase dir → skipped
+      files: ["Globe.tsx", "AkanLogo.tsx", "Globe_Dynamic.tsx", "lowerStart.tsx"],
+      dirs: ["Code", "badDir"],
       trigger: "Globe.tsx",
     });
     expect(content).toBe(`export * from "./AkanLogo";\nexport * from "./Code";\nexport * from "./Globe";\n`);

package/frontendBuild/devGeneratedIndexSync.ts

@@ -1,12 +1,11 @@
 import { mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
 import path from "node:path";
+import { capitalize } from "akanjs/common";
 import { FileSys } from "../fileSys";
 
 const BARREL_FACETS = new Set(["common", "srvkit", "ui", "webkit", "plugin"]);
 const FACET_SOURCE_FILE_RE = /\.(ts|tsx)$/;
 const FACET_EXCLUDED_FILE_RE = /(^index\.tsx?$|\.d\.ts$|\.(test|spec)\.(ts|tsx)$|\.css$|\.scss$|\.sass$)/;
-// `ui` exports PascalCase names only; `common`/`srvkit`/`webkit` export camelCase names only. Names with
-// dots, underscores, or hyphens (e.g. `foo.helper`, `Globe_Dynamic`, `kebab-case`) match neither and are skipped.
 const FACET_PASCAL_CASE_RE = /^[A-Z][A-Za-z0-9]*$/;
 const FACET_CAMEL_CASE_RE = /^[a-z][A-Za-z0-9]*$/;
 const MODULE_UI_TYPES = ["Template", "Unit", "Util", "View", "Zone"] as const;
@@ -159,6 +158,4 @@ const exists = async (file: string) =>
     .then(() => true)
     .catch(() => false);
 
-const capitalize = (value: string) => `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
-
 const formatError = (err: unknown) => (err instanceof Error ? err.message : String(err));

package/frontendBuild/fontOptimizer.test.ts

@@ -1,17 +1,16 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, stat, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { mkdir, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
+import { tempDirs } from "../testHelpers";
 import { FontOptimizer } from "./fontOptimizer";
 
 const SOURCE_FONT = path.resolve(import.meta.dir, "../../../../libs/shared/public/fonts/Assistant-Regular.woff2");
 
-const tempRoots: string[] = [];
+const tempRoot = tempDirs("akan-devkit-font-");
 
 const makeApp = async (layoutSource: string) => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-font-"));
-  tempRoots.push(root);
+  const root = await tempRoot();
   const cwdPath = path.join(root, "apps/demo");
   await mkdir(path.join(cwdPath, "page"), { recursive: true });
   await mkdir(path.join(cwdPath, "public/fonts"), { recursive: true });
@@ -59,10 +58,6 @@ const chainFontList = (extra = "") => `[\n    ${chainFontEntry(extra)},\n  ]`;
 
 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());
@@ -76,7 +71,6 @@ describe("FontOptimizer cache", () => {
     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);
   });
 
@@ -160,8 +154,6 @@ describe("FontOptimizer discovery", () => {
     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"));
 
@@ -170,7 +162,7 @@ describe("FontOptimizer discovery", () => {
     expect(result.fonts).toEqual([]);
     expect(result.files).toEqual([]);
     expect(warnings).toHaveLength(1);
-    expect(warnings[0]).toContain("page/_layout.tsx");
+    expect(warnings[0]).toContain(path.join("page", "_layout.tsx"));
   });
 
   test("warns about an entry it cannot read and keeps the ones it can", async () => {