@reverse-craft/smart-fs 1.0.6 → 2.0.0

package/README.md

@@ -48,9 +48,13 @@ Or if installed globally:
 
 ## Usage
 
-The server provides one tool: `read_code_smart`
+The server provides five tools:
 
-### Parameters
+### 1. read_code_smart
+
+Read and beautify minified/obfuscated JavaScript code with source map coordinates.
+
+#### Parameters
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
@@ -58,22 +62,165 @@ The server provides one tool: `read_code_smart`
 | `start_line` | number | ✓ | - | Start line (1-based) |
 | `end_line` | number | ✓ | - | End line (1-based) |
 | `char_limit` | number | | 300 | Max string length before truncation |
+| `max_line_chars` | number | | 500 | Maximum characters per line |
+| `save_local` | boolean | | false | Save beautified file locally |
+
+#### Example Output
+
+```
+/path/to/obfuscated.js (1-20/5000)
+Src=original position for breakpoints
+ 1 L1:0       var _0x1234 = function() {
+ 2 L1:25        var data = "SGVsbG8gV29ybGQ=...[TRUNCATED 50000 CHARS]...base64==";
+ 3 L1:50078    return decode(data);
+ 4 L1:50100  };
+
+... (Use next start_line=21 to read more)
+```
+
+### 2. find_usage_smart
+
+Find all definitions and references of a variable/function using AST scope analysis.
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file_path` | string | ✓ | - | Path to JavaScript file |
+| `identifier` | string | ✓ | - | Variable or function name to find |
+| `line` | number | | - | Line number for precise binding (recommended for obfuscated code) |
+| `char_limit` | number | | 300 | Max string length before truncation |
+| `max_line_chars` | number | | 500 | Maximum characters per line |
+
+#### Example Output
+
+```
+/path/to/obfuscated.js
+Identifier="_0x1234"
+Src=original position for breakpoints
+Bindings: 1 (Targeted at line 10)
+--- Targeted Scope (const) ---
+📍 Definition:
+      5 L1:100      const _0x1234 = function() {
+🔎 References (3):
+     10 L1:200      return _0x1234(); ◀── hit
+     15 L1:300      _0x1234.call(this);
+     20 L1:400      console.log(_0x1234);
+```
+
+### 3. search_code_smart
+
+Search for text or regex patterns in beautified JavaScript code.
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file_path` | string | ✓ | - | Path to JavaScript file |
+| `query` | string | ✓ | - | Text or regex pattern to search |
+| `context_lines` | number | | 2 | Number of context lines |
+| `case_sensitive` | boolean | | false | Case sensitive search |
+| `is_regex` | boolean | | false | Treat query as regex pattern |
+| `char_limit` | number | | 300 | Max string length before truncation |
+| `max_line_chars` | number | | 500 | Maximum characters per line |
 
-### Example Output
+#### Example Output
 
 ```
-FILE: /path/to/obfuscated.js
-VIEW: Auto-beautified (Lines 1-20 of 5000)
-INFO: [Src L:C] = Location in original minified file (for Chrome Breakpoints)
--------------------------------------------------------------------------------------
- 1 | [Src L1:0        ] | var _0x1234 = function() {
- 2 | [Src L1:25       ] |   var data = "SGVsbG8gV29ybGQ=...[TRUNCATED 50000 CHARS]...base64==";
- 3 | [Src L1:50078    ] |   return decode(data);
- 4 | [Src L1:50100    ] | };
-...
+/path/to/obfuscated.js
+Query="decrypt" (literal, case-insensitive)
+Src=original position for breakpoints
+Matches: 3
+--- Line 42 ---
+  40 L1:1000    function process(data) {
+  41 L1:1020      var key = getKey();
+>>42 L1:1050      return decrypt(data, key);
+  43 L1:1080    }
+  44 L1:1100    
+```
+
+### 4. apply_custom_transform
+
+Apply a custom Babel transformation to deobfuscate JavaScript code.
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `target_file` | string | ✓ | - | Path to the JavaScript file to transform |
+| `script_path` | string | ✓ | - | Path to a JS file exporting a Babel Plugin function |
+| `output_suffix` | string | | _deob | Suffix for output file name |
+
+#### Example Plugin Script
+
+```javascript
+// deob-plugin.js
+module.exports = function() {
+  return {
+    visitor: {
+      // Evaluate constant binary expressions: "a" + "b" -> "ab"
+      BinaryExpression(path) {
+        const { left, right, operator } = path.node;
+        if (operator === '+' && 
+            left.type === 'StringLiteral' && 
+            right.type === 'StringLiteral') {
+          path.replaceWith({ type: 'StringLiteral', value: left.value + right.value });
+        }
+      }
+    }
+  };
+};
+```
+
+#### Example Output
+
+```
+Transform completed successfully!
+
+Output file: /path/to/obfuscated_deob.js
+Source map: /path/to/obfuscated_deob.js.map
+```
+
+The output file includes a cascaded source map that traces back to the original minified file, so breakpoints still work in Chrome DevTools.
+
+### 5. ai_find_jsvmp_dispatcher
+
+AI-powered tool to find JSVMP (JavaScript Virtual Machine Protection) dispatcher patterns in code using LLM analysis. Requires `OPENAI_API_KEY` environment variable.
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file_path` | string | ✓ | - | Path to JavaScript file |
+| `start_line` | number | ✓ | - | Start line (1-based) |
+| `end_line` | number | ✓ | - | End line (1-based) |
+| `char_limit` | number | | 300 | Max string length before truncation |
+
+#### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `OPENAI_API_KEY` | ✓ | - | OpenAI API key |
+| `OPENAI_BASE_URL` | | `https://api.openai.com/v1` | API base URL |
+| `OPENAI_MODEL` | | `gpt-4o-mini` | Model name |
+
+#### Example Output
+
+```
+=== JSVMP Dispatcher Detection Result ===
+File: /path/to/obfuscated.js (100-500)
+
+Summary: 检测到 JSVMP 保护代码，包含主分发器和虚拟栈操作
+
+Detected Regions:
+[ultra_high] Lines 150-300: Switch Dispatcher
+  大型 switch 语句，包含 50+ case 分支，典型的 JSVMP 分发器结构
+
+[high] Lines 120-140: Stack Operation
+  数组操作模式，疑似虚拟栈实现
 ```
 
-The `[Src L:C]` column shows the original position in the minified file - use these coordinates to set breakpoints in Chrome DevTools.
+The `Src L:C` shows the original position in the minified file - use these coordinates to set breakpoints in Chrome DevTools.
 
 ## Features
 

package/dist/analyzer.d.ts

@@ -0,0 +1,91 @@
+import type { SourceMap } from './beautifier.js';
+/**
+ * Original position from source map
+ */
+export interface OriginalPosition {
+    line: number | null;
+    column: number | null;
+}
+/**
+ * Location information for a definition or reference
+ */
+export interface LocationInfo {
+    /** Line number in beautified code (1-based) */
+    line: number;
+    /** Column number in beautified code (0-based) */
+    column: number;
+    /** Original file coordinates from source map */
+    originalPosition: OriginalPosition;
+    /** Content of the line containing this location */
+    lineContent: string;
+}
+/**
+ * Binding information for a variable/function
+ */
+export interface BindingInfo {
+    /** Unique scope identifier */
+    scopeUid: number;
+    /** Binding kind (var, let, const, param, etc.) */
+    kind: string;
+    /** Definition location */
+    definition: LocationInfo;
+    /** All reference locations */
+    references: LocationInfo[];
+    /** Total reference count (before limiting) */
+    totalReferences: number;
+    /** The location that matched the target line (if targeted search) */
+    hitLocation?: LocationInfo;
+}
+/**
+ * Analysis result containing all bindings for an identifier
+ */
+export interface AnalysisResult {
+    /** All bindings found for the identifier */
+    bindings: BindingInfo[];
+    /** The identifier that was searched */
+    identifier: string;
+    /** Whether this was a targeted (line-specific) search */
+    isTargeted: boolean;
+    /** The target line if specified */
+    targetLine?: number;
+}
+/**
+ * Parse JavaScript/TypeScript code into an AST
+ * @param code - Source code to parse
+ * @returns Parsed AST
+ * @throws Error if parsing fails
+ */
+export declare function parseCode(code: string): import("@babel/parser").ParseResult<import("@babel/types").File>;
+/**
+ * Options for binding analysis
+ */
+export interface AnalyzeOptions {
+    /** Maximum references to return per binding (default 10) */
+    maxReferences?: number;
+    /** Target line number for precise binding identification (1-based) */
+    targetLine?: number;
+}
+/**
+ * Analyze bindings for a specific identifier in the code
+ * Uses Babel traverse to find all bindings and their references
+ *
+ * @param code - Beautified code to analyze
+ * @param rawMap - Source map for coordinate mapping
+ * @param identifier - Variable/function name to find
+ * @param options - Analysis options
+ * @returns Analysis result with all bindings
+ */
+export declare function analyzeBindings(code: string, rawMap: SourceMap, identifier: string, options?: AnalyzeOptions): Promise<AnalysisResult>;
+/**
+ * Format source position as "L{line}:{column}" or placeholder
+ */
+export declare function formatSourcePosition(line: number | null, column: number | null): string;
+/**
+ * Format analysis result for output
+ * @param filePath - Path to the file
+ * @param result - Analysis result
+ * @param maxReferences - Maximum references shown per binding
+ * @returns Formatted output string
+ */
+export declare function formatAnalysisResult(filePath: string, result: AnalysisResult, maxReferences?: number): string;
+//# sourceMappingURL=analyzer.d.ts.map

package/dist/analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAsBjD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,UAAU,EAAE,YAAY,CAAC;IACzB,8BAA8B;IAC9B,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,UAAU,EAAE,OAAO,CAAC;IACpB,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAsBD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,oEAOrC;AA6CD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC,CAkIzB;AAGD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAKvF;AAmBD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,EACtB,aAAa,GAAE,MAAW,GACzB,MAAM,CAmFR"}

package/dist/beautifier.d.ts

@@ -0,0 +1,120 @@
+import { type SupportedLanguage } from './languageDetector.js';
+export interface SourceMap {
+    version: number;
+    sources: string[];
+    names: string[];
+    mappings: string;
+    file?: string;
+    sourceRoot?: string;
+}
+export interface BeautifyOptions {
+    /** Override auto-detected language */
+    language?: SupportedLanguage;
+    /** Save beautified file locally (default: true for JS/TS) */
+    saveLocal?: boolean;
+}
+export interface BeautifyResult {
+    code: string;
+    /** Source map (null for languages that don't support it) */
+    rawMap: SourceMap | null;
+    /** 本地保存的美化文件路径 */
+    localPath: string;
+    /** 本地保存的 source map 路径 */
+    localMapPath: string;
+    /** 本地保存失败时的错误信息 */
+    localSaveError?: string;
+    /** Whether fallback mode was used */
+    usedFallback: boolean;
+}
+/**
+ * Local paths result interface
+ */
+export interface LocalPaths {
+    /** Path to the beautified file in the same directory as the original */
+    beautifiedPath: string;
+    /** Path to the source map file in the same directory as the original */
+    mapPath: string;
+}
+/**
+ * Get local file paths for beautified output
+ * Given an original file path, returns the paths where the beautified file
+ * and source map should be saved in the same directory.
+ *
+ * Naming convention:
+ * - Original: {filename}.js -> Beautified: {filename}.beautified.js
+ * - Source map: {filename}.beautified.js.map
+ *
+ * @param originalPath - Path to the original JavaScript file
+ * @returns Object containing beautifiedPath and mapPath
+ */
+export declare function getLocalPaths(originalPath: string): LocalPaths;
+/**
+ * Local cache validation result interface
+ */
+export interface LocalCacheCheck {
+    /** Original file modification time in milliseconds */
+    originalMtime: number;
+    /** Whether the beautified file exists */
+    beautifiedExists: boolean;
+    /** Beautified file modification time in milliseconds (0 if not exists) */
+    beautifiedMtime: number;
+    /** Whether the cache is valid (beautifiedMtime >= originalMtime) */
+    isValid: boolean;
+}
+/**
+ * Check if local beautified cache is valid
+ *
+ * A local cache is considered valid when:
+ * 1. The beautified file exists
+ * 2. The beautified file's modification time is >= the original file's modification time
+ *
+ * @param originalPath - Path to the original JavaScript file
+ * @returns LocalCacheCheck object with validation details
+ */
+export declare function isLocalCacheValid(originalPath: string): Promise<LocalCacheCheck>;
+/**
+ * Beautify JSON content with proper indentation
+ * @param content - JSON string to beautify
+ * @returns Object with beautified JSON string and error flag
+ */
+export declare function beautifyJson(content: string): {
+    code: string;
+    parseFailed: boolean;
+};
+/**
+ * Simple HTML/XML beautification with indentation
+ * This is a basic formatter that handles common cases
+ * @param content - HTML/XML string to beautify
+ * @returns Beautified HTML/XML string, or original content if formatting fails
+ */
+export declare function beautifyHtml(content: string): string;
+/**
+ * Simple CSS beautification with indentation
+ * @param content - CSS string to beautify
+ * @returns Beautified CSS string, or original content if formatting fails
+ */
+export declare function beautifyCss(content: string): string;
+/**
+ * Beautify code string directly based on language
+ * @param code - Source code to beautify
+ * @param language - Language type
+ * @returns Beautified code (or original if fallback mode)
+ */
+export declare function beautifyCode(code: string, language: SupportedLanguage): {
+    code: string;
+    usedFallback: boolean;
+};
+/**
+ * Beautify file based on detected or specified language
+ * - JS/TS: Use esbuild for formatting with source map
+ * - JSON: Use JSON.stringify with indentation
+ * - HTML/XML: Use simple indentation-based formatting
+ * - CSS: Use simple formatting
+ * - Unknown: Return original (fallback mode)
+ *
+ * @param originalPath - Original file path
+ * @param options - Optional beautify options (language, saveLocal, etc.)
+ * @returns Beautified code and Source Map (null for non-JS/TS)
+ */
+export declare function ensureBeautified(originalPath: string, options?: BeautifyOptions): Promise<BeautifyResult>;
+//# sourceMappingURL=beautifier.d.ts.map

package/dist/beautifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beautifier.d.ts","sourceRoot":"","sources":["../src/beautifier.ts"],"names":[],"mappings":"AAKA,OAAO,EAAmC,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAIhG,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,kBAAkB;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,YAAY,EAAE,OAAO,CAAC;CACvB;AA4BD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,UAAU,CAU9D;AAiBD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA2CtF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAQpF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAuDpD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA8CnD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,iBAAiB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CA4BzC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CAyJzB"}

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * smart-fs - Smart file processing library
+ *
+ * Provides code beautification, truncation, search, analysis, and transformation
+ * with multi-language support and source map generation.
+ *
+ * @module smart-fs
+ */
+export * from './types.js';
+export { type SupportedLanguage, type LanguageInfo, detectLanguage, getLanguageInfo, isFullySupportedLanguage, getSupportedExtensions, isExtensionSupported, } from './languageDetector.js';
+export { type SourceMap, type BeautifyOptions, type BeautifyResult, type LocalPaths, type LocalCacheCheck, ensureBeautified, beautifyCode, beautifyJson, beautifyHtml, beautifyCss, getLocalPaths, isLocalCacheValid, } from './beautifier.js';
+export { type TruncateOptions, type TruncateResult, truncateCode, truncateCodeFromFile, truncateFallback, truncateLongLines, truncateCodeHighPerf, } from './truncator.js';
+export { type OriginalPosition as SearchOriginalPosition, type ContextLine, type SearchMatch, type SearchOptions, type SearchResult, searchInCode, formatSearchResult, formatSourcePosition as formatSearchSourcePosition, createRegex, escapeRegex, unescapeBackslashes, } from './searcher.js';
+export { type OriginalPosition as AnalyzeOriginalPosition, type LocationInfo, type BindingInfo, type AnalysisResult, type AnalyzeOptions, analyzeBindings, formatAnalysisResult, formatSourcePosition as formatAnalyzeSourcePosition, parseCode, } from './analyzer.js';
+export { type TransformOptions, type TransformResult, type OutputPaths, type BabelPluginFunction, applyCustomTransform, loadBabelPlugin, runBabelTransform, getOutputPaths, cleanBasename, } from './transformer.js';
+import type { SmartReadOptions, ProcessingResult } from './types.js';
+import type { SearchOptions, SearchResult } from './searcher.js';
+import type { AnalyzeOptions, AnalysisResult } from './analyzer.js';
+/**
+ * Smart read file with beautification and truncation
+ *
+ * This is a convenience function that combines beautification and truncation
+ * into a single operation. It handles:
+ * - Language detection (or uses specified language)
+ * - Code beautification (for supported languages)
+ * - String/line truncation
+ * - Optional line range extraction
+ *
+ * @param filePath - Path to the file to read
+ * @param options - Processing options
+ * @returns ProcessingResult with processed code and metadata
+ *
+ * @example
+ * ```typescript
+ * // Read and process entire file
+ * const result = await smartRead('./src/app.js');
+ *
+ * // Read specific lines with custom options
+ * const result = await smartRead('./src/app.js', {
+ *   startLine: 10,
+ *   endLine: 50,
+ *   charLimit: 200,
+ *   maxLineChars: 400
+ * });
+ * ```
+ */
+export declare function smartRead(filePath: string, options?: SmartReadOptions): Promise<ProcessingResult>;
+/**
+ * Smart search in file with beautification and source map support
+ *
+ * This function beautifies the file first, then searches in the beautified code.
+ * Results include original file positions via source map for setting breakpoints.
+ *
+ * @param filePath - Path to the file to search
+ * @param query - Search query (text or regex pattern)
+ * @param options - Search options
+ * @returns SearchResult with matches and original positions
+ *
+ * @example
+ * ```typescript
+ * // Simple text search
+ * const result = await smartSearch('./src/app.js', 'function');
+ *
+ * // Regex search with options
+ * const result = await smartSearch('./src/app.js', 'function\\s+\\w+', {
+ *   isRegex: true,
+ *   caseSensitive: true,
+ *   contextLines: 3
+ * });
+ * ```
+ */
+export declare function smartSearch(filePath: string, query: string, options?: SearchOptions): Promise<SearchResult & {
+    formatted: string;
+    error?: string;
+}>;
+/**
+ * Find variable/function usage in file
+ *
+ * This function analyzes the code to find all bindings (definitions and references)
+ * for a specific identifier. Results include original file positions via source map.
+ *
+ * @param filePath - Path to the file to analyze
+ * @param identifier - Variable or function name to find
+ * @param options - Analysis options
+ * @returns AnalysisResult with bindings and original positions
+ *
+ * @example
+ * ```typescript
+ * // Find all usages of 'myFunction'
+ * const result = await findUsage('./src/app.js', 'myFunction');
+ *
+ * // Find usage at specific line
+ * const result = await findUsage('./src/app.js', 'data', {
+ *   targetLine: 42
+ * });
+ * ```
+ */
+export declare function findUsage(filePath: string, identifier: string, options?: AnalyzeOptions): Promise<AnalysisResult & {
+    formatted: string;
+    error?: string;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,cAAc,YAAY,CAAC;AAG3B,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,cAAc,EACd,eAAe,EACf,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,KAAK,gBAAgB,IAAI,sBAAsB,EAC/C,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,IAAI,0BAA0B,EAClD,WAAW,EACX,WAAW,EACX,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,KAAK,gBAAgB,IAAI,uBAAuB,EAChD,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,eAAe,EACf,oBAAoB,EACpB,oBAAoB,IAAI,2BAA2B,EACnD,SAAS,GACV,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,GACd,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAQpE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CA+D3B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA8D/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA+DjE"}