@akanjs/devkit 3.1.1-rc.9 → 3.1.1

package/conventionSet.ts

@@ -0,0 +1,67 @@
+import fsPromise from "node:fs/promises";
+import path from "node:path";
+
+export interface ConventionRule {
+  name: string;
+  description: string;
+  paths: string[];
+  body: string;
+}
+
+export class ConventionSet {
+  constructor(
+    readonly core: string,
+    readonly rules: ConventionRule[],
+  ) {}
+
+  static async load(dir: string) {
+    const core = await fsPromise.readFile(path.join(dir, "core.md"), "utf-8");
+    const files = (await fsPromise.readdir(path.join(dir, "rules"))).filter((file) => file.endsWith(".md")).sort();
+    const rules = await Promise.all(
+      files.map(async (file) =>
+        ConventionSet.parseRule(file.slice(0, -3), await fsPromise.readFile(path.join(dir, "rules", file), "utf-8")),
+      ),
+    );
+    return new ConventionSet(core.trim(), rules);
+  }
+
+  static parseRule(name: string, text: string): ConventionRule {
+    const match: RegExpExecArray | null = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    if (!match) throw new Error(`Convention rule ${name} has no frontmatter`);
+    const front = match[1] ?? "";
+    const described: RegExpExecArray | null = /^description:\s*(.+)$/m.exec(front);
+    const description = described?.[1]?.trim() ?? "";
+    const paths = [...front.matchAll(/^\s+-\s+"([^"]+)"$/gm)].map((entry) => entry[1] ?? "");
+    if (!description || paths.length === 0) throw new Error(`Convention rule ${name} needs a description and paths`);
+    return { name, description, paths, body: text.slice(match[0].length).trim() };
+  }
+
+  //? Cursor splits `globs:` on commas, so a `{a,b}` brace list has to be expanded before it is written there.
+  static expand(glob: string): string[] {
+    const open = glob.indexOf("{");
+    if (open === -1) return [glob];
+    const close = glob.indexOf("}", open);
+    if (close === -1) return [glob];
+    const head = glob.slice(0, open);
+    const tail = glob.slice(close + 1);
+    return glob
+      .slice(open + 1, close)
+      .split(",")
+      .flatMap((choice) => ConventionSet.expand(`${head}${choice}${tail}`));
+  }
+
+  static demote(markdown: string) {
+    let fenced = false;
+    return markdown
+      .split("\n")
+      .map((line) => {
+        if (line.startsWith("```")) fenced = !fenced;
+        return !fenced && /^#{1,5} /.test(line) ? `#${line}` : line;
+      })
+      .join("\n");
+  }
+
+  get instruction() {
+    return `${[this.core, ...this.rules.map((rule) => ConventionSet.demote(rule.body))].join("\n\n")}\n`;
+  }
+}

package/csrE2e/ssrRegistry.e2e.test.ts

