paseo-plugin-chat-view 0.0.0-stage → 0.1.0

package/shared/mermaid/flowchart.ts

@@ -0,0 +1,271 @@
+/**
+ * A parser for the Mermaid flowchart subset that actually shows up in agent
+ * output and documentation. Pure and dependency-free: Mermaid itself needs a DOM
+ * and cannot run in a Paseo client bundle, and the transformer must stay
+ * synchronous, so the grammar is walked by hand.
+ *
+ * Anything it fails to recognise is reported rather than guessed at, and the
+ * renderer falls back to showing the source.
+ */
+
+export type Direction = "TD" | "TB" | "BT" | "LR" | "RL";
+export type NodeShape =
+  | "rect"
+  | "round"
+  | "stadium"
+  | "subroutine"
+  | "diamond"
+  | "circle"
+  | "asymmetric";
+export type EdgeStyle = "solid" | "dotted" | "thick";
+
+export interface FlowNode {
+  id: string;
+  label: string;
+  shape: NodeShape;
+}
+
+export interface FlowEdge {
+  from: string;
+  to: string;
+  label: string | null;
+  style: EdgeStyle;
+  arrow: boolean;
+}
+
+/** A `subgraph` block: the box the renderer draws around its member nodes. */
+export interface FlowSubgraph {
+  /** Mermaid's id when given, synthesized otherwise; edges never target it. */
+  id: string;
+  title: string;
+  members: string[];
+}
+
+export interface Flowchart {
+  direction: Direction;
+  nodes: FlowNode[];
+  edges: FlowEdge[];
+  /** Top-level `subgraph` blocks only; a nested one folds into its ancestor. */
+  subgraphs: FlowSubgraph[];
+  /** Lines the parser chose not to interpret, so the UI can say so. */
+  skipped: string[];
+}
+
+const HEADER = /^\s*(?:flowchart|graph)(?:\s+(TD|TB|BT|LR|RL))?\s*$/i;
+
+/** Longest first: `-.->` must win over `-.-`. */
+const OPERATORS: { token: string; style: EdgeStyle; arrow: boolean }[] = [
+  { token: "-.->", style: "dotted", arrow: true },
+  { token: "==>", style: "thick", arrow: true },
+  { token: "-->", style: "solid", arrow: true },
+  { token: "-.-", style: "dotted", arrow: false },
+  { token: "===", style: "thick", arrow: false },
+  { token: "---", style: "solid", arrow: false },
+];
+
+const OPENERS: { open: string; close: string; shape: NodeShape }[] = [
+  { open: "([", close: "])", shape: "stadium" },
+  { open: "[[", close: "]]", shape: "subroutine" },
+  { open: "((", close: "))", shape: "circle" },
+  { open: "{{", close: "}}", shape: "diamond" },
+  { open: "[", close: "]", shape: "rect" },
+  { open: "(", close: ")", shape: "round" },
+  { open: "{", close: "}", shape: "diamond" },
+  { open: ">", close: "]", shape: "asymmetric" },
+];
+
+/**
+ * Mermaid writes an edge label two ways. Rewriting `A -- yes --> B` into
+ * `A -->|yes| B` lets the splitter handle one form.
+ */
+export function normalizeEdgeLabels(line: string): string {
+  return line
+    .replace(/--\s+([^->|]+?)\s+-->/g, "-->|$1|")
+    .replace(/-\.\s+([^.|>]+?)\s+\.->/g, "-.->|$1|")
+    .replace(/==\s+([^=|>]+?)\s+==>/g, "==>|$1|");
+}
+
+function stripQuotes(value: string): string {
+  const trimmed = value.trim();
+  const quoted = /^"(.*)"$/s.exec(trimmed) ?? /^'(.*)'$/s.exec(trimmed);
+  return (quoted ? quoted[1] : trimmed).replace(/<br\s*\/?>/gi, "\n").trim();
+}
+
+/** Reads `id`, `id[Label]`, `id{Decision}`, `id((Circle))` and friends. */
+export function parseNodeExpression(raw: string): FlowNode | null {
+  const text = raw.trim();
+  if (text.length === 0) return null;
+
+  for (const { open, close, shape } of OPENERS) {
+    const start = text.indexOf(open);
+    if (start <= 0) continue;
+    if (!text.endsWith(close)) continue;
+    const id = text.slice(0, start).trim();
+    if (!/^[\w.-]+$/.test(id)) continue;
+    const label = stripQuotes(text.slice(start + open.length, text.length - close.length));
+    return { id, label: label.length > 0 ? label : id, shape };
+  }
+
+  if (!/^[\w.-]+$/.test(text)) return null;
+  return { id: text, label: text, shape: "rect" };
+}
+
+interface Split {
+  parts: string[];
+  operators: { style: EdgeStyle; arrow: boolean; label: string | null }[];
+}
+
+/** Splits `A -->|yes| B --> C` into its nodes and the operators between them. */
+export function splitChain(line: string): Split | null {
+  const parts: string[] = [];
+  const operators: Split["operators"] = [];
+  let rest = line;
+
+  for (;;) {
+    let best: { index: number; op: (typeof OPERATORS)[number] } | null = null;
+    for (const op of OPERATORS) {
+      const index = rest.indexOf(op.token);
+      if (index < 0) continue;
+      if (
+        !best ||
+        index < best.index ||
+        (index === best.index && op.token.length > best.op.token.length)
+      ) {
+        best = { index, op };
+      }
+    }
+    if (!best) break;
+
+    parts.push(rest.slice(0, best.index));
+    let after = rest.slice(best.index + best.op.token.length);
+
+    let label: string | null = null;
+    const labelled = /^\s*\|([^|]*)\|/.exec(after);
+    if (labelled) {
+      label = stripQuotes(labelled[1]);
+      after = after.slice(labelled[0].length);
+    }
+
+    operators.push({ style: best.op.style, arrow: best.op.arrow, label });
+    rest = after;
+  }
+
+  if (operators.length === 0) return null;
+  parts.push(rest);
+  return { parts, operators };
+}
+
+export function parseFlowchart(source: string): Flowchart | null {
+  const lines = source.split("\n");
+  let direction: Direction | null = null;
+  const nodes = new Map<string, FlowNode>();
+  const edges: FlowEdge[] = [];
+  const subgraphs: FlowSubgraph[] = [];
+  const skipped: string[] = [];
+  /** Innermost-first stack of open blocks; only the bottom one is a drawn box. */
+  const open: FlowSubgraph[] = [];
+  /** Nested blocks open inside a drawn box; their ends must not pop the box. */
+  let nested = 0;
+
+  const remember = (node: FlowNode) => {
+    const existing = nodes.get(node.id);
+    // A later definition carrying a real label wins over a bare id mention.
+    if (!existing || (existing.label === existing.id && node.label !== node.id)) {
+      nodes.set(node.id, node);
+    }
+    if (open.length > 0) {
+      const box = open[0] as FlowSubgraph;
+      if (!box.members.includes(node.id)) box.members.push(node.id);
+    }
+  };
+
+  for (const original of lines) {
+    const line = original.replace(/%%.*$/, "").trim();
+    if (line.length === 0) continue;
+
+    const header = HEADER.exec(line);
+    if (header) {
+      direction = (header[1]?.toUpperCase() as Direction) ?? "TD";
+      continue;
+    }
+    if (direction === null) {
+      // Not a flowchart at all; let another parser have it.
+      return null;
+    }
+
+    if (/^subgraph\b/i.test(line)) {
+      // A nested block is not drawn as its own box: its members join the
+      // enclosing one, and the inner header is reported like any other
+      // uninterpreted line so nesting stays visible in the skipped list.
+      if (open.length > 0) {
+        nested += 1;
+        skipped.push(original.trim());
+      } else {
+        const box = parseSubgraphHeader(line, subgraphs.length);
+        if (box) {
+          subgraphs.push(box);
+          open.push(box);
+        } else skipped.push(original.trim());
+      }
+      continue;
+    }
+    if (/^end$/i.test(line)) {
+      if (nested > 0) nested -= 1;
+      else if (open.length > 0) open.pop();
+      else skipped.push(original.trim());
+      continue;
+    }
+    if (/^(?:style|classDef|class|click|linkStyle)\b/i.test(line)) {
+      skipped.push(original.trim());
+      continue;
+    }
+
+    const chain = splitChain(normalizeEdgeLabels(line));
+    if (!chain) {
+      const single = parseNodeExpression(line.replace(/;$/, ""));
+      if (single) remember(single);
+      else skipped.push(original.trim());
+      continue;
+    }
+
+    const parsed = chain.parts.map((part) => parseNodeExpression(part.replace(/;$/, "")));
+    if (parsed.some((node) => node === null)) {
+      skipped.push(original.trim());
+      continue;
+    }
+
+    for (const node of parsed) remember(node as FlowNode);
+    for (let index = 0; index < chain.operators.length; index += 1) {
+      const operator = chain.operators[index];
+      edges.push({
+        from: (parsed[index] as FlowNode).id,
+        to: (parsed[index + 1] as FlowNode).id,
+        label: operator.label,
+        style: operator.style,
+        arrow: operator.arrow,
+      });
+    }
+  }
+
+  if (direction === null) return null;
+  return { direction, nodes: [...nodes.values()], edges, subgraphs, skipped };
+}
+
+/**
+ * Reads the text after `subgraph`: `id["Title"]`, bare `id`, or a free-form
+ * (possibly quoted) title that gets a synthesized id because edges cannot
+ * reach a name with spaces anyway.
+ */
+function parseSubgraphHeader(line: string, index: number): FlowSubgraph | null {
+  const rest = line.replace(/^subgraph\b/i, "").trim();
+  if (rest.length === 0) return null;
+
+  const labelled = /^([\w.-]+)\s*[[(]\s*(.*?)\s*[\])]$/.exec(rest);
+  if (labelled) {
+    const id = labelled[1] as string;
+    const title = stripQuotes(labelled[2] as string);
+    return { id, title: title.length > 0 ? title : id, members: [] };
+  }
+  if (/^[\w.-]+$/.test(rest)) return { id: rest, title: rest, members: [] };
+  return { id: `subgraph-${index}`, title: stripQuotes(rest), members: [] };
+}

