@akanjs/devkit 3.1.1-rc.8 → 3.1.1

package/preview/PreviewView.ts

@@ -0,0 +1,219 @@
+import { PreviewChrome, type PreviewEngine } from "./PreviewChrome";
+
+export interface PreviewProbeOptions {
+  screenshot?: boolean;
+  width?: number;
+  height?: number;
+  engine?: PreviewEngine;
+  /** Bounds the whole probe: a dev server that is recovering takes the connection and never answers. */
+  timeoutMs?: number;
+  /** Waited after the load, so the errors effects throw land before the page is read. */
+  settleMs?: number;
+}
+
+export interface PreviewProbeResult {
+  url: string;
+  finalUrl: string;
+  status: number | null;
+  title: string;
+  text: string;
+  consoleErrors: string[];
+  consoleWarnings: string[];
+  pageErrors: string[];
+  /** Cheap structural smells that read as "the page is broken" without anyone looking at it. */
+  domFindings: string[];
+  screenshot?: string;
+}
+
+interface WebViewLike {
+  navigate(url: string): Promise<void>;
+  evaluate(expression: string): Promise<unknown>;
+  screenshot(options: { encoding: "base64" }): Promise<string>;
+  close(): void | Promise<void>;
+}
+
+interface PageRead {
+  href: string;
+  title: string;
+  text: string;
+  status: number | null;
+  empty: boolean;
+  pageErrors: string[];
+  domFindings: string[];
+}
+
+// Bun.WebView rather than a downloaded browser: on macOS its webkit backend needs no Chromium at all.
+// It is experimental, so its whole surface stays behind this adapter; a Bun minor that changes it breaks one file.
+export class PreviewView {
+  static get available() {
+    return PreviewView.isAvailable();
+  }
+
+  static isAvailable(engine: PreviewEngine = PreviewChrome.backend) {
+    return typeof (Bun as unknown as { WebView?: unknown }).WebView === "function" && PreviewChrome.isAvailable(engine);
+  }
+
+  static unavailableReason(engine: PreviewEngine = PreviewChrome.backend) {
+    if (typeof (Bun as unknown as { WebView?: unknown }).WebView !== "function")
+      return "This Bun build has no WebView, so the page preview is off.";
+    return PreviewChrome.unavailableReason(engine);
+  }
+
+  static async probe(
+    url: string,
+    {
+      screenshot = false,
+      width = 1280,
+      height = 800,
+      engine = PreviewChrome.backend,
+      timeoutMs = 30_000,
+      settleMs = 0,
+    }: PreviewProbeOptions = {},
+  ): Promise<PreviewProbeResult> {
+    const logs: string[] = [];
+    const deadline = Date.now() + timeoutMs;
+    const within = <T>(work: Promise<T>, what: string) => PreviewView.#within(work, deadline, `${what} ${url}`);
+    const view = PreviewView.#open({ width, height, engine, onConsole: (line) => logs.push(line) });
+    try {
+      let page = await PreviewView.#load(view, url, settleMs, within);
+      //? Right after a save the first load can render nothing (`[rscClient] module not loaded`); the next one has it.
+      if (page.empty) {
+        logs.length = 0;
+        page = await PreviewView.#load(view, url, settleMs, within);
+      }
+      const result: PreviewProbeResult = {
+        url,
+        finalUrl: page.href,
+        status: page.status ?? (await PreviewView.#statusOf(page.href, deadline)),
+        title: page.title,
+        text: page.text,
+        consoleErrors: logs.filter((line) => line.startsWith("error")),
+        consoleWarnings: logs.filter((line) => line.startsWith("warn")),
+        pageErrors: page.pageErrors,
+        domFindings: page.domFindings,
+      };
+      if (screenshot) result.screenshot = await within(view.screenshot({ encoding: "base64" }), "screenshotting");
+      return result;
+    } finally {
+      await view.close();
+    }
+  }
+
+  static async #load(
+    view: WebViewLike,
+    url: string,
+    settleMs: number,
+    within: <T>(work: Promise<T>, what: string) => Promise<T>,
+  ): Promise<PageRead> {
+    await within(view.navigate(url), "loading");
+    if (settleMs > 0) await Bun.sleep(settleMs);
+    const read = (await within(view.evaluate(readPageExpression), "reading")) as Partial<PageRead> | null;
+    return {
+      href: typeof read?.href === "string" ? read.href : url,
+      title: typeof read?.title === "string" ? read.title : "",
+      text: typeof read?.text === "string" ? read.text : "",
+      status: typeof read?.status === "number" && read.status > 0 ? read.status : null,
+      empty: read?.empty === true,
+      pageErrors: PreviewView.#strings(read?.pageErrors),
+      domFindings: PreviewView.#strings(read?.domFindings),
+    };
+  }
+
+  //? webkit has no Navigation Timing `responseStatus`, so the status comes from asking the server again, unredirected.
+  static async #statusOf(href: string, deadline: number) {
+    const left = Math.max(1, deadline - Date.now());
+    const response = await fetch(href, { redirect: "manual", signal: AbortSignal.timeout(left) }).catch(() => null);
+    return response?.status ?? null;
+  }
+
+  static async #within<T>(work: Promise<T>, deadline: number, what: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const expired = new Promise<never>((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`Timed out ${what}; the dev server may be rebuilding or stuck.`)),
+        Math.max(0, deadline - Date.now()),
+      );
+    });
+    try {
+      return await Promise.race([work, expired]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  static #open({
+    width,
+    height,
+    engine,
+    onConsole,
+  }: {
+    width: number;
+    height: number;
+    engine: PreviewEngine;
+    onConsole: (line: string) => void;
+  }) {
+    const Ctor = (Bun as unknown as { WebView: new (options: unknown) => WebViewLike }).WebView;
+    return new Ctor({
+      width,
+      height,
+      dataStore: "ephemeral",
+      backend: PreviewChrome.backendOption(engine),
+      // The console option is a callback taking `(type, ...args)`, not an object of console methods.
+      console: (type: string, ...args: unknown[]) => onConsole(`${type} ${PreviewView.formatConsole(args)}`),
+    });
+  }
+
+  /** Substitutes `%s` as the console does, since React passes a warning's detail as arguments, and cuts it short. */
+  static formatConsole(args: unknown[]) {
+    const [first, ...rest] = args;
+    const head =
+      typeof first === "string"
+        ? first.replace(/%[sdifoOc]/g, (token) => {
+            if (!rest.length) return token;
+            const value = rest.shift();
+            return token === "%c" ? "" : String(value);
+          })
+        : String(first);
+    return [head, ...rest.map(String)]
+      .join(" ")
+      .replace(/\n(\s*\n)+/g, "\n")
+      .slice(0, 1_500);
+  }
+
+  static #strings(value: unknown) {
+    return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+  }
+}
+
+// evaluate() takes one expression (a statement list is a SyntaxError), hence the IIFE; one call in flight per view.
+// `view.title` is only refreshed by a navigation, so the title is read from the document.
+const readPageExpression = `(() => {
+  const pageErrors = [];
+  const domFindings = [];
+  const body = document.body;
+  const rendered = body ? Array.from(body.children).filter((el) => !["SCRIPT", "STYLE", "TEMPLATE", "LINK", "NOSCRIPT"].includes(el.tagName) && !el.classList.contains("__akan_hmr_overlay")) : [];
+  const empty = !rendered.length && !(body && body.innerText && body.innerText.trim());
+  if (empty) pageErrors.push("The page body rendered empty.");
+  if (self.__AKAN_HMR_SYSTEM_PAGE__) pageErrors.push("The server could not render this page and answered with its error page: " + (body ? body.innerText.trim().replace(/\\s+/g, " ").slice(0, 400) : ""));
+  const overlay = document.querySelector('.__akan_hmr_overlay[data-status="error"]');
+  if (overlay) pageErrors.push("The dev build failed: " + overlay.textContent.trim().slice(0, 400));
+  const all = Array.from(document.querySelectorAll("body *"));
+  const viewportWidth = document.documentElement.clientWidth;
+  const pageWidth = document.documentElement.scrollWidth;
+  if (pageWidth > viewportWidth + 8) {
+    const wide = all.find((el) => el.getBoundingClientRect().right > viewportWidth + 8);
+    domFindings.push("The page is " + pageWidth + "px wide in a " + viewportWidth + "px viewport" + (wide ? ", first wider element: " + (wide.tagName.toLowerCase() + "." + (typeof wide.className === "string" ? wide.className : "")).slice(0, 120) : "") + ".");
+  }
+  const invisibleText = all.filter((el) => {
+    if (!el.textContent || !el.textContent.trim()) return false;
+    const style = getComputedStyle(el);
+    return style.color === style.backgroundColor && style.backgroundColor !== "rgba(0, 0, 0, 0)";
+  });
+  if (invisibleText.length) domFindings.push(invisibleText.length + " element(s) render text in the same colour as their background.");
+  const unresolved = all.filter((el) => /(^|\\s)(bg|text|border)-(base-100|base-content|primary-content|error)(\\s|$)/.test(typeof el.className === "string" ? el.className : ""));
+  if (unresolved.length) domFindings.push(unresolved.length + " element(s) use a dropped daisyUI colour slot that renders no CSS.");
+  const navigation = performance.getEntriesByType("navigation")[0];
+  const status = navigation && typeof navigation.responseStatus === "number" ? navigation.responseStatus : null;
+  const text = body ? body.innerText.trim().replace(/\\s+/g, " ").slice(0, 600) : "";
+  return { href: location.href, title: document.title, text, status, empty, pageErrors, domFindings };
+})()`;

