@zombie-mermaid/ascii-renderer 2.2.1

package/src/__tests__/helpers/terminal-display-width.ts

@@ -0,0 +1,74 @@
+/**
+ * Independently re-implemented terminal display-width calculation, shared by
+ * the ASCII wide-character regression suites (issues #66, #182, #205, #214).
+ *
+ * Deliberately does NOT import from `src/ascii/display-width.ts` or
+ * `packages/core/src/text-metrics.ts`: these suites verify rendered output against an
+ * authority separate from the implementation under test, so that a bug in the
+ * renderer's own width helper cannot make its tests pass by agreeing with
+ * itself. Mirrors the East Asian Width ranges a real monospace terminal uses
+ * to decide whether a code point renders as 1 or 2 columns.
+ *
+ * Measures per grapheme cluster (`Intl.Segmenter`), not per code point: a
+ * real terminal gives zero columns to a combining mark (it attaches to the
+ * preceding base character — issue #205) and exactly one glyph's worth of
+ * columns to a composed multi-code-point sequence like a ZWJ emoji, flag, or
+ * skin-tone modifier (issue #214), not one glyph's worth per code point.
+ */
+import { expect } from 'vitest'
+
+const EMOJI_PATTERN = /\p{Extended_Pictographic}|\p{Emoji_Presentation}/u
+/** Unicode general categories Mn (Nonspacing_Mark) and Me (Enclosing_Mark). */
+const COMBINING_MARK_PATTERN = /\p{Mn}|\p{Me}/u
+
+const graphemeSegmenter = new Intl.Segmenter(undefined, {
+  granularity: 'grapheme',
+})
+
+function isWideCodePoint(ch: string): boolean {
+  const code = ch.codePointAt(0)!
+  return (
+    (code >= 0x1100 && code <= 0x115f) || // Hangul Jamo
+    (code >= 0x2e80 && code <= 0xa4cf) || // CJK radicals .. Yi
+    (code >= 0xac00 && code <= 0xd7a3) || // Hangul syllables
+    (code >= 0xf900 && code <= 0xfaff) || // CJK compatibility ideographs
+    (code >= 0xff00 && code <= 0xff60) || // Fullwidth forms
+    (code >= 0xffe0 && code <= 0xffe6) || // Fullwidth signs
+    code >= 0x20000 || // CJK extension B+
+    EMOJI_PATTERN.test(ch)
+  )
+}
+
+/** Number of terminal columns one grapheme cluster occupies: 0, 1, or 2. */
+function clusterWidth(cluster: string): number {
+  let sawWide = false
+  let sawNonMark = false
+  for (const ch of cluster) {
+    if (isWideCodePoint(ch)) sawWide = true
+    if (!COMBINING_MARK_PATTERN.test(ch)) sawNonMark = true
+  }
+  if (sawWide) return 2
+  return sawNonMark ? 1 : 0
+}
+
+/** Number of terminal columns `text` occupies. */
+export function terminalDisplayWidth(text: string): number {
+  let width = 0
+  for (const { segment } of graphemeSegmenter.segment(text)) {
+    width += clusterWidth(segment)
+  }
+  return width
+}
+
+/** All rendered lines should occupy the same number of terminal columns. */
+export function assertUniformDisplayWidth(ascii: string): void {
+  const lines = ascii.split('\n')
+  const widths = lines.map(terminalDisplayWidth)
+  const expected = widths[0]
+  for (let i = 0; i < lines.length; i++) {
+    expect(
+      widths[i],
+      `line ${i} (${JSON.stringify(lines[i])}) has display width ${widths[i]}, expected ${expected}`,
+    ).toBe(expected)
+  }
+}

