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

package/codeAgent/skills/akan-scaffold/SKILL.md

@@ -43,8 +43,8 @@ Each result names the next call in `next.tool`. Follow it; do not improvise.
    and each workflow's inputs.)
 2. `apply_workflow({ planPath })` — writes the scaffold and syncs the generated barrels. Returns
    `validationTarget`.
-3. `run_validation({ runIdOrPlan: <validationTarget> })`, or just call `akan_verify`, which runs the whole
-   chain over everything the working tree changed.
+3. `run_validation({ runIdOrPlan: <validationTarget> })`, or run `akan verify` (`akan_verify` in akan code);
+   both are the whole chain in one process.
 4. **Read each scaffolded file before editing it.** They are a few lines each and they extend base classes
    that already generated the CRUD surface. Read the `akan-store` skill before touching a store or adding
    signal endpoints, or you will redeclare `create<Model>` and hit an "already exists" typecheck error.
@@ -60,9 +60,19 @@ Each result names the next call in `next.tool`. Follow it; do not improvise.
 - Hand-writing files is the fallback, used only when no workflow matches, or when apply reports
   unsupported / no-op / failed diagnostics telling you to act manually. Say which case applied.
 - Never hand-edit a generated file to "finish" a scaffold — use `repair_generated` or `akan sync <app>`.
-- No workflow tools this turn? The same order through bash:
-  `akan workflow list` → `akan workflow plan create-module --app <app> --module comment --format json --out <path>`
-  → `akan workflow apply <path> --format json`.
+
+## No workflow tools? The CLI is the same chain
+
+The tools come from `akan mcp` (`--mode plan` reads, `--mode apply` writes). When they are not connected, each
+has a command that prints the same report:
+
+| tool | command |
+| --- | --- |
+| `list_workflows` / `explain_workflow` | `akan workflow list` / `akan workflow explain <name>` |
+| `plan_workflow` | `akan workflow plan create-module --app <app> --module comment --format json --out <path>` |
+| `apply_workflow` | `akan workflow apply <path> --format json` (`--dry-run` previews) |
+| `run_validation` | `akan verify <app>` |
+| `repair_generated` / `repair_imports` / `repair_module_shape` | `akan repair generated\|imports\|module-shape --app <app>` |
 
 ## Worked example — "an intro page, two detail pages, and a comment zone with a database"
 
@@ -73,4 +83,4 @@ Each result names the next call in `next.tool`. Follow it; do not improvise.
    leave the store body empty unless you need extra state.
 4. Write the pages and the comment UI against the generated actions — `st.do.createComment`,
    `st.do.initCommentInPublic`, `st.use.commentListInPublic`.
-5. `akan_verify` until clean.
+5. `akan verify` until it prints `verify ok`.

