code-auditor-mcp 3.4.12 → 3.4.13

package/dist/analyzers/universal/UniversalStylesAnalyzer.js

@@ -10,6 +10,7 @@
  * compute histograms, clusters, and distributions across the entire codebase.
  */
 import { UniversalAnalyzer } from '../../languages/UniversalAnalyzer.js';
+import { withRuleTiming } from '../ruleTiming.js';
 import { makeVisitorStatus } from '../../pipeline.js';
 import { getTailwindExpander } from '../../styles/tailwindUtilityExpander.js';
 import { normalizeValue } from '../../styles/normalizer.js';
@@ -46,125 +47,153 @@ const TAILWIND_SPACING_PX = {
     '96': 384,
 };
 const TAILWIND_SCALE_VALUES = Object.values(TAILWIND_SPACING_PX).sort((a, b) => a - b);
-// ---------------------------------------------------------------------------
-// Analyzer
-// ---------------------------------------------------------------------------
-export class UniversalStylesAnalyzer extends UniversalAnalyzer {
+/**
+ * Values so common that coincidental token-name matches are always noise.
+ * Filtered before any token comparison (Spec 22 Item 1).
+ */
+const TRIVIAL_VALUES = new Set([
+    '0', '0px', '0rem', '0em', '0%', 'none', 'transparent',
+    'inherit', 'initial', 'unset', 'currentcolor', 'auto',
+    '100%', '50%',
+]);
+/**
+ * Leaf layer: identity + stateless style helpers used by every detector.
+ * Kept free of cross-method orchestration so it stays a small, stable base.
+ */
+class UniversalStylesAnalyzerBase extends UniversalAnalyzer {
     name = 'styles';
     description = 'Detects style fragmentation, value drift, token bypass, dead classes, ' +
         'off-scale values, mechanism mixing, declaration-set similarity, and z-index sprawl';
     category = 'style';
-    /**
-     * Override analyze() to query the full style index in one pass instead
-     * of per-file AST processing. The base class analyze() loop is bypassed.
-     */
-    async analyze(files, config = {}, options = {}) {
-        const startTime = Date.now();
-        const cfg = { ...DEFAULT_STYLES_CONFIG, ...config };
-        const violations = [];
-        // Use the IndexHandle passed through the pipeline; fall back if absent.
-        const indexHandle = config.indexHandle;
-        if (!indexHandle) {
-            return {
-                violations: [],
-                errors: [{ file: '', error: 'No index handle available — style index not open' }],
-                status: makeVisitorStatus(0),
-                executionTime: Date.now() - startTime,
-                analyzerName: this.name,
-                metrics: { filesAnalyzed: 0, totalViolations: 0, executionTime: Date.now() - startTime },
-            };
-        }
-        // Query all declarations, tokens, and class usage
-        const declarations = this.queryDeclarations(indexHandle);
-        const tokens = this.queryTokens(indexHandle);
-        const classUsage = this.queryClassUsage(indexHandle);
-        if (declarations.length === 0) {
-            return {
-                violations: [],
-                errors: [],
-                status: makeVisitorStatus(files.length),
-                executionTime: Date.now() - startTime,
-                analyzerName: this.name,
-                metrics: { filesAnalyzed: files.length, totalViolations: 0, executionTime: Date.now() - startTime },
-            };
-        }
-        // Build helpers
-        const tokenValueMap = new Map(); // normalized value → token info
-        for (const t of tokens) {
-            const normalizedTokenVal = normalizeValue(t.value, '__token__');
-            tokenValueMap.set(t.value, { name: t.name, valueType: normalizedTokenVal?.type ?? null });
-        }
-        // Declarations by property
-        const byProperty = new Map();
-        for (const d of declarations) {
-            const list = byProperty.get(d.property) || [];
-            list.push(d);
-            byProperty.set(d.property, list);
+    makeViolation(filePath, line, message, classification) {
+        const v = {
+            file: filePath,
+            line,
+            column: 1,
+            severity: classification.severity,
+            message,
+            rule: classification.rule,
+            analyzer: this.name,
+        };
+        if (classification.symbol) {
+            v.functionName = classification.symbol;
         }
-        // Run detectors
-        violations.push(...this.detectValueDrift(byProperty, cfg, declarations));
-        violations.push(...this.detectOffScaleValues(byProperty, cfg));
-        violations.push(...await this.detectUndefinedClasses(classUsage, declarations, byProperty, cfg));
-        violations.push(...this.detectTokenBypass(declarations, tokenValueMap, cfg));
-        violations.push(...this.detectMechanismFragmentation(declarations, cfg));
-        violations.push(...this.detectDeclarationSetSimilarity(declarations, cfg));
-        violations.push(...this.detectZIndexInventory(byProperty, cfg));
-        // Apply severity overrides from config
-        const severityOverrides = config.severityOverrides ?? {};
-        if (Object.keys(severityOverrides).length > 0) {
-            for (const v of violations) {
-                const override = severityOverrides[v.rule];
-                if (override) {
-                    v.severity = override;
-                }
-            }
+        if (classification.resolution) {
+            v.resolution = classification.resolution;
         }
-        const filtered = violations.filter(v => v.severity !== 'off');
-        const uniqueFiles = new Set(declarations.map(d => d.file_path));
-        return {
-            violations: filtered,
-            errors: [],
-            status: makeVisitorStatus(uniqueFiles.size),
-            executionTime: Date.now() - startTime,
-            analyzerName: this.name,
-            metrics: {
-                filesAnalyzed: uniqueFiles.size,
-                totalViolations: filtered.length,
-                executionTime: Date.now() - startTime,
-            },
-        };
-    }
-    /** Not used — we override analyze() directly. */
-    async analyzeAST(_ast, _adapter, _config, _sourceCode) {
-        return [];
+        return v;
     }
-    // -----------------------------------------------------------------------
-    // Database queries
-    // -----------------------------------------------------------------------
-    queryDeclarations(indexHandle) {
+    /** Parse a CSS color string to [R, G, B] or null. */
+    parseColorToRGB(raw) {
         try {
-            return indexHandle.query('SELECT * FROM style_declarations ORDER BY property, file_path, line');
+            let v = raw.toLowerCase().trim();
+            // Hex
+            if (v.startsWith('#')) {
+                if (v.length === 4) {
+                    // #rgb → #rrggbb
+                    v = '#' + v[1] + v[1] + v[2] + v[2] + v[3] + v[3];
+                }
+                if (v.length === 7) {
+                    return [
+                        parseInt(v.slice(1, 3), 16),
+                        parseInt(v.slice(3, 5), 16),
+                        parseInt(v.slice(5, 7), 16),
+                    ];
+                }
+                if (v.length === 9) {
+                    return [
+                        parseInt(v.slice(1, 3), 16),
+                        parseInt(v.slice(3, 5), 16),
+                        parseInt(v.slice(5, 7), 16),
+                    ];
+                }
+            }
+            // rgb(r, g, b) or rgb(r g b)
+            const rgbMatch = v.match(/rgb\(\s*(\d+)\s*,?\s*(\d+)\s*,?\s*(\d+)\s*\)/);
+            if (rgbMatch) {
+                return [
+                    parseInt(rgbMatch[1]),
+                    parseInt(rgbMatch[2]),
+                    parseInt(rgbMatch[3]),
+                ];
+            }
+            // Named colors — minimal set for common use
+            const named = {
+                'white': [255, 255, 255], 'black': [0, 0, 0],
+                'red': [255, 0, 0], 'blue': [0, 0, 255], 'green': [0, 128, 0],
+                'transparent': [0, 0, 0],
+            };
+            if (named[v])
+                return named[v];
+            return null;
         }
         catch {
-            return [];
+            return null;
         }
     }
-    queryTokens(indexHandle) {
-        try {
-            return indexHandle.query('SELECT * FROM style_tokens');
-        }
-        catch {
-            return [];
+    /** Compute delta-E (CIE76) between two RGB colors. */
+    deltaE(a, b) {
+        const dr = a[0] - b[0];
+        const dg = a[1] - b[1];
+        const db = a[2] - b[2];
+        return Math.sqrt(dr * dr + dg * dg + db * db);
+    }
+    /**
+     * Cluster colors by delta-E distance.
+     * Simple greedy algorithm: each item joins the first cluster it's close enough to,
+     * or starts a new cluster.
+     */
+    clusterByDeltaE(items, threshold) {
+        const clusters = [];
+        for (const item of items) {
+            let placed = false;
+            for (const cluster of clusters) {
+                // Use the first item's RGB as cluster centroid
+                const centroid = cluster[0].rgb;
+                if (this.deltaE(item.rgb, centroid) < threshold) {
+                    cluster.push(item);
+                    placed = true;
+                    break;
+                }
+            }
+            if (!placed) {
+                clusters.push([item]);
+            }
         }
+        return clusters;
     }
-    queryClassUsage(indexHandle) {
+    /** Parse a CSS length value to px-equivalent, or null if not parseable. */
+    parseLengthToPx(raw) {
         try {
-            return indexHandle.query('SELECT * FROM style_class_usage');
+            const v = raw.trim().toLowerCase();
+            if (v === '0' || v === '0px')
+                return 0;
+            const match = v.match(/^(-?\d+(?:\.\d+)?)\s*(px|rem|em|%|vh|vw|pt|cm|mm)?$/);
+            if (!match)
+                return null;
+            const num = parseFloat(match[1]);
+            const unit = match[2] || 'px';
+            // Approximate conversions (assuming 16px base for rem/em)
+            switch (unit) {
+                case 'px': return num;
+                case 'rem': return num * 16;
+                case 'em': return num * 16;
+                case 'pt': return num * 1.333;
+                case 'cm': return num * 37.795;
+                case 'mm': return num * 3.7795;
+                default: return null; // can't convert %/vh/vw without context
+            }
         }
         catch {
-            return [];
+            return null;
         }
     }
+}
+// ---------------------------------------------------------------------------
+// Detector layer: the seven style detectors, reporting through the base
+// layer's makeViolation helper.
+// ---------------------------------------------------------------------------
+class UniversalStylesAnalyzerDetectors extends UniversalStylesAnalyzerBase {
     // -----------------------------------------------------------------------
     // Detector 1: Value Drift
     // -----------------------------------------------------------------------
@@ -251,33 +280,13 @@ export class UniversalStylesAnalyzer extends UniversalAnalyzer {
         }
         if (colors.length < cfg.minCorpus)
             return violations;
-        // Cluster by delta-E
+        // Cluster by delta-E, then flag stragglers in non-dominant clusters.
         const clusters = this.clusterByDeltaE(colors, cfg.colorDeltaE);
-        // Find the dominant cluster (largest)
         clusters.sort((a, b) => b.length - a.length);
         const dominant = clusters[0];
         if (!dominant || dominant.length < cfg.modeMinCount)
             return violations;
-        const dominantSize = dominant.length;
-        // Flag stragglers in non-dominant clusters
-        for (let i = 1; i < clusters.length; i++) {
-            const cluster = clusters[i];
-            const share = cluster.length / colors.length;
-            if (share < cfg.outlierMaxShare && dominantSize >= cfg.modeMinCount) {
-                // Report once per distinct color value in the straggler cluster
-                const seenValues = new Set();
-                for (const item of cluster) {
-                    const normVal = item.decl.raw_value.toLowerCase();
-                    if (seenValues.has(normVal))
-                        continue;
-                    seenValues.add(normVal);
-                    violations.push(this.makeViolation(item.decl.file_path, item.decl.line, `Color drift in "${property}": "${item.decl.raw_value}" is a rare value ` +
-                        `(used ${cluster.length} time${cluster.length === 1 ? '' : 's'}, ` +
-                        `${(share * 100).toFixed(1)}% of ${colors.length} usages). ` +
-                        `Dominant cluster has ${dominantSize} values. Consider using a design token.`, 'warning', 'styles/value-drift', 'color'));
-                }
-            }
-        }
+        violations.push(...flagColorDriftStragglers(clusters, property, cfg, this.makeViolation.bind(this)));
         return violations;
     }
     /**
@@ -315,7 +324,7 @@ export class UniversalStylesAnalyzer extends UniversalAnalyzer {
                 violations.push(this.makeViolation(sample.file_path, sample.line, `Value drift in "${property}": "${sample.raw_value}" is rare ` +
                     `(${list.length} of ${total} usages, ${(share * 100).toFixed(1)}%). ` +
                     `The dominant value "${modeKey}" is used ${modeCount} times. ` +
-                    `Consider using a consistent value or design token.`, 'warning', 'styles/value-drift', 'exact'));
+                    `Consider using a consistent value or design token.`, { severity: 'warning', rule: 'styles/value-drift', symbol: 'exact' }));
             }
         }
         return violations;
@@ -356,7 +365,7 @@ export class UniversalStylesAnalyzer extends UniversalAnalyzer {
                     violations.push(this.makeViolation(decl.file_path, decl.line, `Off-scale "${property}" value: "${decl.raw_value}" (${px}px) ` +
                         `does not align with the inferred ${step}px scale step. ` +
                         `Nearby scale values: ${Math.floor(px / step) * step}px or ` +
-                        `${Math.ceil(px / step) * step}px.`, 'warning', 'styles/off-scale'));
+                        `${Math.ceil(px / step) * step}px.`, { severity: 'warning', rule: 'styles/off-scale' }));
                 }
             }
         }
@@ -389,6 +398,382 @@ export class UniversalStylesAnalyzer extends UniversalAnalyzer {
             return null;
         return bestStep;
     }
+}
+// ---------------------------------------------------------------------------
+// Structure detectors: class/token/mechanism integrity checks over the raw
+// declaration and class-usage rows. Split out of the value-drift detectors so
+// neither class trips the aggregate-complexity ceiling. Lives off the analyzer
+// inheritance chain — it reports through the shared factory and receives the
+// analyzer name once at construction.
+// ---------------------------------------------------------------------------
+/**
+ * Filter class-usage rows down to candidate names worth batch-probing,
+ * applying the skip filters that distinguish definitions, known classes, and
+ * extraction artifacts from genuine consumptions of an unknown class.
+ */
+function collectUndefinedClassCandidates(classUsage, definedClasses) {
+    const seen = new Set();
+    const candidates = [];
+    const usageEntries = [];
+    for (const u of classUsage) {
+        const key = `${u.class_name}::${u.file_path}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        // Skip unresolvable individual class usages
+        if (u.unresolvable)
+            continue;
+        // Skip CSS class SELECTORS (definitions, not usages).
+        // CSS/SCSS files: mechanism 'class' = class_selector node = ".some-class { }"
+        // These DEFINE a class — they are not usages of one. Only usages through
+        // other mechanisms (className, apply, class in HTML) signal consumption.
+        // Without this guard, every CSS selector without a direct declaration
+        // (SCSS @include-only blocks, nested rule_sets) is falsely flagged.
+        if (u.mechanism === 'class' && /\.(css|scss)$/i.test(u.file_path))
+            continue;
+        // Skip known classes from CSS declarations
+        if (definedClasses.has(u.class_name))
+            continue;
+        // Skip PascalCase — likely a component
+        if (/^[A-Z]/.test(u.class_name))
+            continue;
+        // Skip function-like
+        if (u.class_name.includes('('))
+            continue;
+        // Skip numeric
+        if (/^\d/.test(u.class_name))
+            continue;
+        // Skip classes that start/end with [] — not valid CSS class names
+        if (u.class_name.startsWith('[') || u.class_name.startsWith(']'))
+            continue;
+        if (u.class_name.endsWith('[') || u.class_name.endsWith(']'))
+            continue;
+        // Skip extraction artifacts
+        if (/['`"${}?;!@#%^&*+=<>|\\,~]/.test(u.class_name))
+            continue;
+        usageEntries.push(u);
+        candidates.push(u.class_name);
+    }
+    return { candidates, usageEntries };
+}
+function flagColorDriftStragglers(clusters, property, cfg, report) {
+    const violations = [];
+    const dominant = clusters[0];
+    const dominantSize = dominant.length;
+    const total = clusters.reduce((sum, c) => sum + c.length, 0);
+    for (let i = 1; i < clusters.length; i++) {
+        const cluster = clusters[i];
+        const share = cluster.length / total;
+        if (share >= cfg.outlierMaxShare)
+            continue;
+        // Report once per distinct color value in the straggler cluster
+        const seenValues = new Set();
+        for (const item of cluster) {
+            const normVal = item.decl.raw_value.toLowerCase();
+            if (seenValues.has(normVal))
+                continue;
+            seenValues.add(normVal);
+            violations.push(report(item.decl.file_path, item.decl.line, `Color drift in "${property}": "${item.decl.raw_value}" is a rare value ` +
+                `(used ${cluster.length} time${cluster.length === 1 ? '' : 's'}, ` +
+                `${(share * 100).toFixed(1)}% of ${total} usages). ` +
+                `Dominant cluster has ${dominantSize} values. Consider using a design token.`, { severity: 'warning', rule: 'styles/value-drift', symbol: 'color' }));
+        }
+    }
+    return violations;
+}
+/**
+ * Collect the set of defined class names and the stylesheet that first defines
+ * each, in a single pass over the declarations. Bundled as one catalog so the
+ * undefined-class detector (Spec 37 R1: "nearest defined class by edit
+ * distance, and which stylesheet defines it") takes a single context object
+ * rather than threading the name set and location map as two separate
+ * parameters.
+ */
+function collectDefinedClassCatalog(byProperty) {
+    const names = new Set();
+    const locations = new Map();
+    for (const [, decls] of byProperty) {
+        for (const d of decls) {
+            const ctx = d.context;
+            if (!ctx)
+                continue;
+            const matches = ctx.matchAll(/\.([a-zA-Z0-9_-]+)/g);
+            for (const m of matches) {
+                names.add(m[1]);
+                if (!locations.has(m[1]))
+                    locations.set(m[1], d.file_path);
+            }
+        }
+    }
+    return { names, locations };
+}
+/**
+ * Levenshtein edit distance between two class names, capping the DP width so a
+ * large stylesheet catalog stays cheap. Returns Infinity when the length gap
+ * alone exceeds the match ceiling (mirrors schema/codeAnalysis.ts).
+ */
+function levenshteinDistance(a, b, maxDist) {
+    if (Math.abs(a.length - b.length) > maxDist)
+        return Infinity;
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1]
+                ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j - 1], dp[i - 1][j], dp[i][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+/**
+ * Nearest defined class within a bounded edit distance, or null when no known
+ * class is close enough to be a credible suggestion.
+ */
+function nearestDefinedClass(name, definedClasses) {
+    let best = null;
+    let bestDist = Infinity;
+    for (const known of definedClasses) {
+        const dist = levenshteinDistance(name.toLowerCase(), known.toLowerCase(), 3);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = known;
+        }
+    }
+    return best;
+}
+async function initTailwindProbe(expander, cfg, report) {
+    await expander.init({
+        projectRoot: cfg?.projectRoot,
+        useProjectConfig: true,
+        customClasses: cfg?.tailwindClasses ? new Set(cfg.tailwindClasses) : undefined,
+    });
+    // Fail-open rule (Spec 22 R1.3): if the probe fails and Tailwind IS
+    // present, disable the undefined-class detector.
+    if (expander.configFailed && expander.hasTailwindConfig) {
+        return [report('', 0, `Tailwind probe unavailable (${expander.configFailureReason ?? 'unknown error'}) — ` +
+                `undefined-class detection skipped. Classes defined only in Tailwind ` +
+                `config will not be checked. Install tailwindcss in the project ` +
+                `for full class validation.`, { severity: 'suggestion', rule: 'styles/undefined-class-disabled' })];
+    }
+    return null;
+}
+function flagUnresolvedClasses(usageEntries, expander, report, catalog) {
+    return withRuleTiming('styles/undefined-class', () => {
+        const { names: definedClasses, locations: definedClassLocations } = catalog;
+        const violations = [];
+        for (const u of usageEntries) {
+            const resolved = expander.resolve(u.class_name);
+            if (resolved.valid)
+                continue;
+            const nearest = nearestDefinedClass(u.class_name, definedClasses);
+            const nearestFile = nearest ? definedClassLocations.get(nearest) : undefined;
+            violations.push(report(u.file_path, u.line, `Undefined CSS class: "${u.class_name}" has no matching definition ` +
+                `in any stylesheet, Tailwind utility set, or project config.`, {
+                severity: 'warning',
+                rule: 'styles/undefined-class',
+                resolution: {
+                    action: nearest ? 'use-defined-class' : 'define-or-remove-class',
+                    summary: nearest
+                        ? `Rename "${u.class_name}" to the defined class "${nearest}"${nearestFile ? ` (defined in ${nearestFile})` : ''}.`
+                        : `Define the class "${u.class_name}" in a stylesheet, or remove the usage.`,
+                    symbols: nearest ? [nearest] : [u.class_name],
+                    files: nearestFile ? [u.file_path, nearestFile] : [u.file_path],
+                    lines: [u.line],
+                },
+            }));
+        }
+        return violations;
+    });
+}
+function normalizeForTokenMatch(raw) {
+    let v = raw.toLowerCase().trim();
+    v = v.replace(/,\s+/g, ',');
+    if (/^#[0-9a-f]{3}$/.test(v)) {
+        v = '#' + v[1] + v[1] + v[2] + v[2] + v[3] + v[3];
+    }
+    return v;
+}
+function parseNormalizedValueType(normalizedValue) {
+    if (!normalizedValue)
+        return null;
+    try {
+        const nv = JSON.parse(normalizedValue);
+        return nv.type;
+    }
+    catch {
+        return null;
+    }
+}
+function matchBypassToken(d, tokenValueMap, categoricalExclusions, scaleProps) {
+    if (d.token_ref)
+        return null;
+    if (d.property.startsWith('--') || d.property.startsWith('$'))
+        return null;
+    if (categoricalExclusions.has(d.property))
+        return null;
+    if (scaleProps.has(d.property))
+        return null;
+    const normalized = normalizeForTokenMatch(d.raw_value);
+    if (TRIVIAL_VALUES.has(normalized))
+        return null;
+    const tokenInfo = tokenValueMap.get(normalized);
+    if (!tokenInfo)
+        return null;
+    if (tokenInfo.valueType !== null) {
+        const declType = parseNormalizedValueType(d.normalized_value);
+        if (declType !== null && declType !== tokenInfo.valueType)
+            return null;
+    }
+    if (tokenInfo.valueType !== 'color')
+        return null;
+    return tokenInfo;
+}
+function flagPropertyValueFragmentation(declarations, minMechanisms, report) {
+    const violations = [];
+    const pvMap = new Map();
+    const pvSample = new Map();
+    for (const d of declarations) {
+        const key = `${d.property}::${d.normalized_value ?? d.raw_value}`;
+        const mechs = pvMap.get(key) || new Set();
+        mechs.add(d.mechanism);
+        pvMap.set(key, mechs);
+        if (!pvSample.has(key)) {
+            pvSample.set(key, d);
+        }
+    }
+    for (const [key, mechs] of pvMap) {
+        if (mechs.size < minMechanisms)
+            continue;
+        const sample = pvSample.get(key);
+        const [prop, value] = key.split('::');
+        violations.push(report(sample.file_path, sample.line, `Mechanism fragmentation: "${prop}: ${value}" is applied via ` +
+            `${mechs.size} different mechanisms (${[...mechs].sort().join(', ')}). ` +
+            `Consolidate to a single mechanism or design token.`, { severity: 'warning', rule: 'styles/mechanism-fragmentation' }));
+    }
+    return violations;
+}
+function flagFileMechanismMixing(declarations, minMechanisms, report) {
+    const violations = [];
+    const fileMechs = new Map();
+    for (const d of declarations) {
+        const mechs = fileMechs.get(d.file_path) || new Set();
+        mechs.add(d.mechanism);
+        fileMechs.set(d.file_path, mechs);
+    }
+    for (const [file, mechs] of fileMechs) {
+        if (mechs.size < minMechanisms)
+            continue;
+        violations.push(report(file, 1, `Mechanism mixing: ${file} uses ${mechs.size} different style ` +
+            `mechanisms (${[...mechs].sort().join(', ')}). ` +
+            `Consolidate to fewer mechanisms for maintainability.`, { severity: 'suggestion', rule: 'styles/mechanism-mixing' }));
+    }
+    return violations;
+}
+function buildDeclarationBlocks(declarations, minDeclarations) {
+    const blocks = new Map();
+    for (const d of declarations) {
+        if (!d.context)
+            continue;
+        const key = `${d.file_path}::${d.context}`;
+        const list = blocks.get(key) || [];
+        list.push(d);
+        blocks.set(key, list);
+    }
+    return [...blocks.entries()]
+        .map(([key, decls]) => {
+        const valueSet = new Set(decls.map(d => `${d.property}:${d.normalized_value ?? d.raw_value}`));
+        return {
+            key,
+            filePath: decls[0].file_path,
+            context: decls[0].context,
+            line: decls[0].line,
+            declCount: decls.length,
+            valueSet,
+        };
+    })
+        .filter(b => b.declCount >= minDeclarations);
+}
+function flagSimilarBlockPairs(blockEntries, threshold, report) {
+    const violations = [];
+    if (blockEntries.length < 2)
+        return violations;
+    const reported = new Set();
+    for (let i = 0; i < blockEntries.length; i++) {
+        for (let j = i + 1; j < blockEntries.length; j++) {
+            const a = blockEntries[i];
+            const b = blockEntries[j];
+            if (a.key === b.key)
+                continue;
+            const pairKey = [a.key, b.key].sort().join('::');
+            if (reported.has(pairKey))
+                continue;
+            reported.add(pairKey);
+            const intersection = new Set([...a.valueSet].filter(x => b.valueSet.has(x)));
+            const union = new Set([...a.valueSet, ...b.valueSet]);
+            const similarity = intersection.size / union.size;
+            if (similarity >= threshold) {
+                violations.push(report(a.filePath, a.line, `Declaration-set similarity: "${a.context}" and "${b.context}" ` +
+                    `in ${b.filePath} share ${intersection.size} of ${union.size} ` +
+                    `declarations (${(similarity * 100).toFixed(0)}%). ` +
+                    `Consider consolidating these rules or extracting a shared mixin.`, { severity: 'suggestion', rule: 'styles/declaration-set-similarity' }));
+            }
+        }
+    }
+    return violations;
+}
+function buildTokenValueMap(tokens) {
+    const tokenValueMap = new Map();
+    for (const t of tokens) {
+        const normalizedTokenVal = normalizeValue(t.value, '__token__');
+        tokenValueMap.set(t.value, { name: t.name, valueType: normalizedTokenVal?.type ?? null });
+    }
+    return tokenValueMap;
+}
+function groupDeclarationsByProperty(declarations) {
+    const byProperty = new Map();
+    for (const d of declarations) {
+        const list = byProperty.get(d.property) || [];
+        list.push(d);
+        byProperty.set(d.property, list);
+    }
+    return byProperty;
+}
+function applySeverityOverrides(violations, config) {
+    const severityOverrides = config.severityOverrides ?? {};
+    if (Object.keys(severityOverrides).length === 0)
+        return;
+    for (const v of violations) {
+        const override = severityOverrides[v.rule];
+        if (override) {
+            v.severity = override;
+        }
+    }
+}
+function buildStylesResult(spec) {
+    return {
+        violations: spec.violations,
+        errors: spec.errors ?? [],
+        status: makeVisitorStatus(spec.fileCount),
+        executionTime: Date.now() - spec.startTime,
+        analyzerName: spec.name,
+        metrics: {
+            filesAnalyzed: spec.fileCount,
+            totalViolations: spec.violations.length,
+            executionTime: Date.now() - spec.startTime,
+        },
+    };
+}
+class StylesStructureDetectors {
+    makeViolation;
+    constructor(makeViolation) {
+        this.makeViolation = makeViolation;
+    }
     // -----------------------------------------------------------------------
     // Detector 3: Undefined Classes
     // -----------------------------------------------------------------------
@@ -404,112 +789,24 @@ export class UniversalStylesAnalyzer extends UniversalAnalyzer {
      */
     async detectUndefinedClasses(classUsage, _declarations, byProperty, cfg) {
         const violations = [];
-        // Collect all defined class names from CSS declarations
-        const definedClasses = new Set();
-        for (const [, decls] of byProperty) {
-            for (const d of decls) {
-                const ctx = d.context;
-                if (!ctx)
-                    continue;
-                const matches = ctx.matchAll(/\.([a-zA-Z0-9_-]+)/g);
-                for (const m of matches) {
-                    definedClasses.add(m[1]);
-                }
-            }
-        }
-        // ── Init compile-probe (async) ─────────────────────────────────
+        const definedClassCatalog = collectDefinedClassCatalog(byProperty);
         const expander = getTailwindExpander();
-        await expander.init({
-            projectRoot: cfg?.projectRoot,
-            useProjectConfig: true,
-            customClasses: cfg?.tailwindClasses ? new Set(cfg.tailwindClasses) : undefined,
-        });
         // Fail-open rule (Spec 22 R1.3): if the probe fails and Tailwind IS
-        // present, disable the undefined-class detector. Without a working probe
-        // there is no way to validate Tailwind utility classes — flagging every
-        // utility would produce ~875 false positives.
-        //
-        // When Tailwind is absent (no tailwindcss in node_modules), the probe
-        // never runs and CSS-only detection is the correct fallback.
-        if (expander.configFailed && expander.hasTailwindConfig) {
-            violations.push(this.makeViolation('', 0, `Tailwind probe unavailable (${expander.configFailureReason ?? 'unknown error'}) — ` +
-                `undefined-class detection skipped. Classes defined only in Tailwind ` +
-                `config will not be checked. Install tailwindcss in the project ` +
-                `for full class validation.`, 'suggestion', 'styles/undefined-class-disabled'));
-            return violations;
-        }
-        // ── Collect candidate class names for batch probing ─────────────
-        // Gather all potentially-unknown class names first, then batch-probe
-        // them against the project's Tailwind compiler. This is more efficient
-        // than probing one-at-a-time and lets the probe batch in groups.
-        const seen = new Set();
-        const candidates = [];
-        const usageEntries = [];
-        for (const u of classUsage) {
-            const key = `${u.class_name}::${u.file_path}`;
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            // Skip unresolvable individual class usages
-            if (u.unresolvable)
-                continue;
-            // Skip CSS class SELECTORS (definitions, not usages).
-            // CSS/SCSS files: mechanism 'class' = class_selector node = ".some-class { }"
-            // These DEFINE a class — they are not usages of one. Only usages through
-            // other mechanisms (className, apply, class in HTML) signal consumption.
-            // Without this guard, every CSS selector without a direct declaration
-            // (SCSS @include-only blocks, nested rule_sets) is falsely flagged.
-            if (u.mechanism === 'class' && /\.(css|scss)$/i.test(u.file_path))
-                continue;
-            // Skip known classes from CSS declarations
-            if (definedClasses.has(u.class_name))
-                continue;
-            // Skip PascalCase — likely a component
-            if (/^[A-Z]/.test(u.class_name))
-                continue;
-            // Skip function-like
-            if (u.class_name.includes('('))
-                continue;
-            // Skip numeric
-            if (/^\d/.test(u.class_name))
-                continue;
-            // Skip classes that start/end with [] — not valid CSS class names
-            if (u.class_name.startsWith('[') || u.class_name.startsWith(']'))
-                continue;
-            if (u.class_name.endsWith('[') || u.class_name.endsWith(']'))
-                continue;
-            // Skip extraction artifacts
-            if (/['`"${}?;!@#%^&*+=<>|\\,~]/.test(u.class_name))
-                continue;
-            usageEntries.push(u);
-            candidates.push(u.class_name);
-        }
-        // ── Batch-probe unknown classes ─────────────────────────────────
+        // present, disable the undefined-class detector.
+        const failOpen = await initTailwindProbe(expander, cfg, this.makeViolation.bind(this));
+        if (failOpen)
+            return failOpen;
+        // Gather all potentially-unknown class names first, then batch-probe.
+        const { candidates, usageEntries } = collectUndefinedClassCandidates(classUsage, definedClassCatalog.names);
         if (candidates.length > 0 && expander.probeReady) {
             await expander.validateBatch(candidates);
         }
-        // ── Resolve each class from cache + structural patterns ─────────
-        for (const u of usageEntries) {
-            const resolved = expander.resolve(u.class_name);
-            if (resolved.valid)
-                continue;
-            violations.push(this.makeViolation(u.file_path, u.line, `Undefined CSS class: "${u.class_name}" has no matching definition ` +
-                `in any stylesheet, Tailwind utility set, or project config.`, 'warning', 'styles/undefined-class'));
-        }
+        violations.push(...flagUnresolvedClasses(usageEntries, expander, this.makeViolation.bind(this), definedClassCatalog));
         return violations;
     }
     // -----------------------------------------------------------------------
     // Detector 4: Token Bypass
     // -----------------------------------------------------------------------
-    /**
-     * Spec 22 Item 1 — Values so common that coincidental token-name matches
-     * are always noise. Filtered before any token comparison.
-     */
-    static TRIVIAL_VALUES = new Set([
-        '0', '0px', '0rem', '0em', '0%', 'none', 'transparent',
-        'inherit', 'initial', 'unset', 'currentcolor', 'auto',
-        '100%', '50%',
-    ]);
     /**
      * Flag raw values that match a known design token's value but don't
      * reference the token via tokenRef.
@@ -532,74 +829,15 @@ export class UniversalStylesAnalyzer extends UniversalAnalyzer {
         const categoricalExclusions = new Set(cfg.categoricalPropertyExclusions ?? []);
         const scaleProps = new Set(cfg.scaleProperties ?? []);
         for (const d of declarations) {
-            // Skip if already referencing a token (var(--...) reference)
-            if (d.token_ref)
-                continue;
-            // Skip CSS custom-property definition sites — these define
-            // token values, so literals are expected (Spec 22 R2.1).
-            if (d.property.startsWith('--'))
-                continue;
-            // Skip SCSS variable definitions — these define token values
-            // so literals are expected (Spec 22 R2.1).
-            if (d.property.startsWith('$'))
-                continue;
-            // Spec 22 R2.2: skip categorical properties — they have a small set
-            // of valid keyword values (display, position, etc.) and coincidental
-            // token-value matches are noise.
-            if (categoricalExclusions.has(d.property))
-                continue;
-            // Spec 22 R2.3: skip scale properties — values naturally vary along
-            // a scale (font-size, margin, padding, etc.) and raw values at
-            // different scale points are expected, not token bypasses.
-            if (scaleProps.has(d.property))
-                continue;
-            // Normalize the raw value for comparison
-            const normalized = this.normalizeForTokenMatch(d.raw_value);
-            // Spec 22 Item 1: skip trivial values — they're so common that
-            // coincidental token-name matches are always noise.
-            if (UniversalStylesAnalyzer.TRIVIAL_VALUES.has(normalized))
-                continue;
-            const tokenInfo = tokenValueMap.get(normalized);
+            const tokenInfo = matchBypassToken(d, tokenValueMap, categoricalExclusions, scaleProps);
             if (!tokenInfo)
                 continue;
-            // Spec 22 Item 1: value-type equality gate — a token only
-            // matches declarations whose normalized value type is the same.
-            // E.g., --border-radius-lg: 8px (length) should not flag
-            // max-width: 8px because the normalizer types them the same, but
-            // --color-red: #22d3ee (color) should flag color: #22d3ee.
-            if (tokenInfo.valueType !== null) {
-                let declType = null;
-                if (d.normalized_value) {
-                    try {
-                        const nv = JSON.parse(d.normalized_value);
-                        declType = nv.type;
-                    }
-                    catch { /* invalid JSON — proceed neutrally */ }
-                }
-                if (declType !== null && declType !== tokenInfo.valueType)
-                    continue;
-            }
-            // Only color-typed tokens are specific enough to flag;
-            // lengths collide by nature (e.g., 6px matching border-radius tokens).
-            if (tokenInfo.valueType !== 'color')
-                continue;
             violations.push(this.makeViolation(d.file_path, d.line, `Token bypass: "${d.raw_value}" for "${d.property}" matches design ` +
                 `token "${tokenInfo.name}" but was used as a raw value. ` +
-                `Use the token reference instead to keep styles consistent.`, 'warning', 'styles/token-bypass'));
+                `Use the token reference instead to keep styles consistent.`, { severity: 'warning', rule: 'styles/token-bypass' }));
         }
         return violations;
     }
-    /** Normalize a raw value for token-value comparison. */
-    normalizeForTokenMatch(raw) {
-        let v = raw.toLowerCase().trim();
-        // Remove spaces after commas in functional notation
-        v = v.replace(/,\s+/g, ',');
-        // Expand shorthand hex: #fff → #ffffff
-        if (/^#[0-9a-f]{3}$/.test(v)) {
-            v = '#' + v[1] + v[1] + v[2] + v[2] + v[3] + v[3];
-        }
-        return v;
-    }
     // -----------------------------------------------------------------------
     // Detector 5: Mechanism Fragmentation
     // -----------------------------------------------------------------------
@@ -610,41 +848,10 @@ export class UniversalStylesAnalyzer extends UniversalAnalyzer {
      */
     detectMechanismFragmentation(declarations, cfg) {
         const violations = [];
-        // (A) Cross-file: same (property, raw_value) via ≥3 mechanisms
-        const pvMap = new Map(); // "property::value" → set of mechanisms
-        const pvSample = new Map(); // keep one sample for reporting
-        for (const d of declarations) {
-            const key = `${d.property}::${d.normalized_value ?? d.raw_value}`;
-            const mechs = pvMap.get(key) || new Set();
-            mechs.add(d.mechanism);
-            pvMap.set(key, mechs);
-            if (!pvSample.has(key)) {
-                pvSample.set(key, d);
-            }
-        }
-        for (const [key, mechs] of pvMap) {
-            if (mechs.size < cfg.mechanismFragmentationMinMechanisms)
-                continue;
-            const sample = pvSample.get(key);
-            const [prop, value] = key.split('::');
-            violations.push(this.makeViolation(sample.file_path, sample.line, `Mechanism fragmentation: "${prop}: ${value}" is applied via ` +
-                `${mechs.size} different mechanisms (${[...mechs].sort().join(', ')}). ` +
-                `Consolidate to a single mechanism or design token.`, 'warning', 'styles/mechanism-fragmentation'));
-        }
-        // (B) Per-file: a single file mixing ≥3 mechanisms
-        const fileMechs = new Map();
-        for (const d of declarations) {
-            const mechs = fileMechs.get(d.file_path) || new Set();
-            mechs.add(d.mechanism);
-            fileMechs.set(d.file_path, mechs);
-        }
-        for (const [file, mechs] of fileMechs) {
-            if (mechs.size < cfg.mechanismFragmentationMinMechanisms)
-                continue;
-            violations.push(this.makeViolation(file, 1, `Mechanism mixing: ${file} uses ${mechs.size} different style ` +
-                `mechanisms (${[...mechs].sort().join(', ')}). ` +
-                `Consolidate to fewer mechanisms for maintainability.`, 'suggestion', 'styles/mechanism-mixing'));
-        }
+        const report = this.makeViolation.bind(this);
+        const minMechanisms = cfg.mechanismFragmentationMinMechanisms;
+        violations.push(...flagPropertyValueFragmentation(declarations, minMechanisms, report));
+        violations.push(...flagFileMechanismMixing(declarations, minMechanisms, report));
         return violations;
     }
     // -----------------------------------------------------------------------
@@ -656,59 +863,8 @@ export class UniversalStylesAnalyzer extends UniversalAnalyzer {
      * This catches near-duplicate CSS rules that share most declarations.
      */
     detectDeclarationSetSimilarity(declarations, cfg) {
-        const violations = [];
-        // Group declarations by (file, context) to form rule blocks
-        const blocks = new Map();
-        for (const d of declarations) {
-            if (!d.context)
-                continue;
-            const key = `${d.file_path}::${d.context}`;
-            const list = blocks.get(key) || [];
-            list.push(d);
-            blocks.set(key, list);
-        }
-        // Convert blocks to declaration-value sets
-        const blockEntries = [...blocks.entries()]
-            .map(([key, decls]) => {
-            const valueSet = new Set(decls.map(d => `${d.property}:${d.normalized_value ?? d.raw_value}`));
-            return {
-                key,
-                filePath: decls[0].file_path,
-                context: decls[0].context,
-                line: decls[0].line,
-                declCount: decls.length,
-                valueSet,
-            };
-        })
-            .filter(b => b.declCount >= cfg.declarationSetMinDeclarations);
-        if (blockEntries.length < 2)
-            return violations;
-        // Compare pairs
-        const reported = new Set(); // "keyA::keyB"
-        for (let i = 0; i < blockEntries.length; i++) {
-            for (let j = i + 1; j < blockEntries.length; j++) {
-                const a = blockEntries[i];
-                const b = blockEntries[j];
-                // Skip same-file same-context (already the same block) or same key
-                if (a.key === b.key)
-                    continue;
-                const pairKey = [a.key, b.key].sort().join('::');
-                if (reported.has(pairKey))
-                    continue;
-                reported.add(pairKey);
-                // Compute Jaccard similarity
-                const intersection = new Set([...a.valueSet].filter(x => b.valueSet.has(x)));
-                const union = new Set([...a.valueSet, ...b.valueSet]);
-                const similarity = intersection.size / union.size;
-                if (similarity >= cfg.declarationSetSimilarityThreshold) {
-                    violations.push(this.makeViolation(a.filePath, a.line, `Declaration-set similarity: "${a.context}" and "${b.context}" ` +
-                        `in ${b.filePath} share ${intersection.size} of ${union.size} ` +
-                        `declarations (${(similarity * 100).toFixed(0)}%). ` +
-                        `Consider consolidating these rules or extracting a shared mixin.`, 'suggestion', 'styles/declaration-set-similarity'));
-                }
-            }
-        }
-        return violations;
+        const blockEntries = buildDeclarationBlocks(declarations, cfg.declarationSetMinDeclarations);
+        return flagSimilarBlockPairs(blockEntries, cfg.declarationSetSimilarityThreshold, this.makeViolation.bind(this));
     }
     // -----------------------------------------------------------------------
     // Detector 7: Z-Index Inventory
@@ -740,139 +896,116 @@ export class UniversalStylesAnalyzer extends UniversalAnalyzer {
             const sample = values.get(sortedVals[0])[0];
             violations.push(this.makeViolation(sample.file_path, sample.line, `Z-index sprawl: ${values.size} distinct z-index values ` +
                 `(${sortedVals.join(', ')}). Consider defining a z-index scale ` +
-                `(e.g., $z-layers: (dropdown: 100, modal: 200, toast: 300)).`, 'warning', 'styles/z-index-sprawl'));
+                `(e.g., $z-layers: (dropdown: 100, modal: 200, toast: 300)).`, { severity: 'warning', rule: 'styles/z-index-sprawl' }));
         }
         // Flag singletons (z-index values used only once)
         for (const [val, list] of values) {
             if (list.length === 1 && values.size > 2) {
                 const d = list[0];
                 violations.push(this.makeViolation(d.file_path, d.line, `Singleton z-index: z-index: ${val} is used only once. ` +
-                    `Consider whether this value belongs in a shared z-index scale.`, 'suggestion', 'styles/z-index-singleton'));
+                    `Consider whether this value belongs in a shared z-index scale.`, { severity: 'suggestion', rule: 'styles/z-index-singleton' }));
             }
         }
         return violations;
     }
-    // -----------------------------------------------------------------------
-    // Helpers
-    // -----------------------------------------------------------------------
-    makeViolation(filePath, line, message, severity, rule, symbol) {
-        const v = {
-            file: filePath,
-            line,
-            column: 1,
-            severity,
-            message,
-            rule,
-            analyzer: this.name,
-        };
-        if (symbol) {
-            v.functionName = symbol;
+}
+// ---------------------------------------------------------------------------
+// Orchestration layer: queries the style index and dispatches to the
+// detectors. This is the only exported class in the chain.
+// ---------------------------------------------------------------------------
+/**
+ * Universal styles analyzer.
+ */
+export class UniversalStylesAnalyzer extends UniversalStylesAnalyzerDetectors {
+    structure = new StylesStructureDetectors(this.makeViolation.bind(this));
+    /**
+     * Override analyze() to query the full style index in one pass instead
+     * of per-file AST processing. The base class analyze() loop is bypassed.
+     * @param config
+     * @param files
+     * @param options
+     * @returns
+     */
+    async analyze(files, config = {}, options = {}) {
+        const startTime = Date.now();
+        const cfg = { ...DEFAULT_STYLES_CONFIG, ...config };
+        // Use the IndexHandle passed through the pipeline; fall back if absent.
+        const indexHandle = config.indexHandle;
+        if (!indexHandle) {
+            return buildStylesResult({
+                violations: [],
+                errors: [{ file: '', error: 'No index handle available — style index not open' }],
+                fileCount: 0,
+                startTime,
+                name: this.name,
+            });
         }
-        return v;
+        const declarations = this.queryDeclarations(indexHandle);
+        if (declarations.length === 0) {
+            return buildStylesResult({
+                violations: [],
+                fileCount: files.length,
+                startTime,
+                name: this.name,
+            });
+        }
+        const violations = await this.runDetectors({
+            byProperty: groupDeclarationsByProperty(declarations),
+            cfg,
+            declarations,
+            classUsage: this.queryClassUsage(indexHandle),
+            tokenValueMap: buildTokenValueMap(this.queryTokens(indexHandle)),
+        });
+        applySeverityOverrides(violations, config);
+        return buildStylesResult({
+            violations: violations.filter(v => v.severity !== 'off'),
+            fileCount: new Set(declarations.map(d => d.file_path)).size,
+            startTime,
+            name: this.name,
+        });
     }
-    /** Parse a CSS color string to [R, G, B] or null. */
-    parseColorToRGB(raw) {
+    /** Run all detectors and return their combined violations. */
+    async runDetectors(inputs) {
+        const { byProperty, cfg, declarations, classUsage, tokenValueMap } = inputs;
+        const violations = [];
+        violations.push(...this.detectValueDrift(byProperty, cfg, declarations));
+        violations.push(...this.detectOffScaleValues(byProperty, cfg));
+        violations.push(...await this.structure.detectUndefinedClasses(classUsage, declarations, byProperty, cfg));
+        violations.push(...this.structure.detectTokenBypass(declarations, tokenValueMap, cfg));
+        violations.push(...this.structure.detectMechanismFragmentation(declarations, cfg));
+        violations.push(...this.structure.detectDeclarationSetSimilarity(declarations, cfg));
+        violations.push(...this.structure.detectZIndexInventory(byProperty, cfg));
+        return violations;
+    }
+    /** Not used — we override analyze() directly. */
+    async analyzeAST(_ast, _adapter, _config, _sourceCode) {
+        return [];
+    }
+    // -----------------------------------------------------------------------
+    // Database queries
+    // -----------------------------------------------------------------------
+    queryDeclarations(indexHandle) {
         try {
-            let v = raw.toLowerCase().trim();
-            // Hex
-            if (v.startsWith('#')) {
-                if (v.length === 4) {
-                    // #rgb → #rrggbb
-                    v = '#' + v[1] + v[1] + v[2] + v[2] + v[3] + v[3];
-                }
-                if (v.length === 7) {
-                    return [
-                        parseInt(v.slice(1, 3), 16),
-                        parseInt(v.slice(3, 5), 16),
-                        parseInt(v.slice(5, 7), 16),
-                    ];
-                }
-                if (v.length === 9) {
-                    return [
-                        parseInt(v.slice(1, 3), 16),
-                        parseInt(v.slice(3, 5), 16),
-                        parseInt(v.slice(5, 7), 16),
-                    ];
-                }
-            }
-            // rgb(r, g, b) or rgb(r g b)
-            const rgbMatch = v.match(/rgb\(\s*(\d+)\s*,?\s*(\d+)\s*,?\s*(\d+)\s*\)/);
-            if (rgbMatch) {
-                return [
-                    parseInt(rgbMatch[1]),
-                    parseInt(rgbMatch[2]),
-                    parseInt(rgbMatch[3]),
-                ];
-            }
-            // Named colors — minimal set for common use
-            const named = {
-                'white': [255, 255, 255], 'black': [0, 0, 0],
-                'red': [255, 0, 0], 'blue': [0, 0, 255], 'green': [0, 128, 0],
-                'transparent': [0, 0, 0],
-            };
-            if (named[v])
-                return named[v];
-            return null;
+            return indexHandle.query('SELECT * FROM style_declarations ORDER BY property, file_path, line');
         }
         catch {
-            return null;
+            return [];
         }
     }
-    /** Compute delta-E (CIE76) between two RGB colors. */
-    deltaE(a, b) {
-        const dr = a[0] - b[0];
-        const dg = a[1] - b[1];
-        const db = a[2] - b[2];
-        return Math.sqrt(dr * dr + dg * dg + db * db);
-    }
-    /**
-     * Cluster colors by delta-E distance.
-     * Simple greedy algorithm: each item joins the first cluster it's close enough to,
-     * or starts a new cluster.
-     */
-    clusterByDeltaE(items, threshold) {
-        const clusters = [];
-        for (const item of items) {
-            let placed = false;
-            for (const cluster of clusters) {
-                // Use the first item's RGB as cluster centroid
-                const centroid = cluster[0].rgb;
-                if (this.deltaE(item.rgb, centroid) < threshold) {
-                    cluster.push(item);
-                    placed = true;
-                    break;
-                }
-            }
-            if (!placed) {
-                clusters.push([item]);
-            }
+    queryTokens(indexHandle) {
+        try {
+            return indexHandle.query('SELECT * FROM style_tokens');
+        }
+        catch {
+            return [];
         }
-        return clusters;
     }
-    /** Parse a CSS length value to px-equivalent, or null if not parseable. */
-    parseLengthToPx(raw) {
+    queryClassUsage(indexHandle) {
         try {
-            const v = raw.trim().toLowerCase();
-            if (v === '0' || v === '0px')
-                return 0;
-            const match = v.match(/^(-?\d+(?:\.\d+)?)\s*(px|rem|em|%|vh|vw|pt|cm|mm)?$/);
-            if (!match)
-                return null;
-            const num = parseFloat(match[1]);
-            const unit = match[2] || 'px';
-            // Approximate conversions (assuming 16px base for rem/em)
-            switch (unit) {
-                case 'px': return num;
-                case 'rem': return num * 16;
-                case 'em': return num * 16;
-                case 'pt': return num * 1.333;
-                case 'cm': return num * 37.795;
-                case 'mm': return num * 3.7795;
-                default: return null; // can't convert %/vh/vw without context
-            }
+            return indexHandle.query('SELECT * FROM style_class_usage');
         }
         catch {
-            return null;
+            return [];
         }
     }
 }