@akanjs/devkit 3.1.1-rc.15 → 3.1.1-rc.17

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

package/lint/no-oversized-list-limit.grit

@@ -0,0 +1,73 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// A client list request takes at most MAX_PAGE_SIZE (500) rows: SignalResolver.#clientPageLimit
+// (pkgs/akanjs/server/resolver/signal.resolver.ts) clamps a larger limit and answers with 500 rows and no
+// error, so a screen that asked for 10000 silently stops at row 500. A store list reads hasMoreOf<Model><Suffix>
+// as true after a full 500, so only a screen that calls loadMoreOf<Model><Suffix> ever sees the rest. The server
+// logs one warning per list; this rule moves it to the line that asked.
+//
+// Matched: a literal limit above 500 in the generated list fetch, `fetch.<model>List<Suffix>(...sliceArgs,
+// skip, limit, sort?, fetchPolicy?)`; as `limit:` in the option object of `fetch.init<Model><Suffix>`,
+// `fetch.get<Model>Init<Suffix>`, `st.do.init<Model><Suffix>` and `st.do.refresh<Model><Suffix>`; and as the
+// argument of `st.do.setLimitOf<Model><Suffix>`.
+//
+// A rule cannot know a slice's arity, so the positional limit is found by shape: an argument that reads as a
+// skip (`0`, `null`, `undefined`, a name with skip/offset, a page multiplied out) directly before the literal,
+// and after it nothing but a non-numeric sort and a fetch policy. That keeps a numeric slice argument out
+// (`fetch.statListInYear(2026)`, `fetch.statListInMonth(11, 2026)`), as it does a variable limit, `limit: 0`
+// (the store's one-page mode, which the server warns about itself) and a `limit:` key anywhere else (rate
+// limits). Left over: a slice whose own last two arguments read as `(0, 1000)`, such as a price range; suppress
+// that one with `// biome-ignore lint/plugin: <reason>`.
+pattern over_max_page_size() {
+  JsNumberLiteralExpression() as $size where {
+    $size <: r"(?:50[1-9]|5[1-9][0-9]|[6-9][0-9]{2}|[1-9][0-9]{0,2}(?:_?[0-9]{3})+|[1-9]e\+?(?:[3-9]|[1-9][0-9]+))"
+  }
+}
+
+pattern page_skip() {
+  or { r"(?:0|null|undefined)", r"(?i)[\s\S]*(?:skip|offset)[\s\S]*", r"(?i)[\s\S]*page[\s\S]*\*[\s\S]*" }
+}
+
+pattern page_sort() {
+  not JsNumberLiteralExpression()
+}
+
+JsCallExpression(callee = $callee, arguments = JsCallArguments(args = $args)) where {
+  or {
+    and {
+      $callee <: `fetch.$endpoint`,
+      $endpoint <: r"[a-z][A-Za-z0-9_$]*List(?:[A-Z][A-Za-z0-9_$]*)?",
+      $args <: or {
+        [..., page_skip(), over_max_page_size() as $limit],
+        [..., page_skip(), over_max_page_size() as $limit, page_sort()],
+        [..., page_skip(), over_max_page_size() as $limit, page_sort(), $_]
+      }
+    },
+    and {
+      or {
+        and {
+          $callee <: `fetch.$endpoint`,
+          $endpoint <: or { r"init[A-Z][A-Za-z0-9_$]*", r"get[A-Z][A-Za-z0-9_$]*Init(?:[A-Z][A-Za-z0-9_$]*)?" }
+        },
+        and { $callee <: `st.do.$action`, $action <: r"(?:init|refresh)[A-Z][A-Za-z0-9_$]*" }
+      },
+      $args <: some JsObjectExpression(
+        members = some JsPropertyObjectMember(
+          name = r"(?:limit|\x22limit\x22|'limit')",
+          value = over_max_page_size() as $limit
+        )
+      )
+    },
+    and {
+      $callee <: `st.do.$action`,
+      $action <: r"setLimitOf[A-Z][A-Za-z0-9_$]*",
+      $args <: [over_max_page_size() as $limit, ...]
+    }
+  },
+  register_diagnostic(
+    span = $limit,
+    message = "The server serves at most 500 rows per list request and drops the rest without an error, so this list silently stops at row 500. Page through it at 500 or fewer per request (skip/limit, or st.do.loadMoreOf<Model><Suffix>() while hasMoreOf<Model><Suffix>), or compute what the screen needs on the server in an insight or a dedicated endpoint.",
+    severity = "error"
+  )
+}

