@zombie-mermaid/mermaid-parser 3.1.0 → 3.2.0

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
+}

package/src/c4/types.ts

@@ -0,0 +1,136 @@
+import type { Direction, Point } from '@zombie-mermaid/core'
+
+// ============================================================================
+// C4 diagram model (C4Context / C4Container / C4Component / C4Dynamic /
+// C4Deployment). Prior art: lukilabs/beautiful-mermaid#34 and #71
+// (kristjanakkermann, devx) — see the changeset for attribution.
+// ============================================================================
+
+export type C4Variant =
+  'context' | 'container' | 'component' | 'dynamic' | 'deployment'
+
+export type C4ElementKind = 'person' | 'system' | 'container' | 'component'
+
+/** Visual variant of an element: plain box, database cylinder, or queue. */
+export type C4ElementShape = 'default' | 'db' | 'queue'
+
+export interface C4Element {
+  alias: string
+  kind: C4ElementKind
+  shape: C4ElementShape
+  /** `*_Ext` variants: outside the system being described. */
+  external: boolean
+  label: string
+  technology?: string
+  description?: string
+}
+
+export interface C4Boundary {
+  alias: string
+  label: string
+  /** Boundary type (`Boundary(a, "x", "type")`) or deployment node type. */
+  type?: string
+  description?: string
+  /** Aliases of elements declared directly inside this boundary. */
+  elementAliases: string[]
+  children: C4Boundary[]
+}
+
+/**
+ * Layout placement hint carried by `Rel_U`/`Rel_D`/`Rel_L`/`Rel_R` (and their
+ * long-form aliases): where `to` should sit relative to `from`. Plain `Rel`,
+ * `BiRel`, `RelIndex` and `Rel_Back` carry none.
+ */
+export type C4LayoutHint = 'up' | 'down' | 'left' | 'right'
+
+export interface C4Relationship {
+  from: string
+  to: string
+  label: string
+  technology?: string
+  /** `BiRel`: arrowheads at both ends. */
+  bidirectional: boolean
+  /**
+   * `Rel_Back`: the arrowhead points at `from` instead of `to`. `from`/`to`
+   * stay as declared, so layout and placement hints still follow them.
+   */
+  reversed?: boolean
+  /** `RelIndex(n, ...)` in C4Dynamic diagrams. */
+  index?: string
+  /** Placement hint from a directional `Rel_*` macro; see `C4LayoutHint`. */
+  layout?: C4LayoutHint
+}
+
+export interface C4Diagram {
+  variant: C4Variant
+  /**
+   * Top-level layout direction. Never set by the parser (C4 sources have no
+   * direction statement); only `RenderOptions.direction` sets it, via
+   * `withDirectionOverride`. Unset lays out top-to-bottom.
+   */
+  direction?: Direction
+  title?: string
+  /** Every element in declaration order, wherever it is nested. */
+  elements: C4Element[]
+  /** Top-level boundaries; elements outside any boundary are not listed. */
+  boundaries: C4Boundary[]
+  relationships: C4Relationship[]
+}
+
+// ----------------------------------------------------------------------------
+// Positioned model (SVG layout output)
+// ----------------------------------------------------------------------------
+
+export interface PositionedC4Element extends C4Element {
+  x: number
+  y: number
+  width: number
+  height: number
+  /** Name wrapped to the box width, one entry per line. */
+  nameLines: string[]
+  /** Description wrapped to the box width, one entry per line. */
+  descriptionLines: string[]
+}
+
+export interface PositionedC4Boundary {
+  alias: string
+  label: string
+  type?: string
+  description?: string
+  x: number
+  y: number
+  width: number
+  height: number
+  /** Nesting depth, 0 for a top-level boundary. */
+  depth: number
+  /** Centre line of the title, below the frame's top edge (Mermaid's layout). */
+  labelY?: number
+  /** Centre line of the `[type]` text, below the frame's top edge. */
+  typeY?: number
+  /** Centre line of the description (deployment nodes), below the top edge. */
+  descrY?: number
+}
+
+export interface PositionedC4Relationship extends C4Relationship {
+  /** The start and end of the line (a straight chord when `curve` is unset). */
+  points: Point[]
+  /** Control point of a quadratic curve from the first to the last point. */
+  curve?: Point
+  /** Centre of the label block, when the relationship has label text. */
+  labelPosition?: Point
+  /** Centre x of the `[technology]` line, which Mermaid lays out on its own. */
+  technologyX?: number
+}
+
+export interface PositionedC4Diagram {
+  variant: C4Variant
+  title?: string
+  width: number
+  height: number
+  /** Where the title baseline sits (centre x, y), when there is a title. */
+  titlePosition?: Point
+  elements: PositionedC4Element[]
+  /** Outer boundaries first, so inner ones paint on top. */
+  boundaries: PositionedC4Boundary[]
+  relationships: PositionedC4Relationship[]
+}

package/src/index.ts

@@ -28,6 +28,14 @@
 // creating a cycle — see `packages/core/src/direction.ts`'s header.
 // ============================================================================
 
+export * from './architecture/parser.ts'
+export * from './architecture/types.ts'
+export * from './architecture/to-graph.ts'
+
+export * from './c4/parser.ts'
+export * from './c4/types.ts'
+export * from './c4/format.ts'
+
 export * from './class/parser.ts'
 export * from './class/types.ts'
 export * from './class/format.ts'