tsdoc/ts/context/types.ts

/**
 * Context processing mode to control how context is built
 */
export type ContextMode = 'full' | 'trimmed' | 'summarized';

/**
 * Configuration for context trimming
 */
export interface ITrimConfig {
  /** Whether to remove function implementations */
  removeImplementations?: boolean;
  /** Whether to preserve interface definitions */
  preserveInterfaces?: boolean;
  /** Whether to preserve type definitions */
  preserveTypeDefs?: boolean;
  /** Whether to preserve JSDoc comments */
  preserveJSDoc?: boolean;
  /** Maximum lines to keep for function bodies (if not removing completely) */
  maxFunctionLines?: number;
  /** Whether to remove normal comments (non-JSDoc) */
  removeComments?: boolean;
  /** Whether to remove blank lines */
  removeBlankLines?: boolean;
}

/**
 * Task types that require different context optimization
 */
export type TaskType = 'readme' | 'commit' | 'description';

/**
 * Configuration for different tasks
 */
export interface ITaskConfig {
  /** The context mode to use for this task */
  mode?: ContextMode;
  /** File paths to include for this task */
  includePaths?: string[];
  /** File paths to exclude for this task */
  excludePaths?: string[];
  /** For commit tasks, whether to focus on changed files */
  focusOnChangedFiles?: boolean;
  /** For description tasks, whether to include package info */
  includePackageInfo?: boolean;
}

/**
 * Complete context configuration
 */
export interface IContextConfig {
  /** Maximum tokens to use for context */
  maxTokens?: number;
  /** Default context mode */
  defaultMode?: ContextMode;
  /** Task-specific settings */
  taskSpecificSettings?: {
    [key in TaskType]?: ITaskConfig;
  };
  /** Trimming configuration */
  trimming?: ITrimConfig;
  /** Cache configuration */
  cache?: ICacheConfig;
  /** Analyzer configuration */
  analyzer?: IAnalyzerConfig;
  /** Prioritization weights */
  prioritization?: IPrioritizationWeights;
  /** Tier configuration for adaptive trimming */
  tiers?: ITierConfig;
}

/**
 * Cache configuration
 */
export interface ICacheConfig {
  /** Whether caching is enabled */
  enabled?: boolean;
  /** Time-to-live in seconds */
  ttl?: number;
  /** Maximum cache size in MB */
  maxSize?: number;
  /** Cache directory path */
  directory?: string;
}

/**
 * Analyzer configuration
 */
export interface IAnalyzerConfig {
  /** Whether analyzer is enabled */
  enabled?: boolean;
  /** Whether to use AI refinement for selection */
  useAIRefinement?: boolean;
  /** AI model to use for refinement */
  aiModel?: string;
}

/**
 * Weights for file prioritization
 */
export interface IPrioritizationWeights {
  /** Weight for dependency centrality */
  dependencyWeight?: number;
  /** Weight for task relevance */
  relevanceWeight?: number;
  /** Weight for token efficiency */
  efficiencyWeight?: number;
  /** Weight for file recency */
  recencyWeight?: number;
}

/**
 * Tier configuration for adaptive trimming
 */
export interface ITierConfig {
  essential?: ITierSettings;
  important?: ITierSettings;
  optional?: ITierSettings;
}

/**
 * Settings for a single tier
 */
export interface ITierSettings {
  /** Minimum score to qualify for this tier */
  minScore: number;
  /** Trimming level to apply */
  trimLevel: 'none' | 'light' | 'aggressive';
}

/**
 * Basic file information interface
 */
export interface IFileInfo {
  /** The file path */
  path: string;
  /** The file contents */
  contents: string;
  /** The file's relative path from the project root */
  relativePath: string;
  /** The estimated token count of the file */
  tokenCount?: number;
  /** The file's importance score (higher is more important) */
  importanceScore?: number;
}

/**
 * Result of context building
 */
export interface IContextResult {
  /** The generated context string */
  context: string;
  /** The total token count of the context */
  tokenCount: number;
  /** Files included in the context */
  includedFiles: IFileInfo[];
  /** Files that were trimmed */
  trimmedFiles: IFileInfo[];
  /** Files that were excluded */
  excludedFiles: IFileInfo[];
  /** Token savings from trimming */
  tokenSavings: number;
}

/**
 * File metadata without contents (for lazy loading)
 */
export interface IFileMetadata {
  /** The file path */
  path: string;
  /** The file's relative path from the project root */
  relativePath: string;
  /** File size in bytes */
  size: number;
  /** Last modified time (Unix timestamp) */
  mtime: number;
  /** Estimated token count (without loading full contents) */
  estimatedTokens: number;
  /** The file's importance score */
  importanceScore?: number;
}

/**
 * Cache entry for a file
 */
export interface ICacheEntry {
  /** File path */
  path: string;
  /** File contents */
  contents: string;
  /** Token count */
  tokenCount: number;
  /** Last modified time when cached */
  mtime: number;
  /** When this cache entry was created */
  cachedAt: number;
}

/**
 * Dependency information for a file
 */
export interface IFileDependencies {
  /** File path */
  path: string;
  /** Files this file imports */
  imports: string[];
  /** Files that import this file */
  importedBy: string[];
  /** Centrality score (0-1) - how central this file is in the dependency graph */
  centrality: number;
}

/**
 * Analysis result for a file
 */
export interface IFileAnalysis {
  /** File path */
  path: string;
  /** Task relevance score (0-1) */
  relevanceScore: number;
  /** Dependency centrality score (0-1) */
  centralityScore: number;
  /** Token efficiency score (0-1) */
  efficiencyScore: number;
  /** Recency score (0-1) */
  recencyScore: number;
  /** Combined importance score (0-1) */
  importanceScore: number;
  /** Assigned tier */
  tier: 'essential' | 'important' | 'optional' | 'excluded';
  /** Reason for the score */
  reason?: string;
}

/**
 * Result of context analysis
 */
export interface IAnalysisResult {
  /** Task type being analyzed */
  taskType: TaskType;
  /** Analyzed files with scores */
  files: IFileAnalysis[];
  /** Dependency graph */
  dependencyGraph: Map<string, IFileDependencies>;
  /** Total files analyzed */
  totalFiles: number;
  /** Analysis duration in ms */
  analysisDuration: number;
}