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

package/bin/definitions/external/step-guide.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Story 6.1: step-guide 외부 분기 정의
+ *
+ * vanilla JS 함수 기반 step-by-step 가이드 투어(`step-guide`)의 응답 메타·CDN URL·props·cdnDefaults·methods.
+ * `tools/external/step-guide.ts`의 `buildStepGuideResponse`가 본 정의를 읽어 응답 조립.
+ * 5-10 editor 패턴 답습 — 단, step-guide는 함수 호출(`window.stepGuide({el, options})`) 형식.
+ * (json 대신 ts — tsconfig `module: Node16` 환경에서 import 단순화. 빌드 시 자동 포함.)
+ */
+export declare const stepGuideDefinition: {
+    readonly name: "step-guide";
+    readonly exportName: "stepGuide";
+    readonly category: "overlays";
+    readonly description: "vanilla JS 함수 기반 step-by-step 가이드 투어. CDN 로드 후 window.stepGuide({el, options}) 호출.";
+    readonly cdn: {
+        readonly version: "2.0";
+        readonly css: "https://fe-sdk.cdn-nhncommerce.com/@ncds/step-guide/2.0/step-guide.min.css";
+        readonly js: "https://fe-sdk.cdn-nhncommerce.com/@ncds/step-guide/2.0/step-guide.min.js";
+    };
+    readonly props: readonly [{
+        readonly name: "steps";
+        readonly type: "Step[]";
+        readonly required: true;
+        readonly description: "단계 배열";
+    }, {
+        readonly name: "useAnimation";
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "애니메이션 사용 여부";
+    }, {
+        readonly name: "buttonLabel";
+        readonly type: "{ prev, next, done, skip }";
+        readonly description: "버튼 라벨 (v2 default: 이전/다음/완료/나중에 하기)";
+    }, {
+        readonly name: "hideSkip";
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "스킵 버튼 숨김 여부";
+    }, {
+        readonly name: "hideStepCount";
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "스텝 카운트 숨김 여부";
+    }, {
+        readonly name: "hideStepPrefix";
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "STEP N prefix 숨김 여부. 단계 1개일 때는 옵션과 무관하게 자동 생략";
+    }, {
+        readonly name: "exitOnOverlayClick";
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "오버레이 클릭 시 종료 여부";
+    }];
+    readonly cdnDefaults: {
+        useAnimation: boolean;
+        hideSkip: boolean;
+        hideStepCount: boolean;
+        exitOnOverlayClick: boolean;
+    };
+    readonly methods: readonly ["goToStep(index)", "previousStep(e)", "nextStep(e)", "onChange(callback)", "onExit(callback)", "exit(e)"];
+};