@@ -61,7 +61,12 @@ describe.skipIf(!CsrE2eHarness.enabled)("SSR dev registry (minimal)", () => {
   let ssr: CsrE2eHarness;
 
   beforeAll(async () => {
-    ssr = await CsrE2eHarness.start({ app: "minimal", port, env: { AKAN_DEV_SSR_ARM_DELAY_MS: "3000" } });
+    ssr = await CsrE2eHarness.start({
+      app: "minimal",
+      port,
+      // The server-log assertions match verbose-level lines, which a workspace `.env` may or may not turn on.
+      env: { AKAN_DEV_SSR_ARM_DELAY_MS: "3000", AKAN_PUBLIC_LOG_LEVEL: "verbose" },
+    });
   }, 240_000);
 
   afterAll(async () => {

package/deprecatedCommentScanner.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { DeprecatedCommentScanner } from "./deprecatedCommentScanner";
+import type { SourceFileInfo } from "./qualityScanner";
+
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/repo/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS),
+});
+
+const scan = (file: string, lines: string[]) =>
+  new DeprecatedCommentScanner().scan([fileOf(file, `${lines.join("\n")}\n`)]);
+
+describe("DeprecatedCommentScanner", () => {
+  test("flags a trailing, a leading and a block deprecated comment", () => {
+    const warnings = scan("apps/demo/lib/court/court.constant.ts", [
+      "export class CourtInput extends via((field) => ({",
+      "  legacyVenue: field(String).optional(), // deprecated",
+      "  // Deprecated: use courtId",
+      "  legacyCourt: field(String).optional(),",
+      "  /* DEPRECATED */ oldName: field(String).optional(),",
+      "  /** deprecated, read venueId */ oldVenue: field(String).optional(),",
+      "})) {}",
+    ]);
+
+    expect(warnings.map((warning) => warning.line)).toEqual([2, 3, 5, 6]);
+    expect(warnings[0]).toMatchObject({ rule: "akan.comment.deprecated-marker", scope: "comment" });
+    expect(warnings[0]?.message).toContain('"// deprecated"');
+  });
+
+  test("leaves a JSDoc @deprecated tag and prose that only mentions deprecation", () => {
+    expect(
+      scan("libs/demo/ui/field.type.ts", [
+        "export interface FieldProps {",
+        "  /** @deprecated Ignored: the field renders `value`. */",
+        "  defaultValue?: string;",
+        "  /**",
+        "   * Old name.",
+        "   * @deprecated use `value`",
+        "   */",
+        "  initial?: string;",
+        "}",
+        "// Replaces the deprecated upstream plugin.",
+        "export const notice = '// deprecated';",
+      ]),
+    ).toEqual([]);
+  });
+
+  test("stays out of tests", () => {
+    expect(scan("apps/demo/lib/court/court.signal.test.ts", ["const venue = 1; // deprecated"])).toEqual([]);
+  });
+});

package/deprecatedCommentScanner.ts

@@ -0,0 +1,30 @@
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+import { type SourceComment, SourceComments } from "./sourceComments";
+
+export class DeprecatedCommentScanner {
+  static readonly rule = "akan.comment.deprecated-marker";
+  static #marker = /^[!?*\s]*(?:(?:TODO|FIXME|XXX|NOTE)\b\s*:?\s*)?@?deprecated\b/i;
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    return sourceFiles
+      .filter(({ file }) => /^(apps|libs)\//.test(file) && !/\.(test|spec)\.tsx?$/.test(file))
+      .flatMap(({ file, sourceFile }) =>
+        SourceComments.of(sourceFile)
+          .filter((comment) => DeprecatedCommentScanner.#isLooseMarker(comment))
+          .map((comment) => ({
+            rule: DeprecatedCommentScanner.rule,
+            scope: "comment" as const,
+            severity: "warning" as const,
+            file,
+            line: comment.line,
+            message: `"${comment.raw.split(/\r?\n/)[0]?.trim().slice(0, 80)}" marks nothing at the use sites; editors strike through only a JSDoc @deprecated tag.`,
+          })),
+      );
+  }
+
+  static #isLooseMarker({ isJsDoc, body }: SourceComment) {
+    const text = body.filter((line) => line !== "").join(" ");
+    if (isJsDoc && /(^|\s)@deprecated\b/.test(text)) return false;
+    return DeprecatedCommentScanner.#marker.test(text);
+  }
+}

package/endpointReach.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { EndpointReach } from "./endpointReach";
+
+const fileOf = (file: string, content: string) => ({
+  file,
+  sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true),
+});
+
+describe("EndpointReach", () => {
+  test("follows an endpoint or a slice through its service's own and other services' methods, not a job", () => {
+    const reach = new EndpointReach(
+      [
+        fileOf(
+          "apps/demo/lib/court/court.signal.ts",
+          `export class CourtInternal extends internal(srv.court, ({ cron }) => ({
+  sweep: cron("0 * * * *").exec(function () { return this.courtService.sweep(); }),
+})) {}
+export class CourtSlice extends slice(srv.court, { guards: { root: Admin } }, (init) => ({
+  inOrg: init().exec(function (orgId) { return this.courtService.queryInOrg(orgId); }),
+})) {}
+export class CourtEndpoint extends endpoint(srv.court, ({ mutation }) => ({
+  assign: mutation(Boolean).exec(function (id) { return this.courtService.assign(id); }),
+})) {}
+`,
+        ),
+      ],
+      [
+        fileOf(
+          "apps/demo/lib/court/court.service.ts",
+          `export class CourtService extends serve(db.court, () => ({})) {
+  queryInOrg(orgId: string) { return { orgId }; }
+  async assign(id: string) { return await this.#pick(id); }
+  async #pick(id: string) { return await this.pcService.claim(id); }
+  async sweep() { return await this.#pick("all"); }
+}
+`,
+        ),
+        fileOf(
+          "libs/shared/lib/_pc/pc.service.ts",
+          `export class PcService extends serve("pc", () => ({})) {
+  async claim(id: string) { return id; }
+  async release(id: string) { return id; }
+}
+`,
+        ),
+      ],
+    );
+
+    expect(EndpointReach.serviceOf("libs/shared/lib/_pc/pc.service.ts")).toBe("pc");
+    expect(
+      ["court.queryInOrg", "court.assign", "court.#pick", "pc.claim", "court.sweep", "pc.release"].map((key) => {
+        const [service = "", method = ""] = key.split(".");
+        return reach.reaches(service, method);
+      }),
+    ).toEqual([true, true, true, true, false, false]);
+  });
+});

