@akanjs/devkit 3.1.2-rc.3 → 3.2.0-rc.0

package/incrementalBuilder/incrementalBuilder.proc.test.ts

@@ -129,7 +129,7 @@ process.send({ type: "build-batch-result", data: { generation, errors, artifact:
     expect(messages.some((message) => message.type === "build-status")).toBe(false);
   }, 30_000);
 
-  test("draws the app's graph on request, with the libs it reaches and no other app", async () => {
+  test("draws the app's graph and Change Map on request, with the libs it reaches and no other app", async () => {
     const { root } = track(await createTempApp("demo"));
     const appDir = path.join(root, "apps/demo");
     await writeText(
@@ -157,6 +157,27 @@ process.send({ type: "build-batch-result", data: { generation, errors: {}, artif
       ...moduleFiles("apps/other", "note"),
       ...moduleFiles("libs/shared", "file"),
     ]);
+    const git = (...args: string[]) => {
+      const result = Bun.spawnSync(
+        ["git", "-c", "user.name=akan", "-c", "user.email=akan@example.com", "-c", "commit.gpgsign=false", ...args],
+        { cwd: root, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } },
+      );
+      expect(result.exitCode).toBe(0);
+    };
+    git("init", "-q", "-b", "main");
+    git("add", "-A");
+    git("commit", "-q", "--no-verify", "-m", "base");
+    await Promise.all(
+      [
+        ["apps/demo/lib/memo/memo.constant.ts", "Memo"],
+        ["apps/other/lib/note/note.constant.ts", "Note"],
+      ].map(([file, model]) =>
+        writeText(
+          path.join(root, file),
+          `export class ${model} extends via((field) => ({ name: field(String), pinned: field(Boolean) })) {}\n`,
+        ),
+      ),
+    );
     const messages: BuilderMessage[] = [];
     const proc = Bun.spawn(["bun", path.join(import.meta.dir, "incrementalBuilder.proc.ts")], {
       cwd: appDir,
@@ -178,20 +199,98 @@ process.send({ type: "build-batch-result", data: { generation, errors: {}, artif
     try {
       await until(proc, "builder-ready", () => messages.some((message) => message.type === "builder-ready"));
       proc.send({ type: "build-graph", id: 5 } satisfies BuilderMessage);
-      await until(proc, "build-graph-res", () => messages.some((message) => message.type === "build-graph-res"));
+      proc.send({ type: "build-graph", id: 6, changes: { since: null } } satisfies BuilderMessage);
+      proc.send({ type: "build-graph", id: 7, changes: { since: "main" } } satisfies BuilderMessage);
+      await until(
+        proc,
+        "build-graph-res",
+        () => messages.filter((message) => message.type === "build-graph-res").length === 3,
+      );
     } finally {
       proc.kill();
       await proc.exited;
     }
-    const answer = messages.find((message) => message.type === "build-graph-res");
-    if (answer?.type !== "build-graph-res" || !answer.ok) throw new Error(`no graph: ${JSON.stringify(answer)}`);
-    expect(answer.data.workspaceRoot).toBe(root);
-    expect(answer.data.graph.nodes.map((node) => node.id).sort()).toEqual([
+    const answerTo = (id: number) => {
+      const answer = messages.find((message) => message.type === "build-graph-res" && message.id === id);
+      if (answer?.type !== "build-graph-res" || !answer.ok) throw new Error(`no graph: ${JSON.stringify(answer)}`);
+      return answer.data;
+    };
+    const graph = answerTo(5);
+    if (!("graph" in graph)) throw new Error("build-graph answered with changes");
+    expect(graph.workspaceRoot).toBe(root);
+    expect(graph.graph.nodes.map((node) => node.id).sort()).toEqual([
       "model:apps/demo:memo",
       "model:libs/shared:file",
+      "route:apps/demo:/",
     ]);
+    const changes = answerTo(6);
+    if (!("changes" in changes) || "error" in changes.changes)
+      throw new Error(`no changes: ${JSON.stringify(changes)}`);
+    expect(changes.changes.nodes.map(({ id, change }) => [id, change])).toEqual([["model:apps/demo:memo", "changed"]]);
+    expect(changes.changes.summary).toEqual({ added: 0, removed: 0, changed: 1 });
+    expect(answerTo(7)).toEqual(changes);
   }, 30_000);
 
+  test("maps the framework on request, and maps it again after a save under pkgs/akanjs", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `const { generation } = JSON.parse(process.argv[2]);
+process.send({ type: "build-batch-result", data: { generation, errors: {}, artifact: {}, optimizedFonts: { css: "", files: [] } } });
+`,
+    );
+    await writeText(path.join(appDir, "page/_index.tsx"), "export default () => null;\n");
+    await writeText(
+      path.join(appDir, "tsconfig.json"),
+      JSON.stringify({ compilerOptions: { target: "ESNext", paths: { "akanjs/*": ["./pkgs/akanjs/*"] } } }),
+    );
+    await writeText(path.join(root, "pkgs/akanjs/base/scalar.ts"), "export class Scalar {}\n");
+    const messages: BuilderMessage[] = [];
+    const proc = Bun.spawn(["bun", path.join(import.meta.dir, "incrementalBuilder.proc.ts")], {
+      cwd: appDir,
+      env: {
+        ...process.env,
+        AKAN_WORKSPACE_ROOT: root,
+        AKAN_PUBLIC_APP_NAME: "demo",
+        AKAN_PUBLIC_REPO_NAME: "repo",
+        AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+        AKAN_PUBLIC_ENV: "local",
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      serialization: "advanced",
+      ipc: (message: BuilderMessage) => {
+        messages.push(message);
+      },
+    });
+    const classesAnsweredTo = async (id: number) => {
+      proc.send({ type: "build-graph", id, framework: true } satisfies BuilderMessage);
+      await until(proc, `build-graph-res ${id}`, () =>
+        messages.some((message) => message.type === "build-graph-res" && message.id === id),
+      );
+      const answer = messages.find((message) => message.type === "build-graph-res" && message.id === id);
+      if (answer?.type !== "build-graph-res" || !answer.ok || !("framework" in answer.data))
+        throw new Error(`no framework map: ${JSON.stringify(answer)}`);
+      expect(answer.data.workspaceRoot).toBe(root);
+      return answer.data.framework?.facets.flatMap(({ classes }) => classes.map(({ name }) => name));
+    };
+    try {
+      await until(proc, "builder-ready", () => messages.some((message) => message.type === "builder-ready"));
+      expect(await classesAnsweredTo(1)).toEqual(["Scalar"]);
+      await writeText(path.join(root, "pkgs/akanjs/base/scalar.ts"), "export class Scalar {}\nexport class Unit {}\n");
+      const deadline = Date.now() + 15_000;
+      let id = 2;
+      while (Date.now() < deadline) {
+        if ((await classesAnsweredTo(id++))?.includes("Unit")) break;
+        await wait(200);
+      }
+      expect(await classesAnsweredTo(id)).toEqual(["Scalar", "Unit"]);
+    } finally {
+      proc.kill();
+      await proc.exited;
+    }
+  }, 40_000);
+
   test("answers a second shell request in the same generation without building again", async () => {
     const { root } = track(await createTempApp("demo"));
     const appDir = path.join(root, "apps/demo");

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -18,7 +18,6 @@ import { RouteClientBuilder } from "@akanjs/devkit/frontendBuild/routeClientBuil
 import { ServerGraphFile } from "@akanjs/devkit/frontendBuild/serverGraphFile";
 import { SsrDevBundler } from "@akanjs/devkit/frontendBuild/ssrDevBundler";
 import { WatchRootResolver } from "@akanjs/devkit/frontendBuild/watchRootResolver";
-import { WorkspaceGraph } from "@akanjs/devkit/workspaceGraph";
 import { Logger } from "akanjs/common";
 import type {
   BaseBuildArtifact,
@@ -27,7 +26,6 @@ import type {
   BuilderMessage,
   BuilderReq,
   BuilderRes,
-  BuildGraphPayload,
   BuildPhase,
   BuildRouteResultPayload,
   ChangeBatch,
@@ -37,6 +35,7 @@ import { CSR_DEV_PATCHING_MARKER } from "akanjs/server/hmr/csrDevManifest";
 import type { BuildBatchNeed, BuildBatchRequest, BuildBatchResult, OptimizedFonts } from "./buildBatchProtocol";
 import { BuildBatchRunner } from "./buildBatchRunner";
 import { BuilderChannel } from "./builderChannel";
+import { BuilderGraphPayloads } from "./builderGraphPayloads";
 import { type BatchJob, BuilderWorkQueue, type DiscoveryJob } from "./builderWorkQueue";
 import { prepareDevWatchBatch } from "./devWatchBatch";
 
@@ -67,7 +66,7 @@ class IncrementalBuilder {
   #watcher: HmrWatcher | null = null;
   #generation = 0;
   #shellKey: string | null = null;
-  #graph: { generation: number; payload: BuildGraphPayload } | null = null;
+  readonly #graphPayloads: BuilderGraphPayloads;
   #discoveredThrough = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #csrBundler: CsrDevBundler;
@@ -119,6 +118,7 @@ class IncrementalBuilder {
     this.#discovery = options.discovery;
     this.#generation = options.initialGeneration ?? 0;
     this.#discoveredThrough = this.#generation;
+    this.#graphPayloads = new BuilderGraphPayloads(options.app, () => this.#generation);
     this.#batchRunner = new BuildBatchRunner({
       workspaceRoot: options.app.workspace.workspaceRoot,
       cwd: options.app.cwdPath,
@@ -367,6 +367,7 @@ class IncrementalBuilder {
   }
 
   async #handleWatchBatch(batch: ChangeBatch) {
+    this.#graphPayloads.touched(batch.files);
     const rawKinds = new Set(batch.kinds);
     if (rawKinds.size === 0) return;
     const generation = ++this.#generation;
@@ -878,14 +879,9 @@ class IncrementalBuilder {
   }
 
   async handleBuildGraph(msg: BuilderGraphReq): Promise<void> {
-    const generation = this.#generation;
     try {
-      if (this.#graph?.generation !== generation) {
-        const { workspace } = this.#app;
-        const graph = WorkspaceGraph.visibleTo(await WorkspaceGraph.build(workspace), this.#app.name);
-        this.#graph = { generation, payload: { workspaceRoot: workspace.workspaceRoot, graph } };
-      }
-      await BuilderChannel.send({ type: "build-graph-res", id: msg.id, ok: true, data: this.#graph.payload });
+      const data = await this.#graphPayloads.of(msg);
+      await BuilderChannel.send({ type: "build-graph-res", id: msg.id, ok: true, data });
     } catch (err) {
       const error = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
       this.#logger.error(`build-graph failed: ${error}`);

package/integration/devStability.integration.test.ts

@@ -1,7 +1,7 @@
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
 import { AkanAppHost } from "../akanApp";
 import { DevGeneratedIndexSync } from "../frontendBuild";
-import { DevStabilityHarness, type DevStabilityHmrProbe } from "./devStabilityHarness";
+import { DevStabilityHarness, type DevStabilityHmrProbe } from "./devStabilityHarness.fixture";
 
 const integrationEnabled = process.env.AKAN_DEV_STABILITY_INTEGRATION === "1";
 // Contention pushes a cold dev-server boot from ~3s to nearly a minute; 120s ran out mid-restart.

package/integration/devStabilityHarness.test.ts

@@ -2,7 +2,7 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, readdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { tempDirs } from "../testHelpers";
-import { DevStabilityHarness } from "./devStabilityHarness";
+import { DevStabilityHarness } from "./devStabilityHarness.fixture";
 
 const servers: Bun.Server<undefined>[] = [];
 const makeRoot = tempDirs("akan-harness-port-");

package/lint/__fixtures__/no-daisyui-legacy-class/bad.tsx

@@ -1,5 +1,7 @@
-export const CompoundButton = () => <button className="btn-primary" />; // @flag
-export const CompoundBadge = () => <span className="badge-success" />; // @flag
+export const CompoundButton = () => <button className="btn-primary" />; // @warn
+export const CompoundBadge = () => <span className="badge-success" />; // @warn
+export const CompoundStatValue = () => <div className="md:stat-value" />; // @warn
+export const BothHalvesReportTheColourSlot = () => <div className="btn-primary bg-base-100" />; // @flag
 export const DroppedBaseSurface = () => <div className="bg-base-100" />; // @flag
 export const DroppedBaseContentWithOpacity = () => <div className="text-base-content/70" />; // @flag
 export const DroppedBaseOnABorderSide = () => <div className="border-t-base-300" />; // @flag

package/lint/__fixtures__/no-js-private-class-method/bad.tsx

@@ -1,3 +1,5 @@
 export class SyncPrivate { #compute() { return 1; } } // @flag
 export class AsyncPrivate { async #load() { return 1; } } // @flag
+export class StaticPrivate { static #make() { return 1; } } // @flag
 export class CallsPrivate { run() { this.#compute(); } } // @flag
+export class CallsPrivateOptionally { run() { this.#compute?.(); } } // @flag

package/lint/__fixtures__/no-js-private-class-method/good.tsx

@@ -1,3 +1,4 @@
-export class TypescriptPrivate { private _compute() { return 1; } } // @ok
-export class CallsUnderscore { run() { this._compute(); } } // @ok
+export class TypescriptPrivate { private compute() { return 1; } } // @ok
+export class CallsTypescriptPrivate { run() { this.compute(); } } // @ok
 export class PrivateField { #cache = new Map(); } // @ok
+export class CallsOnAPrivateField { #cache = new Map<string, number>(); run() { return this.#cache.get("a"); } } // @ok

package/lint/no-daisyui-legacy-class.grit

@@ -9,8 +9,10 @@ language js(typescript, jsx)
 // Tailwind or app classes (`card`, `input`, `badge`, `btn`, `divider`) are deliberately not
 // flagged, and colour slots that survived into the semantic vocabulary (`primary`, `info`,
 // `success`, `warning`, `neutral`) are not either — only the slots the vocabulary dropped.
-// Biome keeps only the first diagnostic a single plugin registers on a node, so a string
-// carrying both halves reports the component one and surfaces the colour one on the next run.
+// A component name is a warning: an app's own CSS may define `stat-value`, which this rule cannot read, and
+// `akan verify` drops it when the app's or a lib's stylesheet does (cli verifyStyleClasses.ts).
+// Biome keeps only the first diagnostic a single plugin registers on a node, so the colour slot, an error, is
+// tried first: a string carrying both halves reports it, and the component warning surfaces on the next run.
 or {
   JsxString() as $s,
   JsStringLiteralExpression() as $s,
@@ -18,19 +20,19 @@ or {
 } where {
   any {
     and {
-      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:btn-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|link|outline|square|circle|wide|block|xs|sm|md|lg)|badge-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|outline)|alert-(?:info|success|warning|error)|input-(?:bordered|primary|secondary|accent|ghost|error)|select-(?:bordered|primary|ghost)|textarea-(?:bordered|primary|ghost)|checkbox-(?:primary|secondary|accent)|toggle-(?:primary|secondary|accent)|loading-(?:spinner|dots|ring|ball|bars|infinity)|card-(?:body|title|actions)|modal-(?:box|action|backdrop)|collapse-(?:title|content|arrow|plus)|dropdown-(?:content|end|start|hover)|stat-(?:title|value|desc)|tabs-(?:boxed|lifted|bordered)|tab-active|menu-(?:title|dropdown)|steps-(?:horizontal|vertical)|join-item|mockup-(?:code|phone|browser|window)|drawer-(?:side|content|toggle))(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:bg|text|border(?:-[tblrxy])?(?:-[se])?|ring(?:-offset)?|fill|stroke|shadow|from|to|via|divide|outline|decoration|placeholder|caret|accent)-(?:base-(?:100|200|300|content)|(?:primary|secondary|accent|neutral|info|success|warning|error)-content|error)(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
       register_diagnostic(
         span = $s,
-        message = "daisyUI legacy class - daisyUI was removed, so this renders unstyled. Use akanjs/ui components and recipes (Button, buttonRecipe, badgeRecipe, ...) with semantic tokens instead.",
+        message = "daisyUI colour slot - the closed colour vocabulary has no CSS for it, so this renders unstyled. base-100/200/300 -> background/muted/border, base-content -> foreground, <colour>-content -> <colour>-foreground, error -> destructive.",
         severity = "error"
       )
     },
     and {
-      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:bg|text|border(?:-[tblrxy])?(?:-[se])?|ring(?:-offset)?|fill|stroke|shadow|from|to|via|divide|outline|decoration|placeholder|caret|accent)-(?:base-(?:100|200|300|content)|(?:primary|secondary|accent|neutral|info|success|warning|error)-content|error)(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:btn-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|link|outline|square|circle|wide|block|xs|sm|md|lg)|badge-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|outline)|alert-(?:info|success|warning|error)|input-(?:bordered|primary|secondary|accent|ghost|error)|select-(?:bordered|primary|ghost)|textarea-(?:bordered|primary|ghost)|checkbox-(?:primary|secondary|accent)|toggle-(?:primary|secondary|accent)|loading-(?:spinner|dots|ring|ball|bars|infinity)|card-(?:body|title|actions)|modal-(?:box|action|backdrop)|collapse-(?:title|content|arrow|plus)|dropdown-(?:content|end|start|hover)|stat-(?:title|value|desc)|tabs-(?:boxed|lifted|bordered)|tab-active|menu-(?:title|dropdown)|steps-(?:horizontal|vertical)|join-item|mockup-(?:code|phone|browser|window)|drawer-(?:side|content|toggle))(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
       register_diagnostic(
         span = $s,
-        message = "daisyUI colour slot - the closed colour vocabulary has no CSS for it, so this renders unstyled. base-100/200/300 -> background/muted/border, base-content -> foreground, <colour>-content -> <colour>-foreground, error -> destructive.",
-        severity = "error"
+        message = "daisyUI legacy class - daisyUI was removed, so this renders unstyled unless your own CSS defines it. Otherwise use akanjs/ui components and recipes (Button, buttonRecipe, badgeRecipe, ...) with semantic tokens instead.",
+        severity = "warn"
       )
     }
   }

package/lint/no-deep-internal-import.grit

@@ -19,7 +19,7 @@ or {
     $source <: r"\"\.\./\.\./.*\"",
     register_diagnostic(
       span = $source,
-      message = "Module files should not import from two or more parent directories."
+      message = "Module files should not import from two or more parent directories. Import from the layer barrel instead: @apps/<app>/<layer> or @libs/<lib>/<layer>."
     )
   },
   JsModuleSource() as $source where {

package/lint/no-js-private-class-method.grit

@@ -1,42 +1,23 @@
 engine biome(1.0)
 language js(typescript, jsx)
 
+// No rewrite: one node's rewrite cannot rename every reference, skip a taken name, or leave a `#field` alone, so
+// `akan verify` renames a class's `#method`s and their calls in one pass instead (cli verifyPrivateMethods.ts).
+// A call is matched by its callee, so `this.#cache.get()` on a `#private` field is not a private method call.
 or {
   JsMethodClassMember() as $method where {
-    $method <: contains JsPrivateClassMemberName() as $name,
-    $method <: r"async\s+#",
-    $method <: contains `async` as $asyncToken,
-    $name <: r"#(.*)"($bareName),
-    $privateName = join(list = ["_", $bareName], separator = ""),
+    $method <: contains JsPrivateClassMemberName(),
     register_diagnostic(
       span = $method,
-      message = "JavaScript private class methods (#) should not be used in mixin-enabled modules. Use a TypeScript private method with an underscore prefix instead.",
+      message = "A `#private` method breaks once this class is mixed into another. Use a TypeScript `private` method, `private name()` called as `this.name()`; `akan verify` renames it unless the class already has that name.",
       severity = "error"
-    ),
-    $asyncToken => `private async`,
-    $name => $privateName
+    )
   },
-  JsMethodClassMember() as $method where {
-    $method <: contains JsPrivateClassMemberName() as $name,
-    not $method <: r"async\s+#",
-    $name <: r"#(.*)"($bareName),
-    $privateName = join(list = ["private _", $bareName], separator = ""),
-    register_diagnostic(
-      span = $method,
-      message = "JavaScript private class methods (#) should not be used in mixin-enabled modules. Use a TypeScript private method with an underscore prefix instead.",
-      severity = "error"
-    ),
-    $name => $privateName
-  },
-  JsCallExpression() as $call where {
-    $call <: contains JsPrivateName() as $name,
-    $name <: r"#(.*)"($bareName),
-    $privateName = join(list = ["_", $bareName], separator = ""),
+  JsCallExpression(callee = JsStaticMemberExpression(member = JsPrivateName())) as $call where {
     register_diagnostic(
       span = $call,
-      message = "Calls to JavaScript private class methods (#) should use the underscore-prefixed TypeScript private method.",
+      message = "A call to a `#private` method: call the TypeScript `private` method that replaces it, `this.name()`.",
       severity = "error"
-    ),
-    $name => $privateName
+    )
   }
 }

package/maintainabilityBaseline.ts

@@ -16,14 +16,16 @@ export interface BaselineEntry {
 
 type Counts = ReadonlyMap<string, number>;
 
-//* One section per rule, each key holding what the gate measured: lines, store accesses, writes or calls. A count
-//* only falls, so a recorded entry cannot take on more of the debt it records.
+//* One section per rule, each key holding what the gate measured: lines, members, store accesses, writes or calls.
+//* 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";
   static readonly reasonMinChars = 10;
   static readonly debtRules = [
     "akan.size.file",
     "akan.size.component",
+    "akan.size.function",
+    "akan.size.class",
     "akan.component.store-access",
     "akan.store.multi-write",
     "akan.store.root-write-chain",
@@ -34,12 +36,15 @@ export class MaintainabilityBaseline {
   static readonly reasonedRules: ReadonlySet<DebtRuleId> = new Set([
     "akan.size.file",
     "akan.size.component",
+    "akan.size.function",
+    "akan.size.class",
     "akan.component.store-access",
     "akan.service.call-in-loop",
   ]);
 
   static countOf(violation: MaintainabilityViolation) {
     if (violation.kind === "size") return violation.lineCount;
+    if (violation.kind === "classSize") return violation.memberCount;
     if (violation.kind === "storeAccess") return violation.accessCount;
     if (violation.kind === "multiWrite") return violation.writeCount;
     if (violation.kind === "writePlacement") return violation.writes.length;

package/maintainabilityContract.test.ts

@@ -498,6 +498,8 @@ describe("MaintainabilityContract rules", () => {
     expect(MaintainabilityContract.ruleIds).toEqual([
       "akan.size.file",
       "akan.size.component",
+      "akan.size.function",
+      "akan.size.class",
       "akan.store.multi-write",
       "akan.store.root-write-chain",
       "akan.component.write-chain",
@@ -844,3 +846,184 @@ export class CourtEndpoint extends endpoint(srv.court, ({ mutation }) => ({
     expect(await contractOf(root).enforce({ fix: false })).toEqual([]);
   });
 });
+
+describe("MaintainabilityContract packages", () => {
+  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`;
+  const classOf = (name: string, memberNum: number) =>
+    `export class ${name} {\n${Array.from({ length: memberNum }, (_, idx) => `  field${idx} = ${idx};`).join("\n")}\n}\n`;
+
+  test("holds a package file to 800 lines, a function to 150 and a class to 60 members, tests and barrels aside", async () => {
+    const root = await makeWorkspace({
+      "pkgs/@demo/core/server/host.ts": `${classOf("Host", 61)}${functionOf("boot", 151)}${linesOf(600)}`,
+      "pkgs/@demo/core/server/atLimit.ts": `${classOf("Small", 60)}${functionOf("fits", 150)}${linesOf(800 - 212)}\n`,
+      "pkgs/@demo/core/server/host.test.ts": `${functionOf("suite", 900)}`,
+      "pkgs/@demo/core/server/host.fixture.ts": `${functionOf("fixture", 900)}`,
+      "pkgs/@demo/core/server/host.instance.ts": `${functionOf("instance", 900)}`,
+      "pkgs/@demo/core/test/helpers.ts": `${functionOf("helper", 900)}`,
+      "pkgs/@demo/core/types.d.ts": linesOf(900),
+      "pkgs/@demo/core/index.ts": Array.from({ length: 801 }, (_, idx) => `export * from "./m${idx}";`).join("\n"),
+    });
+
+    expect(await packageOf(root).measure()).toEqual([
+      {
+        kind: "size",
+        rule: "akan.size.file",
+        key: "server/host.ts",
+        file: "server/host.ts",
+        line: 1,
+        lineCount: 814,
+        maxLines: 800,
+      },
+      {
+        kind: "size",
+        rule: "akan.size.function",
+        key: "server/host.ts#boot",
+        file: "server/host.ts",
+        line: 64,
+        lineCount: 151,
+        maxLines: 150,
+        function: "boot",
+      },
+      {
+        kind: "classSize",
+        rule: "akan.size.class",
+        key: "server/host.ts#Host",
+        file: "server/host.ts",
+        line: 1,
+        owner: "Host",
+        memberCount: 61,
+        maxMembers: 60,
+      },
+    ]);
+  });
+
+  test("reads a package in a repository through git, so ignored output is never measured", async () => {
+    const root = await makeWorkspace({
+      ".gitignore": "**/dist\n",
+      "pkgs/@demo/core/dist/bundle.ts": linesOf(900),
+      "pkgs/@demo/core/server/committed.ts": linesOf(801),
+    });
+    await commitAll(root);
+    await writeText(path.join(root, "pkgs/@demo/core/server/untracked.ts"), linesOf(802));
+
+    expect((await packageOf(root).measure()).map(({ key }) => key)).toEqual([
+      "server/committed.ts",
+      "server/untracked.ts",
+    ]);
+  });
+
+  test("measures nothing in a package git ignores whole, and leaves a package's examples out", async () => {
+    const root = await makeWorkspace({
+      ".gitignore": "pkgs/gen/\n",
+      "pkgs/gen/package.json": "{}\n",
+      "pkgs/gen/big.ts": functionOf("generated", 162),
+      "pkgs/@demo/core/examples/sample/src/selftest.ts": functionOf("runSelftest", 900),
+    });
+    await commitAll(root);
+
+    expect(await new MaintainabilityContract(root, { type: "pkg", name: "gen" }).measure()).toEqual([]);
+    expect(await packageOf(root).measure()).toEqual([]);
+  });
+
+  test("numbers only the breaches sharing a name, so a short function above leaves a recorded key in place", async () => {
+    const callbackOf = (receiver: string, lineNum: number) => `${receiver}.map(() => {\n${linesOf(lineNum - 2)}\n});\n`;
+    const root = await makeWorkspace({
+      "pkgs/@demo/core/run.ts": `ys.map(() => 1);\n${callbackOf("xs", 160)}${callbackOf("zs", 170)}`,
+    });
+
+    expect((await packageOf(root).measure()).map(({ key }) => key)).toEqual(["run.ts#map()", "run.ts#map()[2]"]);
+  });
+
+  test("records a package's breaches in its own baseline, which only shrinks from the default branch", async () => {
+    const root = await makeWorkspace({ "pkgs/@demo/core/server/host.ts": functionOf("boot", 200) });
+
+    expect((await packageOf(root).seed()).result).toBe("written");
+    expect(await readFile(path.join(root, "pkgs/@demo/core/akan.baseline.json"), "utf8")).toBe(
+      '{\n  "akan.size.function": {\n    "server/host.ts#boot": 200\n  }\n}\n',
+    );
+    await commitAll(root);
+    await writeText(path.join(root, "pkgs/@demo/core/server/host.ts"), functionOf("boot", 210));
+
+    const contract = packageOf(root);
+    const failures = await contract.enforce({ fix: false });
+
+    expect(failures).toMatchObject([{ rule: "akan.size.function", key: "server/host.ts#boot", recorded: 200 }]);
+    expect(contract.describe(failures)).toBe(
+      "[maintainability] 1 violation(s) in pkgs/@demo/core:\n" +
+        "  pkgs/@demo/core/server/host.ts:1  akan.size.function  function boot has 210 lines, over the 150-line limit, up from 200\n" +
+        "How to fix:\n" +
+        "  function: Split it by family into named functions or a collaborator class, each under the limit, keeping its signature for callers.",
+    );
+  });
+});
+
+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`;
+  const host = "pkgs/@demo/core/server/host.ts";
+  const writePackageBaseline = async (root: string, json: object) =>
+    await writeText(path.join(root, "pkgs/@demo/core/akan.baseline.json"), `${JSON.stringify(json, null, 2)}\n`);
+
+  test("refuses an entry for debt the fork point's code did not hold, unless a person gave it a reason", async () => {
+    const root = await makeWorkspace({ [host]: functionOf("boot", 100) });
+    await commitAll(root);
+    await writeText(path.join(root, host), functionOf("boot", 200));
+    await writePackageBaseline(root, { "akan.size.function": { "server/host.ts#boot": 200 } });
+
+    const contract = packageOf(root);
+    const failures = await contract.enforce({ fix: false });
+
+    expect(failures).toMatchObject([
+      { kind: "baselineGrowth", key: "server/host.ts#boot", count: 200, committed: undefined, measured: true, line: 3 },
+    ]);
+    expect(contract.describe(failures)).toMatch(
+      /pkgs\/@demo\/core\/akan\.baseline\.json:3 {2}akan\.baseline\.growth {2}entry "server\/host\.ts#boot" under akan\.size\.function is debt the code at [0-9a-f]{12} does not hold/,
+    );
+
+    await writePackageBaseline(root, {
+      "akan.size.function": { "server/host.ts#boot": 200 },
+      reasons: { "server/host.ts#boot": "One state machine a person chose to keep whole." },
+    });
+    expect(await packageOf(root).enforce({ fix: false })).toEqual([]);
+  });
+
+  test("lets a scope adopt the gate with the debt its code held at the fork point, and no more", async () => {
+    const root = await makeWorkspace({ [host]: functionOf("boot", 200) });
+    await commitAll(root);
+
+    expect((await packageOf(root).seed()).result).toBe("written");
+    expect(await packageOf(root).enforce({ fix: false })).toEqual([]);
+
+    await writeText(path.join(root, host), functionOf("boot", 210));
+    await packageOf(root).seed({ force: true });
+
+    expect(await packageOf(root).enforce({ fix: false })).toMatchObject([
+      { kind: "baselineGrowth", key: "server/host.ts#boot", count: 210, committed: 200, measured: true },
+    ]);
+  });
+
+  test("holds an app new to the branch, or one whose paid-off baseline was removed, to none", async () => {
+    const zone = "apps/demo/lib/court/Court.Zone.tsx";
+    const root = await makeWorkspace({ "apps/other/lib/court/Court.Zone.tsx": linesOf(10) });
+    await commitAll(root);
+    await writeText(path.join(root, zone), linesOf(450));
+    await writeBaseline(root, { "akan.size.file": { "lib/court/Court.Zone.tsx": 450 } });
+
+    expect(await contractOf(root).enforce({ fix: false })).toMatchObject([
+      { kind: "baselineGrowth", key: "lib/court/Court.Zone.tsx", count: 450, committed: undefined, measured: true },
+    ]);
+
+    await writeText(path.join(root, zone), linesOf(400));
+    await contractOf(root).enforce({ fix: true });
+    expect(existsSync(path.join(root, "apps/demo/akan.baseline.json"))).toBe(false);
+    await git(root, "add", "-A");
+    await git(root, "commit", "-q", "-m", "paid off");
+    await writeText(path.join(root, zone), linesOf(450));
+    await writeBaseline(root, { "akan.size.file": { "lib/court/Court.Zone.tsx": 450 } });
+
+    expect(await contractOf(root).enforce({ fix: false })).toMatchObject([
+      { kind: "baselineGrowth", key: "lib/court/Court.Zone.tsx", committed: undefined, measured: true },
+    ]);
+  });
+});