@akanjs/devkit 3.1.1-rc.15 → 3.1.1-rc.17

package/writePlacementScanner.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { SignalMutationIndex } from "./signalMutationIndex";
+import { WritePlacementScanner } from "./writePlacementScanner";
+import { WritingActionIndex } from "./writingActionIndex";
+
+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 index = new WritingActionIndex(
+  new SignalMutationIndex([
+    fileOf(
+      "apps/demo/lib/court/court.signal.ts",
+      `export class CourtEndpoint extends endpoint(srv.court, ({ query, mutation }) => ({
+  skipNvrOnCourt: mutation(cnst.Court, { guards: [User] }).param("courtId", ID).exec(() => null),
+  courtCount: query(Int, { guards: [User] }).exec(() => 0),
+})) {}
+`,
+    ),
+  ]),
+  [
+    fileOf(
+      "apps/demo/lib/court/court.store.ts",
+      `import { fetch, sig } from "../useClient";
+export class CourtStore extends store(sig.court, () => ({})) {
+  async skipNvrOnCourt(courtId: string) {
+    this.setCourt(await fetch.skipNvrOnCourt(courtId));
+  }
+  setPicked(courtId: string) {
+    this.set({ picked: courtId });
+  }
+}
+`,
+    ),
+  ],
+);
+
+const scan = (file: string, body: string) => {
+  const content = `"use client";\nimport { fetch as api, st } from "@apps/demo/client";\n\n${body}\n`;
+  return new WritePlacementScanner(index).scan(
+    file,
+    `apps/demo/${file}`,
+    fileOf(`apps/demo/${file}`, content).sourceFile,
+  );
+};
+
+describe("WritePlacementScanner", () => {
+  test("names every server write a ui/ or webkit/ file sends, by call or by reference, under any import name", () => {
+    expect(
+      scan(
+        "webkit/useSkip.tsx",
+        "export const useSkip = (courtId: string) => ({\n  skip: () => st.do.skipNvrOnCourt(courtId),\n  bound: st.do.skipNvrOnCourt,\n  count: () => api.courtCount(),\n  direct: () => api.skipNvrOnCourt(courtId),\n});",
+      ),
+    ).toEqual({ line: 5, writes: ["st.do.skipNvrOnCourt", "st.do.skipNvrOnCourt", "api.skipNvrOnCourt"] });
+  });
+
+  test("lets a module component call a writing action, and a ui/ file set client state, but not a fetch mutation", () => {
+    expect(
+      scan("lib/court/Court.Zone.tsx", "export const Skip = ({ id }: { id: string }) => st.do.skipNvrOnCourt(id);"),
+    ).toBeNull();
+    expect(scan("ui/Pick.tsx", "export const Pick = ({ id }: { id: string }) => st.do.setPicked(id);")).toBeNull();
+    expect(
+      scan("lib/court/Court.Zone.tsx", "export const Skip = ({ id }: { id: string }) => api.skipNvrOnCourt(id);"),
+    ).toEqual({ line: 4, writes: ["api.skipNvrOnCourt"] });
+  });
+});

package/writePlacementScanner.ts