package/bin/definitions/external/step-guide.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Story 6.1: step-guide 외부 분기 정의
+ *
+ * vanilla JS 함수 기반 step-by-step 가이드 투어(`step-guide`)의 응답 메타·CDN URL·props·cdnDefaults·methods.
+ * `tools/external/step-guide.ts`의 `buildStepGuideResponse`가 본 정의를 읽어 응답 조립.
+ * 5-10 editor 패턴 답습 — 단, step-guide는 함수 호출(`window.stepGuide({el, options})`) 형식.
+ * (json 대신 ts — tsconfig `module: Node16` 환경에서 import 단순화. 빌드 시 자동 포함.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepGuideDefinition = void 0;
+exports.stepGuideDefinition = {
+    name: 'step-guide',
+    exportName: 'stepGuide', // CDN UMD default export = 함수 (소문자, class 아님)
+    category: 'overlays',
+    description: 'vanilla JS 함수 기반 step-by-step 가이드 투어. CDN 로드 후 window.stepGuide({el, options}) 호출.',
+    cdn: {
+        version: '2.0',
+        css: 'https://fe-sdk.cdn-nhncommerce.com/@ncds/step-guide/2.0/step-guide.min.css',
+        js: 'https://fe-sdk.cdn-nhncommerce.com/@ncds/step-guide/2.0/step-guide.min.js',
+    },
+    props: [
+        { name: 'steps', type: 'Step[]', required: true, description: '단계 배열' },
+        { name: 'useAnimation', type: 'boolean', default: true, description: '애니메이션 사용 여부' },
+        {
+            name: 'buttonLabel',
+            type: '{ prev, next, done, skip }',
+            description: '버튼 라벨 (v2 default: 이전/다음/완료/나중에 하기)',
+        },
+        { name: 'hideSkip', type: 'boolean', default: true, description: '스킵 버튼 숨김 여부' },
+        { name: 'hideStepCount', type: 'boolean', default: true, description: '스텝 카운트 숨김 여부' },
+        {
+            name: 'hideStepPrefix',
+            type: 'boolean',
+            default: false,
+            description: 'STEP N prefix 숨김 여부. 단계 1개일 때는 옵션과 무관하게 자동 생략',
+        },
+        {
+            name: 'exitOnOverlayClick',
+            type: 'boolean',
+            default: true,
+            description: '오버레이 클릭 시 종료 여부',
+        },
+    ],
+    cdnDefaults: {
+        useAnimation: true,
+        hideSkip: true,
+        hideStepCount: true,
+        exitOnOverlayClick: true,
+    },
+    methods: ['goToStep(index)', 'previousStep(e)', 'nextStep(e)', 'onChange(callback)', 'onExit(callback)', 'exit(e)'],
+};

package/bin/definitions/js-api.json

@@ -9,7 +9,12 @@
       "onClose": "() => void"
     },
     "methods": ["open()", "close()", "destroy()", "setContent(html: string | HTMLElement)", "isModalOpen()"],
-    "example": "const modal = new window.ncua.Modal({ size: 'sm', onClose: () => {} });\nmodal.setContent('<p>Content</p>');\nmodal.open();"
+    "example": "const modal = new window.ncua.Modal({ size: 'sm', onClose: () => {} });\nmodal.setContent('<p>Content</p>');\nmodal.open();",
+    "cdnDefaults": {
+      "size": "md",
+      "closeOnBackdropClick": false,
+      "closeOnEsc": true
+    }
   },
   "SelectBox": {
     "className": "SelectBox",
@@ -28,8 +33,10 @@
     "methods": ["getValues()", "setValues(options[])", "getSelectedCount()"],
     "example": "const select = new window.ncua.SelectBox(document.getElementById('my-select'), {\n  options: [{ id: '1', text: 'Option 1' }],\n  onChange: (value) => console.log(value)\n});",
     "cdnDefaults": {
-      "size": "xs",
-      "placeholder": "선택하세요"
+      "size": "md",
+      "placeholder": "선택하세요",
+      "disabled": false,
+      "multiple": false
     }
   },
   "ComboBox": {
@@ -49,8 +56,11 @@
     "methods": ["getValues()", "setValues(options[])", "clearInput()", "getSelectedCount()"],
     "example": "const combo = new window.ncua.ComboBox(document.getElementById('my-combo'), {\n  options: [{ id: '1', label: 'React' }],\n  onSearch: (q) => console.log(q)\n});",
     "cdnDefaults": {
-      "size": "xs",
-      "placeholder": "검색하세요"
+      "size": "md",
+      "placeholder": "검색하고 선택하세요",
+      "disabled": false,
+      "multiple": false,
+      "showFooterButtons": false
     }
   },
   "DatePicker": {
@@ -103,7 +113,9 @@
       "min": 0,
       "max": 100,
       "step": 1,
-      "labelPosition": "top-floating"
+      "labelPosition": "top-floating",
+      "disabled": false,
+      "value": 0
     }
   },
   "Tab": {
@@ -136,10 +148,11 @@
     "example": "const tip = window.ncua.Tooltip.createShort('Help', 'Tooltip content');\ndocument.getElementById('container').appendChild(tip.getElement());",
     "cdnDefaults": {
       "type": "short",
-      "tooltipType": "black",
+      "tooltipType": "white",
       "iconType": "stroke",
       "position": "auto",
-      "size": "sm"
+      "size": "sm",
+      "hideArrow": false
     }
   },
   "Notification": {
@@ -181,7 +194,9 @@
     "methods": ["getElement()", "updateOptions(newOptions)", "toHTML()"],
     "example": "const bar = new window.ncua.ProgressBar({ value: 65, label: 'right' });\ndocument.getElementById('container').appendChild(bar.getElement());",
     "cdnDefaults": {
-      "label": "right"
+      "label": "right",
+      "showZeroLabel": false,
+      "valueToPercent": true
     }
   },
   "Tag": {
@@ -200,7 +215,8 @@
     "methods": ["getElement()", "setText(text)", "setCount(count)", "destroy()"],
     "example": "const tag = new window.ncua.Tag({ text: 'Label', close: true, onButtonClick: () => tag.destroy() });\ndocument.getElementById('container').appendChild(tag.getElement());",
     "cdnDefaults": {
-      "size": "sm"
+      "size": "sm",
+      "maxLength": 20
     }
   },
   "FileInput": {
@@ -230,7 +246,9 @@
     "methods": ["getElement()", "setDisabled(boolean)", "destroy()"],
     "example": "const fi = new window.ncua.FileInput({\n  container: 'file-container',\n  onChange: (files) => console.log(files)\n});",
     "cdnDefaults": {
-      "buttonLabel": "파일 찾기"
+      "buttonLabel": "파일 찾기",
+      "multiple": false,
+      "size": "xs"
     }
   },
   "ImageFileInput": {
@@ -262,7 +280,10 @@
       "options.className": "string"
     },
     "cdnDefaults": {
-      "buttonLabel": "파일 찾기"
+      "buttonLabel": "파일 찾기",
+      "imagePreviewTooltipLabel": "이미지 업로드",
+      "multiple": false,
+      "size": "sm"
     },
     "methods": ["getElement()", "getFiles()", "clearFiles()", "setDisabled(boolean)", "destroy()"],
     "example": "const img = new window.ncua.ImageFileInput({\n  container: 'image-container',\n  maxFileCount: 5,\n  onChange: (files) => console.log(files)\n});"
@@ -278,6 +299,19 @@
       "options.className": "string"
     },
     "methods": ["getElement()", "updateColor(color)", "updateSize(size)", "destroy()"],
-    "example": "const icon = new window.ncua.FeaturedIcon({ svgString: '<svg>...</svg>', color: 'success', size: 'md' });\ndocument.getElementById('container').appendChild(icon.getElement());"
+    "example": "const icon = new window.ncua.FeaturedIcon({ svgString: '<svg>...</svg>', color: 'success', size: 'md' });\ndocument.getElementById('container').appendChild(icon.getElement());",
+    "cdnDefaults": {
+      "theme": "light-circle",
+      "color": "neutral",
+      "size": "sm"
+    }
+  },
+  "Table": {
+    "cdnDefaults": {
+      "type": "horizontal",
+      "hoverable": true,
+      "selectable": false,
+      "fixedHeader": false
+    }
   }
 }

package/bin/tools/external/editor.d.ts

@@ -9,9 +9,10 @@
  */
 import { type McpToolResponse } from '../../utils/response.js';
 /** `normalizeName` 적용된 컴포넌트 이름이 editor alias 인지 검사 */
-export declare const isEditorAlias: (normalizedName: string) => boolean;
+declare const isEditorAlias: (normalizedName: string) => boolean;
 /**
  * editor 응답 조립 — ui-admin 흐름 우회.
  * 5-9 helper(`mergeCdnDefaults` / `stripFunctionProps`) import 재사용 (코드 중복 0).
  */
-export declare const buildEditorResponse: (props: Record<string, unknown>, instanceId: string) => McpToolResponse;
+declare const buildEditorResponse: (props: Record<string, unknown>, instanceId: string) => McpToolResponse;
+export { buildEditorResponse, isEditorAlias };

