minovative-mind-cli 2.13.4 → 2.14.0

package/dist/utils/symbolExtractor.d.ts

@@ -1,36 +1,139 @@
 /**
- * Represents an extracted symbol's location within a source file.
+ * Supported classification kinds for extracted AST symbols and definition chunks.
+ */
+export type SymbolKind = 'function' | 'class' | 'method' | 'constructor' | 'interface' | 'type' | 'enum' | 'variable' | 'trait' | 'struct' | 'impl' | 'constant' | 'property' | 'other';
+/**
+ * Represents an extracted symbol's location and metadata within a source file.
  */
 export interface ExtractedSymbol {
-    /** The name of the symbol (function, class, variable, etc.) */
+    /** The name of the symbol (function, class, variable, method, etc.) */
     symbol: string;
-    /** The 0-indexed starting line number of the symbol declaration/block */
+    /** The 0-indexed starting line number of the symbol declaration/block (including docstrings/decorators) */
     startLine: number;
     /** The 0-indexed ending line number of the symbol block */
     endLine: number;
+    /** The classified kind of symbol */
+    kind?: SymbolKind;
+    /** Clean declaration signature (e.g. `function foo(x: number): void` or `class Bar`) */
+    signature?: string;
+    /** Preceding documentation or docstring content if present */
+    doc?: string;
+    /** Optional parent enclosing class/struct/impl/trait name for nested members */
+    parentSymbol?: string;
+}
+/**
+ * Represents a discrete, self-contained definition chunk for granular context injection and retrieval.
+ */
+export interface DefinitionChunk {
+    /** Unique chunk identifier (e.g. `src/utils.ts:UserService#getUser` or `src/utils.ts:fetchAllUsers`) */
+    id: string;
+    /** The primary symbol name */
+    symbol: string;
+    /** Enclosing parent symbol if applicable */
+    parentSymbol?: string;
+    /** The classified kind of definition */
+    kind: SymbolKind;
+    /** 0-indexed starting line number */
+    startLine: number;
+    /** 0-indexed ending line number */
+    endLine: number;
+    /** Declaration signature */
+    signature: string;
+    /** Preceding documentation or docstring if present */
+    doc?: string;
+    /** The exact extracted content of the chunk */
+    content: string;
+    /** Estimated token consumption for this chunk */
+    tokenEstimate: number;
+}
+/**
+ * Options for configuring definition chunk extraction.
+ */
+export interface DefinitionChunkOptions {
+    /** Maximum number of lines per definition chunk before truncation */
+    maxChunkLines?: number;
+    /** Whether to include full implementation bodies or only declaration signatures with stubs */
+    includeBodies?: boolean;
+    /** Filter to specific symbol kinds (e.g. ['function', 'class']) */
+    filterKinds?: SymbolKind[];
+}
+/**
+ * Options for configuring symbol extraction output formatting.
+ */
+export interface ExtractSymbolsOptions {
+    /** Maximum lines per extracted symbol */
+    maxLinesPerSymbol?: number;
+    /** Whether to output only declaration signatures with stubs instead of full bodies */
+    includeSignaturesOnly?: boolean;
 }
 /**
- * Extracts specified target symbols from source file content and returns their line number ranges and names.
+ * Estimates token consumption for a given string using a standard ~3.8 characters per token heuristic.
+ *
+ * @param text - The input string to estimate
+ * @returns Estimated token count
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Parses a target symbol identifier into potential parent and member components.
+ * Handles patterns such as:
+ * - `UserService.getUser` -> `{ parentName: 'UserService', memberName: 'getUser' }`
+ * - `UserService#getUser` -> `{ parentName: 'UserService', memberName: 'getUser' }`
+ * - `UserService::getUser` -> `{ parentName: 'UserService', memberName: 'getUser' }`
+ * - `getUser` -> `{ parentName: null, memberName: 'getUser' }`
+ *
+ * @param rawTarget - The raw symbol string provided by the caller
+ * @returns Object with optional parentName and memberName
+ */
+export declare function parseTargetSymbol(rawTarget: string): {
+    parentName: string | null;
+    memberName: string;
+};
+/**
+ * Extracts specified target symbols from source file content and returns their line number ranges, kind, and signatures.
+ * Supports granular dotted member extraction (e.g. `UserService.getUser` or `User#new`).
  *
  * @param content - The full raw string content of the source file
  * @param filePath - The file path (used to determine language syntax rules via file extension)
- * @param targetElements - An array of symbol names to extract
- * @returns Array of ExtractedSymbol objects containing symbol name, startLine, and endLine
+ * @param targetElements - An array of symbol names or dotted member targets to extract
+ * @returns Array of ExtractedSymbol objects containing symbol name, line ranges, and metadata
  */
 export declare function extractSymbolMetadata(content: string, filePath: string, targetElements: string[]): ExtractedSymbol[];
 /**
- * Extracts specified target symbols (functions, classes, variables, interfaces, etc.) from source file content
+ * Scans a source file and extracts a comprehensive index of all declared symbols (classes, functions,
+ * methods, interfaces, structs, enums, types, etc.) along with their kind, line boundaries, and signatures.
+ *
+ * @param content - Source file content
+ * @param filePath - File path used to infer language and syntax rules
+ * @returns Array of all discovered ExtractedSymbol objects
+ */
+export declare function extractSymbolIndex(content: string, filePath: string): ExtractedSymbol[];
+/**
+ * Chunks a source code file into discrete, structured {@link DefinitionChunk} objects.
+ * Each chunk encapsulates a class, interface, function, method, struct, or type declaration
+ * along with its line range, signature, estimated token count, and content.
+ *
+ * @param content - Source file content
+ * @param filePath - File path used for identifier naming and language rules
+ * @param options - Chunking configuration options
+ * @returns Array of DefinitionChunk objects
+ */
+export declare function chunkDefinitions(content: string, filePath: string, options?: DefinitionChunkOptions): DefinitionChunk[];
+/**
+ * Extracts specified target symbols (functions, classes, methods, variables, interfaces, etc.) from source file content
  * using multi-language regex declarations, doc/decorator context gathering, and balanced brace/indentation block parsing.
  *
+ * Supports dotted / scoped member targeting (e.g. `['UserService.getUser']` or `['User#new']`).
+ *
  * This function significantly reduces token usage when reading large files by returning only the requested symbols
  * along with their context and omission separators.
  *
  * @param content - The full raw string content of the source file
  * @param filePath - The file path (used to determine language syntax rules via file extension)
  * @param targetElements - An array of symbol names to extract (e.g. `['extractSymbols', 'ExtractedSymbol']`)
+ * @param options - Formatting and chunking options
  * @returns The filtered source string containing only the matched symbol blocks and omission markers
  */
-export declare function extractSymbols(content: string, filePath: string, targetElements: string[]): string;
+export declare function extractSymbols(content: string, filePath: string, targetElements: string[], options?: ExtractSymbolsOptions): string;
 /**
  * Extracts a compact declarations outline (type/interface definitions, class skeletons,
  * and function signatures without full implementation bodies) across TypeScript/JavaScript,