@oh-my-pi/pi-utils 16.0.7 → 16.0.8

package/src/vendor/mermaid-ascii/ascii/index.ts

@@ -0,0 +1,187 @@
+// ============================================================================
+// beautiful-mermaid — ASCII renderer public API
+//
+// Renders Mermaid diagrams to ASCII or Unicode box-drawing art.
+// No external dependencies — pure TypeScript.
+//
+// Supported diagram types:
+//   - Flowcharts (graph TD / flowchart LR) — grid-based layout with A* pathfinding
+//   - State diagrams (stateDiagram-v2) — same pipeline as flowcharts
+//   - Sequence diagrams (sequenceDiagram) — column-based timeline layout
+//   - Class diagrams (classDiagram) — level-based UML layout
+//   - ER diagrams (erDiagram) — grid layout with crow's foot notation
+//
+// Usage:
+//   import { renderMermaidASCII } from 'beautiful-mermaid'
+//   const ascii = renderMermaidASCII('graph LR\n  A --> B')
+// ============================================================================
+
+import { parseMermaid } from '../parser'
+import { convertToAsciiGraph } from './converter'
+import { createMapping } from './grid'
+import { drawGraph } from './draw'
+import { canvasToString, flipCanvasVertically, flipRoleCanvasVertically } from './canvas'
+import { renderSequenceAscii } from './sequence'
+import { renderClassAscii } from './class-diagram'
+import { renderErAscii } from './er-diagram'
+import { renderXYChartAscii } from './xychart'
+import { detectColorMode, DEFAULT_ASCII_THEME } from './ansi'
+import type { AsciiConfig, AsciiTheme, ColorMode } from './types'
+import type { Direction } from '../types'
+
+// Re-export types for external use
+export type { AsciiTheme, ColorMode }
+export { DEFAULT_ASCII_THEME, detectColorMode }
+
+export interface AsciiRenderOptions {
+  /** 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
+  /**
+   * Force the layout direction, overriding the direction parsed from the
+   * diagram source. Applies to the flowchart + state-diagram grid pipeline
+   * (sequence/class/ER/xychart renderers ignore it). Useful for re-fitting a
+   * wide `LR` graph into a narrow viewport by laying it out top-down.
+   * Default: undefined (use the source's own direction).
+   */
+  direction?: Direction
+  /**
+   * Color mode for output.
+   * - 'none': No colors (plain text)
+   * - 'auto': Auto-detect (terminal ANSI capabilities, or HTML in browsers)
+   * - 'ansi16': 16-color ANSI
+   * - 'ansi256': 256-color xterm
+   * - 'truecolor': 24-bit RGB
+   * - 'html': HTML <span> tags with inline color styles (for browser rendering)
+   * Default: 'auto'
+   */
+  colorMode?: ColorMode | 'auto'
+  /** Theme colors for ASCII output. Uses default theme if not provided. */
+  theme?: Partial<AsciiTheme>
+}
+
+/**
+ * Detect the diagram type from the mermaid source text.
+ * Mirrors the detection logic in src/index.ts for the SVG renderer.
+ */
+function detectDiagramType(text: string): 'flowchart' | 'sequence' | 'class' | 'er' | 'xychart' {
+  const firstLine = text.trim().split('\n')[0]?.trim().toLowerCase() ?? ''
+
+  if (/^xychart(-beta)?\b/.test(firstLine)) return 'xychart'
+  if (/^sequencediagram\s*$/.test(firstLine)) return 'sequence'
+  if (/^classdiagram\s*$/.test(firstLine)) return 'class'
+  if (/^erdiagram\s*$/.test(firstLine)) return 'er'
+
+  // Default: flowchart/state (handled by parseMermaid internally)
+  return 'flowchart'
+}
+
+/**
+ * Render Mermaid diagram text to an ASCII/Unicode string.
+ *
+ * Synchronous — no async layout engine needed (unlike the SVG renderer).
+ * Auto-detects diagram type from the header line and dispatches to
+ * the appropriate renderer.
+ *
+ * @param text - Mermaid source text (any supported diagram type)
+ * @param options - Rendering options
+ * @returns Multi-line ASCII/Unicode string
+ *
+ * @example
+ * ```ts
+ * const result = renderMermaidAscii(`
+ *   graph LR
+ *     A --> B --> C
+ * `, { useAscii: true })
+ *
+ * // Output:
+ * // +---+     +---+     +---+
+ * // |   |     |   |     |   |
+ * // | A |---->| B |---->| C |
+ * // |   |     |   |     |   |
+ * // +---+     +---+     +---+
+ * ```
+ */
+export function renderMermaidASCII(
+  text: string,
+  options: AsciiRenderOptions = {},
+): string {
+  const config: AsciiConfig = {
+    useAscii: options.useAscii ?? false,
+    paddingX: options.paddingX ?? 5,
+    paddingY: options.paddingY ?? 5,
+    boxBorderPadding: options.boxBorderPadding ?? 1,
+    graphDirection: 'TD', // default, overridden for flowcharts below
+  }
+
+  // Resolve color mode ('auto' or unset → detect environment, otherwise use specified mode)
+  const colorMode: ColorMode = options.colorMode === 'auto' || options.colorMode === undefined
+    ? detectColorMode()
+    : options.colorMode
+
+  // Merge user theme with defaults
+  const theme: AsciiTheme = { ...DEFAULT_ASCII_THEME, ...options.theme }
+
+  const diagramType = detectDiagramType(text)
+
+  switch (diagramType) {
+    case 'xychart':
+      return renderXYChartAscii(text, config, colorMode, theme)
+
+    case 'sequence':
+      return renderSequenceAscii(text, config, colorMode, theme)
+
+    case 'class':
+      return renderClassAscii(text, config, colorMode, theme)
+
+    case 'er':
+      return renderErAscii(text, config, colorMode, theme)
+
+    case 'flowchart':
+    default: {
+      // Flowchart + state diagram pipeline (original)
+      const parsed = parseMermaid(text)
+
+      // Honor an explicit direction override. Applied before normalization so
+      // the LR/TD split and the BT vertical-flip below behave exactly as if the
+      // source had authored this direction.
+      if (options.direction) {
+        parsed.direction = options.direction
+      }
+
+      // Normalize direction for grid layout.
+      // BT is laid out as TD then flipped vertically after drawing.
+      // RL is treated as LR (full RL support not yet implemented).
+      if (parsed.direction === 'LR' || parsed.direction === 'RL') {
+        config.graphDirection = 'LR'
+      } else {
+        config.graphDirection = 'TD'
+      }
+
+      const graph = convertToAsciiGraph(parsed, config)
+      createMapping(graph)
+      drawGraph(graph)
+
+      // BT: flip the finished canvas vertically so the flow runs bottom→top.
+      // The grid layout ran as TD; flipping + character remapping produces BT.
+      if (parsed.direction === 'BT') {
+        flipCanvasVertically(graph.canvas)
+        flipRoleCanvasVertically(graph.roleCanvas)
+      }
+
+      return canvasToString(graph.canvas, {
+        roleCanvas: graph.roleCanvas,
+        colorMode,
+        theme,
+      })
+    }
+  }
+}
+
+/** Lowercase alias kept as the public name used by the pi-utils wrapper. */
+export const renderMermaidAscii = renderMermaidASCII

