@ncds/ui-admin-mcp 1.0.0-alpha.18 → 1.0.0-alpha.20

package/bin/server.js

@@ -20,6 +20,7 @@ const zod_1 = require("zod");
 const getComponentProps_js_1 = require("./tools/getComponentProps.js");
 const getDesignTokens_js_1 = require("./tools/getDesignTokens.js");
 const listComponents_js_1 = require("./tools/listComponents.js");
+const listCompositionOverrides_js_1 = require("./tools/listCompositionOverrides.js");
 const listIcons_js_1 = require("./tools/listIcons.js");
 const ping_js_1 = require("./tools/ping.js");
 const renderToHtml_js_1 = require("./tools/renderToHtml.js");
@@ -63,6 +64,8 @@ const loadRules = (definitionsDir) => {
         'cdn',
         'react',
         'forbidden',
+        'composition',
+        'fontFamily',
         'customArea',
         'compliance',
         'category',
@@ -88,7 +91,7 @@ const main = async () => {
     const complianceRules = (0, dataLoader_js_1.loadComplianceRules)(definitionsDir);
     const jsApiMap = (0, dataLoader_js_1.loadJsApi)(definitionsDir);
     // ── 데이터 로딩 ──
-    const componentMap = (0, dataLoader_js_1.loadComponentsFromDir)(dataLoader_js_1.DEFAULT_DATA_DIR);
+    const { map: componentMap, compositionOverrides } = (0, dataLoader_js_1.loadComponentsFromDir)(dataLoader_js_1.DEFAULT_DATA_DIR);
     const { cdn: cdnMeta, icon: iconMeta } = (0, dataLoader_js_1.loadMeta)(dataLoader_js_1.DEFAULT_DATA_DIR);
     const iconData = (0, dataLoader_js_1.loadIconData)(dataLoader_js_1.DEFAULT_DATA_DIR);
     const tokenData = (0, dataLoader_js_1.loadTokenData)(dataLoader_js_1.DEFAULT_DATA_DIR);
@@ -116,6 +119,7 @@ const main = async () => {
     const iconSummary = (0, listIcons_js_1.buildIconSummary)(iconData);
     const listComponentsResponse = (0, listComponents_js_1.buildListComponentsResponse)(groupedComponents);
     const listIconsResponse = (0, listIcons_js_1.buildListIconsResponse)(iconSummary);
+    const listCompositionOverridesResponse = (0, listCompositionOverrides_js_1.buildListCompositionOverridesResponse)(compositionOverrides, componentMap);
     // ── MCP 서버 생성 + tool 등록 ──
     const server = new mcp_js_1.McpServer({ name: 'ncds-ui-admin', version: version_js_1.VERSION }, { instructions });
     // ping 호출 추적 — 미호출 시 다른 tool 응답에 핵심 rules 주입 (세션 레벨 상태, let 의도적 사용)
@@ -135,6 +139,7 @@ const main = async () => {
         inputSchema: { query: zod_1.z.string().describe('Search keyword (e.g. "search", "alert", "arrow")') },
     }, ({ query }) => withPingReminder((0, searchIcon_js_1.searchIcon)(iconData, query)));
     server.registerTool('list_components', { description: descriptions['list_components'] }, () => withPingReminder((0, listComponents_js_1.listComponents)(listComponentsResponse)));
+    server.registerTool('list_composition_overrides', { description: descriptions['list_composition_overrides'] }, () => withPingReminder((0, listCompositionOverrides_js_1.listCompositionOverrides)(listCompositionOverridesResponse)));
     server.registerTool('search_component', {
         description: descriptions['search_component'],
         inputSchema: { query: zod_1.z.string().describe('Search keyword (Korean/English, case-insensitive)') },

package/bin/tools/getComponentProps.js

@@ -16,6 +16,11 @@ const getComponentProps = (componentMap, name) => {
         props: component.props,
         ...(component.subComponents && { subComponents: component.subComponents }),
         ...(component.usageExamples && { usageExamples: component.usageExamples }),
+        // P8: composition overrides 에서 병합되는 필드들 — AI 가 부모-자식 관계와 권장 조합을 우선 학습
+        ...(component.allowedChildren && { allowedChildren: component.allowedChildren }),
+        ...(component.allowedParents && { allowedParents: component.allowedParents }),
+        ...(component.canonicalExample && { canonicalExample: component.canonicalExample }),
+        ...(component.canonicalExamples && { canonicalExamples: component.canonicalExamples }),
     });
 };
 exports.getComponentProps = getComponentProps;

package/bin/tools/listCompositionOverrides.d.ts

@@ -0,0 +1,61 @@
+/**
+ * list_composition_overrides tool — composition.json composition overrides 적용 현황 요약
+ *
+ * 신규 프로젝트에서 NCDS MCP 와 연결한 뒤, 어느 컴포넌트에 어떤 composition overrides 보강이
+ * 들어가 있는지 표 형태(컴포넌트별 row)로 한 번에 확인하는 용도. 응답이 크지 않도록
+ * 시나리오 키 목록 + 카운트 위주로 구성하고, 상세는 get_component_props 로 유도.
+ *
+ * 순수 함수 — server.ts 부팅 시 1회 buildListCompositionOverridesResponse() 로 사전 직렬화.
+ */
+import type { ComponentData } from '../types.js';
+import type { CompositionEntry } from '../utils/dataLoader.js';
+import { type McpToolResponse } from '../utils/response.js';
+export interface CompositionOverrideSummary {
+    /** 컴포넌트 이름 (kebab-case) */
+    component: string;
+    /** canonicalExamples 시나리오 key 목록 — 비어있으면 [] */
+    canonicalExamples: string[];
+    /** legacy 단일 시나리오 canonicalExample 존재 여부 */
+    hasCanonicalExample: boolean;
+    /** bemClassesExtra 항목 수 */
+    bemClassesExtra: number;
+    /** allowedChildren 정의된 부모 키 목록 (예: ["Table", "Table.Header", ...]) */
+    allowedChildrenKeys: string[];
+    /** allowedParents 정의된 자식 키 목록 */
+    allowedParentsKeys: string[];
+    /** descriptionExtra 존재 여부 */
+    descriptionExtra: boolean;
+    /** aliasesExtra 항목 수 */
+    aliasesExtra: number;
+    /**
+     * 자기 카테고리 천장 대비 정규화 점수 (0.0 ~ 1.0).
+     * 1.0 = 컴포넌트 구조상 가능한 모든 보강 영역을 완료.
+     * compound 는 5 영역, non-compound 는 4 영역 (allowedChildren n/a 제외) 기준으로 정규화되어
+     * 컴포넌트 종류 무관하게 동일 척도로 비교 가능.
+     */
+    coverageScore: number;
+    /**
+     * 컴포넌트 구조상 적용 불가한 보강 영역 목록 (예: non-compound 는 ['allowedChildren']).
+     * 비어있으면 모든 영역이 적용 가능 (compound).
+     * coverageScore 분모에서 자동 제외되어 천장이 1.0 으로 통일된다.
+     */
+    notApplicable: string[];
+    /** coverageScore 한 줄 해석 — high/medium/low 와 강점 영역 요약 */
+    coverageNote: string;
+}
+export interface ListCompositionOverridesResult {
+    /** composition overrides 적용 컴포넌트 수 */
+    total: number;
+    /** 각 척도가 무엇을 의미하고 AI 의 UI 작성 정확도에 어떻게 영향을 주는지 (AI 가 본 응답을 바로 해석하도록 동봉) */
+    metrics: Record<string, string>;
+    /** coverageScore 산식 (가중치 명시) */
+    coverageScoreFormula: string;
+    /** 컴포넌트별 요약 row 배열 — coverageScore 내림차순, 동률은 컴포넌트 이름 알파벳 */
+    overrides: CompositionOverrideSummary[];
+}
+/** composition overrides map → 요약 결과 (순수 함수). coverageScore 내림차순 + 동률은 이름 알파벳. */
+export declare const buildCompositionOverridesSummary: (compositionOverrides: Record<string, CompositionEntry>, componentMap: Map<string, ComponentData>) => ListCompositionOverridesResult;
+/** server.ts 부팅 시 1회 호출 — 응답 사전 직렬화 */
+export declare const buildListCompositionOverridesResponse: (compositionOverrides: Record<string, CompositionEntry>, componentMap: Map<string, ComponentData>) => McpToolResponse;
+/** list_composition_overrides tool — 사전 직렬화된 응답을 그대로 반환 */
+export declare const listCompositionOverrides: (prebuilt: McpToolResponse) => McpToolResponse;

package/bin/tools/listCompositionOverrides.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCompositionOverrides = exports.buildListCompositionOverridesResponse = exports.buildCompositionOverridesSummary = void 0;
+const response_js_1 = require("../utils/response.js");
+/**
+ * coverageScore 가중치 — 각 보강 영역의 점수 기여도.
+ * 시나리오(canonicalExamples)가 가장 큰 가중치를 가지는 이유: AI hallucination 차단력이 가장 큼.
+ */
+const COVERAGE_WEIGHTS = {
+    CANONICAL_EXAMPLES_FULL: 0.5,
+    CANONICAL_EXAMPLES_PARTIAL: 0.25,
+    ALLOWED_CHILDREN_FULL: 0.2,
+    ALLOWED_CHILDREN_PARTIAL: 0.1,
+    BEM_CLASSES_EXTRA: 0.1,
+    DESCRIPTION_EXTRA: 0.1,
+    ALIASES_EXTRA: 0.1,
+};
+/**
+ * 전체 가중치 합 (5 영역 모두 적용 가능한 경우의 최대).
+ * applicableMax = TOTAL_WEIGHT - Σ(notApplicable 영역 가중치) 로 동적 계산.
+ */
+const TOTAL_WEIGHT = 1.0;
+/**
+ * 영역별 가중치 맵 — applicableMax 동적 계산 시 사용.
+ * canonicalExamples 는 항상 적용 가능하므로 포함하지 않음 (분모에서 제외되지 않음).
+ */
+const AREA_WEIGHT_MAP = {
+    allowedChildren: COVERAGE_WEIGHTS.ALLOWED_CHILDREN_FULL,
+    bemClassesExtra: COVERAGE_WEIGHTS.BEM_CLASSES_EXTRA,
+    descriptionExtra: COVERAGE_WEIGHTS.DESCRIPTION_EXTRA,
+    aliasesExtra: COVERAGE_WEIGHTS.ALIASES_EXTRA,
+};
+/** coverageNote tier 임계값. */
+const TIER_THRESHOLD_HIGH = 0.7;
+const TIER_THRESHOLD_MEDIUM = 0.4;
+/** 점수 cap (이론적 최대값). */
+const SCORE_CAP = 1;
+/** 소수점 2자리 반올림용 — `Math.round(x * 100) / 100`. */
+const TWO_DECIMAL_BASE = 100;
+/** AI 가 UI 를 얼마나 정확히 그릴 수 있는지 추정 — 각 composition overrides 보강이 다른 정확도 영역을 커버한다 */
+const METRIC_DESCRIPTIONS = {
+    canonicalExamples: 'AI 가 시나리오별로 분기 가능한 정답 트리 수 (form / data-grid / with-tooltip 등). 가장 강한 정확도 신호 — 0 이면 AI 가 prop 조합을 추측해야 한다.',
+    hasCanonicalExample: 'legacy 단일 시나리오 존재 여부 — 진입용 표준 트리 1건. canonicalExamples 가 비어있는 컴포넌트의 fallback.',
+    bemClassesExtra: 'extract 가 못 잡은 BEM 클래스 화이트리스트 수. validate_html 이 합법/위법을 정확히 판정 — 발명 클래스 사용 차단력.',
+    allowedChildrenKeys: 'compound 부모-자식 제약 노드 수. 잘못된 자식 끼우기 / 컨텍스트 위반 (Table.Pagination in DataGrid 등) 차단력.',
+    allowedParentsKeys: '역방향 제약 노드 수 — 자식이 어느 부모 안에만 허용되는지 명시.',
+    descriptionExtra: 'list_components 응답에 자연어 용도/모드 명시 여부. 같은 컴포넌트가 다른 모드(horizontal/vertical) 로 쓰일 때 AI 가 모드를 인지하는 정확도.',
+    aliasesExtra: 'search_component 한국어/유사 키워드 매칭 별칭 수. AI 가 "폼 레이아웃", "세로 테이블" 같은 비공식 용어로 검색해도 정답 컴포넌트에 도달.',
+    coverageScore: '자기 카테고리 천장 대비 정규화 점수 (0.0 ~ 1.0). 1.0 이면 컴포넌트 구조상 가능한 모든 보강 영역을 완료. applicableMax = 1.0 − Σ(notApplicable 영역 가중치)로 동적 계산되어 모든 컴포넌트가 동일 척도. 절대 가중합이 아니라 정규화 비율이므로 컴포넌트 종류 무관하게 직접 비교 가능.',
+    notApplicable: '컴포넌트 구조상 적용 불가한 보강 영역 목록. non-compound 는 자동으로 ["allowedChildren"] 포함 (자식 없어 부모-자식 제약 의미 없음). composition.json notApplicableAreas 선언(예: extract 가 BEM 을 완전히 잡는 컴포넌트 → ["bemClassesExtra"])과 union 되어 최종 notApplicable 결정. 점수 분모에서 자동 제외되어 천장이 1.0 으로 통일된다.',
+};
+const COVERAGE_FORMULA = 'rawScore (가중 합) = canonicalExamples>=2: +0.50 (>=1 또는 hasCanonicalExample: +0.25) + allowedChildrenKeys>=2: +0.20 (>=1: +0.10, compound 만 적용) + bemClassesExtra>=1: +0.10 + descriptionExtra: +0.10 + aliasesExtra>=1: +0.10. applicableMax = 1.0 − Σ(notApplicable 영역 가중치) — non-compound 는 자동으로 allowedChildren(0.20) 제외, composition.json notApplicableAreas 선언 시 해당 가중치 추가 차감. coverageScore = rawScore / applicableMax (Math.min(1.0, ...)). 임계값: high>=0.70, medium>=0.40, 그 외 low. coverageScore 1.0 = 자기 카테고리에서 더 채울 영역 없음.';
+/** 적용 가능 영역의 절대 가중치 합 (정규화 전 raw 점수). */
+const computeRawScore = (s) => {
+    let score = 0;
+    if (s.canonicalExamples.length >= 2)
+        score += COVERAGE_WEIGHTS.CANONICAL_EXAMPLES_FULL;
+    else if (s.canonicalExamples.length >= 1 || s.hasCanonicalExample)
+        score += COVERAGE_WEIGHTS.CANONICAL_EXAMPLES_PARTIAL;
+    if (s.allowedChildrenKeys.length >= 2)
+        score += COVERAGE_WEIGHTS.ALLOWED_CHILDREN_FULL;
+    else if (s.allowedChildrenKeys.length >= 1)
+        score += COVERAGE_WEIGHTS.ALLOWED_CHILDREN_PARTIAL;
+    if (s.bemClassesExtra >= 1)
+        score += COVERAGE_WEIGHTS.BEM_CLASSES_EXTRA;
+    if (s.descriptionExtra)
+        score += COVERAGE_WEIGHTS.DESCRIPTION_EXTRA;
+    if (s.aliasesExtra >= 1)
+        score += COVERAGE_WEIGHTS.ALIASES_EXTRA;
+    return score;
+};
+/**
+ * 컴포넌트의 notApplicable 영역 목록.
+ * 구조적 제외(non-compound → allowedChildren) + entry 의 notApplicableAreas 선언을 union.
+ */
+const getNotApplicable = (isCompound, entryNotApplicableAreas) => {
+    const structural = isCompound ? [] : ['allowedChildren'];
+    return [...new Set([...structural, ...entryNotApplicableAreas])];
+};
+/**
+ * applicableMax = TOTAL_WEIGHT - Σ(notApplicable 영역 가중치).
+ * compound 기본: 1.0. non-compound 기본: 0.8 (allowedChildren 0.2 제외).
+ * notApplicableAreas 추가 선언 시 해당 가중치만큼 추가 차감 → coverageScore 1.0 = 실제 달성 가능 최대.
+ */
+const getApplicableMax = (notApplicable) => {
+    const excluded = notApplicable.reduce((sum, area) => sum + (AREA_WEIGHT_MAP[area] ?? 0), 0);
+    return Math.round((TOTAL_WEIGHT - excluded) * TWO_DECIMAL_BASE) / TWO_DECIMAL_BASE;
+};
+/** rawScore → coverageScore (자기 카테고리 천장 기준 0~1.0 정규화). */
+const normalizeScore = (rawScore, applicableMax) => Math.min(SCORE_CAP, Math.round((rawScore / applicableMax) * TWO_DECIMAL_BASE) / TWO_DECIMAL_BASE);
+/** coverageScore 를 high/medium/low tier 로 분류. */
+const getTier = (score) => {
+    if (score >= TIER_THRESHOLD_HIGH)
+        return 'high';
+    if (score >= TIER_THRESHOLD_MEDIUM)
+        return 'medium';
+    return 'low';
+};
+const noteFor = (s, score) => {
+    const strengths = [];
+    if (s.canonicalExamples.length >= 2)
+        strengths.push(`시나리오 ${s.canonicalExamples.length}`);
+    else if (s.canonicalExamples.length >= 1 || s.hasCanonicalExample)
+        strengths.push('시나리오 1');
+    if (s.allowedChildrenKeys.length >= 1)
+        strengths.push(`compound 제약 ${s.allowedChildrenKeys.length}`);
+    if (s.bemClassesExtra >= 1)
+        strengths.push(`BEM 화이트리스트 ${s.bemClassesExtra}`);
+    if (s.descriptionExtra)
+        strengths.push('모드 인지 보강');
+    if (s.aliasesExtra >= 1)
+        strengths.push(`검색 별칭 ${s.aliasesExtra}`);
+    const tier = getTier(score);
+    return strengths.length > 0
+        ? `${tier} · ${strengths.join(' + ')}`
+        : `${tier} · 보강 거의 없음 — 직접 작성 hallucination 위험`;
+};
+/** 단일 entry 를 row 로 변환 — compound 여부에 따라 applicableMax 가 결정되고 coverageScore 가 정규화된다. */
+const toSummary = (component, entry, componentMap) => {
+    const base = {
+        component,
+        canonicalExamples: Object.keys(entry.canonicalExamples ?? {}).filter((k) => !k.startsWith('_')),
+        hasCanonicalExample: !!entry.canonicalExample,
+        bemClassesExtra: (entry.bemClassesExtra ?? []).length,
+        allowedChildrenKeys: Object.keys(entry.allowedChildren ?? {}),
+        allowedParentsKeys: Object.keys(entry.allowedParents ?? {}),
+        descriptionExtra: !!entry.descriptionExtra,
+        aliasesExtra: (entry.aliasesExtra ?? []).length,
+    };
+    const subComponentCount = Object.keys(componentMap.get(component)?.subComponents ?? {}).length;
+    const isCompound = subComponentCount > 0;
+    const notApplicable = getNotApplicable(isCompound, entry.notApplicableAreas ?? []);
+    const applicableMax = getApplicableMax(notApplicable);
+    const rawScore = computeRawScore(base);
+    const coverageScore = normalizeScore(rawScore, applicableMax);
+    return { ...base, coverageScore, notApplicable, coverageNote: noteFor(base, coverageScore) };
+};
+/** composition overrides map → 요약 결과 (순수 함수). coverageScore 내림차순 + 동률은 이름 알파벳. */
+const buildCompositionOverridesSummary = (compositionOverrides, componentMap) => {
+    const overrides = Object.entries(compositionOverrides)
+        .map(([component, entry]) => toSummary(component, entry, componentMap))
+        .sort((a, b) => b.coverageScore - a.coverageScore || a.component.localeCompare(b.component));
+    return {
+        total: overrides.length,
+        metrics: METRIC_DESCRIPTIONS,
+        coverageScoreFormula: COVERAGE_FORMULA,
+        overrides,
+    };
+};
+exports.buildCompositionOverridesSummary = buildCompositionOverridesSummary;
+/** server.ts 부팅 시 1회 호출 — 응답 사전 직렬화 */
+const buildListCompositionOverridesResponse = (compositionOverrides, componentMap) => (0, response_js_1.successResponse)((0, exports.buildCompositionOverridesSummary)(compositionOverrides, componentMap));
+exports.buildListCompositionOverridesResponse = buildListCompositionOverridesResponse;
+/** list_composition_overrides tool — 사전 직렬화된 응답을 그대로 반환 */
+const listCompositionOverrides = (prebuilt) => prebuilt;
+exports.listCompositionOverrides = listCompositionOverrides;

package/bin/tools/renderToHtml.d.ts

@@ -34,5 +34,19 @@ export declare const mergeCdnDefaults: (componentName: string, cdnDefaults: Reco
     merged: Record<string, unknown>;
     defaultsApplied: string[];
 };
+/** jsRequired에 따라 js 필드를 생성 */
+export declare const buildJsField: (componentData: ComponentData, jsApiMap: Map<string, JsApiInfo>) => {
+    required: false;
+} | {
+    api?: {
+        className: string;
+        constructor: string;
+        constructorParams: Record<string, string>;
+        methods: string[];
+        example: string;
+    } | undefined;
+    required: true;
+    description: string;
+};
 /** render_to_html tool — props로 React 컴포넌트를 렌더링하여 HTML + React 매핑 반환 */
 export declare const renderToHtml: (params: RenderToHtmlParams) => McpToolResponse;

package/bin/tools/renderToHtml.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderToHtml = exports.mergeCdnDefaults = exports.stripFunctionProps = void 0;
+exports.renderToHtml = exports.buildJsField = exports.mergeCdnDefaults = exports.stripFunctionProps = void 0;
 /**
  * render_to_html tool — 컴포넌트 속성을 전달하면 정확한 HTML + React 매핑을 반환 (순수 함수)
  *
@@ -29,49 +29,106 @@ const MAX_SPEC_DEPTH = 6;
 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" → { Component, propsSpec } */
+/** kebab-case → PascalCase 변환: "action-bar" → "ActionBar", "header-cell" → "HeaderCell" */
+const kebabToPascal = (s) => s.split('-').map(capitalize).join('');
+/** PascalCase → kebab-case 변환: "DataGrid" → "data-grid", "PageTitle" → "page-title" */
+const pascalToKebab = (s) => s.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+/** 단순 컴포넌트 resolve: "button" → { Component, propsSpec, compoundKey: null } */
 const resolveSimpleComponent = (name, ctx) => {
     const normalized = (0, response_js_1.normalizeName)(name);
     const childData = ctx.componentMap.get(normalized);
     const Component = childData?.exportName ? (ctx.bundle[childData.exportName] ?? null) : null;
-    return { Component, propsSpec: childData?.props };
+    return { Component, propsSpec: childData?.props, compoundKey: null };
 };
-/** compound component resolve: "modal.header" → { Component: bundle.Modal.Header, propsSpec: subComponents["Modal.Header"].props } */
+/** compound component resolve: "data-grid.action-bar" → { Component: bundle.DataGrid.ActionBar, propsSpec: subComponents["DataGrid.ActionBar"].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 { Component: null, propsSpec: undefined };
+        return { Component: null, propsSpec: undefined, compoundKey: null };
     const Parent = ctx.bundle[parentExportName];
-    const Component = Parent?.[capitalize(subName)] ?? null;
-    // subComponents key는 "Modal.Header" 형태 (parent export name + sub name)
-    const compoundKey = `${parentExportName}.${capitalize(subName)}`;
+    // kebab→PascalCase: "action-bar" → "ActionBar". 단일 워드도 정상 동작 ("header" → "Header").
+    const pascalSubName = kebabToPascal(subName);
+    const Component = Parent?.[pascalSubName] ?? null;
+    // subComponents key는 "DataGrid.ActionBar" 형태 (parent export name + PascalCase sub name)
+    const compoundKey = `${parentExportName}.${pascalSubName}`;
     const propsSpec = parentData?.subComponents?.[compoundKey]?.props;
-    return { Component, propsSpec };
+    return { Component, propsSpec, compoundKey };
 };
-/** children JSON을 재귀적으로 React element로 변환 */
+/**
+ * 부모 컴포넌트의 allowedChildren[parentKey].forbiddenInContext 에 자식 compound key 가 있는지 검사.
+ * 위반 시 disallowedChildren 응답 entry 생성 (silent drop 의도)
+ */
+const checkForbiddenInContext = (parentKey, childCompoundKey, parentComponentData) => {
+    const allowed = parentComponentData?.allowedChildren?.[parentKey];
+    if (!allowed || Array.isArray(allowed))
+        return null; // 단순 배열 형식은 forbiddenInContext 없음
+    const forbidden = allowed.forbiddenInContext;
+    if (!forbidden)
+        return null;
+    const message = forbidden[childCompoundKey];
+    if (!message)
+        return null;
+    return { reason: 'forbidden_in_context', message };
+};
+/** children JSON을 재귀적으로 React element로 변환 — silent drop 차단 + composition 제약 검증 */
 const resolveChildren = (children, ctx, depth) => {
     if (depth > MAX_CHILDREN_DEPTH)
         return null;
     // 문자열/숫자/boolean — 그대로 반환
     if (typeof children === 'string' || typeof children === 'number' || typeof children === 'boolean')
         return children;
-    // 배열 — 각 요소를 재귀 처리 (MAX_CHILDREN_COUNT 제한)
+    // 배열 — 각 요소를 재귀 처리 (MAX_CHILDREN_COUNT 제한, undefined/null 결과 filter)
     if (Array.isArray(children)) {
-        return children.slice(0, MAX_CHILDREN_COUNT).map((child) => resolveChildren(child, ctx, depth));
+        const limited = children.slice(0, MAX_CHILDREN_COUNT);
+        const results = [];
+        limited.forEach((child, idx) => {
+            const childCtx = { ...ctx, path: `${ctx.path}[${idx}]` };
+            const resolved = resolveChildren(child, childCtx, depth);
+            if (resolved !== null && resolved !== undefined)
+                results.push(resolved);
+        });
+        return results;
     }
     // { component, props?, children? } — React element로 변환
     if (isChildDescriptor(children)) {
         const componentName = children.component.trim();
         const dotIndex = componentName.indexOf('.');
-        // dot notation: "modal.header" → bundle.Modal.Header (+ subComponents props spec)
-        const { Component, propsSpec } = dotIndex > 0
+        // dot notation: "data-grid.action-bar" → bundle.DataGrid.ActionBar (+ subComponents props spec)
+        const resolved = dotIndex > 0
             ? resolveCompoundComponent(componentName, dotIndex, ctx)
             : resolveSimpleComponent(componentName, ctx);
-        if (!Component)
+        const { Component, propsSpec, compoundKey } = resolved;
+        // ── 갭 해소 1: forbiddenInContext 검증 (resolve 가 성공해도 컨텍스트 위반은 차단) ──
+        if (Component && compoundKey && ctx.parentKey) {
+            // ctx.parentKey 는 PascalCase ("DataGrid" 또는 "DataGrid.Table") — componentMap 키는 kebab-case 이므로 변환
+            const rootParentExport = ctx.parentKey.split('.')[0]; // "DataGrid"
+            const parentName = pascalToKebab(rootParentExport); // "data-grid"
+            const parentData = ctx.componentMap.get(parentName);
+            const forbidden = checkForbiddenInContext(ctx.parentKey, compoundKey, parentData);
+            if (forbidden) {
+                ctx.disallowedChildren.push({
+                    path: ctx.path,
+                    parent: ctx.parentKey,
+                    child: compoundKey,
+                    reason: forbidden.reason,
+                    message: forbidden.message,
+                });
+                ctx.warnings.push(`${componentName} 은(는) ${ctx.parentKey} 안에서 사용할 수 없음: ${forbidden.message}`);
+                return null; // silent drop
+            }
+        }
+        // ── 갭 해소 2: lookup 실패 → unknownChildren 보고 (silent drop 차단) ──
+        if (!Component) {
+            const reason = dotIndex > 0 ? 'unknown_subcomponent' : 'unknown_component';
+            ctx.unknownChildren.push({ path: ctx.path, component: componentName, reason });
+            ctx.warnings.push(reason === 'unknown_subcomponent'
+                ? `'${componentName}' 은(는) 알 수 없는 sub-component. get_component_props 로 subComponents 확인 후 정정.`
+                : `'${componentName}' 은(는) 알 수 없는 component. list_components 로 정식 이름 확인 후 정정.`);
             return null;
+        }
         // BLOCKED_PROPS(dangerouslySetInnerHTML, ref, __self, __source)를 먼저 제거
         // propsSpec이 있으면 화이트리스트 필터(sanitizeProps)도 적용하여 XSS/alien prop 차단
         const rawProps = children.props ?? {};
@@ -80,7 +137,13 @@ const resolveChildren = (children, ctx, depth) => {
         // descriptor의 children 필드가 있으면 props.children보다 우선
         const rawChildren = children.children !== undefined ? children.children : childProps.children;
         if (rawChildren !== undefined) {
-            childProps.children = resolveChildren(rawChildren, ctx, depth + 1);
+            // 자식 재귀 시 parentKey 전파 — forbiddenInContext 검증에 사용
+            const nestedCtx = {
+                ...ctx,
+                parentKey: compoundKey ?? ctx.parentKey,
+                path: `${ctx.path}>${componentName}`,
+            };
+            childProps.children = resolveChildren(rawChildren, nestedCtx, depth + 1);
         }
         const resolvedProps = resolveIconProps(childProps, ctx.iconBundle, propsSpec);
         return ctx.reactRuntime.createElement(Component, resolvedProps);
@@ -533,7 +596,7 @@ const lookupPropsSpecByComponentName = (componentName, componentMap) => {
         const parentData = componentMap.get(parentName);
         if (!parentData?.exportName)
             return undefined;
-        const compoundKey = `${parentData.exportName}.${capitalize(subName)}`;
+        const compoundKey = `${parentData.exportName}.${kebabToPascal(subName)}`;
         return parentData.subComponents?.[compoundKey]?.props;
     }
     return componentMap.get((0, response_js_1.normalizeName)(componentName))?.props;
@@ -552,7 +615,8 @@ const reactElementToJsx = (node, ctx) => {
     if (typeof node === 'object' && 'component' in node) {
         const desc = node;
         const componentName = desc.component.trim();
-        const pascalName = componentName.split('.').map(capitalize).join('.');
+        // "data-grid.action-bar" → "DataGrid.ActionBar" (kebab→PascalCase per dot segment)
+        const pascalName = componentName.split('.').map(kebabToPascal).join('.');
         const propsSpec = lookupPropsSpecByComponentName(componentName, ctx.componentMap);
         // 이 descriptor에서 사용된 icon 이름 수집 (imports 생성용)
         if (propsSpec && desc.props) {
@@ -649,6 +713,7 @@ const buildJsField = (componentData, jsApiMap) => {
         }),
     };
 };
+exports.buildJsField = buildJsField;
 // ── 진입점 ────────────────────────────────────────────────────────
 /** render_to_html tool — props로 React 컴포넌트를 렌더링하여 HTML + React 매핑 반환 */
 const renderToHtml = (params) => {
@@ -702,10 +767,45 @@ const renderToHtml = (params) => {
             ...cdnNormalization.warnings,
         ];
         const resolvedProps = resolveIconProps(corrected, iconBundle, componentData.props);
-        // children이 컴포넌트 descriptor면 React element로 변환
-        if (resolvedProps.children !== undefined) {
-            const ctx = { bundle, iconBundle, componentMap, reactRuntime };
-            resolvedProps.children = resolveChildren(resolvedProps.children, ctx, 0);
+        // P12: children + 모든 ReactNode prop 에 대해 component descriptor 자동 resolve.
+        // PageTitle.primaryAction / Modal.actions / BlockHeader.tooltip 같은 ReactNode prop 에
+        // {component, props, children} descriptor 또는 그 배열을 넘기면 React element 로 변환.
+        // children 외 ReactNode prop 도 동일 흐름 — godomall5 결과물에서 PageTitle action 이
+        // 빈 상태로 떨어진 근본 원인(ReactNode prop 자동 resolve 부재) 해결.
+        // Epic 7: resolveChildren 결과(unknown/disallowed/추가 warnings)를 누적할 ctx 초기화.
+        // ctx 는 children 처리 전체에서 공유되어 silent drop 차단 + composition 제약 검증을 수행한다.
+        const renderCtx = {
+            bundle,
+            iconBundle,
+            componentMap,
+            reactRuntime,
+            warnings: [],
+            unknownChildren: [],
+            disallowedChildren: [],
+            parentKey: exportName, // 최상위 부모 키 (compound parent lookup 시작점)
+            path: normalized,
+        };
+        if (resolvedProps.children !== undefined || componentData.props) {
+            if (resolvedProps.children !== undefined) {
+                resolvedProps.children = resolveChildren(resolvedProps.children, renderCtx, 0);
+            }
+            // children 이외의 ReactNode prop 들 — propsSpec.type === 'ReactNode' 인 키 전부 처리
+            if (componentData.props) {
+                for (const [key, spec] of Object.entries(componentData.props)) {
+                    if (key === 'children')
+                        continue; // 위에서 처리됨
+                    if (spec.type !== 'ReactNode')
+                        continue;
+                    const val = resolvedProps[key];
+                    if (val === undefined || val === null)
+                        continue;
+                    // string / number / boolean primitive 는 React 가 직접 렌더 — 건드리지 않음
+                    if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean')
+                        continue;
+                    // component descriptor 또는 그 배열인 경우만 resolve
+                    resolvedProps[key] = resolveChildren(val, renderCtx, 0);
+                }
+            }
         }
         // HTML 출력: CDN-input은 init script, 그 외는 React 정적 HTML (renderToStaticMarkup은 필요할 때만 호출)
         const cdnInitScript = isCdnInput && jsApi?.cdnPattern
@@ -723,6 +823,8 @@ const renderToHtml = (params) => {
             ? Object.fromEntries(cdnMergeResult.defaultsApplied.map((key) => [key, jsApi.cdnDefaults?.[key]]))
             : {};
         const finalDefaultsUsed = { ...hasDefaults, ...cdnDefaultsApplied };
+        // Epic 7: prop warnings + children resolve warnings 통합
+        const allWarnings = [...warnings, ...renderCtx.warnings];
         return (0, response_js_1.successResponse)({
             html,
             component: normalized,
@@ -730,8 +832,10 @@ const renderToHtml = (params) => {
             importPath: componentData.importPath,
             appliedProps: corrected,
             ...(Object.keys(finalDefaultsUsed).length > 0 && { defaultsUsed: finalDefaultsUsed }),
-            ...(warnings.length > 0 && { warnings }),
-            js: buildJsField(componentData, jsApiMap),
+            ...(allWarnings.length > 0 && { warnings: allWarnings }),
+            ...(renderCtx.unknownChildren.length > 0 && { unknownChildren: renderCtx.unknownChildren }),
+            ...(renderCtx.disallowedChildren.length > 0 && { disallowedChildren: renderCtx.disallowedChildren }),
+            js: (0, exports.buildJsField)(componentData, jsApiMap),
             cdn: cdnMeta ?? undefined,
             dataVersion: buildDataVersion(cdnMeta, iconMeta),
             react: buildReactOutput(componentData, corrected, iconMeta, componentMap),

package/bin/tools/validateHtml.js

@@ -29,6 +29,9 @@ const validateHtml = (params) => {
         return (0, response_js_1.successResponse)({ valid: true });
     if (cdnMeta)
         errors.push(...(0, bemValidator_js_1.checkCdnInclusion)(trimmed, cdnMeta));
+    // P13: Vertical Table context 검증 + 페이지 prefix required 마크 검출
+    errors.push(...collectVerticalTableContextErrors(root));
+    warnings.push(...collectCustomRequiredMarkWarnings(root));
     const compliance = buildCompliance({
         root,
         componentMap,
@@ -62,6 +65,71 @@ const buildCompliance = (params) => {
         customSeparation: customResult.customSeparation,
     });
 };
+/** P13: Vertical Table context 위반 검출.
+ *  1) ncua-table--vertical 안 ncua-table__header-cell → horizontal 전용 오용.
+ *  2) ncua-table 안 <tr> 에 ncua-table__row 클래스 누락. */
+const collectVerticalTableContextErrors = (root) => {
+    const errors = [];
+    // (1) vertical 안의 header-cell 검출
+    const verticalRoots = root.querySelectorAll('.ncua-table--vertical');
+    for (const v of verticalRoots) {
+        const headerCells = v.querySelectorAll('.ncua-table__header-cell');
+        for (const _ of headerCells) {
+            errors.push({
+                type: 'vertical_uses_horizontal_header_cell',
+                class: 'ncua-table__header-cell',
+                component: 'table',
+                message: "Vertical Table 안에서 'ncua-table__header-cell' 사용은 horizontal 전용 — vertical 라벨에는 <th scope='row' class='ncua-table__cell'> 사용 (Table.Cell with isHeader=true).",
+                suggestion: "render_to_html('table', { type: 'vertical', children: [...] }) 호출하여 정확한 BEM 출력을 받거나, <th class='ncua-table__header-cell'> 을 <th scope='row' class='ncua-table__cell'> 로 교체.",
+            });
+        }
+    }
+    // (2) ncua-table 안 <tr> 의 ncua-table__row 클래스 누락
+    const allTables = root.querySelectorAll('.ncua-table');
+    for (const t of allTables) {
+        const trs = t.querySelectorAll('tr');
+        for (const tr of trs) {
+            const classAttr = tr.getAttribute('class') ?? '';
+            if (!classAttr.split(/\s+/).includes('ncua-table__row')) {
+                errors.push({
+                    type: 'missing_table_row_class',
+                    class: 'ncua-table__row',
+                    component: 'table',
+                    message: "ncua-table 안의 <tr> 에 'ncua-table__row' 클래스 누락. NCDS Table 의 모든 row 는 이 클래스가 필요.",
+                    suggestion: "render_to_html('table', ...) 출력을 그대로 사용. 수동 작성 시 모든 <tr> 에 class='ncua-table__row' 추가.",
+                });
+                // 같은 row 중복 보고 방지 — 첫 누락만
+                break;
+            }
+        }
+    }
+    return errors;
+};
+/** P13: 페이지 prefix 의 *-required 클래스로 필수 마크 자체 작성 검출.
+ *  텍스트가 정확히 `*` 한 글자이면 ncua-table__required 사용 권장. */
+const collectCustomRequiredMarkWarnings = (root) => {
+    const warnings = [];
+    const allWithClass = root.querySelectorAll('[class]');
+    for (const el of allWithClass) {
+        const classAttr = el.getAttribute('class') ?? '';
+        const classes = classAttr.split(/\s+/).filter(Boolean);
+        // ncua- 가 아닌 prefix 의 *-required 또는 __required-mark 같은 형태
+        const matched = classes.find((c) => !c.startsWith('ncua-') && /(-required(?:-mark)?$|__required(?:-mark)?$)/.test(c));
+        if (!matched)
+            continue;
+        const text = (el.text ?? '').trim();
+        if (text !== '*')
+            continue;
+        warnings.push({
+            type: 'custom_required_mark',
+            class: matched,
+            component: 'table',
+            message: `페이지 prefix 클래스 '${matched}' 로 '*' 필수 마크를 자체 작성. NCDS 가 공식 element 'ncua-table__required' 를 제공.`,
+            suggestion: `<span class='${matched}'>*</span> 를 <span class='ncua-table__required'>*</span> 로 교체 (Vertical Table 라벨 셀 안에 prepend).`,
+        });
+    }
+    return warnings;
+};
 /** 최종 응답 빌드 */
 const buildResponse = (params) => {
     const { errors, warnings, invalidClassesSet, root, compliance } = params;