@zombie-mermaid/mermaid-parser 3.1.0 → 4.0.0

package/src/architecture/to-graph.ts

@@ -0,0 +1,141 @@
+import type {
+  Direction,
+  MermaidEdge,
+  MermaidGraph,
+  MermaidNode,
+  MermaidSubgraph,
+  NodeShape,
+} from '@zombie-mermaid/core'
+import type {
+  ArchitectureDiagram,
+  ArchitectureEdge,
+  ArchitecturePort,
+} from './types.ts'
+
+// ============================================================================
+// Architecture -> flowchart lowering
+//
+// `architecture-beta` is boxes in nested boxes joined by edges, which the
+// flowchart pipeline already lays out and draws (ELK for SVG, the grid router
+// for ASCII). Like the other lowered types it becomes a `MermaidGraph`:
+//
+//   group          -> subgraph (nested via `in`)
+//   service        -> node; the icon picks a shape
+//   junction       -> small filled circle, no label
+//   edge           -> edge; `<`/`>` become arrowheads
+//   `{group}` end  -> the edge attaches to the service's enclosing group
+//
+// What is not carried over: Mermaid places services on a grid from the edge
+// ports, so `a:R -- L:b` means "b is right of a". Here ports only choose the
+// flow direction (majority axis) and which way each edge points in the
+// layout; exact placement is the flowchart layout's. Icons are not drawn
+// (only the database/disk shapes differ) and `align` is ignored.
+// ============================================================================
+
+/** Built-in Mermaid icons that have a distinct flowchart shape. */
+const ICON_SHAPE: Record<string, NodeShape> = {
+  database: 'cylinder',
+  disk: 'cylinder',
+  cloud: 'stadium',
+  internet: 'circle',
+}
+
+const HORIZONTAL: ReadonlySet<ArchitecturePort> = new Set(['L', 'R'])
+
+/** Flow direction: vertical only when more edges leave via T/B than L/R. */
+function pickDirection(edges: readonly ArchitectureEdge[]): Direction {
+  let horizontal = 0
+  let vertical = 0
+  for (const e of edges) {
+    for (const p of [e.sourcePort, e.targetPort]) {
+      if (HORIZONTAL.has(p)) horizontal++
+      else vertical++
+    }
+  }
+  return vertical > horizontal ? 'TB' : 'LR'
+}
+
+/**
+ * Whether the edge, as written, runs against the layout flow. `a:L -- R:b`
+ * puts `a` to the right of `b`, so in a left-to-right layout the edge has to
+ * be emitted reversed for `a` to land on the right.
+ */
+function runsBackwards(e: ArchitectureEdge, direction: Direction): boolean {
+  const horizontal = direction === 'LR' || direction === 'RL'
+  const [back, forward]: ArchitecturePort[] = horizontal
+    ? ['L', 'R']
+    : ['T', 'B']
+  // Source port on the far side of the flow, or target port on the near side.
+  if (e.sourcePort === forward || e.targetPort === back) return false
+  return e.sourcePort === back || e.targetPort === forward
+}
+
+export function architectureToGraph(
+  diagram: ArchitectureDiagram,
+): MermaidGraph {
+  const nodes = new Map<string, MermaidNode>()
+  const parentOf = new Map<string, string | undefined>()
+
+  for (const s of diagram.services) {
+    nodes.set(s.id, {
+      id: s.id,
+      label: s.title,
+      shape: (s.icon && ICON_SHAPE[s.icon]) || 'rectangle',
+    })
+    parentOf.set(s.id, s.parent)
+  }
+  for (const j of diagram.junctions) {
+    nodes.set(j.id, { id: j.id, label: '', shape: 'filled-circle' })
+    parentOf.set(j.id, j.parent)
+  }
+
+  // Subgraphs, nested. Children are attached in declaration order.
+  const subgraphs = new Map<string, MermaidSubgraph>()
+  for (const g of diagram.groups) {
+    subgraphs.set(g.id, {
+      id: g.id,
+      label: g.title,
+      nodeIds: [],
+      children: [],
+    })
+  }
+  const roots: MermaidSubgraph[] = []
+  for (const g of diagram.groups) {
+    const sg = subgraphs.get(g.id)!
+    const parent = g.parent ? subgraphs.get(g.parent) : undefined
+    if (parent) parent.children.push(sg)
+    else roots.push(sg)
+  }
+  for (const [id, parent] of parentOf) {
+    subgraphs.get(parent ?? '')?.nodeIds.push(id)
+  }
+
+  const direction = pickDirection(diagram.edges)
+  const edges: MermaidEdge[] = diagram.edges.map((e) => {
+    const end = (id: string, viaGroup: boolean): string =>
+      (viaGroup ? parentOf.get(id) : undefined) ?? id
+    const forward = !runsBackwards(e, direction)
+    const [source, target] = forward
+      ? [end(e.source, e.sourceGroup), end(e.target, e.targetGroup)]
+      : [end(e.target, e.targetGroup), end(e.source, e.sourceGroup)]
+    return {
+      source,
+      target,
+      style: 'solid',
+      hasArrowStart: forward ? e.arrowStart : e.arrowEnd,
+      hasArrowEnd: forward ? e.arrowEnd : e.arrowStart,
+    }
+  })
+
+  return {
+    direction,
+    nodes,
+    edges,
+    subgraphs: roots,
+    classDefs: new Map(),
+    classAssignments: new Map(),
+    nodeStyles: new Map(),
+    linkStyles: new Map(),
+    interactions: new Map(),
+  }
+}

