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

package/agentsIndex.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import {
+  AGENT_BLOCK_END,
+  AGENT_BLOCK_START,
+  collectScopeRecipeSources,
+  extractAgentBlock,
+  renderRecipeEntries,
+  renderScopeAgentBlock,
+  renderScopeAgentsMd,
+  upsertAgentBlock,
+} from "./agentsIndex";
+import type { RecipeInfo } from "./recipeScanner";
+
+const button: RecipeInfo = {
+  name: "buttonRecipe",
+  importFrom: "akanjs/ui",
+  variants: { variant: ["primary", "ghost"], size: ["sm", "md"] },
+  defaultVariants: { variant: "primary", size: "md" },
+  doc: "버튼 look",
+};
+const appCard: RecipeInfo = { name: "appCard", importFrom: "@apps/minimal/ui", variants: { tone: ["muted", "glass"] } };
+
+describe("renderRecipeEntries", () => {
+  test("groups by import path and marks defaults", () => {
+    const entries = renderRecipeEntries([button, appCard]);
+    expect(entries).toContain("Import from `akanjs/ui`:");
+    expect(entries).toContain("Import from `@apps/minimal/ui`:");
+    expect(entries).toContain("`buttonRecipe`(variant: primary*|ghost · size: sm|md*) — 버튼 look");
+    expect(entries).toContain("`appCard`(tone: muted|glass)");
+  });
+});
+
+describe("renderScopeAgentBlock", () => {
+  test("carries the sync/lint contract and the scope's entries", () => {
+    const block = renderScopeAgentBlock({ type: "app", name: "minimal" }, [appCard]);
+    expect(block).toContain("## Recipes In Scope");
+    expect(block).toContain("akan sync minimal");
+    expect(block).toContain("akan lint minimal");
+    expect(block).toContain("`appCard`");
+  });
+  test("empty scope points to authoring instead of listing nothing", () => {
+    const block = renderScopeAgentBlock({ type: "lib", name: "util" }, []);
+    expect(block).toContain("No scope recipes yet");
+    expect(block).toContain("libs/util/ui/Recipe/<name>.ts");
+  });
+});
+
+describe("upsertAgentBlock / extractAgentBlock", () => {
+  test("round-trips: fresh file → replace block → extract equals block", () => {
+    const fresh = renderScopeAgentsMd({ type: "app", name: "minimal" }, "OLD");
+    expect(extractAgentBlock(fresh)).toBe("OLD");
+    const updated = upsertAgentBlock(
+      fresh.replace("markers freely.", "markers freely.\n\nMy hand-written note."),
+      "NEW",
+    );
+    expect(extractAgentBlock(updated)).toBe("NEW");
+    expect(updated).toContain("My hand-written note.");
+    expect(updated).not.toContain("OLD");
+  });
+  test("appends markers to a file that has none", () => {
+    const updated = upsertAgentBlock("# hand-written\n\ncontent\n", "BLOCK");
+    expect(updated).toContain("# hand-written");
+    expect(updated.indexOf(AGENT_BLOCK_START)).toBeLessThan(updated.indexOf("BLOCK"));
+    expect(updated.trimEnd().endsWith(AGENT_BLOCK_END)).toBe(true);
+  });
+});
+
+describe("collectScopeRecipeSources", () => {
+  test("collects own + dependency lib recipes, never the framework's", async () => {
+    const root = await mkdtemp(path.join(tmpdir(), "agents-index-"));
+    const write = async (rel: string, content: string) => {
+      await mkdir(path.dirname(path.join(root, rel)), { recursive: true });
+      await writeFile(path.join(root, rel), content);
+    };
+    await write("apps/minimal/ui/Recipe/appCard.ts", `export const appCard = recipe(tv({ base: "x" }));`);
+    await write("libs/shared/ui/Recipe/panel.ts", `export const panelRecipe = recipe(tv({ base: "y" }));`);
+    await write("pkgs/akanjs/ui/recipe/buttonRecipe.ts", `export const buttonRecipe = recipe(tv({ base: "z" }));`);
+    const sources = await collectScopeRecipeSources(root, { type: "app", name: "minimal" }, ["shared"]);
+    expect(sources.map((source) => source.importFrom).sort()).toEqual(["@apps/minimal/ui", "@libs/shared/ui"]);
+  });
+});

