@git.zone/tsdoc/dist_ts/context/types.d.ts

A comprehensive TypeScript documentation tool that leverages AI to generate and enhance project documentation, including dynamic README creation, API docs via TypeDoc, and smart commit message generation.

/**
 * 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;
    /** Iterative context building configuration */
    iterative?: IIterativeConfig;
}
/**
 * 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
 * Note: Smart analysis is always enabled; this config only controls advanced options
 */
export interface IAnalyzerConfig {
    /** Whether to use AI refinement for selection (advanced, disabled by default) */
    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;
}
/**
 * Configuration for iterative context building
 */
export interface IIterativeConfig {
    /** Maximum number of iterations allowed */
    maxIterations?: number;
    /** Maximum files to request in first iteration */
    firstPassFileLimit?: number;
    /** Maximum files to request in subsequent iterations */
    subsequentPassFileLimit?: number;
    /** Temperature for AI decision making (0-1) */
    temperature?: number;
    /** Model to use for iterative decisions */
    model?: string;
}
/**
 * AI decision for file selection
 */
export interface IFileSelectionDecision {
    /** AI's reasoning for file selection */
    reasoning: string;
    /** File paths to load */
    filesToLoad: string[];
    /** Estimated tokens needed */
    estimatedTokensNeeded?: number;
}
/**
 * AI decision for context sufficiency
 */
export interface IContextSufficiencyDecision {
    /** Whether context is sufficient */
    sufficient: boolean;
    /** AI's reasoning */
    reasoning: string;
    /** Additional files needed (if not sufficient) */
    additionalFilesNeeded?: string[];
}
/**
 * State for a single iteration
 */
export interface IIterationState {
    /** Iteration number (1-based) */
    iteration: number;
    /** Files loaded in this iteration */
    filesLoaded: IFileInfo[];
    /** Tokens used in this iteration */
    tokensUsed: number;
    /** Total tokens used so far */
    totalTokensUsed: number;
    /** AI decision made in this iteration */
    decision: IFileSelectionDecision | IContextSufficiencyDecision;
    /** Duration of this iteration in ms */
    duration: number;
}
/**
 * Result of iterative context building
 */
export interface IIterativeContextResult extends IContextResult {
    /** Number of iterations performed */
    iterationCount: number;
    /** Details of each iteration */
    iterations: IIterationState[];
    /** Total API calls made */
    apiCallCount: number;
    /** Total duration in ms */
    totalDuration: number;
}
export type { IDiffFileInfo, IProcessedDiff, IDiffProcessorOptions } from './diff-processor.js';