@akanjs/devkit 3.1.1-rc.14 → 3.1.1-rc.16

package/deprecatedCommentScanner.ts

@@ -0,0 +1,30 @@
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+import { type SourceComment, SourceComments } from "./sourceComments";
+
+export class DeprecatedCommentScanner {
+  static readonly rule = "akan.comment.deprecated-marker";
+  static #marker = /^[!?*\s]*(?:(?:TODO|FIXME|XXX|NOTE)\b\s*:?\s*)?@?deprecated\b/i;
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    return sourceFiles
+      .filter(({ file }) => /^(apps|libs)\//.test(file) && !/\.(test|spec)\.tsx?$/.test(file))
+      .flatMap(({ file, sourceFile }) =>
+        SourceComments.of(sourceFile)
+          .filter((comment) => DeprecatedCommentScanner.#isLooseMarker(comment))
+          .map((comment) => ({
+            rule: DeprecatedCommentScanner.rule,
+            scope: "comment" as const,
+            severity: "warning" as const,
+            file,
+            line: comment.line,
+            message: `"${comment.raw.split(/\r?\n/)[0]?.trim().slice(0, 80)}" marks nothing at the use sites; editors strike through only a JSDoc @deprecated tag.`,
+          })),
+      );
+  }
+
+  static #isLooseMarker({ isJsDoc, body }: SourceComment) {
+    const text = body.filter((line) => line !== "").join(" ");
+    if (isJsDoc && /(^|\s)@deprecated\b/.test(text)) return false;
+    return DeprecatedCommentScanner.#marker.test(text);
+  }
+}

package/endpointReach.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { EndpointReach } from "./endpointReach";
+
+const fileOf = (file: string, content: string) => ({
+  file,
+  sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true),
+});
+
+describe("EndpointReach", () => {
+  test("follows an endpoint or a slice through its service's own and other services' methods, not a job", () => {
+    const reach = new EndpointReach(
+      [
+        fileOf(
+          "apps/demo/lib/court/court.signal.ts",
+          `export class CourtInternal extends internal(srv.court, ({ cron }) => ({
+  sweep: cron("0 * * * *").exec(function () { return this.courtService.sweep(); }),
+})) {}
+export class CourtSlice extends slice(srv.court, { guards: { root: Admin } }, (init) => ({
+  inOrg: init().exec(function (orgId) { return this.courtService.queryInOrg(orgId); }),
+})) {}
+export class CourtEndpoint extends endpoint(srv.court, ({ mutation }) => ({
+  assign: mutation(Boolean).exec(function (id) { return this.courtService.assign(id); }),
+})) {}
+`,
+        ),
+      ],
+      [
+        fileOf(
+          "apps/demo/lib/court/court.service.ts",
+          `export class CourtService extends serve(db.court, () => ({})) {
+  queryInOrg(orgId: string) { return { orgId }; }
+  async assign(id: string) { return await this.#pick(id); }
+  async #pick(id: string) { return await this.pcService.claim(id); }
+  async sweep() { return await this.#pick("all"); }
+}
+`,
+        ),
+        fileOf(
+          "libs/shared/lib/_pc/pc.service.ts",
+          `export class PcService extends serve("pc", () => ({})) {
+  async claim(id: string) { return id; }
+  async release(id: string) { return id; }
+}
+`,
+        ),
+      ],
+    );
+
+    expect(EndpointReach.serviceOf("libs/shared/lib/_pc/pc.service.ts")).toBe("pc");
+    expect(
+      ["court.queryInOrg", "court.assign", "court.#pick", "pc.claim", "court.sweep", "pc.release"].map((key) => {
+        const [service = "", method = ""] = key.split(".");
+        return reach.reaches(service, method);
+      }),
+    ).toEqual([true, true, true, true, false, false]);
+  });
+});

package/endpointReach.ts

