@radicool/throughline 0.12.0

package/scripts/crosswalk.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://throughline.dev/schemas/crosswalk.schema.json",
+  "title": "ThroughLine token crosswalk",
+  "description": "Three-way map: new token <-> old Figma token <-> code identifier. Drives the brownfield code retrofit and the tokens:validate CI gate.",
+  "type": "object",
+  "required": ["version", "tokens"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "tokens": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/row" }
+    }
+  },
+  "$defs": {
+    "row": {
+      "type": "object",
+      "required": ["newToken", "newValue", "tier", "figmaOld", "codeTokens", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "newToken": { "type": "string", "minLength": 1, "description": "DTCG dot-path, e.g. color.text.primary" },
+        "newValue": { "type": "string", "minLength": 1, "description": "Resolved leaf value (aliases followed)" },
+        "tier": { "type": "string", "enum": ["primitive", "semantic"] },
+        "figmaOld": { "type": ["string", "null"], "description": "Old Figma variable name/path, or null if newly added" },
+        "codeTokens": { "type": "array", "items": { "type": "string" }, "description": "Old code identifiers this token replaces" },
+        "status": { "type": "string", "enum": ["aligned", "renamed", "drift-fix", "added", "mapped-nearest"] },
+        "recommendedSemantic": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/scripts/grep-color-usage.mjs

@@ -0,0 +1,143 @@
+// Color-usage grep scaffold: size a codebase's color-decision surface by category.
+// Repo-shaped by nature — ships sensible DEFAULT_CATEGORIES and accepts a --config
+// override; logs which categories used the assumed default vs. a detected pattern so
+// coverage is never silently partial. Zero dependencies.
+//
+// Usage:
+//   node grep-color-usage.mjs --root <dir> [--config <patterns.json>] [--out <counts.json>]
+//     patterns.json: { "<category>": { "files": "<regex>", "pattern": "<regex with g flag>" }, ... }
+import { readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+
+// The five categories from the case study. Each: which files it applies to, and the
+// (global) match pattern. Tuned defaults — design-system-audit may override per repo.
+export const DEFAULT_CATEGORIES = {
+  scssColorVars: {
+    files: /\.(scss|sass|css)$/,
+    pattern: /\$[\w-]*(?:color|colour|primary|secondary|tertiary|grey|gray|red|blue|green|yellow|orange|purple|pink|teal|cyan|black|white|brand|accent|surface|ink)[\w-]*/gi,
+  },
+  tailwindColorClasses: {
+    files: /\.(tsx?|jsx?|html|vue|svelte)$/,
+    pattern: /\b(?:bg|text|border|ring|fill|stroke|from|via|to|outline|divide|placeholder|caret|accent|shadow)-(?:primary|secondary|tertiary|grey|gray|red|blue|green|yellow|orange|purple|pink|teal|cyan|brand|accent|surface|ink)[\w-]*/g,
+  },
+  jsColorsUsages: {
+    files: /\.(tsx?|jsx?|mjs|cjs)$/,
+    pattern: /\bColors\.[A-Za-z_$][\w$]*/g,
+  },
+  rawHexRgba: {
+    files: /\.(scss|sass|css|tsx?|jsx?|vue|svelte|html|svg)$/,
+    pattern: /#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)/g,
+  },
+  svgFills: {
+    files: /\.svg$/,
+    pattern: /(?:fill|stroke)="(?!none|currentColor|url\()[^"]+"/g,
+  },
+};
+
+export const DEFAULT_EXCLUDES = [
+  /(^|\/)node_modules(\/|$)/,
+  /(^|\/)generated(\/|$)/,
+  /\.generated\./,
+  /\.test\./,
+  /\.spec\./,
+  /(^|\/)__tests__(\/|$)/,
+  /(^|\/)dist(\/|$)/,
+  /(^|\/)\.next(\/|$)/,
+];
+
+// Source extensions worth opening at all (union of every category's `files`).
+const SOURCE_EXT = /\.(scss|sass|css|tsx?|jsx?|mjs|cjs|vue|svelte|html|svg)$/;
+
+export function* walk(root, excludes = DEFAULT_EXCLUDES) {
+  for (const entry of readdirSync(root)) {
+    const full = join(root, entry);
+    if (excludes.some((re) => re.test(full))) continue;
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      yield* walk(full, excludes);
+    } else if (SOURCE_EXT.test(full)) {
+      yield full;
+    }
+  }
+}
+
+// Count matches per category in one file. A category contributes only if its `files`
+// regex matches this path. Returns { <category>: count } for every category key.
+export function scanFile(path, categories) {
+  const counts = {};
+  for (const key of Object.keys(categories)) counts[key] = 0;
+  const text = readFileSync(path, 'utf8');
+  for (const [key, { files, pattern }] of Object.entries(categories)) {
+    if (!files.test(path)) continue;
+    const re = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : pattern.flags + 'g');
+    const m = text.match(re);
+    counts[key] = m ? m.length : 0;
+  }
+  return counts;
+}
+
+export function grepColorUsage(root, categories = DEFAULT_CATEGORIES, excludes = DEFAULT_EXCLUDES) {
+  const counts = {};
+  for (const key of Object.keys(categories)) counts[key] = 0;
+  const byFile = [];
+  for (const file of walk(root, excludes)) {
+    const fileCounts = scanFile(file, categories);
+    const total = Object.values(fileCounts).reduce((a, b) => a + b, 0);
+    if (total > 0) {
+      byFile.push({ file: relative(root, file), counts: fileCounts });
+      for (const key of Object.keys(fileCounts)) counts[key] += fileCounts[key];
+    }
+  }
+  return { counts, byFile };
+}
+
+// Parse a --config JSON of { category: { files, pattern } } string regexes into RegExp.
+function loadCategories(path) {
+  const raw = JSON.parse(readFileSync(path, 'utf8'));
+  const out = {};
+  for (const [key, { files, pattern }] of Object.entries(raw)) {
+    out[key] = { files: new RegExp(files), pattern: new RegExp(pattern, 'g') };
+  }
+  return out;
+}
+
+function main() {
+  const { values } = parseArgs({
+    options: {
+      root: { type: 'string' },
+      config: { type: 'string' },
+      out: { type: 'string' },
+    },
+  });
+  if (!values.root) {
+    console.error('usage: grep-color-usage.mjs --root <dir> [--config <patterns.json>] [--out <counts.json>]');
+    process.exit(2);
+  }
+  const categories = values.config ? loadCategories(values.config) : DEFAULT_CATEGORIES;
+  // §11: never let coverage be silently partial — say which patterns were assumed.
+  const source = values.config ? `detected (from ${values.config})` : 'ASSUMED defaults';
+  console.log(`color-usage grep — pattern source: ${source}`);
+  console.log(`categories: ${Object.keys(categories).join(', ')}`);
+
+  const { counts, byFile } = grepColorUsage(values.root, categories);
+  const total = Object.values(counts).reduce((a, b) => a + b, 0);
+  console.log('\ncolor-decision surface:');
+  for (const [key, n] of Object.entries(counts)) {
+    console.log(`  ${key.padEnd(24)} ${n}`);
+  }
+  console.log(`  ${'TOTAL'.padEnd(24)} ${total}  (across ${byFile.length} file(s))`);
+  if (!values.config) {
+    console.log('\nnote: patterns are the shipped defaults. Tune them to this repo and re-run with --config for accurate counts.');
+  }
+
+  if (values.out) {
+    writeFileSync(values.out, JSON.stringify({ counts, byFile }, null, 2) + '\n');
+    console.log(`\nwrote ${values.out}`);
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/scripts/guard-token-removal.mjs

@@ -0,0 +1,95 @@
+// Repo-wide token-removal guard: grep .ts/.tsx (minus generated + tests) for
+// references to about-to-be-deleted symbols. Zero dependencies.
+//
+// Cleanup must not proceed until this returns zero references — deleted Tailwind
+// utilities become silent no-ops that tsc/build will not catch (guardrail 4).
+//
+// Usage:
+//   node guard-token-removal.mjs --root <dir> --symbols <symbols.txt>
+//     symbols file: one symbol per line (blank lines and # comments ignored)
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+
+export const DEFAULT_EXCLUDES = [
+  /(^|\/)node_modules(\/|$)/,
+  /(^|\/)generated(\/|$)/,
+  /\.generated\./,
+  /\.test\./,
+  /\.spec\./,
+  /(^|\/)__tests__(\/|$)/,
+  /(^|\/)dist(\/|$)/,
+  /(^|\/)\.next(\/|$)/,
+];
+
+export function* walk(root, excludes = DEFAULT_EXCLUDES) {
+  for (const entry of readdirSync(root)) {
+    const full = join(root, entry);
+    if (excludes.some((re) => re.test(full))) continue;
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      yield* walk(full, excludes);
+    } else if (/\.tsx?$/.test(full)) {
+      yield full;
+    }
+  }
+}
+
+export function scanFile(path, symbols) {
+  const lines = readFileSync(path, 'utf8').split('\n');
+  const hits = [];
+  lines.forEach((line, i) => {
+    for (const sym of symbols) {
+      if (line.includes(sym)) {
+        hits.push({ line: i + 1, symbol: sym, text: line.trim() });
+      }
+    }
+  });
+  return hits;
+}
+
+export function guard(root, symbols, excludes = DEFAULT_EXCLUDES) {
+  const findings = [];
+  for (const file of walk(root, excludes)) {
+    for (const hit of scanFile(file, symbols)) {
+      findings.push({ file: relative(root, file), ...hit });
+    }
+  }
+  return findings;
+}
+
+function readSymbols(path) {
+  return readFileSync(path, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'));
+}
+
+function main() {
+  const { values } = parseArgs({
+    options: {
+      root: { type: 'string' },
+      symbols: { type: 'string' },
+    },
+  });
+  if (!values.root || !values.symbols) {
+    console.error('usage: guard-token-removal.mjs --root <dir> --symbols <symbols.txt>');
+    process.exit(2);
+  }
+  const symbols = readSymbols(values.symbols);
+  const findings = guard(values.root, symbols);
+  if (findings.length === 0) {
+    console.log(`token-removal guard: 0 references to ${symbols.length} symbol(s) — safe to remove.`);
+    return;
+  }
+  console.error(`token-removal guard: ${findings.length} remaining reference(s) — do NOT remove yet:`);
+  for (const f of findings) {
+    console.error(`  ${f.file}:${f.line}  ${f.symbol}  | ${f.text}`);
+  }
+  process.exit(1);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/scripts/install.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, copyFileSync } from 'node:fs';
+import { join, dirname, relative, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { rewritePluginRoot } from './adapters/translate.mjs';
+
+export const BASE = '.throughline';
+export const TARGETS = ['cursor', 'codex', 'generic'];
+const START = '<!-- throughline:start -->';
+const END = '<!-- throughline:end -->';
+
+const MCP_NOTE = {
+  cursor: 'Figma MCP written to .cursor/mcp.json — restart Cursor to load it.',
+  codex: 'Add the [mcp_servers] block from codex-mcp.toml to your Codex config (e.g. ~/.codex/config.toml).',
+  generic: 'Add the MCP server shown under "MCP servers" in AGENTS.md to your agent.',
+};
+
+const USAGE = `throughline init --target=cursor|codex|generic [--dir=.]
+
+Stamps the ThroughLine adapter for <target> into your project, plus the
+runtime payload it reads (.throughline/references, .throughline/scripts).
+Safe to re-run: merges AGENTS.md and .cursor/mcp.json non-destructively.`;
+
+export function parseArgs(argv) {
+  const args = { cmd: null, target: null, dir: process.cwd(), help: false };
+  for (const a of argv) {
+    if (a === '--help' || a === '-h') args.help = true;
+    else if (a.startsWith('--target=')) args.target = a.slice('--target='.length);
+    else if (a.startsWith('--dir=')) args.dir = a.slice('--dir='.length);
+    else if (!a.startsWith('-') && !args.cmd) args.cmd = a;
+  }
+  return args;
+}
+
+export function mergeAgentsBlock(existing, block) {
+  const wrapped = `${START}\n${block.trim()}\n${END}`;
+  if (!existing || !existing.trim()) return `${wrapped}\n`;
+  const s = existing.indexOf(START);
+  const e = existing.indexOf(END);
+  if (s !== -1 && e !== -1 && e > s) {
+    return existing.slice(0, s) + wrapped + existing.slice(e + END.length);
+  }
+  return `${existing.replace(/\s*$/, '')}\n\n${wrapped}\n`;
+}
+
+export function mergeMcpJson(existing, ourServers) {
+  let obj = {};
+  if (existing) {
+    let usable = false;
+    try {
+      const parsed = JSON.parse(existing);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        obj = parsed;
+        usable = true;
+      }
+    } catch { /* malformed → start fresh */ }
+    if (!usable) {
+      console.warn('throughline: existing .cursor/mcp.json is not a JSON object; replacing it with the ThroughLine MCP server config.');
+    }
+  }
+  obj.mcpServers = { ...(obj.mcpServers || {}), ...ourServers };
+  return `${JSON.stringify(obj, null, 2)}\n`;
+}
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const TEXT_EXT = /\.(md|mdc|mjs|json|toml|txt)$/;
+const toPosix = (p) => p.split(sep).join('/');
+
+function walk(dir, base = dir) {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === '.DS_Store') continue;
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walk(abs, base));
+    else out.push(relative(base, abs));
+  }
+  return out;
+}
+
+function writeText(dest, content) {
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, content);
+}
+
+// Copy a source tree into destRoot, rewriting ${CLAUDE_PLUGIN_ROOT} on text
+// files. `skip(relPosix)` drops entries. Returns posix-relative paths written.
+function stagePayload(srcRoot, destRoot, skip) {
+  const written = [];
+  for (const rel of walk(srcRoot)) {
+    const relPosix = toPosix(rel);
+    if (skip && skip(relPosix)) continue;
+    const src = join(srcRoot, rel);
+    const dest = join(destRoot, rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    if (TEXT_EXT.test(rel)) writeFileSync(dest, rewritePluginRoot(readFileSync(src, 'utf8'), BASE));
+    else copyFileSync(src, dest);
+    written.push(relPosix);
+  }
+  return written;
+}
+
+export function install({ target, dir, pkgRoot = PKG_ROOT }) {
+  if (!TARGETS.includes(target)) {
+    throw new Error(`unknown target "${target}"; expected one of: ${TARGETS.join(', ')}`);
+  }
+  const written = [];
+  const adapterDir = join(pkgRoot, 'adapters', target);
+  for (const rel of walk(adapterDir)) {
+    const relPosix = toPosix(rel);
+    const src = join(adapterDir, rel);
+    const dest = join(dir, rel);
+    if (relPosix === 'AGENTS.md') {
+      const existing = existsSync(dest) ? readFileSync(dest, 'utf8') : null;
+      writeText(dest, mergeAgentsBlock(existing, readFileSync(src, 'utf8')));
+    } else if (relPosix === '.cursor/mcp.json') {
+      const ours = JSON.parse(readFileSync(src, 'utf8')).mcpServers || {};
+      const existing = existsSync(dest) ? readFileSync(dest, 'utf8') : null;
+      writeText(dest, mergeMcpJson(existing, ours));
+    } else {
+      mkdirSync(dirname(dest), { recursive: true });
+      copyFileSync(src, dest);
+    }
+    written.push(relPosix);
+  }
+  const payload = [
+    ...stagePayload(join(pkgRoot, 'references'), join(dir, BASE, 'references')),
+    ...stagePayload(join(pkgRoot, 'scripts'), join(dir, BASE, 'scripts'), (r) => r.startsWith('adapters/') || r.endsWith('.test.mjs') || r === 'install.mjs'),
+  ];
+  return { target, dir, written, payload };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { console.log(USAGE); process.exit(0); }
+  if (args.cmd !== 'init') { console.error(`✗ unknown command; expected "init"\n\n${USAGE}`); process.exit(1); }
+  if (!TARGETS.includes(args.target)) {
+    console.error(`✗ --target must be one of: ${TARGETS.join(', ')}\n\n${USAGE}`);
+    process.exit(1);
+  }
+  const res = install({ target: args.target, dir: args.dir });
+  console.log(`✓ throughline: installed ${res.target} adapter (${res.written.length} files) + ${res.payload.length}-file runtime payload into ${res.dir}`);
+  console.log(`  ${MCP_NOTE[res.target]}`);
+}

package/scripts/lib/crosswalk.mjs

@@ -0,0 +1,91 @@
+// Shared loader + structural validation for crosswalk.json.
+// Zero dependencies. Mirrors scripts/crosswalk.schema.json's required/enum rules.
+import { readFileSync } from 'node:fs';
+
+export const STATUS_VALUES = ['aligned', 'renamed', 'drift-fix', 'added', 'mapped-nearest'];
+
+// Row status (kebab) -> manifest tokenCrosswalk.statusCounts key (camelCase).
+export const STATUS_COUNT_KEY = {
+  'aligned': 'aligned',
+  'renamed': 'renamed',
+  'drift-fix': 'driftFix',
+  'added': 'added',
+  'mapped-nearest': 'mappedNearest',
+};
+
+const TIERS = ['primitive', 'semantic'];
+
+export function loadCrosswalk(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (e) {
+    throw new Error(`crosswalk: cannot read file at ${path}: ${e.message}`);
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`crosswalk: invalid JSON in ${path}: ${e.message}`);
+  }
+  if (!data || typeof data !== 'object' || !Array.isArray(data.tokens)) {
+    throw new Error('crosswalk: expected an object with a "tokens" array');
+  }
+  if (data.version !== 1) {
+    throw new Error(`crosswalk: version must be 1, got ${JSON.stringify(data.version)}`);
+  }
+  const ALLOWED_TOP_KEYS = new Set(['$schema', 'version', 'tokens']);
+  for (const key of Object.keys(data)) {
+    if (!ALLOWED_TOP_KEYS.has(key)) {
+      throw new Error(`crosswalk: unknown key at top level: "${key}"`);
+    }
+  }
+  const seen = new Set();
+  data.tokens.forEach((row, i) => validateRow(row, i, seen));
+  return data;
+}
+
+function validateRow(row, i, seen) {
+  const where = `tokens[${i}]`;
+  if (!row || typeof row !== 'object') {
+    throw new Error(`crosswalk: ${where} is not an object`);
+  }
+  for (const field of ['newToken', 'newValue', 'tier', 'status']) {
+    if (typeof row[field] !== 'string' || row[field] === '') {
+      throw new Error(`crosswalk: ${where}.${field} must be a non-empty string`);
+    }
+  }
+  if (!TIERS.includes(row.tier)) {
+    throw new Error(`crosswalk: ${where}.tier must be one of ${TIERS.join(', ')}, got "${row.tier}"`);
+  }
+  if (!STATUS_VALUES.includes(row.status)) {
+    throw new Error(`crosswalk: ${where}.status must be one of ${STATUS_VALUES.join(', ')}, got "${row.status}"`);
+  }
+  if (!Array.isArray(row.codeTokens) || row.codeTokens.some((t) => typeof t !== 'string')) {
+    throw new Error(`crosswalk: ${where}.codeTokens must be an array of strings`);
+  }
+  if (row.figmaOld === undefined || (row.figmaOld !== null && typeof row.figmaOld !== 'string')) {
+    throw new Error(`crosswalk: ${where}.figmaOld must be a string or null`);
+  }
+  if (row.recommendedSemantic != null && typeof row.recommendedSemantic !== 'string') {
+    throw new Error(`crosswalk: ${where}.recommendedSemantic must be a string or null`);
+  }
+  const ALLOWED_ROW_KEYS = new Set(['newToken', 'newValue', 'tier', 'figmaOld', 'codeTokens', 'status', 'recommendedSemantic']);
+  for (const key of Object.keys(row)) {
+    if (!ALLOWED_ROW_KEYS.has(key)) {
+      throw new Error(`crosswalk: ${where} has unknown key: "${key}"`);
+    }
+  }
+  if (seen.has(row.newToken)) {
+    throw new Error(`crosswalk: duplicate newToken "${row.newToken}"`);
+  }
+  seen.add(row.newToken);
+}
+
+export function statusCounts(crosswalk) {
+  const counts = { aligned: 0, renamed: 0, driftFix: 0, added: 0, mappedNearest: 0 };
+  for (const row of crosswalk.tokens) {
+    counts[STATUS_COUNT_KEY[row.status]] += 1;
+  }
+  return counts;
+}

