@akanjs/devkit 3.2.0-rc.5 → 3.2.0-rc.6

package/frontendBuild/clientEntryDiscovery.ts

@@ -4,7 +4,7 @@ import { SOURCE_EXTS } from "../akanApp/devHostPolicy";
 import type { App } from "../commandDecorators";
 import { BarrelAnalyzer, type BarrelExportMap } from "../transforms/barrelAnalyzer";
 import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
-import type { AkanConfig, ClientEntryDiscovery, ScannedImport } from "./clientBuildTypes";
+import type { AkanConfig, ClientEntryDiscovery, DiscoverOptions, ScannedImport } from "./clientBuildTypes";
 
 const USE_CLIENT_RE = /^\s*(?:\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
 const NODE_MODULES_RE = /[\\/]node_modules[\\/]/;
@@ -31,6 +31,8 @@ interface DiscoveryWalk {
   //? Every file's result within this walk, partial ones included: the file the cycle went back to is an ancestor here
   //? and brings the rest itself, and re-walking each path through a dense cycle grows exponentially.
   memo: Map<string, Set<string>>;
+  importsAs?: DiscoverOptions["importsAs"];
+  reachable: Map<string, Set<string>>;
 }
 
 const exportsKeyOf = (map: BarrelExportMap | null): string =>
@@ -50,6 +52,8 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   #resolvedFileCache = new Map<string, Lookup<string | null>>();
   #resolvedSpecifierCache = new Map<string, Lookup<string | null>>();
   #reachableEntriesCache = new Map<string, Set<string>>();
+  //? Keyed by a walk's `importsAs`: a file's answer under swapped imports holds only for walks swapping the same ones.
+  #swappedEntriesCaches = new WeakMap<object, Map<string, Set<string>>>();
   #readFiles = new Set<string>();
   #barrelImporters = new Map<string, Set<string>>();
   //? Barrels a save went beside, by the analysis before it: a save of any component re-reads its barrel, and only an
@@ -70,17 +74,29 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
     return new GraphClientEntryDiscovery(await app.getConfig(), await createTsconfigPackageResolver(app));
   }
 