package/src/__tests__/pathfinder.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect } from 'vitest'
+import {
+  getPath,
+  heuristic,
+  mergePath,
+  createPathBudget,
+  DEFAULT_PATH_BUDGET,
+} from '../pathfinder.ts'
+import type { GridCoord, PathBudget } from '../types.ts'
+import { createGrid, placeBlock, type Grid } from '../grid-occupancy.ts'
+import { renderMermaidASCII } from '@zombie-mermaid/ascii-renderer'
+
+/**
+ * Helper to build an occupied grid from a list of coordinates, going through
+ * the real `Grid` abstraction rather than hand-rolling a raw Map/Set — a
+ * size-1 "block" reserves exactly the one requested cell.
+ */
+function buildGrid(occupied: GridCoord[]): Grid {
+  const grid = createGrid()
+  for (const c of occupied) {
+    placeBlock(grid, c, 1)
+  }
+  return grid
+}
+
+describe('pathfinder', () => {
+  describe('getPath', () => {
+    it('finds a straight-line path on an empty grid', () => {
+      const grid = buildGrid([])
+      const path = getPath(grid, { x: 0, y: 0 }, { x: 0, y: 3 })
+      expect(path).not.toBeNull()
+      expect(path![0]).toEqual({ x: 0, y: 0 })
+      expect(path![path!.length - 1]).toEqual({ x: 0, y: 3 })
+    })
+
+    it('routes around an obstacle', () => {
+      // Block the straight path at (0,1)
+      const grid = buildGrid([{ x: 0, y: 1 }])
+      const path = getPath(grid, { x: 0, y: 0 }, { x: 0, y: 2 })
+      expect(path).not.toBeNull()
+      expect(path![0]).toEqual({ x: 0, y: 0 })
+      expect(path![path!.length - 1]).toEqual({ x: 0, y: 2 })
+      // Path must detour (length > 3)
+      expect(path!.length).toBeGreaterThan(3)
+    })
+
+    it('returns null when destination is completely enclosed', () => {
+      // Surround (2,2) with occupied cells on all 4 sides
+      const grid = buildGrid([
+        { x: 1, y: 2 },
+        { x: 3, y: 2 },
+        { x: 2, y: 1 },
+        { x: 2, y: 3 },
+      ])
+      const path = getPath(grid, { x: 0, y: 0 }, { x: 2, y: 2 })
+      // Destination is occupied-surrounded; A* should return null within iteration limit
+      // (not throw RangeError: Map maximum size exceeded)
+      expect(path).toBeNull()
+    })
+
+    it('returns null for unreachable destination without exhausting memory', () => {
+      // Create a wall that blocks access to the target region
+      const occupied: GridCoord[] = []
+      for (let i = 0; i < 100; i++) {
+        occupied.push({ x: 5, y: i }) // vertical wall at x=5
+      }
+      const grid = buildGrid(occupied)
+      // Target is behind the wall; only reachable via y<0 (disallowed) or y>=100 (very far)
+      getPath(grid, { x: 0, y: 50 }, { x: 10, y: 50 })
+      // Should find a path going around the wall (via y>=100), or return null if
+      // the iteration limit is hit. Either outcome is acceptable; the key is no
+      // crash / unbounded memory growth.
+      expect(true).toBe(true)
+    })
+  })
+
+  describe('heuristic', () => {
+    it('returns 0 for same point', () => {
+      expect(heuristic({ x: 3, y: 5 }, { x: 3, y: 5 })).toBe(0)
+    })
+
+    it('returns manhattan distance for axis-aligned points', () => {
+      expect(heuristic({ x: 0, y: 0 }, { x: 0, y: 5 })).toBe(5)
+      expect(heuristic({ x: 0, y: 0 }, { x: 3, y: 0 })).toBe(3)
+    })
+
+    it('adds +1 penalty for diagonal displacement', () => {
+      expect(heuristic({ x: 0, y: 0 }, { x: 2, y: 3 })).toBe(6) // 2+3+1
+    })
+  })
+
+  describe('mergePath', () => {
+    it('removes collinear intermediate points', () => {
+      const path: GridCoord[] = [
+        { x: 0, y: 0 },
+        { x: 1, y: 0 },
+        { x: 2, y: 0 },
+        { x: 2, y: 1 },
+      ]
+      const merged = mergePath(path)
+      expect(merged).toEqual([
+        { x: 0, y: 0 },
+        { x: 2, y: 0 },
+        { x: 2, y: 1 },
+      ])
+    })
+
+    it('returns short paths unchanged', () => {
+      expect(mergePath([{ x: 0, y: 0 }])).toEqual([{ x: 0, y: 0 }])
+      expect(
+        mergePath([
+          { x: 0, y: 0 },
+          { x: 1, y: 0 },
+        ]),
+      ).toEqual([
+        { x: 0, y: 0 },
+        { x: 1, y: 0 },
+      ])
+    })
+  })
+
+  describe('PathBudget (render-wide iteration budget)', () => {
+    // These test the deterministic mechanism that actually bounds total
+    // pathfinding work for a render — not wall-clock time. See the
+    // ascii-edge-routing-fixes.test.ts "much larger dense fan-in" test
+    // (PR #143) for the wall-clock version of this same regression guard,
+    // which flaked under CPU contention because it measures how long the
+    // work took rather than how much work happened. Asserting on
+    // budget.remaining instead is immune to machine speed/load entirely.
+
+    it('createPathBudget defaults to DEFAULT_PATH_BUDGET', () => {
+      expect(createPathBudget()).toEqual({ remaining: DEFAULT_PATH_BUDGET })
+    })
+
+    it('createPathBudget accepts a custom total', () => {
+      expect(createPathBudget(500)).toEqual({ remaining: 500 })
+    })
+
+    it('decrements a shared budget cumulatively across multiple getPath calls', () => {
+      const grid = buildGrid([])
+      const budget = createPathBudget(1000)
+      const initial = budget.remaining
+
+      getPath(grid, { x: 0, y: 0 }, { x: 0, y: 20 }, budget)
+      const afterFirst = budget.remaining
+      expect(afterFirst).toBeLessThan(initial)
+
+      getPath(grid, { x: 0, y: 0 }, { x: 0, y: 20 }, budget)
+      const afterSecond = budget.remaining
+      // Same search run twice costs the same iterations each time, and the
+      // budget is cumulative across calls, not reset per call — so the
+      // second call must spend down further from where the first left off.
+      expect(afterSecond).toBeLessThan(afterFirst)
+    })
+
+    it('returns null immediately once the budget is exhausted, without spending further iterations', () => {
+      const grid = buildGrid([])
+      const budget: PathBudget = { remaining: 0 }
+      const result = getPath(grid, { x: 0, y: 0 }, { x: 0, y: 5 }, budget)
+      expect(result).toBeNull()
+      // The exhausted-budget check is the first thing getPath does, before
+      // the search loop runs at all, so remaining stays unchanged.
+      expect(budget.remaining).toBe(0)
+    })
+
+    it('never lets budget.remaining go negative', () => {
+      const grid = buildGrid([])
+      const budget = createPathBudget(3) // deliberately smaller than this search needs
+      getPath(grid, { x: 0, y: 0 }, { x: 0, y: 50 }, budget)
+      expect(budget.remaining).toBeGreaterThanOrEqual(0)
+    })
+
+    it('bounds total pathfinding work across many edges to the budget, regardless of edge count', () => {
+      // Structural equivalent of the "much larger dense fan-in" wall-clock
+      // test: 120 fan-in edges, each independently getting its own
+      // unbounded allowance, is what caused the real OOM crashes this
+      // budget exists to prevent (see pathfinder.ts's PathBudget doc
+      // comment). Here, a deliberately small shared budget stands in for
+      // "more total demand than the budget allows" — the same shape of
+      // problem as 120 real edges against the production default.
+      const grid = buildGrid([])
+      const budget = createPathBudget(500)
+      for (let i = 0; i < 120; i++) {
+        getPath(grid, { x: i, y: 0 }, { x: i, y: 40 }, budget)
+      }
+      // Total demand (120 searches x ~40+ iterations each) far exceeds the
+      // 500-iteration budget, so it must land at exactly 0 — proving later
+      // calls were actually cut off partway through, not merely that none
+      // of them individually happened to exceed it.
+      expect(budget.remaining).toBe(0)
+    })
+  })
+
+  describe('dense graph regression', () => {
+    it('does not crash on dense TD graph with multiple fan-in bundles', () => {
+      // Regression test for: RangeError: Map maximum size exceeded
+      // https://github.com/lukilabs/beautiful-mermaid/issues/64
+      const code = `graph TD
+    A["AAA<br>(keita)"] --> C["CCC"]
+    B["BBB<br>(yuriko)"] --> C
+    C --> D["DDDD"]
+    D --> E["EEEE"]
+
+    A1["1 / 2"] --> A
+    A2["3 / 4"] --> A
+    A3["5 / 6"] --> A
+    A4["XXX<br>(YYY ZZZ)"] --> A
+
+    B1["77 77<br>(7 / 7 / 7)"] --> B
+    B2["88-88<br>(99 99)"] --> B
+    B3["111s 222s"] --> B
+
+    D --> F{"F?"}
+    F -->|Yes| G["High level<br>Tr"]
+    F -->|No| H["Dumb Tr<br>S"]`
+
+      // Should not throw (previously threw RangeError: Map maximum size exceeded)
+      const result = renderMermaidASCII(code, { useAscii: false })
+      expect(result).toBeDefined()
+      expect(result.length).toBeGreaterThan(0)
+      // Verify most node labels appear (some may be visually clipped by edge routing)
+      for (const label of [
+        'CCC',
+        'DDDD',
+        'EEEE',
+        '1 / 2',
+        '3 / 4',
+        '5 / 6',
+        'XXX',
+        '77 77',
+        '88-88',
+        '111s 222s',
+        'F?',
+      ]) {
+        expect(result).toContain(label)
+      }
+    })
+  })
+})