package/preview/index.ts

@@ -0,0 +1,2 @@
+export * from "./PreviewChrome";
+export * from "./PreviewView";

package/preview/previewView.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import { PreviewView } from "./PreviewView";
+
+const serve = (html: string, status = 200) =>
+  Bun.serve({ port: 0, fetch: () => new Response(html, { status, headers: { "content-type": "text/html" } }) });
+
+describe("PreviewView", () => {
+  test("reports whether this Bun build can drive a headless page at all", () => {
+    expect(typeof PreviewView.available).toBe("boolean");
+  });
+
+  test("formats a console call the way the console prints it", () => {
+    expect(PreviewView.formatConsole(["%cstyled%c %s of %d", "color:red", "", "two", 3, "extra"])).toBe(
+      "styled two of 3 extra",
+    );
+    expect(PreviewView.formatConsole(["a\n\n\n  \nb"])).toBe("a\nb");
+    expect(PreviewView.formatConsole(["x".repeat(2_000)])).toHaveLength(1_500);
+  });
+
+  test.skipIf(!PreviewView.available)(
+    "finds an empty body and a console error on a real page",
+    async () => {
+      const server = serve('<!doctype html><html><body></body><script>console.error("boom")</script></html>');
+      try {
+        const probe = await PreviewView.probe(`http://localhost:${server.port}/`);
+        expect(probe.pageErrors.join(" ")).toContain("rendered empty");
+        expect(probe.consoleErrors.join(" ")).toContain("boom");
+      } finally {
+        server.stop(true);
+      }
+    },
+    30_000,
+  );
+
+  test.skipIf(!PreviewView.available)(
+    "reads the status, the live title, a failed dev build and a page wider than the viewport",
+    async () => {
+      const server = serve(
+        [
+          "<!doctype html><html><head><title>Before</title></head><body>",
+          '<div style="width:900px">wide</div>',
+          '<div class="__akan_hmr_overlay" data-status="error">Build failed: page.tsx</div>',
+          '<script>document.title = "After";</script>',
+          "</body></html>",
+        ].join(""),
+        404,
+      );
+      try {
+        const probe = await PreviewView.probe(`http://localhost:${server.port}/missing`, { width: 390, height: 844 });
+        expect(probe.status).toBe(404);
+        expect(probe.title).toBe("After");
+        expect(probe.text).toBe("wide Build failed: page.tsx");
+        expect(probe.pageErrors).toEqual(["The dev build failed: Build failed: page.tsx"]);
+        expect(probe.domFindings.join(" ")).toContain("first wider element: div");
+      } finally {
+        server.stop(true);
+      }
+    },
+    30_000,
+  );
+
+  test.skipIf(!PreviewView.available)(
+    "gives up on a server that takes the connection and never answers",
+    async () => {
+      const server = Bun.serve({ port: 0, fetch: () => new Promise<Response>(() => undefined) });
+      try {
+        await expect(PreviewView.probe(`http://localhost:${server.port}/`, { timeoutMs: 1_500 })).rejects.toThrow(
+          "Timed out loading",
+        );
+      } finally {
+        server.stop(true);
+      }
+    },
+    30_000,
+  );
+});

package/prompter.ts

@@ -1,6 +1,7 @@
 import fsPromise from "node:fs/promises";
 import { input, select } from "@inquirer/prompts";
 
+import { ConventionSet } from "./conventionSet";
 import { getDirname } from "./fileSys";
 
 interface FileUpdateRequestProps {
@@ -40,8 +41,14 @@ export class Prompter {
     if (!guideNames.includes(guideName))
       throw new Error(`Unknown guideline "${guideName}". Available: ${guideNames.join(", ")}`);
     const guidelineRoot = await Prompter.#getGuidelineRoot();
+    const composed = `${guidelineRoot}/${guideName}/core.md`;
+    if (await Bun.file(composed).exists())
+      return (await ConventionSet.load(`${guidelineRoot}/${guideName}`)).instruction;
     return await fsPromise.readFile(`${guidelineRoot}/${guideName}/${guideName}.instruction.md`, "utf-8");
   }
+  static async getConventionSet() {
+    return await ConventionSet.load(`${await Prompter.#getGuidelineRoot()}/conventions`);
+  }
   static async getUpdateRequest(guideName: string) {
     return await input({
       message: `What do you want to update in ${guideName}?`,

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/routeSourceValidator.test.ts

@@ -43,12 +43,14 @@ describe("RouteSourceValidator route chains", () => {
   const chain = (source: string, kind: "page" | "layout", pattern: string) =>
     RouteSourceValidator.validateRouteSourceExports(source, `page/${kind}.tsx`, kind, { pattern });
 
-  test("reads params, prompt, apps and devOnly off a page() chain without evaluating it", () => {
+  test("reads params, search names, prompt, apps, guard and devOnly off a page() chain without evaluating it", () => {
     const source = [
       'import { page } from "akanjs/client";',
       "export default page()",
       '  .param("projectId", ID, { desc: "The project." })',
       '  .search("status", String)',
+      "  .search(dynamicName, String)",
+      "  .guard(() => signedIn())",
       "  .config({ transition: 'stack', devOnly: true })",
       '  .prompt("briefProject", "Brief one project.")',
       '  .app("showProject", "Show one project.", ({ projectId }) => null)',
@@ -57,7 +59,14 @@ describe("RouteSourceValidator route chains", () => {
     ].join("\n");
     expect(chain(source, "page", "/:lang/project/:projectId")).toEqual({
       devOnly: true,
-      chain: { kind: "page", params: ["projectId"], prompt: "briefProject", apps: ["showProject", "showBoard"] },
+      chain: {
+        kind: "page",
+        params: ["projectId"],
+        prompt: "briefProject",
+        apps: ["showProject", "showBoard"],
+        search: ["status"],
+        guarded: true,
+      },
     });
   });
 

package/routeSourceValidator.ts

@@ -17,6 +17,10 @@ export interface RouteSourceChain {
   prompt?: string;
   /** The `.app()` names, each one MCP App the build gives a view of its own. */
   apps: string[];
+  /** The `.search()` names, in chain order; a name that is not a literal is left out. */
+  search: string[];
+  /** The chain calls `.guard()`, which gates this route and, on a layout, every route under it. */
+  guarded: boolean;
 }
 
 interface ChainStage {
@@ -104,6 +108,8 @@ export class RouteSourceValidator {
         params: chain.params,
         ...(chain.prompt ? { prompt: chain.prompt } : {}),
         apps: chain.apps,
+        search: chain.search,
+        guarded: chain.guarded,
       },
     };
   }
@@ -168,8 +174,10 @@ export class RouteSourceValidator {
   static #chainOf(kind: RouteSourceChain["kind"], stages: ChainStage[], filePath: string) {
     const params: string[] = [];
     const apps: string[] = [];
+    const search: string[] = [];
     let prompt: string | undefined;
     let devOnly = false;
+    let guarded = false;
     const literal = (stage: ChainStage) => {
       const first = stage.args[0];
       if (!first || !ts.isStringLiteralLike(first))
@@ -182,10 +190,14 @@ export class RouteSourceValidator {
       if (stage.name === "param") params.push(literal(stage));
       else if (stage.name === "prompt") prompt = literal(stage);
       else if (stage.name === "app") apps.push(literal(stage));
-      else if (stage.name === "config")
+      else if (stage.name === "guard") guarded = true;
+      else if (stage.name === "search") {
+        const first = stage.args[0];
+        if (first && ts.isStringLiteralLike(first)) search.push(first.text);
+      } else if (stage.name === "config")
         devOnly = RouteSourceValidator.#devOnlyOf(RouteSourceValidator.#unwrapExpression(stage.args[0]), filePath);
     }
-    return { kind, params, prompt, apps, devOnly };
+    return { kind, params, prompt, apps, search, guarded, devOnly };
   }
 
   /** The same rule the loader applies: a page names every `[x]` it sits under, a layout may name a subset. */

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