roma-debug 0.1.0__py3-none-any.whl

roma_debug/parsers/__init__.py

@@ -0,0 +1,21 @@
+"""ROMA Debug Parsers - Multi-language source code parsing.
+
+This package provides extensible parser support for extracting
+semantic information from source files in multiple programming languages.
+"""
+
+from roma_debug.parsers.base import BaseParser
+from roma_debug.parsers.registry import (
+    get_parser,
+    detect_language,
+    register_parser,
+    ParserRegistry,
+)
+
+__all__ = [
+    "BaseParser",
+    "get_parser",
+    "detect_language",
+    "register_parser",
+    "ParserRegistry",
+]

roma_debug/parsers/base.py

@@ -0,0 +1,189 @@
+"""Abstract base class for language parsers.
+
+All language-specific parsers must implement this interface.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, List
+
+from roma_debug.core.models import Language, Symbol, Import
+
+
+class BaseParser(ABC):
+    """Abstract base class for language parsers.
+
+    Each language parser must implement methods for:
+    - Parsing source code
+    - Finding symbols (functions, classes) at specific lines
+    - Extracting import statements
+    """
+
+    def __init__(self):
+        """Initialize the parser."""
+        self._source: Optional[str] = None
+        self._filepath: Optional[str] = None
+        self._lines: List[str] = []
+        self._parsed: bool = False
+
+    @property
+    @abstractmethod
+    def language(self) -> Language:
+        """Return the language this parser handles."""
+        ...
+
+    @property
+    def source(self) -> Optional[str]:
+        """Return the parsed source code."""
+        return self._source
+
+    @property
+    def filepath(self) -> Optional[str]:
+        """Return the file path being parsed."""
+        return self._filepath
+
+    @property
+    def lines(self) -> List[str]:
+        """Return source split into lines."""
+        return self._lines
+
+    @property
+    def is_parsed(self) -> bool:
+        """Check if a file has been successfully parsed."""
+        return self._parsed
+
+    @abstractmethod
+    def parse(self, source: str, filepath: str = "") -> bool:
+        """Parse source code.
+
+        Args:
+            source: The source code to parse
+            filepath: Optional file path for context
+
+        Returns:
+            True if parsing succeeded, False otherwise
+        """
+        ...
+
+    @abstractmethod
+    def find_enclosing_symbol(self, line_number: int) -> Optional[Symbol]:
+        """Find the innermost symbol containing the given line.
+
+        Args:
+            line_number: 1-based line number
+
+        Returns:
+            Symbol if found, None otherwise
+        """
+        ...
+
+    @abstractmethod
+    def extract_imports(self) -> List[Import]:
+        """Extract all import statements from the parsed source.
+
+        Returns:
+            List of Import objects
+        """
+        ...
+
+    def get_symbol_at_line(self, line_number: int) -> Optional[Symbol]:
+        """Alias for find_enclosing_symbol for backward compatibility."""
+        return self.find_enclosing_symbol(line_number)
+
+    def get_line_content(self, line_number: int) -> Optional[str]:
+        """Get the content of a specific line.
+
+        Args:
+            line_number: 1-based line number
+
+        Returns:
+            Line content or None if out of range
+        """
+        if not self._lines:
+            return None
+        idx = line_number - 1
+        if 0 <= idx < len(self._lines):
+            return self._lines[idx]
+        return None
+
+    def get_line_range(self, start: int, end: int) -> List[str]:
+        """Get a range of lines.
+
+        Args:
+            start: 1-based start line (inclusive)
+            end: 1-based end line (inclusive)
+
+        Returns:
+            List of line contents
+        """
+        if not self._lines:
+            return []
+        start_idx = max(0, start - 1)
+        end_idx = min(len(self._lines), end)
+        return self._lines[start_idx:end_idx]
+
+    def format_snippet(
+        self,
+        start_line: int,
+        end_line: int,
+        highlight_line: Optional[int] = None,
+        with_line_numbers: bool = True,
+    ) -> str:
+        """Format a code snippet with optional line numbers and highlighting.
+
+        Args:
+            start_line: 1-based start line
+            end_line: 1-based end line
+            highlight_line: Optional line to highlight with >>
+            with_line_numbers: Whether to include line numbers
+
+        Returns:
+            Formatted snippet string
+        """
+        lines = self.get_line_range(start_line, end_line)
+        result = []
+
+        for i, line in enumerate(lines):
+            line_num = start_line + i
+            if with_line_numbers:
+                marker = " >> " if line_num == highlight_line else "    "
+                result.append(f"{marker}{line_num:4d} | {line}")
+            else:
+                marker = ">> " if line_num == highlight_line else "   "
+                result.append(f"{marker}{line}")
+
+        return "\n".join(result)
+
+    def extract_symbol_code(
+        self,
+        symbol: Symbol,
+        include_decorators: bool = True,
+        context_before: int = 0,
+        context_after: int = 0,
+    ) -> str:
+        """Extract the full code for a symbol.
+
+        Args:
+            symbol: The symbol to extract
+            include_decorators: Whether to include decorator lines
+            context_before: Extra lines before the symbol
+            context_after: Extra lines after the symbol
+
+        Returns:
+            The symbol's source code
+        """
+        start = symbol.start_line
+        if include_decorators and symbol.decorators:
+            # Decorators are typically on lines before the definition
+            start = max(1, start - len(symbol.decorators))
+
+        start = max(1, start - context_before)
+        end = min(len(self._lines), symbol.end_line + context_after)
+
+        return "\n".join(self.get_line_range(start, end))
+
+    def reset(self):
+        """Reset parser state."""
+        self._source = None
+        self._filepath = None
+        self._lines = []
+        self._parsed = False

roma_debug/parsers/python_ast_parser.py

@@ -0,0 +1,268 @@
+"""Python AST-based parser implementation.
+
+Uses Python's built-in ast module for parsing Python source code.
+This is the legacy fallback parser that provides reliable Python parsing.
+"""
+
+import ast
+from typing import Optional, List
+
+from roma_debug.core.models import Language, Symbol, Import
+from roma_debug.parsers.base import BaseParser
+
+
+class PythonAstParser(BaseParser):
+    """Python parser using the built-in ast module.
+
+    This parser provides reliable Python parsing using Python's own
+    AST module. It's used as the primary Python parser and as a
+    fallback when tree-sitter is unavailable.
+    """
+
+    def __init__(self):
+        """Initialize the Python AST parser."""
+        super().__init__()
+        self._tree: Optional[ast.AST] = None
+        self._symbols: List[Symbol] = []
+        self._imports: List[Import] = []
+
+    @property
+    def language(self) -> Language:
+        """Return Python as the language."""
+        return Language.PYTHON
+
+    def parse(self, source: str, filepath: str = "") -> bool:
+        """Parse Python source code using ast.
+
+        Args:
+            source: Python source code
+            filepath: Optional file path
+
+        Returns:
+            True if parsing succeeded
+        """
+        self.reset()
+        self._source = source
+        self._filepath = filepath
+        self._lines = source.splitlines()
+
+        try:
+            self._tree = ast.parse(source)
+            self._parsed = True
+            self._extract_symbols()
+            self._extract_imports_internal()
+            return True
+        except SyntaxError:
+            return False
+
+    def reset(self):
+        """Reset parser state."""
+        super().reset()
+        self._tree = None
+        self._symbols = []
+        self._imports = []
+
+    def _extract_symbols(self):
+        """Extract all function and class symbols from the AST."""
+        if self._tree is None:
+            return
+
+        def visit_node(node: ast.AST, parent: Optional[Symbol] = None):
+            symbol = None
+
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                kind = "async_function" if isinstance(node, ast.AsyncFunctionDef) else "function"
+                if parent and parent.kind == "class":
+                    kind = "method"
+
+                # Extract decorators
+                decorators = []
+                for dec in node.decorator_list:
+                    if isinstance(dec, ast.Name):
+                        decorators.append(dec.id)
+                    elif isinstance(dec, ast.Attribute):
+                        decorators.append(ast.unparse(dec) if hasattr(ast, 'unparse') else str(dec.attr))
+                    elif isinstance(dec, ast.Call):
+                        if isinstance(dec.func, ast.Name):
+                            decorators.append(dec.func.id)
+                        elif isinstance(dec.func, ast.Attribute):
+                            decorators.append(dec.func.attr)
+
+                # Extract docstring
+                docstring = ast.get_docstring(node)
+
+                symbol = Symbol(
+                    name=node.name,
+                    kind=kind,
+                    start_line=node.lineno,
+                    end_line=node.end_lineno or node.lineno,
+                    start_col=node.col_offset,
+                    end_col=node.end_col_offset or 0,
+                    parent=parent,
+                    decorators=decorators,
+                    docstring=docstring,
+                )
+                self._symbols.append(symbol)
+
+            elif isinstance(node, ast.ClassDef):
+                # Extract decorators
+                decorators = []
+                for dec in node.decorator_list:
+                    if isinstance(dec, ast.Name):
+                        decorators.append(dec.id)
+                    elif isinstance(dec, ast.Attribute):
+                        decorators.append(ast.unparse(dec) if hasattr(ast, 'unparse') else str(dec.attr))
+
+                # Extract docstring
+                docstring = ast.get_docstring(node)
+
+                symbol = Symbol(
+                    name=node.name,
+                    kind="class",
+                    start_line=node.lineno,
+                    end_line=node.end_lineno or node.lineno,
+                    start_col=node.col_offset,
+                    end_col=node.end_col_offset or 0,
+                    parent=parent,
+                    decorators=decorators,
+                    docstring=docstring,
+                )
+                self._symbols.append(symbol)
+
+            # Visit children
+            new_parent = symbol if symbol else parent
+            for child in ast.iter_child_nodes(node):
+                visit_node(child, new_parent)
+
+        visit_node(self._tree)
+
+    def _extract_imports_internal(self):
+        """Extract import statements from the AST."""
+        if self._tree is None:
+            return
+
+        for node in ast.walk(self._tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    self._imports.append(Import(
+                        module_name=alias.name,
+                        alias=alias.asname,
+                        imported_names=[],
+                        is_relative=False,
+                        relative_level=0,
+                        line_number=node.lineno,
+                        language=Language.PYTHON,
+                    ))
+
+            elif isinstance(node, ast.ImportFrom):
+                module = node.module or ""
+                imported_names = [alias.name for alias in node.names]
+                aliases = {alias.name: alias.asname for alias in node.names if alias.asname}
+
+                self._imports.append(Import(
+                    module_name=module,
+                    alias=None,
+                    imported_names=imported_names,
+                    is_relative=node.level > 0,
+                    relative_level=node.level,
+                    line_number=node.lineno,
+                    language=Language.PYTHON,
+                ))
+
+    def find_enclosing_symbol(self, line_number: int) -> Optional[Symbol]:
+        """Find the innermost symbol containing the given line.
+
+        Args:
+            line_number: 1-based line number
+
+        Returns:
+            The innermost Symbol containing the line, or None
+        """
+        best_match: Optional[Symbol] = None
+        best_size = float('inf')
+
+        for symbol in self._symbols:
+            if symbol.contains_line(line_number):
+                size = symbol.end_line - symbol.start_line
+                if size < best_size:
+                    best_match = symbol
+                    best_size = size
+
+        return best_match
+
+    def extract_imports(self) -> List[Import]:
+        """Return all extracted imports.
+
+        Returns:
+            List of Import objects
+        """
+        return self._imports.copy()
+
+    def find_all_symbols(self) -> List[Symbol]:
+        """Return all extracted symbols.
+
+        Returns:
+            List of all Symbol objects
+        """
+        return self._symbols.copy()
+
+    def find_symbols_by_name(self, name: str) -> List[Symbol]:
+        """Find all symbols with the given name.
+
+        Args:
+            name: Symbol name to search for
+
+        Returns:
+            List of matching Symbol objects
+        """
+        return [s for s in self._symbols if s.name == name]
+
+    def find_symbols_by_kind(self, kind: str) -> List[Symbol]:
+        """Find all symbols of a given kind.
+
+        Args:
+            kind: Symbol kind ('function', 'class', 'method', etc.)
+
+        Returns:
+            List of matching Symbol objects
+        """
+        return [s for s in self._symbols if s.kind == kind]
+
+    def get_function_calls_in_symbol(self, symbol: Symbol) -> List[str]:
+        """Extract function/method calls within a symbol.
+
+        Args:
+            symbol: The symbol to analyze
+
+        Returns:
+            List of called function/method names
+        """
+        if self._tree is None:
+            return []
+
+        calls = []
+
+        def find_symbol_node(node: ast.AST) -> Optional[ast.AST]:
+            """Find the AST node for the given symbol."""
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                if node.name == symbol.name and node.lineno == symbol.start_line:
+                    return node
+            for child in ast.iter_child_nodes(node):
+                result = find_symbol_node(child)
+                if result:
+                    return result
+            return None
+
+        symbol_node = find_symbol_node(self._tree)
+        if symbol_node is None:
+            return []
+
+        for node in ast.walk(symbol_node):
+            if isinstance(node, ast.Call):
+                if isinstance(node.func, ast.Name):
+                    calls.append(node.func.id)
+                elif isinstance(node.func, ast.Attribute):
+                    # For method calls like obj.method()
+                    calls.append(node.func.attr)
+
+        return calls

roma_debug/parsers/registry.py

@@ -0,0 +1,196 @@
+"""Parser registry for language detection and parser dispatch.
+
+Provides centralized parser management and language detection from file extensions.
+"""
+
+import os
+from typing import Dict, Optional, Type, Callable
+
+from roma_debug.core.models import Language
+from roma_debug.parsers.base import BaseParser
+
+
+class ParserRegistry:
+    """Registry for language parsers.
+
+    Manages parser registration and provides parser lookup by language
+    or file extension.
+    """
+
+    def __init__(self):
+        """Initialize the registry."""
+        self._parsers: Dict[Language, Type[BaseParser]] = {}
+        self._parser_factories: Dict[Language, Callable[[], BaseParser]] = {}
+        self._instances: Dict[Language, BaseParser] = {}
+
+    def register(
+        self,
+        language: Language,
+        parser_class: Type[BaseParser],
+        factory: Optional[Callable[[], BaseParser]] = None,
+    ):
+        """Register a parser for a language.
+
+        Args:
+            language: The language this parser handles
+            parser_class: The parser class
+            factory: Optional factory function to create parser instances
+        """
+        self._parsers[language] = parser_class
+        if factory:
+            self._parser_factories[language] = factory
+
+    def get_parser(
+        self,
+        language: Language,
+        create_new: bool = False,
+    ) -> Optional[BaseParser]:
+        """Get a parser for the given language.
+
+        Args:
+            language: The language to get a parser for
+            create_new: If True, create a new instance instead of reusing
+
+        Returns:
+            Parser instance or None if no parser registered
+        """
+        if language not in self._parsers:
+            return None
+
+        if create_new or language not in self._instances:
+            if language in self._parser_factories:
+                parser = self._parser_factories[language]()
+            else:
+                parser = self._parsers[language]()
+            if not create_new:
+                self._instances[language] = parser
+            return parser
+
+        return self._instances[language]
+
+    def get_parser_for_file(
+        self,
+        filepath: str,
+        create_new: bool = False,
+    ) -> Optional[BaseParser]:
+        """Get a parser based on file extension.
+
+        Args:
+            filepath: Path to the file
+            create_new: If True, create a new instance
+
+        Returns:
+            Parser instance or None if language not supported
+        """
+        language = detect_language(filepath)
+        return self.get_parser(language, create_new)
+
+    def supports_language(self, language: Language) -> bool:
+        """Check if a language is supported.
+
+        Args:
+            language: The language to check
+
+        Returns:
+            True if a parser is registered for this language
+        """
+        return language in self._parsers
+
+    def supports_file(self, filepath: str) -> bool:
+        """Check if a file type is supported.
+
+        Args:
+            filepath: Path to the file
+
+        Returns:
+            True if the file's language has a registered parser
+        """
+        language = detect_language(filepath)
+        return self.supports_language(language)
+
+    @property
+    def supported_languages(self) -> list:
+        """Get list of supported languages."""
+        return list(self._parsers.keys())
+
+    def clear_instances(self):
+        """Clear cached parser instances."""
+        self._instances.clear()
+
+
+# Global registry instance
+_registry = ParserRegistry()
+
+
+def detect_language(filepath: str) -> Language:
+    """Detect programming language from file path.
+
+    Args:
+        filepath: Path to the source file
+
+    Returns:
+        Language enum value
+    """
+    _, ext = os.path.splitext(filepath)
+    return Language.from_extension(ext)
+
+
+def get_parser(
+    filepath_or_language,
+    create_new: bool = False,
+) -> Optional[BaseParser]:
+    """Get a parser for a file or language.
+
+    Args:
+        filepath_or_language: File path string or Language enum
+        create_new: If True, create a new parser instance
+
+    Returns:
+        Parser instance or None if not supported
+    """
+    if isinstance(filepath_or_language, Language):
+        return _registry.get_parser(filepath_or_language, create_new)
+    return _registry.get_parser_for_file(filepath_or_language, create_new)
+
+
+def register_parser(
+    language: Language,
+    parser_class: Type[BaseParser],
+    factory: Optional[Callable[[], BaseParser]] = None,
+):
+    """Register a parser in the global registry.
+
+    Args:
+        language: The language this parser handles
+        parser_class: The parser class
+        factory: Optional factory function
+    """
+    _registry.register(language, parser_class, factory)
+
+
+def get_registry() -> ParserRegistry:
+    """Get the global parser registry.
+
+    Returns:
+        The global ParserRegistry instance
+    """
+    return _registry
+
+
+# Register built-in parsers
+def _register_builtin_parsers():
+    """Register the built-in parsers."""
+    from roma_debug.parsers.python_ast_parser import PythonAstParser
+
+    register_parser(Language.PYTHON, PythonAstParser)
+
+    # Import tree-sitter parser module to trigger its auto-registration
+    # This allows graceful degradation if tree-sitter is not installed
+    try:
+        import roma_debug.parsers.treesitter_parser  # noqa: F401
+    except ImportError:
+        pass  # tree-sitter not available, only Python will be supported
+
+
+# Auto-register built-in parsers on module import
+_register_builtin_parsers()