@akanjs/devkit 3.0.0-alpha.71 → 3.0.0-alpha.72

package/fileEditor.ts

@@ -1,23 +1,23 @@
 export class FileEditor {
-  private filePath: string;
-  private content: string;
+  #filePath: string;
+  #content: string;
 
   private constructor(filePath: string, content: string) {
-    this.filePath = filePath;
-    this.content = content;
+    this.#filePath = filePath;
+    this.#content = content;
   }
 
   static async create(filePath: string): Promise<FileEditor> {
     try {
       const content = await Bun.file(filePath).text();
       return new FileEditor(filePath, content);
-    } catch (error) {
+    } catch (_error) {
       throw new Error(`Failed to read file: ${filePath}`);
     }
   }
 
   find(pattern: string | RegExp): number {
-    const lines = this.content.split("\n");
+    const lines = this.#content.split("\n");
     const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
 
     for (let i = 0; i < lines.length; i++) {
@@ -30,7 +30,7 @@ export class FileEditor {
   }
 
   findAll(pattern: string | RegExp): number[] {
-    const lines = this.content.split("\n");
+    const lines = this.#content.split("\n");
     const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
     const matches: number[] = [];
 
@@ -50,9 +50,9 @@ export class FileEditor {
       throw new Error(`Pattern not found: ${pattern}`);
     }
 
-    const lines = this.content.split("\n");
+    const lines = this.#content.split("\n");
     lines.splice(lineIndex + 1, 0, data);
-    this.content = lines.join("\n");
+    this.#content = lines.join("\n");
 
     return this;
   }
@@ -64,43 +64,43 @@ export class FileEditor {
       throw new Error(`Pattern not found: ${pattern}`);
     }
 
-    const lines = this.content.split("\n");
+    const lines = this.#content.split("\n");
     lines.splice(lineIndex, 0, data);
-    this.content = lines.join("\n");
+    this.#content = lines.join("\n");
 
     return this;
   }
 
   replace(pattern: string | RegExp, replacement: string): this {
     const regex = typeof pattern === "string" ? new RegExp(pattern, "g") : pattern;
-    this.content = this.content.replace(regex, replacement);
+    this.#content = this.#content.replace(regex, replacement);
     return this;
   }
 
   append(data: string): this {
-    this.content += `\n${data}`;
+    this.#content += `\n${data}`;
     return this;
   }
 
   prepend(data: string): this {
-    this.content = `${data}\n${this.content}`;
+    this.#content = `${data}\n${this.#content}`;
     return this;
   }
 
   async save(): Promise<void> {
     try {
-      await Bun.write(this.filePath, this.content);
-    } catch (error) {
-      throw new Error(`Failed to save file: ${this.filePath}`);
+      await Bun.write(this.#filePath, this.#content);
+    } catch (_error) {
+      throw new Error(`Failed to save file: ${this.#filePath}`);
     }
   }
 
   getContent(): string {
-    return this.content;
+    return this.#content;
   }
 
   setContent(content: string): this {
-    this.content = content;
+    this.#content = content;
     return this;
   }
 }

package/frontendBuild/autoImportSync.test.ts

@@ -355,3 +355,61 @@ describe("AutoImportSync.syncForBatch", () => {
     expect(await readFile(indexFile, "utf8")).not.toContain("@libs/shared/client");
   });
 });
