infiniloom-node 0.3.2 → 0.4.0

package/README.md

@@ -221,6 +221,105 @@ for (const finding of findings) {
 }
 ```
 
+### Call Graph API
+
+Query caller/callee relationships and navigate your codebase programmatically.
+
+#### `buildIndex(path: string, options?: IndexOptions): IndexStatus`
+
+Build or update the symbol index for a repository (required for call graph queries).
+
+```javascript
+const { buildIndex } = require('infiniloom-node');
+
+const status = buildIndex('./my-repo');
+console.log(`Indexed ${status.symbolCount} symbols`);
+```
+
+#### `findSymbol(path: string, name: string): SymbolInfo[]`
+
+Find symbols by name.
+
+```javascript
+const { findSymbol, buildIndex } = require('infiniloom-node');
+
+buildIndex('./my-repo');
+const symbols = findSymbol('./my-repo', 'processRequest');
+for (const s of symbols) {
+  console.log(`${s.name} (${s.kind}) at ${s.file}:${s.line}`);
+}
+```
+
+#### `getCallers(path: string, symbolName: string): SymbolInfo[]`
+
+Get all functions/methods that call the target symbol.
+
+```javascript
+const { getCallers, buildIndex } = require('infiniloom-node');
+
+buildIndex('./my-repo');
+const callers = getCallers('./my-repo', 'authenticate');
+console.log(`authenticate is called by ${callers.length} functions`);
+for (const c of callers) {
+  console.log(`  ${c.name} at ${c.file}:${c.line}`);
+}
+```
+
+#### `getCallees(path: string, symbolName: string): SymbolInfo[]`
+
+Get all functions/methods that the target symbol calls.
+
+```javascript
+const { getCallees, buildIndex } = require('infiniloom-node');
+
+buildIndex('./my-repo');
+const callees = getCallees('./my-repo', 'main');
+console.log(`main calls ${callees.length} functions`);
+```
+
+#### `getReferences(path: string, symbolName: string): ReferenceInfo[]`
+
+Get all references to a symbol (calls, imports, inheritance).
+
+```javascript
+const { getReferences, buildIndex } = require('infiniloom-node');
+
+buildIndex('./my-repo');
+const refs = getReferences('./my-repo', 'UserService');
+for (const r of refs) {
+  console.log(`${r.kind}: ${r.symbol.name} at ${r.symbol.file}:${r.symbol.line}`);
+}
+```
+
+#### `getCallGraph(path: string, options?: CallGraphOptions): CallGraph`
+
+Get the complete call graph with all symbols and call relationships.
+
+```javascript
+const { getCallGraph, buildIndex } = require('infiniloom-node');
+
+buildIndex('./my-repo');
+const graph = getCallGraph('./my-repo');
+console.log(`${graph.stats.totalSymbols} symbols, ${graph.stats.totalCalls} calls`);
+
+// Find most called functions
+const callCounts = new Map();
+for (const edge of graph.edges) {
+  callCounts.set(edge.callee, (callCounts.get(edge.callee) || 0) + 1);
+}
+const sorted = [...callCounts.entries()].sort((a, b) => b[1] - a[1]);
+console.log('Most called:', sorted.slice(0, 5));
+```
+
+#### Async versions
+
+All call graph functions have async versions:
+- `findSymbolAsync(path, name)`
+- `getCallersAsync(path, symbolName)`
+- `getCalleesAsync(path, symbolName)`
+- `getReferencesAsync(path, symbolName)`
+- `getCallGraphAsync(path, options)`
+
 #### `isGitRepo(path: string): boolean`
 
 Check if a path is a git repository.
@@ -257,6 +356,13 @@ interface PackOptions {
   includeTests?: boolean;    // Include test files (default: false)
   securityThreshold?: string;// Minimum severity to block: "critical", "high", "medium", "low"
   tokenBudget?: number;      // Limit total output tokens (0 = no limit)
+  // Git-based filtering options (PR review integration)
+  changedOnly?: boolean;     // Only include files changed in git
+  baseSha?: string;          // Base SHA/ref for diff comparison (e.g., "main", "HEAD~5")
+  headSha?: string;          // Head SHA/ref for diff comparison (default: working tree)
+  stagedOnly?: boolean;      // Include staged changes only
+  includeRelated?: boolean;  // Include related files (importers/dependencies)
+  relatedDepth?: number;     // Depth for related file traversal (1-3, default: 1)
 }
 ```
 
