/**
 * Context Types
 *
 * Types for the context management system.
 */

/**
 * Entity type in the context
 */
export type EntityType = 'Function' | 'Class' | 'File';

/**
 * A single context item representing a code entity
 */
export interface ContextItem {
  /** Fully qualified name (e.g., "module.ClassName.method") */
  qualifiedName: string;
  /** Type of entity */
  entityType: EntityType;
  /** Description (docstring/comment) */
  description?: string;
  /** Absolute file path */
  filePath?: string;
  /** Relevance score (0.0 - 1.0) */
  score: number;
  /** Number of times this entity has appeared in context */
  touchCount: number;
  /** When this entity was last updated */
  lastTouched: Date;
  /** Related entities (callers, callees, etc.) */
  neighbors: string[];
  /** Source provider that discovered this item */
  source?: string;
}

/**
 * Session context container
 */
export interface SessionContext {
  /** Unique session ID */
  sessionId: string;
  /** Terminal/user identifier */
  terminalId: string;
  /** All context items in this session */
  items: ContextItem[];
  /** When session was created */
  createdAt: Date;
  /** When session was last active */
  lastActive: Date;
}

/**
 * Exploration step from agent tool usage
 */
export interface ExplorationStep {
  /** Name of the tool used */
  toolName: string;
  /** Entities discovered by this tool */
  entitiesDiscovered: string[];
  /** Optional: position in search results (for search tools) */
  resultPositions?: Map<string, number>;
}

/**
 * Context provider specification
 */
export interface ContextProviderSpec {
  /** Provider name */
  name: string;
  /** Human-readable description */
  description: string;
  /** Whether this provider requires graph connection */
  requiresGraph: boolean;
}

/**
 * Options for context retrieval
 */
export interface ContextRetrievalOptions {
  /** Minimum score threshold (default: 0.5) */
  minScore?: number;
  /** Maximum items to return (default: 50) */
  maxItems?: number;
  /** Query to re-rank by (optional) */
  query?: string;
  /** Whether to apply re-ranking (default: true if query provided) */
  rerank?: boolean;
}

/**
 * Options for context update
 */
export interface ContextUpdateOptions {
  /** Exploration steps from agent */
  explorationSteps?: ExplorationStep[];
  /** Modified file paths */
  modifiedFiles?: string[];
  /** Decay factor for existing scores (default: 0.8) */
  decayFactor?: number;
}

/**
 * Reranker score breakdown
 */
export interface ScoreBreakdown {
  /** Base score from tool relevance */
  base: number;
  /** Text match score */
  text: number;
  /** Graph-based boost */
  graph: number;
  /** Session recency/frequency boost */
  session: number;
  /** Neighbor match boost */
  neighbor: number;
  /** Longevity boost */
  longevity: number;
  /** File co-occurrence boost */
  fileCooccurrence: number;
  /** Final combined score */
  total: number;
}

/**
 * Scored context item with breakdown
 */
export interface ScoredContextItem {
  item: ContextItem;
  breakdown: ScoreBreakdown;
}

/**
 * Context configuration
 */
export interface ContextConfig {
  /** Minimum score threshold */
  minScore: number;
  /** Maximum items in context */
  maxItems: number;
  /** Score decay factor per update */
  decayFactor: number;
  /** AST neighbor depth to fetch */
  neighborDepth: number;
  /** Whether reranking is enabled */
  rerankEnabled: boolean;
  /** Top-K items after reranking */
  rerankTopK: number;
}

/**
 * Default context configuration
 */
export const DEFAULT_CONTEXT_CONFIG: ContextConfig = {
  minScore: 0.5,
  maxItems: 50,
  decayFactor: 0.8,
  neighborDepth: 2,
  rerankEnabled: true,
  rerankTopK: 20,
};

/**
 * Get config from environment variables
 */
export function getContextConfig(): ContextConfig {
  return {
    minScore: parseFloat(process.env.CONTEXT_MIN_SCORE ?? '0.5'),
    maxItems: parseInt(process.env.CONTEXT_MAX_ITEMS ?? '50', 10),
    decayFactor: parseFloat(process.env.CONTEXT_DECAY_FACTOR ?? '0.8'),
    neighborDepth: parseInt(process.env.CONTEXT_NEIGHBOR_DEPTH ?? '2', 10),
    rerankEnabled: process.env.CONTEXT_RERANK_ENABLED !== 'false',
    rerankTopK: parseInt(process.env.CONTEXT_RERANK_TOP_K ?? '20', 10),
  };
}
