agentic-mermaid 0.1.1 → 0.2.0

package/src/ascii/pathfinder.ts

@@ -1,301 +0,0 @@
-// ============================================================================
-// 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, Direction } from './types.ts'
-import { gridKey, gridCoordEquals } from './types.ts'
-
-// ============================================================================
-// Priority queue (min-heap) for A* open set
-// ============================================================================
-
-interface PQItem {
-  coord: GridCoord
-  priority: number
-  /**
-   * Monotonic insertion sequence. Used as a deterministic FIFO tie-breaker so
-   * equal-priority nodes pop in insertion order regardless of heap topology
-   * (upstream lukilabs#113). Without this, the order two equal-priority cells
-   * are visited depends on incidental heap shape, which let sibling fan-out
-   * edges pick inconsistent corners and produce L-shaped detours.
-   */
-  seq: number
-}
-
-/**
- * Simple min-heap priority queue with deterministic FIFO tie-breaking.
- * 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
-  }
-
-  /**
-   * Order two heap items: by priority, then by insertion sequence (FIFO).
-   * Returns true if `a` should sit above `b` in the min-heap.
-   */
-  private before(a: PQItem, b: PQItem): boolean {
-    if (a.priority !== b.priority) return a.priority < b.priority
-    return a.seq < b.seq
-  }
-
-  private bubbleUp(i: number): void {
-    while (i > 0) {
-      const parent = (i - 1) >> 1
-      if (this.before(this.items[i]!, this.items[parent]!)) {
-        ;[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
-      // Upstream lukilabs#113 used `<=` here to break ties; we encode the same
-      // determinism explicitly via the seq tie-breaker in `before`, which is
-      // unambiguous regardless of traversal order.
-      if (left < n && this.before(this.items[left]!, this.items[smallest]!)) {
-        smallest = left
-      }
-      if (right < n && this.before(this.items[right]!, this.items[smallest]!)) {
-        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 },
-]
-
-/** Build a move-direction order that tries the edge's initial cardinal direction first. */
-function buildMoveDirs(preferredDir?: Direction): GridCoord[] {
-  if (!preferredDir) return [...MOVE_DIRS]
-
-  // Direction values are 3x3 node attachment offsets, not signed deltas:
-  // Up={1,0}, Down={1,2}, Left={0,1}, Right={2,1}.
-  if (preferredDir.x === 2 && preferredDir.y === 1) {
-    return [{ x: 1, y: 0 }, { x: -1, y: 0 }, { x: 0, y: 1 }, { x: 0, y: -1 }]
-  }
-  if (preferredDir.x === 0 && preferredDir.y === 1) {
-    return [{ x: -1, y: 0 }, { x: 1, y: 0 }, { x: 0, y: 1 }, { x: 0, y: -1 }]
-  }
-  if (preferredDir.x === 1 && preferredDir.y === 2) {
-    return [{ x: 0, y: 1 }, { x: 0, y: -1 }, { x: 1, y: 0 }, { x: -1, y: 0 }]
-  }
-  if (preferredDir.x === 1 && preferredDir.y === 0) {
-    return [{ x: 0, y: -1 }, { x: 0, y: 1 }, { x: 1, y: 0 }, { x: -1, y: 0 }]
-  }
-
-  const dx = preferredDir.x - 1
-  const dy = preferredDir.y - 1
-  if (Math.abs(dx) >= Math.abs(dy)) {
-    return dx >= 0
-      ? [{ x: 1, y: 0 }, { x: -1, y: 0 }, { x: 0, y: 1 }, { x: 0, y: -1 }]
-      : [{ x: -1, y: 0 }, { x: 1, y: 0 }, { x: 0, y: 1 }, { x: 0, y: -1 }]
-  }
-  return dy >= 0
-    ? [{ x: 0, y: 1 }, { x: 0, y: -1 }, { x: 1, y: 0 }, { x: -1, y: 0 }]
-    : [{ x: 0, y: -1 }, { x: 0, y: 1 }, { x: 1, y: 0 }, { x: -1, y: 0 }]
-}
-
-/** 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.
- *
- * @param preferredDir - Optional exit direction tried first during neighbour
- *   expansion (see `orderedDirs`). Currently unused by the edge router; kept as
- *   a tested capability and exercised by ascii-pathfinder-determinism.test.ts.
- */
-export function getPath(
-  grid: Map<string, AsciiNode>,
-  from: GridCoord,
-  to: GridCoord,
-  preferredDir?: Direction,
-): GridCoord[] | null {
-  // #66 (ktrysmt): bound the search. `isFreeInGrid` only guards x/y < 0, so an
-  // unreachable target (walled off) would let A* explore +x/+y unboundedly →
-  // OOM/hang. Derive an upper bound from the grid extent + the from/to coords,
-  // plus a hard iteration cap. On exhaustion we return null and the caller
-  // falls back to a direct route, rather than exhausting memory.
-  let maxX = Math.max(from.x, to.x)
-  let maxY = Math.max(from.y, to.y)
-  for (const key of grid.keys()) {
-    const comma = key.indexOf(',')
-    const kx = Number(key.slice(0, comma))
-    const ky = Number(key.slice(comma + 1))
-    if (kx > maxX) maxX = kx
-    if (ky > maxY) maxY = ky
-  }
-  // Margin lets routes detour slightly around obstacles past the extent.
-  const boundX = maxX + 4
-  const boundY = maxY + 4
-  // Iteration cap proportional to the bounded grid area (with a floor).
-  const maxIterations = Math.max(10_000, (boundX + 1) * (boundY + 1) * 4)
-
-  const moveDirs = buildMoveDirs(preferredDir)
-
-  let seq = 0
-  const pq = new MinHeap()
-  pq.push({ coord: from, priority: 0, seq: seq++ })
-
-  const costSoFar = new Map<string, number>()
-  costSoFar.set(gridKey(from), 0)
-
-  const cameFrom = new Map<string, GridCoord | null>()
-  cameFrom.set(gridKey(from), null)
-
-  let iterations = 0
-  while (pq.length > 0) {
-    if (++iterations > maxIterations) return null // #66 guard: bail to caller's fallback
-    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 moveDirs) {
-      const next: GridCoord = { x: current.x + dir.x, y: current.y + dir.y }
-
-      // #66 guard: never expand past the bounded extent. Without this, an
-      // unreachable target lets the search wander the unbounded +x/+y plane.
-      if (next.x > boundX || next.y > boundY) continue
-
-      // 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, seq: seq++ })
-        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))
-}

package/src/ascii/pie.ts

@@ -1,67 +0,0 @@
-// ============================================================================
-// ASCII renderer — Pie chart
-//
-// A pie chart doesn't map cleanly to a character grid, so we render it as a
-// proportional horizontal bar list (the conventional terminal pie rendering):
-//
-//   Pets (title, if present)
-//   Dogs  ████████████████████████  77.2%
-//   Cats  █████                     17.0%
-//   Rats  █                          5.8%
-//
-// Each bar's length is proportional to the slice's share of the total. With
-// `showData` the raw value is shown alongside the percentage. Bars use █
-// (Unicode) or # (ASCII fallback), colored per-slice with the same xychart
-// palette as the SVG renderer for cross-format consistency.
-// ============================================================================
-
-import { parsePieChart } from '../pie/parser.ts'
-import { formatPieValue, formatPiePercent } from '../pie/layout.ts'
-import type { AsciiConfig, AsciiTheme, ColorMode } from './types.ts'
-import { colorizeText } from './ansi.ts'
-import { getSeriesColor, CHART_ACCENT_FALLBACK, isValidHex } from '../xychart/colors.ts'
-
-/** Maximum bar length in characters (the largest slice fills this). */
-const MAX_BAR = 30
-
-function sliceColor(index: number, theme: AsciiTheme): string {
-  const accent = theme.accent && isValidHex(theme.accent) ? theme.accent : CHART_ACCENT_FALLBACK
-  return getSeriesColor(index, accent, theme.bg)
-}
-
-export function renderPieAscii(
-  lines: string[],
-  config: AsciiConfig,
-  colorMode: ColorMode,
-  theme: AsciiTheme,
-): string {
-  const chart = parsePieChart(lines)
-  const barChar = config.useAscii ? '#' : '█'
-
-  const total = chart.entries.reduce((sum, e) => sum + e.value, 0)
-  if (total <= 0) return ''
-
-  // Column widths.
-  const labelWidth = Math.max(...chart.entries.map(e => e.label.length))
-  const maxValue = Math.max(...chart.entries.map(e => e.value))
-
-  const out: string[] = []
-  if (chart.title) out.push(chart.title)
-
-  chart.entries.forEach((entry, index) => {
-    const fraction = entry.value / total
-    // Bar length proportional to the largest slice, min 1 char for nonzero.
-    const barLen = Math.max(1, Math.round((entry.value / maxValue) * MAX_BAR))
-    const bar = barChar.repeat(barLen)
-    const coloredBar = colorMode === 'none' ? bar : colorizeText(bar, sliceColor(index, theme), colorMode)
-
-    const label = entry.label.padEnd(labelWidth)
-    const barPad = ' '.repeat(MAX_BAR - barLen + 2)
-    const pct = formatPiePercent(fraction).padStart(6)
-    const valuePart = chart.showData ? `  [${formatPieValue(entry.value)}]` : ''
-
-    out.push(`${label}  ${coloredBar}${barPad}${pct}${valuePart}`)
-  })
-
-  return out.join('\n')
-}

package/src/ascii/quadrant.ts

@@ -1,158 +0,0 @@
-// ============================================================================
-// ASCII renderer — Quadrant chart
-//
-// Renders a bordered SQUARE grid divided into four quadrants. Quadrant labels
-// sit in their regions, points are plotted at scaled positions marked ●
-// (Unicode) / * (ASCII), and a legend below lists every point's coordinates.
-//
-// Mermaid quadrant numbering: 1=top-right, 2=top-left, 3=bottom-left,
-// 4=bottom-right. Normalized coords (x,y) ∈ [0,1]², y grows UP. Scaling
-// follows the xychart convention: round(t * (extent - 1)).
-// ============================================================================
-
-import { parseQuadrantChart } from '../quadrant/parser.ts'
-import type { QuadrantChart } from '../quadrant/types.ts'
-import type { AsciiConfig, AsciiTheme, ColorMode } from './types.ts'
-import { colorizeText } from './ansi.ts'
-
-/** Interior plot dimensions in cells (odd so the dividers land cleanly). */
-const GRID_W = 41
-const GRID_H = 21
-
-const UNI = {
-  tl: '┌', tr: '┐', bl: '└', br: '┘',
-  h: '─', v: '│',
-  tDown: '┬', tUp: '┴', tLeft: '┤', tRight: '├', cross: '┼',
-  point: '●',
-} as const
-
-const ASC = {
-  tl: '+', tr: '+', bl: '+', br: '+',
-  h: '-', v: '|',
-  tDown: '+', tUp: '+', tLeft: '+', tRight: '+', cross: '+',
-  point: '*',
-} as const
-
-export function renderQuadrantAscii(
-  lines: string[],
-  config: AsciiConfig,
-  colorMode: ColorMode,
-  theme: AsciiTheme,
-): string {
-  const chart = parseQuadrantChart(lines)
-  const ch = config.useAscii ? ASC : UNI
-
-  // Interior grid (rows × cols of single characters). Row 0 = top.
-  const grid: string[][] = Array.from({ length: GRID_H }, () => Array.from({ length: GRID_W }, () => ' '))
-  const midCol = Math.floor(GRID_W / 2)
-  const midRow = Math.floor(GRID_H / 2)
-
-  // Dividers.
-  for (let r = 0; r < GRID_H; r++) grid[r]![midCol] = ch.v
-  for (let c = 0; c < GRID_W; c++) grid[midRow]![c] = ch.h
-  grid[midRow]![midCol] = ch.cross
-
-  // Points — scaled into the grid. x grows right, y grows up (invert row).
-  // Plotted first so quadrant labels (decorative) never clobber a data point.
-  const occupied = new Set<string>()
-  chart.points.forEach(p => {
-    const col = Math.round(p.x * (GRID_W - 1))
-    const row = Math.round((1 - p.y) * (GRID_H - 1))
-    grid[row]![col] = ch.point
-    occupied.add(`${row},${col}`)
-  })
-
-  // Quadrant labels. When points exist, Mermaid renders quadrant text near the
-  // TOP of each region (so it doesn't fight the data); with no points it sits
-  // in the center. We follow that, and never overwrite a plotted point.
-  const top = chart.points.length > 0
-  placeLabel(grid, occupied, chart.quadrants[1], 0, 0, midRow, midCol, top)                    // q2 top-left
-  placeLabel(grid, occupied, chart.quadrants[0], 0, midCol + 1, midRow, GRID_W, top)           // q1 top-right
-  placeLabel(grid, occupied, chart.quadrants[2], midRow + 1, 0, GRID_H, midCol, top)           // q3 bottom-left
-  placeLabel(grid, occupied, chart.quadrants[3], midRow + 1, midCol + 1, GRID_H, GRID_W, top)  // q4 bottom-right
-
-  // Frame the grid with a border, with axis labels on the edges.
-  const out: string[] = []
-  if (chart.title) out.push(centerText(chart.title, GRID_W + 2))
-
-  out.push(ch.tl + ch.h.repeat(GRID_W) + ch.tr)
-  for (let r = 0; r < GRID_H; r++) {
-    // The mid divider row meets the border as ├ … ┤ junctions.
-    const left = r === midRow ? ch.tRight : ch.v
-    const right = r === midRow ? ch.tLeft : ch.v
-    out.push(left + grid[r]!.join('') + right)
-  }
-  out.push(ch.bl + ch.h.repeat(GRID_W) + ch.br)
-
-  // x-axis labels under the grid (left + right).
-  if (chart.xAxis) {
-    out.push(edgeAxisRow(chart.xAxis.near, chart.xAxis.far, GRID_W + 2))
-  }
-  // y-axis labels as a separate annotated line.
-  if (chart.yAxis) {
-    const top = chart.yAxis.far ? `top: ${chart.yAxis.far}` : ''
-    const bottom = `bottom: ${chart.yAxis.near}`
-    out.push(`y-axis  ${bottom}${top ? `  |  ${top}` : ''}`)
-  }
-
-  // Legend — every point with its coordinates.
-  if (chart.points.length > 0) {
-    out.push('')
-    const pointGlyph = colorMode === 'none' ? ch.point : colorizeText(ch.point, pointColor(theme), colorMode)
-    for (const p of chart.points) {
-      out.push(`${pointGlyph} ${p.label}: [${fmt(p.x)}, ${fmt(p.y)}]`)
-    }
-  }
-
-  return out.join('\n')
-}
-
-function pointColor(theme: AsciiTheme): string {
-  return theme.accent ?? theme.fg
-}
-
-function fmt(n: number): string {
-  return Number.isInteger(n) ? String(n) : String(Math.round(n * 100) / 100)
-}
-
-/**
- * Place a label horizontally centered within a sub-rectangle of the grid.
- * When `top` is set the label sits one row down from the region top; otherwise
- * it is vertically centered. Never overwrites a plotted point.
- */
-function placeLabel(
-  grid: string[][],
-  occupied: Set<string>,
-  label: string | undefined,
-  rowStart: number,
-  colStart: number,
-  rowEnd: number,
-  colEnd: number,
-  top: boolean,
-): void {
-  if (!label) return
-  const regionW = colEnd - colStart
-  const regionH = rowEnd - rowStart
-  if (regionW <= 0 || regionH <= 0) return
-  const text = label.length > regionW ? label.slice(0, regionW) : label
-  const row = top ? rowStart + 1 : rowStart + Math.floor(regionH / 2)
-  const col = colStart + Math.max(0, Math.floor((regionW - text.length) / 2))
-  for (let i = 0; i < text.length && col + i < colEnd; i++) {
-    if (occupied.has(`${row},${col + i}`)) continue
-    grid[row]![col + i] = text[i]!
-  }
-}
-
-function centerText(text: string, width: number): string {
-  if (text.length >= width) return text
-  const pad = Math.floor((width - text.length) / 2)
-  return ' '.repeat(pad) + text
-}
-
-/** Bottom edge axis row: near label left-aligned, far label right-aligned. */
-function edgeAxisRow(near: string, far: string | undefined, width: number): string {
-  if (!far) return near
-  const gap = width - near.length - far.length
-  if (gap < 1) return `${near} ${far}`
-  return near + ' '.repeat(gap) + far
-}