rpr-cli 0.1.1__py3-none-any.whl

rpr/map/output.py

@@ -0,0 +1,1030 @@
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from rpr.map.architecture import ArchitectureAssessment
+from rpr.map.chains import RepresentativeChain
+from rpr.map.classifier import ClassifiedNode
+from rpr.map.coverage import CoverageRecord
+from rpr.map.dependencies import ExternalDependencySummary
+from rpr.map.graph import DependencyGraph
+from rpr.map.responsibility import ResponsibilitySummary
+from rpr.map.topology import DirectoryTopology, focus_edges
+from rpr.ui.console import console
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_LAYER_ORDER: list[str] = [
+    "entry_point",
+    "application",
+    "entity",
+    "dto",
+    "repository",
+    "infrastructure",
+    "ui_component",
+    "ui_util",
+    "unknown",
+    "test",
+]
+
+# (fill, stroke) per layer for Mermaid subgraph styles
+_LAYER_COLORS: dict[str, tuple[str, str]] = {
+    "entry_point": ("#D6EAF8", "#5B9BD5"),
+    "application": ("#D5F5E3", "#52BE80"),
+    "entity": ("#FEF9E7", "#F1C40F"),
+    "dto": ("#FDEBD0", "#E67E22"),
+    "repository": ("#E8DAEF", "#8E44AD"),
+    "infrastructure": ("#FADBD8", "#E74C3C"),
+    "ui_component": ("#D1F2EB", "#1ABC9C"),
+    "ui_util": ("#EBF5FB", "#3498DB"),
+    "unknown": ("#F2F3F4", "#95A5A6"),
+}
+
+# (fill, stroke) per topology role for the topology-based Mermaid diagram
+_TOPOLOGY_COLORS: dict[str, tuple[str, str]] = {
+    "entry": ("#D6EAF8", "#5B9BD5"),
+    "core": ("#D5F5E3", "#52BE80"),
+    "leaf": ("#F2F3F4", "#95A5A6"),
+    "other": ("#FEF9E7", "#F1C40F"),
+}
+
+# Test layer is excluded from the diagram to keep it focused on production code
+_DIAGRAM_SKIP_LAYERS: frozenset[str] = frozenset({"test"})
+_DIAGRAM_TOP_N = 3  # max nodes shown per subgraph in default mode
+_EDGE_LIMIT = 300  # max edge lines before truncation
+_MODULE_EDGE_LIMIT = 50  # max module-level edges in the module dependency graph
+_DRY_RUN_LINES = 30  # lines printed in --dry-run mode
+
+# Limits for the three new enrichment sections
+_EXT_DEPS_DIR_LIMIT = 20   # max directories shown in external-dependencies section
+_RESP_DIR_LIMIT = 30       # max directories shown in responsibilities section
+_COV_DIR_LIMIT = 30        # max directories shown in coverage section
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _sanitize_id(path_str: str) -> str:
+    """Convert a file path to a valid Mermaid node ID."""
+    return re.sub(r"[/.\-]", "_", path_str)
+
+
+def _group_by_layer(nodes: list[ClassifiedNode]) -> dict[str, list[ClassifiedNode]]:
+    """Group nodes by layer, sorted by in_degree descending within each group."""
+    groups: dict[str, list[ClassifiedNode]] = defaultdict(list)
+    for node in nodes:
+        groups[node.layer].append(node)
+    return {
+        layer: sorted(members, key=lambda n: n.in_degree, reverse=True)
+        for layer, members in groups.items()
+    }
+
+
+def _collect_languages(nodes: list[ClassifiedNode]) -> list[str]:
+    return sorted({node.file.language for node in nodes})
+
+
+# ---------------------------------------------------------------------------
+# Section renderers
+# ---------------------------------------------------------------------------
+
+
+def _render_header(
+    graph: DependencyGraph, nodes: list[ClassifiedNode], root: Path
+) -> str:
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    languages = ", ".join(_collect_languages(nodes)) or "none"
+    lines = [
+        "# Code Map",
+        "",
+        f"Generated: {ts}",
+        f"Root: {root}",
+        f"Files analyzed: {len(nodes)}",
+        f"Languages: {languages}",
+        f"Backend: {graph.backend}",
+    ]
+    return "\n".join(lines)
+
+
+def _render_layer_table(groups: dict[str, list[ClassifiedNode]]) -> str:
+    rows = []
+    for layer in _LAYER_ORDER:
+        members = groups.get(layer)
+        if not members:
+            continue
+        top3 = ", ".join(m.file.rel_path.as_posix() for m in members[:3])
+        rows.append(f"| {layer} | {len(members)} | {top3} |")
+
+    if not rows:
+        return ""
+
+    lines = [
+        "## Layer Summary",
+        "",
+        "| Layer | File count | Entry files (top 3 by in-degree) |",
+        "|-------|-----------|----------------------------------|",
+    ] + rows
+    return "\n".join(lines)
+
+
+def _render_entry_points(groups: dict[str, list[ClassifiedNode]]) -> str:
+    members = groups.get("entry_point")
+    if not members:
+        return ""
+    lines = ["## Entry Points", ""]
+    for node in members:
+        lines.append(
+            f"- {node.file.rel_path.as_posix()} (out-degree: {node.out_degree})"
+        )
+    return "\n".join(lines)
+
+
+def _build_mermaid(
+    groups: dict[str, list[ClassifiedNode]],
+    graph: DependencyGraph,
+    nodes: list[ClassifiedNode],
+    details: bool,
+) -> str:
+    # Only include layers that have files and are not skipped
+    active_layers = [
+        layer
+        for layer in _LAYER_ORDER
+        if layer not in _DIAGRAM_SKIP_LAYERS and groups.get(layer)
+    ]
+    if not active_layers:
+        return ""
+
+    # Build a lookup: posix rel_path → layer
+    node_layer: dict[str, str] = {n.file.rel_path.as_posix(): n.layer for n in nodes}
+
+    lines: list[str] = []
+
+    # --- Subgraph blocks ---
+    for layer in active_layers:
+        members = groups[layer]
+        shown = members if details else members[:_DIAGRAM_TOP_N]
+        sg_id = f"{layer}_sg"
+        lines.append(f'    subgraph {sg_id}["{layer}"]')
+        for node in shown:
+            node_id = _sanitize_id(node.file.rel_path.as_posix())
+            label = node.file.rel_path.name
+            lines.append(f'        {node_id}["{label}"]')
+        lines.append("    end")
+
+    lines.append("")
+
+    # --- Edges ---
+    if details:
+        # Individual node-to-node edges (skip test-layer nodes)
+        test_keys = {n.file.rel_path.as_posix() for n in nodes if n.layer == "test"}
+        seen_edges: set[tuple[str, str]] = set()
+        for src, deps in sorted(graph.edges.items()):
+            if src in test_keys or node_layer.get(src) in _DIAGRAM_SKIP_LAYERS:
+                continue
+            for dep in deps:
+                if dep in test_keys or node_layer.get(dep) in _DIAGRAM_SKIP_LAYERS:
+                    continue
+                pair = (src, dep)
+                if pair not in seen_edges:
+                    seen_edges.add(pair)
+                    src_id = _sanitize_id(src)
+                    dep_id = _sanitize_id(dep)
+                    lines.append(f"    {src_id} --> {dep_id}")
+    else:
+        # Subgraph-to-subgraph edges (deduplicated, no self-loops)
+        seen_sg_edges: set[tuple[str, str]] = set()
+        for src, deps in graph.edges.items():
+            src_layer = node_layer.get(src)
+            if not src_layer or src_layer in _DIAGRAM_SKIP_LAYERS:
+                continue
+            for dep in deps:
+                dep_layer = node_layer.get(dep)
+                if not dep_layer or dep_layer in _DIAGRAM_SKIP_LAYERS:
+                    continue
+                if src_layer == dep_layer:
+                    continue
+                pair = (src_layer, dep_layer)
+                if pair not in seen_sg_edges:
+                    seen_sg_edges.add(pair)
+                    lines.append(f"    {src_layer}_sg --> {dep_layer}_sg")
+
+    lines.append("")
+
+    # --- Subgraph styles ---
+    for layer in active_layers:
+        if layer in _LAYER_COLORS:
+            fill, stroke = _LAYER_COLORS[layer]
+            lines.append(f"    style {layer}_sg fill:{fill},stroke:{stroke},color:#000")
+
+    inner = "\n".join(lines)
+
+    diagram = (
+        "## Architecture Diagram\n\n"
+        "```mermaid\n"
+        "---\n"
+        "config:\n"
+        "  layout: elk\n"
+        "  theme: base\n"
+        "---\n"
+        "flowchart TB\n"
+        f"{inner}\n"
+        "```"
+    )
+    return diagram
+
+
+def _render_layers_breakdown(groups: dict[str, list[ClassifiedNode]]) -> str:
+    sections: list[str] = ["## Layers Breakdown"]
+    for layer in _LAYER_ORDER:
+        members = groups.get(layer)
+        if not members:
+            continue
+        # Capitalise the layer label for the heading
+        heading = layer.replace("_", " ").title()
+        sections.append(f"\n### {heading}")
+        for node in members:
+            leaf_suffix = " (leaf)" if node.is_leaf else ""
+            path = node.file.rel_path.as_posix()
+            sections.append(
+                f"- {path} — {node.in_degree} dependents, {node.out_degree} dependencies{leaf_suffix}"
+            )
+    return "\n".join(sections)
+
+
+def _render_edges(graph: DependencyGraph, nodes: list[ClassifiedNode]) -> str:
+    test_keys = {n.file.rel_path.as_posix() for n in nodes if n.layer == "test"}
+    leaf_keys = {n.file.rel_path.as_posix() for n in nodes if n.is_leaf}
+    skip_keys = test_keys | leaf_keys
+
+    edge_lines: list[str] = []
+    for src in sorted(graph.edges):
+        if src in skip_keys:
+            continue
+        deps = sorted(d for d in graph.edges[src] if d not in skip_keys)
+        if not deps:
+            continue
+        edge_lines.append(f"`{src}` \u2192 {', '.join(f'`{d}`' for d in deps)}")
+
+    if not edge_lines:
+        return ""
+
+    total = len(edge_lines)
+    truncation_note = ""
+    if total > _EDGE_LIMIT:
+        omitted = total - _EDGE_LIMIT
+        edge_lines = edge_lines[:_EDGE_LIMIT]
+        truncation_note = f"\n_(truncated \u2014 {omitted} edges omitted)_"
+
+    lines = ["## Dependency Edges", ""] + edge_lines
+    if truncation_note:
+        lines.append(truncation_note)
+    return "\n".join(lines)
+
+
+def _render_cycles(graph: DependencyGraph) -> str:
+    if not graph.cycles:
+        return ""
+    lines = ["## \u26a0 Cycles Detected", ""]
+    for cycle in graph.cycles:
+        lines.append("- " + " \u2192 ".join(cycle))
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Multi-resolution section renderers (17d)
+# ---------------------------------------------------------------------------
+
+
+def _render_architecture_summary(assessment: ArchitectureAssessment | None) -> str:
+    if assessment is None:
+        return ""
+
+    lines = ["## Architecture Summary", "", f"Verdict: **{assessment.verdict}**"]
+
+    if assessment.verdict_reasoning:
+        lines.append("")
+        lines.append("**Reasoning:**")
+        for r in assessment.verdict_reasoning:
+            lines.append(f"- {r}")
+
+    if assessment.entry_directories:
+        lines.append("\n### Entry Areas")
+        for sig in assessment.entry_directories:
+            lines.append(
+                f"- {sig.directory} ({sig.file_count} files, {sig.out_degree} outgoing, {sig.in_degree} incoming top-level deps)"
+            )
+
+    if assessment.core_directories:
+        lines.append("\n### Core Areas")
+        for sig in assessment.core_directories:
+            lines.append(
+                f"- {sig.directory} ({sig.file_count} files, {sig.out_degree} outgoing, {sig.in_degree} incoming top-level deps)"
+            )
+
+    if assessment.leaf_directories:
+        lines.append("\n### Leaf Areas")
+        for d in assessment.leaf_directories:
+            lines.append(f"- {d}")
+
+    if assessment.warnings:
+        lines.append("\n### Warnings")
+        for w in assessment.warnings:
+            lines.append(f"- {w}")
+
+    return "\n".join(lines)
+
+
+def _render_top_level_graph(topology: DirectoryTopology | None) -> str:
+    if topology is None:
+        return ""
+    edges = topology.top_level_edges()
+    if not edges:
+        return ""
+    lines = ["## Top-Level Dependencies", ""]
+    for edge in edges:
+        src = edge.source or "(root)"
+        tgt = edge.target or "(root)"
+        lines.append(f"`{src}` -> `{tgt}` ({edge.support} file edges)")
+    return "\n".join(lines)
+
+
+def _render_directory_tree(topology: DirectoryTopology | None) -> str:
+    if topology is None:
+        return ""
+
+    tree_lines: list[str] = []
+
+    def _walk(path: str, depth: int) -> None:
+        node = topology.nodes.get(path)
+        if node is None:
+            return
+        for child in node.children:
+            child_name = child[len(path) + 1 :] if path else child
+            tree_lines.append("  " * depth + child_name + "/")
+            _walk(child, depth + 1)
+
+    _walk("", 0)
+
+    if not tree_lines:
+        return ""
+
+    lines = ["## Directory Tree", "", "```"] + tree_lines + ["```"]
+    return "\n".join(lines)
+
+
+def _render_module_graph(topology: DirectoryTopology | None) -> str:
+    if topology is None:
+        return ""
+    edges = topology.edges_at_depth(2)
+    if not edges:
+        return ""
+
+    lines = ["## Module Dependencies", ""]
+    total = len(edges)
+    truncation_note = ""
+    if total > _MODULE_EDGE_LIMIT:
+        omitted = total - _MODULE_EDGE_LIMIT
+        edges = edges[:_MODULE_EDGE_LIMIT]
+        truncation_note = f"\n_(truncated \u2014 {omitted} edges omitted)_"
+
+    for edge in edges:
+        src = edge.source or "(root)"
+        tgt = edge.target or "(root)"
+        lines.append(f"`{src}` -> `{tgt}` ({edge.support} file edges)")
+
+    if truncation_note:
+        lines.append(truncation_note)
+    return "\n".join(lines)
+
+
+def _render_chains(chains: list[RepresentativeChain] | None) -> str:
+    if not chains:
+        return ""
+
+    lines = ["## Representative Coupling Paths", ""]
+    for i, chain in enumerate(chains, 1):
+        score_note = (
+            f" (coupling score: {chain.coupling_score})" if chain.coupling_score else ""
+        )
+        lines.append(f"### Path {i}: {chain.reason}{score_note}")
+        file_seq = " -> ".join(f"`{f}`" for f in chain.files)
+        lines.append(f"Files: {file_seq}")
+        if chain.directories_crossed:
+            dirs = " -> ".join(f"`{d}`" for d in chain.directories_crossed)
+            lines.append(f"Directories: {dirs}")
+        if chain.truncated and chain.truncation_note:
+            lines.append(f"Note: {chain.truncation_note}")
+        if chain.edge_examples:
+            lines.append("")
+            lines.append("Edge examples:")
+            for ex in chain.edge_examples:
+                lines.append(
+                    f"- `{ex.source_directory}` -> `{ex.target_directory}`: `{ex.source_file}` -> `{ex.target_file}`"
+                )
+        lines.append("")
+
+    return "\n".join(lines).rstrip()
+
+
+def _render_diagnostic_chains(chains: list[RepresentativeChain]) -> str:
+    """Render shortest-path chains for diagnostic validation in --details appendix."""
+    if not chains:
+        return ""
+    lines = [
+        "## Shortest-Path Chains (Diagnostic)",
+        "",
+        "_BFS traversal order — useful for validating graph traversal correctness._",
+        "",
+    ]
+    for i, chain in enumerate(chains, 1):
+        lines.append(f"### Chain {i}: {chain.reason}")
+        file_seq = " -> ".join(f"`{f}`" for f in chain.files)
+        lines.append(f"Files: {file_seq}")
+        if chain.truncated and chain.truncation_note:
+            lines.append(f"Note: {chain.truncation_note}")
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def _render_cycles_and_hotspots(
+    assessment: ArchitectureAssessment | None,
+    graph: DependencyGraph,
+) -> str:
+    has_cycles = bool(graph.cycles)
+    has_dir_cycles = assessment is not None and bool(assessment.directory_cycles)
+    has_hotspots = assessment is not None and bool(assessment.hotspots)
+
+    if not has_cycles and not has_dir_cycles and not has_hotspots:
+        return ""
+
+    lines = ["## Cycles and Hotspots"]
+
+    if has_dir_cycles and assessment is not None:
+        lines.append("\n### Directory Cycles")
+        for dc in assessment.directory_cycles:
+            lines.append("- " + " -> ".join(dc))
+
+    if has_cycles:
+        lines.append("\n### File Cycles")
+        if assessment and assessment.cycle_summaries:
+            for cs in assessment.cycle_summaries:
+                cycle_str = " -> ".join(cs.file_cycle)
+                lines.append(f"- {cycle_str}")
+                if cs.directory_cycle and len(set(cs.directory_cycle)) > 1:
+                    dir_str = " -> ".join(cs.directory_cycle)
+                    lines.append(f"  Directories: {dir_str}")
+        else:
+            for cycle in graph.cycles:
+                lines.append("- " + " -> ".join(cycle))
+
+    if has_hotspots and assessment is not None:
+        lines.append("\n### Hotspots")
+        for h in assessment.hotspots:
+            lines.append(
+                f"- **{h.directory}**: {h.reason} (files={h.file_count}, in={h.in_degree}, out={h.out_degree})"
+            )
+            if h.top_fan_in_files:
+                top_fi = ", ".join(f"`{f}` ({n})" for f, n in h.top_fan_in_files[:3])
+                lines.append(f"  - Highest fan-in: {top_fi}")
+            if h.top_fan_out_files:
+                top_fo = ", ".join(f"`{f}` ({n})" for f, n in h.top_fan_out_files[:3])
+                lines.append(f"  - Highest fan-out: {top_fo}")
+
+    return "\n".join(lines)
+
+
+def _render_topology_mermaid(
+    topology: DirectoryTopology,
+    assessment: ArchitectureAssessment,
+) -> str:
+    """Render the Architecture Diagram from directory topology.
+
+    1. Single-child empty directories (like "rpr-parser" -> "src") are collapsed.
+    2. Deep directories are rendered as nested subgraphs showing the real structure.
+    3. Edges connect the subgraphs to limit lines.
+    """
+    # ── Step 1: dynamic forest roots from the root ("") ──
+    collapsed_map: dict[str, str] = {}
+    forest_roots: set[str] = set()
+
+    root_node = topology.nodes.get("")
+    if not root_node:
+        return ""
+
+    for child in root_node.children:
+        curr = child
+        while True:
+            node = topology.nodes.get(curr)
+            if not node:
+                break
+            if len(node.files) == 0 and len(node.children) == 1:
+                curr = node.children[0]
+            else:
+                break
+        forest_roots.add(curr)
+        collapsed_map[curr] = curr
+
+    rendered_dirs: set[str] = set()
+
+    def _collect_dirs(d: str) -> None:
+        rendered_dirs.add(d)
+        node = topology.nodes.get(d)
+        if node:
+            for c in node.children:
+                _collect_dirs(c)
+
+    for fr in forest_roots:
+        _collect_dirs(fr)
+
+    # ── Step 2: derive edges between rendered directories ──
+    active_edges: set[tuple[str, str]] = set()
+    for edge in topology.edges.values():
+        if (
+            edge.source in rendered_dirs
+            and edge.target in rendered_dirs
+            and edge.source != edge.target
+        ):
+            active_edges.add((edge.source, edge.target))
+
+    def _get_fr(d: str) -> str | None:
+        for fr in forest_roots:
+            if d == fr or d.startswith(fr + "/"):
+                return fr
+        return None
+
+    active_forest_roots: set[str] = set()
+    for src, tgt in active_edges:
+        fr_src = _get_fr(src)
+        fr_tgt = _get_fr(tgt)
+        if fr_src:
+            active_forest_roots.add(fr_src)
+        if fr_tgt:
+            active_forest_roots.add(fr_tgt)
+
+    if not active_forest_roots:
+        return ""
+
+    # ── Step 3: assign roles from assessment ──────────────────────────────────
+    entry_dirs = {sig.directory for sig in assessment.entry_directories}
+    core_dirs = {sig.directory for sig in assessment.core_directories}
+    leaf_dirs = set(assessment.leaf_directories)
+
+    def _role(fr: str) -> str:
+        if fr in entry_dirs:
+            return "entry"
+        if fr in core_dirs:
+            return "core"
+        if fr in leaf_dirs:
+            return "leaf"
+        for ed in entry_dirs:
+            if fr.startswith(ed) or ed.startswith(fr):
+                return "entry"
+        for cd in core_dirs:
+            if fr.startswith(cd) or cd.startswith(fr):
+                return "core"
+        for ld in leaf_dirs:
+            if fr.startswith(ld) or ld.startswith(fr):
+                return "leaf"
+        return "other"
+
+    lines: list[str] = []
+
+    # ── Step 4: subgraph blocks (recursive) ───────────────────────────────────
+    def _render_dir(d: str, label: str, depth: int) -> None:
+        node = topology.nodes.get(d)
+        if not node:
+            return
+
+        indent = "    " * depth
+        sg_id = _sanitize_id(d)
+        lines.append(f'{indent}subgraph {sg_id}["{label}"]')
+
+        for c in node.children:
+            _render_dir(c, Path(c).name, depth + 1)
+
+        lines.append(f"{indent}end")
+
+    for fr in sorted(active_forest_roots):
+        label = collapsed_map[fr]
+        _render_dir(fr, label, 1)
+
+    lines.append("")
+
+    # ── Step 5: edges ─────────────────────────────────────────────────────────
+    for src, tgt in sorted(active_edges):
+        # Skip ancestor↔descendant edges — Mermaid does not support edges
+        # between a parent subgraph and its own nested children.
+        if tgt.startswith(src + "/") or src.startswith(tgt + "/"):
+            continue
+        lines.append(f"    {_sanitize_id(src)} --> {_sanitize_id(tgt)}")
+
+    lines.append("")
+
+    # ── Step 6: style directives ──────────────────────────────────────────────
+    for fr in sorted(active_forest_roots):
+        fill, stroke = _TOPOLOGY_COLORS[_role(fr)]
+        lines.append(
+            f"    style {_sanitize_id(fr)} fill:{fill},stroke:{stroke},color:#000"
+        )
+
+    inner = "\n".join(lines)
+    return (
+        "## Architecture Diagram\n\n"
+        "```mermaid\n"
+        "---\n"
+        "config:\n"
+        "  layout: elk\n"
+        "  theme: base\n"
+        "---\n"
+        "flowchart TB\n"
+        f"{inner}\n"
+        "```"
+    )
+
+
+def _render_details_appendix(
+    groups: dict[str, list[ClassifiedNode]],
+    graph: DependencyGraph,
+    nodes: list[ClassifiedNode],
+    diagnostic_chains: list[RepresentativeChain] | None = None,
+) -> str:
+    sub_sections = [
+        _render_layer_table(groups),
+        _render_entry_points(groups),
+        _build_mermaid(groups, graph, nodes, details=True),
+        _render_layers_breakdown(groups),
+        _render_edges(graph, nodes),
+    ]
+    if diagnostic_chains:
+        sub_sections.append(_render_diagnostic_chains(diagnostic_chains))
+
+    parts: list[str] = []
+    for section in sub_sections:
+        if section.strip():
+            # Demote ## headings to ### inside the appendix
+            demoted = re.sub(r"^## ", "### ", section, flags=re.MULTILINE)
+            parts.append(demoted)
+
+    if not parts:
+        return ""
+
+    return "## Diagnostic Appendix\n\n" + "\n\n".join(parts)
+
+
+_FOCUS_FILE_LIMIT = 50
+_FOCUS_EDGE_LIMIT = 100
+
+
+def _render_focus_drilldown(
+    focus: str,
+    topology: DirectoryTopology,
+    graph: DependencyGraph,
+    assessment: ArchitectureAssessment,
+) -> str:
+    """Render a drill-down section for a specific directory.
+
+    Shows a file-level Mermaid diagram for the focused directory with inbound
+    and outbound external directory nodes for context.
+    """
+    internal_edges, inbound_edges, outbound_edges = focus_edges(
+        topology, focus, graph.edges
+    )
+
+    focus_files = topology.files_in(focus)
+    if not focus_files:
+        return ""
+
+    entry_dirs = {sig.directory for sig in assessment.entry_directories}
+    core_dirs = {sig.directory for sig in assessment.core_directories}
+
+    def _ext_dir(file_path: str) -> str:
+        """Return the top-level directory for an external file."""
+        parts = file_path.split("/")
+        return parts[0] if len(parts) > 1 else ""
+
+    def _role_color(d: str) -> tuple[str, str]:
+        if d in entry_dirs:
+            return _TOPOLOGY_COLORS["entry"]
+        if d in core_dirs:
+            return _TOPOLOGY_COLORS["core"]
+        return _TOPOLOGY_COLORS["other"]
+
+    # Collect external directory names
+    ext_dirs_in: set[str] = {_ext_dir(src) for src, _ in inbound_edges if _ext_dir(src)}
+    ext_dirs_out: set[str] = {
+        _ext_dir(tgt) for _, tgt in outbound_edges if _ext_dir(tgt)
+    }
+
+    # Determine which focus files to show (cap at limit)
+    shown_files = focus_files[:_FOCUS_FILE_LIMIT]
+    truncated = len(focus_files) > _FOCUS_FILE_LIMIT
+    shown_set = set(shown_files)
+
+    lines: list[str] = []
+
+    # Group shown files by their immediate subdirectory under focus
+    sub_groups: dict[str, list[str]] = {}
+    for f in shown_files:
+        remainder = f[len(focus) + 1 :] if focus else f
+        parts = remainder.split("/")
+        sub = parts[0] if len(parts) > 1 else ""
+        sub_groups.setdefault(sub, []).append(f)
+
+    # Render the focused directory subgraph
+    focus_sg = _sanitize_id(focus) if focus else "root"
+    focus_label = focus.split("/")[-1] if focus else "root"
+    lines.append(f'    subgraph {focus_sg}["{focus_label}"]')
+    for sub, files in sorted(sub_groups.items()):
+        if sub:
+            sub_path = f"{focus}/{sub}" if focus else sub
+            sub_sg = _sanitize_id(sub_path)
+            lines.append(f'        subgraph {sub_sg}["{sub}"]')
+            for f in files:
+                fid = _sanitize_id(f)
+                lines.append(f'            {fid}["{Path(f).name}"]')
+            lines.append("        end")
+        else:
+            for f in files:
+                fid = _sanitize_id(f)
+                lines.append(f'        {fid}["{Path(f).name}"]')
+    lines.append("    end")
+    lines.append("")
+
+    # Render external directory nodes
+    for d in sorted(ext_dirs_in | ext_dirs_out):
+        d_id = _sanitize_id(d) + "_ext"
+        lines.append(f'    {d_id}["{d}"]')
+    if ext_dirs_in or ext_dirs_out:
+        lines.append("")
+
+    # Render internal file-to-file edges (capped)
+    edge_count = 0
+    for src, tgt in internal_edges:
+        if src in shown_set and tgt in shown_set and edge_count < _FOCUS_EDGE_LIMIT:
+            lines.append(f"    {_sanitize_id(src)} --> {_sanitize_id(tgt)}")
+            edge_count += 1
+
+    # Render inbound edges from external dirs to internal files
+    seen_inbound: set[tuple[str, str]] = set()
+    for ext_file, int_file in inbound_edges:
+        if int_file in shown_set:
+            ext_d = _ext_dir(ext_file)
+            key = (ext_d, int_file)
+            if key not in seen_inbound and edge_count < _FOCUS_EDGE_LIMIT:
+                lines.append(
+                    f"    {_sanitize_id(ext_d)}_ext --> {_sanitize_id(int_file)}"
+                )
+                seen_inbound.add(key)
+                edge_count += 1
+
+    # Render outbound edges from internal files to external dirs
+    seen_outbound: set[tuple[str, str]] = set()
+    for int_file, ext_file in outbound_edges:
+        if int_file in shown_set:
+            ext_d = _ext_dir(ext_file)
+            key = (int_file, ext_d)
+            if key not in seen_outbound and edge_count < _FOCUS_EDGE_LIMIT:
+                lines.append(
+                    f"    {_sanitize_id(int_file)} --> {_sanitize_id(ext_d)}_ext"
+                )
+                seen_outbound.add(key)
+                edge_count += 1
+
+    if lines:
+        lines.append("")
+
+    # Style directives
+    fill, stroke = _TOPOLOGY_COLORS["other"]
+    lines.append(f"    style {focus_sg} fill:{fill},stroke:{stroke},color:#000")
+    for d in sorted(ext_dirs_in | ext_dirs_out):
+        f_color, s_color = _role_color(d)
+        lines.append(
+            f"    style {_sanitize_id(d)}_ext fill:{f_color},stroke:{s_color},color:#000"
+        )
+
+    inner = "\n".join(lines)
+    mermaid = (
+        "```mermaid\n"
+        "---\n"
+        "config:\n"
+        "  layout: elk\n"
+        "  theme: base\n"
+        "---\n"
+        "flowchart TB\n"
+        f"{inner}\n"
+        "```"
+    )
+
+    label = focus if focus else "root"
+    header = f"## Focus: {label}"
+    if truncated:
+        header += f"\n\n> Showing {len(shown_files)} of {len(focus_files)} files."
+
+    result_parts = [header, mermaid]
+
+    if inbound_edges:
+        ext_in_dirs = sorted(
+            {_ext_dir(src) for src, _ in inbound_edges if _ext_dir(src)}
+        )
+        result_parts.append(
+            "**Inbound dependencies:** " + ", ".join(f"`{d}`" for d in ext_in_dirs)
+        )
+    if outbound_edges:
+        ext_out_dirs = sorted(
+            {_ext_dir(tgt) for _, tgt in outbound_edges if _ext_dir(tgt)}
+        )
+        result_parts.append(
+            "**Outbound dependencies:** " + ", ".join(f"`{d}`" for d in ext_out_dirs)
+        )
+
+    return "\n\n".join(result_parts)
+
+
+# ---------------------------------------------------------------------------
+# Enrichment section renderers
+# ---------------------------------------------------------------------------
+
+
+def _render_external_dependencies(
+    ext_deps: list[ExternalDependencySummary] | None,
+) -> str:
+    """Render the External Dependencies section, or return ``""`` when empty."""
+    if not ext_deps:
+        return ""
+    lines: list[str] = ["## External Dependencies\n"]
+    shown = ext_deps[:_EXT_DEPS_DIR_LIMIT]
+    for summary in shown:
+        label = f"`{summary.directory}`" if summary.directory else "*(root)*"
+        pkgs = ", ".join(f"`{p}`" for p in summary.packages)
+        lines.append(f"**{label}** — {pkgs}")
+    if len(ext_deps) > _EXT_DEPS_DIR_LIMIT:
+        lines.append(
+            f"*… and {len(ext_deps) - _EXT_DEPS_DIR_LIMIT} more directories not shown.*"
+        )
+    return "\n".join(lines)
+
+
+def _render_responsibilities(
+    responsibilities: list[ResponsibilitySummary] | None,
+) -> str:
+    """Render the Module Responsibilities section, or return ``""`` when empty."""
+    if not responsibilities:
+        return ""
+    lines: list[str] = ["## Module Responsibilities\n"]
+    shown = responsibilities[:_RESP_DIR_LIMIT]
+    for summary in shown:
+        label = f"`{summary.directory}`" if summary.directory else "*(root)*"
+        lines.append(f"**{label}** — {summary.summary}")
+    if len(responsibilities) > _RESP_DIR_LIMIT:
+        lines.append(
+            f"*… and {len(responsibilities) - _RESP_DIR_LIMIT} more directories not shown.*"
+        )
+    return "\n".join(lines)
+
+
+def _render_structural_coverage(
+    coverage: list[CoverageRecord] | None,
+) -> str:
+    """Render the Structural Test Coverage section, or return ``""`` when empty."""
+    if not coverage:
+        return ""
+
+    strong = [r for r in coverage if r.evidence == "strong"]
+    fallback = [r for r in coverage if r.evidence == "fallback"]
+    no_evidence = [r for r in coverage if r.evidence == "none"]
+
+    lines: list[str] = ["## Structural Test Coverage\n"]
+    lines.append(
+        f"**Summary:** {len(strong)} director{'y' if len(strong) == 1 else 'ies'} with "
+        f"strong import evidence, {len(fallback)} with name-based fallback evidence, "
+        f"{len(no_evidence)} with no test evidence detected.\n"
+    )
+
+    if strong:
+        lines.append("### Strong Coverage (import evidence)")
+        shown_strong = strong[:_COV_DIR_LIMIT]
+        for rec in shown_strong:
+            label = f"`{rec.module}`" if rec.module else "*(root)*"
+            test_labels = ", ".join(f"`{t}`" for t in rec.test_files[:3])
+            suffix = f" — tested by {test_labels}" if test_labels else ""
+            lines.append(f"- {label}{suffix}")
+        if len(strong) > _COV_DIR_LIMIT:
+            lines.append(f"  *… and {len(strong) - _COV_DIR_LIMIT} more.*")
+
+    if fallback:
+        lines.append("\n### Fallback Coverage (name-based)")
+        shown_fallback = fallback[:_COV_DIR_LIMIT]
+        for rec in shown_fallback:
+            label = f"`{rec.module}`" if rec.module else "*(root)*"
+            test_labels = ", ".join(f"`{t}`" for t in rec.test_files[:3])
+            suffix = f" — inferred from {test_labels} *(name-based)*" if test_labels else " *(name-based)*"
+            lines.append(f"- {label}{suffix}")
+        if len(fallback) > _COV_DIR_LIMIT:
+            lines.append(f"  *… and {len(fallback) - _COV_DIR_LIMIT} more.*")
+
+    if no_evidence:
+        lines.append("\n### No Test Evidence Detected")
+        shown_none = no_evidence[:_COV_DIR_LIMIT]
+        for rec in shown_none:
+            label = f"`{rec.module}`" if rec.module else "*(root)*"
+            lines.append(f"- {label}")
+        if len(no_evidence) > _COV_DIR_LIMIT:
+            lines.append(f"  *… and {len(no_evidence) - _COV_DIR_LIMIT} more.*")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def write_map(
+    graph: DependencyGraph,
+    nodes: list[ClassifiedNode],
+    output: Path,
+    root: Path,
+    dry_run: bool = False,
+    details: bool = False,
+    topology: DirectoryTopology | None = None,
+    assessment: ArchitectureAssessment | None = None,
+    chains: list[RepresentativeChain] | None = None,
+    focus: str | None = None,
+    diagnostic_chains: list[RepresentativeChain] | None = None,
+    ext_deps: list[ExternalDependencySummary] | None = None,
+    responsibilities: list[ResponsibilitySummary] | None = None,
+    coverage: list[CoverageRecord] | None = None,
+) -> None:
+    """Render the dependency graph and classified nodes into a code-map Markdown file.
+
+    Args:
+        graph:             Fully-resolved dependency graph.
+        nodes:             Classified nodes produced by ``classify(graph)``.
+        output:            Destination path for the Markdown file.
+        root:              Project root (written into the header block).
+        dry_run:           When True, print the first 30 lines to stdout instead of writing.
+        details:           When True, append a diagnostic section with raw layer/file details.
+        topology:          Directory topology from ``build_directory_topology``.
+        assessment:        Architecture assessment from ``assess_architecture``.
+        chains:            Coupling-ranked chains from ``build_representative_chains``.
+        focus:             Repo-relative directory path to drill down into.
+        diagnostic_chains: BFS-ordered chains from ``build_diagnostic_chains`` for the
+                           ``--details`` appendix.
+        ext_deps:          Per-directory external dependency summaries.
+        responsibilities:  Per-directory responsibility summaries.
+        coverage:          Per-directory structural test-coverage records.
+    """
+    has_new_artifacts = topology is not None and assessment is not None
+
+    if has_new_artifacts:
+        groups = _group_by_layer(nodes)
+        sections: list[str] = [
+            _render_header(graph, nodes, root),
+            _render_architecture_summary(assessment),
+            _render_topology_mermaid(topology, assessment),  # type: ignore[arg-type]
+            _render_top_level_graph(topology),
+            _render_directory_tree(topology),
+            _render_module_graph(topology),
+            _render_chains(chains),
+        ]
+        if focus is not None and topology is not None and assessment is not None:
+            focus_section = _render_focus_drilldown(focus, topology, graph, assessment)
+            if focus_section.strip():
+                sections.append(focus_section)
+        sections.append(_render_external_dependencies(ext_deps))
+        sections.append(_render_responsibilities(responsibilities))
+        sections.append(_render_structural_coverage(coverage))
+        sections.append(_render_cycles_and_hotspots(assessment, graph))
+        if details:
+            appendix = _render_details_appendix(groups, graph, nodes, diagnostic_chains)
+            if appendix.strip():
+                sections.append(appendix)
+    else:
+        # Legacy layout — preserves backward compatibility for callers that omit new params
+        groups = _group_by_layer(nodes)
+        sections = [
+            _render_header(graph, nodes, root),
+            _render_layer_table(groups),
+            _render_entry_points(groups),
+            _build_mermaid(groups, graph, nodes, details),
+            _render_layers_breakdown(groups),
+            _render_edges(graph, nodes),
+            _render_cycles(graph),
+        ]
+
+    content = "\n\n".join(s for s in sections if s.strip())
+
+    if dry_run:
+        preview = "\n".join(content.splitlines()[:_DRY_RUN_LINES])
+        console.print(preview)
+        return
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(content, encoding="utf-8")