@akanjs/devkit 3.1.0 → 3.1.1-rc.1

package/renderMutationScanner.test.ts

@@ -0,0 +1,223 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { RenderMutationScanner } from "./renderMutationScanner";
+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,
+    file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  ),
+});
+
+const signal = fileOf(
+  "apps/demo/lib/item/item.signal.ts",
+  `
+export class ItemSlice extends slice(srv.item, { guards: { root: Admin, get: Public, cru: User } }, () => ({})) {}
+export class ItemEndpoint extends endpoint(srv.item, ({ query, mutation }) => ({
+  approveItem: mutation(cnst.Item, { guards: [User] }).param("itemId", ID).exec(async function (itemId) {
+    return await this.itemService.approve(itemId);
+  }),
+  itemCount: query(Int, { guards: [User] }).exec(async function () {
+    return 0;
+  }),
+})) {}
+`,
+);
+
+const PAGE = "apps/demo/page/item/[itemId].tsx";
+const pageOf = (chain: string, file = PAGE) =>
+  fileOf(
+    file,
+    `import { fetch, usePage } from "@apps/demo/client";\nimport { ID } from "akanjs/base";\nimport { page } from "akanjs/client";\n\nexport default ${chain};\n`,
+  );
+
+const scan = (...files: SourceFileInfo[]) =>
+  new RenderMutationScanner(new SignalMutationIndex([signal, ...files])).scan(files);
+
+describe("akan.ssr.render-mutation", () => {
+  test("flags one diagnostic per mutation a render sends, awaited or not", () => {
+    const warnings = scan(
+      pageOf(`page()
+  .param("itemId", ID)
+  .render(async ({ itemId }) => {
+    const [item] = await Promise.all([fetch.approveItem(itemId), fetch.itemCount()]);
+    void fetch.updateItem(itemId, {});
+    return <p>{item.id}</p>;
+  })`),
+    );
+    expect(warnings.map(({ rule, line }) => ({ rule, line }))).toEqual([
+      { rule: "akan.ssr.render-mutation", line: 8 },
+      { rule: "akan.ssr.render-mutation", line: 9 },
+    ]);
+    expect(warnings[0]?.message).toContain("fetch.approveItem()");
+    expect(warnings[0]?.fix).toContain("{ duringRender: true }");
+  });
+
+  test("a query, a store action and a client loader are not findings", () => {
+    const warnings = scan(
+      pageOf(`page()
+  .param("itemId", ID)
+  .render(({ itemId }) => {
+    const { itemInitInOrg } = fetch.initItemInOrg(itemId);
+    return <Item.Zone.Card init={itemInitInOrg} count={fetch.itemCount()} />;
+  })`),
+    );
+    expect(warnings).toEqual([]);
+  });
+
+  test("a JSX event handler runs on a user action, while a mapped call still runs in the render", () => {
+    const warnings = scan(
+      pageOf(`page()
+  .param("itemId", ID)
+  .render(({ itemId }) => {
+    return (
+      <form onSubmit={async () => { await fetch.approveItem(itemId); }}>
+        {[itemId].map((id) => <p key={id}>{String(fetch.approveItem(id))}</p>)}
+      </form>
+    );
+  })`),
+    );
+    expect(warnings.map(({ line }) => line)).toEqual([10]);
+  });
+
+  test("a call that opts in with { duringRender: true } is not a finding", () => {
+    expect(
+      scan(
+        pageOf(
+          `page().param("itemId", ID).render(async ({ itemId }) => { await fetch.approveItem(itemId, { duringRender: true }); return null; })`,
+        ),
+      ),
+    ).toEqual([]);
+    expect(
+      scan(
+        pageOf(`page().render(async () => { await fetch.approveItem("x", { duringRender: false }); return null; })`),
+      ),
+    ).toHaveLength(1);
+  });
+
+  test("reads the opt-in only from the slot the runtime reads, right after the declared arguments", () => {
+    const renderOf = (call: string) =>
+      scan(pageOf(`page().param("itemId", ID).render(async ({ itemId }) => { await ${call}; return null; })`)).length;
+    expect(renderOf(`fetch.updateItem(itemId, { duringRender: true })`)).toBe(1);
+    expect(renderOf(`fetch.updateItem(itemId, { title: "x", duringRender: true })`)).toBe(1);
+    expect(renderOf(`fetch.updateItem(itemId, { title: "x" }, { duringRender: true })`)).toBe(0);
+    expect(renderOf(`fetch.mergeItem(itemId, {}, { duringRender: true } as const)`)).toBe(0);
+    expect(renderOf(`fetch.addItemFiles([], { duringRender: true })`)).toBe(1);
+    expect(renderOf(`fetch.addItemFiles([], undefined, { duringRender: true })`)).toBe(0);
+    expect(renderOf(`fetch.createItem({ duringRender: true })`)).toBe(1);
+    expect(renderOf(`fetch.approveItem(itemId, { "duringRender": true })`)).toBe(0);
+    expect(renderOf(`fetch.approveItem(itemId, { duringRender: undefined })`)).toBe(1);
+  });
+
+  test("takes a policy it cannot evaluate as an opt-in, and a value that cannot be one as none", () => {
+    const renderOf = (call: string) =>
+      scan(
+        pageOf(
+          `page().param("itemId", ID).render(async ({ itemId }) => { const warm = { duringRender: true }; await ${call}; return null; })`,
+        ),
+      ).length;
+    for (const call of [
+      "fetch.approveItem(itemId, warm)",
+      "fetch.approveItem(itemId, { ...warm })",
+      "fetch.approveItem(itemId, policyOf(itemId))",
+      "fetch.approveItem(...[itemId, warm])",
+    ])
+      expect(renderOf(call)).toBe(0);
+    for (const call of [
+      "fetch.approveItem(itemId, undefined)",
+      "fetch.approveItem(itemId, null)",
+      'fetch.approveItem(itemId, "warm")',
+      "fetch.updateItem(itemId, warm)",
+    ])
+      expect(renderOf(call)).toBe(1);
+  });
+
+  test("follows a same-file function the stage calls or renders, one level deep", () => {
+    const file = fileOf(
+      PAGE,
+      `import { fetch } from "@apps/demo/client";
+import { ID } from "akanjs/base";
+import { page } from "akanjs/client";
+
+const approve = async (id: string) => await fetch.approveItem(id);
+function Approval({ id }: { id: string }) {
+  void fetch.removeItem(id);
+  return null;
+}
+const unused = async () => await fetch.createItem({});
+const onClickOnly = () => fetch.updateItem("x", {});
+
+export default page()
+  .param("itemId", ID)
+  .render(async ({ itemId }) => {
+    await approve(itemId);
+    return <Approval id={itemId} onSelect={onClickOnly} />;
+  });
+`,
+    );
+    expect(scan(file).map(({ line }) => line)).toEqual([5, 7]);
+  });
+
+  test("reads a page exported by name, a stage given by name and a call by string key", () => {
+    const legacy = fileOf(
+      PAGE,
+      `import { fetch } from "@apps/demo/client";\nconst Page = async () => {\n  await fetch.approveItem("x");\n  return null;\n};\nexport default Page;\n`,
+    );
+    expect(scan(legacy).map(({ line }) => line)).toEqual([3]);
+    const named = fileOf(
+      PAGE,
+      `import { fetch } from "@apps/demo/client";\nimport { page } from "akanjs/client";\nconst render = async () => {\n  await fetch["approveItem"]("x");\n  return null;\n};\nexport default page().render(render);\n`,
+    );
+    expect(scan(named).map(({ line, message }) => [line, message.split("()")[0]])).toEqual([
+      [4, 'fetch["approveItem"]'],
+    ]);
+  });
+
+  test("reads the guard, the head and a layout's render too", () => {
+    const guarded = pageOf(`page()
+  .guard(async () => { await fetch.removeItem("x"); })
+  .head(async () => { await fetch.approveItem("x"); return <title>x</title>; })
+  .render(() => null)`);
+    const wrapping = pageOf(
+      `layout().render(async ({ children }) => { await fetch.createItem({}); return children; })`,
+      "apps/demo/page/item/_layout.tsx",
+    );
+    expect(scan(guarded, wrapping).map(({ file, line }) => `${file}:${line}`)).toEqual([
+      `${PAGE}:6`,
+      `${PAGE}:7`,
+      "apps/demo/page/item/_layout.tsx:5",
+    ]);
+  });
+
+  test("reads a legacy default-exported page function", () => {
+    expect(scan(pageOf(`async function Page() { await fetch.approveItem("x"); return null; }`))).toHaveLength(1);
+  });
+
+  test("an app load, a file outside page/ and a page with no fetch import are not read", () => {
+    expect(
+      scan(
+        pageOf(
+          `page().app("showItem", "Show the item.", async () => { await fetch.approveItem("x"); return null; }).render(() => null)`,
+        ),
+      ),
+    ).toEqual([]);
+    expect(
+      scan(
+        pageOf(`page().render(async () => { await fetch.approveItem("x"); return null; })`, "apps/demo/ui/Item.tsx"),
+      ),
+    ).toEqual([]);
+    const global = fileOf(
+      PAGE,
+      `export default page().render(async () => { await fetch.approveItem("x"); return null; });`,
+    );
+    expect(scan(global)).toEqual([]);
+  });
+});

