@sangheepark/figma-ds-mcp 0.2.3 → 0.2.5

package/dist/tools/pipeline-tools.js

@@ -21,6 +21,7 @@ const FIGMA_STYLE_KEYS = new Set([
     'opacity', 'font-family', 'font-size', 'font-weight', 'color',
     'text-align', 'line-height', 'letter-spacing', 'text-decoration',
     'text-style', 'effect-style',
+    'backdrop-filter',
 ]);
 // emoji 감지 정규식 (surrogate pairs + common symbols)
 const EMOJI_PATTERN = /[\u{1F300}-\u{1F9FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}\u{FE00}-\u{FE0F}\u{200D}\u{20E3}\u{E0020}-\u{E007F}▶♡►◄●○■□★☆♪♫✓✗←→↑↓]/u;
@@ -111,18 +112,52 @@ function enrichSpec(traversal, mapping) {
             if (component) {
                 node['library-key'] = component['library-key'];
                 // Step 2: _ds_props → variant-props + overrides 분리
+                // value 역검색 + default fallback 로직 포함
                 if (node._ds_props) {
                     const variantProps = {};
                     const overrides = {};
                     for (const [key, value] of Object.entries(node._ds_props)) {
                         if (component.variants && key in component.variants) {
-                            // variant axis에 해당하는 prop
+                            // 1) exact key match → variant-props
                             if (typeof value === 'string' && component.defaults?.[key] !== value) {
                                 variantProps[key] = value;
                             }
                         }
+                        else if (component.variants && typeof value === 'string') {
+                            // 2) exact match 실패 → value 역검색: 이 값을 가진 variant axis 찾기
+                            const matchingAxes = [];
+                            for (const [axis, options] of Object.entries(component.variants)) {
+                                if (axis in variantProps)
+                                    continue; // 이미 매핑된 axis 스킵
+                                if (options.includes(value) && component.defaults?.[axis] !== value) {
+                                    matchingAxes.push(axis);
+                                }
+                            }
+                            if (matchingAxes.length === 1) {
+                                // 정확히 1개 axis에서만 발견 → 매핑
+                                variantProps[matchingAxes[0]] = value;
+                            }
+                            // 0개 또는 2개 이상 → 매핑 포기 (default variant 사용)
+                        }
+                        else if (component.properties && typeof value === 'string') {
+                            // 3) variant가 아닌 prop → property name 역검색
+                            if (key in component.properties) {
+                                // exact property name match
+                                overrides[key] = value;
+                            }
+                            else {
+                                // exact match 실패 → TEXT property 자동 매핑
+                                const textProps = Object.entries(component.properties)
+                                    .filter(([, type]) => type === 'TEXT')
+                                    .map(([name]) => name);
+                                if (textProps.length === 1) {
+                                    overrides[textProps[0]] = value;
+                                }
+                                // 0개 또는 2개 이상 → 매핑 포기
+                            }
+                        }
                         else {
-                            // variant가 아닌 prop → overrides (text, boolean, swap)
+                            // boolean 등 기타 → overrides에 직접
                             overrides[key] = value;
                         }
                     }
@@ -169,8 +204,8 @@ function enrichSpec(traversal, mapping) {
                 if (normalized)
                     fontWeight = normalized;
             }
-            if (fontSize && fontWeight) {
-                const key = `${fontSize}/${fontWeight}`;
+            if (fontSize) {
+                const key = `${fontSize}/${fontWeight || '400'}`;
                 const textStyle = mapping.textStyles[key];
                 if (textStyle) {
                     node.style['text-style'] = textStyle;
@@ -200,6 +235,12 @@ function enrichSpec(traversal, mapping) {
             }
         }
         // Step 6: CSS → Figma 정규화
+        // 6-pre: overflow:hidden → layout.clip-content 변환 (6-A 필터링 전에 처리)
+        if (node.style && node.style['overflow'] === 'hidden') {
+            node.layout = node.layout || {};
+            node.layout['clip-content'] = true;
+            delete node.style['overflow'];
+        }
         // 6-A: CSS-only 속성 필터링 (Figma가 지원하지 않는 CSS 속성 제거)
         if (node.style) {
             for (const key of Object.keys(node.style)) {
@@ -215,6 +256,19 @@ function enrichSpec(traversal, mapping) {
                 node.layout.direction = 'column';
             }
         }
+        // 6-D: absolute + fill 정규화
+        // Figma에서 absolute 요소는 parent auto-layout에 참여하지 않으므로
+        // fill은 layoutSizingHorizontal/Vertical = 'FILL'로 처리 → constraints STRETCH 동작
+        // 별도 변환 불필요 — NodeBuilder가 absolute child에 fill을 적용하면 STRETCH로 동작
+        // 다만 x/y가 없으면 0으로 기본값 설정하여 parent 좌상단 정렬
+        if (node.layout?.positioning === 'absolute') {
+            if ((node.layout.width === 'fill' || node.layout.width === '100%') && node.layout.x === undefined) {
+                node.layout.x = '0';
+            }
+            if ((node.layout.height === 'fill' || node.layout.height === '100%') && node.layout.y === undefined) {
+                node.layout.y = '0';
+            }
+        }
         // children 재귀
         if (node.children) {
             node.children.forEach((child, i) => {
@@ -434,26 +488,42 @@ function splitWords(name) {
         .split('_')
         .filter(w => w.length > 0);
 }
-// 3-stage component matching
+// Thresholds for word-split matching
+const AUTO_MATCH_THRESHOLD = 0.80;
+const REVIEW_THRESHOLD = 0.40;
+function buildHint(entry) {
+    const parts = [];
+    if (entry.variants) {
+        const axes = Object.keys(entry.variants).join(', ');
+        parts.push(`variants: ${axes}`);
+    }
+    if (entry.properties) {
+        const props = Object.entries(entry.properties)
+            .map(([k, v]) => `${k}(${v.type})`)
+            .join(', ');
+        parts.push(`props: ${props}`);
+    }
+    return parts.join(' | ') || 'no variants/props';
+}
+// 3-stage component matching with review tier
 function matchComponent(dsName, allComponents) {
     // Stage 1: exact match (case-sensitive)
     const exact = allComponents.get(dsName);
     if (exact)
-        return { ...exact, matchType: 'exact' };
+        return { match: { ...exact, matchType: 'exact' } };
     // Stage 2: case-insensitive match
     const dsLower = dsName.toLowerCase();
     for (const [name, data] of allComponents) {
         if (name.toLowerCase() === dsLower) {
-            return { ...data, matchType: 'case-insensitive' };
+            return { match: { ...data, matchType: 'case-insensitive' } };
         }
     }
     // Stage 3: word-split intersection match
     const inputWords = new Set(splitWords(dsName));
     if (inputWords.size === 0)
-        return null;
-    let bestScore = 0;
-    let bestMatch = null;
-    let bestName = '';
+        return { match: null };
+    // Collect all scores
+    const scored = [];
     for (const [name, data] of allComponents) {
         const dataWords = new Set(splitWords(name));
         let intersection = 0;
@@ -461,19 +531,44 @@ function matchComponent(dsName, allComponents) {
             if (dataWords.has(w))
                 intersection++;
         }
-        const score = intersection / inputWords.size;
-        if (score > bestScore || (score === bestScore && bestName.length > name.length)) {
-            bestScore = score;
-            bestMatch = data;
-            bestName = name;
+        // Dice coefficient: balanced scoring that penalizes asymmetric matches
+        // e.g., "DropdownSingleSelect" (3 words) → "Select" (1 word): 2*1/(3+1) = 0.50
+        //        vs "dropdown_unique" (2 words): 2*1/(3+2) = 0.40
+        const total = inputWords.size + dataWords.size;
+        const score = total > 0 ? (2 * intersection) / total : 0;
+        if (score >= REVIEW_THRESHOLD) {
+            scored.push({ name, data, score });
         }
     }
-    if (bestScore >= 0.8 && bestMatch) {
-        return { ...bestMatch, matchType: `word-split(${bestScore.toFixed(2)})` };
+    scored.sort((a, b) => b.score - a.score);
+    // Auto-match: top score >= 0.80
+    if (scored.length > 0 && scored[0].score >= AUTO_MATCH_THRESHOLD) {
+        return {
+            match: { ...scored[0].data, matchType: `word-split(${scored[0].score.toFixed(2)})` },
+        };
+    }
+    // Review tier: 0.40 <= score < 0.80
+    if (scored.length > 0) {
+        const reviewCandidates = scored.slice(0, 3).map(s => ({
+            name: s.name,
+            score: parseFloat(s.score.toFixed(2)),
+            library: s.data.library,
+            hint: buildHint(s.data.entry),
+        }));
+        return { match: null, reviewCandidates };
     }
-    return null;
+    // No match at all
+    return { match: null };
 }
 function generateMapping(traversals, dataDir) {
+    // 0. Load _config.json for primary library
+    let primaryLibrary = null;
+    try {
+        const config = JSON.parse(readFileSync(join(dataDir, '_config.json'), 'utf-8'));
+        if (config.primary)
+            primaryLibrary = config.primary;
+    }
+    catch { /* _config.json not found — no primary, all libraries equal */ }
     // 1. Load all data files
     const files = readdirSync(dataDir);
     const allComponents = new Map();
@@ -529,8 +624,8 @@ function generateMapping(traversals, dataDir) {
                 if (normalized)
                     fontWeight = normalized;
             }
-            if (fontSize && fontWeight) {
-                fontSpecs.add(`${fontSize}/${fontWeight}`);
+            if (fontSize) {
+                fontSpecs.add(`${fontSize}/${fontWeight || '400'}`);
             }
         }
         // Collect top-level named frames as potential elements
@@ -542,49 +637,70 @@ function generateMapping(traversals, dataDir) {
     traversals.forEach(extractFromNode);
     // 3. Match components
     const components = {};
+    const reviewNeeded = [];
     for (const dsName of dsNames) {
-        const match = matchComponent(dsName, allComponents);
-        if (match) {
+        const result = matchComponent(dsName, allComponents);
+        if (result.match) {
             const comp = {
-                library: match.library,
-                'library-key': match.entry.key,
+                library: result.match.library,
+                'library-key': result.match.entry.key,
             };
-            if (match.entry.variants) {
+            if (result.match.entry.variants) {
                 const variants = {};
                 const defaults = {};
-                for (const [axis, info] of Object.entries(match.entry.variants)) {
+                for (const [axis, info] of Object.entries(result.match.entry.variants)) {
                     variants[axis] = info.options;
                     defaults[axis] = info.default;
                 }
                 comp.variants = variants;
                 comp.defaults = defaults;
             }
-            if (match.entry.properties) {
+            if (result.match.entry.properties) {
                 const properties = {};
-                for (const [propName, propInfo] of Object.entries(match.entry.properties)) {
+                for (const [propName, propInfo] of Object.entries(result.match.entry.properties)) {
                     properties[propName] = propInfo.type;
                 }
                 comp.properties = properties;
             }
             components[dsName] = comp;
         }
+        else if (result.reviewCandidates && result.reviewCandidates.length > 0) {
+            reviewNeeded.push({ dsName, candidates: result.reviewCandidates });
+        }
     }
     // 4. Match tokens (HEX → variable name)
     const tokens = {};
-    // Build reverse map: normalized HEX → variable name (semantic preferred)
+    // Build reverse map: normalized HEX → variable name
+    // Priority: primary library > semantic name > last seen
     const hexToVar = new Map();
     for (const v of allVariables) {
         const hex = normalizeHex(v.value);
         const existing = hexToVar.get(hex);
-        // Prefer semantic (non-primitive): variables without numbers at the end
-        if (!existing || (!isPrimitive(v.name) && isPrimitive(existing))) {
-            hexToVar.set(hex, `{${v.name}}`);
+        if (!existing) {
+            hexToVar.set(hex, { name: v.name, library: v.library });
+        }
+        else {
+            const existingIsPrimary = existing.library === primaryLibrary;
+            const newIsPrimary = v.library === primaryLibrary;
+            if (newIsPrimary && !existingIsPrimary) {
+                // Primary library always wins
+                hexToVar.set(hex, { name: v.name, library: v.library });
+            }
+            else if (existingIsPrimary && !newIsPrimary) {
+                // Existing is primary, keep it
+            }
+            else {
+                // Same priority (both primary or both non-primary): prefer semantic name
+                if (!isPrimitive(v.name) && isPrimitive(existing.name)) {
+                    hexToVar.set(hex, { name: v.name, library: v.library });
+                }
+            }
         }
     }
     for (const hex of hexColors) {
-        const varName = hexToVar.get(hex);
-        if (varName)
-            tokens[hex] = varName;
+        const match = hexToVar.get(hex);
+        if (match)
+            tokens[hex] = `{${match.name}}`;
     }
     // 5. Match text styles (fontSize/fontWeight → style name)
     const textStyles = {};
@@ -619,7 +735,7 @@ function generateMapping(traversals, dataDir) {
             };
         }
     }
-    return { elements, components, tokens, textStyles };
+    return { elements, components, tokens, textStyles, reviewNeeded };
 }
 function normalizeHex(hex) {
     let h = hex.toUpperCase();
@@ -735,6 +851,20 @@ Saves result to outputPath. Replaces ds-data-lookup sub-agent.`, {
             mkdirSync(dirname(outputPath), { recursive: true });
             writeFileSync(outputPath, JSON.stringify(result, null, 2));
             // Summary for context (not the full mapping)
+            const matchedDs = new Set(Object.keys(result.components || {}));
+            const reviewDs = new Set((result.reviewNeeded || []).map(r => r.dsName));
+            const allDs = new Set();
+            function collectDs(node) {
+                if (node._ds)
+                    allDs.add(node._ds);
+                node.children?.forEach(collectDs);
+            }
+            traversals.forEach(collectDs);
+            const unmatchedDs = [];
+            for (const ds of allDs) {
+                if (!matchedDs.has(ds) && !reviewDs.has(ds))
+                    unmatchedDs.push(ds);
+            }
             const summary = {
                 success: true,
                 savedTo: outputPath,
@@ -744,25 +874,177 @@ Saves result to outputPath. Replaces ds-data-lookup sub-agent.`, {
                     textStyles: Object.keys(result.textStyles || {}).length,
                     elements: Object.keys(result.elements || {}).length,
                 },
-                unmatchedDs: [],
+                reviewNeeded: result.reviewNeeded || [],
+                unmatchedDs,
             };
-            // Report unmatched _ds names
-            const matchedDs = new Set(Object.keys(result.components || {}));
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(summary, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        }, null, 2),
+                    }],
+            };
+        }
+    });
+    // run_pipeline — unified pipeline tool
+    server.tool('run_pipeline', `Run the full spec pipeline: generate_mapping → validate → enrich → gate → tree in one call.
+Supports 2-pass pattern: Pass 1 returns reviewNeeded (ambiguous matches). Agent decides, then Pass 2 with resolutions auto-applies decisions.
+If no reviewNeeded, completes in 1 pass.`, {
+        traversals: z.array(z.record(z.unknown())).describe('Array of traversal JSON root nodes'),
+        dataDir: z.string().describe('Path to blueprint data directory (e.g., .claude/blueprint/data/)'),
+        outputPath: z.string().describe('File path to save spec.json (mapping.json saved alongside)'),
+        resolutions: z.record(z.string()).optional().describe('Agent-decided mappings: { dsName: resolvedName }. Pass 2 only.'),
+    }, async ({ traversals, dataDir, outputPath, resolutions }) => {
+        try {
+            let tNodes = traversals;
+            // Step 0: Apply resolutions — replace _ds in traversal nodes
+            if (resolutions && Object.keys(resolutions).length > 0) {
+                // Deep clone to avoid mutating input
+                tNodes = JSON.parse(JSON.stringify(tNodes));
+                const res = resolutions;
+                function applyResolutions(node) {
+                    if (node._ds && res[node._ds]) {
+                        node._ds = res[node._ds];
+                    }
+                    node.children?.forEach(applyResolutions);
+                }
+                tNodes.forEach(applyResolutions);
+            }
+            // Step 1: Generate mapping
+            const mappingResult = generateMapping(tNodes, dataDir);
+            const mappingPath = outputPath.replace(/\.json$/, '') + '_mapping.json';
+            mkdirSync(dirname(mappingPath), { recursive: true });
+            writeFileSync(mappingPath, JSON.stringify(mappingResult, null, 2));
+            // If reviewNeeded exists and no resolutions provided → return early for agent decision
+            const review = mappingResult.reviewNeeded || [];
+            if (review.length > 0 && (!resolutions || Object.keys(resolutions).length === 0)) {
+                // Also report truly unmatched
+                const matchedDs = new Set(Object.keys(mappingResult.components || {}));
+                const reviewDs = new Set(review.map(r => r.dsName));
+                const allDs = new Set();
+                function collectAllDs(node) {
+                    if (node._ds)
+                        allDs.add(node._ds);
+                    node.children?.forEach(collectAllDs);
+                }
+                tNodes.forEach(collectAllDs);
+                const unresolved = [];
+                for (const ds of allDs) {
+                    if (!matchedDs.has(ds) && !reviewDs.has(ds))
+                        unresolved.push(ds);
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                phase: 'review',
+                                message: `${review.length} component(s) need agent review. Provide resolutions and call again.`,
+                                reviewNeeded: review,
+                                unresolved,
+                                mappingSavedTo: mappingPath,
+                                stats: {
+                                    components: Object.keys(mappingResult.components || {}).length,
+                                    tokens: Object.keys(mappingResult.tokens || {}).length,
+                                    textStyles: Object.keys(mappingResult.textStyles || {}).length,
+                                },
+                            }, null, 2),
+                        }],
+                };
+            }
+            // Step 2: Validate traversal(s)
+            const validationErrors = [];
+            const validationWarnings = [];
+            for (const t of tNodes) {
+                const vResult = validateTraversal(t);
+                validationErrors.push(...vResult.errors);
+                validationWarnings.push(...vResult.warnings);
+            }
+            // Step 3: Enrich spec for each traversal
+            const specs = [];
+            const enrichErrors = [];
+            for (const t of tNodes) {
+                const eResult = enrichSpec(t, mappingResult);
+                if (eResult.errors.length > 0) {
+                    enrichErrors.push(...eResult.errors);
+                }
+                specs.push(eResult.spec);
+            }
+            if (enrichErrors.length > 0) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                phase: 'enrich',
+                                errors: enrichErrors,
+                                validationWarnings,
+                            }, null, 2),
+                        }],
+                };
+            }
+            // Step 4: Gate check each spec
+            const gateResults = [];
+            for (const spec of specs) {
+                gateResults.push(gateCheck(spec));
+            }
+            const allGatesPass = gateResults.every(g => g.pass);
+            // Step 5: Save specs and generate trees
+            mkdirSync(dirname(outputPath), { recursive: true });
+            const trees = [];
+            const allStats = [];
+            if (specs.length === 1) {
+                writeFileSync(outputPath, JSON.stringify(specs[0], null, 2));
+                trees.push(specToTree(specs[0]));
+                allStats.push(countSpecNodes(specs[0]));
+            }
+            else {
+                // Multiple specs → save each with index
+                for (let i = 0; i < specs.length; i++) {
+                    const specPath = outputPath.replace(/\.json$/, `_${i}.json`);
+                    writeFileSync(specPath, JSON.stringify(specs[i], null, 2));
+                    trees.push(specToTree(specs[i]));
+                    allStats.push(countSpecNodes(specs[i]));
+                }
+            }
+            // Collect unresolved
+            const matchedDs = new Set(Object.keys(mappingResult.components || {}));
             const allDs = new Set();
-            function collectDs(node) {
+            function collectFinalDs(node) {
                 if (node._ds)
                     allDs.add(node._ds);
-                node.children?.forEach(collectDs);
+                node.children?.forEach(collectFinalDs);
             }
-            traversals.forEach(collectDs);
+            tNodes.forEach(collectFinalDs);
+            const unresolved = [];
             for (const ds of allDs) {
                 if (!matchedDs.has(ds))
-                    summary.unmatchedDs.push(ds);
+                    unresolved.push(ds);
             }
             return {
                 content: [{
                         type: 'text',
-                        text: JSON.stringify(summary, null, 2),
+                        text: JSON.stringify({
+                            success: allGatesPass,
+                            savedTo: outputPath,
+                            mappingSavedTo: mappingPath,
+                            tree: trees.length === 1 ? trees[0] : trees,
+                            stats: allStats.length === 1 ? allStats[0] : allStats,
+                            gateResult: gateResults.length === 1 ? gateResults[0] : gateResults,
+                            validationWarnings: validationWarnings.length > 0 ? validationWarnings : undefined,
+                            unresolved: unresolved.length > 0 ? unresolved : undefined,
+                            reviewNeeded: review.length > 0 ? review : undefined,
+                        }, null, 2),
                     }],
             };
         }
@@ -772,6 +1054,7 @@ Saves result to outputPath. Replaces ds-data-lookup sub-agent.`, {
                         type: 'text',
                         text: JSON.stringify({
                             success: false,
+                            phase: 'error',
                             error: err instanceof Error ? err.message : String(err),
                         }, null, 2),
                     }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sangheepark/figma-ds-mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "MCP server for Code to Figma Bridge — bridges Claude Code to Figma plugin via WebSocket",
   "type": "module",
   "main": "dist/index.js",