infiniloom-node 0.4.1 → 0.4.4

package/index.d.ts

@@ -258,30 +258,30 @@ export interface GitBlameLine {
   /** Line number (1-indexed) */
   lineNumber: number
 }
-/** Diff line information for structured diff parsing */
+/** A single line change within a diff hunk */
 export interface GitDiffLine {
-  /** Change type: "add", "remove", or "context" */
+  /** Type of change: "add", "remove", or "context" */
   changeType: string
-  /** Line number in old file (for remove/context lines) */
+  /** Line number in the old file (null for additions) */
   oldLine?: number
-  /** Line number in new file (for add/context lines) */
+  /** Line number in the new file (null for deletions) */
   newLine?: number
-  /** Line content (without +/- prefix) */
+  /** The actual line content (without +/- prefix) */
   content: string
 }
-/** Diff hunk information for structured diff parsing */
+/** A diff hunk representing a contiguous block of changes */
 export interface GitDiffHunk {
-  /** Starting line in old file */
+  /** Starting line in the old file */
   oldStart: number
-  /** Number of lines in old file */
+  /** Number of lines in the old file section */
   oldCount: number
-  /** Starting line in new file */
+  /** Starting line in the new file */
   newStart: number
-  /** Number of lines in new file */
+  /** Number of lines in the new file section */
   newCount: number
-  /** Hunk header (e.g., "@@ -1,5 +1,6 @@ function name") */
+  /** Header line (e.g., "@@ -1,5 +1,7 @@ function name") */
   header: string
-  /** Lines in this hunk */
+  /** Individual line changes within this hunk */
   lines: Array<GitDiffLine>
 }
 /** Security finding information */
