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

package/frontendBuild/cssCompiler.ts

@@ -17,6 +17,12 @@ 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[];
+}
+
 export class CssCompiler {
   #logger = new Logger("CssCompiler");
   #transpiler = new Bun.Transpiler({ loader: "tsx" });
@@ -48,6 +54,11 @@ export class CssCompiler {
   #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> {
     let cached = this.#fileExistsCache.get(absPath);
@@ -79,8 +90,11 @@ export class CssCompiler {
   async getCss({ refresh }: { refresh?: boolean } = {}) {
     if (this.#cssText !== null && !refresh) return this.#cssText;
     this.#discoveredCssPaths.clear();
+    this.importedStylesheetsByBasePath = {};
     const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh });
-    this.#cssText = await this.compileCss(cssPaths, sourcePaths);
+    const { css, imported } = await this.#compileWithImports(cssPaths, sourcePaths);
+    this.#cssText = css;
+    this.importedStylesheetsByBasePath = { "": imported };
     await this.#warnUnreachableStylesheets();
     return this.#cssText;
   }
@@ -88,6 +102,7 @@ export class CssCompiler {
   async getCssByBasePath({ refresh }: { refresh?: boolean } = {}): Promise<Record<string, string>> {
     if (this.#cssTextByBasePath !== null && !refresh) return this.#cssTextByBasePath;
     this.#discoveredCssPaths.clear();
+    this.importedStylesheetsByBasePath = {};
     const akanConfig = await this.#app.getConfig({ refresh });
     const pageKeys = await this.#app.getPageKeys({ refresh });
     const basePaths = [...akanConfig.basePaths];
@@ -97,7 +112,8 @@ export class CssCompiler {
         if (rootPageKeys.length === 0) return ["", ""] as const;
         const started = Date.now();
         const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh, pageKeys: rootPageKeys });
-        const css = await this.compileCss(cssPaths, sourcePaths);
+        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`,
         );
@@ -108,7 +124,8 @@ export class CssCompiler {
         if (basePathPageKeys.length === 0) return [basePath, ""] as const;
         const started = Date.now();
         const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh, pageKeys: basePathPageKeys });
-        const css = await this.compileCss(cssPaths, sourcePaths);
+        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`,
         );
@@ -231,19 +248,32 @@ export class CssCompiler {
     return tokenPaths.filter((tokensPath): tokensPath is string => !!tokensPath);
   }
   async compileCss(cssPaths: string[], sourcePaths: string[]): Promise<string> {
-    if (cssPaths.length === 0) return "";
+    const { css } = await this.#compileWithImports(cssPaths, sourcePaths);
+    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.
+   */
+  async #compileWithImports(
+    cssPaths: string[],
+    sourcePaths: string[],
+  ): Promise<{ css: string; imported: ImportedStylesheet[] }> {
+    if (cssPaths.length === 0) return { css: "", imported: [] };
 
     const compileStarted = Date.now();
     const compilers = await Promise.all(
       cssPaths.map(async (cssPath) => {
         const css = await Bun.file(cssPath).text();
         const base = path.dirname(cssPath);
+        const imported = new Map<string, string>();
         const compiler = await compile(css, {
           base,
-          loadStylesheet: (id, fromBase) => this.#loadStylesheet(id, fromBase),
+          loadStylesheet: (id, fromBase) => this.#loadStylesheet(id, fromBase, imported),
           loadModule: (id, fromBase) => this.#loadModule(id, fromBase),
         });
-        return { cssPath, compiler };
+        return { cssPath, compiler, imported };
       }),
     );
 
@@ -258,20 +288,32 @@ export class CssCompiler {
       `css candidates scanned count=${candidates.length} sources=${sourcePaths.length} dirs=${sourceDirs.size} in ${Date.now() - scanStarted}ms`,
     );
     const parts: string[] = [];
+    const imported: ImportedStylesheet[] = [];
     for (const entry of compilers) {
       if (!entry) continue;
-      parts.push(entry.compiler.build(candidates));
+      const part = entry.compiler.build(candidates);
+      parts.push(part);
+      for (const [cssPath, content] of entry.imported) {
+        const declaredNames = declaredCustomProperties(content);
+        imported.push({ cssPath, declaredNames });
+        if (declaredNames.length === 0 || declaredNames.some((name) => part.includes(`${name}:`))) continue;
+        this.#logger.warn(
+          `css @import ${cssPath} was loaded by ${entry.cssPath} but none of its ${declaredNames.length} declaration(s) reached the compiled CSS`,
+        );
+      }
     }
     this.#logger.verbose(
       `css compiled paths=${cssPaths.length} candidates=${candidates.length} in ${Date.now() - compileStarted}ms`,
     );
-    return parts.join("\n");
+    return { css: parts.join("\n"), imported };
   }
 
-  async #loadStylesheet(id: string, fromBase: string) {
+  async #loadStylesheet(id: string, fromBase: string, imported?: Map<string, string>) {
     const p = await this.#resolveCssImport(id, fromBase);
     this.#discoveredCssPaths.add(p);
     const content = await Bun.file(p).text();
+    imported?.set(p, content);
+    this.#logger.verbose(`css import "${id}" from ${fromBase} -> ${p} (${content.length} bytes)`);
     return { path: p, base: path.dirname(p), content };
   }
 
