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

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

package/frontendBuild/styleGuard.ts

@@ -0,0 +1,322 @@
+/**
+ * styleGuard — 색 어휘 폐쇄를 강제하는 순수 정적 검사기 (의존성 0).
+ *
+ * 어휘 폐쇄(styles.css `@theme { --color-*: initial }`)로 raw 팔레트가 CSS를 미생성하게 되면
+ * 위반은 "조용한 시각 깨짐"이 된다. styleGuard 는 소스 문자열을 스캔해 그 위반을 명시적 진단으로
+ * 끌어올리고, 에이전트가 읽고 수리할 `suggestion` 을 붙인다.
+ *
+ * severity 는 규칙 고유값(판별력)만 담는다. warn/error 를 막을지 여부는 배선(호출자)이 mode 로 결정한다:
+ *   - dev  : 절대 막지 않음 (모두 경고 로그)
+ *   - build/CI/lint : severity==="error" 위반이 하나라도 있으면 실패
+ *
+ * akanjs 런타임을 import 하지 않는다 — node 표준 라이브러리만 사용.
+ */
+
+export type StyleGuardRule =
+  | "raw-palette"
+  | "arbitrary-color"
+  | "inline-color"
+  | "daisyui-legacy"
+  | "interpolated-arbitrary";
+export type StyleGuardSeverity = "error" | "warn";
+
+export interface StyleGuardViolation {
+  rule: StyleGuardRule;
+  severity: StyleGuardSeverity;
+  path: string;
+  line: number;
+  snippet: string;
+  suggestion: string;
+}
+
+export interface StyleGuardFile {
+  path: string;
+  content: string;
+}
+
+export interface NamedComponentClassMetric {
+  count: number;
+  names: string[];
+}
+
+// 색을 받는 유틸 접두사. daisyuiTokenRename.ts 의 PREFIX 와 동일 계보(방향성 border 포함).
+const PREFIX =
+  "(?:bg|text|border(?:-[tblrxy])?(?:-[se])?|ring(?:-offset)?|fill|stroke|shadow|from|to|via|divide|outline|decoration|placeholder|caret|accent)";
+
+// Tailwind 기본 팔레트 이름. `neutral` 은 시맨틱 토큰이기도 하므로 숫자 suffix 를 요구해 구분한다
+// (`bg-neutral` 은 허용, `bg-neutral-500` 은 raw 팔레트).
+const PALETTE =
+  "(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)";
+
+// 클래스 경계: 앞은 공백/따옴표/백틱/여는 괄호/콜론(변형)/!(important), 뒤는 종결 문자(+ 슬래시=opacity, !).
+const LEAD = "(^|[\\s\"'`{(\\[:!])";
+const TAIL = "(?=[\\s\"'`})\\]:/!,]|$)";
+
+const RAW_PALETTE_RE = new RegExp(`${LEAD}((?:${PREFIX})-)${PALETTE}-\\d{2,3}${TAIL}`, "g");
+
+// 임의값 대괄호 안의 색 리터럴. `[--var]` 같은 변수 참조는 매치되지 않는다(의도).
+const ARBITRARY_COLOR_RE = /\[(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|hwb|color)\([^\]]*\))\]/g;
+
+// 런타임 값으로 조립한 임의값(`min-h-[${n}px]`, `bg-[${color}]`). Tailwind 는 소스 **텍스트**에서
+// 임의값을 추출하므로 CSS 가 아예 생성되지 않는다 — 클래스는 DOM 에 있고 prop 은 연결된 듯 보이지만
+// 아무것도 적용되지 않는 무증상 실패다. 같은 모양의 리터럴이 코드베이스 어딘가에 있으면 기본값만
+// 우연히 동작하고 override 만 조용히 죽어 더 찾기 어려워진다.
+const INTERPOLATED_ARBITRARY_RE = new RegExp(`${LEAD}[a-z][a-z0-9-]*-\\[[^\\]\`]*\\$\\{`, "g");
+
+// style 객체 / <style> 블록. 색 리터럴이 이 안에 있으면 클래스 스캐너를 우회한 것.
+const STYLE_OBJECT_RE = /style=\{\{([\s\S]*?)\}\}/g;
+const STYLE_TAG_RE = /<style[^>]*>([\s\S]*?)<\/style>/g;
+// var(...) 는 허용이므로 매치 대상에서 자연히 빠진다(hex/색함수 리터럴만 탐지).
+const INLINE_COLOR_LITERAL_RE = /#[0-9a-fA-F]{3,8}\b|(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|hwb)\(/g;
+
+// daisyUI 잔재. 판별력 높은 compound(변형 suffix 포함) 패턴만 error 로 잡아 오탐을 억제한다.
+const DAISYUI_LEGACY_RE = new RegExp(
+  `${LEAD}(?:` +
+    // 버튼/배지/알림/입력 등 variant compound
+    "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)|" +
+    // 구조 클래스(daisyUI 전용 조각)
+    "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)" +
+    `)${TAIL}`,
+  "g",
+);
+
+const ALL_RULES: StyleGuardRule[] = [
+  "raw-palette",
+  "arbitrary-color",
+  "inline-color",
+  "daisyui-legacy",
+  "interpolated-arbitrary",
+];
+
+/**
+ * 위반 억제 지시어(escape hatch). 정당한 팔레트 요청(에디터 신택스 하이라이트, 데이터-viz, 의도적 브랜드
+ * 데모)은 거절이 아니라 "명시적 옵트아웃"으로 라우팅한다 — 천장은 제약하지 않되 흔적을 남긴다.
+ *   styleguard-disable <rule?>            → 파일 전체
+ *   styleguard-disable-next-line <rule?>  → 바로 다음 줄
+ * rule 을 생략하면 모든 규칙을 억제한다.
+ */
+interface Directives {
+  file: Set<StyleGuardRule> | "all" | null;
+  nextLine: Map<number, Set<StyleGuardRule> | "all">;
+}
+
+export class StyleGuard {
+  run(files: StyleGuardFile[]): StyleGuardViolation[] {
+    const out: StyleGuardViolation[] = [];
+    for (const file of files) {
+      const directives = this.#parseDirectives(file.content);
+      // 주석 내용을 공백으로 치환(offset·줄번호 보존). 주석에 남은 예전 클래스명이 오탐되지 않게.
+      // directives 는 원본에서 파싱한다 — 지시어 자체가 주석이기 때문.
+      const scan = this.#stripComments(file.content);
+      const local: StyleGuardViolation[] = [];
+      this.#scanClassLiterals(file, scan, local);
+      this.#scanInlineColors(file, scan, local);
+      for (const v of local) if (!this.#isSuppressed(v, directives)) out.push(v);
+    }
+    return out;
+  }
+
+  /** 라인/블록 주석을 같은 길이의 공백으로 치환. 문자열/템플릿 리터럴 안의 `//`·`/*` 는 보존. */
+  #stripComments(src: string): string {
+    const out = src.split("");
+    const blank = (i: number) => {
+      if (src[i] !== "\n") out[i] = " ";
+    };
+    let state: "code" | "line" | "block" | "squote" | "dquote" | "template" = "code";
+    let i = 0;
+    while (i < src.length) {
+      const c = src[i];
+      const d = src[i + 1];
+      if (state === "code") {
+        if (c === "/" && d === "/") {
+          blank(i);
+          blank(i + 1);
+          state = "line";
+          i += 2;
+        } else if (c === "/" && d === "*") {
+          blank(i);
+          blank(i + 1);
+          state = "block";
+          i += 2;
+        } else {
+          if (c === "'") state = "squote";
+          else if (c === '"') state = "dquote";
+          else if (c === "`") state = "template";
+          i++;
+        }
+      } else if (state === "line") {
+        if (c === "\n") state = "code";
+        else blank(i);
+        i++;
+      } else if (state === "block") {
+        if (c === "*" && d === "/") {
+          blank(i);
+          blank(i + 1);
+          state = "code";
+          i += 2;
+        } else {
+          blank(i);
+          i++;
+        }
+      } else {
+        // 문자열/템플릿: 내용 보존, escape 건너뛰고 종결 문자에서 code 로 복귀.
+        const close = state === "squote" ? "'" : state === "dquote" ? '"' : "`";
+        if (c === "\\") i += 2;
+        else {
+          if (c === close) state = "code";
+          i++;
+        }
+      }
+    }
+    return out.join("");
+  }
+
+  #parseDirectives(content: string): Directives {
+    const directives: Directives = { file: null, nextLine: new Map() };
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const nextLineMatch = line.match(/styleguard-disable-next-line\b(.*)$/);
+      if (nextLineMatch) {
+        directives.nextLine.set(i + 2, this.#extractRules(nextLineMatch[1]));
+        continue;
+      }
+      const fileMatch = line.match(/styleguard-disable\b(.*)$/);
+      if (fileMatch) directives.file = this.#mergeFileScope(directives.file, this.#extractRules(fileMatch[1]));
+    }
+    return directives;
+  }
+
+  #extractRules(tail: string): Set<StyleGuardRule> | "all" {
+    const found = ALL_RULES.filter((rule) => tail.includes(rule));
+    return found.length === 0 ? "all" : new Set(found);
+  }
+
+  #mergeFileScope(
+    prev: Set<StyleGuardRule> | "all" | null,
+    next: Set<StyleGuardRule> | "all",
+  ): Set<StyleGuardRule> | "all" {
+    if (prev === "all" || next === "all") return "all";
+    return new Set([...(prev ?? []), ...next]);
+  }
+
+  #isSuppressed(v: StyleGuardViolation, directives: Directives): boolean {
+    if (directives.file === "all" || directives.file?.has(v.rule)) return true;
+    const nextLine = directives.nextLine.get(v.line);
+    return nextLine === "all" || (nextLine?.has(v.rule) ?? false);
+  }
+
+  #scanClassLiterals(file: StyleGuardFile, scan: string, out: StyleGuardViolation[]): void {
+    for (const m of scan.matchAll(RAW_PALETTE_RE)) {
+      out.push(
+        this.#violation(file, m.index ?? 0, {
+          rule: "raw-palette",
+          severity: "error",
+          suggestion:
+            "시맨틱 토큰으로 교체하세요 — 예: text-gray-500→text-muted-foreground, bg-red-500→bg-destructive, bg-blue-500→bg-info. 브랜드 색은 page/styles.css 토큰에서 조정합니다.",
+        }),
+      );
+    }
+    for (const m of scan.matchAll(ARBITRARY_COLOR_RE)) {
+      out.push(
+        this.#violation(file, m.index ?? 0, {
+          rule: "arbitrary-color",
+          severity: "error",
+          suggestion:
+            "임의 색 리터럴 대신 토큰을 쓰세요 — bg-[#3b82f6]→bg-info, text-[rgb(...)]→시맨틱 토큰. 꼭 필요하면 스코프 토큰(.campaign-x { --primary: … })을 정의하세요.",
+        }),
+      );
+    }
+    for (const m of scan.matchAll(DAISYUI_LEGACY_RE)) {
+      out.push(
+        this.#violation(file, m.index ?? 0, {
+          rule: "daisyui-legacy",
+          severity: "error",
+          suggestion:
+            "daisyUI 클래스는 제거됐습니다. akanjs/ui 프리미티브(Button/Badge 등)나 buttonRecipe()/badgeRecipe() + 시맨틱 토큰으로 교체하세요.",
+        }),
+      );
+    }
+    for (const m of scan.matchAll(INTERPOLATED_ARBITRARY_RE)) {
+      out.push(
+        this.#violation(file, m.index ?? 0, {
+          rule: "interpolated-arbitrary",
+          severity: "error",
+          suggestion:
+            "런타임 값으로 임의값 클래스를 조립하면 CSS 가 생성되지 않습니다(스캐너는 소스 텍스트를 읽습니다). 크기/위치는 style prop 으로 넘기세요 — style={{ minHeight }}. 값이 enum 이면 리터럴 클래스 맵으로 두세요.",
+        }),
+      );
+    }
+  }
+
+  #scanInlineColors(file: StyleGuardFile, scan: string, out: StyleGuardViolation[]): void {
+    const push = (index: number) =>
+      out.push(
+        this.#violation(file, index, {
+          rule: "inline-color",
+          severity: "error",
+          suggestion:
+            "인라인 색 리터럴 대신 CSS 변수/토큰을 참조하세요 — style={{ color: 'var(--primary)' }} 또는 시맨틱 클래스(text-primary). 하드코딩 hex/rgb 는 테마 전환을 깨뜨립니다.",
+        }),
+      );
+    for (const region of [STYLE_OBJECT_RE, STYLE_TAG_RE]) {
+      for (const m of scan.matchAll(region)) {
+        const inner = m[1] ?? "";
+        const innerStart = (m.index ?? 0) + m[0].indexOf(inner);
+        for (const lit of inner.matchAll(INLINE_COLOR_LITERAL_RE)) {
+          push(innerStart + (lit.index ?? 0));
+        }
+      }
+    }
+  }
+
+  #violation(
+    file: StyleGuardFile,
+    index: number,
+    base: Pick<StyleGuardViolation, "rule" | "severity" | "suggestion">,
+  ): StyleGuardViolation {
+    const before = file.content.slice(0, index);
+    const line = before.length === 0 ? 1 : before.split("\n").length;
+    const lineStart = before.lastIndexOf("\n") + 1;
+    const lineEnd = file.content.indexOf("\n", index);
+    const snippet = file.content.slice(lineStart, lineEnd === -1 ? undefined : lineEnd).trim();
+    return { ...base, path: file.path, line, snippet };
+  }
+
+  /**
+   * `@layer components` 안에서 선언된 명명 클래스 개수 — 그림자 디자인 시스템 증식의 warn 지표(차단 X).
+   */
+  static countNamedComponentClasses(css: string): NamedComponentClassMetric {
+    const names = new Set<string>();
+    const layerRe = /@layer\s+components\s*\{/g;
+    for (const layer of css.matchAll(layerRe)) {
+      const bodyStart = (layer.index ?? 0) + layer[0].length;
+      const body = StyleGuard.#extractBalanced(css, bodyStart);
+      for (const sel of body.matchAll(/(^|[\s}])\.(-?[a-zA-Z_][\w-]*)/g)) names.add(sel[2]);
+    }
+    return { count: names.size, names: [...names].sort() };
+  }
+
+  static #extractBalanced(css: string, start: number): string {
+    let depth = 1;
+    for (let i = start; i < css.length; i++) {
+      const ch = css[i];
+      if (ch === "{") depth++;
+      else if (ch === "}") {
+        depth--;
+        if (depth === 0) return css.slice(start, i);
+      }
+    }
+    return css.slice(start);
+  }
+}