package/maintainabilityBaseline.test.ts

@@ -0,0 +1,280 @@
+import { describe, expect, test } from "bun:test";
+import { MaintainabilityBaseline } from "./maintainabilityBaseline";
+import { type DebtRuleId, MaintainabilityContract, type MaintainabilityViolation } from "./maintainabilityContract";
+
+const sizeOf = (key: string, lineCount: number): MaintainabilityViolation => ({
+  kind: "size",
+  rule: key.includes("#") ? "akan.size.component" : "akan.size.file",
+  key,
+  file: key.split("#")[0] ?? key,
+  line: 1,
+  lineCount,
+  maxLines: 400,
+});
+const writeOf = (key: string, writeCount = 2): MaintainabilityViolation => ({
+  kind: "multiWrite",
+  rule: "akan.store.multi-write",
+  key,
+  file: key.split("#")[0] ?? key,
+  line: 1,
+  owner: key.split("#")[1] ?? "",
+  writes: [],
+  writeCount,
+});
+const accessOf = (key: string, accessCount: number): MaintainabilityViolation => ({
+  kind: "storeAccess",
+  rule: "akan.component.store-access",
+  key,
+  file: key.split("#")[0] ?? key,
+  line: 1,
+  component: key.split("#")[1] ?? "",
+  accessCount,
+  maxAccesses: 16,
+});
+const placementOf = (file: string, writes: string[]): MaintainabilityViolation => ({
+  kind: "writePlacement",
+  rule: "akan.write.placement",
+  key: file,
+  file,
+  line: 1,
+  writes,
+});
+const baselineOf = (
+  sections: { [rule in DebtRuleId]?: Record<string, number> },
+  reasons: Record<string, string> = {},
+) =>
+  new MaintainabilityBaseline(
+    new Map(Object.entries(sections).map(([rule, counts]) => [rule as DebtRuleId, new Map(Object.entries(counts))])),
+    new Map(Object.entries(reasons)),
+  );
+
+describe("MaintainabilityBaseline", () => {
+  test("keeps one section per rule the gate can fail, the growth check aside", () => {
+    expect(new Set(MaintainabilityBaseline.debtRules)).toEqual(
+      new Set(MaintainabilityContract.ruleIds.filter((rule) => rule !== "akan.baseline.growth")),
+    );
+  });
+
+  test("allows a recorded entry up to its count, writes included, and nothing it does not record", () => {
+    const baseline = MaintainabilityBaseline.parse(
+      JSON.stringify({
+        "akan.size.file": { "lib/a/A.Zone.tsx": 900 },
+        "akan.store.multi-write": { "lib/a/a.store.ts#run": 2 },
+        "akan.write.placement": { "ui/Board.tsx": 1 },
+      }),
+    );
+    expect(baseline.allows(sizeOf("lib/a/A.Zone.tsx", 900))).toBe(true);
+    expect(baseline.allows(sizeOf("lib/a/A.Zone.tsx", 901))).toBe(false);
+    expect(baseline.allows(sizeOf("lib/b/B.Zone.tsx", 401))).toBe(false);
+    expect(baseline.allows(writeOf("lib/a/a.store.ts#run"))).toBe(true);
+    expect(baseline.allows(writeOf("lib/a/a.store.ts#run", 3))).toBe(false);
+    expect(baseline.allows(writeOf("lib/a/a.store.ts#other"))).toBe(false);
+    expect(baseline.allows(placementOf("ui/Board.tsx", ["st.do.removeBoard"]))).toBe(true);
+    expect(baseline.allows(placementOf("ui/Board.tsx", ["st.do.removeBoard", "fetch.placeBoard"]))).toBe(false);
+  });
+
+  test("records the busiest of several breaches under one key", () => {
+    const chainOf = (writeCount: number): MaintainabilityViolation => ({
+      kind: "multiWrite",
+      rule: "akan.component.write-chain",
+      key: "lib/a/A.Zone.tsx#Canvas",
+      file: "lib/a/A.Zone.tsx",
+      line: 1,
+      owner: "Canvas",
+      writes: [],
+      writeCount,
+    });
+    const baseline = MaintainabilityBaseline.of([chainOf(2), chainOf(4)]);
+    expect([...(baseline.sections.get("akan.component.write-chain") ?? [])]).toEqual([["lib/a/A.Zone.tsx#Canvas", 4]]);
+  });
+
+  test("tightens to what still breaks: lowers a shrunk entry, keeps a grown one, drops the rest", () => {
+    const baseline = baselineOf({
+      "akan.size.file": { "lib/a/A.Zone.tsx": 900, "lib/b/B.Zone.tsx": 700, "lib/gone/Gone.Zone.tsx": 600 },
+      "akan.store.multi-write": { "lib/a/a.store.ts#run": 3, "lib/a/a.store.ts#fixed": 2 },
+    });
+    const tightened = baseline.tightenedBy([
+      sizeOf("lib/a/A.Zone.tsx", 850),
+      sizeOf("lib/b/B.Zone.tsx", 720),
+      sizeOf("lib/c/C.Zone.tsx", 500),
+      writeOf("lib/a/a.store.ts#run", 2),
+    ]);
+    expect([...(tightened.sections.get("akan.size.file") ?? [])]).toEqual([
+      ["lib/a/A.Zone.tsx", 850],
+      ["lib/b/B.Zone.tsx", 700],
+    ]);
+    expect([...(tightened.sections.get("akan.store.multi-write") ?? [])]).toEqual([["lib/a/a.store.ts#run", 2]]);
+    expect(baseline.tightenedBy([]).isEmpty).toBe(true);
+  });
+
+  test("names every entry a working baseline added or raised over the reference one, per rule", () => {
+    const committed = baselineOf({
+      "akan.size.file": { "lib/a/A.Zone.tsx": 900 },
+      "akan.store.multi-write": { "a.store.ts#run": 2 },
+    });
+    const working = baselineOf({
+      "akan.size.file": { "lib/a/A.Zone.tsx": 950, "lib/b/B.Zone.tsx": 500 },
+      "akan.store.multi-write": { "a.store.ts#run": 3, "a.store.ts#sneak": 2 },
+    });
+    expect(working.grownFrom(committed)).toEqual([
+      { rule: "akan.size.file", key: "lib/a/A.Zone.tsx", count: 950, committed: 900 },
+      { rule: "akan.size.file", key: "lib/b/B.Zone.tsx", count: 500, committed: undefined },
+      { rule: "akan.store.multi-write", key: "a.store.ts#run", count: 3, committed: 2 },
+      { rule: "akan.store.multi-write", key: "a.store.ts#sneak", count: 2, committed: undefined },
+    ]);
+    expect(committed.tightenedBy([sizeOf("lib/a/A.Zone.tsx", 800)]).grownFrom(committed)).toEqual([]);
+  });
+
+  test("ratchets a component's store accesses like a size: allows up to its entry, lowers it, refuses a raise", () => {
+    const baseline = MaintainabilityBaseline.parse(
+      JSON.stringify({
+        "akan.component.store-access": { "lib/a/A.Zone.tsx#Canvas": 40, "lib/gone/G.Zone.tsx#Old": 30 },
+      }),
+    );
+    expect(baseline.allows(accessOf("lib/a/A.Zone.tsx#Canvas", 40))).toBe(true);
+    expect(baseline.allows(accessOf("lib/a/A.Zone.tsx#Canvas", 41))).toBe(false);
+    expect(baseline.allows(accessOf("lib/b/B.Zone.tsx#Board", 17))).toBe(false);
+    expect(baseline.recordedOf(accessOf("lib/a/A.Zone.tsx#Canvas", 41))).toBe(40);
+
+    const tightened = baseline.tightenedBy([accessOf("lib/a/A.Zone.tsx#Canvas", 33)]);
+    expect([...(tightened.sections.get("akan.component.store-access") ?? [])]).toEqual([
+      ["lib/a/A.Zone.tsx#Canvas", 33],
+    ]);
+    expect(baseline.grownFrom(tightened)).toEqual([
+      { rule: "akan.component.store-access", key: "lib/a/A.Zone.tsx#Canvas", count: 40, committed: 33 },
+      { rule: "akan.component.store-access", key: "lib/gone/G.Zone.tsx#Old", count: 30, committed: undefined },
+    ]);
+    expect(tightened.grownFrom(baseline)).toEqual([]);
+  });
+
+  test("lets a shape entry grow only with a reason of ten non-space characters, a write entry never", () => {
+    const committed = baselineOf({
+      "akan.size.file": { "lib/a/A.Zone.tsx": 900 },
+      "akan.store.multi-write": { "a.store.ts#run": 2 },
+    });
+    const reason = "The canvas is one pointer state machine.";
+    const working = baselineOf(
+      {
+        "akan.size.file": { "lib/a/A.Zone.tsx": 950, "ui/Board.tsx": 450, "lib/b/B.Zone.tsx": 500 },
+        "akan.size.component": { "lib/c/C.Zone.tsx#Grid": 300 },
+        "akan.component.store-access": { "lib/d/D.Zone.tsx#Canvas": 30 },
+        "akan.store.multi-write": { "a.store.ts#run": 2, "a.store.ts#sneak": 2 },
+        "akan.component.write-chain": { "lib/c/C.Zone.tsx#Grid": 2 },
+        "akan.write.placement": { "ui/Board.tsx": 1 },
+        "akan.service.call-in-loop": { "lib/e/e.service.ts#sync": 1 },
+      },
+      {
+        "lib/a/A.Zone.tsx": reason,
+        "ui/Board.tsx": reason,
+        "lib/b/B.Zone.tsx": "a b c d e f g h i",
+        "lib/c/C.Zone.tsx#Grid": reason,
+        "lib/d/D.Zone.tsx#Canvas": reason,
+        "a.store.ts#sneak": reason,
+        "lib/e/e.service.ts#sync": reason,
+      },
+    );
+
+    expect(working.grownFrom(committed)).toEqual([
+      { rule: "akan.size.file", key: "lib/b/B.Zone.tsx", count: 500, committed: undefined },
+      { rule: "akan.store.multi-write", key: "a.store.ts#sneak", count: 2, committed: undefined },
+      { rule: "akan.component.write-chain", key: "lib/c/C.Zone.tsx#Grid", count: 2, committed: undefined },
+      { rule: "akan.write.placement", key: "ui/Board.tsx", count: 1, committed: undefined },
+    ]);
+    expect(working.reasonOf("lib/b/B.Zone.tsx")).toBeUndefined();
+    expect(working.reasonOf("a.store.ts#sneak")).toBeUndefined();
+    expect(working.reasonOf("lib/d/D.Zone.tsx#Canvas")).toBe(reason);
+    expect(working.reasonOf("lib/e/e.service.ts#sync")).toBe(reason);
+  });
+
+  test("keeps a reason only beside a shape entry it still describes", () => {
+    const reason = "The canvas is one pointer state machine.";
+    const baseline = baselineOf(
+      {
+        "akan.size.file": { "lib/a/A.Zone.tsx": 900, "lib/gone/Gone.Zone.tsx": 600 },
+        "akan.component.store-access": { "lib/a/A.Zone.tsx#Canvas": 30 },
+        "akan.store.multi-write": { "lib/a/a.store.ts#run": 2 },
+      },
+      {
+        "lib/a/A.Zone.tsx": reason,
+        "lib/gone/Gone.Zone.tsx": reason,
+        "lib/a/A.Zone.tsx#Canvas": reason,
+        "lib/a/a.store.ts#run": reason,
+        "lib/never/Recorded.tsx": reason,
+      },
+    );
+
+    const tightened = baseline.tightenedBy([
+      sizeOf("lib/a/A.Zone.tsx", 850),
+      accessOf("lib/a/A.Zone.tsx#Canvas", 20),
+      writeOf("lib/a/a.store.ts#run"),
+    ]);
+
+    expect([...(tightened.sections.get("akan.size.file") ?? [])]).toEqual([["lib/a/A.Zone.tsx", 850]]);
+    expect([...tightened.reasons]).toEqual([
+      ["lib/a/A.Zone.tsx", reason],
+      ["lib/a/A.Zone.tsx#Canvas", reason],
+    ]);
+    expect(baseline.tightenedBy([]).reasons.size).toBe(0);
+  });
+
+  test("prints the rule sections in rule order with sorted keys, as Biome would, and reprints them unchanged", () => {
+    const baseline = MaintainabilityBaseline.of([
+      writeOf("lib/z/z.store.ts#run"),
+      sizeOf("lib/court/Court.Zone.tsx#Canvas", 640),
+      sizeOf("lib/court/Court.Zone.tsx", 947),
+      writeOf("lib/court/court.store.ts#assignCourtPcOnCourt", 3),
+      placementOf("ui/Board.tsx", ["st.do.removeBoard"]),
+    ]);
+    const text = baseline.stringify();
+    expect(text).toBe(`{
+  "akan.size.file": {
+    "lib/court/Court.Zone.tsx": 947
+  },
+  "akan.size.component": {
+    "lib/court/Court.Zone.tsx#Canvas": 640
+  },
+  "akan.store.multi-write": {
+    "lib/court/court.store.ts#assignCourtPcOnCourt": 3,
+    "lib/z/z.store.ts#run": 2
+  },
+  "akan.write.placement": {
+    "ui/Board.tsx": 1
+  }
+}
+`);
+    expect(MaintainabilityBaseline.parse(text).stringify()).toBe(text);
+  });
+
+  test("prints the reasons last and only once there are some, reprinting them unchanged", () => {
+    const text = `{
+  "akan.size.file": {
+    "lib/a/A.Zone.tsx": 950,
+    "ui/Board.tsx": 450
+  },
+  "reasons": {
+    "lib/a/A.Zone.tsx": "The canvas is one pointer state machine.",
+    "ui/Board.tsx": "Generated SVG path table for the court layout."
+  }
+}
+`;
+    const reasonless = '{\n  "akan.size.file": {\n    "lib/a/A.Zone.tsx": 950\n  }\n}\n';
+
+    expect(MaintainabilityBaseline.parse(text).stringify()).toBe(text);
+    expect(MaintainabilityBaseline.parse(reasonless).stringify()).toBe(reasonless);
+    expect(MaintainabilityBaseline.parse('{ "reasons": {} }').stringify()).not.toContain("reasons");
+  });
+
+  test("refuses a file that is not the baseline shape, naming it", () => {
+    expect(() => MaintainabilityBaseline.parse("{", "apps/demo/akan.baseline.json")).toThrow(
+      "apps/demo/akan.baseline.json is not valid JSON.",
+    );
+    expect(() => MaintainabilityBaseline.parse("[]")).toThrow("holds an object");
+    expect(() => MaintainabilityBaseline.parse('{ "akan.size.file": { "a": "900" } }')).toThrow('"akan.size.file"');
+    expect(() => MaintainabilityBaseline.parse('{ "akan.store.multi-write": ["a#b"] }')).toThrow(
+      '"akan.store.multi-write"',
+    );
+    expect(() => MaintainabilityBaseline.parse('{ "maxLines": {} }')).toThrow("akan quality baseline --force");
+    expect(() => MaintainabilityBaseline.parse('{ "reasons": { "ui/Board.tsx": 1 } }')).toThrow('"reasons"');
+    expect(MaintainabilityBaseline.parse("{}").isEmpty).toBe(true);
+  });
+});