-  async discover(seeds: string[]): Promise<string[]> {
+  async discover(seeds: string[], { importsAs }: DiscoverOptions = {}): Promise<string[]> {
     this.#settled = this.#settled.then(() => this.#dropRenarrowed());
     await this.#settled;
     const entries = new Set<string>();
+    const reachable = importsAs ? this.#swappedEntriesCache(importsAs) : this.#reachableEntriesCache;
     for (const seed of seeds) {
-      const walk: DiscoveryWalk = { visiting: new Set(), partial: new Set(), memo: new Map() };
+      const walk: DiscoveryWalk = { visiting: new Set(), partial: new Set(), memo: new Map(), importsAs, reachable };
       for (const entry of await this.#discoverFromFile(seed, walk)) entries.add(entry);
     }
     return Array.from(entries).sort();
   }
 
+  async resolveImport(spec: string, importerDir: string): Promise<string | null> {
+    const resolved = await this.#resolveSpecifier(spec, importerDir);
+    return resolved ? path.resolve(resolved) : null;
+  }
+
+  #swappedEntriesCache(importsAs: object): Map<string, Set<string>> {
+    const cache = this.#swappedEntriesCaches.get(importsAs) ?? new Map<string, Set<string>>();
+    this.#swappedEntriesCaches.set(importsAs, cache);
+    return cache;
+  }
+
   invalidate(files: string[]): void {
     if (files.length === 0) return;
     let moved = false;
@@ -95,6 +111,7 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
     this.#epoch += 1;
     // Reachable-entry results are transitive, so a changed child invalidates every ancestor.
     this.#reachableEntriesCache.clear();
+    this.#swappedEntriesCaches = new WeakMap();
     for (const [barrel, before] of this.#analyzer.forget(files))
       if (!this.#reread.has(barrel)) this.#reread.set(barrel, before);
     //? A file gone, or one never read, can leave a found resolution on its old target (`Chart.tsx` to
@@ -223,7 +240,8 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   async #discoverFromFile(file: string, walk: DiscoveryWalk): Promise<Set<string>> {
     const epoch = this.#epoch;
     const absPath = path.resolve(file);
-    const cached = this.#reachableEntriesCache.get(absPath);
+    const importsAs = walk.importsAs?.get(absPath);
+    const cached = walk.reachable.get(absPath);
     if (cached) return new Set(cached);
     const memo = walk.memo.get(absPath);
     if (memo) {
@@ -253,7 +271,8 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
 
     const importerDir = path.dirname(absPath);
     for (const imp of facts.imports) {
-      const spec = imp.path;
+      const swapped = importsAs?.get(imp.path);
+      const spec = swapped === undefined ? imp.path : swapped;
       if (!spec) continue;
       if (NON_SOURCE_EXT_RE.test(spec)) continue;
       const resolved = await this.#resolveSpecifier(spec, importerDir);
@@ -268,7 +287,7 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   #finishDiscovery(absPath: string, walk: DiscoveryWalk, entries: Set<string>, epoch: number): Set<string> {
     walk.visiting.delete(absPath);
     walk.memo.set(absPath, entries);
-    if (epoch === this.#epoch && !walk.partial.has(absPath)) this.#reachableEntriesCache.set(absPath, entries);
+    if (epoch === this.#epoch && !walk.partial.has(absPath)) walk.reachable.set(absPath, entries);
     return new Set(entries);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.2.0-rc.5",
+  "version": "3.2.0-rc.6",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.2.0-rc.5",
+    "@akanjs/language": "3.2.0-rc.6",
     "@earendil-works/pi-agent-core": "1.3.0",
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-codemode": "1.3.0",
@@ -50,7 +50,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.2.0-rc.5",
+    "akanjs": "3.2.0-rc.6",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/routeJsBudget.test.ts

@@ -96,30 +96,50 @@ describe("RouteJsBudget", () => {
     const setup = async (text?: string) => {
       const budgetPath = path.join(await makeTempRoot(), "akan.budget.json");
       if (text !== undefined) await write(budgetPath, text);
-      return { budgetPath, source: "apps/shop/akan.budget.json", environment: "local" };
+      return { app: "shop", budgetPath, source: "apps/shop/akan.budget.json", environment: "local" };
     };
 
-    test("enforce fails a route over its limit and a file it cannot read", async () => {
+    test("enforce fails a route over its limit, a route with no entry, a file it cannot read, and an app with no file", async () => {
       const over = await setup(JSON.stringify({ env: "main", routeJsBrotliKB: { "/:lang/memo": 120 } }));
       await expect(RouteJsBudget.check(sizes, { ...over, mode: "enforce" })).rejects.toThrow(
         "1 route over the JS budget in apps/shop/akan.budget.json (recorded for main, built for local):",
       );
+      await expect(RouteJsBudget.check(sizes, { ...over, mode: "enforce" })).rejects.toThrow(
+        "in apps/shop/akan.budget.json by hand.\n1 route with no entry in apps/shop/akan.budget.json",
+      );
+      const missing = await setup(JSON.stringify({ routeJsBrotliKB: { "/:lang/memo": 130 } }));
+      await expect(RouteJsBudget.check(sizes, { ...missing, mode: "enforce" })).rejects.toThrow(
+        [
+          "1 route with no entry in apps/shop/akan.budget.json, which --check-budget checks every route against:",
+          "  /:lang/new",
+          "Record it in the same change: `akan build shop --update-budget` adds each new route at its measured size.",
+        ].join("\n"),
+      );
       const broken = await setup("{");
       await expect(RouteJsBudget.check(sizes, { ...broken, mode: "enforce" })).rejects.toThrow("is not valid JSON");
+      await expect(RouteJsBudget.check(sizes, { ...(await setup()), mode: "enforce" })).rejects.toThrow(
+        "--check-budget found no apps/shop/akan.budget.json: record one with `akan build shop --update-budget`.",
+      );
     });
 
-    test("report warns of an overage and a file it cannot read, and fails neither", async () => {
+    test("report warns of an overage, a route with no entry and a file it cannot read, and fails none", async () => {
+      const unbudgetedWarning = {
+        file: "apps/shop/akan.budget.json",
+        message: "/:lang/new has no entry; akan build --check-budget fails on it",
+        fix: "record it with akan build shop --update-budget",
+      };
       const over = await setup(JSON.stringify({ env: "main", routeJsBrotliKB: { "/:lang/memo": 120 } }));
       expect(await RouteJsBudget.check(sizes, { ...over, mode: "report" })).toEqual({
         summary:
-          "1 route(s) over apps/shop/akan.budget.json (recorded for main, built for local), reported only: /:lang/memo",
+          "1 route(s) over apps/shop/akan.budget.json (recorded for main, built for local), reported only: /:lang/memo; 1 route(s) without an entry",
         warnings: [
           {
             file: "apps/shop/akan.budget.json",
             message:
-              "/:lang/memo loads 133,120 bytes brotli, over its limit of 126,976 (recorded for main, built for local); akan build fails on it",
-            fix: "shrink what the route loads, or raise its entry by hand in the same change",
+              "/:lang/memo loads 133,120 bytes brotli, over its limit of 126,976 (recorded for main, built for local); akan build --check-budget fails on it",
+            fix: "shrink what the route loads, or raise its entry with akan build shop --raise-budget",
           },
+          unbudgetedWarning,
         ],
       });
       const broken = await setup("{");
@@ -128,8 +148,8 @@ describe("RouteJsBudget", () => {
         warnings: [
           {
             file: "apps/shop/akan.budget.json",
-            message: "apps/shop/akan.budget.json is not valid JSON; akan build fails on it",
-            fix: "correct it, or rewrite it with akan build <app> --update-budget",
+            message: "apps/shop/akan.budget.json is not valid JSON; akan build --check-budget fails on it",
+            fix: "correct it, or rewrite it with akan build shop --update-budget",
           },
         ],
       });
@@ -138,7 +158,8 @@ describe("RouteJsBudget", () => {
       });
       const within = await setup(JSON.stringify({ routeJsBrotliKB: { "/:lang/memo": 130 } }));
       expect(await RouteJsBudget.check(sizes, { ...within, mode: "report" })).toEqual({
-        summary: "within apps/shop/akan.budget.json, 1 route(s) without an entry",
+        summary: "within apps/shop/akan.budget.json; 1 route(s) without an entry",
+        warnings: [unbudgetedWarning],
       });
     });
 
@@ -157,20 +178,35 @@ describe("RouteJsBudget", () => {
       await expect(RouteJsBudget.check(sizes, { ...over, mode: "update" })).rejects.toThrow("/:lang/memo");
       expect(RouteJsBudget.parse(await Bun.file(over.budgetPath).text()).kbByRoute.get("/:lang/memo")).toBe(120);
     });
+
+    test("raise re-records every route at its measured size and names the entries it raised", async () => {
+      const over = await setup(
+        JSON.stringify({ env: "main", routeJsBrotliKB: { "/:lang/memo": 120, "/:lang/new": 90 } }),
+      );
+      expect(await RouteJsBudget.check(sizes, { ...over, mode: "raise" })).toEqual({
+        summary: "apps/shop/akan.budget.json re-recorded at each route's measured size, raised: /:lang/memo",
+      });
+      const written = RouteJsBudget.parse(await Bun.file(over.budgetPath).text());
+      expect(written.env).toBe("local");
+      expect(Object.fromEntries(written.kbByRoute)).toEqual({ "/:lang/memo": 130, "/:lang/new": 70 });
+      expect(await RouteJsBudget.check(sizes, { ...over, mode: "enforce" })).toEqual({
+        summary: "within apps/shop/akan.budget.json",
+      });
+    });
   });
 
   test("names each route over budget, its limit, and how to resolve it", () => {
     expect(
       RouteJsBudget.formatOverages(
         [{ routeId: "/:lang/memo", brotliBytes: 128_000, budgetKB: 120, limitBytes: 126_976 }],
-        "apps/shop/akan.budget.json",
+        { app: "shop", source: "apps/shop/akan.budget.json" },
         " (recorded for main, built for local)",
       ),
     ).toBe(
       [
         "1 route over the JS budget in apps/shop/akan.budget.json (recorded for main, built for local):",
         "  /:lang/memo: 128,000 bytes brotli, over its limit of 126,976 (120KB + the larger of 1% and 4KB)",
-        "Shrink what the route loads. If the growth is intended, raise its entry by hand in the same change.",
+        'Shrink what the route loads. If the growth is intended, record it in the same change: `akan build shop --raise-budget` re-records every route at its measured size, or raise the route\'s entry under "routeJsBrotliKB" in apps/shop/akan.budget.json by hand.',
       ].join("\n"),
     );
   });

package/routeJsBudget.ts

@@ -17,7 +17,7 @@ export interface RouteJsOverage {
   limitBytes: number;
 }
 
-export type RouteJsBudgetMode = "enforce" | "update" | "report" | "off";
+export type RouteJsBudgetMode = "enforce" | "update" | "raise" | "report" | "off";
 
 export interface RouteJsBudgetWarning {
   file: string;
@@ -30,8 +30,20 @@ export interface RouteJsBudgetStatus {
   warnings?: RouteJsBudgetWarning[];
 }
 
+export interface RouteJsBudgetFlags {
+  checkBudget?: boolean;
+  updateBudget?: boolean;
+  raiseBudget?: boolean;
+}
+
+interface BudgetTarget {
+  app: string;
+  source: string;
+}
+
 export interface RouteJsBudgetCheck {
   mode: Exclude<RouteJsBudgetMode, "off">;
+  app: string;
   budgetPath: string;
   source: string;
   environment: string;
@@ -65,47 +77,85 @@ export class RouteJsBudget {
       .sort((a, b) => b.brotliBytes - a.brotliBytes || RouteJsBudget.#byCodeUnit(a.routeId, b.routeId));
   }
 
+  static modeOf({ checkBudget = false, updateBudget = false, raiseBudget = false }: RouteJsBudgetFlags) {
+    if ([checkBudget, updateBudget, raiseBudget].filter(Boolean).length > 1)
+      throw new Error("Pass at most one of --check-budget, --update-budget and --raise-budget.");
+    return checkBudget ? "enforce" : updateBudget ? "update" : raiseBudget ? "raise" : "report";
+  }
+
   static async load(filePath: string, source = filePath): Promise<RouteJsBudget | null> {
     const file = Bun.file(filePath);
     if (!(await file.exists())) return null;
     return RouteJsBudget.parse(await file.text(), source);
   }
 
-  //? `report` runs inside `akan verify`, where an overage or a broken file is no code error to fix in the edit loop.
-  static async check(
-    sizes: RouteJsSize[],
-    { mode, budgetPath, source, environment }: RouteJsBudgetCheck,
-  ): Promise<RouteJsBudgetStatus> {
+  //? A deploy build and `akan verify`'s edit loop only report: `enforce` (`--check-budget`, run by CI) is the gate.
+  static async check(sizes: RouteJsSize[], check: RouteJsBudgetCheck): Promise<RouteJsBudgetStatus> {
+    const { mode, app, budgetPath, source, environment } = check;
     const { committed, unreadable } = await RouteJsBudget.#loadFor(mode, budgetPath, source);
-    const budget = mode === "update" ? (committed ?? new RouteJsBudget()).tightenedBy(sizes, environment) : committed;
-    if (mode === "update" && budget) await Bun.write(budgetPath, budget.stringify());
+    if (mode === "enforce" && !committed)
+      throw new Error(`--check-budget found no ${source}: record one with \`akan build ${app} --update-budget\`.`);
+    const budget =
+      mode === "raise"
+        ? new RouteJsBudget().tightenedBy(sizes, environment)
+        : mode === "update"
+          ? (committed ?? new RouteJsBudget()).tightenedBy(sizes, environment)
+          : committed;
+    if ((mode === "update" || mode === "raise") && budget) await Bun.write(budgetPath, budget.stringify());
     const overages = budget?.overages(sizes) ?? [];
+    const unbudgeted = budget?.unbudgeted(sizes) ?? [];
     const envNote = committed?.envNote(environment) ?? "";
-    if (overages.length && mode !== "report") throw new Error(RouteJsBudget.formatOverages(overages, source, envNote));
-    const unbudgeted = budget?.unbudgeted(sizes).length ?? 0;
-    if (mode === "update") return { summary: `${source} ${unreadable ? `rewritten (${unreadable})` : "updated"}` };
+    const target = { app, source };
+    const failures = [
+      ...(overages.length && mode !== "report" ? [RouteJsBudget.formatOverages(overages, target, envNote)] : []),
+      ...(unbudgeted.length && mode === "enforce" ? [RouteJsBudget.formatUnbudgeted(unbudgeted, target)] : []),
+    ];
+    if (failures.length) throw new Error(failures.join("\n"));
+    if (mode === "update" || mode === "raise")
+      return { summary: RouteJsBudget.#writtenSummary(check, unreadable, committed, budget) };
     if (unreadable)
       return {
         summary: `${unreadable}, not checked`,
         warnings: [
           {
             file: source,
-            message: `${unreadable}; akan build fails on it`,
-            fix: "correct it, or rewrite it with akan build <app> --update-budget",
+            message: `${unreadable}; akan build --check-budget fails on it`,
+            fix: `correct it, or rewrite it with akan build ${app} --update-budget`,
           },
         ],
       };
     if (!budget) return { summary: `no ${RouteJsBudget.fileName}` };
-    if (overages.length)
-      return {
-        summary: `${overages.length} route(s) over ${source}${envNote}, reported only: ${overages.map(({ routeId }) => routeId).join(", ")}`,
-        warnings: overages.map(({ routeId, brotliBytes, limitBytes }) => ({
-          file: source,
-          message: `${routeId} loads ${RouteJsBudget.#bytes(brotliBytes)} bytes brotli, over its limit of ${RouteJsBudget.#bytes(limitBytes)}${envNote}; akan build fails on it`,
-          fix: "shrink what the route loads, or raise its entry by hand in the same change",
-        })),
-      };
-    return { summary: `within ${source}${envNote}${unbudgeted ? `, ${unbudgeted} route(s) without an entry` : ""}` };
+    const warnings = [
+      ...overages.map(({ routeId, brotliBytes, limitBytes }) => ({
+        file: source,
+        message: `${routeId} loads ${RouteJsBudget.#bytes(brotliBytes)} bytes brotli, over its limit of ${RouteJsBudget.#bytes(limitBytes)}${envNote}; akan build --check-budget fails on it`,
+        fix: `shrink what the route loads, or raise its entry with akan build ${app} --raise-budget`,
+      })),
+      ...unbudgeted.map((routeId) => ({
+        file: source,
+        message: `${routeId} has no entry; akan build --check-budget fails on it`,
+        fix: `record it with akan build ${app} --update-budget`,
+      })),
+    ];
+    const verdict = overages.length
+      ? `${overages.length} route(s) over ${source}${envNote}, reported only: ${overages.map(({ routeId }) => routeId).join(", ")}`
+      : `within ${source}${envNote}`;
+    const unbudgetedNote = unbudgeted.length ? `; ${unbudgeted.length} route(s) without an entry` : "";
+    return { summary: `${verdict}${unbudgetedNote}`, ...(warnings.length ? { warnings } : {}) };
+  }
+
+  static #writtenSummary(
+    { mode, source }: RouteJsBudgetCheck,
+    unreadable: string | null,
+    committed: RouteJsBudget | null,
+    written: RouteJsBudget | null,
+  ) {
+    if (unreadable) return `${source} rewritten (${unreadable})`;
+    if (mode === "update") return `${source} updated`;
+    const raised = [...(written?.kbByRoute ?? [])].filter(
+      ([routeId, kb]) => kb > (committed?.kbByRoute.get(routeId) ?? kb),
+    );
+    return `${source} re-recorded at each route's measured size${raised.length ? `, raised: ${raised.map(([routeId]) => routeId).join(", ")}` : ""}`;
   }
 
   static async #loadFor(mode: RouteJsBudgetCheck["mode"], budgetPath: string, source: string) {
@@ -158,18 +208,31 @@ export class RouteJsBudget {
     ];
   }
 
-  static formatOverages(overages: RouteJsOverage[], source: string, envNote = ""): string {
+  static formatOverages(overages: RouteJsOverage[], target: BudgetTarget, envNote = ""): string {
     const bytes = RouteJsBudget.#bytes;
+    const { source } = target;
     return [
       `${overages.length} route${overages.length === 1 ? "" : "s"} over the JS budget in ${source}${envNote}:`,
       ...overages.map(
         ({ routeId, brotliBytes, budgetKB, limitBytes }) =>
           `  ${routeId}: ${bytes(brotliBytes)} bytes brotli, over its limit of ${bytes(limitBytes)} (${budgetKB}KB + the larger of 1% and 4KB)`,
       ),
-      "Shrink what the route loads. If the growth is intended, raise its entry by hand in the same change.",
+      RouteJsBudget.#overageFix(target),
+    ].join("\n");
+  }
+
+  static formatUnbudgeted(routeIds: string[], { app, source }: BudgetTarget): string {
+    return [
+      `${routeIds.length} route${routeIds.length === 1 ? "" : "s"} with no entry in ${source}, which --check-budget checks every route against:`,
+      ...routeIds.map((routeId) => `  ${routeId}`),
+      `Record ${routeIds.length === 1 ? "it" : "them"} in the same change: \`akan build ${app} --update-budget\` adds each new route at its measured size.`,
     ].join("\n");
   }
 
+  static #overageFix({ app, source }: BudgetTarget) {
+    return `Shrink what the route loads. If the growth is intended, record it in the same change: \`akan build ${app} --raise-budget\` re-records every route at its measured size, or raise the route's entry under "${RouteJsBudget.section}" in ${source} by hand.`;
+  }
+
   static #bytes(value: number) {
     return value.toLocaleString("en-US");
   }