coulomb/railiance-fabric
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add graph explorer UI shell

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-18 17:11:36 +02:00
parent d2056c9046
commit d31b1376c8
7 changed files with 396 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
README.md
View File

@@ -95,6 +95,7 @@ GET /repositories/{repo_slug}/inventory
GET /repositories/{repo_slug}/snapshots
GET /repositories/{repo_slug}/snapshots/diff
GET /search?q=jsonschema
GET /ui/graph-explorer
GET /exports/graph-explorer/manifest
GET /exports/graph-explorer
```

1
docs/graph-explorer-contract.md
View File

@@ -19,6 +19,7 @@ payload with stable fields.
The registry service exposes the first Fabric projection:
```text
GET /ui/graph-explorer
GET /exports/graph-explorer/manifest
GET /exports/graph-explorer
```

1
docs/registry-api.md
View File

@@ -64,6 +64,7 @@ GET /exports/state-hub
GET /exports/backstage
GET /exports/xregistry
GET /exports/libraries/xregistry
GET /ui/graph-explorer
GET /exports/graph-explorer/manifest
GET /exports/graph-explorer
```

364
railiance_fabric/graph_explorer_ui.py Normal file
View File

@@ -0,0 +1,364 @@
from __future__ import annotations
def graph_explorer_page() -> str:
return """<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Fabric Map</title>
<style>
:root {
color-scheme: light;
font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
--bg: #f7f8fa;
--panel: #ffffff;
--line: #d6dce5;
--text: #172033;
--muted: #667085;
--accent: #0f766e;
--accent-2: #2563eb;
--warn: #b45309;
}
* { box-sizing: border-box; }
html, body { height: 100%; margin: 0; }
body { background: var(--bg); color: var(--text); font-size: 14px; }
.shell { display: grid; grid-template-rows: auto 1fr; height: 100vh; min-height: 620px; }
.toolbar {
display: grid;
grid-template-columns: minmax(180px, 1.2fr) repeat(3, minmax(120px, .6fr)) auto auto auto;
gap: 8px;
align-items: center;
padding: 10px 12px;
border-bottom: 1px solid var(--line);
background: var(--panel);
}
.main { display: grid; grid-template-columns: minmax(0, 1fr) 340px; min-height: 0; }
.canvas-wrap { position: relative; min-width: 0; min-height: 0; }
#graph-canvas { position: absolute; inset: 0; }
.side {
border-left: 1px solid var(--line);
background: var(--panel);
min-height: 0;
overflow: auto;
padding: 14px;
}
.side h1 { font-size: 17px; line-height: 1.2; margin: 0 0 10px; }
.section { border-top: 1px solid var(--line); padding-top: 12px; margin-top: 12px; }
.section:first-child { border-top: 0; padding-top: 0; margin-top: 0; }
label { color: var(--muted); display: grid; gap: 4px; font-size: 12px; }
input, select, button {
border: 1px solid var(--line);
border-radius: 6px;
color: var(--text);
font: inherit;
min-height: 34px;
padding: 6px 8px;
background: #ffffff;
}
button {
cursor: pointer;
display: inline-flex;
align-items: center;
justify-content: center;
gap: 6px;
white-space: nowrap;
}
button.primary { background: var(--accent); border-color: var(--accent); color: #ffffff; }
button:disabled { color: #98a2b3; cursor: default; }
.button-row { display: flex; flex-wrap: wrap; gap: 8px; }
.meta { color: var(--muted); font-size: 12px; margin: 0; }
.pill {
display: inline-flex;
align-items: center;
border: 1px solid var(--line);
border-radius: 999px;
color: var(--muted);
min-height: 24px;
padding: 2px 8px;
margin: 0 4px 4px 0;
font-size: 12px;
}
.detail-list { display: grid; gap: 6px; margin: 8px 0 0; padding: 0; list-style: none; }
.detail-list li { overflow-wrap: anywhere; }
.popup {
position: absolute;
z-index: 4;
max-width: 260px;
display: none;
border: 1px solid var(--line);
border-radius: 8px;
background: #ffffff;
box-shadow: 0 16px 40px rgba(23, 32, 51, .14);
padding: 10px;
pointer-events: none;
}
.popup strong { display: block; margin-bottom: 4px; }
.notice { color: var(--warn); padding: 14px; }
@media (max-width: 900px) {
.shell { min-height: 760px; }
.toolbar { grid-template-columns: 1fr 1fr; }
.main { grid-template-columns: 1fr; grid-template-rows: minmax(420px, 1fr) 330px; }
.side { border-left: 0; border-top: 1px solid var(--line); }
}
</style>
</head>
<body>
<section class="shell">
<div class="toolbar">
<label>Search <input id="search" autocomplete="off"></label>
<label>Layer <select id="layer-filter"><option value="">Any</option></select></label>
<label>Review <select id="review-filter"><option value="">Any</option><option>accepted</option><option>candidate</option></select></label>
<label>Unresolved <select id="unresolved-filter"><option value="">Any</option><option value="true">Only</option></select></label>
<button type="button" data-action="fit">Fit</button>
<button type="button" data-action="focus">Focus</button>
<button type="button" data-action="clear" class="primary">Reset</button>
<span id="counts" class="meta"></span>
</div>
<main class="main">
<div class="canvas-wrap">
<div id="graph-canvas" role="img" aria-label="Interactive Fabric graph"></div>
<div id="popup" class="popup"></div>
</div>
<aside class="side">
<section class="section">
<h1 id="detail-title">Fabric Map</h1>
<p id="detail-summary" class="meta">No selection</p>
<div id="detail-pills"></div>
<ul id="detail-list" class="detail-list"></ul>
</section>
<section class="section">
<div class="button-row">
<button type="button" data-override="show">Show</button>
<button type="button" data-override="blur">Blur</button>
<button type="button" data-override="hide">Hide</button>
<button type="button" data-action="reset-overrides">Clear Overrides</button>
</div>
</section>
<section class="section">
<p id="hidden-summary" class="meta">Hidden 0</p>
<div id="legend"></div>
</section>
</aside>
</main>
</section>
<script src="https://unpkg.com/cytoscape@3.28.1/dist/cytoscape.min.js"></script>
<script>
(() => {
const manifestUrl = "/exports/graph-explorer/manifest";
const graphUrl = "/exports/graph-explorer";
const canvas = document.getElementById("graph-canvas");
const popup = document.getElementById("popup");
const searchInput = document.getElementById("search");
const layerFilter = document.getElementById("layer-filter");
const reviewFilter = document.getElementById("review-filter");
const unresolvedFilter = document.getElementById("unresolved-filter");
const counts = document.getElementById("counts");
const hiddenSummary = document.getElementById("hidden-summary");
const detailTitle = document.getElementById("detail-title");
const detailSummary = document.getElementById("detail-summary");
const detailPills = document.getElementById("detail-pills");
const detailList = document.getElementById("detail-list");
const legend = document.getElementById("legend");
let cy = null;
let selected = null;
let focusSet = null;
let manualOverrides = {};
let layerColors = {};
const escapeHtml = (value) => String(value ?? "")
.replaceAll("&", "&amp;").replaceAll("<", "&lt;")
.replaceAll(">", "&gt;").replaceAll('"', "&quot;");
const elementText = (data) => [
data.id, data.stableKey, data.label, data.name, data.description,
data.repo, data.domain, data.kind, data.layer, data.edgeType
].join(" ").toLowerCase();
const matchesFilters = (element) => {
const data = element.data();
const text = searchInput.value.trim().toLowerCase();
if (text && !elementText(data).includes(text)) return false;
if (layerFilter.value && data.layer !== layerFilter.value) return false;
if (reviewFilter.value && data.reviewState !== reviewFilter.value) return false;
if (unresolvedFilter.value === "true" && data.unresolved !== true) return false;
if (focusSet && !focusSet.has(element.id())) return false;
return true;
};
const applyFilters = () => {
if (!cy) return;
const hiddenNodes = new Set();
cy.nodes().forEach((node) => {
let state = matchesFilters(node) ? "show" : "hide";
if (manualOverrides[node.id()]) state = manualOverrides[node.id()];
node.data("displayState", state);
node.toggleClass("display-blur", state === "blur");
node.style("display", state === "hide" ? "none" : "element");
if (state === "hide") hiddenNodes.add(node.id());
});
cy.edges().forEach((edge) => {
let state = matchesFilters(edge) ? "show" : "hide";
if (hiddenNodes.has(edge.data("source")) || hiddenNodes.has(edge.data("target"))) state = "hide";
if (manualOverrides[edge.id()]) state = manualOverrides[edge.id()];
edge.data("displayState", state);
edge.toggleClass("display-blur", state === "blur");
edge.style("display", state === "hide" ? "none" : "element");
});
const visibleNodes = cy.nodes().filter((node) => node.style("display") !== "none").length;
const visibleEdges = cy.edges().filter((edge) => edge.style("display") !== "none").length;
const hidden = cy.elements().length - visibleNodes - visibleEdges;
counts.textContent = `${visibleNodes} nodes / ${visibleEdges} edges`;
hiddenSummary.textContent = `Hidden ${hidden}`;
};
const showDetails = (element) => {
selected = element || null;
if (!element) {
detailTitle.textContent = "Fabric Map";
detailSummary.textContent = "No selection";
detailPills.innerHTML = "";
detailList.innerHTML = "";
return;
}
const data = element.data();
detailTitle.textContent = data.name || data.label || data.id;
detailSummary.textContent = data.description || data.id;
detailPills.innerHTML = ["kind", "layer", "repo", "reviewState", "displayState"]
.map((field) => data[field] ? `<span class="pill">${escapeHtml(data[field])}</span>` : "")
.join("");
const links = data.deepLinks || {};
const refs = data.sourceReferences || [];
const rows = [
["id", data.id],
["source", data.source],
["target", data.target],
["edge", data.edgeType],
["strength", data.strength],
...Object.entries(links),
...refs.map((ref) => [ref.label || ref.kind || "source", ref.path || ref.url || ref.ref || ""])
];
detailList.innerHTML = rows
.filter(([, value]) => value)
.map(([key, value]) => `<li><strong>${escapeHtml(key)}</strong> ${escapeHtml(value)}</li>`)
.join("");
};
const applyFocus = () => {
if (!cy || !selected) return;
const collection = selected.union(selected.neighborhood()).union(selected.neighborhood().neighborhood());
focusSet = new Set(collection.map((item) => item.id()));
applyFilters();
};
const renderLegend = (layers) => {
legend.innerHTML = layers.map((layer) =>
`<span class="pill"><span style="display:inline-block;width:10px;height:10px;border-radius:50%;background:${escapeHtml(layer.color || "#667085")}"></span>${escapeHtml(layer.label)}</span>`
).join("");
};
const boot = async () => {
const [manifest, payload] = await Promise.all([
fetch(manifestUrl).then((response) => response.json()),
fetch(graphUrl).then((response) => response.json())
]);
layerColors = Object.fromEntries((manifest.layers || []).map((layer) => [layer.id, layer.color]));
(manifest.layers || []).forEach((layer) => {
const option = document.createElement("option");
option.value = layer.id;
option.textContent = layer.label;
layerFilter.appendChild(option);
});
renderLegend(manifest.layers || []);
const elements = (payload.elements || []).map((element) => ({
...element,
data: {...element.data, color: layerColors[element.data.layer] || "#667085"}
}));
cy = cytoscape({
container: canvas,
elements,
layout: {name: "cose", animate: false, randomize: false},
style: [
{selector: "node", style: {
"background-color": "data(color)",
"border-color": "#172033",
"border-width": 1,
"color": "#172033",
"font-size": 11,
"height": "data(visualSize)",
"label": "data(label)",
"text-background-color": "#ffffff",
"text-background-opacity": .85,
"text-background-padding": 2,
"text-wrap": "wrap",
"text-max-width": 130,
"width": "data(visualSize)"
}},
{selector: "edge", style: {
"curve-style": "bezier",
"line-color": "#98a2b3",
"target-arrow-color": "#98a2b3",
"target-arrow-shape": "triangle",
"width": "data(edgeWidth)"
}},
{selector: "edge[strength = 'strong']", style: {"line-color": "#344054", "target-arrow-color": "#344054"}},
{selector: "edge[strength = 'weak']", style: {"line-style": "dotted"}},
{selector: ".display-blur", style: {"opacity": .24, "label": ""}},
{selector: ".display-blur:selected, .display-blur.hover", style: {"opacity": .78, "label": "data(label)"}},
{selector: ":selected", style: {"border-width": 4, "border-color": "#111827", "line-color": "#111827", "target-arrow-color": "#111827"}}
]
});
cy.on("tap", "node, edge", (event) => showDetails(event.target));
cy.on("tap", (event) => { if (event.target === cy) showDetails(null); });
cy.on("mouseover", "node, edge", (event) => {
event.target.addClass("hover");
const data = event.target.data();
popup.innerHTML = `<strong>${escapeHtml(data.name || data.label || data.id)}</strong><span class="meta">${escapeHtml(data.kind)} / ${escapeHtml(data.layer)}</span>`;
popup.style.left = `${Math.min(event.renderedPosition.x + 14, canvas.clientWidth - 270)}px`;
popup.style.top = `${Math.max(10, event.renderedPosition.y + 14)}px`;
popup.style.display = "block";
});
cy.on("mouseout", "node, edge", (event) => {
event.target.removeClass("hover");
popup.style.display = "none";
});
applyFilters();
};
[searchInput, layerFilter, reviewFilter, unresolvedFilter].forEach((control) => {
control.addEventListener("input", () => { focusSet = null; applyFilters(); });
});
document.querySelector("[data-action='fit']").addEventListener("click", () => cy && cy.fit(cy.elements(":visible"), 48));
document.querySelector("[data-action='focus']").addEventListener("click", applyFocus);
document.querySelector("[data-action='clear']").addEventListener("click", () => {
searchInput.value = "";
layerFilter.value = "";
reviewFilter.value = "";
unresolvedFilter.value = "";
focusSet = null;
applyFilters();
});
document.querySelector("[data-action='reset-overrides']").addEventListener("click", () => {
manualOverrides = {};
applyFilters();
});
document.querySelectorAll("[data-override]").forEach((button) => {
button.addEventListener("click", () => {
if (!selected) return;
manualOverrides[selected.id()] = button.dataset.override;
applyFilters();
});
});
if (!window.cytoscape) {
canvas.innerHTML = "<p class='notice'>Cytoscape.js could not be loaded.</p>";
return;
}
boot().catch((error) => {
canvas.innerHTML = `<p class='notice'>${escapeHtml(error.message)}</p>`;
});
})();
</script>
</body>
</html>
"""