package/codeAgent/skills/akan-transport/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: akan-transport
+description: "Guard and tune endpoints on the wire: writing a Can<Verb><Model> guard, deadlines, cache, idempotency, rate limits, server-to-server calls, body types, bytes and HTTP verbs."
+---
+
+# Akan transport
+
+## Guards
+
+- Every custom `query` / `mutation` / `pubsub` / `message` names its own `guards: [...]`; every `slice()` takes an
+  explicit guard map with `root: Admin`. `Public` belongs on a slice `get:`, and on a mutation only for an act that
+  must work signed out (sign-up, sign-in, token refresh, an OAuth route), which also declares a `rateLimit`.
+- A resource guard is a `Can<Verb><Model>` class in the model library's `srvkit/guards.ts` that fails closed:
+  no resource named, or a load that throws, is `false` (after a `logger.warn`). Admin bypass goes first.
+- Every guard declares `static scope`: `"account"` reads only the caller (`SignedIn`, `Admin`, roles), and
+  `"resource"` needs the call's arguments (every `Can<Verb><Model>`). Keep `static name = "User";` with a comment.
+- Guards read `context.get<T>("account")`, serve HTTP and websocket alike, and stay side-effect free. The acting
+  user comes from `.with(Self)` / `.with(CurrentUserId)` / `.with(Me)`, the address from `.with(Ip)` — never a
+  client-supplied id. The service re-checks ownership: two independent gates.
+
+## Endpoint options
+
+- `{ timeout: <ms> }` is the deadline on both ends; undeclared, the client quits at 30 s and the handler is not
+  cancelled.
+- `{ cache }` only on a `query` with no internal argument, capped at one day; `invalidate(endpoint, args?)` drops
+  it early through a plugged `EndpointCacheControl`.
+- `{ rateLimit: { calls, windowMs?, by? } }` per endpoint, `option.setRateLimit` per app, `plug(RateLimit)` for a
+  business key.
+- A mutation repeated under one `Idempotency-Key` header runs once and replays its first answer.
+- `{ method: "PATCH" | "PUT" | "DELETE" }` moves a mutation off `POST` — only when a foreign protocol forces it.
+- `errors: { 409: ["ticket.error.locked"] }` names the errors an endpoint throws on purpose.
+
+## Bodies and other servers
+
+- `.body()` / `.param()` take scalars, model refs or `enumOf(...)`; `Int` / `Float`, never `Number`; bytes are
+  `Binary`, never `Any`; `Upload` only in a `fileUpload: true` mutation.
+- Server to server, `fetch.clone({ origin })` opens no socket without `connect: true`, retries through `retry`,
+  and rethrows a remote `Err` as it is — never wrap or re-key it.
+
+Full detail: `get_guideline` with `transportRule`, or `mcpRule` for what a guard's scope does to an MCP listing.

package/codeAgent/skills/akan-validate/SKILL.md

@@ -7,17 +7,19 @@ description: "Run the akan check loop after editing and fix each failure class t
 
 ## One call does the whole chain
 
-`akan_verify` runs sync → lint → typecheck → `quality ssr` over everything the working tree has changed, in
-the right order, and reports only what failed. **Call it after editing, before you say you are done.** It
-also runs itself at the end of a turn that changed source, so a failure comes back to you either way.
-
-The same chain by hand, for the app you are editing:
-
-- `akan sync <app>` — after adding, renaming, or deleting any file. Regenerates the barrels.
-- `akan lint <app>` — fast; run after every edit. Prints up to 200 diagnostics.
-- `akan typecheck <app>` — the client/server boundary violations land here, not in lint.
-- `akan quality ssr` — only when you wrote or changed a `.tsx`. Did the server share hold?
-- `akan build <app>` — the full production build; slower, and only when the build itself is in question.
+`akan verify` (the `akan_verify` tool in akan code) syncs, lints with fixes, typechecks, fast-builds each
+changed app, and runs the SSR check for a `.tsx` change — over everything the working tree has changed, in one
+process. It prints one line when it passes and one line per problem when it fails. **Run it after editing,
+before you say you are done.** In akan code it also runs itself at the end of a turn that changed source.
+
+Never run `akan lint`, `akan typecheck` and `akan build` in turn: that is the same work three times over, at
+three times the output. Narrow the one command instead:
+
+- `akan verify <app-or-lib-or-pkg>` — that target whole, changed or not.
+- `akan verify --lint-only` — the quick pass between edits.
+- `akan verify --no-build` — leave the app build out.
+- `akan verify --max 0` — every line, when the report ends in `+N more`.
+- `fixed N files` in the header means lint rewrote them on disk: re-read before editing them again.
 
 Raw `tsc` misses the generated barrels and reports false errors. Do not reach for it.
 

package/codeAgent/tools/AkanCli.ts

