@hegemonart/get-design-done 1.21.0 → 1.23.0

package/scripts/lib/design-tokens/figma.cjs

@@ -0,0 +1,121 @@
+/**
+ * design-tokens/figma.cjs — parse a Figma variable export JSON into
+ * a flat token map (Plan 23-08).
+ *
+ * Consumes the shape returned by mcp__figma__get_variable_defs (and the
+ * official Figma Variables Export JSON). Handles either:
+ *   * `{ variableCollections: { <id>: { name, modes, variables: { <id>: {name, valuesByMode} } } } }`
+ *   * Already-flattened `{ name: value }` map (passes through with format='figma')
+ *
+ * Mode handling: when a variable has multiple modes, we emit one token
+ * per mode using `<collection>.<varName>.<modeName>`. Single-mode
+ * variables emit the bare path.
+ *
+ * Color values are emitted as `rgba(R, G, B, A)` strings; numeric +
+ * string values pass through verbatim.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function rgbaFor(c) {
+  if (typeof c !== 'object' || c === null) return String(c);
+  const r = Math.round((Number(c.r) || 0) * 255);
+  const g = Math.round((Number(c.g) || 0) * 255);
+  const b = Math.round((Number(c.b) || 0) * 255);
+  const a = c.a === undefined ? 1 : Number(c.a);
+  return a === 1 ? `rgb(${r}, ${g}, ${b})` : `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+function valueToString(v) {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+    return String(v);
+  }
+  if (typeof v === 'object') {
+    // Color shape: {r, g, b, a?}.
+    if (Object.prototype.hasOwnProperty.call(v, 'r') &&
+        Object.prototype.hasOwnProperty.call(v, 'g') &&
+        Object.prototype.hasOwnProperty.call(v, 'b')) {
+      return rgbaFor(v);
+    }
+    // Alias / reference — emit the full reference id for the consumer to resolve.
+    if (v.type === 'VARIABLE_ALIAS' && v.id) return `var(--${v.id})`;
+    return JSON.stringify(v);
+  }
+  return String(v);
+}
+
+/**
+ * @param {string} filePath
+ * @returns {{tokens: Record<string, string>, source: string, format: 'figma', warnings: string[]}}
+ */
+function readFigma(filePath) {
+  const abs = path.resolve(filePath);
+  const raw = fs.readFileSync(abs, 'utf8');
+  /** @type {string[]} */
+  const warnings = [];
+  /** @type {unknown} */
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return {
+      tokens: {},
+      source: abs,
+      format: 'figma',
+      warnings: [`json-parse-failed: ${err.message}`],
+    };
+  }
+
+  /** @type {Record<string, string>} */
+  const out = {};
+  // Branch 1: variableCollections shape.
+  if (parsed && typeof parsed === 'object' && parsed.variableCollections) {
+    for (const collId of Object.keys(parsed.variableCollections)) {
+      const coll = parsed.variableCollections[collId];
+      const collName = coll.name || collId;
+      const modes = coll.modes || {};
+      // modes might be an array of {modeId, name} or a map.
+      const modeNames = Array.isArray(modes)
+        ? new Map(modes.map((m) => [m.modeId, m.name]))
+        : new Map(Object.entries(modes).map(([id, m]) => [id, (m && m.name) || id]));
+      const vars = coll.variables || {};
+      for (const varId of Object.keys(vars)) {
+        const v = vars[varId];
+        const varName = v.name || varId;
+        const valuesByMode = v.valuesByMode || {};
+        const modeIds = Object.keys(valuesByMode);
+        if (modeIds.length === 0) {
+          warnings.push(`no-modes: ${collName}.${varName}`);
+          continue;
+        }
+        if (modeIds.length === 1) {
+          const key = `${collName}.${varName}`;
+          out[key] = valueToString(valuesByMode[modeIds[0]]);
+        } else {
+          for (const mid of modeIds) {
+            const modeName = modeNames.get(mid) || mid;
+            out[`${collName}.${varName}.${modeName}`] = valueToString(valuesByMode[mid]);
+          }
+        }
+      }
+    }
+    return { tokens: out, source: abs, format: 'figma', warnings };
+  }
+
+  // Branch 2: already-flattened bag.
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    for (const k of Object.keys(parsed)) {
+      out[k] = valueToString(parsed[k]);
+    }
+    return { tokens: out, source: abs, format: 'figma', warnings };
+  }
+
+  warnings.push('unrecognised-figma-shape');
+  return { tokens: out, source: abs, format: 'figma', warnings };
+}
+
+module.exports = { readFigma };

