@ncds/ui-admin-mcp 1.0.0-alpha.11 → 1.0.0-alpha.13

package/bin/definitions/instructions.md

@@ -226,6 +226,22 @@ Example — Modal with full structure:
 
 Always check `usageExamples` in `get_component_props` for compound component patterns. You can freely omit or reorder sub-components to customize the layout.
 
+`get_component_props` on a compound parent (e.g. `modal`, `button-group`) also returns a `subComponents` field:
+
+```json
+{
+  "props": { "isOpen": {...}, "size": {...}, ... },
+  "subComponents": {
+    "Modal.Header": { "props": { "title": {...}, "align": {...}, "featuredIcon": {...} } },
+    "Modal.Content": { "props": { "children": {...}, "className": {...} } },
+    "Modal.Actions": { "props": { "layout": {...}, "align": {...} } }
+  },
+  "usageExamples": { ... }
+}
+```
+
+Use `subComponents[parent.sub].props` to learn valid props (types, enums, defaults) for each sub-component without calling `get_component_props` again. This prevents recursive tool calls when composing compound components.
+
 ## Rules Schema
 
 The `rules` array in ping response is a flat list of strings grouped by category. Categories:

package/bin/tools/getComponentProps.js

@@ -14,6 +14,7 @@ const getComponentProps = (componentMap, name) => {
         return (0, response_js_1.componentNotFoundResponse)(normalized);
     return (0, response_js_1.successResponse)({
         props: component.props,
+        ...(component.subComponents && { subComponents: component.subComponents }),
         ...(component.usageExamples && { usageExamples: component.usageExamples }),
     });
 };

package/bin/tools/renderToHtml.js

@@ -5,38 +5,37 @@ const response_js_1 = require("../utils/response.js");
 // ── 상수 ──────────────────────────────────────────────────────────
 /** React 특수 props 차단 — injection 방지 */
 const BLOCKED_PROPS = new Set(['dangerouslySetInnerHTML', 'ref', '__self', '__source']);
-/** 아이콘 관련 props — React 변환 시 import 생성 대상 */
-const ICON_PROP_NAMES = new Set(['leadingIcon', 'trailingIcon', 'icon', 'groupIcon']);
 /** children 중첩 렌더링 제한 */
 const MAX_CHILDREN_DEPTH = 5;
 const MAX_CHILDREN_COUNT = 30;
-// ── 타입 가드 ──────────────────────────────────────────────────────
-/** { type: 'icon', icon: string } 형태인지 판별 */
-const isIconSlot = (value) => typeof value === 'object' &&
-    value !== null &&
-    value.type === 'icon' &&
-    typeof value.icon === 'string';
+/** spec-walk 재귀 깊이 제한 — 순환 spec 방지 */
+const MAX_SPEC_DEPTH = 6;
 // ── 타입 가드: children 중첩 ────────────────────────────────────────
 /** { component: string, props?: object } 형태인지 판별 */
 const isChildDescriptor = (value) => typeof value === 'object' && value !== null && typeof value.component === 'string';
 /** PascalCase 변환: "header" → "Header" */
 const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
-/** 단순 컴포넌트 resolve: "button" → bundle.Button */
+/** 단순 컴포넌트 resolve: "button" → { Component, propsSpec } */
 const resolveSimpleComponent = (name, ctx) => {
     const normalized = (0, response_js_1.normalizeName)(name);
     const childData = ctx.componentMap.get(normalized);
-    return childData?.exportName ? ctx.bundle[childData.exportName] ?? null : null;
+    const Component = childData?.exportName ? ctx.bundle[childData.exportName] ?? null : null;
+    return { Component, propsSpec: childData?.props };
 };
