@muloka/figma-console-mcp 0.5.0 → 0.5.2

package/dist/cloudflare/core/diff/diff-engine.js

@@ -1,334 +0,0 @@
-/**
- * Diff engine — pure functions for comparing Figma file/node snapshots
- * across two versions.
- *
- * Scope (v1):
- *   - Page-structure diff (added/removed/renamed pages) from depth=1 file fetches
- *   - Per-node diff for scoped fetches: name, description, children added/removed,
- *     componentPropertyDefinitions changes (for COMPONENT_SET), boundVariables changes
- *
- * NOT in scope (deferred):
- *   - Variable VALUE history (Figma REST does not expose this; planned forward
- *     ledger will fill the gap going forward, never retroactively)
- *   - Style-content diffs (only style add/remove via reachable styles map)
- *   - Inside-fills/strokes binding diffs (top-level boundVariables only for v1)
- */
-/**
- * Compare two file documents (from /v1/files/:key?version=X with depth=1 or higher).
- * Both arguments should be the `document` field of a Figma file response.
- */
-export function diffPageStructure(fromDoc, toDoc) {
-    const fromPages = extractPages(fromDoc);
-    const toPages = extractPages(toDoc);
-    const fromById = new Map(fromPages.map((p) => [p.id, p]));
-    const toById = new Map(toPages.map((p) => [p.id, p]));
-    const added = [];
-    const removed = [];
-    const renamed = [];
-    for (const p of toPages) {
-        if (!fromById.has(p.id)) {
-            added.push(p);
-        }
-        else {
-            const old = fromById.get(p.id);
-            if (old.name !== p.name) {
-                renamed.push({ id: p.id, old_name: old.name, new_name: p.name });
-            }
-        }
-    }
-    for (const p of fromPages) {
-        if (!toById.has(p.id))
-            removed.push(p);
-    }
-    return {
-        pages_added: added,
-        pages_removed: removed,
-        pages_renamed: renamed,
-        summary: {
-            added: added.length,
-            removed: removed.length,
-            renamed: renamed.length,
-        },
-    };
-}
-function extractPages(doc) {
-    const children = doc?.children;
-    if (!Array.isArray(children))
-        return [];
-    return children
-        .filter((c) => c && typeof c.id === "string" && typeof c.name === "string")
-        .map((c) => ({ id: c.id, name: c.name }));
-}
-/**
- * Diff a COMPONENT_SET's componentPropertyDefinitions map.
- * Each definition is keyed by `propName#nodeId` in Figma's response.
- */
-export function diffComponentPropertyDefinitions(fromDefs, toDefs) {
-    const from = fromDefs ?? {};
-    const to = toDefs ?? {};
-    const added = [];
-    const removed = [];
-    const typeChanged = [];
-    const defaultChanged = [];
-    for (const key of Object.keys(to)) {
-        const toDef = to[key];
-        if (!(key in from)) {
-            added.push({ name: key, type: toDef.type, default_value: toDef.defaultValue });
-        }
-        else {
-            const fromDef = from[key];
-            if (fromDef.type !== toDef.type) {
-                typeChanged.push({ name: key, from_type: fromDef.type, to_type: toDef.type });
-            }
-            if (!deepEqual(fromDef.defaultValue, toDef.defaultValue)) {
-                defaultChanged.push({
-                    name: key,
-                    from_default: fromDef.defaultValue,
-                    to_default: toDef.defaultValue,
-                });
-            }
-        }
-    }
-    for (const key of Object.keys(from)) {
-        if (!(key in to)) {
-            const fromDef = from[key];
-            removed.push({ name: key, type: fromDef.type, default_value: fromDef.defaultValue });
-        }
-    }
-    return {
-        added,
-        removed,
-        type_changed: typeChanged,
-        default_changed: defaultChanged,
-        summary: {
-            added: added.length,
-            removed: removed.length,
-            type_changed: typeChanged.length,
-            default_changed: defaultChanged.length,
-        },
-    };
-}
-/**
- * Walk both node trees in parallel (matched by node id), comparing top-level
- * boundVariables. Inside-fills/strokes binding diffs are explicitly NOT included
- * in v1 — they add complexity for marginal additional value over node-level deltas.
- */
-export function collectBindingChanges(fromNode, toNode) {
-    const changes = [];
-    walkBoth(fromNode, toNode, (a, b) => {
-        const aBindings = extractTopLevelBindings(a);
-        const bBindings = extractTopLevelBindings(b);
-        const allKeys = new Set([...Object.keys(aBindings), ...Object.keys(bBindings)]);
-        for (const key of allKeys) {
-            const fromId = aBindings[key] ?? null;
-            const toId = bBindings[key] ?? null;
-            if (fromId === toId)
-                continue;
-            let kind;
-            if (fromId === null)
-                kind = "added";
-            else if (toId === null)
-                kind = "removed";
-            else
-                kind = "rebound";
-            changes.push({
-                node_id: (b ?? a).id,
-                node_name: (b ?? a).name ?? "",
-                property: key,
-                from_variable_id: fromId,
-                to_variable_id: toId,
-                change_kind: kind,
-            });
-        }
-    });
-    return changes;
-}
-function extractTopLevelBindings(node) {
-    const out = {};
-    const bv = node?.boundVariables;
-    if (!bv || typeof bv !== "object")
-        return out;
-    for (const [prop, ref] of Object.entries(bv)) {
-        if (ref && typeof ref === "object") {
-            // Single VARIABLE_ALIAS reference
-            if (ref.type === "VARIABLE_ALIAS" && typeof ref.id === "string") {
-                out[prop] = ref.id;
-                continue;
-            }
-            // Array of refs (e.g., fills binding can be an array — surface first match for v1)
-            if (Array.isArray(ref)) {
-                const first = ref.find((r) => r && r.type === "VARIABLE_ALIAS" && typeof r.id === "string");
-                if (first)
-                    out[`${prop}[0]`] = first.id;
-            }
-        }
-    }
-    return out;
-}
-function walkBoth(fromNode, toNode, visit) {
-    if (!fromNode && !toNode)
-        return;
-    visit(fromNode, toNode);
-    const fromChildren = Array.isArray(fromNode?.children) ? fromNode.children : [];
-    const toChildren = Array.isArray(toNode?.children) ? toNode.children : [];
-    const byIdFrom = new Map();
-    for (const c of fromChildren)
-        if (c?.id)
-            byIdFrom.set(c.id, c);
-    const byIdTo = new Map();
-    for (const c of toChildren)
-        if (c?.id)
-            byIdTo.set(c.id, c);
-    const allIds = new Set([...byIdFrom.keys(), ...byIdTo.keys()]);
-    for (const id of allIds) {
-        walkBoth(byIdFrom.get(id), byIdTo.get(id), visit);
-    }
-}
-/**
- * Diff a single node (typically a COMPONENT_SET) at depth=2. Either side may be
- * null/undefined to represent "newly added" or "removed entirely."
- */
-export function diffNode(fromNode, toNode, mode = "standard") {
-    const id = (toNode ?? fromNode)?.id ?? "";
-    const name = (toNode ?? fromNode)?.name ?? "";
-    const type = (toNode ?? fromNode)?.type ?? "";
-    const out = {
-        node_id: id,
-        node_name: name,
-        node_type: type,
-        name_changed: null,
-        description_changed: null,
-        children_added: [],
-        children_removed: [],
-        component_properties: null,
-        binding_changes: [],
-        change_count: 0,
-        notes: [],
-    };
-    if (!fromNode && toNode) {
-        out.notes.push("Node was added in the target version (no prior state to compare).");
-        out.change_count = 1;
-        return out;
-    }
-    if (fromNode && !toNode) {
-        out.notes.push("Node was removed in the target version (no later state to compare).");
-        out.change_count = 1;
-        return out;
-    }
-    if (!fromNode && !toNode) {
-        out.notes.push("Node not found in either version.");
-        return out;
-    }
-    if (fromNode.name !== toNode.name) {
-        out.name_changed = { from: fromNode.name, to: toNode.name };
-    }
-    if ((fromNode.description ?? "") !== (toNode.description ?? "")) {
-        out.description_changed = {
-            from: fromNode.description ?? "",
-            to: toNode.description ?? "",
-        };
-    }
-    const fromChildIds = new Set((fromNode.children ?? []).filter((c) => c?.id).map((c) => c.id));
-    const toChildIds = new Set((toNode.children ?? []).filter((c) => c?.id).map((c) => c.id));
-    for (const c of toNode.children ?? []) {
-        if (c?.id && !fromChildIds.has(c.id)) {
-            out.children_added.push({ id: c.id, name: c.name ?? "", type: c.type ?? "" });
-        }
-    }
-    for (const c of fromNode.children ?? []) {
-        if (c?.id && !toChildIds.has(c.id)) {
-            out.children_removed.push({ id: c.id, name: c.name ?? "", type: c.type ?? "" });
-        }
-    }
-    if (fromNode.type === "COMPONENT_SET" || toNode.type === "COMPONENT_SET") {
-        const propDiff = diffComponentPropertyDefinitions(fromNode.componentPropertyDefinitions, toNode.componentPropertyDefinitions);
-        const hasAny = propDiff.summary.added > 0 ||
-            propDiff.summary.removed > 0 ||
-            propDiff.summary.type_changed > 0 ||
-            propDiff.summary.default_changed > 0;
-        if (hasAny)
-            out.component_properties = propDiff;
-    }
-    out.binding_changes = collectBindingChanges(fromNode, toNode);
-    out.change_count =
-        (out.name_changed ? 1 : 0) +
-            (out.description_changed ? 1 : 0) +
-            out.children_added.length +
-            out.children_removed.length +
-            (out.component_properties
-                ? out.component_properties.summary.added +
-                    out.component_properties.summary.removed +
-                    out.component_properties.summary.type_changed +
-                    out.component_properties.summary.default_changed
-                : 0) +
-            out.binding_changes.length;
-    if (mode === "summary") {
-        // Strip detail arrays, keep counts only
-        out.children_added = [];
-        out.children_removed = [];
-        if (out.component_properties) {
-            out.component_properties = {
-                added: [],
-                removed: [],
-                type_changed: [],
-                default_changed: [],
-                summary: out.component_properties.summary,
-            };
-        }
-        out.binding_changes = [];
-    }
-    else if (mode === "standard") {
-        // Keep the lightweight summaries (children_added, children_removed,
-        // component_properties.summary). Strip the heavy detail arrays.
-        if (out.component_properties) {
-            out.component_properties = {
-                added: out.component_properties.added.map((p) => ({ ...p, default_value: undefined })),
-                removed: out.component_properties.removed.map((p) => ({
-                    ...p,
-                    default_value: undefined,
-                })),
-                type_changed: out.component_properties.type_changed,
-                default_changed: out.component_properties.default_changed.map((d) => ({
-                    name: d.name,
-                    from_default: undefined,
-                    to_default: undefined,
-                })),
-                summary: out.component_properties.summary,
-            };
-        }
-        // Bindings: keep as-is, they're already compact.
-    }
-    // mode === "detailed" → keep everything
-    return out;
-}
-// ============================================================================
-// Helpers
-// ============================================================================
-function deepEqual(a, b) {
-    if (a === b)
-        return true;
-    if (a === null || b === null)
-        return false;
-    if (typeof a !== typeof b)
-        return false;
-    if (typeof a !== "object")
-        return false;
-    if (Array.isArray(a) !== Array.isArray(b))
-        return false;
-    if (Array.isArray(a)) {
-        if (a.length !== b.length)
-            return false;
-        for (let i = 0; i < a.length; i++)
-            if (!deepEqual(a[i], b[i]))
-                return false;
-        return true;
-    }
-    const aKeys = Object.keys(a);
-    const bKeys = Object.keys(b);
-    if (aKeys.length !== bKeys.length)
-        return false;
-    for (const k of aKeys)
-        if (!deepEqual(a[k], b[k]))
-            return false;
-    return true;
-}

