@zombie-mermaid/ascii-renderer 2.2.1

package/src/__tests__/ascii-sequence-box-group.test.ts

@@ -0,0 +1,159 @@
+// ============================================================================
+// ASCII sequence diagrams — `box ... end` participant grouping (#419)
+//
+// A non-empty box becomes a labelled bracket around its members' header
+// boxes, and an unlabelled bracket around their footer boxes, spanning from
+// the leftmost to the rightmost member. Colour is not representable in
+// ASCII and is ignored (only the label, if any, is drawn).
+// ============================================================================
+
+import { describe, it, expect } from 'vitest'
+import { renderMermaidASCII } from '@zombie-mermaid/ascii-renderer'
+
+describe('ASCII sequence diagrams – box...end', () => {
+  const source = `sequenceDiagram
+  box Aqua Group 1
+  participant A
+  participant B
+  end
+  participant C
+  A->>B: hello
+  B->>C: world`
+
+  it('draws a labelled bracket around the grouped participants (Unicode)', () => {
+    const result = renderMermaidASCII(source, { useAscii: false })
+    expect(result).toBe(
+      [
+        ' ┌─ Group 1 ────────┐            ',
+        ' │ ┌───┐      ┌───┐ │    ┌───┐   ',
+        ' │ │ A │      │ B │ │    │ C │   ',
+        ' │ └─┬─┘      └─┬─┘ │    └─┬─┘   ',
+        ' └───┼──────────┼───┘      │     ',
+        '     │          │          │     ',
+        '     │  hello   │          │     ',
+        '     │──────────▶          │     ',
+        '     │          │          │     ',
+        '     │          │  world   │     ',
+        '     │          │──────────▶     ',
+        '     │          │          │     ',
+        ' ┌───┼──────────┼───┐      │     ',
+        ' │ ┌─┴─┐      ┌─┴─┐ │    ┌─┴─┐   ',
+        ' │ │ A │      │ B │ │    │ C │   ',
+        ' │ └───┘      └───┘ │    └───┘   ',
+        ' └──────────────────┘            ',
+      ].join('\n'),
+    )
+  })
+
+  it('uses the plain-ASCII cross and corners in ASCII mode', () => {
+    const result = renderMermaidASCII(source, { useAscii: true })
+    expect(result).toBe(
+      [
+        ' +- Group 1 --------+            ',
+        ' | +---+      +---+ |    +---+   ',
+        ' | | A |      | B | |    | C |   ',
+        ' | +---+      +---+ |    +---+   ',
+        ' +---+----------+---+      |     ',
+        '     |          |          |     ',
+        '     |  hello   |          |     ',
+        '     |---------->          |     ',
+        '     |          |          |     ',
+        '     |          |  world   |     ',
+        '     |          |---------->     ',
+        '     |          |          |     ',
+        ' +---+----------+---+      |     ',
+        ' | +---+      +---+ |    +---+   ',
+        ' | | A |      | B | |    | C |   ',
+        ' | +---+      +---+ |    +---+   ',
+        ' +------------------+            ',
+      ].join('\n'),
+    )
+  })
+
+  it('draws an unlabelled bracket for a box with a colour but no label', () => {
+    const result = renderMermaidASCII(
+      `sequenceDiagram
+  box Aqua
+  participant A
+  participant B
+  end
+  A->>B: hi`,
+      { useAscii: false },
+    )
+    expect(result).toBe(
+      [
+        ' ┌─────────────────┐  ',
+        ' │ ┌───┐     ┌───┐ │  ',
+        ' │ │ A │     │ B │ │  ',
+        ' │ └─┬─┘     └─┬─┘ │  ',
+        ' └───┼─────────┼───┘  ',
+        '     │         │      ',
+        '     │   hi    │      ',
+        '     │─────────▶      ',
+        '     │         │      ',
+        ' ┌───┼─────────┼───┐  ',
+        ' │ ┌─┴─┐     ┌─┴─┐ │  ',
+        ' │ │ A │     │ B │ │  ',
+        ' │ └───┘     └───┘ │  ',
+        ' └─────────────────┘  ',
+      ].join('\n'),
+    )
+  })
+
+  it('lets a loop opened inside a box nest cleanly inside the bracket', () => {
+    const result = renderMermaidASCII(
+      `sequenceDiagram
+  box G1
+  participant A
+  participant B
+  loop every day
+  A->>B: hi
+  end
+  end
+  A->>B: bye`,
+      { useAscii: false },
+    )
+    expect(result).toBe(
+      [
+        ' ┌─ G1 ────────────┐  ',
+        ' │ ┌───┐     ┌───┐ │  ',
+        ' │ │ A │     │ B │ │  ',
+        ' │ └─┬─┘     └─┬─┘ │  ',
+        ' └───┼─────────┼───┘  ',
+        '     │         │      ',
+        ' ┌loop [every day]─┐  ',
+        ' │   │         │   │  ',
+        ' │   │   hi    │   │  ',
+        ' │   │─────────▶   │  ',
+        ' │   │         │   │  ',
+        ' └─────────────────┘  ',
+        '     │         │      ',
+        '     │   bye   │      ',
+        '     │─────────▶      ',
+        '     │         │      ',
+        ' ┌───┼─────────┼───┐  ',
+        ' │ ┌─┴─┐     ┌─┴─┐ │  ',
+        ' │ │ A │     │ B │ │  ',
+        ' │ └───┘     └───┘ │  ',
+        ' └─────────────────┘  ',
+      ].join('\n'),
+    )
+  })
+
+  it('does not draw a bracket for a box with no members', () => {
+    const withEmptyBox = renderMermaidASCII(
+      `sequenceDiagram
+  box Empty
+  end
+  A->>B: hi`,
+      { useAscii: false },
+    )
+    const withoutBox = renderMermaidASCII(
+      `sequenceDiagram
+  A->>B: hi`,
+      { useAscii: false },
+    )
+    expect(withEmptyBox).not.toContain('Empty')
+    expect(withEmptyBox).toBe(withoutBox)
+  })
+})