@@ -0,0 +1,80 @@
+import path from "node:path";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+
+type ServiceMethod = [service: string, method: string];
+
+//? Only `endpoint(…)` and `slice(…)` answer a caller who waits; an `internal(…)` job (cron, interval, queue) works
+//? per item on purpose, so that one failing item leaves the rest done.
+export class EndpointReach {
+  static readonly #requestBuilders = new Set(["endpoint", "slice"]);
+  readonly #reached = new Set<string>();
+
+  constructor(
+    signalFiles: Pick<SourceFileInfo, "sourceFile">[],
+    serviceFiles: Pick<SourceFileInfo, "file" | "sourceFile">[],
+  ) {
+    const methodsByService = new Map<string, Map<string, ts.MethodDeclaration>>();
+    for (const { file, sourceFile } of serviceFiles) {
+      const methods = methodsByService.get(EndpointReach.serviceOf(file)) ?? new Map<string, ts.MethodDeclaration>();
+      for (const cls of sourceFile.statements.filter(ts.isClassDeclaration))
+        for (const member of cls.members)
+          if (
+            ts.isMethodDeclaration(member) &&
+            member.body &&
+            (ts.isIdentifier(member.name) || ts.isPrivateIdentifier(member.name))
+          )
+            methods.set(member.name.text, member);
+      methodsByService.set(EndpointReach.serviceOf(file), methods);
+    }
+    const pending: ServiceMethod[] = [];
+    const reach = ([service, method]: ServiceMethod) => {
+      const key = `${service}.${method}`;
+      if (this.#reached.has(key) || !methodsByService.get(service)?.has(method)) return;
+      this.#reached.add(key);
+      pending.push([service, method]);
+    };
+    for (const { sourceFile } of signalFiles)
+      for (const cls of sourceFile.statements.filter(ts.isClassDeclaration)) {
+        const base = cls.heritageClauses?.[0]?.types[0]?.expression;
+        if (
+          base &&
+          ts.isCallExpression(base) &&
+          ts.isIdentifier(base.expression) &&
+          EndpointReach.#requestBuilders.has(base.expression.text)
+        )
+          EndpointReach.#serviceCallsIn(base, null).forEach(reach);
+      }
+    for (let next = pending.pop(); next; next = pending.pop()) {
+      const [service, method] = next;
+      const declaration = methodsByService.get(service)?.get(method);
+      if (declaration) EndpointReach.#serviceCallsIn(declaration, service).forEach(reach);
+    }
+  }
+
+  static serviceOf(file: string) {
+    return path.posix.basename(file).replace(/\.service\.ts$/, "");
+  }
+
+  reaches(service: string, method: string) {
+    return this.#reached.has(`${service}.${method}`);
+  }
+
+  static #serviceCallsIn(node: ts.Node, ownService: string | null) {
+    const calls: ServiceMethod[] = [];
+    const visit = (child: ts.Node) => {
+      if (ts.isCallExpression(child) && ts.isPropertyAccessExpression(child.expression)) {
+        const { expression: owner, name } = child.expression;
+        if (owner.kind === ts.SyntaxKind.ThisKeyword && ownService) calls.push([ownService, name.text]);
+        else if (ts.isPropertyAccessExpression(owner) && owner.expression.kind === ts.SyntaxKind.ThisKeyword) {
+          const field = owner.name.text;
+          if (field.length > "Service".length && field.endsWith("Service"))
+            calls.push([field.slice(0, -"Service".length), name.text]);
+        }
+      }
+      ts.forEachChild(child, visit);
+    };
+    visit(node);
+    return calls;
+  }
+}

package/index.ts

@@ -19,6 +19,7 @@ export type * from "./fileSys";
 export type * from "./frontendBuild";
 export type * from "./getRelatedCnsts";
 export type * from "./incrementalBuilder";
+export type * from "./maintainabilityContract";
 export type * from "./mobile";
 export type * from "./packageExportsMap";
 export type * from "./prompter";