+
+describe("AutoImportSync — scope", () => {
+  const writeAt = async (root: string, rel: string, source: string) => {
+    const abs = path.join(root, rel);
+    await mkdir(path.dirname(abs), { recursive: true });
+    await writeFile(abs, source);
+    return abs;
+  };
+
+  // `lib/__lib/` is generated and gitignored: `akan sync` rewrites it, which is also what makes the
+  // watcher hand it to the syncer, so an edit there is churn that the next sync discards.
+  test("leaves the generated lib/__lib stubs alone and still syncs lib/__scalar", async () => {
+    const root = await makeTempRoot();
+    const needsImport = "export class A {\n  count = field(Int);\n}\n";
+    const generated = await writeAt(root, "libs/shared/lib/__lib/lib.constant.ts", needsImport);
+    const scalar = await writeAt(root, "libs/shared/lib/__scalar/money/money.constant.ts", needsImport);
+
+    const result = await new AutoImportSync({ workspaceRoot: root }).syncForBatch([generated, scalar]);
+
+    expect(result.errors).toEqual([]);
+    expect(result.changedFiles).toEqual([scalar]);
+    expect(await readFile(generated, "utf8")).toBe(needsImport);
+    expect(await readFile(scalar, "utf8")).toContain('import { Int } from "akanjs/base";');
+  });
+
+  // The transform is pure and the write is conditional on a difference, so a second pass over its own
+  // output writes nothing — without that the watcher would re-fire on the syncer's own edit.
+  test("a second pass over its own output changes nothing", async () => {
+    const root = await makeTempRoot();
+    const file = await writeAt(
+      root,
+      "libs/shared/lib/task/task.constant.ts",
+      "export class A {\n  count = field(Int);\n}\n",
+    );
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    expect((await sync.syncForBatch([file])).changedFiles).toEqual([file]);
+    const afterFirst = await readFile(file, "utf8");
+    expect((await sync.syncForBatch([file])).changedFiles).toEqual([]);
+    expect(await readFile(file, "utf8")).toBe(afterFirst);
+  });
+
+  // One try/catch per file: a file that cannot be read is reported and the rest of the batch still runs.
+  test("a failing file is reported without abandoning the batch", async () => {
+    const root = await makeTempRoot();
+    const missing = path.join(root, "libs/shared/lib/task/gone.constant.ts");
+    const good = await writeAt(
+      root,
+      "libs/shared/lib/task/task.constant.ts",
+      "export class A {\n  count = field(Int);\n}\n",
+    );
+
+    const result = await new AutoImportSync({ workspaceRoot: root }).syncForBatch([missing, good]);
+
+    expect(result.changedFiles).toEqual([good]);
+    expect(result.errors).toEqual([]);
+  });
+});

package/frontendBuild/autoImportSync.ts

@@ -250,6 +250,10 @@ export class AutoImportSync {
     const parts = rel.split(path.sep).filter(Boolean);
     const [scope, project, facet] = parts;
     if ((scope !== "apps" && scope !== "libs") || !project || !facet) return null;
+    //* `lib/__lib/` holds the generated per-lib re-export stubs — gitignored, and rewritten by every
+    //* `akan sync`, which is also what makes the watcher report them. An edit there is churn at best and
+    //* silently discarded at worst. `lib/__scalar/` is real source and stays in scope.
+    if (facet === "lib" && parts[3] === "__lib") return null;
     const role = roleFor(facet, base);
     if (!role) return null;
 

package/frontendBuild/buildRouteClient.test.ts

@@ -159,28 +159,25 @@ describe("route client store bootstrap", () => {
     await write(uiEntry, 'export { ClientPathWrapper } from "./System/Client";\n');
     await write(clientEntry, '"use client";\nexport const ClientPathWrapper = () => null;\n');
 
-    const discovery = new GraphClientEntryDiscovery(
-      { barrelImports: ["akanjs/ui"], externalLibs: [], optimizeImports: true },
-      async (specifier) => {
-        if (specifier === "akanjs/ui") {
-          return {
-            pkgName: "akanjs/ui",
-            entryFile: uiEntry,
-            pkgDir: path.dirname(uiEntry),
-            preserveFilePath: true,
-          };
-        }
-        if (specifier === "akanjs/ui/System/Client.tsx") {
-          return {
-            pkgName: "akanjs/ui/System/Client.tsx",
-            entryFile: clientEntry,
-            pkgDir: path.dirname(clientEntry),
-            preserveFilePath: true,
-          };
-        }
-        return null;
-      },
-    );
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: ["akanjs/ui"] }, async (specifier) => {
+      if (specifier === "akanjs/ui") {
+        return {
+          pkgName: "akanjs/ui",
+          entryFile: uiEntry,
+          pkgDir: path.dirname(uiEntry),
+          preserveFilePath: true,
+        };
+      }
+      if (specifier === "akanjs/ui/System/Client.tsx") {
+        return {
+          pkgName: "akanjs/ui/System/Client.tsx",
+          entryFile: clientEntry,
+          pkgDir: path.dirname(clientEntry),
+          preserveFilePath: true,
+        };
+      }
+      return null;
+    });
 
     expect(await discovery.discover([seed])).toEqual([clientEntry]);
   });

package/frontendBuild/clientEntryDiscovery.ts

@@ -34,7 +34,7 @@ const shouldSkipNodeModule = (absPath: string) => NODE_MODULES_RE.test(absPath)
  * the traversal matches the module graph the bundler will actually see.
  */
 export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