package/scripts/lib/design-tokens/index.cjs

@@ -0,0 +1,100 @@
+/**
+ * design-tokens/index.cjs — facade over the four token readers
+ * (Plan 23-08).
+ *
+ * Auto-detects format from extension + content sniff, dispatches to
+ * css-vars / js-const / tailwind / figma. Returns the uniform
+ * `{tokens, source, format, warnings}` shape from each reader.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { readCssVars } = require('./css-vars.cjs');
+const { readJsConst } = require('./js-const.cjs');
+const { readTailwind } = require('./tailwind.cjs');
+const { readFigma } = require('./figma.cjs');
+
+/**
+ * @typedef {Object} TokenSet
+ * @property {Object<string, string>} tokens
+ * @property {string} source
+ * @property {'css-vars'|'js-const'|'tailwind'|'figma'} format
+ * @property {string[]} [warnings]
+ */
+
+/**
+ * Sniff format from a file's extension + a head-snippet of its content.
+ *
+ * @param {string} filePath
+ * @returns {'css-vars'|'js-const'|'tailwind'|'figma'}
+ */
+function detectFormat(filePath) {
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith('.css') || lower.endsWith('.scss')) return 'css-vars';
+  if (
+    /tailwind\.config\.(js|cjs|mjs|ts)$/.test(lower) ||
+    lower.endsWith('tailwind.config.js')
+  ) {
+    return 'tailwind';
+  }
+  if (lower.endsWith('.json')) {
+    // Sniff: variableCollections → figma, else js-const path with the JSON.
+    try {
+      const head = fs.readFileSync(filePath, 'utf8').slice(0, 4096);
+      if (head.includes('"variableCollections"')) return 'figma';
+    } catch {
+      /* fall through */
+    }
+    return 'figma';
+  }
+  // Default: any other JS/TS file is js-const.
+  return 'js-const';
+}
+
+/**
+ * Read tokens from a file with auto-detected format.
+ *
+ * @param {string} filePath
+ * @returns {TokenSet}
+ */
+function read(filePath) {
+  const format = detectFormat(filePath);
+  switch (format) {
+    case 'css-vars':
+      return readCssVars(filePath);
+    case 'tailwind':
+      return readTailwind(filePath);
+    case 'figma':
+      return readFigma(filePath);
+    case 'js-const':
+    default:
+      return readJsConst(filePath);
+  }
+}
+
+/**
+ * Read multiple files into separate TokenSets.
+ *
+ * @param {string[]} filePaths
+ * @returns {TokenSet[]}
+ */
+function readAll(filePaths) {
+  if (!Array.isArray(filePaths)) {
+    throw new TypeError('design-tokens: filePaths must be an array');
+  }
+  return filePaths.map((p) => read(p));
+}
+
+module.exports = {
+  read,
+  readAll,
+  detectFormat,
+  // re-export for callers that already know the format
+  readCssVars,
+  readJsConst,
+  readTailwind,
+  readFigma,
+};

package/scripts/lib/design-tokens/js-const.cjs

