@akanjs/devkit 3.1.1-rc.9 → 3.1.2-rc.0

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

package/componentWriteChainScanner.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { ComponentWriteChainScanner } from "./componentWriteChainScanner";
+import type { SourceFileInfo } from "./qualityScanner";
+import { SignalMutationIndex } from "./signalMutationIndex";
+import { WritingActionIndex } from "./writingActionIndex";
+
+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 index = new WritingActionIndex(
+  new SignalMutationIndex([
+    fileOf(
+      "apps/demo/lib/court/court.signal.ts",
+      `export class CourtSlice extends slice(srv.court, { guards: { root: Admin, cru: User } }, () => ({})) {}
+export class CourtEndpoint extends endpoint(srv.court, ({ query, mutation }) => ({
+  skipNvrOnCourt: mutation(cnst.Court, { guards: [User] }).param("courtId", ID).exec(() => null),
+  courtCount: query(Int, { guards: [User] }).exec(() => 0),
+})) {}
+`,
+    ),
+  ]),
+  [
+    fileOf(
+      "apps/demo/lib/court/court.store.ts",
+      `import { fetch, sig } from "../useClient";
+export class CourtStore extends store(sig.court, () => ({})) {
+  async skipNvrOnCourt(courtId: string) {
+    this.setCourt(await fetch.skipNvrOnCourt(courtId));
+  }
+  async loadCourtCount() {
+    this.set({ count: await fetch.courtCount() });
+  }
+}
+`,
+    ),
+  ],
+);
+
+const chainsIn = (body: string) =>
+  new ComponentWriteChainScanner(index).scan(
+    fileOf(
+      "apps/demo/lib/court/Court.Zone.tsx",
+      `"use client";\nimport { st } from "@apps/demo/client";\n\nexport const Install = ({ courtId }: { courtId: string }) => {\n${body}\n};\n`,
+    ).sourceFile,
+  );
+
+describe("ComponentWriteChainScanner", () => {
+  test("reports one handler sending two writing actions at the second", () => {
+    const chains = chainsIn(`  const register = st
+    .tool("registerNvr")
+    .exec(async () => {
+      await st.do.updateCourt(courtId, {});
+      await st.do.loadCourtCount();
+      await st.do.skipNvrOnCourt(courtId);
+    });
+  return <button type="button" onClick={() => void register()} />;`);
+
+    expect(chains).toEqual([
+      { component: "Install", line: 10, writes: ["st.do.updateCourt", "st.do.skipNvrOnCourt"], writeCount: 2 },
+    ]);
+  });
+
+  test("passes two writes in two separate handlers, a render callback included", () => {
+    const chains = chainsIn(`  const courtIds = [courtId];
+  return (
+    <div>
+      {courtIds.map((id) => (
+        <div key={id}>
+          <button type="button" onClick={() => void st.do.removeCourt(id)} />
+          <button type="button" onClick={() => void st.do.skipNvrOnCourt(id)} />
+        </div>
+      ))}
+    </div>
+  );`);
+
+    expect(chains).toEqual([]);
+  });
+
+  test("reads exclusive branches as one and an array or promise callback as part of its handler", () => {
+    const chains = chainsIn(`  const onSave = async (isNew: boolean) => {
+    if (isNew) await st.do.createCourt({});
+    else await st.do.updateCourt(courtId, {});
+  };
+  const onRemoveAll = async (ids: string[]) => {
+    await Promise.all(ids.map((id) => st.do.removeCourt(id)));
+    await st.do.submitCourt().then(() => st.do.mergeCourt(courtId, {}));
+  };
+  return <button type="button" onClick={() => void onSave(true)} />;`);
+
+    expect(chains).toEqual([
+      {
+        component: "Install",
+        line: 11,
+        writes: ["st.do.removeCourt (per item)", "st.do.submitCourt", "st.do.mergeCourt"],
+        writeCount: 4,
+      },
+    ]);
+  });
+
+  test("reads one write per item as a chain, in a loop or a per-element callback, and a hook like a component", () => {
+    const loop = chainsIn(`  const onRemoveAll = async (ids: string[]) => {
+    for (const id of ids) await st.do.removeCourt(id);
+  };
+  return <button type="button" onClick={() => void onRemoveAll([courtId])} />;`);
+    const hook = new ComponentWriteChainScanner(index).scan(
+      fileOf(
+        "apps/demo/webkit/useBulk.tsx",
+        'import { st } from "@apps/demo/client";\n\nexport const useBulk = () => ({\n  run: async (ids: string[]) => {\n    await Promise.all(ids.map((id) => st.do.removeCourt(id)));\n  },\n});\n',
+      ).sourceFile,
+    );
+
+    expect(loop).toEqual([{ component: "Install", line: 6, writes: ["st.do.removeCourt (per item)"], writeCount: 2 }]);
+    expect(hook).toEqual([{ component: "useBulk", line: 5, writes: ["st.do.removeCourt (per item)"], writeCount: 2 }]);
+  });
+
+  test("ignores a component file that does not import st", () => {
+    const chains = new ComponentWriteChainScanner(index).scan(
+      fileOf(
+        "apps/demo/ui/Plain.tsx",
+        "export const Plain = () => {\n  const onClick = async () => {\n    await st.do.createCourt({});\n    await st.do.removeCourt('a');\n  };\n  return null;\n};\n",
+      ).sourceFile,
+    );
+
+    expect(chains).toEqual([]);
+  });
+});

