@akanjs/devkit 2.4.2-rc.2 → 3.0.0-alpha.0

package/frontendBuild/themeValidator.ts

@@ -0,0 +1,150 @@
+/**
+ * themeValidator — 시맨틱 토큰 페어의 WCAG 콘트라스트 자동 검사 (의존성 0).
+ *
+ * 토큰 구조(`--x` ↔ `--x-foreground`)라서 가능해진 검사. AI 가 생성한 팔레트가 "안 읽히는 사이트"가
+ * 되는 것을 원천 차단한다. akanjs 런타임을 import 하지 않는다 — 순수 함수만.
+ *
+ * 임계값(WCAG 2.1):
+ *   - 본문/주요 표면 페어(background·primary·secondary·accent·neutral·card·popover): 4.5:1 (AA normal text)
+ *   - 상태/보조 페어(info·success·warning·destructive·open·muted): 3:1 (UI 컴포넌트 / 큰 텍스트 / 보조 표면)
+ * 현행 styles.css 기본 팔레트(light/dark)는 이 임계값을 모두 통과한다.
+ */
+
+export interface ThemeContrastViolation {
+  scope: string;
+  pair: string;
+  background: string;
+  foreground: string;
+  ratio: number;
+  threshold: number;
+  suggestion: string;
+}
+
+interface PairDef {
+  base: string;
+  fg: string;
+  threshold: number;
+}
+
+const PAIRS: PairDef[] = [
+  { base: "background", fg: "foreground", threshold: 4.5 },
+  { base: "primary", fg: "primary-foreground", threshold: 4.5 },
+  { base: "secondary", fg: "secondary-foreground", threshold: 4.5 },
+  { base: "accent", fg: "accent-foreground", threshold: 4.5 },
+  { base: "neutral", fg: "neutral-foreground", threshold: 4.5 },
+  { base: "card", fg: "card-foreground", threshold: 4.5 },
+  { base: "popover", fg: "popover-foreground", threshold: 4.5 },
+  { base: "muted", fg: "muted-foreground", threshold: 3 },
+  { base: "info", fg: "info-foreground", threshold: 3 },
+  { base: "success", fg: "success-foreground", threshold: 3 },
+  { base: "warning", fg: "warning-foreground", threshold: 3 },
+  { base: "destructive", fg: "destructive-foreground", threshold: 3 },
+  { base: "open", fg: "open-foreground", threshold: 3 },
+];
+
+// 검사 대상 스코프. 그 외 셀렉터(.campaign-x 스코프 토큰 등)는 페어 검사에서 제외.
+const THEME_SCOPES = new Set([":root", '[data-theme="dark"]', '[data-theme="light"]']);
+
+export type ThemeTokensByScope = Record<string, Record<string, string>>;
+
+export class ThemeValidator {
+  /** CSS 문자열에서 토큰을 추출해 알려진 테마 스코프 전체를 검사한다. */
+  validate(css: string): ThemeContrastViolation[] {
+    const tokensByScope = ThemeValidator.parseThemeTokens(css);
+    const violations: ThemeContrastViolation[] = [];
+    for (const [scope, tokens] of Object.entries(tokensByScope)) {
+      if (!THEME_SCOPES.has(scope)) continue;
+      violations.push(...this.validateScope(tokens, scope));
+    }
+    return violations;
+  }
+
+  validateScope(tokens: Record<string, string>, scope: string): ThemeContrastViolation[] {
+    const violations: ThemeContrastViolation[] = [];
+    for (const { base, fg, threshold } of PAIRS) {
+      const bg = tokens[base];
+      const front = tokens[fg];
+      if (!bg || !front) continue;
+      const bgRgb = ThemeValidator.parseHex(bg);
+      const fgRgb = ThemeValidator.parseHex(front);
+      if (!bgRgb || !fgRgb) continue; // var()/비-hex 값은 검사 불가 → 건너뜀
+      const ratio = ThemeValidator.contrastRatio(bgRgb, fgRgb);
+      if (ratio >= threshold) continue;
+      violations.push({
+        scope,
+        pair: `${base} / ${fg}`,
+        background: bg,
+        foreground: front,
+        ratio: Math.round(ratio * 100) / 100,
+        threshold,
+        suggestion: `${scope}의 --${base}(${bg})와 --${fg}(${front}) 대비가 ${ratio.toFixed(2)}:1 로 최소 ${threshold}:1 미만입니다. 한쪽을 더 밝게/어둡게 조정해 대비를 확보하세요.`,
+      });
+    }
+    return violations;
+  }
+
+  /**
+   * `:root` / `[data-theme="…"]` 블록에서 `--token: value` 를 파싱한다. 그룹 셀렉터
+   * (`:root, [data-theme="dark"] { … }`)는 각 셀렉터에 동일 토큰을 분배. 동일 스코프 재등장 시 나중 값이 이긴다
+   * (프레임워크-먼저 / 앱-나중 순서로 넘기면 앱 override 가 반영됨).
+   */
+  static parseThemeTokens(css: string): ThemeTokensByScope {
+    const result: ThemeTokensByScope = {};
+    // 중첩 없는 단순 규칙 블록만 매칭(@theme/@keyframes 등 at-rule 은 셀렉터에 @ 포함이라 제외).
+    const blockRe = /(?:^|})\s*([^{}@]+?)\s*\{([^{}]*)\}/g;
+    for (const block of css.matchAll(blockRe)) {
+      const selectors = block[1].split(",").map((s) => s.trim());
+      const relevant = selectors.filter((s) => THEME_SCOPES.has(ThemeValidator.#normalizeScope(s)));
+      if (relevant.length === 0) continue;
+      const decls: Record<string, string> = {};
+      for (const decl of block[2].matchAll(/--([\w-]+)\s*:\s*([^;]+?)\s*(?:;|$)/g)) {
+        decls[decl[1]] = decl[2].trim();
+      }
+      for (const selector of relevant) {
+        const scope = ThemeValidator.#normalizeScope(selector);
+        result[scope] = { ...(result[scope] ?? {}), ...decls };
+      }
+    }
+    return result;
+  }
+
+  static #normalizeScope(selector: string): string {
+    // 따옴표 정규화: [data-theme=dark] / [data-theme='dark'] → [data-theme="dark"]
+    return selector.replace(/\[data-theme=['"]?([\w-]+)['"]?\]/g, '[data-theme="$1"]').trim();
+  }
+
+  /** #rgb / #rgba / #rrggbb / #rrggbbaa → [r,g,b] (alpha 무시). 비-hex 는 null. */
+  static parseHex(value: string): [number, number, number] | null {
+    const v = value.trim();
+    if (!v.startsWith("#")) return null;
+    const hex = v.slice(1);
+    let full: string;
+    if (hex.length === 3 || hex.length === 4)
+      full = hex
+        .slice(0, 3)
+        .split("")
+        .map((c) => c + c)
+        .join("");
+    else if (hex.length === 6 || hex.length === 8) full = hex.slice(0, 6);
+    else return null;
+    if (!/^[0-9a-fA-F]{6}$/.test(full)) return null;
+    const n = Number.parseInt(full, 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+  }
+
+  static #relativeLuminance([r, g, b]: [number, number, number]): number {
+    const channel = (c: number) => {
+      const s = c / 255;
+      return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+  }
+
+  static contrastRatio(a: [number, number, number], b: [number, number, number]): number {
+    const la = ThemeValidator.#relativeLuminance(a);
+    const lb = ThemeValidator.#relativeLuminance(b);
+    const hi = Math.max(la, lb);
+    const lo = Math.min(la, lb);
+    return (hi + 0.05) / (lo + 0.05);
+  }
+}

package/index.ts

@@ -42,6 +42,7 @@ export type * from "./mobile";
 export type * from "./packageExportsMap";
 export type * from "./prompter";
 export type * from "./qualityScanner";
+export type * from "./recipeScanner";
 export type * from "./scanInfo";
 export type * from "./selectModel";
 export type * from "./spinner";

package/lint/no-arbitrary-color.grit

@@ -0,0 +1,19 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Arbitrary-value color literals (`bg-[#3b82f6]`, `text-[rgb(0,0,0)]`) bypass the semantic
+// token layer, so they ignore data-theme switching and theme contrast validation. Grit port
+// of styleGuard's `arbitrary-color` rule (frontendBuild/styleGuard.ts) — keep in sync.
+// Variable references (`bg-[--brand]`, `text-[var(--fg)]`) do not match, by design.
+or {
+  JsxString() as $s,
+  JsStringLiteralExpression() as $s,
+  JsTemplateChunkElement() as $s
+} where {
+  $s <: r"[\s\S]*\[(?:#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|hwb|color)\([^\]]*\))\][\s\S]*",
+  register_diagnostic(
+    span = $s,
+    message = "Arbitrary color value bypasses the semantic token layer (no theme switching, no contrast validation). Use a semantic token, or reference a variable (bg-[--brand]) declared in styles.css.",
+    severity = "error"
+  )
+}

package/lint/no-daisyui-legacy-class.grit

@@ -0,0 +1,20 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// daisyUI was removed from the UI system; its component classes (`btn-primary`, `card-body`,
+// `mockup-code`, ...) no longer have any CSS behind them and silently render unstyled. Grit
+// port of styleGuard's `daisyui-legacy` rule (frontendBuild/styleGuard.ts) — keep in sync.
+// Only high-signal compound names are matched; bare ambiguous words that collide with
+// Tailwind or app classes (`card`, `input`, `badge`, `btn`) are deliberately not flagged.
+or {
+  JsxString() as $s,
+  JsStringLiteralExpression() as $s,
+  JsTemplateChunkElement() as $s
+} where {
+  $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:btn-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|link|outline|square|circle|wide|block|xs|sm|md|lg)|badge-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|outline)|alert-(?:info|success|warning|error)|input-(?:bordered|primary|secondary|accent|ghost|error)|select-(?:bordered|primary|ghost)|textarea-(?:bordered|primary|ghost)|checkbox-(?:primary|secondary|accent)|toggle-(?:primary|secondary|accent)|loading-(?:spinner|dots|ring|ball|bars|infinity)|card-(?:body|title|actions)|modal-(?:box|action|backdrop)|collapse-(?:title|content|arrow|plus)|dropdown-(?:content|end|start|hover)|stat-(?:title|value|desc)|tabs-(?:boxed|lifted|bordered)|tab-active|menu-(?:title|dropdown)|steps-(?:horizontal|vertical)|join-item|mockup-(?:code|phone|browser|window)|drawer-(?:side|content|toggle))(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+  register_diagnostic(
+    span = $s,
+    message = "daisyUI legacy class - daisyUI was removed, so this renders unstyled. Use akanjs/ui components and recipes (Button, buttonRecipe, badgeRecipe, ...) with semantic tokens instead.",
+    severity = "error"
+  )
+}

package/lint/no-inline-color.grit

@@ -0,0 +1,19 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Color literals inside `style={{ ... }}` bypass the class scanner, the semantic token layer,
+// and theme switching entirely. Grit port of styleGuard's `inline-color` rule
+// (frontendBuild/styleGuard.ts) — keep in sync. `var(--token)` references do not match.
+//
+// Known delta vs the TS guard: color literals inside a `<style>` tag's template body are not
+// matched here (template chunks are not scoped by this pattern); the build-gate styleGuard
+// still covers that case.
+JsStringLiteralExpression() as $s where {
+  $s <: within `style={$obj}`,
+  $s <: r"[\s\S]*(?:#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|hwb)\()[\s\S]*",
+  register_diagnostic(
+    span = $s,
+    message = "Inline color literal in a style object bypasses semantic tokens and theme switching. Use a token class, or style={{ color: 'var(--primary)' }} when a runtime value is unavoidable.",
+    severity = "error"
+  )
+}

package/lint/no-interpolated-arbitrary-class.grit

@@ -0,0 +1,24 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Tailwind extracts arbitrary values from raw source *text*, so a bracket whose contents are built at
+// runtime (`min-h-[${minHeight}px]`, `bg-[${color}]`) compiles to NO css. The class name exists in the DOM
+// and the prop looks wired, but nothing applies — the failure is completely silent, and it gets worse when a
+// literal of the same shape happens to exist elsewhere in the codebase: the default value works by accident
+// while every override dies quietly (that is exactly how `Empty`'s minHeight went unnoticed).
+//
+// Grit port of styleGuard's `interpolated-arbitrary` rule (frontendBuild/styleGuard.ts) — keep the two
+// regexes in sync. Matching template *chunks* is what makes this detectable: the chunk before `${` still
+// carries the unterminated `-[`.
+//
+// The fix is a style prop for the runtime value (`style={{ minHeight }}`) — dimensions are not colors, so
+// no-inline-color does not apply — or a fixed set of literal classes when the value comes from an enum.
+// Escape hatch: `// biome-ignore lint/plugin: <reason>`.
+JsTemplateChunkElement() as $chunk where {
+  $chunk <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])[a-z][a-z0-9-]*-\[[^\]]*$",
+  register_diagnostic(
+    span = $chunk,
+    message = "Interpolated Tailwind arbitrary value (e.g. `min-h-[${n}px]`) - the scanner reads source text, so this compiles to no CSS and is silently ignored. Use a style prop for the runtime value, or a fixed set of literal classes.",
+    severity = "error"
+  )
+}

