ctxman 3.1.1 → 3.2.8

package/index.d.ts

@@ -20,6 +20,8 @@ export interface TokenCalculatorOptions {
   gitingest?: boolean;
   targetModel?: string;
   dashboard?: boolean;
+  cache?: boolean | 'memory' | 'disk' | CacheManagerOptions | CacheManager;
+  cachePath?: string;
 }
 
 /**
@@ -852,6 +854,21 @@ export interface RepoMapMethod {
   line: number;
   /** Declaration on one line, secrets redacted unless `redact: false` */
   signature: string;
+  /** Identifiers invoked inside this method body */
+  calls?: string[];
+}
+
+/**
+ * Cross-file symbol call edge, caller file/symbol -> callee file/symbol.
+ */
+export interface RepoGraphCallEdge {
+  from: string;
+  caller: string;
+  callerLine: number;
+  to: string;
+  callee: string;
+  calleeLine: number;
+  weight: number;
 }
 
 /**
@@ -884,6 +901,7 @@ export interface RepoGraph {
   root: string;
   nodes: RepoGraphNode[];
   edges: RepoGraphEdge[];
+  callEdges?: RepoGraphCallEdge[];
   history: {
     available: boolean;
     requested: number;
@@ -896,6 +914,7 @@ export interface RepoGraph {
     scannedFiles: number;
     files: number;
     edges: number;
+    callEdges?: number;
     unresolvedImports: number;
     skipped: Array<{ path: string; reason: string }>;
     redactions: Record<string, number>;
@@ -919,12 +938,14 @@ export interface RankWeights {
 }
 
 export interface RankOptions {
-  /** Files or folders (project-relative or absolute) to personalise PageRank toward */
+  /** Files, folders or file:symbol targets to personalise PageRank toward */
   focus?: string[];
   /** Blend of the normalised components (default 0.70 / 0.25 / 0.05) */
   weights?: RankWeights;
   /** PageRank damping (default 0.85) */
   damping?: number;
