@akanjs/devkit 3.1.1-rc.9 → 3.1.2-rc.0

package/maintainabilityReport.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, test } from "bun:test";
+import type { SizeViolation } from "./maintainabilityContract";
+import { MaintainabilityReport } from "./maintainabilityReport";
+
+const fileOf = (file: string, lineCount = 450): SizeViolation => ({
+  kind: "size",
+  rule: "akan.size.file",
+  key: file,
+  file,
+  line: 1,
+  lineCount,
+  maxLines: 400,
+});
+
+const fixLinesOf = (message: string) => message.split("How to fix:\n")[1]?.split("\n") ?? [];
+
+describe("MaintainabilityReport", () => {
+  test("gives a client file, a ui/ or webkit/ file, a long component and a busy one the same ordered paths", () => {
+    const message = MaintainabilityReport.describe("apps/demo", [
+      fileOf("lib/court/Court.Zone.tsx"),
+      fileOf("ui/Board.tsx"),
+      fileOf("webkit/useBoard.tsx"),
+      {
+        ...fileOf("lib/court/Court.Zone.tsx", 300),
+        rule: "akan.size.component",
+        key: "lib/court/Court.Zone.tsx#Canvas",
+        line: 4,
+        maxLines: 250,
+        component: "Canvas",
+      },
+      {
+        kind: "storeAccess",
+        rule: "akan.component.store-access",
+        key: "lib/court/Court.Zone.tsx#Canvas",
+        file: "lib/court/Court.Zone.tsx",
+        line: 4,
+        component: "Canvas",
+        accessCount: 20,
+        maxAccesses: 16,
+      },
+    ]);
+    const [fix = "", ...rest] = fixLinesOf(message);
+    const order = ["mode/kind table", "webkit/use<X>.tsx", "`common/`", "add-mutation", "`lib/<sub>`"].map((path) =>
+      fix.indexOf(path),
+    );
+
+    expect(rest).toEqual([]);
+    expect(fix).toStartWith(
+      "  *.Zone.tsx, ui/**, webkit/**, component or hook, component or hook reaching the store often: ",
+    );
+    expect(order.every((idx) => idx > 0)).toBe(true);
+    expect([...order].sort((a, b) => a - b)).toEqual(order);
+    expect(fix).toContain('`{ [kind in cnst.X["value"]]: … }`');
+    expect(fix).toContain("akan workflow plan create-interaction");
+    expect(fix).toContain("never model-bound code moved into `ui/`");
+  });
+
+  test("names a write sent from the wrong place, a call per item and a raised entry with their own fixes", () => {
+    const message = MaintainabilityReport.describe("apps/demo", [
+      {
+        kind: "baselineGrowth",
+        rule: "akan.baseline.growth",
+        key: "lib/court/court.store.ts#assign",
+        file: "akan.baseline.json",
+        line: 5,
+        debtRule: "akan.store.multi-write",
+        count: 3,
+        committed: 2,
+        reference: "3f2a9c1d0b7e",
+      },
+      {
+        kind: "writePlacement",
+        rule: "akan.write.placement",
+        key: "webkit/useBoard.tsx",
+        file: "webkit/useBoard.tsx",
+        line: 7,
+        writes: ["st.do.removeBoard", "fetch.placeBoard"],
+      },
+      {
+        kind: "loopCall",
+        rule: "akan.service.call-in-loop",
+        key: "lib/court/court.service.ts#syncAll",
+        file: "lib/court/court.service.ts",
+        line: 12,
+        owner: "syncAll",
+        calls: ["this.pcService.getPc"],
+        recorded: 0,
+      },
+      {
+        kind: "multiWrite",
+        rule: "akan.component.write-chain",
+        key: "webkit/useBoard.tsx#useBoard",
+        file: "webkit/useBoard.tsx",
+        line: 9,
+        owner: "useBoard",
+        writes: ["st.do.removeBoard (per item)"],
+        writeCount: 2,
+      },
+    ]);
+
+    expect(message).toContain(
+      'akan.baseline.growth  entry "lib/court/court.store.ts#assign" under akan.store.multi-write allows 3 writes, above the 2 at 3f2a9c1d0b7e',
+    );
+    expect(message).toContain(
+      "akan.write.placement  sends 2 server write(s) from outside a store action or a module component: st.do.removeBoard, fetch.placeBoard",
+    );
+    expect(message).toContain(
+      "akan.service.call-in-loop  service method syncAll calls once per item: this.pcService.getPc, more than the 0 recorded",
+    );
+    expect(message).toContain("hook useBoard sends a write per item from one handler: st.do.removeBoard (per item)");
+    expect(fixLinesOf(message).map((line) => line.split(":")[0])).toEqual([
+      "  baseline entry",
+      "  write sent outside a store action or module component",
+      "  service call per item",
+      "  handler with several writes",
+    ]);
+  });
+
+  test("keeps the server files' own fixes", () => {
+    const message = MaintainabilityReport.describe("apps/demo", [
+      fileOf("lib/court/Court.View.tsx"),
+      fileOf("lib/court/court.service.ts", 520),
+    ]);
+
+    expect(fixLinesOf(message)).toEqual([
+      "  *.View.tsx: Move model-independent pieces into ui/ components and display logic onto Light<Model>.",
+      "  *.service.ts: Move state transitions into document chain methods, and split an unrelated responsibility into its own module.",
+    ]);
+  });
+});

