/**
 * packages/extract/src/token-source/types.ts — public type surface.
 * Exports: RepoTreeEntry, ParsedToken, HardcodedFinding, DuplicateFinding,
 *   TokenExtractionProgress, TokenExtractionResult, TokenTier,
 *   TokenProvenanceConfig.
 * See ./INDEX.md for split rationale.
 */

export interface RepoTreeEntry {
  path: string;
  type: 'blob' | 'tree';
  size?: number;
}

/**
 * Classification tier for a parsed token.
 *
 * - **canonical**: Public API of the design system — the tokens consumers
 *   are expected to use. Identified by matching the detected prefix and/or
 *   living in a primary token source file.
 * - **extended**: Build intermediates, consumer overrides, or tokens from
 *   secondary sources. Real values, but not the headline count.
 * - **unknown**: Insufficient signal to classify. Treated as canonical in
 *   display when no provenance config is available.
 */
export type TokenTier = 'canonical' | 'extended' | 'unknown';

/**
 * Optional provenance hints passed into extraction. When absent the
 * classifier assigns 'unknown' to every token (backward compatible —
 * same behavior as before tiers existed).
 */
export interface TokenProvenanceConfig {
  primarySources?: string[];
  allSources?: string[];
  prefix?: string;
  appPaths?: string[];
}

export interface ParsedToken {
  name: string;
  value: string;
  category: string;
  file: string;
  line: number;
  tier: TokenTier;
  identityKey: string;
}

export interface HardcodedFinding {
  file: string;
  line: number;
  property: string;
  hardcodedValue: string;
  suggestedToken: string;
  suggestedTokenValue: string;
  category: string;
  fingerprint: string;
}

export interface TokenExtractionProgress {
  phase: 'tokens' | 'hardcoded';
  filesProcessed: number;
  totalFiles: number;
  tokensFound: number;
  hardcodedFound: number;
}

export interface DuplicateFinding {
  value: string;
  tokenNames: string[];
  files: string[];
  category: string;
  fingerprint: string;
}

export interface TokenExtractionResult {
  tokenPayload: string;
  tokenCount: number;
  /** Count of tokens classified as canonical (equals tokenCount when no provenance config). */
  canonicalCount: number;
  tokenFileCount: number;
  hardcodedFindings: HardcodedFinding[];
  duplicateFindings: DuplicateFinding[];
  /** Raw parsed tokens for downstream detection/aggregation. */
  parsedTokens: ParsedToken[];
}
