@3fn/core 14.1.0 → 15.0.0

package/src/validators/ValidationReasoning.ts

@@ -1,464 +0,0 @@
-/**
- * Mathematical Reasoning Explanations for Validation System
- * 
- * Provides clear mathematical reasoning and explanations for validation decisions
- * across the three-tier validation system (Pass/Warning/Error).
- */
-
-import type { PrimitiveToken, SemanticToken } from '../types';
-import { TokenCategory } from '../types';
-import { isStrategicFlexibilityValue, getStrategicFlexibilityToken } from '../constants/StrategicFlexibilityTokens';
-
-/**
- * Reasoning context for validation explanations
- */
-export interface ReasoningContext {
-  /** Token being validated */
-  token: PrimitiveToken | SemanticToken;
-
-  /** Validation scenario */
-  scenario: 'primitive-usage' | 'semantic-usage' | 'strategic-flexibility' | 'mathematical-violation' | 'problematic-pattern';
-
-  /** Additional context data */
-  contextData?: {
-    /** Expected vs actual values */
-    expectedValue?: number;
-    actualValue?: number;
-
-    /** Mathematical relationship details */
-    relationship?: string;
-
-    /** Usage pattern information */
-    usagePattern?: string;
-
-    /** Platform-specific information */
-    platformInfo?: Record<string, any>;
-
-    /** Baseline grid information */
-    baselineGridInfo?: {
-      gridUnit: number;
-      isAligned: boolean;
-      nearestValid?: number;
-    };
-  };
-}
-
-/**
- * Mathematical reasoning generator for validation results
- */
-export class ValidationReasoning {
-  /**
-   * Generate mathematical reasoning for Pass-level validation
-   */
-  generatePassReasoning(context: ReasoningContext): string {
-    const { token, scenario, contextData } = context;
-
-    switch (scenario) {
-      case 'primitive-usage':
-        return this.generatePrimitivePassReasoning(token as PrimitiveToken, contextData);
-
-      case 'semantic-usage':
-        return this.generateSemanticPassReasoning(token as SemanticToken, contextData);
-
-      case 'strategic-flexibility':
-        return this.generateStrategicFlexibilityReasoning(token as PrimitiveToken, contextData);
-
-      default:
-        return 'Token usage follows established mathematical patterns and design system guidelines';
-    }
-  }
-
-  /**
-   * Generate mathematical reasoning for Warning-level validation
-   */
-  generateWarningReasoning(context: ReasoningContext): string {
-    const { token, scenario, contextData } = context;
-
-    switch (scenario) {
-      case 'problematic-pattern':
-        return this.generateProblematicPatternReasoning(token, contextData);
-
-      default:
-        return 'Token usage is mathematically valid but may indicate suboptimal design patterns';
-    }
-  }
-
-  /**
-   * Generate mathematical reasoning for Error-level validation
-   */
-  generateErrorReasoning(context: ReasoningContext): string {
-    const { token, scenario, contextData } = context;
-
-    switch (scenario) {
-      case 'mathematical-violation':
-        return this.generateMathematicalViolationReasoning(token, contextData);
-
-      default:
-        return 'Token usage violates mathematical relationships or design system constraints';
-    }
-  }
-
-  /**
-   * Generate reasoning for primitive token Pass validation
-   */
-  private generatePrimitivePassReasoning(token: PrimitiveToken, contextData?: ReasoningContext['contextData']): string {
-    const reasoningParts: string[] = [];
-
-    // Base mathematical relationship
-    reasoningParts.push(
-      `Token ${token.name} follows ${token.category} family mathematical foundation with base value ${token.familyBaseValue}`
-    );
-
-    // Mathematical relationship explanation
-    if (token.mathematicalRelationship) {
-      reasoningParts.push(`Mathematical relationship: ${token.mathematicalRelationship}`);
-    }
-
-    // Baseline grid alignment (for applicable categories)
-    if (this.requiresBaselineGridAlignment(token.category)) {
-      if (token.baselineGridAlignment) {
-        reasoningParts.push(
-          `Baseline grid alignment: ${token.baseValue} ÷ 8 = ${token.baseValue / 8} (confirms 8-unit alignment)`
-        );
-      }
-    }
-
-    // Precision targeting (for applicable categories)
-    if (token.isPrecisionTargeted) {
-      reasoningParts.push(
-        `Precision targeting: Uses calculated multipliers for systematic alignment with ${token.category} requirements`
-      );
-    }
-
-    // Cross-platform consistency
-    reasoningParts.push(
-      'Cross-platform mathematical relationships maintained through unitless base values and per-family unit conversion'
-    );
-
-    return reasoningParts.join('; ');
-  }
-
-  /**
-   * Generate reasoning for semantic token Pass validation
-   */
-  private generateSemanticPassReasoning(token: SemanticToken, contextData?: ReasoningContext['contextData']): string {
-    const reasoningParts: string[] = [];
-
-    // Semantic abstraction explanation
-    const referenceList = Object.entries(token.primitiveReferences)
-      .map(([key, ref]) => `${key}: ${ref}`)
-      .join(', ');
-    
-    reasoningParts.push(
-      `Semantic token ${token.name} provides contextual abstraction over primitive token(s): ${referenceList}`
-    );
-
-    // Mathematical inheritance
-    reasoningParts.push(
-      'Mathematical consistency inherited from referenced primitive token'
-    );
-
-    // Contextual appropriateness
-    if (token.context) {
-      reasoningParts.push(`Contextual usage: ${token.context}`);
-    }
-
-    // Design system hierarchy
-    reasoningParts.push(
-      'Follows design system hierarchy: semantic tokens reference primitives, maintaining mathematical relationships'
-    );
-
-    return reasoningParts.join('; ');
-  }
-
-  /**
-   * Generate reasoning for strategic flexibility token validation
-   */
-  private generateStrategicFlexibilityReasoning(token: PrimitiveToken, contextData?: ReasoningContext['contextData']): string {
-    const flexibilityToken = getStrategicFlexibilityToken(token.baseValue);
-
-    if (!flexibilityToken) {
-      return 'Strategic flexibility token with mathematically derived exception to systematic progression';
-    }
-
-    const reasoningParts: string[] = [];
-
-    // Mathematical derivation
-    reasoningParts.push(
-      `Strategic flexibility token: ${flexibilityToken.derivation} = ${flexibilityToken.value}`
-    );
-
-    // Exception explanation
-    reasoningParts.push(
-      `Intentionally breaks ${flexibilityToken.category} family systematic progression for exceptional design requirements`
-    );
-
-    // Mathematical validity
-    reasoningParts.push(
-      'Mathematically derived but provides necessary design flexibility while maintaining proportional relationships'
-    );
-
-    // Usage guidance
-    reasoningParts.push(
-      'Strategic flexibility tokens should maintain ≥80% appropriate usage patterns across the design system'
-    );
-
-    return reasoningParts.join('; ');
-  }
-
-  /**
-   * Generate reasoning for problematic pattern warnings
-   */
-  private generateProblematicPatternReasoning(
-    token: PrimitiveToken | SemanticToken,
-    contextData?: ReasoningContext['contextData']
-  ): string {
-    const reasoningParts: string[] = [];
-
-    // Pattern identification
-    if (contextData?.usagePattern) {
-      reasoningParts.push(`Detected pattern: ${contextData.usagePattern}`);
-    }
-
-    // Mathematical validity confirmation
-    reasoningParts.push('Token usage is mathematically valid within design system constraints');
-
-    // Potential issues
-    reasoningParts.push(
-      'Pattern may indicate suboptimal design decisions or missed opportunities for semantic token usage'
-    );
-
-    // Guidance
-    if ('primitiveReference' in token) {
-      // Semantic token
-      reasoningParts.push(
-        'Consider if primitive token fallback is necessary or if semantic token alternatives exist'
-      );
-    } else {
-      // Primitive token
-      reasoningParts.push(
-        'Consider if semantic token abstraction would be more appropriate for this usage context'
-      );
-    }
-
-    return reasoningParts.join('; ');
-  }
-
-  /**
-   * Generate reasoning for mathematical violation errors
-   */
-  private generateMathematicalViolationReasoning(
-    token: PrimitiveToken | SemanticToken,
-    contextData?: ReasoningContext['contextData']
-  ): string {
-    const reasoningParts: string[] = [];
-
-    // Violation identification
-    if (contextData?.expectedValue && contextData?.actualValue) {
-      reasoningParts.push(
-        `Mathematical violation: expected ${contextData.expectedValue}, found ${contextData.actualValue}`
-      );
-    }
-
-    // Mathematical relationship breakdown
-    if (contextData?.relationship) {
-      reasoningParts.push(`Violated relationship: ${contextData.relationship}`);
-    }
-
-    // Baseline grid violation (if applicable)
-    if (contextData?.baselineGridInfo && !contextData.baselineGridInfo.isAligned) {
-      const { gridUnit, nearestValid } = contextData.baselineGridInfo;
-      reasoningParts.push(
-        `Baseline grid violation: value does not align with ${gridUnit}-unit grid system`
-      );
-
-      if (nearestValid) {
-        reasoningParts.push(`Nearest valid value: ${nearestValid}`);
-      }
-    }
-
-    // Cross-platform consistency issues
-    if (contextData?.platformInfo) {
-      const platforms = Object.keys(contextData.platformInfo);
-      reasoningParts.push(
-        `Cross-platform consistency violation detected across platforms: ${platforms.join(', ')}`
-      );
-    }
-
-    // Impact explanation
-    reasoningParts.push(
-      'Mathematical violations compromise design system consistency and cross-platform predictability'
-    );
-
-    return reasoningParts.join('; ');
-  }
-
-  /**
-   * Generate suggestions for improving token usage
-   */
-  generateSuggestions(context: ReasoningContext): string[] {
-    const { token, scenario, contextData } = context;
-    const suggestions: string[] = [];
-
-    switch (scenario) {
-      case 'mathematical-violation':
-        suggestions.push(...this.generateViolationSuggestions(token, contextData));
-        break;
-
-      case 'problematic-pattern':
-        suggestions.push(...this.generatePatternSuggestions(token, contextData));
-        break;
-
-      case 'strategic-flexibility':
-        suggestions.push(...this.generateFlexibilitySuggestions(token, contextData));
-        break;
-    }
-
-    return suggestions;
-  }
-
-  /**
-   * Generate suggestions for mathematical violations
-   */
-  private generateViolationSuggestions(
-    token: PrimitiveToken | SemanticToken,
-    contextData?: ReasoningContext['contextData']
-  ): string[] {
-    const suggestions: string[] = [];
-
-    // Baseline grid suggestions
-    if (contextData?.baselineGridInfo && !contextData.baselineGridInfo.isAligned) {
-      const { nearestValid } = contextData.baselineGridInfo;
-      if (nearestValid) {
-        suggestions.push(`Use baseline grid aligned value: ${nearestValid}`);
-      }
-      suggestions.push('Consider if this should be a strategic flexibility token');
-    }
-
-    // Semantic token suggestions
-    if ('baseValue' in token) {
-      suggestions.push('Consider using semantic token abstraction instead of primitive token');
-      suggestions.push('Review if token fits within established mathematical progressions');
-    }
-
-    // Mathematical relationship suggestions
-    if (contextData?.relationship) {
-      suggestions.push(`Ensure token follows relationship: ${contextData.relationship}`);
-    }
-
-    return suggestions;
-  }
-
-  /**
-   * Generate suggestions for problematic patterns
-   */
-  private generatePatternSuggestions(
-    token: PrimitiveToken | SemanticToken,
-    contextData?: ReasoningContext['contextData']
-  ): string[] {
-    const suggestions: string[] = [];
-
-    if ('primitiveReference' in token) {
-      // Semantic token
-      suggestions.push('Verify semantic token provides appropriate contextual abstraction');
-      suggestions.push('Consider if primitive token reference is the most appropriate choice');
-    } else {
-      // Primitive token
-      suggestions.push('Consider creating semantic token for this usage context');
-      suggestions.push('Review if token usage follows established design patterns');
-    }
-
-    suggestions.push('Validate usage pattern against design system guidelines');
-
-    return suggestions;
-  }
-
-  /**
-   * Generate suggestions for strategic flexibility usage
-   */
-  private generateFlexibilitySuggestions(
-    token: PrimitiveToken | SemanticToken,
-    contextData?: ReasoningContext['contextData']
-  ): string[] {
-    const suggestions: string[] = [];
-
-    suggestions.push('Monitor strategic flexibility usage to maintain ≥80% appropriate usage');
-    suggestions.push('Consider if semantic token alternative would be more appropriate');
-    suggestions.push('Document rationale for strategic flexibility usage');
-    suggestions.push('Review if usage pattern indicates need for new semantic token');
-
-    return suggestions;
-  }
-
-  /**
-   * Check if token category requires baseline grid alignment
-   */
-  private requiresBaselineGridAlignment(category: TokenCategory): boolean {
-    return category === TokenCategory.SPACING || category === TokenCategory.RADIUS;
-  }
-
-  /**
-   * Generate comprehensive mathematical explanation
-   */
-  generateComprehensiveExplanation(context: ReasoningContext): {
-    reasoning: string;
-    suggestions: string[];
-    mathematicalDetails: string;
-  } {
-    const reasoning = this.generatePassReasoning(context);
-    const suggestions = this.generateSuggestions(context);
-
-    // Generate detailed mathematical explanation
-    const mathematicalDetails = this.generateMathematicalDetails(context);
-
-    return {
-      reasoning,
-      suggestions,
-      mathematicalDetails
-    };
-  }
-
-  /**
-   * Generate detailed mathematical explanation
-   */
-  private generateMathematicalDetails(context: ReasoningContext): string {
-    const { token, contextData } = context;
-    const details: string[] = [];
-
-    if ('baseValue' in token) {
-      // Primitive token details
-      details.push(`Base value: ${token.baseValue} (unitless)`);
-      details.push(`Family base: ${token.familyBaseValue}`);
-      details.push(`Category: ${token.category}`);
-
-      if (token.mathematicalRelationship) {
-        details.push(`Relationship: ${token.mathematicalRelationship}`);
-      }
-    } else {
-      // Semantic token details
-      const references = Object.entries(token.primitiveReferences);
-      
-      // For single 'default' reference, show simplified format
-      if (references.length === 1 && references[0][0] === 'default') {
-        details.push(`Semantic reference: ${references[0][1]}`);
-      } else {
-        // For multi-primitive or non-default keys, show full format
-        const referenceList = references
-          .map(([key, ref]) => `${key}: ${ref}`)
-          .join(', ');
-        details.push(`Semantic references: ${referenceList}`);
-      }
-      
-      details.push(`Category: ${token.category}`);
-      details.push(`Context: ${token.context}`);
-    }
-
-    // Add contextual mathematical details
-    if (contextData?.baselineGridInfo) {
-      const { gridUnit, isAligned } = contextData.baselineGridInfo;
-      details.push(`Baseline grid (${gridUnit}px): ${isAligned ? 'aligned' : 'not aligned'}`);
-    }
-
-    return details.join('; ');
-  }
-}

