@buoy-design/core 0.1.0 → 0.1.1

package/dist/analysis/semantic-diff.js

@@ -1,39 +1,173 @@
-import { createDriftId, normalizeComponentName, normalizeTokenName, tokensMatch, } from '../models/index.js';
+import { createDriftId, normalizeComponentName, normalizeTokenName, tokensMatch, } from "../models/index.js";
+import { TokenSuggestionService, } from "./token-suggestions.js";
+import { stringSimilarity as calcStringSimilarity } from "./string-utils.js";
+import { MATCHING_CONFIG, NAMING_CONFIG, getOutlierThreshold, } from "./config.js";
+/**
+ * Semantic suffixes that represent legitimate separate components.
+ * Components with these suffixes are NOT duplicates of their base component.
+ * e.g., Button vs ButtonGroup are distinct components, not duplicates.
+ */
+const SEMANTIC_COMPONENT_SUFFIXES = [
+    // Compound component patterns
+    "group",
+    "list",
+    "item",
+    "items",
+    "container",
+    "wrapper",
+    "provider",
+    "context",
+    // Layout parts
+    "header",
+    "footer",
+    "body",
+    "content",
+    "section",
+    "sidebar",
+    "panel",
+    // Specific UI patterns
+    "trigger",
+    "target",
+    "overlay",
+    "portal",
+    "root",
+    "slot",
+    "action",
+    "actions",
+    "icon",
+    "label",
+    "text",
+    "title",
+    "description",
+    "separator",
+    "divider",
+    // Size/state variants that are distinct components
+    "small",
+    "large",
+    "mini",
+    "skeleton",
+    "placeholder",
+    "loading",
+    "error",
+    "empty",
+    // Form-related
+    "input",
+    "field",
+    "control",
+    "message",
+    "helper",
+    "hint",
+    // Navigation
+    "link",
+    "menu",
+    "submenu",
+    "tab",
+    "tabs",
+    // Data display
+    "cell",
+    "row",
+    "column",
+    "columns",
+    "head",
+    "view",
+];
+/**
+ * Version/status suffixes that indicate potential duplicates.
+ * Components with ONLY these suffixes are likely duplicates.
+ * e.g., Button vs ButtonNew, Card vs CardLegacy
+ */
+const VERSION_SUFFIXES_PATTERN = /(New|Old|V\d+|Legacy|Updated|Deprecated|Beta|Alpha|Experimental|Next|Previous|Original|Backup|Copy|Clone|Alt|Alternative|Temp|Temporary|WIP|Draft)$/i;
 export class SemanticDiffEngine {
+    // Caches for O(1) lookups instead of repeated computations
+    nameCache = new Map();
+    componentMetadataCache = new Map();
+    // Delegated services
+    tokenSuggestionService = new TokenSuggestionService();
+    /**
+     * Cached version of normalizeComponentName to avoid repeated string operations
+     */
+    cachedNormalizeName(name) {
+        let normalized = this.nameCache.get(name);
+        if (normalized === undefined) {
+            normalized = normalizeComponentName(name);
+            this.nameCache.set(name, normalized);
+        }
+        return normalized;
+    }
+    /**
+     * Get pre-computed component metadata for faster similarity calculations
+     */
+    getComponentMetadata(component) {
+        let metadata = this.componentMetadataCache.get(component.id);
+        if (!metadata) {
+            metadata = {
+                props: new Set(component.props.map((p) => p.name.toLowerCase())),
+                variants: new Set(component.variants.map((v) => v.name.toLowerCase())),
+                dependencies: new Set(component.dependencies.map((d) => d.toLowerCase())),
+            };
+            this.componentMetadataCache.set(component.id, metadata);
+        }
+        return metadata;
+    }
+    /**
+     * Clear caches to prevent memory leaks between operations
+     */
+    clearCaches() {
+        this.nameCache.clear();
+        this.componentMetadataCache.clear();
+    }
     /**
      * Check for framework sprawl - multiple UI frameworks in one codebase
      */
     checkFrameworkSprawl(frameworks) {
         // Only count UI/component frameworks, not backend frameworks
         const uiFrameworkNames = [
-            'react', 'vue', 'svelte', 'angular', 'solid', 'preact', 'lit', 'stencil',
-            'nextjs', 'nuxt', 'astro', 'remix', 'sveltekit', 'gatsby', 'react-native', 'expo', 'flutter'
+            "react",
+            "vue",
+            "svelte",
+            "angular",
+            "solid",
+            "preact",
+            "lit",
+            "stencil",
+            "nextjs",
+            "nuxt",
+            "astro",
+            "remix",
+            "sveltekit",
+            "gatsby",
+            "react-native",
+            "expo",
+            "flutter",
         ];
-        const uiFrameworks = frameworks.filter(f => uiFrameworkNames.includes(f.name));
+        const uiFrameworks = frameworks.filter((f) => uiFrameworkNames.includes(f.name));
         if (uiFrameworks.length <= 1) {
             return null; // No sprawl
         }
-        const frameworkNames = uiFrameworks.map(f => f.name);
+        const frameworkNames = uiFrameworks.map((f) => f.name);
         const primaryFramework = uiFrameworks[0];
         return {
-            id: createDriftId('framework-sprawl', 'project', frameworkNames.join('-')),
-            type: 'framework-sprawl',
-            severity: 'warning',
+            id: createDriftId("framework-sprawl", "project", frameworkNames.join("-")),
+            type: "framework-sprawl",
+            severity: "warning",
             source: {
-                entityType: 'component',
-                entityId: 'project',
-                entityName: 'Project Architecture',
-                location: 'package.json',
+                entityType: "component",
+                entityId: "project",
+                entityName: "Project Architecture",
+                location: "package.json",
             },
-            message: `Framework sprawl detected: ${uiFrameworks.length} UI frameworks in use (${frameworkNames.join(', ')})`,
+            message: `Framework sprawl detected: ${uiFrameworks.length} UI frameworks in use (${frameworkNames.join(", ")})`,
             details: {
                 expected: `Single framework (${primaryFramework.name})`,
                 actual: `${uiFrameworks.length} frameworks`,
-                frameworks: uiFrameworks.map(f => ({ name: f.name, version: f.version })),
+                frameworks: uiFrameworks.map((f) => ({
+                    name: f.name,
+                    version: f.version,
+                })),
                 suggestions: [
-                    'Consider consolidating to a single UI framework',
-                    'Document intentional multi-framework usage if required',
-                    'Create migration plan if frameworks are being deprecated',
+                    "Consider consolidating to a single UI framework",
+                    "Document intentional multi-framework usage if required",
+                    "Create migration plan if frameworks are being deprecated",
                 ],
             },
             detectedAt: new Date(),
@@ -41,39 +175,60 @@ export class SemanticDiffEngine {
     }
     /**
      * Compare components from different sources (e.g., React vs Figma)
+     * Optimized with Map-based indexing for O(n+m) instead of O(n×m)
      */
     compareComponents(sourceComponents, targetComponents, options = {}) {
         const matches = [];
         const matchedSourceIds = new Set();
         const matchedTargetIds = new Set();
-        // Phase 1: Exact name matches
+        // Build target component lookup map for O(1) exact matching - O(m) one-time cost
+        const targetNameMap = new Map();
+        for (const target of targetComponents) {
+            const normalizedName = this.cachedNormalizeName(target.name);
+            targetNameMap.set(normalizedName, target);
+        }
+        // Phase 1: Exact name matches - O(n) instead of O(n × m)
         for (const source of sourceComponents) {
-            const sourceName = normalizeComponentName(source.name);
-            const exactMatch = targetComponents.find(t => normalizeComponentName(t.name) === sourceName);
-            if (exactMatch) {
-                matches.push(this.createMatch(source, exactMatch, 'exact'));
+            const normalizedName = this.cachedNormalizeName(source.name);
+            const exactMatch = targetNameMap.get(normalizedName);
+            if (exactMatch && !matchedTargetIds.has(exactMatch.id)) {
+                matches.push(this.createMatch(source, exactMatch, "exact"));
                 matchedSourceIds.add(source.id);
                 matchedTargetIds.add(exactMatch.id);
             }
         }
-        // Phase 2: Fuzzy matching for remaining
-        const unmatchedSource = sourceComponents.filter(c => !matchedSourceIds.has(c.id));
-        const unmatchedTarget = targetComponents.filter(c => !matchedTargetIds.has(c.id));
-        for (const source of unmatchedSource) {
-            const bestMatch = this.findBestMatch(source, unmatchedTarget);
-            const minConfidence = options.minMatchConfidence || 0.7;
+        // Phase 2: Fuzzy matching for remaining - optimized candidate tracking
+        const unmatchedTargetMap = new Map();
+        for (const target of targetComponents) {
+            if (!matchedTargetIds.has(target.id)) {
+                unmatchedTargetMap.set(target.id, target);
+            }
+        }
+        const minConfidence = options.minMatchConfidence || MATCHING_CONFIG.minMatchConfidence;
+        for (const source of sourceComponents) {
+            if (matchedSourceIds.has(source.id))
+                continue;
+            // Convert to array only for remaining unmatched targets
+            const candidates = Array.from(unmatchedTargetMap.values());
+            const bestMatch = this.findBestMatch(source, candidates);
             if (bestMatch && bestMatch.confidence >= minConfidence) {
                 matches.push(bestMatch);
                 matchedSourceIds.add(source.id);
                 matchedTargetIds.add(bestMatch.target.id);
+                // Remove matched target to prevent re-matching and reduce candidates
+                unmatchedTargetMap.delete(bestMatch.target.id);
             }
         }
         // Phase 3: Generate drift signals
-        const drifts = this.generateComponentDrifts(matches, sourceComponents.filter(c => !matchedSourceIds.has(c.id)), targetComponents.filter(c => !matchedTargetIds.has(c.id)));
+        const orphanedSource = sourceComponents.filter((c) => !matchedSourceIds.has(c.id));
+        const orphanedTarget = targetComponents.filter((c) => !matchedTargetIds.has(c.id));
+        const drifts = this.generateComponentDrifts(matches, orphanedSource, orphanedTarget);
+        // Clear caches to prevent memory leaks
+        this.clearCaches();
         return {
             matches,
-            orphanedSource: sourceComponents.filter(c => !matchedSourceIds.has(c.id)),
-            orphanedTarget: targetComponents.filter(c => !matchedTargetIds.has(c.id)),
+            orphanedSource,
+            orphanedTarget,
             drifts,
         };
     }
@@ -87,7 +242,7 @@ export class SemanticDiffEngine {
         const matchedTargetIds = new Set();
         for (const source of sourceTokens) {
             const sourceName = normalizeTokenName(source.name);
-            const target = targetTokens.find(t => normalizeTokenName(t.name) === sourceName);
+            const target = targetTokens.find((t) => normalizeTokenName(t.name) === sourceName);
             if (!target)
                 continue;
             matchedSourceIds.add(source.id);
@@ -96,46 +251,46 @@ export class SemanticDiffEngine {
             // Check for value divergence
             if (!tokensMatch(source.value, target.value)) {
                 drifts.push({
-                    id: createDriftId('value-divergence', source.id, target.id),
-                    type: 'value-divergence',
-                    severity: 'warning',
+                    id: createDriftId("value-divergence", source.id, target.id),
+                    type: "value-divergence",
+                    severity: "warning",
                     source: this.tokenToDriftSource(source),
                     target: this.tokenToDriftSource(target),
                     message: `Token "${source.name}" has different values between sources`,
                     details: {
                         expected: source.value,
                         actual: target.value,
-                        suggestions: ['Align token values between design and code'],
+                        suggestions: ["Align token values between design and code"],
                     },
                     detectedAt: new Date(),
                 });
             }
         }
         // Orphaned tokens
-        const orphanedSource = sourceTokens.filter(t => !matchedSourceIds.has(t.id));
-        const orphanedTarget = targetTokens.filter(t => !matchedTargetIds.has(t.id));
+        const orphanedSource = sourceTokens.filter((t) => !matchedSourceIds.has(t.id));
+        const orphanedTarget = targetTokens.filter((t) => !matchedTargetIds.has(t.id));
         for (const token of orphanedSource) {
             drifts.push({
-                id: createDriftId('orphaned-token', token.id),
-                type: 'orphaned-token',
-                severity: 'info',
+                id: createDriftId("orphaned-token", token.id),
+                type: "orphaned-token",
+                severity: "info",
                 source: this.tokenToDriftSource(token),
                 message: `Token "${token.name}" exists in ${token.source.type} but not in design`,
                 details: {
-                    suggestions: ['Add token to design system or remove if unused'],
+                    suggestions: ["Add token to design system or remove if unused"],
                 },
                 detectedAt: new Date(),
             });
         }
         for (const token of orphanedTarget) {
             drifts.push({
-                id: createDriftId('orphaned-token', token.id),
-                type: 'orphaned-token',
-                severity: 'info',
+                id: createDriftId("orphaned-token", token.id),
+                type: "orphaned-token",
+                severity: "info",
                 source: this.tokenToDriftSource(token),
                 message: `Token "${token.name}" exists in design but not implemented`,
                 details: {
-                    suggestions: ['Implement token in code or mark as planned'],
+                    suggestions: ["Implement token in code or mark as planned"],
                 },
                 detectedAt: new Date(),
             });
@@ -155,14 +310,15 @@ export class SemanticDiffEngine {
             // Check for deprecation
             if (options.checkDeprecated && component.metadata.deprecated) {
                 drifts.push({
-                    id: createDriftId('deprecated-pattern', component.id),
-                    type: 'deprecated-pattern',
-                    severity: 'warning',
+                    id: createDriftId("deprecated-pattern", component.id),
+                    type: "deprecated-pattern",
+                    severity: "warning",
                     source: this.componentToDriftSource(component),
                     message: `Component "${component.name}" is marked as deprecated`,
                     details: {
                         suggestions: [
-                            component.metadata.deprecationReason || 'Migrate to recommended alternative',
+                            component.metadata.deprecationReason ||
+                                "Migrate to recommended alternative",
                         ],
                     },
                     detectedAt: new Date(),
@@ -173,9 +329,9 @@ export class SemanticDiffEngine {
                 const namingIssue = this.checkNamingConsistency(component.name, namingPatterns);
                 if (namingIssue) {
                     drifts.push({
-                        id: createDriftId('naming-inconsistency', component.id),
-                        type: 'naming-inconsistency',
-                        severity: 'info',
+                        id: createDriftId("naming-inconsistency", component.id),
+                        type: "naming-inconsistency",
+                        severity: "info",
                         source: this.componentToDriftSource(component),
                         message: namingIssue.message,
                         details: {
@@ -190,16 +346,18 @@ export class SemanticDiffEngine {
                 const typeConflict = this.checkPropTypeConsistency(prop, propTypeMap);
                 if (typeConflict) {
                     drifts.push({
-                        id: createDriftId('semantic-mismatch', component.id, prop.name),
-                        type: 'semantic-mismatch',
-                        severity: 'warning',
+                        id: createDriftId("semantic-mismatch", component.id, prop.name),
+                        type: "semantic-mismatch",
+                        severity: "warning",
                         source: this.componentToDriftSource(component),
                         message: `Prop "${prop.name}" in "${component.name}" uses type "${prop.type}" but other components use "${typeConflict.dominantType}"`,
                         details: {
                             expected: typeConflict.dominantType,
                             actual: prop.type,
                             usedIn: typeConflict.examples,
-                            suggestions: ['Standardize prop types across components for consistency'],
+                            suggestions: [
+                                "Standardize prop types across components for consistency",
+                            ],
                         },
                         detectedAt: new Date(),
                     });
@@ -209,9 +367,9 @@ export class SemanticDiffEngine {
             const propNamingIssues = this.checkPropNamingConsistency(component, propNamingMap);
             for (const issue of propNamingIssues) {
                 drifts.push({
-                    id: createDriftId('naming-inconsistency', component.id, issue.propName),
-                    type: 'naming-inconsistency',
-                    severity: 'info',
+                    id: createDriftId("naming-inconsistency", component.id, issue.propName),
+                    type: "naming-inconsistency",
+                    severity: "info",
                     source: this.componentToDriftSource(component),
                     message: issue.message,
                     details: {
@@ -225,50 +383,91 @@ export class SemanticDiffEngine {
                 const a11yIssues = this.checkAccessibility(component);
                 for (const issue of a11yIssues) {
                     drifts.push({
-                        id: createDriftId('accessibility-conflict', component.id),
-                        type: 'accessibility-conflict',
-                        severity: 'critical',
+                        id: createDriftId("accessibility-conflict", component.id),
+                        type: "accessibility-conflict",
+                        severity: "critical",
                         source: this.componentToDriftSource(component),
                         message: `Component "${component.name}" has accessibility issues: ${issue}`,
                         details: {
-                            suggestions: ['Fix accessibility issue to ensure inclusive design'],
+                            suggestions: [
+                                "Fix accessibility issue to ensure inclusive design",
+                            ],
                         },
                         detectedAt: new Date(),
                     });
                 }
             }
             // Check for hardcoded values that should be tokens
-            if (component.metadata.hardcodedValues && component.metadata.hardcodedValues.length > 0) {
+            if (component.metadata.hardcodedValues &&
+                component.metadata.hardcodedValues.length > 0) {
                 const hardcoded = component.metadata.hardcodedValues;
-                const colorCount = hardcoded.filter(h => h.type === 'color').length;
-                const spacingCount = hardcoded.filter(h => h.type === 'spacing' || h.type === 'fontSize').length;
+                const colorCount = hardcoded.filter((h) => h.type === "color").length;
+                const spacingCount = hardcoded.filter((h) => h.type === "spacing" || h.type === "fontSize").length;
+                // Generate token suggestions if available tokens provided
+                const tokenSuggestions = options.availableTokens
+                    ? this.generateTokenSuggestions(hardcoded, options.availableTokens)
+                    : new Map();
                 // Group by type for cleaner messaging
                 if (colorCount > 0) {
-                    const colorValues = hardcoded.filter(h => h.type === 'color');
+                    const colorValues = hardcoded.filter((h) => h.type === "color");
+                    // Build actionable suggestions
+                    const suggestions = [];
+                    const tokenReplacements = [];
+                    for (const cv of colorValues) {
+                        const suggs = tokenSuggestions.get(cv.value);
+                        if (suggs && suggs.length > 0) {
+                            const bestMatch = suggs[0];
+                            tokenReplacements.push(`${cv.value} → ${bestMatch.suggestedToken} (${Math.round(bestMatch.confidence * 100)}% match)`);
+                        }
+                    }
+                    if (tokenReplacements.length > 0) {
+                        suggestions.push(`Suggested replacements:\n  ${tokenReplacements.join("\n  ")}`);
+                    }
+                    else {
+                        suggestions.push("Replace hardcoded colors with design tokens (e.g., var(--primary) or theme.colors.primary)");
+                    }
                     drifts.push({
-                        id: createDriftId('hardcoded-value', component.id, 'color'),
-                        type: 'hardcoded-value',
-                        severity: 'warning',
+                        id: createDriftId("hardcoded-value", component.id, "color"),
+                        type: "hardcoded-value",
+                        severity: "warning",
                         source: this.componentToDriftSource(component),
-                        message: `Component "${component.name}" has ${colorCount} hardcoded color${colorCount > 1 ? 's' : ''}: ${colorValues.map(h => h.value).join(', ')}`,
+                        message: `Component "${component.name}" has ${colorCount} hardcoded color${colorCount > 1 ? "s" : ""}: ${colorValues.map((h) => h.value).join(", ")}`,
                         details: {
-                            suggestions: ['Replace hardcoded colors with design tokens (e.g., var(--primary) or theme.colors.primary)'],
-                            affectedFiles: colorValues.map(h => `${h.property}: ${h.value} (${h.location})`),
+                            suggestions,
+                            affectedFiles: colorValues.map((h) => `${h.property}: ${h.value} (${h.location})`),
+                            tokenSuggestions: tokenReplacements.length > 0 ? tokenReplacements : undefined,
                         },
                         detectedAt: new Date(),
                     });
                 }
                 if (spacingCount > 0) {
-                    const spacingValues = hardcoded.filter(h => h.type === 'spacing' || h.type === 'fontSize');
+                    const spacingValues = hardcoded.filter((h) => h.type === "spacing" || h.type === "fontSize");
+                    // Build actionable suggestions
+                    const suggestions = [];
+                    const tokenReplacements = [];
+                    for (const sv of spacingValues) {
+                        const suggs = tokenSuggestions.get(sv.value);
+                        if (suggs && suggs.length > 0) {
+                            const bestMatch = suggs[0];
+                            tokenReplacements.push(`${sv.value} → ${bestMatch.suggestedToken} (${Math.round(bestMatch.confidence * 100)}% match)`);
+                        }
+                    }
+                    if (tokenReplacements.length > 0) {
+                        suggestions.push(`Suggested replacements:\n  ${tokenReplacements.join("\n  ")}`);
+                    }
+                    else {
+                        suggestions.push("Consider using spacing tokens for consistency");
+                    }
                     drifts.push({
-                        id: createDriftId('hardcoded-value', component.id, 'spacing'),
-                        type: 'hardcoded-value',
-                        severity: 'info',
+                        id: createDriftId("hardcoded-value", component.id, "spacing"),
+                        type: "hardcoded-value",
+                        severity: "info",
                         source: this.componentToDriftSource(component),
-                        message: `Component "${component.name}" has ${spacingCount} hardcoded size value${spacingCount > 1 ? 's' : ''}: ${spacingValues.map(h => h.value).join(', ')}`,
+                        message: `Component "${component.name}" has ${spacingCount} hardcoded size value${spacingCount > 1 ? "s" : ""}: ${spacingValues.map((h) => h.value).join(", ")}`,
                         details: {
-                            suggestions: ['Consider using spacing tokens for consistency'],
-                            affectedFiles: spacingValues.map(h => `${h.property}: ${h.value} (${h.location})`),
+                            suggestions,
+                            affectedFiles: spacingValues.map((h) => `${h.property}: ${h.value} (${h.location})`),
+                            tokenSuggestions: tokenReplacements.length > 0 ? tokenReplacements : undefined,
                         },
                         detectedAt: new Date(),
                     });
@@ -280,14 +479,16 @@ export class SemanticDiffEngine {
         const duplicates = this.detectPotentialDuplicates(components);
         for (const dup of duplicates) {
             drifts.push({
-                id: createDriftId('naming-inconsistency', dup.components[0].id, 'duplicate'),
-                type: 'naming-inconsistency',
-                severity: 'warning',
+                id: createDriftId("naming-inconsistency", dup.components[0].id, "duplicate"),
+                type: "naming-inconsistency",
+                severity: "warning",
                 source: this.componentToDriftSource(dup.components[0]),
-                message: `Potential duplicate components: ${dup.components.map(c => c.name).join(', ')}`,
+                message: `Potential duplicate components: ${dup.components.map((c) => c.name).join(", ")}`,
                 details: {
-                    suggestions: ['Consider consolidating these components or clarifying their distinct purposes'],
-                    relatedComponents: dup.components.map(c => c.name),
+                    suggestions: [
+                        "Consider consolidating these components or clarifying their distinct purposes",
+                    ],
+                    relatedComponents: dup.components.map((c) => c.name),
                 },
                 detectedAt: new Date(),
             });
@@ -301,7 +502,7 @@ export class SemanticDiffEngine {
         const patterns = {
             PascalCase: 0,
             camelCase: 0,
-            'kebab-case': 0,
+            "kebab-case": 0,
             snake_case: 0,
             other: 0,
         };
@@ -309,12 +510,13 @@ export class SemanticDiffEngine {
             const pattern = this.identifyNamingPattern(comp.name);
             patterns[pattern]++;
         }
-        // Find dominant pattern (must be > 60% to be considered dominant)
+        // Find dominant pattern (must exceed threshold to be considered dominant)
         const total = components.length;
         let dominant = null;
         let dominantCount = 0;
         for (const [pattern, count] of Object.entries(patterns)) {
-            if (count > dominantCount && count / total > 0.6) {
+            if (count > dominantCount &&
+                count / total > NAMING_CONFIG.dominantPatternThreshold) {
                 dominant = pattern;
                 dominantCount = count;
             }
@@ -323,14 +525,14 @@ export class SemanticDiffEngine {
     }
     identifyNamingPattern(name) {
         if (/^[A-Z][a-zA-Z0-9]*$/.test(name))
-            return 'PascalCase';
+            return "PascalCase";
         if (/^[a-z][a-zA-Z0-9]*$/.test(name))
-            return 'camelCase';
+            return "camelCase";
         if (/^[a-z][a-z0-9-]*$/.test(name))
-            return 'kebab-case';
+            return "kebab-case";
         if (/^[a-z][a-z0-9_]*$/.test(name))
-            return 'snake_case';
-        return 'other';
+            return "snake_case";
+        return "other";
     }
     checkNamingConsistency(name, patterns) {
         if (!patterns.dominant)
@@ -339,7 +541,7 @@ export class SemanticDiffEngine {
         if (thisPattern === patterns.dominant)
             return null;
         // Only flag if this is a clear outlier
-        const outlierThreshold = Math.max(3, patterns.total * 0.1); // At least 3 or 10% use dominant
+        const outlierThreshold = getOutlierThreshold(patterns.total);
         if (patterns.patterns[patterns.dominant] < outlierThreshold)
             return null;
         return {
@@ -359,7 +561,10 @@ export class SemanticDiffEngine {
                     map.set(normalizedName, { types: new Map(), total: 0 });
                 }
                 const usage = map.get(normalizedName);
-                const typeCount = usage.types.get(prop.type) || { count: 0, examples: [] };
+                const typeCount = usage.types.get(prop.type) || {
+                    count: 0,
+                    examples: [],
+                };
                 typeCount.count++;
                 if (typeCount.examples.length < 3) {
                     typeCount.examples.push(comp.name);
@@ -375,7 +580,7 @@ export class SemanticDiffEngine {
         if (!usage || usage.total < 3)
             return null; // Not enough data
         // Find dominant type
-        let dominantType = '';
+        let dominantType = "";
         let dominantCount = 0;
         for (const [type, data] of usage.types) {
             if (data.count > dominantCount) {
@@ -383,10 +588,11 @@ export class SemanticDiffEngine {
                 dominantCount = data.count;
             }
         }
-        // Only flag if this prop's type differs and dominant is > 70%
+        // Only flag if this prop's type differs and dominant exceeds threshold
         if (prop.type === dominantType)
             return null;
-        if (dominantCount / usage.total < 0.7)
+        if (dominantCount / usage.total <
+            NAMING_CONFIG.establishedConventionThreshold)
             return null;
         const examples = usage.types.get(dominantType)?.examples || [];
         return { dominantType, examples };
@@ -402,16 +608,16 @@ export class SemanticDiffEngine {
         for (const comp of components) {
             for (const prop of comp.props) {
                 const lower = prop.name.toLowerCase();
-                if (lower.includes('click') || lower.includes('press')) {
+                if (lower.includes("click") || lower.includes("press")) {
                     clickHandlers.push(prop.name);
                 }
-                if (lower.includes('change')) {
+                if (lower.includes("change")) {
                     changeHandlers.push(prop.name);
                 }
             }
         }
-        map.set('click', clickHandlers);
-        map.set('change', changeHandlers);
+        map.set("click", clickHandlers);
+        map.set("change", changeHandlers);
         return map;
     }
     checkPropNamingConsistency(component, propNamingMap) {
@@ -419,8 +625,8 @@ export class SemanticDiffEngine {
         for (const prop of component.props) {
             const lower = prop.name.toLowerCase();
             // Check click handler naming
-            if (lower.includes('click') || lower.includes('press')) {
-                const allClickHandlers = propNamingMap.get('click') || [];
+            if (lower.includes("click") || lower.includes("press")) {
+                const allClickHandlers = propNamingMap.get("click") || [];
                 if (allClickHandlers.length >= 5) {
                     const dominant = this.findDominantPropPattern(allClickHandlers);
                     if (dominant && !prop.name.startsWith(dominant.prefix)) {
@@ -429,7 +635,7 @@ export class SemanticDiffEngine {
                             issues.push({
                                 propName: prop.name,
                                 message: `"${prop.name}" in "${component.name}" - ${dominantPct}% of click handlers use "${dominant.prefix}..." pattern`,
-                                suggestion: `Consider using "${dominant.prefix}${prop.name.replace(/^(on|handle)/i, '')}" for consistency`,
+                                suggestion: `Consider using "${dominant.prefix}${prop.name.replace(/^(on|handle)/i, "")}" for consistency`,
                             });
                         }
                     }
@@ -441,10 +647,10 @@ export class SemanticDiffEngine {
     findDominantPropPattern(propNames) {
         const prefixes = {};
         for (const name of propNames) {
-            if (name.startsWith('on'))
-                prefixes['on'] = (prefixes['on'] || 0) + 1;
-            else if (name.startsWith('handle'))
-                prefixes['handle'] = (prefixes['handle'] || 0) + 1;
+            if (name.startsWith("on"))
+                prefixes["on"] = (prefixes["on"] || 0) + 1;
+            else if (name.startsWith("handle"))
+                prefixes["handle"] = (prefixes["handle"] || 0) + 1;
         }
         let dominant = null;
         for (const [prefix, count] of Object.entries(prefixes)) {
@@ -455,7 +661,9 @@ export class SemanticDiffEngine {
         return dominant;
     }
     /**
-     * Detect potential duplicate components based on similar names
+     * Detect potential duplicate components based on similar names.
+     * Only flags true duplicates like Button vs ButtonNew or Card vs CardLegacy.
+     * Does NOT flag compound components like Button vs ButtonGroup or Card vs CardHeader.
      */
     detectPotentialDuplicates(components) {
         const duplicates = [];
@@ -463,33 +671,59 @@ export class SemanticDiffEngine {
         for (const comp of components) {
             if (processed.has(comp.id))
                 continue;
-            // Find components with similar base names
-            const baseName = comp.name
-                .replace(/(New|Old|V\d+|Legacy|Updated|Deprecated)$/i, '')
-                .replace(/\d+$/, '')
-                .toLowerCase();
-            const similar = components.filter(c => {
+            // Extract base name and check if it has a version suffix
+            const { baseName, hasVersionSuffix } = this.extractBaseName(comp.name);
+            const similar = components.filter((c) => {
                 if (c.id === comp.id)
                     return false;
-                const otherBase = c.name
-                    .replace(/(New|Old|V\d+|Legacy|Updated|Deprecated)$/i, '')
-                    .replace(/\d+$/, '')
-                    .toLowerCase();
-                return baseName === otherBase && baseName.length >= 3;
+                const other = this.extractBaseName(c.name);
+                // Only match if base names are identical
+                if (baseName !== other.baseName || baseName.length < 3) {
+                    return false;
+                }
+                // At least one component must have a version suffix to be a duplicate
+                // This prevents Button vs ButtonGroup from matching
+                // But allows Button vs ButtonNew to match
+                return hasVersionSuffix || other.hasVersionSuffix;
             });
             if (similar.length > 0) {
                 const group = [comp, ...similar];
-                group.forEach(c => processed.add(c.id));
+                group.forEach((c) => processed.add(c.id));
                 duplicates.push({ components: group });
             }
         }
         return duplicates;
     }
+    /**
+     * Extract the base name from a component name, stripping version suffixes.
+     * Returns whether the name had a version suffix (indicating potential duplicate).
+     */
+    extractBaseName(name) {
+        const lowerName = name.toLowerCase();
+        // Check if the name ends with a semantic suffix (legitimate separate component)
+        for (const suffix of SEMANTIC_COMPONENT_SUFFIXES) {
+            if (lowerName.endsWith(suffix) &&
+                lowerName.length > suffix.length &&
+                // Ensure the suffix is at a word boundary (e.g., "ButtonGroup" not "Buttong")
+                lowerName[lowerName.length - suffix.length - 1]?.match(/[a-z]/)) {
+                // This is a compound component, not a duplicate candidate
+                // Return the full name as the base (it's distinct)
+                return { baseName: lowerName, hasVersionSuffix: false };
+            }
+        }
+        // Check for version suffixes that indicate duplicates
+        const hasVersionSuffix = VERSION_SUFFIXES_PATTERN.test(name);
+        const strippedName = name
+            .replace(VERSION_SUFFIXES_PATTERN, "")
+            .replace(/\d+$/, "") // Strip trailing numbers
+            .toLowerCase();
+        return { baseName: strippedName, hasVersionSuffix };
+    }
     createMatch(source, target, matchType) {
         return {
             source,
             target,
-            confidence: matchType === 'exact' ? 1 : 0,
+            confidence: matchType === "exact" ? 1 : 0,
             matchType,
             differences: this.findDifferences(source, target),
         };
@@ -501,7 +735,7 @@ export class SemanticDiffEngine {
             const score = this.calculateSimilarity(source, candidate);
             if (score > bestScore) {
                 bestScore = score;
-                const matchType = score > 0.9 ? 'similar' : 'partial';
+                const matchType = score > MATCHING_CONFIG.similarMatchThreshold ? "similar" : "partial";
                 bestMatch = {
                     source,
                     target: candidate,
@@ -515,67 +749,39 @@ export class SemanticDiffEngine {
     }
     calculateSimilarity(a, b) {
         let score = 0;
-        const weights = { name: 0.4, props: 0.3, variants: 0.2, dependencies: 0.1 };
+        const weights = MATCHING_CONFIG.similarityWeights;
         // Name similarity (Levenshtein-based)
         score += weights.name * this.stringSimilarity(a.name, b.name);
-        // Props overlap
-        const aProps = new Set(a.props.map(p => p.name.toLowerCase()));
-        const bProps = new Set(b.props.map(p => p.name.toLowerCase()));
-        const propsIntersection = [...aProps].filter(p => bProps.has(p)).length;
-        const propsUnion = new Set([...aProps, ...bProps]).size;
-        score += weights.props * (propsUnion > 0 ? propsIntersection / propsUnion : 0);
-        // Variant overlap
-        const aVariants = new Set(a.variants.map(v => v.name.toLowerCase()));
-        const bVariants = new Set(b.variants.map(v => v.name.toLowerCase()));
-        const variantsIntersection = [...aVariants].filter(v => bVariants.has(v)).length;
-        const variantsUnion = new Set([...aVariants, ...bVariants]).size;
-        score += weights.variants * (variantsUnion > 0 ? variantsIntersection / variantsUnion : 0);
-        // Dependencies overlap
-        const aDeps = new Set(a.dependencies.map(d => d.toLowerCase()));
-        const bDeps = new Set(b.dependencies.map(d => d.toLowerCase()));
-        const depsIntersection = [...aDeps].filter(d => bDeps.has(d)).length;
-        const depsUnion = new Set([...aDeps, ...bDeps]).size;
-        score += weights.dependencies * (depsUnion > 0 ? depsIntersection / depsUnion : 0);
+        // Use pre-computed metadata for faster overlap calculation
+        const aMeta = this.getComponentMetadata(a);
+        const bMeta = this.getComponentMetadata(b);
+        // Props overlap (using pre-computed Sets)
+        const propsIntersection = [...aMeta.props].filter((p) => bMeta.props.has(p)).length;
+        const propsUnion = new Set([...aMeta.props, ...bMeta.props]).size;
+        score +=
+            weights.props * (propsUnion > 0 ? propsIntersection / propsUnion : 0);
+        // Variant overlap (using pre-computed Sets)
+        const variantsIntersection = [...aMeta.variants].filter((v) => bMeta.variants.has(v)).length;
+        const variantsUnion = new Set([...aMeta.variants, ...bMeta.variants]).size;
+        score +=
+            weights.variants *
+                (variantsUnion > 0 ? variantsIntersection / variantsUnion : 0);
+        // Dependencies overlap (using pre-computed Sets)
+        const depsIntersection = [...aMeta.dependencies].filter((d) => bMeta.dependencies.has(d)).length;
+        const depsUnion = new Set([...aMeta.dependencies, ...bMeta.dependencies])
+            .size;
+        score +=
+            weights.dependencies * (depsUnion > 0 ? depsIntersection / depsUnion : 0);
         return score;
     }
     stringSimilarity(a, b) {
-        const maxLen = Math.max(a.length, b.length);
-        if (maxLen === 0)
-            return 1;
-        const distance = this.levenshteinDistance(a.toLowerCase(), b.toLowerCase());
-        return 1 - distance / maxLen;
-    }
-    levenshteinDistance(a, b) {
-        // Create matrix with proper initialization
-        const rows = b.length + 1;
-        const cols = a.length + 1;
-        const matrix = Array.from({ length: rows }, () => Array(cols).fill(0));
-        // Initialize first column
-        for (let i = 0; i <= b.length; i++) {
-            matrix[i][0] = i;
-        }
-        // Initialize first row
-        for (let j = 0; j <= a.length; j++) {
-            matrix[0][j] = j;
-        }
-        // Fill in the rest of the matrix
-        for (let i = 1; i <= b.length; i++) {
-            for (let j = 1; j <= a.length; j++) {
-                if (b.charAt(i - 1) === a.charAt(j - 1)) {
-                    matrix[i][j] = matrix[i - 1][j - 1];
-                }
-                else {
-                    matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
-                }
-            }
-        }
-        return matrix[b.length][a.length];
+        return calcStringSimilarity(a.toLowerCase(), b.toLowerCase());
     }
     findDifferences(source, target) {
         const differences = [];
         // Compare props
-        const sourceProps = new Map(source.props.map(p => [p.name.toLowerCase(), p]));
-        const targetProps = new Map(target.props.map(p => [p.name.toLowerCase(), p]));
+        const sourceProps = new Map(source.props.map((p) => [p.name.toLowerCase(), p]));
+        const targetProps = new Map(target.props.map((p) => [p.name.toLowerCase(), p]));
         for (const [name, prop] of sourceProps) {
             const targetProp = targetProps.get(name);
             if (!targetProp) {
@@ -583,7 +789,7 @@ export class SemanticDiffEngine {
                     field: `props.${prop.name}`,
                     sourceValue: prop,
                     targetValue: undefined,
-                    severity: prop.required ? 'warning' : 'info',
+                    severity: prop.required ? "warning" : "info",
                 });
             }
             else if (prop.type !== targetProp.type) {
@@ -591,7 +797,7 @@ export class SemanticDiffEngine {
                     field: `props.${prop.name}.type`,
                     sourceValue: prop.type,
                     targetValue: targetProp.type,
-                    severity: 'warning',
+                    severity: "warning",
                 });
             }
         }
@@ -601,7 +807,7 @@ export class SemanticDiffEngine {
                     field: `props.${prop.name}`,
                     sourceValue: undefined,
                     targetValue: prop,
-                    severity: 'info',
+                    severity: "info",
                 });
             }
         }
@@ -611,18 +817,18 @@ export class SemanticDiffEngine {
         const drifts = [];
         // Drifts from matches with significant differences
         for (const match of matches) {
-            const significantDiffs = match.differences.filter(d => d.severity === 'warning' || d.severity === 'critical');
+            const significantDiffs = match.differences.filter((d) => d.severity === "warning" || d.severity === "critical");
             if (significantDiffs.length > 0) {
                 drifts.push({
-                    id: createDriftId('semantic-mismatch', match.source.id, match.target.id),
-                    type: 'semantic-mismatch',
+                    id: createDriftId("semantic-mismatch", match.source.id, match.target.id),
+                    type: "semantic-mismatch",
                     severity: this.getHighestSeverity(match.differences),
                     source: this.componentToDriftSource(match.source),
                     target: this.componentToDriftSource(match.target),
                     message: `Component "${match.source.name}" has ${significantDiffs.length} differences between sources`,
                     details: {
                         diff: JSON.stringify(match.differences, null, 2),
-                        suggestions: ['Review component definitions for consistency'],
+                        suggestions: ["Review component definitions for consistency"],
                     },
                     detectedAt: new Date(),
                 });
@@ -631,13 +837,15 @@ export class SemanticDiffEngine {
         // Orphaned source components
         for (const comp of orphanedSource) {
             drifts.push({
-                id: createDriftId('orphaned-component', comp.id),
-                type: 'orphaned-component',
-                severity: 'warning',
+                id: createDriftId("orphaned-component", comp.id),
+                type: "orphaned-component",
+                severity: "warning",
                 source: this.componentToDriftSource(comp),
                 message: `Component "${comp.name}" exists in ${comp.source.type} but has no match in design`,
                 details: {
-                    suggestions: ['Add component to Figma or document as intentional deviation'],
+                    suggestions: [
+                        "Add component to Figma or document as intentional deviation",
+                    ],
                 },
                 detectedAt: new Date(),
             });
@@ -645,13 +853,13 @@ export class SemanticDiffEngine {
         // Orphaned target components
         for (const comp of orphanedTarget) {
             drifts.push({
-                id: createDriftId('orphaned-component', comp.id),
-                type: 'orphaned-component',
-                severity: 'info',
+                id: createDriftId("orphaned-component", comp.id),
+                type: "orphaned-component",
+                severity: "info",
                 source: this.componentToDriftSource(comp),
                 message: `Component "${comp.name}" exists in design but not implemented`,
                 details: {
-                    suggestions: ['Implement component or mark as planned'],
+                    suggestions: ["Implement component or mark as planned"],
                 },
                 detectedAt: new Date(),
             });
@@ -659,58 +867,91 @@ export class SemanticDiffEngine {
         return drifts;
     }
     componentToDriftSource(comp) {
-        let location = '';
-        if (comp.source.type === 'react') {
+        let location = "";
+        if (comp.source.type === "react") {
             location = `${comp.source.path}:${comp.source.line || 0}`;
         }
-        else if (comp.source.type === 'figma') {
+        else if (comp.source.type === "figma") {
             location = comp.source.url || comp.source.nodeId;
         }
-        else if (comp.source.type === 'storybook') {
+        else if (comp.source.type === "storybook") {
             location = comp.source.url || comp.source.storyId;
         }
         return {
-            entityType: 'component',
+            entityType: "component",
             entityId: comp.id,
             entityName: comp.name,
             location,
         };
     }
     tokenToDriftSource(token) {
-        let location = '';
-        if (token.source.type === 'json' || token.source.type === 'css' || token.source.type === 'scss') {
+        let location = "";
+        if (token.source.type === "json" ||
+            token.source.type === "css" ||
+            token.source.type === "scss") {
             location = token.source.path;
         }
-        else if (token.source.type === 'figma') {
+        else if (token.source.type === "figma") {
             location = token.source.fileKey;
         }
         return {
-            entityType: 'token',
+            entityType: "token",
             entityId: token.id,
             entityName: token.name,
             location,
         };
     }
     getHighestSeverity(differences) {
-        if (differences.some(d => d.severity === 'critical'))
-            return 'critical';
-        if (differences.some(d => d.severity === 'warning'))
-            return 'warning';
-        return 'info';
+        if (differences.some((d) => d.severity === "critical"))
+            return "critical";
+        if (differences.some((d) => d.severity === "warning"))
+            return "warning";
+        return "info";
     }
     checkAccessibility(component) {
         const issues = [];
         // Check if interactive components have required ARIA props
-        const interactiveComponents = ['Button', 'Link', 'Input', 'Select', 'Checkbox', 'Radio'];
-        const isInteractive = interactiveComponents.some(ic => component.name.toLowerCase().includes(ic.toLowerCase()));
+        const interactiveComponents = [
+            "Button",
+            "Link",
+            "Input",
+            "Select",
+            "Checkbox",
+            "Radio",
+        ];
+        const isInteractive = interactiveComponents.some((ic) => component.name.toLowerCase().includes(ic.toLowerCase()));
         if (isInteractive) {
-            const hasAriaLabel = component.props.some(p => p.name.toLowerCase().includes('arialabel') || p.name.toLowerCase().includes('aria-label'));
-            const hasChildren = component.props.some(p => p.name.toLowerCase() === 'children');
-            if (!hasAriaLabel && !hasChildren && component.metadata.accessibility?.issues) {
+            const hasAriaLabel = component.props.some((p) => p.name.toLowerCase().includes("arialabel") ||
+                p.name.toLowerCase().includes("aria-label"));
+            const hasChildren = component.props.some((p) => p.name.toLowerCase() === "children");
+            if (!hasAriaLabel &&
+                !hasChildren &&
+                component.metadata.accessibility?.issues) {
                 issues.push(...component.metadata.accessibility.issues);
             }
         }
         return issues;
     }
+    /**
+     * Find token suggestions for a hardcoded color value
+     * Delegates to TokenSuggestionService
+     */
+    findColorTokenSuggestions(hardcodedValue, tokens, maxSuggestions = 3) {
+        return this.tokenSuggestionService.findColorTokenSuggestions(hardcodedValue, tokens, maxSuggestions);
+    }
+    /**
+     * Find token suggestions for a hardcoded spacing value
+     * Delegates to TokenSuggestionService
+     */
+    findSpacingTokenSuggestions(hardcodedValue, tokens, maxSuggestions = 3) {
+        return this.tokenSuggestionService.findSpacingTokenSuggestions(hardcodedValue, tokens, maxSuggestions);
+    }
+    /**
+     * Generate actionable suggestions for hardcoded values
+     * Delegates to TokenSuggestionService
+     */
+    generateTokenSuggestions(hardcodedValues, tokens) {
+        return this.tokenSuggestionService.generateTokenSuggestions(hardcodedValues, tokens);
+    }
 }
 //# sourceMappingURL=semantic-diff.js.map