@@ -317,363 +317,74 @@ export interface SecurityFinding {
  * ```
  */
 export declare function scanSecurity(path: string): Array<SecurityFinding>
-/** Infiniloom class for advanced usage */
-export declare class Infiniloom {
-  /**
-   * Create a new Infiniloom instance
-   *
-   * # Arguments
-   * * `path` - Path to repository root
-   * * `model` - Optional model name (default: "claude")
-   */
-  constructor(path: string, model?: string | undefined | null)
-  /** Get repository statistics (Bug #4 fix - consistent with scan() function) */
-  getStats(): ScanStats
-  /**
-   * Generate a repository map
-   *
-   * # Arguments
-   * * `budget` - Token budget (default: 2000)
-   * * `max_symbols` - Maximum symbols (default: 50)
-   */
-  generateMap(budget?: number | undefined | null, maxSymbols?: number | undefined | null): string
-  /** Pack repository with specific options */
-  pack(options?: PackOptions | undefined | null): string
-  /** Check for security issues (Bug #8 fix - now returns structured findings) */
-  securityScan(): Array<SecurityFinding>
-  /** Check for security issues (legacy format, returns formatted strings) */
-  securityScanFormatted(): Array<string>
+/** 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
 }
 /**
- * Git repository wrapper for Node.js
+ * Build or update the symbol index for a repository
  *
- * Provides access to git operations like status, diff, log, and blame.
+ * 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 { GitRepo } = require('infiniloom-node');
+ * const { buildIndex } = require('infiniloom-node');
  *
- * const repo = new GitRepo('./my-project');
- * console.log(`Branch: ${repo.currentBranch()}`);
- * console.log(`Commit: ${repo.currentCommit()}`);
+ * const status = buildIndex('./my-repo');
+ * console.log(`Indexed ${status.symbolCount} symbols`);
  *
- * for (const file of repo.status()) {
- *   console.log(`${file.status}: ${file.path}`);
- * }
- * ```
- */
-export declare class GitRepo {
-  /**
-   * Open a git repository
-   *
-   * # Arguments
-   * * `path` - Path to the repository
-   *
-   * # Throws
-   * Error if path is not a git repository
-   */
-  constructor(path: string)
-  /**
-   * Get the current branch name
-   *
-   * # Returns
-   * Current branch name (e.g., "main", "feature/xyz")
-   */
-  currentBranch(): string
-  /**
-   * Get the current commit hash
-   *
-   * # Returns
-   * Full SHA-1 hash of HEAD commit
-   */
-  currentCommit(): string
-  /**
-   * Get working tree status
-   *
-   * Returns both staged and unstaged changes.
-   *
-   * # Returns
-   * Array of file status objects
-   */
-  status(): Array<GitFileStatus>
-  /**
-   * Get files changed between two commits
-   *
-   * # Arguments
-   * * `from_ref` - Starting commit/branch/tag
-   * * `to_ref` - Ending commit/branch/tag
-   *
-   * # Returns
-   * Array of changed files with diff stats
-   */
-  diffFiles(fromRef: string, toRef: string): Array<GitChangedFile>
-  /**
-   * Get recent commits
-   *
-   * # Arguments
-   * * `count` - Maximum number of commits to return (default: 10)
-   *
-   * # Returns
-   * Array of commit objects
-   */
-  log(count?: number | undefined | null): Array<GitCommit>
-  /**
-   * Get commits that modified a specific file
-   *
-   * # Arguments
-   * * `path` - File path (relative to repo root)
-   * * `count` - Maximum number of commits to return (default: 10)
-   *
-   * # Returns
-   * Array of commits that modified the file
-   */
-  fileLog(path: string, count?: number | undefined | null): Array<GitCommit>
-  /**
-   * Get blame information for a file
-   *
-   * # Arguments
-   * * `path` - File path (relative to repo root)
-   *
-   * # Returns
-   * Array of blame line objects
-   */
-  blame(path: string): Array<GitBlameLine>
-  /**
-   * Get list of files tracked by git
-   *
-   * # Returns
-   * Array of file paths tracked by git
-   */
-  lsFiles(): Array<string>
-  /**
-   * Get diff content between two commits for a file
-   *
-   * # Arguments
-   * * `from_ref` - Starting commit/branch/tag
-   * * `to_ref` - Ending commit/branch/tag
-   * * `path` - File path (relative to repo root)
-   *
-   * # Returns
-   * Unified diff content as string
-   */
-  diffContent(fromRef: string, toRef: string, path: string): string
-  /**
-   * Get diff content for uncommitted changes in a file
-   *
-   * Includes both staged and unstaged changes compared to HEAD.
-   *
-   * # Arguments
-   * * `path` - File path (relative to repo root)
-   *
-   * # Returns
-   * Unified diff content as string
-   */
-  uncommittedDiff(path: string): string
-  /**
-   * Get diff for all uncommitted changes
-   *
-   * Returns combined diff for all changed files.
-   *
-   * # Returns
-   * Unified diff content as string
-   */
-  allUncommittedDiffs(): string
-  /**
-   * Check if a file has uncommitted changes
-   *
-   * # Arguments
-   * * `path` - File path (relative to repo root)
-   *
-   * # Returns
-   * True if file has changes, false otherwise
-   */
-  hasChanges(path: string): boolean
-  /**
-   * Get the last commit that modified a file
-   *
-   * # Arguments
-   * * `path` - File path (relative to repo root)
-   *
-   * # Returns
-   * Commit information object
-   */
-  lastModifiedCommit(path: string): GitCommit
-  /**
-   * Get file change frequency in recent days
-   *
-   * Useful for determining file importance based on recent activity.
-   *
-   * # Arguments
-   * * `path` - File path (relative to repo root)
-   * * `days` - Number of days to look back (default: 30)
-   *
-   * # Returns
-   * 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');
+ * // 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 */
@@ -693,15 +404,17 @@ export interface SymbolInfo {
   /** 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
+  /** File path containing the reference (convenience field, same as symbol.file) */
+  file: string
+  /** Line number of the reference (convenience field, same as symbol.line) */
+  line: number
 }
-
 /** An edge in the call graph */
 export interface CallGraphEdge {
   /** Caller symbol ID */
@@ -717,7 +430,6 @@ export interface CallGraphEdge {
   /** Line number of the call */
   line: number
 }
-
 /** Call graph statistics */
 export interface CallGraphStats {
   /** Total number of symbols */
@@ -729,7 +441,6 @@ export interface CallGraphStats {
   /** Number of classes/structs */
   classes: number
 }
-
 /** Complete call graph with nodes and edges */
 export interface CallGraph {
   /** All symbols (nodes) */
@@ -739,7 +450,6 @@ export interface CallGraph {
   /** Summary statistics */
   stats: CallGraphStats
 }
-
 /** Options for call graph queries */
 export interface CallGraphOptions {
   /** Maximum number of nodes to return (default: unlimited) */
@@ -747,12 +457,11 @@ export interface CallGraphOptions {
   /** 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).
+ * Requires an index to be built first (use `buildIndex`).
  *
  * # Arguments
  * * `path` - Path to repository root
@@ -771,16 +480,15 @@ export interface CallGraphOptions {
  * ```
  */
 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).
+ * Requires an index to be built first (use `buildIndex`).
  *
  * # Arguments
  * * `path` - Path to repository root
- * * `symbolName` - Name of the symbol to find callers for
+ * * `symbol_name` - Name of the symbol to find callers for
  *
  * # Returns
  * Array of symbols that call the target symbol
@@ -798,16 +506,15 @@ export declare function findSymbol(path: string, name: string): Array<SymbolInfo
  * ```
  */
 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).
+ * Requires an index to be built first (use `buildIndex`).
  *
  * # Arguments
  * * `path` - Path to repository root
- * * `symbolName` - Name of the symbol to find callees for
+ * * `symbol_name` - Name of the symbol to find callees for
  *
  * # Returns
  * Array of symbols that the target symbol calls
@@ -825,16 +532,15 @@ export declare function getCallers(path: string, symbolName: string): Array<Symb
  * ```
  */
 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).
+ * Requires an index to be built first (use `buildIndex`).
  *
  * # Arguments
  * * `path` - Path to repository root
- * * `symbolName` - Name of the symbol to find references for
+ * * `symbol_name` - Name of the symbol to find references for
  *
  * # Returns
  * Array of reference information including the referencing symbol and kind
@@ -852,12 +558,11 @@ export declare function getCallees(path: string, symbolName: string): Array<Symb
  * ```
  */
 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).
+ * Requires an index to be built first (use `buildIndex`).
  *
  * # Arguments
  * * `path` - Path to repository root
@@ -884,26 +589,16 @@ export declare function getReferences(path: string, symbolName: string): Array<R
  * ```
  */
 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" */
@@ -919,7 +614,6 @@ export interface ChunkOptions {
   /** Sort chunks by priority (core modules first) */
   priorityFirst?: boolean
 }
-
 /** A chunk of repository content */
 export interface RepoChunk {
   /** Chunk index (0-based) */
@@ -935,7 +629,6 @@ export interface RepoChunk {
   /** Formatted content of the chunk */
   content: string
 }
-
 /**
  * Split a repository into chunks for incremental processing
  *
@@ -965,11 +658,6 @@ export interface RepoChunk {
  * ```
  */
 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) */
@@ -977,7 +665,6 @@ export interface ImpactOptions {
   /** Include test files in analysis */
   includeTests?: boolean
 }
-
 /** Symbol affected by a change */
 export interface AffectedSymbol {
   /** Symbol name */
@@ -991,7 +678,6 @@ export interface AffectedSymbol {
   /** How the symbol is affected: "direct", "caller", "callee", "dependent" */
   impactType: string
 }
-
 /** Impact analysis result */
 export interface ImpactResult {
   /** Files directly changed */
@@ -1007,7 +693,6 @@ export interface ImpactResult {
   /** Summary of the impact */
   summary: string
 }
-
 /**
  * Analyze the impact of changes to files or symbols
  *
@@ -1035,11 +720,6 @@ export interface ImpactResult {
  * ```
  */
 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) */
@@ -1051,7 +731,19 @@ export interface DiffContextOptions {
   /** Output format: "xml", "markdown", "json" (default: "xml") */
   format?: 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
+}
 /** A changed file with surrounding context */
 export interface DiffFileContext {
   /** File path */
@@ -1062,12 +754,11 @@ export interface DiffFileContext {
   additions: number
   /** Lines deleted */
   deletions: number
-  /** Unified diff content (if includeDiff is true) */
+  /** Unified diff content (if include_diff is true) */
   diff?: string
   /** Relevant code context around changes */
   contextSnippets: Array<string>
 }
-
 /** Symbol context information */
 export interface ContextSymbolInfo {
   /** Symbol name */
@@ -1083,21 +774,6 @@ export interface ContextSymbolInfo {
   /** 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
  *
@@ -1106,8 +782,8 @@ export interface DiffContextResult {
  *
  * # 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)
+ * * `from_ref` - Starting commit/branch (use "" for unstaged changes)
+ * * `to_ref` - Ending commit/branch (use "HEAD" for staged, "" for working tree)
  * * `options` - Optional context options
  *
  * # Returns
@@ -1130,11 +806,6 @@ export interface DiffContextResult {
  * ```
  */
 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
  *
@@ -1146,7 +817,6 @@ export declare function getDiffContext(path: string, fromRef: string, toRef: str
  * ```
  */
 export declare function packAsync(path: string, options?: PackOptions | undefined | null): Promise<string>
-
 /**
  * Async version of scan
  *
@@ -1158,7 +828,6 @@ export declare function packAsync(path: string, options?: PackOptions | undefine
  * ```
  */
 export declare function scanAsync(path: string, model?: string | undefined | null): Promise<ScanStats>
-
 /**
  * Async version of buildIndex
  *
@@ -1170,7 +839,6 @@ export declare function scanAsync(path: string, model?: string | undefined | nul
  * ```
  */
 export declare function buildIndexAsync(path: string, options?: IndexOptions | undefined | null): Promise<IndexStatus>
-
 /**
  * Async version of chunk
  *
@@ -1182,7 +850,6 @@ export declare function buildIndexAsync(path: string, options?: IndexOptions | u
  * ```
  */
 export declare function chunkAsync(path: string, options?: ChunkOptions | undefined | null): Promise<Array<RepoChunk>>
-
 /**
  * Async version of analyzeImpact
  *
@@ -1194,7 +861,6 @@ export declare function chunkAsync(path: string, options?: ChunkOptions | undefi
  * ```
  */
 export declare function analyzeImpactAsync(path: string, files: Array<string>, options?: ImpactOptions | undefined | null): Promise<ImpactResult>
-
 /**
  * Async version of getDiffContext
  *
@@ -1206,3 +872,458 @@ export declare function analyzeImpactAsync(path: string, files: Array<string>, o
  * ```
  */
 export declare function getDiffContextAsync(path: string, fromRef: string, toRef: string, options?: DiffContextOptions | undefined | null): Promise<DiffContextResult>
+/** Options for filtering symbols */
+export interface SymbolFilter {
+  /** Filter by symbol kind: "function", "class", "method", etc. */
+  kind?: string
+  /** Filter by visibility: "public", "private", "protected" */
+  visibility?: string
+}
+/** A call site where a symbol is called */
+export interface CallSite {
+  /** Name of the calling function/method */
+  caller: string
+  /** Name of the function/method being called */
+  callee: string
+  /** File containing the call */
+  file: string
+  /** Line number of the call (1-indexed) */
+  line: number
+  /** Column number of the call (0-indexed, if available) */
+  column?: number
+  /** Caller symbol ID */
+  callerId: number
+  /** Callee symbol ID */
+  calleeId: number
+}
+/**
+ * Get all symbols in a specific file
+ *
+ * Requires an index to be built first (use `buildIndex`).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `file_path` - Relative path to the file within the repository
+ * * `filter` - Optional filter for symbol kind/visibility
+ *
+ * # Returns
+ * Array of symbols defined in the file
+ *
+ * # Example
+ * ```javascript
+ * const { getSymbolsInFile, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * const symbols = getSymbolsInFile('./my-repo', 'src/auth.ts');
+ * console.log(`Found ${symbols.length} symbols in auth.ts`);
+ * for (const s of symbols) {
+ *   console.log(`  ${s.kind}: ${s.name} at line ${s.line}`);
+ * }
+ * ```
+ */
+export declare function getSymbolsInFile(path: string, filePath: string, filter?: SymbolFilter | undefined | null): Array<SymbolInfo>
+/**
+ * Get the source code of a symbol
+ *
+ * Reads the file and extracts the source code for the specified symbol.
+ * Requires an index to be built first (use `buildIndex`).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `symbol_name` - Name of the symbol to get source for
+ * * `file_path` - Optional file path to disambiguate when multiple symbols have the same name
+ *
+ * # Returns
+ * Source code of the symbol (or the first matching symbol if multiple exist)
+ *
+ * # Example
+ * ```javascript
+ * const { getSymbolSource, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * const source = getSymbolSource('./my-repo', 'authenticate', 'src/auth.ts');
+ * console.log(source);
+ * ```
+ */
+export declare function getSymbolSource(path: string, symbolName: string, filePath?: string | undefined | null): string
+/**
+ * Get symbols that were changed in a diff
+ *
+ * Parses the diff between two refs and identifies which symbols were modified.
+ * Requires an index to be built first (use `buildIndex`).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `from_ref` - Starting commit/branch (e.g., "main", "HEAD~1")
+ * * `to_ref` - Ending commit/branch (e.g., "HEAD", "feature-branch")
+ *
+ * # Returns
+ * Array of symbols that were modified in the diff
+ *
+ * # Example
+ * ```javascript
+ * const { getChangedSymbols, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * const changed = getChangedSymbols('./my-repo', 'main', 'HEAD');
+ * console.log(`${changed.length} symbols were modified`);
+ * for (const s of changed) {
+ *   console.log(`  ${s.kind}: ${s.name} in ${s.file}`);
+ * }
+ * ```
+ */
+export declare function getChangedSymbols(path: string, fromRef: string, toRef: string): Array<SymbolInfo>
+/**
+ * Get test files related to a source file
+ *
+ * Finds test files that:
+ * 1. Import the specified file
+ * 2. Match common test naming conventions (e.g., foo.ts -> foo.test.ts, test_foo.py)
+ *
+ * Requires an index to be built first (use `buildIndex`).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `file_path` - Relative path to the source file
+ *
+ * # Returns
+ * Array of test file paths related to the source file
+ *
+ * # Example
+ * ```javascript
+ * const { getTestsForFile, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * const tests = getTestsForFile('./my-repo', 'src/auth.ts');
+ * console.log(`Found ${tests.length} test files for auth.ts`);
+ * for (const t of tests) {
+ *   console.log(`  ${t}`);
+ * }
+ * ```
+ */
+export declare function getTestsForFile(path: string, filePath: string): Array<string>
+/**
+ * Get call sites where a symbol is called
+ *
+ * Returns the locations where a function/method is called, with exact line numbers.
+ * This is useful for PR review tools that need to post inline comments.
+ *
+ * The function scans the caller's body to find the actual line where the callee is called,
+ * rather than just returning the caller's definition line.
+ *
+ * Requires an index to be built first (use `buildIndex`).
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `symbol_name` - Name of the symbol to find call sites for
+ *
+ * # Returns
+ * Array of call sites with caller information and line numbers
+ *
+ * # Example
+ * ```javascript
+ * const { getCallSites, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * const callSites = getCallSites('./my-repo', 'authenticate');
+ * console.log(`authenticate is called from ${callSites.length} locations`);
+ * for (const site of callSites) {
+ *   console.log(`  ${site.caller} in ${site.file}:${site.line}`);
+ * }
+ * ```
+ */
+export declare function getCallSites(path: string, symbolName: string): Array<CallSite>
+/** Async version of getSymbolsInFile */
+export declare function getSymbolsInFileAsync(path: string, filePath: string, filter?: SymbolFilter | undefined | null): Promise<Array<SymbolInfo>>
+/** Async version of getSymbolSource */
+export declare function getSymbolSourceAsync(path: string, symbolName: string, filePath?: string | undefined | null): Promise<string>
+/** Async version of getChangedSymbols */
+export declare function getChangedSymbolsAsync(path: string, fromRef: string, toRef: string): Promise<Array<SymbolInfo>>
+/** Async version of getTestsForFile */
+export declare function getTestsForFileAsync(path: string, filePath: string): Promise<Array<string>>
+/** Async version of getCallSites */
+export declare function getCallSitesAsync(path: string, symbolName: string): Promise<Array<CallSite>>
+/** Infiniloom class for advanced usage */
+export declare class Infiniloom {
+  /**
+   * Create a new Infiniloom instance
+   *
+   * # Arguments
+   * * `path` - Path to repository root
+   * * `model` - Optional model name (default: "claude")
+   */
+  constructor(path: string, model?: string | undefined | null)
+  /** Get repository statistics (Bug #4 fix - consistent with scan() function) */
+  getStats(): ScanStats
+  /**
+   * Generate a repository map
+   *
+   * # Arguments
+   * * `budget` - Token budget (default: 2000)
+   * * `max_symbols` - Maximum symbols (default: 50)
+   */
+  generateMap(budget?: number | undefined | null, maxSymbols?: number | undefined | null): string
+  /** Pack repository with specific options */
+  pack(options?: PackOptions | undefined | null): string
+  /** Check for security issues (Bug #8 fix - now returns structured findings) */
+  securityScan(): Array<SecurityFinding>
+  /** Check for security issues (legacy format, returns formatted strings) */
+  securityScanFormatted(): Array<string>
+}
+/**
+ * Git repository wrapper for Node.js
+ *
+ * Provides access to git operations like status, diff, log, and blame.
+ *
+ * # Example
+ * ```javascript
+ * const { GitRepo } = require('infiniloom-node');
+ *
+ * const repo = new GitRepo('./my-project');
+ * console.log(`Branch: ${repo.currentBranch()}`);
+ * console.log(`Commit: ${repo.currentCommit()}`);
+ *
+ * for (const file of repo.status()) {
+ *   console.log(`${file.status}: ${file.path}`);
+ * }
+ * ```
+ */
+export declare class GitRepo {
+  /**
+   * Open a git repository
+   *
+   * # Arguments
+   * * `path` - Path to the repository
+   *
+   * # Throws
+   * Error if path is not a git repository
+   */
+  constructor(path: string)
+  /**
+   * Get the current branch name
+   *
+   * # Returns
+   * Current branch name (e.g., "main", "feature/xyz")
+   */
+  currentBranch(): string
+  /**
+   * Get the current commit hash
+   *
+   * # Returns
+   * Full SHA-1 hash of HEAD commit
+   */
+  currentCommit(): string
+  /**
+   * Get working tree status
+   *
+   * Returns both staged and unstaged changes.
+   *
+   * # Returns
+   * Array of file status objects
+   */
+  status(): Array<GitFileStatus>
+  /**
+   * Get files changed between two commits
+   *
+   * # Arguments
+   * * `from_ref` - Starting commit/branch/tag
+   * * `to_ref` - Ending commit/branch/tag
+   *
+   * # Returns
+   * Array of changed files with diff stats
+   */
+  diffFiles(fromRef: string, toRef: string): Array<GitChangedFile>
+  /**
+   * Get recent commits
+   *
+   * # Arguments
+   * * `count` - Maximum number of commits to return (default: 10)
+   *
+   * # Returns
+   * Array of commit objects
+   */
+  log(count?: number | undefined | null): Array<GitCommit>
+  /**
+   * Get commits that modified a specific file
+   *
+   * # Arguments
+   * * `path` - File path (relative to repo root)
+   * * `count` - Maximum number of commits to return (default: 10)
+   *
+   * # Returns
+   * Array of commits that modified the file
+   */
+  fileLog(path: string, count?: number | undefined | null): Array<GitCommit>
+  /**
+   * Get blame information for a file
+   *
+   * # Arguments
+   * * `path` - File path (relative to repo root)
+   *
+   * # Returns
+   * Array of blame line objects
+   */
+  blame(path: string): Array<GitBlameLine>
+  /**
+   * Get list of files tracked by git
+   *
+   * # Returns
+   * Array of file paths tracked by git
+   */
+  lsFiles(): Array<string>
+  /**
+   * Get diff content between two commits for a file
+   *
+   * # Arguments
+   * * `from_ref` - Starting commit/branch/tag
+   * * `to_ref` - Ending commit/branch/tag
+   * * `path` - File path (relative to repo root)
+   *
+   * # Returns
+   * Unified diff content as string
+   */
+  diffContent(fromRef: string, toRef: string, path: string): string
+  /**
+   * Get diff content for uncommitted changes in a file
+   *
+   * Includes both staged and unstaged changes compared to HEAD.
+   *
+   * # Arguments
+   * * `path` - File path (relative to repo root)
+   *
+   * # Returns
+   * Unified diff content as string
+   */
+  uncommittedDiff(path: string): string
+  /**
+   * Get diff for all uncommitted changes
+   *
+   * Returns combined diff for all changed files.
+   *
+   * # Returns
+   * Unified diff content as string
+   */
+  allUncommittedDiffs(): string
+  /**
+   * Check if a file has uncommitted changes
+   *
+   * # Arguments
+   * * `path` - File path (relative to repo root)
+   *
+   * # Returns
+   * True if file has changes, false otherwise
+   */
+  hasChanges(path: string): boolean
+  /**
+   * Get the last commit that modified a file
+   *
+   * # Arguments
+   * * `path` - File path (relative to repo root)
+   *
+   * # Returns
+   * Commit information object
+   */
+  lastModifiedCommit(path: string): GitCommit
+  /**
+   * Get file change frequency in recent days
+   *
+   * Useful for determining file importance based on recent activity.
+   *
+   * # Arguments
+   * * `path` - File path (relative to repo root)
+   * * `days` - Number of days to look back (default: 30)
+   *
+   * # Returns
+   * 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)
+   * * `git_ref` - Git ref (commit hash, branch name, tag, HEAD~n, etc.)
+   *
+   * # Returns
+   * File content as string
+   *
+   * # Example
+   * ```javascript
+   * const { GitRepo } = require('infiniloom-node');
+   *
+   * const repo = new GitRepo('./my-project');
+   * const oldVersion = repo.fileAtRef('src/main.ts', 'HEAD~5');
+   * const mainVersion = repo.fileAtRef('src/main.ts', '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
+   * * `from_ref` - Starting ref (e.g., "main", "HEAD~5", commit hash)
+   * * `to_ref` - 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 information
+   *
+   * # Example
+   * ```javascript
+   * const { GitRepo } = require('infiniloom-node');
+   *
+   * const repo = new GitRepo('./my-project');
+   * const hunks = repo.diffHunks('main', 'HEAD', 'src/index.ts');
+   * 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 { GitRepo } = require('infiniloom-node');
+   *
+   * const repo = new GitRepo('./my-project');
+   * const hunks = repo.uncommittedHunks('src/index.ts');
+   * 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 { GitRepo } = require('infiniloom-node');
+   *
+   * const repo = new GitRepo('./my-project');
+   * const hunks = repo.stagedHunks('src/index.ts');
+   * console.log(`${hunks.length} hunks staged for commit`);
+   * ```
+   */
+  stagedHunks(path?: string | undefined | null): Array<GitDiffHunk>
+}