agentic-mermaid 0.1.1 → 0.1.2

package/src/ascii/types.ts

@@ -1,312 +0,0 @@
-// ============================================================================
-// 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, EdgeMarker, RouteClass } from '../types.ts'
-
-// Re-export shared graph types for convenience
-export type { NodeShape, EdgeMarker }
-
-/**
- * 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
-}
-
-/** 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,
-]
-
-/**
- * 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
-  /**
-   * Source container when the Mermaid edge targets a subgraph id.
-   * Consumed by the converter/grid (grid.ts attachment-point selection) and by
-   * draw.ts's getSubgraphAttachmentPoint to choose WHERE on the container the
-   * edge anchors. NOT the same as attachFromSubgraph (see below), which only
-   * drives border clipping.
-   */
-  fromSubgraph?: AsciiSubgraph
-  /**
-   * Target container when the Mermaid edge targets a subgraph id.
-   * Mirror of fromSubgraph for the edge target. Consumed by grid.ts and
-   * draw.ts's getSubgraphAttachmentPoint for attachment-point selection.
-   */
-  toSubgraph?: AsciiSubgraph
-  text: string
-  path: GridCoord[]
-  labelLine: GridCoord[]
-  startDir: Direction
-  endDir: Direction
-  /** Shared semantic route intent from classifyRoutes(); consumed by grid placement/routing parity. */
-  routeClass?: RouteClass
-  /** Line style: solid (default), dotted (-.->) or thick (==>) */
-  style: AsciiEdgeStyle
-  /** Whether to render a marker at the start (source end) of the edge */
-  hasArrowStart: boolean
-  /** Whether to render a marker at the end (target end) of the edge */
-  hasArrowEnd: boolean
-  /** Marker shape at start when hasArrowStart=true. Defaults to 'arrow' if undefined. */
-  startMarker?: EdgeMarker
-  /** Marker shape at end when hasArrowEnd=true. Defaults to 'arrow' if undefined. */
-  endMarker?: EdgeMarker
-  /** 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[]
-  /**
-   * BUILD-14: when an edge endpoint is a subgraph id (rather than a real node),
-   * the edge attaches to the subgraph container, not a phantom node. For
-   * layout/routing we anchor the edge on a representative member of the
-   * container, but the visible terminus is clipped to the container's border.
-   * - attachFromSubgraph: the SOURCE of the edge is a subgraph container.
-   * - attachToSubgraph: the TARGET of the edge is a subgraph container.
-   *
-   * Consumed ONLY by draw.ts's drawContainerEdge, which clips the routed
-   * polyline at the container border (clipPolylineAtBorder). Distinct from
-   * fromSubgraph/toSubgraph above: those pick the attachment point; these pick
-   * where to clip. Both pairs can be set, and they are not interchangeable.
-   */
-  attachFromSubgraph?: AsciiSubgraph
-  attachToSubgraph?: AsciiSubgraph
-}
-
-/** A subgraph container with bounding box for rendering. */
-export interface AsciiSubgraph {
-  /** Mermaid subgraph id (distinct from the display label); used for container-edge references. */
-  id: string
-  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'
-}
-
-/** 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 — maps "x,y" keys to node references. */
-  grid: Map<string, AsciiNode>
-  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[]
-  /** Grid coordinates where sibling-edge trunk branches need explicit T-junctions. */
-  trunkJunctions: GridCoord[]
-}
-
-// ============================================================================
-// 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}`
-}
-
-/** 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/ascii/validate.ts

@@ -1,120 +0,0 @@
-/**
- * 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
-}
-
-/**
- * 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 (let lineNum = 0; lineNum < lines.length; lineNum++) {
-    const line = lines[lineNum]!
-
-    // 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 (DIAGONAL_CHARS.all.includes(char as '/' | '\\' | '╱' | '╲')) {
-        // 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}`
-  )
-}

package/src/ascii/width.ts

@@ -1,81 +0,0 @@
-// ============================================================================
-// Terminal display width helpers for ASCII/Unicode rendering.
-//
-// Range tables live in src/shared/unicode-ranges.ts so the SVG metrics
-// module can share them without the ascii/ → core import that the
-// substrate lint forbids.
-//
-// Variation selectors (U+FE0E / U+FE0F) modify the WIDTH of the preceding
-// base codepoint, so `visualWidth` does a two-pass tally rather than a
-// per-codepoint sum: it remembers the last-emitted width and rewrites it
-// when a selector arrives. ZWJ (U+200D) and FE0E both have width 0; FE0F
-// forces the previous base to width 2.
-// ============================================================================
-
-import { isWideRange, isZeroWidth, VS_TEXT, VS_EMOJI, ZWJ } from '../shared/unicode-ranges.ts'
-
-/** Sentinel stored in the canvas cell following a fullwidth character. */
-export const WIDE_CHAR_CONTINUATION = '\x00'
-
-/**
- * Width of a single codepoint, with no knowledge of neighbours.
- * Variation selectors are reported as zero-width here; the per-string
- * `visualWidth` applies the selector's retroactive width override.
- */
-export function charVisualWidth(ch: string): number {
-  const code = ch.codePointAt(0) ?? 0
-  if (code === VS_TEXT || code === VS_EMOJI || code === ZWJ) return 0
-  if (isZeroWidth(code)) return 0
-  if (isWideRange(code)) return 2
-  return 1
-}
-
-/**
- * Terminal display width of a string, in cells.
- *
- * Iterates codepoints and applies these post-process rules:
- *   - FE0F  (emoji-presentation selector): force the preceding base to width 2
- *   - FE0E  (text-presentation selector):  force the preceding base to width 1
- *   - 200D  (ZWJ):                          zero width; binds the next base
- *           into an emoji ZWJ sequence — the next base is also forced to 0
- *           so a man-with-laptop (👨‍💻) totals 2 cells, not 4.
- */
-export function visualWidth(text: string): number {
-  let total = 0
-  let lastBaseWidth = 0
-  let zwjPending = false
-  for (const ch of text) {
-    const code = ch.codePointAt(0) ?? 0
-    if (code === VS_EMOJI) {
-      if (lastBaseWidth === 1) {
-        total += 1
-        lastBaseWidth = 2
-      }
-      continue
-    }
-    if (code === VS_TEXT) {
-      if (lastBaseWidth === 2) {
-        total -= 1
-        lastBaseWidth = 1
-      }
-      continue
-    }
-    if (code === ZWJ) {
-      zwjPending = true
-      lastBaseWidth = 0
-      continue
-    }
-    if (isZeroWidth(code)) {
-      lastBaseWidth = 0
-      continue
-    }
-    let w = isWideRange(code) ? 2 : 1
-    if (zwjPending) {
-      w = 0
-      zwjPending = false
-    }
-    total += w
-    lastBaseWidth = w
-  }
-  return total
-}