package/renderMutationScanner.ts

@@ -0,0 +1,209 @@
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+import type { SignalMutationIndex } from "./signalMutationIndex";
+
+//? A server render sends the visitor's credential with no Origin, so its writes run for whoever opens a link.
+export class RenderMutationScanner {
+  static readonly rule = "akan.ssr.render-mutation";
+  static readonly fix =
+    "Send the write from an explicit user action, such as a button that calls a store action. Only a write that is harmless to repeat and safe for anyone to trigger may stay in the render, with `{ duringRender: true }` as the call's option.";
+  static #builders = new Set(["page", "layout", "rootLayout"]);
+  static #stages = new Set(["render", "guard", "head", "loading", "notFound", "error"]);
+  readonly #mutations: SignalMutationIndex;
+
+  constructor(mutations: SignalMutationIndex) {
+    this.#mutations = mutations;
+  }
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    return sourceFiles
+      .filter(({ file }) => /^(apps|libs)\/[^/]+\/page\/.+(?<!\.test|\.spec)\.tsx$/.test(file))
+      .flatMap((sourceFile) => this.#scanRoute(sourceFile));
+  }
+
+  #scanRoute({ file, sourceFile }: SourceFileInfo): QualityWarning[] {
+    const fetchNames = RenderMutationScanner.#fetchBindingsOf(sourceFile);
+    if (!fetchNames.size) return [];
+    const functions = RenderMutationScanner.#functionsOf(sourceFile);
+    const calls = new Set<ts.CallExpression>();
+    const helpers = new Set<ts.Node>();
+    const visit = (node: ts.Node, follow: boolean) => {
+      if (RenderMutationScanner.#isEventHandler(node)) return;
+      if (this.#isRenderMutation(file, node, fetchNames)) calls.add(node);
+      const helper = follow ? RenderMutationScanner.#helperOf(node, functions) : undefined;
+      if (helper) helpers.add(helper);
+      ts.forEachChild(node, (child) => visit(child, follow));
+    };
+    for (const body of RenderMutationScanner.#renderBodiesOf(sourceFile, functions)) visit(body, true);
+    for (const helper of helpers) visit(helper, false);
+    return [...calls]
+      .sort((a, b) => a.getStart(sourceFile) - b.getStart(sourceFile))
+      .map((call) => ({
+        rule: RenderMutationScanner.rule,
+        scope: "ssr",
+        severity: "warning",
+        file,
+        line: sourceFile.getLineAndCharacterOfPosition(call.getStart(sourceFile)).line + 1,
+        message: `${call.expression.getText(sourceFile)}() is a mutation sent while the route renders: anyone who opens a link to this page would perform it, and the call is refused unless it passes { duringRender: true }.`,
+        fix: RenderMutationScanner.fix,
+      }));
+  }
+
+  #isRenderMutation(file: string, node: ts.Node, fetchNames: Set<string>): node is ts.CallExpression {
+    if (!ts.isCallExpression(node)) return false;
+    const name = RenderMutationScanner.#endpointOf(node.expression, fetchNames);
+    if (!name || !this.#mutations.isMutation(file, name)) return false;
+    return !RenderMutationScanner.#optsIn(node, this.#mutations.policyIndexOf(file, name));
+  }
+
+  static #isEventHandler(node: ts.Node) {
+    return ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && /^on[A-Z]/.test(node.name.text);
+  }
+
+  static #endpointOf(callee: ts.Expression, fetchNames: Set<string>) {
+    if (ts.isPropertyAccessExpression(callee))
+      return RenderMutationScanner.#isFetch(callee.expression, fetchNames) ? callee.name.text : null;
+    if (ts.isElementAccessExpression(callee) && ts.isStringLiteralLike(callee.argumentExpression))
+      return RenderMutationScanner.#isFetch(callee.expression, fetchNames) ? callee.argumentExpression.text : null;
+    return null;
+  }
+
+  static #isFetch(expression: ts.Expression, fetchNames: Set<string>) {
+    return ts.isIdentifier(expression) && fetchNames.has(expression.text);
+  }
+
+  //? The runtime reads only the policy slot, and a value there this cannot evaluate (a variable, a call) may opt in.
+  static #optsIn(call: ts.CallExpression, policyIndex: number | null) {
+    if (policyIndex === null) return false;
+    const leading = call.arguments.slice(0, policyIndex + 1);
+    if (leading.some((argument) => ts.isSpreadElement(argument))) return true;
+    const policy = leading[policyIndex];
+    return policy ? RenderMutationScanner.#policyOptsIn(policy) : false;
+  }
+
+  static #policyOptsIn(argument: ts.Expression): boolean {
+    const policy = RenderMutationScanner.#unwrap(argument);
+    if (!ts.isObjectLiteralExpression(policy)) return !RenderMutationScanner.#cannotBePolicy(policy);
+    return policy.properties.some((property) => {
+      if (ts.isSpreadAssignment(property)) return true;
+      if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property)) return false;
+      if (!(ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))) return false;
+      if (property.name.text !== "duringRender") return false;
+      if (ts.isShorthandPropertyAssignment(property)) return true;
+      const value = RenderMutationScanner.#unwrap(property.initializer);
+      return value.kind !== ts.SyntaxKind.FalseKeyword && !(ts.isIdentifier(value) && value.text === "undefined");
+    });
+  }
+
+  static #unwrap(expression: ts.Expression): ts.Expression {
+    let current = expression;
+    while (
+      ts.isParenthesizedExpression(current) ||
+      ts.isAsExpression(current) ||
+      ts.isSatisfiesExpression(current) ||
+      ts.isNonNullExpression(current) ||
+      ts.isTypeAssertionExpression(current)
+    )
+      current = current.expression;
+    return current;
+  }
+
+  static #cannotBePolicy(expression: ts.Expression) {
+    if (ts.isIdentifier(expression)) return expression.text === "undefined";
+    return (
+      ts.isLiteralExpression(expression) ||
+      ts.isNoSubstitutionTemplateLiteral(expression) ||
+      ts.isTemplateExpression(expression) ||
+      ts.isArrayLiteralExpression(expression) ||
+      ts.isArrowFunction(expression) ||
+      ts.isFunctionExpression(expression) ||
+      ts.isVoidExpression(expression) ||
+      ts.isPrefixUnaryExpression(expression) ||
+      [ts.SyntaxKind.NullKeyword, ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(expression.kind)
+    );
+  }
+
+  static #fetchBindingsOf(sourceFile: ts.SourceFile) {
+    const names = new Set<string>();
+    for (const statement of sourceFile.statements) {
+      if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly) continue;
+      const bindings = statement.importClause?.namedBindings;
+      if (!bindings || !ts.isNamedImports(bindings)) continue;
+      for (const element of bindings.elements)
+        if (!element.isTypeOnly && (element.propertyName ?? element.name).text === "fetch")
+          names.add(element.name.text);
+    }
+    return names;
+  }
+
+  static #functionsOf(sourceFile: ts.SourceFile) {
+    const functions = new Map<string, ts.Node>();
+    for (const statement of sourceFile.statements) {
+      if (ts.isFunctionDeclaration(statement) && statement.name && statement.body)
+        functions.set(statement.name.text, statement.body);
+      if (!ts.isVariableStatement(statement)) continue;
+      for (const declaration of statement.declarationList.declarations) {
+        const initializer = declaration.initializer && RenderMutationScanner.#unwrap(declaration.initializer);
+        if (!ts.isIdentifier(declaration.name) || !initializer) continue;
+        if (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer))
+          functions.set(declaration.name.text, initializer.body);
+      }
+    }
+    return functions;
+  }
+
+  //? One level only: a function the stage calls, or renders as a component, runs while the route renders.
+  static #helperOf(node: ts.Node, functions: Map<string, ts.Node>) {
+    const callee = ts.isCallExpression(node)
+      ? node.expression
+      : ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)
+        ? node.tagName
+        : undefined;
+    return callee && ts.isIdentifier(callee) ? functions.get(callee.text) : undefined;
+  }
+
+  static #renderBodiesOf(sourceFile: ts.SourceFile, functions: Map<string, ts.Node>) {
+    const bodies: ts.Node[] = [];
+    const bodyOf = (node: ts.Node) => (ts.isIdentifier(node) ? functions.get(node.text) : node);
+    const visit = (node: ts.Node) => {
+      if (
+        ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        RenderMutationScanner.#stages.has(node.expression.name.text) &&
+        RenderMutationScanner.#isRouteChain(node.expression.expression)
+      )
+        for (const argument of node.arguments) {
+          const body = bodyOf(argument);
+          if (body) bodies.push(body);
+        }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    for (const statement of sourceFile.statements) {
+      const legacy = RenderMutationScanner.#legacyPageOf(statement, functions);
+      if (legacy) bodies.push(legacy);
+    }
+    return bodies;
+  }
+
+  static #isRouteChain(expression: ts.Expression) {
+    let current = expression;
+    while (ts.isCallExpression(current)) {
+      if (ts.isIdentifier(current.expression)) return RenderMutationScanner.#builders.has(current.expression.text);
+      if (!ts.isPropertyAccessExpression(current.expression)) return false;
+      current = current.expression.expression;
+    }
+    return false;
+  }
+
+  static #legacyPageOf(statement: ts.Statement, functions: Map<string, ts.Node>) {
+    if (ts.isFunctionDeclaration(statement))
+      return statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword)
+        ? statement.body
+        : undefined;
+    if (!ts.isExportAssignment(statement)) return undefined;
+    const expression = RenderMutationScanner.#unwrap(statement.expression);
+    if (ts.isIdentifier(expression)) return functions.get(expression.text);
+    return ts.isArrowFunction(expression) || ts.isFunctionExpression(expression) ? expression.body : undefined;
+  }
+}

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