@@ -355,6 +461,30 @@ interface GitBlameLine {
 }
 ```
 
+#### `GitDiffLine`
+
+```typescript
+interface GitDiffLine {
+  changeType: string; // "add", "remove", or "context"
+  oldLine?: number;   // Line number in old file (for remove/context)
+  newLine?: number;   // Line number in new file (for add/context)
+  content: string;    // Line content (without +/- prefix)
+}
+```
+
+#### `GitDiffHunk`
+
+```typescript
+interface GitDiffHunk {
+  oldStart: number;   // Starting line in old file
+  oldCount: number;   // Number of lines in old file
+  newStart: number;   // Starting line in new file
+  newCount: number;   // Number of lines in new file
+  header: string;     // Hunk header (e.g., "@@ -1,5 +1,6 @@ function name")
+  lines: GitDiffLine[]; // Lines in this hunk
+}
+```
+
 ### Infiniloom Class
 
 #### `new Infiniloom(path: string, model?: string)`
@@ -499,6 +629,75 @@ Get file change frequency in recent days.
 
 **Returns:** Number of commits that modified the file in the period
 
+#### `fileAtRef(path: string, gitRef: string): string`
+
+Get file content at a specific git ref (commit, branch, tag).
+
+**Parameters:**
+- `path` - File path relative to repo root
+- `gitRef` - Git ref (commit hash, branch name, tag, HEAD~n, etc.)
+
+**Returns:** File content as string
+
+```javascript
+const repo = new GitRepo('./my-project');
+const oldVersion = repo.fileAtRef('src/main.js', 'HEAD~5');
+const mainVersion = repo.fileAtRef('src/main.js', 'main');
+```
+
+#### `diffHunks(fromRef: string, toRef: string, path?: string): GitDiffHunk[]`
+
+Parse diff between two refs into structured hunks with line-level changes.
+Useful for PR review tools that need to post comments at specific lines.
+
+**Parameters:**
+- `fromRef` - Starting ref (e.g., "main", "HEAD~5", commit hash)
+- `toRef` - Ending ref (e.g., "HEAD", "feature-branch")
+- `path` - Optional file path to filter to a single file
+
+**Returns:** Array of diff hunks with line-level change information
+
+```javascript
+const repo = new GitRepo('./my-project');
+const hunks = repo.diffHunks('main', 'HEAD', 'src/index.js');
+for (const hunk of hunks) {
+  console.log(`Hunk at old:${hunk.oldStart} new:${hunk.newStart}`);
+  for (const line of hunk.lines) {
+    console.log(`${line.changeType}: ${line.content}`);
+  }
+}
+```
+
+#### `uncommittedHunks(path?: string): GitDiffHunk[]`
+
+Parse uncommitted changes (working tree vs HEAD) into structured hunks.
+
+**Parameters:**
+- `path` - Optional file path to filter to a single file
+
+**Returns:** Array of diff hunks for uncommitted changes
+
+```javascript
+const repo = new GitRepo('./my-project');
+const hunks = repo.uncommittedHunks('src/index.js');
+console.log(`${hunks.length} hunks with uncommitted changes`);
+```
+
+#### `stagedHunks(path?: string): GitDiffHunk[]`
+
+Parse staged changes into structured hunks.
+
+**Parameters:**
+- `path` - Optional file path to filter to a single file
+
+**Returns:** Array of diff hunks for staged changes only
+
+```javascript
+const repo = new GitRepo('./my-project');
+const hunks = repo.stagedHunks('src/index.js');
+console.log(`${hunks.length} hunks staged for commit`);
+```
+
 **Example:**
 
 ```javascript