package/src/ascii/wrap.ts

@@ -1,131 +0,0 @@
-// ============================================================================
-// ASCII renderer — width-aware text wrapping.
-//
-// Shared by the journey and timeline ASCII renderers. Wrapping iterates
-// grapheme clusters (Intl.Segmenter) rather than codepoints and measures
-// candidates with the whole-string `visualWidth`, so FE0F emoji count their
-// display width (a per-codepoint sum sees ❤️ as 1 cell; it renders as 2)
-// and ZWJ sequences (👩‍🔬) are never split mid-grapheme.
-//
-// Mid-word breaks follow the SVG layout's breakWordToWidth convention
-// (src/journey/layout.ts): the continuing chunk takes a trailing '-',
-// except when the break falls between two double-width clusters — CJK and
-// fullwidth text wraps at any character without hyphenation.
-// ============================================================================
-
-import { visualWidth } from './width.ts'
-
-/** Options for wrapText/wrapParagraph/breakWord. */
-export interface WrapOptions {
-  /**
-   * Append '-' where a word is broken mid-line (suppressed between
-   * double-width clusters, and when the hyphen itself would not fit).
-   * Default: true. Glyph strips (e.g. the journey score strip) disable it.
-   */
-  hyphenate?: boolean
-}
-
-/** Grapheme segmentation is locale-independent (UAX #29), so this is deterministic. */
-const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
-
-/** Split a string into grapheme clusters (emoji ZWJ sequences stay whole). */
-export function graphemes(text: string): string[] {
-  return Array.from(segmenter.segment(text), s => s.segment)
-}
-
-/**
- * Wrap text to at most `maxWidth` display cells per line. Embedded '\n' are
- * hard breaks. Without a positive finite maxWidth, only splits on '\n'.
- */
-export function wrapText(text: string, maxWidth: number | undefined, options?: WrapOptions): string[] {
-  if (!maxWidth || !Number.isFinite(maxWidth) || maxWidth <= 0) return text.split('\n')
-  const limit = Math.max(1, Math.floor(maxWidth))
-  const lines: string[] = []
-  for (const paragraph of text.split('\n')) {
-    lines.push(...wrapParagraph(paragraph, limit, options))
-  }
-  return lines.length > 0 ? lines : ['']
-}
-
-/**
- * Wrap a single paragraph (no '\n') at word boundaries by display width.
- * Words wider than maxWidth are broken by `breakWord`.
- */
-export function wrapParagraph(text: string, maxWidth: number, options?: WrapOptions): string[] {
-  if (visualWidth(text) <= maxWidth) return [text]
-  const words = text.split(/\s+/).filter(Boolean)
-  if (words.length === 0) return ['']
-
-  const lines: string[] = []
-  let current = ''
-  for (const word of words) {
-    if (!current) {
-      const chunks = breakWord(word, maxWidth, options)
-      lines.push(...chunks.slice(0, -1))
-      current = chunks[chunks.length - 1] ?? ''
-      continue
-    }
-
-    const candidate = `${current} ${word}`
-    if (visualWidth(candidate) <= maxWidth) {
-      current = candidate
-      continue
-    }
-
-    lines.push(current)
-    const chunks = breakWord(word, maxWidth, options)
-    lines.push(...chunks.slice(0, -1))
-    current = chunks[chunks.length - 1] ?? ''
-  }
-  if (current) lines.push(current)
-  return lines
-}
-
-/**
- * Break a single word into chunks of at most maxWidth cells. Greedy over
- * grapheme clusters: each line takes as many whole clusters as fit,
- * reserving one cell for the trailing hyphen when its break needs one.
- * A cluster wider than maxWidth still gets emitted alone (nothing narrower
- * exists to emit), matching the pre-grapheme behavior.
- */
-export function breakWord(word: string, maxWidth: number, options?: WrapOptions): string[] {
-  if (visualWidth(word) <= maxWidth) return [word]
-  const hyphenate = options?.hyphenate ?? true
-  const clusters = graphemes(word)
-  const lines: string[] = []
-  let start = 0
-  while (start < clusters.length) {
-    let end = start + 1 // always consume at least one cluster per line
-    while (end < clusters.length && fitsWithBreak(clusters, start, end + 1, maxWidth, hyphenate)) end++
-    const chunk = clusters.slice(start, end).join('')
-    const hyphen = end < clusters.length
-      && breakNeedsHyphen(clusters[end - 1]!, clusters[end]!, hyphenate)
-      && visualWidth(chunk) + 1 <= maxWidth
-    lines.push(hyphen ? `${chunk}-` : chunk)
-    start = end
-  }
-  return lines
-}
-
-/** Would clusters[start..end) fit in maxWidth, counting the hyphen its break would need? */
-function fitsWithBreak(
-  clusters: string[],
-  start: number,
-  end: number,
-  maxWidth: number,
-  hyphenate: boolean,
-): boolean {
-  const width = visualWidth(clusters.slice(start, end).join(''))
-  const hyphen = end < clusters.length && breakNeedsHyphen(clusters[end - 1]!, clusters[end]!, hyphenate) ? 1 : 0
-  return width + hyphen <= maxWidth
-}
-
-/**
- * A mid-word break takes a hyphen unless it falls between two double-width
- * clusters (CJK, fullwidth forms, emoji), where hyphenation is not a text
- * convention.
- */
-function breakNeedsHyphen(before: string, after: string, hyphenate: boolean): boolean {
-  if (!hyphenate) return false
-  return !(visualWidth(before) === 2 && visualWidth(after) === 2)
-}