@akanjs/devkit 3.1.1-rc.8 → 3.1.1

package/serviceLoopCallScanner.ts

@@ -0,0 +1,122 @@
+import ts from "typescript";
+import { WritePath } from "./writePath";
+
+export interface ServiceLoopCall {
+  method: string;
+  line: number;
+  calls: string[];
+}
+
+type NamedMethod = ts.MethodDeclaration & { name: ts.Identifier | ts.PrivateIdentifier };
+
+type PerItem = false | "loop" | "callback";
+
+//? A counted loop (`for (;;)`, `while`) retries or pages through a query, so only a loop over items is per item.
+export class ServiceLoopCallScanner {
+  static readonly #reachingField = /(?:Service|Model)$/;
+  static readonly #generatedQuery =
+    /^_*(?:get|load|list|find|pick|exists|count|insight|create|update|remove|search)[A-Z]/;
+
+  scan(sourceFile: ts.SourceFile, answersCaller: (method: string) => boolean): ServiceLoopCall[] {
+    return sourceFile.statements.filter(ts.isClassDeclaration).flatMap((cls) => {
+      const methods = cls.members.filter(
+        (member): member is NamedMethod =>
+          ts.isMethodDeclaration(member) &&
+          !!member.body &&
+          (ts.isIdentifier(member.name) || ts.isPrivateIdentifier(member.name)),
+      );
+      const declared = new Set(methods.map((method) => method.name.text));
+      const reaching = ServiceLoopCallScanner.#reachingMethodsOf(methods, declared);
+      const reaches = (call: ts.CallExpression) => ServiceLoopCallScanner.#reaches(call, declared, reaching);
+      const ownModel = cls.name?.text.replace(/Service$/, "") ?? "";
+      return methods.flatMap((method) => {
+        if (!answersCaller(method.name.text)) return [];
+        const calls: ts.CallExpression[] = [];
+        const visit = (node: ts.Node, perItem: PerItem) => {
+          if (
+            perItem &&
+            ts.isCallExpression(node) &&
+            reaches(node) &&
+            !(perItem === "callback" && ServiceLoopCallScanner.#isBatchedLoad(node, declared, ownModel))
+          )
+            calls.push(node);
+          if (ts.isForOfStatement(node) || ts.isForInStatement(node)) {
+            visit(node.expression, perItem);
+            visit(node.statement, "loop");
+            return;
+          }
+          ts.forEachChild(node, (child) =>
+            visit(child, perItem === "loop" || !WritePath.isPerElementCallback(child) ? perItem : "callback"),
+          );
+        };
+        visit(method, false);
+        const first = calls[0];
+        if (!first) return [];
+        return [
+          {
+            method: method.name.text,
+            line: sourceFile.getLineAndCharacterOfPosition(first.getStart(sourceFile)).line + 1,
+            calls: calls.map((call) => call.expression.getText(sourceFile)),
+          },
+        ];
+      });
+    });
+  }
+
+  static #reachingMethodsOf(methods: NamedMethod[], declared: Set<string>) {
+    const reaching = new Set<string>();
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const method of methods) {
+        const name = method.name.text;
+        if (reaching.has(name)) continue;
+        let found = false;
+        const visit = (node: ts.Node) => {
+          if (found) return;
+          if (ts.isCallExpression(node) && ServiceLoopCallScanner.#reaches(node, declared, reaching)) found = true;
+          else ts.forEachChild(node, visit);
+        };
+        visit(method);
+        if (found) {
+          reaching.add(name);
+          grew = true;
+        }
+      }
+    }
+    return reaching;
+  }
+
+  //? `get<Model>` / `load<Model>` / `load<Model>Many` go through the model's DataLoader, so the calls a per-element
+  //? callback issues in one tick are one query; a `for…of` awaiting each item issues them a tick apart, one by one.
+  static #isBatchedLoad(call: ts.CallExpression, declared: Set<string>, ownModel: string) {
+    const callee = call.expression;
+    if (!ts.isPropertyAccessExpression(callee)) return false;
+    const model = ServiceLoopCallScanner.#loadedModelOf(callee, declared, ownModel);
+    if (!model) return false;
+    const className = `${model.charAt(0).toUpperCase()}${model.slice(1)}`;
+    return [`get${className}`, `load${className}`, `load${className}Many`].includes(callee.name.text);
+  }
+
+  static #loadedModelOf(callee: ts.PropertyAccessExpression, declared: Set<string>, ownModel: string) {
+    const owner = callee.expression;
+    if (owner.kind === ts.SyntaxKind.ThisKeyword) return declared.has(callee.name.text) ? null : ownModel;
+    if (!ts.isPropertyAccessExpression(owner) || owner.expression.kind !== ts.SyntaxKind.ThisKeyword) return null;
+    return owner.name.text.match(/^(\w+)Model$/)?.[1] ?? null;
+  }
+
+  static #reaches(call: ts.CallExpression, declared: Set<string>, reaching: Set<string>) {
+    const callee = call.expression;
+    if (!ts.isPropertyAccessExpression(callee)) return false;
+    const owner = callee.expression;
+    if (owner.kind === ts.SyntaxKind.ThisKeyword) {
+      const name = callee.name.text;
+      return declared.has(name) ? reaching.has(name) : ServiceLoopCallScanner.#generatedQuery.test(name);
+    }
+    return (
+      ts.isPropertyAccessExpression(owner) &&
+      owner.expression.kind === ts.SyntaxKind.ThisKeyword &&
+      ServiceLoopCallScanner.#reachingField.test(owner.name.text)
+    );
+  }
+}

