@akanjs/devkit 3.1.1-rc.0 → 3.1.1-rc.10

package/signalMutationIndex.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { SignalMutationIndex } from "./signalMutationIndex";
+
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/repo/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS),
+});
+
+const ticketSignal = fileOf(
+  "apps/demo/lib/ticket/ticket.signal.ts",
+  `
+export class TicketSlice extends slice(srv.ticket, { guards: { root: Admin, get: Public, cru: User } }, () => ({})) {}
+
+export class TicketEndpoint extends endpoint(srv.ticket.with(srv.util.security), ({ query, mutation: write, message }) => ({
+  approveTicket: write(cnst.Ticket, { guards: [User] })
+    .param("ticketId", ID)
+    .exec(async function (ticketId) {
+      return await this.ticketService.approve(ticketId);
+    }),
+  ticketCount: query(Int, { guards: [User] }).exec(async function () {
+    return 0;
+  }),
+  nudgeTicket: message(Boolean, { guards: [User] })
+    .msg("ticketId", ID)
+    .exec(function (ticketId) {
+      return !!ticketId;
+    }),
+}))
+{}
+`,
+);
+
+describe("SignalMutationIndex", () => {
+  test("reads each endpoint's kind from its declaration, aliased builders included", () => {
+    const index = new SignalMutationIndex([ticketSignal]);
+    expect(index.isMutation("apps/demo/page/x.tsx", "approveTicket")).toBe(true);
+    expect(index.isMutation("apps/demo/page/x.tsx", "ticketCount")).toBe(false);
+    expect(index.isMutation("apps/demo/page/x.tsx", "initTicketInOrg")).toBe(false);
+  });
+
+  test("counts a socket message as a mutation, its policy after the message arguments", () => {
+    const index = new SignalMutationIndex([ticketSignal]);
+    expect(index.isMutation("apps/demo/page/x.tsx", "nudgeTicket")).toBe(true);
+    expect(index.policyIndexOf("apps/demo/page/x.tsx", "nudgeTicket")).toBe(1);
+  });
+
+  test("counts the CRUD a model's slice generates as mutations", () => {
+    const index = new SignalMutationIndex([ticketSignal]);
+    for (const name of ["createTicket", "updateTicket", "removeTicket", "mergeTicket", "addTicketFiles"])
+      expect(index.isMutation("apps/demo/page/x.tsx", name)).toBe(true);
+    expect(index.isMutation("apps/demo/page/x.tsx", "ticket")).toBe(false);
+  });
+
+  test("places each mutation's policy right after the arguments the client takes", () => {
+    const signal = fileOf(
+      "apps/demo/lib/item/item.signal.ts",
+      `export class ItemSlice extends slice(srv.item, { guards: { root: Admin, cru: User } }, () => ({})) {}
+export class ItemEndpoint extends endpoint(srv.item, ({ query, mutation }) => ({
+  noteItem: mutation(cnst.Item, { guards: [User] })
+    .param("itemId", ID)
+    .body("note", String)
+    .search("tag", String)
+    .with(Ip)
+    .exec(async function (itemId, note, tag, ip) {
+      return await this.itemService.note(itemId, note, tag, ip);
+    }),
+  touchItems: mutation(Boolean, { guards: [User] }).exec(() => true),
+  itemCount: query(Int, { guards: [User] }).param("itemId", ID).exec(() => 0),
+})) {}`,
+    );
+    const index = new SignalMutationIndex([signal]);
+    const policyOf = (name: string) => index.policyIndexOf("apps/demo/page/x.tsx", name);
+    expect(policyOf("noteItem")).toBe(3);
+    expect(policyOf("touchItems")).toBe(0);
+    expect([policyOf("createItem"), policyOf("removeItem")]).toEqual([1, 1]);
+    expect([policyOf("updateItem"), policyOf("mergeItem"), policyOf("addItemFiles")]).toEqual([2, 2, 2]);
+    expect(policyOf("itemCount")).toBeNull();
+    expect(policyOf("unknownItem")).toBeNull();
+  });
+
+  test("reads a builder given as one parameter and a block body", () => {
+    const signal = fileOf(
+      "libs/shared/lib/_util/util.signal.ts",
+      `export class UtilEndpoint extends endpoint(srv.util, (b) => {
+  return { ping: b.query(String, { guards: [Public] }).exec(() => "pong"), touch: b.mutation(Boolean, { guards: [User] }).exec(() => true) };
+}) {}`,
+    );
+    const index = new SignalMutationIndex([signal]);
+    expect(index.isMutation("libs/shared/page/x.tsx", "touch")).toBe(true);
+    expect(index.isMutation("libs/shared/page/x.tsx", "ping")).toBe(false);
+  });
+
+  test("scopes an app's endpoints to that app and every lib's to all of them", () => {
+    const otherApp = fileOf(
+      "apps/other/lib/_other/other.signal.ts",
+      `export class OtherEndpoint extends endpoint(srv.other, ({ mutation }) => ({ approveTicket: mutation(Boolean, {}).exec(() => true) })) {}`,
+    );
+    const lib = fileOf(
+      "libs/shared/lib/_shared/shared.signal.ts",
+      `export class SharedEndpoint extends endpoint(srv.shared, ({ mutation }) => ({ ticketCount: mutation(Boolean, {}).exec(() => true), touchShared: mutation(Boolean, {}).exec(() => true) })) {}`,
+    );
+    const index = new SignalMutationIndex([ticketSignal, otherApp, lib]);
+    expect(index.isMutation("apps/demo/page/x.tsx", "touchShared")).toBe(true);
+    expect(index.isMutation("apps/demo/page/x.tsx", "ticketCount")).toBe(false);
+    expect(index.isMutation("libs/shared/page/x.tsx", "approveTicket")).toBe(false);
+    expect(index.isMutation("apps/third/page/x.tsx", "approveTicket")).toBe(false);
+  });
+
+  test("ignores signal tests and specs", () => {
+    const spec = fileOf(
+      "apps/demo/lib/ticket/ticket.signal.spec.ts",
+      `endpoint(srv.ticket, ({ mutation }) => ({ fixture: mutation(Boolean, {}).exec(() => true) }));`,
+    );
+    expect(new SignalMutationIndex([spec]).isMutation("apps/demo/page/x.tsx", "fixture")).toBe(false);
+  });
+});