package/shared/mermaid/layout.test.ts

@@ -0,0 +1,305 @@
+import { describe, expect, it } from "vitest";
+import { parseFlowchart } from "./flowchart";
+import {
+  assignLayers,
+  fitScale,
+  layoutFlowchart,
+  layoutSequence,
+  measureNode,
+  overflowsAfterFit,
+} from "./layout";
+
+const chart = (source: string) => parseFlowchart(source)!;
+
+describe("measureNode", () => {
+  it("grows a node to fit its longest line", () => {
+    const narrow = measureNode({ id: "A", label: "A", shape: "rect" });
+    const wide = measureNode({ id: "B", label: "a much longer label", shape: "rect" });
+    expect(wide.width).toBeGreaterThan(narrow.width);
+  });
+
+  it("grows taller for a multi-line label", () => {
+    const one = measureNode({ id: "A", label: "one", shape: "rect" });
+    const two = measureNode({ id: "A", label: "one\ntwo", shape: "rect" });
+    expect(two.height).toBeGreaterThan(one.height);
+  });
+
+  it("keeps a circle square so the label fits inside it", () => {
+    const circle = measureNode({ id: "A", label: "hello", shape: "circle" });
+    expect(circle.width).toBe(circle.height);
+  });
+});
+
+describe("assignLayers", () => {
+  it("puts a chain on successive layers", () => {
+    const graph = chart("flowchart TD\n A --> B --> C");
+    const layers = assignLayers(graph.nodes, graph.edges);
+    expect([layers.get("A"), layers.get("B"), layers.get("C")]).toEqual([0, 1, 2]);
+  });
+
+  it("uses the longest path, not the first one found", () => {
+    // A -> C directly, and A -> B -> C. C belongs below B.
+    const graph = chart("flowchart TD\n A --> C\n A --> B\n B --> C");
+    const layers = assignLayers(graph.nodes, graph.edges);
+    expect(layers.get("C")).toBe(2);
+  });
+
+  it("terminates on a cycle instead of recursing forever", () => {
+    const graph = chart("flowchart TD\n A --> B\n B --> C\n C --> A");
+    const layers = assignLayers(graph.nodes, graph.edges);
+    expect(layers.size).toBe(3);
+    expect(Math.max(...layers.values())).toBeLessThan(3);
+  });
+
+  it("puts two independent roots on the same layer", () => {
+    const graph = chart("flowchart TD\n A --> C\n B --> C");
+    const layers = assignLayers(graph.nodes, graph.edges);
+    expect(layers.get("A")).toBe(layers.get("B"));
+  });
+});
+
+describe("layoutFlowchart", () => {
+  it("stacks layers downward for TD", () => {
+    const layout = layoutFlowchart(chart("flowchart TD\n A --> B"));
+    const [a, b] = ["A", "B"].map((id) => layout.nodes.find((node) => node.id === id)!);
+    expect(b.y).toBeGreaterThan(a.y);
+    expect(Math.abs(a.x - b.x)).toBeLessThan(1);
+  });
+
+  it("wraps a subgraph's members in one padded box with a title strip", () => {
+    const layout = layoutFlowchart(
+      chart("flowchart TD\n subgraph g[Group]\n  A\n  B\n end\n A --> B"),
+    );
+    const [box] = layout.subgraphs;
+    const members = layout.nodes.filter((node) => box.members.includes(node.id));
+    const left = Math.min(...members.map((node) => node.x));
+    const right = Math.max(...members.map((node) => node.x + node.width));
+    const top = Math.min(...members.map((node) => node.y));
+    const bottom = Math.max(...members.map((node) => node.y + node.height));
+    expect(box.title).toBe("Group");
+    expect(box.x).toBeLessThan(left);
+    expect(box.x + box.width).toBeGreaterThan(right);
+    expect(box.y + box.height).toBeGreaterThan(bottom);
+    // The title strip sits above the topmost member, not on top of it.
+    expect(box.y).toBeLessThan(top - 12);
+    // Nodes and edges stay in front: every node sits inside the canvas.
+    expect(Math.min(...layout.nodes.map((node) => node.x))).toBeGreaterThanOrEqual(0);
+    expect(Math.min(...layout.nodes.map((node) => node.y))).toBeGreaterThanOrEqual(0);
+  });
+
+  it("shifts everything when a box's padding crosses the origin", () => {
+    const layout = layoutFlowchart(chart("flowchart LR\n subgraph g[Group]\n  A\n end\n A --> B"));
+    expect(Math.min(...layout.nodes.map((node) => node.x))).toBeGreaterThanOrEqual(0);
+    expect(Math.min(...layout.nodes.map((node) => node.y))).toBeGreaterThanOrEqual(0);
+    expect(Math.min(...layout.subgraphs.map((box) => box.x))).toBeGreaterThanOrEqual(0);
+    // The canvas grows to hold the box instead of clipping it.
+    for (const box of layout.subgraphs) {
+      expect(box.x + box.width).toBeLessThanOrEqual(layout.width);
+      expect(box.y + box.height).toBeLessThanOrEqual(layout.height);
+    }
+  });
+
+  it("routes a layer-skipping edge through a lane inside the canvas for TD", () => {
+    const layout = layoutFlowchart(chart("flowchart TD\n A --> B\n B --> C\n A --> C"));
+    for (const edge of layout.edges) {
+      for (const segment of edge.segments) {
+        expect(segment.x).toBeGreaterThanOrEqual(0);
+        expect(segment.x + segment.width).toBeLessThanOrEqual(layout.width);
+        expect(segment.y + segment.height).toBeLessThanOrEqual(layout.height);
+      }
+    }
+  });
+
+  it("stacks layers rightward for LR", () => {
+    const layout = layoutFlowchart(chart("flowchart LR\n A --> B"));
+    const [a, b] = ["A", "B"].map((id) => layout.nodes.find((node) => node.id === id)!);
+    expect(b.x).toBeGreaterThan(a.x);
+  });
+
+  it("flips the flow for BT", () => {
+    const layout = layoutFlowchart(chart("flowchart BT\n A --> B"));
+    const [a, b] = ["A", "B"].map((id) => layout.nodes.find((node) => node.id === id)!);
+    expect(b.y).toBeLessThan(a.y);
+  });
+
+  it("never overlaps two nodes on the same layer", () => {
+    const layout = layoutFlowchart(chart("flowchart TD\n R --> A\n R --> B\n R --> C"));
+    const row = layout.nodes
+      .filter((node) => node.layer === 1)
+      .sort((left, right) => left.x - right.x);
+    for (let index = 1; index < row.length; index += 1) {
+      expect(row[index].x).toBeGreaterThanOrEqual(row[index - 1].x + row[index - 1].width);
+    }
+  });
+
+  it("reports a canvas large enough to hold every node", () => {
+    const layout = layoutFlowchart(chart("flowchart TD\n R --> A\n R --> B\n A --> C"));
+    for (const node of layout.nodes) {
+      expect(node.x + node.width).toBeLessThanOrEqual(layout.width + 0.001);
+      expect(node.y + node.height).toBeLessThanOrEqual(layout.height + 0.001);
+    }
+  });
+
+  it("routes an edge with segments and points the arrow along the flow", () => {
+    const layout = layoutFlowchart(chart("flowchart TD\n A --> B"));
+    const edge = layout.edges[0];
+    expect(edge.segments).toHaveLength(3);
+    expect(edge.arrowAt?.direction).toBe("down");
+  });
+
+  it("gives a line no arrowhead", () => {
+    expect(layoutFlowchart(chart("flowchart TD\n A --- B")).edges[0].arrowAt).toBeNull();
+  });
+
+  it("places an edge label between its endpoints", () => {
+    const layout = layoutFlowchart(chart("flowchart TD\n A -->|yes| B"));
+    const [a, b] = ["A", "B"].map((id) => layout.nodes.find((node) => node.id === id)!);
+    const label = layout.edges[0].labelAt!;
+    expect(label.y).toBeGreaterThan(a.y);
+    expect(label.y).toBeLessThan(b.y + b.height);
+  });
+
+  it("survives an edge pointing at a node that was never defined", () => {
+    const layout = layoutFlowchart({
+      direction: "TD",
+      nodes: [],
+      edges: [{ from: "A", to: "B", label: null, style: "solid", arrow: true }],
+      subgraphs: [],
+      skipped: [],
+    });
+    expect(layout.edges[0].segments).toEqual([]);
+  });
+});
+
+describe("layoutSequence", () => {
+  const people = [
+    { id: "U", label: "User", actor: false },
+    { id: "S", label: "Payment gateway", actor: true },
+  ];
+
+  it("sizes each column to its own label", () => {
+    const layout = layoutSequence(people, 2);
+    expect(layout.columns[1].width).toBeGreaterThan(layout.columns[0].width);
+  });
+
+  it("never overlaps two columns", () => {
+    const layout = layoutSequence(people, 1);
+    const [first, second] = layout.columns;
+    expect(second.centerX - second.width / 2).toBeGreaterThan(first.centerX + first.width / 2);
+  });
+
+  it("stacks one row per event below the header", () => {
+    const layout = layoutSequence(people, 3);
+    expect(layout.rows).toHaveLength(3);
+    expect(layout.rows[0].y).toBeGreaterThanOrEqual(layout.headerHeight);
+    expect(layout.rows[2].y).toBeGreaterThan(layout.rows[1].y);
+  });
+
+  it("reports a canvas that contains the last column and row", () => {
+    const layout = layoutSequence(people, 2);
+    const last = layout.columns[layout.columns.length - 1];
+    expect(last.centerX + last.width / 2).toBeLessThanOrEqual(layout.width + 0.001);
+    expect(layout.height).toBeGreaterThan(layout.rows[1].y);
+  });
+
+  it("handles a diagram with no events yet", () => {
+    expect(layoutSequence(people, 0).rows).toEqual([]);
+  });
+});
+
+describe("diamond geometry", () => {
+  it("gives a diamond a square box, so its rotated corners reach the edges", () => {
+    const box = measureNode({ id: "A", label: "Has mermaid?", shape: "diamond" });
+    expect(box.width).toBe(box.height);
+  });
+
+  it("keeps the box wide enough for the label across the diagonal", () => {
+    const plain = measureNode({ id: "A", label: "Has mermaid?", shape: "rect" });
+    const diamond = measureNode({ id: "A", label: "Has mermaid?", shape: "diamond" });
+    expect(diamond.width).toBeGreaterThan(plain.width);
+  });
+});
+
+describe("fitScale", () => {
+  it("shrinks a wide diagram to the width it was given", () => {
+    expect(fitScale(900, 1200)).toBeCloseTo(0.75);
+  });
+
+  it("grows a small diagram so it does not sit lost in a wide row", () => {
+    expect(fitScale(900, 300)).toBe(1.3);
+  });
+
+  it("never shrinks past the point where labels stop being readable", () => {
+    expect(fitScale(100, 2000)).toBe(0.55);
+  });
+
+  it("leaves the drawing alone before the container has been measured", () => {
+    expect(fitScale(0, 800)).toBe(1);
+    expect(fitScale(600, 0)).toBe(1);
+  });
+
+  it("reports the case where scrolling is still needed after shrinking", () => {
+    expect(overflowsAfterFit(100, 2000)).toBe(true);
+  });
+
+  it("reports no overflow once the diagram fits", () => {
+    expect(overflowsAfterFit(900, 1200)).toBe(false);
+    expect(overflowsAfterFit(900, 300)).toBe(false);
+  });
+
+  it("scrolls again once the reader zooms a fitted drawing past the row", () => {
+    expect(overflowsAfterFit(900, 1200, 1)).toBe(false);
+    expect(overflowsAfterFit(900, 1200, 1.25)).toBe(true);
+    expect(overflowsAfterFit(100, 2000, 0.5)).toBe(true);
+  });
+});
+
+describe("edges that skip a layer", () => {
+  // Cached? --> Response jumps two layers past Query database and Write cache.
+  const source = `flowchart LR
+    Req([Request]) --> Auth{Authorized?}
+    Auth --> Cache{Cached?}
+    Cache -->|miss| Query[[Query database]]
+    Cache -->|hit| Serve((Response))
+    Query --> Store(Write cache)
+    Store --> Serve`;
+
+  const layout = layoutFlowchart(parseFlowchart(source)!);
+  const long = layout.edges.find((edge) => edge.from === "Cache" && edge.to === "Serve")!;
+  const boxes = layout.nodes.filter((node) => node.id !== "Cache" && node.id !== "Serve");
+
+  it("routes the long edge with five segments rather than three", () => {
+    expect(long.segments).toHaveLength(5);
+    const direct = layout.edges.find((edge) => edge.from === "Query" && edge.to === "Store")!;
+    expect(direct.segments).toHaveLength(3);
+  });
+
+  it("keeps every segment of the long edge out of the boxes it skips", () => {
+    for (const segment of long.segments) {
+      for (const box of boxes) {
+        const overlaps =
+          segment.x < box.x + box.width &&
+          segment.x + segment.width > box.x &&
+          segment.y < box.y + box.height &&
+          segment.y + segment.height > box.y;
+        expect(overlaps, `${long.from}->${long.to} crosses ${box.id}`).toBe(false);
+      }
+    }
+  });
+
+  it("grows the canvas so the lane is inside it", () => {
+    const lowest = Math.max(...long.segments.map((segment) => segment.y + segment.height));
+    expect(lowest).toBeLessThanOrEqual(layout.height);
+  });
+
+  it("still points the arrow into the target", () => {
+    const target = layout.nodes.find((node) => node.id === "Serve")!;
+    expect(long.arrowAt?.direction).toBe("right");
+    expect(long.arrowAt?.x).toBeCloseTo(target.x);
+  });
+
+  it("puts the label on the lane, clear of the nodes", () => {
+    expect(long.label).toBe("hit");
+    for (const box of boxes) expect(long.labelAt!.y).toBeGreaterThan(box.y + box.height);
+  });
+});