package/signalMutationIndex.test.ts

@@ -110,6 +110,21 @@ export class ItemEndpoint extends endpoint(srv.item, ({ query, mutation }) => ({
     expect(index.isMutation("apps/third/page/x.tsx", "approveTicket")).toBe(false);
   });
 
+  test("reads a lib page's call by its own lib's endpoint before another lib's of that name", () => {
+    const shared = fileOf(
+      "libs/shared/lib/_shared/shared.signal.ts",
+      `export class SharedEndpoint extends endpoint(srv.shared, ({ mutation }) => ({ syncFeed: mutation(Boolean, {}).exec(() => true) })) {}`,
+    );
+    const social = fileOf(
+      "libs/social/lib/_social/social.signal.ts",
+      `export class SocialEndpoint extends endpoint(srv.social, ({ query }) => ({ syncFeed: query(Boolean, {}).exec(() => true) })) {}`,
+    );
+    const index = new SignalMutationIndex([shared, social]);
+    expect(index.isMutation("libs/social/page/x.tsx", "syncFeed")).toBe(false);
+    expect(index.policyIndexOf("libs/social/page/x.tsx", "syncFeed")).toBeNull();
+    expect(index.isMutation("libs/shared/page/x.tsx", "syncFeed")).toBe(true);
+  });
+
   test("ignores signal tests and specs", () => {
     const spec = fileOf(
       "apps/demo/lib/ticket/ticket.signal.spec.ts",

package/signalMutationIndex.ts

@@ -34,7 +34,7 @@ export class SignalMutationIndex {
 
   #shapeOf(consumerFile: string, name: string) {
     const [root, owner] = consumerFile.split("/");
-    const own = root === "apps" ? this.#shapesByOwner.get(`apps/${owner}`)?.get(name) : undefined;
+    const own = this.#shapesByOwner.get(`${root}/${owner}`)?.get(name);
     if (own) return own;
     for (const [key, shapes] of this.#shapesByOwner) {
       const shape = shapes.get(name);

package/sourceComments.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { SourceComments } from "./sourceComments";
+
+const commentsOf = (content: string) =>
+  SourceComments.of(ts.createSourceFile("demo.tsx", content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)).map(
+    ({ line, body, isJsDoc }) => ({ line, body, isJsDoc }),
+  );
+
+describe("SourceComments", () => {
+  test("finds leading, trailing, empty-block and end-of-file comments", () => {
+    expect(
+      commentsOf(
+        ["// leading", "const a = 1; // trailing", "const f = () => {", "  /* inside */", "};", "// last", ""].join(
+          "\n",
+        ),
+      ),
+    ).toEqual([
+      { line: 1, body: ["leading"], isJsDoc: false },
+      { line: 2, body: ["trailing"], isJsDoc: false },
+      { line: 4, body: ["inside"], isJsDoc: false },
+      { line: 6, body: ["last"], isJsDoc: false },
+    ]);
+  });
+
+  test("ignores comment syntax inside strings, templates, regexes and JSX text", () => {
+    expect(
+      commentsOf(
+        [
+          'const url = "https://host//path";',
+          `const tpl = \`a // b \${url} // c\`;`,
+          "const re = /\\/\\/x/;",
+          'export const C = () => <div title="//x">// text {/* real */}</div>;',
+          "",
+        ].join("\n"),
+      ),
+    ).toEqual([{ line: 4, body: ["real"], isJsDoc: false }]);
+  });
+
+  test("strips block delimiters and marks a JSDoc", () => {
+    expect(
+      commentsOf(["/**", " * Summary", " * @deprecated use b", " */", "export const a = 1;", ""].join("\n")),
+    ).toEqual([{ line: 1, body: ["", "Summary", "@deprecated use b", ""], isJsDoc: true }]);
+  });
+});

package/sourceComments.ts

@@ -0,0 +1,70 @@
+import ts from "typescript";
+
+export interface SourceComment {
+  raw: string;
+  line: number;
+  isJsDoc: boolean;
+  body: string[];
+}
+
+export class SourceComments {
+  static #scanner = ts.createScanner(ts.ScriptTarget.Latest, false);
+
+  static of(sourceFile: ts.SourceFile): SourceComment[] {
+    const comments: SourceComment[] = [];
+    const scanGap = (start: number, end: number) => {
+      if (end <= start) return;
+      const scanner = SourceComments.#scanner;
+      scanner.setText(sourceFile.text, start, end - start);
+      for (let kind = scanner.scan(); kind !== ts.SyntaxKind.EndOfFileToken; kind = scanner.scan()) {
+        if (kind !== ts.SyntaxKind.SingleLineCommentTrivia && kind !== ts.SyntaxKind.MultiLineCommentTrivia) continue;
+        comments.push(SourceComments.#commentOf(sourceFile, scanner.getTokenStart(), scanner.getTokenText()));
+      }
+      scanner.setText(undefined);
+    };
+    //? Only the trivia between AST children is scanned: string, template, regex and JSX text tokens can hold `//`.
+    const visit = (node: ts.Node) => {
+      if (node.kind === ts.SyntaxKind.JsxText) return;
+      if (ts.isToken(node)) {
+        scanGap(node.pos, node.getStart(sourceFile));
+        return;
+      }
+      const children: ts.Node[] = [];
+      ts.forEachChild(
+        node,
+        (child) => {
+          children.push(child);
+        },
+        (nodes) => {
+          children.push(...nodes);
+        },
+      );
+      let cursor = node.pos;
+      for (const child of children) {
+        scanGap(cursor, child.pos);
+        visit(child);
+        cursor = Math.max(cursor, child.end);
+      }
+      scanGap(cursor, node.end);
+    };
+    visit(sourceFile);
+    return comments;
+  }
+
+  static #commentOf(sourceFile: ts.SourceFile, pos: number, raw: string): SourceComment {
+    return {
+      raw,
+      line: sourceFile.getLineAndCharacterOfPosition(pos).line + 1,
+      isJsDoc: raw.startsWith("/**") && !raw.startsWith("/**/"),
+      body: SourceComments.#bodyOf(raw),
+    };
+  }
+
+  static #bodyOf(raw: string) {
+    if (raw.startsWith("//")) return [raw.replace(/^\/\/+/, "").trim()];
+    return raw
+      .slice(2, raw.endsWith("*/") ? -2 : undefined)
+      .split(/\r?\n/)
+      .map((line) => line.replace(/^\s*\*+/, "").trim());
+  }
+}

package/storeAccessScanner.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { SignalMutationIndex } from "./signalMutationIndex";
+import { StoreAccessScanner } from "./storeAccessScanner";
+import { WritingActionIndex } from "./writingActionIndex";
+
+const sourceOf = (file: string, content: string) =>
+  ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+
+const storeFile = "apps/demo/lib/board/board.store.ts";
+const signalFile = "apps/demo/lib/boardPin/boardPin.signal.ts";
+const signal = sourceOf(
+  signalFile,
+  "export class BoardPinSlice extends slice(srv.boardPin, { guards: { root: Admin, cru: User } }, () => ({})) {}\n",
+);
+const index = new WritingActionIndex(
+  new SignalMutationIndex([{ file: signalFile, absolutePath: "", content: "", sourceFile: signal }]),
+  [
+    {
+      file: storeFile,
+      sourceFile: sourceOf(
+        storeFile,
+        `import { fetch, sig } from "../useClient";
+export class BoardStore extends store(sig.board, () => ({})) {
+  async addPinOnCanvas(boardId: string) {
+    await fetch.createBoardPin({ board: boardId });
+  }
+}
+`,
+      ),
+    },
+  ],
+);
+
+const measure = (content: string) =>
+  new StoreAccessScanner(index).measure(sourceOf("apps/demo/lib/board/Board.Zone.tsx", content));
+
+describe("StoreAccessScanner", () => {
+  test("counts every read, action, selector, slice and agent hook a component reaches the store through", () => {
+    const counts = measure(`"use client";
+import { st as store } from "@apps/demo/client";
+
+export const Canvas = () => {
+  const board = store.use.board();
+  const pins = store.slice.boardInSelf.use.boardList();
+  const zoom = store.sel((state) => state.zoom);
+  const latest = store.ref((state) => state.board);
+  const move = store.tool("movePin").exec(() => store.do.setZoom(1));
+  return <div onClick={() => void store.do.addPinOnCanvas(board.id)}>{pins.length}{zoom}{latest.current?.id}{String(move)}</div>;
+};
+
+export const Empty = () => null;
+`);
+
+    expect(counts).toEqual([
+      { component: "Canvas", line: 4, accessCount: 7 },
+      { component: "Empty", line: 13, accessCount: 0 },
+    ]);
+  });
+
+  test("leaves out a generated form setter bound to its control, but not a writing action named like one", () => {
+    const counts = measure(`"use client";
+import { st } from "@apps/demo/client";
+
+export const General = () => {
+  const boardForm = st.use.boardForm();
+  return (
+    <form>
+      <input value={boardForm.name} onChange={(e) => st.do.setNameOnBoard(e.target.value)} />
+      <input onChange={st.do.addTagOnBoard} />
+      <input onChange={(e) => st.do.writeOnBoard("meta.title", e.target.value)} />
+      <button type="button" onClick={() => void st.do.addPinOnCanvas(boardForm.id)} />
+    </form>
+  );
+};
+`);
+
+    expect(counts).toEqual([{ component: "General", line: 4, accessCount: 2 }]);
+  });
+
+  test("measures nothing in a file that does not import st", () => {
+    expect(measure("export const Plain = () => st.use.board();\n")).toEqual([]);
+  });
+});

package/storeAccessScanner.ts

@@ -0,0 +1,71 @@
+import ts from "typescript";
+import { ComponentSizeScanner } from "./componentSizeScanner";
+import type { WritingActionIndex } from "./writingActionIndex";
+
+export interface StoreAccessCount {
+  component: string;
+  line: number;
+  accessCount: number;
+}
+
+//? A generated form setter only binds a field to its control: a long form is a size breach, not a busy component.
+export class StoreAccessScanner {
+  static readonly #formSetter = /^(?:(?:set|add|sub|addOrSub|upload)[A-Z]\w*On|writeOn)[A-Z]\w*$/;
+  readonly #index: WritingActionIndex;
+
+  constructor(index: WritingActionIndex) {
+    this.#index = index;
+  }
+
+  static stNamesOf(sourceFile: ts.SourceFile) {
+    return StoreAccessScanner.localNamesOf(sourceFile, "st");
+  }
+
+  static localNamesOf(sourceFile: ts.SourceFile, imported: string) {
+    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 === imported)
+          names.add(element.name.text);
+    }
+    return names;
+  }
+
+  measure(sourceFile: ts.SourceFile): StoreAccessCount[] {
+    const stNames = StoreAccessScanner.stNamesOf(sourceFile);
+    if (!stNames.size) return [];
+    return ComponentSizeScanner.componentsAndHooksOf(sourceFile).map(({ name, node }) => {
+      let accessCount = 0;
+      const visit = (child: ts.Node) => {
+        if (
+          ts.isPropertyAccessExpression(child) &&
+          ts.isIdentifier(child.expression) &&
+          stNames.has(child.expression.text) &&
+          !this.#isFormSetter(child)
+        )
+          accessCount += 1;
+        ts.forEachChild(child, visit);
+      };
+      visit(node);
+      return {
+        component: name,
+        line: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1,
+        accessCount,
+      };
+    });
+  }
+
+  #isFormSetter(access: ts.PropertyAccessExpression) {
+    const action = access.parent;
+    return (
+      access.name.text === "do" &&
+      ts.isPropertyAccessExpression(action) &&
+      action.expression === access &&
+      StoreAccessScanner.#formSetter.test(action.name.text) &&
+      !this.#index.isWritingAction(action.name.text)
+    );
+  }
+}

package/storeSource.ts

@@ -0,0 +1,159 @@
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+
+export interface StoreClass {
+  name: string;
+  refName: string | null;
+}
+
+export interface StoreMethod {
+  store: string;
+  name: string;
+  isStatic: boolean;
+  body: ts.Block;
+}
+
+export type StoreCallTarget =
+  | { kind: "fetch"; name: string }
+  | { kind: "action"; name: string; isOwn: boolean }
+  | { kind: "static"; store: string; name: string };
+
+export class StoreSource {
+  readonly file: string;
+  readonly stores: StoreClass[] = [];
+  readonly methods: StoreMethod[] = [];
+  readonly #fetchNames: Set<string>;
+  readonly #ownActionsByStore = new Map<string, Set<string>>();
+  readonly #rootAliasesByMethod = new Map<StoreMethod, Set<string>>();
+
+  //? The actions `store()` generates that send a mutation; `upload<Field>On<Model>` only stages a file the form saves.
+  static generatedWritesOf(refName: string) {
+    const model = `${refName.charAt(0).toUpperCase()}${refName.slice(1)}`;
+    return [
+      `create${model}`,
+      `update${model}`,
+      `remove${model}`,
+      `merge${model}`,
+      `create${model}InForm`,
+      `update${model}InForm`,
+      `submit${model}`,
+    ];
+  }
+
+  constructor({ file, sourceFile }: Pick<SourceFileInfo, "file" | "sourceFile">) {
+    this.file = file;
+    this.#fetchNames = StoreSource.#fetchBindingsOf(sourceFile);
+    for (const statement of sourceFile.statements) {
+      if (!ts.isClassDeclaration(statement) || !statement.name) continue;
+      const refName = StoreSource.#refNameOf(statement);
+      if (refName === undefined) continue;
+      const store = statement.name.text;
+      this.stores.push({ name: store, refName });
+      const ownActions = new Set(refName ? StoreSource.generatedWritesOf(refName) : []);
+      for (const member of statement.members) {
+        if (!ts.isMethodDeclaration(member) || !member.body) continue;
+        const isStatic = !!ts.getModifiers(member)?.some(({ kind }) => kind === ts.SyntaxKind.StaticKeyword);
+        const name = member.name.getText(sourceFile);
+        if (!isStatic) ownActions.add(name);
+        const method = { store, name, isStatic, body: member.body };
+        this.methods.push(method);
+        this.#rootAliasesByMethod.set(method, StoreSource.#rootAliasesIn(member));
+      }
+      this.#ownActionsByStore.set(store, ownActions);
+    }
+  }
+
+  targetsIn(method: StoreMethod) {
+    const targets: StoreCallTarget[] = [];
+    const visit = (node: ts.Node) => {
+      const target = ts.isCallExpression(node) ? this.targetOf(method, node) : null;
+      if (target) targets.push(target);
+      ts.forEachChild(node, visit);
+    };
+    visit(method.body);
+    return targets;
+  }
+
+  targetOf(method: StoreMethod, call: ts.CallExpression): StoreCallTarget | null {
+    const callee = call.expression;
+    if (!ts.isPropertyAccessExpression(callee) && !ts.isElementAccessExpression(callee)) return null;
+    const name = ts.isPropertyAccessExpression(callee)
+      ? callee.name.text
+      : ts.isStringLiteralLike(callee.argumentExpression)
+        ? callee.argumentExpression.text
+        : null;
+    if (name === null) return null;
+    const receiver = StoreSource.#unwrap(callee.expression);
+    const isThis = receiver.kind === ts.SyntaxKind.ThisKeyword;
+    if (isThis && method.isStatic) return { kind: "static", store: method.store, name };
+    if (!isThis && !ts.isIdentifier(receiver)) return null;
+    if (ts.isIdentifier(receiver) && this.#fetchNames.has(receiver.text)) return { kind: "fetch", name };
+    if (isThis || (ts.isIdentifier(receiver) && this.#rootAliasesByMethod.get(method)?.has(receiver.text)))
+      return { kind: "action", name, isOwn: !!this.#ownActionsByStore.get(method.store)?.has(name) };
+    return ts.isIdentifier(receiver) ? { kind: "static", store: receiver.text, name } : null;
+  }
+
+  //? `this`, cast to `RootStore` or not, an alias of it, or a `RootStore` parameter reaches every store's action.
+  static #rootAliasesIn(method: ts.MethodDeclaration) {
+    const aliases = new Set<string>();
+    const visit = (node: ts.Node) => {
+      if (ts.isParameter(node) && ts.isIdentifier(node.name) && StoreSource.#isRootStoreType(node.type))
+        aliases.add(node.name.text);
+      if (
+        ts.isVariableDeclaration(node) &&
+        ts.isIdentifier(node.name) &&
+        node.initializer &&
+        StoreSource.#unwrap(node.initializer).kind === ts.SyntaxKind.ThisKeyword
+      )
+        aliases.add(node.name.text);
+      ts.forEachChild(node, visit);
+    };
+    visit(method);
+    return aliases;
+  }
+
+  static #isRootStoreType(type: ts.TypeNode | undefined) {
+    return (
+      !!type && ts.isTypeReferenceNode(type) && ts.isIdentifier(type.typeName) && type.typeName.text === "RootStore"
+    );
+  }
+
+  static #unwrap(expression: ts.Expression) {
+    let current = expression;
+    while (
+      ts.isParenthesizedExpression(current) ||
+      ts.isAsExpression(current) ||
+      ts.isTypeAssertionExpression(current) ||
+      ts.isSatisfiesExpression(current) ||
+      ts.isNonNullExpression(current)
+    )
+      current = current.expression;
+    return current;
+  }
+
+  static #refNameOf(statement: ts.ClassDeclaration) {
+    for (const clause of statement.heritageClauses ?? []) {
+      if (clause.token !== ts.SyntaxKind.ExtendsKeyword) continue;
+      for (const { expression } of clause.types) {
+        if (!ts.isCallExpression(expression) || !ts.isIdentifier(expression.expression)) continue;
+        if (expression.expression.text !== "store") continue;
+        const sig = expression.arguments[0];
+        return sig && ts.isPropertyAccessExpression(sig) ? sig.name.text : null;
+      }
+    }
+    return undefined;
+  }
+
+  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;
+  }
+}