@zombie-mermaid/mermaid-parser 3.1.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zombie-mermaid/mermaid-parser",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "license": "MIT",
   "description": "Parsers for class, ER, sequence, and XY chart diagrams — the per-type parse functions both svg-renderer and ascii-renderer import directly.",
   "repository": {
@@ -35,6 +35,6 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@zombie-mermaid/core": "3.1.0"
+    "@zombie-mermaid/core": "3.2.0"
   }
 }

package/src/__tests__/architecture-parser.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect } from 'vitest'
+import { splitStatements } from '@zombie-mermaid/core'
+import { parseArchitecture } from '../index.ts'
+
+const parse = (src: string) => parseArchitecture(splitStatements(src))
+const body = (b: string) => parse(`architecture-beta\n${b}`)
+
+describe('parseArchitecture', () => {
+  it('accepts both header spellings', () => {
+    expect(parse('architecture-beta\nservice a').services).toHaveLength(1)
+    expect(parse('architecture\nservice a').services).toHaveLength(1)
+  })
+
+  it('parses a group with icon, title and no parent', () => {
+    expect(body('group api(cloud)[API]').groups).toEqual([
+      { id: 'api', icon: 'cloud', title: 'API', parent: undefined },
+    ])
+  })
+
+  it('parses nested groups, including a parent declared later', () => {
+    const d = body('group inner in outer\ngroup outer')
+    expect(d.groups.map((g) => [g.id, g.parent])).toEqual([
+      ['inner', 'outer'],
+      ['outer', undefined],
+    ])
+  })
+
+  it('parses services with and without icon/title/parent', () => {
+    const d = body(
+      'group g\nservice a(database)[DB] in g\nservice b[Bee]\nservice c(server)\nservice d',
+    )
+    expect(d.services).toEqual([
+      { id: 'a', icon: 'database', title: 'DB', parent: 'g' },
+      { id: 'b', icon: undefined, title: 'Bee', parent: undefined },
+      { id: 'c', icon: 'server', title: 'c', parent: undefined },
+      { id: 'd', icon: undefined, title: 'd', parent: undefined },
+    ])
+  })
+
+  it('strips quotes from custom icon names and keeps hyphenated ids', () => {
+    const d = body('service my-svc("logos:aws")[AWS]')
+    expect(d.services[0]).toMatchObject({ id: 'my-svc', icon: 'logos:aws' })
+  })
+
+  it('parses junctions with and without a parent', () => {
+    const d = body('group g\njunction j1 in g\njunction j2')
+    expect(d.junctions).toEqual([
+      { id: 'j1', parent: 'g' },
+      { id: 'j2', parent: undefined },
+    ])
+  })
+
+  it('ignores align statements', () => {
+    const d = body('service a\nservice b\nalign row a b\nalign column a b')
+    expect(d.edges).toEqual([])
+    expect(d.services).toHaveLength(2)
+  })
+
+  it.each([
+    ['--', false, false],
+    ['-->', false, true],
+    ['<--', true, false],
+    ['<-->', true, true],
+  ])('parses the %s edge operator', (op, start, end) => {
+    const [e] = body(`service a\nservice b\na:R ${op} L:b`).edges
+    expect(e).toMatchObject({ arrowStart: start, arrowEnd: end })
+  })
+
+  it.each(['L', 'R', 'T', 'B'] as const)(
+    'parses source port %s and target port %s',
+    (p) => {
+      for (const q of ['L', 'R', 'T', 'B'] as const) {
+        const [e] = body(`service a\nservice b\na:${p} -- ${q}:b`).edges
+        expect(e).toMatchObject({
+          source: 'a',
+          sourcePort: p,
+          target: 'b',
+          targetPort: q,
+          sourceGroup: false,
+          targetGroup: false,
+        })
+      }
+    },
+  )
+
+  it('parses {group} modifiers on either end', () => {
+    const d = body(
+      'group g\ngroup h\nservice a in g\nservice b in h\na{group}:R -- L:b\na:R -- L:b{group}\na{group}:R -- L:b{group}',
+    )
+    expect(d.edges.map((e) => [e.sourceGroup, e.targetGroup])).toEqual([
+      [true, false],
+      [false, true],
+      [true, true],
+    ])
+  })
+
+  it('allows edges to junctions and {group} on a junction', () => {
+    const d = body('group g\njunction j in g\nservice a\na:R -- L:j{group}')
+    expect(d.edges[0]).toMatchObject({ target: 'j', targetGroup: true })
+  })
+
+  it('allows an edge to precede the declaration it refers to', () => {
+    const d = body('a:R -- L:b\nservice a\nservice b')
+    expect(d.edges).toHaveLength(1)
+  })
+
+  it('splits statements on semicolons and ignores comments', () => {
+    const d = parse(
+      'architecture-beta\n%% a comment\nservice a; service b\na:R -- L:b',
+    )
+    expect(d.services.map((s) => s.id)).toEqual(['a', 'b'])
+  })
+
+  it('converts <br> in titles to newlines', () => {
+    const d = body('service a[Line1<br/>Line2]')
+    expect(d.services[0]?.title).toBe('Line1\nLine2')
+  })
+
+  describe('errors', () => {
+    it.each([
+      ['service a\nservice a', /line 3.*duplicate id "a"/s],
+      ['group a\nservice a', /line 3.*duplicate id "a"/s],
+      ['service a\njunction a', /line 3.*duplicate id "a"/s],
+      ['service a in nope', /line 2.*must name a declared group/s],
+      ['service a\nservice b in a', /line 3.*must name a declared group/s],
+      ['junction j in nope', /line 2.*must name a declared group/s],
+      ['group g in g', /line 2.*cannot be inside itself/s],
+      ['group a in b\ngroup b in c\ngroup c in a', /nested inside itself/],
+      ['service a\na:R -- L:zzz', /line 3.*unknown id "zzz"/s],
+      ['service a\nzzz:R -- L:a', /line 3.*unknown id "zzz"/s],
+      ['group g\nservice a\na:R -- L:g', /line 4.*not the group "g"/s],
+      ['group g\nservice a\ng:R -- L:a', /line 4.*not the group "g"/s],
+      ['service a\nservice b\na{group}:R -- L:b', /line 4.*needs "a" to be/s],
+      ['service a\nservice b\na:R -- L:b{group}', /line 4.*needs "b" to be/s],
+      ['service a\nbogus line', /line 3.*unrecognized statement/s],
+      ['service a\nservice b\na:X -- L:b', /line 4.*unrecognized/s],
+      ['service a\nservice b\na:R - L:b', /line 4.*unrecognized/s],
+      ['service a\nservice b\na R -- L:b', /line 4.*unrecognized/s],
+      ['align row a', /line 2.*unrecognized/s],
+      ['group', /line 2.*unrecognized/s],
+    ])('rejects %j', (b, message) => {
+      expect(() => body(b)).toThrow(message)
+    })
+  })
+})

