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

package/lint/no-import-common-err.grit

@@ -0,0 +1,31 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// `akanjs/common`'s `Err` takes any string, so a mistyped key compiles and `no-throw-raw-error`, which only knows a raw
+// `Error`, passes it. The `Err` from an app's or lib's dict is the same class typed with that dictionary's keys.
+//
+// `import type` stays legal, to annotate a caught `Err`: a type cannot be constructed. A namespace import is not
+// matched, since the rule cannot tell `common.Err` from the helpers such an import is for.
+or {
+  or {
+    JsShorthandNamedImportSpecifier() as $specifier where { $specifier <: r"Err" },
+    JsNamedImportSpecifier() as $specifier where { $specifier <: r"Err\s+as\s[\s\S]*" }
+  } where {
+    $specifier <: within JsImport() as $statement,
+    not $statement <: r"import\s+type[\s\S]*"
+  },
+  JsExportNamedFromSpecifier() as $specifier where {
+    $specifier <: r"Err(?:\s+as\s[\s\S]*)?",
+    $specifier <: within JsExport() as $statement,
+    not $statement <: r"export\s+type[\s\S]*"
+  }
+} where {
+  $statement <: contains JsModuleSource() as $source where {
+    $source <: r"[\x22']akanjs/common(?:/(?:err|index)(?:\.ts)?)?[\x22']"
+  },
+  register_diagnostic(
+    span = $specifier,
+    message = "Do not import `Err` from akanjs/common: it takes any string, so a mistyped key compiles. Import the typed `Err` from the app/lib dict on the server (import { Err } from '../dict') or from the package client entrypoint in UI ('@libs/<lib>/client', '@apps/<app>/client'), and register the key in that module's dictionary `.error({})`. `common/` and `env/` have no legal `Err`: keep throwing code out of them. Write 'import type' if only the type is needed.",
+    severity = "error"
+  )
+}

package/lint/no-init-fetch-in-client.grit

@@ -11,7 +11,7 @@ language js(typescript, jsx)
 // closure reaches nothing.
 //
 // The client is not missing the load, only this spelling of it: every slice also generates
-// `st.do.init<Model><Suffix>` (pkgs/akanjs/store/action.ts), which runs the same two queries and commits
+// `st.do.init<Model><Suffix>` (pkgs/akanjs/store/sliceListActions.ts), which runs the same two queries and commits
 // them to state.
 //
 // Both names are matched by shape, since a lint rule cannot know which slices exist. The generated one is

package/lint/no-web-only-api-outside-webkit.grit

@@ -13,7 +13,7 @@ or {
     $access <: or { `navigator.share`, `navigator.canShare` },
     register_diagnostic(
       span = $access,
-      message = "Android's WebView has no Web Share, so this does nothing in the app. Move it into a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client/native`; the runtime's `share` plugin is the app side.",
+      message = "Android's WebView has no Web Share, so this does nothing in the app. Move it into a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client`; the runtime's `share` plugin is the app side.",
       severity = "warn"
     )
   },
@@ -21,7 +21,7 @@ or {
     $access <: or { `navigator.serviceWorker`, `Notification.requestPermission`, `Notification.permission` },
     register_diagnostic(
       span = $access,
-      message = "A native app page has no service worker or Notification API. Keep this in a `webkit/` hook behind `isNativeApp()`; native push is `push` from `akanjs/client/native`, and `usePushNotification` in libs/util wraps both.",
+      message = "A native app page has no service worker or Notification API. Keep this in a `webkit/` hook behind `isNativeApp()`; native push is `push` from `akanjs/client/native/push`, and `usePushNotification` in libs/util wraps both.",
       severity = "warn"
     )
   },
@@ -37,7 +37,7 @@ or {
     $access <: `navigator.vibrate`,
     register_diagnostic(
       span = $access,
-      message = "iOS has no `navigator.vibrate`. Use `haptics` from `akanjs/client/native` in a `webkit/` hook.",
+      message = "iOS has no `navigator.vibrate`. Use `haptics` from `akanjs/client/native/haptics` in a `webkit/` hook.",
       severity = "warn"
     )
   }

package/maintainabilityBaseline.test.ts

@@ -39,6 +39,14 @@ const placementOf = (file: string, writes: string[]): MaintainabilityViolation =
   line: 1,
   writes,
 });
