rpr-cli 0.1.1__py3-none-any.whl

rpr/map/responsibility.py

@@ -0,0 +1,345 @@
+"""Deterministic responsibility summaries for the code map.
+
+For each directory in the analysed repository this module derives a concise
+one-line description of what that directory is responsible for.  All inference
+is performed from repository contents only; no network calls or LLM inference
+are used.
+
+Heuristics are applied in priority order:
+  1. Module docstring — the first non-empty line of the docstring from a
+     canonical index file (``__init__.py``, ``mod.rs``, or ``index.ts/tsx``).
+  2. Vocabulary match — maps well-known directory name segments to canned
+     descriptions.
+  3. Dominant layer — the most frequent non-``unknown`` layer label from
+     classified nodes in the directory.
+  4. Neutral fallback — "N source files".
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from rpr.map.classifier import ClassifiedNode
+from rpr.map.topology import DirectoryTopology
+
+# ---------------------------------------------------------------------------
+# Vocabulary map  (last path segment → description)
+# ---------------------------------------------------------------------------
+
+_VOCAB: dict[str, str] = {
+    # CLI and entry points
+    "commands": "CLI command handlers",
+    "cli": "Command-line interface entry points",
+    "main": "Application entry point",
+    "app": "Application entry point",
+    # Application layer
+    "application": "Application service layer",
+    "services": "Application services",
+    "use_cases": "Application use-case handlers",
+    "usecases": "Application use-case handlers",
+    "handlers": "Request/event handlers",
+    "workflows": "Application workflows",
+    # Domain
+    "domain": "Domain model",
+    "entities": "Domain entities",
+    "entity": "Domain entity",
+    "models": "Domain models",
+    # DTOs / schemas
+    "dtos": "Data transfer objects",
+    "dto": "Data transfer objects",
+    "schemas": "Data schemas",
+    "types": "Type definitions",
+    # Persistence
+    "repos": "Repository implementations",
+    "repositories": "Repository implementations",
+    "repository": "Repository implementation",
+    # Infrastructure
+    "infrastructure": "Infrastructure adapters",
+    "infra": "Infrastructure adapters",
+    "config": "Configuration",
+    "db": "Database layer",
+    "orm": "ORM models",
+    "migrations": "Database migrations",
+    # API
+    "api": "API layer",
+    "routes": "Route definitions",
+    "routers": "Route definitions",
+    "endpoints": "API endpoints",
+    "middleware": "Middleware",
+    # UI
+    "components": "UI components",
+    "pages": "Page components",
+    "screens": "Screen components",
+    "views": "View components",
+    "hooks": "React hooks",
+    "utils": "Utilities",
+    "util": "Utilities",
+    "helpers": "Helper functions",
+    # Map subsystem
+    "map": "Code-map analysis",
+    "extractor": "Import extraction",
+    "topology": "Directory topology",
+    "classifier": "Layer classification",
+    "output": "Report rendering",
+    "graph": "Dependency graph",
+    "walker": "File walker",
+    "architecture": "Architecture assessment",
+    "chains": "Representative dependency chains",
+    "checks": "Health-check validators",
+    "generators": "Code generators",
+    "scaffolds": "Project scaffolds",
+    "templates": "Code templates",
+    "agent": "AI agent tools",
+    "tui": "Terminal UI",
+    "ui": "User interface",
+}
+
+# Layer labels → human-readable responsibility suffix
+_LAYER_DESCRIPTIONS: dict[str, str] = {
+    "entry_point": "Entry points",
+    "application": "Application logic",
+    "entity": "Domain entities",
+    "dto": "Data transfer objects",
+    "repository": "Data access layer",
+    "infrastructure": "Infrastructure layer",
+    "ui_component": "UI components",
+    "ui_util": "UI utilities",
+    "test": "Tests",
+}
+
+# Patterns for extracting a leading docstring from Rust source.
+_RUST_INNER_DOC_RE = re.compile(r"//!(.+)")
+
+# ---------------------------------------------------------------------------
+# Domain value object
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ResponsibilitySummary:
+    """One-line responsibility description for a single directory.
+
+    Attributes:
+        directory: Repo-relative POSIX path (root is ``""``).
+        summary:   Human-readable responsibility string.
+    """
+
+    directory: str
+    summary: str
+
+
+# ---------------------------------------------------------------------------
+# Docstring extraction helpers
+# ---------------------------------------------------------------------------
+
+
+def _python_docstring(source: str) -> str | None:
+    """Return the first line of the module docstring from Python source, or None."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+    if not tree.body:
+        return None
+    first = tree.body[0]
+    if not isinstance(first, ast.Expr):
+        return None
+    if not isinstance(first.value, ast.Constant) or not isinstance(first.value.value, str):
+        return None
+    lines = [ln.strip() for ln in first.value.value.strip().splitlines() if ln.strip()]
+    return lines[0] if lines else None
+
+
+def _rust_docstring(source: str) -> str | None:
+    """Return the first module-level inner doc comment (``//!``) line, or None."""
+    for line in source.splitlines():
+        stripped = line.strip()
+        m = _RUST_INNER_DOC_RE.match(stripped)
+        if m:
+            text = m.group(1).strip()
+            if text:
+                return text
+    return None
+
+
+def _ts_docstring(source: str) -> str | None:
+    """Return the first JSDoc/TSDoc ``/** … */`` description line, or None."""
+    # Match a leading block comment before the first import/export statement
+    m = re.match(r"\s*/\*\*(.+?)\*/", source, re.DOTALL)
+    if not m:
+        return None
+    inner = m.group(1)
+    for line in inner.splitlines():
+        clean = line.strip().lstrip("*").strip()
+        if clean and not clean.startswith("@"):
+            return clean
+    return None
+
+
+def _read_index_docstring(directory: str, topology: DirectoryTopology) -> str | None:
+    """Attempt to read a docstring from the canonical index file of *directory*.
+
+    Looks for files directly in the directory (``files`` on the DirectoryNode)
+    with names ``__init__.py``, ``mod.rs``, or ``index.ts``/``index.tsx``.
+    Returns None when no index file exists or is not readable.
+    """
+    dir_node = topology.nodes.get(directory)
+    if dir_node is None:
+        return None
+
+    # index_files holds tuples of (relative_path, extractor_fn)
+    candidates: dict[str, object] = {
+        "__init__.py": _python_docstring,
+        "mod.rs": _rust_docstring,
+        "index.ts": _ts_docstring,
+        "index.tsx": _ts_docstring,
+    }
+
+    for file_rel in dir_node.files:
+        filename = file_rel.rsplit("/", 1)[-1]
+        extractor = candidates.get(filename)
+        if extractor is None:
+            continue
+        # Reconstruct abs_path using a best-effort approach; we don't have root
+        # available here.  We delegate this to the caller via the files_in API
+        # and instead skip abs_path reading entirely — rely on caller providing
+        # an optional root for filesystem reads.  See build_responsibility_summaries.
+        del extractor  # accessed by name in public builder
+        return None  # placeholder; actual reads happen in public builder
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Public builder
+# ---------------------------------------------------------------------------
+
+
+def build_responsibility_summaries(
+    topology: DirectoryTopology,
+    classified: list[ClassifiedNode],
+    root: Path | None = None,
+) -> list[ResponsibilitySummary]:
+    """Derive a responsibility summary for every directory in the topology.
+
+    Args:
+        topology:   Directory topology from ``build_directory_topology``.
+        classified: Classified nodes from ``classify(graph)``.
+        root:       Filesystem root; when provided, enables docstring extraction
+                    from index files.
+
+    Returns:
+        A list of :class:`ResponsibilitySummary` objects — one per directory in
+        ``topology.nodes`` — sorted by ``directory``.
+    """
+    # Build file → classified node lookup
+    classified_by_file: dict[str, ClassifiedNode] = {
+        str(n.file.rel_path).replace("\\", "/"): n for n in classified
+    }
+
+    # Build directory → file list mapping (all files recursively)
+    def _files_in_dir(directory: str) -> list[str]:
+        return topology.files_in(directory)
+
+    results: list[ResponsibilitySummary] = []
+
+    for directory in sorted(topology.nodes):
+        summary = _derive_summary(
+            directory, topology, classified_by_file, root
+        )
+        results.append(ResponsibilitySummary(directory=directory, summary=summary))
+
+    return results
+
+
+def _derive_summary(
+    directory: str,
+    topology: DirectoryTopology,
+    classified_by_file: dict[str, ClassifiedNode],
+    root: Path | None,
+) -> str:
+    """Return the best available one-line summary for a single directory."""
+    # ----------------------------------------------------------------
+    # Heuristic 1 — module docstring from index file (requires root)
+    # ----------------------------------------------------------------
+    if root is not None:
+        docstring = _try_index_docstring(directory, topology, root)
+        if docstring:
+            return _cap(docstring)
+
+    # ----------------------------------------------------------------
+    # Heuristic 2 — vocabulary match on last path segment
+    # ----------------------------------------------------------------
+    if directory:
+        last_segment = directory.rsplit("/", 1)[-1].lower()
+        if last_segment in _VOCAB:
+            return _VOCAB[last_segment]
+    else:
+        # Root directory — give a generic label based on project file count
+        pass
+
+    # ----------------------------------------------------------------
+    # Heuristic 3 — dominant non-unknown layer among classified nodes
+    # ----------------------------------------------------------------
+    files_in = topology.files_in(directory)
+    layer_counts: dict[str, int] = {}
+    for file_rel in files_in:
+        node = classified_by_file.get(file_rel)
+        if node is None or node.layer == "unknown":
+            continue
+        layer_counts[node.layer] = layer_counts.get(node.layer, 0) + 1
+
+    if layer_counts:
+        dominant = max(layer_counts, key=lambda k: layer_counts[k])
+        description = _LAYER_DESCRIPTIONS.get(dominant)
+        if description:
+            return description
+
+    # ----------------------------------------------------------------
+    # Heuristic 4 — neutral fallback
+    # ----------------------------------------------------------------
+    file_count = len(files_in)
+    noun = "source file" if file_count == 1 else "source files"
+    return f"{file_count} {noun}"
+
+
+def _try_index_docstring(
+    directory: str,
+    topology: DirectoryTopology,
+    root: Path,
+) -> str | None:
+    """Read and parse the index file docstring for *directory* from disk."""
+    dir_node = topology.nodes.get(directory)
+    if dir_node is None:
+        return None
+
+    _INDEX_FILES: dict[str, object] = {
+        "__init__.py": _python_docstring,
+        "mod.rs": _rust_docstring,
+        "index.ts": _ts_docstring,
+        "index.tsx": _ts_docstring,
+    }
+
+    for file_rel in dir_node.files:
+        filename = file_rel.rsplit("/", 1)[-1]
+        extractor_fn = _INDEX_FILES.get(filename)
+        if extractor_fn is None:
+            continue
+        abs_path = root / Path(file_rel)
+        try:
+            source = abs_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        result = extractor_fn(source)  # type: ignore[operator]
+        if result:
+            return result
+
+    return None
+
+
+def _cap(text: str, limit: int = 120) -> str:
+    """Truncate text to *limit* characters."""
+    return text if len(text) <= limit else text[:limit - 1] + "…"