package/kindBranchScanner.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { KindBranchScanner } from "./kindBranchScanner";
+import type { SourceFileInfo } from "./qualityScanner";
+
+const filesOf = (files: Record<string, string>): SourceFileInfo[] =>
+  Object.entries(files).map(([file, content]) => ({
+    file,
+    absolutePath: `/repo/${file}`,
+    content,
+    sourceFile: ts.createSourceFile(
+      file,
+      content,
+      ts.ScriptTarget.Latest,
+      true,
+      file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    ),
+  }));
+
+const pinConstant = `import { enumOf } from "akanjs/base";
+export class PinKind extends enumOf("pinKind", ["videoScene", "videoTake", "memo"] as const) {}
+export class PinStatus extends enumOf("pinStatus", ["active", "videoTake"] as const) {}
+`;
+const comparing = (expression: string) => `export const isIt = (pin: { kind: string }) => ${expression};\n`;
+
+describe("KindBranchScanner", () => {
+  test("warns on a kind value compared in three files outside its module, naming them and the table to declare", () => {
+    const warnings = new KindBranchScanner().scan(
+      filesOf({
+        "apps/demo/lib/pin/pin.constant.ts": pinConstant,
+        "apps/demo/lib/pin/Pin.Zone.tsx": comparing('pin.kind === "videoScene"'),
+        "apps/demo/lib/board/Board.Zone.tsx": comparing('pin.kind === "videoScene"'),
+        "apps/demo/lib/take/take.store.ts": comparing('"videoScene" !== pin.kind'),
+        "apps/demo/ui/PinCard.tsx": `export const label = (kind: string) => {\n  switch (kind) {\n    case "videoScene":\n      return 1;\n  }\n};\n`,
+        "apps/demo/ui/PinCard.test.tsx": comparing('pin.kind === "videoScene"'),
+      }),
+    );
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toMatchObject({
+      rule: "akan.global.kind-branch",
+      severity: "warning",
+      file: "apps/demo/lib/pin/pin.constant.ts",
+      line: 2,
+      message: '"videoScene" of cnst.PinKind is branched on in 3 files outside the enum\'s module.',
+      locations: [
+        { file: "apps/demo/lib/board/Board.Zone.tsx", line: 1 },
+        { file: "apps/demo/lib/take/take.store.ts", line: 1 },
+        { file: "apps/demo/ui/PinCard.tsx", line: 3 },
+      ],
+    });
+    expect(warnings[0]?.fix).toContain('{ [kind in cnst.PinKind["value"]]: … }');
+  });
+
+  test("reads only a subject named for a kind, and only enums named for one", () => {
+    const warnings = new KindBranchScanner().scan(
+      filesOf({
+        "apps/demo/lib/pin/pin.constant.ts": pinConstant,
+        "apps/demo/lib/a/A.Zone.tsx": comparing('pin.status === "active" || label === "videoScene"'),
+        "apps/demo/lib/b/B.Zone.tsx": comparing('pin.status === "active" || label === "videoScene"'),
+        "apps/demo/lib/c/C.Zone.tsx": comparing('pin.status === "active" || label === "videoScene"'),
+      }),
+    );
+
+    expect(warnings).toEqual([]);
+  });
+
+  test("groups the enums sharing a value, reached from the app's own lib or a lib, never another app or lib", () => {
+    const warnings = new KindBranchScanner().scan(
+      filesOf({
+        "apps/demo/lib/pin/pin.constant.ts": pinConstant,
+        "libs/media/lib/clip/clip.constant.ts": `export class ClipType extends enumOf("clipType", ["videoTake"] as const) {}\n`,
+        "apps/demo/lib/a/A.Zone.tsx": comparing('pin.kind === "videoTake"'),
+        "apps/demo/lib/b/B.Zone.tsx": comparing('pin.kind === "videoTake"'),
+        "apps/demo/lib/c/C.Zone.tsx": comparing('pin.kind === "videoTake"'),
+        "apps/other/lib/a/A.Zone.tsx": comparing('pin.kind === "videoTake"'),
+        "apps/other/lib/b/B.Zone.tsx": comparing('pin.kind === "videoTake"'),
+        "libs/shared/lib/a/A.Zone.tsx": comparing('pin.kind === "videoTake"'),
+      }),
+    );
+
+    expect(warnings.map(({ file, message }) => ({ file, message }))).toEqual([
+      {
+        file: "apps/demo/lib/pin/pin.constant.ts",
+        message: '"videoTake" of cnst.PinKind / cnst.ClipType is branched on in 3 files outside the enum\'s module.',
+      },
+    ]);
+  });
+});

