infiniloom-node 0.4.6 → 0.4.8

package/README.md

@@ -187,10 +187,10 @@ Scan a repository with full configuration options.
 Count tokens in text for a specific model.
 
 **Parameters:**
-- `text` - Text to tokenize
+- `text` - Text to tokenize (null/undefined returns 0)
 - `model` - Optional model name (default: "claude")
 
-**Returns:** Token count
+**Returns:** Token count (0 for empty, null, or undefined input)
 
 #### `semanticCompress(text: string, similarityThreshold?: number, budgetRatio?: number): string`
 
@@ -198,10 +198,10 @@ Compress text using semantic compression while preserving important content.
 
 **Parameters:**
 - `text` - Text to compress
-- `similarityThreshold` - Threshold for grouping similar chunks (0.0-1.0, default: 0.7)
-- `budgetRatio` - Target size as ratio of original (0.0-1.0, default: 0.5)
+- `similarityThreshold` - Threshold for grouping similar chunks (0.0-1.0, default: 0.7). Note: Only affects output when built with "embeddings" feature.
+- `budgetRatio` - Target size as ratio of original (0.0-1.0, default: 0.5). Lower values = more aggressive compression. Affects content as small as 10 characters. Use 1.0 to preserve content unchanged.
 
-**Returns:** Compressed text
+**Returns:** Compressed text (may include truncation markers showing percentage and character counts)
 
 #### `scanSecurity(path: string): SecurityFinding[]`
 
