@hegemonart/get-design-done 1.22.0 → 1.23.0

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 };

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

@@ -0,0 +1,166 @@
+/**
+ * domain-primitives/wcag.cjs — minimal WCAG validator (Plan 23-09).
+ *
+ * Three checks (no axe-core dep):
+ *   1. Contrast ratio (WCAG 1.4.3 / 1.4.6) — given fg + bg colors,
+ *      compute the ratio. Pass: ≥4.5 (AA normal text), fail: <4.5.
+ *   2. Tap target size (WCAG 2.5.5 AAA / 2.5.8 AA) — given width+height
+ *      in CSS pixels, fail if either dimension <24 (AA) or <44 (AAA).
+ *   3. ARIA label presence — given a snippet of HTML, look for
+ *      <button>, <a>, <input> elements without an accessible name
+ *      (no text content AND no aria-label/aria-labelledby).
+ *
+ * All inputs are passed by the caller — this module does not parse
+ * arbitrary CSS or run a browser. Each check returns an Array<HeuristicHit>.
+ */
+
+'use strict';
+
+/**
+ * @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
+ */
+
+const HEX_RE = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+function hexToRgb(hex) {
+  if (typeof hex !== 'string') return null;
+  const m = hex.match(HEX_RE);
+  if (!m) return null;
+  let h = m[1];
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  return {
+    r: parseInt(h.slice(0, 2), 16),
+    g: parseInt(h.slice(2, 4), 16),
+    b: parseInt(h.slice(4, 6), 16),
+  };
+}
+
+function relLuminance({ r, g, b }) {
+  const channel = (v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+/**
+ * WCAG 1.4.3 contrast ratio between two colors.
+ * @param {string} fgHex
+ * @param {string} bgHex
+ * @returns {number} 1.0 to 21.0
+ */
+function contrastRatio(fgHex, bgHex) {
+  const fg = hexToRgb(fgHex);
+  const bg = hexToRgb(bgHex);
+  if (!fg || !bg) return NaN;
+  const lf = relLuminance(fg);
+  const lb = relLuminance(bg);
+  const [hi, lo] = lf > lb ? [lf, lb] : [lb, lf];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * Check contrast against AA (4.5:1) or AAA (7:1) threshold.
+ *
+ * @param {{file: string, fg: string, bg: string, level?: 'AA'|'AAA', context?: string}} input
+ * @returns {HeuristicHit[]}
+ */
+function checkContrast(input) {
+  if (!input || typeof input.fg !== 'string' || typeof input.bg !== 'string') return [];
+  const ratio = contrastRatio(input.fg, input.bg);
+  const level = input.level ?? 'AA';
+  const minimum = level === 'AAA' ? 7 : 4.5;
+  if (Number.isNaN(ratio)) {
+    return [{
+      rule_id: 'wcag/1.4.3',
+      severity: 'P2',
+      summary: `unparseable color: fg=${input.fg} bg=${input.bg}`,
+      file: input.file,
+    }];
+  }
+  if (ratio >= minimum) return [];
+  return [{
+    rule_id: level === 'AAA' ? 'wcag/1.4.6' : 'wcag/1.4.3',
+    severity: ratio < 3 ? 'P0' : 'P1',
+    summary: `Contrast ratio ${ratio.toFixed(2)} below ${level} minimum ${minimum}:1`,
+    evidence: `fg=${input.fg}, bg=${input.bg}, ratio=${ratio.toFixed(2)}`,
+    file: input.file,
+  }];
+}
+
+/**
+ * Check tap target size (WCAG 2.5.5 / 2.5.8).
+ *
+ * @param {{file: string, width: number, height: number, level?: 'AA'|'AAA', name?: string}} input
+ * @returns {HeuristicHit[]}
+ */
+function checkTapTarget(input) {
+  if (!input || typeof input.width !== 'number' || typeof input.height !== 'number') return [];
+  const level = input.level ?? 'AA';
+  const min = level === 'AAA' ? 44 : 24;
+  if (input.width >= min && input.height >= min) return [];
+  return [{
+    rule_id: level === 'AAA' ? 'wcag/2.5.5' : 'wcag/2.5.8',
+    severity: 'P1',
+    summary: `Tap target ${input.width}×${input.height}px below ${level} minimum ${min}×${min}px${input.name ? ` (${input.name})` : ''}`,
+    evidence: `${input.width}×${input.height}`,
+    file: input.file,
+  }];
+}
+
+const INTERACTIVE_RE = /<(button|a|input)\b([^>]*)>([\s\S]*?)<\/\1>|<input\b([^>]*)\/?>/gi;
+
+/**
+ * Check that interactive elements have an accessible name.
+ *
+ * @param {{file: string, content: string}} input
+ * @returns {HeuristicHit[]}
+ */
+function checkAriaLabels(input) {
+  if (!input || typeof input.content !== 'string') return [];
+  const hits = [];
+  // Walk lines so we can attach line numbers.
+  const lines = input.content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const ln = lines[i];
+    const elementMatches = [...ln.matchAll(/<(button|a|input)\b([^>]*?)(?:\s*\/)?>([^<]*)?/gi)];
+    for (const em of elementMatches) {
+      const tag = em[1].toLowerCase();
+      const attrs = em[2] || '';
+      const inner = (em[3] || '').trim();
+      const hasAriaLabel = /\baria-labell?e?d?b?y?\s*=/.test(attrs);
+      const hasTitle = /\btitle\s*=\s*["'][^"']+["']/.test(attrs);
+      const hasAlt = /\balt\s*=\s*["'][^"']+["']/.test(attrs);
+      if (tag === 'input') {
+        // Inputs with type=submit/button can rely on `value` attr.
+        const hasValue = /\bvalue\s*=\s*["'][^"']+["']/.test(attrs);
+        if (hasAriaLabel || hasTitle || hasValue) continue;
+      } else if (inner.length > 0 || hasAriaLabel || hasTitle || hasAlt) {
+        continue;
+      }
+      hits.push({
+        rule_id: 'wcag/4.1.2',
+        severity: 'P1',
+        summary: `<${tag}> has no accessible name (no text content + no aria-label/title)`,
+        evidence: em[0].slice(0, 200),
+        line: i + 1,
+        file: input.file,
+      });
+    }
+  }
+  return hits;
+}
+
+module.exports = {
+  contrastRatio,
+  hexToRgb,
+  checkContrast,
+  checkTapTarget,
+  checkAriaLabels,
+};