/**
 * Shared contract for the design-system conform engine.
 *
 * These types are the single source of truth for the conform pipeline:
 * - `@fragments-sdk/extract` implements `conformSnippet(input, context)`.
 * - `@fragments-sdk/mcp` re-exports the result types as the tool contract.
 * - Cloud / CLI / standalone-MCP each build a `DesignSystemContext` from their
 *   own data source (Convex catalog, local config, bundle) and call the engine.
 *
 * Keeping them here (a browser-safe, dependency-light package) lets every
 * surface agree on one shape without duplication.
 */

export type ConformConfidence = "high" | "medium" | "low";

export interface ConformInput {
  /** UI code to conform: JSX/TSX, HTML, or a CSS/SCSS block. */
  code: string;
  /** Filename or extension hint used to pick the parser (defaults to TSX). */
  filename?: string;
  /** deterministic (default) applies safe edits; none returns findings only. */
  apply?: "deterministic" | "none";
}

export interface ConformLocation {
  line?: number;
  column?: number;
  endLine?: number;
  endColumn?: number;
}

export interface ConformChange {
  kind: "swap-component" | "rewrite-import" | "rename-prop" | "replace-token" | "add-fallback";
  ruleId?: string;
  /** Versioned diagnostic code, e.g. FUI0601. */
  code?: string;
  severity: "error" | "warning" | "info";
  message: string;
  before?: string;
  after?: string;
  /** Canonical primitive involved in the change, when applicable. */
  canonical?: string;
  confidence: ConformConfidence;
  location?: ConformLocation;
}

export interface ConformSuggestion {
  kind:
    | "map-prop-value"
    | "choose-among-alternates"
    | "review-low-confidence"
    | "flag-accessibility";
  message: string;
  canonical?: string;
  hint?: string;
  confidence: ConformConfidence;
  location?: ConformLocation;
}

export interface ConformUnresolved {
  element?: string;
  canonical?: string;
  reason: string;
  location?: ConformLocation;
}

export interface ConformPropMapping {
  rawProp: string;
  canonicalProp: string;
  /**
   * Confirmed value translation table for cross-library prop values, e.g.
   * `{ primary: "brand" }` to rewrite `color="primary"` into `variant="brand"`.
   * A value is only rewritten when it exactly matches a key here; anything else
   * is surfaced as a `map-prop-value` suggestion rather than guessed.
   */
  valueMap?: Record<string, string>;
}

export interface ConformComponentMapping {
  /**
   * Canonical primitive name, e.g. "Button". This is the JSX identifier the
   * conform engine rewrites toward.
   */
  name: string;
  /** Stable canonical vocabulary label when it differs from the component name. */
  canonical?: string;
  /** Native HTML element this component replaces, e.g. "button". */
  htmlEquivalent?: string;
  /** Import source to add or prefer for the canonical component. */
  importPath?: string;
  /** Confirmed prop renames from raw usage to the canonical component API. */
  propMapping?: ConformPropMapping[];
  /** Classifier confidence, when known. Only confirmed mappings should be passed. */
  confidence?: number;
}

export interface ConformResult {
  /** Code with deterministic edits applied, or the original if apply=none / parse failed. */
  conformed: string;
  changed: boolean;
  summary: string;
  designSystem?: {
    name?: string;
    importsAdded: string[];
  };
  /** Applied, deterministic edits. */
  changes: ConformChange[];
  /** Items needing agent judgment (e.g. cross-library prop-value translation). */
  suggestions: ConformSuggestion[];
  /** Elements/values with no design-system equivalent. */
  unresolved: ConformUnresolved[];
  /**
   * How much of the tenant's design system this run could evaluate against.
   * `evaluated` is false when the catalog supplied no tokens and no usable
   * component mappings — in that case a "clean" result proves nothing, so
   * callers (e.g. `prove_compliant`) must not certify compliance.
   */
  coverage?: ConformCoverage;
}

export interface ConformCoverage {
  /** Count of relevant tokens (color/spacing/radius) the engine evaluated against. */
  tokens: number;
  /** Count of usable component mappings the engine evaluated against. */
  components: number;
  /** True when there was at least one token or component to evaluate against. */
  evaluated: boolean;
}

/**
 * A design-system token as the conform engine consumes it. Each surface maps
 * its own token model into this shape.
 */
export interface ConformToken {
  /** Raw value to match against code, e.g. "#2563eb". */
  value: string;
  /**
   * The authored CSS custom property, e.g. "--brand-600", when known. A token
   * is only eligible for an automatic rewrite when this is present — the engine
   * never guesses a variable name.
   */
  cssVar?: string;
  /** Token category, e.g. "color" | "spacing". */
  category?: string;
  /** Human-readable label for suggestions, e.g. "color.brand.600". */
  label?: string;
  /** Tie-break ordering when two tokens share a value: "canonical" wins. */
  tier?: string;
}

/**
 * Everything the conform engine needs about a tenant's design system. Built by
 * each surface (cloud from Convex, CLI from local config, MCP from a bundle).
 */
export interface DesignSystemContext {
  designSystemName?: string;
  tokens: ConformToken[];
  /** Confirmed canonical component replacements for this tenant. */
  components?: ConformComponentMapping[];
}