codegraph-brain 0.6.0__py3-none-any.whl

cgis/core/models.py

@@ -0,0 +1,140 @@
+"""Basic atoms for ontology."""
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class NodeNamespace(StrEnum):
+    """Classifies whether a node belongs to the ingested repo, stdlib, or third-party."""
+
+    INTERNAL = "INTERNAL"
+    STDLIB = "STDLIB"
+    EXTERNAL = "EXTERNAL"
+    UNKNOWN = "UNKNOWN"
+
+
+VIRTUAL_FILE_PATH = "EXTERNAL"
+
+# Edge-target encoding conventions for raw (pre-resolution) targets.
+# These mirror the raw_call: / raw_dep: prefixes used by extractors and the
+# resolver, but apply to self-method dispatch and class-inheritance edges.
+SELF_PREFIX = "self."
+RAW_CLASS_PREFIX = "raw_class:"
+
+
+class NodeType(StrEnum):
+    """All possible node types in the Code Graph."""
+
+    # Structural (L0/L1)
+    FILE = "FILE"
+    MODULE = "MODULE"
+    CLASS = "CLASS"
+    FUNCTION = "FUNCTION"
+    METHOD = "METHOD"
+    VARIABLE = "VARIABLE"
+    IMPORT = "IMPORT"
+    EXPORT = "EXPORT"
+
+    # Runtime/Behavioral (L1/L2)
+    API_ENDPOINT = "API_ENDPOINT"
+    ROUTE_HANDLER = "ROUTE_HANDLER"
+    DB_TABLE = "DB_TABLE"
+    DB_QUERY = "DB_QUERY"
+    EVENT = "EVENT"
+
+    # Semantic (L3/Ontology)
+    DOMAIN_CONCEPT = "DOMAIN_CONCEPT"
+
+
+class EdgeType(StrEnum):
+    """All possible relationship types between nodes."""
+
+    # Structural
+    CONTAINS = "CONTAINS"
+    DECLARES = "DECLARES"
+    BELONGS_TO = "BELONGS_TO"
+    IMPORTS = "IMPORTS"
+    IMPORTS_SYMBOL = "IMPORTS_SYMBOL"
+    EXPORTS = "EXPORTS"
+    EXTENDS = "EXTENDS"
+
+    # Behavioral/Execution
+    CALLS = "CALLS"
+    INSTANTIATES = "INSTANTIATES"
+    REFERENCES = "REFERENCES"
+    USES = "USES"
+    ROUTES_TO = "ROUTES_TO"
+    TRIGGERS = "TRIGGERS"
+    EMITS = "EMITS"
+    CONSUMES = "CONSUMES"
+    DEPENDS_ON = "DEPENDS_ON"
+
+    # Semantic (The OWL-Lite Layer)
+    HANDLES = "HANDLES"
+    TRANSFORMS = "TRANSFORMS"
+    VALIDATES = "VALIDATES"
+    AUTHORIZES = "AUTHORIZES"
+    PERSISTS = "PERSISTS"
+    DOMAIN_DEPENDS_ON = "DOMAIN_DEPENDS_ON"
+
+
+class Node(BaseModel):
+    """
+    Represents a single semantic entity in the code graph.
+    The 'id' must be a Fully Qualified Name (FQN).
+    """
+
+    model_config = ConfigDict(frozen=True)  # Nodes should be immutable once created
+
+    id: str = Field(..., description="Fully Qualified Name (e.g., 'pkg.mod.Class.method')")
+    type: NodeType
+    name: str
+
+    # Location metadata
+    file_path: str
+    start_line: int
+    end_line: int
+
+    # Language context
+    language: str = Field(default="python")
+
+    # Semantic enrichment (L2/L3)
+    ontology_class: str | None = Field(
+        default=None, description="Mapping to the formal ontology class"
+    )
+    domains: list[str] = Field(default_factory=list)
+
+    # Classification
+    namespace: NodeNamespace = Field(default=NodeNamespace.INTERNAL)
+
+    # Reliability
+    confidence_score: float = Field(default=1.0, ge=0.0, le=1.0)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Edge(BaseModel):
+    """
+    Represents a directed relationship between two nodes.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(..., description="Unique edge identifier")
+    source: str = Field(..., description="Source Node FQN")
+    target: str = Field(..., description="Target Node FQN")
+    type: EdgeType
+
+    # Strength and certainty
+    weight: float = Field(
+        default=1.0,
+        ge=0.0,
+        description="Edge strength: 1.0 for plain edges, aggregated count (>1) on quotient edges",
+    )
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
+
+    # Contextual info (e.g., the code snippet or line number of the call)
+    context: str | None = None
+    file_path: str | None = None
+    line_number: int | None = None

cgis/extractors/_python_ast.py

@@ -0,0 +1,194 @@
+"""Pure AST naming and path helpers shared by the Python extractor handlers.
+
+This is a leaf module: it imports only tree-sitter types and holds no state.
+Every function is pure (its output depends solely on its arguments), which lets
+the extractor's handler collaborators depend on it without import cycles.
+"""
+
+from tree_sitter import Node as BaseNode
+
+PYTHON_LANG = "python"
+
+
+def resolve_relative_module(
+    module_fqn: str, leading_dots: int, relative_path: str, is_package: bool = False
+) -> str:
+    """Resolve a relative import to an absolute FQN.
+
+    Args:
+        module_fqn: FQN of the current file, e.g. "src.cgis.extractors.python_extractor"
+        leading_dots: number of leading dots in the import statement
+        relative_path: module path after the dots, e.g. "core" for "from ..core import x"
+        is_package: True when the importing file is a package ``__init__.py``. Its
+            FQN already had the ``/__init__`` suffix stripped, so it IS the
+            package — one leading dot refers to the package itself and must trim
+            one fewer segment than a regular module would.
+
+    Returns "src.cgis.core" for leading_dots=2, relative_path="core" in the example above.
+    """
+    segments = module_fqn.split(".")
+    effective_dots = leading_dots - 1 if is_package and leading_dots > 0 else leading_dots
+    trim = min(effective_dots, len(segments))
+    if trim == 0:
+        # leading_dots == 0: not a relative import — return the module unchanged.
+        # (Guards against `segments[:-0]` == `[]`, which would drop the whole FQN.)
+        base = module_fqn
+    elif trim == len(segments):
+        base = ""
+    else:
+        base = ".".join(segments[:-trim])
+    if relative_path:
+        return f"{base}.{relative_path}" if base else relative_path
+    return base
+
+
+def file_path_to_module_fqn(file_path: str, source_root: str | None = None) -> str:
+    """Convert a file path to a dot-separated module namespace.
+
+    Examples:
+        src/cgis/pipeline.py  -> src.cgis.pipeline
+        src/cgis/__init__.py  -> src.cgis
+        /abs/path/mod.py      -> abs.path.mod
+        C:\\path\\to\\mod.py  -> path.to.mod
+
+        With source_root="src":
+        src/cgis/pipeline.py  -> cgis.pipeline
+    """
+    clean = file_path
+    # Strip Windows drive letter (e.g. "C:") before normalising slashes
+    if len(clean) >= 2 and clean[1] == ":" and clean[0].isalpha():
+        clean = clean[2:]
+    clean = clean.replace("\\", "/").lstrip("/")
+    if source_root:
+        # removeprefix("./") so CI-style roots ("cgis ingest ./src") strip too
+        sr = source_root.replace("\\", "/").removeprefix("./").strip("/") + "/"
+        if clean.startswith(sr):
+            clean = clean[len(sr) :]
+    if clean.endswith(".py"):
+        clean = clean[:-3]
+    if clean.endswith("/__init__"):
+        clean = clean[:-9]
+    return clean.replace("/", ".")
+
+
+def extract_node_name(node: BaseNode | None, code_bytes: bytes) -> str:
+    """Extract node name from name node using byte slicing."""
+    if node:
+        start, end = node.start_byte, node.end_byte
+        return code_bytes[start:end].decode("utf8", errors="replace")
+    return "unknown"
+
+
+def get_identifier(node: BaseNode, code_bytes: bytes) -> str:
+    """Extract name from AST node using byte slicing."""
+    if node.type == "identifier":
+        start, end = node.start_byte, node.end_byte
+        return code_bytes[start:end].decode("utf8", errors="replace")
+    if node.type == "parenthesized_expression":
+        for child in node.children:
+            if child.type not in ("(", ")", "comment"):
+                return get_identifier(child, code_bytes)
+    if node.type in ("attribute", "call", "subscript"):
+        return extract_nested_name(node, code_bytes)
+    return "unknown"
+
+
+def extract_object_attr_name(node: BaseNode, code_bytes: bytes) -> str:
+    """Extract identifier from object/attribute nodes."""
+    obj_node = node.child_by_field_name("object")
+    attr_node = node.child_by_field_name("attribute")
+    if obj_node and attr_node:
+        obj_id = get_identifier(obj_node, code_bytes)
+        attr_id = get_identifier(attr_node, code_bytes)
+        defined = obj_id != "unknown" and attr_id != "unknown"
+        return f"{obj_id}.{attr_id}" if defined else "unknown"
+    if attr_node:
+        return get_identifier(attr_node, code_bytes)
+    return "unknown"
+
+
+def extract_nested_name(node: BaseNode, code_bytes: bytes) -> str:
+    """Extract nested identifier from attribute/call/subscript nodes."""
+    if node.type == "attribute":
+        return extract_object_attr_name(node, code_bytes)
+    if node.type == "call":
+        func_node = node.child_by_field_name("function")
+        if func_node:
+            return get_identifier(func_node, code_bytes)
+    elif node.type == "subscript":
+        value_node = node.child_by_field_name("value")
+        if value_node:
+            return get_identifier(value_node, code_bytes)
+    return "unknown"
+
+
+def get_fqn_prefix(node: BaseNode, code_bytes: bytes) -> str | None:
+    """Traverse up to find class and function names, returning them joined by dots."""
+    parts = []
+    curr = node.parent
+    extract_types = ("class_definition", "function_definition", "async_function_definition")
+    while curr:
+        if curr.type in extract_types:
+            name_node = curr.child_by_field_name("name")
+            parts.append(extract_node_name(name_node, code_bytes))
+        curr = curr.parent
+    return ".".join(reversed(parts)) if parts else None
+
+
+def get_id(node: BaseNode, code_bytes: bytes, file_path: str, source_root: str | None) -> str:
+    """Generate a fully qualified function/method ID including class/function context."""
+    name = node.child_by_field_name("name")
+    node_name = extract_node_name(name, code_bytes)
+    prefix = get_fqn_prefix(node, code_bytes)
+    module = file_path_to_module_fqn(file_path, source_root)
+    if not module:
+        return f"{prefix}.{node_name}" if prefix else node_name
+    return f"{module}.{prefix}.{node_name}" if prefix else f"{module}.{node_name}"
+
+
+def is_method(node: BaseNode) -> bool:
+    """Check if a function node is a method (defined inside a class)."""
+    curr = node.parent
+    while curr:
+        if curr.type == "class_definition":
+            return True
+        if curr.type in ("function_definition", "async_function_definition"):
+            return False
+        curr = curr.parent
+    return False
+
+
+def is_module_level_assignment(
+    node: BaseNode, code_bytes: bytes, current_func_node: object | None
+) -> bool:
+    """True for assignments at true module level (not function, not class body)."""
+    return (
+        node.type == "assignment"
+        and current_func_node is None
+        and get_fqn_prefix(node, code_bytes) is None
+    )
+
+
+def get_decorator_name(decorator_node: BaseNode, code_bytes: bytes) -> str | None:
+    """Return the decorator's callable name from a single decorator node, or None.
+
+    Skips the leading '@' token and any comments; passes the first real expression
+    node to get_identifier, which handles identifier / attribute / call / PEP-614
+    parenthesized expressions.
+    """
+    for inner in decorator_node.children:
+        if inner.type not in ("@", "comment"):
+            name = get_identifier(inner, code_bytes)
+            return name if name != "unknown" else None
+    return None
+
+
+def extract_decorator_names(node: BaseNode, code_bytes: bytes) -> list[str]:
+    """Extract decorator names from a decorated_definition node."""
+    names: list[str] = []
+    for child in node.children:
+        if child.type == "decorator":
+            name = get_decorator_name(child, code_bytes)
+            if name:
+                names.append(name)
+    return names

cgis/extractors/_python_classes.py

@@ -0,0 +1,126 @@
+"""Class-definition handling for the Python extractor.
+
+Emits CLASS nodes plus their CONTAINS/EXTENDS structural edges and the
+abstract-class / metaclass metadata.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from tree_sitter import Node as BaseNode
+
+from cgis.core.models import Edge, EdgeType, Node, NodeType
+from cgis.extractors._python_ast import (
+    PYTHON_LANG,
+    extract_node_name,
+    get_id,
+    get_identifier,
+)
+
+_ABC_NAMES: frozenset[str] = frozenset({"ABC", "ABCMeta"})
+
+
+class ClassHandler:
+    """Extracts CLASS nodes and their inheritance metadata from class AST nodes."""
+
+    def __init__(self, pick_source_root: Callable[[str], str | None]) -> None:
+        """Store the per-file source-root picker used for FQN construction."""
+        self._pick_source_root = pick_source_root
+
+    def process_class_node(
+        self,
+        node: BaseNode,
+        code_bytes: bytes,
+        file_path: str,
+        nodes: list[Node],
+        edges: list[Edge],
+        module_fqn: str,
+        decorators: list[str] | None = None,
+    ) -> None:
+        """Process class definition node."""
+        child = node.child_by_field_name("name")
+        node_id = get_id(node, code_bytes, file_path, self._pick_source_root(file_path))
+        node_name = extract_node_name(child, code_bytes)
+
+        superclass_names = self._collect_superclasses(node, node_id, file_path, code_bytes, edges)
+
+        metadata: dict[str, Any] = {}
+        if decorators:
+            metadata["decorators"] = decorators
+        if self._is_abstract_class(superclass_names, decorators):
+            metadata["is_abstract"] = True
+
+        nodes.append(
+            Node(
+                id=node_id,
+                type=NodeType.CLASS,
+                name=node_name,
+                file_path=file_path,
+                start_line=node.start_point.row + 1,
+                end_line=node.end_point.row + 1,
+                language=PYTHON_LANG,
+                metadata=metadata,
+            )
+        )
+
+        parts = node_id.rsplit(".", maxsplit=1)
+        parent_fqn = parts[0] if len(parts) > 1 else module_fqn
+        edges.append(
+            Edge(
+                id=f"{parent_fqn}:structural:{node_id}",
+                type=EdgeType.CONTAINS,
+                source=parent_fqn,
+                target=node_id,
+                confidence=1.0,
+                file_path=file_path,
+            )
+        )
+
+    def _collect_superclasses(
+        self,
+        node: BaseNode,
+        node_id: str,
+        file_path: str,
+        code_bytes: bytes,
+        edges: list[Edge],
+    ) -> list[str]:
+        """Collect superclass names and emit EXTENDS edges for a class definition node."""
+        names: list[str] = []
+        superclasses_node = node.child_by_field_name("superclasses")
+        if not superclasses_node:
+            return names
+        for sc in superclasses_node.children:
+            if sc.type in ("identifier", "attribute", "subscript"):
+                sc_name = get_identifier(sc, code_bytes)
+                if sc_name != "unknown":
+                    names.append(sc_name)
+                    edges.append(
+                        Edge(
+                            id=f"{node_id}:extends:{sc_name}",
+                            type=EdgeType.EXTENDS,
+                            source=node_id,
+                            target=f"raw_class:{sc_name}",
+                            confidence=1.0,
+                            file_path=file_path,
+                        )
+                    )
+            elif sc.type == "keyword_argument":
+                meta_name = self._extract_metaclass_name(sc, code_bytes)
+                if meta_name:
+                    names.append(meta_name)
+        return names
+
+    @staticmethod
+    def _is_abstract_class(superclass_names: list[str], decorators: list[str] | None) -> bool:
+        """Return True if class should be marked abstract (ABC/ABCMeta in bases or decorators)."""
+        candidates = (*superclass_names, *(decorators or []))
+        return any(n in _ABC_NAMES or n.rpartition(".")[-1] in _ABC_NAMES for n in candidates)
+
+    def _extract_metaclass_name(self, node: BaseNode, code_bytes: bytes) -> str | None:
+        """Return the metaclass name from a keyword_argument node like `metaclass=ABCMeta`."""
+        name_node = node.child_by_field_name("name")
+        value_node = node.child_by_field_name("value")
+        if name_node and value_node and get_identifier(name_node, code_bytes) == "metaclass":
+            meta_name = get_identifier(value_node, code_bytes)
+            return meta_name if meta_name != "unknown" else None
+        return None