@brad-frost-web/eddie-brain 0.32.0

package/dist/analyze/slot-contract-validator.js

@@ -0,0 +1,232 @@
+/**
+ * Slot Contract Validator
+ *
+ * Detects the silent-drop class of bug filed under #595, #627, #639: Eddie
+ * markup that uses a `slot="X"` attribute referencing a slot the component
+ * doesn't declare. The unknown slot reaches the shadow DOM with no matching
+ * `<slot name="X">`, the content is dropped, and nothing in the browser
+ * surfaces the failure.
+ *
+ * Scope:
+ *  - `.html` files (consumer projects, boilerplates)
+ *  - Lit `html\`...\`` template regions inside `.ts` / `.tsx` files
+ *
+ * Strategy:
+ *  - Find every `<ed-...>` opening tag
+ *  - Walk forward to its matching close tag (depth-tracked)
+ *  - Inside that range, find every immediate-child element with a
+ *    `slot="NAME"` attribute
+ *  - Look up the parent component in the index; if NAME is not in the
+ *    declared slot list, emit a finding
+ *
+ * The check is intentionally conservative: false positives are worse than
+ * false negatives because validators run in tight CI loops and noisy
+ * output gets ignored. Components missing from the index are skipped
+ * (rather than flagged as unknown), and the regex is forgiving about
+ * whitespace and quote style.
+ */
+import { readFile } from 'fs/promises';
+export class SlotContractValidator {
+    index;
+    constructor(index) {
+        this.index = index;
+    }
+    /**
+     * Validate a single file for slot-contract violations.
+     * Returns an empty array for files we don't scan (e.g. .scss).
+     */
+    async validateFile(filePath) {
+        let content;
+        try {
+            content = await readFile(filePath, 'utf-8');
+        }
+        catch (error) {
+            return [
+                {
+                    id: `slot-contract-read-error-${Date.now()}`,
+                    category: 'consistency',
+                    severity: 'error',
+                    message: `Failed to read file: ${error instanceof Error ? error.message : String(error)}`,
+                    file: filePath,
+                    autoFixable: false,
+                },
+            ];
+        }
+        if (filePath.endsWith('.html')) {
+            return this.scanRegion(filePath, content, 0);
+        }
+        if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) {
+            const issues = [];
+            for (const region of this.extractLitTemplates(content)) {
+                issues.push(...this.scanRegion(filePath, region.content, region.startLine));
+            }
+            return issues;
+        }
+        return [];
+    }
+    /**
+     * Scan one chunk of markup for slot-contract violations.
+     * `startLine` is the 0-based line offset of the chunk within the file —
+     * issue line numbers are reported relative to the file, not the chunk.
+     */
+    scanRegion(filePath, region, startLine) {
+        const issues = [];
+        // Find every <ed-* ...> opening tag (not self-closing). Walk forward to
+        // the matching close, then scan that range for slotted children.
+        const openTagRegex = /<(ed-[a-z][a-z0-9-]*)\b([^>]*?)>/gi;
+        let match;
+        while ((match = openTagRegex.exec(region)) !== null) {
+            const tagName = match[1].toLowerCase();
+            const attrText = match[2];
+            // Skip self-closing tags — they have no children to slot into.
+            if (attrText.trim().endsWith('/'))
+                continue;
+            const openEnd = match.index + match[0].length;
+            const closeIdx = this.findMatchingClose(region, tagName, openEnd);
+            if (closeIdx === -1)
+                continue;
+            const innerMarkup = region.substring(openEnd, closeIdx);
+            issues.push(...this.scanInner(filePath, tagName, innerMarkup, startLine + this.lineOf(region, openEnd)));
+        }
+        return issues;
+    }
+    /**
+     * Look up the component, then scan the inner markup for any
+     * `slot="NAME"` attribute. Emit a finding for each NAME that the
+     * component doesn't declare.
+     */
+    scanInner(filePath, parentTag, inner, innerStartLine) {
+        const component = this.index.getComponent(parentTag);
+        if (!component)
+            return [];
+        const declaredSlots = new Set(component.slots.map((s) => s.name));
+        // The "default" slot is always reachable as unnamed children — anything
+        // without a slot attribute lands there. Only NAMED slot violations count.
+        declaredSlots.delete('default');
+        const issues = [];
+        const slotAttrRegex = /\bslot\s*=\s*(?:"([^"]+)"|'([^']+)')/g;
+        let m;
+        while ((m = slotAttrRegex.exec(inner)) !== null) {
+            const slotName = m[1] ?? m[2];
+            if (!slotName || slotName === 'default')
+                continue;
+            if (declaredSlots.has(slotName))
+                continue;
+            const lineWithinInner = this.lineOf(inner, m.index);
+            const declared = Array.from(declaredSlots).sort();
+            const declaredHint = declared.length === 0
+                ? `${parentTag} declares no named slots — content with a slot attribute will be dropped`
+                : `declared slots: ${declared.join(', ')}`;
+            issues.push({
+                id: `slot-contract-${parentTag}-${slotName}-${innerStartLine + lineWithinInner}`,
+                category: 'consistency',
+                severity: 'error',
+                message: `<${parentTag}> has no slot named "${slotName}" — slotted content will be silently dropped (${declaredHint})`,
+                file: filePath,
+                line: innerStartLine + lineWithinInner + 1,
+                actual: `slot="${slotName}"`,
+                expected: declared.length > 0 ? `slot="${declared[0]}" (or another declared slot)` : 'remove the slot attribute',
+                autoFixable: false,
+                suggestion: `Call eddie_get_component("${parentTag}") to see the real slot contract; consider whether a property API is the right path instead.`,
+            });
+        }
+        return issues;
+    }
+    /**
+     * Walk forward from `startIdx` to find the matching `</tag>` for an
+     * already-opened `<tag …>`. Tracks open/close depth so nested same-named
+     * tags don't fool the matcher.
+     */
+    findMatchingClose(content, tagName, startIdx) {
+        const openRe = new RegExp(`<${tagName}\\b[^>]*>`, 'gi');
+        const closeRe = new RegExp(`<\\/${tagName}\\s*>`, 'gi');
+        openRe.lastIndex = startIdx;
+        closeRe.lastIndex = startIdx;
+        let depth = 1;
+        while (depth > 0) {
+            const nextOpen = openRe.exec(content);
+            const nextClose = closeRe.exec(content);
+            if (!nextClose)
+                return -1;
+            if (nextOpen && nextOpen.index < nextClose.index) {
+                if (!nextOpen[0].endsWith('/>'))
+                    depth++;
+                // Keep closeRe.lastIndex where it is — we'll re-scan from after the open.
+                closeRe.lastIndex = nextOpen.index + nextOpen[0].length;
+            }
+            else {
+                depth--;
+                if (depth === 0)
+                    return nextClose.index;
+                openRe.lastIndex = nextClose.index + nextClose[0].length;
+            }
+        }
+        return -1;
+    }
+    /**
+     * Extract Lit `html\`...\`` template regions from a TS/TSX file.
+     * Mirrors NamingValidator.extractLitTemplates, but stripped down — we
+     * don't need to handle every nesting edge case, just the common ones.
+     */
+    extractLitTemplates(content) {
+        const regions = [];
+        const lines = content.split('\n');
+        let inTemplate = false;
+        let templateLines = [];
+        let templateStartLine = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const trimmed = line.trim();
+            if (trimmed.startsWith('//'))
+                continue;
+            if (!inTemplate) {
+                const idx = line.indexOf('html`');
+                if (idx !== -1) {
+                    inTemplate = true;
+                    templateStartLine = i;
+                    const after = line.substring(idx + 5);
+                    templateLines = [after];
+                    if (this.templateClosesOnLine(after)) {
+                        inTemplate = false;
+                        regions.push({ content: templateLines.join('\n'), startLine: templateStartLine });
+                        templateLines = [];
+                    }
+                }
+            }
+            else {
+                templateLines.push(line);
+                if (this.templateClosesOnLine(line)) {
+                    inTemplate = false;
+                    regions.push({ content: templateLines.join('\n'), startLine: templateStartLine });
+                    templateLines = [];
+                }
+            }
+        }
+        return regions;
+    }
+    templateClosesOnLine(line) {
+        let inExpr = 0;
+        for (let i = 0; i < line.length; i++) {
+            if (line[i] === '$' && line[i + 1] === '{') {
+                inExpr++;
+                i++;
+            }
+            else if (line[i] === '}' && inExpr > 0) {
+                inExpr--;
+            }
+            else if (line[i] === '`' && inExpr === 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+    lineOf(content, offset) {
+        let line = 0;
+        for (let i = 0; i < offset && i < content.length; i++) {
+            if (content[i] === '\n')
+                line++;
+        }
+        return line;
+    }
+}
+//# sourceMappingURL=slot-contract-validator.js.map

package/dist/analyze/slot-contract-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-contract-validator.js","sourceRoot":"","sources":["../../src/analyze/slot-contract-validator.ts"],"names":[],"mappings":"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"}

package/dist/analyze/token-validator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Token Validator
+ *
+ * Validates token usage across SCSS files, enforcing the 3-tier token architecture,
+ * naming conventions, intent matching, theme coverage, and deprecation rules.
+ */
+import { HealthIssue } from '../types.js';
+import type { TokenTaxonomy } from '../knowledge-graph/token-taxonomy.js';
+export declare class TokenValidator {
+    private readonly tokenPatterns;
+    /**
+     * Validate a single SCSS file for token usage violations
+     */
+    validateFile(filePath: string, taxonomy: TokenTaxonomy): Promise<HealthIssue[]>;
+    /**
+     * Validate all SCSS files in a directory
+     */
+    validateDirectory(dirPath: string, taxonomy: TokenTaxonomy): Promise<HealthIssue[]>;
+    /**
+     * Check for raw color, spacing, and font values
+     */
+    private checkRawValues;
+    /**
+     * Validate that component code uses tier 2+ tokens, not tier 1 directly
+     */
+    private validateTokenTier;
+    /**
+     * Validate that token usage matches its intent (e.g., don't use background token as text color)
+     */
+    private validateIntentMatch;
+    /**
+     * Pull the color subcategory ("background" | "content" | "border") out of
+     * a token name like `--ed-theme-color-content-subtle`. Returns undefined
+     * for non-color tokens or color tokens that don't carry a subcategory
+     * segment in the name (definition-tier raw colors, etc.).
+     */
+    private colorSubcategoryFromTokenName;
+    /**
+     * Bucket a CSS property name into one of the three color subcategory
+     * families. Returns undefined for properties that aren't color-bearing
+     * (we only enforce the rule on color properties; spacing, typography,
+     * etc. take other tokens entirely).
+     *
+     *   background-* / background-color  → "background"
+     *   color, fill, caret-color, accent-color → "content"
+     *   border-*-color / outline-*-color → "border"
+     */
+    private colorPropertyFamily;
+    /**
+     * Check if a token is deprecated
+     */
+    private checkDeprecation;
+    /**
+     * Check that tokens used in one theme exist in all themes.
+     *
+     * Only checks semantic/component tokens (--ed-theme-*), not definition-tier tokens.
+     * Strips comments before matching. Handles var() fallback values correctly
+     * (e.g. var(--ed-foo, none) extracts only --ed-foo).
+     */
+    private checkThemeCoverage;
+}
+//# sourceMappingURL=token-validator.d.ts.map

package/dist/analyze/token-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-validator.d.ts","sourceRoot":"","sources":["../../src/analyze/token-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EACL,WAAW,EAIZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AAS1E,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAsB5B;IAEF;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA2ErF;;OAEG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAezF;;OAEG;IACH,OAAO,CAAC,cAAc;IA0EtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkCzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA2C3B;;;;;OAKG;IACH,OAAO,CAAC,6BAA6B;IAOrC;;;;;;;;;OASG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA0BxB;;;;;;OAMG;YACW,kBAAkB;CA0DjC"}

package/dist/analyze/token-validator.js

@@ -0,0 +1,348 @@
+/**
+ * Token Validator
+ *
+ * Validates token usage across SCSS files, enforcing the 3-tier token architecture,
+ * naming conventions, intent matching, theme coverage, and deprecation rules.
+ */
+import { readFile } from 'fs/promises';
+import scss from 'postcss-scss';
+import glob from 'fast-glob';
+export class TokenValidator {
+    tokenPatterns = [
+        // Raw hex colors
+        {
+            pattern: /#[0-9a-fA-F]{3,6}(?!\w)/g,
+            description: 'Raw hex color value found. Should use --ed-theme-color-* token',
+            category: 'tokens',
+            severity: 'error',
+        },
+        // Raw px values for spacing (outside of calculations/comments)
+        {
+            pattern: /(?<!\/\/.*):\s*\d+px\s*(?:;|!important)/g,
+            description: 'Raw pixel value for spacing/sizing. Should use --ed-spacing-* token',
+            category: 'tokens',
+            severity: 'error',
+        },
+        // Raw font-family values
+        {
+            pattern: /font-family\s*:\s*[^;]*(?!var\(--ed)/g,
+            description: 'Raw font-family value. Should use --ed-typography-font-* token',
+            category: 'tokens',
+            severity: 'error',
+        },
+    ];
+    /**
+     * Validate a single SCSS file for token usage violations
+     */
+    async validateFile(filePath, taxonomy) {
+        try {
+            const content = await readFile(filePath, 'utf-8');
+            const issues = [];
+            // Parse SCSS
+            const root = scss.parse(content);
+            let lineNumber = 0;
+            // Check for raw values using regex patterns
+            const lines = content.split('\n');
+            issues.push(...this.checkRawValues(filePath, lines));
+            // Check CSS variable declarations and usage
+            root.walkDecls((decl) => {
+                const declLine = decl.source?.start?.line || lineNumber;
+                // Check if using a token (has var(--ed-...))
+                if (decl.value.includes('var(--ed-')) {
+                    const matches = decl.value.match(/var\((--ed-[^)]+)\)/g);
+                    if (matches) {
+                        for (const match of matches) {
+                            const tokenName = match.replace(/var\(|\)/g, '');
+                            // Validate token tier
+                            const tierIssue = this.validateTokenTier(filePath, declLine, tokenName, taxonomy);
+                            if (tierIssue)
+                                issues.push(tierIssue);
+                            // Validate intent match (e.g., background token for color property)
+                            const intentIssue = this.validateIntentMatch(filePath, declLine, decl.prop, tokenName, taxonomy);
+                            if (intentIssue)
+                                issues.push(intentIssue);
+                            // Check for deprecation
+                            const deprecationIssue = this.checkDeprecation(filePath, declLine, tokenName, taxonomy);
+                            if (deprecationIssue)
+                                issues.push(deprecationIssue);
+                        }
+                    }
+                }
+            });
+            // Check theme coverage
+            const coverageIssues = await this.checkThemeCoverage(filePath, taxonomy);
+            issues.push(...coverageIssues);
+            return issues;
+        }
+        catch (error) {
+            return [
+                {
+                    id: `token-validate-error-${Date.now()}`,
+                    category: 'tokens',
+                    severity: 'error',
+                    message: `Failed to validate file: ${error instanceof Error ? error.message : String(error)}`,
+                    file: filePath,
+                    autoFixable: false,
+                },
+            ];
+        }
+    }
+    /**
+     * Validate all SCSS files in a directory
+     */
+    async validateDirectory(dirPath, taxonomy) {
+        const scssFiles = await glob('**/*.scss', {
+            cwd: dirPath,
+            absolute: true,
+        });
+        const allIssues = [];
+        for (const file of scssFiles) {
+            const issues = await this.validateFile(file, taxonomy);
+            allIssues.push(...issues);
+        }
+        return allIssues;
+    }
+    /**
+     * Check for raw color, spacing, and font values
+     */
+    checkRawValues(filePath, lines) {
+        const issues = [];
+        let inBlockComment = false;
+        lines.forEach((line, index) => {
+            const trimmed = line.trim();
+            // Track block comments
+            if (trimmed.includes('/*'))
+                inBlockComment = true;
+            if (trimmed.includes('*/')) {
+                inBlockComment = false;
+                return;
+            }
+            if (inBlockComment)
+                return;
+            // Skip single-line comments
+            if (trimmed.startsWith('//'))
+                return;
+            // Skip lines that are token definitions (CSS custom property declarations)
+            if (trimmed.startsWith('--ed-'))
+                return;
+            // Check for raw hex colors
+            const hexMatches = line.matchAll(/#[0-9a-fA-F]{3,6}(?!\w)/g);
+            for (const match of hexMatches) {
+                issues.push({
+                    id: `token-raw-hex-${index}-${match.index}`,
+                    category: 'tokens',
+                    severity: 'error',
+                    message: `Raw hex color value "${match[0]}" found. Use --ed-theme-color-* token`,
+                    file: filePath,
+                    line: index + 1,
+                    column: (match.index || 0) + 1,
+                    actual: match[0],
+                    autoFixable: false,
+                });
+            }
+            // Check for raw px values (not in calculations)
+            if (!line.includes('calc(') && !line.includes('//')) {
+                const pxMatches = line.matchAll(/:\s*(\d+)px\s*(?:;|!important)/g);
+                for (const match of pxMatches) {
+                    // Skip if it's a component value (like border-width: 2px)
+                    const isBorderWidth = line.includes('border-width');
+                    if (!isBorderWidth) {
+                        issues.push({
+                            id: `token-raw-px-${index}-${match.index}`,
+                            category: 'tokens',
+                            severity: 'error',
+                            message: `Raw pixel value "${match[0]}" for spacing/sizing. Use --ed-spacing-* token`,
+                            file: filePath,
+                            line: index + 1,
+                            column: (match.index || 0) + 1,
+                            actual: match[1],
+                            autoFixable: false,
+                        });
+                    }
+                }
+            }
+            // Check for raw font-family
+            if (line.includes('font-family') && !line.includes('var(--ed')) {
+                const fontMatch = line.match(/font-family\s*:\s*([^;]+)/);
+                if (fontMatch && !fontMatch[1].includes('inherit') && !fontMatch[1].includes('initial')) {
+                    issues.push({
+                        id: `token-raw-font-${index}`,
+                        category: 'tokens',
+                        severity: 'error',
+                        message: 'Raw font-family value found. Use --ed-typography-font-* token',
+                        file: filePath,
+                        line: index + 1,
+                        actual: fontMatch[1].trim(),
+                        autoFixable: false,
+                    });
+                }
+            }
+        });
+        return issues;
+    }
+    /**
+     * Validate that component code uses tier 2+ tokens, not tier 1 directly
+     */
+    validateTokenTier(filePath, line, tokenName, taxonomy) {
+        // Only enforce this if we're in a component directory (not in token definitions)
+        if (filePath.includes('/tokens/') || filePath.includes('/design-tokens/')) {
+            return null;
+        }
+        // Extract tier from token name: --ed-{tier}-...
+        // tier 1: --ed-color-*, --ed-spacing-*
+        // tier 2: --ed-theme-*, --ed-semantic-*
+        // tier 3: --ed-component-*
+        const isTier1 = tokenName.match(/--ed-(color|spacing|typography|shadow|border|motion|opacity)-/);
+        if (isTier1 && !filePath.includes('token-definitions')) {
+            return {
+                id: `token-tier-violation-${Date.now()}`,
+                category: 'tokens',
+                severity: 'warning',
+                message: `Component should not directly use tier 1 token "${tokenName}". Use tier 2 (--ed-theme-*) or tier 3 (--ed-component-*) instead`,
+                file: filePath,
+                line,
+                actual: tokenName,
+                expected: tokenName.replace(/--ed-(color|spacing)/, '--ed-theme-$1'),
+                autoFixable: false,
+            };
+        }
+        return null;
+    }
+    /**
+     * Validate that token usage matches its intent (e.g., don't use background token as text color)
+     */
+    validateIntentMatch(filePath, line, cssProperty, tokenName, taxonomy) {
+        // Token-category-mismatch check (#631): every color token has a
+        // subcategory (background / content / border) that maps 1:1 to a CSS
+        // property family. Crossing the boundary — e.g.
+        // `background: var(--ed-theme-color-content-subtle)` — looks subtle in
+        // one theme and wrong in another because the token tiers are tuned
+        // independently per category.
+        const tokenSubcategory = this.colorSubcategoryFromTokenName(tokenName);
+        const propertyFamily = this.colorPropertyFamily(cssProperty);
+        if (tokenSubcategory && propertyFamily && tokenSubcategory !== propertyFamily) {
+            const sibling = tokenName.replace(`color-${tokenSubcategory}-`, `color-${propertyFamily}-`);
+            const siblingExists = !!taxonomy.getToken?.(sibling);
+            const suggestionLine = siblingExists
+                ? `Did you mean \`${sibling}\`?`
+                : `Use a \`color-${propertyFamily}-*\` token here.`;
+            return {
+                id: `token-category-mismatch-${tokenName}-${cssProperty}-${line}`,
+                category: 'tokens',
+                severity: 'error',
+                message: `Token category mismatch: \`${cssProperty}\` is a ${propertyFamily} property but \`${tokenName}\` is a ${tokenSubcategory} token. ${suggestionLine}`,
+                file: filePath,
+                line,
+                actual: `${cssProperty}: var(${tokenName})`,
+                expected: siblingExists ? `${cssProperty}: var(${sibling})` : undefined,
+                autoFixable: siblingExists,
+                suggestion: siblingExists ? sibling : undefined,
+            };
+        }
+        return null;
+    }
+    /**
+     * Pull the color subcategory ("background" | "content" | "border") out of
+     * a token name like `--ed-theme-color-content-subtle`. Returns undefined
+     * for non-color tokens or color tokens that don't carry a subcategory
+     * segment in the name (definition-tier raw colors, etc.).
+     */
+    colorSubcategoryFromTokenName(tokenName) {
+        const m = tokenName.match(/--ed-(?:theme-)?color-(background|content|border)-/);
+        return m ? m[1] : undefined;
+    }
+    /**
+     * Bucket a CSS property name into one of the three color subcategory
+     * families. Returns undefined for properties that aren't color-bearing
+     * (we only enforce the rule on color properties; spacing, typography,
+     * etc. take other tokens entirely).
+     *
+     *   background-* / background-color  → "background"
+     *   color, fill, caret-color, accent-color → "content"
+     *   border-*-color / outline-*-color → "border"
+     */
+    colorPropertyFamily(property) {
+        if (/^background(-color)?$/.test(property))
+            return 'background';
+        if (/^(color|fill|caret-color|accent-color)$/.test(property))
+            return 'content';
+        if (/(^border|outline)([-a-z]*-)?color$/.test(property))
+            return 'border';
+        return undefined;
+    }
+    /**
+     * Check if a token is deprecated
+     */
+    checkDeprecation(filePath, line, tokenName, taxonomy) {
+        // Check taxonomy for deprecated tokens
+        const allTokens = taxonomy.getAll?.() || [];
+        const isDeprecated = allTokens.some((t) => t.name === tokenName && t.deprecated);
+        if (isDeprecated) {
+            return {
+                id: `token-deprecated-${Date.now()}`,
+                category: 'tokens',
+                severity: 'warning',
+                message: `Token "${tokenName}" is deprecated and should not be used`,
+                file: filePath,
+                line,
+                actual: tokenName,
+                autoFixable: false,
+            };
+        }
+        return null;
+    }
+    /**
+     * Check that tokens used in one theme exist in all themes.
+     *
+     * Only checks semantic/component tokens (--ed-theme-*), not definition-tier tokens.
+     * Strips comments before matching. Handles var() fallback values correctly
+     * (e.g. var(--ed-foo, none) extracts only --ed-foo).
+     */
+    async checkThemeCoverage(filePath, taxonomy) {
+        const issues = [];
+        let content = await readFile(filePath, 'utf-8');
+        // Strip block comments to avoid scanning JSDoc/documentation
+        content = content.replace(/\/\*[\s\S]*?\*\//g, '');
+        // Strip single-line comments
+        content = content.replace(/\/\/.*$/gm, '');
+        // Match var(--ed-...) and extract just the token name (before any comma fallback)
+        const tokenMatches = content.match(/var\(\s*(--ed-[^),\s]+)/g) || [];
+        const uniqueTokens = [...new Set(tokenMatches.map((m) => {
+                // Extract token name: "var(--ed-foo" → "--ed-foo"
+                const match = m.match(/var\(\s*(--ed-[^),\s]+)/);
+                return match ? match[1] : '';
+            }).filter(Boolean))];
+        // Only check theme coverage for semantic tokens (--ed-theme-*)
+        // Component-local custom properties (--ed-button-*) are defined in SCSS, not in themes
+        const themeTokens = uniqueTokens.filter((t) => t.startsWith('--ed-theme-'));
+        const allThemes = taxonomy.getThemes?.() || [];
+        if (allThemes.length === 0)
+            return issues;
+        for (const token of themeTokens) {
+            const missingThemes = [];
+            for (const theme of allThemes) {
+                const themeTokenList = taxonomy.getByTheme?.(theme) || [];
+                const hasToken = themeTokenList.some((t) => t.name === token);
+                if (!hasToken) {
+                    missingThemes.push(theme);
+                }
+            }
+            // Only flag if missing from ALL themes (likely a typo) or some themes (actual gap)
+            // If missing from all, it might be a valid component-level override — downgrade to warning
+            if (missingThemes.length > 0 && missingThemes.length < allThemes.length) {
+                issues.push({
+                    id: `token-coverage-${token}`,
+                    category: 'tokens',
+                    severity: 'warning',
+                    message: `Token "${token}" missing from ${missingThemes.length}/${allThemes.length} themes: ${missingThemes.join(', ')}`,
+                    file: filePath,
+                    actual: token,
+                    expected: `Token should exist in all themes`,
+                    autoFixable: false,
+                });
+            }
+        }
+        return issues;
+    }
+}
+//# sourceMappingURL=token-validator.js.map