/**
 * Design Token Types for Fragments
 *
 * These types define the structure for CSS custom property (CSS variable) discovery,
 * parsing, and reverse lookup capabilities. The token system enables:
 *
 * 1. Automatic discovery of design tokens from CSS/SCSS files
 * 2. Reverse lookup: given a computed value, find which token(s) produce it
 * 3. Detection of hardcoded values vs token usage
 * 4. AI-friendly fix suggestions
 */

/**
 * Token categories for grouping and filtering
 */
export type TokenCategory =
  | "color"
  | "spacing"
  | "typography"
  | "radius"
  | "shadow"
  | "sizing"
  | "border"
  | "animation"
  | "z-index"
  | "other";

/**
 * A single design token (CSS custom property)
 */
export interface DesignToken {
  /** Token name with leading dashes (e.g., "--color-primary") */
  name: string;

  /** Raw value as written in CSS (e.g., "var(--color-cobalt-50)") */
  rawValue: string;

  /** Fully resolved value (e.g., "#0051c2") */
  resolvedValue: string;

  /** Inferred category based on naming convention */
  category: TokenCategory;

  /**
   * Token level in the design system hierarchy:
   * - 1 = Base/primitive tokens (raw values like colors, sizes)
   * - 2 = Semantic tokens (references to base tokens with meaning)
   * - 3 = Component tokens (component-specific tokens)
   */
  level: 1 | 2 | 3;

  /**
   * Reference chain showing how the value was resolved
   * e.g., ["--color-primary", "--color-cobalt-50"] means
   * --color-primary references --color-cobalt-50
   */
  referenceChain: string[];

  /** Source file where this token was defined */
  sourceFile: string;

  /** Line number in source file */
  lineNumber?: number;

  /** Theme this token belongs to (e.g., "default", "dark", "light") */
  theme: string;

  /** CSS selector where this token is defined (e.g., ":root", "[data-theme='dark']") */
  selector: string;

  /** Optional description from comments */
  description?: string;
}

/**
 * Token registry for fast lookups
 */
export interface TokenRegistry {
  /** Lookup by token name (e.g., "--color-primary") */
  byName: Map<string, DesignToken>;

  /**
   * REVERSE lookup: resolved value -> token names
   * Key is normalized value (e.g., "#0051c2" lowercase)
   * Value is array of token names that resolve to this value
   */
  byValue: Map<string, string[]>;

  /** Tokens grouped by theme */
  byTheme: Map<string, DesignToken[]>;

  /** Tokens grouped by category */
  byCategory: Map<TokenCategory, DesignToken[]>;

  /** Registry metadata */
  meta: TokenRegistryMeta;
}

/**
 * Token registry metadata
 */
export interface TokenRegistryMeta {
  /** When tokens were discovered */
  discoveredAt: Date;

  /** Source files that were parsed */
  sourceFiles: string[];

  /** Total number of tokens discovered */
  totalTokens: number;

  /** Time taken to parse (ms) */
  parseTimeMs: number;

  /** Number of circular references detected */
  circularRefs: number;

  /** Number of unresolved references */
  unresolvedRefs: number;
}

/**
 * Enhanced style diff item with token information
 */
export interface EnhancedStyleDiffItem {
  /** CSS property name (e.g., "backgroundColor") */
  property: string;

  /** Value from Figma design */
  figma: string;

  /** Value from rendered component */
  rendered: string;

  /** Whether values match (within tolerance) */
  match: boolean;

  /** Token name if Figma value matches a known token */
  figmaToken?: string;

  /** Token name if rendered value uses a token */
  renderedToken?: string;

  /**
   * True if rendered value doesn't use a token but should
   * (i.e., Figma uses a token but code uses hardcoded value)
   */
  isHardcoded: boolean;

  /** Suggested fix if hardcoded */
  suggestedFix?: TokenFix;
}

/**
 * Token-based fix suggestion
 */
export interface TokenFix {
  /** Token name to use (e.g., "--color-primary") */
  tokenName: string;

  /** Token's resolved value */
  tokenValue: string;

  /** Code snippet to fix the issue */
  codeFix: string;

  /** Confidence score 0-1 */
  confidence: number;

  /** Human-readable explanation */
  reason: string;
}

/**
 * Configuration for token discovery
 */
export interface TokenConfig {
  /**
   * Glob patterns for files to scan for tokens
   * e.g., ["src/styles/theme.scss", "src/styles/variables.css"]
   */
  include: string[];

  /**
   * Glob patterns to exclude
   * @example ["node_modules"]
   */
  exclude?: string[];

  /**
   * Map CSS selectors to theme names
   * @example { ":root": "default", "[data-theme='dark']": "dark" }
   */
  themeSelectors?: Record<string, string>;

  /** Enable token comparison in style diffs (default: true) */
  enabled?: boolean;
}

/**
 * Result of parsing a CSS/SCSS file for tokens
 */
export interface TokenParseResult {
  /** Tokens discovered in the file */
  tokens: DesignToken[];

  /** Errors encountered during parsing */
  errors: TokenParseError[];

  /** Warnings (non-fatal issues) */
  warnings: string[];

  /** Parse time in ms */
  parseTimeMs: number;
}

/**
 * Error during token parsing
 */
export interface TokenParseError {
  /** Error message */
  message: string;

  /** File where error occurred */
  file: string;

  /** Line number if known */
  line?: number;

  /** The problematic content if available */
  content?: string;
}

/**
 * Request to match a value to tokens
 */
export interface TokenMatchRequest {
  /** The value to find tokens for (e.g., "#0051c2") */
  value: string;

  /** Property type hint for better matching (e.g., "color") */
  propertyType?: "color" | "spacing" | "typography" | "other";

  /** Specific theme to search in */
  theme?: string;
}

/**
 * Result of token matching
 */
export interface TokenMatchResult {
  /** Exact matches (same resolved value) */
  exactMatches: DesignToken[];

  /** Close matches (similar value, useful for colors) */
  closeMatches: Array<{
    token: DesignToken;
    /** How close the match is (0-1, 1 = exact) */
    similarity: number;
  }>;

  /** Whether any match was found */
  found: boolean;
}

/**
 * Summary of token usage in a component
 */
export interface TokenUsageSummary {
  /** Total CSS properties checked */
  totalProperties: number;

  /** Properties using design tokens */
  usingTokens: number;

  /** Properties with hardcoded values */
  hardcoded: number;

  /** Properties matching but not using tokens explicitly */
  implicitMatches: number;

  /** Compliance percentage (usingTokens / totalProperties * 100) */
  compliancePercent: number;

  /** List of hardcoded properties with fix suggestions */
  hardcodedProperties: EnhancedStyleDiffItem[];
}