graphlens-python 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

graphlens_python/__init__.py

@@ -1,5 +1,6 @@
 """Python language adapter for graphlens."""
 
 from graphlens_python._adapter import PythonAdapter
+from graphlens_python._resolver import TyResolver
 
-__all__ = ["PythonAdapter"]
+__all__ = ["PythonAdapter", "TyResolver"]

graphlens_python/_adapter.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 from graphlens import (
@@ -13,7 +14,7 @@ from graphlens import (
     Relation,
     RelationKind,
 )
-from graphlens.utils import make_node_id
+from graphlens.utils import SpanIndex, make_node_id
 from graphlens.utils.roots import filter_nested_root_files
 
 from graphlens_python._deps import (
@@ -29,22 +30,34 @@ from graphlens_python._project_detector import (
     find_python_roots,
     is_python_project,
 )
+from graphlens_python._resolver import TyResolver
 from graphlens_python._visitor import (
     ImportClassifier,
+    OccurrenceRef,
     PythonASTVisitor,
     VisitorContext,
     parse_python,
 )
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
-    from graphlens.contracts import DependencyFileParser
+    from graphlens.contracts import DependencyFileParser, SymbolResolver
 
 logger = logging.getLogger("graphlens_python")
 
 _STDLIB = get_stdlib_names()
 
+# ---------------------------------------------------------------------------
+# Role → RelationKind mapping
+# ---------------------------------------------------------------------------
+
+_ROLE_TO_KIND: dict[str, RelationKind] = {
+    "call": RelationKind.CALLS,
+    "base": RelationKind.INHERITS_FROM,
+    "annotation": RelationKind.HAS_TYPE,
+    "read": RelationKind.REFERENCES,
+    "write": RelationKind.REFERENCES,
+}
+
 
 class PythonAdapter(LanguageAdapter):
     """Language adapter for Python projects."""
@@ -52,6 +65,7 @@ class PythonAdapter(LanguageAdapter):
     def __init__(
         self,
         dep_parsers: list[DependencyFileParser] | None = None,
+        resolver: SymbolResolver | None = None,
     ) -> None:
         """
         Initialize the Python adapter.
@@ -63,6 +77,11 @@ class PythonAdapter(LanguageAdapter):
                 non-standard package managers (poetry-only setup,
                 pip-tools, pnpm, etc.).
                 Defaults to ``PYTHON_DEFAULT_DEP_PARSERS``.
+            resolver: symbol resolver used for cross-file resolution of
+                calls, references, annotations, and base classes.
+                Defaults to ``TyResolver`` (requires ``ty`` in PATH).
+                Pass ``None`` to disable resolution, or inject a custom
+                ``SymbolResolver`` subclass.
 
         """
         self._dep_parsers = (
@@ -70,6 +89,9 @@ class PythonAdapter(LanguageAdapter):
             if dep_parsers is not None
             else PYTHON_DEFAULT_DEP_PARSERS
         )
+        self._resolver = (
+            resolver if resolver is not None else TyResolver()
+        )
 
     def language(self) -> str:
         return "python"
@@ -94,6 +116,7 @@ class PythonAdapter(LanguageAdapter):
                 project_root,
                 files,
                 self._dep_parsers,
+                self._resolver,
             )
         else:
             py_roots = find_python_roots(project_root)
@@ -110,17 +133,19 @@ class PythonAdapter(LanguageAdapter):
                     py_root,
                     root_files,
                     self._dep_parsers,
+                    self._resolver,
                 )
 
         return graph
 
 