package/signalMutationIndex.ts

@@ -0,0 +1,127 @@
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+
+interface EndpointShape {
+  kind: "query" | "mutation";
+  argCount: number;
+}
+
+export class SignalMutationIndex {
+  //? As the client generates them: `update<Model>(id, data, option?)`, `add<Model>Files(files, parentId?, option?)`.
+  static #generatedArgCounts = { create: 1, update: 2, remove: 1, merge: 2 } as const;
+  static #argMethods = new Set(["param", "body", "search", "room", "msg"]);
+  readonly #shapesByOwner = new Map<string, Map<string, EndpointShape>>();
+
+  constructor(sourceFiles: SourceFileInfo[]) {
+    for (const { file, sourceFile } of sourceFiles) {
+      if (!/^(apps|libs)\/[^/]+\/lib\/.+\.signal\.ts$/.test(file)) continue;
+      const owner = file.split("/").slice(0, 2).join("/");
+      const shapes = this.#shapesByOwner.get(owner) ?? new Map<string, EndpointShape>();
+      SignalMutationIndex.#collect(sourceFile, shapes);
+      this.#shapesByOwner.set(owner, shapes);
+    }
+  }
+
+  isMutation(consumerFile: string, name: string) {
+    return this.#shapeOf(consumerFile, name)?.kind === "mutation";
+  }
+
+  /** Where a call to the mutation passes its `FetchPolicy`: the argument right after the ones it declares. */
+  policyIndexOf(consumerFile: string, name: string): number | null {
+    const shape = this.#shapeOf(consumerFile, name);
+    return shape?.kind === "mutation" ? shape.argCount : null;
+  }
+
+  #shapeOf(consumerFile: string, name: string) {
+    const [root, owner] = consumerFile.split("/");
+    const own = root === "apps" ? this.#shapesByOwner.get(`apps/${owner}`)?.get(name) : undefined;
+    if (own) return own;
+    for (const [key, shapes] of this.#shapesByOwner) {
+      const shape = shapes.get(name);
+      if (key.startsWith("libs/") && shape?.kind === "mutation") return shape;
+    }
+    return undefined;
+  }
+
+  static #collect(sourceFile: ts.SourceFile, kinds: Map<string, EndpointShape>) {
+    const visit = (node: ts.Node) => {
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+        if (node.expression.text === "slice") SignalMutationIndex.#collectGenerated(node, kinds);
+        else if (node.expression.text === "endpoint") SignalMutationIndex.#collectEndpoints(node, kinds);
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+  }
+
+  static #collectGenerated(slice: ts.CallExpression, kinds: Map<string, EndpointShape>) {
+    let service: ts.Expression | undefined = slice.arguments[0];
+    while (service && ts.isCallExpression(service) && ts.isPropertyAccessExpression(service.expression))
+      service = service.expression.expression;
+    if (!service || !ts.isPropertyAccessExpression(service) || !SignalMutationIndex.#isNamed(service.expression, "srv"))
+      return;
+    const model = service.name.text;
+    const capModel = `${model.charAt(0).toUpperCase()}${model.slice(1)}`;
+    for (const [verb, argCount] of Object.entries(SignalMutationIndex.#generatedArgCounts))
+      kinds.set(`${verb}${capModel}`, { kind: "mutation", argCount });
+    kinds.set(`add${capModel}Files`, { kind: "mutation", argCount: 2 });
+  }
+
+  static #collectEndpoints(endpoint: ts.CallExpression, kinds: Map<string, EndpointShape>) {
+    const builder = endpoint.arguments[1];
+    if (!builder || (!ts.isArrowFunction(builder) && !ts.isFunctionExpression(builder))) return;
+    const map = SignalMutationIndex.#returnedObjectOf(builder);
+    if (!map) return;
+    const verbOf = SignalMutationIndex.#verbReaderOf(builder.parameters[0]);
+    for (const property of map.properties) {
+      if (!ts.isPropertyAssignment(property)) continue;
+      if (!ts.isIdentifier(property.name) && !ts.isStringLiteral(property.name)) continue;
+      const { root, argCount } = SignalMutationIndex.#chainOf(property.initializer);
+      const verb = verbOf(root);
+      //? A socket message writes with the visitor's credential as a mutation does, and the client refuses it alike.
+      const kind = verb === "message" ? "mutation" : verb;
+      if (kind === "query" || kind === "mutation") kinds.set(property.name.text, { kind, argCount });
+    }
+  }
+
+  static #returnedObjectOf(builder: ts.ArrowFunction | ts.FunctionExpression) {
+    let body: ts.Node | undefined = builder.body;
+    if (ts.isBlock(body)) body = body.statements.find(ts.isReturnStatement)?.expression;
+    while (body && ts.isParenthesizedExpression(body)) body = body.expression;
+    return body && ts.isObjectLiteralExpression(body) ? body : null;
+  }
+
+  static #verbReaderOf(parameter: ts.ParameterDeclaration | undefined) {
+    const verbs = new Map<string, string>();
+    if (parameter && ts.isObjectBindingPattern(parameter.name))
+      for (const element of parameter.name.elements) {
+        const verb = element.propertyName ?? element.name;
+        if (ts.isIdentifier(verb) && ts.isIdentifier(element.name)) verbs.set(element.name.text, verb.text);
+      }
+    const holder = parameter && ts.isIdentifier(parameter.name) ? parameter.name.text : null;
+    return (callee: ts.Expression | undefined) => {
+      if (callee && ts.isIdentifier(callee)) return verbs.get(callee.text);
+      if (callee && ts.isPropertyAccessExpression(callee) && SignalMutationIndex.#isNamed(callee.expression, holder))
+        return callee.name.text;
+      return undefined;
+    };
+  }
+
+  static #isNamed(expression: ts.Expression, name: string | null) {
+    return ts.isIdentifier(expression) && expression.text === name;
+  }
+
+  static #chainOf(initializer: ts.Expression) {
+    let root = initializer;
+    let argCount = 0;
+    while (
+      ts.isCallExpression(root) &&
+      ts.isPropertyAccessExpression(root.expression) &&
+      ts.isCallExpression(root.expression.expression)
+    ) {
+      if (SignalMutationIndex.#argMethods.has(root.expression.name.text)) argCount += 1;
+      root = root.expression.expression;
+    }
+    return { root: ts.isCallExpression(root) ? root.expression : undefined, argCount };
+  }
+}

