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

package/bin/tools/searchComponent.d.ts

@@ -1,3 +1,8 @@
+/**
+ * search_component tool — name/description/aliases 퍼지 키워드 검색 (순수 함수)
+ *
+ * Calculator: searchComponent — 입력(componentMap, query) → 출력(매칭 결과, 점수순 정렬)
+ */
 import type { ComponentData } from '../types.js';
 import { type McpToolResponse } from '../utils/response.js';
 /** search_component tool — name/description/aliases 퍼지 검색 후 점수순 반환 */

package/bin/tools/searchComponent.js

@@ -1,14 +1,14 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.searchComponent = void 0;
 /**
  * search_component tool — name/description/aliases 퍼지 키워드 검색 (순수 함수)
  *
  * Calculator: searchComponent — 입력(componentMap, query) → 출력(매칭 결과, 점수순 정렬)
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchComponent = void 0;
 const dataLoader_js_1 = require("../utils/dataLoader.js");
-const response_js_1 = require("../utils/response.js");
 const fuzzyMatch_js_1 = require("../utils/fuzzyMatch.js");
+const response_js_1 = require("../utils/response.js");
 /** search_component tool — name/description/aliases 퍼지 검색 후 점수순 반환 */
 const searchComponent = (componentMap, query) => {
     if (!query.trim())

package/bin/tools/validateHtml.d.ts

@@ -1,11 +1,8 @@
-import type { ComponentData, ComplianceRulesData, TokenData } from '../types.js';
+import type { ComplianceRulesData, ComponentData, TokenData } from '../types.js';
 import type { CdnMeta } from '../utils/dataLoader.js';
 import { type McpToolResponse } from '../utils/response.js';
-export type { ValidationError } from '../utils/bemValidator.js';
-export { buildRootClassMap } from '../utils/bemValidator.js';
-export { buildTokenValueMap } from '../utils/tokenValidator.js';
 /** validate_html tool 파라미터 */
-export interface ValidateHtmlParams {
+interface ValidateHtmlParams {
     componentMap: Map<string, ComponentData>;
     rootClassMap: Map<string, string>;
     html: string;
@@ -15,4 +12,9 @@ export interface ValidateHtmlParams {
     tokenValueMap?: Map<string, string[]> | null;
 }
 /** validate_html tool — HTML의 NCUA BEM 클래스 정합성 + 디자인 시스템 준수도 검증 */
-export declare const validateHtml: (params: ValidateHtmlParams) => McpToolResponse;
+declare const validateHtml: (params: ValidateHtmlParams) => McpToolResponse;
+export { validateHtml };
+export type { ValidateHtmlParams };
+export type { ValidationError } from '../utils/bemValidator.js';
+export { buildRootClassMap } from '../utils/bemValidator.js';
+export { buildTokenValueMap } from '../utils/tokenValidator.js';

package/bin/tools/validateHtml.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateHtml = exports.buildTokenValueMap = exports.buildRootClassMap = void 0;
+exports.buildTokenValueMap = exports.buildRootClassMap = exports.validateHtml = void 0;
 /**
  * validate_html tool — NCUA HTML BEM 검증 + 디자인 시스템 준수도 검증 진입점
  *
@@ -9,13 +9,9 @@ exports.validateHtml = exports.buildTokenValueMap = exports.buildRootClassMap =
  * 이 파일은 오케스트레이션만 담당한다.
  */
 const node_html_parser_1 = require("node-html-parser");
-const response_js_1 = require("../utils/response.js");
 const bemValidator_js_1 = require("../utils/bemValidator.js");
 const compliance_js_1 = require("../utils/compliance.js");
-var bemValidator_js_2 = require("../utils/bemValidator.js");
-Object.defineProperty(exports, "buildRootClassMap", { enumerable: true, get: function () { return bemValidator_js_2.buildRootClassMap; } });
-var tokenValidator_js_1 = require("../utils/tokenValidator.js");
-Object.defineProperty(exports, "buildTokenValueMap", { enumerable: true, get: function () { return tokenValidator_js_1.buildTokenValueMap; } });
+const response_js_1 = require("../utils/response.js");
 /** validate_html tool — HTML의 NCUA BEM 클래스 정합성 + 디자인 시스템 준수도 검증 */
 const validateHtml = (params) => {
     const { componentMap, rootClassMap, html, cdnMeta, tokenData, complianceRules, tokenValueMap } = params;
@@ -33,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,
@@ -66,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;
@@ -83,3 +147,7 @@ const buildResponse = (params) => {
         ...(compliance && { compliance }),
     });
 };
+var bemValidator_js_2 = require("../utils/bemValidator.js");
+Object.defineProperty(exports, "buildRootClassMap", { enumerable: true, get: function () { return bemValidator_js_2.buildRootClassMap; } });
+var tokenValidator_js_1 = require("../utils/tokenValidator.js");
+Object.defineProperty(exports, "buildTokenValueMap", { enumerable: true, get: function () { return tokenValidator_js_1.buildTokenValueMap; } });

package/bin/types.d.ts

@@ -7,11 +7,32 @@ export interface PropSpec {
     default?: unknown;
     values?: string[];
     rawType?: string;
+    properties?: Record<string, PropSpec>;
+    /** 타입의 의미적 정체성 — 예: 'icon-component'는 SlotIconComponent 계열 아이콘 컴포넌트. renderer가 iconBundle resolve 대상 판정에 사용 */
+    semantic?: 'icon-component';
 }
 export interface ComponentUsage {
     import: string;
     react: Record<string, string>;
 }
+/** P8: allowedChildren 의 구조화 객체 형태 (P5-2).
+ *  - required: 부모 안에 반드시 있어야 하는 자식
+ *  - recommended: 강력히 권장 (없어도 통과)
+ *  - optional: 선택적 (사용자 명시 요청 시만)
+ *  - forbiddenInContext: { childKey: reason } — 이름은 valid 컴포넌트지만 이 부모 안에서는 사용 금지 + 대체 슬롯 안내 */
+export interface AllowedChildrenSpec {
+    required?: string[];
+    recommended?: string[];
+    optional?: string[];
+    forbiddenInContext?: Record<string, string>;
+}
+/** P8: canonicalExamples 다중 시나리오 맵의 단일 항목 (P5-1). */
+export interface CanonicalExampleEntry {
+    /** 시나리오 한 줄 설명. AI 가 어떤 시나리오를 선택할지 판단에 사용. */
+    description?: string;
+    /** render_to_html 입력으로 그대로 사용 가능한 props 트리. */
+    props: Record<string, unknown>;
+}
 export interface ComponentData {
     name: string;
     exportName: string;
@@ -26,7 +47,26 @@ export interface ComponentData {
     seeAlso: string[];
     /** Props가 확장하는 HTML 요소 — 에이전트가 표준 HTML 속성 사용 가능 여부를 판단 */
     htmlElement?: string;
+    /** 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>;
+    }>;
+    /** P8: Composition Overrides (`src/overrides/composition.json`) 에서 병합되는 부모-자식 제약.
+     *  키는 컴포넌트 자체("DataGrid") 또는 서브("DataGrid.Table") PascalCase.
+     *  값은 단순 배열 (legacy) 또는 구조화 객체 (required/recommended/optional/forbiddenInContext) 모두 허용. */
+    allowedChildren?: Record<string, string[] | AllowedChildrenSpec>;
+    /** P8: composition overrides 에서 병합되는 허용 부모. */
+    allowedParents?: Record<string, string[]>;
+    /** P8: composition overrides 에서 병합되는 canonical 단일 시나리오 (legacy P1-6 호환). */
+    canonicalExample?: {
+        props: Record<string, unknown>;
+    };
+    /** P8: composition overrides 에서 병합되는 canonical 다중 시나리오 맵 (P5-1). 키는 시나리오 식별자. */
+    canonicalExamples?: Record<string, CanonicalExampleEntry>;
     html?: Record<string, string>;
     bemClasses: string[];
     usage: ComponentUsage;
@@ -49,8 +89,9 @@ export interface ReactRuntime {
 export interface Capability {
     tool: string;
     description: string;
+    available: boolean;
 }
-export type McpErrorCode = 'COMPONENT_NOT_FOUND' | 'EXPORT_NAME_MISSING' | 'COMPONENT_NOT_IN_BUNDLE' | 'RENDER_FAILED' | 'INVALID_TOKEN_CATEGORY';
+export type McpErrorCode = 'COMPONENT_NOT_FOUND' | 'EXPORT_NAME_MISSING' | 'COMPONENT_NOT_IN_BUNDLE' | 'RENDER_FAILED' | 'INVALID_TOKEN_CATEGORY' | 'ICON_NOT_FOUND' | 'INVALID_PARAMS' | 'INTERNAL_ERROR';
 export interface TokenEntry {
     name: string;
     value: string;
@@ -67,6 +108,24 @@ export interface TokenData {
     categories: string[];
     groups: TokenGroup[];
 }
+export interface JsApiInfo {
+    className: string;
+    constructor: string;
+    constructorParams: Record<string, string>;
+    methods: string[];
+    staticMethods?: string[];
+    example: string;
+    /** Story 5.9: CDN init script 생성 시 사용자 props 와 deep merge 되는 default 옵션. JSON-serializable 만 (함수 prop 없음). */
+    cdnDefaults?: Record<string, unknown>;
+    /**
+     * CDN 호출 패턴.
+     * - A: `new ncua.X(element, options)` — element가 곧 컨테이너
+     * - B: `new ncua.X(options)` — options.container로 자동 append
+     * - C: `new ncua.X(options)` — getElement() + 수동 append
+     * 부재 시 React 정적 HTML 경로로 fallback.
+     */
+    cdnPattern?: 'A' | 'B' | 'C';
+}
 export interface ComplianceRuleHint {
     attr: string;
     values: string[];

package/bin/utils/bemValidator.d.ts

@@ -6,22 +6,28 @@
 import type { parse } from 'node-html-parser';
 import type { ComponentData } from '../types.js';
 import type { CdnMeta } from './dataLoader.js';
-export interface ValidationError {
-    type: 'invalid_modifier' | 'invalid_element' | 'unknown_component' | 'missing_root_class' | 'mixed_namespace' | 'missing_cdn';
+interface ValidationError {
+    type: 'invalid_modifier' | 'invalid_element' | 'unknown_component' | 'missing_root_class' | 'mixed_namespace' | 'missing_cdn'
+    /** P13: Vertical Table 안에서 horizontal 전용 `ncua-table__header-cell` 사용 */
+     | 'vertical_uses_horizontal_header_cell'
+    /** P13: Vertical/Horizontal Table 안 `<tr>` 에 `ncua-table__row` 클래스 누락 */
+     | 'missing_table_row_class'
+    /** P13: 페이지 prefix `*-required` 클래스로 필수 마크 자체 작성 (ncua-table__required 사용 권장) */
+     | 'custom_required_mark';
     class: string;
     component: string;
     message: string;
     suggestion: string;
 }
 /** 엘리먼트에서 class 목록을 파싱 */
-export declare const getClassList: (el: {
+declare const getClassList: (el: {
     getAttribute: (name: string) => string | undefined;
 }) => string[];
 /** root class → component name 매핑 빌드 — server.ts에서 1회 호출 */
-export declare const buildRootClassMap: (componentMap: Map<string, ComponentData>) => Map<string, string>;
+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']>;
+declare const collectBemErrors: (params: {
+    elements: ReturnType<ReturnType<typeof parse>["querySelectorAll"]>;
     rootClassMap: Map<string, string>;
     componentMap: Map<string, ComponentData>;
 }) => {
@@ -31,6 +37,8 @@ export declare const collectBemErrors: (params: {
     hasNcuaClasses: boolean;
 };
 /** 잘못된 클래스를 제거하여 fixed_html 생성 */
-export declare const buildFixedHtml: (root: ReturnType<typeof parse>, invalidClassesSet: Set<string>) => string;
+declare const buildFixedHtml: (root: ReturnType<typeof parse>, invalidClassesSet: Set<string>) => string;
 /** CDN CSS/JS 링크 포함 여부 검증 */
-export declare const checkCdnInclusion: (html: string, cdnMeta: CdnMeta) => ValidationError[];
+declare const checkCdnInclusion: (html: string, cdnMeta: CdnMeta) => ValidationError[];
+export { buildFixedHtml, buildRootClassMap, checkCdnInclusion, collectBemErrors, getClassList };
+export type { ValidationError };

package/bin/utils/bemValidator.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkCdnInclusion = exports.buildFixedHtml = exports.collectBemErrors = exports.buildRootClassMap = exports.getClassList = void 0;
+exports.getClassList = exports.collectBemErrors = exports.checkCdnInclusion = exports.buildRootClassMap = exports.buildFixedHtml = void 0;
 // ── 상수 ─────────────────────────────────────────────────────────────────
 const MAX_SIMILAR_SUGGESTIONS = 3;
 // ── 순수 헬퍼 ────────────────────────────────────────────────────────────
@@ -102,7 +102,7 @@ const collectBemErrors = (params) => {
     const validSetCache = new Map();
     let foundNcua = false;
     for (const el of elements) {
-        const classes = (0, exports.getClassList)(el);
+        const classes = getClassList(el);
         const ncuaClasses = classes.filter((c) => c.startsWith('ncua-'));
         if (ncuaClasses.length === 0)
             continue;
@@ -119,11 +119,20 @@ const collectBemErrors = (params) => {
             reportUnknownClasses(ncuaClasses, errors, invalidClassesSet);
             continue;
         }
+        // biome-ignore lint/style/noNonNullAssertion: 직전 가드(rootClassMap.has)로 존재 보장
         const componentName = rootClassMap.get(rootClass);
         const component = componentMap.get(componentName);
+        if (!component) {
+            // rootClassMap 에는 있는데 componentMap 에 없는 비정상 상태 (호출자가 두 Map 을 분리 빌드한 경우).
+            // graceful skip — rootClass 가 알 수 없는 컴포넌트인 경로와 동일 처리.
+            reportUnknownClasses(ncuaClasses, errors, invalidClassesSet);
+            continue;
+        }
         if (!validSetCache.has(componentName))
             validSetCache.set(componentName, new Set(component.bemClasses));
-        validateBemClasses(ncuaClasses, validSetCache.get(componentName), componentName, component.bemClasses, errors, invalidClassesSet);
+        validateBemClasses(ncuaClasses, 
+        // biome-ignore lint/style/noNonNullAssertion: 직전 has/set 보장
+        validSetCache.get(componentName), componentName, component.bemClasses, errors, invalidClassesSet);
     }
     return { errors, warnings, invalidClassesSet, hasNcuaClasses: foundNcua };
 };
@@ -133,6 +142,7 @@ const collectMixedNamespaceWarning = (classes, ncuaClasses, rootClass, rootClass
     const customClasses = classes.filter((c) => !c.startsWith('ncua-'));
     if (customClasses.length === 0)
         return;
+    // biome-ignore lint/style/noNonNullAssertion: 삼항 가드로 rootClassMap.has(rootClass) 보장
     const compName = rootClass && rootClassMap.has(rootClass) ? rootClassMap.get(rootClass) : 'unknown';
     warnings.push({
         type: 'mixed_namespace',
@@ -151,7 +161,9 @@ const collectMissingRootClassError = (ncuaClasses, rootClass, rootClassMap, erro
         return;
     errors.push({
         type: 'missing_root_class',
+        // biome-ignore lint/style/noNonNullAssertion: isModifierWithoutRoot 가드에 rootClass != null 포함
         class: rootClass,
+        // biome-ignore lint/style/noNonNullAssertion: 위와 동일 가드 (rootClass != null + has)
         component: rootClassMap.get(rootClass),
         message: `Root class '${rootClass}' is missing. Modifiers/elements require their root class.`,
         suggestion: `Add '${rootClass}' class to the same element.`,
@@ -160,7 +172,7 @@ const collectMissingRootClassError = (ncuaClasses, rootClass, rootClassMap, erro
 /** 잘못된 클래스를 제거하여 fixed_html 생성 */
 const buildFixedHtml = (root, invalidClassesSet) => {
     for (const el of root.querySelectorAll('[class]')) {
-        const classes = (0, exports.getClassList)(el);
+        const classes = getClassList(el);
         const filtered = classes.filter((c) => !invalidClassesSet.has(c));
         if (filtered.length > 0) {
             el.setAttribute('class', filtered.join(' '));

package/bin/utils/compliance.d.ts

@@ -3,12 +3,11 @@
  *
  * 토큰 검증은 tokenValidator.ts에 분리.
  */
-import { parse } from 'node-html-parser';
-import type { ComponentData, ComplianceRulesData, ComplianceError, ComplianceSummary } from '../types.js';
+import type { parse } from 'node-html-parser';
+import type { ComplianceError, ComplianceRulesData, ComplianceSummary, ComponentData } from '../types.js';
 import type { ValidationError } from './bemValidator.js';
-export { detectTokenIssues } from './tokenValidator.js';
 /** NCUA 컴포넌트 누락 감지 — 태그 인덱스로 O(n) 매칭 */
-export declare const detectNcuaOmission: (params: {
+declare const detectNcuaOmission: (params: {
     root: ReturnType<typeof parse>;
     complianceRules: ComplianceRulesData;
     componentMap: Map<string, ComponentData>;
@@ -20,7 +19,7 @@ export declare const detectNcuaOmission: (params: {
     };
 };
 /** NCUA 컴포넌트 내부 커스텀 스타일 감지 */
-export declare const detectCustomNotSeparated: (params: {
+declare const detectCustomNotSeparated: (params: {
     root: ReturnType<typeof parse>;
     rootClassMap: Map<string, string>;
     warnings: ValidationError[];
@@ -32,7 +31,7 @@ export declare const detectCustomNotSeparated: (params: {
     };
 };
 /** 준수도 점수 + 요약 빌드 */
-export declare const buildComplianceSummary: (params: {
+declare const buildComplianceSummary: (params: {
     ncuaErrors: ComplianceError[];
     tokenErrors: ComplianceError[];
     customErrors: ComplianceError[];
@@ -50,3 +49,5 @@ export declare const buildComplianceSummary: (params: {
         violated: number;
     };
 }) => ComplianceSummary;
+export { buildComplianceSummary, detectCustomNotSeparated, detectNcuaOmission };
+export { detectTokenIssues } from './tokenValidator.js';

package/bin/utils/compliance.js

@@ -1,9 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildComplianceSummary = exports.detectCustomNotSeparated = exports.detectNcuaOmission = exports.detectTokenIssues = void 0;
+exports.detectTokenIssues = exports.detectNcuaOmission = exports.detectCustomNotSeparated = exports.buildComplianceSummary = 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;
@@ -183,11 +181,15 @@ 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);
+    // biome-ignore lint/style/noMagicNumbers: 점수 0~1 boundary (clamp)
     const score = totalCheckpoints === 0 ? 1.0 : Math.max(0, Math.min(1, 1 - weightedViolations / totalCheckpoints));
     return {
+        // biome-ignore lint/style/noMagicNumbers: 2자리 소수점 반올림 (×100/100)
         score: Math.round(score * 100) / 100,
         errors: allErrors.slice(0, MAX_COMPLIANCE_ERRORS),
         ncuaUsage,
@@ -197,3 +199,5 @@ const buildComplianceSummary = (params) => {
     };
 };
 exports.buildComplianceSummary = buildComplianceSummary;
+var tokenValidator_js_1 = require("./tokenValidator.js");
+Object.defineProperty(exports, "detectTokenIssues", { enumerable: true, get: function () { return tokenValidator_js_1.detectTokenIssues; } });

package/bin/utils/dataLoader.d.ts

@@ -1,33 +1,62 @@
-import type { ComponentData, IconData, TokenData, ComplianceRulesData } from '../types.js';
-export declare const DEFAULT_DATA_DIR: string;
+import type { ComplianceRulesData, ComponentData, IconData, JsApiInfo, TokenData } from '../types.js';
+declare const DEFAULT_DATA_DIR: string;
+interface CompositionEntry {
+    bemClassesExtra?: string[];
+    /** P5-2: 단순 배열 (legacy) 또는 구조화 객체 모두 허용 */
+    allowedChildren?: Record<string, string[] | import('../types.js').AllowedChildrenSpec>;
+    allowedParents?: Record<string, string[]>;
+    /** P1-6 legacy 단일 시나리오 */
+    canonicalExample?: {
+        props: Record<string, unknown>;
+    };
+    /** P5-1 다중 시나리오 맵 */
+    canonicalExamples?: Record<string, import('../types.js').CanonicalExampleEntry>;
+    /** P13: 컴포넌트 description 끝에 append (메타 보강). list_components / search_component 응답 개선용. */
+    descriptionExtra?: string;
+    /** P13: 컴포넌트 aliases 와 union (중복 제거). search_component 별칭 보강. */
+    aliasesExtra?: string[];
+    /**
+     * coverageScore 분모에서 제외할 보강 영역 목록 — 구조상 채울 수 없는 영역을 선언.
+     * 예: extract 가 BEM 클래스를 완전히 잡는 컴포넌트는 ["bemClassesExtra"] 선언 → 분모 0.10 차감 → 달성 가능한 나머지 영역만 채우면 1.0 달성.
+     * compound/non-compound 구조적 제외(allowedChildren)와 union 되어 최종 notApplicable 결정.
+     */
+    notApplicableAreas?: string[];
+}
+declare const loadCompositionOverrides: () => Record<string, CompositionEntry>;
 export interface CdnMeta {
     version: string;
     css: string;
     js: string;
 }
-export interface IconMeta {
+interface IconMeta {
     packageName: string;
     version: string;
-    cdn: string;
 }
-/** data/ 디렉토리의 JSON 파일을 읽어 componentMap으로 반환 */
-export declare const loadComponentsFromDir: (dataDir: string) => Map<string, ComponentData>;
+/** data/ 디렉토리의 JSON 파일을 읽어 componentMap + compositionOverrides로 반환 */
+declare const loadComponentsFromDir: (dataDir: string) => {
+    map: Map<string, ComponentData>;
+    compositionOverrides: Record<string, CompositionEntry>;
+};
 /** data/_icons.json을 읽어 IconData로 반환 (파일 없으면 빈 데이터) */
-export declare const loadIconData: (dataDir: string) => IconData;
+declare const loadIconData: (dataDir: string) => IconData;
 /** _meta.json 파싱 결과 */
-export interface MetaData {
+interface MetaData {
     cdn: CdnMeta | null;
     icon: IconMeta | null;
 }
 /** data/_meta.json에서 CDN + icon 메타를 1회 읽기로 로드 */
-export declare const loadMeta: (dataDir: string) => MetaData;
+declare const loadMeta: (dataDir: string) => MetaData;
 /** data/_tokens.json을 읽어 TokenData로 반환 (파일 없으면 빈 데이터) */
-export declare const loadTokenData: (dataDir: string) => TokenData;
+declare const loadTokenData: (dataDir: string) => TokenData;
 /** definitions/compliance-rules.json을 로드하여 ComplianceRulesData로 반환 (파일 없으면 null) */
-export declare const loadComplianceRules: (definitionsDir: string) => ComplianceRulesData | null;
+declare const loadComplianceRules: (definitionsDir: string) => ComplianceRulesData | null;
 /** definitions/instructions.md를 로드하여 문자열 반환 */
-export declare const loadInstructions: (definitionsDir: string) => string;
+declare const loadInstructions: (definitionsDir: string) => string;
+/** definitions/js-api.json을 로드하여 exportName→JsApiInfo Map 반환 */
+declare const loadJsApi: (definitionsDir: string) => Map<string, JsApiInfo>;
 /** componentMap에서 이름으로 단일 컴포넌트 조회 */
-export declare const getComponent: (map: Map<string, ComponentData>, name: string) => ComponentData | undefined;
+declare const getComponent: (map: Map<string, ComponentData>, name: string) => ComponentData | undefined;
 /** componentMap의 모든 컴포넌트를 배열로 반환 */
-export declare const getAllComponents: (map: Map<string, ComponentData>) => ComponentData[];
+declare const getAllComponents: (map: Map<string, ComponentData>) => ComponentData[];
+export { DEFAULT_DATA_DIR, getAllComponents, getComponent, loadComplianceRules, loadCompositionOverrides, loadComponentsFromDir, loadIconData, loadInstructions, loadJsApi, loadMeta, loadTokenData, };
+export type { CompositionEntry, IconMeta, MetaData };