rpr-cli 0.1.1__py3-none-any.whl

rpr/map/dependencies.py

@@ -0,0 +1,243 @@
+"""External dependency summarisation for the code map.
+
+For each analysed directory, this module identifies which third-party (or
+system) package identifiers appeared in raw import strings but were *not*
+resolved to in-repo edges by the dependency-graph builder.  The result is a
+per-directory inventory of external package names that developers can review
+without consulting raw source files.
+
+The ``DependencyGraph`` contract is intentionally left unchanged — this module
+is a sibling analysis artifact, not an extension of the resolved graph.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rpr.map.graph import DependencyGraph
+from rpr.map.topology import DirectoryTopology
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# Standard Rust crate roots that are not third-party packages.
+_RUST_STDLIB_ROOTS: frozenset[str] = frozenset(
+    {
+        "std",
+        "core",
+        "alloc",
+        "proc_macro",
+        "test",
+        "self",
+        "super",
+        "crate",
+    }
+)
+
+# Max number of packages listed per directory in the report.
+_MAX_PACKAGES_PER_DIR = 15
+
+
+# ---------------------------------------------------------------------------
+# Domain value object
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ExternalDependencySummary:
+    """Aggregated external packages pulled in by files in a single directory.
+
+    Attributes:
+        directory: Repo-relative POSIX path (root is ``""``).
+        packages:  Sorted, deduplicated external package identifiers.
+    """
+
+    directory: str
+    packages: tuple[str, ...]
+
+
+# ---------------------------------------------------------------------------
+# Language-specific import normalisation
+# ---------------------------------------------------------------------------
+
+
+def _normalise_python(raw: str) -> str | None:
+    """Return the top-level Python package name, or None to discard.
+
+    Relative imports (starting with ``.``) came from the same repository and
+    were already considered by the graph builder; they are discarded here.
+    """
+    if raw.startswith("."):
+        return None
+    segment = raw.split(".")[0]
+    return segment if segment else None
+
+
+def _normalise_ts_js(raw: str) -> str | None:
+    """Return the npm package specifier, or None to discard.
+
+    Relative imports starting with ``.`` or ``/`` are in-repository references
+    that were already processed by the graph builder.
+    """
+    if raw.startswith(".") or raw.startswith("/"):
+        return None
+    # Scoped packages: "@scope/name/sub" → "@scope/name"
+    if raw.startswith("@"):
+        parts = raw.split("/")
+        if len(parts) >= 2:
+            return "/".join(parts[:2])
+        return raw
+    # Bare specifier: "react/jsx-runtime" → "react"
+    return raw.split("/")[0]
+
+
+def _normalise_rust(raw: str) -> str | None:
+    """Return the Rust crate root, or None to discard stdlib/self/crate paths."""
+    # Strip leading "::" that sometimes appears on absolute paths
+    clean = raw.lstrip(":")
+    root = clean.split("::")[0].split("/")[0]
+    if root in _RUST_STDLIB_ROOTS:
+        return None
+    return root if root else None
+
+
+def _normalise_cpp(raw: str) -> str | None:
+    """Return the first path segment of a C++ include, or None to discard.
+
+    Quoted includes (``"…"``) are typically project-relative and were already
+    resolved by the graph builder; only angle-bracket system/library includes
+    are treated as external here.
+    """
+    # Quoted includes are relative → discard
+    if raw.startswith('"'):
+        return None
+    # Angle-bracket includes: strip surrounding < >
+    bare = raw.strip("<>")
+    segment = bare.split("/")[0]
+    return segment if segment else None
+
+
+_NORMALISE_BY_LANGUAGE = {
+    "python": _normalise_python,
+    "typescript": _normalise_ts_js,
+    "javascript": _normalise_ts_js,
+    "rust": _normalise_rust,
+    "cpp": _normalise_cpp,
+}
+
+
+# ---------------------------------------------------------------------------
+# Core builder
+# ---------------------------------------------------------------------------
+
+
+def build_external_dependencies(
+    graph: DependencyGraph,
+    raw_imports: dict[str, list[str]],
+    topology: DirectoryTopology,
+) -> list[ExternalDependencySummary]:
+    """Build per-directory external dependency summaries.
+
+    For every file in *graph*, any raw import string that was *not* resolved to
+    an in-repo graph edge is normalised into an external package name and
+    attributed to the file's parent directory.  Results are deduplicated and
+    sorted both within each directory and across the returned list.
+
+    Args:
+        graph:       The resolved dependency graph (read-only; provides resolved
+                     edges and per-node language information).
+        raw_imports: Mapping ``{file_rel_path: [raw_import, ...]}``.  Typically
+                     produced by ``build_raw_import_inventory(graph)``.
+        topology:    Directory topology (used to obtain the canonical directory
+                     label for each file).
+
+    Returns:
+        A list of :class:`ExternalDependencySummary` objects — one per directory
+        that has at least one external import — sorted by ``directory``.
+        Directories with no external packages are omitted.
+    """
+    # Build a fast lookup set of resolved in-repo edges per file.
+    resolved_per_file: dict[str, set[str]] = {
+        rel: set(deps) for rel, deps in graph.edges.items()
+    }
+
+    # Build a fast lookup: file rel_path → language
+    lang_by_file: dict[str, str] = {
+        str(sf.rel_path).replace("\\", "/"): sf.language
+        for sf in graph.nodes
+    }
+
+    # Build file → directory mapping from topology
+    file_to_dir: dict[str, str] = {}
+    for dir_node in topology.nodes.values():
+        for file_rel in dir_node.files:
+            file_to_dir[file_rel] = dir_node.path
+
+    # Accumulate external packages per directory
+    accumulator: dict[str, set[str]] = {}
+
+    for file_rel, raw_list in raw_imports.items():
+        lang = lang_by_file.get(file_rel)
+        if lang is None:
+            continue  # file not in graph nodes; skip
+        normalise = _NORMALISE_BY_LANGUAGE.get(lang)
+        if normalise is None:
+            continue
+
+        resolved = resolved_per_file.get(file_rel, set())
+        directory = file_to_dir.get(file_rel, "")
+        bucket = accumulator.setdefault(directory, set())
+
+        for raw in raw_list:
+            # Check whether this raw import was resolved into an in-repo edge.
+            # The graph stores edge targets as rel_paths, not raw import strings,
+            # so we identify external imports as those that produce no in-repo edge
+            # pointing to a path that starts with the normalised identifier.
+            # Simpler heuristic: if the raw import starts with "." or the directory
+            # contains a file whose rel_path ends with the import path, it's
+            # already captured in resolved edges.  Here we rely on the normaliser
+            # to filter out relative imports and then check whether *any* resolved
+            # edge target is "plausibly" this import.  The key insight is that the
+            # graph builder already resolves everything it can; what remains in
+            # raw_list but is absent from resolved edges is external.
+            package = normalise(raw)
+            if package is None:
+                continue
+
+            # If every resolved edge target represents an in-repo file, and none
+            # of them looks like it came from this raw import, treat it as external.
+            # We do this conservatively: we check whether any resolved edge target
+            # for this file has the package as a prefix segment.
+            is_in_repo = _looks_like_in_repo(package, resolved, lang)
+            if not is_in_repo:
+                bucket.add(package)
+
+    # Build sorted result, omitting directories with no external packages
+    result: list[ExternalDependencySummary] = []
+    for directory in sorted(accumulator):
+        packages = tuple(sorted(accumulator[directory]))
+        if packages:
+            capped = packages[:_MAX_PACKAGES_PER_DIR]
+            result.append(ExternalDependencySummary(directory=directory, packages=capped))
+    return result
+
+
+def _looks_like_in_repo(package: str, resolved_edges: set[str], lang: str) -> bool:
+    """Return True if *package* appears to be satisfied by an in-repo resolved edge.
+
+    For Python and TS/JS the package name appears as a leading path segment or
+    module path component in the resolved edge targets.  For Rust and C++ the
+    same heuristic applies to crate or include names.
+    """
+    lower_pkg = package.lower()
+    for edge_target in resolved_edges:
+        # Normalise path separators and drop extension for comparison
+        target_norm = edge_target.replace("\\", "/").lower()
+        # e.g. "rpr/map/walker" starts with "rpr" → matches package "rpr"
+        parts = target_norm.split("/")
+        for part in parts:
+            stem = part.rsplit(".", 1)[0]  # strip extension
+            if stem == lower_pkg or part == lower_pkg:
+                return True
+    return False

rpr/map/extractor.py

@@ -0,0 +1,223 @@
+"""Analysis bridge — Rust-first project dependency extraction.
+
+Primary API
+-----------
+``analyze_project(root)`` is the single public entry-point consumed by the
+``rpr map`` command.  It returns a fully-resolved ``DependencyGraph`` domain
+object, delegating the expensive crawl/parse/resolve work to the compiled Rust
+extension when available and falling back to the pure-Python pipeline
+otherwise.
+
+Fallback extraction helpers
+----------------------------
+``extract_imports`` / ``extract_imports_batch`` parse raw import strings from
+source files using the standard library (``ast`` for Python) and regular
+expressions (TypeScript, JavaScript, Rust, C++).  These helpers power the
+Python compatibility path and remain available for callers that need them
+directly.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+import warnings
+from pathlib import Path
+from typing import Callable
+
+from rpr.map.graph import DependencyGraph, build_graph
+from rpr.map.walker import Language, SourceFile, walk
+
+try:
+    import rpr_parser
+
+    _RUST_AVAILABLE = True
+except ImportError:
+    _RUST_AVAILABLE = False
+
+# ---------------------------------------------------------------------------
+# Type alias for per-language extraction functions (LSP: uniform signature)
+# ---------------------------------------------------------------------------
+
+_ExtractFn = Callable[[str], list[str]]
+
+# ---------------------------------------------------------------------------
+# Private per-language extractors (SRP: one concern each)
+# ---------------------------------------------------------------------------
+
+
+def _extract_python(source: str) -> list[str]:
+    """Extract raw import strings from Python source using ``ast``."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    results: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                results.append(alias.name)
+        elif isinstance(node, ast.ImportFrom):
+            dots = "." * (node.level or 0)
+            module = node.module or ""
+            results.append(dots + module)
+    return results
+
+
+# Patterns compiled once at import time for efficiency.
+_TS_JS_PATTERNS = (
+    # import ... from 'X' / "X"
+    re.compile(r"""import\s+.*?from\s+['"]([^'"]+)['"]""", re.DOTALL),
+    # require('X') / require("X")
+    re.compile(r"""require\s*\(\s*['"]([^'"]+)['"]\s*\)"""),
+    # import('X') — dynamic
+    re.compile(r"""import\s*\(\s*['"]([^'"]+)['"]\s*\)"""),
+)
+
+
+def _extract_ts_js(source: str) -> list[str]:
+    """Extract raw import specifiers from TypeScript / JavaScript source."""
+    results: list[str] = []
+    for pattern in _TS_JS_PATTERNS:
+        results.extend(pattern.findall(source))
+    return results
+
+
+_RUST_USE = re.compile(r"use\s+([\w:]+(?:\s+as\s+\w+)?)\s*;")
+_RUST_MOD = re.compile(r"mod\s+(\w+)\s*;")
+_RUST_EXTERN = re.compile(r"extern\s+crate\s+(\w+)\s*;")
+
+
+def _extract_rust(source: str) -> list[str]:
+    """Extract raw import/module strings from Rust source."""
+    results: list[str] = []
+
+    for match in _RUST_USE.finditer(source):
+        # Drop the alias part: "std::io as io" → "std::io"
+        path = match.group(1).split(" as ")[0].strip()
+        results.append(path)
+
+    results.extend(_RUST_MOD.findall(source))
+    results.extend(_RUST_EXTERN.findall(source))
+
+    return results
+
+
+_CPP_QUOTED = re.compile(r'#include\s+"([^"]+)"')
+_CPP_ANGLE = re.compile(r"#include\s+<([^>]+)>")
+
+
+def _extract_cpp(source: str) -> list[str]:
+    """Extract raw include strings from C++ source.
+
+    Angle-bracket includes (system headers) are emitted without the ``<>``
+    delimiters; the graph resolver will drop them as external.
+    """
+    results: list[str] = _CPP_QUOTED.findall(source)
+    results.extend(_CPP_ANGLE.findall(source))
+    return results
+
+
+# Dispatch dict — adding a new language requires only a new entry here (OCP).
+_EXTRACTORS: dict[Language, _ExtractFn] = {
+    "python": _extract_python,
+    "typescript": _extract_ts_js,
+    "javascript": _extract_ts_js,
+    "rust": _extract_rust,
+    "cpp": _extract_cpp,
+}
+
+# ---------------------------------------------------------------------------
+# Public extraction API
+# ---------------------------------------------------------------------------
+
+
+def extract_imports(file: SourceFile) -> list[str]:
+    """Extract raw import strings from a single ``SourceFile``.
+
+    Returns an empty list for unsupported languages.  Returns an empty list
+    and emits a ``UserWarning`` when the file cannot be read.
+    """
+    extractor = _EXTRACTORS.get(file.language)
+    if extractor is None:
+        return []
+
+    try:
+        source = file.abs_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        warnings.warn(f"Cannot read {file.rel_path} — skipping", stacklevel=2)
+        return []
+
+    return extractor(source)
+
+
+def extract_imports_batch(
+    files: list[SourceFile],
+) -> dict[str, list[str]]:
+    """Extract raw imports for every file; returns ``{rel_path: [import, ...]}``."""
+    return {str(f.rel_path).replace("\\", "/"): extract_imports(f) for f in files}
+
+
+def build_raw_import_inventory(graph: DependencyGraph) -> dict[str, list[str]]:
+    """Return raw (unresolved) import strings for every file in *graph*.
+
+    This is a convenience wrapper around :func:`extract_imports_batch` that
+    accepts an already-constructed :class:`~rpr.map.graph.DependencyGraph` and
+    returns the same ``{rel_path: [import, ...]}`` mapping.  The result includes
+    *all* imports — both those that were resolved to in-repo edges and those
+    that remain unresolved (i.e., external packages or unreadable paths).
+
+    Callers that need only external imports should subtract the resolved edges
+    stored in ``graph.edges`` from this inventory.
+    """
+    return extract_imports_batch(graph.nodes)
+
+
+# ---------------------------------------------------------------------------
+# Private path implementations
+# ---------------------------------------------------------------------------
+
+
+def _rust_path(root: Path) -> DependencyGraph:
+    """Delegate the full analysis to the compiled Rust extension."""
+    payload = rpr_parser.build_dependency_graph(str(root))
+    nodes = [
+        SourceFile(
+            abs_path=Path(n["abs_path"]),
+            rel_path=Path(n["rel_path"]),
+            language=n["language"],
+        )
+        for n in payload["nodes"]
+    ]
+    return DependencyGraph(
+        nodes=nodes,
+        edges=payload["edges"],
+        reverse_edges=payload["reverse_edges"],
+        cycles=payload["cycles"],
+        backend="rust",
+    )
+
+
+def _python_path(root: Path) -> DependencyGraph:
+    """Pure-Python compatibility pipeline: walk → extract → build graph."""
+    files = walk(root)
+    imports_by_file = extract_imports_batch(files)
+    return build_graph(files, imports_by_file)
+
+
+# ---------------------------------------------------------------------------
+# Primary public API
+# ---------------------------------------------------------------------------
+
+
+def analyze_project(root: Path) -> DependencyGraph:
+    """Crawl *root* and return a fully-resolved ``DependencyGraph``.
+
+    Delegates to the Rust engine when ``rpr_parser`` is importable; falls back
+    to the Python-only pipeline otherwise.  The returned graph's ``backend``
+    field indicates which path was taken.
+    """
+    if _RUST_AVAILABLE:
+        return _rust_path(root)
+    return _python_path(root)