package/src/vendor/mermaid-ascii/ascii/multiline-utils.ts

@@ -0,0 +1,78 @@
+// ============================================================================
+// ASCII renderer — multi-line text utilities
+//
+// Shared utilities for handling multi-line labels (containing \n from <br> tags)
+// in ASCII/Unicode rendering. Provides consistent text splitting, sizing, and
+// centered rendering across all diagram types.
+// ============================================================================
+
+import type { Canvas } from './types'
+import { drawText } from './canvas'
+import { displayWidth } from '../text-metrics'
+
+/**
+ * Split a label into lines.
+ * Labels are already normalized by parsers (br tags → \n).
+ */
+export function splitLines(label: string): string[] {
+  return label.split('\n')
+}
+
+/**
+ * Get the maximum line width for sizing calculations.
+ * Used to determine column widths for multi-line labels.
+ */
+export function maxLineWidth(label: string): number {
+  const lines = splitLines(label)
+  return Math.max(...lines.map(l => displayWidth(l)), 0)
+}
+
+/**
+ * Get the number of lines for height calculations.
+ * Used to determine row heights for multi-line labels.
+ */
+export function lineCount(label: string): number {
+  return splitLines(label).length
+}
+
+/**
+ * Draw multi-line text centered at (cx, cy).
+ * Expands vertically from the center point.
+ * Each line is horizontally centered independently.
+ */
+export function drawMultilineTextCentered(
+  canvas: Canvas,
+  label: string,
+  cx: number,
+  cy: number
+): void {
+  const lines = splitLines(label)
+  const totalHeight = lines.length
+  // Center vertically: start y positions lines evenly around cy
+  const startY = cy - Math.floor((totalHeight - 1) / 2)
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    // Center each line horizontally
+    const startX = cx - Math.floor(displayWidth(line) / 2)
+    // Force overwrite for node labels (they take priority)
+    drawText(canvas, { x: startX, y: startY + i }, line, true)
+  }
+}
+
+/**
+ * Draw multi-line text left-aligned starting at (x, y).
+ * Each subsequent line is placed one row below.
+ */
+export function drawMultilineTextLeft(
+  canvas: Canvas,
+  label: string,
+  x: number,
+  y: number
+): void {
+  const lines = splitLines(label)
+  for (let i = 0; i < lines.length; i++) {
+    // Force overwrite for node labels (they take priority)
+    drawText(canvas, { x, y: y + i }, lines[i]!, true)
+  }
+}