-/** compound component resolve: "modal.header" → bundle.Modal.Header */
+/** compound component resolve: "modal.header" → { Component: bundle.Modal.Header, propsSpec: subComponents["Modal.Header"].props } */
 const resolveCompoundComponent = (name, dotIndex, ctx) => {
     const parentName = name.slice(0, dotIndex).toLowerCase();
     const subName = name.slice(dotIndex + 1);
     const parentData = ctx.componentMap.get(parentName);
     const parentExportName = parentData?.exportName;
     if (!parentExportName)
-        return null;
+        return { Component: null, propsSpec: undefined };
     const Parent = ctx.bundle[parentExportName];
-    return Parent?.[capitalize(subName)] ?? null;
+    const Component = Parent?.[capitalize(subName)] ?? null;
+    // subComponents key는 "Modal.Header" 형태 (parent export name + sub name)
+    const compoundKey = `${parentExportName}.${capitalize(subName)}`;
+    const propsSpec = parentData?.subComponents?.[compoundKey]?.props;
+    return { Component, propsSpec };
 };
 /** children JSON을 재귀적으로 React element로 변환 */
 const resolveChildren = (children, ctx, depth) => {
@@ -53,22 +52,23 @@ const resolveChildren = (children, ctx, depth) => {
     if (isChildDescriptor(children)) {
         const componentName = children.component.trim();
         const dotIndex = componentName.indexOf('.');
-        // dot notation: "modal.header" → bundle.Modal.Header
-        const Component = dotIndex > 0
+        // dot notation: "modal.header" → bundle.Modal.Header (+ subComponents props spec)
+        const { Component, propsSpec } = dotIndex > 0
             ? resolveCompoundComponent(componentName, dotIndex, ctx)
             : resolveSimpleComponent(componentName, ctx);
         if (!Component)
             return null;
-        const childProps = { ...(children.props ?? {}) };
+        // BLOCKED_PROPS(dangerouslySetInnerHTML, ref, __self, __source)를 먼저 제거
+        // propsSpec이 있으면 화이트리스트 필터(sanitizeProps)도 적용하여 XSS/alien prop 차단
+        const rawProps = children.props ?? {};
+        const blockedRemoved = removeBlockedProps(rawProps);
+        const childProps = propsSpec ? sanitizeProps(blockedRemoved, propsSpec) : blockedRemoved;
         // descriptor의 children 필드가 있으면 props.children보다 우선
         const rawChildren = children.children !== undefined ? children.children : childProps.children;
         if (rawChildren !== undefined) {
             childProps.children = resolveChildren(rawChildren, ctx, depth + 1);
         }
-        // dot notation은 componentMap에 props spec이 없으므로 icon resolve만 적용
-        const parentName = dotIndex > 0 ? componentName.slice(0, dotIndex).toLowerCase() : componentName.toLowerCase();
-        const childData = ctx.componentMap.get(parentName);
-        const resolvedProps = resolveIconProps(childProps, ctx.iconBundle, childData?.props);
+        const resolvedProps = resolveIconProps(childProps, ctx.iconBundle, propsSpec);
         return ctx.reactRuntime.createElement(Component, resolvedProps);
     }
     return children;
@@ -81,26 +81,60 @@ const sanitizeProps = (userProps, propsSpec) => {
     const allowedKeys = new Set([...Object.keys(propsSpec), 'children']);
     return Object.fromEntries(Object.entries(userProps).filter(([key]) => allowedKeys.has(key)));
 };
-/** 아이콘 prop의 icon 문자열을 실제 React 컴포넌트로 resolve */
-const resolveIconProps = (props, iconBundle, propsSpec) => {
-    const resolved = { ...props };
-    for (const key of ICON_PROP_NAMES) {
-        const value = resolved[key];
-        const spec = propsSpec?.[key];
-        // bare function prop (FeaturedIcon 등) — 문자열 이름을 컴포넌트 함수로 직접 resolve
-        if (spec?.type === 'function' && typeof value === 'string') {
-            const iconComponent = iconBundle[value];
-            if (typeof iconComponent === 'function') {
-                resolved[key] = iconComponent;
+/**
+ * spec-walk 재귀 resolver — spec.semantic === 'icon-component' 위치에서 문자열을 iconBundle 컴포넌트로 치환
+ *
+ * 이름 화이트리스트가 아닌 **타입 정체성(semantic)** 기반 판정.
+ * extract 단계에서 ts-morph가 SlotIconComponent alias를 감지하여 spec.semantic을 부착한다.
+ * 중첩 객체/배열을 spec.properties를 따라 자동 순회하므로 어떤 깊이에도 대응.
+ */
+const resolveValueBySpec = (value, spec, iconBundle, depth = 0) => {
+    if (depth > MAX_SPEC_DEPTH)
+        return value;
+    if (!spec)
+        return value;
+    // leaf: icon-component 위치에서 string → 컴포넌트 치환. bundle miss 시 원본 유지.
+    if (spec.semantic === 'icon-component' && typeof value === 'string') {
+        const iconComponent = iconBundle[value];
+        return typeof iconComponent === 'function' ? iconComponent : value;
+    }
+    // 배열: spec이 배열 타입이고 value가 배열이면 각 요소에 재귀 (spec.properties는 요소 shape)
+    if (spec.rawType?.includes('[]') && spec.properties && Array.isArray(value)) {
+        return value.map((item) => {
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                const obj = item;
+                const resolved = { ...obj };
+                for (const [key, childSpec] of Object.entries(spec.properties)) {
+                    if (key in resolved) {
+                        resolved[key] = resolveValueBySpec(resolved[key], childSpec, iconBundle, depth + 1);
+                    }
+                }
+                return resolved;
+            }
+            return item;
+        });
+    }
+    // 중첩 객체: spec.properties를 따라 각 키에 재귀 적용
+    if (spec.properties && value && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        const resolved = { ...obj };
+        for (const [key, childSpec] of Object.entries(spec.properties)) {
+            if (key in resolved) {
+                resolved[key] = resolveValueBySpec(resolved[key], childSpec, iconBundle, depth + 1);
             }
-            continue;
         }
-        // IconSlotType 래퍼 (Button leadingIcon 등) — 래퍼 내부 icon을 컴포넌트로 교체
-        if (!isIconSlot(value))
-            continue;
-        const iconComponent = iconBundle[value.icon];
-        if (typeof iconComponent === 'function') {
-            resolved[key] = { ...value, icon: iconComponent };
+        return resolved;
+    }
+    return value;
+};
+/** 최상위 props를 propsSpec에 따라 재귀 resolve */
+const resolveIconProps = (props, iconBundle, propsSpec) => {
+    if (!propsSpec)
+        return props;
+    const resolved = { ...props };
+    for (const [key, spec] of Object.entries(propsSpec)) {
+        if (key in resolved) {
+            resolved[key] = resolveValueBySpec(resolved[key], spec, iconBundle);
         }
     }
     return resolved;
@@ -108,19 +142,64 @@ const resolveIconProps = (props, iconBundle, propsSpec) => {
 // ── JSX 변환 ──────────────────────────────────────────────────────
 /** JSX attribute 값에서 " 를 이스케이프 */
 const escapeJsxAttrValue = (value) => value.replace(/"/g, '"');
-/** 단일 prop을 JSX attribute 문자열로 변환 */
+/**
+ * spec-walk 재귀로 JSX 값 문자열을 생성.
+ * icon-component 위치의 문자열은 컴포넌트 이름 참조(중괄호 없는 identifier)로,
+ * 중첩 객체는 `{ key: ... }` object literal 형태로 직렬화.
+ */
+const toJsxValueBySpec = (value, spec, depth = 0) => {
+    if (depth > MAX_SPEC_DEPTH)
+        return JSON.stringify(value);
+    // leaf: icon-component 위치의 문자열은 identifier로 반환
+    if (spec?.semantic === 'icon-component' && typeof value === 'string')
+        return value;
+    // 배열: 각 요소를 재귀 직렬화
+    if (spec?.rawType?.includes('[]') && spec.properties && Array.isArray(value)) {
+        const items = value.map((item) => {
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                const obj = item;
+                const entries = Object.entries(obj).map(([k, v]) => {
+                    const childSpec = spec.properties?.[k];
+                    return `${k}: ${toJsxValueBySpec(v, childSpec, depth + 1)}`;
+                });
+                return `{ ${entries.join(', ')} }`;
+            }
+            return JSON.stringify(item);
+        });
+        return `[${items.join(', ')}]`;
+    }
+    // 중첩 객체: spec.properties 따라 각 키를 재귀 직렬화
+    if (spec?.properties && value && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        const entries = Object.entries(obj).map(([k, v]) => {
+            const childSpec = spec.properties?.[k];
+            return `${k}: ${toJsxValueBySpec(v, childSpec, depth + 1)}`;
+        });
+        return `{ ${entries.join(', ')} }`;
+    }
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    return JSON.stringify(value);
+};
+/** 단일 prop을 JSX attribute 문자열로 변환 — spec-driven */
 const toJsxAttr = (key, value, spec) => {
     if (typeof value === 'boolean' && value)
         return key;
-    // bare function icon prop (FeaturedIcon 등) — icon={SearchLg} 형태
-    if (ICON_PROP_NAMES.has(key) && spec?.type === 'function' && typeof value === 'string')
+    // icon-component 최상위 prop — key={SearchLg} 형태
+    if (spec?.semantic === 'icon-component' && typeof value === 'string')
         return `${key}={${value}}`;
+    // 배열 prop — key={[{ ... }, { ... }]} 형태
+    if (spec?.rawType?.includes('[]') && spec.properties && Array.isArray(value)) {
+        return `${key}={${toJsxValueBySpec(value, spec)}}`;
+    }
+    // 중첩 spec 객체 — key={{ icon: X, color: 'success', ... }} 형태 (JSX 표현식 중괄호로 감싸기)
+    if (spec?.properties && value && typeof value === 'object' && !Array.isArray(value)) {
+        return `${key}={${toJsxValueBySpec(value, spec)}}`;
+    }
     if (typeof value === 'string')
         return `${key}="${escapeJsxAttrValue(value)}"`;
     if (typeof value === 'number')
         return `${key}={${value}}`;
-    if (ICON_PROP_NAMES.has(key) && isIconSlot(value))
-        return `${key}={{ type: 'icon', icon: ${value.icon} }}`;
     if (spec?.type === 'enum' || spec?.type === 'string')
         return `${key}="${String(value)}"`;
     return `${key}={${JSON.stringify(value)}}`;
@@ -131,19 +210,47 @@ const propsToJsxAttrs = (props, propsSpec) => Object.entries(props)
     .map(([key, value]) => toJsxAttr(key, value, propsSpec[key]))
     .join(' ');
 // ── 아이콘 추출 ──────────────────────────────────────────────────
-/** icon prop 값에서 아이콘 이름을 추출 */
-const extractIconName = (value) => {
-    if (isIconSlot(value))
-        return value.icon;
-    if (typeof value === 'string' && value.length > 0)
-        return value;
-    return null;
+/** spec-walk로 value에서 icon-component 위치의 문자열 이름을 수집. 중첩 객체 + 배열까지 내려감. */
+const collectIconNamesBySpec = (value, spec, acc, depth = 0) => {
+    if (depth > MAX_SPEC_DEPTH || !spec)
+        return;
+    if (spec.semantic === 'icon-component' && typeof value === 'string' && value.length > 0) {
+        acc.add(value);
+        return;
+    }
+    // 배열 요소 재귀
+    if (spec.rawType?.includes('[]') && spec.properties && Array.isArray(value)) {
+        for (const item of value) {
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                const obj = item;
+                for (const [key, childSpec] of Object.entries(spec.properties)) {
+                    if (key in obj)
+                        collectIconNamesBySpec(obj[key], childSpec, acc, depth + 1);
+                }
+            }
+        }
+        return;
+    }
+    if (spec.properties && value && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        for (const [key, childSpec] of Object.entries(spec.properties)) {
+            if (key in obj) {
+                collectIconNamesBySpec(obj[key], childSpec, acc, depth + 1);
+            }
+        }
+    }
+};
+/** propsSpec을 따라 appliedProps에서 아이콘 이름을 수집 — 이름 화이트리스트 없음 */
+const extractIconNames = (props, propsSpec) => {
+    if (!propsSpec)
+        return [];
+    const acc = new Set();
+    for (const [key, spec] of Object.entries(propsSpec)) {
+        if (key in props)
+            collectIconNamesBySpec(props[key], spec, acc);
+    }
+    return [...acc];
 };
-/** appliedProps에서 아이콘 이름을 추출 (PascalCase) */
-const extractIconNames = (props) => Object.entries(props)
-    .filter(([key]) => ICON_PROP_NAMES.has(key))
-    .map(([, value]) => extractIconName(value))
-    .filter((name) => name !== null);
 // ── 검증 ────────────────────────────────────────────────────────
 /** 잘못된 enum 값을 경고 문자열로 변환 — 교정 결과도 포함 */
 const formatInvalidEnum = (key, value, spec) => {
@@ -202,8 +309,8 @@ const correctMissingRequired = (userProps, propsSpec) => {
             corrected[key] = spec.default;
             continue;
         }
-        // icon function prop (FeaturedIcon 등) — 빈 span 반환 스텁 주입하여 crash 방지
-        if (spec.type === 'function' && ICON_PROP_NAMES.has(key)) {
+        // icon-component 타입 — 빈 span 반환 스텁 주입하여 crash 방지 (spec.semantic 기반 판정)
+        if (spec.semantic === 'icon-component') {
             corrected[key] = () => null;
             continue;
         }
@@ -229,24 +336,105 @@ const correctMissingRequired = (userProps, propsSpec) => {
 const calcDefaultsUsed = (propsSpec, userProps) => Object.fromEntries(Object.entries(propsSpec)
     .filter(([key, spec]) => spec.default !== undefined && !(key in userProps))
     .map(([key, spec]) => [key, spec.default]));
-/** React 변환 매핑 정보를 생성 */
-const buildReactOutput = (componentData, appliedProps, iconMeta) => {
-    const { exportName, importPath, props: propsSpec } = componentData;
-    const imports = [`import { ${exportName} } from '${importPath}';`];
-    const dependencies = [importPath];
-    const iconNames = extractIconNames(appliedProps);
-    if (iconNames.length > 0 && iconMeta) {
-        imports.push(`import { ${iconNames.join(', ')} } from '${iconMeta.packageName}';`);
-        if (!dependencies.includes(iconMeta.packageName)) {
-            dependencies.push(iconMeta.packageName);
+/** descriptor의 component 이름에서 해당 컴포넌트의 propsSpec을 조회 */
+const lookupPropsSpecByComponentName = (componentName, componentMap) => {
+    const dotIndex = componentName.indexOf('.');
+    if (dotIndex > 0) {
+        const parentName = componentName.slice(0, dotIndex).toLowerCase();
+        const subName = componentName.slice(dotIndex + 1);
+        const parentData = componentMap.get(parentName);
+        if (!parentData?.exportName)
+            return undefined;
+        const compoundKey = `${parentData.exportName}.${capitalize(subName)}`;
+        return parentData.subComponents?.[compoundKey]?.props;
+    }
+    return componentMap.get((0, response_js_1.normalizeName)(componentName))?.props;
+};
+/** descriptor/React element 트리를 JSX 문자열로 변환. spec을 따라 icon-component를 식별자로 직렬화하고 사용된 icon 이름을 누적 */
+const reactElementToJsx = (node, ctx) => {
+    if (node == null)
+        return '';
+    if (typeof node === 'string')
+        return node;
+    if (typeof node === 'number' || typeof node === 'boolean')
+        return String(node);
+    if (Array.isArray(node))
+        return node.map((n) => reactElementToJsx(n, ctx)).join('\n');
+    // Component descriptor: { component, props, children } — compound component 포함
+    if (typeof node === 'object' && 'component' in node) {
+        const desc = node;
+        const componentName = desc.component.trim();
+        const pascalName = componentName.split('.').map(capitalize).join('.');
+        const propsSpec = lookupPropsSpecByComponentName(componentName, ctx.componentMap);
+        // 이 descriptor에서 사용된 icon 이름 수집 (imports 생성용)
+        if (propsSpec && desc.props) {
+            for (const [key, spec] of Object.entries(propsSpec)) {
+                if (key in desc.props)
+                    collectIconNamesBySpec(desc.props[key], spec, ctx.iconNames);
+            }
+        }
+        const { children: descChildren, ...restProps } = desc.props || {};
+        const attrs = Object.entries(restProps)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => toJsxAttr(k, v, propsSpec?.[k]))
+            .join(' ');
+        const attrsStr = attrs ? ` ${attrs}` : '';
+        const inner = desc.children ?? descChildren;
+        if (inner != null) {
+            return `<${pascalName}${attrsStr}>${reactElementToJsx(inner, ctx)}</${pascalName}>`;
         }
+        return `<${pascalName}${attrsStr} />`;
     }
+    // React element: { type, props, ... } — spec 조회 불가 → 최소 직렬화
+    if (typeof node === 'object' && 'type' in node) {
+        const el = node;
+        const name = typeof el.type === 'string'
+            ? el.type
+            : typeof el.type === 'function'
+                ? el.type.displayName
+                    || el.type.name
+                    || 'Component'
+                : 'Component';
+        const { children: childChildren, ...restProps } = el.props || {};
+        const attrs = Object.entries(restProps)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => {
+            if (typeof v === 'boolean' && v)
+                return k;
+            if (typeof v === 'string')
+                return `${k}="${v}"`;
+            return `${k}={${JSON.stringify(v)}}`;
+        })
+            .join(' ');
+        const attrsStr = attrs ? ` ${attrs}` : '';
+        if (childChildren != null) {
+            return `<${name}${attrsStr}>${reactElementToJsx(childChildren, ctx)}</${name}>`;
+        }
+        return `<${name}${attrsStr} />`;
+    }
+    return String(node);
+};
+/** React 변환 매핑 정보를 생성 — top-level + 중첩 descriptor에서 사용된 icon을 모두 수집 */
+const buildReactOutput = (componentData, appliedProps, iconMeta, componentMap) => {
+    const { exportName, importPath, props: propsSpec } = componentData;
+    const dependencies = [importPath];
+    // top-level props에서 icon 이름 수집
+    const iconNames = new Set(extractIconNames(appliedProps, propsSpec));
     const attrsStr = propsSpec ? propsToJsxAttrs(appliedProps, propsSpec) : '';
     const attrsPrefix = attrsStr ? ' ' + attrsStr : '';
     const children = appliedProps.children;
+    // children 트리 직렬화 — 그 과정에서 중첩 descriptor의 icon도 누적
+    const jsxCtx = { componentMap, iconNames };
     const jsx = children
-        ? `<${exportName}${attrsPrefix}>${String(children)}</${exportName}>`
+        ? `<${exportName}${attrsPrefix}>${reactElementToJsx(children, jsxCtx)}</${exportName}>`
         : `<${exportName}${attrsPrefix} />`;
+    const imports = [`import { ${exportName} } from '${importPath}';`];
+    if (iconNames.size > 0 && iconMeta) {
+        imports.push(`import { ${[...iconNames].join(', ')} } from '${iconMeta.packageName}';`);
+        if (!dependencies.includes(iconMeta.packageName)) {
+            dependencies.push(iconMeta.packageName);
+        }
+    }
     return { imports, jsx, cssImport: `import '${importPath}/style.css';`, dependencies };
 };
 /** dataVersion 객체를 생성 */
@@ -283,11 +471,11 @@ const renderToHtml = (params) => {
         return (0, response_js_1.componentNotFoundResponse)(normalized);
     const exportName = componentData.exportName;
     if (!exportName) {
-        return (0, response_js_1.errorResponse)('EXPORT_NAME_MISSING', `'${normalized}' 컴포넌트에 exportName이 없습니다.`, '데이터를 재추출해주세요 (yarn extract).');
+        return (0, response_js_1.errorResponse)('EXPORT_NAME_MISSING', `'${normalized}' 컴포넌트에 exportName이 없습니다.`, '데이터를 재추출해주세요 (pnpm extract).');
     }
     const Component = bundle[exportName] ?? null;
     if (!Component) {
-        return (0, response_js_1.errorResponse)('COMPONENT_NOT_IN_BUNDLE', `'${normalized}' (${exportName}) 컴포넌트가 번들에 없습니다.`, '번들을 재빌드해주세요 (yarn build:bundle).');
+        return (0, response_js_1.errorResponse)('COMPONENT_NOT_IN_BUNDLE', `'${normalized}' (${exportName}) 컴포넌트가 번들에 없습니다.`, '번들을 재빌드해주세요 (pnpm build:bundle).');
     }
     try {
         const safeProps = removeBlockedProps(props ?? {});
@@ -317,11 +505,10 @@ const renderToHtml = (params) => {
             js: buildJsField(componentData, jsApiMap),
             cdn: cdnMeta ?? undefined,
             dataVersion: buildDataVersion(cdnMeta, iconMeta),
-            react: buildReactOutput(componentData, corrected, iconMeta),
+            react: buildReactOutput(componentData, corrected, iconMeta, componentMap),
         });
     }
     catch (err) {
-        // catch에서 warnings 재계산 (let 금지 규칙 준수 — validateProps는 순수 함수이므로 동일 결과 보장)
         const catchWarnings = componentData.props ? validateProps(props ?? {}, componentData.props) : [];
         const suggestion = componentData.usageExamples
             ? 'get_component_props로 usageExamples를 확인하고 해당 props로 재시도하세요.'

package/bin/types.d.ts

@@ -8,6 +8,8 @@ export interface PropSpec {
     values?: string[];
     rawType?: string;
     properties?: Record<string, PropSpec>;
+    /** 타입의 의미적 정체성 — 예: 'icon-component'는 SlotIconComponent 계열 아이콘 컴포넌트. renderer가 iconBundle resolve 대상 판정에 사용 */
+    semantic?: 'icon-component';
 }
 export interface ComponentUsage {
     import: string;
@@ -30,6 +32,11 @@ export interface ComponentData {
     /** render_to_html에 전달할 실제 사용 예시 props — meta.ts에서 추출 */
     usageExamples?: Record<string, Record<string, unknown>>;
     props: Record<string, PropSpec>;
+    /** Compound 컴포넌트의 서브 컴포넌트 props 스펙 — 예: Modal.Header, Table.Row
+     *  키는 "Modal.Header" 형태의 dot notation. 서브가 없으면 undefined. */
+    subComponents?: Record<string, {
+        props: Record<string, PropSpec>;
+    }>;
     html?: Record<string, string>;
     bemClasses: string[];
     usage: ComponentUsage;

package/bin/utils/bemValidator.d.ts

@@ -21,7 +21,7 @@ export declare const getClassList: (el: {
 export declare const buildRootClassMap: (componentMap: Map<string, ComponentData>) => Map<string, string>;
 /** 엘리먼트별 BEM 클래스 검증 → errors + warnings + invalidClasses 수집 */
 export declare const collectBemErrors: (params: {
-    elements: ReturnType<ReturnType<typeof parse>['querySelectorAll']>;
+    elements: ReturnType<ReturnType<typeof parse>["querySelectorAll"]>;
     rootClassMap: Map<string, string>;
     componentMap: Map<string, ComponentData>;
 }) => {

package/bin/utils/compliance.js

@@ -183,7 +183,9 @@ const buildComplianceSummary = (params) => {
         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 +
+    const ncuaNotUsedCount = ncuaErrors.length;
+    const totalCheckpoints = ncuaUsage.used +
+        ncuaNotUsedCount +
         (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));

package/bin/utils/dataLoader.d.ts

@@ -8,7 +8,6 @@ export interface CdnMeta {
 export interface IconMeta {
     packageName: string;
     version: string;
-    cdn: string;
 }
 /** data/ 디렉토리의 JSON 파일을 읽어 componentMap으로 반환 */
 export declare const loadComponentsFromDir: (dataDir: string) => Map<string, ComponentData>;

package/bin/utils/dataLoader.js

@@ -27,30 +27,22 @@ const isValidIconJson = (data) => !!data && typeof data === 'object' && 'icons'
 /** data/ 디렉토리의 JSON 파일을 읽어 componentMap으로 반환 */
 const loadComponentsFromDir = (dataDir) => {
     if (!fs_1.default.existsSync(dataDir)) {
-        logger_js_1.logger.error(`mcp/data/ 디렉토리가 없습니다: ${dataDir}`);
-        process.exit(1);
+        throw new Error(`mcp/data/ 디렉토리가 없습니다: ${dataDir}`);
     }
     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);
+        throw new Error(`mcp/data/ 디렉토리에 JSON 파일이 없습니다: ${dataDir}`);
     }
     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);
+        const raw = fs_1.default.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!isValidComponentJson(parsed)) {
+            throw new Error(`JSON 파싱 실패 (${file}): name 필드가 없거나 올바르지 않습니다`);
         }
+        const component = parsed;
+        map.set(component.name, component);
     }
     logger_js_1.logger.info(`컴포넌트 ${map.size}개 로딩 완료`);
     return map;

package/bin/utils/domEnvironment.js

@@ -46,6 +46,7 @@ const setupDomEnvironment = () => {
         globalThis.document = dom.window.document;
     if (typeof globalThis.window === 'undefined')
         globalThis.window = dom.window;
+    /* v8 ignore next 3 -- Node.js 환경에서 navigator 미존재 시 설정. 테스트 실행 순서에 따라 이미 설정된 경우 스킵 */
     if (typeof globalThis.navigator === 'undefined') {
         Object.defineProperty(globalThis, 'navigator', { value: dom.window.navigator, writable: true });
     }

package/bin/utils/fuzzyMatch.d.ts

@@ -5,6 +5,10 @@
  * - 부분 포함 ("비번" ⊂ "비밀번호"는 안 되지만, "로딩" ⊂ "로딩중"은 됨)
  * - 편집 거리(Levenshtein) 기반 오타 허용 ("셀랙트" ↔ "셀렉트", "buttn" ↔ "button")
  */
+/** Levenshtein 편집 거리 */
+export declare const editDistance: (a: string, b: string) => number;
+/** 편집 거리 기반 유사도 (0~1, 1이 완전 일치) */
+export declare const similarity: (a: string, b: string) => number;
 export interface FuzzyResult {
     score: number;
     matchType: 'exact' | 'contains' | 'fuzzy';

package/bin/utils/fuzzyMatch.js

@@ -7,7 +7,7 @@
  * - 편집 거리(Levenshtein) 기반 오타 허용 ("셀랙트" ↔ "셀렉트", "buttn" ↔ "button")
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.bestFuzzyMatch = exports.fuzzyMatch = void 0;
+exports.bestFuzzyMatch = exports.fuzzyMatch = exports.similarity = exports.editDistance = void 0;
 // ── 상수 ──────────────────────────────────────────────────────────
 /** 포함 매칭 시 기본 점수 */
 const CONTAINS_BASE_SCORE = 0.7;
@@ -49,6 +49,15 @@ const editDistance = (a, b) => {
     }
     return prev[n];
 };
+exports.editDistance = editDistance;
+/** 편집 거리 기반 유사도 (0~1, 1이 완전 일치) */
+const similarity = (a, b) => {
+    const maxLen = Math.max(a.length, b.length);
+    if (maxLen === 0)
+        return 1;
+    return 1 - (0, exports.editDistance)(a, b) / maxLen;
+};
+exports.similarity = similarity;
 /**
  * query가 target에 매칭되는지 퍼지 검사
  *
@@ -71,7 +80,7 @@ const fuzzyMatch = (query, target) => {
     // 3. 편집 거리 기반 퍼지 매칭
     const isShortQuery = q.length <= SHORT_QUERY_LENGTH;
     const typoThreshold = isShortQuery ? 1 : Math.ceil(q.length * TYPO_THRESHOLD_RATIO);
-    const dist = editDistance(q, t);
+    const dist = (0, exports.editDistance)(q, t);
     // target이 query보다 훨씬 길면, 부분 문자열 슬라이딩 윈도우로 비교
     const targetIsLonger = t.length > q.length + LENGTH_DIFF_FOR_SUBSTRING;
     const queryIsLongEnough = q.length >= SHORT_QUERY_LENGTH;
@@ -80,7 +89,7 @@ const fuzzyMatch = (query, target) => {
     if (shouldTrySubstringMatch) {
         for (let i = 0; i <= t.length - q.length; i++) {
             const sub = t.substring(i, i + q.length);
-            const subDist = editDistance(q, sub);
+            const subDist = (0, exports.editDistance)(q, sub);
             if (subDist <= typoThreshold) {
                 const subSimilarity = q.length === 0 ? 1 : 1 - subDist / q.length;
                 return { score: SUBSTRING_BASE_SCORE + SUBSTRING_BONUS_MULTIPLIER * subSimilarity, matchType: 'fuzzy' };