@akanjs/devkit 3.0.0 → 3.0.2-rc.0

package/executors.ts

@@ -44,13 +44,16 @@ import { AkanAppConfig, AkanLibConfig, decreaseBuildNum, increaseBuildNum } from
 import { getRootBoundarySegments, isRootBoundarySegments } from "./artifact/implicitRootLayout";
 import { CodegenLock } from "./codegenLock";
 import { FileSys, getDirname } from "./fileSys";
+import { JsonFormatter } from "./jsonFormatter";
 import { Linter } from "./linter";
+import { ManifestDependencies } from "./manifestDependencies";
 import { resolveRepoName } from "./repoIdentity";
-import { AppInfo, LibInfo, PkgInfo, WorkspaceInfo } from "./scanInfo";
+import { AppInfo, isAkanFrameworkDependency, LibInfo, PkgInfo, WorkspaceInfo } from "./scanInfo";
 import { Spinner } from "./spinner";
 // Type-only: `getTypeChecker` loads it on demand to keep `typescript` out of the resident module graph.
 import type { TypeChecker } from "./typeChecker";
 import type { FileContent, PackageJson, TsConfigJson } from "./types";
+import { barrelFacetDirs } from "./workspaceLayout";
 
 export interface PageRoot {
   /** App-relative location of the route files, i.e. the symlink for a synced lib. */
@@ -303,8 +306,7 @@ export class Executor {
     const writePath = this.getPath(filePath);
     const dir = path.dirname(writePath);
     if (!(await FileSys.dirExists(dir))) await mkdir(dir, { recursive: true });
-    //? Biome ends every .json with a newline; without one, `akan lint` and `akan sync` would flip-flop the file.
-    let contentStr = typeof content === "string" ? content : `${JSON.stringify(content, null, 2)}\n`;
+    let contentStr = typeof content === "string" ? content : JsonFormatter.stringify(content, writePath);
 
     if (await FileSys.fileExists(writePath)) {
       const currentContent = await FileSys.readText(writePath);
@@ -839,8 +841,6 @@ interface SysExecutorOptions extends NamedExecutorOptions {
   type: "app" | "lib";
 }
 
-const scanFacetDirs = ["ui", "webkit", "srvkit", "common", "plugin"] as const;
-
 export class SysExecutor extends Executor {
   workspace: WorkspaceExecutor;
   override name: string;
@@ -896,7 +896,7 @@ export class SysExecutor extends Executor {
       this._applyTemplate({ basePath: ".", template: "server.ts", scanInfo }),
       this._applyTemplate({ basePath: ".", template: "client.ts", scanInfo }),
       this.type === "lib" ? this._applyTemplate({ basePath: ".", template: "index.ts", scanInfo }) : null,
-      ...scanFacetDirs.map((facet) =>
+      ...barrelFacetDirs.map((facet) =>
         this._applyTemplate({
           basePath: facet,
           template: "facetIndex/index.ts",
@@ -936,11 +936,9 @@ export class SysExecutor extends Executor {
       await CodegenLock.run(this.workspace.workspaceRoot, `scan:${this.name}`, async () => {
         await Promise.all(this.#getScanTemplateTasks(scanInfo));
         await this.writeJson(`akan.${this.type}.json`, scanInfo.getScanResult());
-        if (this.type === "lib") this.#updateDependencies(scanInfo);
-
+        await this.#updateDependencies(scanInfo);
         if (writeLib) {
           const libInfos = [...scanInfo.getLibInfos().values()];
-          await this.#updateDependencies(scanInfo);
           await Promise.all(libInfos.flatMap((libInfo) => libInfo.exec.#getScanTemplateTasks(libInfo)));
         }
         await this.syncAgentsIndex(scanInfo);
@@ -962,39 +960,35 @@ export class SysExecutor extends Executor {
     // CLAUDE.md 는 얇은 포인터라 최초 1회만 깔아준다 — 사용자가 지우거나 고친 것을 되살리지 않는다.
     if (!(await this.exists("CLAUDE.md"))) await this.writeFile("CLAUDE.md", renderScopeClaudeMd(scope));
   }
+  //* The root is the cached copy the dependency scan read, so a name it declares is judged by the same snapshot.
   async #updateDependencies(scanInfo: AppInfo | LibInfo) {
-    const rootPackageJson = await this.workspace.getPackageJson();
-    const libPackageJson = await this.getPackageJson();
-    const dependencies = scanInfo.getScanResult().dependencies;
-    const devDependencies = scanInfo.getScanResult().devDependencies;
-    const dependencySet = new Set(dependencies);
-    const devDependencySet = new Set(devDependencies);
-    const libPkgJsonWithDeps: PackageJson = {
-      ...libPackageJson,
-      dependencies: {
-        ...Object.fromEntries(
-          Object.entries(libPackageJson.dependencies ?? {}).filter(([dep]) => !devDependencySet.has(dep)),
-        ),
-        ...(Object.fromEntries(
-          dependencies
-            .filter((dep) => rootPackageJson.dependencies?.[dep])
-            .sort()
-            .map((dep) => [dep, rootPackageJson.dependencies?.[dep]]),
-        ) as Record<string, string>),
-      },
-      devDependencies: {
-        ...Object.fromEntries(
-          Object.entries(libPackageJson.devDependencies ?? {}).filter(([dep]) => !dependencySet.has(dep)),
-        ),
-        ...(Object.fromEntries(
-          devDependencies
-            .filter((dep) => rootPackageJson.dependencies?.[dep] || rootPackageJson.devDependencies?.[dep])
-            .sort()
-            .map((dep) => [dep, rootPackageJson.devDependencies?.[dep] ?? rootPackageJson.dependencies?.[dep]]),
-        ) as Record<string, string>),
-      },
-    };
-    await this.setPackageJson(libPkgJsonWithDeps);
+    const [rootPackageJson, packageJson] = await Promise.all([
+      this.workspace.getPackageJson(),
+      this.getPackageJson({ refresh: true }),
+    ]);
+    const { dependencies: runtime, devDependencies: typeOnly, akanConfig } = scanInfo.getScanResult();
+    const kept = new Set([
+      ...ManifestDependencies.keptBy(packageJson),
+      ...akanConfig.externalLibs,
+      ...akanConfig.trustedDependencies,
+    ]);
+    //? The scan leaves the framework out of its imports on purpose, so it is never a prune candidate.
+    const isKept = (dep: string) => kept.has(dep) || isAkanFrameworkDependency(dep);
+    const { dependencies, devDependencies, removed, unverifiable } = new ManifestDependencies(
+      rootPackageJson,
+      { runtime, typeOnly },
+      isKept,
+    ).realign(packageJson);
+    const manifestPath = `${this.type}s/${this.name}/package.json`;
+    if (removed.length)
+      this.logger.info(
+        `Removed from ${manifestPath}, declared by the root and imported nowhere: ${removed.join(", ")} (list one in akan.keepDependencies to keep it)`,
+      );
+    if (unverifiable.length)
+      this.logger.warn(
+        `${manifestPath} lists ${unverifiable.join(", ")}, which the root package.json does not declare, so sync cannot tell whether it is used; kept as is`,
+      );
+    await this.setPackageJson({ ...packageJson, dependencies, devDependencies });
   }
   override async getLocalFile(targetPath: string) {
     const filePath = path.isAbsolute(targetPath) ? targetPath : `${this.type}s/${this.name}/${targetPath}`;
@@ -1119,13 +1113,21 @@ export class AppExecutor extends SysExecutor {
   static from(executor: SysExecutor | WorkspaceExecutor, name: string) {
     return new AppExecutor({ workspace: executor instanceof WorkspaceExecutor ? executor : executor.workspace, name });
   }
-  //* Not dev output: native builds and the update releases waiting to be uploaded, and the downloaded `bin` sources.
-  static readonly #keptOnStart = [path.join(".akan", "native"), path.join(".akan", "cache", "bin")];
+  //* Not dev output: the downloaded `bin` sources.
+  static readonly #keptOnStart = [path.join(".akan", "cache", "bin")];
+  //* Native builds moved to dist/native/<app>; the old folder may hold a signed release nobody uploaded yet.
+  static readonly #legacyNative = path.join(".akan", "native");
   async #removeDevOutput(dir = ".akan") {
     const entries = await readDirEntries(this.getPath(dir)).catch(() => [] as string[]);
     await Promise.all(
       entries.map(async (name) => {
         const entry = path.join(dir, name);
+        if (entry === AppExecutor.#legacyNative) {
+          this.logger.warn(
+            `apps/${this.name}/.akan/native holds native builds from before they moved to dist/native/${this.name}: upload any release waiting in its updates folders, then delete it.`,
+          );
+          return;
+        }
         if (AppExecutor.#keptOnStart.includes(entry)) return;
         if (AppExecutor.#keptOnStart.some((kept) => kept.startsWith(`${entry}${path.sep}`)))
           return await this.#removeDevOutput(entry);
@@ -1209,10 +1211,10 @@ export class AppExecutor extends SysExecutor {
     // Ports and the operation mode are dropped: `define` would bake them in and outrank the container's own values.
     if (type === "build") {
       const buildEnv = { ...env };
-      delete buildEnv.AKAN_PUBLIC_CLIENT_PORT;
-      delete buildEnv.AKAN_PUBLIC_SERVER_PORT;
-      delete buildEnv.AKAN_PUBLIC_OPERATION_MODE;
-      delete process.env.AKAN_PUBLIC_OPERATION_MODE;
+      for (const key of ["AKAN_PUBLIC_CLIENT_PORT", "AKAN_PUBLIC_SERVER_PORT", "AKAN_PUBLIC_OPERATION_MODE"]) {
+        delete buildEnv[key];
+        delete process.env[key];
+      }
       Object.assign(process.env, buildEnv);
     }
     return { env };

package/frontendBuild/csrArtifactBuilder.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText } from "../testHelpers";
+
+const makeTempRoot = tempDirs("akan-csr-artifact-");
+
+describe("CsrArtifactBuilder.bundleOptions", () => {
+  //? A child process: Bun reads `.env` only at start, and the bug was that this snapshot outranked `define`.
+  test("bakes the env a native build sets on process.env, not the .env value Bun loaded at start", async () => {
+    const root = await makeTempRoot();
+    await writeText(path.join(root, ".env"), "AKAN_PUBLIC_ENV=local\n");
+    await writeText(path.join(root, "entry.ts"), 'console.info("envmark:" + process.env.AKAN_PUBLIC_ENV);\n');
+    await writeText(
+      path.join(root, "build.ts"),
+      `import { CsrArtifactBuilder } from ${JSON.stringify(path.join(import.meta.dir, "csrArtifactBuilder.ts"))};
+process.env.AKAN_PUBLIC_ENV = "debug";
+const app = { getPublicEnv: () => ({ AKAN_PUBLIC_ENV: process.env.AKAN_PUBLIC_ENV }) };
+const result = await Bun.build({ ...CsrArtifactBuilder.bundleOptions(app as never, "build"), entrypoints: ["./entry.ts"] });
+console.info(await result.outputs[0].text());
+`,
+    );
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("AKAN_PUBLIC_")));
+    const proc = Bun.spawn([process.execPath, "build.ts"], { cwd: root, env, stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("envmark:debug");
+    expect(stdout).not.toContain("envmark:local");
+  });
+});

package/frontendBuild/csrArtifactBuilder.ts

@@ -54,18 +54,11 @@ export class CsrArtifactBuilder {
     );
 
     const result = await Bun.build({
-      target: "browser",
+      ...CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports),
       entrypoints: htmlBasePaths.map((basePath) => this.#generatedPath(CsrArtifactBuilder.htmlFilename(basePath))),
       files: generatedFiles,
       root: this.#generatedDir,
       outdir: this.#outputDir,
-      splitting: false,
-      minify: true,
-      env: "AKAN_PUBLIC_*",
-      define: bundleDefine(this.#app, this.#command, "csr"),
-      optimizeImports: akanConfig.optimizeImports,
-      // A raw `.css` in the route graph is Tailwind source; the base artifact's compiled sheet is the only stylesheet.
-      plugins: [PagesBundleBuilder.createCssStubPlugin()],
     });
 
     if (!result.success) {
@@ -78,6 +71,19 @@ export class CsrArtifactBuilder {
     return { outputDir: this.#outputDir };
   }
 
+  //? No `env` option: Bun inlines the `.env` it read at process start over `define`, so a native build's `--env` lost.
+  static bundleOptions(app: App, command: "build" | "start", optimizeImports: string[] = []) {
+    return {
+      target: "browser" as const,
+      splitting: false,
+      minify: true,
+      define: bundleDefine(app, command, "csr"),
+      optimizeImports,
+      // A raw `.css` in the route graph is Tailwind source; the base artifact's compiled sheet is the only stylesheet.
+      plugins: [PagesBundleBuilder.createCssStubPlugin()],
+    };
+  }
+
   /** The routes one basePath's HTML boots: its own plus every route outside any basePath, matching `bootCsr`. */
   static pageEntriesForBasePath(pageEntries: PageEntry[], basePath: string, basePaths: string[]): PageEntry[] {
     return CsrEntryFiles.pageEntriesForBasePath(pageEntries, basePath, basePaths);

package/frontendBuild/csrDevModuleCompiler.ts

@@ -154,7 +154,6 @@ export class CsrDevModuleCompiler {
         naming: { entry: "[dir]/[name].[ext]", asset: "assets/[name]-[hash].[ext]" },
         publicPath: this.#routePrefix,
         metafile: true,
-        env: "AKAN_PUBLIC_*",
         //? A factory runs as a classic script, where `import.meta` is a SyntaxError that takes the whole vendor file
         //? down, and Bun's cjs output keeps `import.meta.env` and spells `import.meta.url` as this disk's `file://` path.
         define: { ...this.#context.define, "import.meta": "__akanMeta" },

package/frontendBuild/csrDevResolver.ts

@@ -88,7 +88,6 @@ export class CsrDevResolver {
       target: "browser",
       metafile: true,
       external: [...(this.#context.externals ?? [])],
-      env: "AKAN_PUBLIC_*",
       define: this.#context.define,
       optimizeImports: this.#context.optimizeImports,
       plugins: [PagesBundleBuilder.createCssStubPlugin()],
@@ -112,7 +111,6 @@ export class CsrDevResolver {
       metafile: true,
       throw: false,
       external: [...(this.#context.externals ?? [])],
-      env: "AKAN_PUBLIC_*",
       define: this.#context.define,
       plugins: [
         {

package/frontendBuild/devGeneratedIndexSync.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { tempDirs } from "../testHelpers";
 import { DevGeneratedIndexSync } from "./devGeneratedIndexSync";
@@ -40,6 +40,18 @@ describe("DevGeneratedIndexSync facet barrels", () => {
     expect(content).toBe(`export * from "./aes";\nexport * from "./cloudflareApi";\nexport * from "./storageApi";\n`);
   });
 
+  test("a facet with nothing to export keeps an empty barrel, and a deleted facet gets none", async () => {
+    const root = await makeTempRoot();
+    const content = await barrelFor(root, "common", { files: ["foo.helper.ts"], dirs: [], trigger: "foo.helper.ts" });
+    expect(content).toBe("export {};\n");
+
+    const dir = path.join(root, "libs", "util", "common");
+    await rm(dir, { recursive: true });
+    const sync = new DevGeneratedIndexSync({ workspaceRoot: root });
+    expect(await sync.syncForBatch([path.join(dir, "foo.helper.ts")])).toEqual({ changedFiles: [], errors: [] });
+    expect(await Bun.file(path.join(dir, "index.ts")).exists()).toBe(false);
+  });
+
   test("ui facet exports only clean PascalCase names", async () => {
     const content = await barrelFor(await makeTempRoot(), "ui", {
       files: ["Globe.tsx", "AkanLogo.tsx", "Globe_Dynamic.tsx", "lowerStart.tsx"],

package/frontendBuild/devGeneratedIndexSync.ts

@@ -114,7 +114,8 @@ export class DevGeneratedIndexSync {
 
   async #facetContent(dir: string): Promise<string | null> {
     const nameCasePattern = path.basename(dir) === "ui" ? FACET_PASCAL_CASE_RE : FACET_CAMEL_CASE_RE;
-    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => null);
+    if (!entries) return null;
     const exportNames = entries
       .flatMap((entry) => {
         const name = entry.name;
@@ -125,8 +126,8 @@ export class DevGeneratedIndexSync {
         const exportName = name.replace(FACET_SOURCE_FILE_RE, "");
         return nameCasePattern.test(exportName) ? [exportName] : [];
       })
-      .sort();
-    if (exportNames.length === 0) return null;
+      .sort(compareExportNames);
+    if (exportNames.length === 0) return "export {};\n";
     return `${exportNames.map((name) => `export * from "./${name}";`).join("\n")}\n`;
   }
 
@@ -149,10 +150,26 @@ export class DevGeneratedIndexSync {
       if (await exists(path.join(dir, `${modelName}.${type}.tsx`))) fileTypes.push(type);
     }
     if (fileTypes.length === 0) return null;
-    return `\n${fileTypes.map((type) => `import * as ${type} from "./${modelName}.${type}";`).join("\n")}\n\nexport const ${modelName} = { ${fileTypes.join(", ")} };`;
+    return `${fileTypes.map((type) => `import * as ${type} from "./${modelName}.${type}";`).join("\n")}\n\nexport const ${modelName} = { ${fileTypes.join(", ")} };\n`;
   }
 }
 
+//? Biome's organizeImports order, or `akan lint` reorders the barrel: A < a < B < b, a digit before a letter, and a
+//? run of digits compared by its length first. The facetIndex template sorts the same way.
+const letterRankOf = (char: string) => char.toLowerCase().charCodeAt(0) * 2 + (char === char.toLowerCase() ? 1 : 0);
+const digitRunAt = (name: string, idx: number) => /^\d+/.exec(name.slice(idx))?.[0] ?? "";
+const compareExportNames = (a: string, b: string) => {
+  for (let idx = 0; idx < a.length && idx < b.length; ) {
+    const [runA, runB] = [digitRunAt(a, idx), digitRunAt(b, idx)];
+    if (runA && runB && runA !== runB) return runA.length - runB.length || (runA < runB ? -1 : 1);
+    if (runA && runB) idx += runA.length;
+    else if (runA || runB) return runA ? -1 : 1;
+    else if (a.charAt(idx) !== b.charAt(idx)) return letterRankOf(a.charAt(idx)) - letterRankOf(b.charAt(idx));
+    else idx++;
+  }
+  return a.length - b.length;
+};
+
 const exists = async (file: string) =>
   stat(file)
     .then(() => true)

package/frontendBuild/frontendBuild.test.ts

@@ -354,7 +354,7 @@ describe("DevGeneratedIndexSync", () => {
 
     expect(removed.errors).toEqual([]);
     expect(removed.changedFiles).toEqual([index]);
-    expect(await Bun.file(index).exists()).toBe(false);
+    expect(await readFile(index, "utf8")).toBe("export {};\n");
   });
 
   test("ignores server/client folders as barrel facets", async () => {

package/frontendBuild/hmrWatcher.ts

@@ -61,6 +61,12 @@ export class HmrWatcher {
           const abs = path.resolve(root, filename.toString());
           this.#queue(abs);
         });
+        //? Linux emits an unreadable subdirectory as an async EPERM error event, which throws when unhandled.
+        //? The coverage-gap scan already warns about it, so only other errors are worth a warning here.
+        w.on("error", (err: NodeJS.ErrnoException) => {
+          if (err.code === "EACCES" || err.code === "EPERM") this.#logger.verbose(`[hmr] ${err.message}`);
+          else this.#logger.warn(`[hmr] watcher error under ${root}: ${err.message}`);
+        });
         this.#watchers.push(w);
         this.#logger.verbose(`[hmr] watching ${root}`);
       } catch (err) {

package/integration/devStability.integration.test.ts

@@ -583,10 +583,13 @@ describe("dev resource budgets", () => {
     expect(await DevStabilityHarness.buildWorkerProcess(host.proc.pid)).toBeNull();
   });
 
+  //? Between a fresh builder and one that has built a route, or the host stops enforcing it or never recycles.
+  //? macOS keeps the bundler arenas (~380MiB built); Linux measured 101-115MiB fresh, 157-176MiB built and settled.
+  const CEILING_MB = process.platform === "linux" ? 135 : 200;
+
   budgetTest("recycles the builder at an unmeetable ceiling and keeps developing through it", async () => {
     const harness = await createHarness();
-    // Below the builder once it has served the first route build (about 380MiB), which arms the recycle.
-    const host = await harness.startHost({ timeoutMs: BOOT_MS, env: { AKAN_BUILDER_MAX_RSS_MB: "200" } });
+    const host = await harness.startHost({ timeoutMs: BOOT_MS, env: { AKAN_BUILDER_MAX_RSS_MB: String(CEILING_MB) } });
     const start = host.markLog();
     await harness.waitForHttpText("initial-client-marker", WAIT_MS);
 
@@ -598,7 +601,7 @@ describe("dev resource budgets", () => {
 
     const recycleLog = await host.waitForLogSince(
       start,
-      /recycling builder pid=(\d+) \((rss=\d+MiB>=200MiB after \d+ build\(s\))\)/,
+      new RegExp(`recycling builder pid=(\\d+) \\((rss=\\d+MiB>=${CEILING_MB}MiB after \\d+ build\\(s\\))[;)]`),
       WAIT_MS,
     );
     await host.waitForLogSince(start, /exiting for recycle/, WAIT_MS);
@@ -634,7 +637,7 @@ describe("dev resource budgets", () => {
     const settled = await DevStabilityHarness.builderProcess(host.proc.pid);
     const warned = /ceiling costs about one boot build per interval/.test(host.logs.join("").slice(start));
     //? Past the interval (a slow machine) the next report recycles instead of warning: either answer settles it.
-    if ((settled?.rssBytes ?? 0) >= 200 * MB && !warned)
+    if ((settled?.rssBytes ?? 0) >= CEILING_MB * MB && !warned)
       await host.waitForLogSince(
         settledFrom,
         /ceiling costs about one boot build per interval|recycling builder pid=\d+|skipped: the builder fell to/,
@@ -645,7 +648,7 @@ describe("dev resource budgets", () => {
 
   budgetTest("serves a page requested while the builder is being replaced", async () => {
     const harness = await createHarness();
-    const host = await harness.startHost({ timeoutMs: BOOT_MS, env: { AKAN_BUILDER_MAX_RSS_MB: "200" } });
+    const host = await harness.startHost({ timeoutMs: BOOT_MS, env: { AKAN_BUILDER_MAX_RSS_MB: String(CEILING_MB) } });
     const port = await harness.resolvePort();
     await harness.waitForHttpText("initial-client-marker", WAIT_MS);
 

package/integration/devStabilityHarness.ts

@@ -269,6 +269,8 @@ export const dictionary = serviceDictionary(["en", "ko"])
         // The dev-plan/hmr assertions match verbose-level lines.
         AKAN_PUBLIC_LOG_LEVEL: "verbose",
         NODE_NO_WARNINGS: "1",
+        //? CI's `.env` names the branch; any env but local makes `akan start` ssh-tunnel to that cluster's Redis.
+        AKAN_PUBLIC_ENV: "local",
         PORT_OFFSET: String(offset),
         // Pinned: `getDevPort()` derives from the fixture's index in `apps/`, which parallel runs keep moving.
         AKAN_DEV_PORT: String(port),

package/jsonFormatter.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { JsonFormatter } from "./jsonFormatter";
+import { formatWithBiome, hasBiome } from "./testHelpers";
+
+const pad = (length: number) => "x".repeat(length);
+const thousands = Array.from({ length: 40 }, (_, idx) => idx * 1000);
+
+const fixtures: Record<string, unknown> = {
+  collapsed: { scalars: ["accessToken", "accessLog"], empty: [], none: {}, nested: [["a"], [{}]] },
+  commaAtTheEdge: { a: [pad(108)], b: [pad(109)], c: [pad(109)] },
+  objectsInArray: { routes: [{ path: "/" }, { path: "/a" }] },
+  numbers: { sizes: thousands, words: thousands.map(String) },
+  wide: { a: ["한".repeat(54)], b: ["한".repeat(55)] },
+  rootArray: [pad(60), pad(60)],
+};
+
+describe("JsonFormatter", () => {
+  test("collapses an array that fits the line with its trailing comma, and keeps every object expanded", () => {
+    expect(JsonFormatter.stringify(fixtures.collapsed, "akan.lib.json")).toBe(
+      '{\n  "scalars": ["accessToken", "accessLog"],\n  "empty": [],\n  "none": {},\n  "nested": [["a"], [{}]]\n}\n',
+    );
+    expect(JsonFormatter.stringify(fixtures.commaAtTheEdge, "akan.lib.json").split("\n")).toEqual([
+      "{",
+      `  "a": ["${pad(108)}"],`,
+      '  "b": [',
+      `    "${pad(109)}"`,
+      "  ],",
+      `  "c": ["${pad(109)}"]`,
+      "}",
+      "",
+    ]);
+    expect(JsonFormatter.stringify(fixtures.objectsInArray, "akan.lib.json")).toContain('"routes": [\n    {\n');
+  });
+
+  test("fills an array of numbers that overflows, and keeps any other overflowing array one item a line", () => {
+    const [, sizesOpen, firstRow, secondRow] = JsonFormatter.stringify(fixtures.numbers, "akan.app.json").split("\n");
+    expect(sizesOpen).toBe('  "sizes": [');
+    expect(firstRow).toStartWith("    0, 1000, 2000,");
+    expect(firstRow?.length).toBeLessThanOrEqual(JsonFormatter.lineWidth);
+    expect(secondRow).toStartWith("    18000,");
+    expect(JsonFormatter.stringify(fixtures.numbers, "akan.app.json")).toContain('"words": [\n    "0",\n    "1000",');
+  });
+
+  test("measures a wide character as two columns", () => {
+    const [, fits, overflows] = JsonFormatter.stringify(fixtures.wide, "akan.lib.json").split("\n");
+    expect(fits).toBe(`  "a": ["${"한".repeat(54)}"],`);
+    expect(overflows).toBe('  "b": [');
+  });
+
+  test("keeps a package.json expanded the way JSON.stringify writes it", () => {
+    const manifest = { name: "x", workspaces: ["pkgs/*"], dependencies: {} };
+    expect(JsonFormatter.stringify(manifest, "libs/x/package.json")).toBe(`${JSON.stringify(manifest, null, 2)}\n`);
+  });
+
+  test.skipIf(!hasBiome)("prints what Biome prints", async () => {
+    expect(await formatWithBiome('{"a":[1]}', "libs/fixture/akan.lib.json")).toBe('{ "a": [1] }\n');
+    for (const [name, fixture] of Object.entries(fixtures)) {
+      const printed = JsonFormatter.stringify(fixture, `libs/fixture/${name}.json`);
+      expect(await formatWithBiome(printed, `libs/fixture/${name}.json`)).toBe(printed);
+    }
+    const manifest = JsonFormatter.stringify({ name: "x", workspaces: ["a", "b"] }, "package.json");
+    expect(await formatWithBiome(manifest, "libs/fixture/package.json")).toBe(manifest);
+  });
+});

package/jsonFormatter.ts

@@ -0,0 +1,78 @@
+import path from "node:path";
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+interface Placement {
+  column: number;
+  trailing: number;
+}
+
+//* Prints what `biome format` would, or `akan lint` and `akan sync` flip-flop a generated .json. Biome keeps a
+//* package.json fully expanded (`expand: always`); elsewhere (`auto`) it keeps an object expanded, collapses an array
+//* that fits the 120-column line (a trailing comma included), fills an array of numbers, and ends with a newline.
+export class JsonFormatter {
+  static readonly lineWidth = 120;
+
+  static stringify(value: unknown, filePath: string) {
+    const json = JSON.stringify(value, null, 2);
+    if (path.basename(filePath) === "package.json") return `${json}\n`;
+    return `${JsonFormatter.#print(JSON.parse(json) as JsonValue, 0, { column: 0, trailing: 0 })}\n`;
+  }
+
+  static #print(value: JsonValue, depth: number, placement: Placement): string {
+    if (Array.isArray(value)) return JsonFormatter.#printArray(value, depth, placement);
+    if (value === null || typeof value !== "object") return JSON.stringify(value);
+    const entries = Object.entries(value);
+    if (!entries.length) return "{}";
+    const indent = "  ".repeat(depth + 1);
+    const members = entries.map(([key, member], idx) => {
+      const prefix = `${indent}${JSON.stringify(key)}: `;
+      const trailing = idx < entries.length - 1 ? 1 : 0;
+      return `${prefix}${JsonFormatter.#print(member, depth + 1, { column: Bun.stringWidth(prefix), trailing })}`;
+    });
+    return `{\n${members.join(",\n")}\n${"  ".repeat(depth)}}`;
+  }
+
+  static #printArray(items: JsonValue[], depth: number, { column, trailing }: Placement) {
+    if (!items.length) return "[]";
+    const flat = JsonFormatter.#flat(items);
+    if (flat !== null && column + Bun.stringWidth(flat) + trailing <= JsonFormatter.lineWidth) return flat;
+    const indent = "  ".repeat(depth + 1);
+    const isLast = (idx: number) => idx === items.length - 1;
+    const body = items.every((item) => typeof item === "number")
+      ? JsonFormatter.#fill(
+          items.map((item, idx) => `${JSON.stringify(item)}${isLast(idx) ? "" : ","}`),
+          indent,
+        )
+      : items
+          .map((item, idx) => {
+            const placement = { column: indent.length, trailing: isLast(idx) ? 0 : 1 };
+            return `${indent}${JsonFormatter.#print(item, depth + 1, placement)}`;
+          })
+          .join(",\n");
+    return `[\n${body}\n${"  ".repeat(depth)}]`;
+  }
+
+  static #fill(tokens: string[], indent: string) {
+    const lines: string[] = [];
+    let line = "";
+    for (const token of tokens) {
+      if (line && Bun.stringWidth(line) + 1 + Bun.stringWidth(token) <= JsonFormatter.lineWidth) {
+        line = `${line} ${token}`;
+        continue;
+      }
+      if (line) lines.push(line);
+      line = `${indent}${token}`;
+    }
+    return [...lines, line].join("\n");
+  }
+
+  static #flat(value: JsonValue): string | null {
+    if (Array.isArray(value)) {
+      const items = value.map((item) => JsonFormatter.#flat(item));
+      return items.includes(null) ? null : `[${items.join(", ")}]`;
+    }
+    if (value === null || typeof value !== "object") return JSON.stringify(value);
+    return Object.keys(value).length ? null : "{}";
+  }
+}

package/lint/__fixtures__/README.md

@@ -7,9 +7,12 @@ 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.
+- One case per line. In `bad`, `// @flag` marks a line the rule must report as an error and `// @warn` one it
+  must report as a warning; `// @ok` marks a line in `good`.
+- The `bad` assertion is exact, not containment: every marked line is reported once, at its marker's severity,
+  and nothing else is. A marked line nobody reported is a pattern that stopped matching, a reported line nobody
+  marked is the rule reaching further than the fixture claims, a line reported twice is one site reported
+  twice, and a different severity is a tier that moved.
 - `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`
@@ -35,6 +38,12 @@ Each of these made a rule silently report nothing, and each was found by adding
   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`.
+- A code snippet also matches JSX text that parses as it: `` `new Error` `` reports `<code>new Error</code>` in a
+  docs page. Where a rule meets `.tsx`, match the node kind instead (`JsNewExpression(callee = `Error`)`).
+- A regex is anchored by bare concatenation, so a top-level alternation leaks out of the anchors: `r"fill|stroke"`
+  is `^fill|stroke$` and matches `fillOpacity`. Group it: `r"(?:fill|stroke)"`.
+- A `\"` in a GritQL string is unescaped twice and corrupts it: messages quote with `'`, and a regex spells the
+  character `\x22`.
 
 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-double-brace-placeholder/bad.ts

@@ -0,0 +1,22 @@
+export const dictionary = modelDictionary(["en", "ko"])
+  .of((t) => t(["Video Board", "비디오 보드"]).desc(["A board of cuts", "컷 보드"]))
+  .error({
+    videoBlockedByPolicy: [
+      "The provider refused this video: {{reason}}", // @flag
+      "제공자가 거절했습니다: {{reason}}", // @flag
+    ],
+    invalidValues: [
+      "The device rejects these values: {{fields}} ({{command}}).", // @flag
+      "기기가 받지 않는 값입니다: {{fields}} ({{command}}).", // @flag
+    ],
+  })
+  .translate({
+    greeting: [
+      `Hello {{name}}`, // @flag
+      `안녕하세요 {{name}}`, // @flag
+    ],
+    turnSteps: [
+      `Turn ${"left"} in {{steps}} steps`, // @flag
+      "{{steps}}걸음 뒤 회전", // @flag
+    ],
+  });

package/lint/__fixtures__/no-double-brace-placeholder/fixture.json

@@ -0,0 +1 @@
+{ "path": "apps/demo/lib/videoBoard/videoBoard.dictionary.ts" }

package/lint/__fixtures__/no-double-brace-placeholder/good.ts

@@ -0,0 +1,15 @@
+export const dictionary = modelDictionary(["en", "ko"])
+  .of((t) => t(["Video Board", "비디오 보드"]).desc(["Cuts name a {{slot}} the user types", "컷에 {{슬롯}}을 적습니다"])) // @ok
+  .model((t) => ({
+    refAssets: t(["Ref Assets", "참고 자산"]).desc(["Each plays a {{slot}} of the plan", "기획안의 {{슬롯}}을 맡습니다"]), // @ok
+  }))
+  .endpoint((fn) => ({
+    bindSlot: fn(["Bind Slot", "슬롯 연결"]).desc(["Bind an asset to a {{slot}}", "{{슬롯}}에 자산을 연결합니다"]), // @ok
+  }))
+  .error({
+    videoBlockedByPolicy: ["The provider refused this video: {reason}", "제공자가 거절했습니다: {reason}"], // @ok
+  })
+  .translate({
+    greeting: [`Hello {name}`, `안녕하세요 {name}`], // @ok
+    bracesExplained: ["Wrap a name in { and }", "이름을 { 와 }로 감쌉니다"], // @ok
+  });