@hegemonart/get-design-done 1.30.6 → 1.31.0

package/scripts/lib/figma-extract/receiver.cjs

@@ -0,0 +1,273 @@
+'use strict';
+// scripts/lib/figma-extract/receiver.cjs — Plan 31-06 (Wave B.3)
+// Path C receiver; D-06: ephemeral + 127.0.0.1-only.
+//
+// The localhost half of Path C (D-04). The Figma plugin "GDD Sync" (31-05)
+// reads `figma.variables` from inside Figma (works on any plan — sidesteps the
+// spike's Variables-API-403 Enterprise blocker) and POSTs them here. This
+// receiver validates the payload against payload-schema.json and writes it into
+// the raw/ cache as variables.json, where digest.cjs (31-02) consumes it as
+// Path C via the `source:'gdd-plugin'` marker.
+//
+// Security properties are the WHOLE point (D-06):
+//   - Binds 127.0.0.1 ONLY (host '127.0.0.1', never 0.0.0.0) — unreachable off
+//     the loopback interface.
+//   - REFUSES any non-loopback remote with 403 (req.socket.remoteAddress gate),
+//     even though the bind already makes that essentially unreachable — defense
+//     in depth, and asserted by test via a mocked remote address.
+//   - Validates EVERY payload against the schema BEFORE touching disk (400 on
+//     invalid; nothing written).
+//   - Port is HARDCODED to 5179 — NOT read from env or a CLI flag (acceptance
+//     criterion). Changing it requires a code edit. There is intentionally no
+//     `process.env.*PORT*` read in this module.
+//   - EPHEMERAL: listens only for the duration of one extract run and exits on
+//     the FIRST valid receipt OR on a timeout — never a lingering open port.
+//
+// D-10: this module handles design variables ONLY. It NEVER touches the Figma
+// token (that's a REST-path concern, not Path C). There is no secret-handling
+// code here, and the logger seam receives lifecycle events + counts only —
+// never full payloads.
+
+const http = require('node:http');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const Ajv = require('ajv');
+
+const payloadSchema = require('./payload-schema.json');
+
+// ── constants (D-06 acceptance criterion: hardcoded, no env override) ─────────
+const RECEIVER_HOST = '127.0.0.1'; // loopback ONLY
+const RECEIVER_PORT = 5179; // HARDCODED — intentionally not read from process.env
+
+// The marker digest.cjs (31-02) keys on to route variables.json to Path C.
+const PLUGIN_PAYLOAD_MARKER = 'gdd-plugin';
+
+// Defensive body cap. Large design systems can ship sizeable variable sets
+// (the risk register notes streaming for the raw pull); 50MB is generous for a
+// variables-only JSON payload while still bounding memory from a hostile body.
+const MAX_BODY_BYTES = 50 * 1024 * 1024;
+
+// ── validator (Ajv is a hard repo dependency — package.json "ajv": "^8.18.0") ─
+// Compiled once at module load. Ajv 8 CJS: require('ajv') is the constructor.
+// NOTE: fail-fast (default, NO allErrors). The receiver validates an UNTRUSTED
+// HTTP body from the plugin; `allErrors: true` would walk the entire (possibly
+// hostile, deeply-nested) object collecting every violation — a resource-
+// exhaustion / DoS amplifier (CodeQL js/resources-exhaustion). Fail-fast stops
+// at the first violation, which is all the 400 response needs. The 50MB
+// MAX_BODY_BYTES cap bounds input size; fail-fast bounds traversal cost.
+const AjvCtor = Ajv.default || Ajv;
+const _ajv = new AjvCtor({ strict: false });
+const _validate = _ajv.compile(payloadSchema);
+
+/**
+ * Validate a parsed body against payload-schema.json.
+ * @param {*} body
+ * @returns {{ valid: boolean, errors: Array }}
+ */
+function validatePayload(body) {
+  const valid = _validate(body) === true;
+  return { valid, errors: valid ? [] : (_validate.errors || []) };
+}
+
+/** Normalize req.socket.remoteAddress to a loopback test (IPv4, IPv6, mapped). */
+function isLoopbackRemote(remoteAddress) {
+  return (
+    remoteAddress === '127.0.0.1' ||
+    remoteAddress === '::1' ||
+    remoteAddress === '::ffff:127.0.0.1'
+  );
+}
+
+/** Read the full request body with a hard size cap. Rejects on overflow. */
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error('payload too large'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+/** No-op logger fallback. The real seam receives lifecycle events + counts only. */
+function emit(logger, event) {
+  if (typeof logger === 'function') {
+    try {
+      logger(event);
+    } catch {
+      /* a broken logger must never crash the receiver */
+    }
+  }
+}
+
+/**
+ * Build the request handler. Exported (`createHandler`) so tests can exercise
+ * the loopback gate / routing synchronously by invoking it with a fake req/res
+ * — no real remote socket needed (D-06 refusal path is asserted this way).
+ *
+ * The `onReceipt(parsed, filePath)` callback is invoked exactly once, on the
+ * first VALID localhost POST, AFTER the file is written. startReceiver wires it
+ * to close the server + resolve. Non-localhost (403), bad route (404), parse
+ * error / schema-invalid (400) NEVER call onReceipt — the server keeps waiting.
+ *
+ * @param {object} opts
+ * @param {string} opts.outDir
+ * @param {Function} [opts.logger]
+ * @param {Function} opts.onReceipt  async (parsed, filePath) => void
+ * @returns {Function} (req, res) => void
+ */
+function createHandler({ outDir, logger, onReceipt }) {
+  return function handler(req, res) {
+    // (1) Loopback gate FIRST (D-06) — defense in depth on top of the bind.
+    const remoteAddress = req.socket && req.socket.remoteAddress;
+    if (!isLoopbackRemote(remoteAddress)) {
+      emit(logger, { event: 'reject-403', reason: 'non-localhost' });
+      res.writeHead(403, { 'content-type': 'text/plain' });
+      res.end('forbidden: non-localhost');
+      return;
+    }
+
+    // (2) Route — only POST /variables is handled.
+    if (req.method !== 'POST' || req.url !== '/variables') {
+      emit(logger, { event: 'reject-404', method: req.method, url: req.url });
+      res.writeHead(404, { 'content-type': 'text/plain' });
+      res.end('not found');
+      return;
+    }
+
+    // (3) Read + parse + validate + write. Any thrown error → 500 (no crash).
+    readBody(req)
+      .then(async (raw) => {
+        let parsed;
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          emit(logger, { event: 'reject-400', reason: 'malformed-json' });
+          res.writeHead(400, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: 'malformed-json' }));
+          return;
+        }
+
+        const { valid, errors } = validatePayload(parsed);
+        if (!valid) {
+          emit(logger, { event: 'reject-400', reason: 'schema', errorCount: errors.length });
+          res.writeHead(400, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: 'schema', details: errors }));
+          return;
+        }
+
+        // Valid. Stamp the marker if (defensively) absent, then write the file.
+        if (parsed.source !== PLUGIN_PAYLOAD_MARKER) parsed.source = PLUGIN_PAYLOAD_MARKER;
+        const filePath = path.join(outDir, 'variables.json');
+        await fs.mkdir(outDir, { recursive: true });
+        await fs.writeFile(filePath, JSON.stringify(parsed));
+
+        emit(logger, {
+          event: 'receipt',
+          path: filePath,
+          collections: Array.isArray(parsed.collections) ? parsed.collections.length : 0,
+          variables: Array.isArray(parsed.variables) ? parsed.variables.length : 0,
+        });
+
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+
+        if (typeof onReceipt === 'function') await onReceipt(parsed, filePath);
+      })
+      .catch((err) => {
+        // Body-too-large or unexpected I/O error. Do NOT leak internals; do NOT
+        // resolve the receipt. 500 keeps the server waiting for a retry.
+        emit(logger, { event: 'error', message: err && err.message });
+        if (!res.headersSent) {
+          res.writeHead(500, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: 'internal' }));
+        }
+      });
+  };
+}
+
+/**
+ * Start the ephemeral Path C receiver.
+ *
+ * @param {object} opts
+ * @param {string} opts.outDir              REQUIRED — writes <outDir>/variables.json on valid receipt
+ * @param {number} [opts.timeoutMs=120000]  exits if no valid payload arrives in time
+ * @param {Function} [opts.logger]          structured lifecycle sink (never receives secrets/full payloads)
+ * @returns {Promise<{received:true, path:string} | {received:false, reason:'timeout'}>}
+ *
+ * Resolves with `{received:true, path}` on the FIRST valid POST /variables, or
+ * `{received:false, reason:'timeout'}` on timeout. The server is closed on BOTH
+ * exit paths (ephemeral — D-06). Non-localhost → 403; schema-invalid → 400;
+ * neither resolves the promise (the server keeps waiting until receipt/timeout).
+ */
+function startReceiver({ outDir, timeoutMs = 120000, logger } = {}) {
+  if (!outDir) {
+    return Promise.reject(new TypeError('startReceiver: opts.outDir is required'));
+  }
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer = null;
+    let server = null;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      // Close the server on BOTH exit paths so the port is never left open and
+      // the event loop can drain (process can exit). close() is idempotent-safe.
+      if (server) server.close(() => resolve(result));
+      else resolve(result);
+    };
+
+    const handler = createHandler({
+      outDir,
+      logger,
+      onReceipt: (_parsed, filePath) => finish({ received: true, path: filePath }),
+    });
+
+    server = http.createServer(handler);
+
+    server.on('error', (err) => {
+      // Most likely EADDRINUSE (another receiver already bound 5179) — surface
+      // it to the caller rather than hanging. Only meaningful before listen.
+      if (!settled) {
+        settled = true;
+        if (timer) clearTimeout(timer);
+        reject(err);
+      }
+    });
+
+    server.listen(RECEIVER_PORT, RECEIVER_HOST, () => {
+      emit(logger, { event: 'listen', host: RECEIVER_HOST, port: RECEIVER_PORT });
+      // Arm the timeout only once we are actually listening.
+      timer = setTimeout(() => {
+        emit(logger, { event: 'timeout', timeoutMs });
+        finish({ received: false, reason: 'timeout' });
+      }, timeoutMs);
+      // Don't let the timeout itself keep the process alive past its purpose.
+      if (typeof timer.unref === 'function') timer.unref();
+    });
+  });
+}
+
+module.exports = {
+  startReceiver,
+  createHandler,
+  validatePayload,
+  isLoopbackRemote,
+  RECEIVER_PORT,
+  RECEIVER_HOST,
+  PLUGIN_PAYLOAD_MARKER,
+};