package/ssrScanner.test.ts

@@ -176,6 +176,37 @@ describe("akan.ssr.client-mount-load", () => {
   test("a store action that is not a load is not a finding", () => {
     expect(scanOne(UI, mount("void st.do.openModal();"))).not.toContain("akan.ssr.client-mount-load");
   });
+
+  test("never sends a mutation to the route", () => {
+    const signal = fileOf(
+      "apps/demo/lib/task/task.signal.ts",
+      `export class TaskEndpoint extends endpoint(srv.task, ({ mutation }) => ({ markTaskSeen: mutation(Boolean, {}).exec(() => true) })) {}`,
+    );
+    const [load, write] = new SsrScanner().scan([
+      signal,
+      fileOf(UI, mount("void fetch.viewTask(id); void fetch.markTaskSeen(id);")),
+    ]).warnings;
+    expect(load?.message).toContain("The route can fetch this");
+    expect(load?.fix).toBeUndefined();
+    expect(write?.rule).toBe("akan.ssr.client-mount-load");
+    expect(write?.message).toContain("sends the mutation fetch.markTaskSeen()");
+    expect(write?.fix).toContain("explicit user action");
+    expect(write?.fix).not.toContain("init/view");
+  });
+});
+
+describe("akan.ssr.render-mutation", () => {
+  test("is reported for a route file beside the component rules", () => {
+    const signal = fileOf(
+      "apps/demo/lib/task/task.signal.ts",
+      `export class TaskEndpoint extends endpoint(srv.task, ({ mutation }) => ({ approveTask: mutation(Boolean, {}).exec(() => true) })) {}`,
+    );
+    const route = fileOf(
+      "apps/demo/page/task/_index.tsx",
+      `import { fetch } from "@apps/demo/client";\nexport default page().render(async () => { await fetch.approveTask("x"); return null; });\n`,
+    );
+    expect(rulesOf(signal, route)).toEqual(["akan.ssr.render-mutation"]);
+  });
 });
 
 describe("akan.ssr.template-client-state", () => {

package/ssrScanner.ts

@@ -1,5 +1,7 @@
 import ts from "typescript";
 import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+import { RenderMutationScanner } from "./renderMutationScanner";
+import { SignalMutationIndex } from "./signalMutationIndex";
 
 /** Server/client render split for one app or lib, measured in JSX elements rather than files. */
 export interface SsrBalanceEntry {
@@ -50,19 +52,23 @@ export class SsrScanner {
   );
   // Runtime singletons that only exist in the client bundle; importing either is what forces the directive.
   static #clientRuntimeImports = new Set(["st", "fetch"]);
+  static #mountWriteFix =
+    "Send the write from an explicit user action, such as a button that calls a store action. Do not move it into the route: a write there runs for anyone who opens a link to the page.";
 
   scan(sourceFiles: SourceFileInfo[]): SsrScanResult {
+    const mutations = new SignalMutationIndex(sourceFiles);
     const componentFiles = sourceFiles.filter((sourceFile) => this.#isBalancedFile(sourceFile.file));
     return {
       warnings: [
-        ...componentFiles.flatMap((sourceFile) => this.#scanFile(sourceFile)),
+        ...componentFiles.flatMap((sourceFile) => this.#scanFile(sourceFile, mutations)),
         ...this.#scanModules(componentFiles),
+        ...new RenderMutationScanner(mutations).scan(sourceFiles),
       ],
       balance: this.#measureBalance(componentFiles),
     };
   }
 
-  #scanFile(sourceFile: SourceFileInfo): QualityWarning[] {
+  #scanFile(sourceFile: SourceFileInfo, mutations: SignalMutationIndex): QualityWarning[] {
     if (!this.#hasUseClient(sourceFile.sourceFile)) return [];
     const vendorNames = this.#getVendorNames(sourceFile.sourceFile);
     const hasVendorImport = this.#hasVendorImport(sourceFile.sourceFile);
@@ -118,7 +124,7 @@ export class SsrScanner {
       }
     }
 
-    warnings.push(...this.#getMountLoadWarnings(sourceFile));
+    warnings.push(...this.#getMountLoadWarnings(sourceFile, mutations));
     warnings.push(...this.#getTemplateStateWarnings(sourceFile));
     return warnings;
   }
@@ -147,20 +153,33 @@ export class SsrScanner {
   }
 
   // Only an empty-dependency effect is a finding: a reactive effect answers client state and has no server equivalent.
-  #getMountLoadWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
+  #getMountLoadWarnings(sourceFile: SourceFileInfo, mutations: SignalMutationIndex): QualityWarning[] {
     const warnings: QualityWarning[] = [];
     SsrScanner.#walk(sourceFile.sourceFile, (node) => {
       if (!this.#isMountEffect(sourceFile.sourceFile, node)) return;
-      for (const load of this.#getLoadCalls(sourceFile.sourceFile, node))
+      for (const load of this.#getLoadCalls(sourceFile.sourceFile, node)) {
+        const line = this.#getLine(sourceFile.sourceFile, load.node);
         warnings.push(
-          fileWarning(
-            "akan.ssr.client-mount-load",
-            "ssr",
-            sourceFile.file,
-            `Mount-only effect loads server data with ${load.callee}(). The route can fetch this before the first byte instead.`,
-            this.#getLine(sourceFile.sourceFile, load.node),
-          ),
+          load.callee.startsWith("fetch.") && mutations.isMutation(sourceFile.file, load.callee.slice("fetch.".length))
+            ? {
+                ...fileWarning(
+                  "akan.ssr.client-mount-load",
+                  "ssr",
+                  sourceFile.file,
+                  `Mount-only effect sends the mutation ${load.callee}() each time the component mounts. A write is not data the route can load.`,
+                  line,
+                ),
+                fix: SsrScanner.#mountWriteFix,
+              }
+            : fileWarning(
+                "akan.ssr.client-mount-load",
+                "ssr",
+                sourceFile.file,
+                `Mount-only effect loads server data with ${load.callee}(). The route can fetch this before the first byte instead.`,
+                line,
+              ),
         );
+      }
     });
     return warnings;
   }

package/uploadRelease.ts

@@ -1,80 +0,0 @@
-import { Logger, RestClient } from "akanjs/common";
-
-import { Spinner } from "./spinner";
-
-const spinning = (message: string) => new Spinner(message, { prefix: message, enableSpin: true }).start();
-
-export const uploadRelease = async (
-  appName: string,
-  {
-    workspaceRoot,
-    environment,
-    buildNum,
-    platformVersion,
-    os,
-    local,
-  }: {
-    workspaceRoot: string;
-    environment: string;
-    buildNum: number;
-    platformVersion?: string;
-    os?: "android" | "ios";
-    local?: boolean;
-  },
-) => {
-  const logger = new Logger("uploadRelease");
-  const basePath = local ? "http://localhost:8282/backend" : "https://cloud.akanjs.com/backend";
-  const httpClient = new RestClient(basePath);
-  const readingFilesSpinner = spinning("Reading files...");
-  try {
-    const uploads = [
-      [`builds/${appName}-release.tar.gz`, `${appName}-release.tar.gz`],
-      [`sources/${appName}-source.tar.gz`, `${appName}-source.tar.gz`],
-      [`builds/${appName}-appBuild.zip`, `${appName}-appBuild.zip`],
-    ].map(([relativePath, name]) => ({ file: Bun.file(`${workspaceRoot}/releases/${relativePath}`), name }));
-    const metas = uploads.map(({ file }) => ({ lastModifiedAt: new Date(file.lastModified), size: file.size }));
-    readingFilesSpinner.succeed("Reading files... done");
-
-    const preparingFormSpinner = spinning("Preparing form data...");
-    const formData = new FormData();
-    for (const { file, name } of uploads) formData.append("files", file, name);
-    formData.append("metas", JSON.stringify(metas));
-    formData.append("type", "release");
-    preparingFormSpinner.succeed("Preparing form data... done");
-
-    try {
-      const uploadingFilesSpinner = spinning("Uploading files to server...");
-      const [buildFile, sourceFile, appBuildFile] = await httpClient.post<
-        [{ id: string }, { id: string }, { id: string }]
-      >("/file/addFiles", formData);
-      uploadingFilesSpinner.succeed("Uploading files to server... done");
-
-      const fetchingAppSpinner = spinning(`Fetching dev app information for ${appName}...`);
-      const major = platformVersion ? parseInt(platformVersion.split(".")[0]) : 1;
-      const minor = platformVersion ? parseInt(platformVersion.split(".")[1]) : 0;
-      const patch = platformVersion ? parseInt(platformVersion.split(".")[2]) : 0;
-
-      const devApp = await httpClient.get<{ id: string }>(`/devApp/devAppInName/${appName}`);
-      fetchingAppSpinner.succeed(`Fetching dev app information for ${appName}... done`);
-
-      const pushingReleaseSpinner = spinning(`Pushing release to ${environment} environment...`);
-      const release = await httpClient.post<{ id: string }>(
-        `/release/pushRelease/${devApp.id}/${environment}/${major}/${minor}/${patch}/${sourceFile.id}/${buildFile.id}/${appBuildFile.id}${os ? `/${os}` : ""}`,
-      );
-      pushingReleaseSpinner.succeed(`Pushing release to ${environment} environment... done`);
-      new Spinner(`Successfully pushed release to ${appName}-${environment} server. `, {
-        prefix: `Successfully pushed release to ${appName}-${environment} server. `,
-        enableSpin: false,
-      }).succeed(`Successfully pushed release to ${appName}-${environment} server. `);
-      return release;
-    } catch (e) {
-      const errorMessage = e instanceof Error ? e.message : "Unknown error";
-      logger.error(`Upload release failed: ${errorMessage}`);
-      return null;
-    }
-  } catch (e) {
-    const errorMessage = e instanceof Error ? e.message : "Unknown error";
-    readingFilesSpinner.fail(`Reading files failed: ${errorMessage}`);
-    return null;
-  }
-};