minovative-mind-cli 2.13.4 → 2.14.0

package/dist/utils/symbolExtractor.js

@@ -1,4 +1,15 @@
 import * as path from 'node:path';
+/**
+ * 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 function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 3.8);
+}
 /**
  * Calculates the leading indentation whitespace count of a source code line.
  *
@@ -20,13 +31,37 @@ function isCommentOrEmpty(line, ext) {
     const trimmed = line.trim();
     if (!trimmed)
         return true;
-    if (ext === '.py')
+    if (ext === '.py' || ext === '.pyi')
         return trimmed.startsWith('#');
     return trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*');
 }
 /**
- * Builds a robust regular expression for matching symbol declarations across supported language families
- * (TypeScript/JavaScript, Python, Go, and Rust).
+ * 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 function parseTargetSymbol(rawTarget) {
+    const trimmed = rawTarget.trim();
+    const sepMatch = trimmed.match(/^([A-Za-z0-9_$]+)(?:\.|#|::)([A-Za-z0-9_$]+)$/);
+    if (sepMatch) {
+        return {
+            parentName: sepMatch[1],
+            memberName: sepMatch[2],
+        };
+    }
+    return {
+        parentName: null,
+        memberName: trimmed,
+    };
+}
+/**
+ * Builds a regular expression for matching top-level symbol declarations across supported language families.
  *
  * @param symbolName - The name of the symbol to match
  * @param ext - The file extension determining language syntax rules
@@ -34,16 +69,110 @@ function isCommentOrEmpty(line, ext) {
  */
 function buildDeclarationRegex(symbolName, ext) {
     const s = symbolName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    if (ext === '.py') {
+    if (ext === '.py' || ext === '.pyi') {
         return new RegExp(`^\\s*(?:async\\s+)?(?:def|class)\\s+${s}\\b|^\\s*${s}\\s*[:=]`);
     }
     if (ext === '.go') {
         return new RegExp(`^\\s*(?:func(?:\\s+\\([^)]+\\))?\\s+${s}\\b|type\\s+${s}\\b|var\\s+${s}\\b|const\\s+${s}\\b)`);
     }
     if (ext === '.rs') {
-        return new RegExp(`^\\s*(?:(?:pub\\s+)?(?:async\\s+)?fn\\s+${s}\\b|(?:pub\\s+)?struct\\s+${s}\\b|(?:pub\\s+)?enum\\s+${s}\\b|(?:pub\\s+)?trait\\s+${s}\\b|(?:pub\\s+)?impl(?:\\s+.*)?\\s+(?:for\\s+)?${s}\\b)`);
+        return new RegExp(`^\\s*(?:(?:pub(?:\\([^)]+\\))?\\s+)?(?:async\\s+|const\\s+|unsafe\\s+|extern\\s+)?fn\\s+${s}\\b|(?:pub(?:\\([^)]+\\))?\\s+)?struct\\s+${s}\\b|(?:pub(?:\\([^)]+\\))?\\s+)?enum\\s+${s}\\b|(?:pub(?:\\([^)]+\\))?\\s+)?trait\\s+${s}\\b|(?:pub(?:\\([^)]+\\))?\\s+)?impl(?:\\s+.*)?\\s+(?:for\\s+)?${s}\\b|(?:pub(?:\\([^)]+\\))?\\s+)?type\\s+${s}\\b|(?:pub(?:\\([^)]+\\))?\\s+)?const\\s+${s}\\b)`);
     }
-    return new RegExp(`^\\s*(?:(?:export\\s+|default\\s+|async\\s+|abstract\\s+|static\\s+|public\\s+|private\\s+|protected\\s+|readonly\\s+)*(?:class|function|const|let|var|type|interface|enum)\\s+(?:[\\w<>]+\\s+)?${s}\\b|^\\s*${s}\\s*[:=]|^\\s*(?:(?:public|private|protected|static|abstract|override|async|\\s+)*)${s}\\s*(?:<[^>]+>)?\\s*\\()`);
+    return new RegExp(`^\\s*(?:(?:export\\s+|default\\s+|async\\s+|abstract\\s+|static\\s+|public\\s+|private\\s+|protected\\s+|readonly\\s+|declare\\s+)*(?:class|function|const|let|var|type|interface|enum)\\s+(?:[\\w<>]+\\s+)?${s}\\b|^\\s*${s}\\s*[:=]|^\\s*(?:(?:public|private|protected|static|abstract|override|async|readonly|\\s+)*)${s}\\s*(?:<[^>]+>)?\\s*\\()`);
+}
+/**
+ * Builds a regular expression for matching nested class/struct/impl member methods and fields.
+ *
+ * @param memberName - The name of the member method or property to match
+ * @param ext - The file extension
+ * @returns A RegExp matching the member definition within an enclosing body
+ */
+function buildMemberRegex(memberName, ext) {
+    const m = memberName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (ext === '.py' || ext === '.pyi') {
+        return new RegExp(`^\\s*(?:async\\s+)?def\\s+${m}\\b|^\\s*${m}\\s*[:=]`);
+    }
+    if (ext === '.rs') {
+        return new RegExp(`^\\s*(?:(?:pub(?:\\([^)]+\\))?\\s+)?(?:async\\s+|const\\s+|unsafe\\s+|extern\\s+)?fn\\s+${m}\\b|(?:pub(?:\\([^)]+\\))?\\s+)?(?:type|const)\\s+${m}\\b)`);
+    }
+    if (ext === '.go') {
+        return new RegExp(`^\\s*func\\s+\\([^)]+\\)\\s+${m}\\b|^\\s*${m}\\s+`);
+    }
+    return new RegExp(`^\\s*(?:(?:public|private|protected|static|abstract|override|async|readonly|get|set|\\s+)*)${m}\\s*(?:<[^>]+>)?\\s*\\(|^\\s*(?:public|private|protected|static|readonly|\\s+)*${m}\\s*[:=;]`);
+}
+/**
+ * Infers the {@link SymbolKind} from a line and extension.
+ *
+ * @param line - The line declaring the symbol
+ * @param ext - The file extension
+ * @param isNested - Whether the symbol is inside a parent class/struct/impl
+ * @returns The classified SymbolKind
+ */
+function inferSymbolKind(line, ext, isNested) {
+    const trimmed = line.trim();
+    if (ext === '.py' || ext === '.pyi') {
+        if (trimmed.startsWith('class '))
+            return 'class';
+        if (trimmed.includes('def '))
+            return isNested ? 'method' : 'function';
+        return 'variable';
+    }
+    if (ext === '.rs') {
+        if (trimmed.includes('struct '))
+            return 'struct';
+        if (trimmed.includes('enum '))
+            return 'enum';
+        if (trimmed.includes('trait '))
+            return 'trait';
+        if (trimmed.includes('impl '))
+            return 'impl';
+        if (trimmed.includes('type '))
+            return 'type';
+        if (trimmed.includes('const ') || trimmed.includes('static '))
+            return 'constant';
+        if (trimmed.includes('fn '))
+            return isNested ? 'method' : 'function';
+        return 'other';
+    }
+    if (ext === '.go') {
+        if (trimmed.includes('struct'))
+            return 'struct';
+        if (trimmed.includes('interface'))
+            return 'interface';
+        if (trimmed.startsWith('type '))
+            return 'type';
+        if (trimmed.startsWith('const '))
+            return 'constant';
+        if (trimmed.startsWith('var '))
+            return 'variable';
+        if (trimmed.startsWith('func ('))
+            return 'method';
+        if (trimmed.startsWith('func '))
+            return 'function';
+        return 'other';
+    }
+    // TypeScript / JavaScript
+    if (/\binterface\b/.test(trimmed))
+        return 'interface';
+    if (/\btype\b/.test(trimmed))
+        return 'type';
+    if (/\benum\b/.test(trimmed))
+        return 'enum';
+    if (/\bclass\b/.test(trimmed))
+        return 'class';
+    if (/\bconstructor\b/.test(trimmed))
+        return 'constructor';
+    if (/\bfunction\b/.test(trimmed) || (trimmed.includes('=>') && !isNested))
+        return 'function';
+    if (isNested && (trimmed.includes('(') || /\b(get|set)\b/.test(trimmed)))
+        return 'method';
+    if (/\b(const|readonly)\b/.test(trimmed))
+        return 'constant';
+    if (/\b(let|var)\b/.test(trimmed))
+        return 'variable';
+    if (isNested)
+        return 'property';
+    return 'other';
 }
 /**
  * Scans backwards from a declaration index to collect preceding docstrings, JSDoc blocks, decorators, and line comments.
@@ -58,9 +187,9 @@ function findPrecedingContext(lines, declarationIndex, ext) {
     let insideJsDoc = false;
     while (start > 0) {
         const prevLine = lines[start - 1].trim();
-        const isJsDocEnd = ['.ts', '.js', '.tsx', '.jsx'].includes(ext) && prevLine === '*/';
-        const isJsDocLine = ['.ts', '.js', '.tsx', '.jsx'].includes(ext) && prevLine.startsWith('*');
-        const isJsDocStart = ['.ts', '.js', '.tsx', '.jsx'].includes(ext) && prevLine.startsWith('/**');
+        const isJsDocEnd = ['.ts', '.js', '.tsx', '.jsx', '.mts', '.cts', '.mjs', '.cjs'].includes(ext) && prevLine === '*/';
+        const isJsDocLine = ['.ts', '.js', '.tsx', '.jsx', '.mts', '.cts', '.mjs', '.cjs'].includes(ext) && prevLine.startsWith('*');
+        const isJsDocStart = ['.ts', '.js', '.tsx', '.jsx', '.mts', '.cts', '.mjs', '.cjs'].includes(ext) && prevLine.startsWith('/**');
         if (isJsDocEnd)
             insideJsDoc = true;
         if (!prevLine) {
@@ -73,9 +202,10 @@ function findPrecedingContext(lines, declarationIndex, ext) {
             }
         }
         const isDecorator = prevLine.startsWith('@');
-        const isPythonComment = ext === '.py' && prevLine.startsWith('#');
+        const isPythonComment = (ext === '.py' || ext === '.pyi') && prevLine.startsWith('#');
         const isLineComment = prevLine.startsWith('//');
-        if (isDecorator || isPythonComment || isLineComment || isJsDocEnd || isJsDocLine || isJsDocStart) {
+        const isRustDocOrAttr = (ext === '.rs') && (prevLine.startsWith('///') || prevLine.startsWith('//!') || prevLine.startsWith('#['));
+        if (isDecorator || isPythonComment || isLineComment || isJsDocEnd || isJsDocLine || isJsDocStart || isRustDocOrAttr) {
             start--;
             if (isJsDocStart) {
                 insideJsDoc = false;
@@ -112,7 +242,7 @@ function scanLineValidity(line, state) {
         if (!state.inMultiLineComment && !state.inMultiLineString) {
             if (line[j] === '/' && line[j + 1] === '/')
                 break;
-            if (state.ext === '.py' && line[j] === '#')
+            if ((state.ext === '.py' || state.ext === '.pyi') && line[j] === '#')
                 break;
             if (line[j] === '/' && line[j + 1] === '*') {
                 state.inMultiLineComment = true;
@@ -208,7 +338,7 @@ function processLineChars(line, state) {
  */
 function findBlockEnd(lines, i, ext) {
     let endIndex = i;
-    if (ext === '.py') {
+    if (ext === '.py' || ext === '.pyi') {
         const baseIndentation = getIndentation(lines[i]);
         for (let j = i + 1; j < lines.length; j++) {
             if (isCommentOrEmpty(lines[j], ext)) {
@@ -250,26 +380,36 @@ function addLinesToKeep(linesToKeep, start, end) {
         linesToKeep.add(k);
 }
 /**
- * Checks whether a line matches any of the target symbol declaration regular expressions.
+ * Extracts clean signature representation from lines.
  *
- * @param symbolRegexes - Array of compiled symbol regex objects
- * @param line - The source line string to test
- * @returns The matching SymbolRegex object if found, or null otherwise
+ * @param lines - File lines
+ * @param startLine - Start index of declaration
+ * @param endLine - End index of block
+ * @returns Cleaned signature string
  */
-function findMatchedRegex(symbolRegexes, line) {
-    for (let k = 0; k < symbolRegexes.length; k++) {
-        if (symbolRegexes[k].regex.test(line))
-            return symbolRegexes[k];
+function extractCleanSignature(lines, startLine, endLine) {
+    const sigLines = [];
+    for (let i = startLine; i <= endLine; i++) {
+        const line = lines[i];
+        sigLines.push(line);
+        if (line.includes('{') || line.trim().endsWith(':') || line.trim().endsWith(';'))
+            break;
+    }
+    const rawSig = sigLines.join('\n').trim();
+    const braceIdx = rawSig.indexOf('{');
+    if (braceIdx !== -1) {
+        return rawSig.substring(0, braceIdx).trim();
     }
-    return null;
+    return rawSig;
 }
 /**
- * Extracts specified target symbols from source file content and returns their line number ranges and names.
+ * 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 function extractSymbolMetadata(content, filePath, targetElements) {
     if (!targetElements || targetElements.length === 0)
@@ -285,7 +425,16 @@ export function extractSymbolMetadata(content, filePath, targetElements) {
             validLines[i] = false;
         }
     }
-    const symbolRegexes = targetElements.map((symbol) => ({ symbol, regex: buildDeclarationRegex(symbol, ext) }));
+    const symbolTargets = targetElements.map((target) => {
+        const { parentName, memberName } = parseTargetSymbol(target);
+        return {
+            target,
+            parentName,
+            memberName,
+            regex: buildDeclarationRegex(parentName || memberName, ext),
+            memberRegex: buildMemberRegex(memberName, ext),
+        };
+    });
     const symbols = [];
     let i = 0;
     while (i < lines.length) {
@@ -293,67 +442,470 @@ export function extractSymbolMetadata(content, filePath, targetElements) {
             i++;
             continue;
         }
-        const matched = findMatchedRegex(symbolRegexes, lines[i]);
-        if (matched) {
-            const startIndex = findPrecedingContext(lines, i, ext);
-            const endIndex = findBlockEnd(lines, i, ext);
-            symbols.push({
-                symbol: matched.symbol,
-                startLine: startIndex,
-                endLine: endIndex
-            });
-            i = endIndex + 1;
+        const line = lines[i];
+        for (const symTarget of symbolTargets) {
+            // 1. If target specified a parent (e.g. Class.method)
+            if (symTarget.parentName) {
+                if (symTarget.regex.test(line)) {
+                    const parentStartIndex = findPrecedingContext(lines, i, ext);
+                    const parentEndIndex = findBlockEnd(lines, i, ext);
+                    // Scan inside the parent body for the member
+                    for (let m = i + 1; m <= parentEndIndex; m++) {
+                        if (!validLines[m])
+                            continue;
+                        if (symTarget.memberRegex.test(lines[m])) {
+                            const memberStartIndex = findPrecedingContext(lines, m, ext);
+                            const memberEndIndex = findBlockEnd(lines, m, ext);
+                            const sig = extractCleanSignature(lines, memberStartIndex, memberEndIndex);
+                            symbols.push({
+                                symbol: symTarget.target,
+                                parentSymbol: symTarget.parentName,
+                                startLine: memberStartIndex,
+                                endLine: memberEndIndex,
+                                kind: inferSymbolKind(lines[m], ext, true),
+                                signature: sig,
+                            });
+                            break;
+                        }
+                    }
+                }
+            }
+            else {
+                // 2. Direct top-level match or standalone member match
+                if (symTarget.regex.test(line)) {
+                    const startIndex = findPrecedingContext(lines, i, ext);
+                    const endIndex = findBlockEnd(lines, i, ext);
+                    const sig = extractCleanSignature(lines, startIndex, endIndex);
+                    symbols.push({
+                        symbol: symTarget.target,
+                        startLine: startIndex,
+                        endLine: endIndex,
+                        kind: inferSymbolKind(line, ext, false),
+                        signature: sig,
+                    });
+                    i = endIndex;
+                    break;
+                }
+            }
         }
-        else {
+        i++;
+    }
+    // Deduplicate matched ranges
+    const uniqueSymbols = [];
+    const seenRanges = new Set();
+    for (const s of symbols) {
+        const key = `${s.symbol}:${s.startLine}:${s.endLine}`;
+        if (!seenRanges.has(key)) {
+            seenRanges.add(key);
+            uniqueSymbols.push(s);
+        }
+    }
+    return uniqueSymbols;
+}
+/**
+ * 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 function extractSymbolIndex(content, filePath) {
+    if (!content || !content.trim())
+        return [];
+    const ext = path.extname(filePath).toLowerCase();
+    const lines = content.split('\n');
+    const symbols = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (!trimmed || isCommentOrEmpty(trimmed, ext)) {
             i++;
+            continue;
         }
+        // Check TS/JS declarations
+        if (['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.mjs', '.cjs'].includes(ext)) {
+            const classMatch = trimmed.match(/^(?:export\s+|default\s+|abstract\s+|declare\s+)*class\s+([A-Za-z0-9_$]+)/);
+            const ifaceMatch = trimmed.match(/^(?:export\s+|declare\s+|default\s+)*interface\s+([A-Za-z0-9_$]+)/);
+            const typeMatch = trimmed.match(/^(?:export\s+|declare\s+)*type\s+([A-Za-z0-9_$]+)/);
+            const enumMatch = trimmed.match(/^(?:export\s+|const\s+|declare\s+)*enum\s+([A-Za-z0-9_$]+)/);
+            const fnMatch = trimmed.match(/^(?:export\s+|default\s+|async\s+|declare\s+)*function(?:\s*\*|\s+([A-Za-z0-9_$]+))/);
+            const constFnMatch = trimmed.match(/^(?:export\s+)?(?:const|let|var)\s+([A-Za-z0-9_$]+)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z0-9_$]+)\s*=>/);
+            if (classMatch) {
+                const className = classMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: className,
+                    startLine,
+                    endLine,
+                    kind: 'class',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                // Inspect inner members of class
+                for (let m = i + 1; m < endLine; m++) {
+                    const mLine = lines[m].trim();
+                    if (!mLine || isCommentOrEmpty(mLine, ext))
+                        continue;
+                    const methodMatch = mLine.match(/^(?:public\s+|private\s+|protected\s+|static\s+|async\s+|abstract\s+|override\s+|readonly\s+|get\s+|set\s+)*(constructor|[A-Za-z0-9_$]+)\s*(?:<[^>]+>)?\s*\(/);
+                    if (methodMatch) {
+                        const mName = methodMatch[1];
+                        const mStart = findPrecedingContext(lines, m, ext);
+                        const mEnd = findBlockEnd(lines, m, ext);
+                        symbols.push({
+                            symbol: `${className}.${mName}`,
+                            parentSymbol: className,
+                            startLine: mStart,
+                            endLine: mEnd,
+                            kind: mName === 'constructor' ? 'constructor' : 'method',
+                            signature: extractCleanSignature(lines, m, mEnd),
+                        });
+                        m = mEnd;
+                    }
+                }
+                i = endLine + 1;
+                continue;
+            }
+            if (ifaceMatch) {
+                const ifaceName = ifaceMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: ifaceName,
+                    startLine,
+                    endLine,
+                    kind: 'interface',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+            if (typeMatch) {
+                const typeName = typeMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: typeName,
+                    startLine,
+                    endLine,
+                    kind: 'type',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+            if (enumMatch) {
+                const enumName = enumMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: enumName,
+                    startLine,
+                    endLine,
+                    kind: 'enum',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+            if (fnMatch && fnMatch[1]) {
+                const fnName = fnMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: fnName,
+                    startLine,
+                    endLine,
+                    kind: 'function',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+            if (constFnMatch) {
+                const fnName = constFnMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: fnName,
+                    startLine,
+                    endLine,
+                    kind: 'function',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+        }
+        else if (ext === '.py' || ext === '.pyi') {
+            const classMatch = trimmed.match(/^class\s+([A-Za-z0-9_$]+)/);
+            const fnMatch = trimmed.match(/^(?:async\s+)?def\s+([A-Za-z0-9_$]+)/);
+            if (classMatch) {
+                const className = classMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: className,
+                    startLine,
+                    endLine,
+                    kind: 'class',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                // Inspect inner methods
+                for (let m = i + 1; m <= endLine; m++) {
+                    const mLine = lines[m];
+                    const mTrim = mLine.trim();
+                    const mMatch = mTrim.match(/^(?:async\s+)?def\s+([A-Za-z0-9_$]+)/);
+                    if (mMatch) {
+                        const mName = mMatch[1];
+                        const mStart = findPrecedingContext(lines, m, ext);
+                        const mEnd = findBlockEnd(lines, m, ext);
+                        symbols.push({
+                            symbol: `${className}.${mName}`,
+                            parentSymbol: className,
+                            startLine: mStart,
+                            endLine: mEnd,
+                            kind: 'method',
+                            signature: extractCleanSignature(lines, m, mEnd),
+                        });
+                        m = mEnd;
+                    }
+                }
+                i = endLine + 1;
+                continue;
+            }
+            if (fnMatch) {
+                const fnName = fnMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: fnName,
+                    startLine,
+                    endLine,
+                    kind: 'function',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+        }
+        else if (ext === '.go') {
+            const typeMatch = trimmed.match(/^type\s+([A-Za-z0-9_$]+)\s+(struct|interface|\w+)/);
+            const funcMatch = trimmed.match(/^func\s+(?:\((?:[A-Za-z0-9_$*]+\s+)?([A-Za-z0-9_$*]+)\)\s+)?([A-Za-z0-9_$]+)/);
+            if (typeMatch) {
+                const typeName = typeMatch[1];
+                const typeKind = typeMatch[2] === 'struct' ? 'struct' : typeMatch[2] === 'interface' ? 'interface' : 'type';
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: typeName,
+                    startLine,
+                    endLine,
+                    kind: typeKind,
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+            if (funcMatch) {
+                const receiver = funcMatch[1]?.replace('*', '');
+                const fnName = funcMatch[2];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: receiver ? `${receiver}.${fnName}` : fnName,
+                    parentSymbol: receiver,
+                    startLine,
+                    endLine,
+                    kind: receiver ? 'method' : 'function',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+        }
+        else if (ext === '.rs') {
+            const structMatch = trimmed.match(/^(?:pub(?:\([^)]+\))?\s+)?struct\s+([A-Za-z0-9_$]+)/);
+            const enumMatch = trimmed.match(/^(?:pub(?:\([^)]+\))?\s+)?enum\s+([A-Za-z0-9_$]+)/);
+            const traitMatch = trimmed.match(/^(?:pub(?:\([^)]+\))?\s+)?trait\s+([A-Za-z0-9_$]+)/);
+            const implMatch = trimmed.match(/^(?:pub(?:\([^)]+\))?\s+)?impl(?:\s+<[^>]+>)?\s+(?:([A-Za-z0-9_$]+)\s+for\s+)?([A-Za-z0-9_$]+)/);
+            const fnMatch = trimmed.match(/^(?:pub(?:\([^)]+\))?\s+)?(?:async\s+|const\s+|unsafe\s+|extern\s+)?fn\s+([A-Za-z0-9_$]+)/);
+            if (structMatch) {
+                const name = structMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: name,
+                    startLine,
+                    endLine,
+                    kind: 'struct',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+            if (enumMatch) {
+                const name = enumMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: name,
+                    startLine,
+                    endLine,
+                    kind: 'enum',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+            if (traitMatch) {
+                const name = traitMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: name,
+                    startLine,
+                    endLine,
+                    kind: 'trait',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+            if (implMatch) {
+                const traitName = implMatch[1];
+                const targetType = implMatch[2];
+                const implName = traitName ? `${traitName} for ${targetType}` : targetType;
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: implName,
+                    parentSymbol: targetType,
+                    startLine,
+                    endLine,
+                    kind: 'impl',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                // Inspect inner methods in impl
+                for (let m = i + 1; m < endLine; m++) {
+                    const mLine = lines[m].trim();
+                    const mFnMatch = mLine.match(/^(?:pub(?:\([^)]+\))?\s+)?(?:async\s+|const\s+|unsafe\s+|extern\s+)?fn\s+([A-Za-z0-9_$]+)/);
+                    if (mFnMatch) {
+                        const fnName = mFnMatch[1];
+                        const mStart = findPrecedingContext(lines, m, ext);
+                        const mEnd = findBlockEnd(lines, m, ext);
+                        symbols.push({
+                            symbol: `${targetType}.${fnName}`,
+                            parentSymbol: targetType,
+                            startLine: mStart,
+                            endLine: mEnd,
+                            kind: 'method',
+                            signature: extractCleanSignature(lines, m, mEnd),
+                        });
+                        m = mEnd;
+                    }
+                }
+                i = endLine + 1;
+                continue;
+            }
+            if (fnMatch) {
+                const fnName = fnMatch[1];
+                const startLine = findPrecedingContext(lines, i, ext);
+                const endLine = findBlockEnd(lines, i, ext);
+                symbols.push({
+                    symbol: fnName,
+                    startLine,
+                    endLine,
+                    kind: 'function',
+                    signature: extractCleanSignature(lines, i, endLine),
+                });
+                i = endLine + 1;
+                continue;
+            }
+        }
+        i++;
     }
     return symbols;
 }
 /**
- * Extracts specified target symbols (functions, classes, variables, interfaces, etc.) from source file content
+ * 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 function chunkDefinitions(content, filePath, options) {
+    if (!content || !content.trim())
+        return [];
+    const symbols = extractSymbolIndex(content, filePath);
+    const lines = content.split('\n');
+    const maxChunkLines = options?.maxChunkLines ?? 500;
+    const includeBodies = options?.includeBodies ?? true;
+    const filterKinds = options?.filterKinds ? new Set(options.filterKinds) : null;
+    const chunks = [];
+    for (const sym of symbols) {
+        if (filterKinds && sym.kind && !filterKinds.has(sym.kind))
+            continue;
+        let chunkLines = lines.slice(sym.startLine, sym.endLine + 1);
+        if (!includeBodies && (sym.kind === 'function' || sym.kind === 'method' || sym.kind === 'class')) {
+            const sig = sym.signature || extractCleanSignature(lines, sym.startLine, sym.endLine);
+            chunkLines = [sig + ' { ... }'];
+        }
+        else if (chunkLines.length > maxChunkLines) {
+            const truncated = chunkLines.slice(0, maxChunkLines);
+            truncated.push(`// ... [Truncated: ${chunkLines.length - maxChunkLines} additional lines omitted]`);
+            chunkLines = truncated;
+        }
+        const chunkContent = chunkLines.join('\n');
+        const chunkId = `${filePath}:${sym.symbol}`;
+        chunks.push({
+            id: chunkId,
+            symbol: sym.symbol,
+            parentSymbol: sym.parentSymbol,
+            kind: sym.kind || 'other',
+            startLine: sym.startLine,
+            endLine: sym.endLine,
+            signature: sym.signature || extractCleanSignature(lines, sym.startLine, sym.endLine),
+            doc: sym.doc,
+            content: chunkContent,
+            tokenEstimate: estimateTokens(chunkContent),
+        });
+    }
+    return chunks;
+}
+/**
+ * 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 function extractSymbols(content, filePath, targetElements) {
+export function extractSymbols(content, filePath, targetElements, options) {
     if (!targetElements || targetElements.length === 0)
         return content;
     const ext = path.extname(filePath).toLowerCase();
     const lines = content.split('\n');
     const linesToKeep = new Set();
-    const validLines = new Array(lines.length).fill(true);
-    const scanState = { inMultiLineComment: false, inMultiLineString: null, ext };
-    for (let i = 0; i < lines.length; i++) {
-        const startsInMulti = scanState.inMultiLineComment || scanState.inMultiLineString !== null;
-        const lineHasValidCode = scanLineValidity(lines[i], scanState);
-        if (startsInMulti || (!lineHasValidCode && (scanState.inMultiLineComment || scanState.inMultiLineString !== null))) {
-            validLines[i] = false;
-        }
-    }
-    const symbolRegexes = targetElements.map((symbol) => ({ symbol, regex: buildDeclarationRegex(symbol, ext) }));
-    let i = 0;
-    while (i < lines.length) {
-        if (!validLines[i]) {
-            i++;
-            continue;
-        }
-        const matched = findMatchedRegex(symbolRegexes, lines[i]);
-        if (matched) {
-            const startIndex = findPrecedingContext(lines, i, ext);
-            const endIndex = findBlockEnd(lines, i, ext);
-            addLinesToKeep(linesToKeep, startIndex, endIndex);
-            i = endIndex + 1;
-        }
-        else {
-            i++;
+    const metadata = extractSymbolMetadata(content, filePath, targetElements);
+    for (const meta of metadata) {
+        let start = meta.startLine;
+        let end = meta.endLine;
+        if (options?.maxLinesPerSymbol && end - start + 1 > options.maxLinesPerSymbol) {
+            end = start + options.maxLinesPerSymbol - 1;
         }
+        addLinesToKeep(linesToKeep, start, end);
     }
     if (linesToKeep.size === 0) {
         return `// No specific symbols matching ${JSON.stringify(targetElements)} were found in this file.\n// Try using normal read_file without targetElements, or check spelling.`;