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

package/mobile/tarWriter.ts

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { type FileHandle, open } from "node:fs/promises";
+
+//* An uncompressed POSIX tar of regular files, the same bytes on every OS. A system tar also writes what the host keeps
+//* beside a file (macOS bsdtar an AppleDouble `._` entry for extended attributes), which a receiver refusing unlisted
+//* entries rejects. A name past the ustar field's 100 bytes travels in a pax `path` record before its header.
+export class TarWriter {
+  static readonly #block = 512;
+  static readonly #nameBytes = 100;
+  //? The size field holds 11 octal digits.
+  static readonly #maxSize = 8 ** 11 - 1;
+  readonly #handle: FileHandle;
+  readonly #mtime: number;
+
+  private constructor(handle: FileHandle, mtime: number) {
+    this.#handle = handle;
+    this.#mtime = mtime;
+  }
+
+  //? `mtime` (seconds) goes on every entry, so the same files make the same archive.
+  static async create(file: string, { mtime = 0 }: { mtime?: number } = {}) {
+    return new TarWriter(await open(file, "wx"), mtime);
+  }
+
+  async add(name: string, source: Blob): Promise<string> {
+    const { size } = source;
+    if (size > TarWriter.#maxSize) throw new Error(`${name} is ${size} bytes, more than a tar entry holds.`);
+    if (Buffer.byteLength(name) > TarWriter.#nameBytes) {
+      const pax = Buffer.from(TarWriter.#paxRecord("path", name));
+      await this.#write(
+        TarWriter.#header(`./PaxHeaders/${name.split("/").at(-1) ?? ""}`, pax.length, this.#mtime, "x"),
+      );
+      await this.#write(pax);
+      await this.#pad(pax.length);
+    }
+    await this.#write(TarWriter.#header(name, size, this.#mtime, "0"));
+    const hasher = createHash("sha256");
+    let written = 0;
+    for await (const chunk of source.stream()) {
+      hasher.update(chunk);
+      await this.#write(chunk);
+      written += chunk.length;
+    }
+    if (written !== size) throw new Error(`${name} changed while it was archived: ${written} bytes, not ${size}.`);
+    await this.#pad(size);
+    return hasher.digest("hex");
+  }
+
+  async close() {
+    await this.#write(new Uint8Array(TarWriter.#block * 2));
+    await this.#handle.close();
+  }
+
+  async discard() {
+    await this.#handle.close().catch(() => undefined);
+  }
+
+  async #write(bytes: Uint8Array) {
+    for (let at = 0; at < bytes.length; ) at += (await this.#handle.write(bytes, at)).bytesWritten;
+  }
+
+  async #pad(size: number) {
+    const rest = size % TarWriter.#block;
+    if (rest) await this.#write(new Uint8Array(TarWriter.#block - rest));
+  }
+
+  //? A record's length counts its own digits: `<length> <key>=<value>\n`.
+  static #paxRecord(key: string, value: string) {
+    const body = Buffer.byteLength(` ${key}=${value}\n`);
+    let length = body + 1;
+    while (body + String(length).length !== length) length = body + String(length).length;
+    return `${length} ${key}=${value}\n`;
+  }
+
+  static #header(name: string, size: number, mtime: number, type: "0" | "x") {
+    const header = Buffer.alloc(TarWriter.#block);
+    header.write(name, 0, TarWriter.#nameBytes, "utf8");
+    const octal = (value: number, at: number, width: number) =>
+      header.write(`${value.toString(8).padStart(width - 1, "0")}\0`, at, width, "latin1");
+    octal(0o644, 100, 8);
+    octal(0, 108, 8);
+    octal(0, 116, 8);
+    octal(size, 124, 12);
+    octal(mtime, 136, 12);
+    header.write("        ", 148, 8, "latin1");
+    header.write(type, 156, 1, "latin1");
+    header.write("ustar\0", 257, 6, "latin1");
+    header.write("00", 263, 2, "latin1");
+    const checksum = header.reduce((sum, byte) => sum + byte, 0);
+    header.write(`${checksum.toString(8).padStart(6, "0")}\0 `, 148, 8, "latin1");
+    return header;
+  }
+}

package/mobile/updateUploader.test.ts

@@ -83,6 +83,40 @@ describe("UpdateUploader", () => {
     );
   });
 