package/dist/cloudflare/core/diff/property-compare.js

@@ -1,36 +0,0 @@
-/**
- * Property comparison primitives.
- *
- * Pure helper functions used by both the design-code parity tools and
- * the version diff engine. Moved here from src/core/design-code-tools.ts
- * so multiple consumers can share without circular dependencies.
- */
-/** Convert Figma RGBA (0-1 floats) to hex string */
-export function figmaRGBAToHex(color) {
-    const r = Math.round(color.r * 255);
-    const g = Math.round(color.g * 255);
-    const b = Math.round(color.b * 255);
-    const hex = `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`.toUpperCase();
-    if (color.a !== undefined && color.a < 1) {
-        const a = Math.round(color.a * 255);
-        return `${hex}${a.toString(16).padStart(2, "0")}`;
-    }
-    return hex;
-}
-/** Normalize a color string for comparison (uppercase hex without alpha if fully opaque) */
-export function normalizeColor(color) {
-    let c = color.trim().toUpperCase();
-    // Strip alpha if fully opaque (FF)
-    if (c.length === 9 && c.endsWith("FF")) {
-        c = c.slice(0, 7);
-    }
-    // Expand shorthand (#RGB -> #RRGGBB)
-    if (/^#[0-9A-F]{3}$/.test(c)) {
-        c = `#${c[1]}${c[1]}${c[2]}${c[2]}${c[3]}${c[3]}`;
-    }
-    return c;
-}
-/** Compare numeric values with a tolerance */
-export function numericClose(a, b, tolerance = 1) {
-    return Math.abs(a - b) <= tolerance;
-}

