/** * 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; } export interface Flowchart { direction: Direction; nodes: FlowNode[]; edges: FlowEdge[]; /** 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(//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(); const edges: FlowEdge[] = []; const skipped: string[] = []; 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); } }; 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; } // Subgraphs are not laid out yet; their contents still render as nodes. if (/^subgraph\b/i.test(line) || /^end$/i.test(line)) { 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, skipped }; }