package/index.d.ts

@@ -31,6 +31,18 @@ export interface PackOptions {
   securityThreshold?: string
   /** Token budget for total output (0 = no limit). Files are included by importance until budget is reached. */
   tokenBudget?: number
+  /** Only include files changed in git (requires baseSha or uses uncommitted changes) */
+  changedOnly?: boolean
+  /** Base SHA/ref for diff comparison (e.g., "main", "HEAD~5", commit hash) */
+  baseSha?: string
+  /** Head SHA/ref for diff comparison (default: working tree or HEAD) */
+  headSha?: string
+  /** Include staged changes only (if changedOnly is true and no refs specified) */
+  stagedOnly?: boolean
+  /** Include related files (importers/dependencies of changed files) */
+  includeRelated?: boolean
+  /** Depth for related file traversal (1-3, default: 1) */
+  relatedDepth?: number
 }
 /** Statistics from scanning a repository */
 export interface ScanStats {
@@ -246,6 +258,32 @@ export interface GitBlameLine {
   /** Line number (1-indexed) */
   lineNumber: number
 }
+/** Diff line information for structured diff parsing */
+export interface GitDiffLine {
+  /** Change type: "add", "remove", or "context" */
+  changeType: string
+  /** Line number in old file (for remove/context lines) */
+  oldLine?: number
+  /** Line number in new file (for add/context lines) */
+  newLine?: number
+  /** Line content (without +/- prefix) */
+  content: string
+}
+/** Diff hunk information for structured diff parsing */
+export interface GitDiffHunk {
+  /** Starting line in old file */
+  oldStart: number
+  /** Number of lines in old file */
+  oldCount: number
+  /** Starting line in new file */
+  newStart: number
+  /** Number of lines in new file */
+  newCount: number
+  /** Hunk header (e.g., "@@ -1,5 +1,6 @@ function name") */
+  header: string
+  /** Lines in this hunk */
+  lines: Array<GitDiffLine>
+}
 /** Security finding information */
 export interface SecurityFinding {
   /** File where the finding was detected */
@@ -473,4 +511,698 @@ export declare class GitRepo {
    * Number of commits that modified the file in the period
    */
   fileChangeFrequency(path: string, days?: number | undefined | null): number
+  /**
+   * Get file content at a specific git ref (commit, branch, tag)
+   *
+   * Uses `git show <ref>:<path>` to retrieve file content at that revision.
+   *
+   * # Arguments
+   * * `path` - File path (relative to repo root)
+   * * `gitRef` - Git ref (commit hash, branch name, tag, HEAD~n, etc.)
+   *
+   * # Returns
+   * File content as string
+   *
+   * # Example
+   * ```javascript
+   * const repo = new GitRepo('./my-project');
+   * const oldVersion = repo.fileAtRef('src/main.js', 'HEAD~5');
+   * const mainVersion = repo.fileAtRef('src/main.js', 'main');
+   * ```
+   */
+  fileAtRef(path: string, gitRef: string): string
+  /**
+   * Parse diff between two refs into structured hunks
+   *
+   * Returns detailed hunk information including line numbers for each change.
+   * Useful for PR review tools that need to post comments at specific lines.
+   *
+   * # Arguments
+   * * `fromRef` - Starting ref (e.g., "main", "HEAD~5", commit hash)
+   * * `toRef` - Ending ref (e.g., "HEAD", "feature-branch")
+   * * `path` - Optional file path to filter to a single file
+   *
+   * # Returns
+   * Array of diff hunks with line-level change information
+   *
+   * # Example
+   * ```javascript
+   * const repo = new GitRepo('./my-project');
+   * const hunks = repo.diffHunks('main', 'HEAD', 'src/index.js');
+   * for (const hunk of hunks) {
+   *   console.log(`Hunk at old:${hunk.oldStart} new:${hunk.newStart}`);
+   *   for (const line of hunk.lines) {
+   *     console.log(`${line.changeType}: ${line.content}`);
+   *   }
+   * }
+   * ```
+   */
+  diffHunks(fromRef: string, toRef: string, path?: string | undefined | null): Array<GitDiffHunk>
+  /**
+   * Parse uncommitted changes (working tree vs HEAD) into structured hunks
+   *
+   * # Arguments
+   * * `path` - Optional file path to filter to a single file
+   *
+   * # Returns
+   * Array of diff hunks for uncommitted changes
+   *
+   * # Example
+   * ```javascript
+   * const repo = new GitRepo('./my-project');
+   * const hunks = repo.uncommittedHunks('src/index.js');
+   * console.log(`${hunks.length} hunks with uncommitted changes`);
+   * ```
+   */
+  uncommittedHunks(path?: string | undefined | null): Array<GitDiffHunk>
+  /**
+   * Parse staged changes into structured hunks
+   *
+   * # Arguments
+   * * `path` - Optional file path to filter to a single file
+   *
+   * # Returns
+   * Array of diff hunks for staged changes only
+   *
+   * # Example
+   * ```javascript
+   * const repo = new GitRepo('./my-project');
+   * const hunks = repo.stagedHunks('src/index.js');
+   * console.log(`${hunks.length} hunks staged for commit`);
+   * ```
+   */
+  stagedHunks(path?: string | undefined | null): Array<GitDiffHunk>
+}
+
+// ============================================================================
+// Index API - Build and query symbol indexes
+// ============================================================================
+
+/** Options for building an index */
+export interface IndexOptions {
+  /** Force full rebuild even if index exists */
+  force?: boolean
+  /** Include test files in index */
+  includeTests?: boolean
+  /** Maximum file size to index (bytes) */
+  maxFileSize?: number
+}
+
+/** Index status information */
+export interface IndexStatus {
+  /** Whether an index exists */
+  exists: boolean
+  /** Number of files indexed */
+  fileCount: number
+  /** Number of symbols indexed */
+  symbolCount: number
+  /** Last build timestamp (ISO 8601) */
+  lastBuilt?: string
+  /** Index version */
+  version?: string
+}
+
+/**
+ * Build or update the symbol index for a repository
+ *
+ * The index enables fast diff-to-context lookups and impact analysis.
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `options` - Optional index build options
+ *
+ * # Returns
+ * Index status after building
+ *
+ * # Example
+ * ```javascript
+ * const { buildIndex } = require('infiniloom-node');
+ *
+ * const status = buildIndex('./my-repo');
+ * console.log(`Indexed ${status.symbolCount} symbols`);
+ *
+ * // Force rebuild
+ * const status2 = buildIndex('./my-repo', { force: true });
+ * ```
+ */
+export declare function buildIndex(path: string, options?: IndexOptions | undefined | null): IndexStatus
+
+/**
+ * Get the status of an existing index
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ *
+ * # Returns
+ * Index status information
+ *
+ * # Example
+ * ```javascript
+ * const { indexStatus } = require('infiniloom-node');
+ *
+ * const status = indexStatus('./my-repo');
+ * if (status.exists) {
+ *   console.log(`Index has ${status.symbolCount} symbols`);
+ * } else {
+ *   console.log('No index found, run buildIndex first');
+ * }
+ * ```
+ */
+export declare function indexStatus(path: string): IndexStatus
+
+// ============================================================================
+// Call Graph API - Query symbol relationships
+// ============================================================================
+
+/** Information about a symbol in the call graph */
+export interface SymbolInfo {
+  /** Symbol ID */
+  id: number
+  /** Symbol name */
+  name: string
+  /** Symbol kind (function, class, method, etc.) */
+  kind: string
+  /** File path containing the symbol */
+  file: string
+  /** Start line number */
+  line: number
+  /** End line number */
+  endLine: number
+  /** Function/method signature */
+  signature?: string
+  /** Visibility (public, private, etc.) */
+  visibility: string
+}
+
+/** A reference to a symbol with context */
+export interface ReferenceInfo {
+  /** Symbol making the reference */
+  symbol: SymbolInfo
+  /** Reference kind (call, import, inherit, implement) */
+  kind: string
+}
+
+/** An edge in the call graph */
+export interface CallGraphEdge {
+  /** Caller symbol ID */
+  callerId: number
+  /** Callee symbol ID */
+  calleeId: number
+  /** Caller symbol name */
+  caller: string
+  /** Callee symbol name */
+  callee: string
+  /** File containing the call site */
+  file: string
+  /** Line number of the call */
+  line: number
+}
+
+/** Call graph statistics */
+export interface CallGraphStats {
+  /** Total number of symbols */
+  totalSymbols: number
+  /** Total number of call edges */
+  totalCalls: number
+  /** Number of functions/methods */
+  functions: number
+  /** Number of classes/structs */
+  classes: number
+}
+
+/** Complete call graph with nodes and edges */
+export interface CallGraph {
+  /** All symbols (nodes) */
+  nodes: Array<SymbolInfo>
+  /** Call relationships (edges) */
+  edges: Array<CallGraphEdge>
+  /** Summary statistics */
+  stats: CallGraphStats
+}
+
+/** Options for call graph queries */
+export interface CallGraphOptions {
+  /** Maximum number of nodes to return (default: unlimited) */
+  maxNodes?: number
+  /** Maximum number of edges to return (default: unlimited) */
+  maxEdges?: number
+}
+
+/**
+ * Find a symbol by name
+ *
+ * Searches the index for all symbols matching the given name.
+ * Requires an index to be built first (use buildIndex).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `name` - Symbol name to search for
+ *
+ * # Returns
+ * Array of matching symbols
+ *
+ * # Example
+ * ```javascript
+ * const { findSymbol, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * const symbols = findSymbol('./my-repo', 'processRequest');
+ * console.log(`Found ${symbols.length} symbols named processRequest`);
+ * ```
+ */
+export declare function findSymbol(path: string, name: string): Array<SymbolInfo>
+
+/**
+ * Get all callers of a symbol
+ *
+ * Returns symbols that call any symbol with the given name.
+ * Requires an index to be built first (use buildIndex).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `symbolName` - Name of the symbol to find callers for
+ *
+ * # Returns
+ * Array of symbols that call the target symbol
+ *
+ * # Example
+ * ```javascript
+ * const { getCallers, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * const callers = getCallers('./my-repo', 'authenticate');
+ * console.log(`authenticate is called by ${callers.length} functions`);
+ * for (const c of callers) {
+ *   console.log(`  ${c.name} at ${c.file}:${c.line}`);
+ * }
+ * ```
+ */
+export declare function getCallers(path: string, symbolName: string): Array<SymbolInfo>
+
+/**
+ * Get all callees of a symbol
+ *
+ * Returns symbols that are called by any symbol with the given name.
+ * Requires an index to be built first (use buildIndex).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `symbolName` - Name of the symbol to find callees for
+ *
+ * # Returns
+ * Array of symbols that the target symbol calls
+ *
+ * # Example
+ * ```javascript
+ * const { getCallees, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * const callees = getCallees('./my-repo', 'main');
+ * console.log(`main calls ${callees.length} functions`);
+ * for (const c of callees) {
+ *   console.log(`  ${c.name} at ${c.file}:${c.line}`);
+ * }
+ * ```
+ */
+export declare function getCallees(path: string, symbolName: string): Array<SymbolInfo>
+
+/**
+ * Get all references to a symbol
+ *
+ * Returns all locations where a symbol is referenced (calls, imports, inheritance).
+ * Requires an index to be built first (use buildIndex).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `symbolName` - Name of the symbol to find references for
+ *
+ * # Returns
+ * Array of reference information including the referencing symbol and kind
+ *
+ * # Example
+ * ```javascript
+ * const { getReferences, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * const refs = getReferences('./my-repo', 'UserService');
+ * console.log(`UserService is referenced ${refs.length} times`);
+ * for (const r of refs) {
+ *   console.log(`  ${r.kind}: ${r.symbol.name} at ${r.symbol.file}:${r.symbol.line}`);
+ * }
+ * ```
+ */
+export declare function getReferences(path: string, symbolName: string): Array<ReferenceInfo>
+
+/**
+ * Get the complete call graph
+ *
+ * Returns all symbols and their call relationships.
+ * Requires an index to be built first (use buildIndex).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `options` - Optional filtering options
+ *
+ * # Returns
+ * Call graph with nodes (symbols), edges (calls), and statistics
+ *
+ * # Example
+ * ```javascript
+ * const { getCallGraph, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * const graph = getCallGraph('./my-repo');
+ * console.log(`Call graph: ${graph.stats.totalSymbols} symbols, ${graph.stats.totalCalls} calls`);
+ *
+ * // Find most called functions
+ * const callCounts = new Map();
+ * for (const edge of graph.edges) {
+ *   callCounts.set(edge.callee, (callCounts.get(edge.callee) || 0) + 1);
+ * }
+ * const sorted = [...callCounts.entries()].sort((a, b) => b[1] - a[1]);
+ * console.log('Most called functions:', sorted.slice(0, 10));
+ * ```
+ */
+export declare function getCallGraph(path: string, options?: CallGraphOptions | undefined | null): CallGraph
+
+/** Async version of findSymbol */
+export declare function findSymbolAsync(path: string, name: string): Promise<Array<SymbolInfo>>
+
+/** Async version of getCallers */
+export declare function getCallersAsync(path: string, symbolName: string): Promise<Array<SymbolInfo>>
+
+/** Async version of getCallees */
+export declare function getCalleesAsync(path: string, symbolName: string): Promise<Array<SymbolInfo>>
+
+/** Async version of getReferences */
+export declare function getReferencesAsync(path: string, symbolName: string): Promise<Array<ReferenceInfo>>
+
+/** Async version of getCallGraph */
+export declare function getCallGraphAsync(path: string, options?: CallGraphOptions | undefined | null): Promise<CallGraph>
+
+// ============================================================================
+// Chunk API - Split repositories into manageable pieces
+// ============================================================================
+
+/** Options for chunking a repository */
+export interface ChunkOptions {
+  /** Chunking strategy: "fixed", "file", "module", "symbol", "semantic", "dependency" */
+  strategy?: string
+  /** Maximum tokens per chunk (default: 8000) */
+  maxTokens?: number
+  /** Token overlap between chunks (default: 0) */
+  overlap?: number
+  /** Target model for token counting (default: "claude") */
+  model?: string
+  /** Output format: "xml", "markdown", "json" (default: "xml") */
+  format?: string
+  /** Sort chunks by priority (core modules first) */
+  priorityFirst?: boolean
+}
+
+/** A chunk of repository content */
+export interface RepoChunk {
+  /** Chunk index (0-based) */
+  index: number
+  /** Total number of chunks */
+  total: number
+  /** Primary focus/topic of this chunk */
+  focus: string
+  /** Estimated token count */
+  tokens: number
+  /** Files included in this chunk */
+  files: Array<string>
+  /** Formatted content of the chunk */
+  content: string
+}
+
+/**
+ * Split a repository into chunks for incremental processing
+ *
+ * Useful for processing large repositories that exceed LLM context limits.
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `options` - Optional chunking options
+ *
+ * # Returns
+ * Array of repository chunks
+ *
+ * # Example
+ * ```javascript
+ * const { chunk } = require('infiniloom-node');
+ *
+ * const chunks = chunk('./large-repo', {
+ *   strategy: 'module',
+ *   maxTokens: 50000,
+ *   model: 'claude'
+ * });
+ *
+ * for (const c of chunks) {
+ *   console.log(`Chunk ${c.index}/${c.total}: ${c.focus} (${c.tokens} tokens)`);
+ *   // Process c.content with LLM
+ * }
+ * ```
+ */
+export declare function chunk(path: string, options?: ChunkOptions | undefined | null): Array<RepoChunk>
+
+// ============================================================================
+// Impact API - Analyze change impact
+// ============================================================================
+
+/** Options for impact analysis */
+export interface ImpactOptions {
+  /** Depth of dependency traversal (1-3, default: 2) */
+  depth?: number
+  /** Include test files in analysis */
+  includeTests?: boolean
+}
+
+/** Symbol affected by a change */
+export interface AffectedSymbol {
+  /** Symbol name */
+  name: string
+  /** Symbol kind (function, class, etc.) */
+  kind: string
+  /** File containing the symbol */
+  file: string
+  /** Line number */
+  line: number
+  /** How the symbol is affected: "direct", "caller", "callee", "dependent" */
+  impactType: string
+}
+
+/** Impact analysis result */
+export interface ImpactResult {
+  /** Files directly changed */
+  changedFiles: Array<string>
+  /** Files that depend on changed files */
+  dependentFiles: Array<string>
+  /** Related test files */
+  testFiles: Array<string>
+  /** Symbols affected by the changes */
+  affectedSymbols: Array<AffectedSymbol>
+  /** Overall impact level: "low", "medium", "high", "critical" */
+  impactLevel: string
+  /** Summary of the impact */
+  summary: string
+}
+
+/**
+ * Analyze the impact of changes to files or symbols
+ *
+ * Requires an index to be built first (use buildIndex).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `files` - Files to analyze (can be paths or globs)
+ * * `options` - Optional analysis options
+ *
+ * # Returns
+ * Impact analysis result
+ *
+ * # Example
+ * ```javascript
+ * const { buildIndex, analyzeImpact } = require('infiniloom-node');
+ *
+ * // Build index first
+ * buildIndex('./my-repo');
+ *
+ * // Analyze impact of changes
+ * const impact = analyzeImpact('./my-repo', ['src/auth.ts']);
+ * console.log(`Impact level: ${impact.impactLevel}`);
+ * console.log(`Affected files: ${impact.dependentFiles.length}`);
+ * ```
+ */
+export declare function analyzeImpact(path: string, files: Array<string>, options?: ImpactOptions | undefined | null): ImpactResult
+
+// ============================================================================
+// Diff Context API - Get context-aware diffs
+// ============================================================================
+
+/** Options for diff context */
+export interface DiffContextOptions {
+  /** Depth of context expansion (1-3, default: 2) */
+  depth?: number
+  /** Token budget for context (default: 50000) */
+  budget?: number
+  /** Include the actual diff content (default: false) */
+  includeDiff?: boolean
+  /** Output format: "xml", "markdown", "json" (default: "xml") */
+  format?: string
+}
+
+/** A changed file with surrounding context */
+export interface DiffFileContext {
+  /** File path */
+  path: string
+  /** Change type: "Added", "Modified", "Deleted", "Renamed" */
+  changeType: string
+  /** Lines added */
+  additions: number
+  /** Lines deleted */
+  deletions: number
+  /** Unified diff content (if includeDiff is true) */
+  diff?: string
+  /** Relevant code context around changes */
+  contextSnippets: Array<string>
+}
+
+/** Symbol context information */
+export interface ContextSymbolInfo {
+  /** Symbol name */
+  name: string
+  /** Symbol kind */
+  kind: string
+  /** File containing symbol */
+  file: string
+  /** Line number */
+  line: number
+  /** Why this symbol is included: "changed", "caller", "callee", "dependent" */
+  reason: string
+  /** Symbol signature/definition */
+  signature?: string
 }
+
+/** Context-aware diff result */
+export interface DiffContextResult {
+  /** Changed files with context */
+  changedFiles: Array<DiffFileContext>
+  /** Related symbols and their context */
+  contextSymbols: Array<ContextSymbolInfo>
+  /** Related test files */
+  relatedTests: Array<string>
+  /** Formatted output (if format specified) */
+  formattedOutput?: string
+  /** Total token count */
+  totalTokens: number
+}
+
+/**
+ * Get context-aware diff with surrounding symbols and dependencies
+ *
+ * Unlike basic diffFiles, this provides semantic context around changes.
+ * Requires an index (will build on-the-fly if not present).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `fromRef` - Starting commit/branch (use "" for unstaged changes)
+ * * `toRef` - Ending commit/branch (use "HEAD" for staged, "" for working tree)
+ * * `options` - Optional context options
+ *
+ * # Returns
+ * Context-aware diff result with related symbols
+ *
+ * # Example
+ * ```javascript
+ * const { getDiffContext } = require('infiniloom-node');
+ *
+ * // Get context for last commit
+ * const context = getDiffContext('./my-repo', 'HEAD~1', 'HEAD', {
+ *   depth: 2,
+ *   budget: 50000,
+ *   includeDiff: true
+ * });
+ *
+ * console.log(`Changed: ${context.changedFiles.length} files`);
+ * console.log(`Related symbols: ${context.contextSymbols.length}`);
+ * console.log(`Related tests: ${context.relatedTests.length}`);
+ * ```
+ */
+export declare function getDiffContext(path: string, fromRef: string, toRef: string, options?: DiffContextOptions | undefined | null): DiffContextResult
+
+// ============================================================================
+// Async API - Async versions of key functions
+// ============================================================================
+
+/**
+ * Async version of pack
+ *
+ * # Example
+ * ```javascript
+ * const { packAsync } = require('infiniloom-node');
+ *
+ * const context = await packAsync('./my-repo', { format: 'xml' });
+ * ```
+ */
+export declare function packAsync(path: string, options?: PackOptions | undefined | null): Promise<string>
+
+/**
+ * Async version of scan
+ *
+ * # Example
+ * ```javascript
+ * const { scanAsync } = require('infiniloom-node');
+ *
+ * const stats = await scanAsync('./my-repo', 'claude');
+ * ```
+ */
+export declare function scanAsync(path: string, model?: string | undefined | null): Promise<ScanStats>
+
+/**
+ * Async version of buildIndex
+ *
+ * # Example
+ * ```javascript
+ * const { buildIndexAsync } = require('infiniloom-node');
+ *
+ * const status = await buildIndexAsync('./my-repo', { force: true });
+ * ```
+ */
+export declare function buildIndexAsync(path: string, options?: IndexOptions | undefined | null): Promise<IndexStatus>
+
+/**
+ * Async version of chunk
+ *
+ * # Example
+ * ```javascript
+ * const { chunkAsync } = require('infiniloom-node');
+ *
+ * const chunks = await chunkAsync('./large-repo', { maxTokens: 50000 });
+ * ```
+ */
+export declare function chunkAsync(path: string, options?: ChunkOptions | undefined | null): Promise<Array<RepoChunk>>
+
+/**
+ * Async version of analyzeImpact
+ *
+ * # Example
+ * ```javascript
+ * const { analyzeImpactAsync } = require('infiniloom-node');
+ *
+ * const impact = await analyzeImpactAsync('./my-repo', ['src/auth.ts']);
+ * ```
+ */
+export declare function analyzeImpactAsync(path: string, files: Array<string>, options?: ImpactOptions | undefined | null): Promise<ImpactResult>
+
+/**
+ * Async version of getDiffContext
+ *
+ * # Example
+ * ```javascript
+ * const { getDiffContextAsync } = require('infiniloom-node');
+ *
+ * const context = await getDiffContextAsync('./my-repo', 'HEAD~1', 'HEAD');
+ * ```
+ */
+export declare function getDiffContextAsync(path: string, fromRef: string, toRef: string, options?: DiffContextOptions | undefined | null): Promise<DiffContextResult>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infiniloom-node",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Node.js bindings for infiniloom - Repository context engine for LLMs",
   "main": "index.js",
   "types": "index.d.ts",