/**
 * Pure types for Storybook CSF parsing.
 *
 * These describe the shape extracted from a story file's *content* — no
 * filesystem concepts. The CLI's migrate tool layers fs-backed types
 * (ConversionResult, MigrationReport, MigrateOptions) on top of these.
 */

/** Parsed Storybook story metadata (the default export). */
export interface ParsedMeta {
  /** Full title path (e.g., "Components/Forms/Input"). */
  title: string;
  /** Component name (inferred from title or component ref). */
  componentName: string;
  /** Component import path. */
  componentImport?: string;
  /** Whether the component uses a default import (export default). */
  isDefaultImport?: boolean;
  /** Tags from the story. */
  tags?: string[];
  /** Description from parameters.docs. */
  description?: string;
}

/** Parsed argType definition. */
export interface ParsedArgType {
  /** Storybook control type. */
  control?: string;
  /** Options for select/radio controls. */
  options?: string[];
  /** Prop description. */
  description?: string;
  /** Default value. */
  defaultValue?: unknown;
  /** TypeScript type (if available). */
  type?: string;
  /** Whether the prop is required. */
  required?: boolean;
}

/** Parsed individual story. */
export interface ParsedStory {
  /** Story name (export name). */
  name: string;
  /** Args passed to the component. */
  args: Record<string, unknown>;
  /** Story description. */
  description?: string;
  /** Whether story has a custom render function. */
  hasCustomRender?: boolean;
  /** Raw render code if extractable. */
  renderCode?: string;
}

/** Complete parsed story file. */
export interface ParsedStoryFile {
  /** Original file path (informational only — never read by the parser). */
  filePath: string;
  /** Parsed metadata. */
  meta: ParsedMeta;
  /** Parsed argTypes. */
  argTypes: Record<string, ParsedArgType>;
  /** Parsed stories. */
  stories: ParsedStory[];
  /** Parse warnings. */
  warnings: string[];
  /** Confidence score (0-1) — how reliable the extraction was. */
  confidence: number;
}

export type StoryFactsRung = "full" | "partial" | "presence-only" | "skipped";

export interface StoryComponentImport {
  specifier: string;
  name: string;
}

export interface StoryFactsStory {
  ref: string;
  name: string;
  args?: Record<string, unknown>;
}

export interface StoryFactsDiagnostic {
  level: "warning" | "error";
  message: string;
}

/**
 * Locked Storybook parse seam used by downstream contract ingestion.
 *
 * This shape is additive-only after brief 02: stories are evidence for an
 * existing component identity, never a component identity by themselves.
 */
export interface StoryFacts {
  file: string;
  title?: string;
  componentImport?: StoryComponentImport;
  tags: string[];
  metaArgs: Record<string, unknown>;
  argTypes: Record<string, ParsedArgType>;
  stories: StoryFactsStory[];
  rung: StoryFactsRung;
  diagnostics: StoryFactsDiagnostic[];
  autodocsDescription?: string;
}

/** Detected Storybook configuration. */
export interface StorybookConfig {
  /** Path to .storybook/main.* */
  configPath: string;
  /** Story glob patterns from config. */
  storyPatterns: string[];
  /** Detected framework (react, vue, etc.). */
  framework?: string;
  /** Detected builder (vite, webpack). */
  builder?: string;
  /** Whether config was successfully parsed. */
  valid: boolean;
  /** Parse errors if any. */
  errors?: string[];
}
