@inerrata-corporation/errata 2.0.21 → 2.0.22-dev.4020

package/resources/claude-mods/errata-minimap/hooks/graph.ts

@@ -0,0 +1,349 @@
+import type { ChainFacts, MapGraph, MapNode, Scope } from '../types'
+import type { JudgmentKind } from './minimap'
+import { displayName, shortName } from './minimap'
+
+/**
+ * The graph view (`/errata-view graph`): the original minimap — the burst as a
+ * radial graph, the seed at the centre, one ring per hop, braille edges
+ * coloured by how far each prior travelled. The library (bookcase.ts) is the
+ * default; this stays for people who read structure better than shelves.
+ */
+
+export type RadialNode = MapNode & { x: number; y: number }
+
+export type RadialGraph = {
+  nodes: RadialNode[]
+  /** Index pairs into `nodes`; `true` = an edge of the walk, `false` = a cross edge. */
+  edges: [number, number, boolean][]
+}
+
+/**
+ * Radial layout of one catalogued burst: each node in its parent's angular
+ * sector, one ring per hop, and within a ring a higher score sits closer in.
+ * Positions are in the unit square. `layoutBurst` already lists every node
+ * right after its parent, so one pass places them all.
+ */
+export function layoutRadial(map: MapGraph, cross: ReadonlyArray<readonly [string, string]> = []): RadialGraph {
+  const maxHops = Math.max(1, ...map.nodes.map(n => n.hops))
+  const scores = map.nodes.filter(n => !n.isSeed).map(n => n.score)
+  const [lo, hi] = [Math.min(...scores), Math.max(...scores)]
+  const norm = (s: number) => (hi > lo ? (s - lo) / (hi - lo) : 1)
+
+  const kids = new Map<number, number[]>()
+  map.nodes.forEach((n, i) => {
+    if (n.isSeed) return
+    const p = n.parent >= 0 && n.parent < map.nodes.length ? n.parent : 0
+    kids.set(p, [...(kids.get(p) ?? []), i])
+  })
+  const sector = new Map<number, [number, number]>([[0, [0, Math.PI * 2]]])
+  const nodes: RadialNode[] = map.nodes.map(n => ({ ...n, x: 0.5, y: 0.5 }))
+  const edges: [number, number, boolean][] = []
+  map.nodes.forEach((_, p) => {
+    const children = kids.get(p) ?? []
+    const [a0, a1] = sector.get(p) ?? [0, Math.PI * 2]
+    const span = (a1 - a0) / Math.max(1, children.length)
+    children.forEach((i, k) => {
+      const n = map.nodes[i]!
+      const angle = a0 + span * (k + 0.5) - Math.PI / 2
+      const r = 0.48 * (n.hops / maxHops) * (0.72 + 0.28 * (1 - norm(n.score)))
+      nodes[i] = { ...n, x: 0.5 + r * Math.cos(angle), y: 0.5 + r * Math.sin(angle) }
+      sector.set(i, [a0 + span * k, a0 + span * (k + 1)])
+      edges.push([p, i, true])
+    })
+  })
+
+  const index = new Map(map.nodes.map((n, i) => [n.id, i]))
+  const seen = new Set(edges.map(([a, b]) => key(a, b)))
+  for (const [s, t] of cross) {
+    const a = index.get(s), b = index.get(t)
+    if (a === undefined || b === undefined || a === b || seen.has(key(a, b))) continue
+    seen.add(key(a, b))
+    edges.push([a, b, false])
+  }
+  return { nodes, edges }
+}
+
+function key(a: number, b: number): string {
+  return a < b ? `${a},${b}` : `${b},${a}`
+}
+
+/**
+ * The real edges among a burst's nodes, from the `errata_neighbors` answers the
+ * library already fetched to complete its chains — the graph view's cross
+ * edges cost no call of their own.
+ */
+export function crossEdges(map: MapGraph, facts: Readonly<Record<string, ChainFacts | null>>): [string, string][] {
+  const ids = new Set(map.nodes.map(n => n.id))
+  const out: [string, string][] = []
+  for (const f of Object.values(facts)) {
+    if (!f || !ids.has(f.id)) continue
+    for (const far of [...f.causes, ...f.fixes, ...f.problems, ...f.patterns]) {
+      if (ids.has(far.id) && far.id !== f.id) out.push([f.id, far.id])
+    }
+  }
+  return out
+}
+
+const DEFAULT = 0x01000000
+// Bright enough to read on a dark terminal: the first cut's #3a3f4b vanished there.
+const EDGE_WALK = 0x8a96b4
+const EDGE_CROSS = 0x5c6680
+
+/**
+ * An edge takes the colour of the membrane its far end lives in, so the map
+ * reads "how far did this prior travel to reach me": machine-only, the
+ * project / team / org membranes, or the public Errata Network.
+ */
+export const SCOPE_COLOR: Record<Scope, number> = {
+  machine: 0x8a96b4, // slate — never left this machine
+  project: 0x5fa8ff, // blue
+  team: 0x3fc5b0, // teal
+  org: 0xf0b34a, // amber
+  public: 0xd27cf0, // magenta — The Errata Network
+}
+export const SCOPE_ORDER: Scope[] = ['machine', 'project', 'team', 'org', 'public']
+
+/** The tier an edge is coloured by: its non-seed end, the farther-travelled when both say. */
+export function edgeScope(a: MapNode, b: MapNode): Scope | undefined {
+  const ends = [a, b].filter(v => !v.isSeed && v.scope).map(v => v.scope!)
+  return ends.sort((p, q) => SCOPE_ORDER.indexOf(q) - SCOPE_ORDER.indexOf(p))[0]
+}
+
+function dim(color: number): number {
+  return (((color >> 16) & 255) * 0.6) << 16 | (((color >> 8) & 255) * 0.6) << 8 | ((color & 255) * 0.6)
+}
+const NAME = 0x9aa3b5
+
+export const LABEL_COLOR: Record<string, number> = {
+  Problem: 0xe06c75,
+  Vulnerability: 0xff5f87,
+  Solution: 0x98c379,
+  RootCause: 0xd19a66,
+  Pattern: 0xc678dd,
+  AntiPattern: 0xbe5046,
+  Technique: 0x56b6c2,
+  Constraint: 0xe5c07b,
+  File: 0x61afef,
+  Function: 0x7fb8d8,
+  Method: 0x7fb8d8,
+  Module: 0xa9b1c4,
+  Package: 0xa9b1c4,
+  Const: 0x8fbfa0,
+  Variable: 0x8fbfa0,
+  Interface: 0xb4a7d6,
+  Class: 0xb4a7d6,
+  Type: 0xb4a7d6,
+  Comment: 0x7c8494,
+}
+
+export const LABEL_GLYPH: Record<string, number> = {
+  Problem: 0x25c6, // ◆
+  Vulnerability: 0x25c6,
+  Solution: 0x25cf, // ●
+  RootCause: 0x25b2, // ▲
+  Pattern: 0x2726, // ✦
+  AntiPattern: 0x2726,
+  Technique: 0x25c7, // ◇
+  Constraint: 0x25a0, // ■
+  File: 0x25aa, // ▪
+  // Code structure a burst walks through (CALLS / IMPORTS / DEFINES / CONTAINS).
+  Function: 0x0192, // ƒ
+  Method: 0x0192,
+  Module: 0x229e, // ⊞
+  Package: 0x229e,
+  Const: 0x2261, // ≡
+  Variable: 0x2261,
+  Interface: 0x25a1, // □
+  Class: 0x25a1,
+  Type: 0x25a1,
+  Comment: 0x00b6, // ¶
+}
+
+export function glyphOf(label: string): number {
+  return LABEL_GLYPH[label] ?? 0x2022 // •
+}
+
+export function colorOf(label: string): number {
+  return LABEL_COLOR[label] ?? 0x6b7280
+}
+
+/** Verdict colours on the graph's own (One Dark) palette. */
+export const VERDICT_COLOR: Record<JudgmentKind, number> = { cite: 0x56b6c2, confirm: 0x98c379, fix: 0x98c379, refute: 0xe06c75 }
+
+/** What "transparent" fades toward: the background of the terminal theme. */
+export const DARK_BG = 0x1a1b1e
+export const LIGHT_BG = 0xf7f7f5
+
+/** Fraction of a colour kept at the weakest signal: faint, never gone. */
+const FLOOR = 0.28
+
+/** Signal strength per node, 0..1 over this burst's score range; the seed is full strength. */
+export function strengths(graph: RadialGraph): number[] {
+  const scores = graph.nodes.filter(v => !v.isSeed).map(v => v.score)
+  const [lo, hi] = [Math.min(...scores), Math.max(...scores)]
+  return graph.nodes.map(v => (v.isSeed ? 1 : hi > lo ? (v.score - lo) / (hi - lo) : 1))
+}
+
+/** Blends `color` toward `bg` as signal weakens: strength 1 keeps it, 0 keeps FLOOR of it. */
+export function fade(color: number, strength: number, bg: number): number {
+  const keep = FLOOR + (1 - FLOOR) * Math.max(0, Math.min(1, strength))
+  const ch = (c: number, shift: number) => Math.round(((c >> shift) & 255) * keep + ((bg >> shift) & 255) * (1 - keep))
+  return (ch(color, 16) << 16) | (ch(color, 8) << 8) | ch(color, 0)
+}
+
+/** How far the reveal has run: routes grow out ring by ring (`grow`), then names type out (`type`). Both 0..1. */
+export type Frame = { grow: number; type: number }
+
+export type RasterOptions = {
+  frame?: Frame
+  /** The theme background weak signal fades toward. */
+  bg?: number
+  /** A node the agent is bursting off: drawn inverted, its route to the seed lit. */
+  highlight?: string
+  isPulseOn?: boolean
+  /** Priors the agent just judged: each pulses in its verdict's colour. */
+  marks?: Record<string, JudgmentKind>
+  isMarkOn?: boolean
+}
+
+const HIGHLIGHT = 0xffd75f
+
+/**
+ * The graph as Raster cells (`[codePoint, fg, bg]` u32 triplets, row-major,
+ * base64) at one frame of the reveal. Positions and label slots are planned on
+ * the finished map, so an animated frame only ever draws a prefix of it —
+ * nothing jumps as it fills in.
+ */
+export function rasterizeGraph(graph: RadialGraph, columns: number, rows: number, options: RasterOptions = {}): string {
+  const { frame = { grow: 1, type: 1 }, bg = DARK_BG, highlight, isPulseOn = true, marks = {}, isMarkOn = true } = options
+  const markColor = (id: string): number | undefined => {
+    const kind = marks[id]
+    return kind ? VERDICT_COLOR[kind] : undefined
+  }
+  const words = new Uint32Array(columns * rows * 3)
+  for (let i = 0; i < columns * rows; i++) words.set([0x20, DEFAULT, DEFAULT], i * 3)
+  const occupied = new Uint8Array(columns * rows)
+  const cx = (x: number) => 1 + Math.round(x * Math.max(0, columns - 3))
+  const cy = (y: number) => Math.round(y * Math.max(0, rows - 1))
+  const put = (x: number, y: number, ch: number, fg: number, weight: number, cellBg = DEFAULT) => {
+    if (x < 0 || y < 0 || x >= columns || y >= rows) return false
+    const i = y * columns + x
+    if (occupied[i]! > weight) return false
+    occupied[i] = weight
+    words.set([ch, fg, cellBg], i * 3)
+    return true
+  }
+
+  const pos: [number, number][] = graph.nodes.map(v => [cx(v.x), cy(v.y)])
+  // Two nodes in one cell: walk the later one outward to the nearest free cell.
+  const taken = new Set<number>()
+  graph.nodes.forEach((_, i) => {
+    let [x, y] = pos[i]!
+    for (let r = 0; taken.has(y * columns + x) && r < 6; r++) {
+      const ring = [[1, 0], [-1, 0], [0, 1], [0, -1], [1, 1], [-1, -1], [1, -1], [-1, 1]].map(([dx, dy]) => [x + dx! * (r + 1), y + dy! * (r + 1)] as const)
+      const free = ring.find(([a, b]) => a >= 0 && b >= 0 && a < columns && b < rows && !taken.has(b * columns + a))
+      if (free) [x, y] = free
+    }
+    taken.add(y * columns + x)
+    pos[i] = [x, y]
+  })
+
+  const strength = strengths(graph)
+  // The highlighted node and the walk edges from it back to the seed.
+  const lit = graph.nodes.findIndex(v => v.id === highlight)
+  const route = new Set<number>()
+  for (let at = lit, guard = 0; at > 0 && guard < 16; guard++) {
+    const k = graph.edges.findIndex(([, c, isWalk]) => isWalk && c === at)
+    if (k < 0) break
+    route.add(k)
+    at = graph.edges[k]![0]
+  }
+  const depth = Math.max(1, ...graph.nodes.map(v => v.hops))
+  // How much of the walk edge INTO node i has grown: ring h fills during the h-th slice of `grow`.
+  const reach = (i: number) => (graph.nodes[i]!.isSeed ? 1 : Math.max(0, Math.min(1, frame.grow * depth - (graph.nodes[i]!.hops - 1))))
+
+  // Label slots, planned on the finished map, best first: nodes and earlier labels block, edges do not.
+  const blocked = new Set(pos.map(([x, y]) => y * columns + x))
+  const labels: { i: number; at: number; text: string }[] = []
+  const ranked = graph.nodes.map((v, i) => [v, i] as const).filter(([v]) => !v.isSeed).sort((p, q) => q[0].score - p[0].score)
+  for (const [v, i] of ranked) {
+    const [x, y] = pos[i]!
+    const free = (from: number, len: number) => {
+      if (from < 0 || from + len > columns) return false
+      for (let k = 0; k < len; k++) if (blocked.has(y * columns + from + k)) return false
+      return true
+    }
+    const fits = (len: number) => (free(x + 2, len) ? x + 2 : free(x - 1 - len, len) ? x - 1 - len : -1)
+    let text = shortName(displayName(v.label, v.name), 18)
+    while (text.length >= 4 && fits(text.length) < 0) text = shortName(text.replace(/~$/, ''), text.length - 2)
+    const at = text.length >= 4 ? fits(text.length) : -1
+    if (at < 0) continue
+    for (let k = 0; k < text.length; k++) blocked.add(y * columns + at + k)
+    labels.push({ i, at, text })
+  }
+
+  // Edges go down at braille resolution — 2×4 dots per cell — so a line of any
+  // slope is one continuous stroke. Per-cell box glyphs could not do that: a
+  // cell is ~2× taller than wide, so a visual diagonal steps two cells sideways
+  // per row and adjacent ╱╱ never join.
+  const dots = new Uint8Array(columns * rows)
+  const tone = new Uint8Array(columns * rows) // 2 = a walk edge crosses the cell, 1 = cross edges only
+  const hue = new Uint32Array(columns * rows) // the colour of the strongest edge through the cell
+  const plot = (px: number, py: number, weight: number, color: number) => {
+    const x = px >> 1, y = py >> 2
+    if (x < 0 || y < 0 || x >= columns || y >= rows) return
+    const i = y * columns + x
+    dots[i] = dots[i]! | BRAILLE_BIT[(py & 3) * 2 + (px & 1)]!
+    if (weight >= tone[i]!) hue[i] = color
+    tone[i] = Math.max(tone[i]!, weight)
+  }
+  for (const [k, [a, b, isWalk]] of graph.edges.entries()) {
+    // A walk edge grows parent → child; a cross edge fades in while names type.
+    const progress = isWalk ? reach(b) : frame.type
+    if (progress <= 0) continue
+    const weaker = graph.nodes[a]!.isSeed ? b : graph.nodes[b]!.isSeed ? a : strength[a]! < strength[b]! ? a : b
+    const scope = edgeScope(graph.nodes[a]!, graph.nodes[b]!)
+    const base = scope ? SCOPE_COLOR[scope] : EDGE_WALK
+    const color = route.has(k) ? HIGHLIGHT : fade(isWalk ? base : scope ? dim(base) : EDGE_CROSS, strength[weaker]!, bg)
+    let x0 = pos[a]![0] * 2 + 1, y0 = pos[a]![1] * 4 + 2
+    const x1 = pos[b]![0] * 2 + 1, y1 = pos[b]![1] * 4 + 2
+    const dx = Math.abs(x1 - x0), dy = -Math.abs(y1 - y0)
+    const sx = x0 < x1 ? 1 : -1, sy = y0 < y1 ? 1 : -1
+    const limit = Math.round(progress * Math.max(dx, -dy))
+    let err = dx + dy
+    // Cross edges are dashed so a walk edge reads as the path taken.
+    for (let step = 0; step <= limit; step++) {
+      if (isWalk || step % 4 < 2) plot(x0, y0, route.has(k) ? 4 : isWalk ? 2 : 1, color)
+      if (x0 === x1 && y0 === y1) break
+      const e2 = 2 * err
+      if (e2 >= dy) { err += dy; x0 += sx }
+      if (e2 <= dx) { err += dx; y0 += sy }
+    }
+  }
+  for (let i = 0; i < columns * rows; i++) {
+    if (dots[i]) put(i % columns, Math.floor(i / columns), 0x2800 + dots[i]!, hue[i]!, tone[i]!)
+  }
+
+  graph.nodes.forEach((v, i) => {
+    if (reach(i) < 1) return
+    const [x, y] = pos[i]!
+    if (v.isSeed) put(x, y, 0x25c9, 0xffd75f, 9) // ◉
+    else if (i === lit) put(x, y, glyphOf(v.label), isPulseOn ? bg : HIGHLIGHT, 10, isPulseOn ? HIGHLIGHT : DEFAULT)
+    else if (markColor(v.id) !== undefined) {
+      const c = markColor(v.id)!
+      put(x, y, glyphOf(v.label), isMarkOn ? bg : c, 10, isMarkOn ? c : DEFAULT)
+    }
+    else put(x, y, glyphOf(v.label), fade(colorOf(v.label), strength[i]!, bg), 8)
+  })
+
+  for (const { i, at, text } of labels) {
+    if (reach(i) < 1) continue
+    const shown = Math.floor(text.length * frame.type)
+    const color = i === lit ? HIGHLIGHT : markColor(graph.nodes[i]!.id) ?? fade(NAME, strength[i]!, bg)
+    for (let k = 0; k < shown; k++) put(at + k, pos[i]![1], text.codePointAt(k)!, color, 3)
+  }
+  return new Uint8Array(words.buffer).toBase64()
+}
+
+/** Unicode braille dot bits, indexed by `row * 2 + column` within the 2×4 cell (U+2800 + bits). */
+const BRAILLE_BIT = [0x01, 0x08, 0x02, 0x10, 0x04, 0x20, 0x40, 0x80]