package/src/architecture/types.ts

@@ -0,0 +1,49 @@
+// ============================================================================
+// Architecture diagram types (Mermaid `architecture-beta`)
+// ============================================================================
+
+/** A port on a service/junction: left, right, top, bottom. */
+export type ArchitecturePort = 'L' | 'R' | 'T' | 'B'
+
+export interface ArchitectureGroup {
+  id: string
+  /** Icon name from `(icon)`; kept for consumers, not drawn (see to-graph). */
+  icon?: string
+  /** `[Title]`; falls back to the id. */
+  title: string
+  /** Enclosing group id, from `in <parent>`. */
+  parent?: string
+}
+
+export interface ArchitectureService {
+  id: string
+  icon?: string
+  title: string
+  parent?: string
+}
+
+export interface ArchitectureJunction {
+  id: string
+  parent?: string
+}
+
+export interface ArchitectureEdge {
+  source: string
+  sourcePort: ArchitecturePort
+  /** `{group}` modifier: the edge attaches to the enclosing group's border. */
+  sourceGroup: boolean
+  target: string
+  targetPort: ArchitecturePort
+  targetGroup: boolean
+  /** `<--` / `<-->`: arrowhead at the source end. */
+  arrowStart: boolean
+  /** `-->` / `<-->`: arrowhead at the target end. */
+  arrowEnd: boolean
+}
+
+export interface ArchitectureDiagram {
+  groups: ArchitectureGroup[]
+  services: ArchitectureService[]
+  junctions: ArchitectureJunction[]
+  edges: ArchitectureEdge[]
+}

package/src/c4/format.ts