package/kindBranchScanner.ts

@@ -0,0 +1,158 @@
+import path from "node:path";
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+
+interface EnumDeclaration {
+  name: string;
+  sys: string;
+  file: string;
+  line: number;
+  module: string;
+  values: string[];
+}
+
+interface BranchSite {
+  value: string;
+  file: string;
+  line: number;
+}
+
+//? Enums sharing a value form one group: short of the type checker, nothing tells which one a literal means.
+export class KindBranchScanner {
+  static readonly rule = "akan.global.kind-branch";
+  static readonly minFileNum = 3;
+  static readonly #kindName = /(Kind|Type|Mode)$/;
+  static readonly #kindSubject = /^(kind|type|mode)$|[a-z](Kind|Type|Mode)$/;
+  static readonly #equalities = new Set([
+    ts.SyntaxKind.EqualsEqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsEqualsToken,
+    ts.SyntaxKind.EqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsToken,
+  ]);
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    const enums = sourceFiles.flatMap((sourceFile) => KindBranchScanner.#enumsOf(sourceFile));
+    const ownersByValue = new Map<string, EnumDeclaration[]>();
+    for (const declaration of enums)
+      for (const value of declaration.values)
+        ownersByValue.set(value, [...(ownersByValue.get(value) ?? []), declaration]);
+    const sitesByGroup = new Map<string, { owners: EnumDeclaration[]; sites: BranchSite[] }>();
+    for (const sourceFile of sourceFiles) {
+      if (!/^(apps|libs)\//.test(sourceFile.file) || /\.(test|spec)\.tsx?$/.test(sourceFile.file)) continue;
+      const sys = KindBranchScanner.#sysOf(sourceFile.file);
+      //? An app reaches every lib's enums; a lib only its own, as nothing here knows which libs it depends on.
+      for (const site of KindBranchScanner.#sitesIn(sourceFile, ownersByValue)) {
+        const owners = (ownersByValue.get(site.value) ?? []).filter(
+          (owner) => owner.sys === sys || (owner.sys.startsWith("libs/") && sys.startsWith("apps/")),
+        );
+        if (!owners.length || owners.some(({ module }) => site.file.startsWith(module))) continue;
+        const group = owners.map(({ name, file }) => `${file}#${name}`).join(",");
+        const entry = sitesByGroup.get(group) ?? { owners, sites: [] };
+        entry.sites.push(site);
+        sitesByGroup.set(group, entry);
+      }
+    }
+    return [...sitesByGroup.values()].flatMap(({ owners, sites }) => KindBranchScanner.#warningOf(owners, sites));
+  }
+
+  static #warningOf(owners: EnumDeclaration[], sites: BranchSite[]): QualityWarning[] {
+    const filesByValue = new Map<string, Set<string>>();
+    for (const { value, file } of sites) filesByValue.set(value, (filesByValue.get(value) ?? new Set()).add(file));
+    const values = [...filesByValue]
+      .filter(([, files]) => files.size >= KindBranchScanner.minFileNum)
+      .map(([value]) => value)
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const [owner] = owners;
+    if (!owner || !values.length) return [];
+    const branched = sites.filter(({ value }) => values.includes(value));
+    const fileNum = new Set(branched.map(({ file }) => file)).size;
+    const enumNames = owners.map(({ name }) => `cnst.${name}`).join(" / ");
+    return [
+      {
+        rule: KindBranchScanner.rule,
+        scope: "global",
+        severity: "warning",
+        file: owner.file,
+        line: owner.line,
+        message: `${values.map((value) => `"${value}"`).join(", ")} of ${enumNames} ${values.length > 1 ? "are" : "is"} branched on in ${fileNum} files outside the enum's module.`,
+        locations: branched.map(({ file, line }) => ({ file, line })),
+        fix: `Declare one table keyed by the kind, \`{ [kind in cnst.${owner.name}["value"]]: … }\` (a component, label or handler per kind), and look the kind up in it instead of comparing it in each file.`,
+      },
+    ];
+  }
+
+  static #sitesIn({ file, sourceFile }: SourceFileInfo, ownersByValue: Map<string, EnumDeclaration[]>) {
+    const sites: BranchSite[] = [];
+    const record = (literal: ts.Expression, subject: ts.Expression) => {
+      if (!ts.isStringLiteralLike(literal) || !ownersByValue.has(literal.text)) return;
+      if (!KindBranchScanner.#isKindSubject(subject)) return;
+      sites.push({
+        value: literal.text,
+        file,
+        line: sourceFile.getLineAndCharacterOfPosition(literal.getStart(sourceFile)).line + 1,
+      });
+    };
+    const visit = (node: ts.Node) => {
+      if (ts.isBinaryExpression(node) && KindBranchScanner.#equalities.has(node.operatorToken.kind)) {
+        record(node.left, node.right);
+        record(node.right, node.left);
+      } else if (ts.isCaseClause(node) && ts.isSwitchStatement(node.parent.parent))
+        record(node.expression, node.parent.parent.expression);
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return sites;
+  }
+
+  //? Only a subject named for a kind (`kind`, `pin.kind`, `viewMode`) counts: a bare `"active"` matches too much.
+  static #isKindSubject(subject: ts.Expression) {
+    let current = subject;
+    while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isNonNullExpression(current))
+      current = current.expression;
+    const name = ts.isIdentifier(current)
+      ? current.text
+      : ts.isPropertyAccessExpression(current)
+        ? current.name.text
+        : ts.isElementAccessExpression(current) && ts.isStringLiteralLike(current.argumentExpression)
+          ? current.argumentExpression.text
+          : "";
+    return KindBranchScanner.#kindSubject.test(name);
+  }
+
+  static #enumsOf({ file, sourceFile }: SourceFileInfo): EnumDeclaration[] {
+    if (!/^(apps|libs)\/[^/]+\/lib\/.+\.constant\.ts$/.test(file)) return [];
+    return sourceFile.statements.flatMap((statement) => {
+      if (!ts.isClassDeclaration(statement) || !statement.name) return [];
+      if (!KindBranchScanner.#kindName.test(statement.name.text)) return [];
+      const values = KindBranchScanner.#enumValuesOf(statement);
+      if (!values) return [];
+      return [
+        {
+          name: statement.name.text,
+          sys: KindBranchScanner.#sysOf(file),
+          file,
+          line: sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile)).line + 1,
+          module: `${path.posix.dirname(file)}/`,
+          values,
+        },
+      ];
+    });
+  }
+
+  static #sysOf(file: string) {
+    return file.split("/").slice(0, 2).join("/");
+  }
+
+  static #enumValuesOf(statement: ts.ClassDeclaration) {
+    for (const clause of statement.heritageClauses ?? [])
+      for (const { expression } of clause.types) {
+        if (!ts.isCallExpression(expression) || !ts.isIdentifier(expression.expression)) continue;
+        if (expression.expression.text !== "enumOf") continue;
+        let list = expression.arguments[1];
+        while (list && (ts.isAsExpression(list) || ts.isParenthesizedExpression(list))) list = list.expression;
+        if (!list || !ts.isArrayLiteralExpression(list)) return null;
+        return list.elements.filter(ts.isStringLiteralLike).map(({ text }) => text);
+      }
+    return null;
+  }
+}

