@akanjs/devkit 3.1.1-rc.9 → 3.1.2-rc.0

package/frontendBuild/csrArtifactBuilder.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import type { BaseBuildArtifact } from "akanjs/server";
 import { type PageEntry, resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
+import { type BarrelImportsPluginOptions, createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
 import { createBrowserDirnamePlugin } from "../transforms/browserDirnamePlugin";
 import { SideEffectImportOrder } from "../transforms/sideEffectImportOrder";
 import { bundleDefine } from "./bundleDefine";
@@ -67,6 +68,7 @@ export class CsrArtifactBuilder {
     const options = CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports);
     const result = await Bun.build({
       ...options,
+      plugins: [...options.plugins, await CsrArtifactBuilder.barrelImportsPlugin(this.#app)],
       entrypoints: htmlBasePaths.map((basePath) => this.#generatedPath(CsrArtifactBuilder.htmlFilename(basePath))),
       files: generatedFiles,
       root: this.#generatedDir,
@@ -118,6 +120,11 @@ export class CsrArtifactBuilder {
     };
   }
 
+  //? Whole, the akanjs/ui barrel bundles every component and the optional peers (react-icons) they import.
+  static async barrelImportsPlugin(app: App, pipeAfter?: BarrelImportsPluginOptions["pipeAfter"]) {
+    return await createBarrelImportsPlugin(app, { barrels: ["akanjs/ui"], pipeAfter });
+  }
+
   /** Where a build records the `AKAN_PUBLIC_*` it inlined, which nothing in the minified bundle names. */
   static publicEnvPath(app: App) {
     return path.join(app.dist.cwdPath, ".akan", "artifact", "csr-public-env.json");

package/frontendBuild/mcpAppViewBuilder.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { tempDirs, writeText as write } from "../testHelpers";
+import { CsrArtifactBuilder } from "./csrArtifactBuilder";
 import { McpAppViewBuilder } from "./mcpAppViewBuilder";
 
 const makeTempRoot = tempDirs("akan-mcp-app-views-");
@@ -132,6 +133,68 @@ describe("McpAppViewBuilder.discover", () => {
   });
 });
 
+describe("McpAppViewBuilder.build", () => {
+  test("rewrites the akanjs/ui barrel, trims the page to its apps and drops a lazy component nothing renders", async () => {
+    const root = await makeTempRoot();
+    const file = (rel: string) => path.join(root, rel);
+    await write(
+      file("node_modules/akanjs/package.json"),
+      JSON.stringify({
+        name: "akanjs",
+        exports: { "./ui": "./ui/index.ts", "./ui/*": "./ui/*", "./webkit": "./webkit.ts" },
+      }),
+    );
+    await write(
+      file("node_modules/akanjs/webkit.ts"),
+      "export const McpAppBoot = { run: (view: unknown) => console.info(view) };\n",
+    );
+    await write(
+      file("node_modules/akanjs/ui/index.ts"),
+      'export { Link } from "./Link";\nexport { Toolbox } from "./Toolbox";\n',
+    );
+    await write(file("node_modules/akanjs/ui/Link.ts"), 'export const Link = "a link";\n');
+    await write(
+      file("node_modules/akanjs/ui/Toolbox.ts"),
+      'console.info("a toolbox loaded");\nexport const Toolbox = "a toolbox";\n',
+    );
+    await write(file("apps/demo/ui/lazy.ts"), "export const lazy = (load: () => Promise<unknown>) => ({ load });\n");
+    await write(file("apps/demo/ui/Heavy.ts"), 'export default "a heavy chunk";\n');
+    await write(
+      file("apps/demo/ui/cards.ts"),
+      'import { lazy } from "./lazy";\nexport const Heavy = lazy(() => import("./Heavy"));\nexport const Card = "a card";\n',
+    );
+    await write(
+      file("apps/demo/page/home.tsx"),
+      [
+        'import { Link } from "akanjs/ui";',
+        'import { Card } from "../ui/cards";',
+        "const page = () => ({ app: (name: string, description: string, draw: () => unknown) => ({ render: (render: () => unknown) => [name, description, draw, render] }) });",
+        'export default page().app("showHome", "Show home.", () => [Link, Card]).render(() => "drawn by the render");',
+      ].join("\n"),
+    );
+    const app = {
+      cwdPath: file("apps/demo"),
+      dist: { cwdPath: file("dist/apps/demo") },
+      workspace: { workspaceRoot: root },
+      getTsConfig: async () => ({ compilerOptions: {} }),
+      getPublicEnv: () => ({}),
+      logger: { warn: () => undefined },
+    };
+
+    await new McpAppViewBuilder(app as never, "build").build(
+      [{ key: "./home.tsx", moduleAbsPath: file("apps/demo/page/home.tsx") }],
+      { basePaths: [], cssAssets: {}, options: CsrArtifactBuilder.bundleOptions(app as never, "build") },
+    );
+
+    const view = await Bun.file(file("dist/apps/demo/mcp-apps/showHome.html")).text();
+    expect(view).toContain("a link");
+    expect(view).toContain("a card");
+    expect(view).not.toContain("a toolbox");
+    expect(view).not.toContain("drawn by the render");
+    expect(view).not.toContain("a heavy chunk");
+  });
+});
+
 describe("McpAppViewBuilder.entryOf", () => {
   test("boots the one app with its page, the root layout and overrides it sits under, by relative path", () => {
     const view = {

package/frontendBuild/mcpAppViewBuilder.ts

@@ -78,7 +78,13 @@ export class McpAppViewBuilder {
     const pagePaths = [...new Set(views.map((view) => view.page.moduleAbsPath))];
     const result = await Bun.build({
       ...options,
-      plugins: [...options.plugins, McpAppPageTrimmer.plugin(pagePaths), PureLazyMarker.plugin()],
+      plugins: [
+        ...options.plugins,
+        //? Bun runs one onLoad per module, so the one rewriting the barrel also trims the pages and marks `lazy()`; the
+        //? marker plugin takes the TypeScript that one leaves to Bun, a package's own outside node_modules/akanjs.
+        await CsrArtifactBuilder.barrelImportsPlugin(this.#app, McpAppPageTrimmer.pipe(pagePaths)),
+        PureLazyMarker.plugin(),
+      ],
       entrypoints: views.map((view) => path.join(generatedDir, `${view.name}.html`)),
       files,
       root: generatedDir,

package/frontendBuild/optionalPeers.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import { mkdir, symlink } from "node:fs/promises";
+import path from "node:path";
+import type { BunPlugin } from "bun";
+import { resolveSsrPageEntries } from "../artifact/implicitRootLayout";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { CsrArtifactBuilder } from "./csrArtifactBuilder";
+import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
+
+const makeTempRoot = tempDirs("akan-optional-peers-");
+const akanjsRoot = path.resolve(import.meta.dir, "../../../akanjs");
+const { peerDependenciesMeta } = (await Bun.file(path.join(akanjsRoot, "package.json")).json()) as {
+  peerDependenciesMeta: Record<string, { optional?: boolean }>;
+};
+//? The app installs these itself: they are peers so that it renders with one React.
+const appRenderer = new Set(["react", "react-dom", "react-server-dom-webpack"]);
+const optionalPeers = Object.entries(peerDependenciesMeta)
+  .filter(([name, meta]) => meta.optional && !appRenderer.has(name))
+  .map(([name]) => name);
+const optionalPeerImport = new RegExp(
+  `^(?:${optionalPeers.map((name) => name.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")).join("|")})(?:/|$)`,
+);
+
+const recordOptionalPeers = (reached: string[]): BunPlugin => ({
+  name: "record-optional-peers",
+  setup(build) {
+    build.onResolve({ filter: optionalPeerImport }, ({ path: specifier, importer }) => {
+      reached.push(`${path.relative(akanjsRoot, importer)} -> ${specifier}`);
+      return { path: specifier, external: true };
+    });
+  },
+});
+
+const linkPackage = async (root: string, name: string, dir: string) => {
+  await mkdir(path.join(root, "node_modules"), { recursive: true });
+  await symlink(dir, path.join(root, "node_modules", name));
+};
+
+const writeApp = async (indexPage: string) => {
+  const root = await makeTempRoot();
+  const appDir = path.join(root, "apps/demo");
+  await linkPackage(root, "akanjs", akanjsRoot);
+  await linkPackage(root, "react", path.dirname(Bun.resolveSync("react/package.json", akanjsRoot)));
+  await write(
+    path.join(root, "tsconfig.json"),
+    JSON.stringify({ compilerOptions: { paths: { "@apps/*": ["./apps/*"] } } }),
+  );
+  await write(path.join(appDir, "client.ts"), "export {};\n");
+  await write(path.join(appDir, "env/env.client.ts"), "export const env = {};\n");
+  await write(path.join(appDir, "lib/dict.ts"), "export const getAllDictionary = () => ({});\n");
+  await write(path.join(appDir, "page/_index.tsx"), indexPage);
+  await write(path.join(appDir, "page/_overrides.tsx"), "export default {};\n");
+  return { root, appDir, pageKeys: ["./_index.tsx", "./_overrides.tsx"] };
+};
+
+const buildCsr = async (indexPage: string) => {
+  const { root, appDir, pageKeys } = await writeApp(indexPage);
+  const app = {
+    name: "demo",
+    cwdPath: appDir,
+    dist: { cwdPath: path.join(root, "dist/apps/demo") },
+    workspace: { workspaceRoot: root },
+    getPageKeys: async () => pageKeys,
+    getConfig: async () => ({ basePaths: [], optimizeImports: [], barrelImports: [] }),
+    getTsConfig: async () => ({ compilerOptions: { paths: { "@apps/*": ["./apps/*"] } } }),
+    getPublicEnv: () => ({}),
+    log: () => undefined,
+    verbose: () => undefined,
+    logger: { warn: () => undefined },
+  };
+  const reached: string[] = [];
+  const build = Bun.build;
+  const recorded = spyOn(Bun, "build").mockImplementation((config) =>
+    build({ ...config, plugins: [recordOptionalPeers(reached), ...(config.plugins ?? [])] }),
+  );
+
+  try {
+    await new CsrArtifactBuilder(app as never, "build").build();
+  } finally {
+    recorded.mockRestore();
+  }
+  return { root, reached };
+};
+
+describe("optional peers of akanjs", () => {
+  test("the generated root layout, the _overrides.tsx wrapper and the runtime entries import none", async () => {
+    const { appDir, pageKeys } = await writeApp("export default function Page() {\n  return null;\n}\n");
+    const generated = (await resolveSsrPageEntries({ appCwdPath: appDir, appName: "demo", pageKeys }))
+      .map(({ moduleAbsPath }) => moduleAbsPath)
+      .filter((file) => file.includes(`${path.sep}.akan${path.sep}`));
+    const runtime = [
+      path.join(akanjsRoot, "server/rscClient.tsx"),
+      path.join(akanjsRoot, "server/rscSegmentOutlet.tsx"),
+      path.join(akanjsRoot, "webkit/index.ts"),
+      ...VENDOR_SPECIFIERS.map((specifier) =>
+        path.join(akanjsRoot, "server/vendor", `${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`),
+      ),
+    ];
+    expect(generated).toHaveLength(2);
+
+    //? No barrel rewrite, as a dev registry compiles every module an import names.
+    for (const target of ["browser", "bun"] as const) {
+      const reached: string[] = [];
+      const result = await Bun.build({
+        entrypoints: [...generated, ...runtime],
+        target,
+        throw: false,
+        plugins: [recordOptionalPeers(reached)],
+      });
+
+      expect(result.logs.map((log) => log.message)).toEqual([]);
+      expect(reached).toEqual([]);
+    }
+  });
+
+  test("the CSR shell build of a page drawing akanjs/ui components imports none", async () => {
+    const { reached } = await buildCsr(
+      'import { Link, System } from "akanjs/ui";\n\nexport default function Page() {\n  return (\n    <Link href="/">\n      <System.ThemeToggle />\n    </Link>\n  );\n}\n',
+    );
+
+    expect(reached).toEqual([]);
+  });
+
+  test("the MCP App view build of a page drawing akanjs/ui components imports none", async () => {
+    const { root, reached } = await buildCsr(
+      'import { page } from "akanjs/client";\nimport { Link } from "akanjs/ui";\n\nexport default page()\n  .app("showHome", "Show the home link.", () => <Link href="/">home</Link>)\n  .render(() => null);\n',
+    );
+
+    expect(await Bun.file(path.join(root, "dist/apps/demo/mcp-apps/showHome.html")).exists()).toBe(true);
+    expect(reached).toEqual([]);
+  });
+});

package/index.ts

@@ -19,6 +19,7 @@ export type * from "./fileSys";
 export type * from "./frontendBuild";
 export type * from "./getRelatedCnsts";
 export type * from "./incrementalBuilder";
+export type * from "./maintainabilityContract";
 export type * from "./mobile";
 export type * from "./packageExportsMap";
 export type * from "./prompter";

package/integration/devStability.integration.test.ts

@@ -1,4 +1,5 @@
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { AkanAppHost } from "../akanApp";
 import { DevGeneratedIndexSync } from "../frontendBuild";
 import { DevStabilityHarness, type DevStabilityHmrProbe } from "./devStabilityHarness";
 
@@ -467,7 +468,8 @@ export class FixtureService extends serve("fixture" as const, { serverMode: "bat
     const harness = await createHarness();
     const port = await harness.resolvePort();
     // Child 0's deterministic ws port, held the way an orphaned replica from a killed run would hold it.
-    const blocker = Bun.serve({ port: port + 10_000, fetch: () => new Response("occupied") });
+    //? On the child's own 127.0.0.1: macOS lets a loopback bind share a port a wildcard listener holds.
+    const blocker = Bun.serve({ port: port + 10_000, hostname: "127.0.0.1", fetch: () => new Response("occupied") });
     try {
       const host = await harness.startHost();
       await host.waitForLog(/falling back to an ephemeral port/);
@@ -583,9 +585,9 @@ 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;
+  //? Between a fresh builder and one that has built a route, or the host stops enforcing it or never recycles. Linux
+  //? measured 101-115MiB fresh, 157-176MiB built and settled; macOS's footprint (Bun 1.4.4) 65MiB fresh, 109MiB built.
+  const CEILING_MB = process.platform === "darwin" ? 87 : 135;
 
   budgetTest("recycles the builder at an unmeetable ceiling and keeps developing through it", async () => {
     const harness = await createHarness();
@@ -635,9 +637,11 @@ describe("dev resource budgets", () => {
       await host.waitForLogSince(mark, /pages-rebundle ok/, WAIT_MS).catch(() => undefined);
     }
     const settled = await DevStabilityHarness.builderProcess(host.proc.pid);
+    //? Read as the host reads it: on macOS `ps` also counts the pages the builder freed.
+    const settledRss = settled ? await AkanAppHost.readProcessRssBytes(settled.pid) : null;
     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) >= CEILING_MB * MB && !warned)
+    if ((settledRss ?? 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/,

package/integration/ssrMemoryProbe.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -93,6 +94,7 @@ export class SsrMemoryProbe {
   }
 
   readonly #options: SsrMemoryProbeOptions;
+  readonly #statusToken = randomBytes(32).toString("hex");
   #gatewayPid = 0;
 
   constructor(options: SsrMemoryProbeOptions) {
@@ -119,6 +121,8 @@ export class SsrMemoryProbe {
         SERVER_MODE: "federation",
         ...(basePaths ? { AKAN_PUBLIC_BASE_PATHS: basePaths } : {}),
         PORT: String(port),
+        // A built app run outside `akan start` keeps the health detail and metrics behind this token.
+        AKAN_STATUS_TOKEN: this.#statusToken,
         AKAN_MEMORY_LOG: "1",
         AKAN_MEMORY_LOG_INTERVAL_MS: String(this.#options.metricsIntervalMs),
         ...(cacheOff ? { AKAN_HTML_RESULT_CACHE: "0", AKAN_RSC_RESULT_CACHE: "0" } : {}),
@@ -315,6 +319,7 @@ export class SsrMemoryProbe {
   async #fetchChildMetrics(): Promise<Array<Record<string, number>>> {
     try {
       const res = await fetch(`http://localhost:${this.#options.port}/_akan/app/metrics`, {
+        headers: { authorization: `Bearer ${this.#statusToken}` },
         signal: AbortSignal.timeout(5_000),
       });
       if (!res.ok) return [];
@@ -393,6 +398,7 @@ export class SsrMemoryProbe {
     while (Date.now() < deadline) {
       try {
         const res = await fetch(`http://localhost:${this.#options.port}/_akan/app/health`, {
+          headers: { authorization: `Bearer ${this.#statusToken}` },
           signal: AbortSignal.timeout(2_000),
         });
         if (res.ok) {

package/kindBranchScanner.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { KindBranchScanner } from "./kindBranchScanner";
+import type { SourceFileInfo } from "./qualityScanner";
+
+const filesOf = (files: Record<string, string>): SourceFileInfo[] =>
+  Object.entries(files).map(([file, content]) => ({
+    file,
+    absolutePath: `/repo/${file}`,
+    content,
+    sourceFile: ts.createSourceFile(
+      file,
+      content,
+      ts.ScriptTarget.Latest,
+      true,
+      file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    ),
+  }));
+
+const pinConstant = `import { enumOf } from "akanjs/base";
+export class PinKind extends enumOf("pinKind", ["videoScene", "videoTake", "memo"] as const) {}
+export class PinStatus extends enumOf("pinStatus", ["active", "videoTake"] as const) {}
+`;
+const comparing = (expression: string) => `export const isIt = (pin: { kind: string }) => ${expression};\n`;
+
+describe("KindBranchScanner", () => {
+  test("warns on a kind value compared in three files outside its module, naming them and the table to declare", () => {
+    const warnings = new KindBranchScanner().scan(
+      filesOf({
+        "apps/demo/lib/pin/pin.constant.ts": pinConstant,
+        "apps/demo/lib/pin/Pin.Zone.tsx": comparing('pin.kind === "videoScene"'),
+        "apps/demo/lib/board/Board.Zone.tsx": comparing('pin.kind === "videoScene"'),
+        "apps/demo/lib/take/take.store.ts": comparing('"videoScene" !== pin.kind'),
+        "apps/demo/ui/PinCard.tsx": `export const label = (kind: string) => {\n  switch (kind) {\n    case "videoScene":\n      return 1;\n  }\n};\n`,
+        "apps/demo/ui/PinCard.test.tsx": comparing('pin.kind === "videoScene"'),
+      }),
+    );
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toMatchObject({
+      rule: "akan.global.kind-branch",
+      severity: "warning",
+      file: "apps/demo/lib/pin/pin.constant.ts",
+      line: 2,
+      message: '"videoScene" of cnst.PinKind is branched on in 3 files outside the enum\'s module.',
+      locations: [
+        { file: "apps/demo/lib/board/Board.Zone.tsx", line: 1 },
+        { file: "apps/demo/lib/take/take.store.ts", line: 1 },
+        { file: "apps/demo/ui/PinCard.tsx", line: 3 },
+      ],
+    });
+    expect(warnings[0]?.fix).toContain('{ [kind in cnst.PinKind["value"]]: … }');
+  });
+
+  test("reads only a subject named for a kind, and only enums named for one", () => {
+    const warnings = new KindBranchScanner().scan(
+      filesOf({
+        "apps/demo/lib/pin/pin.constant.ts": pinConstant,
+        "apps/demo/lib/a/A.Zone.tsx": comparing('pin.status === "active" || label === "videoScene"'),
+        "apps/demo/lib/b/B.Zone.tsx": comparing('pin.status === "active" || label === "videoScene"'),
+        "apps/demo/lib/c/C.Zone.tsx": comparing('pin.status === "active" || label === "videoScene"'),
+      }),
+    );
+
+    expect(warnings).toEqual([]);
+  });
+
+  test("groups the enums sharing a value, reached from the app's own lib or a lib, never another app or lib", () => {
+    const warnings = new KindBranchScanner().scan(
+      filesOf({
+        "apps/demo/lib/pin/pin.constant.ts": pinConstant,
+        "libs/media/lib/clip/clip.constant.ts": `export class ClipType extends enumOf("clipType", ["videoTake"] as const) {}\n`,
+        "apps/demo/lib/a/A.Zone.tsx": comparing('pin.kind === "videoTake"'),
+        "apps/demo/lib/b/B.Zone.tsx": comparing('pin.kind === "videoTake"'),
+        "apps/demo/lib/c/C.Zone.tsx": comparing('pin.kind === "videoTake"'),
+        "apps/other/lib/a/A.Zone.tsx": comparing('pin.kind === "videoTake"'),
+        "apps/other/lib/b/B.Zone.tsx": comparing('pin.kind === "videoTake"'),
+        "libs/shared/lib/a/A.Zone.tsx": comparing('pin.kind === "videoTake"'),
+      }),
+    );
+
+    expect(warnings.map(({ file, message }) => ({ file, message }))).toEqual([
+      {
+        file: "apps/demo/lib/pin/pin.constant.ts",
+        message: '"videoTake" of cnst.PinKind / cnst.ClipType is branched on in 3 files outside the enum\'s module.',
+      },
+    ]);
+  });
+});

package/kindBranchScanner.ts

@@ -0,0 +1,158 @@
+import path from "node:path";
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+
+interface EnumDeclaration {
+  name: string;
+  sys: string;
+  file: string;
+  line: number;
+  module: string;
+  values: string[];
+}
+
+interface BranchSite {
+  value: string;
+  file: string;
+  line: number;
+}
+
+//? Enums sharing a value form one group: short of the type checker, nothing tells which one a literal means.
+export class KindBranchScanner {
+  static readonly rule = "akan.global.kind-branch";
+  static readonly minFileNum = 3;
+  static readonly #kindName = /(Kind|Type|Mode)$/;
+  static readonly #kindSubject = /^(kind|type|mode)$|[a-z](Kind|Type|Mode)$/;
+  static readonly #equalities = new Set([
+    ts.SyntaxKind.EqualsEqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsEqualsToken,
+    ts.SyntaxKind.EqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsToken,
+  ]);
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    const enums = sourceFiles.flatMap((sourceFile) => KindBranchScanner.#enumsOf(sourceFile));
+    const ownersByValue = new Map<string, EnumDeclaration[]>();
+    for (const declaration of enums)
+      for (const value of declaration.values)
+        ownersByValue.set(value, [...(ownersByValue.get(value) ?? []), declaration]);
+    const sitesByGroup = new Map<string, { owners: EnumDeclaration[]; sites: BranchSite[] }>();
+    for (const sourceFile of sourceFiles) {
+      if (!/^(apps|libs)\//.test(sourceFile.file) || /\.(test|spec)\.tsx?$/.test(sourceFile.file)) continue;
+      const sys = KindBranchScanner.#sysOf(sourceFile.file);
+      //? An app reaches every lib's enums; a lib only its own, as nothing here knows which libs it depends on.
+      for (const site of KindBranchScanner.#sitesIn(sourceFile, ownersByValue)) {
+        const owners = (ownersByValue.get(site.value) ?? []).filter(
+          (owner) => owner.sys === sys || (owner.sys.startsWith("libs/") && sys.startsWith("apps/")),
+        );
+        if (!owners.length || owners.some(({ module }) => site.file.startsWith(module))) continue;
+        const group = owners.map(({ name, file }) => `${file}#${name}`).join(",");
+        const entry = sitesByGroup.get(group) ?? { owners, sites: [] };
+        entry.sites.push(site);
+        sitesByGroup.set(group, entry);
+      }
+    }
+    return [...sitesByGroup.values()].flatMap(({ owners, sites }) => KindBranchScanner.#warningOf(owners, sites));
+  }
+
+  static #warningOf(owners: EnumDeclaration[], sites: BranchSite[]): QualityWarning[] {
+    const filesByValue = new Map<string, Set<string>>();
+    for (const { value, file } of sites) filesByValue.set(value, (filesByValue.get(value) ?? new Set()).add(file));
+    const values = [...filesByValue]
+      .filter(([, files]) => files.size >= KindBranchScanner.minFileNum)
+      .map(([value]) => value)
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const [owner] = owners;
+    if (!owner || !values.length) return [];
+    const branched = sites.filter(({ value }) => values.includes(value));
+    const fileNum = new Set(branched.map(({ file }) => file)).size;
+    const enumNames = owners.map(({ name }) => `cnst.${name}`).join(" / ");
+    return [
+      {
+        rule: KindBranchScanner.rule,
+        scope: "global",
+        severity: "warning",
+        file: owner.file,
+        line: owner.line,
+        message: `${values.map((value) => `"${value}"`).join(", ")} of ${enumNames} ${values.length > 1 ? "are" : "is"} branched on in ${fileNum} files outside the enum's module.`,
+        locations: branched.map(({ file, line }) => ({ file, line })),
+        fix: `Declare one table keyed by the kind, \`{ [kind in cnst.${owner.name}["value"]]: … }\` (a component, label or handler per kind), and look the kind up in it instead of comparing it in each file.`,
+      },
+    ];
+  }
+
+  static #sitesIn({ file, sourceFile }: SourceFileInfo, ownersByValue: Map<string, EnumDeclaration[]>) {
+    const sites: BranchSite[] = [];
+    const record = (literal: ts.Expression, subject: ts.Expression) => {
+      if (!ts.isStringLiteralLike(literal) || !ownersByValue.has(literal.text)) return;
+      if (!KindBranchScanner.#isKindSubject(subject)) return;
+      sites.push({
+        value: literal.text,
+        file,
+        line: sourceFile.getLineAndCharacterOfPosition(literal.getStart(sourceFile)).line + 1,
+      });
+    };
+    const visit = (node: ts.Node) => {
+      if (ts.isBinaryExpression(node) && KindBranchScanner.#equalities.has(node.operatorToken.kind)) {
+        record(node.left, node.right);
+        record(node.right, node.left);
+      } else if (ts.isCaseClause(node) && ts.isSwitchStatement(node.parent.parent))
+        record(node.expression, node.parent.parent.expression);
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return sites;
+  }
+
+  //? Only a subject named for a kind (`kind`, `pin.kind`, `viewMode`) counts: a bare `"active"` matches too much.
+  static #isKindSubject(subject: ts.Expression) {
+    let current = subject;
+    while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isNonNullExpression(current))
+      current = current.expression;
+    const name = ts.isIdentifier(current)
+      ? current.text
+      : ts.isPropertyAccessExpression(current)
+        ? current.name.text
+        : ts.isElementAccessExpression(current) && ts.isStringLiteralLike(current.argumentExpression)
+          ? current.argumentExpression.text
+          : "";
+    return KindBranchScanner.#kindSubject.test(name);
+  }
+
+  static #enumsOf({ file, sourceFile }: SourceFileInfo): EnumDeclaration[] {
+    if (!/^(apps|libs)\/[^/]+\/lib\/.+\.constant\.ts$/.test(file)) return [];
+    return sourceFile.statements.flatMap((statement) => {
+      if (!ts.isClassDeclaration(statement) || !statement.name) return [];
+      if (!KindBranchScanner.#kindName.test(statement.name.text)) return [];
+      const values = KindBranchScanner.#enumValuesOf(statement);
+      if (!values) return [];
+      return [
+        {
+          name: statement.name.text,
+          sys: KindBranchScanner.#sysOf(file),
+          file,
+          line: sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile)).line + 1,
+          module: `${path.posix.dirname(file)}/`,
+          values,
+        },
+      ];
+    });
+  }
+
+  static #sysOf(file: string) {
+    return file.split("/").slice(0, 2).join("/");
+  }
+
+  static #enumValuesOf(statement: ts.ClassDeclaration) {
+    for (const clause of statement.heritageClauses ?? [])
+      for (const { expression } of clause.types) {
+        if (!ts.isCallExpression(expression) || !ts.isIdentifier(expression.expression)) continue;
+        if (expression.expression.text !== "enumOf") continue;
+        let list = expression.arguments[1];
+        while (list && (ts.isAsExpression(list) || ts.isParenthesizedExpression(list))) list = list.expression;
+        if (!list || !ts.isArrayLiteralExpression(list)) return null;
+        return list.elements.filter(ts.isStringLiteralLike).map(({ text }) => text);
+      }
+    return null;
+  }
+}

package/lint/__fixtures__/no-oversized-list-limit/bad.tsx

@@ -0,0 +1,18 @@
+export const everyCourt = () => fetch.courtListInPublic(0, 10000); // @flag
+export const devicesOfOrg = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 1000); // @flag
+export const sortedDevices = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 1000, "latest"); // @flag
+export const withPolicy = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 1000, null, { crystalize: false }); // @flag
+export const rootList = () => fetch.deviceList(null, 501); // @flag
+export const separated = () => fetch.deviceList(undefined, 10_000); // @flag
+export const exponent = () => fetch.deviceList(0, 1e4); // @flag
+export const namedSkip = (orgId: string, skip: number) => fetch.alertListInOrg(orgId, skip, 2000); // @flag
+export const pagedSkip = (orgId: string, page: number) => fetch.alertListInOrg(orgId, (page - 1) * 20, 2000); // @flag
+export const afterSliceNumbers = () => fetch.statListInYear(2026, 0, 600); // @flag
+export const initInRoute = (orgId: string) => fetch.initDeviceInOrg(orgId, { limit: 1000 }); // @flag
+export const initRoot = () => fetch.initDevice({ sort: "latest", limit: 9999 }); // @flag
+export const getInit = (orgId: string) => fetch.getDeviceInitInOrg(orgId, { limit: 1000 }); // @flag
+export const storeInit = (orgId: string) => st.do.initDeviceInOrg(orgId, { limit: 1000 }); // @flag
+export const storeRefresh = () => st.do.refreshDeviceInOrg({ limit: 1000 }); // @flag
+export const quotedKey = (orgId: string) => st.do.initDeviceInOrg(orgId, { "limit": 1000 }); // @flag
+export const storeSetLimit = () => st.do.setLimitOfDeviceInOrg(1000); // @flag
+export const Monitor = () => <button type="button" onClick={() => st.do.setLimitOfAlertInOrg(5000)}>All</button>; // @flag

package/lint/__fixtures__/no-oversized-list-limit/good.tsx

@@ -0,0 +1,23 @@
+export const atTheCap = () => fetch.courtListInPublic(0, 500); // @ok
+export const onePage = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 20, "latest"); // @ok
+export const variableLimit = (orgId: string, limit: number) => fetch.deviceListInOrg(orgId, 0, limit); // @ok
+export const everyRowMode = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 0); // @ok
+export const yearSlice = () => fetch.statListInYear(2026); // @ok
+export const yearAfterId = (orgId: string) => fetch.statListInOrgYear(orgId, 2026); // @ok
+export const monthAndYear = () => fetch.statListInMonthOfYear(11, 2026); // @ok
+export const twoYears = () => fetch.statListInRange(2025, 2026); // @ok
+export const numbersBeforePaging = () => fetch.statListInRange(0, 2026, 0, 20); // @ok
+export const numbersWithoutPaging = () => fetch.statListInRange(0, 2026, 0); // @ok
+export const notAList = () => fetch.device(0, 1000); // @ok
+export const notFetch = () => api.deviceList(0, 1000); // @ok
+export const lowercaseList = () => fetch.checklist(0, 1000); // @ok
+export const initAtTheCap = (orgId: string) => fetch.initDeviceInOrg(orgId, { limit: 500 }); // @ok
+export const rateLimit = (orgId: string) => fetch.initDeviceInOrg(orgId, { rateLimit: 1000 }); // @ok
+export const nestedLimit = (orgId: string) => fetch.initDeviceInOrg(orgId, { default: { limit: 1000 } }); // @ok
+export const mutationLimit = (id: string) => fetch.updateQuota(id, { limit: 1000 }); // @ok
+export const storeWrite = () => st.do.setLimitOnQuota(1000); // @ok
+export const storeSetSmallLimit = () => st.do.setLimitOfDeviceInOrg(100); // @ok
+export const storeSetPage = () => st.do.setPageOfDeviceInOrg(1000); // @ok
+export const policyOnList = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 20, "latest", { limit: 1000 }); // @ok
+export const Docs = () => <code>fetch.courtListInPublic(0, 10000)</code>; // @ok
+export const sample = "fetch.courtListInPublic(0, 10000)"; // @ok