infiniloom-node 0.4.7 → 0.4.9

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`
 
@@ -199,9 +199,9 @@ 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). 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.
+- `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[]`
 
@@ -567,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

@@ -3,6 +3,20 @@
 
 /* auto-generated by NAPI-RS */
 
+/**
+ * Get the package version
+ *
+ * # Returns
+ * The version string of the infiniloom-node package
+ *
+ * # Example
+ * ```javascript
+ * const { version } = require('infiniloom-node');
+ *
+ * console.log(`infiniloom-node v${version()}`);
+ * ```
+ */
+export declare function version(): string
 /** Options for packing a repository */
 export interface PackOptions {
   /** Output format: "xml", "markdown", "json", "yaml", "toon", or "plain" */
@@ -29,7 +43,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
@@ -107,12 +124,12 @@ export interface ScanOptions {
  * });
  * ```
  */
-export declare function pack(path: string, options?: PackOptions | undefined | null): string
+export declare function pack(path?: string | undefined | null, options?: PackOptions | undefined | null): string
 /**
  * Scan a repository and return statistics
  *
  * # Arguments
- * * `path` - Path to repository root
+ * * `path` - Path to repository root (null/undefined returns error)
  * * `model` - Optional target model (default: "claude") - for backwards compatibility
  *
  * # Returns
@@ -127,7 +144,7 @@ export declare function pack(path: string, options?: PackOptions | undefined | n
  * console.log(`Total tokens: ${stats.totalTokens}`);
  * ```
  */
-export declare function scan(path: string, model?: string | undefined | null): ScanStats
+export declare function scan(path?: string | undefined | null, model?: string | undefined | null): ScanStats
 /**
  * Scan a repository with full options
  *
@@ -154,7 +171,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,7 +185,7 @@ 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
  *
@@ -196,14 +213,19 @@ export declare function countTokens(text: string, model?: string | undefined | n
  * ```javascript
  * const { semanticCompress } = require('infiniloom-node');
  *
- * // Compress to ~30% of original size
- * const compressed = semanticCompress(longText, 0.7, 0.3);
+ * // Using options object (recommended)
+ * const compressed = semanticCompress(longText, { budgetRatio: 0.3 });
  *
- * // Aggressive compression to ~20%
- * const veryCompressed = semanticCompress(longText, 0.7, 0.2);
+ * // With all options
+ * const custom = semanticCompress(longText, {
+ *   similarityThreshold: 0.7,
+ *   budgetRatio: 0.3,
+ *   minChunkSize: 100,
+ *   maxChunkSize: 2000
+ * });
  * ```
  */
-export declare function semanticCompress(text: string, similarityThreshold?: number | undefined | null, budgetRatio?: number | undefined | null): string
+export declare function semanticCompress(text?: string | undefined | null, options?: SemanticCompressOptions | undefined | null): string
 /**
  * Check if a path is a git repository
  *
@@ -329,7 +351,7 @@ export interface SecurityFinding {
  * }
  * ```
  */