package/lint/__fixtures__/no-oversized-list-limit/bad.tsx

@@ -0,0 +1,18 @@
+export const everyCourt = () => fetch.courtListInPublic(0, 10000); // @flag
+export const devicesOfOrg = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 1000); // @flag
+export const sortedDevices = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 1000, "latest"); // @flag
+export const withPolicy = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 1000, null, { crystalize: false }); // @flag
+export const rootList = () => fetch.deviceList(null, 501); // @flag
+export const separated = () => fetch.deviceList(undefined, 10_000); // @flag
+export const exponent = () => fetch.deviceList(0, 1e4); // @flag
+export const namedSkip = (orgId: string, skip: number) => fetch.alertListInOrg(orgId, skip, 2000); // @flag
+export const pagedSkip = (orgId: string, page: number) => fetch.alertListInOrg(orgId, (page - 1) * 20, 2000); // @flag
+export const afterSliceNumbers = () => fetch.statListInYear(2026, 0, 600); // @flag
+export const initInRoute = (orgId: string) => fetch.initDeviceInOrg(orgId, { limit: 1000 }); // @flag
+export const initRoot = () => fetch.initDevice({ sort: "latest", limit: 9999 }); // @flag
+export const getInit = (orgId: string) => fetch.getDeviceInitInOrg(orgId, { limit: 1000 }); // @flag
+export const storeInit = (orgId: string) => st.do.initDeviceInOrg(orgId, { limit: 1000 }); // @flag
+export const storeRefresh = () => st.do.refreshDeviceInOrg({ limit: 1000 }); // @flag
+export const quotedKey = (orgId: string) => st.do.initDeviceInOrg(orgId, { "limit": 1000 }); // @flag
+export const storeSetLimit = () => st.do.setLimitOfDeviceInOrg(1000); // @flag
+export const Monitor = () => <button type="button" onClick={() => st.do.setLimitOfAlertInOrg(5000)}>All</button>; // @flag