@@ -388,6 +430,17 @@ 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.
+ */
+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(
+    (name): name is string => !!name,
+  );
+}
+
 function getPageKeyBasePath(pageKey: string, basePaths: string[]): string | null {
   const normalized = pageKey.split(path.sep).join("/").replace(/^\.\//, "");
   const segments = normalized.split("/");

package/frontendBuild/frontendBuild.test.ts

@@ -5,7 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { RoutesManifest } from "akanjs/server";
 import { CsrArtifactBuilder } from "./csrArtifactBuilder";
-import { CssCompiler, isIgnoredNodeModuleSource } from "./cssCompiler";
+import { CssCompiler, declaredCustomProperties, isIgnoredNodeModuleSource } from "./cssCompiler";
 import { CssImportResolver } from "./cssImportResolver";
 import { DevChangePlanner } from "./devChangePlanner";
 import { DevGeneratedIndexSync } from "./devGeneratedIndexSync";
@@ -443,6 +443,17 @@ describe("CssCompiler", () => {
     expect(css).toContain(".text-fuchsia-500");
   });
 
+  test("reads declarations that prove a stylesheet arrived, ignoring theme variables that may not", () => {
+    expect(declaredCustomProperties(":root { --kakao: #fee500; --naver: #1ec800; }")).toEqual(["--kakao", "--naver"]);
+    expect(declaredCustomProperties("@theme inline {\n  --color-brand: var(--brand);\n}\n")).toEqual([]);
+    expect(declaredCustomProperties("@theme { --color-x: initial; }\n:root { --brand: #111; }")).toEqual(["--brand"]);
+    expect(declaredCustomProperties(".a { color: var(--kakao); }")).toEqual([]);
+    expect(declaredCustomProperties(":root{--a:#111}\n@media (min-width:1px){:root{--a:#222;--b:#333}}")).toEqual([
+      "--a",
+      "--b",
+    ]);
+  });
+
   test("fails loudly on a stylesheet import that resolves to nothing", async () => {
     const root = await makeTempRoot();
     const cssPath = path.join(root, "apps/demo/page/styles.css");
@@ -459,6 +470,28 @@ describe("CssCompiler", () => {
     );
   });
 
+  test("reports every @import per base path so the written asset can be checked against it", async () => {
+    const root = await makeTempRoot();
+    const appDir = path.join(root, "apps/demo");
+    await write(path.join(appDir, "page/_index.tsx"), 'import "./styles.css";\nexport default () => null;\n');
+    await write(path.join(appDir, "page/styles.css"), '@import "../../../libs/shared/ui/brand.css";\n');
+    await write(path.join(root, "libs/shared/ui/brand.css"), ":root { --kakao: #fee500; --naver: #1ec800; }\n");
+
+    const compiler = new CssCompiler({
+      workspace: { workspaceRoot: root },
+      cwdPath: appDir,
+      getPageKeys: async () => ["./_index.tsx"],
+      getConfig: async () => ({ barrelImports: [], basePaths: [] }),
+      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
+    } as never);
+    const cssByBasePath = await compiler.getCssByBasePath();
+
+    expect(cssByBasePath[""]).toContain("--kakao");
+    expect(compiler.importedStylesheetsByBasePath[""]).toEqual([
+      { cssPath: path.join(root, "libs/shared/ui/brand.css"), declaredNames: ["--kakao", "--naver"] },
+    ]);
+  });
+
   test("compiles lib-owned tokens ahead of the app stylesheets that may override them", async () => {
     const root = await makeTempRoot();
     const appDir = path.join(root, "apps/demo");

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -5,7 +5,7 @@ import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex, type RouteSeedIndex, saveRouteSeedIndex } from "../artifact/routeSeedIndex";
 import type { App } from "../commandDecorators";
 import { ClientEntriesBundler } from "./clientEntriesBundler";
-import { CssCompiler } from "./cssCompiler";
+import { CssCompiler, type ImportedStylesheet } from "./cssCompiler";
 import { FontOptimizer } from "./fontOptimizer";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { RouteClientBuilder } from "./routeClientBuilder";
@@ -192,7 +192,7 @@ export class SsrBaseArtifactBuilder {
         Object.entries(cssByBasePath).flatMap(([basePath, baseCssText]) => {
           const cssText = [baseCssText, optimizedFonts.css].filter(Boolean).join("\n");
           if (!cssText) return [];
-          return [this.#writeCssAsset(basePath, cssText)];
+          return [this.#writeCssAsset(basePath, cssText, cssCompiler.importedStylesheetsByBasePath[basePath] ?? [])];
         }),
       ),
     );
@@ -201,7 +201,7 @@ export class SsrBaseArtifactBuilder {
     return { cssCompiler, optimizedFonts, cssAssets };
   }
 
-  async #writeCssAsset(basePath: string, cssText: string) {
+  async #writeCssAsset(basePath: string, cssText: string, imported: ImportedStylesheet[]) {
     const cssAssetName = basePath || "root";
     const preparedCssText = await prepareCssAsset(this.#command, basePath, cssText);
     const cssHash = Bun.hash(`${basePath}\n${preparedCssText}`).toString(36);
@@ -210,7 +210,23 @@ export class SsrBaseArtifactBuilder {
       `/_akan/styles/${cssAssetName}-${cssHash}.css`,
     ];
     await Bun.write(path.join(this.#absArtifactDir, cssRelPath), preparedCssText);
+    SsrBaseArtifactBuilder.#warnDroppedImports(this.#app, cssRelPath, preparedCssText, imported);
     this.#app.verbose(`[base-artifact] wrote ${preparedCssText.length} bytes of CSS for ${basePath} -> ${cssRelPath}`);
     return [basePath, { cssUrl, cssRelPath }] as const;
   }
+
+  /**
+   * Checked against the file written here rather than against the compiled text, because this is the stylesheet
+   * `base-artifact.json` points at and therefore the only one an SSR render serves. A declaration can survive
+   * the compile and still be missing from the asset — a build that ships CSS to the CSR bundle and not to the
+   * server is indistinguishable, in the browser, from a theme that was never written.
+   */
+  static #warnDroppedImports(app: App, cssRelPath: string, css: string, imported: ImportedStylesheet[]) {
+    for (const { cssPath, declaredNames } of imported) {
+      if (declaredNames.length === 0 || declaredNames.some((name) => css.includes(`${name}:`))) continue;
+      app.logger.warn(
+        `[base-artifact] @import ${cssPath} declares ${declaredNames.length} custom propert${declaredNames.length === 1 ? "y" : "ies"} and none of them are in ${cssRelPath}`,
+      );
+    }
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.11",
+  "version": "3.0.0-alpha.13",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -45,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.11",
+    "akanjs": "3.0.0-alpha.13",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",