@zombie-mermaid/ascii-renderer 2.2.1

package/src/types.ts

@@ -0,0 +1,454 @@
+// ============================================================================
+// ASCII renderer — type definitions
+//
+// Ported from AlexanderGrooff/mermaid-ascii (Go).
+// These types model the grid-based coordinate system, 2D text canvas,
+// and graph structures used by the ASCII/Unicode renderer.
+// ============================================================================
+
+import type { NodeShape } from '@zombie-mermaid/core'
+import type { Grid } from './grid-occupancy.ts'
+
+// Re-export NodeShape for convenience
+export type { NodeShape }
+
+/**
+ * Shape type for ASCII rendering — maps parser shapes to ASCII renderers.
+ * Most shapes from the parser are supported, with fallback to 'rectangle'.
+ */
+export type AsciiNodeShape = NodeShape
+
+/** Logical grid coordinate — nodes occupy 3x3 blocks on this grid. */
+export interface GridCoord {
+  x: number
+  y: number
+}
+
+/**
+ * A mutable, render-wide A* iteration budget shared across every getPath
+ * call made while routing one graph's edges (see pathfinder.ts's getPath
+ * and grid.ts's createMapping). Bounds total pathfinding work for the whole
+ * render, independent of any single call's own per-call iteration cap.
+ */
+export interface PathBudget {
+  remaining: number
+}
+
+/** Character-level coordinate on the 2D text canvas. */
+export interface DrawingCoord {
+  x: number
+  y: number
+}
+
+/**
+ * Direction constants model positions on a node's 3x3 grid block.
+ * Each node occupies grid cells [x..x+2, y..y+2].
+ * Directions are offsets into that block, used for edge attachment points.
+ *
+ *   (0,0) UL   (1,0) Up   (2,0) UR
+ *   (0,1) Left (1,1) Mid  (2,1) Right
+ *   (0,2) LL   (1,2) Down (2,2) LR
+ */
+export interface Direction {
+  readonly x: number
+  readonly y: number
+}
+
+export const Up: Direction = { x: 1, y: 0 }
+export const Down: Direction = { x: 1, y: 2 }
+export const Left: Direction = { x: 0, y: 1 }
+export const Right: Direction = { x: 2, y: 1 }
+export const UpperRight: Direction = { x: 2, y: 0 }
+export const UpperLeft: Direction = { x: 0, y: 0 }
+export const LowerRight: Direction = { x: 2, y: 2 }
+export const LowerLeft: Direction = { x: 0, y: 2 }
+export const Middle: Direction = { x: 1, y: 1 }
+
+/** All named directions for iteration. */
+export const ALL_DIRECTIONS: readonly Direction[] = [
+  Up,
+  Down,
+  Left,
+  Right,
+  UpperRight,
+  UpperLeft,
+  LowerRight,
+  LowerLeft,
+  Middle,
+]
+
+/** Compare directions by value (not reference). */
+export function dirEquals(a: Direction, b: Direction): boolean {
+  return a.x === b.x && a.y === b.y
+}
+
+declare const cardinalDirectionBrand: unique symbol
+
+/**
+ * The 4 pure cardinal directions — Up/Down/Left/Right — the only Direction
+ * values pathfinder.ts's routeEdge/tryDirectPath know how to turn into a
+ * single L-shaped route (horizontal-first for Left/Right, vertical-first
+ * for Up/Down). The other 5 Direction values (the four diagonals, plus
+ * Middle) don't correspond to one routing axis. Direction can't
+ * structurally distinguish these on its own — all 9 constants share the
+ * same {x, y} shape — so this is a nominal brand: requireCardinalDirection
+ * below is the only way to produce one, and it checks the actual value
+ * rather than trusting a caller's claim.
+ */
+export type CardinalDirection = Direction & {
+  readonly [cardinalDirectionBrand]: true
+}
+
+function isCardinalDirection(d: Direction): d is CardinalDirection {
+  return (
+    dirEquals(d, Up) ||
+    dirEquals(d, Down) ||
+    dirEquals(d, Left) ||
+    dirEquals(d, Right)
+  )
+}
+
+/**
+ * Narrow a Direction into a CardinalDirection, throwing if it isn't one of
+ * Up/Down/Left/Right. Mirrors requireGridCoord/requirePathBudget elsewhere
+ * in this module family: the invariant that routeEdge only ever receives a
+ * cardinal direction lives in caller logic spread across edge-routing.ts
+ * and edge-bundling.ts, not in Direction's type, so it's checked explicitly
+ * at the boundary rather than trusted silently across modules.
+ */
+export function requireCardinalDirection(d: Direction): CardinalDirection {
+  if (!isCardinalDirection(d)) {
+    throw new Error(
+      `Expected a cardinal direction (Up/Down/Left/Right); got {x:${d.x}, y:${d.y}}`,
+    )
+  }
+  return d
+}
+
+/**
+ * 2D text canvas — column-major (canvas[x][y]).
+ * Each cell holds a single character (or space).
+ */
+export type Canvas = string[][]
+
+/** A node in the ASCII graph, positioned on the grid. */
+export interface AsciiNode {
+  /** Unique identity key — the original node ID from the parser (e.g. "A", "B"). */
+  name: string
+  /** Human-readable label for rendering inside the box (e.g. "Web Server"). */
+  displayLabel: string
+  /** Node shape from the parser (e.g. "rectangle", "diamond", "circle"). */
+  shape: AsciiNodeShape
+  index: number
+  gridCoord: GridCoord | null
+  drawingCoord: DrawingCoord | null
+  drawing: Canvas | null
+  drawn: boolean
+  styleClassName: string
+  styleClass: AsciiStyleClass
+}
+
+/** Style class for colored node text (ported from Go's classDef). */
+export interface AsciiStyleClass {
+  name: string
+  styles: Record<string, string>
+}
+
+/** Edge line style for ASCII rendering. */
+export type AsciiEdgeStyle = 'solid' | 'dotted' | 'thick' | 'invisible'
+
+/** An edge in the ASCII graph, with a routed path. */
+export interface AsciiEdge {
+  from: AsciiNode
+  to: AsciiNode
+  text: string
+  path: GridCoord[]
+  labelLine: GridCoord[]
+  startDir: Direction
+  endDir: Direction
+  /** Line style: solid (default), dotted (-.->) or thick (==>) */
+  style: AsciiEdgeStyle
+  /** Whether to render an arrowhead at the start (source end) of the edge */
+  hasArrowStart: boolean
+  /** Whether to render an arrowhead at the end (target end) of the edge */
+  hasArrowEnd: boolean
+  /**
+   * Terminator shape at the source end when it's a circle/cross marker
+   * (`o--`/`x--`) rather than a plain arrowhead. Undefined draws the
+   * regular arrowhead glyph (per `hasArrowStart`). See issue #330.
+   */
+  startMarker?: 'circle' | 'cross'
+  /** Terminator shape at the target end (`--o`/`--x`). See `startMarker`. */
+  endMarker?: 'circle' | 'cross'
+  /** Bundle this edge belongs to (if any). Set during bundling analysis. */
+  bundle?: EdgeBundle
+  /**
+   * For bundled edges: path from source/target to the junction point.
+   * The full visual path is: pathToJunction + bundle.sharedPath (for fan-in)
+   * or bundle.sharedPath + pathToJunction (for fan-out).
+   */
+  pathToJunction?: GridCoord[]
+  /**
+   * Set when this edge connects the same *pair* of nodes as one or more
+   * sibling edges — either in the same direction (`A -->|One| B` and
+   * `A -->|Two| B`) or, for a pair laid out side by side, in opposite
+   * directions (`A -->|req| B` and `B -->|res| A`). See
+   * `parallelGroupKey` in edge-routing.ts for the exact rule. This is as
+   * opposed to edges that merely share one endpoint, which `bundle` above
+   * already handles via fan-in/fan-out junctions.
+   *
+   * `index` is this edge's 0-based position within the group (declaration
+   * order); `total` is the group's size. `index === 0` keeps the ordinary
+   * single-edge route (determinePath's ordinary preferred/alternative
+   * search), so a graph with no parallel edges renders identically to
+   * before this field existed. `index > 0` routes through an offset lane
+   * instead — see determinePath in edge-routing.ts — so sibling edges never
+   * compute the identical path (and therefore identically-positioned,
+   * mutually-corrupting labels; see #329 and #629).
+   *
+   * `usedOffsets` is the *same* Set object, by reference, on every edge in
+   * the group (assigned once in assignParallelEdgeLanes) — the lane-offset
+   * search in buildParallelLanePath can land two different lane indices on
+   * the same actual offset when both have to detour around the same
+   * obstacle (see that function's doc), so each successful search records
+   * its chosen offset here and skips any offset a sibling already claimed,
+   * keeping every lane in the group on a genuinely distinct path.
+   */
+  parallelLane?: { index: number; total: number; usedOffsets: Set<number> }
+}
+
+/** A subgraph container with bounding box for rendering. */
+export interface AsciiSubgraph {
+  name: string
+  nodes: AsciiNode[]
+  parent: AsciiSubgraph | null
+  children: AsciiSubgraph[]
+  minX: number
+  minY: number
+  maxX: number
+  maxY: number
+  /** Optional direction override for layout within this subgraph (LR or TD). */
+  direction?: 'LR' | 'TD'
+}
+
+// ============================================================================
+// Padding defaults
+//
+// Shared by every renderer that reads AsciiConfig's padding fields. Layouts
+// that predate `paddingX`/`paddingY`/`boxBorderPadding` becoming configurable
+// (sequence, class, ER — see issue #343) compute their own spacing as an
+// offset from these defaults rather than substituting the raw config value
+// directly, so that *not* passing a padding option still renders exactly as
+// it always has (no baseline/snapshot churn) while explicitly passing one
+// still visibly changes spacing. The flowchart/state grid layout (grid.ts)
+// predates this convention and uses `paddingX`/`paddingY` directly as its
+// column/row gap — don't "fix" that to go through these constants too, its
+// existing default already equals them, so behavior is identical.
+// ============================================================================
+
+/** `AsciiConfig.paddingX`'s default — see the block comment above. */
+export const DEFAULT_PADDING_X = 5
+/** `AsciiConfig.paddingY`'s default — see the block comment above. */
+export const DEFAULT_PADDING_Y = 5
+/** `AsciiConfig.boxBorderPadding`'s default — see the block comment above. */
+export const DEFAULT_BOX_BORDER_PADDING = 1
+
+/**
+ * Derive a diagram-local spacing constant from a padding option, offset from
+ * that option's default so a diagram whose own historical constant differs
+ * from the shared default (e.g. class diagrams' 4-column gap vs. the shared
+ * default of 5) still renders unchanged when the caller passes no explicit
+ * padding override. `-x`/`-y`/`-p` still visibly widen or tighten spacing
+ * because they shift `configValue` away from `defaultValue`.
+ *
+ * Shared by sequence.ts/class-diagram.ts/er-diagram.ts so the three
+ * renderers wired up for issue #343 apply padding the same way instead of
+ * each re-deriving this arithmetic.
+ *
+ * @param floor - Minimum result, so a large negative padding can't collapse
+ *   the spacing to zero or negative (which would overlap adjacent elements).
+ */
+export function paddingOffset(
+  configValue: number,
+  defaultValue: number,
+  base: number,
+  floor: number,
+): number {
+  return Math.max(floor, base + (configValue - defaultValue))
+}
+
+/** Configuration for ASCII rendering. */
+export interface AsciiConfig {
+  /** true = ASCII chars (+,-,|), false = Unicode box-drawing (┌,─,│). Default: false */
+  useAscii: boolean
+  /** Horizontal spacing between nodes. Default: 5 */
+  paddingX: number
+  /** Vertical spacing between nodes. Default: 5 */
+  paddingY: number
+  /** Padding inside node boxes. Default: 1 */
+  boxBorderPadding: number
+  /** Graph direction: "LR" or "TD". */
+  graphDirection: 'LR' | 'TD'
+}
+
+/** Full ASCII graph state used during layout and rendering. */
+export interface AsciiGraph {
+  nodes: AsciiNode[]
+  edges: AsciiEdge[]
+  canvas: Canvas
+  /** Role canvas — tracks the role of each character for colored output. */
+  roleCanvas: RoleCanvas
+  /** Grid occupancy map — tracks which "x,y" cells are reserved. */
+  grid: Grid
+  columnWidth: Map<number, number>
+  rowHeight: Map<number, number>
+  subgraphs: AsciiSubgraph[]
+  config: AsciiConfig
+  /** Offset applied to all drawing coords to accommodate subgraph borders. */
+  offsetX: number
+  offsetY: number
+  /** Edge bundles for parallel link visualization. Set during bundling analysis. */
+  bundles: EdgeBundle[]
+  /**
+   * Render-wide A* iteration budget shared across every getPath call made
+   * while routing this graph's edges. Bounds total pathfinding work (and
+   * therefore memory) for graphs with many edges, independent of any
+   * single call's own iteration cap. Set at the start of createMapping's
+   * edge-routing phase; undefined before then. See pathfinder.ts's
+   * PathBudget for details.
+   */
+  pathBudget?: PathBudget
+}
+
+// ============================================================================
+// Coordinate helpers
+// ============================================================================
+
+export function gridCoordEquals(a: GridCoord, b: GridCoord): boolean {
+  return a.x === b.x && a.y === b.y
+}
+
+export function drawingCoordEquals(a: DrawingCoord, b: DrawingCoord): boolean {
+  return a.x === b.x && a.y === b.y
+}
+
+/** Apply a direction offset to a grid coordinate (move into the 3x3 block). */
+export function gridCoordDirection(c: GridCoord, dir: Direction): GridCoord {
+  return { x: c.x + dir.x, y: c.y + dir.y }
+}
+
+/** Key for storing GridCoord in a Map. */
+export function gridKey(c: GridCoord): string {
+  return `${c.x},${c.y}`
+}
+
+/**
+ * Get a node's grid coordinate. Every consumer of a node's `gridCoord` after
+ * layout (edge routing, edge bundling, drawing) runs strictly after
+ * `createMapping` (grid.ts) has placed every node, so this is always defined
+ * for a real graph — but that guarantee lives in layout's control flow, not
+ * in `AsciiNode`'s type (`gridCoord: GridCoord | null`), so it's narrowed
+ * here explicitly rather than trusted silently across the module boundary.
+ *
+ * Lives here (not in grid.ts, where it originated) because it's a pure
+ * predicate over `AsciiNode` with zero dependency on grid/layout state —
+ * keeping it here lets `draw-boxes.ts` and `draw-bundles.ts` reuse it
+ * without pulling in all of grid.ts's transitive imports.
+ */
+export function requireGridCoord(node: AsciiNode): GridCoord {
+  const gc = node.gridCoord
+  if (gc === null) {
+    /* v8 ignore next */
+    throw new Error(
+      `Node "${node.name}" has no gridCoord; grid layout must run before it is read`,
+    )
+  }
+  return gc
+}
+
+/** Default empty style class. */
+export const EMPTY_STYLE: AsciiStyleClass = { name: '', styles: {} }
+
+// ============================================================================
+// Character role types for colored output
+// ============================================================================
+
+/**
+ * Role of a character in the ASCII diagram, used for theming.
+ * Each role maps to a different color when colors are enabled.
+ */
+export type CharRole =
+  | 'text' // Node labels, edge labels
+  | 'border' // Node box borders, subgraph borders
+  | 'line' // Edge lines (paths between nodes)
+  | 'arrow' // Arrowheads (▲▼◄► or ^v<>)
+  | 'corner' // Corner characters at path bends
+  | 'junction' // Junction characters (┬┴├┤ where edges meet boxes)
+
+/**
+ * Role canvas — parallel to Canvas, tracks the role of each character.
+ * Same column-major structure: roleCanvas[x][y] gives the role at (x, y).
+ * null means the character has no role (whitespace).
+ */
+export type RoleCanvas = (CharRole | null)[][]
+
+/**
+ * Theme colors for ASCII output — hex color strings.
+ * Derived from the SVG theme system for visual consistency.
+ */
+export interface AsciiTheme {
+  /** Text color (node labels, edge labels) */
+  fg: string
+  /** Box border color (node borders, subgraph borders) */
+  border: string
+  /** Edge line color (paths between nodes) */
+  line: string
+  /** Arrowhead color (▲▼◄► or ^v<>) */
+  arrow: string
+  /** Theme accent color (optional, used by xycharts for series 0) */
+  accent?: string
+  /** Background color (optional, used by xycharts for dark-mode-aware shading) */
+  bg?: string
+  /** Corner character color (optional, defaults to line) */
+  corner?: string
+  /** Junction character color (optional, defaults to border) */
+  junction?: string
+}
+
+/** Color mode for output. */
+export type ColorMode =
+  | 'none' // No colors (plain text)
+  | 'ansi16' // 16-color ANSI (basic terminals)
+  | 'ansi256' // 256-color ANSI (xterm)
+  | 'truecolor' // 24-bit RGB (modern terminals)
+  | 'html' // HTML <span> tags with inline color styles (browsers)
+
+// ============================================================================
+// Edge bundling types
+// ============================================================================
+
+/**
+ * Edge bundle — groups edges that share a common source or target.
+ * Used to visually merge parallel links before they reach the shared node.
+ *
+ * For fan-in (A & B --> C): multiple sources converge to one target.
+ * For fan-out (A --> B & C): one source diverges to multiple targets.
+ */
+export interface EdgeBundle {
+  /** Bundle type: fan-in = many→one, fan-out = one→many */
+  type: 'fan-in' | 'fan-out'
+  /** Edges in this bundle */
+  edges: AsciiEdge[]
+  /** The common node (target for fan-in, source for fan-out) */
+  sharedNode: AsciiNode
+  /** The non-shared nodes (sources for fan-in, targets for fan-out) */
+  otherNodes: AsciiNode[]
+  /** Junction point where edges merge/split — set during routing */
+  junctionPoint: GridCoord | null
+  /** Path from junction to shared node (drawn once for all edges) */
+  sharedPath: GridCoord[]
+  /** Direction when entering/exiting the junction */
+  junctionDir: Direction
+  /** Direction when entering/exiting the shared node */
+  sharedNodeDir: Direction
+}