package/src/__tests__/testdata/ascii/ampersand_lhs.txt

@@ -0,0 +1,18 @@
+graph LR
+A --> B & C
+---
++---+     +---+
+|   |     |   |
+| A +---->| B |
+|   |     |   |
++-+-+     +---+
+  |            
+  |            
+  |            
+  |            
+  |            
+  |       +---+
+  |       |   |
+  +------>| C |
+          |   |
+          +---+

package/src/__tests__/testdata/ascii/ampersand_lhs_and_rhs.txt

@@ -0,0 +1,18 @@
+graph LR
+A & B --> C & D
+---
++---+     +---+
+|   |     |   |
+| A +--+->| C |
+|   |  |  |   |
++-+-+  |  +---+
+  |    |       
+  |    |       
+  +----+       
+  |    |       
+  |    |       
++-+-+  |  +---+
+|   |  |  |   |
+| B +--+->| D |
+|   |     |   |
++---+     +---+

package/src/__tests__/testdata/ascii/ampersand_rhs.txt

@@ -0,0 +1,18 @@
+graph LR
+A & B --> C
+---
++---+     +---+
+|   |     |   |
+| A +---->| C |
+|   |     |   |
++---+     +---+
+            ^  
+            |  
+            |  
+            |  
+            |  
++---+       |  
+|   |       |  
+| B +-------+
+|   |          
++---+          

