cgis_metrics
Compute whole-graph architectural metrics — coupling bottlenecks, God classes, PageRank — to reveal codebase hotspots; scope or exclude domains for focused reviews.
Instructions
Whole-graph architectural metrics — coupling bottlenecks, God classes, PageRank.
Returns JSON ``{bottlenecks, god_classes, critical, file_coupling, class_cohesion,
resolution}``
computed with vectorized DuckDB aggregations over the whole graph (fan-in/fan-out
coupling, declared-member counts, PageRank, per-file Ca/Ce/instability) — the
global "what are the hotspots?" view that complements the node-local
trace/impact/context tools. Requires the optional ``duckdb`` extra; an
unavailable dependency is reported as a normal ❌ message.
``file_coupling`` counts *files*, not calls: Ca is how many other files
depend on a file (by IMPORTS or CALLS), Ce how many it depends on, and
instability ``I = Ce / (Ca + Ce)`` runs from 0 (stable, expensive to change)
to 1 (volatile); it is null for a file linked to no other.
``class_cohesion`` ranks classes by LCOM4: the number of groups their instance
methods fall into when linked by a shared ``self`` attribute or a call. 1 is
cohesive; 2+ is a class doing unrelated jobs. Dunders (``__init__`` above
all), abstract, static and class methods are not counted.
``resolution`` is the share of edges the resolver could not place, by the
same rule as ``cgis validate``. Read the rankings through it: a node whose
calls are mostly unresolved looks uncoupled because its edges point nowhere.
Under ``scope``/``exclude`` it counts the edges the selected code *emits*.
``exclude`` drops any node whose FQN contains one of the given dot-segments
(e.g. ``["tests"]`` removes both ``tests.*`` and ``domains.*.tests.*``) so
test/vendor scaffolding stays out of the rankings.
``scope`` is its complement: it keeps only nodes under one of the given
dot-prefixes, anchored and cut on a dot boundary, so
``["domains.reservation"]`` is that subtree and not
``domains.reservation_archive``. Use it for a per-domain review. The two
compose, and they differ where it matters for PageRank — ``exclude`` removes
nodes from the propagation graph, ``scope`` filters the rows and lets rank
propagate over the whole graph, so a scoped run reports how central the
subtree is *globally*. Coupling in-degree likewise keeps counting callers
from outside the scope, which is the ripple a domain review is after (#239).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Top-N rows returned per section. | |
| scope | No | Keep only nodes under any of these dot-prefixes, e.g. ["domains.billing"]; rank still propagates over the whole graph. | |
| db_path | No | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. | graph.db |
| exclude | No | Drop nodes whose FQN contains any of these dot-segments, e.g. ["tests"]; they are removed from PageRank propagation too. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |