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

package/maintainabilityReport.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, test } from "bun:test";
+import type { SizeViolation } from "./maintainabilityContract";
+import { MaintainabilityReport } from "./maintainabilityReport";
+
+const fileOf = (file: string, lineCount = 450): SizeViolation => ({
+  kind: "size",
+  rule: "akan.size.file",
+  key: file,
+  file,
+  line: 1,
+  lineCount,
+  maxLines: 400,
+});
+
+const fixLinesOf = (message: string) => message.split("How to fix:\n")[1]?.split("\n") ?? [];
+
+describe("MaintainabilityReport", () => {
+  test("gives a client file, a ui/ or webkit/ file, a long component and a busy one the same ordered paths", () => {
+    const message = MaintainabilityReport.describe("apps/demo", [
+      fileOf("lib/court/Court.Zone.tsx"),
+      fileOf("ui/Board.tsx"),
+      fileOf("webkit/useBoard.tsx"),
+      {
+        ...fileOf("lib/court/Court.Zone.tsx", 300),
+        rule: "akan.size.component",
+        key: "lib/court/Court.Zone.tsx#Canvas",
+        line: 4,
+        maxLines: 250,
+        component: "Canvas",
+      },
+      {
+        kind: "storeAccess",
+        rule: "akan.component.store-access",
+        key: "lib/court/Court.Zone.tsx#Canvas",
+        file: "lib/court/Court.Zone.tsx",
+        line: 4,
+        component: "Canvas",
+        accessCount: 20,
+        maxAccesses: 16,
+      },
+    ]);
+    const [fix = "", ...rest] = fixLinesOf(message);
+    const order = ["mode/kind table", "webkit/use<X>.tsx", "`common/`", "add-mutation", "`lib/<sub>`"].map((path) =>
+      fix.indexOf(path),
+    );
+
+    expect(rest).toEqual([]);
+    expect(fix).toStartWith(
+      "  *.Zone.tsx, ui/**, webkit/**, component or hook, component or hook reaching the store often: ",
+    );
+    expect(order.every((idx) => idx > 0)).toBe(true);
+    expect([...order].sort((a, b) => a - b)).toEqual(order);
+    expect(fix).toContain('`{ [kind in cnst.X["value"]]: … }`');
+    expect(fix).toContain("akan workflow plan create-interaction");
+    expect(fix).toContain("never model-bound code moved into `ui/`");
+  });
+
+  test("names a write sent from the wrong place, a call per item and a raised entry with their own fixes", () => {
+    const message = MaintainabilityReport.describe("apps/demo", [
+      {
+        kind: "baselineGrowth",
+        rule: "akan.baseline.growth",
+        key: "lib/court/court.store.ts#assign",
+        file: "akan.baseline.json",
+        line: 5,
+        debtRule: "akan.store.multi-write",
+        count: 3,
+        committed: 2,
+        reference: "3f2a9c1d0b7e",
+      },
+      {
+        kind: "writePlacement",
+        rule: "akan.write.placement",
+        key: "webkit/useBoard.tsx",
+        file: "webkit/useBoard.tsx",
+        line: 7,
+        writes: ["st.do.removeBoard", "fetch.placeBoard"],
+      },
+      {
+        kind: "loopCall",
+        rule: "akan.service.call-in-loop",
+        key: "lib/court/court.service.ts#syncAll",
+        file: "lib/court/court.service.ts",
+        line: 12,
+        owner: "syncAll",
+        calls: ["this.pcService.getPc"],
+        recorded: 0,
+      },
+      {
+        kind: "multiWrite",
+        rule: "akan.component.write-chain",
+        key: "webkit/useBoard.tsx#useBoard",
+        file: "webkit/useBoard.tsx",
+        line: 9,
+        owner: "useBoard",
+        writes: ["st.do.removeBoard (per item)"],
+        writeCount: 2,
+      },
+    ]);
+
+    expect(message).toContain(
+      'akan.baseline.growth  entry "lib/court/court.store.ts#assign" under akan.store.multi-write allows 3 writes, above the 2 at 3f2a9c1d0b7e',
+    );
+    expect(message).toContain(
+      "akan.write.placement  sends 2 server write(s) from outside a store action or a module component: st.do.removeBoard, fetch.placeBoard",
+    );
+    expect(message).toContain(
+      "akan.service.call-in-loop  service method syncAll calls once per item: this.pcService.getPc, more than the 0 recorded",
+    );
+    expect(message).toContain("hook useBoard sends a write per item from one handler: st.do.removeBoard (per item)");
+    expect(fixLinesOf(message).map((line) => line.split(":")[0])).toEqual([
+      "  baseline entry",
+      "  write sent outside a store action or module component",
+      "  service call per item",
+      "  handler with several writes",
+    ]);
+  });
+
+  test("keeps the server files' own fixes", () => {
+    const message = MaintainabilityReport.describe("apps/demo", [
+      fileOf("lib/court/Court.View.tsx"),
+      fileOf("lib/court/court.service.ts", 520),
+    ]);
+
+    expect(fixLinesOf(message)).toEqual([
+      "  *.View.tsx: Move model-independent pieces into ui/ components and display logic onto Light<Model>.",
+      "  *.service.ts: Move state transitions into document chain methods, and split an unrelated responsibility into its own module.",
+    ]);
+  });
+});

package/maintainabilityReport.ts

@@ -0,0 +1,142 @@
+import { AbstractDoc } from "./abstractDoc";
+import type {
+  DebtRuleId,
+  MaintainabilityCommands,
+  MaintainabilityFailure,
+  MaintainabilityRuleId,
+} from "./maintainabilityContract";
+import { type FileKind, MaintainabilityLimits } from "./maintainabilityLimits";
+
+type FixKey = FileKind | Exclude<MaintainabilityRuleId, "akan.size.file">;
+
+export class MaintainabilityReport {
+  static readonly #clientSplitFix =
+    'Split it, in this order: a mode/kind table `{ [kind in cnst.X["value"]]: … }` in place of mode flags, each entry a component of the module owning the data of that kind; an interaction hook in `webkit/use<X>.tsx` with its pure logic in `common/` (`akan workflow plan create-interaction`); the writes behind one endpoint (`akan workflow plan add-mutation`); last, a sub-concept in its own module (`lib/<sub>` or `lib/_<feature>`), never model-bound code moved into `ui/`.';
+  static readonly #serverMarkupFix =
+    "Move model-independent pieces into ui/ components and display logic onto Light<Model>.";
+  static readonly #oneEndpointFix =
+    "Make it one service method that runs the writes inside `this.transaction(fn)`, with a side effect such as a push command in `this.afterCommit(fn)`, behind one endpoint the action calls once; a write per item becomes one endpoint taking the list. An MCP agent or another screen calling one endpoint alone skips the rest.";
+  static readonly #fixes: { [key in FixKey]: string } = {
+    ".Template.tsx": MaintainabilityReport.#clientSplitFix,
+    ".Unit.tsx": MaintainabilityReport.#serverMarkupFix,
+    ".Util.tsx": MaintainabilityReport.#clientSplitFix,
+    ".View.tsx": MaintainabilityReport.#serverMarkupFix,
+    ".Zone.tsx": MaintainabilityReport.#clientSplitFix,
+    "ui/": MaintainabilityReport.#clientSplitFix,
+    "webkit/": MaintainabilityReport.#clientSplitFix,
+    ".store.ts":
+      "Move business logic into the service behind an endpoint and derived values onto Light<Model>; an action is fetch, set, toast.",
+    ".document.ts":
+      "Move display and predicate logic onto Light<Model>, and split an unrelated concept into its own module.",
+    ".service.ts":
+      "Move state transitions into document chain methods, and split an unrelated responsibility into its own module.",
+    [AbstractDoc.suffix]:
+      "Trim the abstract to a title, one sentence naming what the module owns, and a `## Rules` list of the invariants the code cannot show.",
+    "akan.size.component": MaintainabilityReport.#clientSplitFix,
+    "akan.store.multi-write": MaintainabilityReport.#oneEndpointFix,
+    "akan.store.root-write-chain": `A store may call another through \`RootStore\`, but that does not make the writes one. ${MaintainabilityReport.#oneEndpointFix}`,
+    "akan.component.write-chain":
+      "Move the writes into one service method behind one endpoint, called by one store action the handler calls once; a component chaining `st.do` writes, or writing once per item, leaves an agent or another screen half-done.",
+    "akan.component.store-access": MaintainabilityReport.#clientSplitFix,
+    "akan.write.placement":
+      "A server write leaves the browser through one store action, started by one module component. Move a `fetch.<mutation>` into a store action, and hand `ui/` and `webkit/` code the write as an `onX` prop or hook argument from the module's `Zone` or `Util`: they stay free of any one model, and an agent or another screen reaches the write through the store.",
+    "akan.service.call-in-loop":
+      "Load the set once (`load<Model>Many(ids)`, one filter query) or write it once (one batch method), then loop in memory: a call per item is a round trip per item, so the endpoint slows as its input grows.",
+    "akan.baseline.growth":
+      "Restore the entry from the default branch, then split the file or move the writes instead: `akan lint` lowers an entry as the code shrinks and never raises one.",
+  };
+
+  static readonly #labels: { [key in FixKey]?: string } = {
+    "ui/": "ui/**",
+    "webkit/": "webkit/**",
+    "akan.size.component": "component or hook",
+    "akan.store.multi-write": "store action with several writes",
+    "akan.store.root-write-chain": "store method chaining other stores' writes",
+    "akan.component.write-chain": "handler with several writes",
+    "akan.component.store-access": "component or hook reaching the store often",
+    "akan.write.placement": "write sent outside a store action or module component",
+    "akan.service.call-in-loop": "service call per item",
+    "akan.baseline.growth": "baseline entry",
+  };
+
+  static readonly #units: { [rule in DebtRuleId]: string } = {
+    "akan.size.file": "lines",
+    "akan.size.component": "lines",
+    "akan.component.store-access": "store accesses",
+    "akan.store.multi-write": "writes",
+    "akan.store.root-write-chain": "writes",
+    "akan.component.write-chain": "writes",
+    "akan.write.placement": "writes",
+    "akan.service.call-in-loop": "calls per item",
+  };
+
+  static describe(sysPath: string, failures: MaintainabilityFailure[], commands: MaintainabilityCommands = {}) {
+    const groups = new Map<string, { labels: string[]; rules: Set<MaintainabilityRuleId> }>();
+    for (const failure of failures) {
+      const fixKey = MaintainabilityReport.#fixKeyOf(failure);
+      const fix = MaintainabilityReport.#fixes[fixKey];
+      const group = groups.get(fix) ?? { labels: [], rules: new Set() };
+      const label = MaintainabilityReport.#labelOf(fixKey);
+      if (!group.labels.includes(label)) group.labels.push(label);
+      group.rules.add(failure.rule);
+      groups.set(fix, group);
+    }
+    return [
+      `[maintainability] ${failures.length} violation(s) in ${sysPath}:`,
+      ...failures.map(
+        (failure) =>
+          `  ${sysPath}/${failure.file}:${failure.line}  ${failure.rule}  ${MaintainabilityReport.#problemOf(failure)}`,
+      ),
+      "How to fix:",
+      ...[...groups].flatMap(([fix, { labels, rules }]) => [
+        `  ${labels.join(", ")}: ${fix}`,
+        ...[...new Set([...rules].flatMap((rule) => commands[rule] ?? []))].map((command) => `    Path: ${command}`),
+      ]),
+    ].join("\n");
+  }
+
+  static #problemOf(failure: MaintainabilityFailure) {
+    if (failure.kind === "baselineGrowth") {
+      const entry = `entry "${failure.key}" under ${failure.debtRule}`;
+      return failure.committed === undefined
+        ? `${entry} is not in the baseline at ${failure.reference}, which may only shrink`
+        : `${entry} allows ${failure.count} ${MaintainabilityReport.#units[failure.debtRule]}, above the ${failure.committed} at ${failure.reference}; the baseline may only shrink`;
+    }
+    const grown = failure.recorded === undefined ? "" : `, more than the ${failure.recorded} recorded`;
+    if (failure.kind === "multiWrite") {
+      const writes = failure.writes.some((write) => write.endsWith("(per item)"))
+        ? "a write per item"
+        : `${failure.writes.length} writes`;
+      const listed = `${failure.writes.join(", ")}${grown}`;
+      if (failure.rule === "akan.component.write-chain")
+        return `${MaintainabilityReport.#unitOf(failure.owner)} ${failure.owner} sends ${writes} from one handler: ${listed}`;
+      if (failure.rule === "akan.store.root-write-chain")
+        return `store method ${failure.owner} chains ${writes} through other stores from the browser: ${listed}`;
+      return `store action ${failure.owner} sends ${writes} from the browser: ${listed}`;
+    }
+    if (failure.kind === "writePlacement")
+      return `sends ${failure.writes.length} server write(s) from outside a store action or a module component: ${failure.writes.join(", ")}${grown}`;
+    if (failure.kind === "loopCall")
+      return `service method ${failure.owner} calls once per item: ${failure.calls.join(", ")}${grown}`;
+    if (failure.kind === "storeAccess")
+      return `${MaintainabilityReport.#unitOf(failure.component)} ${failure.component} reaches the store ${failure.accessCount} times, over the ${failure.maxAccesses}-access limit${failure.recorded === undefined ? "" : `, up from ${failure.recorded}`}`;
+    const subject = failure.component
+      ? `${MaintainabilityReport.#unitOf(failure.component)} ${failure.component} has`
+      : "file has";
+    const up = failure.recorded === undefined ? "" : `, up from ${failure.recorded}`;
+    return `${subject} ${failure.lineCount} lines, over the ${failure.maxLines}-line limit${up}`;
+  }
+
+  static #unitOf(name: string) {
+    return /^use[A-Z]/.test(name) ? "hook" : "component";
+  }
+
+  static #fixKeyOf(failure: MaintainabilityFailure): FixKey {
+    if (failure.rule !== "akan.size.file") return failure.rule;
+    return MaintainabilityLimits.fileKindOf(failure.file) ?? "akan.size.component";
+  }
+
+  static #labelOf(fixKey: FixKey) {
+    return MaintainabilityReport.#labels[fixKey] ?? `*${fixKey}`;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.1-rc.15",
+  "version": "3.1.1-rc.16",
   "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.15",
+    "akanjs": "3.1.1-rc.16",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/qualityScanner.test.ts

@@ -355,3 +355,78 @@ describe("bang comments in browser-reachable files", () => {
     );
   });
 });
+
+describe("AkanQualityScanner comment and dead-export rules", () => {
+  test("reports comment density, a loose deprecated marker and a test-only export, each with its fix", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/court/court.constant.ts": [
+        ...Array.from({ length: 5 }, (_, idx) => `// restates line ${idx}`),
+        "export class CourtInput {",
+        "  legacyVenue?: string; // deprecated",
+        "}",
+        "",
+      ].join("\n"),
+      "apps/demo/webkit/boardLayout.ts": "export const computeGroupBoxes = () => [];\n",
+      "apps/demo/webkit/boardLayout.test.ts":
+        'import { computeGroupBoxes } from "./boardLayout";\ncomputeGroupBoxes();\n',
+    });
+
+    const result = await new AkanQualityScanner().scan(root);
+    const density = rulesOf(result, "akan.comment.density");
+    const deprecated = rulesOf(result, "akan.comment.deprecated-marker");
+    const testOnly = rulesOf(result, "akan.global.test-only-export");
+
+    expect(density.map((warning) => warning.file)).toEqual(["apps/demo/lib/court/court.constant.ts"]);
+    expect(density[0]?.fix).toContain('AGENTS.md "Comments"');
+    expect(deprecated.map((warning) => warning.line)).toEqual([7]);
+    expect(deprecated[0]?.fix).toContain("/** @deprecated");
+    expect(testOnly.map((warning) => warning.file)).toEqual(["apps/demo/webkit/boardLayout.ts"]);
+    expect(testOnly[0]?.fix).toContain("unexported");
+  });
+});
+
+describe("AkanQualityScanner kind-branch rule", () => {
+  test("warns on a kind compared across three files and points at a kind table", async () => {
+    const compare = 'export const isScene = (pin: { kind: string }) => pin.kind === "videoScene";\n';
+    const root = await makeWorkspace({
+      "apps/demo/lib/pin/pin.constant.ts":
+        'export class PinKind extends enumOf("pinKind", ["videoScene", "memo"] as const) {}\n',
+      "apps/demo/lib/board/board.constant.ts": compare,
+      "apps/demo/lib/take/take.store.ts": compare,
+      "apps/demo/webkit/pinLayout.ts": compare,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.global.kind-branch");
+
+    expect(warnings.map(({ file, severity }) => ({ file, severity }))).toEqual([
+      { file: "apps/demo/lib/pin/pin.constant.ts", severity: "warning" },
+    ]);
+    expect(warnings[0]?.fix).toContain('cnst.PinKind["value"]');
+  });
+});
+
+describe("AkanQualityScanner baseline exceptions", () => {
+  test("reports each app's recorded baseline entries per rule", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/akan.baseline.json": `${JSON.stringify(
+        {
+          "akan.size.file": { "ui/Board.tsx": 420 },
+          reasons: { "ui/Board.tsx": "Generated SVG path table for the court." },
+        },
+        null,
+        2,
+      )}\n`,
+      "apps/demo/ui/Board.tsx": "export const Board = () => null;\n",
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.baseline.exceptions");
+
+    expect(warnings.map(({ file, message }) => ({ file, message }))).toEqual([
+      {
+        file: "apps/demo/akan.baseline.json",
+        message:
+          'apps/demo carries 1 reasoned exception and 0 adopted-debt entries for akan.size.file: ui/Board.tsx ("Generated SVG path table for the court.").',
+      },
+    ]);
+  });
+});

package/qualityScanner.ts

@@ -5,8 +5,13 @@ import { RESERVED_ROUTE_CONFIG_EXPORTS } from "akanjs/common";
 import ignore from "ignore";
 import ts from "typescript";
 import { AbstractDoc } from "./abstractDoc";
+import { CommentDensityScanner } from "./commentDensityScanner";
+import { DeprecatedCommentScanner } from "./deprecatedCommentScanner";
 import { FormSetterScanner } from "./formSetterScanner";
+import { KindBranchScanner } from "./kindBranchScanner";
+import { MaintainabilityExceptionScanner } from "./maintainabilityExceptionScanner";
 import { fileWarning, formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
+import { TestOnlyExportScanner } from "./testOnlyExportScanner";
 import {
   facetIndexShadowOf,
   isAllowedLibFacetRootFile,
@@ -17,7 +22,7 @@ import {
 } from "./workspaceLayout";
 
 type QualitySeverity = "warning";
-type QualityScope = "global" | "file" | "convention" | "layout" | "ssr" | "agent";
+type QualityScope = "global" | "file" | "convention" | "layout" | "ssr" | "agent" | "comment";
 
 export interface QualityWarning {
   rule: string;
@@ -115,6 +120,8 @@ const RULE_FIXES: Record<string, string> = {
     "Rename one of the exports, or if they are the same thing, extract it into one shared module and import it in both places.",
   "akan.global.duplicate-exported-function-body":
     "Extract the shared implementation into a single exported helper and import it, instead of copying the body.",
+  "akan.global.test-only-export":
+    "Delete the export together with its test. If a live caller in the same file needs it, keep it unexported and test it through that caller.",
   "akan.file.recommended-max-lines":
     "Split the file by responsibility — move Zones, Utils, or subcomponents into sibling files.",
   "akan.file.max-lines": "Break the file into smaller focused modules; keep one primary responsibility per file.",
@@ -163,6 +170,10 @@ const RULE_FIXES: Record<string, string> = {
     "Add a <Model>.Unit.tsx for list/card rendering and a <Model>.View.tsx for the detail surface, then have the Zone delegate to them.",
   "akan.ssr.template-client-state":
     "Bind the field to the store instead: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`.",
+  "akan.comment.density":
+    'Delete comments that restate the code, label a section, or narrate a step; keep only those carrying a fact the code cannot show, such as a vendor quirk or security reasoning (AGENTS.md "Comments").',
+  "akan.comment.deprecated-marker":
+    "Replace the comment with `/** @deprecated <what to use instead> */` on the declaration, so every use site shows it struck through.",
 };
 
 function getRuleFix(rule: string): string | undefined {
@@ -193,6 +204,9 @@ export class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
       ...new FormSetterScanner().scan(sourceFiles),
+      ...new CommentDensityScanner().scan(sourceFiles),
+      ...new DeprecatedCommentScanner().scan(sourceFiles),
+      ...(await new MaintainabilityExceptionScanner().scan(workspaceRoot)),
       ...ssr.warnings,
     ];
 
@@ -297,6 +311,8 @@ export class AkanQualityScanner {
       });
     }
 