@@ -0,0 +1,120 @@
+import type { C4Boundary, C4Element, C4Relationship } from './types.ts'
+
+// ============================================================================
+// C4 text and layout-hint helpers shared by the SVG and ASCII renderers, so
+// both draw the same words and honor the same `Rel_U/D/L/R` hints.
+// ============================================================================
+
+/** Greedy word wrap; a word longer than `width` stays on its own line. */
+export function wrapC4Text(text: string, width: number): string[] {
+  const out: string[] = []
+  for (const paragraph of text.split('\n')) {
+    let cur = ''
+    for (const word of paragraph.split(/\s+/).filter(Boolean)) {
+      if (cur && cur.length + 1 + word.length > width) {
+        out.push(cur)
+        cur = word
+      } else {
+        cur = cur ? `${cur} ${word}` : word
+      }
+    }
+    out.push(cur)
+  }
+  return out
+}
+
+const STEREOTYPES: Record<C4Element['kind'], string> = {
+  person: 'Person',
+  system: 'Software System',
+  container: 'Container',
+  component: 'Component',
+}
+
+/**
+ * The bracketed type line under an element's name, as Mermaid draws it:
+ * `[Person]`, `[Software System]`, `[Container: PostgreSQL]`. External,
+ * database and queue variants share their base kind's line; the fill and the
+ * shape tell them apart.
+ */
+export function c4TypeLine(el: C4Element): string {
+  const tech =
+    (el.kind === 'container' || el.kind === 'component') && el.technology
+      ? `: ${el.technology}`
+      : ''
+  return `[${STEREOTYPES[el.kind]}${tech}]`
+}
+
+/** A boundary's type line (`[ENTERPRISE]`, `[Ubuntu]`), when it has a type. */
+export function c4BoundaryTypeLine(b: C4Boundary): string | undefined {
+  return b.type ? `[${b.type}]` : undefined
+}
+
+/**
+ * The text lines of a relationship label: the label itself (prefixed with its
+ * sequence number in a C4Dynamic diagram), then the technology in brackets on its
+ * own line. Empty when the relationship has neither.
+ */
+export function c4RelLabelLines(rel: C4Relationship): string[] {
+  const lines: string[] = []
+  const head = [rel.index ? `${rel.index}:` : '', rel.label]
+    .filter(Boolean)
+    .join(' ')
+  if (head) lines.push(head)
+  if (rel.technology) lines.push(`[${rel.technology}]`)
+  return lines
+}
+
+/**
+ * How a relationship constrains placement. `source` is meant to sit before
+ * `target` along `axis`: above it for `'vertical'`, left of it for
+ * `'horizontal'`. `Rel_U`/`Rel_L` reverse the pair (the target sits above /
+ * left of the source); plain `Rel` is a vertical hint, since C4 diagrams flow
+ * top to bottom by default.
+ */
+export interface C4Placement {
+  source: string
+  target: string
+  axis: 'vertical' | 'horizontal'
+  /** True when the hint came from an explicit `Rel_U/D/L/R`. */
+  explicit: boolean
+}
+
+export function c4Placement(rel: C4Relationship): C4Placement {
+  switch (rel.layout) {
+    case 'up':
+      return {
+        source: rel.to,
+        target: rel.from,
+        axis: 'vertical',
+        explicit: true,
+      }
+    case 'left':
+      return {
+        source: rel.to,
+        target: rel.from,
+        axis: 'horizontal',
+        explicit: true,
+      }
+    case 'right':
+      return {
+        source: rel.from,
+        target: rel.to,
+        axis: 'horizontal',
+        explicit: true,
+      }
+    case 'down':
+      return {
+        source: rel.from,
+        target: rel.to,
+        axis: 'vertical',
+        explicit: true,
+      }
+    default:
+      return {
+        source: rel.from,
+        target: rel.to,
+        axis: 'vertical',
+        explicit: false,
+      }
+  }
+}

package/src/c4/parser.ts

@@ -0,0 +1,271 @@
+import { normalizeBrTags, type Statement } from '@zombie-mermaid/core'
+import type {
+  C4Boundary,
+  C4Diagram,
+  C4Element,
+  C4ElementKind,
+  C4LayoutHint,
+  C4ElementShape,
+  C4Relationship,
+  C4Variant,
+} from './types.ts'
+
+// ============================================================================
+// C4 diagram parser
+//
+// Supported syntax (Mermaid C4 macros):
+//   Person / Person_Ext (alias, label, descr)
+//   System[Db|Queue][_Ext] (alias, label, descr)
+//   Container[Db|Queue][_Ext] (alias, label, techn, descr)
+//   Component[Db|Queue][_Ext] (alias, label, techn, descr)
+//   Boundary / Enterprise_Boundary / System_Boundary / Container_Boundary
+//     (alias, label[, type]) { ... }
+//   Deployment_Node / Node / Node_L / Node_R (alias, label, type, descr) { ... }
+//   Rel / BiRel / Rel_U|Up|D|Down|L|Left|R|Right|Back (from, to, label, techn)
+//   RelIndex (index, from, to, label, techn)
+//   title <text>
+//
+// `Rel_U/D/L/R` record a placement hint (`C4Relationship.layout`) the
+// renderers use to steer layout. Accepted and ignored (styling / layout
+// config this renderer does not honor): UpdateElementStyle, UpdateRelStyle, UpdateLayoutConfig, LAYOUT_*,
+// SHOW_LEGEND, SHOW_FLOATING_LEGEND, AddElementTag, AddRelTag,
+// AddBoundaryTag, RoleTag. Named arguments (`$tags="x"`, `$link=...`) are
+// dropped.
+// ============================================================================
+
+const HEADERS: Record<string, C4Variant> = {
+  c4context: 'context',
+  c4container: 'container',
+  c4component: 'component',
+  c4dynamic: 'dynamic',
+  c4deployment: 'deployment',
+}
+
+const IGNORED_MACRO =
+  /^(?:UpdateElementStyle|UpdateRelStyle|UpdateLayoutConfig|LAYOUT_[A-Z_]+|SHOW_LEGEND|SHOW_FLOATING_LEGEND|AddElementTag|AddRelTag|AddBoundaryTag|RoleTag)\b/
+
+const ELEMENT_NAME = /^(Person|System|Container|Component)(Db|Queue)?(_Ext)?$/
+const BOUNDARY_NAME =
+  /^(?:Boundary|Enterprise_Boundary|System_Boundary|Container_Boundary)$/
+const NODE_NAME = /^(?:Deployment_Node|Node|Node_L|Node_R)$/
+const REL_NAME =
+  /^(Rel|BiRel|Rel_U|Rel_Up|Rel_D|Rel_Down|Rel_L|Rel_Left|Rel_R|Rel_Right|Rel_Back|RelIndex)$/
+
+const BOUNDARY_TYPES: Record<string, string> = {
+  Enterprise_Boundary: 'ENTERPRISE',
+  System_Boundary: 'SYSTEM',
+  Container_Boundary: 'CONTAINER',
+}
+
+const REL_HINTS: Record<string, C4LayoutHint> = {
+  Rel_U: 'up',
+  Rel_Up: 'up',
+  Rel_D: 'down',
+  Rel_Down: 'down',
+  Rel_L: 'left',
+  Rel_Left: 'left',
+  Rel_R: 'right',
+  Rel_Right: 'right',
+}
+
+function unquote(a: string): string {
+  const t = a.trim()
+  const inner =
+    t.length >= 2 && t.startsWith('"') && t.endsWith('"') ? t.slice(1, -1) : t
+  return normalizeBrTags(inner)
+}
+
+/**
+ * Split a macro's argument list on top-level commas. Double-quoted strings
+ * may contain commas and parentheses; `$name=value` named arguments are
+ * dropped. Returns null when a quote is unbalanced.
+ */
+function splitArgs(inner: string): string[] | null {
+  const raw: string[] = []
+  let cur = ''
+  let inQuote = false
+  for (const ch of inner) {
+    if (ch === '"') inQuote = !inQuote
+    if (ch === ',' && !inQuote) {
+      raw.push(cur)
+      cur = ''
+    } else {
+      cur += ch
+    }
+  }
+  if (inQuote) return null
+  raw.push(cur)
+  return raw
+    .map((a) => a.trim())
+    .filter((a) => !a.startsWith('$'))
+    .map(unquote)
+}
+
+/** `Name(args)` optionally followed by ` {`. */
+const MACRO = /^([A-Za-z_][A-Za-z0-9_]*)\s*\((.*)\)\s*(\{)?\s*$/
+
+function fail(stmt: Statement, msg: string): never {
+  throw new Error(`C4 diagram, line ${stmt.line}: ${msg} — "${stmt.text}"`)
+}
+
+/**
+ * Parse a Mermaid C4 diagram. Expects the first statement to be a
+ * `C4Context` / `C4Container` / `C4Component` / `C4Dynamic` /
+ * `C4Deployment` header.
+ */
+export function parseC4Diagram(lines: Statement[]): C4Diagram {
+  const variant = HEADERS[lines[0]?.text.trim().toLowerCase() ?? '']
+  if (!variant) {
+    throw new Error(
+      `C4 diagram: expected a header of C4Context, C4Container, C4Component, C4Dynamic or C4Deployment, got "${lines[0]?.text ?? ''}"`,
+    )
+  }
+
+  const diagram: C4Diagram = {
+    variant,
+    elements: [],
+    boundaries: [],
+    relationships: [],
+  }
+  const aliases = new Set<string>()
+  const stack: C4Boundary[] = []
+  /** Boundary declared on the previous statement without an inline `{`. */
+  let pendingBoundary: C4Boundary | undefined
+
+  const claim = (stmt: Statement, alias: string | undefined): string => {
+    if (!alias) fail(stmt, 'missing alias (first argument)')
+    if (aliases.has(alias)) fail(stmt, `duplicate alias "${alias}"`)
+    aliases.add(alias)
+    return alias
+  }
+
+  for (let i = 1; i < lines.length; i++) {
+    const stmt = lines[i]!
+    const line = stmt.text
+
+    if (line === '}') {
+      if (stack.length === 0) fail(stmt, 'unmatched "}"')
+      stack.pop()
+      continue
+    }
+    // Brace on its own line, directly after a boundary macro.
+    if (line === '{') {
+      if (!pendingBoundary) fail(stmt, 'unexpected "{"')
+      stack.push(pendingBoundary)
+      pendingBoundary = undefined
+      continue
+    }
+    pendingBoundary = undefined
+
+    const titleMatch = line.match(/^title(?:\s+(.*))?$/i)
+    if (titleMatch) {
+      diagram.title = normalizeBrTags((titleMatch[1] ?? '').trim())
+      continue
+    }
+
+    if (IGNORED_MACRO.test(line)) continue
+
+    const m = line.match(MACRO)
+    if (!m) fail(stmt, 'unrecognized statement')
+    const name = m[1]!
+    const opensBlock = m[3] === '{'
+    const args = splitArgs(m[2]!)
+    if (!args) fail(stmt, 'unbalanced quotes')
+
+    const el = name.match(ELEMENT_NAME)
+    if (el) {
+      if (opensBlock) fail(stmt, `"${name}" cannot contain a block`)
+      const kind = el[1]!.toLowerCase() as C4ElementKind
+      const shape: C4ElementShape =
+        el[2] === 'Db' ? 'db' : el[2] === 'Queue' ? 'queue' : 'default'
+      const hasTech = kind === 'container' || kind === 'component'
+      const alias = claim(stmt, args[0])
+      const element: C4Element = {
+        alias,
+        kind,
+        shape,
+        external: el[3] !== undefined,
+        label: args[1] || alias,
+      }
+      const technology = hasTech ? args[2] : undefined
+      const description = hasTech ? args[3] : args[2]
+      if (technology) element.technology = technology
+      if (description) element.description = description
+      diagram.elements.push(element)
+      stack.at(-1)?.elementAliases.push(alias)
+      continue
+    }
+
+    if (BOUNDARY_NAME.test(name) || NODE_NAME.test(name)) {
+      const isNode = NODE_NAME.test(name)
+      const alias = claim(stmt, args[0])
+      const boundary: C4Boundary = {
+        alias,
+        label: args[1] || alias,
+        elementAliases: [],
+        children: [],
+      }
+      // Mermaid labels every frame with a type: the macro's own for the
+      // typed boundaries, else the explicit argument, else a default.
+      // (System_/Container_/Enterprise_Boundary take no type arg.)
+      const typed = BOUNDARY_TYPES[name]
+      if (typed) boundary.type = typed
+      else if (args[2] && (isNode || name === 'Boundary'))
+        boundary.type = args[2]
+      else boundary.type = isNode ? 'node' : 'system'
+      if (isNode && args[3]) boundary.description = args[3]
+      const parent = stack.at(-1)
+      if (parent) parent.children.push(boundary)
+      else diagram.boundaries.push(boundary)
+      if (opensBlock) stack.push(boundary)
+      else pendingBoundary = boundary
+      continue
+    }
+
+    const rel = name.match(REL_NAME)
+    if (rel) {
+      const indexed = name === 'RelIndex'
+      const a = indexed ? args.slice(1) : args
+      if (!a[0] || !a[1]) {
+        fail(stmt, 'a relationship needs "from" and "to" aliases')
+      }
+      const r: C4Relationship = {
+        from: a[0],
+        to: a[1],
+        label: a[2] ?? '',
+        bidirectional: name === 'BiRel',
+      }
+      if (a[3]) r.technology = a[3]
+      if (name === 'Rel_Back') r.reversed = true
+      const hint = REL_HINTS[name]
+      if (hint) r.layout = hint
+      diagram.relationships.push(r)
+      continue
+    }
+
+    fail(stmt, `unknown C4 macro "${name}"`)
+  }
+
+  if (stack.length > 0) {
+    throw new Error(
+      `C4 diagram: boundary "${stack.at(-1)!.alias}" is missing its closing "}"`,
+    )
+  }
+  // Mermaid ignores RelIndex's index argument: in C4Dynamic every relationship
+  // is numbered by its position in the source, and no other variant numbers.
+  if (diagram.variant === 'dynamic') {
+    diagram.relationships.forEach((r, i) => {
+      r.index = String(i + 1)
+    })
+  }
+  for (const r of diagram.relationships) {
+    for (const end of [r.from, r.to]) {
+      if (!aliases.has(end)) {
+        throw new Error(
+          `C4 diagram: relationship refers to undeclared alias "${end}"`,
+        )
+      }
+    }
+  }
+  return diagram
+}