/**
 * Unified Types for Vreko Dashboard Webview
 *
 * These types mirror the WorkspaceDataSnapshot from WorkspaceDataService.
 * Since webviews run in a browser context, they cannot import directly from
 * extension code, so types are re-declared here.
 *
 * @see apps/vscode/src/services/WorkspaceDataService.ts for source definitions
 * @packageDocumentation
 */

// =============================================================================
// DATASECTION<T> ENVELOPE (for graceful degradation)
// =============================================================================

/**
 * Status envelope for data sections with loading/error/stale states.
 * Mirrors DataSection from @vreko/contracts/local-service.
 *
 * @example
 * ```typescript
 * const section: DataSection<FragileFileData[]> = {
 *   status: "ready",
 *   data: [{ filePath: "auth.ts", fragilityScore: 0.8 }],
 *   fetchedAt: Date.now()
 * };
 * ```
 */
export type DataSection<T> =
	| { status: "loading" }
	| { status: "ready"; data: T; fetchedAt: number }
	| { status: "error"; error: string; staleData?: T; fetchedAt?: number }
	| { status: "stale"; data: T; fetchedAt: number };

// =============================================================================
// DASHBOARD TAB TYPES
// =============================================================================

/**
 * Valid dashboard tabs - matches DashboardTab in UnifiedDashboardPanel.ts
 * Note: "home" and "vitals" are legacy aliases that resolve to "intelligence"
 */
export type DashboardTab = "home" | "vitals" | "activity" | "settings" | "welcome" | "intelligence";

/**
 * Resolved tab type (after alias mapping)
 */
export type ResolvedTab = "intelligence" | "activity" | "welcome" | "settings";

/**
 * Resolves legacy tab names to their current equivalents.
 * Per UX v3 spec: "home" and "vitals" map to "intelligence"
 */
export function resolveTab(tab: DashboardTab): ResolvedTab {
	if (tab === "home" || tab === "vitals") {
		return "intelligence";
	}
	return tab;
}

/**
 * Tab configuration item
 */
export interface TabConfig {
	id: DashboardTab;
	label: string;
	icon: string;
}

// =============================================================================
// WEBVIEW PERSISTED STATE (for getState/setState)
// =============================================================================

/**
 * State persisted across webview reloads via VS Code's getState/setState API.
 * Data is always re-fetched; only UI state is persisted.
 */
export interface WebviewPersistedState {
	/** Currently active tab */
	activeTab: DashboardTab;
	/** Scroll positions per section (key = section ID) */
	scrollPositions: Record<string, number>;
	/** Filter selections for activity timeline */
	filterSelections: FilterState;
	/** Which collapsible sections are expanded */
	expandedSections: string[];
}

/**
 * Filter state for activity timeline
 */
export interface FilterState {
	dateRange: "today" | "yesterday" | "week" | "all";
	riskLevel: "all" | "high" | "medium" | "low";
	toolFilter: "all" | "cursor" | "claude" | "copilot";
	groupBySession: boolean;
}

// =============================================================================
// STATS TYPES (from WorkspaceDataService.DashboardStats)
// =============================================================================

/**
 * Stats aggregation for dashboard home tab
 */
export interface DashboardStats {
	snapshotsToday: number;
	totalSnapshots: number;
	restoresToday: number;
	linesProtected: number;
	tokensSaved: number;
	restoresThisWeek: number;
	efficiencyPercentile: number;
}

// =============================================================================
// ACTIVITY TYPES (from WorkspaceDataService.ActivityData)
// =============================================================================

/**
 * Activity timeline event
 */
export interface ActivityEvent {
	id: string;
	type: "ai-edit" | "manual-snapshot" | "auto-snapshot" | "restore";
	file: string;
	timestamp: number;
	aiTool?: string;
	details?: string;
}

/**
 * AI detection log entry
 */
export interface AIDetectionEntry {
	tool: string;
	sessions: number;
	accuracy: number;
	lastDetected: number;
}

/**
 * Activity data for activity tab
 */
export interface ActivityData {
	timeline: ActivityEvent[];
	aiDetectionLog: AIDetectionEntry[];
	todayEvents: number;
	yesterdayEvents: number;
	weekEvents: number;
}

// =============================================================================
// VITALS TYPES
// =============================================================================

/**
 * Backend vitals data structure (nested format from WorkspaceDataService.VitalsData)
 */
export interface BackendVitalsData {
	pulse: { changesPerMinute: number; level: string };
	temperature: { aiPercentage: number; level: string };
	pressure: { value: number };
	oxygen: { value: number };
	trajectory: string;
}

/**
 * UI vitals data structure (flat format for @vreko/ui WorkspaceVitals component)
 * @see packages/ui/src/vitals/WorkspaceVitals.tsx
 */