package/endpointReach.ts

@@ -0,0 +1,80 @@
+import path from "node:path";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+
+type ServiceMethod = [service: string, method: string];
+
+//? Only `endpoint(…)` and `slice(…)` answer a caller who waits; an `internal(…)` job (cron, interval, queue) works
+//? per item on purpose, so that one failing item leaves the rest done.
+export class EndpointReach {
+  static readonly #requestBuilders = new Set(["endpoint", "slice"]);
+  readonly #reached = new Set<string>();
+
+  constructor(
+    signalFiles: Pick<SourceFileInfo, "sourceFile">[],
+    serviceFiles: Pick<SourceFileInfo, "file" | "sourceFile">[],
+  ) {
+    const methodsByService = new Map<string, Map<string, ts.MethodDeclaration>>();
+    for (const { file, sourceFile } of serviceFiles) {
+      const methods = methodsByService.get(EndpointReach.serviceOf(file)) ?? new Map<string, ts.MethodDeclaration>();
+      for (const cls of sourceFile.statements.filter(ts.isClassDeclaration))
+        for (const member of cls.members)
+          if (
+            ts.isMethodDeclaration(member) &&
+            member.body &&
+            (ts.isIdentifier(member.name) || ts.isPrivateIdentifier(member.name))
+          )
+            methods.set(member.name.text, member);
+      methodsByService.set(EndpointReach.serviceOf(file), methods);
+    }
+    const pending: ServiceMethod[] = [];
+    const reach = ([service, method]: ServiceMethod) => {
+      const key = `${service}.${method}`;
+      if (this.#reached.has(key) || !methodsByService.get(service)?.has(method)) return;
+      this.#reached.add(key);
+      pending.push([service, method]);
+    };
+    for (const { sourceFile } of signalFiles)
+      for (const cls of sourceFile.statements.filter(ts.isClassDeclaration)) {
+        const base = cls.heritageClauses?.[0]?.types[0]?.expression;
+        if (
+          base &&
+          ts.isCallExpression(base) &&
+          ts.isIdentifier(base.expression) &&
+          EndpointReach.#requestBuilders.has(base.expression.text)
+        )
+          EndpointReach.#serviceCallsIn(base, null).forEach(reach);
+      }
+    for (let next = pending.pop(); next; next = pending.pop()) {
+      const [service, method] = next;
+      const declaration = methodsByService.get(service)?.get(method);
+      if (declaration) EndpointReach.#serviceCallsIn(declaration, service).forEach(reach);
+    }
+  }
+
+  static serviceOf(file: string) {
+    return path.posix.basename(file).replace(/\.service\.ts$/, "");
+  }
+
+  reaches(service: string, method: string) {
+    return this.#reached.has(`${service}.${method}`);
+  }
+
+  static #serviceCallsIn(node: ts.Node, ownService: string | null) {
+    const calls: ServiceMethod[] = [];
+    const visit = (child: ts.Node) => {
+      if (ts.isCallExpression(child) && ts.isPropertyAccessExpression(child.expression)) {
+        const { expression: owner, name } = child.expression;
+        if (owner.kind === ts.SyntaxKind.ThisKeyword && ownService) calls.push([ownService, name.text]);
+        else if (ts.isPropertyAccessExpression(owner) && owner.expression.kind === ts.SyntaxKind.ThisKeyword) {
+          const field = owner.name.text;
+          if (field.length > "Service".length && field.endsWith("Service"))
+            calls.push([field.slice(0, -"Service".length), name.text]);
+        }
+      }
+      ts.forEachChild(child, visit);
+    };
+    visit(node);
+    return calls;
+  }
+}

package/executors.test.ts

