Impact Analysis and Insights

Impact Analysis & Insights

Two related capabilities that turn the graph from a picture into an analysis tool: impact analysis (reason about a specific node) and insights (let PolyGraph find problems for you). Both are pure graph algorithms over a prebuilt adjacency (lib/graph/query.ts, lib/graph/insights.ts).

Impact analysis

Select a node and ask questions about reachability and blast radius:

Question	What it returns
Dependencies	What this node depends on, to an adjustable depth (1–5).
Dependents	What depends on this node, to an adjustable depth (1–5).
Neighborhood	Everything within N undirected hops, including the node itself.
Shortest path	The shortest path from one node to another (or none).
Why connected	The path and the specific edges that connect two nodes.
Blast radius	Everything transitively affected by a change here, grouped by package / file / kind.

Blast radius is the headline: it answers "if I change this, what could break?" and the grouping makes a large result set readable. The same blastRadius computation also feeds the diff overlay (see CLI: Rules & Diff), which reports when a node's blast radius grows between two revisions.

Insights (the Problems panel)

The Problems / Insights panel runs a battery of architectural-issue detectors and presents clickable findings. Each finding carries a set of node ids that open as a focused subgraph — so you go from "you have a cycle" to seeing the cycle in one click.

Detector	Flags
Cycle	Strongly-connected components with more than one member (import/dependency cycles).
Fan-out	Nodes with an outlier number of dependencies.
Fan-in	Nodes with an outlier number of dependents.
Bottleneck	Nodes that are both high fan-in and high fan-out — change-amplifiers.
Orphan	Isolated nodes (degree 0).
Client → server violation	A client-tagged module importing a server-tagged one.
Undeclared dependency	An external package that's imported but not declared in any manifest.
Deep chain	A dependency chain at least 6 nodes long (over the SCC condensation).
Instability (SDP)	A stable module depending on a less-stable one — Martin's Stable-Dependencies Principle, computed over import edges.
Ambiguous reference	An edge whose evidence is ambiguous (more than one plausible target).
Unresolved reference	A reference the analyzer couldn't resolve at all (e.g. a broken relative import).

How outliers and thresholds work

Detectors are bounded and tuned so the panel is signal, not noise:

• Fan-in/out/bottleneck use a mean-plus-kσ outlier test (σ = 2) with a degree floor (6), so small graphs don't generate spurious "hubs".
• Deep chain requires ≥ 6 nodes; instability requires a margin of 0.3 to flag.
• Each detector is capped (50 findings per kind) so a pathological graph can't flood the panel.

Findings are deterministic — the same graph always produces the same list.

From insight to enforcement

The Problems panel is exploratory. When you want to prevent an issue from coming back, encode it as a rule and run it in CI — see CLI: Rules & Diff. The detectors here (cycles, fan-out, deep chains, client→server) map directly onto the CLI's rule and threshold types.