repo-scoping/docs/dependency-visualization-exploration.md

Dependency Visualization Exploration

Repository Scoping exposes approved repository characteristics as a layered dependency graph for curator review. The graph is Cytoscape-compatible JSON from /repos/{repository_id}/dependency-graph; the interactive view lives at /ui/repos/{repository_id}/dependency-graph.

The visualization framework decision is recorded in docs/adr-dependency-graph-visualization-framework.md.

Layers

Graph nodes carry stable layer metadata:

• fact: deterministic scanner output, keyed by fact kind, path, and name.
• evidence: approved evidence records that interpret facts or source references.
• feature: concrete implemented behavior or surface area.
• capability: curator-approved functional claim.
• ability: higher-level ability grouping.
• scope: repository-level scope summary.

Evidence sits between facts and interpreted claims. Evidence should point to a feature when it supports a specific implementation surface, such as a test for a CLI command. Evidence should point directly to a capability when it supports the capability as a whole and no narrower feature target is known. Facts can observe evidence and features; evidence can support features or capabilities.

Document-level facts are normalized for graph readability. Derived SCOPE.md facts are suppressed when they only restate generated scope, and README/SCOPE document facts that describe the same file-level support are represented once.

Display States

Each active graph element receives a displayState:

• show: visible with normal labels and styling.
• blur: visible in a muted style; labels and descriptions are suppressed until hover or selection.
• hide: removed from the active graph payload and listed in hidden_elements.

Rule precedence is deterministic: later rules override earlier rules, then manual overrides win last. If a node is hidden, connected edges are hidden too. If a node is blurred, connected edges receive a muted context hint so the surrounding dependency path remains visible without competing for attention. Manual overrides are stored by stable graph key and orphaned keys are surfaced when a profile references nodes or edges that no longer exist.

Filter Rules

Rules are JSON objects with an action of show, blur, or hide, plus a match object. Common match fields include kind, layer, reviewState, primaryClass, attributes, confidence, freshnessState, ownership, dependencyType, strength, sameLayer, path, and text.

Example:

{
  "name": "Blur deterministic facts",
  "action": "blur",
  "match": {"layer": "fact"}
}

View Profiles

View profiles are repository-scoped saved graph perspectives. The profile API supports create, list, load, update, duplicate, and delete operations under /repos/{repository_id}/dependency-graph/profiles.

When a graph is opened without an explicit profile_id, the most recently saved repository profile is applied by default. API clients can pass use_latest_profile=false to request an unsaved full graph view.

Profiles store:

• name and optional description
• default graph mode
• filter rules
• manual visibility overrides
• timestamps

Example profiles:

• Scope Impact: default impact mode; show stale or changed nodes and blur current context.
• Hide Tooling Noise: hide facts with dependency or tooling attributes.
• Evidence Audit: show evidence and facts; blur abilities and scope.
• Same-Layer Normalization Review: show same-layer edges and blur ordinary upward dependency arrows.

Hiding evidence can make a graph appear cleaner while also removing the reason a capability is trusted. Prefer blurring evidence when reviewing scope impact so the support chain remains visible as context.

Nodes scale within a bounded size range when confidence is available. Edge width is derived from dependency strength. Hovering a graph element shows a compact popup; selecting it still opens the full side-panel detail.