22
railiance_fabric/server.py
View File

@@ -3,6 +3,7 @@ from __future__ import annotations
import argparse
import json
import sys
from dataclasses import dataclass
from http import HTTPStatus
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
@@ -10,6 +11,7 @@ from typing import Any
from urllib.parse import parse_qs, urlparse
from .graph_explorer import fabric_graph_explorer_manifest, fabric_graph_explorer_payload
from .graph_explorer_ui import graph_explorer_page
from .registry import (
RegistryError,
RegistryStore,
@@ -24,6 +26,11 @@ from .registry import (
)
@dataclass(frozen=True)
class HtmlResponse:
body: str
class RegistryHandler(BaseHTTPRequestHandler):
store: RegistryStore
@@ -40,6 +47,8 @@ class RegistryHandler(BaseHTTPRequestHandler):
parts = _parts(path)
if path == "/health":
return HTTPStatus.OK, {"status": "ok"}
if parts == ["ui", "graph-explorer"]:
return HTTPStatus.OK, HtmlResponse(graph_explorer_page())
if path == "/status":
return HTTPStatus.OK, self.store.status()
if parts == ["repositories"]:
@@ -129,7 +138,10 @@ class RegistryHandler(BaseHTTPRequestHandler):
query = parse_qs(parsed.query)
try:
status, body = action(parsed.path, query)
self._send_json(int(status), body)
if isinstance(body, HtmlResponse):
self._send_text(int(status), body.body, "text/html; charset=utf-8")
else:
self._send_json(int(status), body)
except RegistryError as exc:
self._send_json(exc.status_code, {"error": exc.message})
except json.JSONDecodeError as exc:
@@ -149,8 +161,14 @@ class RegistryHandler(BaseHTTPRequestHandler):
def _send_json(self, status: int, body: Any) -> None:
payload = json.dumps(body, indent=2, sort_keys=True).encode("utf-8")
self._send_bytes(status, payload, "application/json; charset=utf-8")
def _send_text(self, status: int, body: str, content_type: str) -> None:
self._send_bytes(status, body.encode("utf-8"), content_type)
def _send_bytes(self, status: int, payload: bytes, content_type: str) -> None:
self.send_response(status)
self.send_header("Content-Type", "application/json; charset=utf-8")
self.send_header("Content-Type", content_type)
self.send_header("Content-Length", str(len(payload)))
self.end_headers()
self.wfile.write(payload)

8
tests/test_graph_explorer.py
View File

@@ -177,11 +177,19 @@ def test_registry_serves_graph_explorer_exports(tmp_path: Path) -> None:
manifest = json.loads(response.read())
with urllib.request.urlopen(f"{base_url}/exports/graph-explorer", timeout=5) as response:
payload = json.loads(response.read())
with urllib.request.urlopen(f"{base_url}/ui/graph-explorer", timeout=5) as response:
page = response.read().decode("utf-8")
content_type = response.headers["Content-Type"]
_validate_schema("graph-explorer-manifest.schema.yaml", manifest)
_validate_schema("graph-explorer-payload.schema.yaml", payload)
assert manifest["id"] == "railiance-fabric.registry-map"
assert payload["metrics"]["registered_only_repo_count"] == 1
assert content_type.startswith("text/html")
assert 'id="graph-canvas"' in page
assert "cytoscape.min.js" in page
assert "/exports/graph-explorer/manifest" in page
assert 'data-override="hide"' in page
finally:
server.shutdown()
server.server_close()

2
workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md
View File

@@ -205,7 +205,7 @@ Acceptance notes:
```task
id: RAIL-FAB-WP-0008-T04
status: todo
status: in_progress
priority: high
state_hub_task_id: "75c1f234-026c-44ed-9c88-db39653b81e0"
```