package/scripts/lib/figma-extract/render-md.cjs

@@ -0,0 +1,143 @@
+'use strict';
+/**
+ * Plan 31-02 — productionized from spike 001 digest.mjs buildDesignMd().
+ *
+ * Deterministic DESIGN.md renderer with a STABLE section order:
+ *   header (provenance) →
+ *   ## Tokens         (### Color, ### Typography, ### Other — only when non-empty) →
+ *   ## Components      (Total line; sets first, then ### Singleton components) →
+ *   ## Widgets / Pages
+ *
+ * Determinism guarantee: identical {tokens, components, widgets, fileMeta} input
+ * produces BYTE-IDENTICAL output. The ONLY nondeterministic value is the
+ * provenance line's `fetched_at`, which the caller injects (tests pass a fixed
+ * value). This module NEVER calls new Date()/Date.now() — required for 31-10's
+ * golden-snapshot baseline.
+ *
+ * Pure CommonJS, no external deps, no I/O.
+ */
+
+// Size-bounding slice caps (carried over verbatim from the spike for parity).
+const CAP_COLOR = 200;
+const CAP_TYPOGRAPHY = 100;
+const CAP_OTHER = 100;
+const CAP_VARIANTS = 20;
+const CAP_SINGLETONS = 100;
+const CAP_WIDGETS = 50;
+
+/**
+ * @param {object} input
+ * @param {Array} input.tokens       assembled tokens [{name,type,collection?,modes?,value?,description?}]
+ * @param {Array} input.components   from walk.cjs collectComponents().components
+ * @param {Array} input.widgets      from walk.cjs collectComponents().widgets
+ * @param {object} input.fileMeta    { file_key, fetched_at, name } — fetched_at is the only injected nondeterminism
+ * @returns {string} DESIGN.md body
+ */
+function renderDesignMd({ tokens, components, widgets, fileMeta }) {
+  const toks = Array.isArray(tokens) ? tokens : [];
+  const comps = Array.isArray(components) ? components : [];
+  const wids = Array.isArray(widgets) ? widgets : [];
+  const meta = fileMeta || {};
+
+  const colorTokens = toks.filter((t) => t.type === 'COLOR' || t.type === 'FILL');
+  const textTokens = toks.filter((t) => t.type === 'TEXT');
+  const otherTokens = toks.filter(
+    (t) => !['COLOR', 'FILL', 'TEXT'].includes(t.type)
+  );
+
+  const lines = [];
+  lines.push(`# DESIGN.md`);
+  lines.push(``);
+  lines.push(
+    `> Auto-generated from Figma file \`${meta.file_key}\` at ${meta.fetched_at}`
+  );
+  lines.push(`> Source: ${meta.name || 'Design system'}`);
+  lines.push(``);
+
+  // ── ## Tokens ──────────────────────────────────────────────────────────────
+  lines.push(`## Tokens`);
+  lines.push(``);
+
+  if (colorTokens.length) {
+    lines.push(`### Color`);
+    lines.push(``);
+    for (const t of colorTokens.slice(0, CAP_COLOR)) {
+      const modes = t.modes
+        ? Object.entries(t.modes)
+            .map(([m, v]) => `${m}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
+            .join(' | ')
+        : JSON.stringify(t.value);
+      lines.push(`- \`${t.name}\` — ${modes}`);
+    }
+    lines.push(``);
+  }
+
+  if (textTokens.length) {
+    lines.push(`### Typography`);
+    lines.push(``);
+    for (const t of textTokens.slice(0, CAP_TYPOGRAPHY)) {
+      const v = t.value || Object.values(t.modes || {})[0];
+      lines.push(`- \`${t.name}\` — ${typeof v === 'object' ? JSON.stringify(v) : v}`);
+    }
+    lines.push(``);
+  }
+
+  if (otherTokens.length) {
+    lines.push(`### Other`);
+    lines.push(``);
+    for (const t of otherTokens.slice(0, CAP_OTHER)) {
+      lines.push(`- \`${t.name}\` (${t.type})`);
+    }
+    lines.push(``);
+  }
+
+  // ── ## Components ───────────────────────────────────────────────────────────
+  lines.push(`## Components`);
+  lines.push(``);
+  const sets = comps.filter((c) => c.type === 'COMPONENT_SET');
+  const singles = comps.filter((c) => c.type === 'COMPONENT');
+  lines.push(
+    `Total: ${sets.length} component sets + ${singles.length} singleton components`
+  );
+  lines.push(``);
+
+  for (const c of sets) {
+    lines.push(`### ${c.name}`);
+    if (c.description) lines.push(`> ${c.description}`);
+    if (c.variants && c.variants.length) {
+      lines.push(`Variants (${c.variants.length}):`);
+      for (const v of c.variants.slice(0, CAP_VARIANTS)) lines.push(`- ${v}`);
+      if (c.variants.length > CAP_VARIANTS) {
+        lines.push(`- … +${c.variants.length - CAP_VARIANTS} more`);
+      }
+    }
+    if (c.props && c.props.length) {
+      lines.push(`Props:`);
+      for (const p of c.props) {
+        const opts = p.options ? ` [${p.options.join(', ')}]` : '';
+        lines.push(`- \`${p.name}\` (${p.type})${opts} — default: \`${p.default}\``);
+      }
+    }
+    lines.push(``);
+  }
+
+  if (singles.length) {
+    lines.push(`### Singleton components`);
+    lines.push(``);
+    for (const c of singles.slice(0, CAP_SINGLETONS)) {
+      lines.push(`- \`${c.name}\``);
+    }
+    lines.push(``);
+  }
+
+  // ── ## Widgets / Pages ──────────────────────────────────────────────────────
+  lines.push(`## Widgets / Pages`);
+  lines.push(``);
+  for (const w of wids.slice(0, CAP_WIDGETS)) {
+    lines.push(`- ${w.name} (\`${w.id}\`)`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { renderDesignMd };

package/scripts/lib/figma-extract/styles-resolver.cjs

@@ -0,0 +1,147 @@
+'use strict';
+// Plan 31-03 — Path B of D-04 (three-path token extraction).
+//
+// Fixes spike 001's 0-tokens bug. The spike's digest.mjs extractTokensFromStyles
+// (lines 96-132) looked up each /styles entry's `node_id` inside `file.document`
+// and found nothing — because published-style SOURCE nodes are NOT serialized into
+// the main document tree. They live in canvas frames that require a SEPARATE
+// `/files/:key/nodes?ids=...` fetch. This module implements that missing second pass:
+//
+//   step 1: read the /styles list (node_id + style_type + name)        <- caller supplies
+//   step 2: GET /files/:key/nodes?ids=<comma-joined> to read real values <- injected fetcher
+//
+// Resolution priority within D-04: Variables > plugin sync > styles. Styles (this
+// module) is the last-resort fallback for non-Enterprise, legacy-styles DSs.
+//
+// No direct network call lives here except inside the buildStylesResolver-bound
+// fetcher; tests drive resolveStyleTokens fully offline via an injected fetchNodes.
+
+// Chunk cap for /nodes?ids= requests. Figma limits URL length, so large style sets
+// are split into batches of this size and the results merged.
+const MAX_IDS_PER_REQUEST = 100;
+
+const DEFAULT_API_BASE = 'https://api.figma.com/v1';
+
+// rgb(0..1) channels → 2-hex; appends an alpha hex byte only when a < 1.
+// Ported from spike 001 digest.mjs rgbToHex (lines 13-17) — keep value shape identical.
+function rgbToHex({ r, g, b, a }) {
+  const to = (v) => Math.round((v || 0) * 255).toString(16).padStart(2, '0');
+  const hex = `#${to(r)}${to(g)}${to(b)}`;
+  return a !== undefined && a < 1 ? `${hex}${to(a)}` : hex;
+}
+
+// Split an array into contiguous chunks of at most `size`.
+function chunk(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+// Figma's /nodes response wraps each node under `.document`. Tolerate both the
+// wrapped shape ({ document: <node> }) and a bare node, so the resolver is robust
+// to either the live API or a flattened fixture.
+function unwrapNode(entry) {
+  if (!entry) return undefined;
+  return entry.document !== undefined ? entry.document : entry;
+}
+
+// Resolve a single style's value from its source node, by style_type.
+// Returns undefined when the node lacks the data for that type (style is then skipped).
+function resolveValue(styleType, node) {
+  if (!node) return undefined;
+  if (styleType === 'FILL') {
+    const fill = node.fills && node.fills[0];
+    if (fill && fill.color) return rgbToHex({ ...fill.color, a: fill.opacity });
+    return undefined;
+  }
+  if (styleType === 'TEXT') {
+    const st = node.style;
+    if (!st) return undefined;
+    return {
+      family: st.fontFamily,
+      weight: st.fontWeight,
+      size: st.fontSize,
+      lineHeight: st.lineHeightPx,
+      letterSpacing: st.letterSpacing,
+    };
+  }
+  if (styleType === 'EFFECT') {
+    const eff = node.effects && node.effects[0];
+    return eff !== undefined ? eff : undefined;
+  }
+  return undefined;
+}
+
+// Core two-step resolver (Path B). Pure transform over injected data — no network.
+//   stylesList: the /styles response body
+//               ({ meta: { styles: [{ node_id, style_type, name, description }] } })
+//   fetchNodes: async (ids: string[]) => /nodes response body
+//               ({ nodes: { <id>: { document: <node> } | <node> } })
+// Returns Array<{ name, type:'FILL'|'TEXT'|'EFFECT', value, description }>.
+//   FILL   → value = hex string (rgb→hex, alpha-aware)
+//   TEXT   → value = { family, weight, size, lineHeight, letterSpacing }
+//   EFFECT → value = the first effect object
+// Returns [] when stylesList has no styles (fetchNodes is NOT called), or when every
+// node lookup misses. A style whose node_id is absent from /nodes is skipped (graceful).
+async function resolveStyleTokens({ stylesList, fetchNodes }) {
+  const styles = (stylesList && stylesList.meta && stylesList.meta.styles) || [];
+  if (styles.length === 0) return [];
+  if (typeof fetchNodes !== 'function') {
+    throw new TypeError('resolveStyleTokens: fetchNodes must be a function');
+  }
+
+  // Step 2: batch the node_ids and fetch their real source nodes, merging into one map.
+  const ids = styles.map((s) => s.node_id).filter((id) => id != null);
+  const nodeMap = {};
+  for (const idChunk of chunk(ids, MAX_IDS_PER_REQUEST)) {
+    const body = await fetchNodes(idChunk);
+    const nodes = (body && body.nodes) || {};
+    for (const id of idChunk) {
+      const node = unwrapNode(nodes[id]);
+      if (node !== undefined) nodeMap[id] = node;
+    }
+  }
+
+  // Map each style onto its resolved value. Skip styles whose node missed or whose
+  // node lacked the data for its type.
+  const out = [];
+  for (const s of styles) {
+    const node = nodeMap[s.node_id];
+    if (!node) continue;
+    const value = resolveValue(s.style_type, node);
+    if (value !== undefined) {
+      out.push({
+        name: s.name,
+        type: s.style_type,
+        value,
+        description: s.description || '',
+      });
+    }
+  }
+  return out;
+}
+
+// Bind a resolver to a live (fileKey, token, fetchImpl, apiBase) so digest.cjs can
+// inject Path B. Returns an async fn(file, styles) — exactly the `stylesResolver(file, styles)`
+// seam shape digest.cjs (31-02) calls. It ignores `file` (the document tree never holds
+// the source nodes — that is the spike bug) and resolves `styles` via a /nodes fetcher.
+// 31-07's SKILL wires this for live runs. The token is sent ONLY as the X-Figma-Token
+// header and is NEVER logged or persisted (D-10).
+function buildStylesResolver({ fileKey, token, fetchImpl, apiBase } = {}) {
+  const base = apiBase || DEFAULT_API_BASE;
+  const doFetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : undefined);
+  return async function stylesResolver(_file, styles) {
+    const fetchNodes = async (ids) => {
+      if (typeof doFetch !== 'function') {
+        throw new Error('buildStylesResolver: no fetch implementation available');
+      }
+      const url = `${base}/files/${fileKey}/nodes?ids=${ids.join(',')}`;
+      const res = await doFetch(url, { headers: { 'X-Figma-Token': token } });
+      if (!res.ok) throw new Error(`/nodes ${res.status}`);
+      return res.json();
+    };
+    return resolveStyleTokens({ stylesList: styles, fetchNodes });
+  };
+}
+
+module.exports = { resolveStyleTokens, buildStylesResolver, MAX_IDS_PER_REQUEST, rgbToHex };

package/scripts/lib/figma-extract/walk.cjs

@@ -0,0 +1,100 @@
+'use strict';
+/**
+ * Plan 31-02 — productionized from spike 001 digest.mjs walk() + summarizeWidgets().
+ *
+ * Node-tree walker with VARIANT ROLLUP (decision D-02, variant rollup default-on).
+ *
+ * The spike proved a naive walk inflates the component count ~16× (2,593 vs 167
+ * entries) because each COMPONENT_SET's variant children are counted as separate
+ * components. The fix — locked here as the non-optional default — is to SKIP the
+ * COMPONENT children of a COMPONENT_SET and record their names as a `variants[]`
+ * field on the parent set. A COMPONENT_SET with N variant children therefore
+ * yields exactly ONE component entry, not N (+1).
+ *
+ * Pure CommonJS, no external deps, no I/O, no network.
+ *
+ * Exports:
+ *   walkDocument(node, ctx, parentIsSet)  — low-level recursive helper (unit-testable)
+ *   collectComponents(documentNode)       — top-level entry over file.document
+ */
+
+/**
+ * Recursive tree walker. Mutates `ctx` in place.
+ *
+ * @param {object|null|undefined} node          a Figma node (document/canvas/frame/component/…)
+ * @param {{components:Array, widgets:Array, depth:number}} ctx accumulator
+ * @param {boolean} [parentIsSet=false]         true when the parent node is a COMPONENT_SET
+ */
+function walkDocument(node, ctx, parentIsSet = false) {
+  if (!node) return;
+
+  // Rollup core: a COMPONENT is only a standalone component when its parent is
+  // NOT a COMPONENT_SET. COMPONENT children of a set are variants — skipped here
+  // (they are recorded as variants[] on the parent set below).
+  const isStandaloneComponent = node.type === 'COMPONENT' && !parentIsSet;
+
+  if (node.type === 'COMPONENT_SET' || isStandaloneComponent) {
+    ctx.components.push({
+      id: node.id,
+      name: node.name,
+      type: node.type,
+      description: node.description || '',
+      // Variant names live on the set's children; standalone components have none.
+      variants:
+        node.type === 'COMPONENT_SET'
+          ? (node.children || []).map((c) => c.name)
+          : undefined,
+      // componentPropertyDefinitions → flattened props. Figma suffixes prop keys
+      // with '#<id>' for uniqueness; strip it for the human-facing name.
+      props: node.componentPropertyDefinitions
+        ? Object.entries(node.componentPropertyDefinitions).map(([k, v]) => ({
+            name: k.split('#')[0],
+            type: v.type,
+            default: v.defaultValue,
+            options: v.variantOptions,
+          }))
+        : undefined,
+    });
+  }
+
+  // Top-level FRAMEs (depth 1 — direct children of a page/canvas) are widget /
+  // page candidates for downstream classification.
+  if (ctx.depth === 1 && node.type === 'FRAME') {
+    ctx.widgets.push({ id: node.id, name: node.name });
+  }
+
+  if (node.children) {
+    ctx.depth++;
+    // Children of a COMPONENT_SET are variants — flag so they are not re-pushed.
+    const childParentIsSet = node.type === 'COMPONENT_SET';
+    for (const child of node.children) walkDocument(child, ctx, childParentIsSet);
+    ctx.depth--;
+  }
+}
+
+/**
+ * Collect components (with variant rollup) and top-level frames from a document.
+ *
+ * @param {object} documentNode  file.document — has .children = pages (CANVAS nodes)
+ * @returns {{components:Array, widgets:Array}}
+ *   components: Array<{ id, name, type:'COMPONENT_SET'|'COMPONENT', description,
+ *                       variants?:string[], props?:Array<{name,type,default,options}> }>
+ *   widgets:    Array<{ id, name }>  — top-level FRAMEs (depth 1)
+ */
+function collectComponents(documentNode) {
+  const ctx = { components: [], widgets: [], depth: 0 };
+  if (!documentNode || !documentNode.children) {
+    return { components: ctx.components, widgets: ctx.widgets };
+  }
+  // Pages (CANVAS) sit at depth 0; their children are depth 1 — that's where
+  // top-level frames become widget candidates. Mirror the spike's depth handling
+  // by entering each page's children at depth 1.
+  for (const page of documentNode.children) {
+    if (!page || !page.children) continue;
+    ctx.depth = 1;
+    for (const child of page.children) walkDocument(child, ctx, false);
+  }
+  return { components: ctx.components, widgets: ctx.widgets };
+}
+
+module.exports = { walkDocument, collectComponents };