generated from coulomb/repo-seed
101 lines
3.9 KiB
Markdown
101 lines
3.9 KiB
Markdown
# 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.
|