package/src/__tests__/testdata/ascii/ampersand_td_fanin.txt

@@ -0,0 +1,18 @@
+graph TD
+A & B --> C
+---
++---+     +---+
+|   |     |   |
+| A |     | B |
+|   |     |   |
++-+-+     +-+-+
+  |         |
+  |         |
+  +---------+
+  |
+  v
++---+
+|   |
+| C |
+|   |
++---+

package/src/__tests__/testdata/ascii/ampersand_td_fanout.txt

@@ -0,0 +1,18 @@
+graph TD
+A --> B & C
+---
++---+
+|   |
+| A |
+|   |
++---+
+  |
+  |
+  +---------+
+  |         |
+  v         v
++---+     +---+
+|   |     |   |
+| B |     | C |
+|   |     |   |
++---+     +---+

package/src/__tests__/testdata/ascii/ampersand_without_edge.txt

@@ -0,0 +1,18 @@
+graph LR
+A & B
+---
++---+
+|   |
+| A |
+|   |
++---+
+     
+     
+     
+     
+     
++---+
+|   |
+| B |
+|   |
++---+

package/src/__tests__/testdata/ascii/back_reference_from_child.txt

@@ -0,0 +1,10 @@
+graph LR
+A --> B --> C --> A
+---
++---+     +---+     +---+
+|   |     |   |     |   |
+| A +---->| B +---->| C |
+|   |     |   |     |   |
++---+     +---+     +-+-+
+  ^                   |  
+  +-------------------+  

package/src/__tests__/testdata/ascii/backlink_from_bottom.txt

@@ -0,0 +1,22 @@
+graph LR
+A --> B
+B --> C
+A --> C
+B --> D
+C --> D
+---
++---+     +---+     +---+
+|   |     |   |     |   |
+| A +---->| B +---->| D |
+|   |     |   |     |   |
++-+-+     +-+-+     +---+
+  |         |         ^  
+  |         |         |  
+  |         |         |  
+  |         |         |  
+  |         v         |  
+  |       +---+       |  
+  |       |   |       |  
+  +------>| C +-------+
+          |   |          
+          +---+          

package/src/__tests__/testdata/ascii/backlink_from_top.txt

@@ -0,0 +1,22 @@
+graph LR
+A --> B
+B --> C
+A --> C
+B --> D
+D --> C
+---
++---+     +---+     +---+
+|   |     |   |     |   |
+| A +---->| B +--+->+ D |
+|   |     |   |  |  |   |
++-+-+     +-+-+  |  +---+
+  |         |    |       
+  |         |    |       
+  |         +----+       
+  |         |            
+  |         v            
+  |       +---+          
+  |       |   |          
+  +------>| C |          
+          |   |          
+          +---+          

package/src/__tests__/testdata/ascii/backlink_with_short_y_padding.txt

@@ -0,0 +1,20 @@
+paddingX=5
+paddingY=3
+graph LR
+A --> B & C
+B --> C & D
+D --> C
+---
++---+     +---+     +---+
+|   |     |   |     |   |
+| A +---->| B +--+->+ D |
+|   |     |   |  |  |   |
++-+-+     +-+-+  |  +---+
+  |         |    |       
+  |         +----+       
+  |         v            
+  |       +---+          
+  |       |   |          
+  +------>| C |          
+          |   |          
+          +---+          