+  /** Include cross-file AST symbol call edges in PageRank and focus expansion */
+  callGraph?: boolean;
 }
 
 export interface RankedFile {
@@ -953,6 +974,8 @@ export interface RepoMapOptions extends RepoGraphOptions, RankOptions {
   style?: 'text' | 'markdown' | 'json' | 'dot';
   /** Render the dependency edges instead of the map */
   graph?: boolean;
+  /** Annotate methods with cross-file call targets and include call edges in graph/ranking */
+  callGraph?: boolean;
 }
 
 export interface RepoMapFile {
@@ -987,6 +1010,15 @@ export interface RepoMapResult {
  */
 export function buildRepoGraph(root: string, options?: RepoGraphOptions): RepoGraph;
 
+/**
+ * Build cross-file AST symbol call edges across mapped nodes and import edges
+ */
+export function buildCallGraph(
+  nodes: RepoGraphNode[],
+  edges: RepoGraphEdge[],
+  contentsByPath?: Map<string, string>
+): RepoGraphCallEdge[];
+
 /**
  * Rank the files of a graph, best first: PageRank blended with git change frequency and
  * symbol references
@@ -1035,6 +1067,8 @@ export interface PrContextOptions {
   maxFileBytes?: number;
   /** Most related tests to list (default: 50) */
   maxRelatedTests?: number;
+  /** Additional repositories for multi-repo PR review context */
+  repos?: WorkspaceRepoInput[];
 }
 
 export interface PrRevision {
@@ -1072,6 +1106,7 @@ export interface PrChangedMethod extends PrMethod {
 }
 
 export interface PrCommit {
+  repo?: string;
   sha: string;
   short: string;
   author: string;
@@ -1088,6 +1123,8 @@ export interface PrRelatedTest {
 }
 
 export interface PrContextResult {
+  /** Participating repositories when `repos` was supplied */
+  repos?: Array<{ alias: string; root: string }>;
   /** The rendered context */
   output: string;
   /** Tokens of `output` */
@@ -1153,6 +1190,20 @@ export interface ExplainHistoryOptions {
   rev?: string;
   /** Include each commit's diff of the target */
   patches?: boolean;
+  /** Fetch referenced GitHub/GitLab issue, PR and MR discussions (default false) */
+  discussions?: boolean;
+  /** Maximum remote discussions fetched (default 10) */
+  maxDiscussions?: number;
+  /** Maximum comments fetched per discussion (default 5) */
+  maxComments?: number;
+  /** Per-request timeout in milliseconds (default 5000) */
+  discussionTimeoutMs?: number;
+  /** Explicit GitHub/GitLab API token override */
+  token?: string;
+  /** Custom fetch implementation */
+  fetch?: typeof globalThis.fetch;
+  /** Environment override for token lookup */
+  env?: NodeJS.ProcessEnv;
   /** Commits of the file examined for co-changes (default 500, 0 = off) */
   couplingWindow?: number;
   /** Co-changed files listed (default 10) */
@@ -1172,6 +1223,8 @@ export interface ExplainHistoryOptions {
   redact?: boolean;
   /** Directory relative target paths start from (default: root) */
   cwd?: string;
+  /** Additional repositories for multi-repo history & cross-repo ADR/doc/test lookup */
+  repos?: WorkspaceRepoInput[];
 }
 
 export interface WhyCommit {
@@ -1204,6 +1257,7 @@ export interface WhyIssueReference {
 }
 
 export interface ExplainHistoryData {
+  repos?: Array<{ alias: string; root: string }>;
   target: {
     path: string;
     symbol: string | null;
@@ -1240,6 +1294,26 @@ export interface ExplainHistoryData {
     coAuthors: Array<{ value: string; commits: string[] }>;
     reviewers: Array<{ value: string; commits: string[] }>;
   };
+  discussions: Array<{
+    id: string;
+    number: number;
+    repo: string;
+    provider: 'github' | 'gitlab';
+    kind: 'issue' | 'pr' | 'mr';
+    title: string;
+    state: string;
+    author: string;
+    createdAt: string | null;
+    url: string | null;
+    labels: string[];
+    body: string;
+    commits: string[];
+    comments: Array<{
+      author: string;
+      createdAt: string | null;
+      body: string;
+    }>;
+  }>;
   ownership: {
     startLine: number | null;
     endLine: number | null;
@@ -1282,6 +1356,8 @@ export interface ExplainHistoryData {
 }
 
 export interface ExplainHistoryResult {
+  /** Participating repositories when `repos` was supplied */
+  repos?: Array<{ alias: string; root: string }>;
   /** The rendered document */
   text: string;
   style: 'markdown' | 'xml' | 'json';
@@ -1420,3 +1496,866 @@ export interface PackResult {
  * BUDGET_TOO_SMALL, SPLIT_TOO_SMALL).
  */
 export function packContext(root: string, options?: PackOptions): Promise<PackResult>;
+
+// ============================================
+// Core v3 Modular Pipeline & Cache
+// ============================================
+
+export interface CacheManagerOptions {
+  enabled?: boolean;
+  strategy?: 'disk' | 'memory';
+  ttl?: number;
+  path?: string;
+  maxEntries?: number;
+  maxSize?: number;
+}
+
+export interface CacheMeta {
+  size?: number;
+  namespace?: string;
+  encoding?: string;
+  methodLevel?: boolean;
+  extraKey?: string;
+}
+
+export class CacheManager {
+  constructor(options?: CacheManagerOptions);
+  options: Required<CacheManagerOptions>;
+  stats: {
+    hits: number;
+    misses: number;
+    writes: number;
+    evictions: number;
+    errors: number;
+  };
+  get(
+    filePath: string,
+    modifiedTime: number | Date | null,
+    meta?: CacheMeta
+  ): Record<string, unknown> | null;
+  set(
+    filePath: string,
+    analysis: Record<string, unknown>,
+    modifiedTime: number | Date | null,
+    meta?: CacheMeta
+  ): void;
+  isExpired(
+    cacheTimestamp: number,
+    cacheModifiedTime: number | null,
+    currentModifiedTime: number | Date | null,
+    cachedSize?: number | null,
+    currentSize?: number | null
+  ): boolean;
+  getCacheKey(filePath: string, meta?: CacheMeta): string;
+  clear(): void;
+  prune(): void;
+  getStats(): {
+    hits: number;
+    misses: number;
+    writes: number;
+    evictions: number;
+    errors: number;
+    totalRequests: number;
+    hitRate: number;
+    cacheSize: number;
+  };
+}
+
+export function resolveCacheManager(
+  cacheOption: boolean | 'memory' | 'disk' | CacheManagerOptions | CacheManager | null | undefined,
+  defaults?: CacheManagerOptions
+): CacheManager | null;
+
+export interface ScannedFile {
+  path: string;
+  relativePath: string;
+  name: string;
+  extension: string;
+  size: number;
+  modified: Date;
+  created: Date;
+}
+
+export interface ScannerOptions {
+  respectGitignore?: boolean;
+  followSymlinks?: boolean;
+  maxDepth?: number;
+  policy?: Policy | false | null;
+  respectIgnoreFiles?: string | string[];
+  env?: NodeJS.ProcessEnv;
+}
+
+export class Scanner {
+  constructor(rootPath: string, options?: ScannerOptions);
+  rootPath: string;
+  scan(): ScannedFile[];
+  isDenied(relativePath: string): boolean;
+  shouldIgnore(relativePath: string, fullPath?: string): boolean;
+  getPolicy(): Policy | null;
+  getStats(): {
+    filesScanned: number;
+    directoriesTraversed: number;
+    filesIgnored: number;
+    filesDenied: number;
+    errors: number;
+  };
+  reset(): void;
+}
+
+export interface AnalyzerOptions {
+  methodLevel?: boolean;
+  parallel?: boolean;
+  maxWorkers?: number;
+  targetModel?: string | null;
+  encoding?: string;
+  cache?: boolean | 'memory' | 'disk' | CacheManagerOptions | CacheManager;
+  cachePath?: string;
+}
+
+export interface AnalyzedFile {
+  path: string;
+  relativePath: string;
+  name: string;
+  extension: string;
+  size: number;
+  modified: Date | number;
+  tokens: number;
+  lines: number;
+  language: string;
+  methods?: MethodInfo[];
+  methodCount?: number;
+}
+
+export interface AnalyzerStats {
+  totalFiles: number;
+  totalTokens: number;
+  totalSize: number;
+  totalMethods: number;
+  totalLines: number;
+  byLanguage: Record<string, { files: number; tokens: number; size: number }>;
+  largestFiles: Array<{ path: string; tokens: number; size: number }>;
+  analysisTime: number;
+  cacheHits?: number;
+  cacheMisses?: number;
+}
+
+export class Analyzer {
+  constructor(options?: AnalyzerOptions);
+  analyze(files: ScannedFile[]): Promise<{ files: AnalyzedFile[]; stats: AnalyzerStats }>;
+  analyzeFile(fileInfo: ScannedFile): Promise<AnalyzedFile | null>;
+  getStats(): AnalyzerStats;
+  reset(): void;
+  getLanguageDistribution(): Array<{
+    language: string;
+    files: number;
+    tokens: number;
+    size: number;
+    percentage: number;
+  }>;
+}
+
+export interface ContextBuilderOptions {
+  targetModel?: string | null;
+  targetTokens?: number | null;
+  useCase?: string;
+  includeTests?: boolean;
+  includeDocumentation?: boolean;
+  methodLevel?: boolean;
+  priorityStrategy?: 'balanced' | 'changed-first' | 'core-first';
+}
+
+export class ContextBuilder {
+  constructor(options?: ContextBuilderOptions);
+  build(analysisResult: { files: AnalyzedFile[]; stats: AnalyzerStats }): Record<string, unknown>;
+  getSummary(context: Record<string, unknown>): string;
+}
+
+export interface ReporterOptions {
+  format?: string;
+  outputPath?: string | null;
+  clipboard?: boolean;
+  verbose?: boolean;
+}
+
+export class Reporter {
+  constructor(options?: ReporterOptions);
+  report(context: Record<string, unknown>, stats: AnalyzerStats): Promise<void>;
+  exportToFile(context: Record<string, unknown>, outputPath: string): Promise<void>;
+  exportToClipboard(context: Record<string, unknown>): Promise<void>;
+  generateSummary(context: Record<string, unknown>): string;
+}
+
+// ============================================
+// Search, Symbol Lookup, Token Counting, RAG & Policy
+// ============================================
+
+export interface SearchProjectOptions {
+  limit?: number;
+  maxTokens?: number;
+  redact?: boolean;
+  windowLines?: number;
+}
+
+export interface SearchHit {
+  file: string;
+  name: string | null;
+  kind: string;
+  parent?: string;
+  startLine: number;
+  endLine: number;
+  score: number;
+  tokens: number;
+  text: string | null;
+  truncated?: boolean;
+}
+
+export interface SearchProjectResult {
+  query: string;
+  root: string;
+  files: number;
+  chunks: number;
+  tokens: number;
+  results: SearchHit[];
+}
+
+export function searchProject(
+  root: string,
+  query: string,
+  options?: SearchProjectOptions
+): SearchProjectResult;
+
+export interface GetSymbolOptions {
+  file?: string;
+  limit?: number;
+  maxTokens?: number;
+  redact?: boolean;
+  repos?: WorkspaceRepoInput[];
+}
+
+export interface SymbolMatch {
+  name: string;
+  kind: string;
+  parent?: string;
+  repo?: string;
+  file: string;
+  startLine: number;
+  endLine: number;
+  tokens: number;
+  source: string;
+  truncated?: boolean;
+}
+
+export interface GetSymbolResult {
+  query: string;
+  match: 'exact' | 'case-insensitive' | 'none';
+  total: number;
+  repos?: Array<{ alias: string; root: string }>;
+  symbols: SymbolMatch[];
+  suggestions?: Array<{
+    name: string;
+    kind: string;
+    parent?: string;
+    file: string;
+    startLine: number;
+  }>;
+}
+
+export function getSymbol(root: string, query: string, options?: GetSymbolOptions): GetSymbolResult;
+
+export interface CountForModelOptions {
+  model?: string;
+  text?: string;
+  repos?: WorkspaceRepoInput[];
+  api?: boolean;
+  client?: unknown;
+  onProgress?: (done: number, total: number) => void;
+}
+
+export interface CountForModelResult {
+  model: string;
+  modelName: string;
+  vendor: string;
+  files: number;
+  encoding: string;
+  localTokens: number;
+  tokens: number;
+  method: 'local' | 'anthropic-api';
+  exact: boolean;
+  contextWindow: number;
+  fits: boolean;
+  percentOfWindow: number;
+  requests?: number;
+  ratio?: number | null;
+  repos?: Array<{
+    alias: string;
+    root: string;
+    files: number;
+    localTokens: number;
+    tokens: number;
+    percentOfWindow: number;
+  }>;
+  largestFiles: Array<{ path: string; tokens: number }>;
+}
+
+export function countForModel(
+  root: string,
+  options?: CountForModelOptions
+): Promise<CountForModelResult>;
+
+export interface AskCodebaseOptions {
+  limit?: number;
+  redact?: boolean;
+  maxChars?: number;
+  repos?: WorkspaceRepoInput[];
+  onProgress?: (event: 'indexing' | 'indexed') => void;
+  createStore?: (storePath: string, repo?: ResolvedWorkspaceRepo) => unknown;
+}
+
+export interface AskCodebaseResult {
+  query: string;
+  indexed: boolean;
+  repos?: Array<{ alias: string; root: string }>;
+  results: Array<{
+    repo?: string;
+    file: string;
+    score: number | null;
+    text: string;
+    truncated: boolean;
+  }>;
+  removedByPolicy: number;
+  redactions: number;
+}
+
+export function askCodebase(
+  root: string,
+  query: string,
+  options?: AskCodebaseOptions
+): Promise<AskCodebaseResult>;
+
+export class Policy {
+  active: boolean;
+  requireRedaction: boolean;
+  maxExportTokens: number | null;
+  allowedModels: string[] | null;
+  ignoreFiles: string[];
+  audit: { enabled: boolean; path: string };
+  sources: Array<{ scope: string; file: string }>;
+  isDenied(relativePath: string): boolean;
+  isAuditLog(relativePath: string): boolean;
+  toJSON(): Record<string, unknown>;
+}
+
+export class PolicyConfigError extends Error {
+  file: string;
+  errors: string[];
+  exitCode: number;
+}
+
+export class PolicyViolationError extends Error {
+  violations: Array<Record<string, unknown>>;
+  exitCode: number;
+}
+
+export function loadPolicy(rootPath: string, options?: { env?: NodeJS.ProcessEnv }): Policy;
+
+export interface WorkspacePolicySummary {
+  valid: boolean;
+  active: boolean;
+  requireRedaction: boolean;
+  maxExportTokens: number | null;
+  allowedTargetModels: Array<{
+    repo: string;
+    scope: string;
+    file: string;
+    patterns: string[];
+  }> | null;
+  ignoreFiles: string[];
+  repos: Array<Record<string, unknown>>;
+}
+
+export function checkWorkspacePolicies(
+  primaryRoot: string,
+  extraRepos?: WorkspaceRepoInput[],
+  options?: { env?: NodeJS.ProcessEnv }
+): WorkspacePolicySummary;
+
+export interface WorkspaceAuditResult {
+  repos: Array<{ alias: string; root: string }>;
+  files: string[];
+  allFiles: string[];
+  missing: string[];
+  total: number;
+  events: Array<Record<string, unknown>>;
+  skippedLines: number;
+  policyErrors: Array<{ repo: string; root: string; message: string }>;
+}
+
+export function readWorkspaceAuditLogs(
+  primaryRoot: string,
+  extraRepos?: WorkspaceRepoInput[],
+  options?: { since?: Date | null; limit?: number | null; env?: NodeJS.ProcessEnv }
+): WorkspaceAuditResult;
+
+// ============================================
+// Focused Neighborhood Context (`ctxman focus`)
+// ============================================
+
+export type FocusDirection = 'both' | 'imports' | 'importers' | 'calls' | 'callers';
+
+export interface FocusOptions extends Omit<PackOptions, 'files'> {
+  /** Target function or method name for symbol-level call graph traversal */
+  symbol?: string;
+  /** Graph traversal hops (default: 1; 0 = target file only) */
+  depth?: number;
+  /** Traversal direction (default: 'both') */
+  direction?: FocusDirection;
+  /** Include outgoing imports (default: true) */
+  imports?: boolean;
+  /** Include incoming importers (default: true) */
+  importers?: boolean;
+  /** Include cross-file AST symbol call graph edges (default: true) */
+  callGraph?: boolean;
+  /** Include outgoing cross-file calls (default: true) */
+  calls?: boolean;
+  /** Include incoming cross-file callers (default: true) */
+  callers?: boolean;
+  /** Include test files in neighborhood (default: true) */
+  includeTests?: boolean;
+  /** Git commits mined for tie-breaking PageRank (default: 0) */
+  history?: number;
+  /** Explicit rank order override */
+  rankOrder?: string[];
+  /** Additional repositories for multi-repo workspace focus */
+  repos?: WorkspaceRepoInput[];
+}
+
+export interface FocusNeighbor {
+  path: string;
+  distance: number;
+  relation: 'import' | 'importer' | 'call' | 'caller' | 'both';
+  score: number;
+}
+
+export interface FocusMetadata {
+  target: string;
+  symbol?: string | null;
+  depth: number;
+  direction: FocusDirection;
+  callGraph?: boolean;
+  inGraph: boolean;
+  neighbors: FocusNeighbor[];
+  callEdges?: RepoGraphCallEdge[];
+  repos?: Array<{ alias: string; root: string }>;
+}
+
+export interface FocusResult extends PackResult {
+  focus: FocusMetadata;
+  repos?: Array<{ alias: string; root: string }>;
+}
+
+export class FocusError extends Error {
+  code: string;
+  constructor(code: string, message: string);
+}
+
+export function focusContext(
+  root: string,
+  target: string,
+  options?: FocusOptions
+): Promise<FocusResult>;
+
+export function describeFocus(result: FocusResult): string;
+
+// ============================================
+// Hybrid Search (BM25 + Semantic RRF)
+// ============================================
+
+export type HybridSearchMode = 'bm25' | 'semantic' | 'hybrid';
+
+export interface HybridSearchOptions extends SearchProjectOptions {
+  mode?: HybridSearchMode;
+  rrfK?: number;
+  bm25Weight?: number;
+  semanticWeight?: number;
+  fallbackToBm25?: boolean;
+  onProgress?: (event: 'indexing' | 'indexed') => void;
+  createStore?: (storePath: string) => unknown;
+}
+
+export interface HybridSearchHit extends SearchHit {
+  bm25Rank: number | null;
+  semanticRank: number | null;
+  bm25Score: number | null;
+  semanticScore: number | null;
+}
+
+export interface HybridSearchResult {
+  query: string;
+  mode: HybridSearchMode;
+  effectiveMode: HybridSearchMode;
+  semanticAvailable: boolean;
+  indexed: boolean;
+  root: string;
+  files: number;
+  chunks: number;
+  tokens: number;
+  warnings: string[];
+  results: HybridSearchHit[];
+}
+
+export function hybridSearch(
+  root: string,
+  query: string,
+  options?: HybridSearchOptions
+): Promise<HybridSearchResult>;
+
+// ============================================
+// Multi-Repository Workspace (`--repo`)
+// ============================================
+
+export type WorkspaceRepoInput = string | { path: string; alias?: string };
+
+export interface ResolvedWorkspaceRepo {
+  alias: string;
+  root: string;
+  realRoot?: string;
+  policy?: Policy;
+}
+
+export function resolveWorkspaceRepos(repos: WorkspaceRepoInput[]): ResolvedWorkspaceRepo[];
+
+export interface WorkspaceGraph extends RepoGraph {
+  repos: Array<{ alias: string; root: string }>;
+}
+
+export function buildWorkspaceGraph(
+  repos: WorkspaceRepoInput[],
+  options?: RepoGraphOptions & { callGraph?: boolean }
+): WorkspaceGraph;
+
+export interface WorkspaceMapResult extends RepoMapResult {
+  repos: Array<{ alias: string; root: string }>;
+}
+
+export function mapWorkspace(
+  repos: WorkspaceRepoInput[],
+  options?: RepoMapOptions
+): WorkspaceMapResult;
+
+export interface WorkspaceSearchHit extends SearchHit {
+  repo: string;
+}
+
+export interface WorkspaceSearchResult extends Omit<SearchProjectResult, 'results'> {
+  repos: Array<{ alias: string; root: string }>;
+  results: WorkspaceSearchHit[];
+}
+
+export function searchWorkspace(
+  repos: WorkspaceRepoInput[],
+  query: string,
+  options?: SearchProjectOptions
+): WorkspaceSearchResult;
+
+export interface WorkspacePackResult extends PackResult {
+  repos: Array<{ alias: string; root: string }>;
+}
+
+export function packWorkspace(
+  repos: WorkspaceRepoInput[],
+  options?: Omit<PackOptions, 'files' | 'cwd'>
+): Promise<WorkspacePackResult>;
+
+// ============================================
+// RAG Vector Stores & Embedding Providers (v3.2.0)
+// ============================================
+
+export class LocalHashEmbeddingProvider {
+  dimension: number;
+  constructor(dimension?: number);
+  embed(text: string): Promise<number[]>;
+}
+
+export class AutoEmbeddingProvider {
+  modelName?: string;
+  constructor(options?: { modelName?: string });
+  init(): Promise<void>;
+  embed(text: string): Promise<number[]>;
+}
+
+export class SqliteVectorStore {
+  storagePath: string;
+  dbPath: string;
+  constructor(embeddingProvider: any, storagePath?: string);
+  init(): Promise<void>;
+  addDocument(
+    text: string,
+    metadata?: Record<string, any>
+  ): Promise<{ upserted: number; skipped: number }>;
+  addDocuments(
+    docs: Array<{ text: string; id?: string; metadata?: Record<string, any> }>
+  ): Promise<{ upserted: number; skipped: number }>;
+  removeDocument(idOrFilePath: string): Promise<number>;
+  upsertGraphNode(node: Record<string, any>): Promise<void>;
+  replaceGraphEdges(
+    fromPath: string,
+    edges?: Array<{ to: string; weight?: number }>
+  ): Promise<void>;
+  removeGraphNode(filePath: string): Promise<{ removedNode: number; removedEdges: number }>;
+  syncGraph(graph: {
+    nodes?: Array<Record<string, any>>;
+    edges?: Array<{ from: string; to: string; weight?: number }>;
+    replaceAll?: boolean;
+  }): Promise<void>;
+  getGraph(): Promise<{
+    nodes: Array<Record<string, any>>;
+    edges: Array<{ from: string; to: string; weight: number }>;
+  }>;
+  graphCounts(): { nodes: number; edges: number };
+  search(
+    queryText: string,
+    limit?: number
+  ): Promise<Array<{ id?: string; text: string; score: number; metadata: Record<string, any> }>>;
+  deleteTable(): Promise<void>;
+  count(): number;
+  close(): void;
+}
+
+export interface FileWatcherOptions {
+  debounce?: number;
+  recursive?: boolean;
+  ignorePatterns?: Array<string | RegExp>;
+  repos?: string[];
+}
+
+export class FileWatcher {
+  rootPath: string;
+  options: FileWatcherOptions;
+  isWatching: boolean;
+  isMultiRepo: boolean;
+  repos: Array<{ root: string; alias: string | null }>;
+  constructor(rootPath: string, options?: FileWatcherOptions);
+  start(): void;
+  stop(): void;
+  shouldIgnore(relativePath: string, repoRoot?: string): boolean;
+  getStats(): {
+    totalChanges: number;
+    ignoredChanges: number;
+    errors: number;
+    isWatching: boolean;
+    activeWatchers: number;
+    pendingDebounce: number;
+  };
+  resetStats(): void;
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+export interface IncrementalAnalyzerOptions extends AnalyzerOptions {
+  projectRoot?: string;
+  repos?: string[];
+  sync?: boolean;
+  syncRag?: boolean;
+  syncGraph?: boolean;
+  storePath?: string;
+  vectorStore?: SqliteVectorStore;
+  embeddingProvider?: any;
+  redactSecrets?: boolean;
+  maxFileBytes?: number;
+  hydrateGraphOnStart?: boolean;
+}
+
+export class IncrementalAnalyzer {
+  projectRoot: string | null;
+  vectorStore: SqliteVectorStore | null;
+  constructor(options?: IncrementalAnalyzerOptions);
+  isMultiRepo: boolean;
+  repos: Array<{ root: string; alias: string | null }>;
+  isPathDenied(graphPath: string): boolean;
+  ensureSyncReady(rootOverride?: string | null): Promise<boolean>;
+  bootstrapSync(
+    root?: string,
+    options?: { repos?: string[] }
+  ): Promise<{
+    files: number;
+    ragUpserted: number;
+    ragSkipped: number;
+    graphNodes: number;
+    graphEdges: number;
+    repos?: string[];
+  }>;
+  syncFileChange(changeEvent: Record<string, any>): Promise<{
+    rag: Record<string, any> | null;
+    graph: Record<string, any> | null;
+  }>;
+  analyzeChange(changeEvent: Record<string, any>): Promise<void>;
+  handleFileDeleted(changeEvent: Record<string, any>): Promise<void>;
+  getGraph(): Promise<{
+    nodes: Array<Record<string, any>>;
+    edges: Array<{ from: string; to: string; weight: number }>;
+  }>;
+  getStats(): AnalyzerStats;
+  getCachedAnalysis(filePath: string): AnalyzedFile | null;
+  clearCache(): void;
+  close(): void;
+  getCacheStats(): {
+    cachedFiles: number;
+    cacheSize: number;
+    graphNodes: number;
+    graphEdges: number;
+    vectorDocuments: number;
+  };
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+// ============================================
+// Task-Driven Auto Context (v3.2.0)
+// ============================================
+
+export interface TaskContextOptions {
+  budget?: number | string;
+  format?: 'markdown' | 'json' | 'xml';
+  searchMode?: 'hybrid' | 'bm25' | 'semantic';
+  callGraph?: boolean;
+  redact?: boolean;
+  output?: string;
+  model?: string;
+  limit?: number;
+  repos?: WorkspaceRepoInput[];
+}
+
+export interface TaskContextResult {
+  query: string;
+  format: string;
+  budget: number;
+  totalTokens: number;
+  text: string;
+  seeds: Array<{ file: string; score: number; kind?: string; name?: string }>;
+  files: Array<{ path: string; hop: number; compressed: boolean; tokens: number; lines: number }>;
+  callEdges?: RepoGraphCallEdge[];
+  omitted: Array<{ path: string; reason: string }>;
+  redactions: { total: number };
+  repos?: Array<{ alias: string; root: string }>;
+}
+
+export function buildTaskContext(
+  root: string,
+  taskQuery: string,
+  options?: TaskContextOptions
+): Promise<TaskContextResult>;
+
+// ============================================
+// Failure Diagnosis (v3.2.0)
+// ============================================
+
+export interface DiagnoseFailureOptions {
+  budget?: number | string;
+  format?: 'markdown' | 'json' | 'xml';
+  callGraph?: boolean;
+  redact?: boolean;
+  windowLines?: number;
+  output?: string;
+  repos?: WorkspaceRepoInput[];
+}
+
+export interface DiagnoseFailureResult {
+  frames: Array<any>;
+  implicatedFiles: string[];
+  totalTokens: number;
+  budget: number;
+  text: string;
+  history: Array<{ file: string; text: string; tokens: number }>;
+  neighbors: string[];
+  callEdges?: RepoGraphCallEdge[];
+  redactions: { total: number };
+  repos?: Array<{ alias: string; root: string }>;
+}
+
+export function diagnoseFailure(
+  root: string,
+  traceOrLog: string,
+  options?: DiagnoseFailureOptions
+): Promise<DiagnoseFailureResult>;
+
+// ============================================
+// Institutional Memory Bridge (v3.2.0)
+// ============================================
+
+export interface AnalyzerCitation {
+  id: string;
+  kind: string;
+  title: string;
+  snippet: string;
+  url: string | null;
+  author: string | null;
+  timestamp: string | null;
+  refs: string[];
+  score: number;
+}
+
+export interface QueryAnalyzerOptions {
+  file?: string;
+  symbol?: string;
+  commits?: string[];
+  limit?: number;
+  redact?: boolean;
+}
+
+export function queryAnalyzerCitations(
+  rootOrDbPath: string,
+  options?: QueryAnalyzerOptions
+): AnalyzerCitation[];
+
+// ============================================
+// Expert Finder ("Who knows about this?")
+// ============================================
+
+export class WhoError extends Error {
+  constructor(message: string);
+}
+
+export interface FindExpertsOptions {
+  limit?: number;
+  commitWindow?: number;
+  halfLifeDays?: number;
+  since?: string;
+  style?: 'markdown' | 'xml' | 'json';
+  nowMs?: number;
+  repos?: WorkspaceRepoInput[];
+}
+
+export interface ExpertEntry {
+  name: string;
+  email: string | null;
+  score: number;
+  blameLines: number;
+  blameShare: number;
+  commits: number;
+  commitShare: number;
+  recencyShare: number;
+  additions: number;
+  deletions: number;
+  lastActive: string | null;
+  isCodeOwner: boolean;
+  codeOwnerHandles: string[];
+  filesTouched: number;
+  recentCommits: Array<{ sha: string; date: string | null; subject: string }>;
+}
+
+export interface FindExpertsResult {
+  repos?: Array<{ alias: string; root: string }>;
+  data: {
+    repos?: Array<{ alias: string; root: string }>;
+    target: { query: string; mode: string; label: string; files: string[] };
+    codeOwners: { file: string | null; owners: string[] };
+    totalAuthors: number;
+    experts: ExpertEntry[];
+  };
+  experts: ExpertEntry[];
+  text: string;
+}
+
+export function findExperts(
+  projectDir: string,
+  target: string,
+  options?: FindExpertsOptions
+): Promise<FindExpertsResult>;