package/src/vendor/mermaid-ascii/ascii/pathfinder.ts

@@ -0,0 +1,215 @@
+// ============================================================================
+// ASCII renderer — A* pathfinding for edge routing
+//
+// Ported from AlexanderGrooff/mermaid-ascii cmd/arrow.go.
+// Uses A* search with a corner-penalizing heuristic to find clean
+// paths between nodes on the grid. Prefers straight lines over zigzags.
+// ============================================================================
+
+import type { GridCoord, AsciiNode } from './types'
+import { gridKey, gridCoordEquals } from './types'
+
+// ============================================================================
+// Priority queue (min-heap) for A* open set
+// ============================================================================
+
+interface PQItem {
+  coord: GridCoord
+  priority: number
+}
+
+/**
+ * Simple min-heap priority queue.
+ * For the grid sizes we handle (~100s of cells), this is more than fast enough.
+ */
+class MinHeap {
+  private items: PQItem[] = []
+
+  get length(): number {
+    return this.items.length
+  }
+
+  push(item: PQItem): void {
+    this.items.push(item)
+    this.bubbleUp(this.items.length - 1)
+  }
+
+  pop(): PQItem | undefined {
+    if (this.items.length === 0) return undefined
+    const top = this.items[0]!
+    const last = this.items.pop()!
+    if (this.items.length > 0) {
+      this.items[0] = last
+      this.sinkDown(0)
+    }
+    return top
+  }
+
+  private bubbleUp(i: number): void {
+    while (i > 0) {
+      const parent = (i - 1) >> 1
+      if (this.items[i]!.priority < this.items[parent]!.priority) {
+        ;[this.items[i], this.items[parent]] = [this.items[parent]!, this.items[i]!]
+        i = parent
+      } else {
+        break
+      }
+    }
+  }
+
+  private sinkDown(i: number): void {
+    const n = this.items.length
+    while (true) {
+      let smallest = i
+      const left = 2 * i + 1
+      const right = 2 * i + 2
+      if (left < n && this.items[left]!.priority < this.items[smallest]!.priority) {
+        smallest = left
+      }
+      if (right < n && this.items[right]!.priority < this.items[smallest]!.priority) {
+        smallest = right
+      }
+      if (smallest !== i) {
+        ;[this.items[i], this.items[smallest]] = [this.items[smallest]!, this.items[i]!]
+        i = smallest
+      } else {
+        break
+      }
+    }
+  }
+}
+
+// ============================================================================
+// A* heuristic
+// ============================================================================
+
+/**
+ * Manhattan distance with a +1 penalty when both dx and dy are non-zero.
+ * This encourages the pathfinder to prefer straight lines and minimize corners.
+ */
+export function heuristic(a: GridCoord, b: GridCoord): number {
+  const absX = Math.abs(a.x - b.x)
+  const absY = Math.abs(a.y - b.y)
+  if (absX === 0 || absY === 0) {
+    return absX + absY
+  }
+  return absX + absY + 1
+}
+
+// ============================================================================
+// A* pathfinding
+// ============================================================================
+
+/** 4-directional movement (no diagonals in grid pathfinding). */
+const MOVE_DIRS: GridCoord[] = [
+  { x: 1, y: 0 },
+  { x: -1, y: 0 },
+  { x: 0, y: 1 },
+  { x: 0, y: -1 },
+]
+
+/** Check if a grid cell is unoccupied and has non-negative coordinates. */
+function isFreeInGrid(grid: Map<string, AsciiNode>, c: GridCoord): boolean {
+  if (c.x < 0 || c.y < 0) return false
+  return !grid.has(gridKey(c))
+}
+
+/**
+ * Find a path from `from` to `to` on the grid using A*.
+ * Returns the path as an array of GridCoords, or null if no path exists.
+ */
+export function getPath(
+  grid: Map<string, AsciiNode>,
+  from: GridCoord,
+  to: GridCoord,
+): GridCoord[] | null {
+  const pq = new MinHeap()
+  pq.push({ coord: from, priority: 0 })
+
+  const costSoFar = new Map<string, number>()
+  costSoFar.set(gridKey(from), 0)
+
+  const cameFrom = new Map<string, GridCoord | null>()
+  cameFrom.set(gridKey(from), null)
+
+  while (pq.length > 0) {
+    const current = pq.pop()!.coord
+
+    if (gridCoordEquals(current, to)) {
+      // Reconstruct path by walking backwards through cameFrom
+      const path: GridCoord[] = []
+      let c: GridCoord | null = current
+      while (c !== null) {
+        path.unshift(c)
+        c = cameFrom.get(gridKey(c)) ?? null
+      }
+      return path
+    }
+
+    const currentCost = costSoFar.get(gridKey(current))!
+
+    for (const dir of MOVE_DIRS) {
+      const next: GridCoord = { x: current.x + dir.x, y: current.y + dir.y }
+
+      // Allow moving to the destination even if it's occupied (it's a node boundary)
+      if (!isFreeInGrid(grid, next) && !gridCoordEquals(next, to)) {
+        continue
+      }
+
+      const newCost = currentCost + 1
+      const nextKey = gridKey(next)
+      const existingCost = costSoFar.get(nextKey)
+
+      if (existingCost === undefined || newCost < existingCost) {
+        costSoFar.set(nextKey, newCost)
+        const priority = newCost + heuristic(next, to)
+        pq.push({ coord: next, priority })
+        cameFrom.set(nextKey, current)
+      }
+    }
+  }
+
+  return null // No path found
+}
+
+/**
+ * Simplify a path by removing intermediate waypoints on straight segments.
+ * E.g., [(0,0), (1,0), (2,0), (2,1)] becomes [(0,0), (2,0), (2,1)].
+ * This reduces the number of line-drawing operations.
+ */
+export function mergePath(path: GridCoord[]): GridCoord[] {
+  if (path.length <= 2) return path
+
+  const toRemove = new Set<number>()
+  let step0 = path[0]!
+  let step1 = path[1]!
+
+  for (let idx = 2; idx < path.length; idx++) {
+    const step2 = path[idx]!
+    const prevDx = step1.x - step0.x
+    const prevDy = step1.y - step0.y
+    const dx = step2.x - step1.x
+    const dy = step2.y - step1.y
+
+    // Same direction — the middle point is redundant
+    if (prevDx === dx && prevDy === dy) {
+      // In Go: indexToRemove = append(indexToRemove, idx+1) but idx is 0-based from path[2:]
+      // which corresponds to index idx in the full path. Go uses idx+1 because idx iterates
+      // from 0 in the [2:] slice, mapping to full-array index idx+1.
+      // Actually re-checking Go code: the loop is `for idx, step2 := range path[2:]`
+      // so idx=0 → path[2], and it removes idx+1 which is index 1 in the full array.
+      // Wait, that doesn't look right. Let me re-read:
+      //   step0 = path[0], step1 = path[1]
+      //   for idx, step2 := range path[2:] { ... indexToRemove = append(indexToRemove, idx+1) ... }
+      //   When idx=0, step2=path[2], and it removes index 1 (step1 = path[1]) if directions match
+      // So it removes the middle point (step1) which is at index idx+1 in the original array
+      // when counting from the 2-ahead loop. Let me just track which middle indices to remove.
+      toRemove.add(idx - 1) // Remove the middle point (step1's position)
+    }
+
+    step0 = step1
+    step1 = step2
+  }
+
+  return path.filter((_, i) => !toRemove.has(i))
+}