package/src/__tests__/testdata/ascii/cls_all_relationships.txt

@@ -0,0 +1,19 @@
+classDiagram
+  A <|-- B : inherits
+  C *-- D : owns
+  E o-- F : has
+  G --> H : uses
+  I ..> J : depends
+  K ..|> L : implements
+---
+   +---+       +---+    +---+     +---+      +---+          +---+       
+   | A |       | C |    | E |     | G |      | I |          | K |       
+   +---+       +---+    +---+     +---+      +---+          +---+       
+     ^           *        o         |          :              :         
+ inherits      owns      has      uses      depends      implements     
+     |           |        |         v          v              v         
+   +---+       +---+    +---+     +---+      +---+          +---+       
+   | B |       | D |    | F |     | H |      | J |          | L |       
+   +---+       +---+    +---+     +---+      +---+          +---+       
+                                                                        
+                                                                        

package/src/__tests__/testdata/ascii/cls_annotation.txt

@@ -0,0 +1,29 @@
+classDiagram
+  class Shape {
+    <<abstract>>
+    +draw() void
+  }
+  class Circle {
+    +radius int
+    +draw() void
+  }
+  Shape <|-- Circle
+---
++----------------+    
+| <<abstract>>   |    
+| Shape          |    
++----------------+    
+| + draw(): void |    
++----------------+    
+         ^            
+         |            
+         |            
++----------------+    
+| Circle         |    
++----------------+    
+| + int: radius  |    
++----------------+    
+| + draw(): void |    
++----------------+    
+                      
+                      

package/src/__tests__/testdata/ascii/cls_association.txt

@@ -0,0 +1,14 @@
+classDiagram
+  Student --> Course : enrolls
+---
++---------+    
+| Student |    
++---------+    
+     |         
+  enrolls      
+     v         
++--------+     
+| Course |     
++--------+     
+               
+               

package/src/__tests__/testdata/ascii/cls_basic.txt

@@ -0,0 +1,15 @@
+classDiagram
+  class Animal {
+    +String name
+    +eat() void
+  }
+---
++----------------+    
+| Animal         |    
++----------------+    
+| + name: String |    
++----------------+    
+| + eat(): void  |    
++----------------+    
+                      
+                      

package/src/__tests__/testdata/ascii/cls_dependency.txt

@@ -0,0 +1,14 @@
+classDiagram
+  Client ..> Server : uses
+---
++--------+    
+| Client |    
++--------+    
+     :        
+   uses       
+     v        
++--------+    
+| Server |    
++--------+    
+              
+              

package/src/__tests__/testdata/ascii/cls_inheritance.txt

@@ -0,0 +1,20 @@
+classDiagram
+  Animal <|-- Dog
+  Animal : +String name
+  Dog : +bark() void
+---
++----------------+    
+| Animal         |    
++----------------+    
+| + name: String |    
++----------------+    
+         ^            
+         |            
+         |            
++----------------+    
+| Dog            |    
++----------------+    
+| + bark(): void |    
++----------------+    
+                      
+                      

package/src/__tests__/testdata/ascii/cls_methods.txt

@@ -0,0 +1,21 @@
+classDiagram
+  class BankAccount {
+    +String owner
+    -int balance
+    +deposit(int amount) void
+    +withdraw(int amount) bool
+    -validate() bool
+  }
+---
++------------------------------+    
+| BankAccount                  |    
++------------------------------+    
+| + owner: String              |    
+| - balance: int               |    
++------------------------------+    
+| + deposit(int amount): void  |    
+| + withdraw(int amount): bool |    
+| - validate(): bool           |    
++------------------------------+    
+                                    
+                                    

package/src/__tests__/testdata/ascii/comments.txt

@@ -0,0 +1,23 @@
+graph LR
+%% This is a comment
+A --> B
+%% Another comment
+B --> C
+A --> C
+%% Final comment
+---
++---+     +---+
+|   |     |   |
+| A +---->| B |
+|   |     |   |
++-+-+     +-+-+
+  |         |  
+  |         |  
+  |         |  
+  |         |  
+  |         v  
+  |       +---+
+  |       |   |
+  +------>| C |
+          |   |
+          +---+

package/src/__tests__/testdata/ascii/custom_padding.txt

@@ -0,0 +1,10 @@
+paddingX=2
+paddingY=1
+graph LR
+A --> B
+---
++---+  +---+
+|   |  |   |
+| A +->| B |
+|   |  |   |
++---+  +---+