+    warnings.push(...new TestOnlyExportScanner().scan(sourceFiles));
+    warnings.push(...new KindBranchScanner().scan(sourceFiles));
     return warnings;
   }
 

package/serviceLoopCallScanner.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { ServiceLoopCallScanner } from "./serviceLoopCallScanner";
+
+const scan = (body: string, answersCaller: (method: string) => boolean = () => true) =>
+  new ServiceLoopCallScanner().scan(
+    ts.createSourceFile(
+      "court.service.ts",
+      `export class CourtService extends serve(db.court, () => ({})) {\n${body}\n}\n`,
+      ts.ScriptTarget.Latest,
+      true,
+    ),
+    answersCaller,
+  );
+
+describe("ServiceLoopCallScanner", () => {
+  test("names a service, model or generated query called per item, directly or through a method of its own", () => {
+    const calls = scan(`  async syncAll(ids: string[]) {
+    for (const id of await this.listIds()) await this.pcService.ping(id);
+    await Promise.all(ids.map((id) => this.#touch(id)));
+    ids.forEach((id) => this.logger.info(id));
+  }
+  async #touch(id: string) {
+    await this.getCourt(id);
+  }`);
+
+    expect(calls).toEqual([{ method: "syncAll", line: 3, calls: ["this.pcService.ping", "this.#touch"] }]);
+  });
+
+  test("spares a counted loop, a call made once, and a method no endpoint reaches", () => {
+    const body = `  async retry(id: string) {
+    for (let attempt = 0; attempt < 3; attempt += 1) await this.courtModel.touch(id);
+    while (await this.courtModel.isLocked(id)) await Bun.sleep(10);
+  }
+  async sweep(ids: string[]) {
+    const courts = await this.loadCourtMany(ids);
+    for (const court of courts) court.touch();
+    await Promise.all(ids.map((id) => this.pcService.ping(id)));
+  }`;
+
+    expect(scan(body, (method) => method === "retry")).toEqual([]);
+  });
+
+  test("spares a get or load a per-element callback issues in one tick, which the DataLoader batches", () => {
+    const calls = scan(`  async courtsOf(ids: string[], pcIds: string[]) {
+    await Promise.all(ids.map((id) => this.getCourt(id)));
+    await Promise.all(pcIds.map((id) => this.pcModel.loadPc(id)));
+    await Promise.all(ids.map((id) => this.courtModel.countCourt({ id })));
+    for (const id of ids) await this.courtModel.getCourt(id);
+  }`);
+
+    expect(calls).toEqual([
+      { method: "courtsOf", line: 5, calls: ["this.courtModel.countCourt", "this.courtModel.getCourt"] },
+    ]);
+  });
+});

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/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 }]);
+  });
+});