+  test("uploads a desktop release's envelope, with the v1 pair only when the pair is that release", async () => {
+    const manifest = { kind: "app", bundle: "1.3.0-3000", archive: { url: `app/${sha("c")}.tar.gz` }, patches: [] };
+    await inUpdatesDir(
+      {
+        [`macos-arm64/app/${sha("c")}.tar.gz`]: "tar",
+        "macos-arm64/main/app.json": envelope(manifest),
+        "macos-arm64/main.json": JSON.stringify({ ...manifest, bundle: "1.2.0-2000" }),
+        "macos-arm64/main.json.sig": "sig",
+        "macos-arm64/beta/app.json": envelope({ ...manifest, bundle: "1.4.0-4000" }),
+        "macos-arm64/beta.json": JSON.stringify({ ...manifest, bundle: "1.4.0-4000" }),
+        "macos-arm64/beta.json.sig": "sig",
+      },
+      async (updatesDir) => {
+        const dir = path.join(updatesDir, "macos-arm64");
+        const upload = async (channel: string, bundle: string) => {
+          const { bucket, writes } = fakeBucket();
+          await new UpdateUploader(bucket, "").upload(updatesDir, { dir, channel, bundle });
+          return writes.map(({ key }) => key);
+        };
+
+        expect(await upload("main", "1.3.0-3000")).toEqual([
+          `macos-arm64/app/${sha("c")}.tar.gz`,
+          "macos-arm64/main/app.json",
+        ]);
+        expect(await upload("beta", "1.4.0-4000")).toEqual([
+          `macos-arm64/app/${sha("c")}.tar.gz`,
+          "macos-arm64/beta.json.sig",
+          "macos-arm64/beta.json",
+          "macos-arm64/beta/app.json",
+        ]);
+      },
+    );
+  });
+
   test("uploads a phone release's own files and envelope, never pack records or another manifest beside them", async () => {
     await inUpdatesDir(
       {

package/mobile/updateUploader.ts

@@ -51,12 +51,8 @@ export class UpdateUploader {
   //* APIs, which a later publish from another machine may have replaced.
   static async releaseFiles(updatesDir: string, { dir, channel, bundle }: PublishedUpdate): Promise<string[]> {
     const keyOf = (file: unknown) => UpdateUploader.#keyOf(updatesDir, dir, file);
-    const desktop = await UpdateUploader.#read<UpdateManifest>(path.join(dir, `${channel}.json`));
-    if (desktop?.bundle === bundle) {
-      const archive = desktop.archive?.url;
-      const patches = UpdateUploader.#field(desktop.patches, "url");
-      return [archive, ...patches, `${channel}.json.sig`, `${channel}.json`].map(keyOf);
-    }
+    const v1 = await UpdateUploader.#read<UpdateManifest>(path.join(dir, `${channel}.json`));
+    const pair = v1?.bundle === bundle ? [`${channel}.json.sig`, `${channel}.json`] : [];
     const names = await readdir(path.join(dir, channel)).catch(() => [] as string[]);
     for (const name of names.filter((name) => name.endsWith(".json"))) {
       const envelope = await UpdateUploader.#read<UpdateEnvelope>(path.join(dir, channel, name));
@@ -65,6 +61,8 @@ export class UpdateUploader {
           ? UpdateUploader.#parse<UpdateManifest>(Buffer.from(envelope.manifest, "base64").toString("utf8"))
           : null;
       if (manifest?.bundle !== bundle) continue;
+      if (manifest.kind === "app")
+        return [...UpdateUploader.#appFiles(manifest), ...pair, `${channel}/${name}`].map(keyOf);
       const hashes = [...new Set(UpdateUploader.#field(manifest.files, "sha256"))];
       if (!hashes.every((hash): hash is string => typeof hash === "string" && /^[0-9a-f]{64}$/.test(hash)))
         throw new Error(
@@ -72,9 +70,14 @@ export class UpdateUploader {
         );
       return [...hashes.map((hash) => `${UpdatePackFolder.filesDir}/${hash}`), `${channel}/${name}`].map(keyOf);
     }
+    if (v1 && pair.length) return [...UpdateUploader.#appFiles(v1), ...pair].map(keyOf);
     throw new Error(`${dir} holds no ${channel} manifest of release ${bundle}; nothing was uploaded.`);
   }
 
+  static #appFiles(manifest: Partial<UpdateManifest>): unknown[] {
+    return [manifest.archive?.url, ...UpdateUploader.#field(manifest.patches, "url")];
+  }
+
   static #keyOf(updatesDir: string, dir: string, file: unknown) {
     const resolved = typeof file === "string" ? path.resolve(dir, file) : "";
     const key = path.relative(updatesDir, resolved);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.1-rc.0",
+  "version": "3.1.1-rc.10",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -48,7 +48,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.1-rc.0",
+    "akanjs": "3.1.1-rc.10",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

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