codegraph-ir 0.1.0__py3-none-any.whl

cgir/languages/base.py

@@ -0,0 +1,221 @@
+"""LanguageAdapter — the per-language seam.
+
+Every downstream analysis (symbols, cfg, effects, pdg, param-flow, purity,
+slicing) is written *once* against the RepoGraph and a shared node-attr
+contract. What differs between languages is only grammar-specific
+extraction: what node type is a call, which builtins are effectful, how a
+branch's condition is reached. A ``LanguageAdapter`` answers exactly those
+questions, so a new language is one adapter, not a re-implemented pipeline.
+
+Tree-sitter is the shared substrate (Python, TypeScript, Go, Rust all have
+grammars), so adapters trade in :class:`tree_sitter.Node`. The adapter
+abstracts the *grammar*, not the parser technology.
+
+The surface grows by phase as passes are migrated behind it:
+* phase 1 — parse / locate / effects / calls
+* phase 2 — CFG statement classification + field extraction
+* phase 3 — ingest structural dispatch + attr extraction
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from tree_sitter import Node as TSNode
+
+# (dotted_callee, arg_identifier_names, 1-based_line)
+CallSite = tuple[str, list[str], int]
+
+
+# --- normalized statement descriptors (phase 2: CFG) ---------------------------
+#
+# The CFG *topology* (how branches wire, loop back-edges, try/finally joins)
+# is language-universal and lives in cgir/analyses/cfg.py. The adapter's job
+# is to classify each statement and hand back its parts in one of these
+# shapes; the builder never looks at grammar node types.
+
+
+@dataclass(slots=True)
+class SimpleDesc:
+    reads: list[str] = field(default_factory=list)
+    mutates: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class AssignDesc:
+    writes: list[str] = field(default_factory=list)
+    mutates: list[str] = field(default_factory=list)
+    reads: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class ReturnDesc:
+    reads: list[str] = field(default_factory=list)
+    mutates: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class BranchDesc:
+    """An if/elif (or `else if`) arm. Chains via ``next_branch``."""
+
+    reads: list[str] = field(default_factory=list)
+    consequence: TSNode | None = None
+    else_block: TSNode | None = None
+    next_branch: TSNode | None = None  # elif_clause / nested `if` — described again
+
+
+@dataclass(slots=True)
+class LoopDesc:
+    reads: list[str] = field(default_factory=list)
+    writes: list[str] = field(default_factory=list)  # for-targets
+    body: TSNode | None = None
+
+
+@dataclass(slots=True)
+class WithDesc:
+    """Resource-acquisition header (with / using / try-with-resources)."""
+
+    writes: list[str] = field(default_factory=list)  # `as` aliases
+    reads: list[str] = field(default_factory=list)
+    body: TSNode | None = None
+
+
+@dataclass(slots=True)
+class HandlerDesc:
+    node: TSNode
+    writes: list[str] = field(default_factory=list)  # `except ... as e`
+    block: TSNode | None = None
+
+
+@dataclass(slots=True)
+class TryDesc:
+    body: TSNode | None = None
+    handlers: list[HandlerDesc] = field(default_factory=list)
+    else_block: TSNode | None = None
+    finally_block: TSNode | None = None
+
+
+@dataclass(slots=True)
+class CaseDesc:
+    node: TSNode
+    reads: list[str] = field(default_factory=list)  # subject + guard
+    consequence: TSNode | None = None
+
+
+@dataclass(slots=True)
+class MatchDesc:
+    cases: list[CaseDesc] = field(default_factory=list)
+
+
+StatementDesc = (
+    SimpleDesc | AssignDesc | ReturnDesc | BranchDesc | LoopDesc | WithDesc | TryDesc | MatchDesc
+)
+
+
+# --- normalized module declarations (phase 3: ingest) ---------------------------
+#
+# The structural spine (Repository → File → Module → members + CONTAINS) and
+# node/edge construction are language-universal and live in
+# sources/tree_sitter_source.py. The adapter walks a module root and yields
+# these; the ingester never looks at grammar node types.
+
+
+@dataclass(slots=True)
+class ParamDecl:
+    name: str
+    node: TSNode
+
+
+@dataclass(slots=True)
+class FunctionDecl:
+    node: TSNode
+    name: str
+    params: list[ParamDecl] = field(default_factory=list)
+    signature: str = ""
+    returns: str | None = None
+    doc: str = ""
+    raises: list[str] = field(default_factory=list)
+    decorators: list[str] = field(default_factory=list)
+    free_names: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class ClassDecl:
+    node: TSNode
+    name: str
+    methods: list[FunctionDecl] = field(default_factory=list)
+    # field name → declared type name, for DI/receiver call resolution
+    # (``this.svc.method()`` where ``svc: ChaptersService``).
+    fields: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class ImportDecl:
+    node: TSNode
+    target: str
+    alias: str | None = None
+
+
+@dataclass(slots=True)
+class VariableDecl:
+    node: TSNode
+    name: str
+
+
+Declaration = FunctionDecl | ClassDecl | ImportDecl | VariableDecl
+
+
+class LanguageAdapter(ABC):
+    name: str = "base"
+    file_extensions: tuple[str, ...] = ()
+
+    @abstractmethod
+    def parse(self, source: bytes) -> TSNode:
+        """Parse source bytes; return the tree's root node."""
+
+    @abstractmethod
+    def locate_function(self, root: TSNode, name: str, start_row: int) -> TSNode | None:
+        """The function/method node named ``name`` starting on 0-based ``start_row``."""
+
+    @abstractmethod
+    def direct_effects(self, func_node: TSNode, source: bytes, aliases: dict[str, str]) -> set[str]:
+        """Direct effect tags (io/net/fs/db/nondeterm/raise) in the body.
+
+        ``aliases`` maps local import names to their absolute dotted target
+        (built language-neutrally from ``Import`` nodes), so an adapter can
+        resolve ``r.get`` → ``requests.get`` before matching its tables.
+        """
+
+    @abstractmethod
+    def call_sites(self, func_node: TSNode, source: bytes) -> list[CallSite]:
+        """Call sites in the body: dotted callee, arg identifier names, line."""
+
+    # --- phase 2: CFG extraction --------------------------------------------
+
+    @abstractmethod
+    def function_body(self, func_node: TSNode) -> TSNode | None:
+        """The function's body block node."""
+
+    @abstractmethod
+    def block_statements(self, block: TSNode) -> list[TSNode]:
+        """Statement nodes of a block, comments filtered."""
+
+    @abstractmethod
+    def describe_statement(self, node: TSNode, source: bytes) -> StatementDesc:
+        """Classify one statement and extract its parts (see descriptors)."""
+
+    # --- phase 3: ingest extraction ------------------------------------------
+
+    @abstractmethod
+    def module_declarations(
+        self, root: TSNode, source: bytes, module_name: str, rel_path: str
+    ) -> list[Declaration]:
+        """Top-level declarations of a module, fully extracted.
+
+        ``module_name`` is the dotted module path (for languages with dotted
+        relative imports, e.g. Python ``from ..a import x``); ``rel_path`` is
+        the repo-relative file path (for path-specifier imports, e.g. TS
+        ``from './util'``). Method params exclude implicit receivers
+        (``self``/``this``).
+        """

