@akanjs/devkit 2.4.2-rc.3 → 3.0.0-alpha.1

package/qualityScanner.test.ts

@@ -3,7 +3,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { AbstractDoc } from "./abstractDoc";
-import { AkanQualityScanner } from "./qualityScanner";
+import { AkanQualityScanner, type QualityScanResult } from "./qualityScanner";
 
 const tempRoots: string[] = [];
 
@@ -44,3 +44,142 @@ describe("AkanQualityScanner abstract rule", () => {
     expect(warnings[0]?.fix).toContain("akan compact");
   });
 });
+
+const staticMarkup = (elementNum: number) =>
+  Array.from({ length: elementNum }, (_, idx) => `      <p className="text-sm">row ${idx}</p>`).join("\n");
+
+const rulesOf = (result: QualityScanResult, rule: string) => result.warnings.filter((warning) => warning.rule === rule);
+
+describe("AkanQualityScanner ssr rules", () => {
+  test("flags a client file that uses no client-only capability", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Plain.tsx": `"use client";\nexport const Plain = () => <div>plain</div>;\n`,
+      "apps/demo/ui/Interactive.tsx": `"use client";\nexport const Interactive = () => <button onClick={() => null}>go</button>;\n`,
+      "apps/demo/ui/Hooked.tsx": `"use client";\nimport { useState } from "react";\nexport const Hooked = () => {\n  const [open] = useState(false);\n  return <div>{open ? "y" : "n"}</div>;\n};\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.unnecessary-use-client");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("apps/demo/ui/Plain.tsx");
+  });
+
+  test("keeps the directive on a third-party wrapper and on an index_ boundary", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Chart.tsx": `"use client";\nimport { Bar } from "react-chartjs-2";\nexport const Chart = () => <Bar data={{}} />;\n`,
+      "apps/demo/ui/Lazy/index_.tsx": `"use client";\nexport { Inner } from "./Inner";\n`,
+    });
+
+    expect(rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.unnecessary-use-client")).toHaveLength(0);
+  });
+
+  test("flags a static component and a mostly-static component inside a client file", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Panels.tsx": [
+        `"use client";`,
+        `import { useState } from "react";`,
+        `export const StaticPanel = () => (`,
+        `  <section>`,
+        staticMarkup(5),
+        `  </section>`,
+        `);`,
+        `export const MixedPanel = () => {`,
+        `  const [open, setOpen] = useState(false);`,
+        `  return (`,
+        `    <section>`,
+        staticMarkup(12),
+        `      <span>{open ? "open" : "shut"}</span>`,
+        `    </section>`,
+        `  );`,
+        `};`,
+        "",
+      ].join("\n"),
+    });
+
+    const result = await new AkanQualityScanner().scan(root);
+    const staticWarnings = rulesOf(result, "akan.ssr.client-static-component");
+    const mixedWarnings = rulesOf(result, "akan.ssr.client-static-markup");
+
+    expect(staticWarnings).toHaveLength(1);
+    expect(staticWarnings[0]?.message).toContain("StaticPanel");
+    expect(staticWarnings[0]?.fix).toContain("server file");
+    expect(mixedWarnings).toHaveLength(1);
+    expect(mixedWarnings[0]?.message).toContain("MixedPanel");
+  });
+
+  test("flags a mount-only load but not a reactive one", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Zone.tsx": [
+        `"use client";`,
+        `import { useEffect } from "react";`,
+        `export const List = ({ tag }: { tag: string }) => {`,
+        `  useEffect(() => {`,
+        `    void st.do.initPostInPublic();`,
+        `  }, []);`,
+        `  useEffect(() => {`,
+        `    void st.do.getPostListInTag(tag);`,
+        `  }, [tag]);`,
+        `  return <div>{tag}</div>;`,
+        `};`,
+        "",
+      ].join("\n"),
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.client-mount-load");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("st.do.initPostInPublic");
+    expect(warnings[0]?.fix).toContain("init/view");
+  });
+
+  test("flags useState in a Template", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Template.tsx": `"use client";\nimport { useState } from "react";\nexport const General = () => {\n  const [draft, setDraft] = useState("");\n  return <input value={draft} onChange={(e) => setDraft(e.target.value)} />;\n};\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.template-client-state");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.fix).toContain("st.do.setFieldOnX");
+  });
+
+  test("flags a module that renders only from client files", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Zone.tsx": [
+        `"use client";`,
+        `import { useState } from "react";`,
+        `export const Card = () => {`,
+        `  const [open] = useState(false);`,
+        `  return (`,
+        `    <section>`,
+        staticMarkup(14),
+        `      <span>{open ? "open" : "shut"}</span>`,
+        `    </section>`,
+        `  );`,
+        `};`,
+        "",
+      ].join("\n"),
+      "libs/shared/lib/user/User.Zone.tsx": `"use client";\nimport { st } from "@libs/shared/client";\nexport const Self = () => <User.View.General user={st.use.self()} />;\n`,
+      "libs/shared/lib/user/User.View.tsx": `export const General = ({ name }: { name: string }) => <div>{name}</div>;\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.module-missing-server-view");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("apps/demo/lib/post");
+  });
+
+  test("measures the server render share per scope and for the workspace", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Server.tsx": `export const Server = () => (\n  <section>\n    <p>a</p>\n    <p>b</p>\n  </section>\n);\n`,
+      "libs/shared/ui/Client.tsx": `"use client";\nexport const Client = () => <button onClick={() => null}>go</button>;\n`,
+    });
+
+    const { ssrBalance } = await new AkanQualityScanner().scan(root);
+
+    expect(ssrBalance.map((entry) => entry.scope)).toEqual(["apps/demo", "libs/shared", "workspace"]);
+    expect(ssrBalance[0]).toMatchObject({ serverMass: 3, clientMass: 0, serverShare: 1 });
+    expect(ssrBalance[1]).toMatchObject({ serverMass: 0, clientMass: 1 });
+    expect(ssrBalance[2]).toMatchObject({ scope: "workspace", serverMass: 3, clientMass: 1 });
+  });
+});

package/qualityScanner.ts

@@ -4,9 +4,10 @@ import path from "node:path";
 import ignore from "ignore";
 import ts from "typescript";
 import { AbstractDoc } from "./abstractDoc";
+import { formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
 
 type QualitySeverity = "warning";
-type QualityScope = "global" | "file" | "convention" | "layout";
+type QualityScope = "global" | "file" | "convention" | "layout" | "ssr";
 
 export interface QualityWarning {
   rule: string;
@@ -23,10 +24,11 @@ export interface QualityScanResult {
   workspaceRoot: string;
   scannedFiles: number;
   warnings: QualityWarning[];
+  ssrBalance: SsrBalanceEntry[];
   suggestedRules: string[];
 }
 
-interface SourceFileInfo {
+export interface SourceFileInfo {
   file: string;
   absolutePath: string;
   content: string;
@@ -169,6 +171,18 @@ const RULE_FIXES: Record<string, string> = {
     "Move the file into a domain module folder under lib/; keep lib root limited to generated support facets.",
   "akan.layout.module-ui-file":
     "Rename the file to an allowed module UI name, or move it to ui/ if it is not a module component.",
+  "akan.ssr.unnecessary-use-client":
+    'Delete the "use client" directive so the file renders on the server. If it exists only to wrap one client child, drop the wrapper and use the child directly.',
+  "akan.ssr.client-static-component":
+    "Move the component to a server file — a <Model>.Unit.tsx / <Model>.View.tsx for a module, or a ui/ file with no directive — and reference it from the client file.",
+  "akan.ssr.client-static-markup":
+    "Keep the interactive element in the client component and hoist the static subtree into a server component, then accept it as `children` or render it through a Unit/View reference.",
+  "akan.ssr.client-mount-load":
+    "Load the data in the route with `fetch.initX(...)` / `fetch.viewX(...)` and pass the init/view object down as a prop; the client store hydrates from it and the effect goes away.",
+  "akan.ssr.module-missing-server-view":
+    "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}`.",
 };
 
 function getRuleFix(rule: string): string | undefined {
@@ -190,6 +204,7 @@ export class AkanQualityScanner {
         .filter((file) => AbstractDoc.isAbstractPath(file))
         .map((file) => this.#readTextFile(workspaceRoot, file)),
     );
+    const ssr = new SsrScanner().scan(sourceFiles);
     const warnings = [
       ...this.#scanGlobalQuality(sourceFiles),
       ...sourceFiles.flatMap((sourceFile) => this.#scanSingleFileQuality(sourceFile)),
@@ -197,6 +212,7 @@ export class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
+      ...ssr.warnings,
     ];
 
     return {
@@ -205,6 +221,7 @@ export class AkanQualityScanner {
       warnings: warnings
         .map((warning) => ({ ...warning, fix: warning.fix ?? getRuleFix(warning.rule) }))
         .sort(compareWarnings),
+      ssrBalance: ssr.balance,
       suggestedRules: SUGGESTED_RULES,
     };
   }
@@ -470,6 +487,10 @@ export function formatQualityScanResult(result: QualityScanResult) {
     "",
     ...formatQualityWarnings(result.warnings),
     "",
+    "SSR balance (component files, JSX elements rendered per side):",
+    "",
+    ...formatSsrBalance(result.ssrBalance),
+    "",
     "Suggested quality rules:",
     "",
     ...result.suggestedRules.map((rule) => `  - ${rule}`),
@@ -477,6 +498,24 @@ export function formatQualityScanResult(result: QualityScanResult) {
   return sections.join("\n");
 }
 
+export function formatSsrScanResult(result: QualityScanResult) {
+  const sections = [
+    "Akan SSR Balance Scan",
+    `workspace: ${result.workspaceRoot}`,
+    `scanned files: ${result.scannedFiles}`,
+    `ssr warnings: ${result.warnings.length}`,
+    "",
+    "Server render share (component files, JSX elements rendered per side):",
+    "",
+    ...formatSsrBalance(result.ssrBalance),
+    "",
+    "Warnings:",
+    "",
+    ...formatQualityWarnings(result.warnings),
+  ];
+  return sections.join("\n");
+}
+
 export function formatQualityWarnings(warnings: QualityWarning[]) {
   if (warnings.length === 0) return ["No warnings found."];
   return warnings.flatMap((warning) => {

package/recipeScanner.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { collectRecipeSources, findInlineRecipeDuplicates, type RecipeInfo, scanRecipes } from "./recipeScanner";
+
+const byName = (recipes: RecipeInfo[], name: string) => recipes.find((recipe) => recipe.name === name);
+
+// Mirrors pkgs/akanjs/ui/recipe/ (framework) — two recipes in one source, variant + size surfaces.
+// The scanner is per-source, so a folder of one-recipe files and a legacy multi-recipe file both parse.
+const FRAMEWORK = `
+import { recipe, tv } from "./recipeFactory";
+export const buttonRecipe = recipe(
+  tv({
+    base: "inline-flex items-center",
+    variants: {
+      variant: { primary: "bg-primary", ghost: "bg-transparent", link: "underline" },
+      size: { sm: "h-8", md: "h-10", lg: "h-12" },
+    },
+    defaultVariants: { variant: "primary", size: "md" },
+  }),
+);
+export type ButtonVariants = NonNullable<Parameters<typeof buttonRecipe>[0]>;
+export const badgeRecipe = recipe(tv({ base: "rounded-full", variants: { variant: { default: "bg-muted", info: "bg-info" } } }));
+`;
+
+// Mirrors apps/minimal/ui/Recipe/ shapes — base-only (no variants) + single-variant, with per-export JSDoc.
+const APP = `
+import { recipe, tv } from "akanjs/ui";
+/** 전체 화면 배경/전경. 페이지 루트 컨테이너. */
+export const appScreen = recipe(tv({ base: "min-h-screen bg-background text-foreground" }));
+/** 챗 버블 — 수신/발신 방향에 따라 정렬·색을 바꾼다. */
+export const chatBubbleRecipe = recipe(
+  tv({ base: "max-w-[78%] rounded-3xl", variants: { side: { incoming: "bg-muted", outgoing: "ml-auto bg-primary" } }, defaultVariants: { side: "incoming" } }),
+);
+`;
+
+// A docs page: the ONLY real code is a layout div; a recipe "definition" lives inside a template-literal code sample.
+const DOCS_TSX = `
+import { Code } from "akanjs/ui";
+export default function Page() {
+  return (
+    <div>
+      <Code.Snippet code={\`export const fakeRecipe = recipe(tv({ base: "bg-primary", variants: { tone: { a: "x" } } }));\`} />
+    </div>
+  );
+}
+`;
+
+describe("scanRecipes", () => {
+  test("detects framework recipes with full variant surface", () => {
+    const recipes = scanRecipes([{ path: "recipe.ts", content: FRAMEWORK, importFrom: "akanjs/ui" }]);
+    expect(recipes.map((r) => r.name).sort()).toEqual(["badgeRecipe", "buttonRecipe"]);
+
+    const button = byName(recipes, "buttonRecipe");
+    expect(button?.importFrom).toBe("akanjs/ui");
+    expect(button?.variants.variant).toEqual(["primary", "ghost", "link"]);
+    expect(button?.variants.size).toEqual(["sm", "md", "lg"]);
+    expect(button?.defaultVariants).toEqual({ variant: "primary", size: "md" });
+
+    const badge = byName(recipes, "badgeRecipe");
+    expect(badge?.variants.variant).toEqual(["default", "info"]);
+    expect(badge?.defaultVariants).toBeUndefined();
+  });
+
+  test("handles base-only recipes and captures the JSDoc one-liner", () => {
+    const recipes = scanRecipes([{ path: "Recipe.ts", content: APP, importFrom: "@apps/minimal/ui" }]);
+
+    const screen = byName(recipes, "appScreen");
+    expect(screen?.variants).toEqual({}); // base-only → empty variant surface
+    expect(screen?.doc).toBe("전체 화면 배경/전경. 페이지 루트 컨테이너.");
+    expect(screen?.importFrom).toBe("@apps/minimal/ui");
+
+    const bubble = byName(recipes, "chatBubbleRecipe");
+    expect(bubble?.variants.side).toEqual(["incoming", "outgoing"]);
+    expect(bubble?.doc).toBe("챗 버블 — 수신/발신 방향에 따라 정렬·색을 바꾼다.");
+  });
+
+  test("does NOT match recipe definitions inside string/template literals (docs code samples)", () => {
+    const recipes = scanRecipes([{ path: "ui-recipe.tsx", content: DOCS_TSX, importFrom: "@apps/akan/ui" }]);
+    expect(recipes).toEqual([]);
+  });
+
+  test("skips recipe() calls whose argument is not tv(...)", () => {
+    const src = `export const x = recipe(buildStyles());\nexport const y = recipe(tv({ base: "a" }));`;
+    const recipes = scanRecipes([{ path: "f.ts", content: src, importFrom: "@x" }]);
+    expect(recipes.map((r) => r.name)).toEqual(["y"]);
+  });
+
+  test("ignores non-exported recipe consts and merges multiple sources", () => {
+    const src = `const hidden = recipe(tv({ base: "a" }));\nexport const shown = recipe(tv({ base: "b" }));`;
+    const recipes = scanRecipes([
+      { path: "a.ts", content: src, importFrom: "@a" },
+      { path: "b.ts", content: `export const other = recipe(tv({ base: "c" }));`, importFrom: "@b" },
+    ]);
+    expect(recipes.map((r) => `${r.name}@${r.importFrom}`).sort()).toEqual(["other@@b", "shown@@a"]);
+  });
+});
+
+// Recipes moved from a flat `ui/Recipe.ts` to a `ui/Recipe/` folder. Three consumers (the AGENTS.md recipe
+// index, the recipeGate lint, the MCP module context) go through collectRecipeSources, and every one of them
+// degrades silently — empty list, no error — if it stops finding sources. These tests are that alarm.
+// The advisory exists to catch a look being re-authored inline. Requiring every base token only matched a
+// verbatim copy of the whole base — the one shape that never occurs in practice — so it reported nothing on
+// the near-copies it was built for, and silently, being advisory. These tests pin the ratio behaviour.
+describe("findInlineRecipeDuplicates", () => {
+  // 8 tokens → ceil(8 * 0.7) = 6 must be reproduced.
+  const EIGHT = `export const cardRecipe = recipe(tv({ base: "flex rounded-box border border-border bg-card p-4 text-card-foreground shadow-sm" }));`;
+  const THREE = `export const gridRecipe = recipe(tv({ base: "grid gap-3 xl:grid-cols-2" }));`;
+  const recipesOf = (src: string) => scanRecipes([{ path: "Recipe.ts", content: src, importFrom: "@apps/x/ui" }]);
+  const hits = (src: string, jsx: string) =>
+    findInlineRecipeDuplicates(recipesOf(src), [{ path: "Page.tsx", content: jsx }]).map((d) => d.recipe);
+
+  test("flags a verbatim re-author of the whole base", () => {
+    const jsx = `<div className="flex rounded-box border border-border bg-card p-4 text-card-foreground shadow-sm" />`;
+    expect(hits(EIGHT, jsx)).toEqual(["cardRecipe"]);
+  });
+
+  test("flags a near-copy that drops two tokens — the case the exact-match rule missed", () => {
+    const jsx = `<div className="flex rounded-box border border-border bg-card p-4" />`;
+    expect(hits(EIGHT, jsx)).toEqual(["cardRecipe"]);
+  });
+
+  test("ignores a className that merely shares a few generic utilities", () => {
+    expect(hits(EIGHT, `<div className="flex border p-4" />`)).toEqual([]);
+  });
+
+  test("still requires every token of a minimum-length fingerprint", () => {
+    expect(hits(THREE, `<div className="grid gap-3 xl:grid-cols-2" />`)).toEqual(["gridRecipe"]);
+    expect(hits(THREE, `<div className="grid gap-3" />`)).toEqual([]);
+  });
+
+  test("does not flag a className that consumes the recipe", () => {
+    expect(hits(EIGHT, `<div className={cardRecipe({}, "w-full")} />`)).toEqual([]);
+  });
+});
+
+describe("collectRecipeSources", () => {
+  const seed = async (files: Record<string, string>) => {
+    const root = await mkdtemp(path.join(tmpdir(), "akan-recipe-"));
+    for (const [rel, content] of Object.entries(files)) {
+      const abs = path.join(root, rel);
+      await Bun.write(abs, content);
+    }
+    return root;
+  };
+  const recipeSrc = (name: string) => `export const ${name} = recipe(tv({ base: "a" }));`;
+
+  test("reads every recipe file in the folder, skipping index and tests", async () => {
+    const root = await seed({
+      "ui/Recipe/index.ts": `export * from "./appCard";`,
+      "ui/Recipe/appCard.ts": recipeSrc("appCard"),
+      "ui/Recipe/appBox.ts": recipeSrc("appBox"),
+      "ui/Recipe/appBox.test.ts": recipeSrc("shouldBeSkipped"),
+      "ui/Recipe/notes.md": "ignored",
+    });
+    const sources = await collectRecipeSources(path.join(root, "ui"), "@apps/x/ui");
+    expect(sources).toHaveLength(2);
+    expect(
+      scanRecipes(sources)
+        .map((r) => r.name)
+        .sort(),
+    ).toEqual(["appBox", "appCard"]);
+  });
+
+  test("still reads a flat Recipe.ts so an unmigrated app keeps working", async () => {
+    const root = await seed({ "ui/Recipe.ts": recipeSrc("legacy") });
+    const sources = await collectRecipeSources(path.join(root, "ui"), "@apps/x/ui");
+    expect(scanRecipes(sources).map((r) => r.name)).toEqual(["legacy"]);
+  });
+
+  test("honours the framework's lowercase basename", async () => {
+    const root = await seed({ "ui/recipe/buttonRecipe.ts": recipeSrc("buttonRecipe") });
+    const sources = await collectRecipeSources(path.join(root, "ui"), "akanjs/ui", "recipe");
+    expect(scanRecipes(sources).map((r) => r.name)).toEqual(["buttonRecipe"]);
+  });
+
+  test("returns nothing when neither shape exists, without throwing", async () => {
+    const root = await mkdtemp(path.join(tmpdir(), "akan-recipe-"));
+    await writeFile(path.join(root, "placeholder"), "");
+    expect(await collectRecipeSources(path.join(root, "ui"), "@apps/x/ui")).toEqual([]);
+  });
+});

package/recipeScanner.ts

@@ -0,0 +1,233 @@
+import { readdir } from "node:fs/promises";
+import ts from "typescript";
+
+/**
+ * A single Akan UI recipe discovered by scanning source. `variants` maps each variant key to its allowed option
+ * names (e.g. `{ variant: ["primary", "ghost"], size: ["sm", "md"] }`); a base-only recipe has `variants: {}`.
+ * `importFrom` is the module a consumer imports the recipe from (e.g. `@apps/minimal/ui`).
+ */
+export interface RecipeInfo {
+  name: string;
+  importFrom: string;
+  variants: Record<string, string[]>;
+  defaultVariants?: Record<string, string>;
+  doc?: string;
+  /** The recipe's `base` class string when it is a plain string literal — the SSOT fingerprint. */
+  base?: string;
+}
+
+export interface RecipeSource {
+  path: string;
+  content: string;
+  importFrom: string;
+}
+
+/**
+ * Collects every recipe source under a `ui` folder. Recipes live one-per-file in a `Recipe/` folder
+ * (`recipe/` for the framework), so this reads the whole folder; the flat `Recipe.ts` is still read for
+ * apps that have not moved yet. Every consumer of `scanRecipes` must go through here — three call sites
+ * (AGENTS.md recipe index, `recipeGate` lint, MCP module context) hardcoded the flat path before, and each
+ * one fails silently (empty list, no error) when the file is absent.
+ */
+export const collectRecipeSources = async (
+  uiDirPath: string,
+  importFrom: string,
+  basename = "Recipe",
+): Promise<RecipeSource[]> => {
+  const read = async (filePath: string): Promise<RecipeSource | null> => {
+    const content = await Bun.file(filePath)
+      .text()
+      .catch(() => "");
+    return content ? { path: filePath, content, importFrom } : null;
+  };
+  const flat = await read(`${uiDirPath}/${basename}.ts`);
+  const dirEntries = await readdir(`${uiDirPath}/${basename}`).catch(() => [] as string[]);
+  const fromDir = await Promise.all(
+    dirEntries
+      .filter((entry) => entry.endsWith(".ts") && entry !== "index.ts" && !/\.(test|spec)\.ts$/.test(entry))
+      .sort()
+      .map((entry) => read(`${uiDirPath}/${basename}/${entry}`)),
+  );
+  return [flat, ...fromDir].filter((source): source is RecipeSource => !!source);
+};
+
+/**
+ * Statically finds every `export const <name> = recipe(tv({ ... }))` across the given sources and extracts its
+ * variant surface + leading JSDoc one-liner. Detection is by the `recipe(tv(...))` call shape (not by name suffix,
+ * since base-only recipes like `appScreen` omit the `Recipe` suffix). Being AST-based, it never matches recipe
+ * definitions that appear only inside string/template literals (e.g. code examples in docs pages).
+ */
+export const scanRecipes = (sources: RecipeSource[]): RecipeInfo[] => {
+  const recipes: RecipeInfo[] = [];
+  for (const source of sources) {
+    const sourceFile = ts.createSourceFile(
+      source.path,
+      source.content,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TSX,
+    );
+    for (const statement of sourceFile.statements) {
+      if (!ts.isVariableStatement(statement) || !isExported(statement)) continue;
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue;
+        const parsed = parseRecipeCall(declaration.initializer);
+        if (!parsed) continue;
+        recipes.push({
+          name: declaration.name.text,
+          importFrom: source.importFrom,
+          variants: parsed.variants,
+          ...(parsed.defaultVariants ? { defaultVariants: parsed.defaultVariants } : {}),
+          ...(getLeadingDoc(source.content, statement) ? { doc: getLeadingDoc(source.content, statement) } : {}),
+          ...(parsed.base ? { base: parsed.base } : {}),
+        });
+      }
+    }
+  }
+  return recipes;
+};
+
+const isExported = (statement: ts.VariableStatement): boolean =>
+  statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+
+/** Matches `recipe( tv( <ObjectLiteral> ) )` and returns the variant surface, or null for anything else. */
+const parseRecipeCall = (
+  initializer: ts.Expression,
+): { variants: Record<string, string[]>; defaultVariants?: Record<string, string>; base?: string } | null => {
+  if (!ts.isCallExpression(initializer)) return null;
+  if (!ts.isIdentifier(initializer.expression) || initializer.expression.text !== "recipe") return null;
+  const tvCall = initializer.arguments[0];
+  if (!tvCall || !ts.isCallExpression(tvCall)) return null;
+  if (!ts.isIdentifier(tvCall.expression) || tvCall.expression.text !== "tv") return null;
+  const config = tvCall.arguments[0];
+  if (!config || !ts.isObjectLiteralExpression(config)) return null;
+  return extractVariants(config);
+};
+
+const extractVariants = (config: ts.ObjectLiteralExpression) => {
+  const variants: Record<string, string[]> = {};
+  let defaultVariants: Record<string, string> | undefined;
+  let base: string | undefined;
+  for (const property of config.properties) {
+    if (!ts.isPropertyAssignment(property) || !isNamed(property.name)) continue;
+    const key = propName(property.name);
+    if (key === "base" && ts.isStringLiteral(property.initializer)) {
+      base = property.initializer.text;
+    } else if (key === "variants" && ts.isObjectLiteralExpression(property.initializer)) {
+      for (const variant of property.initializer.properties) {
+        if (!ts.isPropertyAssignment(variant) || !isNamed(variant.name)) continue;
+        if (!ts.isObjectLiteralExpression(variant.initializer)) continue;
+        variants[propName(variant.name)] = variant.initializer.properties
+          .filter((option): option is ts.PropertyAssignment => ts.isPropertyAssignment(option) && isNamed(option.name))
+          .map((option) => propName(option.name));
+      }
+    } else if (key === "defaultVariants" && ts.isObjectLiteralExpression(property.initializer)) {
+      defaultVariants = {};
+      for (const preset of property.initializer.properties) {
+        if (!ts.isPropertyAssignment(preset) || !isNamed(preset.name)) continue;
+        defaultVariants[propName(preset.name)] = ts.isStringLiteral(preset.initializer)
+          ? preset.initializer.text
+          : preset.initializer.getText();
+      }
+    }
+  }
+  return { variants, defaultVariants, base };
+};
+
+const isNamed = (name: ts.PropertyName): name is ts.Identifier | ts.StringLiteral =>
+  ts.isIdentifier(name) || ts.isStringLiteral(name);
+const propName = (name: ts.Identifier | ts.StringLiteral): string => name.text;
+
+export interface RecipeDuplicate {
+  recipe: string;
+  path: string;
+  line: number;
+  className: string;
+}
+
+/**
+ * Fraction of a recipe's base tokens an inline className must reproduce to count as a duplicate.
+ *
+ * Requiring *every* token (the original rule) only caught a verbatim copy of the whole base, which is the one
+ * form of duplication that essentially never happens: someone re-authoring a look reproduces the gist, not all
+ * eight tokens. So the check passed on exactly the near-duplicates it existed to find, and silently — it is an
+ * advisory, so nothing went red. A ratio catches those; false positives are cheap here for the same reason.
+ */
+const DUPLICATE_TOKEN_RATIO = 0.7;
+
+/** Minimum base tokens for a recipe to be worth fingerprinting at all. */
+const MIN_FINGERPRINT_TOKENS = 3;
+
+/**
+ * SSOT advisory: finds JSX `className` string values that hand-rewrite a recipe's base fingerprint instead of
+ * consuming the recipe. Only recipes whose base has 3+ distinctive tokens are checked — shorter fingerprints
+ * (`grid gap-3` …) are generic utilities and would flood the report with false positives. A className counts as
+ * a duplicate once it reproduces {@link DUPLICATE_TOKEN_RATIO} of those tokens, so a near-copy that drops or
+ * swaps one still reports. AST-scoped to real `className` attributes, so class strings inside doc-example
+ * template literals never match.
+ */
+export const findInlineRecipeDuplicates = (
+  recipes: RecipeInfo[],
+  files: { path: string; content: string }[],
+): RecipeDuplicate[] => {
+  const fingerprints = recipes
+    .map((recipe) => ({ recipe: recipe.name, tokens: (recipe.base ?? "").split(/\s+/).filter(Boolean) }))
+    .filter((fingerprint) => fingerprint.tokens.length >= MIN_FINGERPRINT_TOKENS)
+    // Ceil so the threshold never rounds below the minimum: a 3-token base still needs 3 of 3.
+    .map((fingerprint) => ({ ...fingerprint, needed: Math.ceil(fingerprint.tokens.length * DUPLICATE_TOKEN_RATIO) }));
+  if (fingerprints.length === 0) return [];
+  const duplicates: RecipeDuplicate[] = [];
+  for (const file of files) {
+    const sourceFile = ts.createSourceFile(file.path, file.content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const visit = (node: ts.Node) => {
+      if (ts.isJsxAttribute(node) && node.name.getText(sourceFile) === "className" && node.initializer) {
+        for (const value of stringValuesIn(node.initializer)) {
+          const classSet = new Set(value.split(/\s+/));
+          for (const fingerprint of fingerprints) {
+            const matched = fingerprint.tokens.filter((token) => classSet.has(token)).length;
+            if (matched >= fingerprint.needed) {
+              const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+              duplicates.push({ recipe: fingerprint.recipe, path: file.path, line: line + 1, className: value });
+            }
+          }
+        }
+      }
+      node.forEachChild(visit);
+    };
+    visit(sourceFile);
+  }
+  return duplicates;
+};
+
+const stringValuesIn = (node: ts.Node): string[] => {
+  const values: string[] = [];
+  const visit = (child: ts.Node) => {
+    if (
+      ts.isStringLiteral(child) ||
+      ts.isNoSubstitutionTemplateLiteral(child) ||
+      ts.isTemplateHead(child) ||
+      ts.isTemplateMiddle(child) ||
+      ts.isTemplateTail(child)
+    )
+      values.push(child.text);
+    child.forEachChild(visit);
+  };
+  visit(node);
+  return values;
+};
+
+/** The first non-empty line of the JSDoc/line comment immediately preceding the statement, markers stripped. */
+const getLeadingDoc = (fullText: string, node: ts.Node): string | undefined => {
+  const ranges = ts.getLeadingCommentRanges(fullText, node.getFullStart());
+  if (!ranges?.length) return undefined;
+  const { pos, end } = ranges[ranges.length - 1];
+  const line = fullText
+    .slice(pos, end)
+    .replace(/^\/\*\*?/, "")
+    .replace(/\*\/\s*$/, "")
+    .replace(/^\/\/+/gm, "")
+    .split("\n")
+    .map((row) => row.replace(/^\s*\*\s?/, "").trim())
+    .find((row) => row.length > 0);
+  return line || undefined;
+};