@akanjs/devkit 3.1.1-rc.9 → 3.1.1

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

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