package/src/validators/WCAGValidator.ts

@@ -1,219 +0,0 @@
-/**
- * WCAG Validator
- * 
- * Validates accessibility tokens against WCAG (Web Content Accessibility Guidelines)
- * success criteria to ensure compliance with accessibility standards.
- * 
- * WCAG References:
- * - 2.4.7 Focus Visible (Level AA): Keyboard focus indicator must be visible
- * - 1.4.11 Non-text Contrast (Level AA): UI components must have 3:1 contrast minimum
- * 
- * @see https://www.w3.org/WAI/WCAG21/quickref/
- */
-
-export interface WCAGValidationResult {
-  /** Validation level: 'pass', 'warning', or 'error' */
-  level: 'pass' | 'warning' | 'error';
-  
-  /** Human-readable validation message */
-  message: string;
-  
-  /** WCAG success criterion reference (optional) */
-  wcag?: string;
-  
-  /** Contrast ratio value (for contrast validations) */
-  contrastRatio?: number;
-}
-
-/**
- * WCAG Validator for accessibility token compliance
- */
-export class WCAGValidator {
-  /**
-   * Validate focus indicator contrast ratio
-   * 
-   * WCAG 1.4.11 Non-text Contrast (Level AA) requires a minimum 3:1 contrast ratio
-   * for UI components and graphical objects, including focus indicators.
-   * 
-   * @param focusColor - Focus indicator color (hex format)
-   * @param backgroundColor - Background color to compare against (hex format)
-   * @returns Validation result with contrast ratio and compliance status
-   * 
-   * @example
-   * ```typescript
-   * const result = validator.validateFocusContrast('#3B82F6', '#FFFFFF');
-   * // Returns: { level: 'pass', message: '...', contrastRatio: 3.14 }
-   * ```
-   */
-  validateFocusContrast(
-    focusColor: string,
-    backgroundColor: string
-  ): WCAGValidationResult {
-    const contrastRatio = this.calculateContrastRatio(focusColor, backgroundColor);
-    const minimumRatio = 3.0; // WCAG 1.4.11 Level AA requirement
-    
-    if (contrastRatio >= minimumRatio) {
-      return {
-        level: 'pass',
-        message: `Focus indicator contrast ratio ${contrastRatio.toFixed(2)}:1 meets WCAG 1.4.11 (minimum 3:1)`,
-        contrastRatio,
-      };
-    } else {
-      return {
-        level: 'error',
-        message: `Focus indicator contrast ratio ${contrastRatio.toFixed(2)}:1 fails WCAG 1.4.11 (minimum 3:1)`,
-        wcag: '1.4.11 Non-text Contrast (Level AA)',
-        contrastRatio,
-      };
-    }
-  }
-  
-  /**
-   * Validate focus indicator visibility
-   * 
-   * WCAG 2.4.7 Focus Visible (Level AA) requires that keyboard focus indicators
-   * are visible. This validation checks that offset and width values support
-   * visibility requirements.
-   * 
-   * @param offset - Focus indicator offset in pixels
-   * @param width - Focus indicator width in pixels
-   * @returns Validation result with visibility compliance status
-   * 
-   * @example
-   * ```typescript
-   * const result = validator.validateFocusVisibility(2, 2);
-   * // Returns: { level: 'pass', message: '...' }
-   * ```
-   */
-  validateFocusVisibility(
-    offset: number,
-    width: number
-  ): WCAGValidationResult {
-    const minimumWidth = 1; // Minimum 1px for visibility
-    const minimumOffset = 0; // Can be 0 or positive
-    
-    // Check for invalid values
-    if (width < minimumWidth) {
-      return {
-        level: 'error',
-        message: `Focus indicator width ${width}px is below minimum ${minimumWidth}px for visibility (WCAG 2.4.7)`,
-        wcag: '2.4.7 Focus Visible (Level AA)',
-      };
-    }
-    
-    if (offset < minimumOffset) {
-      return {
-        level: 'error',
-        message: `Focus indicator offset ${offset}px is negative, must be ${minimumOffset}px or greater (WCAG 2.4.7)`,
-        wcag: '2.4.7 Focus Visible (Level AA)',
-      };
-    }
-    
-    // Check for suboptimal but valid values
-    if (offset === 0 && width < 2) {
-      return {
-        level: 'warning',
-        message: `Focus indicator (${width}px width, ${offset}px offset) may have reduced visibility - consider 2px width with 2px offset for better clarity`,
-        wcag: '2.4.7 Focus Visible (Level AA)',
-      };
-    }
-    
-    // Valid configuration
-    return {
-      level: 'pass',
-      message: `Focus indicator (${width}px width, ${offset}px offset) meets WCAG 2.4.7 visibility requirements`,
-    };
-  }
-  
-  /**
-   * Calculate contrast ratio between two colors
-   * 
-   * Implements the WCAG contrast ratio formula:
-   * (L1 + 0.05) / (L2 + 0.05)
-   * where L1 is the relative luminance of the lighter color
-   * and L2 is the relative luminance of the darker color.
-   * 
-   * @param color1 - First color in hex format (#RRGGBB or #RGB)
-   * @param color2 - Second color in hex format (#RRGGBB or #RGB)
-   * @returns Contrast ratio (1:1 to 21:1)
-   * 
-   * @see https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html
-   * 
-   * @example
-   * ```typescript
-   * const ratio = validator.calculateContrastRatio('#000000', '#FFFFFF');
-   * // Returns: 21 (maximum contrast)
-   * ```
-   */
-  calculateContrastRatio(color1: string, color2: string): number {
-    const luminance1 = this.getRelativeLuminance(color1);
-    const luminance2 = this.getRelativeLuminance(color2);
-    
-    const lighter = Math.max(luminance1, luminance2);
-    const darker = Math.min(luminance1, luminance2);
-    
-    return (lighter + 0.05) / (darker + 0.05);
-  }
-  
-  /**
-   * Calculate relative luminance of a color
-   * 
-   * Implements the WCAG relative luminance formula:
-   * L = 0.2126 * R + 0.7152 * G + 0.0722 * B
-   * where R, G, and B are the linearized RGB values.
-   * 
-   * @param hexColor - Color in hex format (#RRGGBB or #RGB)
-   * @returns Relative luminance (0 to 1)
-   * 
-   * @private
-   */
-  private getRelativeLuminance(hexColor: string): number {
-    // Parse hex color to RGB
-    const rgb = this.hexToRgb(hexColor);
-    
-    // Convert RGB values to linear RGB (remove gamma correction)
-    const linearRgb = rgb.map(channel => {
-      const normalized = channel / 255;
-      return normalized <= 0.03928
-        ? normalized / 12.92
-        : Math.pow((normalized + 0.055) / 1.055, 2.4);
-    });
-    
-    // Calculate relative luminance using WCAG formula
-    return 0.2126 * linearRgb[0] + 0.7152 * linearRgb[1] + 0.0722 * linearRgb[2];
-  }
-  
-  /**
-   * Convert hex color to RGB array
-   * 
-   * Supports both 3-digit (#RGB) and 6-digit (#RRGGBB) hex formats.
-   * 
-   * @param hexColor - Color in hex format
-   * @returns RGB array [r, g, b] with values 0-255
-   * 
-   * @private
-   */
-  private hexToRgb(hexColor: string): [number, number, number] {
-    // Remove # prefix if present
-    const hex = hexColor.replace(/^#/, '');
-    
-    // Handle 3-digit hex format (#RGB)
-    if (hex.length === 3) {
-      const r = parseInt(hex[0] + hex[0], 16);
-      const g = parseInt(hex[1] + hex[1], 16);
-      const b = parseInt(hex[2] + hex[2], 16);
-      return [r, g, b];
-    }
-    
-    // Handle 6-digit hex format (#RRGGBB)
-    if (hex.length === 6) {
-      const r = parseInt(hex.substring(0, 2), 16);
-      const g = parseInt(hex.substring(2, 4), 16);
-      const b = parseInt(hex.substring(4, 6), 16);
-      return [r, g, b];
-    }
-    
-    // Invalid format - return black as fallback
-    return [0, 0, 0];
-  }
-}