@akanjs/devkit 3.2.0-rc.1 → 3.2.0-rc.10

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");
   }

package/transforms/barrelAnalyzer.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import { parseNamedList } from "./moduleSyntax";
@@ -41,6 +42,8 @@ export class BarrelAnalyzer {
   readonly #logger = new Logger("BarrelAnalyzer");
   readonly #opts: BarrelAnalyzerOptions;
   readonly #cache = new Map<string, Promise<BarrelExportMap | null>>();
+  readonly #read = new Map<string, Set<string>>();
+  readonly #realDirs = new Map<string, string>();
   readonly #tsTranspiler = new Bun.Transpiler({ loader: "ts" });
   readonly #tsxTranspiler = new Bun.Transpiler({ loader: "tsx" });
 
@@ -56,12 +59,44 @@ export class BarrelAnalyzer {
     return promise;
   }
 
+  async filesOf(pkgName: string): Promise<string[]> {
+    await this.analyze(pkgName);
+    return [...(this.#read.get(pkgName) ?? [])];
+  }
+
+  //? A file beside one the analysis read counts too: created, it can take over a star export's specifier (`Foo.tsx`
+  //? beside `Foo/index.tsx`) with no read file changed. Both sides by realpath: a watcher names a symlinked lib's
+  //? files by their real path, where the walk went through the link.
+  forget(files: string[]): Map<string, Promise<BarrelExportMap | null>> {
+    const dirs = new Set(files.map((file) => realDirOf(file)));
+    const forgotten = new Map<string, Promise<BarrelExportMap | null>>();
+    for (const [pkgName, read] of this.#read) {
+      const analysis = this.#cache.get(pkgName);
+      if (!analysis || ![...read].some((file) => dirs.has(this.#realDirOf(file)))) continue;
+      forgotten.set(pkgName, analysis);
+      this.#cache.delete(pkgName);
+      this.#read.delete(pkgName);
+    }
+    return forgotten;
+  }
+
+  #realDirOf(file: string): string {
+    let dir = this.#realDirs.get(file);
+    if (dir === undefined) {
+      dir = realDirOf(file);
+      this.#realDirs.set(file, dir);
+    }
+    return dir;
+  }
+
   async #analyzeSafe(pkgName: string): Promise<BarrelExportMap | null> {
     try {
       const pkg = await this.#opts.resolvePackage(pkgName);
       if (!pkg) return null;
       const map: BarrelExportMap = new Map();
-      await this.#walk(pkg.entryFile, pkg, map, new Set());
+      const read = new Set<string>();
+      this.#read.set(pkgName, read);
+      await this.#walk(pkg.entryFile, pkg, map, read);
       return map;
     } catch (err) {
       this.#logger.error(`analyze failed for ${pkgName}: ${(err as Error).message}`);
@@ -170,6 +205,16 @@ export class BarrelAnalyzer {
   }
 }
 
+const realDirOf = (file: string): string => {
+  const dir = path.dirname(path.resolve(file));
+  try {
+    return fs.realpathSync.native(dir);
+  } catch {
+    // A directory removed with the file keeps its own path.
+    return dir;
+  }
+};
+
 const isRelative = (spec: string): boolean => {
   return spec.startsWith("./") || spec.startsWith("../") || spec === "." || spec === "..";
 };

package/transforms/barrelImportsPlugin.ts

@@ -4,7 +4,7 @@ import ts from "typescript";
 import { StoreBootstrap } from "../artifact/storeBootstrap";
 import type { App } from "../commandDecorators";
 import { BarrelAnalyzer, type BarrelExportMap, type PackageEntry } from "./barrelAnalyzer";
-import { loaderFor, type NamedItem, parseNamedList } from "./moduleSyntax";
+import { loaderFor, type NamedItem } from "./moduleSyntax";
 
 export interface BarrelImportsPluginOptions {
   /** Absolute paths whose content is returned unchanged (e.g. node_modules). */
@@ -234,10 +234,22 @@ const resolveFileCandidate = async (candidate: string): Promise<string | null> =
 
 const MACRO_ATTR_RE = /with\s*\{\s*type\s*:\s*["']macro["']\s*\}/;
 
+export interface RewriteBarrelImportsOptions {
+  /** Each replacement takes one line plus the newlines the statement spanned, so later lines keep their numbers. */
+  keepLines?: boolean;
+  specifierOf?: (subpath: string) => string;
+  /** Called for each import of a listed barrel with the value names whose rewrite reads its export map. */
+  onImport?: (barrel: string, names: string[]) => void;
+}
+
+export const workspaceBarrels = (barrels: readonly string[]): string[] =>
+  barrels.filter((barrel) => /^@(?:apps|libs)\//.test(barrel));
+
 export const rewriteBarrelImports = async (
   source: string,
   barrels: string[],
   analyzer: BarrelAnalyzer,
+  { keepLines = false, specifierOf = (subpath: string) => subpath, onImport }: RewriteBarrelImportsOptions = {},
 ): Promise<string | null> => {
   // Sound pre-filter before the costly parse: a static import cannot name a specifier absent from the text.
   if (!barrels.some((barrel) => source.includes(barrel))) return null;
@@ -251,20 +263,32 @@ export const rewriteBarrelImports = async (
     const stmt = statements[i];
     if (!stmt) continue;
     if (!barrels.includes(stmt.specifier)) continue;
+    const names = valueNamesOf(stmt.clause);
+    if (names.length > 0) onImport?.(stmt.specifier, names);
     const map = await analyzer.analyze(stmt.specifier);
     if (!map || map.size === 0) continue;
-    const replacement = rewriteSingleStatement(stmt, map);
-    if (replacement === null) continue;
+    const lines = rewriteSingleStatement(stmt, map, specifierOf);
+    if (lines === null) continue;
+    const replacement = keepLines
+      ? `${lines.join(" ")}${"\n".repeat(source.slice(stmt.start, stmt.end).split("\n").length - 1)}`
+      : lines.join("\n");
     out = out.slice(0, stmt.start) + replacement + out.slice(stmt.end);
     changed = true;
   }
   return changed ? out : null;
 };
 
+interface ParsedClause {
+  defaultImport?: string;
+  namespaceImport?: string;
+  named?: NamedItem[];
+  typeOnly: boolean;
+}
+
 interface ImportStatement {
   start: number;
   end: number;
-  clause: string;
+  clause: ParsedClause | null;
   specifier: string;
 }
 
@@ -286,52 +310,42 @@ const findImportStatements = (source: string): ImportStatement[] => {
     statements.push({
       start: statement.getStart(sourceFile),
       end: statement.end,
-      clause: source.slice(importClause.getStart(sourceFile), importClause.end).trim(),
+      clause: clauseOf(importClause),
       specifier: statement.moduleSpecifier.text,
     });
   }
   return statements;
 };
 
-interface ParsedClause {
-  defaultImport?: string;
-  namespaceImport?: string;
-  named?: NamedItem[];
-  typeOnly: boolean;
-}
-
-const parseImportClause = (clause: string): ParsedClause | null => {
-  let rest = clause.trim();
-  let typeOnly = false;
-  if (rest.startsWith("type ")) {
-    typeOnly = true;
-    rest = rest.slice(5).trim();
-  }
-  const parsed: ParsedClause = { typeOnly };
-  const commaMatch = /^(\w+)\s*,\s*(.+)$/.exec(rest);
-  if (commaMatch) {
-    parsed.defaultImport = commaMatch[1];
-    rest = commaMatch[2] ?? "";
-  } else if (/^\w+$/.test(rest)) {
-    parsed.defaultImport = rest;
-    return parsed;
-  }
-  if (rest.startsWith("*")) {
-    const ns = /^\*\s+as\s+(\w+)$/.exec(rest);
-    if (!ns) return null;
-    parsed.namespaceImport = ns[1];
-    return parsed;
-  }
-  if (rest.startsWith("{")) {
-    const close = rest.indexOf("}");
-    if (close === -1) return null;
-    parsed.named = parseNamedList(rest.slice(1, close));
+const clauseOf = (importClause: ts.ImportClause): ParsedClause | null => {
+  const parsed: ParsedClause = { typeOnly: importClause.phaseModifier === ts.SyntaxKind.TypeKeyword };
+  if (importClause.name) parsed.defaultImport = importClause.name.text;
+  const bindings = importClause.namedBindings;
+  if (!bindings) return parsed;
+  if (ts.isNamespaceImport(bindings)) return { ...parsed, namespaceImport: bindings.name.text };
+  const named: NamedItem[] = [];
+  for (const element of bindings.elements) {
+    if (element.propertyName && !ts.isIdentifier(element.propertyName)) return null;
+    named.push({
+      imported: (element.propertyName ?? element.name).text,
+      local: element.name.text,
+      isType: element.isTypeOnly,
+    });
   }
-  return parsed;
+  return { ...parsed, named };
 };
 
-const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): string | null => {
-  const clause = parseImportClause(stmt.clause);
+const valueNamesOf = (clause: ParsedClause | null): string[] => {
+  if (!clause || clause.namespaceImport || clause.typeOnly) return [];
+  return (clause.named ?? []).filter((item) => !item.isType).map((item) => item.imported);
+};
+
+const rewriteSingleStatement = (
+  stmt: ImportStatement,
+  map: BarrelExportMap,
+  specifierOf: (subpath: string) => string,
+): string[] | null => {
+  const { clause } = stmt;
   if (!clause) return null;
   // Namespace imports need the whole barrel — cannot rewrite safely.
   if (clause.namespaceImport) return null;
@@ -353,7 +367,7 @@ const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): st
       continue;
     }
     if (target.namespace) {
-      namespaceLines.push(`import * as ${item.local} from "${target.subpath}";`);
+      namespaceLines.push(`import * as ${item.local} from ${JSON.stringify(specifierOf(target.subpath))};`);
       continue;
     }
     const list = rewrites.get(target.subpath) ?? [];
@@ -364,7 +378,9 @@ const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): st
   if (rewrites.size === 0 && namespaceLines.length === 0) return null;
 
   //? An app or lib client barrel's import-time side effects are its client runtime and store, not its module UI.
-  const lines: string[] = [...(StoreBootstrap.ofClientBarrel(stmt.specifier, map) ?? [])];
+  const lines = (StoreBootstrap.ofClientBarrel(stmt.specifier, map) ?? []).map(
+    (specifier) => `import ${JSON.stringify(specifierOf(specifier))};`,
+  );
 
   if (clause.defaultImport || remaining.length > 0) {
     const parts: string[] = [];
@@ -374,11 +390,11 @@ const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): st
   }
 
   for (const [subpath, items] of rewrites) {
-    lines.push(`import { ${items.map(serializeNamedItem).join(", ")} } from "${subpath}";`);
+    lines.push(`import { ${items.map(serializeNamedItem).join(", ")} } from ${JSON.stringify(specifierOf(subpath))};`);
   }
   lines.push(...namespaceLines);
 
-  return lines.join("\n");
+  return lines;
 };
 
 const serializeNamedItem = (item: NamedItem): string => {

package/transforms/transforms.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
 import path from "node:path";
 import { ApplicationBuildReporter } from "../applicationBuildReporter";
 import { tempDirs, writeText as write } from "../testHelpers";
@@ -262,6 +263,27 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(await rewriteBarrelImports(source, ["@libs/util/common"], analyzer)).toBeNull();
   });
 
+  test("forgets an analysis when a file beside one it read changes, under the link or the real path", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "real/ui/index.ts"), 'export * from "./Foo";\n');
+    await write(path.join(root, "real/ui/Foo.ts"), "export const Foo = 1;\n");
+    await write(path.join(root, "real/other/Bar.ts"), "export const Bar = 1;\n");
+    fs.symlinkSync(path.join(root, "real"), path.join(root, "linked"));
+    const pkgDir = path.join(root, "linked/ui");
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: async () => ({ pkgName: "@scope/ui", entryFile: path.join(pkgDir, "index.ts"), pkgDir }),
+    });
+    const analyzed = async () => {
+      await analyzer.analyze("@scope/ui");
+      return analyzer;
+    };
+
+    expect([...(await analyzed()).forget([path.join(root, "real/other/Bar.ts")]).keys()]).toEqual([]);
+    expect([...(await analyzed()).forget([path.join(root, "real/ui/Foo.ts")]).keys()]).toEqual(["@scope/ui"]);
+    expect([...(await analyzed()).forget([path.join(pkgDir, "Created.ts")]).keys()]).toEqual(["@scope/ui"]);
+    expect([...analyzer.forget([path.join(pkgDir, "Foo.ts")]).keys()]).toEqual([]);
+  });
+
   test("rewrites flattenable named imports and preserves default, type, and unknown imports", async () => {
     const analyzer = fakeAnalyzer([
       ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
@@ -287,6 +309,27 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(await rewriteBarrelImports('import { A } from "@other/pkg";', ["@scope/pkg"], analyzer)).toBeNull();
   });
 
+  test("reads every name of an import whose braces hold comments, aliases and type-only names", async () => {
+    const analyzer = fakeAnalyzer([
+      ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
+      ["st", { subpath: "@scope/pkg/store", originalName: "st" }],
+    ]);
+    const rewrite = async (source: string) => await rewriteBarrelImports(source, ["@scope/pkg"], analyzer);
+    const narrowed = 'import { A } from "@scope/pkg/leaf";\nimport { st } from "@scope/pkg/store";\n';
+
+    expect(await rewrite('import {\n  A, // the leaf\n  st,\n} from "@scope/pkg";\n')).toBe(narrowed);
+    expect(await rewrite('import { A, /* the store */ st } from "@scope/pkg";\n')).toBe(narrowed);
+    expect(await rewrite('import { type Shape, A as Leaf, st as store } from "@scope/pkg";\n')).toBe(
+      [
+        'import { type Shape } from "@scope/pkg";',
+        'import { A as Leaf } from "@scope/pkg/leaf";',
+        'import { st as store } from "@scope/pkg/store";',
+        "",
+      ].join("\n"),
+    );
+    expect(await rewrite('import { "A" as quoted } from "@scope/pkg";\n')).toBeNull();
+  });
+
   test("keeps a client barrel's runtime and store, never its module UI, when flattening an app or lib import", async () => {
     const root = await makeTempRoot();
     for (const sys of ["apps/demo", "libs/kit"]) {
@@ -308,13 +351,15 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     }
     await write(path.join(root, "libs/hand/client.ts"), 'export { thing } from "./lib/thing";\n');
     await write(path.join(root, "libs/hand/lib/thing.ts"), "export const thing = 1;\n");
+    await write(path.join(root, "libs/half/client.ts"), 'export { st } from "./lib/st";\n');
+    await write(path.join(root, "libs/half/lib/st.ts"), "export const st = {};\n");
     const analyzer = new BarrelAnalyzer({
       resolvePackage: await createTsconfigPackageResolver({
         workspace: { workspaceRoot: root },
         getTsConfig: async () => ({ compilerOptions: { paths: { "@apps/*": ["./apps/*"], "@libs/*": ["./libs/*"] } } }),
       } as never),
     });
-    const barrels = ["@apps/demo/client", "@libs/kit/client", "@libs/hand/client"];
+    const barrels = ["@apps/demo/client", "@libs/kit/client", "@libs/hand/client", "@libs/half/client"];
     const rewrite = async (source: string) => await rewriteBarrelImports(source, barrels, analyzer);
 
     expect(await rewrite('import { Memo, st } from "@apps/demo/client";\n')).toBe(
@@ -348,6 +393,27 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(await rewrite('import { thing } from "@libs/hand/client";\n')).toBe(
       ['import "@libs/hand/client";', 'import { thing } from "@libs/hand/lib/thing";', ""].join("\n"),
     );
+    expect(await rewrite('import { st } from "@libs/half/client";\n')).toBe(
+      ['import "@libs/half/client";', 'import { st } from "@libs/half/lib/st";', ""].join("\n"),
+    );
+  });
+
+  test("keeps each statement's line count and writes the specifier specifierOf gives a target", async () => {
+    const analyzer = fakeAnalyzer([
+      ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
+      ["ns", { subpath: "@scope/pkg/namespace", originalName: "ns", namespace: true }],
+    ]);
+    const source = 'import {\n  A,\n  ns,\n} from "@scope/pkg";\nconsole.log(A, ns);\n';
+
+    const rewritten = await rewriteBarrelImports(source, ["@scope/pkg"], analyzer, {
+      keepLines: true,
+      specifierOf: (subpath) => `./${subpath.slice("@scope/pkg/".length)}.ts`,
+    });
+
+    expect(rewritten).toBe(
+      'import { A } from "./leaf.ts"; import * as ns from "./namespace.ts";\n\n\n\nconsole.log(A, ns);\n',
+    );
+    expect(rewritten?.split("\n")).toHaveLength(source.split("\n").length);
   });
 
   test("does not rewrite import-looking code inside template literals", async () => {