@mp3wizard/figma-console-mcp 1.14.0

package/dist/cloudflare/core/enrichment/enrichment-service.js

@@ -0,0 +1,272 @@
+/**
+ * Enrichment Service
+ * Coordinates enrichment of Figma API responses
+ */
+import { StyleValueResolver } from "./style-resolver.js";
+import { RelationshipMapper } from "./relationship-mapper.js";
+export class EnrichmentService {
+    constructor(logger) {
+        // Caches
+        this.fileDataCache = new Map();
+        this.lastEnrichmentTime = new Map();
+        this.CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+        this.logger = logger;
+        this.styleResolver = new StyleValueResolver(logger);
+        this.relationshipMapper = new RelationshipMapper(logger);
+    }
+    /**
+     * Enrich styles response
+     */
+    async enrichStyles(styles, fileKey, options = {}, fileData) {
+        if (!options.enrich) {
+            return styles; // Return as-is if enrichment not requested
+        }
+        this.logger.info({ fileKey, count: styles.length }, "Enriching styles");
+        try {
+            // Get file data for relationships (use provided data if available)
+            const data = fileData || await this.getFileDataForEnrichment(fileKey);
+            const variables = this.extractVariablesMap(data);
+            // Build relationships if requested
+            if (options.include_usage) {
+                await this.relationshipMapper.buildRelationships(data);
+            }
+            const enrichedStyles = [];
+            for (const style of styles) {
+                const enriched = {
+                    ...style,
+                };
+                // Resolve value and variable reference
+                if (options.include_exports !== false) {
+                    const { value, variableRef } = await this.styleResolver.resolveStyleValue(style, variables, options.max_depth);
+                    enriched.resolved_value = value;
+                    enriched.variable_reference = variableRef;
+                    // Generate export formats
+                    if (value && options.export_formats) {
+                        enriched.export_formats = this.styleResolver.generateExportFormats(style.name, value, style.style_type, options.export_formats);
+                    }
+                }
+                // Add usage information
+                if (options.include_usage) {
+                    const styleId = style.node_id || style.key || style.id;
+                    enriched.used_in_components =
+                        this.relationshipMapper.getComponentsByStyle(styleId);
+                    enriched.usage_count =
+                        this.relationshipMapper.getStyleUsageCount(styleId);
+                }
+                enrichedStyles.push(enriched);
+            }
+            this.logger.info({ enrichedCount: enrichedStyles.length }, "Styles enrichment complete");
+            return enrichedStyles;
+        }
+        catch (error) {
+            this.logger.error({ error }, "Failed to enrich styles");
+            return styles; // Return original on error
+        }
+    }
+    /**
+     * Enrich variables response
+     */
+    async enrichVariables(variables, fileKey, options = {}, fileData) {
+        if (!options.enrich) {
+            return variables;
+        }
+        this.logger.info({ fileKey, count: variables.length }, "Enriching variables");
+        try {
+            const data = fileData || await this.getFileDataForEnrichment(fileKey);
+            const variablesMap = this.extractVariablesMap(data);
+            // Build relationships if requested
+            if (options.include_usage) {
+                await this.relationshipMapper.buildRelationships(data);
+            }
+            const enrichedVars = [];
+            for (const variable of variables) {
+                const enriched = {
+                    ...variable,
+                };
+                // Resolve values for all modes
+                if (options.include_exports !== false) {
+                    const resolved_values = {};
+                    for (const [modeId, value] of Object.entries(variable.valuesByMode || {})) {
+                        const resolvedValue = await this.styleResolver.resolveVariableValue(variable, variablesMap, options.max_depth);
+                        resolved_values[modeId] = resolvedValue;
+                    }
+                    enriched.resolved_values = resolved_values;
+                    // Generate export formats using first mode
+                    const firstModeValue = Object.values(resolved_values)[0];
+                    if (firstModeValue && options.export_formats) {
+                        enriched.export_formats = this.styleResolver.generateExportFormats(variable.name, firstModeValue, variable.resolvedType, options.export_formats);
+                    }
+                }
+                // Add usage information
+                if (options.include_usage) {
+                    enriched.used_in_styles =
+                        this.relationshipMapper.getStylesByVariable(variable.id);
+                    enriched.used_in_components =
+                        this.relationshipMapper.getComponentsByVariable(variable.id);
+                    enriched.usage_count =
+                        this.relationshipMapper.getVariableUsageCount(variable.id);
+                }
+                // Add dependencies
+                if (options.include_dependencies) {
+                    enriched.dependencies =
+                        this.relationshipMapper.getVariableDependencies(variable.id);
+                }
+                enrichedVars.push(enriched);
+            }
+            this.logger.info({ enrichedCount: enrichedVars.length }, "Variables enrichment complete");
+            return enrichedVars;
+        }
+        catch (error) {
+            this.logger.error({ error }, "Failed to enrich variables");
+            return variables;
+        }
+    }
+    /**
+     * Enrich component response
+     */
+    async enrichComponent(component, fileKey, options = {}, fileData) {
+        if (!options.enrich) {
+            return component;
+        }
+        this.logger.info({ fileKey, componentId: component.id }, "Enriching component");
+        try {
+            const enriched = {
+                ...component,
+            };
+            const data = fileData || await this.getFileDataForEnrichment(fileKey);
+            // Build relationships
+            await this.relationshipMapper.buildRelationships(data);
+            // Extract styles used
+            if (component.styles) {
+                const stylesUsed = [];
+                for (const [prop, styleId] of Object.entries(component.styles)) {
+                    const style = data.styles?.[styleId];
+                    if (style) {
+                        stylesUsed.push({
+                            style_id: styleId,
+                            style_name: style.name,
+                            style_type: style.style_type,
+                            property: prop,
+                        });
+                    }
+                }
+                enriched.styles_used = stylesUsed;
+            }
+            // Extract variables used
+            if (component.boundVariables) {
+                const varsUsed = [];
+                // This would need actual variable resolution
+                enriched.variables_used = varsUsed;
+            }
+            // Detect hardcoded values (simplified for now)
+            // TODO: Implement full hardcoded value detection
+            enriched.hardcoded_values = [];
+            // Calculate token coverage
+            const totalProps = (enriched.styles_used?.length || 0) + (enriched.variables_used?.length || 0) + (enriched.hardcoded_values?.length || 0);
+            const tokenProps = (enriched.styles_used?.length || 0) + (enriched.variables_used?.length || 0);
+            enriched.token_coverage =
+                totalProps > 0 ? Math.round((tokenProps / totalProps) * 100) : 0;
+            this.logger.info({ componentId: component.id, coverage: enriched.token_coverage }, "Component enrichment complete");
+            return enriched;
+        }
+        catch (error) {
+            this.logger.error({ error }, "Failed to enrich component");
+            return component;
+        }
+    }
+    /**
+     * Enrich file data response
+     */
+    async enrichFileData(fileData, options = {}) {
+        if (!options.enrich) {
+            return fileData;
+        }
+        this.logger.info({ fileKey: fileData.fileKey }, "Enriching file data");
+        try {
+            const enriched = {
+                ...fileData,
+            };
+            // Build relationships for statistics
+            await this.relationshipMapper.buildRelationships(fileData);
+            // Calculate statistics
+            const styles = Object.values(fileData.styles || {});
+            const variables = Array.from(this.extractVariablesMap(fileData).values());
+            const unusedStyles = this.relationshipMapper.getUnusedStyles(styles);
+            const unusedVars = this.relationshipMapper.getUnusedVariables(variables);
+            enriched.statistics = {
+                total_variables: variables.length,
+                total_styles: styles.length,
+                total_components: Object.keys(fileData.components || {}).length,
+                unused_variables: unusedVars.length,
+                unused_styles: unusedStyles.length,
+                average_token_coverage: 0, // TODO: Calculate from components
+                total_hardcoded_values: 0, // TODO: Calculate from components
+                audit_issues_count: 0, // TODO: Calculate from audit
+            };
+            // Calculate health score (simple formula)
+            const usageRate = variables.length > 0
+                ? ((variables.length - unusedVars.length) / variables.length) * 100
+                : 100;
+            enriched.health_score = Math.round(usageRate);
+            this.logger.info({ health_score: enriched.health_score }, "File data enrichment complete");
+            return enriched;
+        }
+        catch (error) {
+            this.logger.error({ error }, "Failed to enrich file data");
+            return fileData;
+        }
+    }
+    /**
+     * Get file data for enrichment (with caching)
+     * NOTE: This is a placeholder that returns the data passed in
+     * In a full implementation, this would fetch fresh data from Figma API
+     */
+    async getFileDataForEnrichment(fileKey, providedData) {
+        const now = Date.now();
+        const lastEnrich = this.lastEnrichmentTime.get(fileKey) || 0;
+        // Return cached if fresh
+        if (this.fileDataCache.has(fileKey) &&
+            now - lastEnrich < this.CACHE_TTL_MS) {
+            return this.fileDataCache.get(fileKey);
+        }
+        // If data is provided, use it (from the tool that called us)
+        // This avoids redundant API calls since the tool already fetched the data
+        const fileData = providedData || {
+            styles: {},
+            variables: {},
+            document: {},
+            components: {},
+        };
+        this.fileDataCache.set(fileKey, fileData);
+        this.lastEnrichmentTime.set(fileKey, now);
+        return fileData;
+    }
+    /**
+     * Set file data in cache (called by tools that already have the data)
+     */
+    setFileDataCache(fileKey, fileData) {
+        this.fileDataCache.set(fileKey, fileData);
+        this.lastEnrichmentTime.set(fileKey, Date.now());
+    }
+    /**
+     * Extract variables as a Map for efficient lookup
+     */
+    extractVariablesMap(fileData) {
+        const variablesMap = new Map();
+        if (fileData.variables) {
+            for (const [id, variable] of Object.entries(fileData.variables)) {
+                variablesMap.set(id, variable);
+            }
+        }
+        return variablesMap;
+    }
+    /**
+     * Clear all caches
+     */
+    clearCache() {
+        this.fileDataCache.clear();
+        this.lastEnrichmentTime.clear();
+        this.styleResolver.clearCache();
+        this.relationshipMapper.clear();
+    }
+}