package/bin/tools/external/editor.js

@@ -9,7 +9,7 @@
  * 호출 진입점: `renderToHtml` 함수 시작부 (Task 1 결정).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildEditorResponse = exports.isEditorAlias = void 0;
+exports.isEditorAlias = exports.buildEditorResponse = void 0;
 const editor_js_1 = require("../../definitions/external/editor.js");
 const response_js_1 = require("../../utils/response.js");
 const renderToHtml_js_1 = require("../renderToHtml.js");

package/bin/tools/external/step-guide.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Story 6.1: step-guide 외부 분기 모듈
+ *
+ * vanilla JS 함수 기반 가이드 투어(`step-guide`)는 ui-admin 외부 패키지이며
+ * 5-10 editor와 동일 패턴으로 ui-admin 흐름을 우회하고 본 모듈에서 응답을 직접 조립한다.
+ * 핵심 차이 — step-guide는 함수 호출(`window.stepGuide({el, options})`) 형식이라
+ * 5-10 patternD(생성자 호출 `new window.NcdsEditor(querySelector)`)와 다른 init 스니펫 패턴 신설.
+ *
+ * 호출 진입점: `renderToHtml` 함수 시작부 (editor 분기 다음).
+ */
+import { type McpToolResponse } from '../../utils/response.js';
+/** `normalizeName` 적용된 컴포넌트 이름이 step-guide alias 인지 검사 */
+declare const isStepGuideAlias: (normalizedName: string) => boolean;
+/**
+ * step-guide 응답 조립 — ui-admin 흐름 우회.
+ * 5-9 helper(`mergeCdnDefaults` / `stripFunctionProps`) import 재사용 (코드 중복 0).
+ */
+declare const buildStepGuideResponse: (props: Record<string, unknown>, _instanceId: string) => McpToolResponse;
+export { buildStepGuideResponse, isStepGuideAlias };

