5.3 Graph Analysis

An engineer runs bazel query 'deps(//app:server)', sees thousands of labels, and concludes that the closure explains a slow rebuild. The query has found a real structure, but the conclusion has crossed several invisible boundaries: declared targets are not configured targets, targets are not actions, and a reachable node is not evidence that anything executed.

The useful habit is to keep three choices together: graph layer, question, and evidence. Choose the layer whose nodes and edges match the claim, ask only what that layer can answer, and require evidence from the layer where the expected effect would appear. This turns a graph picture or count from a plausible story into the beginning of a reproducible investigation.

Move from Meaning to Investigation to Design

The three child articles follow the order in which a sound graph decision is made.

5.3.1 Graph Theory Foundations is the recommended conceptual deepening. It fixes node identity, edge direction, universe, and projection before applying ideas such as reachability, components, bridges, or topological order. Read it when an unfamiliar metric or topology claim needs that precision. Its job is to prevent a correct graph algorithm from answering the wrong Bazel question.

5.3.2 Practical Graph Analysis is the core operational entry. It starts with bounded fan-in, fan-out, closure, and path observations, explains the edge behind an outlier, makes the smallest justified repair, and verifies the effect with layer-appropriate evidence. It locally introduces the graph terms needed for that workflow, so a reader can start here after learning query even if the recommended foundations article was skipped. The deeper topology vocabulary then remains available when the bounded case needs it.

5.3.3 Target Boundary Design turns observed structure into a core design decision. It asks whether interfaces, direct dependency surfaces, consumer sets, ownership, and ABI shielding justify a different target boundary. It follows practical analysis because “smaller graph node” must not silently become “smaller unit of work” before evidence identifies the boundary under discussion.

One Graph Does Not Answer Every Question

Use the organizing model as a short diagnostic sentence:

On the [layer], I am asking [question], and [evidence] would confirm or reject the claim.

For example, an unexpected dependency is naturally a declared-target question, so a bounded query path is appropriate evidence. Whether select() retains that dependency in a particular build is a configured-target question and needs cquery. Whether a proposed split creates independent work is an action question and needs aquery. Whether it improved elapsed time or reuse needs a matched profile or execution log. 5.2 Query provides the operating details for those views. This section teaches how to choose among them and how far each result can carry an argument.

The recurring difficulty is that the same labels appear across the story. That visual continuity can tempt you to treat target reachability, configured analysis, planned actions, and observed execution as one graph with different commands. They are related views with different node identities and evidence limits. When a conclusion moves to another layer, the investigation must move with it.

Choose the Shortest Useful Path

For architecture review or an unfamiliar graph metric, read all three articles in order: interpretation first, bounded investigation second, boundary design third. That path prevents premature fixes based on ambiguous counts.

If you already have a concrete unwanted dependency or closure regression, skim the graph contract in 5.3.1 Graph Theory Foundations and move to 5.3.2 Practical Graph Analysis. Return to 5.3.3 Target Boundary Design only when the evidence suggests changing target boundaries rather than removing or redirecting one edge.

If the proposal is “split this large target to make builds faster,” begin with 5.3.2 Practical Graph Analysis to bound the affected structure, then use 5.3.3 Target Boundary Design to decide whether a target split improves a real interface and ownership boundary. Performance remains a prediction until the matched experiment in 5.4.3 Measuring Granularity Trade-offs tests it. Avoid beginning with a repository-wide graph rendering. A narrow question and a witness path usually reveal more than a dense repository-wide graph whose scope and layer are hard to explain.