package/componentWriteChainScanner.ts

@@ -0,0 +1,104 @@
+import ts from "typescript";
+import { ComponentSizeScanner } from "./componentSizeScanner";
+import { StoreAccessScanner } from "./storeAccessScanner";
+import { WritePath } from "./writePath";
+import type { WritingActionIndex } from "./writingActionIndex";
+
+export interface ComponentWriteChain {
+  component: string;
+  line: number;
+  writes: string[];
+  writeCount: number;
+}
+
+//? A callback an array method or a promise runs belongs to the handler that started it; any other function is one.
+export class ComponentWriteChainScanner {
+  static readonly #inlineCallers = new Set([
+    "map",
+    "flatMap",
+    "forEach",
+    "filter",
+    "reduce",
+    "some",
+    "every",
+    "find",
+    "findIndex",
+    "then",
+    "catch",
+    "finally",
+  ]);
+  readonly #index: WritingActionIndex;
+
+  constructor(index: WritingActionIndex) {
+    this.#index = index;
+  }
+
+  scan(sourceFile: ts.SourceFile): ComponentWriteChain[] {
+    const stNames = StoreAccessScanner.stNamesOf(sourceFile);
+    if (!stNames.size) return [];
+    const path = new WritePath(
+      (call) => {
+        const action = ComponentWriteChainScanner.#actionOf(call.expression, stNames);
+        return !!action && this.#index.isWritingAction(action);
+      },
+      { enters: ComponentWriteChainScanner.#isInlineCallback },
+    );
+    return ComponentSizeScanner.componentsAndHooksOf(sourceFile).flatMap(({ name, node }) =>
+      ComponentWriteChainScanner.#handlersIn(node).flatMap((handler) => {
+        const writes = path.along(handler);
+        const writeCount = path.countOf(writes);
+        const second = writes[1] ?? writes[0];
+        if (writeCount < 2 || !second) return [];
+        return [
+          {
+            component: name,
+            line: sourceFile.getLineAndCharacterOfPosition(second.getStart(sourceFile)).line + 1,
+            writes: writes.map((call) => path.labelOf(call, sourceFile)),
+            writeCount,
+          },
+        ];
+      }),
+    );
+  }
+
+  static #handlersIn(component: ts.Node) {
+    const bodies: ts.ConciseBody[] = [];
+    const visit = (node: ts.Node) => {
+      if (
+        ComponentWriteChainScanner.#isFunction(node) &&
+        node.body &&
+        !ComponentWriteChainScanner.#isInlineCallback(node)
+      )
+        bodies.push(node.body);
+      ts.forEachChild(node, visit);
+    };
+    visit(component);
+    return bodies;
+  }
+
+  static #isFunction(node: ts.Node): node is ts.FunctionLikeDeclaration {
+    return (
+      ts.isArrowFunction(node) ||
+      ts.isFunctionExpression(node) ||
+      ts.isFunctionDeclaration(node) ||
+      ts.isMethodDeclaration(node)
+    );
+  }
+
+  static #isInlineCallback(fn: ts.Node) {
+    const call = fn.parent;
+    return (
+      !!call &&
+      ts.isCallExpression(call) &&
+      call.arguments.some((arg) => arg === fn) &&
+      ts.isPropertyAccessExpression(call.expression) &&
+      ComponentWriteChainScanner.#inlineCallers.has(call.expression.name.text)
+    );
+  }
+
+  static #actionOf(callee: ts.Expression, stNames: Set<string>) {
+    if (!ts.isPropertyAccessExpression(callee) || !ts.isPropertyAccessExpression(callee.expression)) return null;
+    const { expression: st, name } = callee.expression;
+    return ts.isIdentifier(st) && stNames.has(st.text) && name.text === "do" ? callee.name.text : null;
+  }
+}

