graphlens-python 0.2.2__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,8 @@ 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 (
     PYTHON_DEFAULT_DEP_PARSERS,
@@ -28,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."""
@@ -51,6 +65,7 @@ class PythonAdapter(LanguageAdapter):
     def __init__(
         self,
         dep_parsers: list[DependencyFileParser] | None = None,
+        resolver: SymbolResolver | None = None,
     ) -> None:
         """
         Initialize the Python adapter.
@@ -62,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 = (
@@ -69,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"
@@ -93,27 +116,36 @@ class PythonAdapter(LanguageAdapter):
                 project_root,
                 files,
                 self._dep_parsers,
+                self._resolver,
             )
         else:
-            for py_root in find_python_roots(project_root):
+            py_roots = find_python_roots(project_root)
+            for py_root in py_roots:
                 root_files = self.collect_files(py_root)
+                root_files = filter_nested_root_files(
+                    root_files,
+                    py_root,
+                    py_roots,
+                )
                 _analyze_root(
                     graph,
                     project_root,
                     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)
@@ -157,6 +189,7 @@ def _analyze_root(
         )
 
     modules: dict[str, str] = {}
+    all_occurrences: list[tuple[str, OccurrenceRef]] = []
 
     for file in files:
         source_root = (
@@ -225,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}
@@ -238,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/_project_detector.py

@@ -6,6 +6,8 @@ import configparser
 import tomllib
 from typing import TYPE_CHECKING
 
+from graphlens.utils import collect_marker_roots
+
 if TYPE_CHECKING:
     from pathlib import Path
 
@@ -47,38 +49,21 @@ def find_python_roots(search_root: Path) -> list[Path]:
     """
     Find the actual Python project roots within search_root.
 
-    If search_root itself has Python markers, returns ``[search_root]``.
-    Otherwise walks subdirectories for marker files and returns their parent
-    directories — one per distinct Python sub-project.  This ensures that
-    ``detect_project_name`` and source-root resolution use the *correct* root
-    rather than the monorepo root, giving accurate import mappings.
+    Walks for marker files and returns their parent directories — one per
+    distinct Python sub-project. A marker at ``search_root`` does not hide
+    nested marker roots. This ensures that ``detect_project_name`` and
+    source-root resolution use the *correct* root rather than treating the
+    whole monorepo as one project.
 
     Falls back to ``[search_root]`` when no markers are found anywhere (the
     directory contains only bare .py scripts with no packaging metadata).
     """
-    if _has_python_markers(search_root):
-        return [search_root]
-
-    roots: list[Path] = []
-    for marker in PYTHON_MARKERS:
-        for marker_file in sorted(search_root.rglob(marker)):
-            rel_parts = marker_file.relative_to(search_root).parts
-            if _EXCLUDED_DIRS & set(rel_parts):
-                continue
-            if marker == "pyproject.toml" and not (
-                _pyproject_has_project_section(marker_file)
-            ):
-                continue
-            candidate = marker_file.parent
-            # Skip if already covered by a previously found (ancestor) root
-            if any(
-                candidate == r or candidate.is_relative_to(r)
-                for r in roots
-            ):
-                continue
-            roots.append(candidate)
-
-    return sorted(roots) if roots else [search_root]
+    return collect_marker_roots(
+        search_root,
+        PYTHON_MARKERS,
+        excluded_dirs=_EXCLUDED_DIRS,
+        marker_filter=_is_valid_python_marker,
+    )
 
 
 def detect_project_name(project_root: Path) -> str:
@@ -121,14 +106,17 @@ def _has_python_markers(directory: Path) -> bool:
         path = directory / marker
         if not path.exists():
             continue
-        if marker == "pyproject.toml":
-            if _pyproject_has_project_section(path):
-                return True
-        else:
+        if _is_valid_python_marker(path):
             return True
     return False
 
 
+def _is_valid_python_marker(path: Path) -> bool:
+    if path.name == "pyproject.toml":
+        return _pyproject_has_project_section(path)
+    return True
+
+
 def _pyproject_has_project_section(path: Path) -> bool:
     try:
         with path.open("rb") as f: