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

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/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.d.ts

@@ -1,21 +1,52 @@
-/**
- * render_to_html tool — 컴포넌트 속성을 전달하면 정확한 HTML + React 매핑을 반환 (순수 함수)
- *
- * DOM 환경과 React/ReactDOM은 server.ts에서 초기화하고 파라미터로 전달한다.
- * 이 파일에는 fs, path, require, let이 없다.
- */
-import type { ComponentData, ReactRuntime } from '../types.js';
+import type { ComponentData, JsApiInfo, ReactRuntime } from '../types.js';
 import type { CdnMeta, IconMeta } from '../utils/dataLoader.js';
 import { type McpToolResponse } from '../utils/response.js';
 /** render_to_html tool 파라미터 */
 export interface RenderToHtmlParams {
     componentMap: Map<string, ComponentData>;
     bundle: Record<string, unknown>;
+    iconBundle: Record<string, unknown>;
     cdnMeta: CdnMeta | null;
     iconMeta: IconMeta | null;
     reactRuntime: ReactRuntime;
+    jsApiMap: Map<string, JsApiInfo>;
     name: string;
     props?: Record<string, unknown>;
+    /**
+     * CDN init 패턴(Story 5.8) 생성 시 `<div id>` 접미사로 사용되는 고유 식별자.
+     * server.ts가 매 호출마다 `crypto.randomUUID().slice(0, 6)` 방식으로 생성해 주입한다.
+     * renderToHtml.ts는 순수 함수 원칙(파일 헤더 주석)을 위해 내부에서 랜덤을 생성하지 않는다.
+     */
+    instanceId: string;
 }
+/** Story 5.9: 사용자 props 에서 함수 prop 재귀 제거 (JSON 직렬화·deep merge 안전).
+ *  cdnDefaults 는 JSON 이라 함수 없음 → 사용자 props 만 정리.
+ *  Story 5.10: 외부 분기 모듈(`tools/external/editor.ts`)에서도 재사용 → export. */
+export declare const stripFunctionProps: (obj: unknown) => unknown;
+/** Story 5.9: cdnDefaults 와 사용자 props 를 deep merge.
+ *  - 사용자 값 우선 (lodash merge 의 두 번째 인자가 우선)
+ *  - 함수 prop 은 사용자 props 에서 stripFunctionProps 로 사전 제거
+ *  - DatePicker `datePickerOptions` 배열 한정: 각 항목의 `options` 에 cdnDefaults 의 첫 항목 options 를 per-element 부분 merge
+ *  - 다른 배열(`buttons` 등) 은 사용자 값 그대로
+ *  반환: { merged, defaultsApplied } — defaultsApplied 는 cdnDefaults 에 있고 사용자 props 에 없는 top-level 키 (defaultsUsed 응답용)
+ *  Story 5.10: 외부 분기 모듈(`tools/external/editor.ts`)에서도 재사용 → export. */
+export declare const mergeCdnDefaults: (componentName: string, cdnDefaults: Record<string, unknown> | undefined, userProps: Record<string, unknown>) => {
+    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;