@finggujadhav/compiler 0.9.5 → 0.9.7

package/a11y.js

@@ -0,0 +1,101 @@
+/**
+ * FingguFlux A11y Scanner
+ * Validates template ARIA compliance against FingguFlux contracts.
+ */
+
+export const ARIA_CONTRACTS = {
+    'ff-accordion': {
+        required: ['role="button"', 'aria-expanded'],
+        recommended: ['aria-controls'],
+        stateSync: 'aria-expanded'
+    },
+    'ff-tabs': {
+        required: ['role="tablist"', 'role="tab"', 'role="tabpanel"'],
+        stateSync: 'aria-selected'
+    },
+    'ff-modal': {
+        required: ['role="dialog"', 'aria-modal="true"']
+    },
+    'ff-dropdown': {
+        required: ['aria-haspopup="true"'],
+        stateSync: 'aria-expanded'
+    }
+};
+
+export function validateTemplate(content) {
+    const issues = [];
+
+    // Check Accordion patterns
+    if (content.includes('ff-accordion-header')) {
+        const headers = content.match(/<button[^>]*class="[^"]*ff-accordion-header[^"]*"[^>]*>/g) || [];
+        headers.forEach(header => {
+            if (!header.includes('aria-expanded')) {
+                issues.push({
+                    component: 'Accordion',
+                    type: 'Error',
+                    message: 'Missing aria-expanded on ff-accordion-header'
+                });
+            }
+            if (header.includes('data-ff-state')) {
+                const state = header.match(/data-ff-state="([^"]*)"/);
+                const aria = header.match(/aria-expanded="([^"]*)"/);
+                if (state && aria) {
+                    const expected = state[1] === 'open' ? 'true' : 'false';
+                    if (aria[1] !== expected) {
+                        issues.push({
+                            component: 'Accordion',
+                            type: 'Warning',
+                            message: `aria-expanded ("${aria[1]}") inconsistent with data-ff-state ("${state[1]}")`
+                        });
+                    }
+                }
+            }
+        });
+    }
+
+    // Check Modal patterns
+    if (content.includes('ff-modal')) {
+        const modals = content.match(/<div[^>]*class="[^"]*ff-modal[^"]*"[^>]*>/g) || [];
+        modals.forEach(modal => {
+            if (!modal.includes('role="dialog"') && !modal.includes('role="alertdialog"')) {
+                issues.push({
+                    component: 'Modal',
+                    type: 'Error',
+                    message: 'Missing role="dialog" or "alertdialog" on ff-modal'
+                });
+            }
+            if (!modal.includes('aria-modal="true"')) {
+                issues.push({
+                    component: 'Modal',
+                    type: 'Warning',
+                    message: 'Missing aria-modal="true" on ff-modal'
+                });
+            }
+        });
+    }
+
+    return issues;
+}
+
+/**
+ * Basic Contrast Ratio Calculator (WCAG 2.1)
+ * @param {string} hex1 
+ * @param {string} hex2 
+ * @returns {number}
+ */
+export function getContrastRatio(hex1, hex2) {
+    const getL = (c) => {
+        let rv = parseInt(c, 16) / 255;
+        return rv <= 0.03928 ? rv / 12.92 : Math.pow((rv + 0.055) / 1.055, 2.4);
+    };
+    const getLuminance = (hex) => {
+        const r = hex.slice(1, 3);
+        const g = hex.slice(3, 5);
+        const b = hex.slice(5, 7);
+        return 0.2126 * getL(r) + 0.7152 * getL(g) + 0.0722 * getL(b);
+    };
+
+    const l1 = getLuminance(hex1);
+    const l2 = getLuminance(hex2);
+    return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+}

package/cli.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 /**
  * FingguFlux CLI
- * v0.9.5 Accessibility Hardening
+ * v0.9.7-RC Release Candidate Preparation
  */
 import fs from 'fs';
 import path from 'path';
 import { scanFiles, getProjectFiles } from './scanner.js';
 import { CompilerEngine } from './engine.js';
+import { runThemeCheck, printThemeCheckReport } from './theme-check.js';
+import {
+    generateSnapshot, writeSnapshot, runSnapshotCompare, printSnapshotReport
+} from './snapshot.js';
 
 const args = process.argv.slice(2);
 const command = args[0] || 'build';
@@ -34,9 +38,15 @@ async function main() {
         case 'a11y':
             await runA11y();
             break;
+        case 'theme-check':
+            await runThemeCheckCommand();
+            break;
+        case 'snapshot':
+            await runSnapshotCommand();
+            break;
         default:
             console.error(`Unknown command: ${command}`);
-            console.log('Available commands: build, analyze, doctor, a11y');
+            console.log('Available commands: build, analyze, doctor, a11y, theme-check, snapshot');
             process.exit(1);
     }
 }
@@ -219,6 +229,72 @@ async function runA11y() {
     }
 }
 
