code-finder 0.1.0__py3-none-any.whl

claude_context/enhanced_ast_chunker.py

@@ -0,0 +1,1129 @@
+"""
+Enhanced AST-based Code Chunker with Rich Metadata Extraction
+
+This module ports key features from supermemoryai/code-chunk to provide
+richer semantic metadata for code chunks, improving retrieval and
+documentation generation quality.
+
+Key enhancements over basic ast_chunker:
+- Full scope chain tracking (class > method > nested function)
+- Complete signature extraction with parameters and types
+- Import dependency tracking per chunk
+- Contextualized text generation for LLM consumption
+
+Supports: Python, JavaScript, TypeScript, Go
+"""
+
+import re
+import logging
+from typing import List, Dict, Any, Optional, Tuple, Set
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Try to import tree-sitter dependencies
+try:
+    import tree_sitter_python as tspython
+    import tree_sitter_javascript as tsjavascript
+    import tree_sitter_typescript as tstypescript
+    import tree_sitter_go as tsgo
+    from tree_sitter import Language, Parser, Node
+    HAS_TREE_SITTER = True
+    logger.info("Tree-sitter available for enhanced AST parsing")
+except ImportError as e:
+    HAS_TREE_SITTER = False
+    Node = Any  # Type hint fallback
+    logger.warning(f"Tree-sitter not available: {e}")
+
+
+@dataclass
+class ImportInfo:
+    """Information about an import statement"""
+    module: str  # The module being imported from
+    name: str    # The specific name imported (or module name for simple imports)
+    alias: Optional[str] = None  # Alias if 'as X' is used
+    is_from_import: bool = False  # True for 'from X import Y'
+    line: int = 0
+
+
+@dataclass
+class ParameterInfo:
+    """Information about a function parameter"""
+    name: str
+    type_annotation: Optional[str] = None
+    default_value: Optional[str] = None
+    is_variadic: bool = False  # *args
+    is_keyword: bool = False   # **kwargs
+
+
+@dataclass
+class EnhancedCodeChunk:
+    """
+    Rich code chunk with full metadata for improved retrieval and understanding.
+
+    This extends the basic CodeChunk with:
+    - Full scope chain (hierarchical context)
+    - Complete function signatures
+    - Import dependency tracking
+    - Contextualized text for LLM consumption
+    """
+    # Core content
+    text: str  # Raw code text
+    contextualized_text: str  # Code with context prepended
+
+    # Location
+    line_range: Tuple[int, int]  # (start, end) 0-indexed
+    byte_range: Tuple[int, int]  # (start, end)
+
+    # Entity identification
+    chunk_type: str  # function, class, method, import_block, module, type
+    name: Optional[str] = None
+    signature: Optional[str] = None
+    docstring: Optional[str] = None
+
+    # Parameters (for functions/methods)
+    parameters: List[ParameterInfo] = field(default_factory=list)
+    return_type: Optional[str] = None
+
+    # Hierarchical context
+    scope: List[str] = field(default_factory=list)  # Full scope chain
+
+    # Dependencies
+    imports: List[ImportInfo] = field(default_factory=list)  # Used imports
+
+    # Metadata
+    language: str = ""
+    filepath: str = ""
+    is_partial: bool = False  # True if chunk was split due to size
+
+    # Size tracking
+    size_chars: int = field(default=0, init=False)
+
+    def __post_init__(self):
+        if self.size_chars == 0:
+            self.size_chars = len(re.sub(r'\s', '', self.text))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for storage/serialization"""
+        return {
+            "text": self.text,
+            "contextualized_text": self.contextualized_text,
+            "line_range": self.line_range,
+            "byte_range": self.byte_range,
+            "chunk_type": self.chunk_type,
+            "name": self.name,
+            "signature": self.signature,
+            "docstring": self.docstring,
+            "parameters": [
+                {
+                    "name": p.name,
+                    "type": p.type_annotation,
+                    "default": p.default_value,
+                    "is_variadic": p.is_variadic,
+                    "is_keyword": p.is_keyword
+                }
+                for p in self.parameters
+            ],
+            "return_type": self.return_type,
+            "scope": self.scope,
+            "imports": [
+                {
+                    "module": i.module,
+                    "name": i.name,
+                    "alias": i.alias
+                }
+                for i in self.imports
+            ],
+            "language": self.language,
+            "filepath": self.filepath,
+            "is_partial": self.is_partial,
+            "size_chars": self.size_chars
+        }
+
+
+class EnhancedASTChunker:
+    """
+    Enhanced AST chunker with rich metadata extraction.
+
+    Ports key features from supermemoryai/code-chunk:
+    - Scope chain tracking
+    - Signature extraction
+    - Import dependency linking
+    - Contextualized text generation
+    """
+
+    # Node types that represent scope boundaries
+    SCOPE_NODES = {
+        'python': ['class_definition', 'function_definition', 'async_function_definition'],
+        'javascript': ['class_declaration', 'function_declaration', 'arrow_function', 'method_definition'],
+        'typescript': ['class_declaration', 'function_declaration', 'arrow_function', 'method_definition',
+                      'interface_declaration'],
+        'go': ['function_declaration', 'method_declaration', 'type_declaration']
+    }
+
+    # Node types that should become chunks
+    CHUNK_NODES = {
+        'python': [
+            'function_definition', 'async_function_definition', 'class_definition',
+            'decorated_definition'
+        ],
+        'javascript': [
+            'function_declaration', 'class_declaration', 'method_definition',
+            'arrow_function', 'export_statement'
+        ],
+        'typescript': [
+            'function_declaration', 'class_declaration', 'method_definition',
+            'arrow_function', 'interface_declaration', 'type_alias_declaration',
+            'export_statement'
+        ],
+        'go': [
+            'function_declaration', 'method_declaration', 'type_declaration'
+        ]
+    }
+
+    def __init__(
+        self,
+        max_chunk_size: int = 1500,
+        context_mode: str = "full",
+        merge_small_chunks: bool = False,
+        min_chunk_size: int = 100
+    ):
+        """
+        Initialize the enhanced AST chunker.
+
+        Args:
+            max_chunk_size: Maximum chunk size in characters
+            context_mode: Context detail level ('none', 'minimal', 'full')
+            merge_small_chunks: Whether to merge adjacent small chunks
+            min_chunk_size: Minimum chunk size for merging
+        """
+        self.max_chunk_size = max_chunk_size
+        self.context_mode = context_mode
+        self.merge_small_chunks = merge_small_chunks
+        self.min_chunk_size = min_chunk_size
+
+        self.parsers: Dict[str, Parser] = {}
+        self.supported_languages = ['python', 'javascript', 'typescript', 'go']
+
+        if HAS_TREE_SITTER:
+            self._initialize_parsers()
+
+    def _initialize_parsers(self) -> None:
+        """Initialize tree-sitter parsers for supported languages"""
+        parser_configs = [
+            ('python', tspython.language),
+            ('javascript', tsjavascript.language),
+            ('typescript', lambda: tstypescript.language_tsx()),
+            ('go', tsgo.language)
+        ]
+
+        for lang, lang_fn in parser_configs:
+            try:
+                language = Language(lang_fn())
+                self.parsers[lang] = Parser(language)
+                logger.debug(f"{lang} parser initialized")
+            except Exception as e:
+                logger.warning(f"Failed to initialize {lang} parser: {e}")
+
+    def chunk_file(
+        self,
+        file_path: Path,
+        content: Optional[str] = None
+    ) -> List[EnhancedCodeChunk]:
+        """
+        Chunk a file into semantically complete units with rich metadata.
+
+        Args:
+            file_path: Path to the source file
+            content: Optional pre-loaded content
+
+        Returns:
+            List of EnhancedCodeChunk objects
+        """
+        file_path = Path(file_path)
+
+        if content is None:
+            try:
+                content = file_path.read_text(encoding='utf-8', errors='ignore')
+            except Exception as e:
+                logger.error(f"Failed to read {file_path}: {e}")
+                return []
+
+        language = self._detect_language(file_path)
+
+        if not HAS_TREE_SITTER or language not in self.parsers:
+            logger.debug(f"Using fallback chunking for {file_path}")
+            return self._chunk_fallback(content, language, str(file_path))
+
+        try:
+            return self._chunk_with_ast(content, language, str(file_path))
+        except Exception as e:
+            logger.warning(f"AST parsing failed for {file_path}, using fallback: {e}")
+            return self._chunk_fallback(content, language, str(file_path))
+
+    def _detect_language(self, file_path: Path) -> str:
+        """Detect programming language from file extension"""
+        ext_map = {
+            '.py': 'python',
+            '.js': 'javascript',
+            '.jsx': 'javascript',
+            '.ts': 'typescript',
+            '.tsx': 'typescript',
+            '.go': 'go'
+        }
+        return ext_map.get(file_path.suffix.lower(), 'unknown')
+
+    def _bs(self, node) -> str:
+        """Slice source bytes by node byte offsets and decode to str.
+
+        Tree-sitter nodes report byte offsets, not character offsets.
+        Using ``source_str[start_byte:end_byte]`` gives wrong results
+        when the file contains multi-byte UTF-8 characters (emojis, etc.).
+        """
+        return self._source_bytes[node.start_byte:node.end_byte].decode('utf-8', errors='replace')
+
+    def _chunk_with_ast(
+        self,
+        content: str,
+        language: str,
+        filepath: str
+    ) -> List[EnhancedCodeChunk]:
+        """
+        Chunk code using tree-sitter AST parsing with rich metadata extraction.
+        """
+        parser = self.parsers[language]
+        self._source_bytes = bytes(content, 'utf-8')
+        tree = parser.parse(self._source_bytes)
+
+        if not tree.root_node:
+            return self._chunk_fallback(content, language, filepath)
+
+        # First pass: parse all imports
+        all_imports = self._parse_all_imports(tree.root_node, content, language)
+
+        # Second pass: extract chunks with scope tracking
+        chunks = self._extract_chunks(
+            tree.root_node,
+            content,
+            language,
+            filepath,
+            scope=[],
+            all_imports=all_imports
+        )
+
+        # Generate contextualized text for each chunk
+        for chunk in chunks:
+            chunk.contextualized_text = self._build_contextualized_text(chunk)
+
+        return chunks
+
+    def _parse_all_imports(
+        self,
+        root: Node,
+        source: str,
+        language: str
+    ) -> Dict[str, ImportInfo]:
+        """
+        Parse all imports in the file and return a mapping of names to import info.
+        """
+        imports: Dict[str, ImportInfo] = {}
+
+        if language == 'python':
+            self._parse_python_imports(root, source, imports)
+        elif language in ['javascript', 'typescript']:
+            self._parse_js_imports(root, source, imports)
+        elif language == 'go':
+            self._parse_go_imports(root, source, imports)
+
+        return imports
+
+    def _parse_python_imports(
+        self,
+        node: Node,
+        source: str,
+        imports: Dict[str, ImportInfo]
+    ) -> None:
+        """Parse Python import statements"""
+        if node.type == 'import_statement':
+            # import X, Y, Z
+            for child in node.children:
+                if child.type == 'dotted_name':
+                    name = self._bs(child)
+                    imports[name] = ImportInfo(
+                        module=name,
+                        name=name,
+                        line=child.start_point[0]
+                    )
+                elif child.type == 'aliased_import':
+                    # import X as Y
+                    dotted = None
+                    alias = None
+                    for c in child.children:
+                        if c.type == 'dotted_name':
+                            dotted = self._bs(c)
+                        elif c.type == 'identifier':
+                            alias = self._bs(c)
+                    if dotted:
+                        imports[alias or dotted] = ImportInfo(
+                            module=dotted,
+                            name=dotted,
+                            alias=alias,
+                            line=child.start_point[0]
+                        )
+
+        elif node.type == 'import_from_statement':
+            # from X import Y, Z
+            module = None
+            for child in node.children:
+                if child.type == 'dotted_name':
+                    module = self._bs(child)
+                elif child.type == 'identifier' and module:
+                    name = self._bs(child)
+                    imports[name] = ImportInfo(
+                        module=module,
+                        name=name,
+                        is_from_import=True,
+                        line=child.start_point[0]
+                    )
+                elif child.type == 'aliased_import':
+                    original = None
+                    alias = None
+                    for c in child.children:
+                        if c.type == 'identifier':
+                            if original is None:
+                                original = self._bs(c)
+                            else:
+                                alias = self._bs(c)
+                    if original and module:
+                        imports[alias or original] = ImportInfo(
+                            module=module,
+                            name=original,
+                            alias=alias,
+                            is_from_import=True,
+                            line=child.start_point[0]
+                        )
+
+        # Recurse
+        for child in node.children:
+            self._parse_python_imports(child, source, imports)
+
+    def _parse_js_imports(
+        self,
+        node: Node,
+        source: str,
+        imports: Dict[str, ImportInfo]
+    ) -> None:
+        """Parse JavaScript/TypeScript import statements"""
+        if node.type == 'import_statement':
+            module = None
+            # Find the module string
+            for child in node.children:
+                if child.type == 'string':
+                    module = self._bs(child).strip("'\"")
+
+            if module:
+                # Find imported names
+                for child in node.children:
+                    if child.type == 'import_clause':
+                        self._extract_js_import_names(child, source, module, imports, node.start_point[0])
+
+        # Recurse
+        for child in node.children:
+            self._parse_js_imports(child, source, imports)
+
+    def _extract_js_import_names(
+        self,
+        node: Node,
+        source: str,
+        module: str,
+        imports: Dict[str, ImportInfo],
+        line: int
+    ) -> None:
+        """Extract names from JS import clause"""
+        for child in node.children:
+            if child.type == 'identifier':
+                # Default import
+                name = self._bs(child)
+                imports[name] = ImportInfo(module=module, name=name, line=line)
+            elif child.type == 'named_imports':
+                # { X, Y as Z }
+                for spec in child.children:
+                    if spec.type == 'import_specifier':
+                        original = None
+                        alias = None
+                        for c in spec.children:
+                            if c.type == 'identifier':
+                                if original is None:
+                                    original = self._bs(c)
+                                else:
+                                    alias = self._bs(c)
+                        if original:
+                            imports[alias or original] = ImportInfo(
+                                module=module,
+                                name=original,
+                                alias=alias,
+                                is_from_import=True,
+                                line=line
+                            )
+            elif child.type == 'namespace_import':
+                # import * as X
+                for c in child.children:
+                    if c.type == 'identifier':
+                        name = self._bs(c)
+                        imports[name] = ImportInfo(module=module, name='*', alias=name, line=line)
+
+    def _parse_go_imports(
+        self,
+        node: Node,
+        source: str,
+        imports: Dict[str, ImportInfo]
+    ) -> None:
+        """Parse Go import statements"""
+        if node.type == 'import_declaration':
+            for child in node.children:
+                if child.type == 'import_spec':
+                    pkg = None
+                    alias = None
+                    for c in child.children:
+                        if c.type == 'interpreted_string_literal':
+                            pkg = self._bs(c).strip('"')
+                        elif c.type == 'package_identifier' or c.type == 'identifier':
+                            alias = self._bs(c)
+                    if pkg:
+                        # Use last part of package path as name
+                        name = pkg.split('/')[-1]
+                        imports[alias or name] = ImportInfo(
+                            module=pkg,
+                            name=name,
+                            alias=alias,
+                            line=child.start_point[0]
+                        )
+                elif child.type == 'import_spec_list':
+                    self._parse_go_imports(child, source, imports)
+
+        for child in node.children:
+            self._parse_go_imports(child, source, imports)
+
+    def _extract_chunks(
+        self,
+        node: Node,
+        source: str,
+        language: str,
+        filepath: str,
+        scope: List[str],
+        all_imports: Dict[str, ImportInfo]
+    ) -> List[EnhancedCodeChunk]:
+        """
+        Recursively extract chunks from AST with scope tracking.
+        """
+        chunks = []
+        chunk_node_types = self.CHUNK_NODES.get(language, [])
+        scope_node_types = self.SCOPE_NODES.get(language, [])
+
+        # Check if this node should be a chunk
+        if node.type in chunk_node_types:
+            chunk = self._create_chunk(node, source, language, filepath, scope, all_imports)
+            if chunk:
+                chunks.append(chunk)
+
+                # Update scope for children if this is a scope boundary
+                if node.type in scope_node_types and chunk.name:
+                    scope = scope + [chunk.name]
+
+        # Process children
+        for child in node.children:
+            child_chunks = self._extract_chunks(
+                child, source, language, filepath, scope, all_imports
+            )
+            chunks.extend(child_chunks)
+
+        return chunks
+
+    def _create_chunk(
+        self,
+        node: Node,
+        source: str,
+        language: str,
+        filepath: str,
+        scope: List[str],
+        all_imports: Dict[str, ImportInfo]
+    ) -> Optional[EnhancedCodeChunk]:
+        """Create an EnhancedCodeChunk from an AST node"""
+        text = self._bs(node)
+        if not text.strip():
+            return None
+
+        # Determine chunk type and extract name
+        chunk_type, name = self._analyze_node(node, source, language)
+
+        # Extract signature for functions/methods
+        signature = None
+        parameters = []
+        return_type = None
+        if chunk_type in ['function', 'method']:
+            sig_info = self._extract_signature(node, source, language)
+            signature = sig_info.get('signature')
+            parameters = sig_info.get('parameters', [])
+            return_type = sig_info.get('return_type')
+
+        # Extract docstring
+        docstring = self._extract_docstring(node, source, language)
+
+        # Find which imports are used in this chunk
+        used_imports = self._find_used_imports(text, all_imports)
+
+        return EnhancedCodeChunk(
+            text=text,
+            contextualized_text="",  # Will be filled later
+            line_range=(node.start_point[0], node.end_point[0]),
+            byte_range=(node.start_byte, node.end_byte),
+            chunk_type=chunk_type,
+            name=name,
+            signature=signature,
+            docstring=docstring,
+            parameters=parameters,
+            return_type=return_type,
+            scope=scope.copy(),
+            imports=used_imports,
+            language=language,
+            filepath=filepath
+        )
+
+    def _analyze_node(
+        self,
+        node: Node,
+        source: str,
+        language: str
+    ) -> Tuple[str, Optional[str]]:
+        """Determine chunk type and extract name from node"""
+        node_type = node.type
+        name = None
+
+        # Python
+        if language == 'python':
+            if node_type in ['function_definition', 'async_function_definition']:
+                name = self._get_identifier(node, source)
+                return ('function', name)
+            elif node_type == 'class_definition':
+                name = self._get_identifier(node, source)
+                return ('class', name)
+            elif node_type == 'decorated_definition':
+                # Get the actual definition inside
+                for child in node.children:
+                    if child.type in ['function_definition', 'async_function_definition']:
+                        return self._analyze_node(child, source, language)
+                    elif child.type == 'class_definition':
+                        return self._analyze_node(child, source, language)
+
+        # JavaScript/TypeScript
+        elif language in ['javascript', 'typescript']:
+            if node_type == 'function_declaration':
+                name = self._get_identifier(node, source)
+                return ('function', name)
+            elif node_type == 'class_declaration':
+                name = self._get_identifier(node, source)
+                return ('class', name)
+            elif node_type == 'method_definition':
+                name = self._get_property_identifier(node, source)
+                return ('method', name)
+            elif node_type == 'arrow_function':
+                return ('function', 'arrow_function')
+            elif node_type == 'interface_declaration':
+                name = self._get_identifier(node, source)
+                return ('interface', name)
+            elif node_type == 'type_alias_declaration':
+                name = self._get_identifier(node, source)
+                return ('type', name)
+
+        # Go
+        elif language == 'go':
+            if node_type == 'function_declaration':
+                name = self._get_identifier(node, source)
+                return ('function', name)
+            elif node_type == 'method_declaration':
+                name = self._get_field_identifier(node, source)
+                return ('method', name)
+            elif node_type == 'type_declaration':
+                name = self._get_type_identifier(node, source)
+                return ('type', name)
+
+        return ('block', None)
+
+    def _get_identifier(self, node: Node, source: str) -> Optional[str]:
+        """Get identifier name from node's children"""
+        for child in node.children:
+            if child.type == 'identifier':
+                return self._bs(child)
+        return None
+
+    def _get_property_identifier(self, node: Node, source: str) -> Optional[str]:
+        """Get property identifier for JS methods"""
+        for child in node.children:
+            if child.type == 'property_identifier':
+                return self._bs(child)
+        return None
+
+    def _get_field_identifier(self, node: Node, source: str) -> Optional[str]:
+        """Get field identifier for Go methods"""
+        for child in node.children:
+            if child.type == 'field_identifier':
+                return self._bs(child)
+        return None
+
+    def _get_type_identifier(self, node: Node, source: str) -> Optional[str]:
+        """Get type identifier for Go type declarations"""
+        for child in node.children:
+            if child.type == 'type_spec':
+                for c in child.children:
+                    if c.type == 'type_identifier':
+                        return self._bs(c)
+        return None
+
+    def _extract_signature(
+        self,
+        node: Node,
+        source: str,
+        language: str
+    ) -> Dict[str, Any]:
+        """Extract complete function signature"""
+        result = {'signature': None, 'parameters': [], 'return_type': None}
+
+        if language == 'python':
+            result = self._extract_python_signature(node, source)
+        elif language in ['javascript', 'typescript']:
+            result = self._extract_js_signature(node, source)
+        elif language == 'go':
+            result = self._extract_go_signature(node, source)
+
+        return result
+
+    def _extract_python_signature(self, node: Node, source: str) -> Dict[str, Any]:
+        """Extract Python function signature"""
+        name = self._get_identifier(node, source)
+        parameters = []
+        return_type = None
+
+        for child in node.children:
+            if child.type == 'parameters':
+                parameters = self._parse_python_parameters(child, source)
+            elif child.type == 'type':
+                return_type = self._bs(child)
+
+        # Build signature string
+        param_str = ', '.join(self._format_parameter(p) for p in parameters)
+        sig = f"def {name}({param_str})"
+        if return_type:
+            sig += f" -> {return_type}"
+
+        return {
+            'signature': sig,
+            'parameters': parameters,
+            'return_type': return_type
+        }
+
+    def _parse_python_parameters(self, params_node: Node, source: str) -> List[ParameterInfo]:
+        """Parse Python function parameters"""
+        parameters = []
+
+        for child in params_node.children:
+            if child.type == 'identifier':
+                parameters.append(ParameterInfo(
+                    name=self._bs(child)
+                ))
+            elif child.type == 'typed_parameter':
+                name = None
+                type_ann = None
+                for c in child.children:
+                    if c.type == 'identifier':
+                        name = self._bs(c)
+                    elif c.type == 'type':
+                        type_ann = self._bs(c)
+                if name:
+                    parameters.append(ParameterInfo(name=name, type_annotation=type_ann))
+            elif child.type == 'default_parameter':
+                name = None
+                type_ann = None
+                default = None
+                for c in child.children:
+                    if c.type == 'identifier':
+                        name = self._bs(c)
+                    elif c.type == 'type':
+                        type_ann = self._bs(c)
+                    elif c.type not in ['identifier', 'type', '=', ':']:
+                        default = self._bs(c)
+                if name:
+                    parameters.append(ParameterInfo(
+                        name=name,
+                        type_annotation=type_ann,
+                        default_value=default
+                    ))
+            elif child.type == 'typed_default_parameter':
+                name = None
+                type_ann = None
+                default = None
+                for c in child.children:
+                    if c.type == 'identifier':
+                        name = self._bs(c)
+                    elif c.type == 'type':
+                        type_ann = self._bs(c)
+                    elif c.type not in ['identifier', 'type', '=', ':']:
+                        default = self._bs(c)
+                if name:
+                    parameters.append(ParameterInfo(
+                        name=name,
+                        type_annotation=type_ann,
+                        default_value=default
+                    ))
+            elif child.type == 'list_splat_pattern':
+                name = self._get_identifier(child, source)
+                if name:
+                    parameters.append(ParameterInfo(name=name, is_variadic=True))
+            elif child.type == 'dictionary_splat_pattern':
+                name = self._get_identifier(child, source)
+                if name:
+                    parameters.append(ParameterInfo(name=name, is_keyword=True))
+
+        return parameters
+
+    def _extract_js_signature(self, node: Node, source: str) -> Dict[str, Any]:
+        """Extract JavaScript/TypeScript function signature"""
+        name = self._get_identifier(node, source) or self._get_property_identifier(node, source)
+        parameters = []
+        return_type = None
+
+        for child in node.children:
+            if child.type == 'formal_parameters':
+                parameters = self._parse_js_parameters(child, source)
+            elif child.type == 'type_annotation':
+                return_type = self._bs(child).lstrip(': ')
+
+        # Build signature
+        param_str = ', '.join(self._format_parameter(p) for p in parameters)
+        sig = f"function {name or 'anonymous'}({param_str})"
+        if return_type:
+            sig += f": {return_type}"
+
+        return {
+            'signature': sig,
+            'parameters': parameters,
+            'return_type': return_type
+        }
+
+    def _parse_js_parameters(self, params_node: Node, source: str) -> List[ParameterInfo]:
+        """Parse JavaScript/TypeScript function parameters"""
+        parameters = []
+
+        for child in params_node.children:
+            if child.type == 'identifier':
+                parameters.append(ParameterInfo(
+                    name=self._bs(child)
+                ))
+            elif child.type == 'required_parameter' or child.type == 'optional_parameter':
+                name = None
+                type_ann = None
+                for c in child.children:
+                    if c.type == 'identifier':
+                        name = self._bs(c)
+                    elif c.type == 'type_annotation':
+                        type_ann = self._bs(c).lstrip(': ')
+                if name:
+                    parameters.append(ParameterInfo(name=name, type_annotation=type_ann))
+            elif child.type == 'rest_pattern':
+                name = self._get_identifier(child, source)
+                if name:
+                    parameters.append(ParameterInfo(name=name, is_variadic=True))
+
+        return parameters
+
+    def _extract_go_signature(self, node: Node, source: str) -> Dict[str, Any]:
+        """Extract Go function signature"""
+        name = self._get_identifier(node, source) or self._get_field_identifier(node, source)
+        parameters = []
+        return_type = None
+
+        for child in node.children:
+            if child.type == 'parameter_list':
+                parameters = self._parse_go_parameters(child, source)
+            elif child.type == 'result':
+                return_type = self._bs(child)
+
+        # Build signature
+        param_str = ', '.join(self._format_parameter(p) for p in parameters)
+        sig = f"func {name or 'anonymous'}({param_str})"
+        if return_type:
+            sig += f" {return_type}"
+
+        return {
+            'signature': sig,
+            'parameters': parameters,
+            'return_type': return_type
+        }
+
+    def _parse_go_parameters(self, params_node: Node, source: str) -> List[ParameterInfo]:
+        """Parse Go function parameters"""
+        parameters = []
+
+        for child in params_node.children:
+            if child.type == 'parameter_declaration':
+                names = []
+                type_ann = None
+                for c in child.children:
+                    if c.type == 'identifier':
+                        names.append(self._bs(c))
+                    elif c.type in ['type_identifier', 'pointer_type', 'slice_type',
+                                   'array_type', 'map_type', 'interface_type']:
+                        type_ann = self._bs(c)
+                for name in names:
+                    parameters.append(ParameterInfo(name=name, type_annotation=type_ann))
+
+        return parameters
+
+    def _format_parameter(self, param: ParameterInfo) -> str:
+        """Format a parameter for signature display"""
+        prefix = ''
+        if param.is_variadic:
+            prefix = '*'
+        elif param.is_keyword:
+            prefix = '**'
+
+        result = f"{prefix}{param.name}"
+        if param.type_annotation:
+            result += f": {param.type_annotation}"
+        if param.default_value:
+            result += f" = {param.default_value}"
+        return result
+
+    def _extract_docstring(
+        self,
+        node: Node,
+        source: str,
+        language: str
+    ) -> Optional[str]:
+        """Extract docstring from a function/class node"""
+        if language == 'python':
+            # Look for string as first statement in body
+            for child in node.children:
+                if child.type == 'block':
+                    for stmt in child.children:
+                        if stmt.type == 'expression_statement':
+                            for expr in stmt.children:
+                                if expr.type == 'string':
+                                    docstring = self._bs(expr)
+                                    # Clean up the docstring
+                                    return docstring.strip('"""\'\'\'').strip()
+                        elif stmt.type not in ['comment', 'pass_statement']:
+                            break  # Docstring must be first
+                    break
+        elif language in ['javascript', 'typescript']:
+            # Look for JSDoc comment before the node
+            # This would require looking at preceding siblings or comments
+            pass
+
+        return None
+
+    def _find_used_imports(
+        self,
+        chunk_text: str,
+        all_imports: Dict[str, ImportInfo]
+    ) -> List[ImportInfo]:
+        """Find which imports are used in a chunk"""
+        used = []
+        # Simple word boundary check for each import name
+        for name, import_info in all_imports.items():
+            # Use word boundary to avoid partial matches
+            if re.search(rf'\b{re.escape(name)}\b', chunk_text):
+                used.append(import_info)
+        return used
+
+    def _build_contextualized_text(self, chunk: EnhancedCodeChunk) -> str:
+        """
+        Build contextualized text with metadata prepended.
+
+        This format is optimized for LLM consumption and embedding.
+        """
+        if self.context_mode == 'none':
+            return chunk.text
+
+        lines = []
+
+        # File path
+        lines.append(f"# {chunk.filepath}")
+
+        if self.context_mode in ['minimal', 'full']:
+            # Scope chain
+            if chunk.scope:
+                scope_str = ' > '.join(chunk.scope)
+                lines.append(f"# Scope: {scope_str}")
+
+        if self.context_mode == 'full':
+            # Signature
+            if chunk.signature:
+                lines.append(f"# Signature: {chunk.signature}")
+
+            # Used imports
+            if chunk.imports:
+                import_names = [f"{i.name}" for i in chunk.imports[:5]]  # Limit to 5
+                if len(chunk.imports) > 5:
+                    import_names.append(f"... +{len(chunk.imports) - 5} more")
+                lines.append(f"# Uses: {', '.join(import_names)}")
+
+            # Docstring summary (first line)
+            if chunk.docstring:
+                first_line = chunk.docstring.split('\n')[0][:100]
+                lines.append(f"# Doc: {first_line}")
+
+        lines.append("")  # Blank line before code
+        lines.append(chunk.text)
+
+        return '\n'.join(lines)
+
+    def _chunk_fallback(
+        self,
+        content: str,
+        language: str,
+        filepath: str
+    ) -> List[EnhancedCodeChunk]:
+        """
+        Fallback line-based chunking when tree-sitter is unavailable.
+        """
+        lines = content.split('\n')
+        chunks = []
+        current_chunk_lines = []
+        current_start = 0
+
+        for i, line in enumerate(lines):
+            current_chunk_lines.append(line)
+
+            # Check if we should start a new chunk
+            should_split = (
+                len('\n'.join(current_chunk_lines)) > self.max_chunk_size or
+                self._is_chunk_boundary(line, language)
+            )
+
+            if should_split and current_chunk_lines:
+                text = '\n'.join(current_chunk_lines)
+                if text.strip():
+                    chunk = EnhancedCodeChunk(
+                        text=text,
+                        contextualized_text=f"# {filepath}\n\n{text}",
+                        line_range=(current_start, i),
+                        byte_range=(0, 0),  # Not calculated for fallback
+                        chunk_type='block',
+                        language=language,
+                        filepath=filepath
+                    )
+                    chunks.append(chunk)
+
+                current_chunk_lines = []
+                current_start = i + 1
+
+        # Handle remaining lines
+        if current_chunk_lines:
+            text = '\n'.join(current_chunk_lines)
+            if text.strip():
+                chunks.append(EnhancedCodeChunk(
+                    text=text,
+                    contextualized_text=f"# {filepath}\n\n{text}",
+                    line_range=(current_start, len(lines) - 1),
+                    byte_range=(0, 0),
+                    chunk_type='block',
+                    language=language,
+                    filepath=filepath
+                ))
+
+        return chunks
+
+    def _is_chunk_boundary(self, line: str, language: str) -> bool:
+        """Detect potential chunk boundaries for fallback mode"""
+        line = line.strip()
+
+        if language == 'python':
+            return line.startswith(('def ', 'class ', 'async def ', '@'))
+        elif language in ['javascript', 'typescript']:
+            return (line.startswith(('function ', 'class ', 'export ')) or
+                   'function(' in line or '=>' in line)
+        elif language == 'go':
+            return line.startswith(('func ', 'type '))
+
+        return False
+
+
+# Convenience function
+def enhanced_chunk_code(
+    file_path: Path,
+    content: Optional[str] = None,
+    max_chunk_size: int = 1500,
+    context_mode: str = "full"
+) -> List[EnhancedCodeChunk]:
+    """
+    Convenience function to chunk code with enhanced metadata extraction.
+
+    Args:
+        file_path: Path to the source file
+        content: Optional pre-loaded content
+        max_chunk_size: Maximum chunk size
+        context_mode: Context detail level ('none', 'minimal', 'full')
+
+    Returns:
+        List of EnhancedCodeChunk objects
+    """
+    chunker = EnhancedASTChunker(
+        max_chunk_size=max_chunk_size,
+        context_mode=context_mode
+    )
+    return chunker.chunk_file(file_path, content)
+
+
+if __name__ == "__main__":
+    # Test the enhanced chunker
+    import sys
+
+    logging.basicConfig(level=logging.DEBUG)
+
+    if len(sys.argv) < 2:
+        print("Usage: python enhanced_ast_chunker.py <file_path>")
+        sys.exit(1)
+
+    test_file = Path(sys.argv[1])
+
+    print(f"\nTesting EnhancedASTChunker on: {test_file}")
+    print("=" * 60)
+
+    chunker = EnhancedASTChunker(context_mode="full")
+
+    try:
+        chunks = chunker.chunk_file(test_file)
+
+        print(f"\nFound {len(chunks)} chunks:\n")
+
+        for i, chunk in enumerate(chunks):
+            print(f"{'='*60}")
+            print(f"Chunk {i + 1}: {chunk.chunk_type} - {chunk.name or '(unnamed)'}")
+            print(f"{'='*60}")
+            print(f"Lines: {chunk.line_range[0]+1}-{chunk.line_range[1]+1}")
+            print(f"Scope: {' > '.join(chunk.scope) or '(module level)'}")
+            if chunk.signature:
+                print(f"Signature: {chunk.signature}")
+            if chunk.parameters:
+                print(f"Parameters: {len(chunk.parameters)}")
+                for p in chunk.parameters[:3]:
+                    print(f"  - {p.name}: {p.type_annotation or 'untyped'}")
+            if chunk.return_type:
+                print(f"Return type: {chunk.return_type}")
+            if chunk.imports:
+                print(f"Uses imports: {[i.name for i in chunk.imports[:5]]}")
+            if chunk.docstring:
+                print(f"Docstring: {chunk.docstring[:80]}...")
+            print(f"\nContextualized text preview:")
+            print("-" * 40)
+            print(chunk.contextualized_text[:500])
+            if len(chunk.contextualized_text) > 500:
+                print("...")
+            print()
+
+    except Exception as e:
+        print(f"Error: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)