@zombie-mermaid/ascii-renderer 2.2.1

package/src/__tests__/edge-cell-styles.test.ts

@@ -0,0 +1,278 @@
+import { describe, it, expect } from 'vitest'
+import {
+  createEdgeCellStyles,
+  findStyleConflict,
+  claimPathCells,
+  createEdgeCellOwners,
+  findUnrelatedOverlap,
+  claimPathOwners,
+} from '../edge-cell-styles.ts'
+import { createGrid, placeBlock } from '../grid-occupancy.ts'
+import type { AsciiEdge, AsciiNode } from '../types.ts'
+import { Down } from '../types.ts'
+
+describe('edge-cell-styles', () => {
+  it('reports no conflict against an empty map', () => {
+    const grid = createGrid()
+    const cellStyles = createEdgeCellStyles()
+    const path = [
+      { x: 0, y: 0 },
+      { x: 3, y: 0 },
+    ]
+    expect(findStyleConflict(grid, cellStyles, path, 'solid')).toBeNull()
+  })
+
+  it('does not flag a second same-style edge through claimed cells', () => {
+    const grid = createGrid()
+    const cellStyles = createEdgeCellStyles()
+    const path = [
+      { x: 0, y: 0 },
+      { x: 3, y: 0 },
+    ]
+    claimPathCells(grid, cellStyles, path, 'solid')
+    // A second solid edge reusing the same cells is exactly the "sibling
+    // edges share a trunk" / "LR routing merges naturally at corners"
+    // behavior other tests rely on — must stay unflagged.
+    expect(findStyleConflict(grid, cellStyles, path, 'solid')).toBeNull()
+  })
+
+  it('flags a different-style edge crossing already-claimed cells', () => {
+    const grid = createGrid()
+    const cellStyles = createEdgeCellStyles()
+    const path = [
+      { x: 0, y: 0 },
+      { x: 3, y: 0 },
+    ]
+    claimPathCells(grid, cellStyles, path, 'solid')
+    expect(findStyleConflict(grid, cellStyles, path, 'dotted')).toEqual({
+      x: 0,
+      y: 0,
+    })
+  })
+
+  it('reports the first conflicting cell in path order', () => {
+    const grid = createGrid()
+    const cellStyles = createEdgeCellStyles()
+    claimPathCells(
+      grid,
+      cellStyles,
+      [
+        { x: 5, y: 0 },
+        { x: 8, y: 0 },
+      ],
+      'thick',
+    )
+    const crossing = [
+      { x: 0, y: 0 },
+      { x: 10, y: 0 },
+    ]
+    expect(findStyleConflict(grid, cellStyles, crossing, 'solid')).toEqual({
+      x: 5,
+      y: 0,
+    })
+  })
+
+  it('first claim wins — claiming a cell twice with different styles keeps the original', () => {
+    const grid = createGrid()
+    const cellStyles = createEdgeCellStyles()
+    const cell = [{ x: 1, y: 1 }]
+    claimPathCells(grid, cellStyles, cell, 'solid')
+    claimPathCells(grid, cellStyles, cell, 'dotted')
+    // Still solid from the first claim, so a *third* dotted edge is still
+    // reported as a conflict rather than silently "winning" the cell.
+    expect(findStyleConflict(grid, cellStyles, cell, 'dotted')).toEqual({
+      x: 1,
+      y: 1,
+    })
+  })
+
+  it('does not flag cells the path never touches', () => {
+    const grid = createGrid()
+    const cellStyles = createEdgeCellStyles()
+    claimPathCells(
+      grid,
+      cellStyles,
+      [
+        { x: 0, y: 0 },
+        { x: 0, y: 5 },
+      ],
+      'solid',
+    )
+    const unrelated = [
+      { x: 10, y: 10 },
+      { x: 12, y: 10 },
+    ]
+    expect(findStyleConflict(grid, cellStyles, unrelated, 'dotted')).toBeNull()
+  })
+
+  /**
+   * Regression: an edge's path always includes its own source/target
+   * node's border cell — that's how it connects to the box at all — so
+   * two edges sharing a node (one incoming, one outgoing, as in a retry
+   * loop's `B -->|No| D; D -.-> A`) legitimately share that exact port
+   * cell. An earlier version tracked *every* path cell including
+   * node-owned ones, which flagged this as a conflict — and since an edge
+   * always returns to its own node's fixed attachment point regardless of
+   * grid occupancy, "blocking" a node cell and re-routing found the
+   * identical cell again every time, so the fix never actually converged.
+   */
+  it('does not flag a shared node-border cell as a conflict', () => {
+    const grid = createGrid()
+    placeBlock(grid, { x: 4, y: 8 }) // node D's reserved 3x3 block
+    const cellStyles = createEdgeCellStyles()
+
+    // Incoming solid edge terminating at D's top-center port, (5, 8).
+    claimPathCells(
+      grid,
+      cellStyles,
+      [
+        { x: 2, y: 5 },
+        { x: 5, y: 5 },
+        { x: 5, y: 8 },
+      ],
+      'solid',
+    )
+
+    // Outgoing dotted edge leaving from D's right-side port, (6, 9) —
+    // inside the same reserved block, so still node-owned — then diverging
+    // into its own open column (7) rather than reusing (5, *).
+    const conflict = findStyleConflict(
+      grid,
+      cellStyles,
+      [
+        { x: 6, y: 9 },
+        { x: 7, y: 9 },
+        { x: 7, y: 1 },
+      ],
+      'dotted',
+    )
+    expect(conflict).toBeNull()
+  })
+
+  it('still flags a genuine open-space conflict alongside a shared node border', () => {
+    const grid = createGrid()
+    placeBlock(grid, { x: 4, y: 8 }) // node D's reserved 3x3 block
+    const cellStyles = createEdgeCellStyles()
+
+    claimPathCells(
+      grid,
+      cellStyles,
+      [
+        { x: 2, y: 5 },
+        { x: 5, y: 5 },
+        { x: 5, y: 8 },
+      ],
+      'solid',
+    )
+
+    // A different-style edge that reaches D via the *same open-space*
+    // column (5, 5)-(5, 8), not just the shared port cell, is still a
+    // real conflict — reported at the first open cell it crosses.
+    const conflict = findStyleConflict(
+      grid,
+      cellStyles,
+      [
+        { x: 5, y: 1 },
+        { x: 5, y: 8 },
+      ],
+      'dotted',
+    )
+    expect(conflict).toEqual({ x: 5, y: 5 })
+  })
+})
+
+function makeNode(name: string): AsciiNode {
+  return {
+    name,
+    displayLabel: name,
+    shape: 'rectangle',
+    index: 0,
+    gridCoord: null,
+    drawingCoord: null,
+    drawing: null,
+    drawn: false,
+    styleClassName: '',
+    styleClass: { name: '', styles: {} },
+  }
+}
+
+function makeEdge(from: AsciiNode, to: AsciiNode): AsciiEdge {
+  return {
+    from,
+    to,
+    text: '',
+    path: [],
+    labelLine: [],
+    startDir: Down,
+    endDir: Down,
+    style: 'solid',
+    hasArrowStart: false,
+    hasArrowEnd: true,
+  }
+}
+
+describe('edge-cell-styles — chain overlap (multi-owner cells)', () => {
+  /**
+   * Regression for a CodeRabbit finding on PR #1093 (the #1067 fix):
+   * `claimPathOwners` originally stored only the *first* edge to claim a
+   * cell (`if (!owners.has(key)) owners.set(key, edge)`). When an edge
+   * unrelated to any chain claims a shared cell before the real chain
+   * partner does (an ordering `graph.edges` doesn't control), the chain
+   * partner's own claim was silently dropped — so `findUnrelatedOverlap`
+   * only ever saw the unrelated edge's claim, never found a chain pair, and
+   * missed the real overlap entirely. Cells must track every edge that
+   * claims them, not just the first.
+   */
+  it('detects a chain-pair overlap even when an unrelated edge claimed the corridor first', () => {
+    const grid = createGrid()
+    const owners = createEdgeCellOwners()
+
+    const a = makeNode('A')
+    const b = makeNode('B')
+    const c = makeNode('C')
+    const x = makeNode('X')
+    const y = makeNode('Y')
+
+    const edgeAB = makeEdge(a, b)
+    const edgeBC = makeEdge(b, c)
+    const edgeXY = makeEdge(x, y) // unrelated to the A->B->C chain
+
+    const corridor = [
+      { x: 0, y: 0 },
+      { x: 0, y: 1 },
+      { x: 0, y: 2 },
+    ]
+
+    // The unrelated edge claims the corridor first.
+    claimPathOwners(grid, owners, corridor, edgeXY)
+    // The true chain partner (A->B) also routes through it.
+    claimPathOwners(grid, owners, corridor, edgeAB)
+
+    // B->C, checked against the same corridor, must still find its A->B
+    // chain partner's overlap — not be hidden behind X->Y's earlier claim.
+    const conflict = findUnrelatedOverlap(grid, owners, corridor, edgeBC)
+    expect(conflict).toEqual({ x: 0, y: 0 })
+  })
+
+  it('still finds nothing when only an unrelated edge claimed the corridor', () => {
+    const grid = createGrid()
+    const owners = createEdgeCellOwners()
+
+    const b = makeNode('B')
+    const c = makeNode('C')
+    const x = makeNode('X')
+    const y = makeNode('Y')
+
+    const edgeBC = makeEdge(b, c)
+    const edgeXY = makeEdge(x, y)
+
+    const corridor = [
+      { x: 0, y: 0 },
+      { x: 0, y: 1 },
+    ]
+
+    claimPathOwners(grid, owners, corridor, edgeXY)
+
+    expect(findUnrelatedOverlap(grid, owners, corridor, edgeBC)).toBeNull()
+  })
+})