package/lint/__fixtures__/no-oversized-list-limit/good.tsx

@@ -0,0 +1,23 @@
+export const atTheCap = () => fetch.courtListInPublic(0, 500); // @ok
+export const onePage = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 20, "latest"); // @ok
+export const variableLimit = (orgId: string, limit: number) => fetch.deviceListInOrg(orgId, 0, limit); // @ok
+export const everyRowMode = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 0); // @ok
+export const yearSlice = () => fetch.statListInYear(2026); // @ok
+export const yearAfterId = (orgId: string) => fetch.statListInOrgYear(orgId, 2026); // @ok
+export const monthAndYear = () => fetch.statListInMonthOfYear(11, 2026); // @ok
+export const twoYears = () => fetch.statListInRange(2025, 2026); // @ok
+export const numbersBeforePaging = () => fetch.statListInRange(0, 2026, 0, 20); // @ok
+export const numbersWithoutPaging = () => fetch.statListInRange(0, 2026, 0); // @ok
+export const notAList = () => fetch.device(0, 1000); // @ok
+export const notFetch = () => api.deviceList(0, 1000); // @ok
+export const lowercaseList = () => fetch.checklist(0, 1000); // @ok
+export const initAtTheCap = (orgId: string) => fetch.initDeviceInOrg(orgId, { limit: 500 }); // @ok
+export const rateLimit = (orgId: string) => fetch.initDeviceInOrg(orgId, { rateLimit: 1000 }); // @ok
+export const nestedLimit = (orgId: string) => fetch.initDeviceInOrg(orgId, { default: { limit: 1000 } }); // @ok
+export const mutationLimit = (id: string) => fetch.updateQuota(id, { limit: 1000 }); // @ok
+export const storeWrite = () => st.do.setLimitOnQuota(1000); // @ok
+export const storeSetSmallLimit = () => st.do.setLimitOfDeviceInOrg(100); // @ok
+export const storeSetPage = () => st.do.setPageOfDeviceInOrg(1000); // @ok
+export const policyOnList = (orgId: string) => fetch.deviceListInOrg(orgId, 0, 20, "latest", { limit: 1000 }); // @ok
+export const Docs = () => <code>fetch.courtListInPublic(0, 10000)</code>; // @ok
+export const sample = "fetch.courtListInPublic(0, 10000)"; // @ok

package/lint/no-oversized-list-limit.grit

