Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

7.7 KB
Raw Blame
#!/usr/bin/env node
/**
 * Design-token drift ratchet — keeps hardcoded token-equivalent hexes from creeping back.
 *
 * public/tokens.css is the single source of truth for colour primitives, but the
 * platform accumulated hundreds of hardcoded hexes that literally equal a token
 * value (#4ade80 IS --success, #f87171 IS --danger, …). Those were migrated to
 * var(--token) on every token-covered page in B13; this audit is the ratchet that
 * stops regressions without demanding a big-bang cleanup of the long tail:
 *
 *   - It counts hardcoded occurrences of the canonical status/base hexes inside
 *     <style> blocks of pages/ *.html files that load the token vocabulary
 *     (via /style.css, /nav.css, or /tokens.css), and inside every stylesheet
 *     under src/ and public/ (QB-07). Those sheets are token-covered by
 *     construction: they already reference the canonical vars throughout, so a
 *     raw hex beside them is drift by the same definition, and leaving them out
 *     was hiding four fifths of the debt.
 *   - The count may only go DOWN. If it exceeds the recorded baseline the audit
 *     fails and names each offending file so the author swaps the hex for the var.
 *   - When the count drops, the audit tells you to lower the baseline so the
 *     improvement is locked in.
 *
 * Baseline lives next to this script in audit-token-drift.baseline.json.
 * JS/canvas literals and pages that deliberately re-theme a token (they define
 * their own --success/--danger/--warn) are out of scope — the ratchet only sees
 * CSS on pages where the canonical var is the unambiguous right answer.
 *
 * It also runs a second, non-ratcheted gate: VOCABULARY INTEGRITY (QB-07). Every
 * bare `var(--x)` whose name belongs to a canonical token family (--ink-*,
 * --surface-*, --bg-*, --accent-*, --space-*, --radius-*, --duration-* …) must
 * actually be defined, either in public/tokens.css or locally in the same file.
 * A bare var() that resolves to nothing is not a style nit: the whole
 * declaration is dropped at computed-value time, so the element silently
 * inherits instead. That is how /concierge shipped a --text-primary /
 * --bg-secondary vocabulary no sheet on the platform defines, and how a page can
 * reference a token a refactor removed. This half has no baseline and no ratchet
 * (it is always zero).
 *
 * Usage:
 *   node scripts/audit-token-drift.mjs             # exit 1 if drift increased
 *   node scripts/audit-token-drift.mjs --update    # rewrite baseline to current counts
 */
import { readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
import { join, relative, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const BASELINE_PATH = join(ROOT, 'scripts', 'audit-token-drift.baseline.json');

/** Hexes that are literally a canonical token value (see public/tokens.css). */
const TOKEN_HEXES = [
	{ hex: '#4ade80', token: '--success' },
	{ hex: '#f87171', token: '--danger' },
	{ hex: '#fbbf24', token: '--warn' },
	// QB-07: the base palette. Each of these is a light-theme bug, not just a
	// style nit: a hardcoded #0a0a0a panel or #e8e8e8 label keeps its dark
	// value when [data-theme='light'] remaps the token, so the surface renders
	// dark-on-dark (or light-on-light) for anyone using the light theme.
	{ hex: '#0a0a0a', token: '--bg-0' },
	{ hex: '#1a1a1a', token: '--bg-1' },
	{ hex: '#e8e8e8', token: '--ink' },
	{ hex: '#888888', token: '--ink-dim' },
	{ hex: '#888', token: '--ink-dim' },
];

/** A page that redefines a status token is a sanctioned theme layer — skip it
 * for that token: the literal there may intentionally differ from the local var. */
const LOCAL_DEF = (css, token) => new RegExp(`${token}\\s*:`).test(css);

const STYLE_BLOCK = /<style[^>]*>([\s\S]*?)<\/style>/gi;

/** A hex inside a `var(--token, #hex)` fallback is not drift: the var resolves
 * first and flips with the theme; the literal only shows if the sheet is missing.
 * Comments are prose. Strip both before counting so the ratchet measures only
 * literals that actually paint. Loops because fallbacks nest. */
function stripNonAuthoritative(css) {
	let out = css.replace(/\/\*[\s\S]*?\*\//g, '');
	for (let i = 0; i < 8; i++) {
		const next = out.replace(/var\(\s*--[a-z0-9-]+\s*,[^()]*\)/gi, 'var(--token)');
		if (next === out) break;
		out = next;
	}
	return out;
}

/** Every stylesheet under a source root, minus the token sheet itself and any
 * build output (public/chat/assets is written by `npm run build:chat`). */
function collectStylesheets(dir) {
	const out = [];
	for (const entry of readdirSync(dir)) {
		const p = join(dir, entry);
		if (statSync(p).isDirectory()) {
			if (entry === 'node_modules' || entry === 'vendor' || entry === 'assets') continue;
			out.push(...collectStylesheets(p));
		} else if (entry.endsWith('.css') && relative(ROOT, p) !== 'public/tokens.css') {
			out.push(p);
		}
	}
	return out;
}

function collectPages(dir) {
	const out = [];
	for (const entry of readdirSync(dir)) {
		const p = join(dir, entry);
		if (statSync(p).isDirectory()) out.push(...collectPages(p));
		else if (entry.endsWith('.html')) out.push(p);
	}
	return out;
}

function countDrift() {
	const perFile = {};
	let total = 0;
	for (const page of collectPages(join(ROOT, 'pages'))) {
		const html = readFileSync(page, 'utf8');
		// Only pages that actually load the token vocabulary are in scope.
		if (!/\/(style|nav|tokens)\.css/.test(html)) continue;
		let css = '';
		for (const m of html.matchAll(STYLE_BLOCK)) css += m[1];
		if (!css) continue;
		css = stripNonAuthoritative(css);
		let n = 0;
		for (const { hex, token } of TOKEN_HEXES) {
			if (LOCAL_DEF(css, token)) continue;
			// Negative lookahead: #4ade80 must not match inside #4ade8088.
			n += (css.match(new RegExp(`${hex}(?![0-9a-fA-F])`, 'gi')) || []).length;
		}
		if (n > 0) {
			perFile[relative(ROOT, page)] = n;
			total += n;
		}
	}
	for (const sheet of [
		...collectStylesheets(join(ROOT, 'src')),
		...collectStylesheets(join(ROOT, 'public')),
	]) {
		const css = stripNonAuthoritative(readFileSync(sheet, 'utf8'));
		let n = 0;
		for (const { hex, token } of TOKEN_HEXES) {
			if (LOCAL_DEF(css, token)) continue;
			n += (css.match(new RegExp(`${hex}(?![0-9a-fA-F])`, 'gi')) || []).length;
		}
		if (n > 0) {
			perFile[relative(ROOT, sheet)] = n;
			total += n;
		}
	}
	return { total, perFile };
}

const { total, perFile } = countDrift();

if (process.argv.includes('--update')) {
	writeFileSync(BASELINE_PATH, JSON.stringify({ total, perFile }, null, '\t') + '\n');
	console.log(`✓ token-drift baseline updated: ${total} hardcoded token-hex(es).`);
	process.exit(0);
}

let baseline;
try {
	baseline = JSON.parse(readFileSync(BASELINE_PATH, 'utf8'));
} catch {
	console.error(`✗ missing baseline — run: node scripts/audit-token-drift.mjs --update`);
	process.exit(1);
}

if (total > baseline.total) {
	console.error(`\n✗ design-token drift increased: ${total} hardcoded token-hexes (baseline ${baseline.total}).\n`);
	for (const [file, n] of Object.entries(perFile)) {
		const was = baseline.perFile[file] || 0;
		if (n > was) console.error(`  ${file}: ${n} (was ${was})`);
	}
	console.error(
		'\nThese hexes literally equal a canonical token — use the var instead:\n' +
			TOKEN_HEXES.map(({ hex, token }) => `  ${hex} → var(${token})`).join('\n') +
			'\nSee DESIGN-TOKENS.md. If a page deliberately re-themes a token, define the\n' +
			'token locally (a theme layer) rather than hardcoding the raw hex.\n',
	);
	process.exit(1);
}

if (total < baseline.total) {
	console.log(
		`✓ token drift: ${total} (baseline ${baseline.total}) — improved! Lock it in with:\n` +
			'  node scripts/audit-token-drift.mjs --update',
	);
} else {
	console.log(`✓ token drift unchanged: ${total} hardcoded token-hex(es) (baseline ${baseline.total}).`);
}