@@ -0,0 +1,50 @@
+import ts from "typescript";
+import { StoreAccessScanner } from "./storeAccessScanner";
+import type { WritingActionIndex } from "./writingActionIndex";
+
+export interface WritePlacement {
+  line: number;
+  writes: string[];
+}
+
+//* A write leaves the browser through one store action, started by one module component: an agent, a test or another
+//* screen reaches it through the store, and `ui/` / `webkit/` stay free of any one model.
+export class WritePlacementScanner {
+  readonly #index: WritingActionIndex;
+
+  constructor(index: WritingActionIndex) {
+    this.#index = index;
+  }
+
+  scan(file: string, workspaceFile: string, sourceFile: ts.SourceFile): WritePlacement | null {
+    const fetchNames = StoreAccessScanner.localNamesOf(sourceFile, "fetch");
+    const stNames = file.startsWith("lib/") ? new Set<string>() : StoreAccessScanner.stNamesOf(sourceFile);
+    if (!fetchNames.size && !stNames.size) return null;
+    const sites: ts.PropertyAccessExpression[] = [];
+    const visit = (node: ts.Node) => {
+      if (ts.isPropertyAccessExpression(node) && this.#isWrite(node, workspaceFile, fetchNames, stNames))
+        sites.push(node);
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    const first = sites[0];
+    if (!first) return null;
+    return {
+      line: sourceFile.getLineAndCharacterOfPosition(first.getStart(sourceFile)).line + 1,
+      writes: sites.map((site) => site.getText(sourceFile)),
+    };
+  }
+
+  #isWrite(access: ts.PropertyAccessExpression, workspaceFile: string, fetchNames: Set<string>, stNames: Set<string>) {
+    const owner = access.expression;
+    if (ts.isIdentifier(owner) && fetchNames.has(owner.text))
+      return this.#index.isMutation(workspaceFile, access.name.text);
+    return (
+      ts.isPropertyAccessExpression(owner) &&
+      owner.name.text === "do" &&
+      ts.isIdentifier(owner.expression) &&
+      stNames.has(owner.expression.text) &&
+      this.#index.isWritingAction(access.name.text)
+    );
+  }
+}

package/writingActionIndex.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { SignalMutationIndex } from "./signalMutationIndex";
+import { WritingActionIndex } from "./writingActionIndex";
+
+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 signals = [
+  fileOf(
+    "apps/demo/lib/court/court.signal.ts",
+    `export class CourtSlice extends slice(srv.court, { guards: { root: Admin, cru: User } }, () => ({})) {}
+export class CourtEndpoint extends endpoint(srv.court, ({ query, mutation }) => ({
+  courtCount: query(Int, { guards: [User] }).exec(() => 0),
+})) {}
+`,
+  ),
+  fileOf(
+    "libs/shared/lib/push/push.signal.ts",
+    `export class PushEndpoint extends endpoint(srv.push, ({ mutation }) => ({
+  pushPcCommand: mutation(Boolean, { guards: [User] }).param("courtId", ID).exec(() => true),
+})) {}
+`,
+  ),
+];
+
+const courtStore = fileOf(
+  "apps/demo/lib/court/court.store.ts",
+  `import { fetch, sig } from "../useClient";
+export class CourtStore extends store(sig.court, () => ({})) {
+  async countCourts() {
+    this.set({ count: await fetch.courtCount() });
+  }
+  async openCourt(courtId: string) {
+    const root = this as unknown as RootStore;
+    await root.restartPc(courtId);
+  }
+  async refreshAfterOpen(courtId: string) {
+    await this.openCourt(courtId);
+    await this.countCourts();
+  }
+}
+`,
+);
+const pcStore = fileOf(
+  "apps/demo/lib/_pc/pc.store.ts",
+  `import { fetch, sig } from "../useClient";
+export class PcStore extends store(sig.pc, () => ({})) {
+  async restartPc(courtId: string) {
+    await PcStore.sendRestart(courtId);
+  }
+  static async sendRestart(courtId: string) {
+    await fetch.pushPcCommand(courtId);
+  }
+}
+`,
+);
+
+const indexOf = (storeFiles: SourceFileInfo[]) => new WritingActionIndex(new SignalMutationIndex(signals), storeFiles);
+
+describe("WritingActionIndex", () => {
+  test("holds the generated actions that send a mutation for a model with a slice, not its form setters", () => {
+    const index = indexOf([courtStore, pcStore]);
+    for (const name of [
+      "createCourt",
+      "updateCourt",
+      "removeCourt",
+      "mergeCourt",
+      "createCourtInForm",
+      "updateCourtInForm",
+      "submitCourt",
+    ])
+      expect(index.isWritingAction(name)).toBe(true);
+    for (const name of ["setNameOnCourt", "writeOnCourt", "uploadImageOnCourt", "newCourt", "editCourt", "viewCourt"])
+      expect(index.isWritingAction(name)).toBe(false);
+    expect(index.isWritingAction("createPc")).toBe(false);
+  });
+
+  test("follows writes through a static helper, the RootStore alias and a sibling action to a fixed point", () => {
+    const index = indexOf([courtStore, pcStore]);
+
+    expect(index.isWritingAction("restartPc")).toBe(true);
+    expect(index.isWritingAction("openCourt")).toBe(true);
+    expect(index.isWritingAction("refreshAfterOpen")).toBe(true);
+    expect(index.isWritingAction("countCourts")).toBe(false);
+  });
+
+  test("knows no action of a store it was not given", () => {
+    const index = indexOf([courtStore]);
+
+    expect(index.isWritingAction("restartPc")).toBe(false);
+    expect(index.isWritingAction("openCourt")).toBe(false);
+  });
+});

package/writingActionIndex.ts

@@ -0,0 +1,63 @@
+import type ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import type { SignalMutationIndex } from "./signalMutationIndex";
+import { type StoreCallTarget, type StoreMethod, StoreSource } from "./storeSource";
+
+//? Stores merge into one root, so an action name means one action wherever it is called from.
+export class WritingActionIndex {
+  readonly #mutations: SignalMutationIndex;
+  readonly #actions = new Set<string>();
+  readonly #statics = new Set<string>();
+
+  constructor(mutations: SignalMutationIndex, storeFiles: Pick<SourceFileInfo, "file" | "sourceFile">[]) {
+    this.#mutations = mutations;
+    const sources = storeFiles.map((storeFile) => new StoreSource(storeFile));
+    for (const source of sources)
+      for (const { refName } of source.stores) {
+        const generated = refName ? StoreSource.generatedWritesOf(refName) : [];
+        if (generated[0] && mutations.isMutation(source.file, generated[0]))
+          for (const name of generated) this.#actions.add(name);
+      }
+    const methods = sources.flatMap((source) =>
+      source.methods.map((method) => ({ file: source.file, method, targets: source.targetsIn(method) })),
+    );
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const { file, method, targets } of methods) {
+        if (this.#holds(method) || !targets.some((target) => this.#writes(file, target))) continue;
+        if (method.isStatic) this.#statics.add(`${method.store}.${method.name}`);
+        else this.#actions.add(method.name);
+        grew = true;
+      }
+    }
+  }
+
+  isWritingAction(name: string) {
+    return this.#actions.has(name);
+  }
+
+  isMutation(consumerFile: string, name: string) {
+    return this.#mutations.isMutation(consumerFile, name);
+  }
+
+  writeOf(source: StoreSource, method: StoreMethod, call: ts.CallExpression): StoreCallTarget | null {
+    const target = source.targetOf(method, call);
+    if (!target || !this.#writes(source.file, target)) return null;
+    const isSelf =
+      target.kind !== "fetch" &&
+      target.name === method.name &&
+      (target.kind === "static" ? method.isStatic && target.store === method.store : !method.isStatic);
+    return isSelf ? null : target;
+  }
+
+  #holds(method: StoreMethod) {
+    return method.isStatic ? this.#statics.has(`${method.store}.${method.name}`) : this.#actions.has(method.name);
+  }
+
+  #writes(file: string, target: StoreCallTarget) {
+    if (target.kind === "fetch") return this.#mutations.isMutation(file, target.name);
+    if (target.kind === "action") return this.#actions.has(target.name);
+    return this.#statics.has(`${target.store}.${target.name}`);
+  }
+}