generated from coulomb/repo-seed
87 lines
3.1 KiB
Markdown
87 lines
3.1 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.
|
|
|
|
## 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.
|
|
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`, `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`.
|
|
|
|
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.
|