sidegraph 0.1.0__py3-none-any.whl

sidegraph/viz/model.py

@@ -0,0 +1,248 @@
+"""Assemble a semantic graph over the owned Decision/Fact records and their anchored
+entities. Pure and portable: reads only :class:`~sidegraph.store.Store` — no engine reader,
+no host specifics, no writes. :mod:`sidegraph.viz.render` turns this into HTML/JSON.
+
+# see design/superpowers/specs/2026-07-12-decision-graph-viz-design.md
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..store import Store
+
+_TERMINAL_STATUSES = frozenset({"superseded", "rejected", "deprecated"})
+_PROBLEM_BINDING_STATUSES = frozenset({"degraded", "orphaned"})
+
+
+@dataclass
+class VizNode:
+    id: str
+    type: str  # "decision" | "fact" | "entity"
+    label: str
+    detail: dict[str, object]  # full record fields for the click-to-inspect sidebar
+    kind: str | None = None  # decision kind (adr/lesson/constraint/gotcha); else None
+    status: str | None = None  # record status; None for entities
+    tier: int | None = None  # entity primary tier (min over incident anchors); None for records
+    community: str | None = None  # entity last_seen_community; None for records
+    degree: int = 0
+    dangling: bool = False  # record node with no anchor binding at all (any status)
+    problem: bool = False  # dangling OR incident to a degraded/orphaned binding
+
+
+@dataclass
+class VizEdge:
+    source: str
+    target: str
+    kind: str  # "anchor" | "supersedes" | "supports" | "domain-parent"
+    status: str | None = None  # binding status for anchor edges
+    relation: str | None = None  # binding relation for anchor edges
+    weight: float = 1.0
+
+
+@dataclass
+class VizStats:
+    decisions: int = 0
+    facts: int = 0
+    entities: int = 0
+    orphaned_bindings: int = 0
+    degraded_bindings: int = 0
+    dangling_records: int = 0
+    supersede_links: int = 0
+    truncated: int = 0
+
+
+@dataclass
+class VizGraph:
+    nodes: list[VizNode] = field(default_factory=list)
+    edges: list[VizEdge] = field(default_factory=list)
+    stats: VizStats = field(default_factory=VizStats)
+
+
+def _short(text: str, limit: int = 60) -> str:
+    stripped = text.strip()
+    line = stripped.splitlines()[0] if stripped else ""
+    return line if len(line) <= limit else line[: limit - 1] + "…"
+
+
+def _recompute_degree(nodes: dict[str, VizNode], edges: list[VizEdge]) -> None:
+    for n in nodes.values():
+        n.degree = 0
+    for e in edges:
+        nodes[e.source].degree += 1
+        nodes[e.target].degree += 1
+
+
+def build_graph(
+    store: Store,
+    *,
+    include_superseded: bool = True,
+    only_problems: bool = False,
+    max_nodes: int = 800,
+) -> VizGraph:
+    """Build a :class:`VizGraph` from the store. See module docstring."""
+    nodes: dict[str, VizNode] = {}
+    edges: list[VizEdge] = []
+    referenced_entities: dict[str, int] = {}  # entity_id -> min tier seen
+
+    def _keep(status: str) -> bool:
+        return include_superseded or status not in _TERMINAL_STATUSES
+
+    def _anchor_edges(record_id: str) -> None:
+        for b in store.bindings_for_record(record_id):
+            edges.append(
+                VizEdge(
+                    source=record_id,
+                    target=b.entity_id,
+                    kind="anchor",
+                    status=b.status,
+                    relation=b.relation,
+                    weight=b.weight,
+                )
+            )
+            prev = referenced_entities.get(b.entity_id)
+            referenced_entities[b.entity_id] = b.tier if prev is None else min(prev, b.tier)
+
+    # --- decision & fact record nodes + their anchor / structural edges ---
+    for d in store.iter_decisions():
+        if not _keep(d.status.value):
+            continue
+        nodes[d.id] = VizNode(
+            id=d.id,
+            type="decision",
+            label=_short(d.title),
+            kind=d.kind.value,
+            status=d.status.value,
+            detail={
+                "title": d.title,
+                "kind": d.kind.value,
+                "status": d.status.value,
+                "context": d.context,
+                "choice": d.choice,
+                "rejected": d.rejected,
+                "consequences": d.consequences,
+                "scope": d.scope.value,
+            },
+        )
+        _anchor_edges(d.id)
+        if d.supersedes:
+            edges.append(VizEdge(source=d.id, target=d.supersedes, kind="supersedes"))
+
+    for f in store.iter_facts():
+        if not _keep(f.status.value):
+            continue
+        nodes[f.id] = VizNode(
+            id=f.id,
+            type="fact",
+            label=_short(f.statement),
+            status=f.status.value,
+            detail={
+                "statement": f.statement,
+                "source": f.source,
+                "supports": list(f.supports),
+                "status": f.status.value,
+            },
+        )
+        _anchor_edges(f.id)
+        if f.supersedes:
+            edges.append(VizEdge(source=f.id, target=f.supersedes, kind="supersedes"))
+        for dec_id in f.supports:
+            edges.append(VizEdge(source=f.id, target=dec_id, kind="supports"))
+
+    # --- entity nodes (only those referenced by a binding) ---
+    for entity_id, tier in referenced_entities.items():
+        ent = store.get_entity(entity_id)
+        if ent is None:
+            continue
+        label = ent.descriptor.name if ent.descriptor else ent.canonical_name
+        nodes[entity_id] = VizNode(
+            id=entity_id,
+            type="entity",
+            label=label,
+            tier=tier,
+            community=ent.last_seen_community,
+            detail={
+                "canonical_name": ent.canonical_name,
+                "kind": ent.kind.value,
+                "file_path": ent.descriptor.file_path if ent.descriptor else None,
+                "last_seen_community": ent.last_seen_community,
+            },
+        )
+
+    # --- domain parent hierarchy (between the domain: entities already drawn) ---
+    domains = list(store.iter_domains())
+    slug_by_domain_id = {dm.domain_id: dm.slug for dm in domains}
+    entity_by_domain_slug: dict[str, str] = {}
+    for nid, n in nodes.items():
+        cname = n.detail.get("canonical_name")
+        if n.type == "entity" and isinstance(cname, str) and cname.startswith("domain:"):
+            entity_by_domain_slug[cname[len("domain:") :]] = nid
+    for dm in domains:
+        if not dm.parent_id or dm.parent_id not in slug_by_domain_id:
+            continue
+        child = entity_by_domain_slug.get(dm.slug)
+        parent = entity_by_domain_slug.get(slug_by_domain_id[dm.parent_id])
+        if child and parent:
+            edges.append(VizEdge(source=child, target=parent, kind="domain-parent"))
+
+    # --- prune edges to surviving endpoints ---
+    edges = [e for e in edges if e.source in nodes and e.target in nodes]
+
+    # --- dangling + problem flags ---
+    # "dangling" = zero anchor bindings at all; a degraded/orphaned binding is a separate
+    # "problem" signal (an anchored record whose binding decayed is not unanchored).
+    has_binding: set[str] = set()
+    incident_problem: set[str] = set()
+    for e in edges:
+        if e.kind == "anchor":
+            has_binding.add(e.source)
+            if e.status in _PROBLEM_BINDING_STATUSES:
+                incident_problem.add(e.source)
+                incident_problem.add(e.target)
+    for nid, n in nodes.items():
+        if n.type in ("decision", "fact"):
+            n.dangling = nid not in has_binding
+        n.problem = n.dangling or nid in incident_problem
+
+    # --- only-problems filter (problem nodes + 1-hop context) ---
+    if only_problems:
+        problem_nodes = {nid for nid, n in nodes.items() if n.problem}
+        keep = set(problem_nodes)
+        for e in edges:
+            if e.source in problem_nodes or e.target in problem_nodes:
+                keep.add(e.source)
+                keep.add(e.target)
+        nodes = {nid: n for nid, n in nodes.items() if nid in keep}
+        edges = [e for e in edges if e.source in nodes and e.target in nodes]
+
+    _recompute_degree(nodes, edges)
+
+    # --- max-nodes truncation (deterministic priority; never silent) ---
+    stats = VizStats()
+    if len(nodes) > max_nodes:
+
+        def _priority(n: VizNode) -> tuple[int, int, int, int, str]:
+            terminal = 1 if (n.status in _TERMINAL_STATUSES) else 0
+            type_rank = 2 if n.type == "entity" else 0
+            # `n.id` as the final tiebreak makes truncation deterministic across index
+            # rebuilds -- otherwise ties fall back to dict/iteration order, which is not
+            # reproducible.
+            return (0 if n.problem else 1, type_rank, terminal, -n.degree, n.id)
+
+        ranked = sorted(nodes.values(), key=_priority)
+        keep_ids = {n.id for n in ranked[:max_nodes]}
+        stats.truncated = len(nodes) - len(keep_ids)
+        nodes = {nid: n for nid, n in nodes.items() if nid in keep_ids}
+        edges = [e for e in edges if e.source in nodes and e.target in nodes]
+        _recompute_degree(nodes, edges)
+
+    # --- final stats over the surviving graph ---
+    stats.decisions = sum(1 for n in nodes.values() if n.type == "decision")
+    stats.facts = sum(1 for n in nodes.values() if n.type == "fact")
+    stats.entities = sum(1 for n in nodes.values() if n.type == "entity")
+    stats.orphaned_bindings = sum(1 for e in edges if e.kind == "anchor" and e.status == "orphaned")
+    stats.degraded_bindings = sum(1 for e in edges if e.kind == "anchor" and e.status == "degraded")
+    stats.dangling_records = sum(1 for n in nodes.values() if n.dangling)
+    stats.supersede_links = sum(1 for e in edges if e.kind == "supersedes")
+
+    return VizGraph(nodes=list(nodes.values()), edges=edges, stats=stats)

sidegraph/viz/render.py

@@ -0,0 +1,110 @@
+"""Turn a :class:`~sidegraph.viz.model.VizGraph` into a vis-network-ready JSON document
+(``to_json``) and a self-contained offline HTML file (``to_html``, added in Task 4).
+
+# see design/superpowers/specs/2026-07-12-decision-graph-viz-design.md
+"""
+
+from __future__ import annotations
+
+import importlib.resources as resources
+import json
+from dataclasses import asdict
+
+from .model import VizEdge, VizGraph, VizNode
+
+_KIND_COLOR = {
+    "adr": "#4f8ef7",  # blue
+    "gotcha": "#e0533d",  # warm red — mistakes
+    "constraint": "#e0913d",  # amber
+    "lesson": "#c76fe0",  # purple
+}
+_TIER_COLOR = {2: "#8a94a6", 1: "#6a5acd", 0: "#557a55"}
+_FACT_COLOR = "#3dae9c"
+_EDGE_STATUS_COLOR = {"live": "#8a94a6", "degraded": "#e0913d", "orphaned": "#e0533d"}
+_TERMINAL_STATUSES = frozenset({"superseded", "rejected", "deprecated"})
+_PROBLEM_BORDER = "#e0533d"
+
+
+def _node_json(n: VizNode) -> dict[str, object]:
+    if n.type == "decision":
+        background = _KIND_COLOR.get(n.kind or "", "#4f8ef7")
+        shape = "box"
+    elif n.type == "fact":
+        background = _FACT_COLOR
+        shape = "diamond"
+    else:
+        background = _TIER_COLOR.get(n.tier if n.tier is not None else 2, "#8a94a6")
+        shape = "dot"
+    border = _PROBLEM_BORDER if n.problem else background
+    title = n.type
+    if n.status:
+        title += f" · {n.status}"
+    if n.tier is not None:
+        title += f" · tier {n.tier}"
+    return {
+        "id": n.id,
+        "type": n.type,
+        "label": n.label,
+        "title": title,
+        "color": {
+            "background": background,
+            "border": border,
+            "highlight": {"background": background, "border": "#ffffff"},
+        },
+        "shape": shape,
+        "size": 10 + min(n.degree, 20) * 1.5,
+        "opacity": 0.4 if (n.status in _TERMINAL_STATUSES) else 1.0,
+        "problem": n.problem,
+        "dangling": n.dangling,
+        "detail": n.detail,
+    }
+
+
+def _edge_json(e: VizEdge) -> dict[str, object]:
+    if e.kind == "anchor":
+        color = _EDGE_STATUS_COLOR.get(e.status or "live", "#8a94a6")
+        width = 1.0 + 3.0 * e.weight
+        label = "" if e.relation in (None, "affects") else e.relation
+        dashes: object = False
+    elif e.kind == "supersedes":
+        color, width, label, dashes = "#b0b0b0", 1.5, "supersedes", True
+    elif e.kind == "supports":
+        color, width, label, dashes = "#3dae9c", 1.5, "supports", False
+    else:  # domain-parent
+        color, width, label, dashes = "#6a5acd", 1.5, "parent", [2, 4]
+    return {
+        "from": e.source,
+        "to": e.target,
+        "kind": e.kind,
+        "color": {"color": color, "opacity": 0.7},
+        "width": width,
+        "label": label,
+        "dashes": dashes,
+        "arrows": "to",
+        "status": e.status,
+        "relation": e.relation,
+        "weight": e.weight,
+    }
+
+
+def to_json(graph: VizGraph) -> dict[str, object]:
+    """vis-network-ready ``{nodes, edges, stats}`` — embedded in the HTML and emitted by
+    ``sidegraph-viz --json``."""
+    return {
+        "nodes": [_node_json(n) for n in graph.nodes],
+        "edges": [_edge_json(e) for e in graph.edges],
+        "stats": asdict(graph.stats),
+    }
+
+
+def to_html(graph: VizGraph) -> str:
+    """Render a self-contained offline HTML: the vendored vis-network library and the graph
+    JSON are inlined into ``template.html``. No external resource is ever loaded."""
+    pkg = resources.files("sidegraph.viz")
+    template = pkg.joinpath("template.html").read_text(encoding="utf-8")
+    library = pkg.joinpath("assets", "vis-network.min.js").read_text(encoding="utf-8")
+    # `</` -> `<\/` so no string value inside the JSON can close the <script> element early.
+    data = json.dumps(to_json(graph)).replace("</", "<\\/")
+    html = template.replace("__SIDEGRAPH_VIS_JS__", library)
+    html = html.replace("__SIDEGRAPH_GRAPH_JSON__", data)
+    return html

sidegraph/viz/template.html

@@ -0,0 +1,131 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Sidegraph — decision/fact graph</title>
+<style>
+  :root { color-scheme: dark; }
+  html, body { margin: 0; height: 100%; background: #0f0f1a; color: #e6e6ef;
+    font: 13px/1.4 -apple-system, "Segoe UI", Roboto, sans-serif; }
+  #app { display: flex; height: 100vh; }
+  #net { flex: 1; height: 100%; }
+  #side { width: 340px; box-sizing: border-box; padding: 14px; overflow-y: auto;
+    background: #16162a; border-left: 1px solid #262640; }
+  #side h1 { font-size: 15px; margin: 0 0 8px; }
+  #search { width: 100%; box-sizing: border-box; padding: 6px 8px; margin-bottom: 10px;
+    background: #0f0f1a; color: #e6e6ef; border: 1px solid #33334d; border-radius: 4px; }
+  .stat { display: flex; justify-content: space-between; padding: 2px 0; }
+  .stat b { color: #fff; }
+  .warn b, .warn span { color: #e0533d; }
+  #legend div { padding: 2px 0; }
+  .sw { display: inline-block; width: 10px; height: 10px; margin-right: 6px;
+    border-radius: 2px; vertical-align: middle; }
+  #info { margin-top: 12px; border-top: 1px solid #262640; padding-top: 10px; }
+  #info h2 { font-size: 13px; margin: 0 0 6px; word-break: break-word; }
+  #info .field { margin: 4px 0; }
+  #info .k { color: #9a9ab0; display: block; font-size: 11px; text-transform: uppercase;
+    letter-spacing: .04em; }
+  pre { white-space: pre-wrap; word-break: break-word; margin: 2px 0; }
+  h3 { font-size: 12px; text-transform: uppercase; letter-spacing: .05em;
+    color: #9a9ab0; margin: 14px 0 4px; }
+</style>
+</head>
+<body>
+<div id="app">
+  <div id="net"></div>
+  <div id="side">
+    <h1>Sidegraph graph</h1>
+    <input id="search" placeholder="search nodes…" autocomplete="off">
+    <div id="stats"></div>
+    <h3>Legend</h3>
+    <div id="legend"></div>
+    <div id="info"><em>click a node to inspect</em></div>
+  </div>
+</div>
+<script>__SIDEGRAPH_VIS_JS__</script>
+<script>
+const GRAPH = __SIDEGRAPH_GRAPH_JSON__;
+(function () {
+  const nodes = new vis.DataSet(GRAPH.nodes);
+  const edges = new vis.DataSet(GRAPH.edges);
+  const network = new vis.Network(document.getElementById("net"), { nodes, edges }, {
+    physics: {
+      stabilization: false,             // no hidden pre-settle — let the layout play out on screen
+      minVelocity: 2,                   // auto-stop once motion drops below this (~1-2s settle)
+      barnesHut: {
+        theta: 0.6,
+        gravitationalConstant: -16000,  // repulsion — spreads dense hubs apart
+        centralGravity: 0.35,           // pulls loose 2-3 node clusters back toward center
+        springLength: 180,              // rest length between linked nodes
+        springConstant: 0.05,
+        damping: 0.3,                   // higher -> the visible settle stops quickly
+        avoidOverlap: 0.3,              // keep node bodies from overlapping
+      },
+    },
+    interaction: { hover: true, tooltipDelay: 120 },
+    nodes: { font: { color: "#e6e6ef" } },
+    edges: { smooth: { type: "continuous" } },
+  });
+  const byId = {};
+  GRAPH.nodes.forEach(function (n) { byId[n.id] = n; });
+
+  const s = GRAPH.stats || {};
+  const rows = [
+    ["decisions", s.decisions], ["facts", s.facts], ["entities", s.entities],
+    ["orphaned bindings", s.orphaned_bindings], ["degraded bindings", s.degraded_bindings],
+    ["dangling records", s.dangling_records], ["supersede links", s.supersede_links],
+  ];
+  let statHtml = rows.map(function (r) {
+    return '<div class="stat"><span>' + r[0] + "</span><b>" + (r[1] || 0) + "</b></div>";
+  }).join("");
+  if (s.truncated) {
+    statHtml += '<div class="stat warn"><span>truncated</span><b>' + s.truncated + "</b></div>";
+  }
+  document.getElementById("stats").innerHTML = statHtml;
+
+  const legend = [
+    ["ADR", "#4f8ef7"], ["gotcha", "#e0533d"], ["constraint", "#e0913d"],
+    ["lesson", "#c76fe0"], ["fact", "#3dae9c"], ["entity", "#8a94a6"],
+    ["binding live", "#8a94a6"], ["binding degraded", "#e0913d"],
+    ["binding orphaned", "#e0533d"],
+  ];
+  document.getElementById("legend").innerHTML = legend.map(function (l) {
+    return '<div><span class="sw" style="background:' + l[1] + '"></span>' + l[0] + "</div>";
+  }).join("");
+
+  function escapeHtml(str) {
+    return String(str).replace(/[&<>"]/g, function (c) {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c];
+    });
+  }
+
+  network.on("click", function (params) {
+    const info = document.getElementById("info");
+    if (!params.nodes.length) { info.innerHTML = "<em>click a node to inspect</em>"; return; }
+    const n = byId[params.nodes[0]];
+    const d = n.detail || {};
+    let html = "<h2>" + escapeHtml(n.label) + "</h2>";
+    html += '<div class="field"><span class="k">type</span>' + escapeHtml(n.type) + "</div>";
+    Object.keys(d).forEach(function (k) {
+      const v = d[k];
+      if (v === null || v === undefined || v === "") return;
+      const val = Array.isArray(v) ? v.join(", ") : String(v);
+      html += '<div class="field"><span class="k">' + escapeHtml(k) + '</span><pre>'
+        + escapeHtml(val) + "</pre></div>";
+    });
+    info.innerHTML = html;
+  });
+
+  document.getElementById("search").addEventListener("input", function (e) {
+    const q = e.target.value.toLowerCase().trim();
+    if (!q) return;
+    const hit = GRAPH.nodes.find(function (n) {
+      return (n.label || "").toLowerCase().indexOf(q) !== -1;
+    });
+    if (hit) { network.selectNodes([hit.id]); network.focus(hit.id, { scale: 1.1 }); }
+  });
+})();
+</script>
+</body>
+</html>