package/src/__tests__/grid-occupancy.test.ts

@@ -0,0 +1,240 @@
+import { describe, it, expect } from 'vitest'
+import {
+  createGrid,
+  isOccupied,
+  isFree,
+  isBlockFree,
+  placeBlock,
+  pathCells,
+  cloneGrid,
+  NODE_BLOCK_SIZE,
+} from '../grid-occupancy.ts'
+
+describe('grid-occupancy', () => {
+  it('createGrid starts empty', () => {
+    const grid = createGrid()
+    expect(isOccupied(grid, { x: 0, y: 0 })).toBe(false)
+    expect(isFree(grid, { x: 0, y: 0 })).toBe(true)
+  })
+
+  describe('isFree', () => {
+    it('is false for negative coordinates even when unoccupied', () => {
+      const grid = createGrid()
+      expect(isOccupied(grid, { x: -1, y: 0 })).toBe(false)
+      expect(isFree(grid, { x: -1, y: 0 })).toBe(false)
+      expect(isFree(grid, { x: 0, y: -1 })).toBe(false)
+    })
+
+    it('is false for an occupied non-negative cell', () => {
+      const grid = createGrid()
+      placeBlock(grid, { x: 2, y: 2 }, 1)
+      expect(isFree(grid, { x: 2, y: 2 })).toBe(false)
+    })
+
+    it('is true for a free non-negative cell', () => {
+      const grid = createGrid()
+      expect(isFree(grid, { x: 5, y: 5 })).toBe(true)
+    })
+  })
+
+  describe('isBlockFree / placeBlock', () => {
+    it('reports a fresh block as free, then occupied after placing', () => {
+      const grid = createGrid()
+      const origin = { x: 0, y: 0 }
+      expect(isBlockFree(grid, origin)).toBe(true)
+      placeBlock(grid, origin)
+      expect(isBlockFree(grid, origin)).toBe(false)
+      // Every cell in the default NODE_BLOCK_SIZE x NODE_BLOCK_SIZE block
+      // is reserved, not just the origin cell.
+      for (let dx = 0; dx < NODE_BLOCK_SIZE; dx++) {
+        for (let dy = 0; dy < NODE_BLOCK_SIZE; dy++) {
+          expect(isOccupied(grid, { x: origin.x + dx, y: origin.y + dy })).toBe(
+            true,
+          )
+        }
+      }
+    })
+
+    it('detects partial overlap with an already-placed block', () => {
+      const grid = createGrid()
+      placeBlock(grid, { x: 0, y: 0 }) // occupies (0,0)..(2,2)
+      // Shifted by 1 in each axis: overlaps the first block at (1,1)-(2,2)
+      // even though its own origin cell (1,1) is inside the first block too.
+      expect(isBlockFree(grid, { x: 1, y: 1 })).toBe(false)
+      // Fully disjoint block (mod-4 pitch) is free.
+      expect(isBlockFree(grid, { x: 4, y: 0 })).toBe(true)
+    })
+
+    it('throws rather than silently overwriting on collision', () => {
+      const grid = createGrid()
+      placeBlock(grid, { x: 0, y: 0 })
+      expect(() => placeBlock(grid, { x: 1, y: 1 })).toThrow(/already occupied/)
+    })
+
+    it('supports a single-cell block via size=1', () => {
+      const grid = createGrid()
+      placeBlock(grid, { x: 3, y: 3 }, 1)
+      expect(isOccupied(grid, { x: 3, y: 3 })).toBe(true)
+      expect(isOccupied(grid, { x: 4, y: 3 })).toBe(false)
+      expect(isOccupied(grid, { x: 3, y: 4 })).toBe(false)
+    })
+  })
+
+  describe('Grid.delete', () => {
+    it('releases a cell so it reports free again', () => {
+      const grid = createGrid()
+      grid.add('5,5')
+      expect(grid.has('5,5')).toBe(true)
+      grid.delete('5,5')
+      expect(grid.has('5,5')).toBe(false)
+    })
+
+    it('is a no-op for a cell that was never reserved', () => {
+      const grid = createGrid()
+      expect(() => grid.delete('9,9')).not.toThrow()
+      expect(grid.has('9,9')).toBe(false)
+    })
+  })
+
+  describe('pathCells', () => {
+    it('returns an empty array for an empty path', () => {
+      expect(pathCells([])).toEqual([])
+    })
+
+    it('returns the single point for a one-point path', () => {
+      expect(pathCells([{ x: 4, y: 7 }])).toEqual([{ x: 4, y: 7 }])
+    })
+
+    it('walks every intermediate cell of a horizontal segment', () => {
+      const cells = pathCells([
+        { x: 0, y: 0 },
+        { x: 3, y: 0 },
+      ])
+      expect(cells).toEqual([
+        { x: 0, y: 0 },
+        { x: 1, y: 0 },
+        { x: 2, y: 0 },
+        { x: 3, y: 0 },
+      ])
+    })
+
+    it('walks every intermediate cell of a vertical segment', () => {
+      const cells = pathCells([
+        { x: 2, y: 5 },
+        { x: 2, y: 2 },
+      ])
+      expect(cells).toEqual([
+        { x: 2, y: 5 },
+        { x: 2, y: 4 },
+        { x: 2, y: 3 },
+        { x: 2, y: 2 },
+      ])
+    })
+
+    it('walks a clean 45° diagonal', () => {
+      const cells = pathCells([
+        { x: 0, y: 0 },
+        { x: 3, y: 3 },
+      ])
+      expect(cells).toEqual([
+        { x: 0, y: 0 },
+        { x: 1, y: 1 },
+        { x: 2, y: 2 },
+        { x: 3, y: 3 },
+      ])
+    })
+
+    /**
+     * Regression for a real crash: `determinePath`'s Case-4 direct fallback
+     * (`edge.path = [prefFrom, prefTo]`, used when A* finds no route at
+     * all) can produce a segment whose dx/dy ratio is anything, not just
+     * 0, equal, or axis-aligned. An earlier version of `pathCells` stepped
+     * both axes by `Math.sign(delta)` every iteration, which only ever
+     * reaches the target when `|dx| === |dy|` — for a 10-wide, 3-tall
+     * segment like this one it walks (10,10), (11,11)... forever, since x
+     * and y can never both equal (10,3) on the same iteration. That
+     * doesn't just produce a wrong path — it hung the real render until a
+     * backing `Set` threw "maximum size exceeded" (see
+     * ascii-edge-cross-style-overlap.test.ts for the end-to-end repro).
+     * Bresenham handles any ratio and is guaranteed to land exactly on the
+     * endpoint in `max(|dx|, |dy|) + 1` steps.
+     */
+    it('terminates and lands exactly on the endpoint for a non-45° diagonal', () => {
+      const cells = pathCells([
+        { x: 0, y: 0 },
+        { x: 10, y: 3 },
+      ])
+      expect(cells[cells.length - 1]).toEqual({ x: 10, y: 3 })
+      expect(cells.length).toBe(11) // max(|10|, |3|) + 1
+      // Every step must move by at most one cell on each axis (no skips,
+      // no doubling back) — Bresenham can step both axes in the same
+      // iteration to stay close to the true line, so Chebyshev distance
+      // between consecutive cells is always exactly 1, though Manhattan
+      // distance can be 1 or 2.
+      for (let i = 1; i < cells.length; i++) {
+        const a = cells[i - 1]!
+        const b = cells[i]!
+        expect(Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y))).toBe(1)
+      }
+    })
+
+    it('walks a multi-segment path corner-to-corner without duplicating the shared corner', () => {
+      const cells = pathCells([
+        { x: 0, y: 0 },
+        { x: 2, y: 0 },
+        { x: 2, y: 2 },
+      ])
+      expect(cells).toEqual([
+        { x: 0, y: 0 },
+        { x: 1, y: 0 },
+        { x: 2, y: 0 },
+        { x: 2, y: 1 },
+        { x: 2, y: 2 },
+      ])
+    })
+
+    /**
+     * Regression: an earlier version silently returned a path truncated at
+     * `MAX_WALK_STEPS`, which under-reports to a caller checking "every
+     * cell this path touches" (edge-cell-styles.ts's conflict detection,
+     * specifically) — a conflict past the cutoff would simply never be
+     * seen. Throwing converts that silent blind spot into a loud failure.
+     */
+    it('throws rather than silently returning a truncated path past the walk limit', () => {
+      expect(() =>
+        pathCells([
+          { x: 0, y: 0 },
+          { x: 200_000, y: 0 },
+        ]),
+      ).toThrow(/did not reach its endpoint/)
+    })
+  })
+
+  describe('Grid.keys / cloneGrid', () => {
+    it('keys() iterates every reserved cell', () => {
+      const grid = createGrid()
+      grid.add('1,1')
+      grid.add('2,2')
+      expect(new Set(grid.keys())).toEqual(new Set(['1,1', '2,2']))
+    })
+
+    it('cloneGrid copies current reservations into an independent grid', () => {
+      const original = createGrid()
+      original.add('1,1')
+      const clone = cloneGrid(original)
+      expect(isOccupied(clone, { x: 1, y: 1 })).toBe(true)
+
+      // Independent: mutating one after cloning doesn't affect the other.
+      original.add('2,2')
+      expect(isOccupied(clone, { x: 2, y: 2 })).toBe(false)
+
+      clone.add('3,3')
+      expect(isOccupied(original, { x: 3, y: 3 })).toBe(false)
+    })
+
+    it('cloneGrid on an empty grid produces an empty grid', () => {
+      const clone = cloneGrid(createGrid())
+      expect([...clone.keys()]).toEqual([])
+    })
+  })
+})