package/agentsIndex.ts

@@ -0,0 +1,146 @@
+import type { RecipeInfo, RecipeSource } from "./recipeScanner";
+
+// recipeScanner 는 상단에서 typescript(~65MB)를 끌어온다. 이 모듈은 executors(CLI 엔트리 그래프)에
+// 상주하므로 스캔 스택은 첫 사용 시점에 지연 로드한다 — 정적 import 로 되돌리면 entryModuleGraph 테스트가 깨진다.
+let recipeScannerLoad: Promise<typeof import("./recipeScanner")> | null = null;
+const loadRecipeScanner = () => (recipeScannerLoad ??= import("./recipeScanner"));
+
+/**
+ * agentsIndex — 스코프별 에이전트 색인의 단일 렌더러.
+ *
+ * 색인은 소유 경계로 쪼갠다: 루트 AGENTS.md 는 프레임워크(akanjs/ui) 레시피만 싣고, 각 앱/lib 은
+ * 자기 스코프에서 import 가능한 레시피(own + 의존 lib)를 자기 AGENTS.md 에 싣는다. 항상 로드되는
+ * 컨텍스트가 앱 수에 비례해 커지는 것과, import 불가능한 이웃 앱 레시피가 환상을 유발하는 것을 막는다.
+ *
+ * 신선도는 두 지점이 보장한다: `SysExecutor.scan(write)` 가 재생성하고(akan sync/build/start 가 전부
+ * 지나가는 길목), `akan lint` 가 스캔 결과와 커밋된 블록을 비교해 stale 이면 실패시킨다.
+ */
+
+export const AGENT_BLOCK_START = "<!-- akan:agent:start -->";
+export const AGENT_BLOCK_END = "<!-- akan:agent:end -->";
+
+export interface AgentsIndexScope {
+  type: "app" | "lib";
+  name: string;
+}
+
+/** Replace the content between the akan:agent markers, preserving everything else; append when absent. */
+export const upsertAgentBlock = (existing: string, block: string): string => {
+  const managed = `${AGENT_BLOCK_START}\n${block}\n${AGENT_BLOCK_END}`;
+  const startIndex = existing.indexOf(AGENT_BLOCK_START);
+  const endIndex = existing.indexOf(AGENT_BLOCK_END);
+  if (startIndex >= 0 && endIndex > startIndex) {
+    return `${existing.slice(0, startIndex)}${managed}${existing.slice(endIndex + AGENT_BLOCK_END.length)}`;
+  }
+  return `${existing.replace(/\s*$/, "")}\n\n${managed}\n`;
+};
+
+/** The content between the akan:agent markers, or null when the file carries no managed block. */
+export const extractAgentBlock = (content: string): string | null => {
+  const startIndex = content.indexOf(AGENT_BLOCK_START);
+  const endIndex = content.indexOf(AGENT_BLOCK_END);
+  if (startIndex < 0 || endIndex <= startIndex) return null;
+  return content.slice(startIndex + AGENT_BLOCK_START.length, endIndex).trim();
+};
+
+// Variant signature — the full consumption contract, so an agent never has to open the recipe
+// file (and pull its css bodies into context) just to call one. `*` = default, `key?` = boolean flag.
+const signatureOf = (recipe: RecipeInfo): string => {
+  const entries = Object.entries(recipe.variants);
+  if (entries.length === 0) return "";
+  const parts = entries.map(([key, values]) => {
+    if (values.length === 1 && values[0] === "true") return `${key}?`;
+    const def = recipe.defaultVariants?.[key];
+    return `${key}: ${values.map((value) => (value === def ? `${value}*` : value)).join("|")}`;
+  });
+  return `(${parts.join(" · ")})`;
+};
+
+/** Recipes grouped by import path as markdown list blocks — the shared body of every recipe index. */
+export const renderRecipeEntries = (recipes: RecipeInfo[]): string => {
+  const groups = new Map<string, RecipeInfo[]>();
+  for (const recipe of recipes) groups.set(recipe.importFrom, [...(groups.get(recipe.importFrom) ?? []), recipe]);
+  return [...groups.entries()]
+    .map(([importFrom, list]) => {
+      const items = list
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((recipe) => `- \`${recipe.name}\`${signatureOf(recipe)}${recipe.doc ? ` — ${recipe.doc}` : ""}`)
+        .join("\n");
+      return `Import from \`${importFrom}\`:\n${items}`;
+    })
+    .join("\n\n");
+};
+
+/**
+ * Every recipe source importable from the scope: its own `ui/Recipe/` plus each dependency lib's.
+ * Framework recipes are excluded on purpose — they live in the root AGENTS.md, valid for every scope.
+ */
+export const collectScopeRecipeSources = async (
+  workspaceRoot: string,
+  scope: AgentsIndexScope,
+  libDeps: string[],
+): Promise<RecipeSource[]> => {
+  const { collectRecipeSources } = await loadRecipeScanner();
+  const sources: RecipeSource[] = [
+    ...(await collectRecipeSources(
+      `${workspaceRoot}/${scope.type}s/${scope.name}/ui`,
+      `@${scope.type}s/${scope.name}/ui`,
+    )),
+  ];
+  for (const lib of [...new Set(libDeps)].sort()) {
+    if (scope.type === "lib" && lib === scope.name) continue;
+    sources.push(...(await collectRecipeSources(`${workspaceRoot}/libs/${lib}/ui`, `@libs/${lib}/ui`)));
+  }
+  return sources;
+};
+
+/** Collect + scan in one call, so consumers need no value import of the scanner stack. */
+export const scanScopeRecipes = async (
+  workspaceRoot: string,
+  scope: AgentsIndexScope,
+  libDeps: string[],
+): Promise<RecipeInfo[]> => {
+  const { scanRecipes } = await loadRecipeScanner();
+  return scanRecipes(await collectScopeRecipeSources(workspaceRoot, scope, libDeps));
+};
+
+/** The managed block of a scope AGENTS.md — deterministic, so lint can compare it against a re-scan. */
+export const renderScopeAgentBlock = (scope: AgentsIndexScope, recipes: RecipeInfo[]): string => {
+  const scopePath = `${scope.type}s/${scope.name}`;
+  const intro = `## Recipes In Scope
+
+UI recipes importable from \`${scopePath}\` code, **in addition to** the framework recipes indexed in the root
+\`AGENTS.md\` \`## Recipes\`. Same contract: import by exact name, then \`<name>(variants?, className?)\` — the second
+arg merges internally and takes an array too, so never wrap it in \`cn()\`. \`*\` marks the default, \`key?\` is a
+boolean flag. Do not guess recipe names or import paths; this index is regenerated by \`akan sync ${scope.name}\`
+and verified by \`akan lint ${scope.name}\`.`;
+  if (recipes.length === 0) {
+    return `${intro}
+
+No scope recipes yet. Before inlining a repeated surface (card, box, tile, …), reuse a framework recipe from the
+root \`AGENTS.md\` or author one as \`${scopePath}/ui/Recipe/<name>.ts\` (one recipe per file, re-exported from that
+folder's \`index.ts\`) — see the \`recipeRule\` guideline.`;
+  }
+  return `${intro}
+
+${renderRecipeEntries(recipes)}`;
+};
+
+/** A fresh scope AGENTS.md: a short hand-editable header around the managed block. */
+export const renderScopeAgentsMd = (scope: AgentsIndexScope, block: string): string => `# ${scope.name} — Agent Guide
+
+Scoped guide for coding agents working in \`${scope.type}s/${scope.name}\`. Workspace-wide conventions live in the
+root \`AGENTS.md\`; this file carries what is importable from this ${scope.type === "app" ? "app" : "library"}. The
+section between the \`akan:agent\` markers is regenerated by \`akan sync ${scope.name}\`; edit anything outside the
+markers freely.
+
+${AGENT_BLOCK_START}
+${block}
+${AGENT_BLOCK_END}
+`;
+
+/** Claude Code reads nested CLAUDE.md files as it works under a directory; keep it a thin pointer. */
+export const renderScopeClaudeMd = (scope: AgentsIndexScope): string => `# ${scope.name} — Claude Code Guide
+
+@AGENTS.md
+`;

package/akanContext.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { capitalize } from "akanjs/common";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
+import { collectRecipeSources, findInlineRecipeDuplicates, scanRecipes } from "./recipeScanner";
 import type { PackageJson } from "./types";
 import {
   type GeneratedSyncState,
@@ -313,6 +314,9 @@ const constantFieldNames = (content: string) =>
   [...content.matchAll(/\b([A-Za-z_$][\w$]*)\s*:\s*field\(/g)].map((match) => match[1]).filter(Boolean);
 
 const appRootAllowFiles = new Set([
+  // 스코프 에이전트 가이드 — scan(write) 이 유지 (agentsIndex.ts); scanInfo.ts 의 appRootAllowedFiles 와 동기
+  "AGENTS.md",
+  "CLAUDE.md",
   "akan.app.json",
   "akan.config.ts",
   "capacitor.config.ts",
@@ -752,6 +756,124 @@ export class AkanContextAnalyzer {
       }
     }
 
+    // Recipe SSOT advisory (항상 warning — 차단하지 않음): recipe 지문이 인라인 className 으로 재작성된
+    // 곳의 추이를 보이게 한다. 유입이 실제로 재발하면 그때 lint 승격을 검토한다 — 증거 기반 에스컬레이션.
+    for (const sys of [...context.apps, ...context.libs]) {
+      const sources = await collectRecipeSources(path.join(workspace.workspaceRoot, sys.path, "ui"), "ui");
+      if (sources.length === 0) continue;
+      const recipes = scanRecipes(sources);
+      const files: { path: string; content: string }[] = [];
+      const glob = new Bun.Glob("**/*.tsx");
+      for await (const abs of glob.scan({ cwd: path.join(workspace.workspaceRoot, sys.path), absolute: true })) {
+        if (/[\\/](node_modules|\.akan|dist)[\\/]|[\\/]v1[\\/]/.test(abs) || /\.(test|spec)\.tsx$/.test(abs)) continue;
+        files.push({
+          path: abs,
+          content: await Bun.file(abs)
+            .text()
+            .catch(() => ""),
+        });
+      }
+      const duplicates = findInlineRecipeDuplicates(recipes, files);
+      if (duplicates.length === 0) continue;
+      const preview = duplicates
+        .slice(0, 3)
+        .map((duplicate) => `${path.relative(workspace.workspaceRoot, duplicate.path)}:${duplicate.line}`)
+        .join(", ");
+      diagnostics.push({
+        severity: "warning",
+        code: "recipe-inline-duplicate",
+        path: path.join(sys.path, "ui/Recipe"),
+        message: `${sys.name}: ${duplicates.length} inline className(s) re-author a recipe fingerprint (${preview}${duplicates.length > 3 ? ", …" : ""}) — consume the recipe instead.`,
+      });
+    }
+
+    // Recipe index freshness. The recipe indexes are generated and read as authoritative — a recipe missing
+    // from its index gets re-invented inline, and a name lingering in it gets imported and fails. The index is
+    // split by ownership: the root AGENTS.md `## Recipes` lists framework recipes only, and every app/lib lists
+    // what it may additionally import in its own AGENTS.md `## Recipes In Scope`. Doctor never writes, so this
+    // is the check that catches a *committed* stale index (lint/sync self-heal the working tree instead).
+    const scanNames = async (uiDirPath: string, basename?: string) =>
+      new Set(scanRecipes(await collectRecipeSources(uiDirPath, "ui", basename)).map((info) => info.name));
+    const declaredByImport = new Map<string, Set<string>>();
+    declaredByImport.set("akanjs/ui", await scanNames(path.join(workspace.workspaceRoot, "pkgs/akanjs/ui"), "recipe"));
+    for (const sys of [...context.apps, ...context.libs])
+      declaredByImport.set(`@${sys.path}/ui`, await scanNames(path.join(workspace.workspaceRoot, sys.path, "ui")));
+    // Section slice anchors the heading to a full line — the same string appears back-ticked in prose.
+    const sectionOf = (content: string, heading: string) => {
+      const match = new RegExp(`^${heading}$`, "m").exec(content);
+      if (!match) return "";
+      const section = content.slice(match.index);
+      const sectionEnd = section.indexOf("\n## ", 1);
+      return sectionEnd === -1 ? section : section.slice(0, sectionEnd);
+    };
+    // `Import from \`<path>\`:` groups with their `- \`name\`` items, so each name checks against its owner.
+    const listedByImport = (body: string) => {
+      const groups = new Map<string, Set<string>>();
+      let current: Set<string> | null = null;
+      for (const line of body.split("\n")) {
+        const group = /^Import from `([^`]+)`:/.exec(line);
+        if (group) {
+          current = groups.get(group[1]) ?? new Set();
+          groups.set(group[1], current);
+          continue;
+        }
+        const item = /^- `([A-Za-z0-9_$]+)`/.exec(line);
+        if (item && current) current.add(item[1]);
+        else if (!item) current = null;
+      }
+      return groups;
+    };
+    const pushIndexDiagnostic = (indexPath: string, missing: string[], stale: string[], repairCommand: string) => {
+      if (missing.length === 0 && stale.length === 0) return;
+      const action = repairAction(
+        "generated",
+        repairCommand,
+        "Regenerate the recipe index from the scanned recipes.",
+        true,
+      );
+      const parts = [
+        missing.length > 0 ? `${missing.length} declared but unlisted (${missing.slice(0, 5).join(", ")})` : "",
+        stale.length > 0 ? `${stale.length} listed but gone (${stale.slice(0, 5).join(", ")})` : "",
+      ].filter(Boolean);
+      diagnostics.push({
+        severity: "error",
+        code: "recipe-index-stale",
+        path: indexPath,
+        message: `${indexPath} recipe index is out of date — ${parts.join("; ")}. Agents read this list as authoritative.`,
+        repairActions: [action],
+      });
+      repairActions.push(action);
+    };
+    const frameworkDeclared = declaredByImport.get("akanjs/ui") ?? new Set<string>();
+    if (frameworkDeclared.size > 0) {
+      const agentsMd = await Bun.file(path.join(workspace.workspaceRoot, "AGENTS.md"))
+        .text()
+        .catch(() => "");
+      const listed = listedByImport(sectionOf(agentsMd, "## Recipes")).get("akanjs/ui") ?? new Set<string>();
+      pushIndexDiagnostic(
+        "AGENTS.md",
+        [...frameworkDeclared].filter((name) => !listed.has(name)).sort(),
+        [...listed].filter((name) => !frameworkDeclared.has(name)).sort(),
+        "akan agent install agents-md",
+      );
+    }
+    for (const sys of [...context.apps, ...context.libs]) {
+      const own = declaredByImport.get(`@${sys.path}/ui`) ?? new Set<string>();
+      const scopeMd = await Bun.file(path.join(workspace.workspaceRoot, sys.path, "AGENTS.md"))
+        .text()
+        .catch(() => "");
+      const groups = listedByImport(sectionOf(scopeMd, "## Recipes In Scope"));
+      const ownListed = groups.get(`@${sys.path}/ui`) ?? new Set<string>();
+      const missing = [...own].filter((name) => !ownListed.has(name)).sort();
+      // Every listed name — the scope's own and its dependency libs' — must still exist at its owner.
+      const stale = [...groups.entries()]
+        .flatMap(([importFrom, names]) =>
+          [...names].filter((name) => !(declaredByImport.get(importFrom) ?? new Set()).has(name)),
+        )
+        .sort();
+      pushIndexDiagnostic(`${sys.path}/AGENTS.md`, missing, stale, `akan sync ${sys.name}`);
+    }
+
     const scopedDiagnostics = diagnostics.map((diagnostic) => ({
       ...diagnostic,
       scope: workflowPaths.length

package/executors.ts

@@ -31,6 +31,13 @@ import {
 } from "akanjs/common";
 import { $ } from "bun";
 import chalk from "chalk";
+import {
+  renderScopeAgentBlock,
+  renderScopeAgentsMd,
+  renderScopeClaudeMd,
+  scanScopeRecipes,
+  upsertAgentBlock,
+} from "./agentsIndex";
 import { AkanAppConfig, AkanLibConfig, decreaseBuildNum, increaseBuildNum } from "./akanConfig";
 import { FileSys } from "./fileSys";
 import { getDirname } from "./getDirname";
@@ -1080,10 +1087,29 @@ export class SysExecutor extends Executor {
         await this.#updateDependencies(scanInfo);
         await Promise.all(libInfos.flatMap((libInfo) => libInfo.exec.#getScanTemplateTasks(libInfo)));
       }
+      await this.syncAgentsIndex(scanInfo);
     }
     this.#scanInfo = scanInfo;
     return scanInfo;
   }
+  /**
+   * 스코프 에이전트 색인(apps|libs/<name>/AGENTS.md) 재생성 — own + 의존 lib 레시피만 싣는다(프레임워크
+   * 레시피는 루트 AGENTS.md 소관). scan(write) 경로에 물려 있어 sync/build/start 어디를 지나도 갱신되고,
+   * `akan lint` 가 같은 렌더 결과와 비교해 신선도를 강제한다. 마커 밖 내용은 사용자 소유라 보존한다.
+   */
+  async syncAgentsIndex(scanInfo?: AppInfo | LibInfo) {
+    const info = scanInfo ?? (await this.scan({ write: false }));
+    const scope = { type: this.type, name: this.name };
+    const recipes = await scanScopeRecipes(this.workspace.workspaceRoot, scope, info.getScanResult().libDeps);
+    const block = renderScopeAgentBlock(scope, recipes);
+    const existing = (await this.exists("AGENTS.md")) ? await this.readFile("AGENTS.md") : null;
+    await this.writeFile(
+      "AGENTS.md",
+      existing?.trim() ? upsertAgentBlock(existing, block) : renderScopeAgentsMd(scope, block),
+    );
+    // CLAUDE.md 는 얇은 포인터라 최초 1회만 깔아준다 — 사용자가 지우거나 고친 것을 되살리지 않는다.
+    if (!(await this.exists("CLAUDE.md"))) await this.writeFile("CLAUDE.md", renderScopeClaudeMd(scope));
+  }
   async #updateDependencies(scanInfo: AppInfo | LibInfo) {
     const rootPackageJson = await this.workspace.getPackageJson();
     const libPackageJson = await this.getPackageJson();

package/frontendBuild/frontendBuild.test.ts

@@ -113,7 +113,9 @@ describe("PagesBundleBuilder", () => {
     await write(entry, ['import "./styles.css";', "export const marker = 1;", ""].join("\n"));
     await write(
       css,
-      ['@plugin "daisyui" {', "  themes: false;", "}", "@theme {", "  --color-primary: red;", "}", ""].join("\n"),
+      ['@plugin "tailwind-scrollbar" {', "  themes: false;", "}", "@theme {", "  --color-primary: red;", "}", ""].join(
+        "\n",
+      ),
     );
 
     const result = await Bun.build({

package/frontendBuild/index.ts

@@ -18,5 +18,8 @@ export * from "./routeClientBuilder";
 export * from "./routesManifestArtifactSerializer";
 export * from "./sourceMtimeIndex";
 export * from "./ssrBaseArtifactBuilder";
+export * from "./styleContract";
+export * from "./styleGuard";
+export * from "./themeValidator";
 export * from "./vendorSpecifiers";
 export * from "./watchRootResolver";

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -184,6 +184,8 @@ export class SsrBaseArtifactBuilder {
   }> {
     const cssCompiler = new CssCompiler(this.#app);
     const cssByBasePath = await cssCompiler.getCssByBasePath();
+    // 스타일 계약(어휘 폐쇄 + WCAG)은 빌드가 아니라 lint 가 강제한다: 어휘 폐쇄는 biome grit 플러그인
+    // (devkit/lint/no-raw-palette-class.grit 외 3종), 콘트라스트는 `akan lint` 의 themeValidator.
     const optimizedFonts = await new FontOptimizer(this.#app, this.#command).optimize();
     const cssAssets = Object.fromEntries(
       await Promise.all(

package/frontendBuild/styleContract.ts

@@ -0,0 +1,29 @@
+/**
+ * styleGuard + themeValidator 결과를 배선(build/dev/lint)이 공유하는 포맷으로 정리한다.
+ * severity 사다리: style 위반은 severity==="error" 인 것만, theme 위반은 전부 차단(build/CI) 대상.
+ * dev 는 이 결과를 경고로만 출력한다.
+ */
+import type { StyleGuardViolation } from "./styleGuard";
+import type { ThemeContrastViolation } from "./themeValidator";
+
+export interface StyleContractViolations {
+  style: StyleGuardViolation[];
+  theme: ThemeContrastViolation[];
+}
+
+export const countBlocking = (v: StyleContractViolations): number =>
+  v.style.filter((s) => s.severity === "error").length + v.theme.length;
+
+export const formatStyleContract = (v: StyleContractViolations): string => {
+  const lines: string[] = [];
+  for (const s of v.style) {
+    lines.push(`  [${s.severity}] ${s.rule}  ${s.path}:${s.line}`);
+    lines.push(`      ${s.snippet}`);
+    lines.push(`      → ${s.suggestion}`);
+  }
+  for (const t of v.theme) {
+    lines.push(`  [error] contrast  ${t.scope}  ${t.pair} = ${t.ratio}:1 (min ${t.threshold}:1)`);
+    lines.push(`      → ${t.suggestion}`);
+  }
+  return lines.join("\n");
+};

package/frontendBuild/styleGuard.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, test } from "bun:test";
+import { StyleGuard, type StyleGuardRule } from "./styleGuard";
+
+const guard = new StyleGuard();
+const scan = (content: string, path = "Demo.tsx") => guard.run([{ path, content }]);
+const rules = (content: string): StyleGuardRule[] => scan(content).map((v) => v.rule);
+
+describe("StyleGuard raw-palette", () => {
+  test("flags raw Tailwind palette utilities", () => {
+    expect(rules('<div className="bg-blue-500 text-gray-700" />')).toEqual(["raw-palette", "raw-palette"]);
+  });
+
+  test("flags palette with variant prefix and opacity", () => {
+    expect(rules('<div className="hover:bg-red-500/50" />')).toContain("raw-palette");
+  });
+
+  test("flags numeric neutral but allows bare semantic neutral", () => {
+    expect(rules('<div className="bg-neutral-500" />')).toEqual(["raw-palette"]);
+    expect(scan('<div className="bg-neutral text-neutral-foreground" />')).toHaveLength(0);
+  });
+
+  test("does not flag semantic tokens or black/white", () => {
+    expect(scan('<div className="bg-primary text-muted-foreground border-border" />')).toHaveLength(0);
+    expect(scan('<div className="bg-black text-white bg-white/30 bg-black/50" />')).toHaveLength(0);
+  });
+
+  test("does not flag non-color numeric utilities", () => {
+    expect(scan('<div className="gap-4 mt-2 grid-cols-3 w-500" />')).toHaveLength(0);
+  });
+});
+
+describe("StyleGuard arbitrary-color", () => {
+  test("flags hex and color-function arbitrary values", () => {
+    expect(rules('<div className="bg-[#3b82f6]" />')).toEqual(["arbitrary-color"]);
+    expect(rules('<div className="text-[rgb(0,0,0)]" />')).toEqual(["arbitrary-color"]);
+  });
+
+  test("allows arbitrary CSS variable references", () => {
+    expect(scan('<div className="bg-[--brand] text-[var(--fg)]" />')).toHaveLength(0);
+  });
+});
+
+describe("StyleGuard inline-color", () => {
+  test("flags hardcoded color in style object", () => {
+    expect(rules("<div style={{ color: '#fff', background: 'rgb(0,0,0)' }} />")).toEqual([
+      "inline-color",
+      "inline-color",
+    ]);
+  });
+
+  test("flags color literal inside <style> tag", () => {
+    expect(rules("<style>{`.x { color: #abcdef; }`}</style>")).toEqual(["inline-color"]);
+  });
+
+  test("allows var() references in style object", () => {
+    expect(scan("<div style={{ color: 'var(--primary)', width: '100%' }} />")).toHaveLength(0);
+  });
+});
+
+describe("StyleGuard daisyui-legacy", () => {
+  test("flags high-signal daisyUI compound classes", () => {
+    expect(rules('<button className="btn-primary" />')).toEqual(["daisyui-legacy"]);
+    expect(rules('<span className="badge-success" />')).toEqual(["daisyui-legacy"]);
+    expect(rules('<div className="modal-box card-body" />')).toEqual(["daisyui-legacy", "daisyui-legacy"]);
+  });
+
+  test("does not flag bare ambiguous names that collide with Tailwind", () => {
+    expect(scan('<div className="card input badge btn" />')).toHaveLength(0);
+  });
+});
+
+// The fixtures below must contain a literal `${`. Writing it inside a plain string trips biome's
+// noTemplateCurlyInString, so the placeholder is assembled from `D` — that keeps the rule on for real code
+// instead of scattering suppressions through the fixtures.
+const D = "$";
+const INTERPOLATED = {
+  size: `<div className={\`min-h-[${D}{minHeight}px] flex\`} />`,
+  color: `<div className={\`bg-[${D}{color}] w-full\`} />`,
+  brokenBracket: `<div className={\`min-h-[ w-full${D}{minHeight}px] flex\`} />`,
+  outsideBrackets: `<div className={\`flex gap-2 ${D}{isOpen ? "opacity-50" : ""}\`} />`,
+  styleProp: `<div style={{ minHeight }} className={\`flex ${D}{extra}\`} />`,
+};
+
+describe("StyleGuard interpolated-arbitrary", () => {
+  test("flags an arbitrary value assembled from a runtime expression", () => {
+    expect(rules(INTERPOLATED.size)).toEqual(["interpolated-arbitrary"]);
+    expect(rules(INTERPOLATED.color)).toEqual(["interpolated-arbitrary"]);
+  });
+
+  test("flags the broken-bracket typo that swallows the next class", () => {
+    expect(rules(INTERPOLATED.brokenBracket)).toEqual(["interpolated-arbitrary"]);
+  });
+
+  test("allows a literal arbitrary value, and interpolation outside brackets", () => {
+    expect(scan('<div className="min-h-[300px] flex" />')).toHaveLength(0);
+    expect(scan(INTERPOLATED.outsideBrackets)).toHaveLength(0);
+    expect(scan(INTERPOLATED.styleProp)).toHaveLength(0);
+  });
+});
+
+describe("StyleGuard violation shape", () => {
+  test("reports 1-based line and trimmed snippet with a suggestion", () => {
+    const content = ['<div className="ok" />', '  <div className="bg-blue-500" />'].join("\n");
+    const [v] = scan(content);
+    expect(v.line).toBe(2);
+    expect(v.snippet).toBe('<div className="bg-blue-500" />');
+    expect(v.severity).toBe("error");
+    expect(v.suggestion.length).toBeGreaterThan(0);
+  });
+});
+
+describe("StyleGuard comment handling", () => {
+  test("does not flag class names inside line or block comments", () => {
+    expect(scan('// iconClassName="btn-primary bg-blue-500"')).toHaveLength(0);
+    expect(scan("/** legacy: toggle-accent / bg-red-500 */")).toHaveLength(0);
+    expect(scan("{/* <div className='bg-blue-500' /> */}")).toHaveLength(0);
+  });
+
+  test("still flags real code on a line that also contains a string with //", () => {
+    expect(rules('<a href="https://x.io" className="bg-blue-500" />')).toEqual(["raw-palette"]);
+  });
+});
+
+describe("StyleGuard escape hatch", () => {
+  test("styleguard-disable-next-line suppresses the following line only", () => {
+    const content = [
+      "// styleguard-disable-next-line raw-palette",
+      '<div className="bg-blue-500" />',
+      '<div className="bg-red-500" />',
+    ].join("\n");
+    const found = scan(content);
+    expect(found).toHaveLength(1);
+    expect(found[0].line).toBe(3);
+  });
+
+  test("file-level styleguard-disable suppresses the named rule everywhere", () => {
+    const content = ["// styleguard-disable raw-palette", '<div className="bg-blue-500 bg-[#fff]" />'].join("\n");
+    // raw-palette suppressed, arbitrary-color still reported.
+    expect(rules(content)).toEqual(["arbitrary-color"]);
+  });
+
+  test("bare styleguard-disable suppresses all rules in the file", () => {
+    const content = ["/* styleguard-disable */", '<div className="bg-blue-500 btn-primary bg-[#fff]" />'].join("\n");
+    expect(scan(content)).toHaveLength(0);
+  });
+});
+
+describe("StyleGuard.countNamedComponentClasses", () => {
+  test("counts named classes declared inside @layer components", () => {
+    const css = `
+      @layer components {
+        .foo { color: var(--primary); }
+        .bar-baz { padding: 1rem; }
+      }
+      .outside { color: red; }
+    `;
+    const metric = StyleGuard.countNamedComponentClasses(css);
+    expect(metric.count).toBe(2);
+    expect(metric.names).toEqual(["bar-baz", "foo"]);
+  });
+
+  test("returns zero when no component layer exists", () => {
+    expect(StyleGuard.countNamedComponentClasses(".a { color: red; }").count).toBe(0);
+  });
+});