codegraph-brain 0.6.0__py3-none-any.whl

cgis/query/render/mermaid.py

@@ -0,0 +1,235 @@
+"""Implements mermaid queries to render diagram."""
+
+import re
+
+from cgis.core.models import VIRTUAL_FILE_PATH, Edge, Node, NodeNamespace, NodeType
+from cgis.extractors.python_extractor import file_path_to_module_fqn
+
+_RAW_CALL_PREFIX = "raw_call:"
+_UNRESOLVED_STYLE = ":::unresolvedNode"
+
+# Bare ids that collide with Mermaid keywords break the parser (`end` closes a
+# subgraph, etc.); such slugs — and any starting with a digit — are prefixed.
+_MERMAID_RESERVED = frozenset(
+    {"graph", "subgraph", "end", "class", "classdef", "click", "style", "linkstyle", "direction"}
+)
+_NON_ID_CHARS = re.compile(r"[^0-9A-Za-z]+")
+
+
+def _sanitize_token(text: str) -> str:
+    """Collapse anything outside [A-Za-z0-9_] to single underscores; never empty."""
+    token = _NON_ID_CHARS.sub("_", text).strip("_")
+    return token or "node"
+
+
+def _guard_token(slug: str) -> str:
+    """Prefix to dodge a leading digit or a Mermaid reserved word."""
+    if slug and (slug[0].isdigit() or slug.lower() in _MERMAID_RESERVED):
+        return f"id_{slug}"
+    return slug
+
+
+def _file_stem(file_path: str) -> str:
+    """Basename without extension, e.g. ``src/cgis/pipeline.py`` → ``pipeline``."""
+    name = file_path.replace("\\", "/").rsplit("/", maxsplit=1)[-1]
+    return name.rsplit(".", maxsplit=1)[0] or name
+
+
+def _fqn_slug(fqn: str) -> str:
+    """Readable id for a bare FQN (phantom/external/raw_call): its last two segments."""
+    body = fqn.removeprefix(_RAW_CALL_PREFIX)
+    tail = "_".join(body.split(".")[-2:])
+    return _guard_token(_sanitize_token(tail))
+
+
+def _internal_node_slug(node_id: str, path_fqn: str) -> str | None:
+    """Slug an internal node by matching the longest module suffix of its path FQN.
+
+    The extractor builds node ids relative to the ingest root, which may be a
+    suffix of the file-path-derived FQN (e.g. id ``cgis.pipeline.run`` when the
+    path yields ``src.cgis.pipeline``). Trying successively shorter suffixes
+    keeps the ``<file_stem>`` prefix even when the two roots differ. The stem is
+    always the deepest segment of the path FQN. Returns None on no match.
+    """
+    parts = path_fqn.split(".")
+    stem = parts[-1]
+    for i in range(len(parts)):
+        candidate = ".".join(parts[i:])
+        if node_id == candidate:
+            return _guard_token(_sanitize_token(stem))
+        if node_id.startswith(candidate + "."):
+            suffix = node_id[len(candidate) + 1 :]
+            return _guard_token(_sanitize_token(f"{stem}_{suffix}"))
+    return None
+
+
+def _node_slug(node: Node) -> str:
+    """Readable id for a node: ``<file_stem>_<Class>_<method>`` (#210).
+
+    For internal nodes the symbol suffix is peeled off the module FQN derived
+    from the file path; module/file nodes slug to the bare stem. Non-internal or
+    virtual nodes (and any that don't match the path FQN) fall back to
+    :func:`_fqn_slug`. Collisions are disambiguated later by :class:`_IdAllocator`.
+    """
+    if node.namespace == NodeNamespace.INTERNAL and node.file_path != VIRTUAL_FILE_PATH:
+        slug = _internal_node_slug(node.id, file_path_to_module_fqn(node.file_path))
+        if slug is not None:
+            return slug
+    return _fqn_slug(node.id)
+
+
+class _IdAllocator:
+    """Hands out unique, readable, deterministic Mermaid ids for one diagram.
+
+    Same key → same id (idempotent); a fresh slug colliding with an already-used
+    one gets a numeric ``_2`` / ``_3`` … suffix, deterministic in call order.
+    """
+
+    def __init__(self) -> None:
+        """Start with empty key→id and used-id registries."""
+        self._by_key: dict[str, str] = {}
+        self._used: set[str] = set()
+
+    def _claim(self, key: str, base: str) -> str:
+        """Return the id for ``key``, allocating ``base`` (suffixed on collision) if new."""
+        existing = self._by_key.get(key)
+        if existing is not None:
+            return existing
+        slug = base
+        counter = 2
+        while slug in self._used:
+            slug = f"{base}_{counter}"
+            counter += 1
+        self._used.add(slug)
+        self._by_key[key] = slug
+        return slug
+
+    def for_node(self, node: Node) -> str:
+        """Allocate (or reuse) the id for a graph node."""
+        return self._claim(node.id, _node_slug(node))
+
+    def for_fqn(self, fqn: str) -> str:
+        """Allocate (or reuse) the id for a bare FQN endpoint (phantom stub)."""
+        return self._claim(fqn, _fqn_slug(fqn))
+
+    def for_subgraph(self, file_path: str) -> str:
+        """Allocate (or reuse) the id for a file subgraph block."""
+        return self._claim(
+            f"sg::{file_path}", _guard_token(_sanitize_token(f"sg_{_file_stem(file_path)}"))
+        )
+
+
+def _escape(text: str) -> str:
+    """Escape special characters that break Mermaid double-quoted node labels."""
+    return (
+        text.replace("\\", "\\\\").replace('"', "#quot;").replace("<", "&lt;").replace(">", "&gt;")
+    )
+
+
+class MermaidCompiler:
+    """
+    Compiles a subgraph (Nodes, Edges) into highly readable, valid Mermaid.js diagrams.
+    Handles ID normalization and injects CSS classDefs for clean code visualization.
+    """
+
+    def __init__(self) -> None:
+        """Initialise with the default CSS class definitions for node styling."""
+        self._style_defs = [
+            "classDef classNode fill:#e8f5e9,stroke:#2e7d32,stroke-width:1.5px,color:#1b5e20;",
+            "classDef funcNode fill:#e3f2fd,stroke:#1565c0,stroke-width:1.5px,color:#0d47a1;",
+            "classDef methodNode fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1.5px,color:#4a148c;",
+            (
+                "classDef unresolvedNode fill:#fffde7,stroke:#fbc02d,stroke-width:1.5px,"
+                "stroke-dasharray: 4 4,color:#f57f17;"
+            ),
+            "classDef defaultNode fill:#fafafa,stroke:#9e9e9e,stroke-width:1.5px,color:#212121;",
+            "classDef stdlibNode fill:#eceff1,stroke:#607d8b,stroke-width:1px,color:#455a64;",
+            (
+                "classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,"
+                "stroke-dasharray: 3 3,color:#bf360c;"
+            ),
+        ]
+
+    def _get_node_label(self, node: Node) -> str:
+        """Formats the visible text inside a node (Name + file name + line range)."""
+        filename = node.file_path.replace("\\", "/").split("/")[-1]
+        return _escape(f"{node.name} ({filename}:{node.start_line})")
+
+    def _get_style_class(self, node: Node) -> str:
+        """Map a node to its Mermaid CSS class suffix based on namespace and type."""
+        if node.namespace == NodeNamespace.STDLIB:
+            return ":::stdlibNode"
+        if node.namespace == NodeNamespace.EXTERNAL:
+            return ":::externalNode"
+        if node.namespace == NodeNamespace.UNKNOWN:
+            return _UNRESOLVED_STYLE
+        if node.file_path == VIRTUAL_FILE_PATH and node.namespace == NodeNamespace.INTERNAL:
+            return _UNRESOLVED_STYLE
+        if node.type == NodeType.CLASS:
+            return ":::classNode"
+        if node.type == NodeType.FUNCTION:
+            return ":::funcNode"
+        if node.type == NodeType.METHOD:
+            return ":::methodNode"
+        return ":::defaultNode"
+
+    def _render_node_line(self, node: Node, id_map: dict[str, str], indent: str) -> str:
+        """Format a single node declaration with its label and style class."""
+        safe_id = id_map[node.id]
+        return f'{indent}{safe_id}["{self._get_node_label(node)}"]{self._get_style_class(node)}'
+
+    def _render_subgraphs(
+        self, file_groups: dict[str, list[Node]], id_map: dict[str, str], alloc: "_IdAllocator"
+    ) -> list[str]:
+        """Render nodes grouped into subgraph blocks, one block per source file."""
+        lines: list[str] = []
+        for file_path, group_nodes in file_groups.items():
+            sg_id = alloc.for_subgraph(file_path)
+            sg_label = _escape(file_path.replace("\\", "/").split("/")[-1])
+            lines.append(f'    subgraph {sg_id}["{sg_label}"]')
+            lines.extend(self._render_node_line(n, id_map, "        ") for n in group_nodes)
+            lines.append("    end")
+        return lines
+
+    def _render_edges(
+        self, edges: list[Edge], id_map: dict[str, str], alloc: "_IdAllocator"
+    ) -> list[str]:
+        """Render edge declarations, injecting phantom node stubs for unknown endpoints."""
+        lines: list[str] = []
+        for edge in edges:
+            source_safe = id_map.get(edge.source)
+            if not source_safe:
+                source_safe = alloc.for_fqn(edge.source)
+                lines.append(f'    {source_safe}["{_escape(edge.source)}"]:::defaultNode')
+                id_map[edge.source] = source_safe
+
+            target_safe = id_map.get(edge.target)
+            if not target_safe:
+                target_safe = alloc.for_fqn(edge.target)
+                is_unresolved = edge.target.startswith(_RAW_CALL_PREFIX)
+                clean_target = _escape(edge.target.removeprefix(_RAW_CALL_PREFIX))
+                target_style = _UNRESOLVED_STYLE if is_unresolved else ":::defaultNode"
+                lines.append(f'    {target_safe}["{clean_target}"]{target_style}')
+                id_map[edge.target] = target_safe
+
+            lines.append(f"    {source_safe} -->|{edge.type.value}| {target_safe}")
+        return lines
+
+    def compile(self, nodes: list[Node], edges: list[Edge]) -> str:
+        """Generates Mermaid Graph Definition, grouping nodes by file into subgraphs."""
+        lines = ["graph TD", *self._style_defs, ""]
+
+        alloc = _IdAllocator()
+        id_map = {node.id: alloc.for_node(node) for node in nodes}
+
+        file_groups: dict[str, list[Node]] = {}
+        for node in nodes:
+            file_groups.setdefault(node.file_path, []).append(node)
+
+        if len(file_groups) > 1:
+            lines.extend(self._render_subgraphs(file_groups, id_map, alloc))
+        else:
+            lines.extend(self._render_node_line(n, id_map, "    ") for n in nodes)
+
+        lines.extend(self._render_edges(edges, id_map, alloc))
+        return "\n".join(lines)