@@ -0,0 +1,107 @@
+/**
+ * design-tokens/js-const.cjs — load token modules via spawned-node
+ * subprocess (Plan 23-08).
+ *
+ * Why subprocess: the project may use ESM, CJS, or .ts (with type-strip
+ * runtimes); evaluating user JS in-process risks side effects + version
+ * skew. Fork a child node with a tiny harness that requires/imports the
+ * target file and prints its tokens as JSON.
+ *
+ * Recognised export shapes (in priority order):
+ *   1. `module.exports.tokens = { … }` (CJS named)
+ *   2. `module.exports = { tokens: { … } }` (CJS object with `tokens`)
+ *   3. `module.exports = { … }` (CJS bag — direct map of name→value)
+ *   4. `export const tokens = { … }` (ESM named) — handled via dynamic import in harness
+ *   5. `export default { tokens: { … } }` (ESM default) — same
+ *
+ * Returns flat `{name: value}` map. Nested objects flattened with `.`
+ * separator (e.g. `{color: {primary: '#abc'}}` → `color.primary`).
+ *
+ * Values are stringified via `String(value)`; arrays JSON-encoded.
+ */
+
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const HARNESS_PATH = require('node:path').join(__dirname, '_js-harness.cjs');
+
+/**
+ * Flatten a nested object into dotted keys.
+ *
+ * @param {unknown} val
+ * @param {string} prefix
+ * @param {Record<string, string>} out
+ */
+function flatten(val, prefix, out) {
+  if (val === null || val === undefined) return;
+  if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean') {
+    out[prefix] = String(val);
+    return;
+  }
+  if (Array.isArray(val)) {
+    out[prefix] = JSON.stringify(val);
+    return;
+  }
+  if (typeof val === 'object') {
+    for (const k of Object.keys(val)) {
+      const next = prefix ? `${prefix}.${k}` : k;
+      flatten(val[k], next, out);
+    }
+    return;
+  }
+  out[prefix] = String(val);
+}
+
+/**
+ * Read tokens from a JS/CJS/MJS module file.
+ *
+ * @param {string} filePath
+ * @returns {{tokens: Record<string, string>, source: string, format: 'js-const', warnings: string[]}}
+ */
+function readJsConst(filePath) {
+  const abs = path.resolve(filePath);
+  if (!fs.existsSync(abs)) {
+    throw new Error(`js-const: file not found: ${abs}`);
+  }
+  if (!fs.existsSync(HARNESS_PATH)) {
+    throw new Error(`js-const: harness missing at ${HARNESS_PATH}`);
+  }
+  const r = spawnSync(process.execPath, [HARNESS_PATH, abs], {
+    encoding: 'utf8',
+    timeout: 15_000,
+  });
+  /** @type {string[]} */
+  const warnings = [];
+  if (r.status !== 0) {
+    return {
+      tokens: {},
+      source: abs,
+      format: 'js-const',
+      warnings: [
+        `harness-exit-${r.status}: ${(r.stderr || '').slice(0, 400)}`,
+      ],
+    };
+  }
+  /** @type {{tokens?: unknown, error?: string}} */
+  let parsed;
+  try {
+    parsed = JSON.parse(r.stdout);
+  } catch (err) {
+    return {
+      tokens: {},
+      source: abs,
+      format: 'js-const',
+      warnings: [`harness-output-parse-failed: ${err.message}`],
+    };
+  }
+  if (parsed.error) warnings.push(parsed.error);
+  /** @type {Record<string, string>} */
+  const flat = {};
+  flatten(parsed.tokens, '', flat);
+  return { tokens: flat, source: abs, format: 'js-const', warnings };
+}
+
+module.exports = { readJsConst, _flatten: flatten };

package/scripts/lib/design-tokens/tailwind.cjs

