feat(context): Introduce smart context system: analyzer, lazy loader, cache and README/docs improvements

ts/context/types.ts

@@ -58,6 +58,73 @@ export interface IContextConfig {
   };
   /** 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';
 }
 
 /**
@@ -92,4 +159,90 @@ export interface IContextResult {
   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;
 }