@muloka/figma-console-mcp 0.1.0

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();
+    }
+}

package/dist/cloudflare/core/enrichment/style-resolver.js

@@ -0,0 +1,346 @@
+/**
+ * Style Value Resolver
+ * Resolves style values from variable references and provides formatted outputs
+ */
+export class StyleValueResolver {
+    constructor(logger) {
+        this.cache = new Map();
+        this.variableCache = new Map();
+        this.logger = logger;
+    }
+    /**
+     * Resolve a style's value, handling variable references
+     */
+    async resolveStyleValue(style, variables, maxDepth = 10) {
+        const cacheKey = `style:${style.key || style.node_id}`;
+        // Check cache
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey);
+        }
+        try {
+            // Get the actual style node data
+            const styleData = await this.getStyleData(style);
+            if (!styleData) {
+                return { value: null };
+            }
+            // Check if this style uses a variable
+            const variableRef = this.findVariableReference(styleData);
+            if (variableRef && variables.has(variableRef.id)) {
+                // Resolve the variable value
+                const variable = variables.get(variableRef.id);
+                const resolvedValue = await this.resolveVariableValue(variable, variables, maxDepth);
+                const result = {
+                    value: resolvedValue,
+                    variableRef: {
+                        id: variableRef.id,
+                        name: variable.name,
+                        collection: variable.variableCollectionId,
+                        resolvedType: variable.resolvedType,
+                    },
+                };
+                this.cache.set(cacheKey, result);
+                return result;
+            }
+            // No variable reference, return direct value
+            const directValue = this.extractDirectValue(styleData, style.style_type);
+            const result = { value: directValue };
+            this.cache.set(cacheKey, result);
+            return result;
+        }
+        catch (error) {
+            this.logger.error({
+                error,
+                style: style.name,
+            }, "Error resolving style value");
+            return { value: null };
+        }
+    }
+    /**
+     * Resolve a variable's value, handling alias chains.
+     *
+     * `modeId` selects which mode's value to resolve; omitted, it falls back
+     * to the variable's first mode (legacy behavior for callers that don't
+     * care about modes). The cache is keyed per (variable, mode) so
+     * multi-mode variables don't all resolve to the first mode's value.
+     */
+    async resolveVariableValue(variable, allVariables, maxDepth = 10, currentDepth = 0, modeId) {
+        if (currentDepth >= maxDepth) {
+            this.logger.warn({
+                variable: variable.name,
+            }, "Max resolution depth reached");
+            return null;
+        }
+        // Pick the mode to resolve: the requested modeId when this variable
+        // has a value for it, otherwise the first available mode (alias
+        // targets in other collections have different modeIds).
+        const modes = Object.keys(variable.valuesByMode || {});
+        if (modes.length === 0) {
+            return null;
+        }
+        const effectiveMode = modeId !== undefined && variable.valuesByMode[modeId] !== undefined
+            ? modeId
+            : modes[0];
+        const cacheKey = `var:${variable.id}:${effectiveMode}`;
+        if (this.variableCache.has(cacheKey)) {
+            return this.variableCache.get(cacheKey);
+        }
+        try {
+            const value = variable.valuesByMode[effectiveMode];
+            // Check if this is an alias (reference to another variable)
+            if (value !== null && typeof value === "object" && value.type === "VARIABLE_ALIAS") {
+                const targetVariable = allVariables.get(value.id);
+                if (!targetVariable) {
+                    this.logger.warn({
+                        source: variable.name,
+                        targetId: value.id,
+                    }, "Variable alias target not found");
+                    return null;
+                }
+                // Recursively resolve the alias, carrying the requested modeId
+                // through so same-collection targets resolve the same mode.
+                const resolvedValue = await this.resolveVariableValue(targetVariable, allVariables, maxDepth, currentDepth + 1, modeId);
+                this.variableCache.set(cacheKey, resolvedValue);
+                return resolvedValue;
+            }
+            // Direct value - format based on type
+            const formattedValue = this.formatVariableValue(value, variable.resolvedType);
+            this.variableCache.set(cacheKey, formattedValue);
+            return formattedValue;
+        }
+        catch (error) {
+            this.logger.error({
+                error,
+                variable: variable.name,
+            }, "Error resolving variable value");
+            return null;
+        }
+    }
+    /**
+     * Format a variable value based on its type
+     */
+    formatVariableValue(value, type) {
+        // Guard only null/undefined — 0, false, and "" are legitimate
+        // variable values (opacity 0, boolean flags off, empty strings).
+        if (value === null || value === undefined)
+            return null;
+        switch (type) {
+            case "COLOR":
+                return this.formatColor(value);
+            case "FLOAT":
+            case "NUMBER":
+                return value;
+            case "STRING":
+                return value;
+            case "BOOLEAN":
+                return Boolean(value);
+            default:
+                return value;
+        }
+    }
+    /**
+     * Format a color value to hex string
+     */
+    formatColor(color) {
+        if (typeof color === "string") {
+            return color;
+        }
+        if (color.r !== undefined && color.g !== undefined && color.b !== undefined) {
+            const clampByte = (f) => Math.max(0, Math.min(255, Math.round(f * 255)));
+            const toHex = (byte) => byte.toString(16).padStart(2, "0");
+            const r = clampByte(color.r);
+            const g = clampByte(color.g);
+            const b = clampByte(color.b);
+            let hex = `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+            // Preserve alpha: append the alpha byte for semi-transparent colors
+            // (mirrors rgbaToHex in tokens/figma-converter.ts).
+            if (color.a !== undefined && color.a < 1) {
+                hex += toHex(clampByte(color.a));
+            }
+            return hex.toUpperCase();
+        }
+        return null;
+    }
+    /**
+     * Generate export formats for a resolved value
+     */
+    generateExportFormats(name, value, type, formats = ["css", "sass", "tailwind", "typescript", "json"]) {
+        const result = {};
+        // Sanitize name for different formats
+        const cssName = this.toCSSVariableName(name);
+        const sassName = this.toSassVariableName(name);
+        const tailwindName = this.toTailwindClassName(name);
+        const tsName = this.toTypeScriptPath(name);
+        const jsonPath = this.toJSONPath(name);
+        for (const format of formats) {
+            switch (format) {
+                case "css":
+                    result.css = `var(${cssName})`;
+                    break;
+                case "sass":
+                    result.sass = sassName;
+                    break;
+                case "tailwind":
+                    result.tailwind = tailwindName;
+                    break;
+                case "typescript":
+                    result.typescript = tsName;
+                    break;
+                case "json":
+                    result.json = jsonPath;
+                    break;
+            }
+        }
+        return result;
+    }
+    /**
+     * Convert token name to CSS variable format
+     * Example: "color/background/primary-default" -> "--color-background-primary-default"
+     */
+    toCSSVariableName(name) {
+        return `--${name.replace(/\//g, "-").toLowerCase()}`;
+    }
+    /**
+     * Convert token name to Sass variable format
+     * Example: "color/background/primary-default" -> "$color-background-primary-default"
+     */
+    toSassVariableName(name) {
+        return `$${name.replace(/\//g, "-").toLowerCase()}`;
+    }
+    /**
+     * Convert token name to Tailwind class format
+     * Example: "color/background/primary-default" -> "bg-primary"
+     */
+    toTailwindClassName(name) {
+        const parts = name.split("/");
+        // Try to infer Tailwind utility class
+        if (parts[0] === "color") {
+            if (parts[1] === "background") {
+                return `bg-${parts[parts.length - 1].toLowerCase()}`;
+            }
+            if (parts[1] === "text") {
+                return `text-${parts[parts.length - 1].toLowerCase()}`;
+            }
+            if (parts[1] === "border") {
+                return `border-${parts[parts.length - 1].toLowerCase()}`;
+            }
+        }
+        if (parts[0] === "spacing") {
+            return `space-${parts[parts.length - 1].toLowerCase()}`;
+        }
+        // Fallback: use last part
+        return parts[parts.length - 1].toLowerCase();
+    }
+    /**
+     * Convert token name to TypeScript path format
+     * Example: "color/background/primary-default" -> "tokens.color.background.primaryDefault"
+     */
+    toTypeScriptPath(name) {
+        const parts = name.split("/");
+        const camelCaseParts = parts.map((part, index) => {
+            if (index === 0)
+                return part.toLowerCase();
+            return part
+                .split("-")
+                .map((word, i) => i === 0
+                ? word.toLowerCase()
+                : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+                .join("");
+        });
+        return `tokens.${camelCaseParts.join(".")}`;
+    }
+    /**
+     * Convert token name to nested JSON path
+     * Example: "color/background/primary-default" -> { color: { background: { primaryDefault: value } } }
+     */
+    toJSONPath(name) {
+        const parts = name.split("/");
+        const result = {};
+        let current = result;
+        for (let i = 0; i < parts.length; i++) {
+            const key = parts[i]
+                .split("-")
+                .map((word, j) => j === 0
+                ? word.toLowerCase()
+                : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+                .join("");
+            if (i === parts.length - 1) {
+                current[key] = "[VALUE]"; // Placeholder
+            }
+            else {
+                current[key] = {};
+                current = current[key];
+            }
+        }
+        return result;
+    }
+    /**
+     * Get style data from Figma API
+     * This would be called via the Figma API client
+     */
+    async getStyleData(style) {
+        // TODO: Implement actual Figma API call
+        // For now, return the style object itself
+        return style;
+    }
+    /**
+     * Find variable reference in style data
+     */
+    findVariableReference(styleData) {
+        // Check for boundVariables (new variables API)
+        if (styleData.boundVariables) {
+            // Check common properties that can be bound to variables
+            const props = ["fills", "strokes", "effects", "text"];
+            for (const prop of props) {
+                if (styleData.boundVariables[prop]) {
+                    const binding = styleData.boundVariables[prop];
+                    if (Array.isArray(binding) && binding.length > 0) {
+                        return { id: binding[0].id };
+                    }
+                    if (binding.id) {
+                        return { id: binding.id };
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract direct value from style (no variable)
+     */
+    extractDirectValue(styleData, styleType) {
+        switch (styleType) {
+            case "FILL":
+                if (styleData.fills && styleData.fills.length > 0) {
+                    const fill = styleData.fills[0];
+                    if (fill.type === "SOLID") {
+                        return this.formatColor(fill.color);
+                    }
+                }
+                return null;
+            case "TEXT":
+                if (styleData.fontFamily) {
+                    return {
+                        fontFamily: styleData.fontFamily,
+                        fontSize: styleData.fontSize,
+                        fontWeight: styleData.fontWeight,
+                        lineHeight: styleData.lineHeight,
+                    };
+                }
+                return null;
+            case "EFFECT":
+                if (styleData.effects && styleData.effects.length > 0) {
+                    return styleData.effects;
+                }
+                return null;
+            default:
+                return null;
+        }
+    }
+    /**
+     * Clear the cache
+     */
+    clearCache() {
+        this.cache.clear();
+        this.variableCache.clear();
+    }
+}