@copperbox/why 1.0.0

package/ui/story-panel.js

@@ -0,0 +1,125 @@
+// Story panel: a dumb renderer over the story payload (`why blame --json`,
+// schemas/story.schema.json). Every semantic arrives precomputed — the hedge
+// is baked into renderedRationale (displayed verbatim, never re-derived) and
+// the expired-constraint blast radius arrives as `downstream` — so this file
+// only lays cards out. Exported as a pure (document, story) → element
+// function so the DOM smoke test can drive it without a browser.
+
+/** Same vocabulary the engine precomputes into coverage spans; the contract
+ * doc says stories derive theirs the same way from type + status. */
+export function glyphFor(type, status) {
+  if (type === "question") return "?";
+  if (status === "expired" || status === "superseded") return "⚠";
+  return "●";
+}
+
+export function formatTarget(target) {
+  if (!target.lines) return target.path;
+  const { start, end } = target.lines;
+  return `${target.path}:${start}${end === start ? "" : `-${end}`}`;
+}
+
+function el(doc, tag, className, text) {
+  const node = doc.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function isExpiredConstraint(block) {
+  return block.type === "constraint" && block.status === "expired";
+}
+
+function badge(doc, className, text) {
+  return el(doc, "span", `badge ${className}`, text);
+}
+
+const EDGE_LABELS = [
+  ["becauseOf", "because of"],
+  ["insteadOf", "instead of"],
+  ["supersededBy", "superseded by"],
+];
+
+function renderCard(doc, block, isWarning) {
+  const expired = isExpiredConstraint(block);
+  const classes = ["card", `type-${block.type}`];
+  if (expired) classes.push("expired");
+  if (isWarning) classes.push("warning");
+  const card = el(doc, "article", classes.join(" "));
+
+  const head = el(doc, "header", "card-head");
+  head.append(el(doc, "span", `glyph${expired ? " glyph-warn" : ""}`, glyphFor(block.type, block.status)));
+  head.append(el(doc, "strong", "card-title", block.title));
+  head.append(badge(doc, "type", block.type));
+  if (expired) {
+    head.append(badge(doc, "loud", `EXPIRED ${block.expired_on ?? "(date unknown)"}`));
+  } else if (block.status !== undefined) {
+    head.append(badge(doc, `status status-${block.status}`, block.status));
+  }
+  if (block.happened_on !== undefined) head.append(badge(doc, "date", block.happened_on));
+  if (block.type !== "question" && block.confidence !== undefined) {
+    head.append(badge(doc, `conf conf-${block.confidence}`, block.confidence));
+  }
+  card.append(head);
+
+  // Display verbatim: the mandatory hedge prefix is already in the data.
+  if (block.renderedRationale !== "") {
+    card.append(el(doc, "p", `rationale${block.hedged ? " hedged" : ""}`, block.renderedRationale));
+  }
+
+  for (const [key, label] of EDGE_LABELS) {
+    const edges = block.edges[key];
+    if (edges.length === 0) continue;
+    const row = el(doc, "div", "edges");
+    row.append(el(doc, "span", "edge-label", label));
+    const list = el(doc, "ul", "edge-list");
+    for (const edge of edges) {
+      const suffix = edge.type === undefined ? "" : ` (${edge.type}${edge.status === undefined ? "" : ` — ${edge.status}`})`;
+      list.append(el(doc, "li", "edge", `${edge.title}${suffix}`));
+    }
+    row.append(list);
+    card.append(row);
+  }
+
+  for (const decision of block.downstream) {
+    card.append(el(doc, "p", "scar", `→ downstream decision "${decision.title}" may now be scar tissue.`));
+  }
+
+  if (block.citations.length > 0) {
+    const list = el(doc, "ul", "citations");
+    for (const citation of block.citations) {
+      const item = el(doc, "li");
+      const link = el(doc, "a", "citation", citation.label);
+      link.href = citation.url;
+      link.target = "_blank";
+      link.rel = "noreferrer";
+      item.append(link);
+      list.append(item);
+    }
+    card.append(list);
+  }
+  return card;
+}
+
+/** Render one story payload into a detached element the caller mounts. */
+export function renderStoryPanel(doc, story) {
+  const root = el(doc, "section", "story");
+  root.append(el(doc, "h2", "story-target", story.span ?? formatTarget(story.target)));
+  if (story.hits.length === 0) {
+    root.append(el(doc, "p", "story-empty", `No concepts anchor ${formatTarget(story.target)}.`));
+  }
+  // Warnings first, matching the VS Code hover/webview order — both surfaces
+  // must tell the same story, and expired constraints stay loud.
+  for (const warning of story.warnings) root.append(renderCard(doc, warning, true));
+  for (const hit of story.hits) root.append(renderCard(doc, hit, false));
+  if (story.hits.length === 0 && story.nearby.length > 0) {
+    root.append(el(doc, "h3", "nearby-head", "Anchored concepts nearby (nearest first)"));
+    const list = el(doc, "ul", "nearby");
+    for (const near of story.nearby) {
+      const anchor = near.anchor.lines === undefined ? near.anchor.path : `${near.anchor.path}:${near.anchor.lines}`;
+      list.append(el(doc, "li", "nearby-item", `${glyphFor(near.type, near.status)} ${near.title} — ${near.type} · ${anchor}`));
+    }
+    root.append(list);
+  }
+  return root;
+}

package/ui/style.css

@@ -0,0 +1,229 @@
+/* `why serve` UI. One sheet, no imports, no external references — the
+ * self-containment test forbids any http(s):// in built assets. Confidence
+ * colors and the scar-tissue/question treatments implement the status →
+ * treatment table in docs/ui-contract.md. */
+
+:root {
+  --bg: #14181f;
+  --panel: #1b212b;
+  --line: #2a3340;
+  --fg: #dde3ec;
+  --dim: #8b95a5;
+  --accent: #5b9cf5;
+  --red: #ff6b6b;
+  --yellow: #e2a336;
+  --ok: #57b47a;
+  --question: #b57edc;
+  --conf-recorded: #57b47a;
+  --conf-corroborated: #7fc98f;
+  --conf-inferred: #e2a336;
+  --conf-speculative: #d0743c;
+  --conf-none: #d0743c;
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font: 14px/1.5 system-ui, sans-serif;
+}
+
+.error { color: var(--red); padding: 0.5rem 1rem; }
+.hint { color: var(--dim); padding: 0.5rem 1rem; }
+
+/* --- Header ----------------------------------------------------------- */
+
+.topbar {
+  display: flex;
+  align-items: center;
+  gap: 1.25rem;
+  padding: 0.5rem 1rem;
+  background: var(--panel);
+  border-bottom: 1px solid var(--line);
+  position: sticky;
+  top: 0;
+  z-index: 2;
+}
+
+.brand { font-weight: 700; font-size: 1.1rem; color: var(--accent); }
+
+nav .tab {
+  color: var(--dim);
+  text-decoration: none;
+  padding: 0.25rem 0.6rem;
+  border-radius: 4px;
+}
+nav .tab.active, nav .tab:hover { color: var(--fg); background: var(--line); }
+
+.chips { margin-left: auto; display: flex; gap: 0.5rem; }
+.chip {
+  text-decoration: none;
+  font-size: 0.8rem;
+  padding: 0.15rem 0.6rem;
+  border-radius: 999px;
+  border: 1px solid var(--line);
+  color: var(--dim);
+}
+.chip-red { color: var(--red); border-color: var(--red); }
+.chip-yellow { color: var(--yellow); border-color: var(--yellow); }
+.chip-ok { color: var(--ok); }
+
+/* --- Layout ----------------------------------------------------------- */
+
+.layout {
+  display: grid;
+  grid-template-columns: minmax(180px, 240px) 1fr minmax(280px, 380px);
+  gap: 0;
+  min-height: calc(100vh - 3rem);
+}
+
+.sidebar {
+  border-right: 1px solid var(--line);
+  padding: 0.75rem 0.5rem;
+  overflow: auto;
+  max-height: calc(100vh - 3rem);
+  position: sticky;
+  top: 3rem;
+}
+
+.story-panel {
+  border-left: 1px solid var(--line);
+  padding: 0.75rem;
+  overflow: auto;
+  max-height: calc(100vh - 3rem);
+  position: sticky;
+  top: 3rem;
+}
+
+/* --- File tree ---------------------------------------------------------- */
+
+.tree { list-style: none; margin: 0; padding-left: 0.9rem; }
+.tree summary.dir { cursor: pointer; color: var(--dim); }
+.tree a.file { color: var(--fg); text-decoration: none; display: inline-block; padding: 0.05rem 0.25rem; }
+.tree a.file:hover { background: var(--line); border-radius: 3px; }
+.covered-dot { color: var(--accent); font-size: 0.6rem; margin-left: 0.35rem; vertical-align: middle; }
+
+/* --- File view (blame gutter) ------------------------------------------- */
+
+.file-path { font-size: 1rem; padding: 0.5rem 1rem 0; margin: 0; }
+
+table.code {
+  border-collapse: collapse;
+  width: 100%;
+  font: 12px/1.45 ui-monospace, monospace;
+  margin-top: 0.5rem;
+}
+table.code td { padding: 0 0.5rem; white-space: pre; vertical-align: top; }
+table.code tr.group-start td { border-top: 1px solid var(--line); }
+table.code tr:hover td { background: #222a36; }
+table.code tr.covered { cursor: pointer; }
+
+td.num { color: var(--dim); text-align: right; user-select: none; width: 3.5rem; }
+td.git { color: var(--dim); width: 12rem; max-width: 12rem; overflow: hidden; text-overflow: ellipsis; }
+td.text { width: 100%; }
+
+/* Syntax highlighting (ui/highlight.js) — best-effort token classes over the
+ * code text; purely presentational, layered on top of the blame payload. */
+td.text .tok-kw { color: #c678dd; }
+td.text .tok-str { color: #98c379; }
+td.text .tok-com { color: var(--dim); font-style: italic; }
+td.text .tok-num { color: #d19a66; }
+td.text .tok-type { color: #e5c07b; }
+td.text .tok-fn { color: #61afef; }
+
+/* The why gutter stripe: color by confidence; scar tissue and questions
+ * get their own loud treatments. */
+td.why {
+  width: 1.4rem;
+  min-width: 1.4rem;
+  text-align: center;
+  border-left: 3px solid transparent;
+  color: var(--dim);
+  user-select: none;
+}
+td.why.why-conf-recorded { border-left-color: var(--conf-recorded); color: var(--conf-recorded); }
+td.why.why-conf-corroborated { border-left-color: var(--conf-corroborated); color: var(--conf-corroborated); }
+td.why.why-conf-inferred { border-left-color: var(--conf-inferred); color: var(--conf-inferred); }
+td.why.why-conf-speculative { border-left-color: var(--conf-speculative); color: var(--conf-speculative); }
+td.why.why-conf-none { border-left-color: var(--conf-none); color: var(--conf-none); }
+td.why.why-question { border-left-color: var(--question); color: var(--question); border-left-style: dotted; }
+td.why.why-expired {
+  border-left-color: var(--red);
+  color: var(--red);
+  background: rgba(255, 107, 107, 0.12);
+}
+
+/* --- Story panel ---------------------------------------------------------- */
+
+.story-target { font-size: 0.95rem; margin: 0.25rem 0 0.75rem; color: var(--dim); }
+
+.card {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  padding: 0.6rem 0.75rem;
+  margin-bottom: 0.75rem;
+}
+.card.expired { border-color: var(--red); box-shadow: 0 0 0 1px var(--red); }
+
+.card-head { display: flex; flex-wrap: wrap; gap: 0.4rem; align-items: baseline; }
+.card-title { margin-right: 0.25rem; }
+.glyph-warn { color: var(--red); }
+
+.badge {
+  font-size: 0.7rem;
+  padding: 0.05rem 0.45rem;
+  border-radius: 999px;
+  border: 1px solid var(--line);
+  color: var(--dim);
+}
+.badge.loud {
+  color: #fff;
+  background: var(--red);
+  border-color: var(--red);
+  font-weight: 700;
+}
+.badge.conf-recorded { color: var(--conf-recorded); border-color: var(--conf-recorded); }
+.badge.conf-corroborated { color: var(--conf-corroborated); border-color: var(--conf-corroborated); }
+.badge.conf-inferred { color: var(--conf-inferred); border-color: var(--conf-inferred); }
+.badge.conf-speculative { color: var(--conf-speculative); border-color: var(--conf-speculative); }
+
+.rationale { margin: 0.5rem 0; }
+.rationale.hedged { font-style: italic; }
+
+.edges { display: flex; gap: 0.5rem; font-size: 0.85rem; }
+.edge-label { color: var(--dim); min-width: 7.5rem; }
+.edge-list { list-style: none; margin: 0; padding: 0; }
+
+.scar {
+  color: var(--red);
+  font-weight: 600;
+  margin: 0.5rem 0;
+}
+
+.citations { list-style: none; margin: 0.5rem 0 0; padding: 0; font-size: 0.85rem; }
+.citations a { color: var(--accent); }
+
+.nearby { list-style: none; padding: 0; }
+.nearby-item { color: var(--dim); padding: 0.15rem 0; }
+
+/* --- Graph -------------------------------------------------------------- */
+
+.graph-view { padding: 0.75rem 1rem; }
+.legend { display: flex; gap: 1rem; margin-bottom: 0.5rem; color: var(--dim); }
+.legend-dot { margin-right: 0.3rem; }
+.graph-view canvas { background: var(--panel); border: 1px solid var(--line); border-radius: 6px; }
+
+/* --- Doctor ---------------------------------------------------------------- */
+
+.doctor-view { padding: 0.75rem 1.25rem; max-width: 64rem; }
+.doctor-headline.ok { color: var(--ok); }
+.doctor-headline.red { color: var(--red); }
+.doctor-title { margin: 0.9rem 0 0.25rem; font-size: 0.95rem; }
+.doctor-title.tone-ok { color: var(--ok); }
+.doctor-title.tone-red { color: var(--red); }
+.doctor-title.tone-yellow { color: var(--yellow); }
+.doctor-items { list-style: none; padding-left: 0.5rem; margin: 0; }
+.doctor-item { font: 12px/1.6 ui-monospace, monospace; color: var(--fg); }