package/src/__tests__/helpers/ascii-form.ts

@@ -0,0 +1,142 @@
+/**
+ * Structural fact extraction for rendered ASCII diagrams — shared by the
+ * "form invariant" suites (ascii-sequence-form-invariants.test.ts,
+ * ascii-class-box-occupancy.test.ts, ascii-er-box-occupancy.test.ts).
+ *
+ * These suites assert structural properties of the rendered output (does
+ * this box overlap that one, does this label fit inside its container)
+ * rather than diffing against a committed fixture. `svg-samples.visual.test.ts`
+ * / `ascii-samples.visual.test.ts` only self-diff against their own baseline
+ * screenshot, which can never catch a defect that was already present when
+ * that baseline was captured — these helpers exist to check the renderer
+ * against its own stated semantics instead (e.g. "a box must be wide enough
+ * to hold its label", "an unrelated box must never be overwritten").
+ *
+ * Deliberately works on the *rendered string*, not renderer internals:
+ * `renderSequenceAscii`/`renderClassAscii`/`renderErAscii` each do
+ * parse→layout→draw→stringify in one function with no layout object
+ * exposed, and (checked directly) `src/ascii/er-diagram.ts`'s own occupancy
+ * guard (`boxCells`) is a flat, entity-agnostic occupied-cell set — even the
+ * renderer's own internals can't answer "which entity owns this cell"
+ * without a scan shaped like the one below. Matches this repo's existing
+ * convention of small, local, string-based test helpers (see
+ * `helpers/terminal-display-width.ts`).
+ */
+
+export interface Rect {
+  x0: number
+  x1: number
+  y0: number
+  y1: number
+}
+
+/** Border-ish characters in both Unicode and `useAscii: true` box-drawing. */
+const BORDER_CHARS = new Set([
+  '│',
+  '┌',
+  '└',
+  '├',
+  '┤',
+  '┐',
+  '┘',
+  '─',
+  '┬',
+  '┴',
+  '┼',
+  '+',
+  '|',
+  '-',
+])
+
+function isBorderish(ch: string | undefined): boolean {
+  return ch !== undefined && BORDER_CHARS.has(ch)
+}
+
+function lineAt(lines: string[], y: number, x: number): string | undefined {
+  return lines[y]?.[x]
+}
+
+/**
+ * Locate a named, bordered box (an actor box, a class box, an entity box) by
+ * its header text.
+ *
+ * Finds the row where `name` sits with a border-ish character immediately to
+ * its left and right (skipping padding spaces), *and* a border-ish character
+ * directly above that same column (the box's top border or a section
+ * divider) — the second check keeps a name that's a substring of another
+ * name, or that happens to appear inside an attribute/label string, from
+ * false-matching a header row it isn't actually part of. Then walks outward
+ * from that row along the left/right border columns until the border stops
+ * holding, to find the box's full vertical extent.
+ *
+ * Works identically in Unicode and `useAscii: true` mode: it only asks "is
+ * this column border-ish at this row," never which specific glyph is there.
+ */
+export function findBoxRect(ascii: string, name: string): Rect {
+  const lines = ascii.split('\n')
+
+  for (let y = 0; y < lines.length; y++) {
+    const line = lines[y]!
+    let searchFrom = 0
+    for (;;) {
+      const idx = line.indexOf(name, searchFrom)
+      if (idx === -1) break
+      searchFrom = idx + 1
+
+      let left = idx - 1
+      while (left >= 0 && line[left] === ' ') left--
+      let right = idx + name.length
+      while (right < line.length && line[right] === ' ') right++
+
+      if (!isBorderish(line[left]) || !isBorderish(line[right])) continue
+      // Require a border-ish char directly above this header row (top
+      // border or a divider) — rejects a match inside a box's body text.
+      if (!isBorderish(lineAt(lines, y - 1, left))) continue
+
+      const x0 = left
+      const x1 = right
+
+      let y0 = y
+      while (
+        isBorderish(lineAt(lines, y0 - 1, x0)) &&
+        isBorderish(lineAt(lines, y0 - 1, x1))
+      ) {
+        y0--
+      }
+      let y1 = y
+      while (
+        isBorderish(lineAt(lines, y1 + 1, x0)) &&
+        isBorderish(lineAt(lines, y1 + 1, x1))
+      ) {
+        y1++
+      }
+
+      return { x0, x1, y0, y1 }
+    }
+  }
+
+  throw new Error(`findBoxRect: no bordered box found for "${name}"`)
+}
+
+/**
+ * Locate free-floating text (a relationship label, a note's own text) that
+ * isn't itself inside a bordered box header — same row/column scan as
+ * `findBoxRect` but without the border precondition. Returns the tightest
+ * rectangle containing every occurrence-adjacent character of `text` on its
+ * line (just the matched span, not a box).
+ */
+export function findTextRect(ascii: string, text: string): Rect {
+  const lines = ascii.split('\n')
+  for (let y = 0; y < lines.length; y++) {
+    const idx = lines[y]!.indexOf(text)
+    if (idx !== -1) {
+      return { x0: idx, x1: idx + text.length - 1, y0: y, y1: y }
+    }
+  }
+  throw new Error(`findTextRect: "${text}" not found`)
+}
+
+/** Half-open interval overlap check between two rectangles. */
+export function rectsOverlap(a: Rect, b: Rect): boolean {
+  return a.x0 <= b.x1 && a.x1 >= b.x0 && a.y0 <= b.y1 && a.y1 >= b.y0
+}