-export declare function scanSecurity(path: string): Array<SecurityFinding>
+export declare function scanSecurity(path?: string | undefined | null): Array<SecurityFinding>
 /** Options for building an index */
 export interface IndexOptions {
   /** Force full rebuild even if index exists */
@@ -485,6 +507,45 @@ export interface CallGraphOptions {
   /** Maximum number of edges to return (default: unlimited) */
   maxEdges?: number
 }
+/** Result from getSymbolSource containing source code and metadata */
+export interface SymbolSourceResult {
+  /** The source code of the symbol */
+  source: string
+  /** Path to the file containing the symbol (relative to repo root) */
+  path: string
+  /** Start line number (1-indexed) */
+  startLine: number
+  /** End line number (1-indexed) */
+  endLine: number
+  /** Symbol name */
+  name: string
+  /** Symbol kind (function, method, class, etc.) */
+  kind: string
+}
+/** Options for generateMap */
+export interface GenerateMapOptions {
+  /** Token budget for the map (default: 2000) */
+  budget?: number
+  /** Maximum number of symbols to include (default: 50) */
+  maxSymbols?: number
+}
+/** Options for semanticCompress */
+export interface SemanticCompressOptions {
+  /**
+   * Threshold for grouping similar chunks (0.0-1.0, default: 0.7)
+   * Note: Only affects output when built with "embeddings" feature.
+   */
+  similarityThreshold?: number
+  /**
+   * Target size as ratio of original (0.0-1.0, default: 0.5)
+   * Lower values = more aggressive compression
+   */
+  budgetRatio?: number
+  /** Minimum chunk size in characters (default: 100) */
+  minChunkSize?: number
+  /** Maximum chunk size in characters (default: 2000) */
+  maxChunkSize?: number
+}
 /**
  * Feature #2: Filter options for symbol queries
  *
@@ -506,8 +567,8 @@ export interface QueryFilter {
  * Requires an index to be built first (use `buildIndex`).
  *
  * # Arguments
- * * `path` - Path to repository root
- * * `name` - Symbol name to search for
+ * * `path` - Path to repository root (null/undefined returns error)
+ * * `name` - Symbol name to search for (null/undefined returns error)
  *
  * # Returns
  * Array of matching symbols
@@ -521,7 +582,7 @@ export interface QueryFilter {
  * console.log(`Found ${symbols.length} symbols named processRequest`);
  * ```
  */
-export declare function findSymbol(path: string, name: string): Array<SymbolInfo>
+export declare function findSymbol(path?: string | undefined | null, name?: string | undefined | null): Array<SymbolInfo>
 /**
  * Get all callers of a symbol
  *
@@ -529,8 +590,8 @@ export declare function findSymbol(path: string, name: string): Array<SymbolInfo
  * Requires an index to be built first (use `buildIndex`).
  *
  * # Arguments
- * * `path` - Path to repository root
- * * `symbol_name` - Name of the symbol to find callers for
+ * * `path` - Path to repository root (null/undefined returns error)
+ * * `symbol_name` - Name of the symbol to find callers for (null/undefined returns error)
  *
  * # Returns
  * Array of symbols that call the target symbol
@@ -547,7 +608,7 @@ export declare function findSymbol(path: string, name: string): Array<SymbolInfo
  * }
  * ```
  */
-export declare function getCallers(path: string, symbolName: string): Array<SymbolInfo>
+export declare function getCallers(path?: string | undefined | null, symbolName?: string | undefined | null): Array<SymbolInfo>
 /**
  * Get all callees of a symbol
  *
@@ -555,8 +616,8 @@ export declare function getCallers(path: string, symbolName: string): Array<Symb
  * Requires an index to be built first (use `buildIndex`).
  *
  * # Arguments
- * * `path` - Path to repository root
- * * `symbol_name` - Name of the symbol to find callees for
+ * * `path` - Path to repository root (null/undefined returns error)
+ * * `symbol_name` - Name of the symbol to find callees for (null/undefined returns error)
  *
  * # Returns
  * Array of symbols that the target symbol calls
@@ -573,7 +634,7 @@ export declare function getCallers(path: string, symbolName: string): Array<Symb
  * }
  * ```
  */
-export declare function getCallees(path: string, symbolName: string): Array<SymbolInfo>
+export declare function getCallees(path?: string | undefined | null, symbolName?: string | undefined | null): Array<SymbolInfo>
 /**
  * Get all references to a symbol
  *
@@ -599,7 +660,7 @@ export declare function getCallees(path: string, symbolName: string): Array<Symb
  * }
  * ```
  */
-export declare function getReferences(path: string, symbolName: string): Array<ReferenceInfo>
+export declare function getReferences(path?: string | undefined | null, symbolName?: string | undefined | null): Array<ReferenceInfo>
 /**
  * Find symbols by name with filtering
  *
@@ -743,17 +804,17 @@ export declare function getReferencesFilteredAsync(path: string, symbolName: str
  * console.log('Most called functions:', sorted.slice(0, 10));
  * ```
  */
-export declare function getCallGraph(path: string, options?: CallGraphOptions | undefined | null): CallGraph
+export declare function getCallGraph(path?: string | undefined | null, options?: CallGraphOptions | undefined | null): CallGraph
 /** Async version of findSymbol */
-export declare function findSymbolAsync(path: string, name: string): Promise<Array<SymbolInfo>>
+export declare function findSymbolAsync(path?: string | undefined | null, name?: string | undefined | null): Promise<Array<SymbolInfo>>
 /** Async version of getCallers */
-export declare function getCallersAsync(path: string, symbolName: string): Promise<Array<SymbolInfo>>
+export declare function getCallersAsync(path?: string | undefined | null, symbolName?: string | undefined | null): Promise<Array<SymbolInfo>>
 /** Async version of getCallees */
-export declare function getCalleesAsync(path: string, symbolName: string): Promise<Array<SymbolInfo>>
+export declare function getCalleesAsync(path?: string | undefined | null, symbolName?: string | undefined | null): Promise<Array<SymbolInfo>>
 /** Async version of getReferences */
-export declare function getReferencesAsync(path: string, symbolName: string): Promise<Array<ReferenceInfo>>
+export declare function getReferencesAsync(path?: string | undefined | null, symbolName?: string | undefined | null): Promise<Array<ReferenceInfo>>
 /** Async version of getCallGraph */
-export declare function getCallGraphAsync(path: string, options?: CallGraphOptions | undefined | null): Promise<CallGraph>
+export declare function getCallGraphAsync(path?: string | undefined | null, options?: CallGraphOptions | undefined | null): Promise<CallGraph>
 /** Options for chunking a repository */
 export interface ChunkOptions {
   /** Chunking strategy: "fixed", "file", "module", "symbol", "semantic", "dependency" */
@@ -821,6 +882,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 {
@@ -887,6 +954,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 {
@@ -973,7 +1046,7 @@ export declare function getDiffContext(path: string, fromRef: string, toRef: str
  * const context = await packAsync('./my-repo', { format: 'xml' });
  * ```
  */
-export declare function packAsync(path: string, options?: PackOptions | undefined | null): Promise<string>
+export declare function packAsync(path?: string | undefined | null, options?: PackOptions | undefined | null): Promise<string>
 /**
  * Async version of scan
  *
@@ -984,7 +1057,7 @@ export declare function packAsync(path: string, options?: PackOptions | undefine
  * const stats = await scanAsync('./my-repo', 'claude');
  * ```
  */
-export declare function scanAsync(path: string, model?: string | undefined | null): Promise<ScanStats>
+export declare function scanAsync(path?: string | undefined | null, model?: string | undefined | null): Promise<ScanStats>
 /**
  * Async version of buildIndex
  *
@@ -1098,11 +1171,12 @@ export declare function getSymbolsInFile(path: string, filePath: string, filter?
  * const { getSymbolSource, buildIndex } = require('infiniloom-node');
  *
  * buildIndex('./my-repo');
- * const source = getSymbolSource('./my-repo', 'authenticate', 'src/auth.ts');
- * console.log(source);
+ * const result = getSymbolSource('./my-repo', 'authenticate', 'src/auth.ts');
+ * console.log(`Source at ${result.path}:${result.startLine}`);
+ * console.log(result.source);
  * ```
  */
-export declare function getSymbolSource(path: string, symbolName: string, filePath?: string | undefined | null): string
+export declare function getSymbolSource(path?: string | undefined | null, symbolName?: string | undefined | null, filePath?: string | undefined | null): SymbolSourceResult
 /**
  * Get symbols that were changed in a diff
  *
@@ -1193,7 +1267,7 @@ export declare function getCallSites(path: string, symbolName: string): Array<Ca
 /** 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>
+export declare function getSymbolSourceAsync(path?: string | undefined | null, symbolName?: string | undefined | null, filePath?: string | undefined | null): Promise<SymbolSourceResult>
 /** Async version of getChangedSymbols */
 export declare function getChangedSymbolsAsync(path: string, fromRef: string, toRef: string): Promise<Array<SymbolInfo>>
 /** Async version of getTestsForFile */
@@ -1391,10 +1465,15 @@ export declare class Infiniloom {
    * Generate a repository map
    *
    * # Arguments
-   * * `budget` - Token budget (default: 2000)
-   * * `max_symbols` - Maximum symbols (default: 50)
+   * * `options` - Options object with budget (default: 2000) and maxSymbols (default: 50)
+   *
+   * # Example
+   * ```javascript
+   * const loom = new Infiniloom('./my-repo');
+   * const map = loom.generateMap({ budget: 3000, maxSymbols: 100 });
+   * ```
    */
-  generateMap(budget?: number | undefined | null, maxSymbols?: number | undefined | null): string
+  generateMap(options?: GenerateMapOptions | 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) */
@@ -1428,9 +1507,9 @@ export declare class GitRepo {
    * * `path` - Path to the repository
    *
    * # Throws
-   * Error if path is not a git repository
+   * Error if path is null/undefined or not a git repository
    */
-  constructor(path: string)
+  constructor(path?: string | undefined | null)
   /**
    * Get the current branch name
    *

package/index.js

@@ -310,8 +310,9 @@ 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, 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
+const { version, 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.version = version
 module.exports.pack = pack
 module.exports.scan = scan
 module.exports.scanWithOptions = scanWithOptions

package/package.json

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