@@ -0,0 +1,98 @@
+/**
+ * design-tokens/tailwind.cjs — extract tokens from a Tailwind config
+ * (Plan 23-08).
+ *
+ * Reuses the js-const subprocess harness to evaluate the config (which
+ * may be CJS or ESM, plain JS or .ts via type-strip), then walks
+ * `theme` + `theme.extend` into a flat token map keyed by
+ * `<scale>.<key>` (e.g. `colors.brand.500`, `spacing.4`).
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const HARNESS_PATH = path.join(__dirname, '_js-harness.cjs');
+
+function flatten(val, prefix, out) {
+  if (val === null || val === undefined) return;
+  if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean') {
+    out[prefix] = String(val);
+    return;
+  }
+  if (Array.isArray(val)) {
+    out[prefix] = JSON.stringify(val);
+    return;
+  }
+  if (typeof val === 'object') {
+    for (const k of Object.keys(val)) {
+      const next = prefix ? `${prefix}.${k}` : k;
+      flatten(val[k], next, out);
+    }
+  }
+}
+
+/**
+ * Read a Tailwind config. Prefers `theme.extend` over base `theme` for
+ * each scale (matching Tailwind merge semantics: extend extends).
+ *
+ * @param {string} filePath
+ * @returns {{tokens: Record<string, string>, source: string, format: 'tailwind', warnings: string[]}}
+ */
+function readTailwind(filePath) {
+  const abs = path.resolve(filePath);
+  if (!fs.existsSync(abs)) {
+    throw new Error(`tailwind: file not found: ${abs}`);
+  }
+  const r = spawnSync(process.execPath, [HARNESS_PATH, abs], {
+    encoding: 'utf8',
+    timeout: 15_000,
+  });
+  /** @type {string[]} */
+  const warnings = [];
+  if (r.status !== 0) {
+    return {
+      tokens: {},
+      source: abs,
+      format: 'tailwind',
+      warnings: [`harness-exit-${r.status}: ${(r.stderr || '').slice(0, 400)}`],
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(r.stdout);
+  } catch (err) {
+    return {
+      tokens: {},
+      source: abs,
+      format: 'tailwind',
+      warnings: [`harness-output-parse-failed: ${err.message}`],
+    };
+  }
+  if (parsed.error) warnings.push(parsed.error);
+  /** @type {Record<string, string>} */
+  const out = {};
+  const config = parsed.tokens ?? {};
+  // The harness returns the module exports (or `tokens` field). Tailwind
+  // configs export an object with a `theme` field. Some configs export
+  // `{theme, plugins, …}` directly.
+  const theme = config.theme || config;
+  // Base theme.
+  if (theme && typeof theme === 'object') {
+    for (const scale of Object.keys(theme)) {
+      if (scale === 'extend') continue;
+      flatten(theme[scale], scale, out);
+    }
+  }
+  // theme.extend overrides per-scale.
+  if (theme && theme.extend && typeof theme.extend === 'object') {
+    for (const scale of Object.keys(theme.extend)) {
+      flatten(theme.extend[scale], scale, out);
+    }
+  }
+  return { tokens: out, source: abs, format: 'tailwind', warnings };
+}
+
+module.exports = { readTailwind };

package/scripts/lib/domain-primitives/anti-patterns.cjs

@@ -0,0 +1,66 @@
+/**
+ * domain-primitives/anti-patterns.cjs — anti-pattern regex matcher
+ * (Plan 23-09).
+ *
+ * Same shape as nng.cjs. Loads rules from `reference/anti-patterns.md`
+ * yaml blocks. Caller may inject rules via opts.rules.
+ *
+ * Rule yaml shape:
+ *   id: ban-01
+ *   severity: P1
+ *   grep: 'side-stripe-class'
+ *   summary: 'Side-stripe borders are an AI-slop tell'
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseRulesFromMarkdown } = require('./nng.cjs');
+
+let _cache = null;
+
+function loadRules(cwd) {
+  if (_cache) return _cache;
+  const root = cwd ?? path.resolve(__dirname, '..', '..', '..');
+  const file = path.join(root, 'reference', 'anti-patterns.md');
+  if (!fs.existsSync(file)) {
+    _cache = [];
+    return _cache;
+  }
+  _cache = parseRulesFromMarkdown(fs.readFileSync(file, 'utf8'));
+  return _cache;
+}
+
+/**
+ * @param {{file: string, content: string, type?: string, cwd?: string, rules?: object[]}} input
+ * @returns {Array<{rule_id: string, severity: string, summary: string, evidence?: string, line?: number, file: string}>}
+ */
+function check(input) {
+  if (!input || typeof input !== 'object') return [];
+  if (typeof input.content !== 'string' || typeof input.file !== 'string') return [];
+  const rules = Array.isArray(input.rules) ? input.rules : loadRules(input.cwd);
+  const hits = [];
+  const lines = input.content.split(/\r?\n/);
+  for (const rule of rules) {
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(rule.grep);
+      if (!m) continue;
+      hits.push({
+        rule_id: rule.id,
+        severity: rule.severity,
+        summary: rule.summary,
+        evidence: m[0].slice(0, 200),
+        line: i + 1,
+        file: input.file,
+      });
+    }
+  }
+  return hits;
+}
+
+function _resetCache() {
+  _cache = null;
+}
+
+module.exports = { check, _resetCache };

package/scripts/lib/domain-primitives/nng.cjs

