openlore 2.0.0

package/dist/core/analyzer/signature-extractor.js

@@ -0,0 +1,675 @@
+/**
+ * Signature Extractor
+ *
+ * Extracts function/class signatures and docstrings from source files
+ * across multiple languages using regex patterns (no AST required).
+ *
+ * Used to build a compact semantic index of all project files for Stage 1,
+ * replacing the simple file-path list with language-aware summaries.
+ */
+// Max signatures per file to keep output compact
+const MAX_SIGS_PER_FILE = 25;
+// Max chars per Stage 1 chunk (~10k tokens, safe for all providers)
+export const STAGE1_MAX_CHARS = 40_000;
+// ============================================================================
+// LANGUAGE DETECTION
+// ============================================================================
+export function detectLanguage(filePath) {
+    const ext = filePath.split('.').pop()?.toLowerCase() ?? '';
+    switch (ext) {
+        case 'py': return 'Python';
+        case 'ts':
+        case 'tsx': return 'TypeScript';
+        case 'js':
+        case 'jsx': return 'JavaScript';
+        case 'go': return 'Go';
+        case 'rs': return 'Rust';
+        case 'rb': return 'Ruby';
+        case 'java': return 'Java';
+        case 'kt': return 'Kotlin';
+        case 'php': return 'PHP';
+        case 'cs': return 'C#';
+        case 'cpp':
+        case 'cc':
+        case 'cxx':
+        case 'h':
+        case 'hpp': return 'C++';
+        case 'c': return 'C';
+        case 'swift': return 'Swift';
+        default: return 'unknown';
+    }
+}
+// ============================================================================
+// PYTHON EXTRACTOR
+// ============================================================================
+function extractPython(content) {
+    const entries = [];
+    const lines = content.split('\n');
+    let pendingDecorator;
+    let currentClass;
+    let currentClassIndent = -1;
+    for (let i = 0; i < lines.length && entries.length < MAX_SIGS_PER_FILE; i++) {
+        const line = lines[i];
+        const trimmed = line.trimStart();
+        const indent = line.length - trimmed.length;
+        // Track class context (methods vs module-level functions)
+        if (indent === 0 && currentClass && indent <= currentClassIndent) {
+            currentClass = undefined;
+            currentClassIndent = -1;
+        }
+        // Decorator lines
+        const decoratorMatch = trimmed.match(/^(@(?:[\w.]+)(?:\([^)]*\))?)/);
+        if (decoratorMatch) {
+            pendingDecorator = decoratorMatch[1];
+            continue;
+        }
+        // Class declaration
+        const classMatch = trimmed.match(/^class\s+(\w+)(?:\s*\(([^)]*)\))?\s*:/);
+        if (classMatch && indent === 0) {
+            const name = classMatch[1];
+            const bases = classMatch[2] ? `(${classMatch[2]})` : '';
+            const docstring = extractPythonDocstring(lines, i + 1);
+            entries.push({
+                kind: 'class',
+                name,
+                signature: `class ${name}${bases}:`,
+                docstring,
+            });
+            currentClass = name;
+            currentClassIndent = indent;
+            pendingDecorator = undefined;
+            continue;
+        }
+        // Function / method declaration
+        const funcMatch = trimmed.match(/^(async\s+)?def\s+(\w+)\s*\(([^)]*)\)(?:\s*->\s*([^\n:]+))?\s*:/);
+        if (funcMatch) {
+            const isAsync = !!funcMatch[1];
+            const name = funcMatch[2];
+            const params = funcMatch[3].trim();
+            const ret = funcMatch[4]?.trim() ?? '';
+            // Skip private methods (leading underscore) unless very few entries so far
+            if (name.startsWith('_') && name !== '__init__' && entries.length > 2) {
+                pendingDecorator = undefined;
+                continue;
+            }
+            const asyncPrefix = isAsync ? 'async ' : '';
+            const returnSuffix = ret ? ` -> ${ret}` : '';
+            // Compact params: remove 'self' from display
+            const displayParams = params
+                .split(',')
+                .map(p => p.trim())
+                .filter(p => p !== 'self' && p !== 'cls')
+                .join(', ');
+            const sig = `${asyncPrefix}def ${name}(${displayParams})${returnSuffix}`;
+            const docstring = extractPythonDocstring(lines, i + 1);
+            const kind = indent > 0 ? 'method' : 'function';
+            entries.push({
+                kind,
+                name,
+                signature: (indent > 0 ? '  ' : '') + sig,
+                docstring,
+                decorator: pendingDecorator,
+            });
+            pendingDecorator = undefined;
+            continue;
+        }
+        // Module-level ALL_CAPS constants (PEP 8 convention), only at indent 0 and outside class
+        const constMatch = indent === 0 && !currentClass
+            ? trimmed.match(/^([A-Z][A-Z0-9_]{1,})\s*(?::\s*[\w[\], |]+)?\s*=/)
+            : null;
+        if (constMatch) {
+            const name = constMatch[1];
+            const sig = trimmed.slice(0, 80).replace(/\s+/g, ' ');
+            // Use preceding # comment as docstring
+            const comment = lines[i - 1]?.trim().startsWith('#')
+                ? lines[i - 1].trim().slice(1).trim()
+                : undefined;
+            entries.push({ kind: 'const', name, signature: sig, docstring: comment });
+            pendingDecorator = undefined;
+            continue;
+        }
+        // Reset decorator if line is neither decorator nor def/class
+        if (trimmed && !trimmed.startsWith('#')) {
+            pendingDecorator = undefined;
+        }
+    }
+    return entries;
+}
+function extractPythonDocstring(lines, startIdx) {
+    const next = lines[startIdx]?.trimStart() ?? '';
+    if (next.startsWith('"""') || next.startsWith("'''")) {
+        const quote = next.startsWith('"""') ? '"""' : "'''";
+        const inner = next.slice(3);
+        // Single-line docstring: """Text"""
+        if (inner.includes(quote)) {
+            return inner.slice(0, inner.indexOf(quote)).trim() || undefined;
+        }
+        // Multi-line: take the first non-empty line
+        return inner.trim() || lines[startIdx + 1]?.trim() || undefined;
+    }
+    return undefined;
+}
+// ============================================================================
+// TYPESCRIPT / JAVASCRIPT EXTRACTOR
+// ============================================================================
+function extractTypeScript(content) {
+    const entries = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length && entries.length < MAX_SIGS_PER_FILE; i++) {
+        const line = lines[i];
+        const trimmed = line.trimStart();
+        // Collect JSDoc comment above the declaration
+        let jsDoc;
+        if (i > 0) {
+            jsDoc = extractJSDoc(lines, i);
+        }
+        // export class / export abstract class
+        const classMatch = trimmed.match(/^export\s+(?:default\s+)?(?:abstract\s+)?class\s+(\w+)(?:\s+extends\s+([\w<>, .]+?))?(?:\s+implements\s+[\w<>, .]+)?\s*\{?/);
+        if (classMatch) {
+            const name = classMatch[1];
+            const ext = classMatch[2] ? ` extends ${classMatch[2].trim()}` : '';
+            entries.push({ kind: 'class', name, signature: `export class ${name}${ext}`, docstring: jsDoc });
+            continue;
+        }
+        // export interface
+        const ifaceMatch = trimmed.match(/^export\s+(?:default\s+)?interface\s+(\w+)(?:\s+extends\s+[\w<>, .]+)?\s*\{?/);
+        if (ifaceMatch) {
+            entries.push({ kind: 'interface', name: ifaceMatch[1], signature: `export interface ${ifaceMatch[1]}`, docstring: jsDoc });
+            continue;
+        }
+        // export type
+        const typeMatch = trimmed.match(/^export\s+type\s+(\w+)\s*(?:<[^>]*>)?\s*=/);
+        if (typeMatch) {
+            entries.push({ kind: 'type', name: typeMatch[1], signature: `export type ${typeMatch[1]}`, docstring: jsDoc });
+            continue;
+        }
+        // export function / export async function / export default function
+        const fnMatch = trimmed.match(/^export\s+(?:default\s+)?(?:async\s+)?function\s+(\w+)\s*(?:<[^>]*>)?\s*\(([^)]*)\)(?:\s*:\s*([^{]+))?/);
+        if (fnMatch) {
+            const name = fnMatch[1];
+            const params = compactParams(fnMatch[2]);
+            const ret = fnMatch[3]?.trim().replace(/\s+/g, ' ') ?? '';
+            const sig = `export function ${name}(${params})${ret ? ': ' + ret : ''}`;
+            entries.push({ kind: 'function', name, signature: sig, docstring: jsDoc });
+            continue;
+        }
+        // Multi-line export function: `export [async] function name(` with params on following lines
+        const fnOpenMatch = trimmed.match(/^export\s+(?:default\s+)?(?:async\s+)?function\s+(\w+)\s*(?:<[^>]*>)?\s*\($/);
+        if (fnOpenMatch) {
+            const name = fnOpenMatch[1];
+            // Scan forward to collect params until closing paren
+            let parenDepth = 1;
+            const paramLines = [];
+            let retType = '';
+            let j = i + 1;
+            for (; j < lines.length && parenDepth > 0; j++) {
+                const jl = lines[j];
+                for (const ch of jl) {
+                    if (ch === '(')
+                        parenDepth++;
+                    else if (ch === ')') {
+                        parenDepth--;
+                        if (parenDepth === 0)
+                            break;
+                    }
+                }
+                if (parenDepth > 0)
+                    paramLines.push(jl.trim().replace(/,$/, ''));
+            }
+            // Try to get return type from the line after closing paren (e.g. `): Promise<T> {`)
+            if (j < lines.length) {
+                const retMatch = lines[j].match(/\)\s*:\s*([^{]+)/);
+                if (retMatch)
+                    retType = retMatch[1].trim().replace(/\s+/g, ' ');
+            }
+            const params = paramLines.map(p => p.split(':')[0].trim()).filter(Boolean).join(', ');
+            const sig = `export function ${name}(${params})${retType ? ': ' + retType : ''}`;
+            entries.push({ kind: 'function', name, signature: sig, docstring: jsDoc });
+            continue;
+        }
+        // export const foo = (...) => / export const foo: Type = (...)
+        const arrowMatch = trimmed.match(/^export\s+const\s+(\w+)(?:\s*:\s*[\w<>[\], |&]+)?\s*=\s*(?:async\s+)?\(/);
+        if (arrowMatch) {
+            entries.push({ kind: 'function', name: arrowMatch[1], signature: `export const ${arrowMatch[1]} = (...)`, docstring: jsDoc });
+            continue;
+        }
+        // export const FOO = { ... } / [...] / primitive — objects, arrays, config constants
+        const constMatch = trimmed.match(/^export\s+const\s+(\w+)/);
+        if (constMatch) {
+            const sig = trimmed.slice(0, 80).replace(/\s+/g, ' ');
+            entries.push({ kind: 'const', name: constMatch[1], signature: sig, docstring: jsDoc });
+            continue;
+        }
+        // Public/private class methods (indented, not '#' private fields) — single-line params
+        // Private methods with JSDoc are included: they're documented because the impl is worth finding.
+        const methodMatch = trimmed.match(/^(?:public\s+|static\s+|override\s+|async\s+|private\s+|protected\s+)*(?:public\s+|private\s+|protected\s+)?(?:static\s+)?(?:async\s+)?(\w+)\s*\(([^)]*)\)(?:\s*:\s*([^{]+))?.*\{/);
+        if (methodMatch && line.startsWith('  ') && !trimmed.startsWith('//') && !trimmed.startsWith('*') && !trimmed.startsWith('#')) {
+            const name = methodMatch[1];
+            if (/^[a-z]/.test(name) && name !== 'if' && name !== 'for' && name !== 'while' && name !== 'switch' && name !== 'return') {
+                const params = compactParams(methodMatch[2]);
+                const ret = methodMatch[3]?.trim().replace(/\s+/g, ' ') ?? '';
+                entries.push({ kind: 'method', name, signature: `  ${name}(${params})${ret ? ': ' + ret : ''}`, docstring: jsDoc });
+                continue;
+            }
+        }
+        // Multi-line class method: `[static] [async] methodName(` with no closing paren on same line
+        const methodOpenMatch = trimmed.match(/^(?:public\s+|static\s+|override\s+|async\s+|private\s+|protected\s+)*(?:public\s+|private\s+|protected\s+)?(?:static\s+)?(?:async\s+)?(\w+)\s*\($/);
+        if (methodOpenMatch && line.startsWith('  ') && !trimmed.startsWith('//') && !trimmed.startsWith('*') && !trimmed.startsWith('#')) {
+            const name = methodOpenMatch[1];
+            if (/^[a-z]/.test(name) && name !== 'if' && name !== 'for' && name !== 'while' && name !== 'switch' && name !== 'return') {
+                let parenDepth = 1;
+                const paramLines = [];
+                let retType = '';
+                let j = i + 1;
+                for (; j < lines.length && parenDepth > 0; j++) {
+                    const jl = lines[j];
+                    for (const ch of jl) {
+                        if (ch === '(')
+                            parenDepth++;
+                        else if (ch === ')') {
+                            parenDepth--;
+                            if (parenDepth === 0)
+                                break;
+                        }
+                    }
+                    if (parenDepth > 0)
+                        paramLines.push(jl.trim().replace(/,$/, ''));
+                }
+                if (j < lines.length) {
+                    const retMatch = lines[j].match(/\)\s*:\s*([^{]+)/);
+                    if (retMatch)
+                        retType = retMatch[1].trim().replace(/\s+/g, ' ');
+                }
+                const params = paramLines.map(p => p.split(':')[0].trim()).filter(Boolean).join(', ');
+                entries.push({ kind: 'method', name, signature: `  ${name}(${params})${retType ? ': ' + retType : ''}`, docstring: jsDoc });
+            }
+        }
+    }
+    return entries;
+}
+function extractJSDoc(lines, declLineIdx) {
+    // Walk backwards to find */ then /**
+    let endIdx = declLineIdx - 1;
+    // Skip blank lines
+    while (endIdx >= 0 && lines[endIdx].trim() === '')
+        endIdx--;
+    if (endIdx < 0 || !lines[endIdx].trim().endsWith('*/'))
+        return undefined;
+    let startIdx = endIdx;
+    while (startIdx >= 0 && !lines[startIdx].trim().startsWith('/**'))
+        startIdx--;
+    if (startIdx < 0)
+        return undefined;
+    // Find first meaningful @description or plain text line
+    for (let j = startIdx + 1; j <= endIdx; j++) {
+        const t = lines[j].replace(/^\s*\*\s?/, '').trim();
+        if (t && !t.startsWith('@'))
+            return t;
+    }
+    return undefined;
+}
+function compactParams(params) {
+    return params
+        .split(',')
+        .map(p => p.trim().replace(/\s+/g, ' '))
+        .filter(Boolean)
+        .join(', ');
+}
+// ============================================================================
+// GO EXTRACTOR
+// ============================================================================
+function extractGo(content) {
+    const entries = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length && entries.length < MAX_SIGS_PER_FILE; i++) {
+        const line = lines[i];
+        // func (r *Receiver) Name(args) ret or func Name(args) ret
+        const match = line.match(/^func\s+(?:\([^)]+\)\s+)?(\w+)\s*\(([^)]*)\)(?:\s*(?:\([^)]*\)|[\w*[\], ]+))?/);
+        if (match) {
+            const name = match[1];
+            if (name === 'init' || name.startsWith('test') || name.startsWith('Test'))
+                continue;
+            // Grab comment above
+            const comment = lines[i - 1]?.trim().startsWith('//') ? lines[i - 1].trim().slice(2).trim() : undefined;
+            entries.push({ kind: 'function', name, signature: line.trim().replace(/\s*\{.*$/, ''), docstring: comment });
+        }
+        // type Foo struct or type Foo interface
+        const typeMatch = line.match(/^type\s+(\w+)\s+(struct|interface)\s*\{?/);
+        if (typeMatch) {
+            entries.push({ kind: typeMatch[2] === 'interface' ? 'interface' : 'class', name: typeMatch[1], signature: `type ${typeMatch[1]} ${typeMatch[2]}` });
+        }
+    }
+    return entries;
+}
+// ============================================================================
+// RUST EXTRACTOR
+// ============================================================================
+function extractRust(content) {
+    const entries = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length && entries.length < MAX_SIGS_PER_FILE; i++) {
+        const line = lines[i];
+        // pub fn / pub async fn
+        const fnMatch = line.match(/^\s*pub(?:\(crate\))?\s+(?:async\s+)?fn\s+(\w+)\s*(?:<[^>]*>)?\s*\(([^)]*)\)(?:\s*->\s*([^{]+))?/);
+        if (fnMatch) {
+            const name = fnMatch[1];
+            const params = compactParams(fnMatch[2]);
+            const ret = fnMatch[3]?.trim() ?? '';
+            const sig = `pub fn ${name}(${params})${ret ? ' -> ' + ret : ''}`;
+            const comment = lines[i - 1]?.trim().startsWith('///') ? lines[i - 1].trim().slice(3).trim() : undefined;
+            entries.push({ kind: 'function', name, signature: sig, docstring: comment });
+        }
+        // pub struct / pub enum
+        const typeMatch = line.match(/^\s*pub(?:\(crate\))?\s+(struct|enum)\s+(\w+)/);
+        if (typeMatch) {
+            entries.push({ kind: 'class', name: typeMatch[2], signature: `pub ${typeMatch[1]} ${typeMatch[2]}` });
+        }
+    }
+    return entries;
+}
+// ============================================================================
+// RUBY EXTRACTOR
+// ============================================================================
+function extractRuby(content) {
+    const entries = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length && entries.length < MAX_SIGS_PER_FILE; i++) {
+        const line = lines[i].trim();
+        const classMatch = line.match(/^class\s+(\w+)(?:\s*<\s*(\w+))?/);
+        if (classMatch) {
+            const name = classMatch[1];
+            const parent = classMatch[2] ? ` < ${classMatch[2]}` : '';
+            entries.push({ kind: 'class', name, signature: `class ${name}${parent}` });
+            continue;
+        }
+        const methodMatch = line.match(/^def\s+(\w+)(?:\s*\(([^)]*)\))?/);
+        if (methodMatch) {
+            const name = methodMatch[1];
+            const params = methodMatch[2] ? `(${methodMatch[2]})` : '';
+            entries.push({ kind: 'function', name, signature: `def ${name}${params}` });
+        }
+    }
+    return entries;
+}
+// ============================================================================
+// C++ EXTRACTOR
+// ============================================================================
+/** Keywords that look like function names but are control-flow or declarations */
+const CPP_SKIP_NAMES = new Set([
+    'if', 'for', 'while', 'switch', 'catch', 'namespace', 'class', 'struct',
+    'return', 'delete', 'do', 'else', 'new', 'sizeof', 'static_assert', 'assert',
+    'typedef', 'template', 'decltype', 'alignof', 'typeid',
+]);
+function extractCpp(content) {
+    const entries = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length && entries.length < MAX_SIGS_PER_FILE; i++) {
+        const line = lines[i];
+        const trimmed = line.trimStart();
+        // Skip preprocessor directives, comments, empty lines
+        if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*'))
+            continue;
+        // class / struct declaration (not a forward declaration ending in ;)
+        const classMatch = trimmed.match(/^(?:class|struct)\s+(\w+)\b/);
+        if (classMatch && !trimmed.endsWith(';')) {
+            const keyword = trimmed.startsWith('struct') ? 'struct' : 'class';
+            const name = classMatch[1];
+            const comment = lines[i - 1]?.trim().startsWith('//') ? lines[i - 1].trim().slice(2).trim() : undefined;
+            entries.push({ kind: 'class', name, signature: `${keyword} ${name}`, docstring: comment });
+            continue;
+        }
+        // Function / method: look for Name(params) followed by qualifiers then { or :
+        // This regex finds the last word before a ( that has content after closing )
+        const fnMatch = trimmed.match(/\b(\w+)\s*\(([^)]*)\)\s*(?:const\s*)?(?:noexcept[^{;]*)?\s*(?:override\s*)?(?:final\s*)?(?:->\s*[\w:*&<>, ]+\s*)?[{:]/);
+        if (fnMatch) {
+            const name = fnMatch[1];
+            if (!CPP_SKIP_NAMES.has(name) && /^[a-zA-Z_]/.test(name)) {
+                const params = compactParams(fnMatch[2]);
+                const comment = lines[i - 1]?.trim().startsWith('//') ? lines[i - 1].trim().slice(2).trim() : undefined;
+                const kind = line.startsWith('  ') || line.startsWith('\t') ? 'method' : 'function';
+                entries.push({ kind, name, signature: `${name}(${params})`, docstring: comment });
+            }
+        }
+    }
+    return entries;
+}
+// ============================================================================
+// SWIFT EXTRACTOR
+// ============================================================================
+function extractSwift(content) {
+    const entries = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length && entries.length < MAX_SIGS_PER_FILE; i++) {
+        const line = lines[i];
+        const trimmed = line.trimStart();
+        // Collect /// doc comment above the declaration
+        let docstring;
+        if (i > 0) {
+            let j = i - 1;
+            while (j >= 0 && lines[j].trim() === '')
+                j--;
+            if (j >= 0 && lines[j].trim().startsWith('///')) {
+                docstring = lines[j].trim().slice(3).trim() || undefined;
+            }
+        }
+        // class / struct / actor / enum declaration
+        const typeMatch = trimmed.match(/^(?:public\s+|open\s+|internal\s+|private\s+|fileprivate\s+)*(?:final\s+)?(class|struct|actor|enum)\s+(\w+)/);
+        if (typeMatch) {
+            const keyword = typeMatch[1];
+            const name = typeMatch[2];
+            const kind = keyword === 'enum' ? 'type' : 'class';
+            entries.push({ kind, name, signature: `${keyword} ${name}`, docstring });
+            continue;
+        }
+        // protocol declaration
+        const protocolMatch = trimmed.match(/^(?:public\s+|internal\s+|private\s+|fileprivate\s+)*protocol\s+(\w+)/);
+        if (protocolMatch) {
+            entries.push({ kind: 'interface', name: protocolMatch[1], signature: `protocol ${protocolMatch[1]}`, docstring });
+            continue;
+        }
+        // func declaration (free or method)
+        const funcMatch = trimmed.match(/^(?:public\s+|open\s+|internal\s+|private\s+|fileprivate\s+|static\s+|class\s+|override\s+|mutating\s+)*(?:async\s+)?func\s+(\w+)\s*(?:<[^>]*>)?\s*\(([^)]*)\)(?:\s*(?:async|throws|rethrows))?\s*(?:->\s*([^{]+))?/);
+        if (funcMatch) {
+            const name = funcMatch[1];
+            const params = compactParams(funcMatch[2]);
+            const ret = funcMatch[3]?.trim().replace(/\s+/g, ' ') ?? '';
+            const isMethod = line.startsWith('  ') || line.startsWith('\t');
+            const sig = `func ${name}(${params})${ret ? ' -> ' + ret : ''}`;
+            entries.push({ kind: isMethod ? 'method' : 'function', name, signature: isMethod ? '  ' + sig : sig, docstring });
+            continue;
+        }
+        // init declaration
+        const initMatch = trimmed.match(/^(?:public\s+|internal\s+|private\s+|fileprivate\s+|convenience\s+|required\s+)*init\s*(?:\?|!)?(?:<[^>]*>)?\s*\(/);
+        if (initMatch) {
+            const sig = 'init(' + (trimmed.split('(')[1]?.split(')')[0] ?? '') + ')';
+            entries.push({ kind: 'method', name: 'init', signature: '  ' + sig.slice(0, 80), docstring });
+            continue;
+        }
+    }
+    return entries;
+}
+// ============================================================================
+// JAVA EXTRACTOR
+// ============================================================================
+/** Java modifier keywords that can precede a type or method declaration. */
+const JAVA_MODIFIER_PREFIX = '(?:public\\s+|private\\s+|protected\\s+|static\\s+|final\\s+|abstract\\s+|synchronized\\s+|default\\s+|native\\s+|sealed\\s+|non-sealed\\s+)*';
+/** Keywords that look like method names but are not. */
+const JAVA_SKIP_NAMES = new Set([
+    'if', 'for', 'while', 'switch', 'return', 'do', 'else', 'try', 'catch', 'finally',
+    'new', 'throw', 'class', 'interface', 'enum', 'record',
+]);
+function extractJava(content) {
+    const entries = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length && entries.length < MAX_SIGS_PER_FILE; i++) {
+        const line = lines[i];
+        const trimmed = line.trimStart();
+        // Skip lines that are clearly not declarations
+        if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*'))
+            continue;
+        if (trimmed.startsWith('@'))
+            continue; // annotations
+        // Collect Javadoc comment above the declaration (walk back through
+        // annotations and blank lines to find the closing `*/`).
+        const docstring = extractJavadoc(lines, i);
+        // class / interface / enum / record / @interface
+        const typeMatch = trimmed.match(new RegExp('^' + JAVA_MODIFIER_PREFIX + '(class|interface|enum|record|@interface)\\s+(\\w+)'));
+        if (typeMatch) {
+            const keyword = typeMatch[1];
+            const name = typeMatch[2];
+            const kind = keyword === 'interface' || keyword === '@interface' ? 'interface' : 'class';
+            const sig = trimmed.replace(/\s*\{.*$/, '').slice(0, 120);
+            entries.push({ kind, name, signature: sig, docstring });
+            continue;
+        }
+        // Method: `[modifiers] [<generics>] ReturnType name(params)` — return type
+        // may include generics, arrays, and dotted package-qualified names.
+        const methodMatch = trimmed.match(new RegExp('^' + JAVA_MODIFIER_PREFIX + '(?:<[^>]+>\\s+)?([\\w<>\\[\\], ?.]+?)\\s+(\\w+)\\s*\\(([^)]*)\\)'));
+        if (methodMatch) {
+            const returnType = methodMatch[1].trim();
+            const name = methodMatch[2];
+            if (JAVA_SKIP_NAMES.has(name))
+                continue;
+            // Skip obvious field declarations like `private final Foo bar = ...` —
+            // fields don't have `(` so the regex wouldn't match. This path is
+            // method-only by construction.
+            const params = compactParams(methodMatch[3]);
+            const isMethod = line.startsWith('  ') || line.startsWith('\t');
+            const sig = `${returnType} ${name}(${params})`;
+            entries.push({
+                kind: isMethod ? 'method' : 'function',
+                name,
+                signature: (isMethod ? '  ' : '') + sig,
+                docstring,
+            });
+            continue;
+        }
+    }
+    return entries;
+}
+/**
+ * Walk backwards from declLineIdx, skipping annotations and blank lines, to
+ * find a preceding Javadoc block (`/** … *\/`). Returns the first meaningful
+ * line of the block, or undefined.
+ */
+function extractJavadoc(lines, declLineIdx) {
+    let endIdx = declLineIdx - 1;
+    // Skip annotation lines and blanks
+    while (endIdx >= 0) {
+        const t = lines[endIdx].trim();
+        if (t === '' || t.startsWith('@')) {
+            endIdx--;
+            continue;
+        }
+        break;
+    }
+    if (endIdx < 0 || !lines[endIdx].trim().endsWith('*/'))
+        return undefined;
+    let startIdx = endIdx;
+    while (startIdx >= 0 && !lines[startIdx].trim().startsWith('/**'))
+        startIdx--;
+    if (startIdx < 0)
+        return undefined;
+    for (let j = startIdx + 1; j <= endIdx; j++) {
+        const t = lines[j].replace(/^\s*\*\s?/, '').trim();
+        if (t && !t.startsWith('@') && !t.startsWith('/'))
+            return t;
+    }
+    return undefined;
+}
+// ============================================================================
+// GENERIC FALLBACK EXTRACTOR
+// ============================================================================
+function extractGeneric(content) {
+    const entries = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length && entries.length < MAX_SIGS_PER_FILE; i++) {
+        const line = lines[i];
+        // Generic: lines that look like declarations (function/class/def keywords)
+        const match = line.match(/^\s*(?:public|private|protected|export|static|async)?\s*(?:function|class|def|func|fn|sub|procedure)\s+(\w+)/);
+        if (match) {
+            entries.push({ kind: 'function', name: match[1], signature: line.trim().slice(0, 120) });
+        }
+    }
+    return entries;
+}
+// ============================================================================
+// MAIN EXTRACTOR
+// ============================================================================
+export function extractSignatures(filePath, content) {
+    const language = detectLanguage(filePath);
+    let entries;
+    switch (language) {
+        case 'Python':
+            entries = extractPython(content);
+            break;
+        case 'TypeScript':
+        case 'JavaScript':
+            entries = extractTypeScript(content);
+            break;
+        case 'Go':
+            entries = extractGo(content);
+            break;
+        case 'Rust':
+            entries = extractRust(content);
+            break;
+        case 'Ruby':
+            entries = extractRuby(content);
+            break;
+        case 'C++':
+            entries = extractCpp(content);
+            break;
+        case 'Swift':
+            entries = extractSwift(content);
+            break;
+        case 'Java':
+            entries = extractJava(content);
+            break;
+        default:
+            entries = extractGeneric(content);
+            break;
+    }
+    return { path: filePath, language, entries };
+}
+// ============================================================================
+// FORMATTER
+// ============================================================================
+/**
+ * Format signature maps as compact text blocks for Stage 1 LLM prompt.
+ * Returns an array of chunk strings — 1 element if total fits within maxChars,
+ * N elements if chunking is needed. Files are never split across chunks.
+ */
+export function formatSignatureMaps(maps, maxChars = STAGE1_MAX_CHARS) {
+    // Filter out files with no signatures
+    const meaningful = maps.filter(m => m.entries.length > 0);
+    const chunks = [];
+    let current = '';
+    for (const map of meaningful) {
+        const block = formatSingleFile(map);
+        // If adding this block would exceed the limit, flush current chunk
+        if (current.length > 0 && current.length + block.length > maxChars) {
+            chunks.push(current.trim());
+            current = '';
+        }
+        current += block + '\n';
+    }
+    if (current.trim()) {
+        chunks.push(current.trim());
+    }
+    return chunks.length > 0 ? chunks : ['(no signatures extracted)'];
+}
+function formatSingleFile(map) {
+    const lines = [`=== ${map.path} [${map.language}] ===`];
+    for (const entry of map.entries) {
+        if (entry.decorator) {
+            lines.push(entry.decorator);
+        }
+        lines.push(entry.signature);
+        if (entry.docstring) {
+            const indent = entry.signature.startsWith('  ') ? '    ' : '  ';
+            lines.push(`${indent}"""${entry.docstring}"""`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=signature-extractor.js.map