package/lint/no-raw-palette-class.grit

@@ -0,0 +1,25 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Vocabulary closure (`@theme { --color-*: initial }` in akanjs/ui/styles.css) strips the raw
+// Tailwind palette, so classes like `bg-blue-500` generate NO css and silently render as
+// currentColor/transparent. This rule surfaces that silent breakage at lint time. It is the
+// grit port of styleGuard's `raw-palette` rule (frontendBuild/styleGuard.ts) — keep the two
+// regexes in sync. Matching string/template nodes (not raw text) skips comments for free.
+//
+// Bare `bg-neutral` is a semantic token and allowed; the numeric suffix (`bg-neutral-500`)
+// is what marks a raw palette class. black/white stay in the vocabulary for overlays.
+// Escape hatch for legitimate fixed colors: `// biome-ignore lint/plugin: <reason>`
+// (file-wide: `// biome-ignore-all lint/plugin: <reason>`).
+or {
+  JsxString() as $s,
+  JsStringLiteralExpression() as $s,
+  JsTemplateChunkElement() as $s
+} where {
+  $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:bg|text|border(?:-[tblrxy])?(?:-[se])?|ring(?:-offset)?|fill|stroke|shadow|from|to|via|divide|outline|decoration|placeholder|caret|accent)-(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d{2,3}(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+  register_diagnostic(
+    span = $s,
+    message = "Raw Tailwind palette class (e.g. bg-blue-500) - vocabulary closure strips these, so they render as no CSS. Use a semantic token (bg-primary, text-foreground/70, ...) or add a biome-ignore with a reason.",
+    severity = "error"
+  )
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.4.2-rc.2",
+  "version": "3.0.0-alpha.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -44,10 +44,9 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.2-rc.2",
+    "akanjs": "3.0.0-alpha.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
-    "daisyui": "5.5.23",
     "dayjs": "^1.11.20",
     "fontaine": "^0.8.0",
     "fonteditor-core": "^2.6.3",

package/qualityScanner.test.ts

@@ -0,0 +1,46 @@
+import { afterEach, describe, expect, test } from "bun:test";
+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";
+
+const tempRoots: string[] = [];
+
+const makeWorkspace = async (files: Record<string, string>) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-quality-scanner-"));
+  tempRoots.push(root);
+  for (const [filePath, content] of Object.entries({ ".gitignore": "node_modules\n", ...files })) {
+    const absolutePath = path.join(root, filePath);
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, content);
+  }
+  return root;
+};
+
+const abstractOf = (lineNum: number) =>
+  ["# post Abstract", ...Array.from({ length: lineNum - 1 }, (_, idx) => `- rule ${idx}`)].join("\n");
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("AkanQualityScanner abstract rule", () => {
+  test("warns on an abstract over the line limit and points at akan compact", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/post.abstract.md": abstractOf(AbstractDoc.maxLines + 1),
+      "apps/demo/lib/post/post.constant.ts": "export class Post {}\n",
+      "libs/shared/lib/user/user.abstract.md": abstractOf(AbstractDoc.maxLines),
+      "libs/shared/lib/user/user.constant.ts": "export class User {}\n",
+    });
+
+    const result = await new AkanQualityScanner().scan(root);
+    const warnings = result.warnings.filter((warning) => warning.rule === "akan.file.abstract-max-lines");
+
+    expect(result.scannedFiles).toBe(4);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("apps/demo/lib/post/post.abstract.md");
+    expect(warnings[0]?.message).toContain(`${AbstractDoc.maxLines + 1} lines`);
+    expect(warnings[0]?.fix).toContain("akan compact");
+  });
+});