package/maintainabilityReport.ts

@@ -0,0 +1,153 @@
+import { AbstractDoc } from "./abstractDoc";
+import type {
+  DebtRuleId,
+  MaintainabilityCommands,
+  MaintainabilityFailure,
+  MaintainabilityRuleId,
+} from "./maintainabilityContract";
+import { type FileKind, MaintainabilityLimits } from "./maintainabilityLimits";
+
+type FixKey = FileKind | Exclude<MaintainabilityRuleId, "akan.size.file">;
+
+export class MaintainabilityReport {
+  static readonly #clientSplitFix =
+    'Split it, in this order: a mode/kind table `{ [kind in cnst.X["value"]]: … }` in place of mode flags, each entry a component of the module owning the data of that kind; an interaction hook in `webkit/use<X>.tsx` with its pure logic in `common/` (`akan workflow plan create-interaction`); the writes behind one endpoint (`akan workflow plan add-mutation`); last, a sub-concept in its own module (`lib/<sub>` or `lib/_<feature>`), never model-bound code moved into `ui/`.';
+  static readonly #serverMarkupFix =
+    "Move model-independent pieces into ui/ components and display logic onto Light<Model>.";
+  static readonly #oneEndpointFix =
+    "Make it one service method that runs the writes inside `this.transaction(fn)`, with a side effect such as a push command in `this.afterCommit(fn)`, behind one endpoint the action calls once; a write per item becomes one endpoint taking the list. An MCP agent or another screen calling one endpoint alone skips the rest.";
+  static readonly #fixes: { [key in FixKey]: string } = {
+    ".Template.tsx": MaintainabilityReport.#clientSplitFix,
+    ".Unit.tsx": MaintainabilityReport.#serverMarkupFix,
+    ".Util.tsx": MaintainabilityReport.#clientSplitFix,
+    ".View.tsx": MaintainabilityReport.#serverMarkupFix,
+    ".Zone.tsx": MaintainabilityReport.#clientSplitFix,
+    "ui/": MaintainabilityReport.#clientSplitFix,
+    "webkit/": MaintainabilityReport.#clientSplitFix,
+    ".store.ts":
+      "Move business logic into the service behind an endpoint and derived values onto Light<Model>; an action is fetch, set, toast.",
+    ".document.ts":
+      "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.",
+    [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.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":
+      "Move the writes into one service method behind one endpoint, called by one store action the handler calls once; a component chaining `st.do` writes, or writing once per item, leaves an agent or another screen half-done.",
+    "akan.component.store-access": MaintainabilityReport.#clientSplitFix,
+    "akan.write.placement":
+      "A server write leaves the browser through one store action, started by one module component. Move a `fetch.<mutation>` into a store action, and hand `ui/` and `webkit/` code the write as an `onX` prop or hook argument from the module's `Zone` or `Util`: they stay free of any one model, and an agent or another screen reaches the write through the store.",
+    "akan.service.call-in-loop":
+      "Load the set once (`load<Model>Many(ids)`, one filter query) or write it once (`create<Model>Many(rows)`, one batch method), then loop in memory: a call per item is a round trip per item, so the endpoint slows as its input grows.",
+    "akan.baseline.growth":
+      "Restore the entry from the default branch, then split the file or move the writes instead: `akan lint` lowers an entry as the code shrinks and never raises one.",
+  };
+
+  static readonly #labels: { [key in FixKey]?: string } = {
+    "ui/": "ui/**",
+    "webkit/": "webkit/**",
+    "akan.size.component": "component or hook",
+    "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",
+    "akan.component.store-access": "component or hook reaching the store often",
+    "akan.write.placement": "write sent outside a store action or module component",
+    "akan.service.call-in-loop": "service call per item",
+    "akan.baseline.growth": "baseline entry",
+  };
+
+  static readonly #units: { [rule in DebtRuleId]: string } = {
+    "akan.size.file": "lines",
+    "akan.size.component": "lines",
+    "akan.component.store-access": "store accesses",
+    "akan.store.multi-write": "writes",
+    "akan.store.root-write-chain": "writes",
+    "akan.component.write-chain": "writes",
+    "akan.write.placement": "writes",
+    "akan.service.call-in-loop": "calls per item",
+  };
+
+  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 fix = MaintainabilityReport.#fixes[fixKey];
+      const group = groups.get(fix) ?? { labels: [], rules: new Set() };
+      const label = MaintainabilityReport.#labelOf(fixKey);
+      if (!group.labels.includes(label)) group.labels.push(label);
+      group.rules.add(failure.rule);
+      groups.set(fix, group);
+    }
+    return [
+      `[maintainability] ${failures.length} violation(s) in ${sysPath}:`,
+      ...failures.map(
+        (failure) =>
+          `  ${sysPath}/${failure.file}:${failure.line}  ${failure.rule}  ${MaintainabilityReport.#problemOf(failure)}`,
+      ),
+      "How to fix:",
+      ...[...groups].flatMap(([fix, { labels, rules }]) => [
+        `  ${labels.join(", ")}: ${fix}`,
+        ...[...new Set([...rules].flatMap((rule) => commands[rule] ?? []))].map((command) => `    Path: ${command}`),
+      ]),
+    ].join("\n");
+  }
+
+  static entriesOf(sysPath: string, failures: MaintainabilityFailure[], commands: MaintainabilityCommands = {}) {
+    return failures.map((failure) => ({
+      file: `${sysPath}/${failure.file}`,
+      line: failure.line,
+      rule: failure.rule,
+      problem: MaintainabilityReport.#problemOf(failure),
+      fix: MaintainabilityReport.#fixes[MaintainabilityReport.#fixKeyOf(failure)],
+      path: commands[failure.rule]?.[0] ?? null,
+    }));
+  }
+
+  static #problemOf(failure: MaintainabilityFailure) {
+    if (failure.kind === "baselineGrowth") {
+      const entry = `entry "${failure.key}" under ${failure.debtRule}`;
+      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`;
+    }
+    const grown = failure.recorded === undefined ? "" : `, more than the ${failure.recorded} recorded`;
+    if (failure.kind === "multiWrite") {
+      const writes = failure.writes.some((write) => write.endsWith("(per item)"))
+        ? "a write per item"
+        : `${failure.writes.length} writes`;
+      const listed = `${failure.writes.join(", ")}${grown}`;
+      if (failure.rule === "akan.component.write-chain")
+        return `${MaintainabilityReport.#unitOf(failure.owner)} ${failure.owner} sends ${writes} from one handler: ${listed}`;
+      if (failure.rule === "akan.store.root-write-chain")
+        return `store method ${failure.owner} chains ${writes} through other stores from the browser: ${listed}`;
+      return `store action ${failure.owner} sends ${writes} from the browser: ${listed}`;
+    }
+    if (failure.kind === "writePlacement")
+      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 === "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 up = failure.recorded === undefined ? "" : `, up from ${failure.recorded}`;
+    return `${subject} ${failure.lineCount} lines, over the ${failure.maxLines}-line limit${up}`;
+  }
+
+  static #unitOf(name: string) {
+    return /^use[A-Z]/.test(name) ? "hook" : "component";
+  }
+
+  static #fixKeyOf(failure: MaintainabilityFailure): FixKey {
+    if (failure.rule !== "akan.size.file") return failure.rule;
+    return MaintainabilityLimits.fileKindOf(failure.file) ?? "akan.size.component";
+  }
+
+  static #labelOf(fixKey: FixKey) {
+    return MaintainabilityReport.#labels[fixKey] ?? `*${fixKey}`;
+  }
+}