package/src/validate.ts

@@ -0,0 +1,189 @@
+/**
+ * ASCII Rendering Validation Utilities
+ *
+ * Provides validation functions for ASCII diagram output,
+ * including diagonal line detection to ensure orthogonal-only routing.
+ */
+
+/**
+ * Characters that represent diagonal lines in ASCII and Unicode modes.
+ * These should never appear in properly rendered diagrams.
+ */
+export const DIAGONAL_CHARS = {
+  ascii: ['/', '\\'],
+  unicode: ['\u2571', '\u2572'], // ╱ ╲
+  all: ['/', '\\', '\u2571', '\u2572'],
+} as const
+
+/**
+ * Position of a diagonal character in ASCII output.
+ */
+export interface DiagonalPosition {
+  line: number
+  col: number
+  char: string
+}
+
+/**
+ * Type guard narrowing a single character to one of `DIAGONAL_CHARS.all`.
+ */
+function isDiagonalChar(
+  char: string,
+): char is (typeof DIAGONAL_CHARS.all)[number] {
+  return (DIAGONAL_CHARS.all as readonly string[]).includes(char)
+}
+
+/**
+ * Check if ASCII output contains any diagonal line characters.
+ * Returns true if diagonals are found (which is an error condition).
+ *
+ * @param asciiOutput - The rendered ASCII diagram string
+ * @returns true if diagonal characters are present, false otherwise
+ */
+export function hasDiagonalLines(asciiOutput: string): boolean {
+  return DIAGONAL_CHARS.all.some((char) => asciiOutput.includes(char))
+}
+
+/**
+ * Find all diagonal line character positions in ASCII output.
+ * Useful for debugging when diagonals are detected.
+ *
+ * Skips diagonal characters that appear inside node labels (between box borders).
+ * This prevents false positives from labels like "feature/auth" or "release/1.0".
+ *
+ * @param asciiOutput - The rendered ASCII diagram string
+ * @returns Array of positions where diagonal characters were found
+ */
+export function findDiagonalLines(asciiOutput: string): DiagonalPosition[] {
+  const positions: DiagonalPosition[] = []
+  const lines = asciiOutput.split('\n')
+
+  // Box-drawing characters that indicate node boundaries
+  const boxBorders = new Set(['│', '┤', '├', '║', '┃', '|'])
+
+  for (const [lineNum, line] of lines.entries()) {
+    // Find all box border positions in this line
+    const borderPositions: number[] = []
+    for (let col = 0; col < line.length; col++) {
+      if (boxBorders.has(line[col]!)) {
+        borderPositions.push(col)
+      }
+    }
+
+    for (let col = 0; col < line.length; col++) {
+      const char = line[col]!
+      if (isDiagonalChar(char)) {
+        // Check if this position is inside a node (between two box borders)
+        // Find the nearest borders before and after this position
+        let insideNode = false
+        for (let i = 0; i < borderPositions.length - 1; i++) {
+          const leftBorder = borderPositions[i]!
+          const rightBorder = borderPositions[i + 1]!
+          if (col > leftBorder && col < rightBorder) {
+            // This diagonal char is between two borders - likely inside a node label
+            insideNode = true
+            break
+          }
+        }
+
+        if (!insideNode) {
+          positions.push({
+            line: lineNum + 1, // 1-indexed for human readability
+            col: col + 1,
+            char,
+          })
+        }
+      }
+    }
+  }
+
+  return positions
+}
+
+/**
+ * Assert that ASCII output contains no diagonal lines.
+ * Throws an error with detailed position information if diagonals are found.
+ *
+ * @param asciiOutput - The rendered ASCII diagram string
+ * @param context - Optional context string for error message (e.g., diagram name)
+ * @throws Error if diagonal characters are present
+ */
+export function assertNoDiagonals(asciiOutput: string, context?: string): void {
+  if (!hasDiagonalLines(asciiOutput)) {
+    return
+  }
+
+  const positions = findDiagonalLines(asciiOutput)
+  const contextStr = context ? ` in "${context}"` : ''
+  const positionStr = positions
+    .map((p) => `  Line ${p.line}, Col ${p.col}: '${p.char}'`)
+    .join('\n')
+
+  throw new Error(
+    `Diagonal lines detected${contextStr}. ` +
+      `Edges must use orthogonal Manhattan routing (90° bends only).\n` +
+      `Found ${positions.length} diagonal character(s):\n${positionStr}`,
+  )
+}
+
+/**
+ * Position of an orphaned tee/junction character in ASCII output.
+ */
+export interface OrphanedJunctionPosition {
+  line: number
+  col: number
+  char: string
+}
+
+/**
+ * Find "orphaned" tee/junction characters — a ├/┤/┬/┴ whose perpendicular
+ * arm (the part of the glyph that's supposed to come from a pre-existing
+ * border or line, not from the edge that merged into it) has nothing on
+ * either side. A genuine junction always has *something* immediately on
+ * both sides of that arm (a border character, another line, an arrowhead,
+ * etc.); a blank cell on both sides means the character was written as a
+ * junction without a real line to justify it (see issue #86).
+ *
+ * - ├ / ┤ carry a vertical arm, so both sides means the row above and below.
+ * - ┬ / ┴ carry a horizontal arm, so both sides means the column left and right.
+ *
+ * @param asciiOutput - The rendered ASCII diagram string
+ * @returns Array of positions where an orphaned junction was found
+ */
+export function findOrphanedJunctions(
+  asciiOutput: string,
+): OrphanedJunctionPosition[] {
+  const lines = asciiOutput.split('\n')
+  const positions: OrphanedJunctionPosition[] = []
+
+  for (const [lineNum, line] of lines.entries()) {
+    for (let col = 0; col < line.length; col++) {
+      const char = line[col]!
+      if (char === '├' || char === '┤') {
+        const above = lines[lineNum - 1]?.[col] ?? ' '
+        const below = lines[lineNum + 1]?.[col] ?? ' '
+        if (above === ' ' && below === ' ') {
+          positions.push({ line: lineNum + 1, col: col + 1, char })
+        }
+      } else if (char === '┬' || char === '┴') {
+        const left = line[col - 1] ?? ' '
+        const right = line[col + 1] ?? ' '
+        if (left === ' ' && right === ' ') {
+          positions.push({ line: lineNum + 1, col: col + 1, char })
+        }
+      }
+    }
+  }
+
+  return positions
+}
+
+/**
+ * Check if ASCII output contains any orphaned tee/junction characters.
+ * Returns true if any are found (which is an error condition).
+ *
+ * @param asciiOutput - The rendered ASCII diagram string
+ */
+export function hasOrphanedJunctions(asciiOutput: string): boolean {
+  return findOrphanedJunctions(asciiOutput).length > 0
+}