cgir/languages/cache.py

@@ -0,0 +1,73 @@
+"""Parse-once source cache.
+
+Two layers of caching, both keyed so they are always correct:
+
+* :func:`parse_cached` — a process-wide store keyed by ``(adapter, content
+  hash)``. A parse tree is a pure function of the bytes and the grammar, so
+  this is safe across analysis passes *and* across repeated scans (watch
+  mode): an unchanged file is parsed once, ever. Bounded LRU so a long-lived
+  watch process doesn't grow without limit.
+* :class:`SourceCache` — a per-run, path-keyed view used by the analysis
+  passes, which walk *per function* and would otherwise re-read/re-parse a
+  file once per function. It now resolves parse trees through
+  :func:`parse_cached`, so the ingest pass and every analysis share one
+  parse per content.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections import OrderedDict
+from pathlib import Path
+
+from tree_sitter import Node as TSNode
+
+from cgir.languages.base import LanguageAdapter
+from cgir.languages.registry import adapter_for_extension
+
+# (adapter name, sha256(content)) -> parsed root. Bounded LRU.
+_PARSE_STORE: OrderedDict[tuple[str, bytes], TSNode] = OrderedDict()
+_PARSE_STORE_MAX = 8192
+
+
+def parse_cached(adapter: LanguageAdapter, source: bytes) -> TSNode:
+    """Parse ``source`` with ``adapter``, reusing a cached tree for identical
+    content. Correct across passes and scans — the tree only depends on the
+    grammar and the bytes."""
+    key = (adapter.name, hashlib.sha256(source).digest())
+    cached = _PARSE_STORE.get(key)
+    if cached is not None:
+        _PARSE_STORE.move_to_end(key)
+        return cached
+    root = adapter.parse(source)
+    _PARSE_STORE[key] = root
+    if len(_PARSE_STORE) > _PARSE_STORE_MAX:
+        _PARSE_STORE.popitem(last=False)
+    return root
+
+
+def clear_parse_cache() -> None:
+    """Drop the process-wide parse store (tests / memory reclamation)."""
+    _PARSE_STORE.clear()
+
+
+class SourceCache:
+    def __init__(self, repo_path: Path, adapter: LanguageAdapter | None = None) -> None:
+        self._repo_path = repo_path
+        self._forced = adapter
+        self._entries: dict[str, tuple[bytes, TSNode, LanguageAdapter] | None] = {}
+
+    def get(self, rel_path: str) -> tuple[bytes, TSNode, LanguageAdapter] | None:
+        """Return ``(source_bytes, root_node, adapter)`` for a path, or None."""
+        if rel_path not in self._entries:
+            adapter = self._forced or adapter_for_extension(Path(rel_path).suffix)
+            if adapter is None:
+                self._entries[rel_path] = None
+            else:
+                try:
+                    source = (self._repo_path / rel_path).read_bytes()
+                except OSError:
+                    self._entries[rel_path] = None
+                else:
+                    self._entries[rel_path] = (source, parse_cached(adapter, source), adapter)
+        return self._entries[rel_path]