claude-code-workflow 6.3.53 → 7.0.0

package/codex-lens/src/codexlens/parsers/astgrep_binding.py

@@ -0,0 +1,320 @@
+"""ast-grep based parser binding for CodexLens.
+
+Provides AST-level pattern matching via ast-grep-py (PyO3 bindings).
+
+Note: This module wraps the official ast-grep Python bindings for pattern-based
+code analysis. If ast-grep-py is unavailable, the parser returns None gracefully.
+Callers should use tree-sitter or regex-based fallbacks.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+# Import patterns from centralized definition (avoid duplication)
+from codexlens.parsers.patterns.python import get_pattern, PYTHON_PATTERNS
+
+# Graceful import pattern following treesitter_parser.py convention
+try:
+    from ast_grep_py import SgNode, SgRoot
+    ASTGREP_AVAILABLE = True
+except ImportError:
+    SgNode = None  # type: ignore[assignment,misc]
+    SgRoot = None  # type: ignore[assignment,misc]
+    ASTGREP_AVAILABLE = False
+
+log = logging.getLogger(__name__)
+
+
+class AstGrepBinding:
+    """Wrapper for ast-grep-py bindings with CodexLens integration.
+
+    Provides pattern-based AST matching for code relationship extraction.
+    Uses declarative patterns with metavariables ($A, $$ARGS) for matching.
+    """
+
+    # Language ID mapping to ast-grep language names
+    LANGUAGE_MAP = {
+        "python": "python",
+        "javascript": "javascript",
+        "typescript": "typescript",
+        "tsx": "tsx",
+    }
+
+    def __init__(self, language_id: str, path: Optional[Path] = None) -> None:
+        """Initialize ast-grep binding for a language.
+
+        Args:
+            language_id: Language identifier (python, javascript, typescript, tsx)
+            path: Optional file path for language variant detection
+        """
+        self.language_id = language_id
+        self.path = path
+        self._language: Optional[str] = None
+        self._root: Optional[SgRoot] = None  # type: ignore[valid-type]
+
+        if ASTGREP_AVAILABLE:
+            self._initialize_language()
+
+    def _initialize_language(self) -> None:
+        """Initialize ast-grep language setting."""
+        # Detect TSX from file extension
+        if self.language_id == "typescript" and self.path is not None:
+            if self.path.suffix.lower() == ".tsx":
+                self._language = "tsx"
+                return
+
+        self._language = self.LANGUAGE_MAP.get(self.language_id)
+
+    def is_available(self) -> bool:
+        """Check if ast-grep binding is available and ready.
+
+        Returns:
+            True if ast-grep-py is installed and language is supported
+        """
+        return ASTGREP_AVAILABLE and self._language is not None
+
+    def parse(self, source_code: str) -> bool:
+        """Parse source code into ast-grep syntax tree.
+
+        Args:
+            source_code: Source code text to parse
+
+        Returns:
+            True if parsing succeeds, False otherwise
+        """
+        if not self.is_available() or SgRoot is None:
+            return False
+
+        try:
+            self._root = SgRoot(source_code, self._language)  # type: ignore[misc]
+            return True
+        except (ValueError, TypeError, RuntimeError) as e:
+            log.debug(f"ast-grep parse error: {e}")
+            self._root = None
+            return False
+
+    def find_all(self, pattern: str) -> List[SgNode]:  # type: ignore[valid-type]
+        """Find all matches for a pattern in the parsed source.
+
+        Args:
+            pattern: ast-grep pattern string (e.g., "class $NAME($$$BASES) $$$BODY")
+
+        Returns:
+            List of matching SgNode objects, empty if no matches or not parsed
+        """
+        if not self.is_available() or self._root is None:
+            return []
+
+        try:
+            root_node = self._root.root()
+            # ast-grep-py 0.40+ requires dict config format
+            config = {"rule": {"pattern": pattern}}
+            return list(root_node.find_all(config))
+        except (ValueError, TypeError, AttributeError) as e:
+            log.debug(f"ast-grep find_all error: {e}")
+            return []
+
+    def find_inheritance(self) -> List[Dict[str, str]]:
+        """Find all class inheritance declarations.
+
+        Returns:
+            List of dicts with 'class_name' and 'bases' keys
+        """
+        if self.language_id != "python":
+            return []
+
+        matches = self.find_all(get_pattern("class_with_bases"))
+        results: List[Dict[str, str]] = []
+
+        for node in matches:
+            class_name = self._get_match(node, "NAME")
+            if class_name:
+                results.append({
+                    "class_name": class_name,
+                    "bases": self._get_match(node, "BASES"),  # Base classes text
+                })
+
+        return results
+
+    def find_calls(self) -> List[Dict[str, str]]:
+        """Find all function/method calls.
+
+        Returns:
+            List of dicts with 'function' and 'line' keys
+        """
+        if self.language_id != "python":
+            return []
+
+        matches = self.find_all(get_pattern("call"))
+        results: List[Dict[str, str]] = []
+
+        for node in matches:
+            func_name = self._get_match(node, "FUNC")
+            if func_name:
+                # Skip self. and cls. prefixed calls
+                base = func_name.split(".", 1)[0]
+                if base not in {"self", "cls"}:
+                    results.append({
+                        "function": func_name,
+                        "line": str(self._get_line_number(node)),
+                    })
+
+        return results
+
+    def find_imports(self) -> List[Dict[str, str]]:
+        """Find all import statements.
+
+        Returns:
+            List of dicts with 'module' and 'type' keys
+        """
+        if self.language_id != "python":
+            return []
+
+        results: List[Dict[str, str]] = []
+
+        # Find 'import X' statements
+        import_matches = self.find_all(get_pattern("import_stmt"))
+        for node in import_matches:
+            module = self._get_match(node, "MODULE")
+            if module:
+                results.append({
+                    "module": module,
+                    "type": "import",
+                    "line": str(self._get_line_number(node)),
+                })
+
+        # Find 'from X import Y' statements
+        from_matches = self.find_all(get_pattern("import_from"))
+        for node in from_matches:
+            module = self._get_match(node, "MODULE")
+            names = self._get_match(node, "NAMES")
+            if module:
+                results.append({
+                    "module": module,
+                    "names": names or "",
+                    "type": "from_import",
+                    "line": str(self._get_line_number(node)),
+                })
+
+        return results
+
+    def _get_match(self, node: SgNode, metavar: str) -> str:  # type: ignore[valid-type]
+        """Extract matched metavariable value from node.
+
+        Args:
+            node: SgNode with match
+            metavar: Metavariable name (without $ prefix)
+
+        Returns:
+            Matched text or empty string
+        """
+        if node is None:
+            return ""
+        try:
+            match = node.get_match(metavar)
+            if match is not None:
+                return match.text()
+        except (ValueError, AttributeError, KeyError) as e:
+            log.debug(f"ast-grep get_match error for {metavar}: {e}")
+        return ""
+
+    def _get_node_text(self, node: SgNode) -> str:  # type: ignore[valid-type]
+        """Get full text of a node.
+
+        Args:
+            node: SgNode to extract text from
+
+        Returns:
+            Node's text content
+        """
+        if node is None:
+            return ""
+        try:
+            return node.text()
+        except (ValueError, AttributeError) as e:
+            log.debug(f"ast-grep get_node_text error: {e}")
+            return ""
+
+    def _get_line_number(self, node: SgNode) -> int:  # type: ignore[valid-type]
+        """Get starting line number of a node.
+
+        Args:
+            node: SgNode to get line number for
+
+        Returns:
+            1-based line number
+        """
+        if node is None:
+            return 0
+        try:
+            range_info = node.range()
+            # ast-grep-py 0.40+ returns Range object with .start.line attribute
+            if hasattr(range_info, 'start') and hasattr(range_info.start, 'line'):
+                return range_info.start.line + 1  # Convert to 1-based
+            # Fallback for string format "(0,0)-(1,8)"
+            if isinstance(range_info, str) and range_info:
+                start_part = range_info.split('-')[0].strip('()')
+                start_line = int(start_part.split(',')[0])
+                return start_line + 1
+        except (ValueError, AttributeError, TypeError, IndexError) as e:
+            log.debug(f"ast-grep get_line_number error: {e}")
+        return 0
+
+    def _get_line_range(self, node: SgNode) -> Tuple[int, int]:  # type: ignore[valid-type]
+        """Get line range (start, end) of a node.
+
+        Args:
+            node: SgNode to get line range for
+
+        Returns:
+            Tuple of (start_line, end_line), both 1-based inclusive
+        """
+        if node is None:
+            return (0, 0)
+        try:
+            range_info = node.range()
+            # ast-grep-py 0.40+ returns Range object with .start.line and .end.line
+            if hasattr(range_info, 'start') and hasattr(range_info, 'end'):
+                start_line = getattr(range_info.start, 'line', 0)
+                end_line = getattr(range_info.end, 'line', 0)
+                return (start_line + 1, end_line + 1)  # Convert to 1-based
+            # Fallback for string format "(0,0)-(1,8)"
+            if isinstance(range_info, str) and range_info:
+                parts = range_info.split('-')
+                start_part = parts[0].strip('()')
+                end_part = parts[1].strip('()')
+                start_line = int(start_part.split(',')[0])
+                end_line = int(end_part.split(',')[0])
+                return (start_line + 1, end_line + 1)
+        except (ValueError, AttributeError, TypeError, IndexError) as e:
+            log.debug(f"ast-grep get_line_range error: {e}")
+        return (0, 0)
+
+    def get_language(self) -> Optional[str]:
+        """Get the configured ast-grep language.
+
+        Returns:
+            Language string or None if not configured
+        """
+        return self._language
+
+
+def is_astgrep_available() -> bool:
+    """Check if ast-grep-py is installed and available.
+
+    Returns:
+        True if ast-grep bindings can be imported
+    """
+    return ASTGREP_AVAILABLE
+
+
+def get_supported_languages() -> List[str]:
+    """Get list of supported languages for ast-grep.
+
+    Returns:
+        List of language identifiers
+    """
+    return list(AstGrepBinding.LANGUAGE_MAP.keys())

package/codex-lens/src/codexlens/parsers/astgrep_js_ts_processor.py

@@ -0,0 +1,306 @@
+"""Ast-grep processors for JavaScript/TypeScript relationship extraction.
+
+These processors are intentionally narrower than the tree-sitter relationship
+extractor: they focus on stable, high-signal edges for static graph usage:
+- IMPORTS: ES module imports + CommonJS require() (string literal only)
+- INHERITS: class/interface extends
+
+They are used when Config.use_astgrep is True.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Callable, List, Optional, Sequence, Set, Tuple
+
+from codexlens.entities import CodeRelationship, IndexedFile, RelationshipType
+from codexlens.parsers.astgrep_processor import BaseAstGrepProcessor
+
+
+_IDENT_RE = re.compile(r"^[A-Za-z_$][A-Za-z0-9_$]*$")
+_BRACE_IMPORT_RE = re.compile(
+    r"\bimport\s+(?:type\s+)?(?:[A-Za-z_$][A-Za-z0-9_$]*\s*,\s*)?\{\s*(?P<names>[^}]*)\}\s*from\b",
+    re.MULTILINE,
+)
+
+
+def _strip_quotes(value: str) -> str:
+    value = (value or "").strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"', "`"}:
+        return value[1:-1]
+    return value
+
+
+def _module_from_literal(raw: str) -> str:
+    raw = (raw or "").strip()
+    if not raw:
+        return ""
+    return _strip_quotes(raw).strip()
+
+
+def _extract_named_imports(raw: str) -> List[str]:
+    raw = (raw or "").strip()
+    if not raw:
+        return []
+
+    # Normalize any surrounding braces the match might include.
+    if raw.startswith("{") and raw.endswith("}"):
+        raw = raw[1:-1].strip()
+
+    # Split by commas at top-level; named imports do not nest in JS/TS syntax.
+    parts = [p.strip() for p in raw.split(",") if p.strip()]
+    names: List[str] = []
+    for part in parts:
+        # TS: "type Foo" inside braces
+        if part.startswith("type "):
+            part = part[5:].strip()
+        # Handle `foo as bar` (TS) / `foo as bar` (proposed) / `foo as bar`-style text.
+        if " as " in part:
+            part = part.split(" as ", 1)[0].strip()
+        if _IDENT_RE.match(part):
+            names.append(part)
+    return names
+
+
+def _extract_brace_import_names(statement: str) -> str:
+    statement = (statement or "").strip()
+    if not statement:
+        return ""
+    match = _BRACE_IMPORT_RE.search(statement)
+    if not match:
+        return ""
+    return (match.group("names") or "").strip()
+
+
+def _dedupe_relationships(rels: Sequence[CodeRelationship]) -> List[CodeRelationship]:
+    seen: Set[Tuple[str, str, str]] = set()
+    out: List[CodeRelationship] = []
+    for r in rels:
+        key = (r.source_symbol, r.target_symbol, r.relationship_type.value)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(r)
+    return out
+
+
+class _AstGrepJsTsProcessor(BaseAstGrepProcessor):
+    def __init__(
+        self,
+        language_id: str,
+        *,
+        path: Optional[Path] = None,
+        get_pattern: Callable[[str], str],
+    ) -> None:
+        super().__init__(language_id, path)
+        self._get_pattern = get_pattern
+
+    def parse(self, text: str, path: Path) -> Optional[IndexedFile]:
+        if not self.is_available():
+            return None
+
+        try:
+            relationships = self._extract_relationships(text, path)
+            return IndexedFile(
+                path=str(path.resolve()),
+                language=self.language_id,
+                symbols=[],
+                chunks=[],
+                relationships=relationships,
+            )
+        except Exception:
+            return None
+
+    def process_matches(  # type: ignore[override]
+        self,
+        matches,  # SgNode list (runtime-only type)
+        source_code: str,
+        path: Path,
+    ) -> List[CodeRelationship]:
+        # Not used by the current JS/TS processors; keep the interface for parity.
+        _ = (matches, source_code, path)
+        return []
+
+    def _extract_relationships(self, source_code: str, path: Path) -> List[CodeRelationship]:
+        source_file = str(path.resolve())
+        rels: List[CodeRelationship] = []
+
+        rels.extend(self._extract_imports(source_code, source_file=source_file))
+        rels.extend(self._extract_inherits(source_code, source_file=source_file))
+
+        return _dedupe_relationships(rels)
+
+    def _extract_imports(self, source_code: str, *, source_file: str) -> List[CodeRelationship]:
+        rels: List[CodeRelationship] = []
+
+        def record(module_name: str, line: int) -> None:
+            if not module_name:
+                return
+            rels.append(
+                CodeRelationship(
+                    source_symbol="<module>",
+                    target_symbol=module_name,
+                    relationship_type=RelationshipType.IMPORTS,
+                    source_file=source_file,
+                    target_file=None,
+                    source_line=line,
+                )
+            )
+
+        # Any `import ... from "mod"` form
+        for pat_name in ("import_from_dq", "import_from_sq"):
+            for node in self.run_ast_grep(source_code, self._get_pattern(pat_name)):
+                mod = _module_from_literal(self._get_match(node, "MODULE"))
+                if mod:
+                    record(mod, self._get_line_number(node))
+
+        # Side-effect import: import "mod"
+        for pat_name in ("import_side_effect_dq", "import_side_effect_sq"):
+            for node in self.run_ast_grep(source_code, self._get_pattern(pat_name)):
+                mod = _module_from_literal(self._get_match(node, "MODULE"))
+                if mod:
+                    record(mod, self._get_line_number(node))
+
+        # Named imports (named-only): import { a, b as c } from "mod"
+        for pat_name in ("import_named_only_dq", "import_named_only_sq"):
+            for node in self.run_ast_grep(source_code, self._get_pattern(pat_name)):
+                mod = _module_from_literal(self._get_match(node, "MODULE"))
+                if not mod:
+                    continue
+                raw_names = _extract_brace_import_names(self._get_node_text(node))
+                for name in _extract_named_imports(raw_names):
+                    record(f"{mod}.{name}", self._get_line_number(node))
+
+        # Named imports (default + named): import X, { a, b as c } from "mod"
+        for pat_name in ("import_default_named_dq", "import_default_named_sq"):
+            for node in self.run_ast_grep(source_code, self._get_pattern(pat_name)):
+                mod = _module_from_literal(self._get_match(node, "MODULE"))
+                if not mod:
+                    continue
+                raw_names = _extract_brace_import_names(self._get_node_text(node))
+                for name in _extract_named_imports(raw_names):
+                    record(f"{mod}.{name}", self._get_line_number(node))
+
+        # CommonJS require("mod") (string literal only)
+        for pat_name in ("require_call_dq", "require_call_sq"):
+            for node in self.run_ast_grep(source_code, self._get_pattern(pat_name)):
+                mod = _module_from_literal(self._get_match(node, "MODULE"))
+                if mod:
+                    record(mod, self._get_line_number(node))
+
+        return rels
+
+    def _extract_inherits(self, source_code: str, *, source_file: str) -> List[CodeRelationship]:
+        rels: List[CodeRelationship] = []
+
+        for node in self.run_ast_grep(source_code, self._get_pattern("class_extends")):
+            class_name = (self._get_match(node, "NAME") or "").strip()
+            base_raw = (self._get_match(node, "BASE") or "").strip()
+            if not class_name or not base_raw:
+                continue
+            base = base_raw.split("<", 1)[0].strip()
+            if not base:
+                continue
+            rels.append(
+                CodeRelationship(
+                    source_symbol=class_name,
+                    target_symbol=base,
+                    relationship_type=RelationshipType.INHERITS,
+                    source_file=source_file,
+                    target_file=None,
+                    source_line=self._get_line_number(node),
+                )
+            )
+
+        return rels
+
+
+class AstGrepJavaScriptProcessor(_AstGrepJsTsProcessor):
+    def __init__(self, path: Optional[Path] = None) -> None:
+        from codexlens.parsers.patterns.javascript import get_pattern as get_js_pattern
+
+        super().__init__("javascript", path=path, get_pattern=get_js_pattern)
+
+
+class AstGrepTypeScriptProcessor(_AstGrepJsTsProcessor):
+    def __init__(self, path: Optional[Path] = None) -> None:
+        from codexlens.parsers.patterns.typescript import get_pattern as get_ts_pattern
+
+        super().__init__("typescript", path=path, get_pattern=get_ts_pattern)
+
+    def _extract_inherits(self, source_code: str, *, source_file: str) -> List[CodeRelationship]:
+        rels = super()._extract_inherits(source_code, source_file=source_file)
+
+        # Interface extends: interface Foo extends Bar {}
+        for node in self.run_ast_grep(source_code, self._get_pattern("interface_extends")):
+            name = (self._get_match(node, "NAME") or "").strip()
+            base_raw = (self._get_match(node, "BASE") or "").strip()
+            if not name or not base_raw:
+                continue
+            base = base_raw.split("<", 1)[0].strip()
+            if not base:
+                continue
+            rels.append(
+                CodeRelationship(
+                    source_symbol=name,
+                    target_symbol=base,
+                    relationship_type=RelationshipType.INHERITS,
+                    source_file=source_file,
+                    target_file=None,
+                    source_line=self._get_line_number(node),
+                )
+            )
+
+        return _dedupe_relationships(rels)
+
+    def _extract_imports(self, source_code: str, *, source_file: str) -> List[CodeRelationship]:
+        # Reuse JS logic for standard imports
+        rels = super()._extract_imports(source_code, source_file=source_file)
+
+        def record(module_name: str, line: int) -> None:
+            if not module_name:
+                return
+            rels.append(
+                CodeRelationship(
+                    source_symbol="<module>",
+                    target_symbol=module_name,
+                    relationship_type=RelationshipType.IMPORTS,
+                    source_file=source_file,
+                    target_file=None,
+                    source_line=line,
+                )
+            )
+
+        # Type-only imports: import type ... from "mod"
+        for pat_name in ("import_type_from_dq", "import_type_from_sq"):
+            for node in self.run_ast_grep(source_code, self._get_pattern(pat_name)):
+                mod = _module_from_literal(self._get_match(node, "MODULE"))
+                if mod:
+                    record(mod, self._get_line_number(node))
+
+        for pat_name in ("import_type_named_only_dq", "import_type_named_only_sq"):
+            for node in self.run_ast_grep(source_code, self._get_pattern(pat_name)):
+                mod = _module_from_literal(self._get_match(node, "MODULE"))
+                if not mod:
+                    continue
+                raw_names = _extract_brace_import_names(self._get_node_text(node))
+                for name in _extract_named_imports(raw_names):
+                    record(f"{mod}.{name}", self._get_line_number(node))
+
+        for pat_name in ("import_type_default_named_dq", "import_type_default_named_sq"):
+            for node in self.run_ast_grep(source_code, self._get_pattern(pat_name)):
+                mod = _module_from_literal(self._get_match(node, "MODULE"))
+                if not mod:
+                    continue
+                raw_names = _extract_brace_import_names(self._get_node_text(node))
+                for name in _extract_named_imports(raw_names):
+                    record(f"{mod}.{name}", self._get_line_number(node))
+
+        return _dedupe_relationships(rels)
+
+
+__all__ = [
+    "AstGrepJavaScriptProcessor",
+    "AstGrepTypeScriptProcessor",
+]