cgis/query/render/metrics.py

@@ -0,0 +1,346 @@
+"""DuckDB analytical layer — whole-graph architectural metrics (#16).
+
+SQLite is great for the point reads/writes of ingestion and BFS traversal, but
+slow for full-graph aggregations (degree, coupling, God-object detection). DuckDB
+is an embedded OLAP engine that *attaches* to the existing ``graph.db`` SQLite
+file with zero copy and runs vectorized queries without loading the graph into
+Python — so it scales to large monorepos where a NetworkX-in-RAM approach would
+OOM.
+
+DuckDB is an **optional** dependency (``pip install codegraph-brain[analytics]``):
+importing this module is fine without it, but constructing :class:`DuckDBAnalyzer`
+raises a clear error so the CLI can degrade gracefully.
+"""
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from cgis.core.models import VIRTUAL_FILE_PATH, NodeType
+
+# Optional dependency. Annotated ``Any`` (not ``Module | None``) so the import reads
+# the same — and ``duckdb.connect(...)`` type-checks — whether or not duckdb is
+# installed in the type-checking environment.
+duckdb: Any
+try:
+    import duckdb
+except ImportError:  # pragma: no cover - exercised only without the optional extra
+    duckdb = None
+
+_DUCKDB_MISSING = (
+    "DuckDB is required for analytical metrics but is not installed. "
+    "Install it with: pip install 'codegraph-brain[analytics]'  (or: uv add duckdb)"
+)
+
+
+def _segment_exclusion(id_expr: str, segments: Sequence[str]) -> tuple[str, list[str]]:
+    """Build a WHERE fragment excluding FQNs that contain any of ``segments``.
+
+    A segment matches a whole dot-delimited component **anywhere** in the id, so
+    ``tests`` drops both ``tests.utils.x`` and ``domains.resv.tests.test_x`` while
+    keeping ``domains.testservice`` (substring, not a segment). Returns
+    ``("", [])`` when ``segments`` is empty. The fragment uses ``?`` placeholders
+    (the segments ride in as query parameters, never string-interpolated) and
+    ``LIKE … ESCAPE '\\'`` with ``%``/``_``/``\\`` escaped, so a segment is matched
+    literally and the path stays injection-safe.
+    """
+    if not segments:  # reachable empty case (default ()) — and guards a None caller
+        return "", []
+    clauses: list[str] = []
+    params: list[str] = []
+    # dict.fromkeys dedupes while preserving order; skip empty/whitespace segments
+    # (they would yield a '%..%' pattern that matches no real FQN — a silent no-op).
+    for seg in dict.fromkeys(segments):
+        if not seg.strip():
+            continue
+        escaped = seg.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        clauses.append(f"('.' || {id_expr} || '.') NOT LIKE ? ESCAPE '\\'")
+        params.append(f"%.{escaped}.%")
+    if not clauses:
+        return "", []
+    return " AND " + " AND ".join(clauses), params
+
+
+def _coupling_query(exclude_sql: str) -> str:
+    """Coupling query with an optional segment-exclusion fragment on the node list."""
+    return f"""
+WITH incoming AS (
+    SELECT target AS node_id, COUNT(*) AS in_deg
+    FROM edges WHERE type = 'CALLS' GROUP BY target
+),
+outgoing AS (
+    SELECT e.source AS node_id, COUNT(*) AS out_deg
+    FROM edges e
+    JOIN nodes t ON e.target = t.id
+    WHERE e.type = 'CALLS'
+      AND t.namespace = 'INTERNAL'
+      AND t.file_path != '{VIRTUAL_FILE_PATH}'
+    GROUP BY e.source
+)
+SELECT
+    n.id,
+    n.type,
+    COALESCE(i.in_deg, 0) AS in_degree,
+    COALESCE(o.out_deg, 0) AS out_degree
+FROM nodes n
+LEFT JOIN incoming i ON n.id = i.node_id
+LEFT JOIN outgoing o ON n.id = o.node_id
+WHERE n.namespace = 'INTERNAL'
+  AND n.type IN ('FUNCTION', 'METHOD')
+  AND n.file_path != '{VIRTUAL_FILE_PATH}'{exclude_sql}
+ORDER BY (COALESCE(i.in_deg, 0) + COALESCE(o.out_deg, 0)) DESC, n.id
+LIMIT ?
+"""
+
+
+def _god_class_query(exclude_sql: str) -> str:
+    """God-class query with an optional segment-exclusion fragment on the class id."""
+    return f"""
+SELECT e.source AS node_id, COUNT(*) AS declares
+FROM edges e
+JOIN nodes n ON e.source = n.id
+WHERE e.type = 'DECLARES' AND n.type = 'CLASS'{exclude_sql}
+GROUP BY e.source
+ORDER BY declares DESC, e.source
+LIMIT ?
+"""
+
+
+# Vectorized PageRank: 20 fixed iterations of the standard damped formula, run as
+# DuckDB temp-table joins (Python only drives the loop — the data never leaves the
+# in-memory DuckDB). Dangling nodes (no outgoing internal CALLS) redistribute their
+# mass uniformly so rank isn't silently lost on a graph full of leaf functions.
+_PAGERANK_DAMPING = 0.85
+_PAGERANK_ITERATIONS = 20
+_PAGERANK_INTERNAL = (
+    f"namespace = 'INTERNAL' AND file_path != '{VIRTUAL_FILE_PATH}' "
+    "AND type IN ('FUNCTION', 'METHOD', 'CLASS')"
+)
+_PAGERANK_STEP = """
+CREATE OR REPLACE TEMP TABLE pr_next AS
+WITH dangling AS (
+    SELECT COALESCE(SUM(r.r), 0.0) AS mass
+    FROM pr_rank r
+    WHERE r.id NOT IN (SELECT src FROM pr_out)
+),
+inflow AS (
+    SELECT e.dst AS id, SUM(r.r / o.deg) AS s
+    FROM pr_edges e
+    JOIN pr_rank r ON e.src = r.id
+    JOIN pr_out o ON e.src = o.src
+    GROUP BY e.dst
+)
+SELECT nd.id AS id,
+       ? + ? * (COALESCE(i.s, 0.0) + (SELECT mass FROM dangling) / ?) AS r
+FROM pr_nodes nd
+LEFT JOIN inflow i ON nd.id = i.id
+"""
+
+
+class NodeMetric(BaseModel):
+    """Per-node architectural metric: fan-in (coupling) and fan-out (complexity)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    node_id: str
+    node_type: str
+    in_degree: int
+    out_degree: int
+    page_rank: float = 0.0
+
+
+class ArchitectureReport(BaseModel):
+    """Whole-graph summary an agent or human can read to spot hotspots."""
+
+    model_config = ConfigDict(frozen=True)
+
+    bottlenecks: list[NodeMetric]
+    god_classes: list[NodeMetric]
+    critical: list[NodeMetric] = []
+
+
+class DuckDBAnalyzer:
+    """Run vectorized architectural metrics over a SQLite graph via DuckDB.
+
+    Attaches read-only to the SQLite file (zero copy) so the live graph is never
+    mutated and ``database is locked`` errors are avoided. Use as a context
+    manager so the DuckDB connection is always closed.
+    """
+
+    def __init__(self, sqlite_db_path: str) -> None:
+        """Open an in-memory DuckDB and attach ``sqlite_db_path`` read-only.
+
+        Raises ``RuntimeError`` if the optional duckdb dependency is missing and
+        ``FileNotFoundError`` if the database file does not exist.
+        """
+        if duckdb is None:
+            raise RuntimeError(_DUCKDB_MISSING)
+        if not Path(sqlite_db_path).is_file():
+            msg = f"Database not found: {sqlite_db_path}. Run `cgis ingest` first."
+            raise FileNotFoundError(msg)
+        self.conn = duckdb.connect(":memory:")
+        try:
+            self.conn.execute("INSTALL sqlite;")
+            self.conn.execute("LOAD sqlite;")
+            # The path can't be a bound parameter in ATTACH; single-quote-escape it
+            # (and the is_file check above) keeps the literal injection-safe.
+            safe_path = sqlite_db_path.replace("'", "''")
+            self.conn.execute(f"ATTACH '{safe_path}' AS gdb (TYPE SQLITE, READ_ONLY);")
+            self.conn.execute("USE gdb;")
+        except Exception:
+            # INSTALL/LOAD/ATTACH can fail (offline extension fetch, non-SQLite file).
+            # Close the just-opened connection so it never leaks past a failed __init__.
+            self.conn.close()
+            raise
+
+    def __enter__(self) -> "DuckDBAnalyzer":
+        """Enter the context manager, returning this analyzer."""
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        """Close the DuckDB connection on context exit."""
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying DuckDB connection."""
+        self.conn.close()
+
+    def _rows_to_metrics(self, rows: list[tuple[Any, ...]]) -> list[NodeMetric]:
+        """Map ``(id, type, in_degree, out_degree)`` rows to NodeMetric models."""
+        return [
+            NodeMetric(
+                node_id=str(node_id),
+                node_type=str(node_type),
+                in_degree=int(in_degree),
+                out_degree=int(out_degree),
+            )
+            for node_id, node_type, in_degree, out_degree in rows
+        ]
+
+    def get_coupling_metrics(
+        self, limit: int = 10, exclude: Sequence[str] = ()
+    ) -> list[NodeMetric]:
+        """Top INTERNAL functions/methods by total coupling (fan-in + fan-out).
+
+        High in-degree marks a critical bottleneck (many callers); high out-degree
+        marks an over-orchestrating or complex unit. External/stdlib and
+        unresolved ``raw_call:`` targets are excluded so ``len``/``print`` noise
+        never tops the list. ``exclude`` drops any node whose FQN contains one of
+        the given dot-segments (e.g. ``["tests"]``) from the ranked list.
+        """
+        where, params = _segment_exclusion("n.id", exclude)
+        rows = self.conn.execute(_coupling_query(where), [*params, limit]).fetchall()
+        return self._rows_to_metrics(rows)
+
+    def get_god_classes(self, limit: int = 5, exclude: Sequence[str] = ()) -> list[NodeMetric]:
+        """Top classes by declared-member count (DECLARES fan-out).
+
+        ``out_degree`` carries the number of methods/attributes the class
+        declares — a high value is the classic God-object smell. ``exclude`` drops
+        classes whose FQN contains one of the given dot-segments.
+        """
+        where, params = _segment_exclusion("n.id", exclude)
+        rows = self.conn.execute(_god_class_query(where), [*params, limit]).fetchall()
+        return [
+            NodeMetric(
+                node_id=str(node_id),
+                node_type=NodeType.CLASS.value,
+                in_degree=0,
+                out_degree=int(declares),
+            )
+            for node_id, declares in rows
+        ]
+
+    def get_pagerank(self, limit: int = 10, exclude: Sequence[str] = ()) -> list[NodeMetric]:
+        """Top INTERNAL nodes by PageRank over the internal CALLS graph.
+
+        PageRank weights a node by the *transitive* importance of what reaches it,
+        not just direct in-degree, so a function called by other heavily-used
+        functions ranks above one called by many trivial leaves. External/stdlib
+        and resolver virtual pseudo-nodes are excluded.
+
+        Unlike the coupling metric (FUNCTION/METHOD only), the PageRank universe
+        also includes CLASS nodes — a constructor call is a CALLS edge to the
+        class, so a heavily-instantiated class (e.g. a core data model) is
+        legitimately central. Uncalled classes simply rest at the floor rank.
+
+        ``exclude`` removes any node whose FQN contains one of the given
+        dot-segments from the PageRank universe entirely (so excluded nodes leave
+        the propagation graph, not just the final ranking).
+
+        Each row also carries its ``in_degree``/``out_degree`` **within the same
+        internal, exclude-applied CALLS graph PageRank ran on** (#237) — so a
+        high rank paired with ``in_degree == 0`` is legible as a dangling-mass
+        artifact (a leaf sink that accrued redistributed rank, not a real hub)
+        rather than a genuine centrality signal.
+        """
+        conn = self.conn
+        where, params = _segment_exclusion("id", exclude)
+        conn.execute(
+            "CREATE OR REPLACE TEMP TABLE pr_nodes AS "
+            f"SELECT id FROM nodes WHERE {_PAGERANK_INTERNAL}{where}",
+            params,
+        )
+        n = int(conn.execute("SELECT COUNT(*) FROM pr_nodes").fetchone()[0])
+        if n == 0:
+            return []
+        conn.execute(
+            "CREATE OR REPLACE TEMP TABLE pr_edges AS "
+            "SELECT e.source AS src, e.target AS dst FROM edges e "
+            "JOIN pr_nodes s ON e.source = s.id JOIN pr_nodes d ON e.target = d.id "
+            "WHERE e.type = 'CALLS'"
+        )
+        conn.execute(
+            "CREATE OR REPLACE TEMP TABLE pr_out AS "
+            "SELECT src, COUNT(*) AS deg FROM pr_edges GROUP BY src"
+        )
+        conn.execute(
+            "CREATE OR REPLACE TEMP TABLE pr_in AS "
+            "SELECT dst, COUNT(*) AS deg FROM pr_edges GROUP BY dst"
+        )
+        conn.execute(
+            "CREATE OR REPLACE TEMP TABLE pr_rank AS SELECT id, 1.0 / ? AS r FROM pr_nodes", [n]
+        )
+        base = (1.0 - _PAGERANK_DAMPING) / n
+        for _ in range(_PAGERANK_ITERATIONS):
+            conn.execute(_PAGERANK_STEP, [base, _PAGERANK_DAMPING, n])
+            conn.execute("CREATE OR REPLACE TEMP TABLE pr_rank AS SELECT * FROM pr_next")
+        rows = conn.execute(
+            "SELECT r.id, nd.type, r.r, "
+            "COALESCE(pin.deg, 0) AS in_deg, COALESCE(pout.deg, 0) AS out_deg "
+            "FROM pr_rank r JOIN nodes nd ON r.id = nd.id "
+            "LEFT JOIN pr_in pin ON r.id = pin.dst "
+            "LEFT JOIN pr_out pout ON r.id = pout.src "
+            "ORDER BY r.r DESC, r.id LIMIT ?",
+            [limit],
+        ).fetchall()
+        return [
+            NodeMetric(
+                node_id=str(i),
+                node_type=str(t),
+                in_degree=int(in_deg),
+                out_degree=int(out_deg),
+                page_rank=float(r),
+            )
+            for i, t, r, in_deg, out_deg in rows
+        ]
+
+    def architecture_report(
+        self,
+        bottleneck_limit: int = 10,
+        god_limit: int = 5,
+        critical_limit: int = 10,
+        exclude: Sequence[str] = (),
+    ) -> ArchitectureReport:
+        """Bundle the coupling bottlenecks, God classes, and PageRank-critical nodes.
+
+        ``exclude`` is threaded into all three sections — any node whose FQN
+        contains one of the given dot-segments (e.g. ``["tests"]``) is dropped.
+        """
+        return ArchitectureReport(
+            bottlenecks=self.get_coupling_metrics(bottleneck_limit, exclude),
+            god_classes=self.get_god_classes(god_limit, exclude),
+            critical=self.get_pagerank(critical_limit, exclude),
+        )

cgis/resolver/__init__.py

@@ -0,0 +1 @@
+"""CGIS resolver package — FQN resolution and semantic uplift engine."""