package/scripts/validate-crosswalk.mjs

@@ -0,0 +1,96 @@
+// Crosswalk validator: resolved DTCG value == crosswalk newValue, for every row.
+// The tokens:validate CI gate. Zero dependencies.
+//
+// Usage:
+//   node validate-crosswalk.mjs --crosswalk crosswalk.json --tokens dtcg/tokens.json
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { loadCrosswalk, statusCounts } from './lib/crosswalk.mjs';
+
+const REF = /^\{([^}]+)\}$/;
+
+// Flatten nested DTCG groups into { "dot.path": rawValue }. Skips $-prefixed meta keys.
+export function flattenDtcg(obj, prefix = [], out = {}) {
+  for (const [key, val] of Object.entries(obj)) {
+    if (key.startsWith('$')) continue;
+    if (val && typeof val === 'object' && '$value' in val) {
+      out[[...prefix, key].join('.')] = val.$value;
+    } else if (val && typeof val === 'object') {
+      flattenDtcg(val, [...prefix, key], out);
+    }
+  }
+  return out;
+}
+
+// Follow {alias} chains to a leaf literal. Throws on missing or circular refs.
+export function resolveValue(name, flat, seen = new Set()) {
+  if (!(name in flat)) throw new Error(`token "${name}" not found in DTCG source`);
+  const val = flat[name];
+  if (typeof val === 'string') {
+    const m = val.match(REF);
+    if (m) {
+      if (seen.has(name)) throw new Error(`circular reference at "${name}"`);
+      seen.add(name);
+      return resolveValue(m[1], flat, seen);
+    }
+  }
+  return val;
+}
+
+function norm(v) {
+  return String(v).trim().toLowerCase();
+}
+
+export function validate(crosswalk, dtcg) {
+  const flat = flattenDtcg(dtcg);
+  const results = { total: crosswalk.tokens.length, passed: 0, mismatches: [], missing: [] };
+  for (const row of crosswalk.tokens) {
+    let resolved;
+    try {
+      resolved = resolveValue(row.newToken, flat);
+    } catch {
+      results.missing.push(row.newToken);
+      continue;
+    }
+    if (norm(resolved) === norm(row.newValue)) {
+      results.passed += 1;
+    } else {
+      results.mismatches.push({ token: row.newToken, expected: row.newValue, actual: resolved });
+    }
+  }
+  return results;
+}
+
+function main() {
+  const { values } = parseArgs({
+    options: {
+      crosswalk: { type: 'string' },
+      tokens: { type: 'string' },
+    },
+  });
+  if (!values.crosswalk || !values.tokens) {
+    console.error('usage: validate-crosswalk.mjs --crosswalk <crosswalk.json> --tokens <dtcg/tokens.json>');
+    process.exit(2);
+  }
+  const crosswalk = loadCrosswalk(values.crosswalk);
+  const dtcg = JSON.parse(readFileSync(values.tokens, 'utf8'));
+  const r = validate(crosswalk, dtcg);
+
+  console.log(`tokens:validate — ${r.passed}/${r.total} resolved values match`);
+  console.log('status counts:', JSON.stringify(statusCounts(crosswalk)));
+  if (r.missing.length) {
+    console.error(`\n${r.missing.length} token(s) missing from the DTCG source:`);
+    for (const t of r.missing) console.error(`  - ${t}`);
+  }
+  if (r.mismatches.length) {
+    console.error(`\n${r.mismatches.length} mismatch(es):`);
+    for (const m of r.mismatches) console.error(`  - ${m.token}: crosswalk says ${m.expected}, source resolves to ${m.actual}`);
+  }
+  const ok = r.passed === r.total;
+  if (!ok) process.exit(1);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}