# 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:

```json
{
  "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.