@ncds/ui-admin-mcp 1.0.0-alpha.2

package/bin/utils/bemValidator.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkCdnInclusion = exports.buildFixedHtml = exports.collectBemErrors = exports.buildRootClassMap = exports.getClassList = void 0;
+// ── 상수 ─────────────────────────────────────────────────────────────────
+const MAX_SIMILAR_SUGGESTIONS = 3;
+// ── 순수 헬퍼 ────────────────────────────────────────────────────────────
+/** 엘리먼트에서 class 목록을 파싱 */
+const getClassList = (el) => el.getAttribute('class')?.split(/\s+/) ?? [];
+exports.getClassList = getClassList;
+/** root class → component name 매핑 빌드 — server.ts에서 1회 호출 */
+const buildRootClassMap = (componentMap) => {
+    const rootClassMap = new Map();
+    for (const [name, data] of componentMap) {
+        for (const cls of data.bemClasses) {
+            if (!cls.includes('--') && !cls.includes('__'))
+                rootClassMap.set(cls, name);
+        }
+    }
+    return rootClassMap;
+};
+exports.buildRootClassMap = buildRootClassMap;
+/** ncua- 클래스에서 root class를 결정 (modifier/element 제외, 가장 짧은 것) */
+const findRootClass = (ncuaClasses) => {
+    const roots = ncuaClasses.filter((c) => !c.includes('--') && !c.includes('__'));
+    if (roots.length === 0)
+        return undefined;
+    return roots.sort((a, b) => a.length - b.length)[0];
+};
+/** BEM 구분자(-- 또는 __)의 첫 위치를 반환. 없으면 -1 */
+const findFirstSeparatorIndex = (dashIdx, underIdx) => {
+    if (dashIdx >= 0 && underIdx >= 0)
+        return Math.min(dashIdx, underIdx);
+    if (dashIdx >= 0)
+        return dashIdx;
+    return underIdx;
+};
+/** modifier/element 클래스에서 root class를 추론 */
+const inferRootClass = (ncuaClasses, rootClassMap) => {
+    for (const cls of ncuaClasses) {
+        const sepIdx = findFirstSeparatorIndex(cls.indexOf('--'), cls.indexOf('__'));
+        if (sepIdx > 0) {
+            const candidate = cls.substring(0, sepIdx);
+            if (rootClassMap.has(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+};
+/** 문자열 유사도 — 공통 접두사 길이 기반 */
+const prefixSimilarity = (a, b) => {
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i])
+        i++;
+    return i;
+};
+/** 유사도 상위 N개 제안 — modifier 오류면 modifier만, element 오류면 element만 */
+const suggestSimilar = (invalidClass, validClasses, max = MAX_SIMILAR_SUGGESTIONS) => {
+    const isElement = invalidClass.includes('__');
+    return validClasses
+        .filter((c) => (isElement ? c.includes('__') : c.includes('--')))
+        .map((c) => ({ class: c, score: prefixSimilarity(invalidClass, c) }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, max)
+        .map((item) => item.class);
+};
+/** unknown component 에러 수집 */
+const reportUnknownClasses = (ncuaClasses, errors, invalidClassesSet) => {
+    for (const cls of ncuaClasses) {
+        errors.push({
+            type: 'unknown_component',
+            class: cls,
+            component: 'unknown',
+            message: `Unknown component class '${cls}'. No matching component found.`,
+            suggestion: 'Use list_components to see all available components.',
+        });
+        invalidClassesSet.add(cls);
+    }
+};
+/** BEM 클래스 유효성 검증 */
+const validateBemClasses = (ncuaClasses, validSet, componentName, bemClasses, errors, invalidClassesSet) => {
+    for (const cls of ncuaClasses) {
+        if (validSet.has(cls))
+            continue;
+        const similar = suggestSimilar(cls, bemClasses);
+        errors.push({
+            type: cls.includes('__') ? 'invalid_element' : 'invalid_modifier',
+            class: cls,
+            component: componentName,
+            message: `Invalid BEM class '${cls}' for component '${componentName}'.`,
+            suggestion: similar.length > 0 ? `Similar: ${similar.join(', ')}` : 'Use get_component_props to see valid BEM classes.',
+        });
+        invalidClassesSet.add(cls);
+    }
+};
+// ── BEM 검증 엔트리 함수 ────────────────────────────────────────────────
+/** 엘리먼트별 BEM 클래스 검증 → errors + warnings + invalidClasses 수집 */
+const collectBemErrors = (params) => {
+    const { elements, rootClassMap, componentMap } = params;
+    const errors = [];
+    const warnings = [];
+    const invalidClassesSet = new Set();
+    const validSetCache = new Map();
+    let foundNcua = false;
+    for (const el of elements) {
+        const classes = (0, exports.getClassList)(el);
+        const ncuaClasses = classes.filter((c) => c.startsWith('ncua-'));
+        if (ncuaClasses.length === 0)
+            continue;
+        foundNcua = true;
+        let rootClass = findRootClass(ncuaClasses);
+        if (!rootClass || !rootClassMap.has(rootClass)) {
+            const inferred = inferRootClass(ncuaClasses, rootClassMap);
+            if (inferred)
+                rootClass = inferred;
+        }
+        collectMixedNamespaceWarning(classes, ncuaClasses, rootClass, rootClassMap, warnings);
+        collectMissingRootClassError(ncuaClasses, rootClass, rootClassMap, errors);
+        if (!rootClass || !rootClassMap.has(rootClass)) {
+            reportUnknownClasses(ncuaClasses, errors, invalidClassesSet);
+            continue;
+        }
+        const componentName = rootClassMap.get(rootClass);
+        const component = componentMap.get(componentName);
+        if (!validSetCache.has(componentName))
+            validSetCache.set(componentName, new Set(component.bemClasses));
+        validateBemClasses(ncuaClasses, validSetCache.get(componentName), componentName, component.bemClasses, errors, invalidClassesSet);
+    }
+    return { errors, warnings, invalidClassesSet, hasNcuaClasses: foundNcua };
+};
+exports.collectBemErrors = collectBemErrors;
+/** mixed_namespace 경고 수집 */
+const collectMixedNamespaceWarning = (classes, ncuaClasses, rootClass, rootClassMap, warnings) => {
+    const customClasses = classes.filter((c) => !c.startsWith('ncua-'));
+    if (customClasses.length === 0)
+        return;
+    const compName = rootClass && rootClassMap.has(rootClass) ? rootClassMap.get(rootClass) : 'unknown';
+    warnings.push({
+        type: 'mixed_namespace',
+        class: ncuaClasses[0],
+        component: compName,
+        message: `Element mixes NCUA classes (${ncuaClasses.join(', ')}) with custom classes (${customClasses.join(', ')}).`,
+        suggestion: 'Keep NCUA components isolated. Use a separate wrapper for custom styling.',
+    });
+};
+/** missing_root_class 에러 수집 */
+const collectMissingRootClassError = (ncuaClasses, rootClass, rootClassMap, errors) => {
+    const hasModifiers = ncuaClasses.some((c) => c.includes('--'));
+    const hasRootInElement = ncuaClasses.some((c) => !c.includes('--') && !c.includes('__'));
+    const isModifierWithoutRoot = hasModifiers && !hasRootInElement && rootClass != null && rootClassMap.has(rootClass);
+    if (!isModifierWithoutRoot)
+        return;
+    errors.push({
+        type: 'missing_root_class',
+        class: rootClass,
+        component: rootClassMap.get(rootClass),
+        message: `Root class '${rootClass}' is missing. Modifiers/elements require their root class.`,
+        suggestion: `Add '${rootClass}' class to the same element.`,
+    });
+};
+/** 잘못된 클래스를 제거하여 fixed_html 생성 */
+const buildFixedHtml = (root, invalidClassesSet) => {
+    for (const el of root.querySelectorAll('[class]')) {
+        const classes = (0, exports.getClassList)(el);
+        const filtered = classes.filter((c) => !invalidClassesSet.has(c));
+        if (filtered.length > 0) {
+            el.setAttribute('class', filtered.join(' '));
+        }
+        else {
+            el.removeAttribute('class');
+        }
+    }
+    return root.toString();
+};
+exports.buildFixedHtml = buildFixedHtml;
+/** CDN CSS/JS 링크 포함 여부 검증 */
+const checkCdnInclusion = (html, cdnMeta) => {
+    const errors = [];
+    if (!html.includes(cdnMeta.css)) {
+        errors.push({
+            type: 'missing_cdn',
+            class: '(page-level)',
+            component: '(page-level)',
+            message: 'HTML contains NCUA components but is missing the required CDN CSS link.',
+            suggestion: `Add <link href="${cdnMeta.css}" rel="stylesheet">`,
+        });
+    }
+    if (!html.includes(cdnMeta.js)) {
+        errors.push({
+            type: 'missing_cdn',
+            class: '(page-level)',
+            component: '(page-level)',
+            message: 'HTML contains NCUA components but is missing the required CDN JS link.',
+            suggestion: `Add <script src="${cdnMeta.js}"></script>`,
+        });
+    }
+    return errors;
+};
+exports.checkCdnInclusion = checkCdnInclusion;

package/bin/utils/compliance.d.ts

@@ -0,0 +1,52 @@
+/**
+ * compliance 검증 순수 함수 — NCUA 컴포넌트 누락, 커스텀 분리 검증, 준수도 점수
+ *
+ * 토큰 검증은 tokenValidator.ts에 분리.
+ */
+import { parse } from 'node-html-parser';
+import type { ComponentData, ComplianceRulesData, ComplianceError, ComplianceSummary } from '../types.js';
+import type { ValidationError } from './bemValidator.js';
+export { detectTokenIssues } from './tokenValidator.js';
+/** NCUA 컴포넌트 누락 감지 — 태그 인덱스로 O(n) 매칭 */
+export declare const detectNcuaOmission: (params: {
+    root: ReturnType<typeof parse>;
+    complianceRules: ComplianceRulesData;
+    componentMap: Map<string, ComponentData>;
+}) => {
+    errors: ComplianceError[];
+    ncuaUsage: {
+        used: number;
+        available: number;
+    };
+};
+/** NCUA 컴포넌트 내부 커스텀 스타일 감지 */
+export declare const detectCustomNotSeparated: (params: {
+    root: ReturnType<typeof parse>;
+    rootClassMap: Map<string, string>;
+    warnings: ValidationError[];
+}) => {
+    errors: ComplianceError[];
+    customSeparation: {
+        clean: number;
+        violated: number;
+    };
+};
+/** 준수도 점수 + 요약 빌드 */
+export declare const buildComplianceSummary: (params: {
+    ncuaErrors: ComplianceError[];
+    tokenErrors: ComplianceError[];
+    customErrors: ComplianceError[];
+    ncuaUsage: {
+        used: number;
+        available: number;
+    };
+    tokenUsage: {
+        correct: number;
+        missing: number;
+        invalid: number;
+    };
+    customSeparation: {
+        clean: number;
+        violated: number;
+    };
+}) => ComplianceSummary;

package/bin/utils/compliance.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildComplianceSummary = exports.detectCustomNotSeparated = exports.detectNcuaOmission = exports.detectTokenIssues = void 0;
+const bemValidator_js_1 = require("./bemValidator.js");
+var tokenValidator_js_1 = require("./tokenValidator.js");
+Object.defineProperty(exports, "detectTokenIssues", { enumerable: true, get: function () { return tokenValidator_js_1.detectTokenIssues; } });
+// ── 상수 ─────────────────────────────────────────────────────────────────
+const MAX_COMPLIANCE_ERRORS = 10;
+const NCUA_NOT_USED_MEDIUM_WEIGHT = 0.5;
+const COMPLIANCE_WEIGHTS = {
+    ncua_not_used: 1.0,
+    token_not_used: 0.5,
+    invalid_token: 1.0,
+    custom_not_separated: 1.0,
+};
+/** 규칙의 hints가 요소 속성과 매칭되는지 확인 */
+const matchesHints = (el, hints) => {
+    if (!hints)
+        return true;
+    for (const hint of hints) {
+        const attrValue = el.getAttribute(hint.attr);
+        if (!attrValue || !hint.values.includes(attrValue.toLowerCase()))
+            return false;
+    }
+    return true;
+};
+/** 태그명 → 해당 태그의 규칙 배열 인덱스 (§ 5.3 O(n) 전환) */
+const buildTagRuleIndex = (rules, componentMap) => {
+    const index = new Map();
+    for (const rule of rules) {
+        if (!componentMap.has(rule.ncuaComponent))
+            continue;
+        const existing = index.get(rule.match.tag);
+        if (existing)
+            existing.push(rule);
+        else
+            index.set(rule.match.tag, [rule]);
+    }
+    return index;
+};
+/** ncua- root class → compliance rule의 ncuaComponent 매핑 */
+const buildNcuaRootToComponentMap = (complianceRules, componentMap) => {
+    const map = new Map();
+    for (const rule of complianceRules.patterns) {
+        const component = componentMap.get(rule.ncuaComponent);
+        if (!component)
+            continue;
+        for (const cls of component.bemClasses) {
+            if (!cls.includes('--') && !cls.includes('__'))
+                map.set(cls, rule.ncuaComponent);
+        }
+    }
+    return map;
+};
+/** compliance rules 중 componentMap에 실제 존재하는 고유 컴포넌트 수 */
+const countAvailableComponents = (patterns, componentMap) => {
+    const available = new Set();
+    for (const rule of patterns) {
+        if (componentMap.has(rule.ncuaComponent))
+            available.add(rule.ncuaComponent);
+    }
+    return available.size;
+};
+// ── 검증 함수 ────────────────────────────────────────────────────────────
+/** ncua 클래스를 가진 요소에서 사용 중인 컴포넌트 수집 */
+const collectUsedComponents = (el, ncuaRootMap, usedComponents) => {
+    for (const cls of (0, bemValidator_js_1.getClassList)(el)) {
+        const comp = ncuaRootMap.get(cls);
+        if (comp)
+            usedComponents.add(comp);
+    }
+};
+/** 네이티브 HTML 요소에서 ncua_not_used 에러 매칭 */
+const matchNativeElement = (el, tagIndex) => {
+    const tag = el.tagName?.toLowerCase();
+    if (!tag)
+        return undefined;
+    const candidateRules = tagIndex.get(tag);
+    if (!candidateRules)
+        return undefined;
+    for (const rule of candidateRules) {
+        if (!matchesHints(el, rule.match.hints))
+            continue;
+        return {
+            type: 'ncua_not_used',
+            target: `<${tag}>`,
+            component: rule.ncuaComponent,
+            message: `Native <${tag}> used instead of NCUA '${rule.ncuaComponent}' component.`,
+            suggestion: `Use NCUA '${rule.ncuaComponent}' component. Call search_component('${rule.ncuaComponent}') for usage.`,
+            ...(rule.confidence === 'medium' && { severity: 'warning' }),
+        };
+    }
+    return undefined;
+};
+/** NCUA 컴포넌트 누락 감지 — 태그 인덱스로 O(n) 매칭 */
+const detectNcuaOmission = (params) => {
+    const { root, complianceRules, componentMap } = params;
+    const errors = [];
+    const usedComponents = new Set();
+    const tagIndex = buildTagRuleIndex(complianceRules.patterns, componentMap);
+    const ncuaRootMap = buildNcuaRootToComponentMap(complianceRules, componentMap);
+    for (const el of root.querySelectorAll('*')) {
+        if ((0, bemValidator_js_1.getClassList)(el).some((c) => c.startsWith('ncua-'))) {
+            collectUsedComponents(el, ncuaRootMap, usedComponents);
+            continue;
+        }
+        const error = matchNativeElement(el, tagIndex);
+        if (error)
+            errors.push(error);
+    }
+    return {
+        errors,
+        ncuaUsage: {
+            used: usedComponents.size,
+            available: countAvailableComponents(complianceRules.patterns, componentMap),
+        },
+    };
+};
+exports.detectNcuaOmission = detectNcuaOmission;
+/** NCUA 컴포넌트 내부 커스텀 스타일 감지 */
+const detectCustomNotSeparated = (params) => {
+    const { root, rootClassMap, warnings } = params;
+    const errors = [];
+    let violated = 0;
+    let clean = 0;
+    const suppressedClasses = new Set();
+    for (const el of root.querySelectorAll('[class]')) {
+        const classes = (0, bemValidator_js_1.getClassList)(el);
+        const ncuaClasses = classes.filter((c) => c.startsWith('ncua-'));
+        if (ncuaClasses.length === 0)
+            continue;
+        const target = ncuaClasses[0];
+        const hasInlineStyle = !!el.getAttribute('style');
+        const isBemInternal = ncuaClasses.some((c) => c.includes('__'));
+        const hasCustomOverride = isBemInternal && classes.some((c) => !c.startsWith('ncua-'));
+        if (hasInlineStyle) {
+            violated++;
+            errors.push(buildCustomError(target, rootClassMap, 'inline'));
+        }
+        else if (hasCustomOverride) {
+            violated++;
+            suppressedClasses.add(target);
+            errors.push(buildCustomError(target, rootClassMap, 'override'));
+        }
+        else {
+            clean++;
+        }
+    }
+    suppressMixedNamespaceWarnings(warnings, suppressedClasses);
+    return { errors, customSeparation: { clean, violated } };
+};
+exports.detectCustomNotSeparated = detectCustomNotSeparated;
+/** custom_not_separated 에러 빌드 */
+const buildCustomError = (target, rootClassMap, kind) => {
+    const rootClass = kind === 'inline' ? target.split('--')[0].split('__')[0] : target.split('__')[0];
+    const message = kind === 'inline'
+        ? `Inline style on NCUA component element '${target}'. NCUA components should not have inline styles.`
+        : `Custom class override on NCUA BEM internal element '${target}'. Do not add custom classes to BEM sub-elements.`;
+    return {
+        type: 'custom_not_separated',
+        target,
+        component: rootClassMap.get(rootClass) ?? 'unknown',
+        message,
+        suggestion: 'Use a separate wrapper outside the NCUA component for custom styling.',
+    };
+};
+/** mixed_namespace warnings 중 suppress 대상을 제거 */
+const suppressMixedNamespaceWarnings = (warnings, suppressedClasses) => {
+    if (suppressedClasses.size === 0)
+        return;
+    for (let i = warnings.length - 1; i >= 0; i--) {
+        if (warnings[i].type === 'mixed_namespace' && suppressedClasses.has(warnings[i].class)) {
+            warnings.splice(i, 1);
+        }
+    }
+};
+/** 준수도 점수 + 요약 빌드 */
+const buildComplianceSummary = (params) => {
+    const { ncuaErrors, tokenErrors, customErrors, ncuaUsage, tokenUsage, customSeparation } = params;
+    const allErrors = [...ncuaErrors, ...tokenErrors, ...customErrors];
+    let weightedViolations = 0;
+    for (const err of allErrors) {
+        const isMedium = err.type === 'ncua_not_used' && err.severity === 'warning';
+        weightedViolations += isMedium ? NCUA_NOT_USED_MEDIUM_WEIGHT : COMPLIANCE_WEIGHTS[err.type];
+    }
+    const totalCheckpoints = ncuaUsage.available +
+        (tokenUsage.correct + tokenUsage.missing + tokenUsage.invalid) +
+        (customSeparation.clean + customSeparation.violated);
+    const score = totalCheckpoints === 0 ? 1.0 : Math.max(0, Math.min(1, 1 - weightedViolations / totalCheckpoints));
+    return {
+        score: Math.round(score * 100) / 100,
+        errors: allErrors.slice(0, MAX_COMPLIANCE_ERRORS),
+        ncuaUsage,
+        tokenUsage,
+        customSeparation,
+        totalViolations: allErrors.length,
+    };
+};
+exports.buildComplianceSummary = buildComplianceSummary;

package/bin/utils/dataLoader.d.ts

@@ -0,0 +1,33 @@
+import type { ComponentData, IconData, TokenData, ComplianceRulesData } from '../types.js';
+export declare const DEFAULT_DATA_DIR: string;
+export interface CdnMeta {
+    version: string;
+    css: string;
+    js: string;
+}
+export interface IconMeta {
+    packageName: string;
+    version: string;
+    cdn: string;
+}
+/** data/ 디렉토리의 JSON 파일을 읽어 componentMap으로 반환 */
+export declare const loadComponentsFromDir: (dataDir: string) => Map<string, ComponentData>;
+/** data/_icons.json을 읽어 IconData로 반환 (파일 없으면 빈 데이터) */
+export declare const loadIconData: (dataDir: string) => IconData;
+/** _meta.json 파싱 결과 */
+export interface MetaData {
+    cdn: CdnMeta | null;
+    icon: IconMeta | null;
+}
+/** data/_meta.json에서 CDN + icon 메타를 1회 읽기로 로드 */
+export declare const loadMeta: (dataDir: string) => MetaData;
+/** data/_tokens.json을 읽어 TokenData로 반환 (파일 없으면 빈 데이터) */
+export declare const loadTokenData: (dataDir: string) => TokenData;
+/** definitions/compliance-rules.json을 로드하여 ComplianceRulesData로 반환 (파일 없으면 null) */
+export declare const loadComplianceRules: (definitionsDir: string) => ComplianceRulesData | null;
+/** definitions/instructions.md를 로드하여 문자열 반환 */
+export declare const loadInstructions: (definitionsDir: string) => string;
+/** componentMap에서 이름으로 단일 컴포넌트 조회 */
+export declare const getComponent: (map: Map<string, ComponentData>, name: string) => ComponentData | undefined;
+/** componentMap의 모든 컴포넌트를 배열로 반환 */
+export declare const getAllComponents: (map: Map<string, ComponentData>) => ComponentData[];

package/bin/utils/dataLoader.js

@@ -0,0 +1,174 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAllComponents = exports.getComponent = exports.loadInstructions = exports.loadComplianceRules = exports.loadTokenData = exports.loadMeta = exports.loadIconData = exports.loadComponentsFromDir = exports.DEFAULT_DATA_DIR = void 0;
+/**
+ * dataLoader — mcp/data/*.json + definitions/ 파일을 읽어 반환
+ *
+ * 함수 분류:
+ *   loadComponentsFromDir, loadIconData, loadCdnMeta, loadInstructions → 부수효과 (fs I/O)
+ *   getComponent, getAllComponents → 순수 함수 (Map 조회)
+ *
+ * Map 소유권은 server.ts가 가진다. 이 파일은 상태를 보유하지 않는다.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const logger_js_1 = require("./logger.js");
+const response_js_1 = require("./response.js");
+exports.DEFAULT_DATA_DIR = path_1.default.resolve(__dirname, '../../data');
+// ── 검증 헬퍼 (§ 3.8 복잡한 조건을 의도가 드러나는 이름으로 분리) ──────────
+/** JSON.parse 결과가 name: string 필드를 가진 컴포넌트 객체인지 검증 */
+const isValidComponentJson = (data) => !!data && typeof data === 'object' && 'name' in data && typeof data.name === 'string';
+/** JSON.parse 결과가 icons 배열을 가진 아이콘 데이터인지 검증 */
+const isValidIconJson = (data) => !!data && typeof data === 'object' && 'icons' in data && Array.isArray(data.icons);
+// ── 부수효과 함수 (fs I/O) ────────────────────────────────────────────────
+/** data/ 디렉토리의 JSON 파일을 읽어 componentMap으로 반환 */
+const loadComponentsFromDir = (dataDir) => {
+    if (!fs_1.default.existsSync(dataDir)) {
+        logger_js_1.logger.error(`mcp/data/ 디렉토리가 없습니다: ${dataDir}`);
+        process.exit(1);
+    }
+    const jsonFiles = fs_1.default.readdirSync(dataDir).filter((f) => f.endsWith('.json') && !f.startsWith('_'));
+    if (jsonFiles.length === 0) {
+        logger_js_1.logger.error(`mcp/data/ 디렉토리에 JSON 파일이 없습니다: ${dataDir}`);
+        process.exit(1);
+    }
+    const map = new Map();
+    for (const file of jsonFiles) {
+        const filePath = path_1.default.join(dataDir, file);
+        try {
+            const raw = fs_1.default.readFileSync(filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (!isValidComponentJson(parsed)) {
+                throw new Error('name 필드가 없거나 올바르지 않습니다');
+            }
+            const component = parsed;
+            map.set(component.name, component);
+        }
+        catch (err) {
+            logger_js_1.logger.error(`JSON 파싱 실패 (${file}): ${(0, response_js_1.toErrorMessage)(err)}`);
+            process.exit(1);
+        }
+    }
+    logger_js_1.logger.info(`컴포넌트 ${map.size}개 로딩 완료`);
+    return map;
+};
+exports.loadComponentsFromDir = loadComponentsFromDir;
+/** data/_icons.json을 읽어 IconData로 반환 (파일 없으면 빈 데이터) */
+const loadIconData = (dataDir) => {
+    const iconPath = path_1.default.join(dataDir, '_icons.json');
+    if (!fs_1.default.existsSync(iconPath)) {
+        logger_js_1.logger.error(`_icons.json이 없습니다: ${iconPath}`);
+        return { totalCount: 0, fillCount: 0, icons: [] };
+    }
+    try {
+        const raw = fs_1.default.readFileSync(iconPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!isValidIconJson(parsed)) {
+            throw new Error('icons 배열이 없습니다');
+        }
+        return parsed;
+    }
+    catch (err) {
+        logger_js_1.logger.error(`_icons.json 파싱 실패: ${(0, response_js_1.toErrorMessage)(err)}`);
+        return { totalCount: 0, fillCount: 0, icons: [] };
+    }
+};
+exports.loadIconData = loadIconData;
+/** data/_meta.json에서 CDN + icon 메타를 1회 읽기로 로드 */
+const loadMeta = (dataDir) => {
+    const metaPath = path_1.default.join(dataDir, '_meta.json');
+    if (!fs_1.default.existsSync(metaPath))
+        return { cdn: null, icon: null };
+    try {
+        const raw = fs_1.default.readFileSync(metaPath, 'utf-8');
+        const meta = JSON.parse(raw);
+        return {
+            cdn: isValidCdnMeta(meta.cdn) ? meta.cdn : null,
+            icon: isValidIconMeta(meta.icon) ? meta.icon : null,
+        };
+    }
+    catch (err) {
+        logger_js_1.logger.error(`_meta.json 파싱 실패: ${(0, response_js_1.toErrorMessage)(err)}`);
+        return { cdn: null, icon: null };
+    }
+};
+exports.loadMeta = loadMeta;
+/** CdnMeta 스키마 검증 */
+const isValidCdnMeta = (data) => !!data &&
+    typeof data === 'object' &&
+    'version' in data &&
+    'css' in data &&
+    'js' in data &&
+    typeof data.version === 'string';
+/** IconMeta 스키마 검증 */
+const isValidIconMeta = (data) => !!data &&
+    typeof data === 'object' &&
+    'packageName' in data &&
+    'version' in data &&
+    typeof data.packageName === 'string';
+/** data/_tokens.json을 읽어 TokenData로 반환 (파일 없으면 빈 데이터) */
+const loadTokenData = (dataDir) => {
+    const tokenPath = path_1.default.join(dataDir, '_tokens.json');
+    if (!fs_1.default.existsSync(tokenPath)) {
+        logger_js_1.logger.error(`_tokens.json이 없습니다: ${tokenPath}`);
+        return { totalCount: 0, categories: [], groups: [] };
+    }
+    try {
+        const raw = fs_1.default.readFileSync(tokenPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!isValidTokenJson(parsed)) {
+            throw new Error('totalCount 또는 groups 배열이 없습니다');
+        }
+        return parsed;
+    }
+    catch (err) {
+        logger_js_1.logger.error(`_tokens.json 파싱 실패: ${(0, response_js_1.toErrorMessage)(err)}`);
+        return { totalCount: 0, categories: [], groups: [] };
+    }
+};
+exports.loadTokenData = loadTokenData;
+/** TokenData 스키마 검증 */
+const isValidTokenJson = (data) => !!data &&
+    typeof data === 'object' &&
+    'totalCount' in data &&
+    'groups' in data &&
+    Array.isArray(data.groups);
+/** compliance-rules.json 스키마 검증 */
+const isValidComplianceRulesJson = (data) => !!data && typeof data === 'object' && 'patterns' in data && Array.isArray(data.patterns);
+/** definitions/compliance-rules.json을 로드하여 ComplianceRulesData로 반환 (파일 없으면 null) */
+const loadComplianceRules = (definitionsDir) => {
+    const filePath = path_1.default.resolve(definitionsDir, 'compliance-rules.json');
+    if (!fs_1.default.existsSync(filePath)) {
+        logger_js_1.logger.info('compliance-rules.json이 없습니다 — compliance 검증 비활성화');
+        return null;
+    }
+    try {
+        const raw = fs_1.default.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!isValidComplianceRulesJson(parsed)) {
+            throw new Error('patterns 배열이 없습니다');
+        }
+        return parsed;
+    }
+    catch (err) {
+        logger_js_1.logger.error(`compliance-rules.json 파싱 실패: ${(0, response_js_1.toErrorMessage)(err)}`);
+        return null;
+    }
+};
+exports.loadComplianceRules = loadComplianceRules;
+/** definitions/instructions.md를 로드하여 문자열 반환 */
+const loadInstructions = (definitionsDir) => {
+    const instructionsPath = path_1.default.resolve(definitionsDir, 'instructions.md');
+    return fs_1.default.readFileSync(instructionsPath, 'utf-8').trim();
+};
+exports.loadInstructions = loadInstructions;
+// ── 순수 함수 (외부 상태 없음, Map을 파라미터로 받음) ──────────────────────
+/** componentMap에서 이름으로 단일 컴포넌트 조회 */
+const getComponent = (map, name) => map.get(name);
+exports.getComponent = getComponent;
+/** componentMap의 모든 컴포넌트를 배열로 반환 */
+const getAllComponents = (map) => Array.from(map.values());
+exports.getAllComponents = getAllComponents;

package/bin/utils/domEnvironment.d.ts

@@ -0,0 +1,9 @@
+/**
+ * DOM + React 런타임 초기화 — jsdom 환경 + createPortal mock + React SSR
+ *
+ * Action (부수효과): globalThis를 변조한다. server.ts 또는 테스트 beforeAll에서 1회 호출.
+ * 이 파일로 추출하여 server.ts/테스트 간 코드 중복을 제거한다 (§ 3.9).
+ */
+import type { ReactRuntime } from '../types.js';
+/** jsdom + React SSR 환경을 초기화하고 ReactRuntime을 반환 */
+export declare const setupDomEnvironment: () => ReactRuntime;