package/src/__tests__/ascii-sequence-cjk-width.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Regression tests for issue #334 — sequence-diagram participant boxes and
+ * message labels don't account for double-width CJK characters, so box
+ * borders no longer line up with their content once the diagram contains
+ * Japanese/Korean/Chinese text.
+ *
+ * This is the same bug class already fixed for flowchart boxes (#66,
+ * `ascii-cjk-width.test.ts`) and class/ER boxes (#182,
+ * `ascii-multibox-cjk-width.test.ts`) — `src/ascii/sequence.ts` measured and
+ * wrote actor-box content, message labels, block headers/dividers, and note
+ * content by UTF-16 code unit (`.length` / per-code-unit `for` loops)
+ * instead of the display-width-aware helpers in `src/ascii/display-width.ts`
+ * (`displayWidth` / `toDisplayCells`), which `maxLineWidth`
+ * (`multiline-utils.ts`) already used correctly for *sizing* — only the
+ * *drawing* loops were the gap.
+ *
+ * Width is measured with `terminalDisplayWidth`, an oracle independently
+ * re-implemented from `src/ascii/display-width.ts` (see the shared helper's
+ * own doc comment), so these tests verify rendered output against an
+ * authority separate from the implementation under test.
+ *
+ * NOTE on the Unicode-charset arrowhead glyphs (▶ ◀ ◁ ▷): these are
+ * pre-existing, unrelated to #334, and out of scope here. `isWideChar`
+ * (text-metrics.ts) treats any `\p{Extended_Pictographic}` code point as
+ * double-width, which also matches these geometric-shape arrowheads even
+ * though their Unicode East Asian Width property is "Ambiguous" (narrow in
+ * a default terminal locale) — so a row containing one of them measures one
+ * column wider than an otherwise-identical row without one, in *every*
+ * Unicode-charset sequence diagram, CJK or not. `assertUniformDisplayWidth`
+ * (used unmodified by the flowchart/class/ER suites, which draw ASCII
+ * `>`/`<`/`^`/`v` arrowheads instead) would spuriously fail on any arrow row
+ * here, so this file measures specific row pairs instead of whole-diagram
+ * uniformity, and separately guards that only arrowhead-glyph rows are ever
+ * the odd one out.
+ */
+import { describe, it, expect } from 'vitest'
+import { renderMermaidASCII } from '@zombie-mermaid/ascii-renderer'
+import { terminalDisplayWidth } from './helpers/terminal-display-width.ts'
+
+const ARROWHEAD_GLYPHS = ['▶', '◀', '◁', '▷']
+
+/** True if `line` contains one of the ambiguous-width arrowhead glyphs. */
+function hasArrowheadGlyph(line: string): boolean {
+  return ARROWHEAD_GLYPHS.some((g) => line.includes(g))
+}
+
+/**
+ * Every rendered row shares one terminal display width, *except* rows
+ * containing an arrowhead glyph (see the file-level doc comment) — those
+ * are allowed to be exactly one column wider than the rest.
+ */
+function assertUniformWidthIgnoringArrowheads(ascii: string): void {
+  const lines = ascii.split('\n')
+  const widths = lines.map(terminalDisplayWidth)
+  const plainWidths = widths.filter((_, i) => !hasArrowheadGlyph(lines[i]!))
+  const expected = plainWidths[0]
+  for (let i = 0; i < lines.length; i++) {
+    const allowance = hasArrowheadGlyph(lines[i]!) ? 1 : 0
+    expect(
+      widths[i],
+      `line ${i} (${JSON.stringify(lines[i])}) has display width ${widths[i]}, expected ${expected} (+${allowance} allowed for an arrowhead glyph)`,
+    ).toBe(expected! + allowance)
+  }
+}
+
+/**
+ * Find the line containing `needle` and the line directly above it, and
+ * assert they occupy the same terminal display width — the direct
+ * manifestation of "border lines up with its own content" that the issue
+ * reports (border 28 columns vs. content 33 columns for the exact repro).
+ */
+function assertContentMatchesBorderAbove(ascii: string, needle: string): void {
+  const lines = ascii.split('\n')
+  const contentIndex = lines.findIndex((l) => l.includes(needle))
+  expect(contentIndex).toBeGreaterThan(0)
+  const contentLine = lines[contentIndex]!
+  const borderLine = lines[contentIndex - 1]!
+  expect(
+    terminalDisplayWidth(contentLine),
+    `content row ${JSON.stringify(contentLine)} vs. border row ${JSON.stringify(borderLine)}`,
+  ).toBe(terminalDisplayWidth(borderLine))
+}
+
+describe('ASCII sequence diagrams — CJK/wide-char box alignment (issue #334)', () => {
+  for (const useAscii of [false, true]) {
+    describe(useAscii ? 'ASCII charset' : 'Unicode charset', () => {
+      // Exact repro from the issue body.
+      const mermaid =
+        'sequenceDiagram\n  participant A as アリス\n  participant B as ボブ\n  A->>B: こんにちは'
+
+      it('renders the issue repro with every row sharing one display width (up to arrowheads)', () => {
+        const ascii = renderMermaidASCII(mermaid, {
+          useAscii,
+          colorMode: 'none',
+        })
+        assertUniformWidthIgnoringArrowheads(ascii)
+      })
+
+      it('aligns the header participant box border with its CJK content', () => {
+        const ascii = renderMermaidASCII(mermaid, {
+          useAscii,
+          colorMode: 'none',
+        })
+        assertContentMatchesBorderAbove(ascii, 'アリス')
+      })
+
+      it('aligns the footer participant box border with its CJK content', () => {
+        const ascii = renderMermaidASCII(mermaid, {
+          useAscii,
+          colorMode: 'none',
+        })
+        const lines = ascii.split('\n')
+        // The footer box repeats the same label — its content row is the
+        // *last* line containing it, not the header's (first) occurrence.
+        const contentIndex = lines
+          .map((l) => l.includes('アリス'))
+          .lastIndexOf(true)
+        expect(contentIndex).toBeGreaterThan(0)
+        expect(terminalDisplayWidth(lines[contentIndex]!)).toBe(
+          terminalDisplayWidth(lines[contentIndex - 1]!),
+        )
+      })
+
+      it('centers the CJK message label between lifelines without widening its row', () => {
+        const ascii = renderMermaidASCII(mermaid, {
+          useAscii,
+          colorMode: 'none',
+        })
+        const lines = ascii.split('\n')
+        const labelIndex = lines.findIndex((l) => l.includes('こんにちは'))
+        expect(labelIndex).toBeGreaterThan(0)
+        // Neighboring lifeline-only rows (blank rows immediately above/below
+        // the label) share the same fixed canvas width and contain no
+        // arrowhead glyph — a direct, quirk-free comparison.
+        const blankAbove = lines[labelIndex - 1]!
+        expect(terminalDisplayWidth(lines[labelIndex]!)).toBe(
+          terminalDisplayWidth(blankAbove),
+        )
+      })
+
+      it('does not corrupt the label text itself', () => {
+        const ascii = renderMermaidASCII(mermaid, {
+          useAscii,
+          colorMode: 'none',
+        })
+        expect(ascii).toContain('アリス')
+        expect(ascii).toContain('ボブ')
+        expect(ascii).toContain('こんにちは')
+      })
+    })
+  }
+
+  it('handles a mixed CJK + Latin actor name', () => {
+    const mermaid =
+      'sequenceDiagram\n  participant A as Aliceさん\n  participant B as Bob\n  A->>B: hi'
+    const ascii = renderMermaidASCII(mermaid, { colorMode: 'none' })
+    assertUniformWidthIgnoringArrowheads(ascii)
+    assertContentMatchesBorderAbove(ascii, 'Aliceさん')
+  })
+
+  it('handles a CJK self-message label without corrupting the canvas', () => {
+    const mermaid =
+      'sequenceDiagram\n  participant A as アリス\n  A->>A: 独り言のテスト'
+    const ascii = renderMermaidASCII(mermaid, { colorMode: 'none' })
+    assertUniformWidthIgnoringArrowheads(ascii)
+    expect(ascii).toContain('独り言のテスト')
+  })
+
+  it('handles a CJK label inside an alt block without breaking the block wall', () => {
+    const mermaid =
+      'sequenceDiagram\n  participant A as アリス\n  participant B as ボブ\n  alt 条件が真の場合\n    A->>B: メッセージ\n  end'
+    const ascii = renderMermaidASCII(mermaid, { colorMode: 'none' })
+    assertUniformWidthIgnoringArrowheads(ascii)
+    expect(ascii).toContain('条件が真の場合')
+  })
+
+  it('widens the wall to fit an oversized CJK block header instead of clipping it (#352/#387)', () => {
+    // A block's wall now widens to fit its header/divider label (#352,
+    // extended by #387 to also keep the widened wall clear of any
+    // participant it doesn't enclose) rather than clipping a label longer
+    // than the messages' own lifeline span. `writeTextCells`' `exclusiveMaxX`
+    // clip (added here for #334) is still a defensive backstop — exercised
+    // by the other display-width-vs-clip-bound cases in this file — but a
+    // block header specifically no longer reaches it: `maxBlockLabelWidth`
+    // measures the label with the same CJK-aware `displayWidth` this file's
+    // other tests check, so the wall grows enough that the clip never
+    // engages. This asserts the full label renders, uncorrupted, with the
+    // wall closing immediately after it.
+    const mermaid =
+      'sequenceDiagram\n  participant A as ア\n  participant B as ボ\n  alt 非常に長い条件のラベルがここに続きますよずっと\n    A->>B: x\n  end'
+    const ascii = renderMermaidASCII(mermaid, { colorMode: 'none' })
+    assertUniformWidthIgnoringArrowheads(ascii)
+    const lines = ascii.split('\n')
+    const headerLine = lines.find((l) => l.includes('alt ['))!
+    expect(headerLine).toBeDefined()
+    // Full label present, not clipped.
+    expect(headerLine).toContain(
+      '非常に長い条件のラベルがここに続きますよずっと',
+    )
+    // The wall's right corner must close immediately after the label,
+    // well-formed — proves the wall grew to fit rather than the label
+    // merely being drawn past a wall that didn't move.
+    expect(headerLine!.endsWith('┐')).toBe(true)
+  })
+
+  it('handles a CJK divider label inside an alt block', () => {
+    const mermaid =
+      'sequenceDiagram\n  participant A as アリス\n  participant B as ボブ\n  alt 場合A\n    A->>B: one\n  else 場合B\n    A->>B: two\n  end'
+    const ascii = renderMermaidASCII(mermaid, { colorMode: 'none' })
+    assertUniformWidthIgnoringArrowheads(ascii)
+    expect(ascii).toContain('場合B')
+  })
+
+  it('aligns a CJK note box border with its content', () => {
+    const mermaid =
+      'sequenceDiagram\n  participant A as アリス\n  Note over A: 重要なメモです'
+    const ascii = renderMermaidASCII(mermaid, { colorMode: 'none' })
+    assertContentMatchesBorderAbove(ascii, '重要なメモです')
+  })
+
+  it('leaves the common all-ASCII case intact', () => {
+    // Guard against the fix perturbing diagrams with no wide characters —
+    // uses the ignoring-arrowheads helper since the Unicode charset still
+    // draws an ambiguous-width arrowhead glyph even for plain-ASCII labels.
+    const mermaid =
+      'sequenceDiagram\n  participant Alice\n  participant Bob\n  Alice->>Bob: hello'
+    for (const useAscii of [false, true]) {
+      const ascii = renderMermaidASCII(mermaid, { useAscii, colorMode: 'none' })
+      assertUniformWidthIgnoringArrowheads(ascii)
+      expect(ascii).toContain('Alice')
+      expect(ascii).toContain('Bob')
+      expect(ascii).toContain('hello')
+    }
+  })
+})

package/src/__tests__/ascii-sequence-create-destroy.test.ts

@@ -0,0 +1,114 @@
+// ============================================================================
+// ASCII sequence diagrams — `create participant` / `destroy` lifecycle (#419)
+//
+// A created participant's box sits on the row of the message that creates
+// it (the arrow stops at the box's edge, the lifeline starts under it); a
+// destroyed participant's lifeline ends with a cross on the row under the
+// destroying arrow, and it gets no footer box.
+// ============================================================================
+
+import { describe, it, expect } from 'vitest'
+import { renderMermaidASCII } from '@zombie-mermaid/ascii-renderer'
+
+const source = `sequenceDiagram
+  A->>B: one
+  create participant C
+  A->>C: two
+  destroy B
+  A->>B: three`
+
+describe('ASCII sequence diagrams – create/destroy', () => {
+  it('renders the created box on its creating row and the destroy cross under the destroying arrow', () => {
+    const result = renderMermaidASCII(source, { useAscii: false })
+    expect(result).toBe(
+      [
+        ' ┌───┐      ┌───┐             ',
+        ' │ A │      │ B │             ',
+        ' └─┬─┘      └─┬─┘             ',
+        '   │          │               ',
+        '   │   one    │               ',
+        '   │──────────▶               ',
+        '   │          │               ',
+        '   │        two               ',
+        '   │          │       ┌───┐   ',
+        '   │─────────────────▶│ C │   ',
+        '   │          │       └─┬─┘   ',
+        '   │          │         │     ',
+        '   │  three   │         │     ',
+        '   │──────────▶         │     ',
+        '   │          ✕         │     ',
+        '   │                    │     ',
+        ' ┌─┴─┐                ┌─┴─┐   ',
+        ' │ A │                │ C │   ',
+        ' └───┘                └───┘   ',
+      ].join('\n'),
+    )
+  })
+
+  it('uses the plain-ASCII cross and corners in ASCII mode', () => {
+    const result = renderMermaidASCII(source, { useAscii: true })
+    expect(result).toBe(
+      [
+        ' +---+      +---+             ',
+        ' | A |      | B |             ',
+        ' +---+      +---+             ',
+        '   |          |               ',
+        '   |   one    |               ',
+        '   |---------->               ',
+        '   |          |               ',
+        '   |        two               ',
+        '   |          |       +---+   ',
+        '   |----------------->| C |   ',
+        '   |          |       +---+   ',
+        '   |          |         |     ',
+        '   |  three   |         |     ',
+        '   |---------->         |     ',
+        '   |          x         |     ',
+        '   |                    |     ',
+        ' +---+                +---+   ',
+        ' | A |                | C |   ',
+        ' +---+                +---+   ',
+      ].join('\n'),
+    )
+  })
+
+  it('stops a right-to-left creating arrow at the right edge of the created box', () => {
+    const result = renderMermaidASCII(
+      `sequenceDiagram
+      create participant C
+      D->>C: hi`,
+      { useAscii: false },
+    )
+    expect(result).toBe(
+      [
+        '           ┌───┐   ',
+        '           │ D │   ',
+        '           └─┬─┘   ',
+        '             │     ',
+        '       hi    │     ',
+        ' ┌───┐       │     ',
+        ' │ C │◀──────│     ',
+        ' └─┬─┘       │     ',
+        '   │         │     ',
+        ' ┌─┴─┐     ┌─┴─┐   ',
+        ' │ C │     │ D │   ',
+        ' └───┘     └───┘   ',
+      ].join('\n'),
+    )
+  })
+
+  it('keeps the alias and stick figure of a created actor, and drops nothing into the text', () => {
+    const result = renderMermaidASCII(
+      `sequenceDiagram
+      A->>B: x
+      create actor D as Donald
+      B->>D: hi`,
+      { useAscii: false },
+    )
+    expect(result).toContain('Donald')
+    expect(result).toContain('/|\\')
+    expect(result).not.toContain('create')
+    // Donald's box is not in the header row: the first line holds only A and B
+    expect(result.split('\n')[1]).not.toContain('Donald')
+  })
+})