+const bareOf = (file: string, count: number): MaintainabilityViolation => ({
+  kind: "bareError",
+  rule: "akan.error.bare-error",
+  key: file,
+  file,
+  line: 1,
+  lines: Array.from({ length: count }, (_, idx) => idx + 1),
+});
 const baselineOf = (
   sections: { [rule in DebtRuleId]?: Record<string, number> },
   reasons: Record<string, string> = {},
@@ -217,6 +225,47 @@ describe("MaintainabilityBaseline", () => {
     expect(baseline.tightenedBy([]).reasons.size).toBe(0);
   });
 
+  test("holds a total rule to the sum of its section: a moved count passes, a raised sum names the files that rose", () => {
+    const baseline = baselineOf({ "akan.error.bare-error": { "server/a.ts": 2, "server/b.ts": 1 } });
+
+    expect(baseline.unallowed([bareOf("server/c.ts", 3)])).toEqual([]);
+    expect(baseline.unallowed([bareOf("server/a.ts", 3), bareOf("server/b.ts", 1)])).toEqual([
+      bareOf("server/a.ts", 3),
+    ]);
+    expect(baseline.tightenedBy([bareOf("server/c.ts", 2)]).sections.get("akan.error.bare-error")).toEqual(
+      new Map([["server/c.ts", 2]]),
+    );
+    expect(baseline.tightenedBy([bareOf("server/a.ts", 4)]).sections.get("akan.error.bare-error")).toEqual(
+      new Map([
+        ["server/a.ts", 2],
+        ["server/b.ts", 1],
+      ]),
+    );
+    expect(baselineOf({ "akan.error.bare-error": { "server/c.ts": 3 } }).grownFrom(baseline)).toEqual([]);
+    expect(baselineOf({ "akan.error.bare-error": { "server/c.ts": 4 } }).grownFrom(baseline)).toEqual([
+      { rule: "akan.error.bare-error", key: MaintainabilityBaseline.totalKey, count: 4, committed: 3 },
+    ]);
+    expect(baseline.grownFrom(new MaintainabilityBaseline())).toEqual([
+      { rule: "akan.error.bare-error", key: MaintainabilityBaseline.totalKey, count: 3, committed: undefined },
+    ]);
+  });
+
+  test("names a total recorded above the code's and no other, on a total rule only", () => {
+    const baseline = baselineOf({
+      "akan.size.file": { "lib/a/A.Zone.tsx": 900 },
+      "akan.error.bare-error": { "server/a.ts": 2, "server/b.ts": 1 },
+    });
+
+    expect(baseline.staleTotals([bareOf("server/a.ts", 2)])).toEqual([
+      { rule: "akan.error.bare-error", count: 2, recorded: 3 },
+    ]);
+    expect(baseline.staleTotals([])).toEqual([{ rule: "akan.error.bare-error", count: 0, recorded: 3 }]);
+    expect(baseline.staleTotals([bareOf("server/c.ts", 3)])).toEqual([]);
+    expect(baseline.staleTotals([bareOf("server/c.ts", 4)])).toEqual([]);
+    expect(baseline.tightenedBy([bareOf("server/a.ts", 1)]).staleTotals([bareOf("server/a.ts", 1)])).toEqual([]);
+    expect(new MaintainabilityBaseline().staleTotals([])).toEqual([]);
+  });
+
   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"),

package/maintainabilityBaseline.ts

@@ -14,9 +14,16 @@ export interface BaselineEntry {
   reason?: string;
 }
 
+export interface BaselineStaleTotal {
+  rule: DebtRuleId;
+  count: number;
+  recorded: number;
+}
+
 type Counts = ReadonlyMap<string, number>;
 
-//* One section per rule, each key holding what the gate measured: lines, members, store accesses, writes or calls.
+//* One section per rule, each key holding what the gate measured: lines, members, accesses, writes, calls or the
+//* built-in Errors constructed or extended.
 //* A count only falls, so a recorded entry cannot take on more of the debt it records.
 export class MaintainabilityBaseline {
   static readonly fileName = "akan.baseline.json";
@@ -32,7 +39,13 @@ export class MaintainabilityBaseline {
     "akan.component.write-chain",
     "akan.write.placement",
     "akan.service.call-in-loop",
+    "akan.error.bare-error",
   ] as const satisfies readonly DebtRuleId[];
+  //* Added after baselines were committed: where the reference holds no section for one, its code there is the floor.
+  static readonly lateRules: ReadonlySet<DebtRuleId> = new Set(["akan.error.bare-error"]);
+  //* Held to the package's sum, so a moved or split file keeps its count; the per-file entries name the file that rose.
+  static readonly totalRules: ReadonlySet<DebtRuleId> = new Set(["akan.error.bare-error"]);
+  static readonly totalKey = "(total)";
   static readonly reasonedRules: ReadonlySet<DebtRuleId> = new Set([
     "akan.size.file",
     "akan.size.component",
@@ -48,6 +61,7 @@ export class MaintainabilityBaseline {
     if (violation.kind === "storeAccess") return violation.accessCount;
     if (violation.kind === "multiWrite") return violation.writeCount;
     if (violation.kind === "writePlacement") return violation.writes.length;
+    if (violation.kind === "bareError") return violation.lines.length;
     return violation.calls.length;
   }
 
@@ -116,6 +130,30 @@ export class MaintainabilityBaseline {
     return recorded !== undefined && MaintainabilityBaseline.countOf(violation) <= recorded;
   }
 
+  unallowed(violations: MaintainabilityViolation[]) {
+    const measured = MaintainabilityBaseline.of(violations);
+    return violations.filter(
+      (violation) =>
+        !(
+          MaintainabilityBaseline.totalRules.has(violation.rule) &&
+          measured.totalOf(violation.rule) <= this.totalOf(violation.rule)
+        ) && !this.allows(violation),
+    );
+  }
+
+  staleTotals(violations: MaintainabilityViolation[]): BaselineStaleTotal[] {
+    const measured = MaintainabilityBaseline.of(violations);
+    return [...MaintainabilityBaseline.totalRules].flatMap((rule) => {
+      const count = measured.totalOf(rule);
+      const recorded = this.totalOf(rule);
+      return count < recorded ? [{ rule, count, recorded }] : [];
+    });
+  }
+
+  totalOf(rule: DebtRuleId) {
+    return [...(this.sections.get(rule)?.values() ?? [])].reduce((sum, count) => sum + count, 0);
+  }
+
   recordedOf(violation: MaintainabilityViolation) {
     return this.sections.get(violation.rule)?.get(violation.key);
   }
@@ -140,13 +178,32 @@ export class MaintainabilityBaseline {
     );
   }
 
+  rulesOutside(other: MaintainabilityBaseline | null): DebtRuleId[] {
+    return [...this.sections]
+      .filter(
+        ([rule, counts]) =>
+          counts.size && (other === null || (MaintainabilityBaseline.lateRules.has(rule) && !other.sections.has(rule))),
+      )
+      .map(([rule]) => rule);
+  }
+
+  withSectionsOf(other: MaintainabilityBaseline | null, rules: ReadonlySet<DebtRuleId>) {
+    if (!other) return this;
+    const sections = new Map(this.sections);
+    for (const rule of rules) sections.set(rule, other.sections.get(rule) ?? new Map());
+    return new MaintainabilityBaseline(sections, this.reasons);
+  }
+
   tightenedBy(violations: MaintainabilityViolation[]) {
     const current = MaintainabilityBaseline.of(violations);
     const sections = new Map(
-      [...this.sections].map(([rule, counts]) => [
-        rule,
-        MaintainabilityBaseline.#lowered(counts, current.sections.get(rule) ?? new Map()),
-      ]),
+      [...this.sections].map(([rule, counts]) => {
+        const measured = current.sections.get(rule) ?? new Map<string, number>();
+        if (!MaintainabilityBaseline.totalRules.has(rule))
+          return [rule, MaintainabilityBaseline.#lowered(counts, measured)];
+        //? Over budget, a file that went down may only have moved its count; recording it would refuse that move later.
+        return [rule, current.totalOf(rule) > this.totalOf(rule) ? counts : measured];
+      }),
     );
     return new MaintainabilityBaseline(sections).#withReasonsOf(this.reasons);
   }
@@ -161,12 +218,20 @@ export class MaintainabilityBaseline {
   //* Only a shape entry grows with a reason: a write rule guards correctness, whatever the reason.
   grownFrom(committed: MaintainabilityBaseline): BaselineEntryGrowth[] {
     return [...this.sections].flatMap(([rule, counts]) =>
-      MaintainabilityBaseline.#raised(counts, committed.sections.get(rule) ?? new Map())
-        .filter(([key]) => !(MaintainabilityBaseline.reasonedRules.has(rule) && this.reasonOf(key)))
-        .map(([key, count, recorded]) => ({ rule, key, count, committed: recorded })),
+      MaintainabilityBaseline.totalRules.has(rule)
+        ? this.#totalGrownFrom(committed, rule)
+        : MaintainabilityBaseline.#raised(counts, committed.sections.get(rule) ?? new Map())
+            .filter(([key]) => !(MaintainabilityBaseline.reasonedRules.has(rule) && this.reasonOf(key)))
+            .map(([key, count, recorded]) => ({ rule, key, count, committed: recorded })),
     );
   }
 
+  #totalGrownFrom(committed: MaintainabilityBaseline, rule: DebtRuleId): BaselineEntryGrowth[] {
+    const count = this.totalOf(rule);
+    const recorded = committed.sections.has(rule) ? committed.totalOf(rule) : undefined;
+    return count > (recorded ?? 0) ? [{ rule, key: MaintainabilityBaseline.totalKey, count, committed: recorded }] : [];
+  }
+
   stringify() {
     const sections = MaintainabilityBaseline.debtRules.flatMap((rule) => {
       const counts = this.sections.get(rule);

package/maintainabilityContract.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { readFile, rm } from "node:fs/promises";
 import path from "node:path";
 import { MaintainabilityBaseline } from "./maintainabilityBaseline";
 import { MaintainabilityContract } from "./maintainabilityContract";
@@ -506,6 +506,7 @@ describe("MaintainabilityContract rules", () => {
       "akan.component.store-access",
       "akan.write.placement",
       "akan.service.call-in-loop",
+      "akan.error.bare-error",
       "akan.baseline.growth",
     ]);
     const root = await makeWorkspace({
@@ -958,6 +959,306 @@ describe("MaintainabilityContract packages", () => {
   });
 });
 
+describe("MaintainabilityContract bare errors", () => {
+  const manifest = '{ "name": "akanjs" }\n';
+  const akanjsOf = (root: string) => new MaintainabilityContract(root, { type: "pkg", name: "akanjs" });
+  const failing = (count: number, prefix = "f") =>
+    `${Array.from(
+      { length: count },
+      (_, idx) => `export const ${prefix}${idx} = () => {\n  throw new Error("${idx}");\n};`,
+    ).join("\n")}\n`;
+  const shapes = `import { AkanError } from "akanjs/base";
+import { Err } from "akanjs/dictionary";
+export const a = () => {
+  throw new globalThis.Error("1");
+};
+export const b = () => {
+  throw Object.assign(new Error("2"), { statusCode: 400 });
+};
+export const c = (err?: Error) => {
+  throw err ?? Error("3");
+};
+export const d = (x: boolean) => {
+  throw x ? new TypeError("4a") : new RangeError("4b");
+};
+export const e = () => {
+  const failure = new Error("5");
+  throw failure;
+};
+export const f = () => {
+  throw (<Error>new Error("6"))!;
+};
+export const g = () => new Promise((_, reject) => reject(new Error("7") satisfies Error));
+class LocalError extends Error {}
+export const h = () => {
+  throw new LocalError("9");
+};
+export const i = (Error: ErrorConstructor) => {
+  throw new Error("shadowed by a parameter");
+};
+export const j = () => {
+  const TypeError = class {};
+  throw new TypeError();
+};
+export const k = (input: unknown) => {
+  if (input === 1) throw new AkanError("coded", "coded", { statusCode: 400 });
+  if (input === 2) throw new Err.NotFound("base.error.missing");
+  if (input instanceof Error) Error.captureStackTrace(input);
+  throw new DOMException("aborted", "AbortError");
+};
+`;
+  const baselineAt = async (root: string) =>
+    MaintainabilityBaseline.parse(
+      await readFile(path.join(root, "pkgs/akanjs/akan.baseline.json"), "utf8"),
+    ).sections.get("akan.error.bare-error");
+
+  test("counts each built-in Error constructed, rejected or extended under server/, service/ and signal/ of akanjs", async () => {
+    const root = await makeWorkspace({
+      "pkgs/akanjs/package.json": manifest,
+      "pkgs/akanjs/server/shapes.ts": shapes,
+      "pkgs/akanjs/signal/fail.ts": failing(1),
+      "pkgs/akanjs/service/run.test.ts": failing(2),
+      "pkgs/akanjs/client/run.ts": failing(2),
+      "pkgs/akanjs/service/imported.ts": `import { Error } from "./errors";\nexport const fail = () => new Error("x");\n`,
+      "pkgs/framework/package.json": manifest,
+      "pkgs/framework/server/fail.ts": failing(1),
+      "pkgs/other/package.json": '{ "name": "other" }\n',
+      "pkgs/other/server/fail.ts": failing(1),
+    });
+
+    expect(await akanjsOf(root).measure()).toEqual([
+      {
+        kind: "bareError",
+        rule: "akan.error.bare-error",
+        key: "server/shapes.ts",
+        file: "server/shapes.ts",
+        line: 4,
+        lines: [4, 7, 10, 13, 13, 16, 20, 22, 23],
+      },
+      {
+        kind: "bareError",
+        rule: "akan.error.bare-error",
+        key: "signal/fail.ts",
+        file: "signal/fail.ts",
+        line: 2,
+        lines: [2],
+      },
+    ]);
+    expect(await new MaintainabilityContract(root, { type: "pkg", name: "framework" }).measure()).toMatchObject([
+      { rule: "akan.error.bare-error", key: "server/fail.ts" },
+    ]);
+    expect(await new MaintainabilityContract(root, { type: "pkg", name: "other" }).measure()).toEqual([]);
+  });
+
+  test("holds the package's total, so a rename or a split passes and the entries follow the code", async () => {
+    const root = await makeWorkspace({
+      "pkgs/akanjs/package.json": manifest,
+      "pkgs/akanjs/server/host.ts": failing(3),
+    });
+    await akanjsOf(root).seed();
+    await commitAll(root);
+    await git(root, "checkout", "-q", "-b", "feat");
+
+    await git(root, "mv", "pkgs/akanjs/server/host.ts", "pkgs/akanjs/server/moved.ts");
+    expect(await akanjsOf(root).enforce({ fix: false })).toEqual([]);
+    expect(await akanjsOf(root).enforce({ fix: true })).toEqual([]);
+    expect(await baselineAt(root)).toEqual(new Map([["server/moved.ts", 3]]));
+
+    await writeText(path.join(root, "pkgs/akanjs/server/moved.ts"), failing(1));
+    await writeText(path.join(root, "pkgs/akanjs/signal/extracted.ts"), failing(2, "g"));
+    expect(await akanjsOf(root).enforce({ fix: false })).toEqual([]);
+    expect(await akanjsOf(root).enforce({ fix: true })).toEqual([]);
+    expect(await baselineAt(root)).toEqual(
+      new Map([
+        ["server/moved.ts", 1],
+        ["signal/extracted.ts", 2],
+      ]),
+    );
+
+    await writeText(path.join(root, "pkgs/akanjs/signal/extracted.ts"), failing(1, "g"));
+    expect(await akanjsOf(root).enforce({ fix: true })).toEqual([]);
+    expect(await baselineAt(root)).toEqual(
+      new Map([
+        ["server/moved.ts", 1],
+        ["signal/extracted.ts", 1],
+      ]),
+    );
+  });
+
+  test("fails a new bare Error anywhere, naming the file whose count rose", async () => {
+    const root = await makeWorkspace({
+      "pkgs/akanjs/package.json": manifest,
+      "pkgs/akanjs/server/host.ts": failing(3),
+    });
+    await akanjsOf(root).seed();
+    await commitAll(root);
+    await writeText(path.join(root, "pkgs/akanjs/service/fresh.ts"), failing(1));
+
+    const contract = akanjsOf(root);
+    const failures = await contract.enforce({ fix: false });
+
+    expect(failures).toMatchObject([{ rule: "akan.error.bare-error", key: "service/fresh.ts", lines: [2] }]);
+    expect(contract.describe(failures)).toBe(
+      "[maintainability] 1 violation(s) in pkgs/akanjs:\n" +
+        "  pkgs/akanjs/service/fresh.ts:2  akan.error.bare-error  constructs or extends 1 bare Error, on line 2, and the package's total grew\n" +
+        "How to fix:\n" +
+        "  bare Error: Construct an `AkanError` subclass from `akanjs/base` with a code the caller can branch on, and a `statusCode` when it answers a request: an existing class whose code fits, or a new one beside the code that fails; a class extending a built-in Error extends `AkanError` instead. A failure another process reported travels as itself. The package's total is what is held, so moving a bare Error between files passes and `akan lint` rewrites the entries.",
+    );
+
+    await writeText(path.join(root, "pkgs/akanjs/server/host.ts"), failing(4));
+    await Bun.write(path.join(root, "pkgs/akanjs/service/fresh.ts"), "export const fine = 1;\n");
+    expect(await akanjsOf(root).enforce({ fix: false })).toMatchObject([
+      { rule: "akan.error.bare-error", key: "server/host.ts", lines: [2, 5, 8, 11], recorded: 3 },
+    ]);
+  });
+
+  test("refuses a working total raised over the fork point's, whatever file it is recorded under", async () => {
+    const root = await makeWorkspace({
+      "pkgs/akanjs/package.json": manifest,
+      "pkgs/akanjs/server/host.ts": failing(2),
+    });
+    await akanjsOf(root).seed();
+    await commitAll(root);
+    await writeText(path.join(root, "pkgs/akanjs/server/host.ts"), failing(3));
+    await akanjsOf(root).seed({ force: true });
+
+    const contract = akanjsOf(root);
+    const failures = await contract.enforce({ fix: false });
+
+    expect(failures).toMatchObject([
+      { kind: "baselineGrowth", debtRule: "akan.error.bare-error", key: "(total)", count: 3, committed: 2, line: 2 },
+    ]);
+    expect(contract.describe(failures)).toMatch(
+      /akan\.baseline\.json:2 {2}akan\.baseline\.growth {2}akan\.error\.bare-error allows 3 bare Errors in all, above the 2 at [0-9a-f]{12}; the baseline may only shrink/,
+    );
+  });
+
+  test("refuses a paydown that keeps the baseline, so a later change cannot spend what it paid", async () => {
+    const root = await makeWorkspace({
+      "pkgs/akanjs/package.json": manifest,
+      "pkgs/akanjs/server/a.ts": failing(3),
+    });
+    await akanjsOf(root).seed();
+    await commitAll(root);
+    await git(root, "checkout", "-q", "-b", "pr-1");
+    await writeText(path.join(root, "pkgs/akanjs/server/a.ts"), failing(1));
+
+    const contract = akanjsOf(root);
+    const failures = await contract.enforce({ fix: false });
+
+    expect(failures).toEqual([
+      {
+        kind: "staleTotal",
+        rule: "akan.error.bare-error",
+        key: "(total)",
+        file: "akan.baseline.json",
+        line: 2,
+        count: 1,
+        recorded: 3,
+      },
+    ]);
+    expect(contract.describe(failures)).toBe(
+      "[maintainability] 1 violation(s) in pkgs/akanjs:\n" +
+        "  pkgs/akanjs/akan.baseline.json:2  akan.error.bare-error  records 3 bare Errors in all, above the 1 the code holds\n" +
+        "How to fix:\n" +
+        "  baseline total: Run `akan verify <package>`, which lowers the section, and commit `akan.baseline.json` in this change: a recorded total above the code is room for a new failure anywhere. A bare `akan verify` covers only uncommitted files.",
+    );
+
+    expect(await akanjsOf(root).enforce({ fix: true })).toEqual([]);
+    expect(await baselineAt(root)).toEqual(new Map([["server/a.ts", 1]]));
+    expect(await akanjsOf(root).enforce({ fix: false })).toEqual([]);
+
+    await git(root, "add", "-A");
+    await git(root, "commit", "-q", "-m", "pr 1");
+    await git(root, "checkout", "-q", "main");
+    await git(root, "merge", "-q", "--ff-only", "pr-1");
+    await git(root, "checkout", "-q", "-b", "pr-2");
+    await writeText(path.join(root, "pkgs/akanjs/signal/new.ts"), failing(2, "g"));
+
+    expect(await akanjsOf(root).enforce({ fix: false })).toMatchObject([
+      { rule: "akan.error.bare-error", key: "signal/new.ts", lines: [2, 5] },
+    ]);
+  });
+
+  test("refuses a stale total in a scope with no reference to compare with", async () => {
+    const root = await makeWorkspace({
+      "pkgs/akanjs/package.json": manifest,
+      "pkgs/akanjs/server/a.ts": failing(1),
+      "pkgs/akanjs/akan.baseline.json": '{\n  "akan.error.bare-error": {\n    "server/a.ts": 3\n  }\n}\n',
+    });
+
+    expect(await akanjsOf(root).enforce({ fix: false })).toMatchObject([{ kind: "staleTotal", count: 1, recorded: 3 }]);
+  });
+
+  test("leaves the section untouched while over budget, so a move survives a run that also added one", async () => {
+    const root = await makeWorkspace({
+      "pkgs/akanjs/package.json": manifest,
+      "pkgs/akanjs/server/a.ts": failing(3),
+      "pkgs/akanjs/server/b.ts": failing(1),
+    });
+    await akanjsOf(root).seed();
+    await commitAll(root);
+    await git(root, "checkout", "-q", "-b", "feat");
+    await writeText(path.join(root, "pkgs/akanjs/server/a.ts"), failing(2));
+    await writeText(path.join(root, "pkgs/akanjs/server/b.ts"), failing(2));
+    await writeText(path.join(root, "pkgs/akanjs/server/c.ts"), failing(1));
+
+    expect(await akanjsOf(root).enforce({ fix: true })).toMatchObject([
+      { key: "server/b.ts", recorded: 1 },
+      { key: "server/c.ts" },
+    ]);
+    expect(await baselineAt(root)).toEqual(
+      new Map([
+        ["server/a.ts", 3],
+        ["server/b.ts", 1],
+      ]),
+    );
+
+    await rm(path.join(root, "pkgs/akanjs/server/c.ts"));
+    expect(await akanjsOf(root).enforce({ fix: true })).toEqual([]);
+    expect(await baselineAt(root)).toEqual(
+      new Map([
+        ["server/a.ts", 2],
+        ["server/b.ts", 2],
+      ]),
+    );
+    expect(await akanjsOf(root).enforce({ fix: false })).toEqual([]);
+  });
+
+  test("adopts the rule in a baseline that predates it with the fork point's total, and no more", async () => {
+    const root = await makeWorkspace({
+      "pkgs/akanjs/package.json": manifest,
+      "pkgs/akanjs/server/host.ts": failing(2),
+      "pkgs/akanjs/akan.baseline.json": '{\n  "akan.size.file": {\n    "server/big.ts": 900\n  }\n}\n',
+      "pkgs/akanjs/server/big.ts": linesOf(900),
+    });
+    await commitAll(root);
+
+    await akanjsOf(root).seed({ force: true });
+    expect(await baselineAt(root)).toEqual(new Map([["server/host.ts", 2]]));
+    expect(await akanjsOf(root).enforce({ fix: false })).toEqual([]);
+
+    await writeText(path.join(root, "pkgs/akanjs/signal/fresh.ts"), failing(1));
+    await akanjsOf(root).seed({ force: true });
+    const contract = akanjsOf(root);
+    const failures = await contract.enforce({ fix: false });
+
+    expect(failures).toMatchObject([
+      {
+        kind: "baselineGrowth",
+        debtRule: "akan.error.bare-error",
+        key: "(total)",
+        count: 3,
+        committed: 2,
+        measured: true,
+      },
+    ]);
+    expect(contract.describe(failures)).toMatch(
+      /akan\.error\.bare-error allows 3 bare Errors in all, above the 2 the code at [0-9a-f]{12} holds with no entry for its rule recorded there/,
+    );
+  });
+});
+
 describe("MaintainabilityContract reference without a baseline", () => {
   const packageOf = (root: string) => new MaintainabilityContract(root, { type: "pkg", name: "@demo/core" });
   const functionOf = (name: string, lineNum: number) => `export function ${name}() {\n${linesOf(lineNum - 2)}\n}\n`;