rpr/map/topology.py

@@ -0,0 +1,327 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from rpr.map.graph import DependencyGraph
+
+# ---------------------------------------------------------------------------
+# Private path helpers
+# ---------------------------------------------------------------------------
+
+
+def _posix_parent(path: str) -> str:
+    """Return the parent directory of a POSIX path string.
+
+    "api/routes/user.py" -> "api/routes"
+    "main.py"            -> ""
+    ""                   -> ""
+    """
+    idx = path.rfind("/")
+    return path[:idx] if idx != -1 else ""
+
+
+def _ancestors(directory: str) -> list[str]:
+    """Return all ancestor directories including self and root "".
+
+    "api/routes" -> ["api/routes", "api", ""]
+    "api"        -> ["api", ""]
+    ""           -> [""]
+    """
+    result: list[str] = []
+    current = directory
+    while True:
+        result.append(current)
+        if current == "":
+            break
+        current = _posix_parent(current)
+    return result
+
+
+def _truncate_to_depth(directory: str, depth: int) -> str:
+    """Truncate a directory path to the first *depth* segments.
+
+    _truncate_to_depth("api/routes/v2", 1) -> "api"
+    _truncate_to_depth("api/routes/v2", 2) -> "api/routes"
+    _truncate_to_depth("api", 1)           -> "api"
+    _truncate_to_depth("", 1)              -> ""
+    """
+    if not directory:
+        return ""
+    parts = directory.split("/")
+    return "/".join(parts[:depth])
+
+
+# ---------------------------------------------------------------------------
+# Domain value objects
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class DirectoryNode:
+    """A directory in the containment tree."""
+
+    path: str  # POSIX rel_path; root is ""
+    parent: str | None  # None only for root ""
+    children: tuple[str, ...]  # sorted immediate child directory paths
+    files: tuple[str, ...]  # sorted file rel_paths directly in this dir
+
+
+@dataclass(frozen=True)
+class DirectoryEdge:
+    """An aggregated dependency edge between two directories."""
+
+    source: str  # source directory POSIX path
+    target: str  # target directory POSIX path
+    support: int  # number of file-level edges contributing
+    representatives: tuple[tuple[str, str], ...]  # sorted (src_file, dest_file) pairs
+
+
+# ---------------------------------------------------------------------------
+# Directory topology aggregate
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DirectoryTopology:
+    """Directory-level projection of a file-level DependencyGraph.
+
+    ``nodes`` preserves every discovered directory (including the root "").
+    ``edges`` holds full-depth directory edges derived from file-level edges.
+    Query methods produce derived views without modifying the stored state.
+    """
+
+    nodes: dict[str, DirectoryNode]  # path -> DirectoryNode
+    edges: dict[tuple[str, str], DirectoryEdge]  # (src_dir, tgt_dir) -> edge
+    root: str  # always ""
+
+    # ------------------------------------------------------------------
+    # Derived views
+    # ------------------------------------------------------------------
+
+    def edges_at_depth(self, depth: int) -> list[DirectoryEdge]:
+        """Return directory edges with both endpoints truncated to *depth* segments.
+
+        Edges where source == target after truncation (intra-directory) are
+        excluded.  Representatives and support counts are merged across all
+        full-depth edges that collapse to the same truncated pair.  The result
+        is sorted by (source, target).
+        """
+        accumulator: dict[tuple[str, str], list[tuple[str, str]]] = {}
+        for edge in self.edges.values():
+            src = _truncate_to_depth(edge.source, depth)
+            tgt = _truncate_to_depth(edge.target, depth)
+            if src == tgt:
+                continue
+            key = (src, tgt)
+            bucket = accumulator.setdefault(key, [])
+            bucket.extend(edge.representatives)
+
+        result: list[DirectoryEdge] = []
+        for (src, tgt), pairs in sorted(accumulator.items()):
+            deduped = sorted(set(pairs))
+            result.append(
+                DirectoryEdge(
+                    source=src,
+                    target=tgt,
+                    support=len(deduped),
+                    representatives=tuple(deduped),
+                )
+            )
+        return result
+
+    def top_level_edges(self) -> list[DirectoryEdge]:
+        """Shorthand for ``edges_at_depth(1)``."""
+        return self.edges_at_depth(1)
+
+    def subgraph(self, directory: str) -> list[DirectoryEdge]:
+        """Return edges where at least one endpoint is an immediate child of *directory*.
+
+        Internal paths (under *directory*) are expressed at child depth — one
+        segment deeper than *directory*.  External paths are truncated to
+        top-level (depth 1) so outbound dependencies are readable.  Edges
+        entirely outside the directory are excluded.  The root directory ("")
+        returns the same result as ``top_level_edges()``.
+        """
+        child_depth = directory.count("/") + 2 if directory else 1
+        prefix = directory + "/" if directory else ""
+
+        def _is_under(dir_path: str) -> bool:
+            if not directory:
+                return True
+            return dir_path == directory or dir_path.startswith(prefix)
+
+        def _truncate_for_side(dir_path: str) -> str:
+            if _is_under(dir_path):
+                return _truncate_to_depth(dir_path, child_depth)
+            return _truncate_to_depth(dir_path, 1)
+
+        accumulator: dict[tuple[str, str], list[tuple[str, str]]] = {}
+        for edge in self.edges.values():
+            src_is_under = _is_under(edge.source)
+            tgt_is_under = _is_under(edge.target)
+            if not src_is_under and not tgt_is_under:
+                continue
+
+            src = _truncate_for_side(edge.source)
+            tgt = _truncate_for_side(edge.target)
+            if src == tgt:
+                continue
+
+            key = (src, tgt)
+            bucket = accumulator.setdefault(key, [])
+            bucket.extend(edge.representatives)
+
+        result: list[DirectoryEdge] = []
+        for (src, tgt), pairs in sorted(accumulator.items()):
+            deduped = sorted(set(pairs))
+            result.append(
+                DirectoryEdge(
+                    source=src,
+                    target=tgt,
+                    support=len(deduped),
+                    representatives=tuple(deduped),
+                )
+            )
+        return result
+
+    def files_in(self, directory: str) -> list[str]:
+        """Return all file rel_paths recursively contained under *directory*.
+
+        The result is sorted for determinism.
+        """
+        collected: list[str] = []
+        prefix = directory + "/" if directory else ""
+        for node in self.nodes.values():
+            if node.path == directory or node.path.startswith(prefix):
+                collected.extend(node.files)
+        return sorted(collected)
+
+
+# ---------------------------------------------------------------------------
+# Public builder
+# ---------------------------------------------------------------------------
+
+
+def build_directory_topology(graph: DependencyGraph, root: Path) -> DirectoryTopology:  # noqa: ARG001
+    """Build a DirectoryTopology from a file-level DependencyGraph.
+
+    The *root* parameter is accepted for API symmetry with other map builders
+    but is not required for the computation (all paths are already relative
+    inside the graph).
+
+    Args:
+        graph: The file-level dependency graph (read-only input).
+        root:  The filesystem root that was analysed (unused internally).
+
+    Returns:
+        A fully populated DirectoryTopology.
+    """
+    # ------------------------------------------------------------------
+    # Step 1: Collect all directory paths and direct-file containment.
+    # ------------------------------------------------------------------
+    dir_files: dict[str, list[str]] = {"": []}  # root always present
+
+    for node in graph.nodes:
+        file_key = str(node.rel_path).replace("\\", "/")
+        parent_dir = _posix_parent(file_key)
+        # Record the file under its immediate parent only.
+        dir_files.setdefault(parent_dir, []).append(file_key)
+        # Ensure every ancestor directory exists (even if it contains no
+        # direct files).
+        for ancestor in _ancestors(parent_dir):
+            dir_files.setdefault(ancestor, [])
+
+    # ------------------------------------------------------------------
+    # Step 2: Build parent -> children index.
+    # ------------------------------------------------------------------
+    dir_children: dict[str, list[str]] = {d: [] for d in dir_files}
+
+    for directory in dir_files:
+        if directory == "":
+            continue
+        parent = _posix_parent(directory)
+        dir_children.setdefault(parent, []).append(directory)
+
+    # ------------------------------------------------------------------
+    # Step 3: Construct DirectoryNode objects.
+    # ------------------------------------------------------------------
+    nodes: dict[str, DirectoryNode] = {}
+    for directory in dir_files:
+        parent: str | None = _posix_parent(directory) if directory else None
+        nodes[directory] = DirectoryNode(
+            path=directory,
+            parent=parent,
+            children=tuple(sorted(dir_children.get(directory, []))),
+            files=tuple(sorted(dir_files[directory])),
+        )
+
+    # ------------------------------------------------------------------
+    # Step 4: Build full-depth directory edges from file-level edges.
+    # ------------------------------------------------------------------
+    edge_pairs: dict[tuple[str, str], list[tuple[str, str]]] = {}
+
+    for src_file, deps in graph.edges.items():
+        src_dir = _posix_parent(src_file)
+        for tgt_file in deps:
+            tgt_dir = _posix_parent(tgt_file)
+            if src_dir == tgt_dir:
+                continue  # intra-directory at full depth — skip
+            key = (src_dir, tgt_dir)
+            edge_pairs.setdefault(key, []).append((src_file, tgt_file))
+
+    # ------------------------------------------------------------------
+    # Step 5: Construct DirectoryEdge objects.
+    # ------------------------------------------------------------------
+    edges: dict[tuple[str, str], DirectoryEdge] = {}
+    for (src_dir, tgt_dir), pairs in edge_pairs.items():
+        deduped = sorted(set(pairs))
+        edges[(src_dir, tgt_dir)] = DirectoryEdge(
+            source=src_dir,
+            target=tgt_dir,
+            support=len(deduped),
+            representatives=tuple(deduped),
+        )
+
+    return DirectoryTopology(nodes=nodes, edges=edges, root="")
+
+
+def focus_edges(
+    topology: DirectoryTopology,
+    directory: str,
+    graph_edges: dict[str, list[str]],
+) -> tuple[list[tuple[str, str]], list[tuple[str, str]], list[tuple[str, str]]]:
+    """Return file-level edges classified relative to a focused directory.
+
+    Args:
+        topology:    Directory topology used to enumerate files under *directory*.
+        directory:   Repo-relative POSIX path of the directory to focus on.
+        graph_edges: File-level edges from ``DependencyGraph.edges``.
+
+    Returns:
+        A three-tuple ``(internal_edges, inbound_edges, outbound_edges)``:
+
+        - *internal_edges*: ``(src_file, tgt_file)`` where both files are
+          under *directory*.
+        - *inbound_edges*: ``(external_file, internal_file)`` where the
+          source is outside *directory* and the target is inside.
+        - *outbound_edges*: ``(internal_file, external_file)`` where the
+          source is inside *directory* and the target is outside.
+    """
+    focus_files = set(topology.files_in(directory))
+    internal: list[tuple[str, str]] = []
+    inbound: list[tuple[str, str]] = []
+    outbound: list[tuple[str, str]] = []
+
+    for src, targets in graph_edges.items():
+        src_inside = src in focus_files
+        for tgt in targets:
+            tgt_inside = tgt in focus_files
+            if src_inside and tgt_inside:
+                internal.append((src, tgt))
+            elif src_inside and not tgt_inside:
+                outbound.append((src, tgt))
+            elif not src_inside and tgt_inside:
+                inbound.append((src, tgt))
+
+    return sorted(internal), sorted(inbound), sorted(outbound)