rpr-cli 0.1.1__py3-none-any.whl

rpr/generators/cursor.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from rpr.context import RunContext
+from rpr.generators.base import Rule, interpolate
+
+HEADER = "<!-- Generated by rpr sync -- do not edit manually -->\n\n"
+
+
+def generate_cursor_rules(
+    rules: list[Rule],
+    project_dir: Path,
+    variables: dict[str, str],
+    ctx: RunContext,
+) -> None:
+    rules_dir = project_dir / ".cursor" / "rules"
+    ctx.ensure_dir(rules_dir)
+
+    for rule in rules:
+        content = interpolate(rule.content, variables)
+        globs = rule.apply_to
+
+        mdc = f"""---
+description: {rule.description}
+globs: {globs}
+alwaysApply: {"true" if globs == "**" else "false"}
+---
+
+{HEADER}{content}
+"""
+        ctx.write_file(
+            rules_dir / f"{rule.id}.mdc",
+            mdc,
+            preview_markdown=True,
+            markdown_title=f"Cursor Rule Preview: {rule.id}",
+            markdown_max_lines=80,
+        )

rpr/generators/gemini.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from rpr.context import RunContext
+from rpr.generators.base import Rule, interpolate
+
+HEADER = "<!-- Generated by rpr sync -- do not edit manually -->\n\n"
+
+
+def generate_gemini_rules(
+    rules: list[Rule],
+    project_dir: Path,
+    variables: dict[str, str],
+    ctx: RunContext,
+) -> None:
+    sections: list[str] = [HEADER.strip()]
+
+    for rule in rules:
+        content = interpolate(rule.content, variables)
+        section_header = (
+            f"## {rule.description}" if rule.description else f"## {rule.id}"
+        )
+        sections.append(f"{section_header}\n\n{content}")
+
+    full_content = "\n\n---\n\n".join(sections) + "\n"
+    ctx.write_file(
+        project_dir / "GEMINI.md",
+        full_content,
+        preview_markdown=True,
+        markdown_title="Gemini Instructions Preview",
+        markdown_max_lines=80,
+    )

rpr/map/architecture.py