package/src/__tests__/architecture-to-graph.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest'
+import { splitStatements } from '@zombie-mermaid/core'
+import { parseArchitecture, architectureToGraph } from '../index.ts'
+
+const lower = (b: string) =>
+  architectureToGraph(
+    parseArchitecture(splitStatements(`architecture-beta\n${b}`)),
+  )
+const two = 'service a\nservice b\n'
+
+describe('architectureToGraph', () => {
+  it('maps icons to shapes and unknown icons to rectangles', () => {
+    const g = lower(
+      'service a(database)\nservice b(disk)\nservice c(cloud)\nservice d(internet)\nservice e(server)\nservice f("logos:aws")\nservice g',
+    )
+    const shapes = [...g.nodes.values()].map((n) => n.shape)
+    expect(shapes).toEqual([
+      'cylinder',
+      'cylinder',
+      'stadium',
+      'circle',
+      'rectangle',
+      'rectangle',
+      'rectangle',
+    ])
+  })
+
+  it('nests groups three deep and places nodes in their own group', () => {
+    const g = lower(
+      'group a\ngroup b in a\ngroup c in b\nservice s in c\nservice t in a\njunction j in b',
+    )
+    const a = g.subgraphs[0]!
+    expect(g.subgraphs).toHaveLength(1)
+    expect(a.nodeIds).toEqual(['t'])
+    expect(a.children[0]?.id).toBe('b')
+    expect(a.children[0]?.nodeIds).toEqual(['j'])
+    expect(a.children[0]?.children[0]).toMatchObject({
+      id: 'c',
+      nodeIds: ['s'],
+    })
+  })
+
+  it('keeps sibling top-level groups as separate roots', () => {
+    const g = lower('group a\ngroup b\nservice s in a\nservice t in b')
+    expect(g.subgraphs.map((s) => s.id)).toEqual(['a', 'b'])
+  })
+
+  it('draws a junction as an unlabelled filled circle', () => {
+    expect(lower('junction j').nodes.get('j')).toEqual({
+      id: 'j',
+      label: '',
+      shape: 'filled-circle',
+    })
+  })
+
+  describe('{group} edges', () => {
+    it('attaches the source end to the enclosing group', () => {
+      const [e] = lower(
+        'group g\nservice a in g\nservice b\na{group}:R -- L:b',
+      ).edges
+      expect(e).toMatchObject({ source: 'g', target: 'b' })
+    })
+
+    it('attaches the target end to the enclosing group', () => {
+      const [e] = lower(
+        'group g\nservice a in g\nservice b\nb:R -- L:a{group}',
+      ).edges
+      expect(e).toMatchObject({ source: 'b', target: 'g' })
+    })
+
+    it('attaches both ends, and uses the immediate (innermost) group', () => {
+      const [e] = lower(
+        'group o\ngroup i in o\nservice a in i\njunction j in o\na{group}:R -- L:j{group}',
+      ).edges
+      expect(e).toMatchObject({ source: 'i', target: 'o' })
+    })
+
+    it('follows an edge reversal', () => {
+      const [e] = lower(
+        'group g\nservice a in g\nservice b\na{group}:L -- R:b',
+      ).edges
+      expect(e).toMatchObject({ source: 'b', target: 'g' })
+    })
+  })
+
+  describe('flow direction', () => {
+    it.each([
+      ['a:R -- L:b', 'LR'],
+      ['a:L -- R:b', 'LR'],
+      ['a:B -- T:b', 'TB'],
+      ['a:T -- B:b', 'TB'],
+      // Tie goes to LR.
+      ['a:R -- T:b', 'LR'],
+      ['a:R -- L:b\na:R -- B:b\na:T -- B:b', 'LR'],
+      ['a:B -- T:b\na:R -- B:b', 'TB'],
+    ])('%j -> %s', (edges, dir) => {
+      expect(lower(two + edges).direction).toBe(dir)
+    })
+
+    it('defaults to LR with no edges', () => {
+      expect(lower('service a').direction).toBe('LR')
+    })
+  })
+
+  describe('edge reversal', () => {
+    it.each([
+      // [edge, source, target, arrowStart, arrowEnd]
+      ['a:R -- L:b', 'a', 'b'],
+      ['a:L -- R:b', 'b', 'a'],
+      ['a:R -- R:b', 'a', 'b'],
+      // A back-side target port wins: the edge is not reversed.
+      ['a:L -- L:b', 'a', 'b'],
+    ])('LR: %s runs %s -> %s', (edge, source, target) => {
+      const [e] = lower(two + edge).edges
+      expect([e?.source, e?.target]).toEqual([source, target])
+    })
+
+    it.each([
+      ['a:B -- T:b', 'a', 'b'],
+      ['a:T -- B:b', 'b', 'a'],
+    ])('TB: %s runs %s -> %s', (edge, source, target) => {
+      const [e] = lower(two + edge).edges
+      expect([e?.source, e?.target]).toEqual([source, target])
+    })
+
+    it('does not reverse an edge whose ports are on the other axis', () => {
+      // Direction is TB (two vertical edges outweigh one horizontal), and
+      // L/R ports say nothing about top/bottom order.
+      const g = lower(two + 'a:L -- R:b\na:B -- T:b\na:B -- T:b')
+      expect(g.direction).toBe('TB')
+      expect([g.edges[0]?.source, g.edges[0]?.target]).toEqual(['a', 'b'])
+    })
+
+    it.each([
+      ['a:R -- L:b', false, false],
+      ['a:R --> L:b', false, true],
+      ['a:R <-- L:b', true, false],
+      ['a:R <--> L:b', true, true],
+    ])('keeps arrowheads on %s', (edge, start, end) => {
+      expect(lower(two + edge).edges[0]).toMatchObject({
+        hasArrowStart: start,
+        hasArrowEnd: end,
+        style: 'solid',
+      })
+    })
+
+    it.each([
+      // Reversed edges swap which end carries the arrowhead.
+      ['a:L --> R:b', true, false],
+      ['a:L <-- R:b', false, true],
+      ['a:L <--> R:b', true, true],
+      ['a:L -- R:b', false, false],
+    ])('swaps arrowheads when reversing %s', (edge, start, end) => {
+      expect(lower(two + edge).edges[0]).toMatchObject({
+        source: 'b',
+        target: 'a',
+        hasArrowStart: start,
+        hasArrowEnd: end,
+      })
+    })
+  })
+
+  it('carries no flowchart styling', () => {
+    const g = lower(two + 'a:R -- L:b')
+    expect(g.classDefs.size).toBe(0)
+    expect(g.nodeStyles.size).toBe(0)
+    expect(g.linkStyles.size).toBe(0)
+  })
+})

package/src/__tests__/c4-parser.test.ts

@@ -0,0 +1,265 @@
+import { describe, it, expect } from 'vitest'
+import { splitStatements } from '@zombie-mermaid/core'
+import { parseC4Diagram } from '../index.ts'
+
+const parse = (src: string) => parseC4Diagram(splitStatements(src))
+
+describe('parseC4Diagram', () => {
+  it('parses every variant header', () => {
+    const cases = [
+      ['C4Context', 'context'],
+      ['C4Container', 'container'],
+      ['C4Component', 'component'],
+      ['C4Dynamic', 'dynamic'],
+      ['C4Deployment', 'deployment'],
+    ] as const
+    for (const [header, variant] of cases) {
+      expect(parse(header).variant).toBe(variant)
+    }
+  })
+
+  it('rejects a non-C4 header', () => {
+    expect(() => parse('flowchart TD')).toThrow(
+      /expected a header of C4Context/,
+    )
+  })
+
+  it('parses persons, systems and external variants', () => {
+    const d = parse(`C4Context
+  title Bank
+  Person(c, "Customer", "A user")
+  Person_Ext(x, "Auditor")
+  System(s, "Banking", "Core")
+  SystemDb_Ext(db, "Ledger", "Books")
+  SystemQueue(q, "Bus")`)
+    expect(d.title).toBe('Bank')
+    expect(
+      d.elements.map((e) => [e.alias, e.kind, e.shape, e.external]),
+    ).toEqual([
+      ['c', 'person', 'default', false],
+      ['x', 'person', 'default', true],
+      ['s', 'system', 'default', false],
+      ['db', 'system', 'db', true],
+      ['q', 'system', 'queue', false],
+    ])
+    expect(d.elements[0]).toMatchObject({
+      label: 'Customer',
+      description: 'A user',
+    })
+  })
+
+  it('reads technology before description for containers and components', () => {
+    const d = parse(`C4Container
+  Container(api, "API", "Node.js", "Serves JSON")
+  ComponentDb(store, "Store", "Postgres")`)
+    expect(d.elements[0]).toMatchObject({
+      technology: 'Node.js',
+      description: 'Serves JSON',
+    })
+    expect(d.elements[1]).toMatchObject({
+      kind: 'component',
+      shape: 'db',
+      technology: 'Postgres',
+    })
+    expect(d.elements[1]!.description).toBeUndefined()
+  })
+
+  it('keeps commas and parentheses inside quoted arguments', () => {
+    const d = parse('C4Context\nSystem(s, "A, B (C)", "one, two")')
+    expect(d.elements[0]).toMatchObject({
+      label: 'A, B (C)',
+      description: 'one, two',
+    })
+  })
+
+  it('drops $named arguments', () => {
+    const d = parse(
+      'C4Context\nSystem(s, "S", "d", $tags="t", $link="https://x.test")',
+    )
+    expect(d.elements[0]).toMatchObject({ label: 'S', description: 'd' })
+  })
+
+  it('nests boundaries and assigns elements to the innermost one', () => {
+    const d = parse(`C4Container
+  Enterprise_Boundary(e, "Corp") {
+    System_Boundary(sb, "Sys") {
+      Container(a, "A", "Go")
+    }
+    Person(p, "P")
+  }
+  Container(out, "Out", "Go")`)
+    expect(d.boundaries).toHaveLength(1)
+    const e = d.boundaries[0]!
+    expect(e.elementAliases).toEqual(['p'])
+    expect(e.children[0]).toMatchObject({ alias: 'sb', elementAliases: ['a'] })
+    expect(d.elements.map((x) => x.alias)).toEqual(['a', 'p', 'out'])
+  })
+
+  it('accepts a brace on its own line and a boundary type', () => {
+    const d = parse(`C4Context
+  Boundary(b, "B", "region")
+  {
+    System(s, "S")
+  }`)
+    expect(d.boundaries[0]).toMatchObject({
+      alias: 'b',
+      type: 'region',
+      elementAliases: ['s'],
+    })
+  })
+
+  it('parses deployment nodes as boundaries with type and description', () => {
+    const d = parse(`C4Deployment
+  Deployment_Node(n, "Server", "Ubuntu", "Prod box") {
+    Container(app, "App", "Java")
+  }`)
+    expect(d.boundaries[0]).toMatchObject({
+      type: 'Ubuntu',
+      description: 'Prod box',
+      elementAliases: ['app'],
+    })
+  })
+
+  it('parses relationships, BiRel, directional variants and RelIndex', () => {
+    const d = parse(`C4Dynamic
+  System(a, "A")
+  System(b, "B")
+  Rel(a, b, "Calls", "HTTPS")
+  BiRel(a, b, "Syncs")
+  Rel_Back(b, a, "Replies")
+  RelIndex(1, a, b, "First")`)
+    expect(d.relationships).toEqual([
+      {
+        from: 'a',
+        to: 'b',
+        label: 'Calls',
+        technology: 'HTTPS',
+        bidirectional: false,
+        index: '1',
+      },
+      { from: 'a', to: 'b', label: 'Syncs', bidirectional: true, index: '2' },
+      {
+        from: 'b',
+        to: 'a',
+        label: 'Replies',
+        bidirectional: false,
+        reversed: true,
+        index: '3',
+      },
+      { from: 'a', to: 'b', label: 'First', bidirectional: false, index: '4' },
+    ])
+  })
+
+  it('numbers relationships by position in C4Dynamic only, ignoring the RelIndex argument (as Mermaid does)', () => {
+    const src = (head: string) => `${head}
+  System(a, "A")
+  System(b, "B")
+  RelIndex(9, a, b, "First")
+  Rel(b, a, "Second")`
+    const dyn = parse(src('C4Dynamic')).relationships.map((r) => r.index)
+    expect(dyn).toEqual(['1', '2'])
+    const ctx = parse(src('C4Context')).relationships.map((r) => r.index)
+    expect(ctx).toEqual([undefined, undefined])
+  })
+
+  it("gives every boundary Mermaid's type text", () => {
+    const d = parse(`C4Deployment
+  Enterprise_Boundary(e, "E") {
+    System_Boundary(s, "S") {
+      Container_Boundary(c, "C") {
+        Boundary(g, "G")
+        Boundary(t, "T", "region")
+        Node(n, "N")
+        Deployment_Node(m, "M", "Ubuntu")
+      }
+    }
+  }`)
+    const types = new Map<string, string | undefined>()
+    const walk = (bs: typeof d.boundaries): void =>
+      bs.forEach((b) => {
+        types.set(b.alias, b.type)
+        walk(b.children)
+      })
+    walk(d.boundaries)
+    expect(Object.fromEntries(types)).toEqual({
+      e: 'ENTERPRISE',
+      s: 'SYSTEM',
+      c: 'CONTAINER',
+      g: 'system',
+      t: 'region',
+      n: 'node',
+      m: 'Ubuntu',
+    })
+  })
+
+  it('records Rel_U/D/L/R placement hints and leaves the rest unhinted', () => {
+    const d = parse(`C4Context
+  System(a, "A")
+  System(b, "B")
+  Rel_U(a, b, "1")
+  Rel_Up(a, b, "2")
+  Rel_D(a, b, "3")
+  Rel_Down(a, b, "4")
+  Rel_L(a, b, "5")
+  Rel_Left(a, b, "6")
+  Rel_R(a, b, "7")
+  Rel_Right(a, b, "8")
+  Rel(a, b, "9")
+  Rel_Back(a, b, "10")`)
+    expect(d.relationships.map((r) => r.layout)).toEqual([
+      'up',
+      'up',
+      'down',
+      'down',
+      'left',
+      'left',
+      'right',
+      'right',
+      undefined,
+      undefined,
+    ])
+  })
+
+  it('silently ignores style and layout macros', () => {
+    const d = parse(`C4Context
+  System(a, "A")
+  UpdateElementStyle(a, $bgColor="red")
+  UpdateLayoutConfig($c4ShapeInRow="2")
+  SHOW_LEGEND()`)
+    expect(d.elements).toHaveLength(1)
+  })
+
+  describe('errors', () => {
+    it('reports duplicate aliases with a line number', () => {
+      expect(() => parse('C4Context\nSystem(a, "A")\nSystem(a, "B")')).toThrow(
+        /line 3: duplicate alias "a"/,
+      )
+    })
+    it('reports unknown macros', () => {
+      expect(() => parse('C4Context\nWidget(a, "A")')).toThrow(
+        /unknown C4 macro "Widget"/,
+      )
+    })
+    it('reports unrecognized statements', () => {
+      expect(() => parse('C4Context\nnonsense here')).toThrow(
+        /unrecognized statement/,
+      )
+    })
+    it('reports relationships to undeclared aliases', () => {
+      expect(() =>
+        parse('C4Context\nSystem(a, "A")\nRel(a, ghost, "x")'),
+      ).toThrow(/undeclared alias "ghost"/)
+    })
+    it('reports unbalanced braces', () => {
+      expect(() =>
+        parse('C4Context\nBoundary(b, "B") {\nSystem(a, "A")'),
+      ).toThrow(/missing its closing/)
+      expect(() => parse('C4Context\n}')).toThrow(/unmatched "}"/)
+    })
+    it('reports unbalanced quotes', () => {
+      expect(() => parse('C4Context\nSystem(a, "A)')).toThrow(
+        /unbalanced quotes/,
+      )
+    })
+  })
+})