generated from coulomb/repo-seed
85 lines
3.8 KiB
Markdown
85 lines
3.8 KiB
Markdown
# Graph Explorer Transfer Review
|
|
|
|
This note closes the first implementation step for `RAIL-FAB-WP-0008-T01`.
|
|
It reviews the repo-scoping dependency graph work from `RREG-WP-0010` and
|
|
`RREG-WP-0011` and turns the transferable parts into Fabric requirements.
|
|
|
|
## Source Implementation
|
|
|
|
Repo-scoping already has a useful graph explorer shape:
|
|
|
|
- `docs/adr-dependency-graph-visualization-framework.md` chooses Cytoscape.js
|
|
because the required interaction model is graph-native: pan, zoom, selection,
|
|
layouts, styling, filtering, and path exploration.
|
|
- `docs/dependency-visualization-exploration.md` defines layered graph data,
|
|
`show` / `blur` / `hide` display states, deterministic filters, manual
|
|
overrides, and saved view profiles.
|
|
- `src/repo_scoping/core/service.py` emits Cytoscape-compatible payloads with
|
|
stable keys, metadata-rich node and edge data, visibility state, hidden
|
|
elements, profile application, confidence sizing, and edge strength sizing.
|
|
- `src/repo_scoping/web_ui/views.py` provides the first UI shell: profile
|
|
controls, structured filters, manual overrides, focus depth, hover popups,
|
|
selection details, and a layered layout.
|
|
- `tests/test_web_api.py` verifies graph endpoints, ad hoc filters, profile
|
|
creation, duplicate profiles, latest-profile defaulting, and UI wiring.
|
|
|
|
## Reusable Behaviors
|
|
|
|
Fabric should carry these behaviors into the shared graph explorer contract:
|
|
|
|
- Cytoscape-compatible element arrays with `data` and optional `classes`.
|
|
- Stable element keys that survive refreshes, so layout state, profile rules,
|
|
and deep links do not churn.
|
|
- Metadata-rich nodes and edges rather than UI-only labels.
|
|
- Explicit `layer`, `kind`, `reviewState`, `freshnessState`, and
|
|
`displayState` fields.
|
|
- Visibility actions of `show`, `blur`, and `hide`, with later rules overriding
|
|
earlier rules and manual overrides winning last.
|
|
- Hidden element reporting, so over-filtered views are recoverable.
|
|
- Edge treatment for context-muted nodes.
|
|
- View profiles that can persist filter rules and manual overrides when a host
|
|
provides profile endpoints.
|
|
- Hover popups for compact inspection and selection panels for full detail.
|
|
- Layout modes for full graph, impact or filtered graph, selected path, and
|
|
neighborhood focus.
|
|
- Visual hints for confidence, strength, same-layer edges, stale or unresolved
|
|
state, and review state.
|
|
|
|
## Adapter-Owned Semantics
|
|
|
|
These repo-scoping concepts should remain in the repo-scoping adapter and not
|
|
be hard-coded into the engine:
|
|
|
|
- Layer names of `fact`, `evidence`, `feature`, `capability`, `ability`, and
|
|
`scope`.
|
|
- Candidate graph approval semantics.
|
|
- Dependency impact analysis over base and target analysis runs.
|
|
- Document fact normalization and README/SCOPE de-duplication.
|
|
- Scope curation recommendations.
|
|
|
|
Fabric has its own adapter semantics:
|
|
|
|
- Layer names of `repository`, `service`, `capability`, `interface`,
|
|
`dependency`, `binding`, and `library`.
|
|
- Registered-only repositories without accepted graph snapshots.
|
|
- State Hub repo ids, workplan links, and registry endpoints as deep links.
|
|
- Unresolved dependencies where provider bindings are missing or disputed.
|
|
- Blast-radius and provider-chain exploration across accepted Fabric
|
|
declarations.
|
|
|
|
## Extraction Recommendation
|
|
|
|
Start in `railiance-fabric` with a host-neutral manifest and payload contract,
|
|
plus a Fabric registry projection. The first UI shell can live locally while
|
|
the contract is still moving.
|
|
|
|
Extract into a separate repository only after two host adapters are proven:
|
|
|
|
1. Fabric registry map adapter.
|
|
2. Repo-scoping dependency graph adapter.
|
|
|
|
The likely extracted repository is `graph-explorer-engine`. It should own the
|
|
static interaction shell, schema definitions, layout/filter/profile client
|
|
logic, and adapter manifest contract. Host repos should keep graph projection,
|
|
profile persistence, authentication, and domain-specific deep links.
|