package/qualityScanner.ts

@@ -3,6 +3,7 @@ import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import ignore from "ignore";
 import ts from "typescript";
+import { AbstractDoc } from "./abstractDoc";
 
 type QualitySeverity = "warning";
 type QualityScope = "global" | "file" | "convention" | "layout";
@@ -32,6 +33,11 @@ interface SourceFileInfo {
   sourceFile: ts.SourceFile;
 }
 
+interface TextFileInfo {
+  file: string;
+  content: string;
+}
+
 interface ExportedFunctionLike {
   name: string;
   kind: "class" | "function" | "function-variable";
@@ -142,6 +148,8 @@ const RULE_FIXES: Record<string, string> = {
   "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.",
+  "akan.file.abstract-max-lines":
+    "Run `akan compact <app-or-lib>` to rewrite the abstract with the AI editor, keeping only the invariants and workflows the source files cannot show.",
   "akan.file.placeholder-export":
     "Remove the placeholder export; generated indexes should only re-export real modules.",
   "akan.file.dictionary-stale-text": "Replace the scaffold text with real localized copy for this dictionary entry.",
@@ -172,18 +180,28 @@ function getRuleFix(rule: string): string | undefined {
 export class AkanQualityScanner {
   async scan(workspaceRoot: string): Promise<QualityScanResult> {
     const targetFiles = await this.#collectTargetFiles(workspaceRoot);
-    const sourceFiles = await Promise.all(targetFiles.map((file) => this.#readSourceFile(workspaceRoot, file)));
+    const sourceFiles = await Promise.all(
+      targetFiles
+        .filter((file) => !AbstractDoc.isAbstractPath(file))
+        .map((file) => this.#readSourceFile(workspaceRoot, file)),
+    );
+    const abstractFiles = await Promise.all(
+      targetFiles
+        .filter((file) => AbstractDoc.isAbstractPath(file))
+        .map((file) => this.#readTextFile(workspaceRoot, file)),
+    );
     const warnings = [
       ...this.#scanGlobalQuality(sourceFiles),
       ...sourceFiles.flatMap((sourceFile) => this.#scanSingleFileQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanComponentQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
+      ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
     ];
 
     return {
       workspaceRoot,
-      scannedFiles: sourceFiles.length,
+      scannedFiles: sourceFiles.length + abstractFiles.length,
       warnings: warnings
         .map((warning) => ({ ...warning, fix: warning.fix ?? getRuleFix(warning.rule) }))
         .sort(compareWarnings),
@@ -226,6 +244,8 @@ export class AkanQualityScanner {
       }
       if ((relativePath.endsWith(".ts") || relativePath.endsWith(".tsx")) && !relativePath.endsWith(".d.ts")) {
         files.push(relativePath);
+      } else if (AbstractDoc.isAbstractPath(relativePath)) {
+        files.push(relativePath);
       }
     }
   }
@@ -241,6 +261,10 @@ export class AkanQualityScanner {
     };
   }
 
+  async #readTextFile(workspaceRoot: string, file: string): Promise<TextFileInfo> {
+    return { file, content: await readFile(path.join(workspaceRoot, file), "utf8") };
+  }
+
   #scanGlobalQuality(sourceFiles: SourceFileInfo[]): QualityWarning[] {
     const exportedFunctionLikes = sourceFiles.flatMap((sourceFile) => getExportedFunctionLikes(sourceFile));
     const warnings: QualityWarning[] = [];
@@ -391,6 +415,20 @@ export class AkanQualityScanner {
     return warnings;
   }
 
+  #scanAbstractQuality({ file, content }: TextFileInfo): QualityWarning[] {
+    const lineCount = AbstractDoc.lineCountOf(content);
+    if (lineCount <= AbstractDoc.maxLines) return [];
+    return [
+      {
+        rule: "akan.file.abstract-max-lines",
+        scope: "file",
+        severity: "warning",
+        file,
+        message: `Abstract has ${lineCount} lines. Keep abstracts under ${AbstractDoc.maxLines} lines and compact them periodically.`,
+      },
+    ];
+  }
+
   #scanLayoutQuality(sourceFile: SourceFileInfo): QualityWarning[] {
     const segments = sourceFile.file.split("/");
     const warnings: QualityWarning[] = [];

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