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

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

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/integration/devResourceProbe.ts

@@ -285,9 +285,14 @@ export class DevResourceProbe {
       "rscWorkerRecycleCount",
       "httpFullSsrCount",
     ];
-    const rssMb = (Number(child.rssBytes ?? 0) / 1024 / 1024).toFixed(0);
+    // `rssBytes` is the replica's own; the RSC worker is a separate process reporting under
+    // `rscWorker*`. These used to be the same field, because the worker's report shadowed the
+    // replica's — so this line printed the worker's RSS labelled as the child's.
+    const toMb = (bytes: unknown) => (Number(bytes ?? 0) / 1024 / 1024).toFixed(0);
     const parts = keys.map((key) => `${key}=${child[key] ?? "?"}`);
-    console.info(`[metrics ${label}] rsc rss=${rssMb}MB ${parts.join(" ")}`);
+    console.info(
+      `[metrics ${label}] replicaRss=${toMb(child.rssBytes)}MB rscWorkerRss=${toMb(child.rscWorkerRssBytes)}MB ${parts.join(" ")}`,
+    );
   }
 
   async #waitForLog(pattern: RegExp, timeoutMs: number): Promise<boolean> {