@@ -422,6 +422,9 @@ for (const sym of impact.affectedSymbols) {
 interface ImpactOptions {
   depth?: number;         // Depth of dependency traversal (1-3, default: 2)
   includeTests?: boolean; // Include test files in analysis (default: false)
+  model?: string;         // Target model for token counting (default: "claude")
+  exclude?: string[];     // Glob patterns to exclude (e.g., ["**/*.test.ts", "dist/**"])
+  include?: string[];     // Glob patterns to include (e.g., ["src/**/*.ts"])
 }
 ```
 
@@ -495,6 +498,10 @@ interface DiffContextOptions {
   depth?: number;       // Context expansion depth (1-3, default: 2)
   budget?: number;      // Token budget for context (default: 50000)
   includeDiff?: boolean; // Include actual diff content (default: false)
+  format?: string;      // Output format: "xml", "markdown", "json" (default: "xml")
+  model?: string;       // Target model for token counting (default: "claude")
+  exclude?: string[];   // Glob patterns to exclude (e.g., ["**/*.test.ts", "dist/**"])
+  include?: string[];   // Glob patterns to include (e.g., ["src/**/*.ts"])
 }
 ```
 
@@ -560,7 +567,7 @@ interface PackOptions {
   exclude?: string[];        // Glob patterns to exclude (e.g., ["**/*.test.ts"])
   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)
+  tokenBudget?: number;      // Limit total output tokens (0 = no limit, negative values rejected)
   // 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")

package/index.d.ts

@@ -29,7 +29,10 @@ export interface PackOptions {
   includeTests?: boolean
   /** Minimum security severity to block on: "critical", "high", "medium", "low" (default: "critical") */
   securityThreshold?: string
-  /** Token budget for total output (0 = no limit). Files are included by importance until budget is reached. */
+  /**
+   * Token budget for total output (0 = no limit). Files are included by importance until budget is reached.
+   * Negative values are invalid and will throw an error.
+   */
   tokenBudget?: number
   /** Only include files changed in git (requires baseSha or uses uncommitted changes) */
   changedOnly?: boolean
@@ -154,7 +157,7 @@ export declare function scanWithOptions(path: string, options?: ScanOptions | un
  * Count tokens in text for a specific model
  *
  * # Arguments
- * * `text` - Text to tokenize
+ * * `text` - Text to tokenize (null/undefined returns 0)
  * * `model` - Optional model name (default: "claude")
  *
  * # Returns
@@ -168,26 +171,39 @@ export declare function scanWithOptions(path: string, options?: ScanOptions | un
  * console.log(`Tokens: ${count}`);
  * ```
  */
-export declare function countTokens(text: string, model?: string | undefined | null): number
+export declare function countTokens(text?: string | undefined | null, model?: string | undefined | null): number
 /**
  * Compress text using semantic compression
  *
  * Uses heuristic-based compression to reduce content while preserving meaning.
- * When built with the "embeddings" feature, uses neural networks for clustering.
+ * The compression works in three modes:
+ *
+ * 1. **Repetitive content**: Detects and collapses repeated patterns/lines
+ * 2. **Chunk-based**: Splits content at paragraph/sentence boundaries and keeps a ratio
+ * 3. **Character-based**: For content without boundaries, truncates to budget_ratio
  *
  * # Arguments
  * * `text` - Text to compress
- * * `similarity_threshold` - Threshold for grouping similar chunks (0.0-1.0, default: 0.7)
- * * `budget_ratio` - Target size as ratio of original (0.0-1.0, default: 0.5)
+ * * `similarity_threshold` - Threshold for grouping similar chunks (0.0-1.0, default: 0.7).
+ *   Note: Only affects output when built with "embeddings" feature.
+ * * `budget_ratio` - Target size as ratio of original (0.0-1.0, default: 0.5).
+ *   Lower values = more aggressive compression. For example:
+ *   - 0.5 = keep ~50% of content
+ *   - 0.3 = keep ~30% of content
+ *   - 1.0 = no compression
  *
  * # Returns
- * Compressed text
+ * Compressed text with markers indicating what was removed
  *
  * # Example
  * ```javascript
  * const { semanticCompress } = require('infiniloom-node');
  *
+ * // Compress to ~30% of original size
  * const compressed = semanticCompress(longText, 0.7, 0.3);
+ *
+ * // Aggressive compression to ~20%
+ * const veryCompressed = semanticCompress(longText, 0.7, 0.2);
  * ```
  */
 export declare function semanticCompress(text: string, similarityThreshold?: number | undefined | null, budgetRatio?: number | undefined | null): string
@@ -325,6 +341,13 @@ export interface IndexOptions {
   includeTests?: boolean
   /** Maximum file size to index (bytes) */
   maxFileSize?: number
+  /** Directories/patterns to exclude (e.g., ["node_modules", "dist", "vendor", "*.generated.*"]) */
+  exclude?: Array<string>
+  /**
+   * Incremental update - only re-index changed files (default: false)
+   * When true, compares file hashes with existing index and only rebuilds changed files
+   */
+  incremental?: boolean
 }
 /** Index status information */
 export interface IndexStatus {
@@ -338,6 +361,10 @@ export interface IndexStatus {
   lastBuilt?: string
   /** Index version */
   version?: string
+  /** Number of files updated in incremental build (only set for incremental builds) */
+  filesUpdated?: number
+  /** Whether this was an incremental update */
+  incremental?: boolean
 }
 /**
  * Build or update the symbol index for a repository
@@ -395,9 +422,9 @@ export interface SymbolInfo {
   kind: string
   /** File path containing the symbol */
   file: string
-  /** Start line number */
+  /** Start line number (1-indexed, consistent with editors/IDEs) */
   line: number
-  /** End line number */
+  /** End line number (1-indexed, consistent with editors/IDEs) */
   endLine: number
   /** Function/method signature */
   signature?: string
@@ -412,7 +439,11 @@ export interface ReferenceInfo {
   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 of the reference (1-indexed, convenience field, same as symbol.line)
+   * Note: This is the line where the referencing symbol is defined, not where the
+   * actual reference occurs. For call site line numbers, use getCallSites() instead.
+   */
   line: number
 }
 /** An edge in the call graph */
@@ -457,6 +488,20 @@ export interface CallGraphOptions {
   /** Maximum number of edges to return (default: unlimited) */
   maxEdges?: number
 }
+/**
+ * Feature #2: Filter options for symbol queries
+ *
+ * Allows filtering query results by symbol kind.
+ */
+export interface QueryFilter {
+  /**
+   * Filter by symbol kinds: "function", "method", "class", "struct", "interface", "trait", "enum", etc.
+   * If specified, only symbols of these kinds are returned.
+   */
+  kinds?: Array<string>
+  /** Exclude specific kinds (e.g., exclude "import" to skip import statements) */
+  excludeKinds?: Array<string>
+}
 /**
  * Find a symbol by name
  *
@@ -558,6 +603,119 @@ export declare function getCallees(path: string, symbolName: string): Array<Symb
  * ```
  */
 export declare function getReferences(path: string, symbolName: string): Array<ReferenceInfo>
+/**
+ * Find symbols by name with filtering
+ *
+ * Like `findSymbol`, but allows filtering results by symbol kind.
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `name` - Symbol name to search for
+ * * `filter` - Optional filter for symbol kinds
+ *
+ * # Returns
+ * Array of matching symbols that pass the filter
+ *
+ * # Example
+ * ```javascript
+ * const { findSymbolFiltered, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * // Find only functions named "process"
+ * const funcs = findSymbolFiltered('./my-repo', 'process', {
+ *   kinds: ['function', 'method']
+ * });
+ * // Find all symbols except imports
+ * const noImports = findSymbolFiltered('./my-repo', 'User', {
+ *   excludeKinds: ['import']
+ * });
+ * ```
+ */
+export declare function findSymbolFiltered(path: string, name: string, filter?: QueryFilter | undefined | null): Array<SymbolInfo>
+/**
+ * Get callers of a symbol with filtering
+ *
+ * Like `getCallers`, but allows filtering results by symbol kind.
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `symbol_name` - Name of the symbol to find callers for
+ * * `filter` - Optional filter for symbol kinds
+ *
+ * # Returns
+ * Array of filtered calling symbols
+ *
+ * # Example
+ * ```javascript
+ * const { getCallersFiltered, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * // Get only function callers (not class methods)
+ * const callers = getCallersFiltered('./my-repo', 'authenticate', {
+ *   kinds: ['function']
+ * });
+ * ```
+ */
+export declare function getCallersFiltered(path: string, symbolName: string, filter?: QueryFilter | undefined | null): Array<SymbolInfo>
+/**
+ * Get callees of a symbol with filtering
+ *
+ * Like `getCallees`, but allows filtering results by symbol kind.
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `symbol_name` - Name of the symbol to find callees for
+ * * `filter` - Optional filter for symbol kinds
+ *
+ * # Returns
+ * Array of filtered called symbols
+ *
+ * # Example
+ * ```javascript
+ * const { getCalleesFiltered, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * // Get only function calls (not method calls)
+ * const callees = getCalleesFiltered('./my-repo', 'main', {
+ *   kinds: ['function']
+ * });
+ * ```
+ */
+export declare function getCalleesFiltered(path: string, symbolName: string, filter?: QueryFilter | undefined | null): Array<SymbolInfo>
+/**
+ * Get references to a symbol with filtering
+ *
+ * Like `getReferences`, but allows filtering results by symbol kind.
+ *
+ * # Arguments
+ * * `path` - Path to repository root
+ * * `symbol_name` - Name of the symbol to find references for
+ * * `filter` - Optional filter for referencing symbol kinds
+ *
+ * # Returns
+ * Array of filtered reference information
+ *
+ * # Example
+ * ```javascript
+ * const { getReferencesFiltered, buildIndex } = require('infiniloom-node');
+ *
+ * buildIndex('./my-repo');
+ * // Get only call references from functions
+ * const refs = getReferencesFiltered('./my-repo', 'UserService', {
+ *   kinds: ['function', 'method'],
+ *   excludeKinds: ['import']
+ * });
+ * ```
+ */
+export declare function getReferencesFiltered(path: string, symbolName: string, filter?: QueryFilter | undefined | null): Array<ReferenceInfo>
+/** Async version of findSymbolFiltered */
+export declare function findSymbolFilteredAsync(path: string, name: string, filter?: QueryFilter | undefined | null): Promise<Array<SymbolInfo>>
+/** Async version of getCallersFiltered */
+export declare function getCallersFilteredAsync(path: string, symbolName: string, filter?: QueryFilter | undefined | null): Promise<Array<SymbolInfo>>
+/** Async version of getCalleesFiltered */
+export declare function getCalleesFilteredAsync(path: string, symbolName: string, filter?: QueryFilter | undefined | null): Promise<Array<SymbolInfo>>
+/** Async version of getReferencesFiltered */
+export declare function getReferencesFilteredAsync(path: string, symbolName: string, filter?: QueryFilter | undefined | null): Promise<Array<ReferenceInfo>>
 /**
  * Get the complete call graph
  *
@@ -613,6 +771,8 @@ export interface ChunkOptions {
   format?: string
   /** Sort chunks by priority (core modules first) */
   priorityFirst?: boolean
+  /** Directories/patterns to exclude (e.g., ["vendor", "generated", "*.test.*"]) */
+  exclude?: Array<string>
 }
 /** A chunk of repository content */
 export interface RepoChunk {
@@ -664,6 +824,12 @@ export interface ImpactOptions {
   depth?: number
   /** Include test files in analysis */
   includeTests?: boolean
+  /** Target model for token counting (default: "claude") */
+  model?: string
+  /** Glob patterns to exclude (e.g., ["**/*.test.ts", "dist/**"]) */
+  exclude?: Array<string>
+  /** Glob patterns to include (e.g., ["src/**/*.ts"]) */
+  include?: Array<string>
 }
 /** Symbol affected by a change */
 export interface AffectedSymbol {
@@ -730,6 +896,12 @@ export interface DiffContextOptions {
   includeDiff?: boolean
   /** Output format: "xml", "markdown", "json" (default: "xml") */
   format?: string
+  /** Target model for token counting (default: "claude") */
+  model?: string
+  /** Glob patterns to exclude (e.g., ["**/*.test.ts", "dist/**"]) */
+  exclude?: Array<string>
+  /** Glob patterns to include (e.g., ["src/**/*.ts"]) */
+  include?: Array<string>
 }
 /** Context-aware diff result */
 export interface DiffContextResult {

package/index.js

@@ -310,7 +310,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { pack, scan, scanWithOptions, countTokens, Infiniloom, semanticCompress, isGitRepo, GitRepo, scanSecurity, buildIndex, indexStatus, findSymbol, getCallers, getCallees, getReferences, getCallGraph, findSymbolAsync, getCallersAsync, getCalleesAsync, getReferencesAsync, getCallGraphAsync, chunk, analyzeImpact, getDiffContext, packAsync, scanAsync, buildIndexAsync, chunkAsync, analyzeImpactAsync, getDiffContextAsync, getSymbolsInFile, getSymbolSource, getChangedSymbols, getTestsForFile, getCallSites, getSymbolsInFileAsync, getSymbolSourceAsync, getChangedSymbolsAsync, getTestsForFileAsync, getCallSitesAsync, getChangedSymbolsFiltered, getTransitiveCallers, getCallSitesWithContext, getChangedSymbolsFilteredAsync, getTransitiveCallersAsync, getCallSitesWithContextAsync } = nativeBinding
+const { pack, scan, scanWithOptions, countTokens, Infiniloom, semanticCompress, isGitRepo, GitRepo, scanSecurity, buildIndex, indexStatus, findSymbol, getCallers, getCallees, getReferences, findSymbolFiltered, getCallersFiltered, getCalleesFiltered, getReferencesFiltered, findSymbolFilteredAsync, getCallersFilteredAsync, getCalleesFilteredAsync, getReferencesFilteredAsync, getCallGraph, findSymbolAsync, getCallersAsync, getCalleesAsync, getReferencesAsync, getCallGraphAsync, chunk, analyzeImpact, getDiffContext, packAsync, scanAsync, buildIndexAsync, chunkAsync, analyzeImpactAsync, getDiffContextAsync, getSymbolsInFile, getSymbolSource, getChangedSymbols, getTestsForFile, getCallSites, getSymbolsInFileAsync, getSymbolSourceAsync, getChangedSymbolsAsync, getTestsForFileAsync, getCallSitesAsync, getChangedSymbolsFiltered, getTransitiveCallers, getCallSitesWithContext, getChangedSymbolsFilteredAsync, getTransitiveCallersAsync, getCallSitesWithContextAsync } = nativeBinding
 
 module.exports.pack = pack
 module.exports.scan = scan
@@ -327,6 +327,14 @@ module.exports.findSymbol = findSymbol
 module.exports.getCallers = getCallers
 module.exports.getCallees = getCallees
 module.exports.getReferences = getReferences
+module.exports.findSymbolFiltered = findSymbolFiltered
+module.exports.getCallersFiltered = getCallersFiltered
+module.exports.getCalleesFiltered = getCalleesFiltered
+module.exports.getReferencesFiltered = getReferencesFiltered
+module.exports.findSymbolFilteredAsync = findSymbolFilteredAsync
+module.exports.getCallersFilteredAsync = getCallersFilteredAsync
+module.exports.getCalleesFilteredAsync = getCalleesFilteredAsync
+module.exports.getReferencesFilteredAsync = getReferencesFilteredAsync
 module.exports.getCallGraph = getCallGraph
 module.exports.findSymbolAsync = findSymbolAsync
 module.exports.getCallersAsync = getCallersAsync

package/package.json

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