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

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);
+  });
+});

package/maintainabilityBaseline.ts

@@ -0,0 +1,220 @@
+import { JsonFormatter } from "./jsonFormatter";
+import type { DebtRuleId, MaintainabilityViolation } from "./maintainabilityContract";
+
+export interface BaselineEntryGrowth {
+  rule: DebtRuleId;
+  key: string;
+  count: number;
+  committed?: number;
+}
+
+export interface BaselineEntry {
+  key: string;
+  count: number;
+  reason?: string;
+}
+
+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.
+export class MaintainabilityBaseline {
+  static readonly fileName = "akan.baseline.json";
+  static readonly reasonMinChars = 10;
+  static readonly debtRules = [
+    "akan.size.file",
+    "akan.size.component",
+    "akan.component.store-access",
+    "akan.store.multi-write",
+    "akan.store.root-write-chain",
+    "akan.component.write-chain",
+    "akan.write.placement",
+    "akan.service.call-in-loop",
+  ] as const satisfies readonly DebtRuleId[];
+  static readonly reasonedRules: ReadonlySet<DebtRuleId> = new Set([
+    "akan.size.file",
+    "akan.size.component",
+    "akan.component.store-access",
+    "akan.service.call-in-loop",
+  ]);
+
+  static countOf(violation: MaintainabilityViolation) {
+    if (violation.kind === "size") return violation.lineCount;
+    if (violation.kind === "storeAccess") return violation.accessCount;
+    if (violation.kind === "multiWrite") return violation.writeCount;
+    if (violation.kind === "writePlacement") return violation.writes.length;
+    return violation.calls.length;
+  }
+
+  static isDebtRule(name: string): name is DebtRuleId {
+    return (MaintainabilityBaseline.debtRules as readonly string[]).includes(name);
+  }
+
+  //? `lenient` reads another commit's copy, whose sections an older or newer CLI may have named differently.
+  static parse(
+    text: string,
+    source = MaintainabilityBaseline.fileName,
+    { lenient = false }: { lenient?: boolean } = {},
+  ) {
+    let json: unknown;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      throw new Error(`${source} is not valid JSON.`);
+    }
+    if (typeof json !== "object" || json === null || Array.isArray(json))
+      throw new Error(`${source} holds an object keyed by rule id.`);
+    const sections = new Map<DebtRuleId, Counts>();
+    let reasons = new Map<string, string>();
+    for (const [name, value] of Object.entries(json)) {
+      if (name === "reasons") {
+        const entries = MaintainabilityBaseline.#reasonsOf(value);
+        if (!entries) throw new Error(`${source}: "reasons" maps an entry's key to a sentence.`);
+        reasons = new Map(entries);
+        continue;
+      }
+      if (!MaintainabilityBaseline.isDebtRule(name)) {
+        if (lenient) continue;
+        throw new Error(
+          `${source}: "${name}" is not a rule id. Its sections are ${MaintainabilityBaseline.debtRules.join(", ")} and "reasons"; rewrite it with \`akan quality baseline --force\`.`,
+        );
+      }
+      const counts = MaintainabilityBaseline.#countsOf(value);
+      if (!counts) throw new Error(`${source}: "${name}" maps each key to a whole-number count.`);
+      sections.set(name, new Map(counts));
+    }
+    return new MaintainabilityBaseline(sections, reasons);
+  }
+
+  static of(violations: MaintainabilityViolation[], reasons: ReadonlyMap<string, string> = new Map()) {
+    const sections = new Map<DebtRuleId, Map<string, number>>();
+    for (const violation of violations) {
+      const counts = sections.get(violation.rule) ?? new Map<string, number>();
+      const count = MaintainabilityBaseline.countOf(violation);
+      counts.set(violation.key, Math.max(counts.get(violation.key) ?? 0, count));
+      sections.set(violation.rule, counts);
+    }
+    return new MaintainabilityBaseline(sections).#withReasonsOf(reasons);
+  }
+
+  constructor(
+    readonly sections: ReadonlyMap<DebtRuleId, Counts> = new Map(),
+    readonly reasons: ReadonlyMap<string, string> = new Map(),
+  ) {}
+
+  get isEmpty() {
+    return [...this.sections.values()].every((counts) => !counts.size);
+  }
+
+  allows(violation: MaintainabilityViolation) {
+    const recorded = this.recordedOf(violation);
+    return recorded !== undefined && MaintainabilityBaseline.countOf(violation) <= recorded;
+  }
+
+  recordedOf(violation: MaintainabilityViolation) {
+    return this.sections.get(violation.rule)?.get(violation.key);
+  }
+
+  reasonOf(key: string) {
+    const reason = this.#holdsReasoned(key) ? this.reasons.get(key) : undefined;
+    return reason && reason.replace(/\s/g, "").length >= MaintainabilityBaseline.reasonMinChars ? reason : undefined;
+  }
+
+  entriesByRule() {
+    return new Map(
+      [...this.sections]
+        .filter(([, counts]) => counts.size)
+        .map(([rule, counts]): [DebtRuleId, BaselineEntry[]] => [
+          rule,
+          [...counts].map(([key, count]) => ({
+            key,
+            count,
+            reason: MaintainabilityBaseline.reasonedRules.has(rule) ? this.reasonOf(key) : undefined,
+          })),
+        ]),
+    );
+  }
+
+  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()),
+      ]),
+    );
+    return new MaintainabilityBaseline(sections).#withReasonsOf(this.reasons);
+  }
+
+  #withReasonsOf(reasons: ReadonlyMap<string, string>) {
+    return new MaintainabilityBaseline(
+      this.sections,
+      new Map([...reasons].filter(([key]) => this.#holdsReasoned(key))),
+    );
+  }
+
+  //* 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 })),
+    );
+  }
+
+  stringify() {
+    const sections = MaintainabilityBaseline.debtRules.flatMap((rule) => {
+      const counts = this.sections.get(rule);
+      return counts?.size ? [[rule, MaintainabilityBaseline.#sortedObjectOf(counts)] as const] : [];
+    });
+    return JsonFormatter.stringify(
+      {
+        ...Object.fromEntries(sections),
+        ...(this.reasons.size ? { reasons: MaintainabilityBaseline.#sortedObjectOf(this.reasons) } : {}),
+      },
+      MaintainabilityBaseline.fileName,
+    );
+  }
+
+  #holdsReasoned(key: string) {
+    return [...this.sections].some(
+      ([rule, counts]) => MaintainabilityBaseline.reasonedRules.has(rule) && counts.has(key),
+    );
+  }
+
+  static #countsOf(value: unknown) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+    const entries = Object.entries(value);
+    return entries.every(([, count]) => Number.isInteger(count)) ? (entries as [string, number][]) : null;
+  }
+
+  static #reasonsOf(value: unknown) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+    const entries = Object.entries(value);
+    return entries.every(([, reason]) => typeof reason === "string") ? (entries as [string, string][]) : null;
+  }
+
+  static #lowered(recorded: Counts, current: Counts) {
+    return new Map(
+      [...recorded].flatMap(([key, count]) => {
+        const measured = current.get(key);
+        return measured === undefined ? [] : [[key, Math.min(count, measured)] as const];
+      }),
+    );
+  }
+
+  static #raised(working: Counts, committed: Counts) {
+    return [...working].flatMap(([key, count]) => {
+      const recorded = committed.get(key);
+      return recorded !== undefined && count <= recorded ? [] : [[key, count, recorded] as const];
+    });
+  }
+
+  static #sortedObjectOf<T>(values: ReadonlyMap<string, T>) {
+    return Object.fromEntries([...values].sort(([a], [b]) => MaintainabilityBaseline.#byKey(a, b)));
+  }
+
+  static #byKey(a: string, b: string) {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+}