-def _analyze_root(
+def _analyze_root(  # noqa: PLR0913, PLR0915
     graph: GraphLens,
     project_root: Path,
     py_root: Path,
     files: list[Path],
     dep_parsers: list[DependencyFileParser],
+    resolver: SymbolResolver,
 ) -> None:
     """Analyze one Python project root and populate graph in-place."""
     project_name = detect_project_name(py_root)
@@ -164,6 +189,7 @@ def _analyze_root(
         )
 
     modules: dict[str, str] = {}
+    all_occurrences: list[tuple[str, OccurrenceRef]] = []
 
     for file in files:
         source_root = (
@@ -232,6 +258,16 @@ def _analyze_root(
             ctx, graph, file_id, source_bytes, classifier
         )
         visitor.visit(tree.root_node)
+        all_occurrences.extend(
+            (visitor.abs_file_path, o) for o in visitor.occurrences
+        )
+
+    # Resolution pass: bind occurrences to real nodes or EXTERNAL_SYMBOL
+    span_index = SpanIndex.from_graph(graph)
+    resolver.prepare(py_root, files)
+    _resolve_occurrences(
+        graph, project_name, resolver, span_index, all_occurrences
+    )
 
     # PROJECT --CONTAINS--> top-level modules
     top_level = {qn: mid for qn, mid in modules.items() if "." not in qn}
@@ -245,6 +281,107 @@ def _analyze_root(
         )
 
 
+def _ensure_external_symbol(
+    graph: GraphLens, project_name: str, qname: str, origin: str
+) -> str:
+    """
+    Return the id of an EXTERNAL_SYMBOL node for ``qname``.
+
+    Creates the node if it does not yet exist in ``graph``.
+
+    Args:
+        graph: the graph to update in-place.
+        project_name: used as the namespace for ``make_node_id``.
+        qname: fully-qualified name of the external symbol.
+        origin: one of ``"stdlib"``, ``"third_party"``, ``"unknown"``,
+            or ``"internal"`` (fallback when the module node is absent).
+
+    Returns:
+        The node id of the EXTERNAL_SYMBOL.
+
+    """
+    sym_id = make_node_id(
+        project_name, qname, NodeKind.EXTERNAL_SYMBOL.value
+    )
+    if sym_id not in graph.nodes:
+        graph.add_node(
+            Node(
+                id=sym_id,
+                kind=NodeKind.EXTERNAL_SYMBOL,
+                qualified_name=qname,
+                name=qname.rsplit(".", maxsplit=1)[-1],
+                metadata={"origin": origin},
+            )
+        )
+    return sym_id
+
+
+def _resolve_occurrences(
+    graph: GraphLens,
+    project_name: str,
+    resolver: SymbolResolver,
+    span_index: SpanIndex,
+    occurrences: list[tuple[str, OccurrenceRef]],
+) -> None:
+    """
+    Resolve all accumulated occurrences and emit edges.
+
+    For each ``(abs_path, occ)`` pair:
+
+    1. Ask the resolver for the definition site.
+    2. If the definition is internal, look up the target node id via
+       ``span_index.at()``.
+    3. If the node is not found (or origin is external), create/reuse an
+       ``EXTERNAL_SYMBOL`` fallback node.
+    4. Emit a ``Relation`` of the appropriate kind, with span metadata
+       and, for read/write occurrences, an ``access`` key.
+
+    Args:
+        graph: the graph to update in-place.
+        project_name: namespace used for EXTERNAL_SYMBOL node ids.
+        resolver: the symbol resolver that was already ``prepare()``d.
+        span_index: pre-built index of node spans from ``graph``.
+        occurrences: list of ``(absolute_file_path, OccurrenceRef)`` pairs
+            collected during the file-visit loop.
+
+    """
+    for abs_path, occ in occurrences:
+        rel_kind = _ROLE_TO_KIND[occ.role]
+        ref = resolver.definition_at(Path(abs_path), occ.line, occ.col)
+        if ref is None:
+            continue
+        target_id: str | None = None
+        if ref.origin == "internal" and ref.file_path is not None:
+            target_id = span_index.at(
+                str(ref.file_path), ref.line, ref.col
+            )
+        if target_id is None:
+            # When full_name is absent, use a position-qualified key so that
+            # distinct unresolved sites don't collapse into the same node.
+            fallback_qname = (
+                ref.full_name
+                if ref.full_name
+                else f"{occ.role}@{occ.line}:{occ.col}"
+            )
+            target_id = _ensure_external_symbol(
+                graph,
+                project_name,
+                fallback_qname,
+                ref.origin,
+            )
+        metadata: dict[str, object] = {"span": occ.span}
+        if occ.role in ("read", "write"):
+            metadata["access"] = occ.role
+        graph.add_relation(
+            Relation(
+                source_id=occ.enclosing_id,
+                target_id=target_id,
+                kind=rel_kind,
+                metadata=metadata,
+            )
+        )
+
+
 def _find_source_root_for(file: Path, source_roots: list[Path]) -> Path | None:
     for root in source_roots:
         try:

graphlens_python/_module_resolver.py

@@ -17,7 +17,7 @@ def find_source_roots(project_root: Path, files: list[Path]) -> list[Path]:
         and any(files)
         and any(f.is_relative_to(src) for f in files)
     ):
-        return [src]
+        return [src, project_root]
     return [project_root]
 
 

graphlens_python/_resolver.py

@@ -0,0 +1,392 @@
+"""TyResolver — LSP-backed Python symbol resolver using ``ty server``."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import select
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+from urllib.parse import unquote
+
+from graphlens.contracts import Occurrence, ResolvedRef, SymbolResolver
+
+logger = logging.getLogger("graphlens_python")
+
+
+def _uri_to_path(uri: str) -> Path | None:
+    """Convert a ``file://`` URI to a ``Path``; None for other schemes."""
+    if not uri.startswith("file://"):
+        return None
+    return Path(unquote(uri[7:]))
+
+
+class _TyLspClient:
+    """Minimal synchronous LSP JSON-RPC client for ``ty server`` (stdio)."""
+
+    def __init__(self, project_root: Path) -> None:
+        ty_bin = shutil.which("ty") or "ty"
+        self._proc: subprocess.Popen = subprocess.Popen(  # type: ignore[type-arg]
+            [ty_bin, "server"],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            cwd=str(project_root),
+        )
+        self._next_id = 0
+        self._opened_uris: set[str] = set()
+        self._initialize(project_root)
+
+    # ------------------------------------------------------------------
+    # Transport
+    # ------------------------------------------------------------------
+
+    def _write(self, msg: dict) -> None:  # type: ignore[type-arg]
+        if self._proc.stdin is None or self._proc.poll() is not None:
+            return
+        body = json.dumps(msg, separators=(",", ":")).encode()
+        header = f"Content-Length: {len(body)}\r\n\r\n".encode()
+        try:
+            self._proc.stdin.write(header + body)
+            self._proc.stdin.flush()
+        except OSError:
+            pass
+
+    def _read_one(self, timeout: float = 30.0) -> dict | None:  # type: ignore[type-arg]
+        """Read one LSP message, waiting at most *timeout* seconds."""
+        if self._proc.stdout is None or self._proc.poll() is not None:
+            return None
+        ready, _, _ = select.select([self._proc.stdout], [], [], timeout)
+        if not ready:
+            logger.warning("ty server timed out after %.0fs", timeout)
+            return None
+        content_length = 0
+        try:
+            while True:
+                raw = self._proc.stdout.readline()
+                if not raw:
+                    return None  # EOF — server exited
+                stripped = raw.strip()
+                if not stripped:
+                    break  # blank line ends LSP headers
+                if stripped.lower().startswith(b"content-length:"):
+                    content_length = int(stripped.split(b":", 1)[1].strip())
+            if not content_length:
+                return {}
+            body = self._proc.stdout.read(content_length)
+            return json.loads(body) if body else {}
+        except (OSError, ValueError, json.JSONDecodeError) as exc:
+            logger.debug("ty server read error: %s", exc)
+            return None
+
+    def _recv_response(
+        self, expected_id: int, timeout: float = 30.0
+    ) -> dict | None:  # type: ignore[type-arg]
+        """
+        Consume messages until the one with *expected_id* arrives.
+
+        Server-to-client requests (have both ``id`` and ``method``) receive a
+        MethodNotFound error so ty does not stall waiting for a reply.
+        Notifications (no ``id``) are silently discarded.
+        """
+        for _ in range(500):  # cap to prevent accidental infinite loop
+            msg = self._read_one(timeout=timeout)
+            if msg is None:
+                return None
+            msg_id = msg.get("id")
+            if "method" in msg:
+                # Server-to-client request — reply with error to unblock ty
+                if msg_id is not None:
+                    self._write(
+                        {
+                            "jsonrpc": "2.0",
+                            "id": msg_id,
+                            "error": {
+                                "code": -32601,
+                                "message": "Method not found",
+                            },
+                        }
+                    )
+                continue  # notification or server request — skip
+            if msg_id == expected_id:
+                return msg
+        logger.warning("ty server did not respond to request %d", expected_id)
+        return None
+
+    def _request(
+        self, method: str, params: object, timeout: float = 30.0
+    ) -> dict | None:  # type: ignore[type-arg]
+        self._next_id += 1
+        mid = self._next_id
+        self._write(
+            {"jsonrpc": "2.0", "id": mid, "method": method, "params": params}
+        )
+        return self._recv_response(mid, timeout=timeout)
+
+    def _notify(self, method: str, params: object) -> None:
+        self._write({"jsonrpc": "2.0", "method": method, "params": params})
+
+    # ------------------------------------------------------------------
+    # LSP lifecycle
+    # ------------------------------------------------------------------
+
+    def _initialize(self, project_root: Path) -> None:
+        resp = self._request(
+            "initialize",
+            {
+                "processId": os.getpid(),
+                "rootUri": project_root.as_uri(),
+                "capabilities": {
+                    "textDocument": {
+                        "definition": {"dynamicRegistration": False},
+                        "references": {"dynamicRegistration": False},
+                    },
+                },
+                "workspaceFolders": [
+                    {"uri": project_root.as_uri(), "name": project_root.name},
+                ],
+            },
+        )
+        if resp is not None:
+            self._notify("initialized", {})
+
+    # ------------------------------------------------------------------
+    # File management
+    # ------------------------------------------------------------------
+
+    def open_file(self, file: Path) -> str:
+        """Open *file* in ty (idempotent) and return its ``file://`` URI."""
+        uri = file.as_uri()
+        if uri not in self._opened_uris:
+            self._opened_uris.add(uri)
+            try:
+                text = file.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                text = ""
+            self._notify(
+                "textDocument/didOpen",
+                {
+                    "textDocument": {
+                        "uri": uri,
+                        "languageId": "python",
+                        "version": 1,
+                        "text": text,
+                    },
+                },
+            )
+            # Wait for ty to finish analyzing the file before returning.
+            # Without this, definition queries sent immediately after didOpen
+            # block for 30+ seconds until ty's background analysis completes.
+            self._drain_for_diagnostics(uri)
+        return uri
+
+    def _drain_for_diagnostics(self, uri: str, timeout: float = 5.0) -> None:
+        """Drain messages until publishDiagnostics for *uri* (or timeout)."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            remaining = deadline - time.monotonic()
+            msg = self._read_one(timeout=min(remaining, 1.0))
+            if msg is None:
+                break
+            method = msg.get("method", "")
+            msg_id = msg.get("id")
+            if method and msg_id is not None:
+                # Server-to-client request — reply with error to unblock ty
+                self._write(
+                    {
+                        "jsonrpc": "2.0",
+                        "id": msg_id,
+                        "error": {"code": -32601, "message": "MethodNotFound"},
+                    }
+                )
+            elif (
+                method == "textDocument/publishDiagnostics"
+                and msg.get("params", {}).get("uri") == uri
+            ):
+                return  # ty finished analyzing this file
+
+    # ------------------------------------------------------------------
+    # Queries
+    # ------------------------------------------------------------------
+
+    def definition(
+        self, file: Path, line: int, col: int
+    ) -> dict | None:  # type: ignore[type-arg]
+        """Return the first LSP ``Location`` for 1-based *(line, col)*."""
+        uri = self.open_file(file)
+        resp = self._request(
+            "textDocument/definition",
+            {
+                "textDocument": {"uri": uri},
+                "position": {"line": line - 1, "character": col - 1},
+            },
+            timeout=30.0,
+        )
+        if resp is None:
+            return None
+        result = resp.get("result")
+        if not result:
+            return None
+        return result[0] if isinstance(result, list) else result
+
+    def references(
+        self, file: Path, line: int, col: int
+    ) -> list[dict]:  # type: ignore[type-arg]
+        """Return LSP ``Location`` list for 1-based *(line, col)*."""
+        uri = self.open_file(file)
+        resp = self._request(
+            "textDocument/references",
+            {
+                "textDocument": {"uri": uri},
+                "position": {"line": line - 1, "character": col - 1},
+                "context": {"includeDeclaration": False},
+            },
+            timeout=30.0,
+        )
+        if resp is None:
+            return []
+        result = resp.get("result")
+        return result if isinstance(result, list) else []
+
+    # ------------------------------------------------------------------
+    # Cleanup
+    # ------------------------------------------------------------------
+
+    def shutdown(self) -> None:
+        if self._proc.poll() is not None:
+            return
+        try:
+            self._request("shutdown", None)
+            self._notify("exit", None)
+            self._proc.wait(timeout=5)
+        except Exception:
+            with contextlib.suppress(Exception):
+                self._proc.kill()
+
+    def __del__(self) -> None:
+        with contextlib.suppress(Exception):
+            self.shutdown()
+
+
+class TyResolver(SymbolResolver):
+    """
+    Resolve Python symbols via ``ty server`` (Astral ty, Rust-based).
+
+    Spawns one ``ty server`` LSP subprocess per :meth:`prepare` call.
+    Files are opened lazily on the first ``definition_at`` query — bulk
+    pre-opening is intentionally avoided because sending hundreds of
+    ``textDocument/didOpen`` notifications at once fills ty's stdin buffer
+    and deadlocks on large projects.
+
+    Requires ``ty`` to be in ``PATH``. Install from
+    https://docs.astral.sh/ty/.  If ``ty`` is not found, :meth:`prepare`
+    logs a warning and all queries return ``None``/``[]`` (the structural
+    graph is still produced correctly).
+
+    All methods return ``None``/``[]`` on any error — never raise.
+    ``infer_type_at`` always returns ``None`` (type inference via LSP hover
+    would require parsing ty's markdown output).
+    """
+
+    def __init__(self) -> None:
+        self._client: _TyLspClient | None = None
+        self._root: Path | None = None
+
+    def prepare(self, project_root: Path, files: list[Path]) -> None:  # noqa: ARG002
+        if self._client is not None:
+            with contextlib.suppress(Exception):
+                self._client.shutdown()
+            self._client = None
+        self._root = project_root
+        try:
+            self._client = _TyLspClient(project_root)
+        except Exception:
+            logger.warning("Failed to start ty server for %s", project_root)
+            self._client = None
+
+    def definition_at(
+        self, file: Path, line: int, col: int
+    ) -> ResolvedRef | None:
+        if self._client is None:
+            return None
+        try:
+            loc = self._client.definition(file, line, col)
+        except Exception:
+            return None
+        if loc is None:
+            return None
+        return self._loc_to_ref(loc)
+
+    def infer_type_at(
+        self, file: Path, line: int, col: int  # noqa: ARG002
+    ) -> ResolvedRef | None:
+        return None
+
+    def references_to(
+        self, file: Path, line: int, col: int
+    ) -> list[Occurrence]:
+        if self._client is None:
+            return []
+        try:
+            locs = self._client.references(file, line, col)
+        except Exception:
+            return []
+        out: list[Occurrence] = []
+        for loc in locs:
+            fp = _uri_to_path(loc.get("uri", ""))
+            if fp is None:
+                continue
+            start = loc.get("range", {}).get("start", {})
+            out.append(
+                Occurrence(
+                    file_path=fp,
+                    line=start.get("line", 0) + 1,
+                    col=start.get("character", 0) + 1,
+                    is_definition=False,
+                    access="unknown",
+                )
+            )
+        return out
+
+    def _loc_to_ref(self, loc: dict) -> ResolvedRef:  # type: ignore[type-arg]
+        fp = _uri_to_path(loc.get("uri", ""))
+        start = loc.get("range", {}).get("start", {})
+        return ResolvedRef(
+            full_name="",
+            file_path=fp,
+            line=start.get("line", 0) + 1,
+            col=start.get("character", 0) + 1,
+            kind="",
+            origin=self._classify(fp),
+        )
+
+    def _classify(self, file_path: Path | None) -> str:
+        if file_path is None:
+            return "stdlib"
+        parts = file_path.parts
+        if "typeshed" in parts:
+            return "stdlib"
+        if "site-packages" in parts or "dist-packages" in parts:
+            return "third_party"
+        if self._root is not None:
+            with contextlib.suppress(ValueError):
+                file_path.relative_to(self._root)
+                return "internal"
+        # Resolve symlinks before comparing: uv manages Pythons via symlinks
+        # (cpython-3.13-... → cpython-3.13.5-...) and ty returns real paths.
+        real = file_path.resolve()
+        base = Path(sys.base_prefix).resolve()
+        with contextlib.suppress(ValueError):
+            real.relative_to(base)
+            return "stdlib"
+        return "unknown"
+
+    def __del__(self) -> None:
+        if self._client is not None:
+            with contextlib.suppress(Exception):
+                self._client.shutdown()

graphlens_python/_visitor.py

@@ -26,6 +26,33 @@ if TYPE_CHECKING:
 logger = logging.getLogger("graphlens_python")
 
 _PY_LANGUAGE = Language(tspython.language())
+
+
+# ---------------------------------------------------------------------------
+# Occurrence reference (use-site record)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class OccurrenceRef:
+    """
+    A use-site that the resolver will bind to a definition.
+
+    Coordinates are 1-based (matching Span convention).
+
+    Roles:
+      ``call``       — call-site of a function/method
+      ``read``       — identifier read on the right-hand side
+      ``write``      — assignment target
+      ``annotation`` — type annotation or TypeAlias RHS
+      ``base``       — class base in the heritage list
+    """
+
+    role: str
+    line: int
+    col: int
+    enclosing_id: str
+    span: Span
 _parser = Parser(_PY_LANGUAGE)
 
 
@@ -109,6 +136,9 @@ class PythonASTVisitor:
         self._container_stack: list[str] = [file_node_id]
         # Stack of NodeKind to know if we're inside a class
         self._kind_stack: list[NodeKind] = [NodeKind.FILE]
+        # Occurrence use-sites collected during this visit
+        self.occurrences: list[OccurrenceRef] = []
+        self.abs_file_path: str = str(ctx.file_path)
 
     # -------------------------------------------------------------------------
     # Dispatch
@@ -133,9 +163,8 @@ class PythonASTVisitor:
         self._visit_children(node)
 
     def _visit_decorated_definition(self, node: TSNode) -> None:
-        decorators = [
-            _decorator_name(c) for c in node.children if c.type == "decorator"
-        ]
+        decorator_nodes = [c for c in node.children if c.type == "decorator"]
+        decorators = [_decorator_name(c) for c in decorator_nodes]
         inner = next(
             (
                 c
@@ -147,15 +176,15 @@ class PythonASTVisitor:
         if inner is None:
             return
         if inner.type == "class_definition":
-            self._handle_class(inner, decorators)
+            self._handle_class(inner, decorators, decorator_nodes)
         else:
-            self._handle_function(inner, decorators)
+            self._handle_function(inner, decorators, decorator_nodes)
 
     def _visit_class_definition(self, node: TSNode) -> None:
-        self._handle_class(node, decorators=[])
+        self._handle_class(node, decorators=[], decorator_nodes=[])
 
     def _visit_function_definition(self, node: TSNode) -> None:
-        self._handle_function(node, decorators=[])
+        self._handle_function(node, decorators=[], decorator_nodes=[])
 
     def _visit_import_statement(self, node: TSNode) -> None:
         # import X  /  import X.Y  /  import X as Y
@@ -275,7 +304,12 @@ class PythonASTVisitor:
     # Class and function handlers
     # -------------------------------------------------------------------------
 
-    def _handle_class(self, node: TSNode, decorators: list[str]) -> None:
+    def _handle_class(
+        self,
+        node: TSNode,
+        decorators: list[str],
+        decorator_nodes: list[TSNode] | None = None,
+    ) -> None:
         name_node = next(
             (c for c in node.children if c.type == "identifier"), None
         )
@@ -296,6 +330,10 @@ class PythonASTVisitor:
                     bases.append(base_name)
 
         is_abstract = "ABC" in bases or "ABCMeta" in bases
+        _enum_names = {"Enum", "IntEnum", "StrEnum", "Flag", "IntFlag"}
+        is_enum = any(
+            b.rsplit(".", 1)[-1] in _enum_names for b in bases
+        )
         class_node = self._make_node(
             NodeKind.CLASS,
             qname,
@@ -305,20 +343,24 @@ class PythonASTVisitor:
                 "decorators": decorators,
                 "bases": bases,
                 "is_abstract": is_abstract,
+                "is_enum": is_enum,
             },
+            name_node=name_node,
         )
         self._add_node_with_relation(class_node, RelationKind.DECLARES)
 
-        # INHERITS_FROM
-        for base_name in bases:
-            sym = self._get_or_create_external_symbol(base_name)
-            self._graph.add_relation(
-                Relation(
-                    source_id=class_node.id,
-                    target_id=sym.id,
-                    kind=RelationKind.INHERITS_FROM,
-                )
-            )
+        # Decorator arguments used as values (e.g. @deco(handler)).
+        self._scan_decorators(decorator_nodes, class_node.id)
+
+        # Record base occurrences (resolver emits INHERITS_FROM later)
+        if arg_list:
+            for c in arg_list.children:
+                if c.type in ("identifier", "attribute"):
+                    base_name_node = _first_identifier(c)
+                    if base_name_node is not None:
+                        self._record_occurrence(
+                            "base", base_name_node, class_node.id
+                        )
 
         self._push(qname, class_node.id, NodeKind.CLASS)
         body = next((c for c in node.children if c.type == "block"), None)
@@ -326,7 +368,12 @@ class PythonASTVisitor:
             self._visit_children(body)
         self._pop()
 
-    def _handle_function(self, node: TSNode, decorators: list[str]) -> None:
+    def _handle_function(
+        self,
+        node: TSNode,
+        decorators: list[str],
+        decorator_nodes: list[TSNode] | None = None,
+    ) -> None:
         is_async = any(c.type == "async" for c in node.children)
         parent_kind = self._kind_stack[-1]
         kind = (
@@ -368,9 +415,18 @@ class PythonASTVisitor:
                 "is_property": "property" in decorators,
                 "return_annotation": return_annotation,
             },
+            name_node=name_node,
         )
         self._add_node_with_relation(func_node, RelationKind.DECLARES)
 
+        # Decorator arguments used as values (e.g. @deco(handler)).
+        self._scan_decorators(decorator_nodes, func_node.id)
+
+        # Record return annotation occurrence
+        if type_node is not None:
+            self._record_annotation(type_node, func_node.id)
+            self._scan_annotation_calls(type_node, func_node.id)
+
         self._push(qname, func_node.id, kind)
 
         # Parameters
@@ -380,18 +436,11 @@ class PythonASTVisitor:
         if params_node:
             self._extract_parameters(params_node, func_node.id, qname)
 
-        # Body: extract calls + visit nested defs
+        # Body: single traversal records calls + reads + dispatches nested
+        # defs, with no double-counting.
         body = next((c for c in node.children if c.type == "block"), None)
         if body:
-            self._extract_calls(body, func_node.id)
-            # Visit nested class/function definitions
-            for child in body.children:
-                if child.type in (
-                    "function_definition",
-                    "class_definition",
-                    "decorated_definition",
-                ):
-                    self.visit(child)
+            self._walk_body(body, func_node.id)
 
         self._pop()
 
@@ -407,8 +456,11 @@ class PythonASTVisitor:
             annotation: str | None = None
             has_default = False
             is_variadic = False
+            id_node: TSNode | None = None
+            ann_type_node: TSNode | None = None
 
             if child.type == "identifier":
+                id_node = child
                 param_name = _node_text(child)
 
             elif child.type == "default_parameter":
@@ -423,20 +475,24 @@ class PythonASTVisitor:
                     (c for c in child.children if c.type == "identifier"), None
                 )
                 param_name = _node_text(id_node) if id_node else None
-                type_node = next(
+                ann_type_node = next(
                     (c for c in child.children if c.type == "type"), None
                 )
-                annotation = _node_text(type_node) if type_node else None
+                annotation = (
+                    _node_text(ann_type_node) if ann_type_node else None
+                )
 
             elif child.type == "typed_default_parameter":
                 id_node = next(
                     (c for c in child.children if c.type == "identifier"), None
                 )
                 param_name = _node_text(id_node) if id_node else None
-                type_node = next(
+                ann_type_node = next(
                     (c for c in child.children if c.type == "type"), None
                 )
-                annotation = _node_text(type_node) if type_node else None
+                annotation = (
+                    _node_text(ann_type_node) if ann_type_node else None
+                )
                 has_default = True
 
             elif child.type in {
@@ -464,6 +520,7 @@ class PythonASTVisitor:
                     "has_default": has_default,
                     "is_variadic": is_variadic,
                 },
+                name_node=id_node,
             )
             self._safe_add_node(param_node)
             self._graph.add_relation(
@@ -473,59 +530,285 @@ class PythonASTVisitor:
                     kind=RelationKind.DECLARES,
                 )
             )
+            # Record annotation occurrence for typed parameters
+            if ann_type_node is not None:
+                self._record_annotation(ann_type_node, param_node.id)
+                # Calls embedded in the annotation (e.g. Depends(get_dep))
+                # are value uses enclosed by the function, not the parameter.
+                self._scan_annotation_calls(ann_type_node, function_id)
 
     # -------------------------------------------------------------------------
-    # Call extraction
+    # Value scanning (single source of truth for read + call occurrences)
     # -------------------------------------------------------------------------
 
-    def _extract_calls(self, body: TSNode, caller_id: str) -> None:
-        """Find all call nodes in body and emit CALLS relations."""
-        for child in body.children:
-            self._find_calls_in_node(child, caller_id)
-
-    def _find_calls_in_node(self, node: TSNode, caller_id: str) -> None:
+    _NESTED_DEF_TYPES = (
+        "function_definition",
+        "class_definition",
+        "decorated_definition",
+    )
+
+    def _scan_value(self, node: TSNode, enclosing_id: str) -> None:
+        """
+        Record ``read`` and ``call`` occurrences for a value expression.
+
+        This is the single place that turns a value-position subtree into
+        occurrences, so each identifier yields exactly one ``read`` and each
+        call yields exactly one ``call``. Used for assignment right-hand
+        sides, return expressions, standalone expression statements, call
+        argument lists, decorator arguments, and ``Annotated[...]`` /
+        ``Depends(...)`` annotations.
+
+        Rules:
+        - ``call`` → record a ``call`` on the callee name, then scan each
+          argument (nested calls + identifier args become occurrences).
+          The callee's receiver (``obj`` in ``obj.m()``) is not recorded.
+        - ``identifier`` → record a ``read``.
+        - otherwise → recurse into children.
+
+        Value expressions never contain nested definitions (those are
+        statements), so no def-skipping guard is needed here.
+        """
         if node.type == "call":
-            func_node = next(
-                (
-                    c
-                    for c in node.children
-                    if c.type in ("identifier", "attribute")
-                ),
+            callee = next(
+                (c for c in node.children
+                 if c.type in ("identifier", "attribute")),
                 None,
             )
-            if func_node:
-                callee_name = _name_from_node(func_node)
-                if callee_name:
-                    sym_id = make_node_id(
-                        self._ctx.project_name,
-                        callee_name,
-                        NodeKind.SYMBOL.value,
-                    )
-                    if sym_id not in self._graph.nodes:
-                        self._graph.add_node(
-                            Node(
-                                id=sym_id,
-                                kind=NodeKind.SYMBOL,
-                                qualified_name=callee_name,
-                                name=callee_name.split(".")[-1],
-                                span=_make_span(node),
-                            )
-                        )
-                    self._graph.add_relation(
-                        Relation(
-                            source_id=caller_id,
-                            target_id=sym_id,
-                            kind=RelationKind.CALLS,
-                        )
-                    )
-        # Don't recurse into nested function/class definitions
-        if node.type not in (
-            "function_definition",
-            "class_definition",
-            "decorated_definition",
-        ):
+            if callee is not None:
+                name_node = (
+                    callee.children[-1]
+                    if callee.type == "attribute" else callee
+                )
+                self._record_occurrence("call", name_node, enclosing_id)
+            arg_list = next(
+                (c for c in node.children if c.type == "argument_list"),
+                None,
+            )
+            if arg_list is not None:
+                for c in arg_list.children:
+                    if c.type not in ("(", ")", ","):
+                        if c.type == "keyword_argument":
+                            # Scan only the value (last child), not the name,
+                            # to avoid spurious REFERENCES on kwarg names.
+                            val = c.children[-1] if c.children else None
+                            if val is not None:
+                                self._scan_value(val, enclosing_id)
+                        else:
+                            self._scan_value(c, enclosing_id)
+            return
+        if node.type == "identifier":
+            self._record_occurrence("read", node, enclosing_id)
+            return
+        for child in node.children:
+            self._scan_value(child, enclosing_id)
+
+    def _walk_body(self, body: TSNode, enclosing_id: str) -> None:
+        """
+        Walk a function/module/class body once, recording occurrences.
+
+        A single traversal records calls and reads with no double-counting:
+        assignments and return statements go through their dedicated
+        handlers; every other value-position expression goes through
+        ``_scan_value``. Nested definitions are dispatched to ``visit`` so
+        their own nodes/bodies are built. Compound statements (if/for/while/
+        with/try/...) are descended into so calls and reads in nested blocks
+        and headers are captured.
+        """
+        for child in body.children:
+            self._walk_statement(child, enclosing_id)
+
+    def _walk_statement(self, node: TSNode, enclosing_id: str) -> None:
+        """
+        Dispatch a single statement (or clause) node (see ``_walk_body``).
+
+        Assignments and returns go through their dedicated handlers; nested
+        definitions are dispatched to ``visit``; ``block`` children and
+        block-bearing clauses (``else_clause``, ``except_clause``, ...) are
+        recursed into; every remaining child is a value expression scanned
+        via ``_scan_value``.
+        """
+        if node.type in self._NESTED_DEF_TYPES:
+            self.visit(node)
+            return
+        if node.type == "expression_statement":
             for child in node.children:
-                self._find_calls_in_node(child, caller_id)
+                if child.type == "assignment":
+                    self._handle_assignment(child)
+                else:
+                    self._scan_value(child, enclosing_id)
+            return
+        if node.type == "return_statement":
+            self._visit_return_statement(node)
+            return
+        # Compound / clause / other statements. Direct children are either
+        # blocks, block-bearing clauses (else/except/elif/finally/...), or
+        # header value expressions (conditions, iterables, context managers).
+        for child in node.children:
+            if child.type == "block":
+                self._walk_body(child, enclosing_id)
+            elif _has_block(child):
+                self._walk_statement(child, enclosing_id)
+            else:
+                self._scan_value(child, enclosing_id)
+
+    def _record_occurrence(
+        self, role: str, name_node: TSNode, enclosing_id: str
+    ) -> None:
+        """Append an OccurrenceRef for the given name node and role."""
+        span = _make_span(name_node)
+        if span is None:
+            return
+        self.occurrences.append(
+            OccurrenceRef(
+                role=role,
+                line=span.start_line,
+                col=span.start_col,
+                enclosing_id=enclosing_id,
+                span=span,
+            )
+        )
+
+    def _record_annotation(
+        self, type_node: TSNode, enclosing_id: str
+    ) -> None:
+        """
+        Record an ``annotation`` occurrence for the leading identifier.
+
+        The leading identifier is taken from a ``type`` node (return
+        annotation or parameter annotation).
+        """
+        ident = _first_identifier(type_node)
+        if ident is not None:
+            self._record_occurrence("annotation", ident, enclosing_id)
+
+    def _scan_decorators(
+        self, decorator_nodes: list[TSNode] | None, enclosing_id: str
+    ) -> None:
+        """
+        Record call/read occurrences for decorator call arguments.
+
+        For ``@deco(handler)`` this records a ``call`` on ``deco`` and a
+        ``read`` on the ``handler`` value argument. Bare decorators
+        (``@deco``) have no call node, so nothing is recorded.
+        """
+        for dec in decorator_nodes or []:
+            call = next(
+                (c for c in dec.children if c.type == "call"), None
+            )
+            if call is not None:
+                self._scan_value(call, enclosing_id)
+
+    def _scan_annotation_calls(
+        self, type_node: TSNode, enclosing_id: str
+    ) -> None:
+        """
+        Scan ``call`` nodes embedded in a type annotation as values.
+
+        Covers ``Annotated[T, Depends(get_dep)]`` and similar: the
+        ``Depends(...)`` call records a ``call`` on ``Depends`` and a
+        ``read`` on ``get_dep``. Plain type identifiers are left to
+        ``_record_annotation`` (HAS_TYPE), not recorded here.
+        """
+        for call in _find_calls(type_node):
+            self._scan_value(call, enclosing_id)
+
+    # -------------------------------------------------------------------------
+    # Assignment / variable handling
+    # -------------------------------------------------------------------------
+
+    def _visit_return_statement(self, node: TSNode) -> None:
+        """
+        Record ``read``/``call`` occurrences for a return expression.
+
+        Only the non-keyword children are inspected (the ``return`` keyword
+        is skipped). Value scanning is delegated to ``_scan_value`` so reads
+        and calls in the returned expression are recorded exactly once.
+        """
+        for child in node.children:
+            if child.type != "return":
+                self._scan_value(child, self._container_stack[-1])
+
+    def _visit_expression_statement(self, node: TSNode) -> None:
+        """
+        Dispatch expression_statement children at module/class scope.
+
+        Assignments create VARIABLE/ATTRIBUTE/TYPE_ALIAS nodes; every other
+        value-position expression is scanned via ``_scan_value`` so calls and
+        their argument reads are recorded exactly once. Function bodies do
+        not reach this method (they are driven by ``_walk_body``).
+        """
+        for child in node.children:
+            if child.type == "assignment":
+                self._handle_assignment(child)
+            else:
+                self._scan_value(child, self._container_stack[-1])
+
+    def _handle_assignment(self, node: TSNode) -> None:
+        # TODO(deferred): tuple-unpacking / augmented / walrus assignments not
+        # modeled (see spec §9 deferred)
+        """
+        Create a VARIABLE, ATTRIBUTE, or TYPE_ALIAS node from an assignment.
+
+        Dispatch rules:
+        - ``x: TypeAlias = v``  → TYPE_ALIAS
+        - ``self.attr = v``     → ATTRIBUTE
+        - inside class body     → ATTRIBUTE
+        - otherwise             → VARIABLE
+        """
+        lhs = node.children[0]
+        annotation = next(
+            (c for c in node.children if c.type == "type"), None
+        )
+        rhs = node.children[-1] if node.children[-1] is not lhs else None
+        # For self.attr = v, use the LAST identifier child (the attribute
+        # name), not the first (which would be 'self').
+        if lhs.type == "attribute":
+            name_node = next(
+                (c for c in reversed(lhs.children) if c.type == "identifier"),
+                None,
+            )
+        else:
+            name_node = _first_identifier(lhs)
+        if name_node is None:
+            return
+        name = _node_text(name_node)
+        is_alias = (
+            annotation is not None
+            and _node_text(annotation) == "TypeAlias"
+        )
+        # Attribute: inside class body or lhs is self.<attr>
+        in_class = self._kind_stack[-1] == NodeKind.CLASS
+        is_self_attr = (
+            lhs.type == "attribute"
+            and lhs.children
+            and _node_text(lhs.children[0]) == "self"
+        )
+        kind: NodeKind
+        if is_alias:
+            kind = NodeKind.TYPE_ALIAS
+        elif in_class or is_self_attr:
+            kind = NodeKind.ATTRIBUTE
+        else:
+            kind = NodeKind.VARIABLE
+        qname = f"{self._scope_stack[-1]}.{name}"
+        var_node = self._make_node(
+            kind,
+            qname,
+            name,
+            node,
+            metadata={"is_constant": name.isupper()},
+            name_node=name_node,
+        )
+        self._add_node_with_relation(var_node, RelationKind.DECLARES)
+        self._record_occurrence("write", name_node, self._container_stack[-1])
+        if rhs is not None and not is_alias:
+            self._scan_value(rhs, self._container_stack[-1])
+        elif is_alias and rhs is not None:
+            ident = _first_identifier(rhs)
+            if ident is not None:
+                self._record_occurrence(
+                    "annotation", ident, self._container_stack[-1]
+                )
 
     # -------------------------------------------------------------------------
     # Import helper
@@ -630,14 +913,26 @@ class PythonASTVisitor:
         if node.id not in self._graph.nodes:
             self._graph.add_node(node)
 
-    def _make_node(
+    def _make_node(  # noqa: PLR0913
         self,
         kind: NodeKind,
         qualified_name: str,
         name: str,
         ts_node: TSNode | None = None,
         metadata: dict[str, object] | None = None,
+        name_node: TSNode | None = None,
     ) -> Node:
+        """
+        Create a graph Node, optionally recording a ``name_span``.
+
+        The ``name_span`` captures the identifier token position so jedi
+        can map definition locations back to nodes.
+        """
+        md = dict(metadata or {})
+        if name_node is not None:
+            name_span = _make_span(name_node)
+            if name_span is not None:
+                md["name_span"] = name_span
         return Node(
             id=make_node_id(
                 self._ctx.project_name, qualified_name, kind.value
@@ -647,7 +942,7 @@ class PythonASTVisitor:
             name=name,
             file_path=str(self._ctx.file_path),
             span=_make_span(ts_node) if ts_node else None,
-            metadata=metadata or {},
+            metadata=md,
         )
 
     def _push(self, qname: str, node_id: str, kind: NodeKind) -> None:
@@ -732,3 +1027,41 @@ def _make_span(node: TSNode | None) -> Span | None:
         )
     except Exception:
         return None
+
+
+def _has_block(node: TSNode) -> bool:
+    """Return True if *node* directly contains a ``block`` child."""
+    return any(c.type == "block" for c in node.children)
+
+
+def _find_calls(node: TSNode) -> list[TSNode]:
+    """
+    Return the outermost ``call`` nodes reachable from *node*.
+
+    Does not descend into a call's own children, so nested calls inside
+    arguments are left to the value scanner that processes each returned
+    call. Used to locate ``Depends(...)``-style calls embedded inside type
+    annotations.
+    """
+    if node.type == "call":
+        return [node]
+    out: list[TSNode] = []
+    for child in node.children:
+        out.extend(_find_calls(child))
+    return out
+
+
+def _first_identifier(node: TSNode) -> TSNode | None:
+    """
+    Return the first ``identifier`` leaf reachable from *node* (pre-order).
+
+    Used to resolve the leading name in a composite type expression such as
+    ``list[int]``, ``Optional[str]``, or ``dict[str, int]``.
+    """
+    if node.type == "identifier":
+        return node
+    for child in node.children:
+        found = _first_identifier(child)
+        if found is not None:
+            return found
+    return None

{graphlens_python-0.3.0.dist-info → graphlens_python-0.4.0.dist-info}/METADATA

@@ -1,8 +1,9 @@
 Metadata-Version: 2.3
 Name: graphlens-python
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python language adapter for graphlens
 Requires-Dist: graphlens
 Requires-Dist: tree-sitter>=0.24
 Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: ty
 Requires-Python: >=3.13

graphlens_python-0.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+graphlens_python/__init__.py,sha256=txtdNJKr1SrA_Z9PWqaPYA7UHIQuGbHcArvQeekOkC0,191
+graphlens_python/_adapter.py,sha256=5M-OB6IPGuy_KW18OJ6mblQW2LMgPH1OCd9TlYNeUB4,13532
+graphlens_python/_deps.py,sha256=cs1NbyRbKYbYh_qKFoM7IBvkp89vYtd2KWWp__SGRsQ,6716
+graphlens_python/_module_resolver.py,sha256=0Haso97nTndH23xJn0kvr4MsMMh1mvEp0tDGdIFoPiY,2668
+graphlens_python/_project_detector.py,sha256=-vRHZot3aHMvHXwE3nrXCXC9mSYX4y90xwwuQjY3u-c,3880
+graphlens_python/_resolver.py,sha256=r18ake5S-aOCb3CpKtMukKhEkXsVGfy6bfQyoqWZWA8,14369
+graphlens_python/_visitor.py,sha256=PS1-UVHzC3Bz_dO-WQIcX5kaSWQWgeQ50-BI1Po5T68,38277
+graphlens_python-0.4.0.dist-info/WHEEL,sha256=oBsDExVIEya4llboy9Ce1l6on8xt3GrtT29y6pYVypw,81
+graphlens_python-0.4.0.dist-info/entry_points.txt,sha256=HRwCWZJIrgqLXDR5lit5XnCkXDYc3lwWICTrrHPhWhw,62
+graphlens_python-0.4.0.dist-info/METADATA,sha256=lm4mOiWTQ1DQ6_3X2pGS9j0ri0cT5eD9kC2nHYPs6Qc,247
+graphlens_python-0.4.0.dist-info/RECORD,,

{graphlens_python-0.3.0.dist-info → graphlens_python-0.4.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.11.12
+Generator: uv 0.11.23
 Root-Is-Purelib: true
 Tag: py3-none-any

graphlens_python-0.3.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-graphlens_python/__init__.py,sha256=eadIHZwAbZCE7TvpWUNONO3oMIFZQG3hdTVY_un9JIk,127
-graphlens_python/_adapter.py,sha256=QDYlQ1ts6CiW64FhbXWJ__3vTI-EnwGPC-7vGvS5cQY,8572
-graphlens_python/_deps.py,sha256=cs1NbyRbKYbYh_qKFoM7IBvkp89vYtd2KWWp__SGRsQ,6716
-graphlens_python/_module_resolver.py,sha256=gABfLKnAOJLGFtKHPlrCAAv1MAwCV_DpNzpZXbzadik,2654
-graphlens_python/_project_detector.py,sha256=-vRHZot3aHMvHXwE3nrXCXC9mSYX4y90xwwuQjY3u-c,3880
-graphlens_python/_visitor.py,sha256=nCrKi3Fuub6R2XrvlXbdI1k2Flalb9lkU9dFCWy3bAo,25173
-graphlens_python-0.3.0.dist-info/WHEEL,sha256=-unyBNsdNo6Y_XVO25zjvxasG_uUFN_fBd_kLyKE-Fk,81
-graphlens_python-0.3.0.dist-info/entry_points.txt,sha256=HRwCWZJIrgqLXDR5lit5XnCkXDYc3lwWICTrrHPhWhw,62
-graphlens_python-0.3.0.dist-info/METADATA,sha256=oRb802KwatpoZ6b1NBACry6TpIaQRx-qaVuAlcrxM1U,229
-graphlens_python-0.3.0.dist-info/RECORD,,