+async function runThemeCheckCommand() {
+    // Locate the tokens CSS
+    const possiblePaths = [
+        path.resolve('./packages/core/tokens.css'),
+        path.resolve('./node_modules/@finggujadhav/core/tokens.css'),
+        path.resolve('../../packages/core/tokens.css'),
+    ];
+    const tokensPath = possiblePaths.find(p => fs.existsSync(p));
+    if (!tokensPath) {
+        console.error('❌ tokens.css not found. Searched:');
+        possiblePaths.forEach(p => console.error('   ' + p));
+        process.exit(1);
+    }
+
+    const css = fs.readFileSync(tokensPath, 'utf8');
+    const verbose = args.includes('--verbose');
+
+    let result;
+    try {
+        result = runThemeCheck(css);
+    } catch (e) {
+        console.error('❌ theme-check failed:', e.message);
+        process.exit(1);
+    }
+
+    printThemeCheckReport(result, { verbose });
+
+    if (!result.pass) process.exit(1);
+}
+
+async function runSnapshotCommand() {
+    const doWrite = args.includes('--write');
+    const doCompare = args.includes('--compare');
+    const verbose = args.includes('--verbose');
+
+    if (!doWrite && !doCompare) {
+        console.error('Usage: finggu snapshot --write   (generate/update baseline)');
+        console.error('       finggu snapshot --compare (CI break-guard diff)');
+        process.exit(1);
+    }
+
+    if (doWrite) {
+        console.log('\n📸 Generating API surface snapshot…');
+        const snap = writeSnapshot();
+        const dim = snap.surface;
+        console.log(`  ✅ CSS tokens    : ${dim.cssTokens.length}`);
+        console.log(`  ✅ JS exports    : ${dim.jsExports.length}`);
+        console.log(`  ✅ CLI commands  : ${dim.cliCommands.length}`);
+        console.log(`  ✅ Component CSS : ${dim.componentFiles.length}`);
+        console.log(`\n✨ Snapshot written → packages/core/API_SURFACE_SNAPSHOT.json  (v${snap.version})\n`);
+        return;
+    }
+
+    if (doCompare) {
+        let report;
+        try {
+            report = runSnapshotCompare();
+        } catch (e) {
+            console.error('\n❌', e.message);
+            process.exit(1);
+        }
+        printSnapshotReport(report, verbose);
+        if (!report.pass) process.exit(1);
+    }
+}
+
 main().catch(err => {
     console.error('Command failed:', err);
     process.exit(1);

package/engine.js

@@ -158,7 +158,7 @@ export class CompilerEngine {
     generateReport() {
         return {
             timestamp: new Date().toISOString(),
-            engineVersion: "0.9.4",
+            engineVersion: "0.9.7",
             mode: this.mode,
             stats: this.getStats(),
             mapping: this.getMapping()

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@finggujadhav/compiler",
-    "version": "0.9.5",
+    "version": "0.9.7",
     "description": "The FingguFlux static analysis and selector hardening engine.",
     "main": "engine.js",
     "bin": {
@@ -9,9 +9,18 @@
     "files": [
         "engine.js",
         "scanner.js",
-        "cli.js"
+        "cli.js",
+        "a11y.js",
+        "theme-check.js",
+        "snapshot.js"
     ],
     "type": "module",
+    "scripts": {
+        "test": "node --test test/theme-check.test.js",
+        "test:snapshot": "node --test test/snapshot.test.js",
+        "test:all": "node --test test/**/*.test.js",
+        "release-check": "node cli.js theme-check && node cli.js snapshot --compare"
+    },
     "engines": {
         "node": ">=16.0.0"
     },

package/snapshot.js

@@ -0,0 +1,384 @@
+/**
+ * FingguFlux API Surface Snapshot Engine
+ * v0.9.7-RC – Release Candidate Preparation
+ *
+ * Generates an authoritative, machine-readable snapshot of the ENTIRE
+ * public API surface and diffs it against a stored baseline to detect:
+ *   • BREAKING: removed CSS tokens
+ *   • BREAKING: removed JS exports
+ *   • BREAKING: removed CLI commands
+ *   • BREAKING: removed component CSS files
+ *   • WARNING:  added tokens (unregistered additions)
+ *   • WARNING:  deprecated APIs approaching removal date
+ *
+ * Zero runtime overhead — this module is a build/CI tool only.
+ * It produces no browser-bound code.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ─── Paths ────────────────────────────────────────────────────────────────────
+
+const CORE_DIR = path.resolve(__dirname, '../core');
+const COMPILER_DIR = path.resolve(__dirname, '../compiler');
+const JS_HELPER_DIR = path.resolve(__dirname, '../js-helper');
+const SNAPSHOT_PATH = path.resolve(CORE_DIR, 'API_SURFACE_SNAPSHOT.json');
+const REGISTRY_PATH = path.resolve(CORE_DIR, 'TOKENS_REGISTRY.json');
+const DEPRECATION_PATH = path.resolve(CORE_DIR, 'DEPRECATION_LOG.json');
+
+// ─── CSS token extractor ──────────────────────────────────────────────────────
+
+/**
+ * Extract all --ff-* CSS custom property definitions from a CSS string.
+ * Excludes var() references (same logic as theme-check.js).
+ * @param {string} css
+ * @returns {string[]} sorted token names
+ */
+export function extractCSSTokens(css) {
+    const tokens = new Set();
+    const re = /(--ff-[\w-]+)\s*:/g;
+    let m;
+    while ((m = re.exec(css)) !== null) {
+        const before = css.slice(0, m.index);
+        const lastVar = before.lastIndexOf('var(');
+        const lastClose = before.lastIndexOf(')');
+        if (lastVar !== -1 && lastVar > lastClose) continue;
+        tokens.add(m[1]);
+    }
+    return [...tokens].sort();
+}
+
+/**
+ * Collect all --ff-* CSS tokens from tokens.css (includes dark overrides).
+ * @returns {string[]}
+ */
+export function collectCSSTokens() {
+    const tokensCss = path.join(CORE_DIR, 'tokens.css');
+    if (!fs.existsSync(tokensCss)) return [];
+    return extractCSSTokens(fs.readFileSync(tokensCss, 'utf8'));
+}
+
+// ─── Component surface collector ─────────────────────────────────────────────
+
+/**
+ * Collect all component CSS filenames published in @finggujadhav/core.
+ * @returns {string[]} sorted list of component file basenames (e.g. "button.css")
+ */
+export function collectComponentFiles() {
+    const compDir = path.join(CORE_DIR, 'components');
+    if (!fs.existsSync(compDir)) return [];
+    return fs.readdirSync(compDir)
+        .filter(f => f.endsWith('.css'))
+        .sort();
+}
+
+// ─── JS export collector ─────────────────────────────────────────────────────
+
+/**
+ * Extract named exports from a TypeScript source file.
+ * Handles: export function/class/const/type/interface/enum declarations
+ * and `export { ... }` re-export blocks.
+ * @param {string} src  file content
+ * @returns {string[]} sorted export names
+ */
+export function extractTSExports(src) {
+    const names = new Set();
+
+    // Named declarations: export function foo / export const foo / export type Foo / etc.
+    const declRe = /^export\s+(?:async\s+)?(?:function|class|const|let|var|type|interface|enum)\s+([\w$]+)/gm;
+    let m;
+    while ((m = declRe.exec(src)) !== null) names.add(m[1]);
+
+    // Re-export blocks: export { foo, bar as baz }
+    const blockRe = /export\s*\{([^}]+)\}/g;
+    while ((m = blockRe.exec(src)) !== null) {
+        m[1].split(',').forEach(part => {
+            const alias = part.trim().split(/\s+as\s+/);
+            const name = (alias[1] || alias[0]).trim();
+            if (name) names.add(name);
+        });
+    }
+
+    return [...names].sort();
+}
+
+/**
+ * Collect all public JS exports from @finggujadhav/js-helper src.
+ * @returns {string[]}
+ */
+export function collectJSExports() {
+    const srcDir = path.join(JS_HELPER_DIR, 'src');
+    if (!fs.existsSync(srcDir)) return [];
+
+    const allExports = new Set();
+    const files = fs.readdirSync(srcDir).filter(f => f.endsWith('.ts') && f !== 'index.ts');
+
+    for (const file of files) {
+        const src = fs.readFileSync(path.join(srcDir, file), 'utf8');
+        extractTSExports(src).forEach(e => allExports.add(e));
+    }
+    return [...allExports].sort();
+}
+
+// ─── CLI command surface collector ───────────────────────────────────────────
+
+/**
+ * Extract CLI command names from cli.js by scanning the switch statement.
+ * @returns {string[]} sorted command names
+ */
+export function collectCLICommands() {
+    const cliPath = path.join(COMPILER_DIR, 'cli.js');
+    if (!fs.existsSync(cliPath)) return [];
+
+    const src = fs.readFileSync(cliPath, 'utf8');
+    const commands = new Set();
+    const re = /case\s+'([\w:-]+)'\s*:/g;
+    let m;
+    while ((m = re.exec(src)) !== null) commands.add(m[1]);
+    return [...commands].sort();
+}
+
+// ─── Snapshot builder ─────────────────────────────────────────────────────────
+
+/**
+ * Generate a complete API surface snapshot object.
+ * @returns {{ generatedAt: string, version: string, surface: object }}
+ */
+export function generateSnapshot() {
+    // Read version from core package.json
+    const corePkg = JSON.parse(fs.readFileSync(path.join(CORE_DIR, 'package.json'), 'utf8'));
+
+    return {
+        $schema: 'https://fingguflux.dev/schemas/api-surface-snapshot.json',
+        generatedAt: new Date().toISOString(),
+        version: corePkg.version,
+        surface: {
+            cssTokens: collectCSSTokens(),
+            jsExports: collectJSExports(),
+            cliCommands: collectCLICommands(),
+            componentFiles: collectComponentFiles(),
+        },
+    };
+}
+
+/**
+ * Write the snapshot to disk at packages/core/API_SURFACE_SNAPSHOT.json.
+ * @param {object} [snapshotOverride]  optionally pass a pre-built snapshot
+ * @returns {object} the written snapshot
+ */
+export function writeSnapshot(snapshotOverride) {
+    const snap = snapshotOverride ?? generateSnapshot();
+    fs.writeFileSync(SNAPSHOT_PATH, JSON.stringify(snap, null, 4), 'utf8');
+    return snap;
+}
+
+// ─── Snapshot comparator ──────────────────────────────────────────────────────
+
+/**
+ * Compare two API surface sets and produce structured diff.
+ * @param {string[]} baseline  items in the stored snapshot
+ * @param {string[]} current   items in the freshly generated snapshot
+ * @param {string}   label     human-readable label for reporting
+ * @returns {{ removed: string[], added: string[] }}
+ */
+export function diffSurface(baseline, current, label) {
+    const baseSet = new Set(baseline);
+    const currentSet = new Set(current);
+
+    const removed = [...baseSet].filter(x => !currentSet.has(x)).sort();
+    const added = [...currentSet].filter(x => !baseSet.has(x)).sort();
+
+    return { label, removed, added };
+}
+
+/**
+ * Load the deprecation log.
+ * @returns {Array<{name:string, type:string, since:string, until:string, replacement:string|null, reason:string}>}
+ */
+export function loadDeprecationLog() {
+    if (!fs.existsSync(DEPRECATION_PATH)) return [];
+    return JSON.parse(fs.readFileSync(DEPRECATION_PATH, 'utf8')).deprecations ?? [];
+}
+
+/**
+ * Check for deprecated items that are past their `until` version and
+ * should have been removed — these are breaking-change guards.
+ * @param {string} currentVersion  e.g. "0.9.7"
+ * @returns {Array} overdue deprecations
+ */
+export function detectOverdueDeprecations(currentVersion) {
+    const log = loadDeprecationLog();
+    return log.filter(d => {
+        if (!d.until) return false;
+        return compareVersions(d.until, currentVersion) < 0;
+    });
+}
+
+/** Simple semver comparator (major.minor.patch only). */
+function compareVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) > (pb[i] ?? 0)) return 1;
+        if ((pa[i] ?? 0) < (pb[i] ?? 0)) return -1;
+    }
+    return 0;
+}
+
+// ─── Snapshot comparison runner ───────────────────────────────────────────────
+
+/**
+ * Full snapshot comparison pipeline.
+ * Loads the stored baseline, generates a fresh snapshot, diffs all surface
+ * dimensions, detects overdue deprecations, and returns a structured report.
+ *
+ * @param {object} [opts]
+ * @param {object} [opts.currentSnapshot]   override the live snapshot (for tests)
+ * @param {object} [opts.baselineSnapshot]  override the stored baseline (for tests)
+ * @param {string} [opts.currentVersion]    override version string (for tests)
+ * @returns {{
+ *   pass: boolean,
+ *   breakingChanges: string[],
+ *   warnings: string[],
+ *   diffs: object[],
+ *   overdueDeprecations: object[]
+ * }}
+ */
+export function runSnapshotCompare(opts = {}) {
+    // --- Load baseline ---
+    const baseline = opts.baselineSnapshot ?? (() => {
+        if (!fs.existsSync(SNAPSHOT_PATH)) {
+            throw new Error(
+                'API_SURFACE_SNAPSHOT.json not found. ' +
+                "Run 'finggu snapshot --write' to generate the initial baseline."
+            );
+        }
+        return JSON.parse(fs.readFileSync(SNAPSHOT_PATH, 'utf8'));
+    })();
+
+    // --- Generate current state ---
+    const current = opts.currentSnapshot ?? generateSnapshot();
+
+    // --- Diff each surface dimension ---
+    const diffs = [
+        diffSurface(baseline.surface.cssTokens, current.surface.cssTokens, 'CSS Tokens'),
+        diffSurface(baseline.surface.jsExports, current.surface.jsExports, 'JS Exports'),
+        diffSurface(baseline.surface.cliCommands, current.surface.cliCommands, 'CLI Commands'),
+        diffSurface(baseline.surface.componentFiles, current.surface.componentFiles, 'Component Files'),
+    ];
+
+    const breakingChanges = [];
+    const warnings = [];
+
+    for (const diff of diffs) {
+        // Removals are BREAKING
+        for (const item of diff.removed) {
+            breakingChanges.push(`[BREAKING] ${diff.label}: '${item}' was removed from the public API surface.`);
+        }
+        // Additions are warnings (undocumented surface growth)
+        for (const item of diff.added) {
+            warnings.push(`[WARN] ${diff.label}: '${item}' is new — ensure it is intentional and documented.`);
+        }
+    }
+
+    // --- Overdue deprecations (items past their `until` date are breaking) ---
+    const currentVersion = opts.currentVersion ?? current.version;
+    const overdue = detectOverdueDeprecations(currentVersion);
+    for (const d of overdue) {
+        breakingChanges.push(
+            `[BREAKING] Deprecation overdue: '${d.name}' (${d.type}) was scheduled for removal in v${d.until} ` +
+            `but is still present. Remove it or extend the deprecation window.`
+        );
+    }
+
+    return {
+        pass: breakingChanges.length === 0,
+        breakingChanges,
+        warnings,
+        diffs,
+        overdueDeprecations: overdue,
+        baselineVersion: baseline.version,
+        currentVersion,
+    };
+}
+
+// ─── CLI printer ──────────────────────────────────────────────────────────────
+
+const C = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+
+const line = (ch = '─', n = 54) => ch.repeat(n);
+
+export function printSnapshotReport(report, verbose = false) {
+    const { pass, breakingChanges, warnings, diffs, overdueDeprecations,
+        baselineVersion, currentVersion } = report;
+
+    console.log('');
+    console.log(`${C.bold}${C.cyan}📸 FingguFlux API Surface Snapshot — Drift Audit${C.reset}`);
+    console.log(C.gray + line() + C.reset);
+    console.log(`  Baseline : ${C.bold}v${baselineVersion}${C.reset}`);
+    console.log(`  Current  : ${C.bold}v${currentVersion}${C.reset}`);
+    console.log('');
+
+    // Surface summary
+    for (const diff of diffs) {
+        const removedCount = diff.removed.length;
+        const addedCount = diff.added.length;
+        const icon = removedCount ? C.red + '✖' :
+            addedCount ? C.yellow + '⚠' :
+                C.green + '✔';
+        console.log(`  ${icon}${C.reset}  ${diff.label.padEnd(18)} ` +
+            `${removedCount ? C.red + removedCount + ' removed' + C.reset : '—'} ` +
+            `${addedCount ? C.yellow + addedCount + ' added' + C.reset : ''}`);
+    }
+
+    // Breaking changes
+    if (breakingChanges.length > 0) {
+        console.log('');
+        console.log(C.red + C.bold + `  ⛔ ${breakingChanges.length} Breaking Change(s) Detected` + C.reset);
+        for (const msg of breakingChanges) {
+            console.log(`  ${C.red}${msg}${C.reset}`);
+        }
+    }
+
+    // Warnings
+    if (warnings.length > 0 && (verbose || breakingChanges.length === 0)) {
+        console.log('');
+        console.log(C.yellow + C.bold + `  ⚠  ${warnings.length} Warning(s)` + C.reset);
+        for (const msg of warnings) {
+            console.log(`  ${C.yellow}${msg}${C.reset}`);
+        }
+    }
+
+    // Overdue deprecations
+    if (overdueDeprecations.length > 0) {
+        console.log('');
+        console.log(C.red + C.bold + `  🚨 ${overdueDeprecations.length} Overdue Deprecation(s)` + C.reset);
+        for (const d of overdueDeprecations) {
+            console.log(`  ${C.red}• ${d.name} (${d.type}) — scheduled removal: v${d.until}${C.reset}`);
+            if (d.replacement) console.log(`    ${C.gray}→ replacement: ${d.replacement}${C.reset}`);
+        }
+    }
+
+    console.log('');
+    console.log(C.gray + line() + C.reset);
+
+    if (pass) {
+        console.log(`${C.green}${C.bold}✨ API surface STABLE. No breaking changes detected.${C.reset}`);
+    } else {
+        console.log(`${C.red}${C.bold}🚫 API surface has BREAKING CHANGES. Release blocked.${C.reset}`);
+        console.log(`${C.gray}  Fix all [BREAKING] issues before bumping version.${C.reset}`);
+    }
+    console.log('');
+}

package/theme-check.js

@@ -0,0 +1,480 @@
+/**
+ * FingguFlux Theme-Check Engine
+ * v0.9.6 – Theme Engine Stabilization & Contract Freeze
+ *
+ * ZERO RUNTIME OVERHEAD: This module is a pure build-time static analyser.
+ * It reads CSS files and the TOKENS_REGISTRY.json contract, then emits
+ * structured diagnostics.  It produces NO code that ships to the browser.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// ─── ANSI colour helpers ──────────────────────────────────────────────────────
+const C = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    grey: '\x1b[90m',
+};
+const clr = (code, text) => `${code}${text}${C.reset}`;
+
+// ─── Token extraction ─────────────────────────────────────────────────────────
+
+/**
+ * Parse every `--ff-*` custom-property *definition* from a CSS string.
+ * Only captures tokens that appear on the LEFT-hand side of a colon,
+ * i.e. actual definitions, not var() references.
+ *
+ * @param {string} css
+ * @returns {Set<string>}
+ */
+export function extractDefinedTokens(css) {
+    const defined = new Set();
+    // Match:  --ff-something-here  :  <value>
+    const re = /(--ff-[\w-]+)\s*:/g;
+    let m;
+    while ((m = re.exec(css)) !== null) {
+        // Skip tokens that appear inside var(...) — they are references, not definitions
+        const before = css.slice(0, m.index);
+        const lastVar = before.lastIndexOf('var(');
+        const lastClose = before.lastIndexOf(')');
+        if (lastVar !== -1 && lastVar > lastClose) continue;
+        defined.add(m[1]);
+    }
+    return defined;
+}
+
+
+/**
+ * Build a context map: token → array of CSS at-rule / selector scopes
+ * where the token is defined.
+ *
+ * Scopes we care about:
+ *   'light'  — :root or [data-ff-theme="light"]
+ *   'dark'   — [data-ff-theme="dark"]
+ *   'system' — @media (prefers-color-scheme: dark)
+ *   'global' — anything else (e.g. root-level without a theme wrapper)
+ *
+ * @param {string} css
+ * @returns {Map<string, Set<string>>}  token → scopes
+ */
+export function extractTokensByScope(css) {
+    /** @type {Map<string, Set<string>>} */
+    const map = new Map();
+
+    /**
+     * We parse character-by-character to maintain an accurate scope stack.
+     * scopeStack[i] holds the classified scope name for depth i+1.
+     *
+     * Scopes:
+     *   'light'  — :root or [data-ff-theme="light"] (or comma-list containing either)
+     *   'dark'   — [data-ff-theme="dark"]
+     *   'system' — @media (prefers-color-scheme: dark) { ... }
+     *   'global' — anything else
+     *
+     * Nesting rule: 'system' dominates — any inner selector inside a system
+     * @media block stays classified as 'system', even if it contains ':root'.
+     */
+    const scopeStack = [];   // one entry per open brace depth
+    let depth = 0;
+
+    let pending = '';        // text accumulating before the next '{'
+    let inString = false;
+    let stringChar = '';
+
+    /**
+     * @param {string} sel - the raw selector / at-rule text
+     * @param {string} parentScope - the scope of the enclosing block ('global', 'system', etc.)
+     */
+    const classifySelector = (sel, parentScope) => {
+        const s = sel.toLowerCase().trim();
+        if (!s) return parentScope;
+
+        // @media rule itself
+        if (s.includes('@media')) {
+            if (s.includes('prefers-color-scheme') && s.includes('dark')) {
+                return 'system';
+            }
+            return 'global';
+        }
+
+        // If we're already inside a system (dark media) block, any inner rule is system too
+        if (parentScope === 'system') return 'system';
+
+        // Explicit dark theme selector
+        if (s.includes('[data-ff-theme="dark"]') || s.includes("[data-ff-theme='dark']")) {
+            return 'dark';
+        }
+
+        // Light: :root or comma-list like ":root, [data-ff-theme='light']"
+        if (
+            s.includes(':root') ||
+            s.includes('[data-ff-theme="light"]') ||
+            s.includes("[data-ff-theme='light']")
+        ) {
+            return 'light';
+        }
+
+        return 'global';
+    };
+
+    const addToken = (tok, scope) => {
+        if (!map.has(tok)) map.set(tok, new Set());
+        map.get(tok).add(scope);
+    };
+
+    const extractTokensFromText = (text, scope) => {
+        // Match only actual custom-property definitions:
+        //   --ff-name  :  <value>
+        // We use a regex that matches --ff-name followed by whitespace and colon,
+        // then verify it is NOT inside a var() call.
+        const re = /(--ff-[\w-]+)\s*:/g;
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            // Exclude matches that are inside var(...) — check what precedes the token
+            const before = text.slice(0, m.index);
+            const lastVar = before.lastIndexOf('var(');
+            const lastClose = before.lastIndexOf(')');
+            if (lastVar !== -1 && lastVar > lastClose) {
+                continue; // inside a var() call
+            }
+            addToken(m[1], scope);
+        }
+    };
+
+    // Determine effective scope from the stack (outermost non-global wins for system)
+    const currentScope = () => {
+        // 'system' takes absolute priority (outermost) when present anywhere in stack
+        if (scopeStack.includes('system')) return 'system';
+        // Otherwise find the innermost meaningful scope
+        for (let i = scopeStack.length - 1; i >= 0; i--) {
+            if (scopeStack[i] !== 'global') return scopeStack[i];
+        }
+        return 'global';
+    };
+
+    const parentScope = () => {
+        if (scopeStack.length === 0) return 'global';
+        // Same logic as currentScope but without the new entry
+        if (scopeStack.includes('system')) return 'system';
+        for (let i = scopeStack.length - 1; i >= 0; i--) {
+            if (scopeStack[i] !== 'global') return scopeStack[i];
+        }
+        return 'global';
+    };
+
+    for (let i = 0; i < css.length; i++) {
+        const ch = css[i];
+
+        // Basic string tracking (to avoid misinterpreting { } inside strings/comments)
+        if (!inString && (ch === '"' || ch === "'")) {
+            inString = true;
+            stringChar = ch;
+            pending += ch;
+            continue;
+        }
+        if (inString && ch === stringChar && css[i - 1] !== '\\') {
+            inString = false;
+            pending += ch;
+            continue;
+        }
+        if (inString) {
+            pending += ch;
+            continue;
+        }
+
+        if (ch === '{') {
+            const scope = classifySelector(pending, parentScope());
+            scopeStack.push(scope);
+            depth++;
+            pending = '';
+        } else if (ch === '}') {
+            // Flush any pending text before closing the block
+            if (pending.trim()) {
+                extractTokensFromText(pending, currentScope());
+            }
+            scopeStack.pop();
+            depth--;
+            pending = '';
+        } else {
+            pending += ch;
+            // Flush at semicolons to keep memory usage bounded
+            if (ch === ';' && depth > 0) {
+                extractTokensFromText(pending, currentScope());
+                pending = '';
+            }
+        }
+    }
+
+    return map;
+}
+
+
+
+// ─── Registry loader ──────────────────────────────────────────────────────────
+
+/**
+ * Locate and parse TOKENS_REGISTRY.json.
+ * Searches: CWD, packages/core, ../../packages/core (monorepo root).
+ *
+ * @returns {{ registry: object, registryPath: string }}
+ */
+export function loadRegistry() {
+    const candidates = [
+        path.resolve('./packages/core/TOKENS_REGISTRY.json'),
+        path.resolve('../../packages/core/TOKENS_REGISTRY.json'),
+        path.resolve('./node_modules/@finggujadhav/core/TOKENS_REGISTRY.json'),
+    ];
+
+    for (const p of candidates) {
+        if (fs.existsSync(p)) {
+            try {
+                return { registry: JSON.parse(fs.readFileSync(p, 'utf8')), registryPath: p };
+            } catch (e) {
+                throw new Error(`TOKENS_REGISTRY.json at ${p} is malformed JSON: ${e.message}`);
+            }
+        }
+    }
+
+    throw new Error(
+        'TOKENS_REGISTRY.json not found. ' +
+        'Expected at packages/core/TOKENS_REGISTRY.json. ' +
+        'Run the FingguFlux bootstrap task to regenerate it.'
+    );
+}
+
+/**
+ * Returns the flat set of ALL token names from every category in the registry.
+ *
+ * @param {object} registry
+ * @returns {Set<string>}
+ */
+export function registryAllTokens(registry) {
+    const all = new Set();
+    for (const cat of Object.values(registry.categories)) {
+        for (const tok of cat.tokens) all.add(tok);
+    }
+    return all;
+}
+
+// ─── Core checks ─────────────────────────────────────────────────────────────
+
+/**
+ * REMOVAL DETECTION
+ * Finds tokens present in the registry but ABSENT from the actual CSS.
+ *
+ * @param {Set<string>} registryTokens
+ * @param {Set<string>} definedTokens
+ * @returns {string[]} removed token names
+ */
+export function detectRemovals(registryTokens, definedTokens) {
+    const removed = [];
+    for (const tok of registryTokens) {
+        if (!definedTokens.has(tok)) removed.push(tok);
+    }
+    return removed.sort();
+}
+
+/**
+ * RENAME DETECTION
+ * Checks the registry's `renames` array for tokens that have been moved
+ * but whose *old* name still appears as a definition in the CSS.
+ *
+ * Registry renames format:
+ *   { "from": "--ff-old-name", "to": "--ff-new-name", "since": "0.9.6" }
+ *
+ * @param {Array<{from:string,to:string,since:string}>} renames
+ * @param {Set<string>} definedTokens
+ * @returns {Array<{from:string,to:string,since:string}>}
+ */
+export function detectRenames(renames, definedTokens) {
+    return renames.filter(r => definedTokens.has(r.from));
+}
+
+/**
+ * ADDITION DETECTION
+ * Tokens defined in CSS that are NOT present in the registry (undocumented additions).
+ *
+ * @param {Set<string>} registryTokens
+ * @param {Set<string>} definedTokens
+ * @returns {string[]}
+ */
+export function detectAdditions(registryTokens, definedTokens) {
+    const added = [];
+    for (const tok of definedTokens) {
+        if (!registryTokens.has(tok)) added.push(tok);
+    }
+    return added.sort();
+}
+
+/**
+ * THEME COMPLETENESS
+ * Validates that every token listed under registry.theming[theme].required
+ * is defined (has a definition) within the correct CSS scope.
+ *
+ * @param {object} theming     registry.theming
+ * @param {Map<string, Set<string>>} tokensByScope
+ * @returns {Object.<string, string[]>}  theme → missing tokens
+ */
+export function validateThemeCompleteness(theming, tokensByScope) {
+    const results = {};
+
+    for (const [theme, config] of Object.entries(theming)) {
+        const missing = [];
+        const required = config.required || [];
+
+        for (const tok of required) {
+            const scopes = tokensByScope.get(tok);
+            if (!scopes) {
+                missing.push(tok);
+                continue;
+            }
+
+            let satisfied = false;
+
+            if (theme === 'light') {
+                // Light theme: token must be present in 'light' scope (which includes :root)
+                satisfied = scopes.has('light');
+            } else {
+                // Dark / system: token MUST be explicitly overridden in that specific scope.
+                // A token that only exists in 'light' scope is NOT considered satisfied
+                // for dark/system, because that is precisely what theme-check is enforcing —
+                // that the author hasn't forgotten to provide the dark/system overrides.
+                satisfied = scopes.has(theme);
+            }
+
+            if (!satisfied) missing.push(tok);
+        }
+
+        results[theme] = missing;
+    }
+
+    return results;
+}
+
+// ─── Main runner ──────────────────────────────────────────────────────────────
+
+/**
+ * Run the full theme-check suite against a CSS string.
+ *
+ * @param {string} css  Combined tokens CSS content
+ * @param {object} [registryOverride]  Inject registry directly (used in tests)
+ * @returns {{
+ *   pass: boolean,
+ *   removals: string[],
+ *   renames: Array,
+ *   additions: string[],
+ *   themeGaps: Object,
+ *   warnings: string[]
+ * }}
+ */
+export function runThemeCheck(css, registryOverride) {
+    const { registry } = registryOverride
+        ? { registry: registryOverride }
+        : loadRegistry();
+
+    const definedTokens = extractDefinedTokens(css);
+    const tokensByScope = extractTokensByScope(css);
+    const registryTokens = registryAllTokens(registry);
+
+    const removals = detectRemovals(registryTokens, definedTokens);
+    const renames = detectRenames(registry.renames || [], definedTokens);
+    const additions = detectAdditions(registryTokens, definedTokens);
+    const themeGaps = validateThemeCompleteness(registry.theming || {}, tokensByScope);
+
+    const warnings = [];
+    if (additions.length > 0) {
+        warnings.push(
+            `${additions.length} token(s) defined in CSS but absent from TOKENS_REGISTRY.json. ` +
+            'Add them to the registry to freeze the contract.'
+        );
+    }
+
+    const pass =
+        removals.length === 0 &&
+        renames.length === 0 &&
+        Object.values(themeGaps).every(arr => arr.length === 0);
+
+    return { pass, removals, renames, additions, themeGaps, warnings };
+}
+
+// ─── Pretty-printer ───────────────────────────────────────────────────────────
+
+/**
+ * Print a human-readable theme-check report to stdout.
+ *
+ * @param {{ pass: boolean, removals: string[], renames: Array, additions: string[], themeGaps: Object, warnings: string[] }} result
+ * @param {{ verbose?: boolean }} [opts]
+ */
+export function printThemeCheckReport(result, opts = {}) {
+    const { pass, removals, renames, additions, themeGaps, warnings } = result;
+    const verbose = opts.verbose || false;
+
+    console.log('');
+    console.log(clr(C.bold + C.cyan, '🎨 FingguFlux Theme-Check – Contract Freeze Audit'));
+    console.log(clr(C.grey, '─'.repeat(54)));
+
+    // ── Removals ──────────────────────────────────────────────
+    if (removals.length === 0) {
+        console.log(clr(C.green, '✅ No token removals detected.'));
+    } else {
+        console.log(clr(C.red, `❌ ${removals.length} token(s) REMOVED (breaking change!):`));
+        removals.forEach(t => console.log(clr(C.red, `   – ${t}`)));
+    }
+
+    // ── Renames ───────────────────────────────────────────────
+    if (renames.length === 0) {
+        console.log(clr(C.green, '✅ No stale renamed tokens in CSS.'));
+    } else {
+        console.log(clr(C.yellow, `⚠️  ${renames.length} stale rename(s) found:`));
+        renames.forEach(r =>
+            console.log(clr(C.yellow, `   ${r.from}  →  ${r.to}  (since v${r.since})`))
+        );
+    }
+
+    // ── Unregistered additions ────────────────────────────────
+    if (additions.length === 0) {
+        console.log(clr(C.green, '✅ All defined tokens are registered.'));
+    } else if (verbose) {
+        console.log(clr(C.yellow, `⚠️  ${additions.length} unregistered token(s):`));
+        additions.forEach(t => console.log(clr(C.grey, `   + ${t}`)));
+    } else {
+        console.log(clr(C.yellow, `⚠️  ${additions.length} unregistered token(s). Use --verbose to list.`));
+    }
+
+    // ── Theme completeness ────────────────────────────────────
+    console.log('');
+    console.log(clr(C.bold, '  Theme Completeness'));
+    console.log(clr(C.grey, '  ' + '─'.repeat(40)));
+
+    for (const [theme, missing] of Object.entries(themeGaps)) {
+        const icon = missing.length === 0 ? clr(C.green, '✅') : clr(C.red, '❌');
+        const label = theme.padEnd(8);
+        if (missing.length === 0) {
+            console.log(`  ${icon} ${label} — all required tokens present`);
+        } else {
+            console.log(`  ${icon} ${label} — ${missing.length} missing:`);
+            missing.forEach(t => console.log(clr(C.red, `        – ${t}`)));
+        }
+    }
+
+    // ── Warnings ──────────────────────────────────────────────
+    if (warnings.length > 0) {
+        console.log('');
+        warnings.forEach(w => console.log(clr(C.yellow, `  ⚡ ${w}`)));
+    }
+
+    // ── Final verdict ─────────────────────────────────────────
+    console.log('');
+    console.log(clr(C.grey, '─'.repeat(54)));
+    if (pass) {
+        console.log(clr(C.bold + C.green, '✨ Theme contract STABLE. No issues found.'));
+    } else {
+        console.log(clr(C.bold + C.red, '💥 Theme contract UNSTABLE. Fix the issues above.'));
+    }
+    console.log('');
+}