@@ -0,0 +1,495 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from rpr.map.graph import DependencyGraph
+from rpr.map.topology import DirectoryEdge, DirectoryTopology
+
+# ---------------------------------------------------------------------------
+# Tunable thresholds
+# ---------------------------------------------------------------------------
+
+_LARGE_DIR_FACTOR: float = 2.5
+_HIGH_DEGREE_FACTOR: float = 2.5
+_CYCLE_FILE_FRACTION: float = 0.15
+_MIN_ONION_DIRS: int = 2
+_WRAPPER_NAMES: frozenset[str] = frozenset({"src", "lib", "packages", "apps", "pkg"})
+_TOP_HOTSPOT_FILES: int = 5  # max file-level bottlenecks reported per hotspot
+
+
+# ---------------------------------------------------------------------------
+# Value objects
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ArchitectureSignal:
+    """Evidence supporting the classification of a directory as entry or core."""
+
+    directory: str
+    in_degree: int
+    out_degree: int
+    file_count: int
+    note: str
+
+
+@dataclass(frozen=True)
+class CycleSummary:
+    """A file-level import cycle expressed alongside its directory-level projection."""
+
+    file_cycle: tuple[str, ...]
+    directory_cycle: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Hotspot:
+    """A directory flagged as potentially problematic."""
+
+    directory: str
+    reason: str  # space-separated subset of: "large", "highly_connected", "mixed_role"
+    file_count: int
+    in_degree: int
+    out_degree: int
+    top_fan_in_files: tuple[tuple[str, int], ...] = ()  # (file_path, fan_in_count)
+    top_fan_out_files: tuple[tuple[str, int], ...] = ()  # (file_path, fan_out_count)
+
+
+@dataclass
+class ArchitectureAssessment:
+    """Agent-readable interpretation of a repository's architectural structure."""
+
+    entry_files: list[str]
+    entry_directories: list[ArchitectureSignal]
+    core_directories: list[ArchitectureSignal]
+    leaf_files: list[str]
+    leaf_directories: list[str]
+    cycle_summaries: list[CycleSummary]
+    directory_cycles: list[tuple[str, ...]]
+    hotspots: list[Hotspot]
+    warnings: list[str]
+    verdict: Literal["likely_onion", "layered_but_mixed", "unclear"]
+    verdict_reasoning: list[str]  # conditions that led to this verdict
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _posix_parent(path: str) -> str:
+    idx = path.rfind("/")
+    return path[:idx] if idx != -1 else ""
+
+
+def _cycle_to_dir_projection(file_cycle: list[str]) -> tuple[str, ...]:
+    """Project a file-level cycle onto its parent directories.
+
+    Adjacent duplicates are collapsed so that intra-directory hops do not
+    produce repeated directory entries in the summary.
+    """
+    dirs: list[str] = []
+    for f in file_cycle:
+        d = _posix_parent(f)
+        if not dirs or dirs[-1] != d:
+            dirs.append(d)
+    return tuple(dirs)
+
+
+def _detect_directory_cycles(adj: dict[str, list[str]]) -> list[list[str]]:
+    """Iterative DFS cycle detection on a directory adjacency dict."""
+    WHITE, GRAY, BLACK = 0, 1, 2
+    all_nodes: set[str] = set(adj.keys())
+    for deps in adj.values():
+        all_nodes.update(deps)
+    color: dict[str, int] = {n: WHITE for n in all_nodes}
+    found: list[list[str]] = []
+    seen: set[tuple[str, ...]] = set()
+
+    for start in sorted(all_nodes):
+        if color[start] != WHITE:
+            continue
+        path: list[str] = [start]
+        stack: list[tuple[str, int, list[str]]] = [(start, 0, adj.get(start, []))]
+        color[start] = GRAY
+        while stack:
+            node, idx, nbrs = stack[-1]
+            if idx < len(nbrs):
+                stack[-1] = (node, idx + 1, nbrs)
+                nb = nbrs[idx]
+                if color.get(nb, WHITE) == GRAY:
+                    ci = path.index(nb)
+                    cycle = path[ci:] + [nb]
+                    canonical = _canonical_dir_cycle(cycle)
+                    if canonical not in seen:
+                        seen.add(canonical)
+                        found.append(cycle)
+                elif color.get(nb, WHITE) == WHITE:
+                    color[nb] = GRAY
+                    path.append(nb)
+                    stack.append((nb, 0, adj.get(nb, [])))
+            else:
+                stack.pop()
+                path.pop()
+                color[node] = BLACK
+    return found
+
+
+def _canonical_dir_cycle(cycle: list[str]) -> tuple[str, ...]:
+    body = cycle[:-1]
+    if not body:
+        return ()
+    min_idx = body.index(min(body))
+    return tuple(body[min_idx:] + body[:min_idx])
+
+
+def _resolve_top_dirs(raw_top_dirs: set[str], topology: DirectoryTopology) -> set[str]:
+    """Unwrap wrapper directories one level deep.
+
+    A depth-1 directory whose name is in ``_WRAPPER_NAMES`` and has child
+    directories is replaced by its immediate children.  All other depth-1
+    directories are kept as-is.
+    """
+    resolved: set[str] = set()
+    for d in raw_top_dirs:
+        node = topology.nodes.get(d)
+        if d in _WRAPPER_NAMES and node and node.children:
+            resolved.update(node.children)
+        else:
+            resolved.add(d)
+    return resolved
+
+
+def _map_to_effective_dir(directory: str, top_dirs: set[str]) -> str | None:
+    """Map a full-depth directory path to its effective top-level directory.
+
+    Returns the element of *top_dirs* that *directory* equals or is a
+    descendant of, or ``None`` if no match is found.
+    """
+    if directory in top_dirs:
+        return directory
+    for td in top_dirs:
+        if directory.startswith(td + "/"):
+            return td
+    return None
+
+
+def _compute_effective_edges(
+    topology: DirectoryTopology, top_dirs: set[str]
+) -> list[DirectoryEdge]:
+    """Compute edges between effective top-level directories.
+
+    Each full-depth edge is mapped through ``_map_to_effective_dir``.
+    Self-loops (both endpoints resolve to the same effective dir) are excluded.
+    Representatives and support are merged across all contributing edges.
+    """
+    accumulator: dict[tuple[str, str], list[tuple[str, str]]] = {}
+    for edge in topology.edges.values():
+        src = _map_to_effective_dir(edge.source, top_dirs)
+        tgt = _map_to_effective_dir(edge.target, top_dirs)
+        if src is None or tgt is None or src == tgt:
+            continue
+        bucket = accumulator.setdefault((src, tgt), [])
+        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_files_in_dir(
+    directory: str,
+    all_files: set[str],
+    metric: dict[str, int],
+    top_n: int,
+) -> tuple[tuple[str, int], ...]:
+    """Return the top_n files within *directory* ranked by *metric* descending.
+
+    Only includes files with a non-zero metric value.
+    """
+    prefix = directory + "/"
+    dir_files = [f for f in all_files if f == directory or f.startswith(prefix)]
+    ranked = sorted(dir_files, key=lambda f: -metric.get(f, 0))
+    return tuple((f, metric.get(f, 0)) for f in ranked[:top_n] if metric.get(f, 0) > 0)
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def assess_architecture(
+    graph: DependencyGraph, topology: DirectoryTopology
+) -> ArchitectureAssessment:
+    """Produce an ArchitectureAssessment from a file-level graph and directory topology.
+
+    The assessment is conservative: a ``likely_onion`` verdict is only emitted
+    when dependency flow is predominantly inward and the derived top-level
+    directory graph is acyclic with no high file-level cycle density.
+    """
+    # ── 1. File-level degrees ────────────────────────────────────────────────
+    all_files = {str(n.rel_path).replace("\\", "/") for n in graph.nodes}
+    file_out: dict[str, int] = {f: len(graph.edges.get(f, [])) for f in all_files}
+    file_in: dict[str, int] = {
+        f: len(graph.reverse_edges.get(f, [])) for f in all_files
+    }
+
+    # ── 2. Entry files (no importer, has outgoing deps) ──────────────────────
+    entry_files = sorted(
+        f for f in all_files if file_in.get(f, 0) == 0 and file_out.get(f, 0) > 0
+    )
+
+    # ── 3. Leaf files (no outgoing deps to tracked files) ────────────────────
+    leaf_files = sorted(f for f in all_files if file_out.get(f, 0) == 0)
+
+    # ── 4. Top-level directory degree computation ─────────────────────────────
+    # Depth-1 directories are the initial candidates.  Wrapper directories
+    # (e.g. "src", "packages") that contain sub-directories are unwrapped
+    # one level so the analysis reflects the real architectural components.
+    raw_top_dirs: set[str] = {d for d in topology.nodes if d and "/" not in d}
+    top_dirs = _resolve_top_dirs(raw_top_dirs, topology)
+    top_edges = _compute_effective_edges(topology, top_dirs)
+
+    dir_out_targets: dict[str, set[str]] = {d: set() for d in top_dirs}
+    dir_in_sources: dict[str, set[str]] = {d: set() for d in top_dirs}
+
+    for edge in top_edges:
+        if edge.source in top_dirs:
+            dir_out_targets[edge.source].add(edge.target)
+        if edge.target in top_dirs:
+            dir_in_sources[edge.target].add(edge.source)
+
+    dir_out_deg: dict[str, int] = {d: len(s) for d, s in dir_out_targets.items()}
+    dir_in_deg: dict[str, int] = {d: len(s) for d, s in dir_in_sources.items()}
+    # Use recursive file count so parent dirs reflect their full subtree.
+    dir_file_count: dict[str, int] = {d: len(topology.files_in(d)) for d in top_dirs}
+
+    # ── 5. Entry directories (in=0, out>0) ───────────────────────────────────
+    entry_directories: list[ArchitectureSignal] = [
+        ArchitectureSignal(
+            directory=d,
+            in_degree=dir_in_deg[d],
+            out_degree=dir_out_deg[d],
+            file_count=dir_file_count[d],
+            note=f"entry: {dir_out_deg[d]} outgoing, 0 incoming top-level deps",
+        )
+        for d in sorted(top_dirs)
+        if dir_out_deg[d] > 0 and dir_in_deg[d] == 0
+    ]
+
+    # ── 6. Core directories (out=0, in>0) ────────────────────────────────────
+    core_directories: list[ArchitectureSignal] = [
+        ArchitectureSignal(
+            directory=d,
+            in_degree=dir_in_deg[d],
+            out_degree=dir_out_deg[d],
+            file_count=dir_file_count[d],
+            note=f"core: {dir_in_deg[d]} incoming, 0 outgoing top-level deps",
+        )
+        for d in sorted(top_dirs)
+        if dir_in_deg[d] > 0 and dir_out_deg[d] == 0
+    ]
+
+    # ── 7. Leaf directories (no edges at all — fully isolated) ───────────────
+    leaf_directories = sorted(
+        d for d in top_dirs if dir_out_deg[d] == 0 and dir_in_deg[d] == 0
+    )
+
+    # ── 8. Cycle summaries from the file-level graph ──────────────────────────
+    cycle_summaries: list[CycleSummary] = [
+        CycleSummary(
+            file_cycle=tuple(fc),
+            directory_cycle=_cycle_to_dir_projection(fc),
+        )
+        for fc in graph.cycles
+    ]
+
+    # ── 9. Directory-level cycle detection ────────────────────────────────────
+    dir_adj: dict[str, list[str]] = {d: sorted(dir_out_targets[d]) for d in top_dirs}
+    dir_cycles = _detect_directory_cycles(dir_adj)
+
+    # ── 10. Hotspots ──────────────────────────────────────────────────────────
+    hotspots: list[Hotspot] = []
+    if top_dirs:
+        mean_files = sum(dir_file_count.values()) / len(top_dirs)
+        mean_deg = sum(dir_out_deg[d] + dir_in_deg[d] for d in top_dirs) / len(top_dirs)
+        for d in sorted(top_dirs):
+            fc = dir_file_count[d]
+            out_d = dir_out_deg[d]
+            in_d = dir_in_deg[d]
+            labels: list[str] = []
+            if mean_files > 0 and fc > _LARGE_DIR_FACTOR * mean_files:
+                labels.append("large")
+            if mean_deg > 0 and (out_d + in_d) > _HIGH_DEGREE_FACTOR * mean_deg:
+                labels.append("highly_connected")
+            if in_d >= 2 and out_d >= 2:
+                labels.append("mixed_role")
+            if labels:
+                top_fi = _top_files_in_dir(d, all_files, file_in, _TOP_HOTSPOT_FILES)
+                top_fo = _top_files_in_dir(d, all_files, file_out, _TOP_HOTSPOT_FILES)
+                hotspots.append(
+                    Hotspot(
+                        directory=d,
+                        reason=" ".join(labels),
+                        file_count=fc,
+                        in_degree=in_d,
+                        out_degree=out_d,
+                        top_fan_in_files=top_fi,
+                        top_fan_out_files=top_fo,
+                    )
+                )
+
+    # ── 11. Warnings ──────────────────────────────────────────────────────────
+    warnings: list[str] = []
+
+    files_in_cycles: set[str] = set()
+    for fc in graph.cycles:
+        files_in_cycles.update(fc)
+    cycle_density = len(files_in_cycles) / max(len(all_files), 1)
+
+    if cycle_density > _CYCLE_FILE_FRACTION:
+        warnings.append(
+            f"High cycle density: {len(files_in_cycles)} of {len(all_files)} files "
+            f"({cycle_density:.0%}) are involved in import cycles."
+        )
+
+    if dir_cycles:
+        warnings.append(
+            f"{len(dir_cycles)} top-level directory cycle(s) detected; "
+            "dependency flow is not strictly layered."
+        )
+
+    bi_coupled = [
+        (a, b)
+        for a in sorted(top_dirs)
+        for b in sorted(dir_out_targets.get(a, set()))
+        if a < b and a in dir_out_targets.get(b, set())
+    ]
+    if bi_coupled:
+        pairs = ", ".join(f"{a}<->{b}" for a, b in bi_coupled[:3])
+        suffix = f" (+{len(bi_coupled) - 3} more)" if len(bi_coupled) > 3 else ""
+        warnings.append(
+            f"Bidirectional coupling between top-level directories: {pairs}{suffix}."
+        )
+
+    for h in hotspots:
+        warnings.append(
+            f"Hotspot '{h.directory}': {h.reason} "
+            f"(files={h.file_count}, in={h.in_degree}, out={h.out_degree})."
+        )
+
+    # ── 12. Verdict ────────────────────────────────────────────────────────────
+    has_entry = bool(entry_directories)
+    has_core = bool(core_directories)
+    has_dir_cycles = bool(dir_cycles)
+    high_cycle_density = cycle_density > _CYCLE_FILE_FRACTION
+
+    if (
+        len(top_dirs) >= _MIN_ONION_DIRS
+        and has_entry
+        and has_core
+        and not has_dir_cycles
+        and not high_cycle_density
+    ):
+        verdict: Literal["likely_onion", "layered_but_mixed", "unclear"] = (
+            "likely_onion"
+        )
+    elif not high_cycle_density and (has_entry or has_core) and len(top_dirs) >= 2:
+        verdict = "layered_but_mixed"
+    else:
+        verdict = "unclear"
+
+    if verdict == "unclear":
+        reasons: list[str] = []
+        if high_cycle_density:
+            reasons.append("high cycle density")
+        if not has_entry:
+            reasons.append("no clear entry directories identified")
+        if not has_core:
+            reasons.append("no clear core directories identified")
+        if len(top_dirs) < 2:
+            reasons.append("too few top-level directories to assess structure")
+        if reasons:
+            warnings.append(f"Verdict is unclear: {'; '.join(reasons)}.")
+
+    # ── 13. Verdict reasoning ──────────────────────────────────────────────────
+    verdict_reasoning: list[str] = []
+
+    if entry_directories:
+        _names = ", ".join(sig.directory for sig in entry_directories[:3])
+        _suffix = (
+            f" (+{len(entry_directories) - 3} more)"
+            if len(entry_directories) > 3
+            else ""
+        )
+        verdict_reasoning.append(f"Entry areas detected: {_names}{_suffix}")
+    else:
+        verdict_reasoning.append("No clear entry areas detected")
+
+    if core_directories:
+        _names = ", ".join(sig.directory for sig in core_directories[:3])
+        _suffix = (
+            f" (+{len(core_directories) - 3} more)" if len(core_directories) > 3 else ""
+        )
+        verdict_reasoning.append(f"Core areas detected: {_names}{_suffix}")
+    else:
+        verdict_reasoning.append("No clear core areas detected")
+
+    if dir_cycles:
+        verdict_reasoning.append(
+            f"Directory cycles present ({len(dir_cycles)}): dependency flow is not strictly layered"
+        )
+    else:
+        verdict_reasoning.append("No directory-level cycles detected")
+
+    if high_cycle_density:
+        verdict_reasoning.append(
+            f"High file-level cycle density: {cycle_density:.0%} of files in cycles "
+            f"(threshold {_CYCLE_FILE_FRACTION:.0%})"
+        )
+    else:
+        verdict_reasoning.append(
+            f"Cycle density within threshold: {cycle_density:.0%} of files in cycles"
+        )
+
+    if bi_coupled:
+        _pairs_str = ", ".join(f"{a}<->{b}" for a, b in bi_coupled[:2])
+        _suffix = f" (+{len(bi_coupled) - 2} more)" if len(bi_coupled) > 2 else ""
+        verdict_reasoning.append(
+            f"Bidirectional coupling between top-level directories: {_pairs_str}{_suffix}"
+        )
+    else:
+        verdict_reasoning.append(
+            "No bidirectional coupling between top-level directories"
+        )
+
+    mixed_role_hs = [h for h in hotspots if "mixed_role" in h.reason]
+    if mixed_role_hs:
+        _names = ", ".join(h.directory for h in mixed_role_hs[:3])
+        _suffix = f" (+{len(mixed_role_hs) - 3} more)" if len(mixed_role_hs) > 3 else ""
+        verdict_reasoning.append(f"Mixed-role hotspots detected: {_names}{_suffix}")
+    else:
+        verdict_reasoning.append("No mixed-role hotspots detected")
+
+    return ArchitectureAssessment(
+        entry_files=entry_files,
+        entry_directories=entry_directories,
+        core_directories=core_directories,
+        leaf_files=leaf_files,
+        leaf_directories=leaf_directories,
+        cycle_summaries=cycle_summaries,
+        directory_cycles=[tuple(dc) for dc in dir_cycles],
+        hotspots=hotspots,
+        warnings=warnings,
+        verdict=verdict,
+        verdict_reasoning=verdict_reasoning,
+    )