@@ -24,7 +24,8 @@ export class AkanCli {
       cwd: this.#cwd,
       stdout: "pipe",
       stderr: "pipe",
-      env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
+      //? A workspace .env's AKAN_PUBLIC_LOG_LEVEL=verbose reaches the child too, and buried its error under 90 lines.
+      env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1", AKAN_LOG_STDOUT_LEVEL: "warn" },
     });
     const timer = setTimeout(() => proc.kill(), timeoutMs);
     const [stdout, stderr, exitCode] = await Promise.all([

package/codeAgent/tools/AkanEditScope.ts

@@ -2,12 +2,13 @@ export interface AkanEditScopeResult {
   paths: string[];
   apps: string[];
   libs: string[];
+  pkgs: string[];
   /** A created, deleted or renamed file under `apps/**` or `libs/**` — the only kind a barrel has to catch up with. */
   needsSync: boolean;
   touchesTsx: boolean;
 }
 
-const empty: AkanEditScopeResult = { paths: [], apps: [], libs: [], needsSync: false, touchesTsx: false };
+const empty: AkanEditScopeResult = { paths: [], apps: [], libs: [], pkgs: [], needsSync: false, touchesTsx: false };
 
 // Read from git, not tool events: an edit made through `bash` (a heredoc, sed, a codemod) produces no write tool call.
 export class AkanEditScope {
@@ -21,6 +22,7 @@ export class AkanEditScope {
       paths,
       apps: AkanEditScope.#targets(paths, "apps"),
       libs: AkanEditScope.#targets(paths, "libs"),
+      pkgs: AkanEditScope.#targets(paths, "pkgs"),
       needsSync: entries.some((entry) => /[ARD?]/.test(entry.code) && /^(apps|libs)\//.test(entry.file)),
       touchesTsx: paths.some((file) => file.endsWith(".tsx")),
     };
@@ -38,10 +40,13 @@ export class AkanEditScope {
     return new Set(text.split("\n").filter((line) => line.trim().length > 3));
   }
 
-  static #targets(paths: string[], root: "apps" | "libs") {
+  static #targets(paths: string[], root: "apps" | "libs" | "pkgs") {
     const names = paths
       .filter((file) => file.startsWith(`${root}/`))
-      .map((file) => file.split("/")[1] ?? "")
+      .map((file) => {
+        const [, first = "", second = ""] = file.split("/");
+        return first.startsWith("@") && second ? `${first}/${second}` : first;
+      })
       .filter(Boolean);
     return [...new Set(names)];
   }

package/codeAgent/tools/AkanToolPack.ts

@@ -1,7 +1,6 @@
 import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { Workspace } from "../../commandDecorators";
-import { AkanEditScope } from "./AkanEditScope";
 import { AkanVerifier } from "./AkanVerifier";
 
 export interface AkanToolPackOptions {
@@ -66,17 +65,12 @@ export class AkanToolPack {
       name: AkanToolPack.verifyToolName,
       label: "akan verify",
       description:
-        "Run the akan validation chain (sync, lint, typecheck, and quality ssr for .tsx changes) over everything the working tree has changed, and report what failed. Call this after editing before you finish.",
-      promptSnippet: "akan_verify: run sync/lint/typecheck/quality over the working tree's changes",
+        "Run `akan verify` over everything the working tree has changed: sync, lint (with fixes), typecheck, a fast build of each changed app, and the SSR check for .tsx changes, in one call. It prints one line when it passes and one line per problem when it fails. Call this after editing, before you finish; never run lint, typecheck or build separately.",
+      promptSnippet: "akan_verify: sync, lint, typecheck and build what the working tree changed, in one call",
       parameters: Type.Object({}),
       execute: async () => {
-        const scope = await AkanEditScope.since(this.#options.cwd, new Set());
-        const report = await verifier.verify(scope);
-        return {
-          content: [{ type: "text", text: AkanVerifier.summarize(report) }],
-          details: undefined,
-          isError: !report.ok,
-        };
+        const report = await verifier.verify();
+        return { content: [{ type: "text", text: report.text }], details: undefined, isError: !report.ok };
       },
     });
   }

package/codeAgent/tools/AkanVerifier.ts

@@ -1,48 +1,30 @@
 import { AkanCli, type AkanCliResult } from "./AkanCli";
-import type { AkanEditScopeResult } from "./AkanEditScope";
 
 export interface AkanVerifyReport {
   ok: boolean;
-  steps: AkanCliResult[];
-  scope: AkanEditScopeResult;
+  text: string;
 }
 
 export class AkanVerifier {
+  static readonly tailLines = 20;
   readonly #cli: AkanCli;
 
   constructor(cwd: string) {
     this.#cli = new AkanCli(cwd);
   }
 
-  async verify(scope: AkanEditScopeResult): Promise<AkanVerifyReport> {
-    const steps: AkanCliResult[] = [];
-    const targets = [...scope.apps, ...scope.libs];
-    // Order matters: a stale barrel reads to typecheck as a missing symbol, and lint moves the positions it reports.
-    if (scope.needsSync) for (const target of targets) steps.push(await this.#cli.run(["sync", target]));
-    for (const target of targets) steps.push(await this.#cli.run(["lint", target]));
-    for (const app of scope.apps) steps.push(await this.#cli.run(["typecheck", app]));
-    if (scope.touchesTsx) steps.push(await this.#cli.run(["quality", "ssr"]));
-    return { ok: steps.every((step) => step.ok), steps, scope };
+  async verify(paths: string[] = []): Promise<AkanVerifyReport> {
+    const args = ["verify", ...(paths.length ? ["--files", paths.join(",")] : [])];
+    const result = await this.#cli.run(args, { timeoutMs: 600_000 });
+    return { ok: result.ok, text: AkanVerifier.summarize(result) };
   }
 
-  /** What a model needs to act: which step failed and its tail — never the whole output, which rides every later turn. */
-  static summarize(report: AkanVerifyReport, { tailLines = 40 }: { tailLines?: number } = {}) {
-    if (!report.steps.length) return "No akan target was touched, so there was nothing to verify.";
-    if (report.ok) return `Verification passed: ${report.steps.map((step) => step.command).join(", ")}.`;
-    const failed = report.steps.filter((step) => !step.ok);
-    const passed = report.steps.filter((step) => step.ok).map((step) => step.command);
-    const blocks = failed.map((step) => `### ${step.command} (exit ${step.exitCode})\n${tail(step.output, tailLines)}`);
-    return [
-      `Verification failed: ${failed.map((step) => step.command).join(", ")}.`,
-      passed.length ? `Passed: ${passed.join(", ")}.` : "",
-      ...blocks,
-    ]
-      .filter(Boolean)
-      .join("\n\n");
+  //* `akan verify` already prints the agent-sized report; only a crash before it prints needs trimming.
+  static summarize(result: AkanCliResult) {
+    if (result.output.startsWith("verify ")) return result.output;
+    const lines = result.output.split("\n");
+    const tail =
+      lines.length <= AkanVerifier.tailLines ? result.output : `…\n${lines.slice(-AkanVerifier.tailLines).join("\n")}`;
+    return `${result.command} exited ${result.exitCode} before reporting:\n${tail}`;
   }
 }
-
-const tail = (text: string, lines: number) => {
-  const all = text.split("\n");
-  return all.length <= lines ? text : `…\n${all.slice(-lines).join("\n")}`;
-};

package/codeAgent/tools/akanCodePlugins.test.ts

@@ -111,38 +111,18 @@ describe("TurnFeedback", () => {
 });
 
 describe("AkanVerifier.summarize", () => {
-  const scope = { paths: ["apps/a/x.ts"], apps: ["a"], libs: [], needsSync: false, touchesTsx: false };
+  test("passes the verify report through untouched", () => {
+    const output =
+      "verify fail · a · lint ok · typecheck 1 error · 4.1s\napps/a/x.ts:1:7 TS2322 Type 'string' is not assignable to type 'number'.";
+    expect(AkanVerifier.summarize({ command: "akan verify", ok: false, exitCode: 1, output })).toBe(output);
+  });
 
-  test("names the failing step and keeps only its tail", () => {
+  test("keeps only the tail of a crash that never reached the report", () => {
     const output = [...Array(100).keys()].map((n) => `line ${n}`).join("\n");
-    const text = AkanVerifier.summarize(
-      {
-        ok: false,
-        scope,
-        steps: [
-          { command: "akan lint a", ok: true, exitCode: 0, output: "" },
-          { command: "akan typecheck a", ok: false, exitCode: 1, output },
-        ],
-      },
-      { tailLines: 5 },
-    );
-    expect(text).toContain("Verification failed: akan typecheck a");
-    expect(text).toContain("Passed: akan lint a");
+    const text = AkanVerifier.summarize({ command: "akan verify", ok: false, exitCode: 1, output });
+    expect(text).toStartWith("akan verify exited 1 before reporting:");
     expect(text).toContain("line 99");
-    expect(text).not.toContain("line 10\n");
-  });
-
-  test("says so plainly when everything passed", () => {
-    const text = AkanVerifier.summarize({
-      ok: true,
-      scope,
-      steps: [{ command: "akan lint a", ok: true, exitCode: 0, output: "" }],
-    });
-    expect(text).toContain("Verification passed");
-  });
-
-  test("an untouched workspace is not a failure", () => {
-    expect(AkanVerifier.summarize({ ok: true, scope, steps: [] })).toContain("nothing to verify");
+    expect(text).not.toContain("line 79\n");
   });
 });
 
@@ -153,9 +133,11 @@ describe("AkanEditScope", () => {
     const baseline = await AkanEditScope.baseline(root);
     await writeText(path.join(root, "apps", "demo", "lib", "post", "post.service.ts"), "export {};\n");
     await writeText(path.join(root, "libs", "shared", "ui", "Card.tsx"), "export const Card = () => null;\n");
+    await writeText(path.join(root, "pkgs", "@akanjs", "cli", "index.ts"), "export {};\n");
     const scope = await AkanEditScope.since(root, baseline);
     expect(scope.apps).toEqual(["demo"]);
     expect(scope.libs).toEqual(["shared"]);
+    expect(scope.pkgs).toEqual(["@akanjs/cli"]);
     expect(scope.needsSync).toBe(true);
     expect(scope.touchesTsx).toBe(true);
   });
@@ -165,7 +147,7 @@ describe("AkanEditScope", () => {
     await Bun.spawn(["git", "init", "-q"], { cwd: root, stdout: "ignore", stderr: "ignore" }).exited;
     const baseline = await AkanEditScope.baseline(root);
     const scope = await AkanEditScope.since(root, baseline);
-    expect(scope).toEqual({ paths: [], apps: [], libs: [], needsSync: false, touchesTsx: false });
+    expect(scope).toEqual({ paths: [], apps: [], libs: [], pkgs: [], needsSync: false, touchesTsx: false });
   });
 });
 

package/commentDensityScanner.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { CommentDensityScanner } from "./commentDensityScanner";
+import type { SourceFileInfo } from "./qualityScanner";
+
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/repo/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(
+    file,
+    content,
+    ts.ScriptTarget.Latest,
+    true,
+    file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  ),
+});
+
+const codeOf = (lineNum: number) => Array.from({ length: lineNum }, (_, idx) => `const value${idx} = ${idx};`);
+const commentsOf = (lineNum: number) => Array.from({ length: lineNum }, (_, idx) => `// note ${idx}`);
+const scan = (files: Record<string, string[]>) =>
+  new CommentDensityScanner().scan(Object.entries(files).map(([file, lines]) => fileOf(file, `${lines.join("\n")}\n`)));
+
+describe("CommentDensityScanner", () => {
+  test("flags a module over 1% with at least five comment lines, summed across its files", () => {
+    const warnings = scan({
+      "apps/demo/lib/post/post.service.ts": [...commentsOf(3), ...codeOf(100)],
+      "apps/demo/lib/post/post.document.ts": [...codeOf(50), ...commentsOf(2)],
+    });
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toMatchObject({
+      rule: "akan.comment.density",
+      scope: "comment",
+      file: "apps/demo/lib/post/post.service.ts",
+      line: 1,
+    });
+    expect(warnings[0]?.message).toContain("apps/demo/lib/post is 3.23% comments (5 of 155 non-blank lines)");
+    expect(warnings[0]?.locations).toEqual([
+      { file: "apps/demo/lib/post/post.service.ts", line: 1 },
+      { file: "apps/demo/lib/post/post.document.ts", line: 51 },
+    ]);
+  });
+
+  test("passes a module under 1%, and a small module with fewer than five comment lines", () => {
+    expect(
+      scan({
+        "apps/demo/lib/post/post.service.ts": [...commentsOf(5), ...codeOf(600)],
+        "apps/demo/lib/tag/tag.service.ts": [...commentsOf(4), ...codeOf(10)],
+      }),
+    ).toEqual([]);
+  });
+
+  test("does not count lint and TS directives or the store scaffold markers", () => {
+    expect(
+      scan({
+        "apps/demo/lib/post/post.store.ts": [
+          "export class PostStore extends store(sig.post, () => ({",
+          "  // state",
+          "})) {",
+          "  // action",
+          "}",
+          "// biome-ignore lint/style/noNonNullAssertion: vendor typing",
+          "/* biome-ignore lint/plugin: fixed brand color */",
+          "// @ts-expect-error vendor typing",
+          "// @ts-ignore vendor typing",
+          ...codeOf(5),
+        ],
+      }),
+    ).toEqual([]);
+  });
+
+  test("does not count comment syntax inside strings or JSX text", () => {
+    expect(
+      scan({
+        "apps/demo/ui/Links.tsx": [
+          'export const home = "https://host//home";',
+          'export const docs = "https://host//docs";',
+          `export const api = \`https://host//\${home}\`;`,
+          "export const Links = () => (",
+          "  <p>",
+          "    // not a comment",
+          "    // still text",
+          "  </p>",
+          ");",
+        ],
+      }),
+    ).toEqual([]);
+  });
+
+  test("measures neither srvkit nor guards.ts nor tests", () => {
+    expect(
+      scan({
+        "apps/demo/srvkit/vendorApi.ts": [...commentsOf(20), ...codeOf(10)],
+        "apps/demo/lib/post/guards.ts": [...commentsOf(20), ...codeOf(10)],
+        "apps/demo/lib/post/post.signal.test.ts": [...commentsOf(20), ...codeOf(10)],
+        "apps/demo/ui/Card.test.tsx": [...commentsOf(20), ...codeOf(10)],
+      }),
+    ).toEqual([]);
+  });
+
+  test("aggregates a ui folder as one entry and a ui file as its own", () => {
+    const warnings = scan({
+      "apps/demo/ui/Chart/Bar.tsx": [...commentsOf(3), ...codeOf(20)],
+      "apps/demo/ui/Chart/Pie.tsx": [...commentsOf(3), ...codeOf(20)],
+      "apps/demo/ui/Badge.tsx": [...commentsOf(4), ...codeOf(20)],
+    });
+
+    expect(warnings.map((warning) => warning.message.split(" is ")[0])).toEqual(["apps/demo/ui/Chart"]);
+  });
+
+  test("leaves a recipe's one-line JSDoc description uncounted", () => {
+    const recipeOf = (name: string) => [`/** ${name} look. */`, `export const ${name}Recipe = recipe(tv({}));`];
+    expect(
+      scan({
+        "apps/demo/ui/Recipe/panel.ts": [...recipeOf("panel"), ...recipeOf("tile"), ...recipeOf("card")],
+        "apps/demo/ui/Recipe/chip.ts": [...recipeOf("chip"), ...recipeOf("pill"), ...recipeOf("tag")],
+      }),
+    ).toEqual([]);
+  });
+});

package/commentDensityScanner.ts

@@ -0,0 +1,101 @@
+import path from "node:path";
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+import { type SourceComment, SourceComments } from "./sourceComments";
+
+interface CommentedFile {
+  file: string;
+  line: number;
+  commentLineNum: number;
+}
+
+interface CommentTally {
+  lineNum: number;
+  commentLineNum: number;
+  files: CommentedFile[];
+}
+
+export class CommentDensityScanner {
+  static readonly rule = "akan.comment.density";
+  static readonly maxShare = 0.01;
+  static readonly minCommentLineNum = 5;
+  static #directive =
+    /^(?:biome-ignore|@ts-(?:expect-error|ignore|nocheck|check)\b|eslint-(?:disable|enable)|<reference\b)/;
+  static #scaffoldMarkers = new Set(["state", "action"]);
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    const tallies = new Map<string, CommentTally>();
+    for (const sourceFile of sourceFiles) {
+      const unit = CommentDensityScanner.#unitOf(sourceFile.file);
+      if (!unit || !CommentDensityScanner.#isMeasured(sourceFile)) continue;
+      const tally = tallies.get(unit) ?? { lineNum: 0, commentLineNum: 0, files: [] };
+      const commentLines = CommentDensityScanner.#commentLinesOf(sourceFile);
+      tally.lineNum += sourceFile.content.split(/\r?\n/).filter((line) => line.trim() !== "").length;
+      tally.commentLineNum += commentLines.length;
+      if (commentLines[0] !== undefined)
+        tally.files.push({ file: sourceFile.file, line: commentLines[0], commentLineNum: commentLines.length });
+      tallies.set(unit, tally);
+    }
+    return [...tallies]
+      .filter(([, tally]) => CommentDensityScanner.#isDense(tally))
+      .map(([unit, tally]) => CommentDensityScanner.#warningOf(unit, tally));
+  }
+
+  static #commentLinesOf({ file, sourceFile }: SourceFileInfo) {
+    const isRecipe = file.includes("/ui/Recipe/");
+    const lines = new Set<number>();
+    for (const comment of SourceComments.of(sourceFile)) {
+      if (CommentDensityScanner.#isExempt(comment)) continue;
+      const contentIdxs = comment.body.flatMap((text, idx) => (text ? [idx] : []));
+      //? A recipe's first JSDoc line is its description in the generated AGENTS.md recipe index.
+      const countedIdxs = isRecipe && comment.isJsDoc ? contentIdxs.slice(1) : contentIdxs;
+      for (const idx of countedIdxs) lines.add(comment.line + idx);
+    }
+    return [...lines].sort((a, b) => a - b);
+  }
+
+  static #isExempt({ raw, body }: SourceComment) {
+    const head = body.find((text) => text !== "") ?? "";
+    if (CommentDensityScanner.#directive.test(head)) return true;
+    return raw.startsWith("//") && CommentDensityScanner.#scaffoldMarkers.has(head.toLowerCase());
+  }
+
+  static #isDense({ lineNum, commentLineNum }: CommentTally) {
+    return (
+      commentLineNum >= CommentDensityScanner.minCommentLineNum &&
+      commentLineNum > lineNum * CommentDensityScanner.maxShare
+    );
+  }
+
+  static #warningOf(unit: string, { lineNum, commentLineNum, files }: CommentTally): QualityWarning {
+    const [primary] = [...files].sort((a, b) => b.commentLineNum - a.commentLineNum);
+    const share = ((commentLineNum / lineNum) * 100).toFixed(2);
+    return {
+      rule: CommentDensityScanner.rule,
+      scope: "comment",
+      severity: "warning",
+      file: primary?.file ?? unit,
+      line: primary?.line,
+      message: `${unit} is ${share}% comments (${commentLineNum} of ${lineNum} non-blank lines); product lib/ and ui/ code stays under ${CommentDensityScanner.maxShare * 100}%.`,
+      ...(files.length > 1 ? { locations: files.map(({ file, line }) => ({ file, line })) } : {}),
+    };
+  }
+
+  static #unitOf(file: string) {
+    const segments = file.split("/");
+    if ((segments[0] !== "apps" && segments[0] !== "libs") || segments.length < 4) return null;
+    if (segments[2] === "ui") return segments.slice(0, 4).join("/");
+    if (segments[2] !== "lib") return null;
+    const depth = segments[3] === "__scalar" ? 5 : 4;
+    return segments.length > depth ? segments.slice(0, depth).join("/") : null;
+  }
+
+  static #isMeasured({ file, sourceFile }: SourceFileInfo) {
+    if (/\.(test|spec)\.tsx?$/.test(file) || path.basename(file) === "guards.ts") return false;
+    return !sourceFile.statements.every(
+      (statement) =>
+        ts.isExportDeclaration(statement) ||
+        (ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)),
+    );
+  }
+}

package/componentSizeScanner.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { ComponentSizeScanner } from "./componentSizeScanner";
+
+const measure = (content: string) =>
+  new ComponentSizeScanner().measure(
+    ts.createSourceFile("Board.tsx", content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX),
+  );
+
+const bodyOf = (lineNum: number) => Array.from({ length: lineNum }, (_, idx) => `  const v${idx} = ${idx};`).join("\n");
+
+describe("ComponentSizeScanner", () => {
+  test("measures a function declaration and a const arrow from their first to their last line", () => {
+    const sizes = measure(
+      `import { cn } from "akanjs/client";\n\nexport function Board() {\n${bodyOf(3)}\n  return null;\n}\n\nexport const Cell = () => {\n${bodyOf(10)}\n  return null;\n};\n`,
+    );
+    expect(sizes).toEqual([
+      { name: "Board", line: 3, lineCount: 6 },
+      { name: "Cell", line: 10, lineCount: 13 },
+    ]);
+  });
+
+  test("measures a wrapped component with its wrapper", () => {
+    const sizes = measure(
+      `export const Canvas = memo(\n  forwardRef((props, ref) => {\n${bodyOf(4)}\n    return null;\n  }),\n);\n`,
+    );
+    expect(sizes).toEqual([{ name: "Canvas", line: 1, lineCount: 9 }]);
+  });
+
+  test("skips a helper, a value, a bodiless overload and a nested component", () => {
+    const sizes = measure(
+      `const toLabel = () => "x";\nexport const Columns = 3;\nexport const Theme = { dark: true };\nexport function Overloaded(): null;\nexport const Outer = () => {\n  const Inner = () => null;\n  return <Inner />;\n};\n`,
+    );
+    expect(sizes.map(({ name }) => name)).toEqual(["Outer"]);
+  });
+});

package/componentSizeScanner.ts

@@ -0,0 +1,52 @@
+import ts from "typescript";
+
+export interface ComponentSize {
+  name: string;
+  line: number;
+  lineCount: number;
+}
+
+export interface ComponentNode {
+  name: string;
+  node: ts.FunctionDeclaration | ts.VariableDeclaration;
+}
+
+//? A hook is a component without markup: the same function-sized unit of screen code, so the same limits hold.
+export class ComponentSizeScanner {
+  static readonly #componentName = /^(?:[A-Z]|use[A-Z])[A-Za-z0-9]*$/;
+
+  static componentsAndHooksOf(sourceFile: ts.SourceFile): ComponentNode[] {
+    return sourceFile.statements.flatMap((statement): ComponentNode[] => {
+      if (ts.isFunctionDeclaration(statement))
+        return statement.name && statement.body && ComponentSizeScanner.#componentName.test(statement.name.text)
+          ? [{ name: statement.name.text, node: statement }]
+          : [];
+      if (!ts.isVariableStatement(statement)) return [];
+      return statement.declarationList.declarations.flatMap((declaration) =>
+        ts.isIdentifier(declaration.name) &&
+        ComponentSizeScanner.#componentName.test(declaration.name.text) &&
+        declaration.initializer &&
+        ComponentSizeScanner.#holdsFunction(declaration.initializer)
+          ? [{ name: declaration.name.text, node: declaration }]
+          : [],
+      );
+    });
+  }
+
+  measure(sourceFile: ts.SourceFile): ComponentSize[] {
+    return ComponentSizeScanner.componentsAndHooksOf(sourceFile).map(({ name, node }) => {
+      const line = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+      const endLine = sourceFile.getLineAndCharacterOfPosition(node.getEnd()).line + 1;
+      return { name, line, lineCount: endLine - line + 1 };
+    });
+  }
+
+  //? A wrapped component (`memo(() => …)`, `forwardRef(…)`) is still one component, measured with its wrapper.
+  static #holdsFunction(expression: ts.Expression): boolean {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression(current))
+      current = current.expression;
+    if (ts.isArrowFunction(current) || ts.isFunctionExpression(current)) return true;
+    return ts.isCallExpression(current) && current.arguments.some((arg) => ComponentSizeScanner.#holdsFunction(arg));
+  }
+}