Architecture erodes one shortcut at a time: a UI file imports a database client, a low-level utility reaches into a feature module. Vibgrate Graph calls these surprising connections oddities, and vg oddities brings them to the surface. This guide explains what they are, how to find them, and how to decide which ones to fix.
Overview
Vibgrate Graph groups your code into natural areas (communities) based on how nodes connect. An oddity is an edge that crosses between areas in a way the rest of the structure does not predict — a link that stands out as surprising given the surrounding pattern. These are strong candidates for architectural smells: layering violations, leaky abstractions, and accidental coupling.
Prerequisites
Build a code map so the graph exists, then confirm it is current:
vg build
vg status
Find oddities
vg oddities
Each result points at a cross-area connection that looks out of place. Read it as a question rather than a verdict: “why does this node reach across into that area?” Some answers are legitimate; others reveal a shortcut that should be refactored.
Triaging the results
Work through the list with these questions:
- Is this a layering violation? A presentation node calling straight into persistence usually deserves an interface in between.
- Is it accidental coupling? Two unrelated features sharing internal state is fragile — extract a shared module instead.
- Is it intentional? Some cross-area links are deliberate seams. Note them so they are not re-flagged in spirit later.
To understand any flagged node in depth, inspect it directly:
vg show
This reveals its callers and callees so you can see exactly how the surprising link is formed.
Where oddities fit
vg oddities is most useful alongside the other map-level insights: vg areas shows the groupings the oddities cross, and vg hubs shows the nodes under the most pressure. Run all three when you want a structural health read on a codebase — for example, before a large refactor or when inheriting an unfamiliar project.
Related
- Discover code areas with
vg areas. - Find architectural hubs with
vg hubs. - Map the codebase with
vg map.
The analysis is deterministic and runs entirely on your machine.