package/frontendBuild/themeValidator.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { ThemeValidator } from "./themeValidator";
+
+const validator = new ThemeValidator();
+
+describe("ThemeValidator.parseHex", () => {
+  test("parses shorthand, full, and alpha hex", () => {
+    expect(ThemeValidator.parseHex("#fff")).toEqual([255, 255, 255]);
+    expect(ThemeValidator.parseHex("#0a0a0a")).toEqual([10, 10, 10]);
+    expect(ThemeValidator.parseHex("#ffffff80")).toEqual([255, 255, 255]);
+  });
+
+  test("returns null for non-hex values", () => {
+    expect(ThemeValidator.parseHex("var(--primary)")).toBeNull();
+    expect(ThemeValidator.parseHex("rgb(0,0,0)")).toBeNull();
+  });
+});
+
+describe("ThemeValidator.contrastRatio", () => {
+  test("black/white is 21:1", () => {
+    expect(ThemeValidator.contrastRatio([0, 0, 0], [255, 255, 255])).toBeCloseTo(21, 0);
+  });
+});
+
+describe("ThemeValidator.parseThemeTokens", () => {
+  test("distributes grouped selectors and normalizes quotes", () => {
+    const css = `:root, [data-theme=dark] { --background: #0a0a0a; --foreground: #fafafa; }`;
+    const tokens = ThemeValidator.parseThemeTokens(css);
+    expect(tokens[":root"].background).toBe("#0a0a0a");
+    expect(tokens['[data-theme="dark"]'].foreground).toBe("#fafafa");
+  });
+
+  test("ignores at-rule blocks like @theme", () => {
+    const css = `@theme inline { --color-primary: var(--primary); } :root { --background: #fff; }`;
+    const tokens = ThemeValidator.parseThemeTokens(css);
+    expect(Object.keys(tokens)).toEqual([":root"]);
+  });
+});
+
+describe("ThemeValidator.validate", () => {
+  test("flags a low-contrast pair", () => {
+    const css = `:root { --background: #ffffff; --foreground: #eeeeee; }`;
+    const violations = validator.validate(css);
+    expect(violations).toHaveLength(1);
+    expect(violations[0].pair).toBe("background / foreground");
+    expect(violations[0].ratio).toBeLessThan(4.5);
+  });
+
+  test("passes when status pairs meet the relaxed 3:1 threshold", () => {
+    // info #3b82f6 on white ≈ 3.68 — below 4.5 but above the 3:1 UI threshold.
+    const css = `:root { --info: #3b82f6; --info-foreground: #ffffff; }`;
+    expect(validator.validate(css)).toHaveLength(0);
+  });
+
+  test("skips pairs whose token is a var() reference", () => {
+    const css = `:root { --primary: var(--brand); --primary-foreground: #000000; }`;
+    expect(validator.validate(css)).toHaveLength(0);
+  });
+});
+
+describe("shipped framework palette", () => {
+  test("pkgs/akanjs/ui/styles.css passes WCAG contrast for all scopes", () => {
+    const stylesPath = path.resolve(import.meta.dir, "../../../akanjs/ui/styles.css");
+    const css = readFileSync(stylesPath, "utf8");
+    const violations = validator.validate(css);
+    expect(violations).toEqual([]);
+  });
+});