@@ -275,10 +275,6 @@ describe("Executor filesystem helpers", () => {
       "Akan workspace agent guide",
     );
     expect(await readFile(path.join(root, "workspace/AGENTS.md"), "utf8")).toContain("sample Agent Guide");
-    expect(await readFile(path.join(root, "workspace/docs/AI-DEVELOPMENT.md"), "utf8")).toContain(
-      "AI Development Guide",
-    );
-    expect(await readFile(path.join(root, "workspace/docs/GENERATED.md"), "utf8")).toContain("Generated Akan Files");
     // Rules live in the package's base config, so a framework release reaches an existing workspace on `bun update`.
     expect(await readFile(path.join(root, "workspace/biome.json"), "utf8")).toContain(
       '"extends": ["@akanjs/devkit/biome.base.json"]',

package/executors.ts

@@ -49,6 +49,7 @@ import { JsonFormatter } from "./jsonFormatter";
 import { Linter } from "./linter";
 import { ManifestDependencies } from "./manifestDependencies";
 import { resolveRepoName } from "./repoIdentity";
+import type { RouteSourceInfo } from "./routeSourceValidator";
 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.
@@ -66,6 +67,12 @@ export interface PageRoot {
   keyPrefix: string;
 }
 
+export interface AppRouteSource {
+  key: string;
+  absPath: string;
+  info: RouteSourceInfo;
+}
+
 export interface WrittenFileContent extends FileContent {
   written: boolean;
 }
@@ -557,8 +564,8 @@ export class Executor {
     return fileContents;
   }
 
-  // A template cannot sort the identifiers it emits (`Task` vs `Zoo`). Best-effort: `create-akan-workspace`
-  // scaffolds before `bun install`, with no local Biome binary yet.
+  // Best-effort: `create-akan-workspace` scaffolds before `bun install`, with no local Biome binary yet, so a
+  // template emits Biome's form itself (`templates/biomeForm.ts`).
   async #formatAppliedTemplate(fileContents: FileContent[]) {
     const filePaths = fileContents
       .map((fileContent) => fileContent.filePath)
@@ -1278,6 +1285,7 @@ export class AppExecutor extends SysExecutor {
   }
 
   #pageKeys: string[] | null = null;
+  #routeSources: AppRouteSource[] = [];
   #excludeDevOnlyPages = false;
   async getPageKeys({ refresh }: { refresh?: boolean } = {}): Promise<string[]> {
     if (this.#pageKeys && !refresh) return this.#pageKeys;
@@ -1288,6 +1296,7 @@ export class AppExecutor extends SysExecutor {
     const devOnlyKeys = new Set<string>();
     const devOnlyDirs: string[] = [];
     const pageRoots = await this.getPageRoots();
+    const routeSources: AppRouteSource[] = [];
     const libKeyPrefixes = pageRoots.map((root) => root.keyPrefix).filter(Boolean);
     for (const root of pageRoots) {
       if (!(await FileSys.dirExists(root.dir))) continue;
@@ -1333,6 +1342,7 @@ export class AppExecutor extends SysExecutor {
             rootLayout: isRootLayout,
             pattern: parsed.pattern,
           });
+          routeSources.push({ key, absPath, info });
           if (info.devOnly) {
             devOnlyKeys.add(key);
             //* A dev-only layout takes its whole subtree, or its pages would ship without their chrome.
@@ -1343,9 +1353,15 @@ export class AppExecutor extends SysExecutor {
       }
     }
     pageKeys.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    this.#routeSources = routeSources.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
     this.#pageKeys = this.#excludeDevOnlyPages ? this.#dropDevOnlyPages(pageKeys, devOnlyKeys, devOnlyDirs) : pageKeys;
     return this.#pageKeys;
   }
+  /** Each page and layout file `getPageKeys` read, with what its chain declares; overrides files are not listed. */
+  async getRouteSources({ refresh }: { refresh?: boolean } = {}): Promise<AppRouteSource[]> {
+    await this.getPageKeys({ refresh });
+    return this.#routeSources;
+  }
   #dropDevOnlyPages(pageKeys: string[], devOnlyKeys: Set<string>, devOnlyDirs: string[]): string[] {
     if (!devOnlyKeys.size) return pageKeys;
     const isDevOnly = (key: string) => devOnlyKeys.has(key) || devOnlyDirs.some((dir) => key.startsWith(dir));

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/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.',
+      },
+    ]);
+  });
+});