package/bin/tools/external/step-guide.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Story 6.1: step-guide 외부 분기 모듈
+ *
+ * vanilla JS 함수 기반 가이드 투어(`step-guide`)는 ui-admin 외부 패키지이며
+ * 5-10 editor와 동일 패턴으로 ui-admin 흐름을 우회하고 본 모듈에서 응답을 직접 조립한다.
+ * 핵심 차이 — step-guide는 함수 호출(`window.stepGuide({el, options})`) 형식이라
+ * 5-10 patternD(생성자 호출 `new window.NcdsEditor(querySelector)`)와 다른 init 스니펫 패턴 신설.
+ *
+ * 호출 진입점: `renderToHtml` 함수 시작부 (editor 분기 다음).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStepGuideAlias = exports.buildStepGuideResponse = void 0;
+const step_guide_js_1 = require("../../definitions/external/step-guide.js");
+const response_js_1 = require("../../utils/response.js");
+const renderToHtml_js_1 = require("../renderToHtml.js");
+/** step-guide 컴포넌트로 매칭할 alias 집합 (render_to_html 진입점용, 보수적 4 영문) */
+const STEP_GUIDE_ALIASES = new Set(['step-guide', 'stepguide', 'ncdsstepguide', 'step_guide']);
+/** `normalizeName` 적용된 컴포넌트 이름이 step-guide alias 인지 검사 */
+const isStepGuideAlias = (normalizedName) => STEP_GUIDE_ALIASES.has(normalizedName);
+exports.isStepGuideAlias = isStepGuideAlias;
+/**
+ * init 스니펫 — 함수 호출 형식.
+ * 5-10 patternD(생성자 호출 `new window.NcdsEditor(querySelector)`)와 다른 새 패턴.
+ *   - 컨테이너 div 없음 — step-guide는 document.body 에 overlay를 그리는 도구라 격리 div 의미 없음
+ *   - `el: document.body` — step-guide의 _fetchSteps 가 _targetElement 안에서만 step.element selector를 검색하므로
+ *     사용자가 step.element에 외부 카드 selector를 명시할 수 있도록 document.body를 target으로 지정
+ *   - 함수 호출: `window.stepGuide({ el: document.body, options: ... })`
+ *   - JSON.stringify로 options 직렬화 (data-* 미사용)
+ */
+const buildInitSnippet = (options) => {
+    const optionsJson = JSON.stringify(options);
+    return [
+        '<script>',
+        "  document.addEventListener('DOMContentLoaded', function () {",
+        `    window.stepGuide({ el: document.body, options: ${optionsJson} });`,
+        '  });',
+        '</script>',
+    ].join('\n');
+};
+/**
+ * step-guide 응답 조립 — ui-admin 흐름 우회.
+ * 5-9 helper(`mergeCdnDefaults` / `stripFunctionProps`) import 재사용 (코드 중복 0).
+ */
+const buildStepGuideResponse = (props, _instanceId // 격리 div 제거로 인해 unused — 외부 분기 시그니처 일관성 위해 인자는 유지
+) => {
+    // 5-9: 함수 prop 사전 제거 + cdnDefaults deep merge (사용자 props 우선)
+    const cleanedProps = (0, renderToHtml_js_1.stripFunctionProps)(props);
+    const { merged, defaultsApplied } = (0, renderToHtml_js_1.mergeCdnDefaults)('step-guide', step_guide_js_1.stepGuideDefinition.cdnDefaults, cleanedProps);
+    const html = buildInitSnippet(merged);
+    // cdnDefaults 적용된 키 → defaultsUsed 응답
+    const defaultsUsed = Object.fromEntries(defaultsApplied.map((key) => [
+        key,
+        step_guide_js_1.stepGuideDefinition.cdnDefaults[key],
+    ]));
+    return (0, response_js_1.successResponse)({
+        html,
+        component: step_guide_js_1.stepGuideDefinition.name,
+        exportName: step_guide_js_1.stepGuideDefinition.exportName,
+        importPath: 'step-guide',
+        appliedProps: merged,
+        ...(Object.keys(defaultsUsed).length > 0 && { defaultsUsed }),
+        js: {
+            required: true,
+            description: '이 컴포넌트는 인터랙션을 위해 CDN JS가 필요합니다',
+            api: {
+                exportName: step_guide_js_1.stepGuideDefinition.exportName,
+                methods: step_guide_js_1.stepGuideDefinition.methods,
+            },
+        },
+        cdn: step_guide_js_1.stepGuideDefinition.cdn,
+        dataVersion: { '@ncds/step-guide': step_guide_js_1.stepGuideDefinition.cdn.version },
+        react: {
+            notes: 'React 환경: useEffect 내 window.stepGuide({el, options}) 호출 + cleanup에서 instance.exit() 호출. ' +
+                'StrictMode 이중 마운트 회피 — cleanup 멱등성 보장 필요 (exit()가 이미 호출된 후 다시 호출되어도 안전).',
+        },
+    });
+};
+exports.buildStepGuideResponse = buildStepGuideResponse;

package/bin/tools/getComponentProps.d.ts

@@ -1,3 +1,6 @@
+/**
+ * get_component_props tool — 컴포넌트 props 스펙 반환 (순수 함수)
+ */
 import type { ComponentData } from '../types.js';
 import { type McpToolResponse } from '../utils/response.js';
 /** get_component_props tool — 컴포넌트의 props 스펙을 JSON으로 반환 */

package/bin/tools/getComponentProps.js

@@ -1,9 +1,9 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getComponentProps = void 0;
 /**
  * get_component_props tool — 컴포넌트 props 스펙 반환 (순수 함수)
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getComponentProps = void 0;
 const dataLoader_js_1 = require("../utils/dataLoader.js");
 const response_js_1 = require("../utils/response.js");
 /** get_component_props tool — 컴포넌트의 props 스펙을 JSON으로 반환 */