package/dist/cloudflare/core/diff/version-cache.js

@@ -1,74 +0,0 @@
-/**
- * In-memory LRU cache for Figma file snapshots at past versions.
- *
- * Past versions are immutable, so a cached snapshot for `${fileKey}:${versionId}`
- * never goes stale. The cache is process-scoped (no persistence) and bounded by
- * a max-entries cap rather than a byte budget — keeps the implementation simple
- * and avoids assumptions about JSON serialization size.
- *
- * HEAD ("current") is intentionally NOT cached because it changes on every save.
- * Callers should pass `null` as the versionId for HEAD requests; the cache
- * methods short-circuit on null.
- *
- * Usage:
- *   const cache = new VersionSnapshotCache();
- *   const key = cache.makeKey(fileKey, versionId, depth, nodeIds);
- *   let snapshot = cache.get(key);
- *   if (!snapshot) {
- *     snapshot = await api.getFile(fileKey, { version: versionId, depth });
- *     cache.set(key, snapshot);
- *   }
- */
-export class VersionSnapshotCache {
-    constructor(options = {}) {
-        // Map preserves insertion order — first key is the LRU.
-        this.store = new Map();
-        this.maxEntries = options.maxEntries ?? 50;
-    }
-    /**
-     * Build a stable cache key from the request parameters.
-     * Returns null for HEAD requests (versionId is null/undefined/empty).
-     */
-    makeKey(fileKey, versionId, depth, nodeIds) {
-        if (!versionId)
-            return null;
-        const idsHash = nodeIds && nodeIds.length > 0
-            ? [...nodeIds].sort().join(",")
-            : "";
-        const depthPart = depth === undefined ? "full" : String(depth);
-        return `${fileKey}:${versionId}:${depthPart}:${idsHash}`;
-    }
-    get(key) {
-        if (key === null)
-            return undefined;
-        if (!this.store.has(key))
-            return undefined;
-        // Refresh recency: delete + re-insert moves the key to the end.
-        const value = this.store.get(key);
-        this.store.delete(key);
-        this.store.set(key, value);
-        return value;
-    }
-    set(key, value) {
-        if (key === null)
-            return;
-        if (this.store.has(key))
-            this.store.delete(key);
-        this.store.set(key, value);
-        while (this.store.size > this.maxEntries) {
-            const oldestKey = this.store.keys().next().value;
-            if (oldestKey === undefined)
-                break;
-            this.store.delete(oldestKey);
-        }
-    }
-    has(key) {
-        return key !== null && this.store.has(key);
-    }
-    get size() {
-        return this.store.size;
-    }
-    clear() {
-        this.store.clear();
-    }
-}