package/conventionSet.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import fsPromise from "node:fs/promises";
+import path from "node:path";
+import { ConventionSet } from "./conventionSet";
+import { MaintainabilityContract } from "./maintainabilityContract";
+import { Prompter } from "./prompter";
+
+describe("ConventionSet", () => {
+  test("expands every brace list, so a comma-separated glob field can carry it", () => {
+    expect(ConventionSet.expand("{apps,libs}/**/*.{ts,tsx}")).toEqual([
+      "apps/**/*.ts",
+      "apps/**/*.tsx",
+      "libs/**/*.ts",
+      "libs/**/*.tsx",
+    ]);
+    expect(ConventionSet.expand("**/.env*")).toEqual(["**/.env*"]);
+  });
+
+  test("reads a rule's description and paths from its frontmatter, and refuses one without", () => {
+    const rule = ConventionSet.parseRule(
+      "page",
+      '---\ndescription: Route files.\npaths:\n  - "{apps,libs}/**/page/**"\n---\n\n# Pages\n',
+    );
+    expect(rule).toEqual({
+      name: "page",
+      description: "Route files.",
+      paths: ["{apps,libs}/**/page/**"],
+      body: "# Pages",
+    });
+    expect(() => ConventionSet.parseRule("bare", "# Pages\n")).toThrow("no frontmatter");
+    expect(() => ConventionSet.parseRule("empty", "---\ndescription: x\n---\n")).toThrow("description and paths");
+  });
+
+  test("nests each rule under the core when composed, leaving fenced code alone", () => {
+    const set = new ConventionSet("## Core", [
+      { name: "a", description: "d", paths: ["x"], body: "# A\n\n## Part\n\n```sh\n# a comment\n```" },
+    ]);
+    expect(set.instruction).toBe("## Core\n\n## A\n\n### Part\n\n```sh\n# a comment\n```\n");
+  });
+
+  test("the shipped conventions guideline is the core followed by every rule", async () => {
+    const set = await Prompter.getConventionSet();
+    const instruction = await Prompter.getInstruction("conventions");
+    expect(set.rules.length).toBeGreaterThanOrEqual(10);
+    expect(instruction.startsWith(set.core)).toBe(true);
+    for (const rule of set.rules) {
+      expect(rule.body).toStartWith("# ");
+      expect(instruction).toContain(`\n#${rule.body.split("\n")[0]}\n`);
+    }
+  });
+
+  test("names only checks that exist, and names every lint plugin and maintainability gate somewhere", async () => {
+    const set = await Prompter.getConventionSet();
+    const named = new Set(
+      [set.core, ...set.rules.map((rule) => rule.body)].flatMap((text) =>
+        [...text.matchAll(/`([^`\s]+)`/g)].map((match) => match[1] ?? ""),
+      ),
+    );
+    const plugins = (await fsPromise.readdir(path.join(import.meta.dir, "lint")))
+      .filter((file) => file.endsWith(".grit"))
+      .map((file) => file.slice(0, -".grit".length));
+    const gates: readonly string[] = MaintainabilityContract.ruleIds;
+    const gateAreas = new Set(gates.map((id) => id.split(".").slice(0, 2).join(".")));
+    const isPluginName = (name: string) => /^non?-[a-z]+(-[a-z]+)+$/.test(name);
+    const isGateName = (name: string) =>
+      gateAreas.has(name.split(".").slice(0, 2).join(".")) && !name.endsWith(".json");
+
+    expect([...named].filter((name) => isPluginName(name) && !plugins.includes(name))).toEqual([]);
+    expect([...named].filter((name) => isGateName(name) && !gates.includes(name))).toEqual([]);
+    expect(plugins.filter((plugin) => !named.has(plugin))).toEqual([]);
+    expect(gates.filter((gate) => !named.has(gate))).toEqual([]);
+  });
+});