@akanjs/devkit 3.1.2-rc.4 → 3.2.0-rc.1

package/maintainabilityContract.ts

@@ -5,6 +5,7 @@ import ts from "typescript";
 import { ComponentSizeScanner } from "./componentSizeScanner";
 import { ComponentWriteChainScanner } from "./componentWriteChainScanner";
 import { EndpointReach } from "./endpointReach";
+import { GitRevision } from "./gitRevision";
 import { MaintainabilityBaseline } from "./maintainabilityBaseline";
 import { MaintainabilityLimits } from "./maintainabilityLimits";
 import { MaintainabilityReport } from "./maintainabilityReport";
@@ -13,11 +14,12 @@ import { ServiceLoopCallScanner } from "./serviceLoopCallScanner";
 import { SignalMutationIndex } from "./signalMutationIndex";
 import { StoreAccessScanner } from "./storeAccessScanner";
 import { StoreWriteScanner } from "./storeWriteScanner";
+import { StructureScanner } from "./structureScanner";
 import { WritePlacementScanner } from "./writePlacementScanner";
 import { WritingActionIndex } from "./writingActionIndex";
 
 export interface MaintainabilityScope {
-  type: "app" | "lib";
+  type: "app" | "lib" | "pkg";
   name: string;
 }
 
@@ -27,13 +29,26 @@ export type MaintainabilityCommands = { [rule in MaintainabilityRuleId]?: readon
 
 export interface SizeViolation {
   kind: "size";
-  rule: "akan.size.file" | "akan.size.component";
+  rule: "akan.size.file" | "akan.size.component" | "akan.size.function";
   key: string;
   file: string;
   line: number;
   lineCount: number;
   maxLines: number;
   component?: string;
+  function?: string;
+  recorded?: number;
+}
+
+export interface ClassSizeViolation {
+  kind: "classSize";
+  rule: "akan.size.class";
+  key: string;
+  file: string;
+  line: number;
+  owner: string;
+  memberCount: number;
+  maxMembers: number;
   recorded?: number;
 }
 
@@ -92,10 +107,12 @@ export interface BaselineGrowth {
   count: number;
   committed?: number;
   reference: string;
+  measured?: boolean;
 }
 
 export type MaintainabilityViolation =
   | SizeViolation
+  | ClassSizeViolation
   | MultiWriteViolation
   | StoreAccessViolation
   | WritePlacementViolation
@@ -108,6 +125,8 @@ export class MaintainabilityContract {
   static readonly ruleIds = [
     "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",
@@ -121,6 +140,7 @@ export class MaintainabilityContract {
   readonly #workspaceRoot: string;
   readonly #scope: MaintainabilityScope;
   readonly #libNames: string[];
+  #tree: ReadonlyMap<string, string> | null = null;
 
   constructor(workspaceRoot: string, scope: MaintainabilityScope, libNames: string[] = []) {
     this.#workspaceRoot = workspaceRoot;
@@ -137,6 +157,7 @@ export class MaintainabilityContract {
   }
 
   async measure(): Promise<MaintainabilityViolation[]> {
+    if (this.#scope.type === "pkg") return await this.#measurePackage();
     const [signalFiles, storeFiles, serviceFiles] = await Promise.all([
       this.#reachedSources("lib/**/*.signal.ts"),
       this.#reachedSources("lib/**/*.store.ts"),
@@ -144,10 +165,7 @@ export class MaintainabilityContract {
     ]);
     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 files = await this.#filesIn(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));
   }
@@ -168,12 +186,19 @@ export class MaintainabilityContract {
         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 }))
+    const working = fix ? tightened : baseline;
+    const source = `${reference.label}:${this.sysPath}/${MaintainabilityBaseline.fileName}`;
+    const committed =
+      reference.text !== null
+        ? MaintainabilityBaseline.parse(reference.text, source, { lenient: true })
+        : working.isEmpty
+          ? null
+          : await this.#measuredAt(reference.ref);
+    if (committed === null) return failures;
+    const lines = ((await this.#readBaseline()) ?? "").split(/\r?\n/);
+    const growths = working
+      .grownFrom(committed)
       .map(
         ({ rule, ...growth }): BaselineGrowth => ({
           kind: "baselineGrowth",
@@ -181,7 +206,8 @@ export class MaintainabilityContract {
           file: MaintainabilityBaseline.fileName,
           line: MaintainabilityContract.#lineOf(lines, rule, growth.key),
           debtRule: rule,
-          reference: reference.ref,
+          reference: reference.label,
+          ...(reference.text === null ? { measured: true } : {}),
           ...growth,
         }),
       )
@@ -206,6 +232,77 @@ export class MaintainabilityContract {
     return MaintainabilityReport.describe(this.sysPath, failures, commands);
   }
 
+  async #measurePackage() {
+    const files = (await this.#packageFiles()).filter(MaintainabilityLimits.isPackageSource);
+    const violations = await Promise.all(
+      files.map(async (file) => {
+        const workspaceFile = `${this.sysPath}/${file}`;
+        const content = await this.#read(workspaceFile);
+        return MaintainabilityContract.#measurePackageFile(file, this.#sourceOf(workspaceFile, content).sourceFile);
+      }),
+    );
+    return violations.flat();
+  }
+
+  static #measurePackageFile(file: string, sourceFile: ts.SourceFile) {
+    const violations: MaintainabilityViolation[] = [];
+    const maxLines = MaintainabilityLimits.packageFileMaxLines;
+    const lineCount = MaintainabilityLimits.lineCountOf(sourceFile.text);
+    if (lineCount > maxLines && !MaintainabilityLimits.isReexportBarrel(file, sourceFile.text))
+      violations.push({ kind: "size", rule: "akan.size.file", key: file, file, line: 1, lineCount, maxLines });
+    const { functions, classes } = new StructureScanner().measure(sourceFile);
+    const longFunctions = functions.filter(({ lineCount }) => lineCount > MaintainabilityLimits.functionMaxLines);
+    for (const { name, line, lineCount } of MaintainabilityContract.#numbered(longFunctions))
+      violations.push({
+        kind: "size",
+        rule: "akan.size.function",
+        key: `${file}#${name}`,
+        file,
+        line,
+        lineCount,
+        maxLines: MaintainabilityLimits.functionMaxLines,
+        function: name,
+      });
+    const largeClasses = classes.filter(({ memberCount }) => memberCount > MaintainabilityLimits.classMaxMembers);
+    for (const { name, line, memberCount } of MaintainabilityContract.#numbered(largeClasses))
+      violations.push({
+        kind: "classSize",
+        rule: "akan.size.class",
+        key: `${file}#${name}`,
+        file,
+        line,
+        owner: name,
+        memberCount,
+        maxMembers: MaintainabilityLimits.classMaxMembers,
+      });
+    return violations;
+  }
+
+  //? Only breaches are numbered: a short function sharing a recorded one's name never moves the recorded key.
+  static #numbered<Item extends { name: string }>(items: Item[]) {
+    const seen = new Map<string, number>();
+    return items.map((item) => {
+      const count = (seen.get(item.name) ?? 0) + 1;
+      seen.set(item.name, count);
+      return count === 1 ? item : { ...item, name: `${item.name}[${count}]` };
+    });
+  }
+
+  //? Git lists what the package holds without its ignored build output, caches and sample artifacts.
+  async #packageFiles() {
+    const listed = this.#tree
+      ? null
+      : await this.#git(["ls-files", "-z", "-co", "--exclude-standard", "--", `./${this.sysPath}`]);
+    if (listed === null) return await this.#filesIn(this.sysPath, "**/*.{ts,tsx}");
+    const prefix = `${this.sysPath}/`;
+    return listed
+      .split("\0")
+      .filter((file) => file.startsWith(prefix) && existsSync(path.join(this.#workspaceRoot, file)))
+      .map((file) => file.slice(prefix.length))
+      .filter((file) => !file.includes("node_modules/"))
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  }
+
   async #measureFile(
     file: string,
     index: WritingActionIndex,
@@ -217,7 +314,7 @@ export class MaintainabilityContract {
     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 content = await this.#read(workspaceFile);
     const violations: MaintainabilityViolation[] = [];
     const lineCount = MaintainabilityLimits.lineCountOf(content);
     if (maxLines && lineCount > maxLines && !MaintainabilityLimits.isReexportBarrel(file, content))
@@ -303,17 +400,9 @@ export class MaintainabilityContract {
   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"))),
+      roots.map(async (root) => (await this.#filesIn(root, pattern)).map((file) => `${root}/${file}`)),
     );
+    return await Promise.all(files.flat().map(async (file) => this.#sourceOf(file, await this.#read(file))));
   }
 
   #sourceOf(file: string, content: string): SourceFileInfo {
@@ -334,7 +423,21 @@ export class MaintainabilityContract {
   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 };
+    return { ref, label: ref === "HEAD" ? ref : ref.slice(0, 12), text };
+  }
+
+  //* With no baseline file at the reference, the debt its code already holds is the floor: none for a scope new to the
+  //* branch or one whose paid-off file was removed, and the breaches it had for a scope that adopts the gate here.
+  async #measuredAt(ref: string) {
+    if ((await this.#git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`])) === null) return null;
+    const roots = [this.sysPath, ...this.#libNames.map((libName) => `libs/${libName}`)];
+    const contract = new MaintainabilityContract(this.#workspaceRoot, this.#scope, this.#libNames);
+    contract.#tree = await new GitRevision(this.#workspaceRoot).filesAt(
+      ref,
+      (file) => /\.(tsx?|md)$/.test(file),
+      roots,
+    );
+    return MaintainabilityBaseline.of(await contract.measure());
   }
 
   //* A branch's own commits cannot be the reference: one that raises an entry would make the raise the new floor.
@@ -393,12 +496,24 @@ export class MaintainabilityContract {
     return Math.max(idx + 1, 1);
   }
 
-  static async #filesUnder(root: string, pattern: string) {
+  async #filesIn(root: string, pattern: string) {
+    const glob = new Bun.Glob(pattern);
+    const files = this.#tree
+      ? [...this.#tree.keys()]
+          .filter((file) => file.startsWith(`${root}/`))
+          .map((file) => file.slice(root.length + 1))
+          .filter((file) => glob.match(file))
+      : await MaintainabilityContract.#filesOnDisk(path.join(this.#workspaceRoot, root), glob);
+    return files.filter((file) => !file.includes("node_modules/")).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  }
+
+  static async #filesOnDisk(root: string, glob: Bun.Glob) {
     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));
+    const files = await Array.fromAsync(glob.scan({ cwd: root, onlyFiles: true }));
+    return files.map((file) => file.split(path.sep).join("/"));
+  }
+
+  async #read(file: string) {
+    return this.#tree ? (this.#tree.get(file) ?? "") : await readFile(path.join(this.#workspaceRoot, file), "utf8");
   }
 }

package/maintainabilityExceptionScanner.test.ts

@@ -15,7 +15,7 @@ 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 () => {
+  test("warns once per app, lib or package and rule, counting reasoned exceptions apart from adopted debt", async () => {
     const root = await makeWorkspace({
       "apps/demo/akan.baseline.json": baselineOf({
         "akan.size.file": {
@@ -38,6 +38,11 @@ describe("MaintainabilityExceptionScanner", () => {
         },
       }),
       "libs/shared/akan.baseline.json": baselineOf({ "akan.size.file": { "ui/Table.tsx": 500 } }),
+      "pkgs/core/akan.baseline.json": baselineOf({ "akan.size.class": { "server/host.ts#Host": 70 } }),
+      "pkgs/@demo/tool/akan.baseline.json": baselineOf({
+        "akan.size.function": { "boot.ts#boot": 200 },
+        reasons: { "boot.ts#boot": reason },
+      }),
       "libs/util/akan.baseline.json": baselineOf({}),
       "libs/broken/akan.baseline.json": "{",
       "apps/clean/main.ts": "export {};\n",
@@ -48,7 +53,7 @@ describe("MaintainabilityExceptionScanner", () => {
       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(warnings).toHaveLength(10);
     expect(byRule("apps/demo/akan.baseline.json", "akan.size.file")).toMatchObject({
       scope: "file",
       severity: "warning",
@@ -84,6 +89,12 @@ describe("MaintainabilityExceptionScanner", () => {
     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("pkgs/core/akan.baseline.json", "akan.size.class")?.message).toBe(
+      "pkgs/core carries 0 reasoned exceptions and 1 adopted-debt entry for akan.size.class: server/host.ts#Host.",
+    );
+    expect(byRule("pkgs/@demo/tool/akan.baseline.json", "akan.size.function")?.message).toBe(
+      `pkgs/@demo/tool carries 1 reasoned exception and 0 adopted-debt entries for akan.size.function: boot.ts#boot (${JSON.stringify(reason)}).`,
+    );
     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

@@ -14,12 +14,7 @@ export class MaintainabilityExceptionScanner {
 
   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}`);
-      }),
+      ["apps", "libs", "pkgs"].map((sysRoot) => MaintainabilityExceptionScanner.#dirsIn(workspaceRoot, sysRoot)),
     );
     const warnings = await Promise.all(
       sysPaths.flat().map((sysPath) => MaintainabilityExceptionScanner.#scanSys(workspaceRoot, sysPath)),
@@ -27,6 +22,21 @@ export class MaintainabilityExceptionScanner {
     return warnings.flat();
   }
 
+  static async #dirsIn(workspaceRoot: string, root: string): Promise<string[]> {
+    const absoluteRoot = path.join(workspaceRoot, root);
+    if (!existsSync(absoluteRoot)) return [];
+    const entries = await readdir(absoluteRoot, { withFileTypes: true });
+    const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => `${root}/${entry.name}`);
+    const nested = await Promise.all(
+      dirs.map(async (dir) =>
+        root === "pkgs" && path.posix.basename(dir).startsWith("@")
+          ? await MaintainabilityExceptionScanner.#dirsIn(workspaceRoot, dir)
+          : [dir],
+      ),
+    );
+    return nested.flat();
+  }
+
   static async #scanSys(workspaceRoot: string, sysPath: string): Promise<QualityWarning[]> {
     const file = `${sysPath}/${MaintainabilityBaseline.fileName}`;
     const absolutePath = path.join(workspaceRoot, file);

package/maintainabilityLimits.ts

@@ -22,6 +22,9 @@ export class MaintainabilityLimits {
   static readonly #maxLinesByKind = { ...MaintainabilityLimits.fileMaxLines, ...MaintainabilityLimits.folderMaxLines };
   static readonly componentMaxLines = 250;
   static readonly componentMaxStoreAccesses = 16;
+  static readonly packageFileMaxLines = 800;
+  static readonly functionMaxLines = 150;
+  static readonly classMaxMembers = 60;
 
   static fileKindOf(sysRelativePath: string): FileKind | null {
     const kinds = Object.keys(MaintainabilityLimits.#maxLinesByKind) as FileKind[];
@@ -54,6 +57,15 @@ export class MaintainabilityLimits {
     return /^(ui|webkit)\/.+\.tsx?$/.test(sysRelativePath) && !sysRelativePath.endsWith(".d.ts");
   }
 
+  static isPackageSource(pkgRelativePath: string) {
+    return (
+      /\.tsx?$/.test(pkgRelativePath) &&
+      !pkgRelativePath.endsWith(".d.ts") &&
+      !/(^|\/)(examples|test|tests|__tests__|__fixtures__|__mocks__)\//.test(pkgRelativePath) &&
+      !/\.(test|spec|fixture|instance|bench)\.tsx?$/.test(pkgRelativePath)
+    );
+  }
+
   static #isTest(sysRelativePath: string) {
     return /\.(test|spec)\.tsx?$/.test(sysRelativePath);
   }

package/maintainabilityReport.test.ts

@@ -127,4 +127,39 @@ describe("MaintainabilityReport", () => {
       "  *.service.ts: Move state transitions into document chain methods, and split an unrelated responsibility into its own module.",
     ]);
   });
+
+  test("gives a package file, whatever its folder, a long function and a large class the package fixes", () => {
+    const message = MaintainabilityReport.describe("pkgs/akanjs", [
+      { ...fileOf("ui/Constant/Doc.tsx", 813), maxLines: 800 },
+      {
+        ...fileOf("store/action.ts", 824),
+        rule: "akan.size.function",
+        key: "store/action.ts#makeActions",
+        maxLines: 150,
+        function: "makeActions",
+      },
+      {
+        kind: "classSize",
+        rule: "akan.size.class",
+        key: "server/akanApp.ts#AkanApp",
+        file: "server/akanApp.ts",
+        line: 90,
+        owner: "AkanApp",
+        memberCount: 154,
+        maxMembers: 60,
+        recorded: 150,
+      },
+    ]);
+
+    expect(message).toContain(
+      "pkgs/akanjs/ui/Constant/Doc.tsx:1  akan.size.file  file has 813 lines, over the 800-line limit",
+    );
+    expect(message).toContain(
+      "pkgs/akanjs/store/action.ts:1  akan.size.function  function makeActions has 824 lines, over the 150-line limit",
+    );
+    expect(message).toContain(
+      "pkgs/akanjs/server/akanApp.ts:90  akan.size.class  class AkanApp has 154 members, over the 60-member limit, up from 150",
+    );
+    expect(fixLinesOf(message).map((line) => line.split(":")[0])).toEqual(["  package file", "  function", "  class"]);
+  });
 });

package/maintainabilityReport.ts

@@ -7,7 +7,7 @@ import type {
 } from "./maintainabilityContract";
 import { type FileKind, MaintainabilityLimits } from "./maintainabilityLimits";
 
-type FixKey = FileKind | Exclude<MaintainabilityRuleId, "akan.size.file">;
+type FixKey = FileKind | "package" | Exclude<MaintainabilityRuleId, "akan.size.file">;
 
 export class MaintainabilityReport {
   static readonly #clientSplitFix =
@@ -30,9 +30,15 @@ export class MaintainabilityReport {
       "Move display and predicate logic onto Light<Model>, and split an unrelated concept into its own module.",
     ".service.ts":
       "Move state transitions into document chain methods, and split an unrelated responsibility into its own module.",
+    package:
+      "Split it by responsibility: one class per file, and each family of helpers in a file of its own behind the package's existing exports.",
     [AbstractDoc.suffix]:
       "Trim the abstract to a title, one sentence naming what the module owns, and a `## Rules` list of the invariants the code cannot show.",
     "akan.size.component": MaintainabilityReport.#clientSplitFix,
+    "akan.size.function":
+      "Split it by family into named functions or a collaborator class, each under the limit, keeping its signature for callers.",
+    "akan.size.class":
+      "Move each family of members into a collaborator the class holds, and keep the public members on the class as its facade.",
     "akan.store.multi-write": MaintainabilityReport.#oneEndpointFix,
     "akan.store.root-write-chain": `A store may call another through \`RootStore\`, but that does not make the writes one. ${MaintainabilityReport.#oneEndpointFix}`,
     "akan.component.write-chain":
@@ -49,7 +55,10 @@ export class MaintainabilityReport {
   static readonly #labels: { [key in FixKey]?: string } = {
     "ui/": "ui/**",
     "webkit/": "webkit/**",
+    package: "package file",
     "akan.size.component": "component or hook",
+    "akan.size.function": "function",
+    "akan.size.class": "class",
     "akan.store.multi-write": "store action with several writes",
     "akan.store.root-write-chain": "store method chaining other stores' writes",
     "akan.component.write-chain": "handler with several writes",
@@ -62,6 +71,8 @@ export class MaintainabilityReport {
   static readonly #units: { [rule in DebtRuleId]: string } = {
     "akan.size.file": "lines",
     "akan.size.component": "lines",
+    "akan.size.function": "lines",
+    "akan.size.class": "members",
     "akan.component.store-access": "store accesses",
     "akan.store.multi-write": "writes",
     "akan.store.root-write-chain": "writes",
@@ -73,7 +84,7 @@ export class MaintainabilityReport {
   static describe(sysPath: string, failures: MaintainabilityFailure[], commands: MaintainabilityCommands = {}) {
     const groups = new Map<string, { labels: string[]; rules: Set<MaintainabilityRuleId> }>();
     for (const failure of failures) {
-      const fixKey = MaintainabilityReport.#fixKeyOf(failure);
+      const fixKey = MaintainabilityReport.#fixKeyOf(sysPath, failure);
       const fix = MaintainabilityReport.#fixes[fixKey];
       const group = groups.get(fix) ?? { labels: [], rules: new Set() };
       const label = MaintainabilityReport.#labelOf(fixKey);
@@ -101,7 +112,7 @@ export class MaintainabilityReport {
       line: failure.line,
       rule: failure.rule,
       problem: MaintainabilityReport.#problemOf(failure),
-      fix: MaintainabilityReport.#fixes[MaintainabilityReport.#fixKeyOf(failure)],
+      fix: MaintainabilityReport.#fixes[MaintainabilityReport.#fixKeyOf(sysPath, failure)],
       path: commands[failure.rule]?.[0] ?? null,
     }));
   }
@@ -109,9 +120,14 @@ export class MaintainabilityReport {
   static #problemOf(failure: MaintainabilityFailure) {
     if (failure.kind === "baselineGrowth") {
       const entry = `entry "${failure.key}" under ${failure.debtRule}`;
+      const units = MaintainabilityReport.#units[failure.debtRule];
+      if (failure.measured)
+        return failure.committed === undefined
+          ? `${entry} is debt the code at ${failure.reference} does not hold, and with no baseline there the baseline may only shrink from that code`
+          : `${entry} allows ${failure.count} ${units}, above the ${failure.committed} the code at ${failure.reference} holds with no baseline there; the baseline may only shrink`;
       return failure.committed === undefined
         ? `${entry} is not in the baseline at ${failure.reference}, which may only shrink`
-        : `${entry} allows ${failure.count} ${MaintainabilityReport.#units[failure.debtRule]}, above the ${failure.committed} at ${failure.reference}; the baseline may only shrink`;
+        : `${entry} allows ${failure.count} ${units}, above the ${failure.committed} at ${failure.reference}; the baseline may only shrink`;
     }
     const grown = failure.recorded === undefined ? "" : `, more than the ${failure.recorded} recorded`;
     if (failure.kind === "multiWrite") {
@@ -129,11 +145,15 @@ export class MaintainabilityReport {
       return `sends ${failure.writes.length} server write(s) from outside a store action or a module component: ${failure.writes.join(", ")}${grown}`;
     if (failure.kind === "loopCall")
       return `service method ${failure.owner} calls once per item: ${failure.calls.join(", ")}${grown}`;
+    if (failure.kind === "classSize")
+      return `class ${failure.owner} has ${failure.memberCount} members, over the ${failure.maxMembers}-member limit${failure.recorded === undefined ? "" : `, up from ${failure.recorded}`}`;
     if (failure.kind === "storeAccess")
       return `${MaintainabilityReport.#unitOf(failure.component)} ${failure.component} reaches the store ${failure.accessCount} times, over the ${failure.maxAccesses}-access limit${failure.recorded === undefined ? "" : `, up from ${failure.recorded}`}`;
-    const subject = failure.component
-      ? `${MaintainabilityReport.#unitOf(failure.component)} ${failure.component} has`
-      : "file has";
+    const subject = failure.function
+      ? `function ${failure.function} has`
+      : failure.component
+        ? `${MaintainabilityReport.#unitOf(failure.component)} ${failure.component} has`
+        : "file has";
     const up = failure.recorded === undefined ? "" : `, up from ${failure.recorded}`;
     return `${subject} ${failure.lineCount} lines, over the ${failure.maxLines}-line limit${up}`;
   }
@@ -142,8 +162,9 @@ export class MaintainabilityReport {
     return /^use[A-Z]/.test(name) ? "hook" : "component";
   }
 
-  static #fixKeyOf(failure: MaintainabilityFailure): FixKey {
+  static #fixKeyOf(sysPath: string, failure: MaintainabilityFailure): FixKey {
     if (failure.rule !== "akan.size.file") return failure.rule;
+    if (sysPath.startsWith("pkgs/")) return "package";
     return MaintainabilityLimits.fileKindOf(failure.file) ?? "akan.size.component";
   }
 

package/mobile/nativePublicEnv.test.ts

@@ -114,7 +114,7 @@ describe("NativePublicEnv", () => {
       WorkspaceExecutor.publicEnvPin = null;
     });
 
-    test("leaves exactly the pinned values and the derived ones, and outranks the root .env", async () => {
+    test("leaves exactly the pinned values and the derived ones, and outranks the shell and the root .env", async () => {
       const root = await makeTempRoot();
       const envFile = path.join(root, ".env");
       await writeText(
@@ -125,6 +125,10 @@ describe("NativePublicEnv", () => {
       NativePublicEnv.pin(recorded);
       expect(NativePublicEnv.of(process.env)).toEqual(recorded);
       expect(process.env.AKAN_PUBLIC_APP_NAME).toBe("lu");
+      Object.assign(process.env, {
+        AKAN_PUBLIC_REPO_NAME: "from-shell",
+        AKAN_PUBLIC_SERVE_DOMAIN: "shell.example.com",
+      });
       const base = WorkspaceExecutor.getBaseDevEnv(envFile);
       expect(base.repoName).toBe("softs2");
       expect(base.serveDomain).toBe("akamir.com");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.2-rc.4",
+  "version": "3.2.0-rc.1",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.1.2-rc.4",
+    "@akanjs/language": "3.2.0-rc.1",
     "@earendil-works/pi-agent-core": "1.3.0",
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-codemode": "1.3.0",
@@ -50,7 +50,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.2-rc.4",
+    "akanjs": "3.2.0-rc.1",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/preview/PreviewChrome.ts

@@ -12,12 +12,12 @@ export class PreviewChrome {
   /** Set this to drive Chrome on macOS too, e.g. to reproduce what a pod sees. */
   static readonly backendEnvKey = "AKAN_CODE_WEBVIEW_BACKEND";
 
-  /** The executables Bun looks for on PATH before giving up. */
+  /** The executables Bun looks for on PATH before giving up, in its order: the first found is the one it starts. */
   static readonly executables = [
-    "chromium",
-    "chromium-browser",
     "google-chrome-stable",
     "google-chrome",
+    "chromium-browser",
+    "chromium",
     "brave-browser",
     "microsoft-edge",
     "chrome",