-  #akanConfig: AkanConfig;
+  #akanConfig: Pick<AkanConfig, "barrelImports">;
   #resolvePackage: PackageResolver;
   #analyzer: BarrelAnalyzer;
   #tsTranspiler = new Bun.Transpiler({ loader: "tsx" });
@@ -57,7 +57,7 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   #unresolvedPaths = new Set<string>();
   #unresolvedSpecifiers = new Set<string>();
 
-  constructor(akanConfig: AkanConfig, resolvePackage: PackageResolver) {
+  constructor(akanConfig: Pick<AkanConfig, "barrelImports">, resolvePackage: PackageResolver) {
     this.#akanConfig = akanConfig;
     this.#resolvePackage = resolvePackage;
     this.#analyzer = new BarrelAnalyzer({ resolvePackage });

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> {
@@ -387,26 +398,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/index.ts

@@ -20,7 +20,6 @@ export * from "./routesManifestArtifactSerializer";
 export * from "./sourceMtimeIndex";
 export * from "./ssrBaseArtifactBuilder";
 export * from "./styleContract";
-export * from "./styleGuard";
 export * from "./themeValidator";
 export * from "./vendorSpecifiers";
 export * from "./watchRootResolver";

package/frontendBuild/styleContract.ts

@@ -1,29 +1,23 @@
 /**
- * styleGuard + themeValidator 결과를 배선(build/dev/lint)이 공유하는 포맷으로 정리한다.
- * severity 사다리: style 위반은 severity==="error" 인 것만, theme 위반은 전부 차단(build/CI) 대상.
- * dev 는 이 결과를 경고로만 출력한다.
+ * Reports the style contract that `akan lint` enforces, in the shape build/dev/lint share.
+ *
+ * Only contrast lives here. The vocabulary closure — raw palette classes, arbitrary colors, dropped
+ * daisyUI slots, inline color literals, interpolated arbitrary values — is enforced by the grit plugins
+ * in `lint/*.grit` during the biome run, so it is not re-scanned. Contrast cannot be a lint rule at all:
+ * it is arithmetic over resolved token *values*, which no syntactic pattern can reach.
  */
-import type { StyleGuardViolation } from "./styleGuard";
 import type { ThemeContrastViolation } from "./themeValidator";
 
 export interface StyleContractViolations {
-  style: StyleGuardViolation[];
   theme: ThemeContrastViolation[];
 }
 
-export const countBlocking = (v: StyleContractViolations): number =>
-  v.style.filter((s) => s.severity === "error").length + v.theme.length;
+export const countBlocking = (violations: StyleContractViolations): number => violations.theme.length;
 
-export const formatStyleContract = (v: StyleContractViolations): string => {
-  const lines: string[] = [];
-  for (const s of v.style) {
-    lines.push(`  [${s.severity}] ${s.rule}  ${s.path}:${s.line}`);
-    lines.push(`      ${s.snippet}`);
-    lines.push(`      → ${s.suggestion}`);
-  }
-  for (const t of v.theme) {
-    lines.push(`  [error] contrast  ${t.scope}  ${t.pair} = ${t.ratio}:1 (min ${t.threshold}:1)`);
-    lines.push(`      → ${t.suggestion}`);
-  }
-  return lines.join("\n");
-};
+export const formatStyleContract = (violations: StyleContractViolations): string =>
+  violations.theme
+    .flatMap((theme) => [
+      `  [error] contrast  ${theme.scope}  ${theme.pair} = ${theme.ratio}:1 (min ${theme.threshold}:1)`,
+      `      → ${theme.suggestion}`,
+    ])
+    .join("\n");

package/frontendBuild/themeValidator.ts

@@ -1,13 +1,17 @@
 /**
- * themeValidator — 시맨틱 토큰 페어의 WCAG 콘트라스트 자동 검사 (의존성 0).
+ * 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.
  *
- * 토큰 구조(`--x` ↔ `--x-foreground`)라서 가능해진 검사. AI 가 생성한 팔레트가 "안 읽히는 사이트"가
- * 되는 것을 원천 차단한다. akanjs 런타임을 import 하지 않는다 — 순수 함수만.
+ * 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.
  *
- * 임계값(WCAG 2.1):
- *   - 본문/주요 표면 페어(background·primary·secondary·accent·neutral·card·popover): 4.5:1 (AA normal text)
- *   - 상태/보조 페어(info·success·warning·destructive·open·muted): 3:1 (UI 컴포넌트 / 큰 텍스트 / 보조 표면)
- * 현행 styles.css 기본 팔레트(light/dark)는 이 임계값을 모두 통과한다.
+ * 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.
  */
 
 export interface ThemeContrastViolation {
@@ -42,13 +46,13 @@ const PAIRS: PairDef[] = [
   { base: "open", fg: "open-foreground", threshold: 3 },
 ];
 
-// 검사 대상 스코프. 그 외 셀렉터(.campaign-x 스코프 토큰 등)는 페어 검사에서 제외.
+// 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 {
-  /** CSS 문자열에서 토큰을 추출해 알려진 테마 스코프 전체를 검사한다. */
+  /** Extracts tokens from the css text and checks every scope it recognizes. */
   validate(css: string): ThemeContrastViolation[] {
     const tokensByScope = ThemeValidator.parseThemeTokens(css);
     const violations: ThemeContrastViolation[] = [];
@@ -67,7 +71,7 @@ export class ThemeValidator {
       if (!bg || !front) continue;
       const bgRgb = ThemeValidator.parseHex(bg);
       const fgRgb = ThemeValidator.parseHex(front);
-      if (!bgRgb || !fgRgb) continue; // var()/비-hex 값은 검사 불가 → 건너뜀
+      if (!bgRgb || !fgRgb) continue; // a var() or non-hex value has no ratio to compute
       const ratio = ThemeValidator.contrastRatio(bgRgb, fgRgb);
       if (ratio >= threshold) continue;
       violations.push({
@@ -77,20 +81,21 @@ export class ThemeValidator {
         foreground: front,
         ratio: Math.round(ratio * 100) / 100,
         threshold,
-        suggestion: `${scope}의 --${base}(${bg})와 --${fg}(${front}) 대비가 ${ratio.toFixed(2)}:1 로 최소 ${threshold}:1 미만입니다. 한쪽을 더 밝게/어둡게 조정해 대비를 확보하세요.`,
+        suggestion: `In ${scope}, --${base} (${bg}) against --${fg} (${front}) is ${ratio.toFixed(2)}:1, under the ${threshold}:1 minimum. Lighten or darken one of them until it clears.`,
       });
     }
     return violations;
   }
 
   /**
-   * `:root` / `[data-theme="…"]` 블록에서 `--token: value` 를 파싱한다. 그룹 셀렉터
-   * (`:root, [data-theme="dark"] { … }`)는 각 셀렉터에 동일 토큰을 분배. 동일 스코프 재등장 시 나중 값이 이긴다
-   * (프레임워크-먼저 / 앱-나중 순서로 넘기면 앱 override 가 반영됨).
+   * 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.
    */
   static parseThemeTokens(css: string): ThemeTokensByScope {
     const result: ThemeTokensByScope = {};
-    // 중첩 없는 단순 규칙 블록만 매칭(@theme/@keyframes 등 at-rule 은 셀렉터에 @ 포함이라 제외).
+    // 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());
@@ -109,11 +114,11 @@ export class ThemeValidator {
   }
 
   static #normalizeScope(selector: string): string {
-    // 따옴표 정규화: [data-theme=dark] / [data-theme='dark'] → [data-theme="dark"]
+    // Quote normalization: [data-theme=dark] / [data-theme='dark'] -> [data-theme="dark"]
     return selector.replace(/\[data-theme=['"]?([\w-]+)['"]?\]/g, '[data-theme="$1"]').trim();
   }
 
-  /** #rgb / #rgba / #rrggbb / #rrggbbaa → [r,g,b] (alpha 무시). 비-hex 는 null. */
+  /** #rgb / #rgba / #rrggbb / #rrggbbaa -> [r,g,b], alpha ignored. Null for anything not hex. */
   static parseHex(value: string): [number, number, number] | null {
     const v = value.trim();
     if (!v.startsWith("#")) return null;

package/incrementalBuilder/devWatchBatch.ts

@@ -1,4 +1,4 @@
-import type { BuilderEvent, ChangeBatch } from "akanjs/server";
+import type { BuilderEvent, ChangeBatch, DevChangePlan } from "akanjs/server";
 import type { DevChangePlanner, GeneratedIndexSyncResult } from "../frontendBuild";
 
 export interface PrepareDevWatchBatchOptions {
@@ -12,6 +12,8 @@ export interface PreparedDevWatchBatch {
   files: string[];
   kinds: ("code" | "css" | "config")[];
   expandedBatch: ChangeBatch;
+  /** The same plan the event carries, where `devPlan` is optional — read it here, not off the event. */
+  devPlan: DevChangePlan;
   event: Extract<BuilderEvent, { type: "invalidate" }>;
   hasSyncErrors: boolean;
 }
@@ -35,13 +37,15 @@ export const prepareDevWatchBatch = ({
   });
 
   if (indexSync.errors.length > 0 && !devPlan.actions.includes("report-error")) {
-    devPlan.actions = [...devPlan.actions, "report-error"].sort();
+    const withReport: DevChangePlan["actions"] = [...devPlan.actions, "report-error"];
+    devPlan.actions = withReport.sort();
   }
 
   return {
     files,
     kinds,
     expandedBatch,
+    devPlan,
     event: { type: "invalidate", kinds, files, generation, devPlan },
     hasSyncErrors: indexSync.errors.length > 0,
   };

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -186,6 +186,11 @@ class IncrementalBuilder {
     this.#shuttingDown = true;
     const started = Date.now();
     this.#logger.debug(`shutdown requested (${reason}); draining ${this.#inFlight} work item(s)`);
+    // Stopped before the drain, or a save landing mid-drain would enqueue a batch behind the queue tail
+    // this method already awaited — and `process.exit(0)` would cut that batch off partway through
+    // writing its artifacts. The replacement rebuilds every artifact from its boot build anyway, so the
+    // batch is not lost; a half-written one would be.
+    this.#watcher?.stop();
     if (this.#cssRebuildTimer) {
       // Only reachable if a css batch landed between the idle report and this request: the fresh
       // boot build recompiles css from scratch anyway, so dropping the debounce loses nothing.
@@ -303,13 +308,12 @@ class IncrementalBuilder {
     //* them to the watcher so its verification scan does not read them back as a user edit and spend a
     //* second generation rebuilding identical content.
     await this.#watcher?.absorb([...autoImport.changedFiles, ...indexSync.changedFiles]);
-    const { files, kinds, expandedBatch, event, hasSyncErrors } = prepareDevWatchBatch({
+    const { files, kinds, expandedBatch, devPlan, event, hasSyncErrors } = prepareDevWatchBatch({
       generation,
       batch,
       indexSync,
       changePlanner: this.#changePlanner,
     });
-    const devPlan = event.devPlan;
     this.#logger.verbose(
       `[hmr] batch generation=${generation} kinds=${kinds.join(",")} files=${files.length} generated=${indexSync.changedFiles.length} roles=${devPlan.roles.join(",") || "(none)"} actions=${devPlan.actions.join(",") || "(none)"}`,
     );

package/index.ts

@@ -22,19 +22,15 @@ export type * from "./applicationBuildRunner";
 export type * from "./applicationReleasePackager";
 export type * from "./applicationTestPreload";
 export type * from "./artifact";
-export type * from "./builder";
 export type * from "./capacitorApp";
 export type * from "./cloud";
 export type * from "./commandDecorators";
 export type * from "./createTunnel";
 export type * from "./dependencyScanner";
 export type * from "./executors";
-export type * from "./extractDeps";
 export type * from "./fileSys";
 export type * from "./frontendBuild";
-export type * from "./getCredentials";
 export type * from "./getDirname";
-export type * from "./getModelFileData";
 export type * from "./getRelatedCnsts";
 export type * from "./guideline";
 export type * from "./incrementalBuilder";
@@ -46,7 +42,6 @@ export type * from "./recipeScanner";
 export type * from "./scanInfo";
 export type * from "./selectModel";
 export type * from "./spinner";
-export type * from "./streamAi";
 export type * from "./transforms";
 export type * from "./typeChecker";
 export type * from "./types";

package/lint/__fixtures__/README.md

@@ -0,0 +1,40 @@
+# grit rule fixtures
+
+One folder per `lint/*.grit` rule. `gritRules.test.ts` runs biome with that one plugin enabled and asserts
+`bad` reports **exactly** the marked lines and `good` reports nothing — so a rule that silently stops
+matching after a biome upgrade fails the suite instead of going quiet, and `every rule in this folder has a
+fixture` fails when a rule is added without one.
+
+## Contract
+
+- One case per line. `// @flag` marks a line the rule must report in `bad`; `// @ok` marks a line in `good`.
+- The `bad` assertion is set equality, not containment: a marked line nobody reported is a pattern that
+  stopped matching, and a reported line nobody marked is the rule reaching further than the fixture claims.
+- `good` is the half that matters most: an over-matching rule is what makes developers distrust the gate.
+- `fixture.json` is optional:
+  - `path` — where the source is written inside the temp workspace, for a rule that reads `$filename`
+    (`no-deep-internal-import`, `no-redeclare-predefined-endpoint`). Its extension also picks which of
+    `bad.ts` / `bad.tsx` is read.
+  - `expect: "file"` — for a rule whose span is the whole file (`no-bang-comment-in-client`), where there is
+    no per-line diagnostic to match. `bad` must report at least once.
+- A rule with two independent gates gets one subfolder per gate (`no-init-fetch-in-client/{use-client,store-file}`).
+- These files are excluded from the repo's own biome run (root `biome.json` `files.includes`) and from
+  `tsc` (`tsconfig.json` `exclude`), because they reference undeclared identifiers on purpose and the
+  formatter would reorder the class strings the vocabulary fixtures test.
+
+## Biome GritQL constraints these fixtures pinned down
+
+Each of these made a rule silently report nothing, and each was found by adding the fixture:
+
+- A bare snippet in JSX-attribute shape (`` `$name={$value}` ``) matches **no** JsxAttribute. Match the node
+  and read its fields: `JsxAttribute(name = $name, initializer = ...)`.
+- `JsModule()` never matches as a top-level pattern, and no node pattern is given comment trivia. A rule
+  about comments has to go through `file($name, $body)`, whose span is the whole file.
+- `file()`'s `$body` is the module's **token** span: interior trivia is visible, the leading and trailing
+  trivia are not. So a comment above the first statement or below the last one is unreachable from GritQL —
+  that is `no-bang-comment-in-client`'s blind spot, and why its fixture puts the marker between statements.
+- A regex capture (`r"..."($var)`) carries no source range: a diagnostic spanned on one gets no location,
+  and `$var` does not interpolate into a `message`.
+
+The five vocabulary fixtures were ported from `frontendBuild/styleGuard.test.ts`, the pre-grit
+implementation of the same rules, when that scanner was retired.

package/lint/__fixtures__/no-arbitrary-color/bad.tsx

@@ -0,0 +1,3 @@
+export const HexValue = () => <div className="bg-[#3b82f6]" />; // @flag
+export const ColorFunctionValue = () => <div className="text-[rgb(0,0,0)]" />; // @flag
+export const HslValue = () => <div className="border-[hsl(210,100%,50%)]" />; // @flag

package/lint/__fixtures__/no-arbitrary-color/good.tsx

@@ -0,0 +1,4 @@
+export const CssVariableShorthand = () => <div className="bg-[--brand]" />; // @ok
+export const CssVariableFunction = () => <div className="text-[var(--fg)]" />; // @ok
+export const ArbitrarySizeNotColor = () => <div className="min-h-[300px] w-[42ch]" />; // @ok
+export const SemanticToken = () => <div className="bg-primary" />; // @ok

package/lint/__fixtures__/no-async-component-in-ui/bad.tsx

@@ -0,0 +1,4 @@
+export const Card = async () => <div className="flex" />; // @flag
+export const Typed: FC = async () => <div className="flex" />; // @flag
+export async function Panel() { return <div className="flex" />; } // @flag
+export default async function Shell() { return <div className="flex" />; } // @flag

package/lint/__fixtures__/no-async-component-in-ui/good.tsx

@@ -0,0 +1,4 @@
+export const Card = () => <div className="flex" />; // @ok
+export const Handler = () => { const onSave = async () => save(); return <button onClick={onSave} />; }; // @ok
+export const loadThing = async () => await fetchThing(); // @ok
+export function Panel() { return <div className="flex" />; } // @ok

package/lint/__fixtures__/no-bang-comment-in-client/bad.tsx

@@ -0,0 +1,4 @@
+export const a = 1;
+//! FIXME: this marker survives minification and ships to every visitor
+/*! and so does the block form */
+export const b = 2;

package/lint/__fixtures__/no-bang-comment-in-client/fixture.json

@@ -0,0 +1 @@
+{ "expect": "file" }