export interface UIVitalsData {
	pulse: number;
	temperature: number;
	pressure: number;
	oxygen: number;
	score: number;
}

/**
 * Session health metrics (from WorkspaceDataService.SessionHealth)
 */
export interface SessionHealth {
	healthScore: number;
	trajectory: "improving" | "stable" | "degrading" | "critical";
	activeWarnings: string[];
	lastSnapshotMinutesAgo: number | null;
	suggestions: string[];
}

/**
 * Snapshot recommendation (from WorkspaceDataService.SnapshotRecommendation)
 */
export interface SnapshotRecommendation {
	should: boolean;
	reason: string;
	urgency: "now" | "soon" | "optional";
}

/**
 * Agent guidance for safe operations (from WorkspaceDataService.AgentGuidance)
 */
export interface AgentGuidance {
	safeOperations: string[];
	blockedOperations: string[];
	suggestion: string;
}

/**
 * UI guidance format (for @vreko/ui WorkspaceVitals component)
 */
export interface UIGuidance {
	message: string;
}

// =============================================================================
// LEARNINGS / VIOLATIONS / PATTERNS
// =============================================================================

/**
 * Learning entry (from WorkspaceDataService.Learning)
 */
export interface Learning {
	id: string;
	type: "pattern" | "pitfall" | "efficiency" | "discovery" | "workflow";
	trigger: string;
	action: string;
	source: string;
	createdAt: string;
}

/**
 * Violation entry (from WorkspaceDataService.Violation)
 */
export interface Violation {
	type: string;
	file: string;
	message: string;
	count: number;
	date: string;
	prevention?: string;
	promotionStatus: "tracking" | "ready_for_promotion" | "promoted" | "automated";
}

/**
 * Pattern entry (from WorkspaceDataService.WorkspacePattern)
 */
export interface WorkspacePattern {
	type: string;
	description: string;
	prevention: string;
	occurrences: number;
	promotedAt: string;
	lastSeenAt: string;
}

// =============================================================================
// MCP CONNECTION TYPES
// =============================================================================

/**
 * MCP connection status (from WorkspaceDataService.MCPConnectionInfo)
 */
export interface MCPConnectionInfo {
	state: "connected" | "disconnected" | "reconnecting" | "cli_missing";
	daemonVersion?: string;
	attempt?: number;
	maxAttempts?: number;
}

// =============================================================================
// MESSAGE PROTOCOL TYPES
// =============================================================================

/**
 * Message from extension to webview (update message payload)
 * Matches the postMessage format in UnifiedDashboardPanel.sendDataToWebview()
 */
export interface UpdateMessagePayload {
	type: "update";
	stats: DashboardStats;
	activity: ActivityData;
	settings: SettingsState;
	vitals: BackendVitalsData | null;
	sessionHealth: SessionHealth;
	recommendation: SnapshotRecommendation;
	guidance: AgentGuidance;
	learnings: Learning[];
	violations: Violation[];
	patterns: WorkspacePattern[];
	mcpConnection: MCPConnectionInfo;
	// NEW: Intelligence data from local-service
	intelligence?: {
		fragileFiles?: {
			items: Array<{
				filePath: string;
				fragilityScore: number;
				severity: "moderate" | "high" | "critical";
				reason: string;
				suggestion: string;
				rollbackCount: number;
				aiChurnCount: number;
			}>;
			total: number;
		};
		coChanges?: {
			items: Array<{
				fileA: string;
				fileB: string;
				frequency: number;
				occurrences: number;
				relationship: string;
				reason: string;
				lastObserved: string;
			}>;
			total: number;
		};
		health?: {
			score: number;
			trajectory: "improving" | "stable" | "declining";
			warningCount: number;
		};
		warnings?: {
			items: Array<{
				id: string;
				message: string;
				severity: "info" | "warning" | "error";
				filePath?: string;
				suggestion?: string;
			}>;
			total: number;
		};
		summary?: {
			learningsCount: number;
			patternsCount: number;
			fragileFilesCount: number;
			coChangePatternsCount: number;
			totalSessions: number;
			linesAnalyzed: number;
			healthScore: number;
			healthTrajectory: string;
		};
	};
}

/**
 * Navigate message from extension to webview
 */
export interface NavigateMessage {
	type: "navigate";
	tab: DashboardTab;
}

/**
 * Union of all extension-to-webview message types
 */
export type ExtensionMessage = UpdateMessagePayload | NavigateMessage;

// =============================================================================
// SETTINGS STATE (from WorkspaceDataService.SettingsState)
// =============================================================================

/**
 * Settings state for setup tab
 */
export interface SettingsState {
	detectedAITool: string | null;
	cliInstalled: boolean;
	cliVersion: string | null;
	protectionThreshold: "low" | "medium" | "high";
	excludePatterns: string[];
	languagePacks: Array<{ name: string; enabled: boolean; builtin: boolean }>;
}
