@akanjs/devkit 3.1.1-rc.8 → 3.1.1

package/maintainabilityContract.ts

@@ -0,0 +1,404 @@
+import { existsSync } from "node:fs";
+import { readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import ts from "typescript";
+import { ComponentSizeScanner } from "./componentSizeScanner";
+import { ComponentWriteChainScanner } from "./componentWriteChainScanner";
+import { EndpointReach } from "./endpointReach";
+import { MaintainabilityBaseline } from "./maintainabilityBaseline";
+import { MaintainabilityLimits } from "./maintainabilityLimits";
+import { MaintainabilityReport } from "./maintainabilityReport";
+import type { SourceFileInfo } from "./qualityScanner";
+import { ServiceLoopCallScanner } from "./serviceLoopCallScanner";
+import { SignalMutationIndex } from "./signalMutationIndex";
+import { StoreAccessScanner } from "./storeAccessScanner";
+import { StoreWriteScanner } from "./storeWriteScanner";
+import { WritePlacementScanner } from "./writePlacementScanner";
+import { WritingActionIndex } from "./writingActionIndex";
+
+export interface MaintainabilityScope {
+  type: "app" | "lib";
+  name: string;
+}
+
+export type MaintainabilityRuleId = (typeof MaintainabilityContract.ruleIds)[number];
+export type DebtRuleId = Exclude<MaintainabilityRuleId, "akan.baseline.growth">;
+export type MaintainabilityCommands = { [rule in MaintainabilityRuleId]?: readonly string[] };
+
+export interface SizeViolation {
+  kind: "size";
+  rule: "akan.size.file" | "akan.size.component";
+  key: string;
+  file: string;
+  line: number;
+  lineCount: number;
+  maxLines: number;
+  component?: string;
+  recorded?: number;
+}
+
+export interface MultiWriteViolation {
+  kind: "multiWrite";
+  rule: "akan.store.multi-write" | "akan.store.root-write-chain" | "akan.component.write-chain";
+  key: string;
+  file: string;
+  line: number;
+  owner: string;
+  writes: string[];
+  writeCount: number;
+  recorded?: number;
+}
+
+export interface WritePlacementViolation {
+  kind: "writePlacement";
+  rule: "akan.write.placement";
+  key: string;
+  file: string;
+  line: number;
+  writes: string[];
+  recorded?: number;
+}
+
+export interface LoopCallViolation {
+  kind: "loopCall";
+  rule: "akan.service.call-in-loop";
+  key: string;
+  file: string;
+  line: number;
+  owner: string;
+  calls: string[];
+  recorded?: number;
+}
+
+export interface StoreAccessViolation {
+  kind: "storeAccess";
+  rule: "akan.component.store-access";
+  key: string;
+  file: string;
+  line: number;
+  component: string;
+  accessCount: number;
+  maxAccesses: number;
+  recorded?: number;
+}
+
+export interface BaselineGrowth {
+  kind: "baselineGrowth";
+  rule: "akan.baseline.growth";
+  key: string;
+  file: string;
+  line: number;
+  debtRule: DebtRuleId;
+  count: number;
+  committed?: number;
+  reference: string;
+}
+
+export type MaintainabilityViolation =
+  | SizeViolation
+  | MultiWriteViolation
+  | StoreAccessViolation
+  | WritePlacementViolation
+  | LoopCallViolation;
+export type MaintainabilityFailure = MaintainabilityViolation | BaselineGrowth;
+
+export type BaselineSeed = "written" | "kept" | "removed" | "clean";
+
+export class MaintainabilityContract {
+  static readonly ruleIds = [
+    "akan.size.file",
+    "akan.size.component",
+    "akan.store.multi-write",
+    "akan.store.root-write-chain",
+    "akan.component.write-chain",
+    "akan.component.store-access",
+    "akan.write.placement",
+    "akan.service.call-in-loop",
+    "akan.baseline.growth",
+  ] as const;
+  static readonly #measuredFiles = "{lib,ui,webkit,srvkit,common,plugin}/**/*.{ts,tsx,md}";
+  static readonly #defaultBranches = ["upstream/HEAD", "upstream/main", "origin/HEAD", "origin/main", "main", "master"];
+  readonly #workspaceRoot: string;
+  readonly #scope: MaintainabilityScope;
+  readonly #libNames: string[];
+
+  constructor(workspaceRoot: string, scope: MaintainabilityScope, libNames: string[] = []) {
+    this.#workspaceRoot = workspaceRoot;
+    this.#scope = scope;
+    this.#libNames = libNames.filter((libName) => scope.type === "app" || libName !== scope.name);
+  }
+
+  get sysPath() {
+    return `${this.#scope.type}s/${this.#scope.name}`;
+  }
+
+  get baselinePath() {
+    return path.join(this.#workspaceRoot, this.sysPath, MaintainabilityBaseline.fileName);
+  }
+
+  async measure(): Promise<MaintainabilityViolation[]> {
+    const [signalFiles, storeFiles, serviceFiles] = await Promise.all([
+      this.#reachedSources("lib/**/*.signal.ts"),
+      this.#reachedSources("lib/**/*.store.ts"),
+      this.#reachedSources("lib/**/*.service.ts"),
+    ]);
+    const index = new WritingActionIndex(new SignalMutationIndex(signalFiles), storeFiles);
+    const reach = new EndpointReach(signalFiles, serviceFiles);
+    const files = await MaintainabilityContract.#filesUnder(
+      path.join(this.#workspaceRoot, this.sysPath),
+      MaintainabilityContract.#measuredFiles,
+    );
+    const violations = await Promise.all(files.map((file) => this.#measureFile(file, index, reach)));
+    return violations.flat().sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
+  }
+
+  async enforce({ fix }: { fix: boolean }): Promise<MaintainabilityFailure[]> {
+    const [violations, existing, reference] = await Promise.all([
+      this.measure(),
+      this.#readBaseline(),
+      this.#readReferenceBaseline(),
+    ]);
+    const baseline =
+      existing === null ? new MaintainabilityBaseline() : MaintainabilityBaseline.parse(existing, this.baselinePath);
+    const tightened = baseline.tightenedBy(violations);
+    if (fix && existing !== null) await this.#tighten(baseline, tightened);
+    const failures: MaintainabilityFailure[] = violations
+      .filter((violation) => !baseline.allows(violation))
+      .map((violation) => {
+        const recorded = baseline.recordedOf(violation);
+        return recorded === undefined ? violation : { ...violation, recorded };
+      });
+    if (reference === null) return failures;
+    const lines = ((await this.#readBaseline()) ?? "").split(/\r?\n/);
+    const label = `${reference.ref}:${this.sysPath}/${MaintainabilityBaseline.fileName}`;
+    //? Without fix the file on disk is what merges, so an entry it holds above the measured count is checked as written.
+    const growths = (fix ? tightened : baseline)
+      .grownFrom(MaintainabilityBaseline.parse(reference.text, label, { lenient: true }))
+      .map(
+        ({ rule, ...growth }): BaselineGrowth => ({
+          kind: "baselineGrowth",
+          rule: "akan.baseline.growth",
+          file: MaintainabilityBaseline.fileName,
+          line: MaintainabilityContract.#lineOf(lines, rule, growth.key),
+          debtRule: rule,
+          reference: reference.ref,
+          ...growth,
+        }),
+      )
+      .sort((a, b) => a.line - b.line);
+    return [...growths, ...failures];
+  }
+
+  async seed({ force = false }: { force?: boolean } = {}): Promise<{
+    result: BaselineSeed;
+    violations: MaintainabilityViolation[];
+  }> {
+    const violations = await this.measure();
+    const exists = existsSync(this.baselinePath);
+    if (exists && !force) return { result: "kept", violations };
+    const next = MaintainabilityBaseline.of(violations, MaintainabilityContract.#reasonsIn(await this.#readBaseline()));
+    if (!next.isEmpty) await writeFile(this.baselinePath, next.stringify());
+    else if (exists) await rm(this.baselinePath, { force: true });
+    return { result: next.isEmpty ? (exists ? "removed" : "clean") : "written", violations };
+  }
+
+  describe(failures: MaintainabilityFailure[], commands?: MaintainabilityCommands) {
+    return MaintainabilityReport.describe(this.sysPath, failures, commands);
+  }
+
+  async #measureFile(
+    file: string,
+    index: WritingActionIndex,
+    reach: EndpointReach,
+  ): Promise<MaintainabilityViolation[]> {
+    const maxLines = MaintainabilityLimits.fileMaxLinesOf(file);
+    const isStore = file.endsWith(".store.ts");
+    const isService = file.endsWith(".service.ts");
+    const isClientCode = MaintainabilityLimits.isClientCode(file);
+    if (!maxLines && !isStore && !isClientCode) return [];
+    const workspaceFile = `${this.sysPath}/${file}`;
+    const content = await readFile(path.join(this.#workspaceRoot, workspaceFile), "utf8");
+    const violations: MaintainabilityViolation[] = [];
+    const lineCount = MaintainabilityLimits.lineCountOf(content);
+    if (maxLines && lineCount > maxLines && !MaintainabilityLimits.isReexportBarrel(file, content))
+      violations.push({ kind: "size", rule: "akan.size.file", key: file, file, line: 1, lineCount, maxLines });
+    if (!isStore && !isService && !isClientCode) return violations;
+    const source = this.#sourceOf(workspaceFile, content);
+    if (isClientCode) violations.push(...MaintainabilityContract.#measureClientCode(file, source, index));
+    if (isStore)
+      for (const { action, line, writes, writeCount, isRootChain } of new StoreWriteScanner(index).scan(source))
+        violations.push({
+          kind: "multiWrite",
+          rule: isRootChain ? "akan.store.root-write-chain" : "akan.store.multi-write",
+          key: `${file}#${action}`,
+          file,
+          line,
+          owner: action,
+          writes,
+          writeCount,
+        });
+    if (isService)
+      for (const { method, line, calls } of new ServiceLoopCallScanner().scan(source.sourceFile, (method) =>
+        reach.reaches(EndpointReach.serviceOf(file), method),
+      ))
+        violations.push({
+          kind: "loopCall",
+          rule: "akan.service.call-in-loop",
+          key: `${file}#${method}`,
+          file,
+          line,
+          owner: method,
+          calls,
+        });
+    return violations;
+  }
+
+  static #measureClientCode(
+    file: string,
+    { file: workspaceFile, sourceFile }: SourceFileInfo,
+    index: WritingActionIndex,
+  ) {
+    const violations: MaintainabilityViolation[] = [];
+    const placement = new WritePlacementScanner(index).scan(file, workspaceFile, sourceFile);
+    if (placement)
+      violations.push({ kind: "writePlacement", rule: "akan.write.placement", key: file, file, ...placement });
+    for (const component of new ComponentSizeScanner().measure(sourceFile))
+      if (component.lineCount > MaintainabilityLimits.componentMaxLines)
+        violations.push({
+          kind: "size",
+          rule: "akan.size.component",
+          key: `${file}#${component.name}`,
+          file,
+          line: component.line,
+          lineCount: component.lineCount,
+          maxLines: MaintainabilityLimits.componentMaxLines,
+          component: component.name,
+        });
+    for (const { component, line, writes, writeCount } of new ComponentWriteChainScanner(index).scan(sourceFile))
+      violations.push({
+        kind: "multiWrite",
+        rule: "akan.component.write-chain",
+        key: `${file}#${component}`,
+        file,
+        line,
+        owner: component,
+        writes,
+        writeCount,
+      });
+    for (const { component, line, accessCount } of new StoreAccessScanner(index).measure(sourceFile))
+      if (accessCount > MaintainabilityLimits.componentMaxStoreAccesses)
+        violations.push({
+          kind: "storeAccess",
+          rule: "akan.component.store-access",
+          key: `${file}#${component}`,
+          file,
+          line,
+          component,
+          accessCount,
+          maxAccesses: MaintainabilityLimits.componentMaxStoreAccesses,
+        });
+    return violations;
+  }
+
+  async #reachedSources(pattern: string) {
+    const roots = [this.sysPath, ...this.#libNames.map((libName) => `libs/${libName}`)];
+    const files = await Promise.all(
+      roots.map(async (root) =>
+        (await MaintainabilityContract.#filesUnder(path.join(this.#workspaceRoot, root), pattern)).map(
+          (file) => `${root}/${file}`,
+        ),
+      ),
+    );
+    return await Promise.all(
+      files
+        .flat()
+        .map(async (file) => this.#sourceOf(file, await readFile(path.join(this.#workspaceRoot, file), "utf8"))),
+    );
+  }
+
+  #sourceOf(file: string, content: string): SourceFileInfo {
+    const scriptKind = file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+    return {
+      file,
+      absolutePath: path.join(this.#workspaceRoot, file),
+      content,
+      sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, scriptKind),
+    };
+  }
+
+  async #readBaseline() {
+    return existsSync(this.baselinePath) ? await readFile(this.baselinePath, "utf8") : null;
+  }
+
+  //? `./` resolves the path from the workspace root, which may sit below the repository root.
+  async #readReferenceBaseline() {
+    const ref = await this.#referenceRef();
+    const text = await this.#git(["show", `${ref}:./${this.sysPath}/${MaintainabilityBaseline.fileName}`]);
+    return text === null ? null : { ref: ref === "HEAD" ? ref : ref.slice(0, 12), text };
+  }
+
+  //* A branch's own commits cannot be the reference: one that raises an entry would make the raise the new floor.
+  //* The fork point from the default branch holds still, whatever the branch commits.
+  //* Without that history the only copy left is the branch's own, so a shallow checkout fails instead of passing.
+  async #referenceRef() {
+    for (const branch of MaintainabilityContract.#defaultBranches) {
+      if ((await this.#git(["rev-parse", "--verify", "--quiet", `${branch}^{commit}`])) === null) continue;
+      const forkPoint = (await this.#git(["merge-base", "HEAD", branch]))?.trim();
+      if (forkPoint) return forkPoint;
+      throw new Error(MaintainabilityContract.#missingHistory(this.sysPath, `HEAD shares no commit with ${branch}`));
+    }
+    if ((await this.#git(["rev-parse", "--is-shallow-repository"]))?.trim() === "true")
+      throw new Error(MaintainabilityContract.#missingHistory(this.sysPath, "this is a shallow clone"));
+    return "HEAD";
+  }
+
+  static #missingHistory(sysPath: string, cause: string) {
+    return (
+      `${sysPath}/${MaintainabilityBaseline.fileName} is compared with its copy where this branch forked from the default branch, ` +
+      `but ${cause}. Fetch the default branch with its history (in GitHub Actions, actions/checkout with fetch-depth: 0).`
+    );
+  }
+
+  async #git(args: string[]) {
+    try {
+      const proc = Bun.spawn(["git", ...args], { cwd: this.#workspaceRoot, stdout: "pipe", stderr: "ignore" });
+      const [text, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+      return exitCode === 0 ? text : null;
+    } catch {
+      return null;
+    }
+  }
+
+  static #reasonsIn(text: string | null) {
+    if (text === null) return new Map<string, string>();
+    try {
+      return MaintainabilityBaseline.parse(text, MaintainabilityBaseline.fileName, { lenient: true }).reasons;
+    } catch {
+      //? A file too broken to read is what `--force` replaces; its reasons go with it.
+      return new Map<string, string>();
+    }
+  }
+
+  async #tighten(current: MaintainabilityBaseline, next: MaintainabilityBaseline) {
+    if (next.isEmpty) await rm(this.baselinePath, { force: true });
+    else if (next.stringify() !== current.stringify()) await writeFile(this.baselinePath, next.stringify());
+  }
+
+  static #lineOf(lines: string[], rule: DebtRuleId, key: string) {
+    const from = Math.max(
+      lines.findIndex((line) => line.includes(`${JSON.stringify(rule)}:`)),
+      0,
+    );
+    const idx = lines.findIndex((line, lineIdx) => lineIdx >= from && line.includes(`${JSON.stringify(key)}:`));
+    return Math.max(idx + 1, 1);
+  }
+
+  static async #filesUnder(root: string, pattern: string) {
+    if (!existsSync(root)) return [];
+    const files = await Array.fromAsync(new Bun.Glob(pattern).scan({ cwd: root, onlyFiles: true }));
+    return files
+      .map((file) => file.split(path.sep).join("/"))
+      .filter((file) => !file.includes("node_modules/"))
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  }
+}

package/maintainabilityExceptionScanner.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { MaintainabilityExceptionScanner } from "./maintainabilityExceptionScanner";
+import { tempDirs, writeText } from "./testHelpers";
+
+const makeTempRoot = tempDirs("akan-maintainability-exceptions-");
+
+const makeWorkspace = async (files: Record<string, string>) => {
+  const root = await makeTempRoot();
+  for (const [filePath, content] of Object.entries(files)) await writeText(path.join(root, filePath), content);
+  return root;
+};
+
+const baselineOf = (json: object) => `${JSON.stringify(json, null, 2)}\n`;
+const reason = "The court canvas is one pointer state machine.";
+
+describe("MaintainabilityExceptionScanner", () => {
+  test("warns once per app or lib and rule, counting reasoned exceptions apart from adopted debt", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/akan.baseline.json": baselineOf({
+        "akan.size.file": {
+          "lib/court/Court.Zone.tsx": 450,
+          "ui/Board.tsx": 420,
+          "webkit/useBoard.tsx": 410,
+        },
+        "akan.size.component": { "lib/court/Court.Zone.tsx#Canvas": 300 },
+        "akan.component.store-access": { "lib/court/Court.Zone.tsx#Canvas": 30 },
+        "akan.store.multi-write": { "lib/court/court.store.ts#assign": 2 },
+        "akan.component.write-chain": { "lib/court/Court.Zone.tsx#Install": 2 },
+        "akan.write.placement": { "ui/Board.tsx": 1 },
+        "akan.service.call-in-loop": { "lib/court/court.service.ts#syncAll": 1 },
+        reasons: {
+          "lib/court/Court.Zone.tsx": reason,
+          "ui/Board.tsx": "Generated SVG path table.",
+          "webkit/useBoard.tsx": "too short",
+          "lib/court/court.store.ts#assign": reason,
+          "lib/court/court.service.ts#syncAll": reason,
+        },
+      }),
+      "libs/shared/akan.baseline.json": baselineOf({ "akan.size.file": { "ui/Table.tsx": 500 } }),
+      "libs/util/akan.baseline.json": baselineOf({}),
+      "libs/broken/akan.baseline.json": "{",
+      "apps/clean/main.ts": "export {};\n",
+    });
+
+    const warnings = await new MaintainabilityExceptionScanner().scan(root);
+    const byRule = (file: string, rule: string) =>
+      warnings.find((warning) => warning.file === file && warning.message.includes(`for ${rule}:`));
+
+    expect(warnings.map(({ rule }) => rule).every((rule) => rule === MaintainabilityExceptionScanner.rule)).toBe(true);
+    expect(warnings).toHaveLength(8);
+    expect(byRule("apps/demo/akan.baseline.json", "akan.size.file")).toMatchObject({
+      scope: "file",
+      severity: "warning",
+      line: 3,
+      message:
+        `apps/demo carries 2 reasoned exceptions and 1 adopted-debt entry for akan.size.file: ` +
+        `lib/court/Court.Zone.tsx (${JSON.stringify(reason)}), ui/Board.tsx ("Generated SVG path table."), webkit/useBoard.tsx.`,
+      locations: [
+        { file: "apps/demo/akan.baseline.json", line: 3 },
+        { file: "apps/demo/akan.baseline.json", line: 4 },
+        { file: "apps/demo/akan.baseline.json", line: 5 },
+      ],
+    });
+    expect(byRule("apps/demo/akan.baseline.json", "akan.size.component")?.message).toBe(
+      "apps/demo carries 0 reasoned exceptions and 1 adopted-debt entry for akan.size.component: lib/court/Court.Zone.tsx#Canvas.",
+    );
+    expect(byRule("apps/demo/akan.baseline.json", "akan.component.store-access")?.line).toBe(11);
+    expect(byRule("apps/demo/akan.baseline.json", "akan.component.store-access")?.message).toContain(
+      "0 reasoned exceptions and 1 adopted-debt entry",
+    );
+    expect(byRule("apps/demo/akan.baseline.json", "akan.store.multi-write")?.message).toBe(
+      "apps/demo carries 0 reasoned exceptions and 1 adopted-debt entry for akan.store.multi-write: lib/court/court.store.ts#assign.",
+    );
+    expect(byRule("apps/demo/akan.baseline.json", "akan.component.write-chain")?.message).toContain(
+      "lib/court/Court.Zone.tsx#Install",
+    );
+    expect(byRule("apps/demo/akan.baseline.json", "akan.write.placement")?.message).toBe(
+      "apps/demo carries 0 reasoned exceptions and 1 adopted-debt entry for akan.write.placement: ui/Board.tsx.",
+    );
+    expect(byRule("apps/demo/akan.baseline.json", "akan.service.call-in-loop")?.message).toBe(
+      `apps/demo carries 1 reasoned exception and 0 adopted-debt entries for akan.service.call-in-loop: lib/court/court.service.ts#syncAll (${JSON.stringify(reason)}).`,
+    );
+    expect(byRule("libs/shared/akan.baseline.json", "akan.size.file")?.message).toBe(
+      "libs/shared carries 0 reasoned exceptions and 1 adopted-debt entry for akan.size.file: ui/Table.tsx.",
+    );
+    expect(byRule("apps/demo/akan.baseline.json", "akan.size.component")?.fix).toContain("threshold is wrong");
+    expect(byRule("apps/demo/akan.baseline.json", "akan.store.multi-write")?.fix).toContain("add-mutation");
+  });
+});

package/maintainabilityExceptionScanner.ts

@@ -0,0 +1,85 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { type BaselineEntry, MaintainabilityBaseline } from "./maintainabilityBaseline";
+import type { DebtRuleId } from "./maintainabilityContract";
+import type { QualityWarning } from "./qualityScanner";
+
+export class MaintainabilityExceptionScanner {
+  static readonly rule = "akan.baseline.exceptions";
+  static readonly #shapeFix =
+    "Many reasoned exceptions under one rule mean its threshold is wrong: fix the limit in MaintainabilityLimits rather than record another. Otherwise shrink the code, and `akan lint` lowers each entry and drops it once it passes.";
+  static readonly #correctnessFix =
+    "A write rule takes no exception: send the writes through one store action and one endpoint (`akan workflow plan add-mutation`), and `akan lint` drops the entry.";
+
+  async scan(workspaceRoot: string): Promise<QualityWarning[]> {
+    const sysPaths = await Promise.all(
+      ["apps", "libs"].map(async (sysRoot) => {
+        const absoluteRoot = path.join(workspaceRoot, sysRoot);
+        if (!existsSync(absoluteRoot)) return [];
+        const entries = await readdir(absoluteRoot, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => `${sysRoot}/${entry.name}`);
+      }),
+    );
+    const warnings = await Promise.all(
+      sysPaths.flat().map((sysPath) => MaintainabilityExceptionScanner.#scanSys(workspaceRoot, sysPath)),
+    );
+    return warnings.flat();
+  }
+
+  static async #scanSys(workspaceRoot: string, sysPath: string): Promise<QualityWarning[]> {
+    const file = `${sysPath}/${MaintainabilityBaseline.fileName}`;
+    const absolutePath = path.join(workspaceRoot, file);
+    if (!existsSync(absolutePath)) return [];
+    const text = await readFile(absolutePath, "utf8");
+    let baseline: MaintainabilityBaseline;
+    try {
+      baseline = MaintainabilityBaseline.parse(text, file);
+    } catch {
+      //? `akan lint` names a malformed baseline and how it breaks; the scan reports only the ones it can read.
+      return [];
+    }
+    const lines = text.split(/\r?\n/);
+    return [...baseline.entriesByRule()].map(([rule, entries]) =>
+      MaintainabilityExceptionScanner.#warningOf(sysPath, file, lines, rule, entries),
+    );
+  }
+
+  static #warningOf(
+    sysPath: string,
+    file: string,
+    lines: string[],
+    rule: DebtRuleId,
+    entries: BaselineEntry[],
+  ): QualityWarning {
+    const reasonedNum = entries.filter(({ reason }) => reason !== undefined).length;
+    const adoptedNum = entries.length - reasonedNum;
+    const listed = entries.map(({ key, reason }) =>
+      reason === undefined ? key : `${key} (${JSON.stringify(reason)})`,
+    );
+    const locations = entries.map(({ key }) => ({
+      file,
+      line: MaintainabilityExceptionScanner.#lineOf(lines, rule, key),
+    }));
+    return {
+      rule: MaintainabilityExceptionScanner.rule,
+      scope: "file",
+      severity: "warning",
+      file,
+      line: locations[0]?.line ?? 1,
+      message: `${sysPath} carries ${reasonedNum} reasoned exception${reasonedNum === 1 ? "" : "s"} and ${adoptedNum} adopted-debt entr${adoptedNum === 1 ? "y" : "ies"} for ${rule}: ${listed.join(", ")}.`,
+      locations,
+      fix: MaintainabilityBaseline.reasonedRules.has(rule)
+        ? MaintainabilityExceptionScanner.#shapeFix
+        : MaintainabilityExceptionScanner.#correctnessFix,
+    };
+  }
+
+  static #lineOf(lines: string[], rule: DebtRuleId, key: string) {
+    const from = Math.max(
+      lines.findIndex((line) => line.includes(`${JSON.stringify(rule)}:`)),
+      0,
+    );
+    return Math.max(lines.findIndex((line, idx) => idx >= from && line.includes(`${JSON.stringify(key)}:`)) + 1, 1);
+  }
+}

package/maintainabilityLimits.ts

@@ -0,0 +1,60 @@
+import path from "node:path";
+import ts from "typescript";
+import { AbstractDoc } from "./abstractDoc";
+
+export type FileKind =
+  | keyof typeof MaintainabilityLimits.fileMaxLines
+  | keyof typeof MaintainabilityLimits.folderMaxLines;
+
+export class MaintainabilityLimits {
+  static readonly fileMaxLines = {
+    ".Template.tsx": 400,
+    ".Unit.tsx": 400,
+    ".Util.tsx": 400,
+    ".View.tsx": 400,
+    ".Zone.tsx": 400,
+    ".store.ts": 400,
+    ".document.ts": 500,
+    ".service.ts": 500,
+    [AbstractDoc.suffix]: AbstractDoc.maxLines,
+  } as const;
+  static readonly folderMaxLines = { "ui/": 400, "webkit/": 400 } as const;
+  static readonly #maxLinesByKind = { ...MaintainabilityLimits.fileMaxLines, ...MaintainabilityLimits.folderMaxLines };
+  static readonly componentMaxLines = 250;
+  static readonly componentMaxStoreAccesses = 16;
+
+  static fileKindOf(sysRelativePath: string): FileKind | null {
+    const kinds = Object.keys(MaintainabilityLimits.#maxLinesByKind) as FileKind[];
+    const suffix = kinds.find((kind) => sysRelativePath.endsWith(kind));
+    if (suffix) return suffix;
+    if (!/\.tsx?$/.test(sysRelativePath) || MaintainabilityLimits.#isTest(sysRelativePath)) return null;
+    return kinds.find((kind) => sysRelativePath.startsWith(kind)) ?? null;
+  }
+
+  static fileMaxLinesOf(sysRelativePath: string) {
+    const kind = MaintainabilityLimits.fileKindOf(sysRelativePath);
+    return kind ? MaintainabilityLimits.#maxLinesByKind[kind] : null;
+  }
+
+  static isReexportBarrel(file: string, content: string) {
+    if (path.posix.basename(file) !== "index.ts") return false;
+    return ts
+      .createSourceFile(file, content, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS)
+      .statements.every((statement) => ts.isExportDeclaration(statement));
+  }
+
+  static lineCountOf(content: string) {
+    return AbstractDoc.lineCountOf(content);
+  }
+
+  //? Under `lib/` only the `.tsx` components run in the browser; `ui/` and `webkit/` run there whole.
+  static isClientCode(sysRelativePath: string) {
+    if (MaintainabilityLimits.#isTest(sysRelativePath)) return false;
+    if (sysRelativePath.startsWith("lib/")) return sysRelativePath.endsWith(".tsx");
+    return /^(ui|webkit)\/.+\.tsx?$/.test(sysRelativePath) && !sysRelativePath.endsWith(".d.ts");
+  }
+
+  static #isTest(sysRelativePath: string) {
+    return /\.(test|spec)\.tsx?$/.test(sysRelativePath);
+  }
+}