package/mobile/desktopRelease.test.ts

@@ -381,7 +381,7 @@ describe("DesktopRelease signer", () => {
 
   const windowsTool = (powershell: (out: string) => Promise<number>) =>
     recordingTool(async (cmd, env) => {
-      if (cmd[0] === "tar.exe") {
+      if (cmd[0] === path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe")) {
         await Bun.write(path.join(extractedTo(cmd), cmd.at(-1) ?? ""), "MZ");
         return { code: 0, output: "" };
       }

package/mobile/desktopRelease.ts

@@ -245,7 +245,9 @@ Set-Content -LiteralPath $env:AKAN_SIGNER_OUT -Value $subject -Encoding UTF8`;
   }
 
   static async #subjectOf(run: SignatureTool, archive: string, tmp: string, exe: string) {
-    await run(["tar.exe", "-xzf", archive, "-C", tmp, exe]);
+    //? Windows' own bsdtar: a GNU tar ahead of it on PATH (Git's) takes `C:` for a remote host.
+    const tar = path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe");
+    await run([tar, "-xzf", archive, "-C", tmp, exe]);
     const extracted = path.join(tmp, exe);
     if (!(await Bun.file(extracted).exists())) return { signer: null, unread: `the archive holds no ${exe}` };
     const out = path.join(tmp, "signer.txt");

package/mobile/desktopServerStage.test.ts

@@ -145,6 +145,7 @@ describe("DesktopServerStage", () => {
     ];
     const imageOnly = [
       "Dockerfile",
+      "akan.env.json",
       "package.json",
       "rscWorker.js",
       "console.js",

package/mobile/desktopServerStage.ts

@@ -2,6 +2,7 @@ import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { toError } from "akanjs/common";
 import type { ServerPolicy } from "akanjs/native/api";
+import { BUILD_ENV_FILE } from "akanjs/server/lifecycle/buildEnv";
 import type { AkanAppConfig, NativeEnv } from "../akanConfig";
 import type { App } from "../commandDecorators";
 import type { PackageJson } from "../types";
@@ -26,9 +27,10 @@ export interface DesktopServerRun extends ServerPolicy {
 export class DesktopServerStage {
   //? An API-only server starts neither the RSC worker nor the akan console and serves no CSR, public/ or SSR
   //? artifact, and `install` wrote its own package.json and bun.lock. The rest of dist is the server's: its chunks,
-  //? a `.node`, a `.wasm`.
+  //? a `.node`, a `.wasm`. The build's env file would hand it the PORT and AKAN_LOG_TO_FILE its launcher leaves out.
   static readonly uncarried = new Set([
     "Dockerfile",
+    BUILD_ENV_FILE,
     "package.json",
     "bun.lock",
     "rscWorker.js",

package/mobile/nativeApp.test.ts

@@ -313,18 +313,33 @@ describe("NativeApp", () => {
     expect(await injected()).toContain('"indexPath":"/mobile"');
   });
 
-  test("builds its config from the app's locales and the plugins' native contributions", async () => {
+  test("builds its config from the app's locales, the plugins' native contributions and the inlined public env", async () => {
     const push: AkanPlugin = { name: "push-notification", native: { permission: "push", plugins: ["push"] } };
-    const app = new NativeApp(
-      fakeApp([push, { name: "other" }]),
-      target({ basePath: undefined, permissions: ["push"] }),
-    );
+    const root = await makeTempRoot();
+    const portal = { ...fakeApp([push, { name: "other" }]), dist: { cwdPath: path.join(root, "dist/apps/portal") } };
+    await CsrArtifactBuilder.writePublicEnv(portal as unknown as App, {
+      "process.env.AKAN_PUBLIC_APP_NAME": '"portal"',
+      "process.env.AKAN_PUBLIC_ENV": '"main"',
+      "process.env.AKAN_PUBLIC_SERVE_DOMAIN": '"akamir.com"',
+      "process.env.AKAN_PUBLIC_SERVER_URL": '"http://192.168.0.5:8080/api"',
+    });
+    const app = new NativeApp(portal as unknown as App, target({ basePath: undefined, permissions: ["push"] }));
 
     const { config, warnings } = await app.config({ platform: "android" });
 
     expect(warnings).toEqual([]);
     expect(config.plugins).toEqual([...NativeConfig.basePlugins, "push"]);
     expect(config.web.dir).toBe(path.join(nativeDir, "default/web"));
+    const csp = config.security?.csp as Record<string, string[]> | undefined;
+    expect(csp?.["connect-src"]).toEqual([
+      "'self'",
+      "blob:",
+      "data:",
+      "https:",
+      "wss:",
+      "http://192.168.0.5:8080",
+      "ws://192.168.0.5:8080",
+    ]);
   });
 
   test("a config nothing is built from (the update key's) stages no desktop bin", async () => {

package/mobile/nativeApp.ts

@@ -124,10 +124,11 @@ export class NativeApp {
     stageBin?: boolean;
     arch?: DesktopArch;
   }) {
-    const [appConfig, plugins, nativePlugins] = await Promise.all([
+    const [appConfig, plugins, nativePlugins, publicEnv] = await Promise.all([
       this.app.getConfig(),
       this.app.collectPlugins(),
       NativePluginFolders.of(this.app),
+      NativePublicEnv.inlined(this.app),
     ]);
     const desktop = platform === "macos" || platform === "windows" || platform === "linux";
     const carried = desktop && stageBin ? await new DesktopBin(this.app, appConfig).stage(this.binDir, arch) : [];
@@ -137,9 +138,11 @@ export class NativeApp {
       webDir: this.web.dir,
       contributions: plugins.flatMap((plugin) => (plugin.native ? [plugin.native] : [])),
       locales: appConfig.i18n.locales,
+      i18n: appConfig.i18n,
       env: this.env,
       platform,
       nativePlugins,
+      publicEnv,
       ...(server ? { desktopServer: server } : {}),
       ...(carried.length ? { desktopBin: this.binDir } : {}),
     });