@akanjs/devkit 3.0.0-alpha.3 → 3.0.0-alpha.5

package/akanContext.ts

@@ -14,6 +14,7 @@ import {
   workflowRunArtifactPath,
   workflowSyncDir,
 } from "./workflow";
+import { appRootAllowedDirs, appRootAllowedFiles, isScannedAppRootEntry } from "./workspaceLayout";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -313,36 +314,6 @@ const moduleShapeFiles = (module: AkanModuleContext) => {
 const constantFieldNames = (content: string) =>
   [...content.matchAll(/\b([A-Za-z_$][\w$]*)\s*:\s*field\(/g)].map((match) => match[1]).filter(Boolean);
 
-const appRootAllowFiles = new Set([
-  // 스코프 에이전트 가이드 — scan(write) 이 유지 (agentsIndex.ts); scanInfo.ts 의 appRootAllowedFiles 와 동기
-  "AGENTS.md",
-  "CLAUDE.md",
-  "akan.app.json",
-  "akan.config.ts",
-  "capacitor.config.ts",
-  "client.ts",
-  "main.ts",
-  "package.json",
-  "server.ts",
-  "tsconfig.json",
-]);
-
-const appRootAllowDirs = new Set([
-  ".akan",
-  "android",
-  "common",
-  "env",
-  "ios",
-  "lib",
-  "page",
-  "private",
-  "public",
-  "script",
-  "srvkit",
-  "ui",
-  "webkit",
-]);
-
 const safeReadDir = async (dirPath: string) => {
   try {
     return (await readdir(dirPath, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
@@ -671,7 +642,8 @@ export class AkanContextAnalyzer {
     for (const app of context.apps) {
       const appPath = path.join(workspace.workspaceRoot, app.path);
       for (const entry of await safeReadDir(appPath)) {
-        const allowed = entry.isDirectory() ? appRootAllowDirs.has(entry.name) : appRootAllowFiles.has(entry.name);
+        if (!isScannedAppRootEntry(entry.name)) continue;
+        const allowed = entry.isDirectory() ? appRootAllowedDirs.has(entry.name) : appRootAllowedFiles.has(entry.name);
         if (!allowed) {
           const action = repairAction(
             "module-shape",

package/applicationBuildRunner.ts

@@ -112,7 +112,7 @@ export class ApplicationBuildRunner {
       () => precompressArtifacts(this.#app),
       (result) =>
         result.files > 0
-          ? `${result.files} files, ${ApplicationBuildRunner.formatBytes(result.inputBytes)} -> ${ApplicationBuildRunner.formatBytes(result.outputBytes)}`
+          ? `${result.files} files, ${ApplicationBuildRunner.formatBytes(result.inputBytes)} -> gzip ${ApplicationBuildRunner.formatBytes(result.outputBytes)} / br ${ApplicationBuildRunner.formatBytes(result.brotliBytes)}`
           : "no files",
       phaseOptions,
     );

package/frontendBuild/allRoutesBuilder.ts

@@ -47,11 +47,24 @@ export class AllRoutesBuilder {
     this.#app.verbose(`[build-all] discovered ${seedIndex.entries.length} routes`);
     this.#discovery = await GraphClientEntryDiscovery.create(this.#app);
 
+    // Discovery first, bundling second. Chunk splitting only dedupes within one `Bun.build`, so a
+    // dependency shared by entries from different routes was emitted once per route that reached it.
+    // Discovery is cached and does no bundling, so collecting every entry up front costs almost nothing.
+    const allEntries: string[] = [];
+    const seen = new Set<string>();
     for (const entry of seedIndex.entries) {
       const seeds = Array.from(new Set([...seedIndex.globalLayoutFiles, ...entry.seeds]));
-      const delta = await this.#buildRoute(entry.routeId, seeds);
-      this.#mergeRoute(entry.routeId, delta);
+      for (const discovered of await this.#discovery.discover(seeds)) {
+        if (seen.has(discovered)) continue;
+        seen.add(discovered);
+        allEntries.push(discovered);
+      }
+      this.#routeIds.push(entry.routeId);
     }
+    this.#app.verbose(`[build-all] ${allEntries.length} client entries across ${this.#routeIds.length} routes`);
+
+    const delta = await this.#buildEntries(allEntries);
+    this.#mergeDelta(delta);
     this.#merged.knownEntries = Array.from(this.#knownSet);
 
     const manifest: RoutesManifest = {
@@ -76,28 +89,34 @@ export class AllRoutesBuilder {
     return { manifest, manifestPath, seedIndex };
   }
 
-  async #buildRoute(routeId: string, seeds: string[]): Promise<BuildRouteClientResult> {
+  async #buildEntries(entries: string[]): Promise<BuildRouteClientResult> {
     if (!this.#discovery) throw new Error("[build-all] client entry discovery is not initialized");
+    if (entries.length === 0)
+      return {
+        manifestDelta: {},
+        ssrManifestDelta: { moduleLoading: null, moduleMap: {} },
+        newEntries: [],
+        clientDeps: [],
+      };
     const started = Date.now();
     const delta = await new RouteClientBuilder({
       app: this.#app,
-      routeId,
-      seeds,
+      seeds: [],
+      entries,
       artifact: this.#artifact,
       knownEntries: this.#knownSet,
       discovery: this.#discovery,
       command: this.#command,
     }).build();
-    this.#app.verbose(`[build-all] ${routeId} +${delta.newEntries.length} entries (${Date.now() - started}ms)`);
+    this.#app.verbose(`[build-all] bundled ${delta.newEntries.length} entries (${Date.now() - started}ms)`);
     return delta;
   }
 
-  #mergeRoute(routeId: string, delta: BuildRouteClientResult): void {
+  #mergeDelta(delta: BuildRouteClientResult): void {
     for (const [key, row] of Object.entries(delta.manifestDelta)) this.#merged.clientManifest[key] = row;
     for (const [url, byName] of Object.entries(delta.ssrManifestDelta.moduleMap)) {
       this.#merged.ssrManifest.moduleMap[url] = byName;
     }
     for (const abs of delta.newEntries) this.#knownSet.add(abs);
-    this.#routeIds.push(routeId);
   }
 }

package/frontendBuild/precompressArtifacts.ts

@@ -1,26 +1,41 @@
 import fs from "node:fs";
 import path from "node:path";
+import zlib from "node:zlib";
 import type { App } from "../commandDecorators";
 
 const COMPRESSIBLE_EXTS = new Set([".css", ".html", ".js", ".json", ".svg"]);
 const MIN_COMPRESS_BYTES = 1024;
+/**
+ * Quality 11 is roughly 100x slower than gzip, so it is spent only where it pays: there is one CSS asset
+ * per basePath and it is the largest single file the app ships, worth ~20% over gzip for ~0.2s. Raising the
+ * several hundred JS chunks from 9 to 11 costs ~12s of build time to save a few hundred KB, so they stay at 9.
+ */
+const BROTLI_QUALITY_BY_EXT = { ".css": 11 } as const;
+const DEFAULT_BROTLI_QUALITY = 9;
+const GZIP_LEVEL = 9;
 
 export interface PrecompressArtifactsResult {
   files: number;
   inputBytes: number;
   outputBytes: number;
+  brotliBytes: number;
 }
 
 export async function precompressArtifacts(app: App): Promise<PrecompressArtifactsResult> {
-  const roots = [path.join(app.dist.cwdPath, ".akan/artifact/client")];
-  const result: PrecompressArtifactsResult = { files: 0, inputBytes: 0, outputBytes: 0 };
+  //* styles too: WebRouter serves both prefixes through the same sidecar-aware #fileResponse, and the
+  //* one CSS asset per basePath is the largest uncompressed payload the app ships.
+  const roots = [
+    path.join(app.dist.cwdPath, ".akan/artifact/client"),
+    path.join(app.dist.cwdPath, ".akan/artifact/styles"),
+  ];
+  const result: PrecompressArtifactsResult = { files: 0, inputBytes: 0, outputBytes: 0, brotliBytes: 0 };
 
   await Promise.all(roots.map((root) => precompressRoot(root, result)));
   if (result.files > 0) {
     app.verbose(
-      `[precompress] wrote ${result.files} gzip sidecars (${formatBytes(result.inputBytes)} -> ${formatBytes(
+      `[precompress] wrote ${result.files} sidecars (${formatBytes(result.inputBytes)} -> gzip ${formatBytes(
         result.outputBytes,
-      )})`,
+      )} / br ${formatBytes(result.brotliBytes)})`,
     );
   }
   return result;
@@ -32,16 +47,29 @@ async function precompressRoot(root: string, result: PrecompressArtifactsResult)
   for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
     if (!(await shouldPrecompress(filePath))) continue;
     const bytes = await Bun.file(filePath).bytes();
-    const gz = Bun.gzipSync(toArrayBuffer(bytes));
-    await Bun.write(`${filePath}.gz`, gz);
+    const buffer = toArrayBuffer(bytes);
+    const gz = Bun.gzipSync(buffer, { level: GZIP_LEVEL });
+    const br = brotliCompress(buffer, path.extname(filePath).toLowerCase());
+    await Promise.all([Bun.write(`${filePath}.gz`, gz), Bun.write(`${filePath}.br`, br)]);
     result.files += 1;
     result.inputBytes += bytes.byteLength;
     result.outputBytes += gz.byteLength;
+    result.brotliBytes += br.byteLength;
   }
 }
 
+function brotliCompress(buffer: ArrayBuffer, ext: string): Buffer {
+  const quality = BROTLI_QUALITY_BY_EXT[ext as keyof typeof BROTLI_QUALITY_BY_EXT] ?? DEFAULT_BROTLI_QUALITY;
+  return zlib.brotliCompressSync(buffer, {
+    params: {
+      [zlib.constants.BROTLI_PARAM_QUALITY]: quality,
+      [zlib.constants.BROTLI_PARAM_SIZE_HINT]: buffer.byteLength,
+    },
+  });
+}
+
 async function shouldPrecompress(filePath: string): Promise<boolean> {
-  if (filePath.endsWith(".gz")) return false;
+  if (filePath.endsWith(".gz") || filePath.endsWith(".br")) return false;
   if (!COMPRESSIBLE_EXTS.has(path.extname(filePath).toLowerCase())) return false;
   const file = Bun.file(filePath);
   if (!(await file.exists())) return false;

package/frontendBuild/routeClientBuilder.ts

@@ -33,6 +33,15 @@ export interface BuildRouteClientOptions {
   routeId?: string;
   command?: "build" | "start";
   discovery?: ClientEntryDiscovery;
+  /**
+   * Client entries resolved by the caller, which skips discovery and bundles exactly this list.
+   *
+   * `AllRoutesBuilder` passes every route's entries at once so they share one `Bun.build`. Chunk
+   * splitting is scoped to a single invocation, so a dependency reachable from entries spread across
+   * several invocations is emitted once per invocation — mermaid landed in `apps/akan` four times that
+   * way. Dev keeps one build per route and leaves this unset.
+   */
+  entries?: string[];
 }
 
 export interface BuildRouteClientResult {
@@ -61,6 +70,7 @@ export class RouteClientBuilder {
   #knownEntries: Set<string>;
   #command: "build" | "start";
   #discovery?: ClientEntryDiscovery;
+  #entries?: string[];
 
   constructor(options: BuildRouteClientOptions) {
     this.#app = options.app;
@@ -68,11 +78,13 @@ export class RouteClientBuilder {
     this.#knownEntries = options.knownEntries ?? new Set<string>();
     this.#command = options.command ?? "start";
     this.#discovery = options.discovery;
+    this.#entries = options.entries;
   }
 
   async build(): Promise<BuildRouteClientResult> {
-    const discovery = this.#discovery ?? (await GraphClientEntryDiscovery.create(this.#app));
-    const discovered = await discovery.discover(this.#seeds);
+    const discovered =
+      this.#entries ??
+      (await (this.#discovery ?? (await GraphClientEntryDiscovery.create(this.#app))).discover(this.#seeds));
     const entries = discovered.filter((e) => !this.#knownEntries.has(e));
     if (entries.length === 0) return this.#emptyResult(discovered);
 

package/lint/no-bang-comment-in-client.grit

@@ -0,0 +1,20 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Bun's bundler classifies `//!` and `/*!` as legal comments (the `@license` / `@preserve` class) and keeps
+// them through `minify: true`, so a `//!` marker in browser-reachable code ships verbatim to every visitor.
+// `legalComments` is not a Bun.build option, so the source is the only place to stop it.
+// The two alternatives anchor the marker to line start or to whitespace after code, which keeps a literal
+// like `'https://host//!path'` from tripping the rule. A marker on the file's very first line is trivia that
+// Biome does not expose to the pattern, so it is the one case this rule cannot see.
+JsModule() as $mod where {
+  or {
+    $mod <: r"(?m)(?s).*^[ \t]*//!.*",
+    $mod <: r"(?s).*[^\s/][ \t]+//!.*"
+  },
+  register_diagnostic(
+    span = $mod,
+    message = "The `//!` marker survives minification (Bun keeps it as a legal comment) and ships to the browser. Use `// FIXME:` or `// TODO:` in client-reachable code; keep `//!` for server, srvkit, and CLI files.",
+    severity = "error"
+  )
+}

package/package.json

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

package/qualityScanner.test.ts

@@ -183,3 +183,17 @@ describe("AkanQualityScanner ssr rules", () => {
     expect(ssrBalance[2]).toMatchObject({ scope: "workspace", serverMass: 3, clientMass: 1 });
   });
 });
+
+describe("AkanQualityScanner layout rules", () => {
+  test("flags an unknown app root file but not a facet entrypoint", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/client.ts": "export const client = 1;\n",
+      "apps/demo/helper.ts": "export const helper = 1;\n",
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.app-root-file");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("apps/demo/helper.ts");
+  });
+});

package/qualityScanner.ts

@@ -5,6 +5,7 @@ import ignore from "ignore";
 import ts from "typescript";
 import { AbstractDoc } from "./abstractDoc";
 import { formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
+import { appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
 
 type QualitySeverity = "warning";
 type QualityScope = "global" | "file" | "convention" | "layout" | "ssr";
@@ -90,29 +91,6 @@ const SUGGESTED_RULES = [
   "Avoid large mixed-purpose class files; class export files should import helpers from neighboring utility files instead of declaring them inline.",
 ];
 
-const APP_ROOT_FILES = new Set([
-  "akan.app.json",
-  "akan.config.ts",
-  "capacitor.config.ts",
-  "client.ts",
-  "main.ts",
-  "package.json",
-  "server.ts",
-  "tsconfig.json",
-]);
-
-const LIB_ROOT_FILES = new Set([
-  "cnst.ts",
-  "db.ts",
-  "dict.ts",
-  "option.ts",
-  "sig.ts",
-  "srv.ts",
-  "st.ts",
-  "useClient.ts",
-  "useServer.ts",
-]);
-
 const CONVENTION_SUFFIXES = [
   ".constant.ts",
   ".dictionary.ts",
@@ -449,7 +427,7 @@ export class AkanQualityScanner {
   #scanLayoutQuality(sourceFile: SourceFileInfo): QualityWarning[] {
     const segments = sourceFile.file.split("/");
     const warnings: QualityWarning[] = [];
-    if (segments[0] === "apps" && segments.length === 3 && !APP_ROOT_FILES.has(segments[2])) {
+    if (segments[0] === "apps" && segments.length === 3 && !appRootAllowedFiles.has(segments[2])) {
       warnings.push({
         rule: "akan.layout.app-root-file",
         scope: "layout",
@@ -460,7 +438,7 @@ export class AkanQualityScanner {
     }
 
     const libRootFile = getLibRootFile(sourceFile.file);
-    if (libRootFile && !LIB_ROOT_FILES.has(libRootFile)) {
+    if (libRootFile && !libFacetRootAllowedFiles.has(libRootFile)) {
       warnings.push({
         rule: "akan.layout.lib-root-file",
         scope: "layout",

package/scanInfo.ts

@@ -11,6 +11,7 @@ import type {
 } from "./akanConfig";
 
 import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "./executors";
+import { appRootAllowedDirs, appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
 
 const scalarFileTypes = ["constant", "dictionary", "document", "template", "unit", "util", "view", "zone"] as const;
 type ScalarFileType = (typeof scalarFileTypes)[number];
@@ -43,49 +44,7 @@ type DatabaseFileType = (typeof databaseFileTypes)[number];
 
 type ModuleKind = "database" | "service" | "scalar";
 
-const appRootAllowedFiles = new Set([
-  // 스코프 에이전트 가이드 — scan(write) 이 유지하는 색인 + 마커 밖 hand-written 내용 (agentsIndex.ts)
-  "AGENTS.md",
-  "CLAUDE.md",
-  "akan.app.json",
-  "akan.config.ts",
-  "capacitor.config.ts",
-  "client.ts",
-  "main.ts",
-  "package.json",
-  "server.ts",
-  "tsconfig.json",
-  "tsconfig.tsbuildinfo",
-]);
 const generatedRootCapacitorConfigFiles = ["capacitor.config.js", "capacitor.config.json"] as const;
-const appRootAllowedDirs = new Set([
-  ".akan",
-  "android",
-  "env",
-  "ios",
-  "lib",
-  "mobile",
-  "page",
-  "private",
-  "public",
-  "script",
-  "ui",
-  "srvkit",
-  "webkit",
-  "common",
-  "secrets",
-]);
-const libRootAllowedFiles = new Set([
-  "cnst.ts",
-  "db.ts",
-  "dict.ts",
-  "option.ts",
-  "sig.ts",
-  "srv.ts",
-  "st.ts",
-  "useClient.ts",
-  "useServer.ts",
-]);
 const internalLibDirs = new Set(["__lib", "__scalar"]);
 const moduleNonUiFileTypes = {
   database: new Set(["constant", "dictionary", "document", "service", "signal", "store"]),
@@ -107,7 +66,7 @@ const createDependencyScanner = async (exec: AppExecutor | LibExecutor | PkgExec
 
 const isAllowedTestFile = (filename: string) => testFilePattern.test(filename);
 const isAllowedLibRootFile = (filename: string) =>
-  libRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
+  libFacetRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
 const getScanPath = (exec: AppExecutor | LibExecutor, relativePath: string) =>
   path.posix.join(`${exec.type}s`, exec.name, relativePath.split(path.sep).join("/"));
 async function clearGeneratedRootCapacitorConfigs(exec: AppExecutor | LibExecutor) {

package/workspaceLayout.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { appRootAllowedDirs, appRootAllowedFiles, isScannedAppRootEntry } from "./workspaceLayout";
+
+describe("app root layout allowlist", () => {
+  test("admits the scoped agent guides sync writes into every app", () => {
+    expect(appRootAllowedFiles.has("AGENTS.md")).toBe(true);
+    expect(appRootAllowedFiles.has("CLAUDE.md")).toBe(true);
+  });
+
+  test("admits every documented app root folder", () => {
+    for (const dirname of ["mobile", "plugin", "secrets", "srvkit", "webkit"]) {
+      expect(appRootAllowedDirs.has(dirname)).toBe(true);
+    }
+  });
+
+  test("rejects an app root entry no facet owns", () => {
+    expect(appRootAllowedFiles.has("helper.ts")).toBe(false);
+    expect(appRootAllowedDirs.has("base")).toBe(false);
+  });
+
+  test("skips dotfile artifacts the sync glob never sees, but keeps .akan", () => {
+    expect(isScannedAppRootEntry(".DS_Store")).toBe(false);
+    expect(isScannedAppRootEntry(".akan")).toBe(true);
+    expect(isScannedAppRootEntry("lib")).toBe(true);
+  });
+});

package/workspaceLayout.ts

@@ -0,0 +1,61 @@
+/**
+ * App/lib 루트 레이아웃 허용 목록 — 단일 소스.
+ *
+ * 같은 규칙을 scanInfo(`akan sync`, hard error) · akanContext(`akan doctor`, diagnostic) ·
+ * qualityScanner(`akan quality scan`, warning) 세 곳이 각자 복사해 두면서 실제로 어긋났다
+ * (스코프 AGENTS.md/CLAUDE.md 는 sync 만 허용, `plugin` 은 문서에만, `secrets` 는 doctor 만 거부).
+ * 규칙을 추가할 때는 이 파일만 고치고, 루트 AGENTS.md 와 `.cursor/rules/akan-scan-conventions.mdc`
+ * 의 목록도 같이 갱신한다.
+ */
+
+export const appRootAllowedFiles = new Set([
+  // 스코프 에이전트 가이드 — scan(write) 이 유지하는 색인 + 마커 밖 hand-written 내용 (agentsIndex.ts)
+  "AGENTS.md",
+  "CLAUDE.md",
+  "akan.app.json",
+  "akan.config.ts",
+  "capacitor.config.ts",
+  "client.ts",
+  "main.ts",
+  "package.json",
+  "server.ts",
+  "tsconfig.json",
+  "tsconfig.tsbuildinfo",
+]);
+
+export const appRootAllowedDirs = new Set([
+  ".akan",
+  "android",
+  "common",
+  "env",
+  "ios",
+  "lib",
+  "mobile",
+  "page",
+  "plugin",
+  "private",
+  "public",
+  "script",
+  "secrets",
+  "srvkit",
+  "ui",
+  "webkit",
+]);
+
+export const libFacetRootAllowedFiles = new Set([
+  "cnst.ts",
+  "db.ts",
+  "dict.ts",
+  "option.ts",
+  "sig.ts",
+  "srv.ts",
+  "st.ts",
+  "useClient.ts",
+  "useServer.ts",
+]);
+
+/**
+ * scanSync 는 앱 루트를 `Bun.Glob("*")` 로 읽어 dotfile 을 아예 보지 못한다. 디렉터리를 직접 읽는
+ * doctor 가 그 차이만큼 `.DS_Store` 같은 툴 산출물을 에러로 올리므로 같은 기준으로 걸러낸다.
+ */
+export const isScannedAppRootEntry = (name: string) => !name.startsWith(".") || appRootAllowedDirs.has(name);