package/dist/cloudflare/core/enrichment/index.js

@@ -0,0 +1,7 @@
+/**
+ * Enrichment module exports
+ * Phase 5: Enriched Data Extraction & Design System Auditing
+ */
+export { StyleValueResolver } from "./style-resolver.js";
+export { RelationshipMapper } from "./relationship-mapper.js";
+export { EnrichmentService } from "./enrichment-service.js";

package/dist/cloudflare/core/enrichment/relationship-mapper.js

@@ -0,0 +1,351 @@
+/**
+ * Relationship Mapper
+ * Maps relationships between styles, variables, and components
+ * Tracks usage counts and builds reverse lookup indexes
+ */
+export class RelationshipMapper {
+    constructor(logger) {
+        // Relationship indexes
+        this.componentsByStyle = new Map();
+        this.componentsByVariable = new Map();
+        this.stylesByVariable = new Map();
+        this.variableDependencies = new Map();
+        // Usage counters
+        this.styleUsageCount = new Map();
+        this.variableUsageCount = new Map();
+        this.logger = logger;
+    }
+    /**
+     * Build all relationship indexes from file data
+     */
+    async buildRelationships(fileData) {
+        this.logger.info("Building relationship indexes");
+        try {
+            // Clear existing indexes
+            this.clear();
+            // Build variable dependencies first
+            if (fileData.variables) {
+                await this.buildVariableDependencies(fileData.variables);
+            }
+            // Build style-variable relationships
+            if (fileData.styles && fileData.variables) {
+                await this.buildStyleVariableRelationships(fileData.styles, fileData.variables);
+            }
+            // Build component relationships
+            if (fileData.document) {
+                await this.buildComponentRelationships(fileData.document);
+            }
+            this.logger.info({
+                styles: this.componentsByStyle.size,
+                variables: this.componentsByVariable.size,
+            }, "Relationship indexes built successfully");
+        }
+        catch (error) {
+            this.logger.error({ error }, "Error building relationships");
+            throw error;
+        }
+    }
+    /**
+     * Get components that use a specific style
+     */
+    getComponentsByStyle(styleId) {
+        return this.componentsByStyle.get(styleId) || [];
+    }
+    /**
+     * Get components that use a specific variable
+     */
+    getComponentsByVariable(variableId) {
+        return this.componentsByVariable.get(variableId) || [];
+    }
+    /**
+     * Get styles that use a specific variable
+     */
+    getStylesByVariable(variableId) {
+        return this.stylesByVariable.get(variableId) || [];
+    }
+    /**
+     * Get variable dependencies (what variables this variable references)
+     */
+    getVariableDependencies(variableId) {
+        return this.variableDependencies.get(variableId) || [];
+    }
+    /**
+     * Get usage count for a style
+     */
+    getStyleUsageCount(styleId) {
+        return this.styleUsageCount.get(styleId) || 0;
+    }
+    /**
+     * Get usage count for a variable
+     */
+    getVariableUsageCount(variableId) {
+        return this.variableUsageCount.get(variableId) || 0;
+    }
+    /**
+     * Find unused styles (styles with zero usage)
+     */
+    getUnusedStyles(allStyles) {
+        const unused = [];
+        for (const style of allStyles) {
+            const usageCount = this.getStyleUsageCount(style.node_id || style.key || style.id);
+            if (usageCount === 0) {
+                unused.push({
+                    id: style.id || style.key,
+                    name: style.name,
+                    type: style.style_type || style.styleType,
+                    node_id: style.node_id || style.key,
+                });
+            }
+        }
+        return unused;
+    }
+    /**
+     * Find unused variables (variables with zero usage)
+     */
+    getUnusedVariables(allVariables) {
+        const unused = [];
+        for (const variable of allVariables) {
+            const usageCount = this.getVariableUsageCount(variable.id);
+            if (usageCount === 0) {
+                unused.push({
+                    id: variable.id,
+                    name: variable.name,
+                    collection: variable.variableCollectionId,
+                    resolvedType: variable.resolvedType,
+                });
+            }
+        }
+        return unused;
+    }
+    /**
+     * Build variable dependency graph (which variables reference which)
+     */
+    async buildVariableDependencies(variables) {
+        for (const [variableId, variable] of variables.entries()) {
+            const dependencies = this.extractVariableDependencies(variable, variables);
+            if (dependencies.length > 0) {
+                this.variableDependencies.set(variableId, dependencies);
+            }
+        }
+    }
+    /**
+     * Extract dependencies from a single variable
+     */
+    extractVariableDependencies(variable, allVariables, depth = 0) {
+        const dependencies = [];
+        // Check all modes for variable aliases
+        for (const [modeId, value] of Object.entries(variable.valuesByMode || {})) {
+            if (typeof value === "object" &&
+                value !== null &&
+                value.type === "VARIABLE_ALIAS") {
+                const targetId = value.id;
+                const targetVariable = allVariables.get(targetId);
+                if (targetVariable) {
+                    dependencies.push({
+                        id: targetId,
+                        name: targetVariable.name,
+                        type: "alias",
+                        depth,
+                    });
+                    // Increment usage count for the referenced variable
+                    const currentCount = this.variableUsageCount.get(targetId) || 0;
+                    this.variableUsageCount.set(targetId, currentCount + 1);
+                }
+            }
+        }
+        return dependencies;
+    }
+    /**
+     * Build relationships between styles and variables
+     */
+    async buildStyleVariableRelationships(styles, variables) {
+        for (const style of styles) {
+            const variableRefs = this.extractStyleVariableReferences(style);
+            for (const varRef of variableRefs) {
+                // Track which styles use this variable
+                if (!this.stylesByVariable.has(varRef)) {
+                    this.stylesByVariable.set(varRef, []);
+                }
+                this.stylesByVariable.get(varRef)?.push({
+                    id: style.id || style.key,
+                    name: style.name,
+                    type: style.style_type || style.styleType,
+                    node_id: style.node_id || style.key,
+                });
+                // Increment variable usage count
+                const currentCount = this.variableUsageCount.get(varRef) || 0;
+                this.variableUsageCount.set(varRef, currentCount + 1);
+            }
+        }
+    }
+    /**
+     * Extract variable references from a style
+     */
+    extractStyleVariableReferences(style) {
+        const refs = [];
+        // Check boundVariables
+        if (style.boundVariables) {
+            const props = ["fills", "strokes", "effects", "text"];
+            for (const prop of props) {
+                if (style.boundVariables[prop]) {
+                    const binding = style.boundVariables[prop];
+                    if (Array.isArray(binding)) {
+                        for (const b of binding) {
+                            if (b.id)
+                                refs.push(b.id);
+                        }
+                    }
+                    else if (binding.id) {
+                        refs.push(binding.id);
+                    }
+                }
+            }
+        }
+        return refs;
+    }
+    /**
+     * Build component relationships by traversing the document tree
+     */
+    async buildComponentRelationships(document) {
+        // Traverse all pages
+        if (document.children) {
+            for (const page of document.children) {
+                await this.traverseNode(page, page.name);
+            }
+        }
+    }
+    /**
+     * Recursively traverse nodes to find component instances and their style/variable usage
+     */
+    async traverseNode(node, pageName, path = []) {
+        const currentPath = [...path, node.name];
+        // Check if this node uses any styles
+        if (node.styles) {
+            this.trackNodeStyleUsage(node, pageName, currentPath);
+        }
+        // Check if this node uses any variables (via boundVariables)
+        if (node.boundVariables) {
+            this.trackNodeVariableUsage(node, pageName, currentPath);
+        }
+        // Recurse into children
+        if (node.children) {
+            for (const child of node.children) {
+                await this.traverseNode(child, pageName, currentPath);
+            }
+        }
+    }
+    /**
+     * Track which styles a node uses
+     */
+    trackNodeStyleUsage(node, pageName, path) {
+        const componentUsage = {
+            id: node.id,
+            name: node.name,
+            type: node.type,
+            page: pageName,
+        };
+        // Check all style properties (fill, stroke, text, effect, grid)
+        const styleProps = ["fill", "stroke", "text", "effect", "grid"];
+        for (const prop of styleProps) {
+            const styleId = node.styles?.[prop];
+            if (styleId) {
+                // Add to componentsByStyle index
+                if (!this.componentsByStyle.has(styleId)) {
+                    this.componentsByStyle.set(styleId, []);
+                }
+                this.componentsByStyle.get(styleId)?.push(componentUsage);
+                // Increment style usage count
+                const currentCount = this.styleUsageCount.get(styleId) || 0;
+                this.styleUsageCount.set(styleId, currentCount + 1);
+            }
+        }
+    }
+    /**
+     * Track which variables a node uses
+     */
+    trackNodeVariableUsage(node, pageName, path) {
+        const componentUsage = {
+            id: node.id,
+            name: node.name,
+            type: node.type,
+            page: pageName,
+        };
+        // Extract all variable IDs from boundVariables
+        const variableIds = this.extractNodeVariableReferences(node);
+        for (const varId of variableIds) {
+            // Add to componentsByVariable index
+            if (!this.componentsByVariable.has(varId)) {
+                this.componentsByVariable.set(varId, []);
+            }
+            this.componentsByVariable.get(varId)?.push(componentUsage);
+            // Increment variable usage count
+            const currentCount = this.variableUsageCount.get(varId) || 0;
+            this.variableUsageCount.set(varId, currentCount + 1);
+        }
+    }
+    /**
+     * Extract all variable references from a node's boundVariables
+     */
+    extractNodeVariableReferences(node) {
+        const refs = [];
+        if (!node.boundVariables)
+            return refs;
+        // boundVariables can have many properties (fills, strokes, etc.)
+        for (const [prop, binding] of Object.entries(node.boundVariables)) {
+            if (Array.isArray(binding)) {
+                for (const b of binding) {
+                    if (b.id)
+                        refs.push(b.id);
+                }
+            }
+            else if (binding && typeof binding === "object" && binding.id) {
+                refs.push(binding.id);
+            }
+        }
+        return refs;
+    }
+    /**
+     * Detect circular variable references
+     */
+    detectCircularReferences() {
+        const circular = [];
+        const visited = new Set();
+        const currentPath = [];
+        for (const [variableId] of this.variableDependencies) {
+            this.detectCircularDFS(variableId, visited, currentPath, circular);
+        }
+        return circular;
+    }
+    /**
+     * DFS helper for detecting circular references
+     */
+    detectCircularDFS(variableId, visited, currentPath, circular) {
+        if (currentPath.includes(variableId)) {
+            // Found a cycle
+            const cycleStart = currentPath.indexOf(variableId);
+            const cycle = currentPath.slice(cycleStart).concat(variableId);
+            circular.push({ chain: cycle });
+            return;
+        }
+        if (visited.has(variableId))
+            return;
+        visited.add(variableId);
+        currentPath.push(variableId);
+        const dependencies = this.variableDependencies.get(variableId) || [];
+        for (const dep of dependencies) {
+            this.detectCircularDFS(dep.id, visited, currentPath, circular);
+        }
+        currentPath.pop();
+    }
+    /**
+     * Clear all indexes and caches
+     */
+    clear() {
+        this.componentsByStyle.clear();
+        this.componentsByVariable.clear();
+        this.stylesByVariable.clear();
+        this.variableDependencies.clear();
+        this.styleUsageCount.clear();
+        this.variableUsageCount.clear();
+    }
+}