@@ -0,0 +1,136 @@
+/**
+ * domain-primitives/nng.cjs — NNG-style heuristic checker
+ * (Plan 23-09).
+ *
+ * Runs grep-style rules against a single source artifact. Rules are
+ * loaded from `reference/heuristics.md` as fenced yaml blocks of the form:
+ *
+ *   ```yaml
+ *   id: nng-01
+ *   severity: P1
+ *   grep: 'placeholder-as-label'
+ *   summary: 'Inputs use placeholder text instead of an explicit label'
+ *   ```
+ *
+ * If the reference file has no parseable yaml blocks today (the current
+ * registry is prose), the checker simply treats the rule list as empty.
+ * Caller may supply `opts.rules` directly to bypass the file-load path,
+ * which is the test-friendly entry point.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SEVERITIES = new Set(['P0', 'P1', 'P2', 'P3']);
+
+/**
+ * @typedef {Object} HeuristicHit
+ * @property {string} rule_id
+ * @property {'P0'|'P1'|'P2'|'P3'} severity
+ * @property {string} summary
+ * @property {string} [evidence]
+ * @property {number} [line]
+ * @property {string} file
+ */
+
+/**
+ * @typedef {Object} CompiledRule
+ * @property {string} id
+ * @property {'P0'|'P1'|'P2'|'P3'} severity
+ * @property {RegExp} grep
+ * @property {string} summary
+ */
+
+/**
+ * Extract every fenced ```yaml block from a markdown string and parse
+ * each as a flat key:value mapping (single-level, no nesting). Skips
+ * blocks that don't have an `id` and `grep` field.
+ *
+ * @param {string} markdown
+ * @returns {CompiledRule[]}
+ */
+function parseRulesFromMarkdown(markdown) {
+  const rules = [];
+  const re = /```yaml\s*\n([\s\S]*?)\n```/g;
+  let m;
+  while ((m = re.exec(markdown)) !== null) {
+    const body = m[1];
+    /** @type {Record<string, string>} */
+    const fields = {};
+    for (const line of body.split(/\r?\n/)) {
+      const kv = line.match(/^\s*([A-Za-z_][\w-]*)\s*:\s*(.*?)\s*$/);
+      if (!kv) continue;
+      let v = kv[2];
+      if ((v.startsWith("'") && v.endsWith("'")) || (v.startsWith('"') && v.endsWith('"'))) {
+        v = v.slice(1, -1);
+      }
+      fields[kv[1]] = v;
+    }
+    if (!fields.id || !fields.grep || !SEVERITIES.has(fields.severity)) continue;
+    let regex;
+    try {
+      regex = new RegExp(fields.grep);
+    } catch {
+      continue;
+    }
+    rules.push({
+      id: fields.id,
+      severity: /** @type {'P0'|'P1'|'P2'|'P3'} */ (fields.severity),
+      grep: regex,
+      summary: fields.summary || fields.id,
+    });
+  }
+  return rules;
+}
+
+let _ruleCache = null;
+
+function loadRules(cwd) {
+  if (_ruleCache) return _ruleCache;
+  const root = cwd ?? path.resolve(__dirname, '..', '..', '..');
+  const file = path.join(root, 'reference', 'heuristics.md');
+  if (!fs.existsSync(file)) {
+    _ruleCache = [];
+    return _ruleCache;
+  }
+  const md = fs.readFileSync(file, 'utf8');
+  _ruleCache = parseRulesFromMarkdown(md);
+  return _ruleCache;
+}
+
+/**
+ * @param {{file: string, content: string, type?: string, cwd?: string, rules?: CompiledRule[]}} input
+ * @returns {HeuristicHit[]}
+ */
+function check(input) {
+  if (!input || typeof input !== 'object') return [];
+  if (typeof input.content !== 'string' || typeof input.file !== 'string') return [];
+  const rules = Array.isArray(input.rules) ? input.rules : loadRules(input.cwd);
+  /** @type {HeuristicHit[]} */
+  const hits = [];
+  const lines = input.content.split(/\r?\n/);
+  for (const rule of rules) {
+    for (let i = 0; i < lines.length; i++) {
+      const ln = lines[i];
+      const match = ln.match(rule.grep);
+      if (!match) continue;
+      hits.push({
+        rule_id: rule.id,
+        severity: rule.severity,
+        summary: rule.summary,
+        evidence: match[0].slice(0, 200),
+        line: i + 1,
+        file: input.file,
+      });
+    }
+  }
+  return hits;
+}
+
+function _resetCache() {
+  _ruleCache = null;
+}
+
+module.exports = { check, parseRulesFromMarkdown, _resetCache };