@@ -0,0 +1,73 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// A client list request takes at most MAX_PAGE_SIZE (500) rows: SignalResolver.#clientPageLimit
+// (pkgs/akanjs/server/resolver/signal.resolver.ts) clamps a larger limit and answers with 500 rows and no
+// error, so a screen that asked for 10000 silently stops at row 500. A store list reads hasMoreOf<Model><Suffix>
+// as true after a full 500, so only a screen that calls loadMoreOf<Model><Suffix> ever sees the rest. The server
+// logs one warning per list; this rule moves it to the line that asked.
+//
+// Matched: a literal limit above 500 in the generated list fetch, `fetch.<model>List<Suffix>(...sliceArgs,
+// skip, limit, sort?, fetchPolicy?)`; as `limit:` in the option object of `fetch.init<Model><Suffix>`,
+// `fetch.get<Model>Init<Suffix>`, `st.do.init<Model><Suffix>` and `st.do.refresh<Model><Suffix>`; and as the
+// argument of `st.do.setLimitOf<Model><Suffix>`.
+//
+// A rule cannot know a slice's arity, so the positional limit is found by shape: an argument that reads as a
+// skip (`0`, `null`, `undefined`, a name with skip/offset, a page multiplied out) directly before the literal,
+// and after it nothing but a non-numeric sort and a fetch policy. That keeps a numeric slice argument out
+// (`fetch.statListInYear(2026)`, `fetch.statListInMonth(11, 2026)`), as it does a variable limit, `limit: 0`
+// (the store's one-page mode, which the server warns about itself) and a `limit:` key anywhere else (rate
+// limits). Left over: a slice whose own last two arguments read as `(0, 1000)`, such as a price range; suppress
+// that one with `// biome-ignore lint/plugin: <reason>`.
+pattern over_max_page_size() {
+  JsNumberLiteralExpression() as $size where {
+    $size <: r"(?:50[1-9]|5[1-9][0-9]|[6-9][0-9]{2}|[1-9][0-9]{0,2}(?:_?[0-9]{3})+|[1-9]e\+?(?:[3-9]|[1-9][0-9]+))"
+  }
+}
+
+pattern page_skip() {
+  or { r"(?:0|null|undefined)", r"(?i)[\s\S]*(?:skip|offset)[\s\S]*", r"(?i)[\s\S]*page[\s\S]*\*[\s\S]*" }
+}
+
+pattern page_sort() {
+  not JsNumberLiteralExpression()
+}
+
+JsCallExpression(callee = $callee, arguments = JsCallArguments(args = $args)) where {
+  or {
+    and {
+      $callee <: `fetch.$endpoint`,
+      $endpoint <: r"[a-z][A-Za-z0-9_$]*List(?:[A-Z][A-Za-z0-9_$]*)?",
+      $args <: or {
+        [..., page_skip(), over_max_page_size() as $limit],
+        [..., page_skip(), over_max_page_size() as $limit, page_sort()],
+        [..., page_skip(), over_max_page_size() as $limit, page_sort(), $_]
+      }
+    },
+    and {
+      or {
+        and {
+          $callee <: `fetch.$endpoint`,
+          $endpoint <: or { r"init[A-Z][A-Za-z0-9_$]*", r"get[A-Z][A-Za-z0-9_$]*Init(?:[A-Z][A-Za-z0-9_$]*)?" }
+        },
+        and { $callee <: `st.do.$action`, $action <: r"(?:init|refresh)[A-Z][A-Za-z0-9_$]*" }
+      },
+      $args <: some JsObjectExpression(
+        members = some JsPropertyObjectMember(
+          name = r"(?:limit|\x22limit\x22|'limit')",
+          value = over_max_page_size() as $limit
+        )
+      )
+    },
+    and {
+      $callee <: `st.do.$action`,
+      $action <: r"setLimitOf[A-Z][A-Za-z0-9_$]*",
+      $args <: [over_max_page_size() as $limit, ...]
+    }
+  },
+  register_diagnostic(
+    span = $limit,
+    message = "The server serves at most 500 rows per list request and drops the rest without an error, so this list silently stops at row 500. Page through it at 500 or fewer per request (skip/limit, or st.do.loadMoreOf<Model><Suffix>() while hasMoreOf<Model><Suffix>), or compute what the screen needs on the server in an insight or a dedicated endpoint.",
+    severity = "error"
+  )
+}