@zombie-mermaid/mermaid-parser 2.2.1

package/src/sequence/types.ts

@@ -0,0 +1,242 @@
+// ============================================================================
+// Sequence diagram types
+//
+// Models the parsed and positioned representations of a Mermaid sequence diagram.
+// Sequence diagrams show actor interactions over time (vertical timeline).
+// ============================================================================
+
+/** Parsed sequence diagram — logical structure from mermaid text */
+export interface SequenceDiagram {
+  /** Ordered list of actors/participants */
+  actors: Actor[]
+  /** Messages between actors in chronological order */
+  messages: Message[]
+  /** Structural blocks (loop, alt, opt, par, critical) */
+  blocks: Block[]
+  /** Notes attached to actors */
+  notes: Note[]
+  /**
+   * Standalone `activate X` / `deactivate X` statements, in source order.
+   * The inline `+`/`-` arrow shorthand is *not* recorded here — it stays on
+   * `Message.activate` / `Message.deactivate` — but both feed the same
+   * activation stack at layout time (see layout.ts), so the two forms
+   * render identically.
+   */
+  activations: ActivationEvent[]
+  /**
+   * `box <color?> <label?> … end` participant groups, in source order. A box
+   * with no members (nothing declared inside it) is kept here but drawn by
+   * neither renderer.
+   */
+  boxes: ParticipantBox[]
+}
+
+/** A `box … end` group of participants (Mermaid's "Grouping / Box"). */
+export interface ParticipantBox {
+  /** Descriptive label; empty when the box has none. */
+  label: string
+  /**
+   * Validated CSS colour (named, `#hex`, `rgb()`/`rgba()`, `hsl()`/`hsla()`)
+   * exactly as written. Unset for a transparent box — including an explicit
+   * `box transparent …`, and any first word that isn't a colour, which then
+   * counts as the start of the label (Mermaid's `parseBoxData` rule).
+   */
+  color?: string
+  /** Ids of the participants declared (or first used) inside the box. */
+  actorIds: string[]
+}
+
+/**
+ * One standalone `activate X` (`kind: 'start'`) or `deactivate X`
+ * (`kind: 'end'`) statement. Mermaid's own grammar expands the `+`/`-` arrow
+ * shorthand into exactly these events — `A->>+B` is a message followed by an
+ * `activeStart` for the recipient, `A-->>-B` a message followed by an
+ * `activeEnd` for the sender — so this is the primitive and the shorthand is
+ * sugar over it.
+ */
+export interface ActivationEvent {
+  actorId: string
+  kind: 'start' | 'end'
+  /**
+   * Index of the message this statement follows (-1 if it precedes every
+   * message). The activation bar starts/ends at that message's row, which
+   * is where the shorthand form's bar starts/ends too.
+   */
+  afterIndex: number
+}
+
+export interface Actor {
+  id: string
+  label: string
+  /** 'participant' renders as a box, 'actor' renders as a stick figure */
+  type: 'participant' | 'actor'
+  /**
+   * Index of the message that creates this participant (`create participant
+   * X` on the line before it). The participant's box is drawn at that
+   * message's row instead of in the header, and its lifeline starts there.
+   * Unset for participants that exist from the top of the diagram.
+   */
+  createdAt?: number
+  /**
+   * Index of the message that destroys this participant (`destroy X` on the
+   * line before it). Its lifeline ends at that message's row with a cross,
+   * and no footer box is drawn. Unset for participants that live to the end.
+   */
+  destroyedAt?: number
+}
+
+export interface Message {
+  from: string
+  to: string
+  label: string
+  /** Arrow style: solid line or dashed line */
+  lineStyle: 'solid' | 'dashed'
+  /** Arrow head: filled (closed) or open */
+  arrowHead: 'filled' | 'open'
+  /**
+   * Set for a "lost message" cross-terminator (`-x`/`--x`). `arrowHead`
+   * stays `'filled'` for these (unchanged, to preserve existing SVG output)
+   * — this flag lets the ASCII renderer draw a distinct cross glyph instead
+   * of the plain filled arrowhead it shares with `->>`/`-->>`. See issue
+   * #330; not yet modeled by the SVG renderer's markers.
+   */
+  isLost?: boolean
+  /** Activate the target lifeline (+) */
+  activate?: boolean
+  /** Deactivate the source lifeline (-) */
+  deactivate?: boolean
+  /** Bidirectional arrow (`<<->>` or `<<-->>`) — draw an arrow head on both ends */
+  bidirectional?: boolean
+  /** Sequence number to display next to this arrow when `autonumber` is active */
+  seqNumber?: number
+}
+
+export interface Block {
+  /** Block type keyword */
+  type: 'loop' | 'alt' | 'opt' | 'par' | 'critical' | 'break' | 'rect'
+  /** Label for the block header */
+  label: string
+  /** Index of the first message inside this block */
+  startIndex: number
+  /** Index of the last message inside this block (inclusive) */
+  endIndex: number
+  /** For alt/par blocks: indices where "else"/"and" dividers appear (message indices) */
+  dividers: Array<{ index: number; label: string }>
+}
+
+export interface Note {
+  /** Which actor(s) the note is attached to */
+  actorIds: string[]
+  /** Note text content */
+  text: string
+  /** Position relative to the actor(s) */
+  position: 'left' | 'right' | 'over'
+  /** Message index after which this note appears */
+  afterIndex: number
+}
+
+// ============================================================================
+// Positioned sequence diagram — ready for SVG rendering
+// ============================================================================
+
+export interface PositionedSequenceDiagram {
+  width: number
+  height: number
+  actors: PositionedActor[]
+  lifelines: Lifeline[]
+  messages: PositionedMessage[]
+  activations: Activation[]
+  blocks: PositionedBlock[]
+  notes: PositionedNote[]
+  /** `box … end` group backgrounds, drawn behind everything else. */
+  boxes: PositionedParticipantBox[]
+}
+
+/** A positioned `box … end` group: a full-height background behind its participants. */
+export interface PositionedParticipantBox {
+  label: string
+  /** See {@link ParticipantBox.color}. */
+  color?: string
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface PositionedActor {
+  id: string
+  label: string
+  type: 'participant' | 'actor'
+  /** Center x of the actor box */
+  x: number
+  /** Top y of the actor box */
+  y: number
+  width: number
+  height: number
+}
+
+/** Vertical dashed line from actor to bottom of diagram */
+export interface Lifeline {
+  actorId: string
+  x: number
+  topY: number
+  bottomY: number
+  /**
+   * Set when the actor is destroyed mid-diagram (`Actor.destroyedAt`):
+   * `bottomY` is then the destroying message's row rather than the diagram
+   * bottom, and the renderer marks it with a cross.
+   */
+  destroyed?: boolean
+}
+
+export interface PositionedMessage {
+  from: string
+  to: string
+  label: string
+  lineStyle: 'solid' | 'dashed'
+  arrowHead: 'filled' | 'open'
+  /** Start point (from actor's lifeline) */
+  x1: number
+  /** End point (to actor's lifeline) */
+  x2: number
+  /** Vertical position */
+  y: number
+  /** Whether this is a self-message (same actor) */
+  isSelf: boolean
+  /** Bidirectional arrow (`<<->>` or `<<-->>`) — draw an arrow head on both ends */
+  bidirectional: boolean
+  /** Sequence number to display next to this arrow when `autonumber` is active */
+  seqNumber?: number
+}
+
+/** Narrow rectangle on a lifeline showing active processing */
+export interface Activation {
+  actorId: string
+  x: number
+  topY: number
+  bottomY: number
+  width: number
+}
+
+export interface PositionedBlock {
+  type: Block['type']
+  label: string
+  x: number
+  y: number
+  width: number
+  height: number
+  /** Divider lines within the block (for alt/par) */
+  dividers: Array<{ y: number; label: string }>
+}
+
+export interface PositionedNote {
+  text: string
+  x: number
+  y: number
+  width: number
+  height: number
+  /** Actor IDs this note is attached to (for SVG attribution) */
+  actors?: string[]
+  /** Note position relative to actors (for SVG attribution) */
+  position?: 'left' | 'right' | 'over'
+}

package/src/xychart/colors.ts

@@ -0,0 +1,177 @@
+// ============================================================================
+// XY Chart — shared color palette
+//
+// Generates monochromatic shades from the theme accent color.
+// Series 0 = accent (or blue fallback). Series 1+ are darker/lighter
+// shades of the same hue with subtle hue drift to stay in the same
+// color family (like navy ↔ cyan from blue).
+//
+// Used by both the SVG and ASCII renderers.
+// ============================================================================
+
+/** Default accent for charts when the theme doesn't provide one. */
+export const CHART_ACCENT_FALLBACK = '#3b82f6' // blue-500
+
+// ---------------------------------------------------------------------------
+// HSL ↔ Hex conversion
+// ---------------------------------------------------------------------------
+
+function hexToHsl(hex: string): [number, number, number] {
+  const h = hex.replace('#', '')
+  const ri = parseInt(h.substring(0, 2), 16) / 255
+  const gi = parseInt(h.substring(2, 4), 16) / 255
+  const bi = parseInt(h.substring(4, 6), 16) / 255
+
+  const max = Math.max(ri, gi, bi)
+  const min = Math.min(ri, gi, bi)
+  const l = (max + min) / 2
+
+  if (max === min) return [0, 0, l * 100]
+
+  const d = max - min
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+
+  let hue: number
+  if (max === ri) hue = ((gi - bi) / d + (gi < bi ? 6 : 0)) / 6
+  else if (max === gi) hue = ((bi - ri) / d + 2) / 6
+  else hue = ((ri - gi) / d + 4) / 6
+
+  return [hue * 360, s * 100, l * 100]
+}
+
+function hslToHex(h: number, s: number, l: number): string {
+  const si = s / 100
+  const li = l / 100
+
+  const c = (1 - Math.abs(2 * li - 1)) * si
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
+  const m = li - c / 2
+
+  let r: number, g: number, b: number
+  if (h < 60) {
+    r = c
+    g = x
+    b = 0
+  } else if (h < 120) {
+    r = x
+    g = c
+    b = 0
+  } else if (h < 180) {
+    r = 0
+    g = c
+    b = x
+  } else if (h < 240) {
+    r = 0
+    g = x
+    b = c
+  } else if (h < 300) {
+    r = x
+    g = 0
+    b = c
+  } else {
+    r = c
+    g = 0
+    b = x
+  }
+
+  const toHex = (v: number) =>
+    Math.round((v + m) * 255)
+      .toString(16)
+      .padStart(2, '0')
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`
+}
+
+// ---------------------------------------------------------------------------
+// Hex ↔ RGB conversion
+// ---------------------------------------------------------------------------
+
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace('#', '')
+  return [
+    parseInt(h.substring(0, 2), 16),
+    parseInt(h.substring(2, 4), 16),
+    parseInt(h.substring(4, 6), 16),
+  ]
+}
+
+function rgbToHex(r: number, g: number, b: number): string {
+  const toHex = (v: number) =>
+    Math.round(Math.max(0, Math.min(255, v)))
+      .toString(16)
+      .padStart(2, '0')
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Check whether a string is a valid 6-digit hex color (e.g. "#3b82f6"). */
+export function isValidHex(color: string): boolean {
+  return /^#[0-9a-fA-F]{6}$/.test(color)
+}
+
+/**
+ * Detect whether a background color is dark (lightness < 50%).
+ */
+export function isDarkBackground(bgHex: string): boolean {
+  return hexToHsl(bgHex)[2] < 50
+}
+
+/**
+ * Mix two hex colors in RGB space.
+ * `ratio` controls how much of `fgHex` shows: 0 = pure bg, 1 = pure fg.
+ * Equivalent to alpha-compositing fg over bg at the given opacity.
+ */
+export function mixHexColors(
+  bgHex: string,
+  fgHex: string,
+  ratio: number,
+): string {
+  const [br, bg, bb] = hexToRgb(bgHex)
+  const [fr, fg, fb] = hexToRgb(fgHex)
+  const inv = 1 - ratio
+  return rgbToHex(
+    br * inv + fr * ratio,
+    bg * inv + fg * ratio,
+    bb * inv + fb * ratio,
+  )
+}
+
+/**
+ * Get the hex color for a series index.
+ * Index 0 returns the accent color as-is.
+ * Index 1+ alternate between darker and lighter shades of the same hue
+ * with subtle hue drift (±8-12° per tier) to stay in the same family.
+ *
+ * When `bgColor` is provided, shade direction adapts to the background:
+ *   - Light bg: odd = darker, even = lighter (default)
+ *   - Dark bg:  odd = lighter, even = darker (so shades stay visible)
+ */
+export function getSeriesColor(
+  index: number,
+  accentColor: string,
+  bgColor?: string,
+): string {
+  if (index === 0) return accentColor
+  // Fall back to defaults when inputs aren't valid hex (e.g. CSS variable refs like "var(--accent)")
+  const safeAccent = isValidHex(accentColor)
+    ? accentColor
+    : CHART_ACCENT_FALLBACK
+  const safeBg = bgColor && isValidHex(bgColor) ? bgColor : undefined
+  const [h, s] = hexToHsl(safeAccent)
+  const chartS = Math.max(55, Math.min(85, s))
+
+  const tier = Math.ceil(index / 2)
+  const oddIndex = index % 2 === 1
+
+  // On dark backgrounds, flip: odd = lighter, even = darker
+  const dark = safeBg && isDarkBackground(safeBg) ? !oddIndex : oddIndex
+  const l = dark ? Math.max(25, 48 - tier * 13) : Math.min(78, 55 + tier * 11)
+
+  // Subtle hue drift: darker shades shift slightly negative, lighter shift positive
+  const hShift = (dark ? -8 : 12) * tier
+  const newH = (((h + hShift) % 360) + 360) % 360
+
+  return hslToHex(newH, chartS, l)
+}

package/src/xychart/parser.ts

@@ -0,0 +1,246 @@
+import type { XYChart, XYAxis, XYChartSeries } from './types.ts'
+import type { Statement } from '@zombie-mermaid/core'
+
+// ============================================================================
+// XY Chart parser
+//
+// Parses Mermaid xychart-beta syntax into a typed XYChart structure.
+//
+// Supported directives:
+//   xychart-beta [horizontal]
+//   title "Chart Title"
+//   x-axis [label1, label2, ...]          — categorical
+//   x-axis min --> max                     — numeric range
+//   x-axis "Axis Title" [label1, ...]      — with title
+//   x-axis "Axis Title" min --> max        — with title
+//   y-axis (same patterns)
+//   bar [val1, val2, ...]
+//   line [val1, val2, ...]
+// ============================================================================
+
+/**
+ * Parse a Mermaid xychart-beta diagram from preprocessed lines.
+ * Lines should already be trimmed and comment-stripped.
+ */
+export function parseXYChart(lines: Statement[]): XYChart {
+  const xAxis: XYAxis = {}
+  const yAxis: XYAxis = {}
+  const series: XYChartSeries[] = []
+  let title: string | undefined
+  let horizontal = false
+
+  for (const stmt of lines) {
+    const line = stmt.text
+    // Header line — detect horizontal
+    if (/^xychart(-beta)?\b/i.test(line)) {
+      if (/\bhorizontal\b/i.test(line)) horizontal = true
+      continue
+    }
+
+    // Title
+    const titleMatch = line.match(/^title\s+"([^"]+)"/)
+    if (titleMatch) {
+      title = titleMatch[1]
+      continue
+    }
+
+    // x-axis with categories: x-axis "Title" [a, b, c] or x-axis [a, b, c]
+    const xCatMatch = line.match(/^x-axis\s+(?:"([^"]*)"\s*)?\[([^\]]+)\]/)
+    if (xCatMatch) {
+      if (xCatMatch[1]) xAxis.title = xCatMatch[1]
+      xAxis.categories = splitCategoryList(xCatMatch[2]!).map((s) =>
+        unquote(s.trim()),
+      )
+      continue
+    }
+
+    // x-axis with range: x-axis "Title" min --> max or x-axis min --> max
+    const xRangeMatch = line.match(
+      /^x-axis\s+(?:"([^"]*)"\s+)?(-?\d+(?:\.\d+)?)\s*-->\s*(-?\d+(?:\.\d+)?)/,
+    )
+    if (xRangeMatch) {
+      if (xRangeMatch[1]) xAxis.title = xRangeMatch[1]
+      xAxis.range = {
+        min: parseFloat(xRangeMatch[2]!),
+        max: parseFloat(xRangeMatch[3]!),
+      }
+      continue
+    }
+
+    // y-axis with range: y-axis "Title" min --> max or y-axis min --> max
+    const yRangeMatch = line.match(
+      /^y-axis\s+(?:"([^"]*)"\s+)?(-?\d+(?:\.\d+)?)\s*-->\s*(-?\d+(?:\.\d+)?)/,
+    )
+    if (yRangeMatch) {
+      if (yRangeMatch[1]) yAxis.title = yRangeMatch[1]
+      yAxis.range = {
+        min: parseFloat(yRangeMatch[2]!),
+        max: parseFloat(yRangeMatch[3]!),
+      }
+      continue
+    }
+
+    // y-axis with just title (no range)
+    const yTitleOnly = line.match(/^y-axis\s+"([^"]+)"\s*$/)
+    if (yTitleOnly) {
+      yAxis.title = yTitleOnly[1]
+      continue
+    }
+
+    // bar [...]
+    const barMatch = line.match(/^bar\s+\[([^\]]+)\]/)
+    if (barMatch) {
+      series.push({
+        type: 'bar',
+        data: parseNumericArray(barMatch[1]!, 'bar', line, stmt.line),
+      })
+      continue
+    }
+
+    // line [...]
+    const lineMatch = line.match(/^line\s+\[([^\]]+)\]/)
+    if (lineMatch) {
+      series.push({
+        type: 'line',
+        data: parseNumericArray(lineMatch[1]!, 'line', line, stmt.line),
+      })
+      continue
+    }
+
+    // None of the recognized directive shapes matched. A line that doesn't
+    // start with any known xychart-beta keyword at all falls through
+    // silently below, same as before — but a line that *does* start with
+    // one of the five keyworded directives (x-axis/y-axis/bar/line/title)
+    // and still failed every pattern above is almost certainly an attempt
+    // at that directive with broken syntax (an unclosed bracket, a missing
+    // quote, a malformed range). Previously this was silently dropped —
+    // the diagram would render with that axis/series just missing and no
+    // indication why. Surface an actionable error instead. See issue #541
+    // (parser error-message quality audit — this parser had zero throw
+    // sites before this pass).
+    const keywordMatch = line.match(/^(x-axis|y-axis|bar|line|title)\b/i)
+    if (keywordMatch) {
+      throw malformedDirectiveError(
+        keywordMatch[1]!.toLowerCase(),
+        line,
+        stmt.line,
+      )
+    }
+  }
+
+  // Auto-derive y-axis range from data if not specified
+  if (!yAxis.range && series.length > 0) {
+    const allValues = series.flatMap((s) => s.data)
+    let min = Math.min(...allValues)
+    let max = Math.max(...allValues)
+    const span = max - min || 1
+    // Add 10% padding
+    min = min - span * 0.1
+    max = max + span * 0.1
+    // Floor to 0 if all values are positive and min is close to 0
+    if (min > 0 && min < span * 0.5) min = 0
+    yAxis.range = { min, max }
+  }
+
+  // Fallback y-axis range
+  if (!yAxis.range) {
+    yAxis.range = { min: 0, max: 100 }
+  }
+
+  return { title, horizontal, xAxis, yAxis, series }
+}
+
+/**
+ * Split a categorical x-axis bracket's comma-separated contents into raw
+ * item strings, treating a comma *inside* a double-quoted item as literal
+ * text rather than a delimiter. A naive `.split(',')` would break
+ * `["Jan, Feb", "Mar"]` into three pieces instead of two — quoting a value
+ * that itself contains a comma is exactly the case quoting exists for. Each
+ * returned raw item is still trimmed and unquoted by the caller.
+ */
+function splitCategoryList(str: string): string[] {
+  const items: string[] = []
+  let current = ''
+  let inQuotes = false
+  for (const char of str) {
+    if (char === '"') {
+      inQuotes = !inQuotes
+      current += char
+    } else if (char === ',' && !inQuotes) {
+      items.push(current)
+      current = ''
+    } else {
+      current += char
+    }
+  }
+  items.push(current)
+  return items
+}
+
+/**
+ * Strip one matching pair of leading/trailing double quotes from a category
+ * item, if present — mirroring how an axis *title* capture group already
+ * unquotes via its regex. `x-axis [A, B, C]` items are only split and
+ * trimmed, so a quoted item like `"CLI output / logs"` previously kept its
+ * literal quote characters in the rendered label. See issue #1087.
+ */
+function unquote(value: string): string {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1)
+  }
+  return value
+}
+
+/**
+ * Parse a `bar`/`line` series' comma-separated bracket contents into
+ * numbers, throwing on any element that isn't a valid number instead of
+ * silently coercing it to `NaN` (which serializes as `null` and can
+ * propagate into layout math with no indication anything was wrong — see
+ * issue #541's audit finding on this exact parser).
+ */
+function parseNumericArray(
+  str: string,
+  seriesType: 'bar' | 'line',
+  line: string,
+  lineNumber: number,
+): number[] {
+  return str.split(',').map((raw, index) => {
+    const trimmed = raw.trim()
+    const value = parseFloat(trimmed)
+    if (trimmed.length === 0 || Number.isNaN(value)) {
+      throw new Error(
+        `Line ${lineNumber}: Invalid numeric value ${JSON.stringify(trimmed)} at position ${
+          index + 1
+        } in "${line}". Every value in a ${seriesType} [...] list must be a number.`,
+      )
+    }
+    return value
+  })
+}
+
+/** Expected-syntax hint per xychart-beta keyword, for `malformedDirectiveError`. */
+const XYCHART_DIRECTIVE_HELP: Record<string, string> = {
+  'x-axis':
+    'x-axis [A, B, C] (categories) or x-axis 0 --> 100 (numeric range), either optionally preceded by a quoted title',
+  'y-axis':
+    'y-axis 0 --> 100 (numeric range) or y-axis "Title" (title only), optionally preceded by a quoted title before a range',
+  bar: 'bar [10, 20, 30] — a comma-separated numeric array in square brackets',
+  line: 'line [10, 20, 30] — a comma-separated numeric array in square brackets',
+  title: 'title "Chart Title" — a double-quoted string',
+}
+
+/**
+ * Build the error for a line that starts with a recognized xychart-beta
+ * keyword (x-axis/y-axis/bar/line/title) but doesn't match that keyword's
+ * expected syntax in any of the forms this parser supports.
+ */
+function malformedDirectiveError(
+  keyword: string,
+  line: string,
+  lineNumber: number,
+): Error {
+  const help = XYCHART_DIRECTIVE_HELP[keyword] ?? keyword
+  return new Error(
+    `Line ${lineNumber}: Malformed xychart-beta "${keyword}" directive: "${line}". Expected: ${help}.`,
+  )
+}