package/bin/tools/ping.d.ts

@@ -1,7 +1,7 @@
 /**
  * ping tool — NCUA MCP 서버 health check + capabilities/rules 제공 (순수 함수)
  */
-import type { ComponentData, Capability } from '../types.js';
+import type { Capability, ComponentData } from '../types.js';
 import type { CdnMeta, IconMeta } from '../utils/dataLoader.js';
 import { type McpToolResponse } from '../utils/response.js';
 /** ping tool 파라미터 — server.ts에서 모든 데이터를 소유하고 전달한다 */

package/bin/tools/renderToHtml.js

@@ -15,6 +15,7 @@ exports.renderToHtml = exports.mergeCdnDefaults = exports.stripFunctionProps = v
 const lodash_1 = require("lodash");
 const response_js_1 = require("../utils/response.js");
 const editor_js_1 = require("./external/editor.js");
+const step_guide_js_1 = require("./external/step-guide.js");
 // ── 상수 ──────────────────────────────────────────────────────────
 /** React 특수 props 차단 — injection 방지 */
 const BLOCKED_PROPS = new Set(['dangerouslySetInnerHTML', 'ref', '__self', '__source']);
@@ -657,6 +658,10 @@ const renderToHtml = (params) => {
     if ((0, editor_js_1.isEditorAlias)(normalized)) {
         return (0, editor_js_1.buildEditorResponse)(props ?? {}, instanceId);
     }
+    // Story 6.1: step-guide alias 검출 시 ui-admin 흐름 우회 — 외부 분기 (함수 호출 형식)
+    if ((0, step_guide_js_1.isStepGuideAlias)(normalized)) {
+        return (0, step_guide_js_1.buildStepGuideResponse)(props ?? {}, instanceId);
+    }
     const componentData = componentMap.get(normalized);
     if (!componentData)
         return (0, response_js_1.componentNotFoundResponse)(normalized);
@@ -709,7 +714,10 @@ const renderToHtml = (params) => {
         const html = cdnInitScript !== null
             ? cdnInitScript
             : `<!-- ncua:${normalized} start -->\n${reactRuntime.renderToStaticMarkup(reactRuntime.createElement(Component, resolvedProps))}\n<!-- ncua:${normalized} end -->`;
-        const hasDefaults = componentData.props ? calcDefaultsUsed(componentData.props, corrected) : {};
+        // Story 5.1-8: jsRequired 컴포넌트는 React data 의 default 무시 (vanilla 정의에 없는 React-only default 누수 차단).
+        // React 컴포넌트는 기존 동작 유지.
+        const isJsRequired = componentData.jsRequired === true;
+        const hasDefaults = !isJsRequired && componentData.props ? calcDefaultsUsed(componentData.props, corrected) : {};
         // Story 5.9: cdnDefaults 적용된 키도 defaultsUsed 에 노출 (에이전트 학습용)
         const cdnDefaultsApplied = isCdnInput && jsApi?.cdnDefaults
             ? Object.fromEntries(cdnMergeResult.defaultsApplied.map((key) => [key, jsApi.cdnDefaults?.[key]]))

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;
@@ -83,3 +79,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/utils/bemValidator.d.ts

@@ -6,7 +6,7 @@
 import type { parse } from 'node-html-parser';
 import type { ComponentData } from '../types.js';
 import type { CdnMeta } from './dataLoader.js';
-export interface ValidationError {
+interface ValidationError {
     type: 'invalid_modifier' | 'invalid_element' | 'unknown_component' | 'missing_root_class' | 'mixed_namespace' | 'missing_cdn';
     class: string;
     component: string;
@@ -14,13 +14,13 @@ export interface ValidationError {
     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: {
+declare const collectBemErrors: (params: {
     elements: ReturnType<ReturnType<typeof parse>["querySelectorAll"]>;
     rootClassMap: Map<string, string>;
     componentMap: Map<string, ComponentData>;
@@ -31,6 +31,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(' '));