agentic-mermaid 0.1.1 → 0.1.2

package/src/agent/pie-body.ts

@@ -1,270 +0,0 @@
-// ============================================================================
-// Pie structured body (promotes pie from opaque-only fallback semantics to
-// structured mutation, following the journey/xychart/architecture pilots).
-//
-// Modeled grammar (mirrors the legacy renderer parser, src/pie/parser.ts):
-//   pie [showData] [title <text>]
-//   title <text>                 — standalone title directive
-//   showData                     — standalone show-data directive
-//   "<label>" : <positive number>
-//
-// Structured-or-opaque: any other non-blank, non-comment line (accTitle,
-// accDescr, unmodeled syntax) returns null so the caller falls back to a
-// lossless opaque body. We deliberately re-emit a canonical header
-// (`pie showData`) plus standalone `title` / entry lines; the legacy parser
-// re-parses that canonical output identically (differential-tested). Render
-// support is unchanged — the legacy renderer keeps parsing canonical source.
-//
-// The legacy parser ERRORS LOUDLY on malformed entries; here a structured body
-// is only produced when every line is modeled and every entry is a quoted
-// label with a positive numeric value — anything else falls back to opaque
-// (which preserves it verbatim), and the legacy renderer still surfaces the
-// loud error at render time.
-// ============================================================================
-
-import { unknownOpMessage } from './mutation-ops.ts'
-import type {
-  PieBody, PieMutationOp,
-  MutationError, Result, LayoutWarning, VerifyOptions,
-} from './types.ts'
-import { ok, err, DEFAULT_LABEL_CHAR_CAP } from './types.ts'
-import { labelOverflowWarning } from './label-metrics.ts'
-
-// ---- Number format ----------------------------------------------------------
-//
-// Pie values are positive numbers (Mermaid supports up to two decimal places).
-// Canonical format is `String(n)` for finite n > 0; `parseFloat(String(n)) === n`
-// for every finite n, and the legacy parser reads values with parseFloat.
-
-function formatNumber(n: number): string {
-  return String(n)
-}
-
-function isPositiveFinite(n: unknown): n is number {
-  return typeof n === 'number' && Number.isFinite(n) && n > 0
-}
-
-// ---- Parser -----------------------------------------------------------------
-
-/** Entry line: a quoted label, a colon, and a value (shape mirrors legacy). */
-const ENTRY_RE = /^"((?:[^"\\]|\\.)*)"\s*:\s*(.+)$/
-/** Mermaid pie values: positive numbers, up to two decimal places. */
-const NUMBER_RE = /^\+?(?:\d+(?:\.\d+)?|\.\d+)$/
-
-function decodeEscapes(raw: string): string {
-  return raw.replace(/\\(["\\])/g, '$1')
-}
-
-/** Re-encode a label for emission inside `"..."` (inverse of decodeEscapes). */
-function encodeLabel(label: string): string {
-  return label.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
-}
-
-/**
- * Parse pie body lines (header excluded). The header tail (showData / inline
- * title) is parsed separately by the family hook and passed in. Returns a
- * structured body only if EVERY non-blank, non-comment line is a modeled
- * title / showData / entry directive with a positive numeric value and a
- * quoted label that round-trips. Otherwise returns null (opaque fallback).
- *
- * A structured body must contain at least one slice (the legacy renderer needs
- * data to render).
- */
-export function parsePieBody(lines: string[], header: { showData: boolean; title?: string }): PieBody | null {
-  const body: PieBody = { kind: 'pie', showData: header.showData, slices: [] }
-  if (header.title !== undefined) body.title = header.title
-  let sIdx = 0
-
-  for (const raw of lines) {
-    const line = raw.trim()
-    if (!line) continue
-    if (line.startsWith('%%')) continue
-
-    if (/^showData\s*$/i.test(line)) {
-      body.showData = true
-      continue
-    }
-
-    const titleMatch = line.match(/^title\s+(.+)$/i)
-    if (titleMatch) {
-      const title = titleMatch[1]!.trim()
-      if (!title) return null
-      body.title = title
-      continue
-    }
-
-    const entryMatch = line.match(ENTRY_RE)
-    if (entryMatch) {
-      const label = decodeEscapes(entryMatch[1]!)
-      const rawValue = entryMatch[2]!.trim()
-      if (!NUMBER_RE.test(rawValue)) return null
-      const value = Number.parseFloat(rawValue)
-      if (!isPositiveFinite(value)) return null
-      // A label that wouldn't round-trip (newlines, etc.) falls back to opaque.
-      if (label.includes('\n')) return null
-      body.slices.push({ id: `slice-${sIdx++}`, label, value })
-      continue
-    }
-
-    // Unmodeled line (accTitle/accDescr/malformed entry/anything else) → opaque.
-    return null
-  }
-
-  if (body.slices.length === 0) return null
-
-  return body
-}
-
-// ---- Serializer -------------------------------------------------------------
-
-export function renderPie(body: PieBody): string {
-  const header = body.showData ? 'pie showData' : 'pie'
-  const lines: string[] = [header]
-  if (body.title !== undefined) lines.push(`  title ${body.title}`)
-  for (const s of body.slices) {
-    lines.push(`  "${encodeLabel(s.label)}" : ${formatNumber(s.value)}`)
-  }
-  return lines.join('\n') + '\n'
-}
-
-// ---- Mutator ----------------------------------------------------------------
-
-function clonePie(b: PieBody): PieBody {
-  return {
-    kind: 'pie',
-    title: b.title,
-    showData: b.showData,
-    slices: b.slices.map(s => ({ id: s.id, label: s.label, value: s.value })),
-  }
-}
-
-function makeSliceIdAllocator(body: PieBody): () => string {
-  const seen = new Set(body.slices.map(s => s.id))
-  return () => {
-    let n = 0
-    while (seen.has(`slice-${n}`)) n++
-    const id = `slice-${n}`
-    seen.add(id)
-    return id
-  }
-}
-
-function validLabel(value: unknown, field: string): Result<string, MutationError> {
-  if (typeof value !== 'string') return err({ code: 'INVALID_OP', message: `Pie ${field} must be a string` })
-  const trimmed = value.trim()
-  if (!trimmed || trimmed.includes('\n')) {
-    return err({ code: 'INVALID_OP', message: `Pie ${field} must be non-empty single-line text` })
-  }
-  return ok(trimmed)
-}
-
-function validValue(value: unknown): Result<number, MutationError> {
-  if (!isPositiveFinite(value)) {
-    return err({ code: 'INVALID_OP', message: `Pie slice value must be a positive finite number, got ${JSON.stringify(value)}` })
-  }
-  return ok(value)
-}
-
-function findSlice(body: PieBody, label: string): number {
-  return body.slices.findIndex(s => s.label === label)
-}
-
-export function mutatePie(body: PieBody, op: PieMutationOp): Result<PieBody, MutationError> {
-  const next = clonePie(body)
-  const nextId = makeSliceIdAllocator(next)
-
-  switch (op.kind) {
-    case 'set_title': {
-      if (op.title === null) { delete next.title; break }
-      const t = validLabel(op.title, 'title')
-      if (!t.ok) return t
-      next.title = t.value
-      break
-    }
-    case 'set_show_data': {
-      if (typeof op.showData !== 'boolean') {
-        return err({ code: 'INVALID_OP', message: 'Pie set_show_data requires a boolean showData' })
-      }
-      next.showData = op.showData
-      break
-    }
-    case 'add_slice': {
-      const label = validLabel(op.label, 'slice label')
-      if (!label.ok) return label
-      if (findSlice(next, label.value) >= 0) {
-        return err({ code: 'INVALID_OP', message: `Pie slice "${label.value}" already exists` })
-      }
-      const value = validValue(op.value)
-      if (!value.ok) return value
-      next.slices.push({ id: nextId(), label: label.value, value: value.value })
-      break
-    }
-    case 'remove_slice': {
-      const label = validLabel(op.label, 'slice label')
-      if (!label.ok) return label
-      const idx = findSlice(next, label.value)
-      if (idx < 0) return err({ code: 'SLICE_NOT_FOUND', message: `Pie slice "${label.value}" not found` })
-      next.slices.splice(idx, 1)
-      break
-    }
-    case 'rename_slice': {
-      const from = validLabel(op.from, 'slice label')
-      if (!from.ok) return from
-      const to = validLabel(op.to, 'slice label')
-      if (!to.ok) return to
-      const idx = findSlice(next, from.value)
-      if (idx < 0) return err({ code: 'SLICE_NOT_FOUND', message: `Pie slice "${from.value}" not found` })
-      if (from.value !== to.value && findSlice(next, to.value) >= 0) {
-        return err({ code: 'INVALID_OP', message: `Pie slice "${to.value}" already exists` })
-      }
-      next.slices[idx]!.label = to.value
-      break
-    }
-    case 'set_slice_value': {
-      const label = validLabel(op.label, 'slice label')
-      if (!label.ok) return label
-      const idx = findSlice(next, label.value)
-      if (idx < 0) return err({ code: 'SLICE_NOT_FOUND', message: `Pie slice "${label.value}" not found` })
-      const value = validValue(op.value)
-      if (!value.ok) return value
-      next.slices[idx]!.value = value.value
-      break
-    }
-    case 'reorder_slice': {
-      const { from, to } = op
-      if (!Number.isInteger(from) || !Number.isInteger(to) || !next.slices[from] || to < 0 || to >= next.slices.length) {
-        return err({ code: 'SLICE_NOT_FOUND', message: `reorder_slice indices out of range (from=${from}, to=${to})` })
-      }
-      const [moved] = next.slices.splice(from, 1)
-      next.slices.splice(to, 0, moved!)
-      break
-    }
-    default: {
-      const _x: never = op
-      return err({ code: 'INVALID_OP', message: unknownOpMessage('pie', _x) })
-    }
-  }
-
-  // Preserve the structured floor: a pie must keep at least one slice so it
-  // always renders.
-  if (next.slices.length === 0) {
-    return err({ code: 'INVALID_OP', message: 'Pie must keep at least one slice' })
-  }
-
-  return ok(next)
-}
-
-// ---- Verifier (FamilyPlugin.verify hook) ------------------------------------
-
-export function verifyPie(body: PieBody, opts: VerifyOptions): LayoutWarning[] {
-  const cap = opts.labelCharCap ?? DEFAULT_LABEL_CHAR_CAP
-  const warnings: LayoutWarning[] = []
-  const overflow = (target: string, text: string) => {
-    const w = labelOverflowWarning(target, text, cap)
-    if (w) warnings.push(w)
-  }
-  if (body.slices.length === 0) warnings.push({ code: 'EMPTY_DIAGRAM' })
-  if (body.title !== undefined) overflow('title', body.title)
-  for (const s of body.slices) overflow(s.id, s.label)
-  return warnings
-}

package/src/agent/png.ts

@@ -1,171 +0,0 @@
-// ============================================================================
-// renderMermaidPNG — rasterize a Mermaid diagram to a PNG byte array.
-//
-// Uses @resvg/resvg-js (napi-rs build, pinned 2.6.2) for deterministic
-// rasterization. Critical choices from the Loop 8 5-critic plan-hardening:
-//
-// - napi-rs build (NOT WASM) — same prebuilt .node binary under Bun and
-//   Node via N-API compat, eliminates WASM-init differences.
-// - loadSystemFonts: false + bundled DejaVu Sans fonts in assets/fonts/ —
-//   without this, fontconfig differences between OSes and CI images would
-//   collapse cross-runtime parity.
-// - SVG input rendered with embedFontImport: false so resvg doesn't fetch
-//   from Google Fonts at rasterization time (offline / CSP / sandbox safe).
-// - PNG bytes returned as Uint8Array (runtime-neutral, Code Mode friendly).
-//
-// What's tested: in-process determinism (5x same-input SHA-256 stable),
-// cross-runtime determinism (bun ≡ node on same-machine x86_64/ARM64 when
-// Node + built dist are present), basic PNG validity.
-// What's NOT tested: direct x86_64-vs-ARM64 byte equality, resvg version drift
-// across npm install runs. See docs/quality.md "PNG determinism".
-// ============================================================================
-
-import { fileURLToPath } from 'node:url'
-import { join, dirname } from 'node:path'
-import { existsSync } from 'node:fs'
-import { Resvg } from '@resvg/resvg-js'
-import type { ValidDiagram } from './types.ts'
-import type { StyleInput } from '../scene/style-registry.ts'
-import { serializeMermaid } from './serialize.ts'
-import { renderMermaidSVG } from '../index.ts'
-import { inlineFontVarForRaster } from '../theme.ts'
-import { findUncoveredScripts } from './font-coverage.ts'
-
-/**
- * Loud-tofu guard: emitted when rendered text contains characters no loaded
- * font covers (they would silently rasterize as empty boxes). Delivered to
- * `PngOptions.onWarning` when provided, otherwise written to stderr — never
- * silent either way.
- */
-export interface PngFontWarning {
-  code: 'PNG_FONT_COVERAGE'
-  /** Coarse script bucket of the uncovered characters ('CJK', 'emoji', …). */
-  script: string
-  /** The uncovered characters, unique, ascending codepoint order. */
-  chars: string[]
-  /** Human-readable summary naming the script and the escape hatches. */
-  message: string
-}
-
-export interface PngOptions {
-  /** Output scale multiplier (default 2 — retina). */
-  scale?: number
-  /** Background color, any CSS color string (default 'white'). */
-  background?: string
-  /** Constrain output dimensions; otherwise honors scale on the SVG bounds. */
-  fitTo?: { width?: number; height?: number }
-  /** Style name | spec | stack, same as RenderOptions.style. Faces referenced
-   *  by the built-in looks are bundled in assets/fonts/; other families fall
-   *  back to DejaVu Sans unless supplied via fontDirs. */
-  style?: StyleInput | StyleInput[]
-  /** Ink-wobble seed for styled looks, same as RenderOptions.seed. */
-  seed?: number
-  /** Extra font directories searched in addition to the bundled ones —
-   *  the escape hatch for custom styles that reference unbundled families
-   *  and for scripts the bundled fonts don't cover (CJK, emoji). */
-  fontDirs?: string[]
-  /** Also load the OS's installed fonts (default false). Opting in trades
-   *  cross-machine determinism for coverage — useful when the diagram needs
-   *  CJK/emoji glyphs and a system font provides them. Coverage warnings are
-   *  skipped in this mode: the system font set is unknown to the checker. */
-  loadSystemFonts?: boolean
-  /** Receives glyph-coverage warnings instead of the default stderr write.
-   *  Warnings never change the PNG bytes; identical inputs render
-   *  identically whether or not a handler is installed. */
-  onWarning?: (warning: PngFontWarning) => void
-}
-
-/**
- * Resolve the bundled-fonts directory. Walks up from this module path until
- * it finds `assets/fonts/`. Caches the result so it's only resolved once.
- */
-let cachedFontDir: string | null = null
-function resolveFontDir(): string | null {
-  if (cachedFontDir !== null) return cachedFontDir
-  // import.meta.url works under Bun + Node ESM
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const here = typeof (import.meta as any).url === 'string' ? fileURLToPath((import.meta as any).url) : __filename
-  let dir = dirname(here)
-  for (let i = 0; i < 6; i++) {
-    const candidate = join(dir, 'assets', 'fonts')
-    if (existsSync(candidate)) { cachedFontDir = candidate; return candidate }
-    const parent = dirname(dir)
-    if (parent === dir) break
-    dir = parent
-  }
-  // Don't crash if not found — resvg will fall back to its default fonts.
-  // Cross-runtime determinism may weaken in that case; documented gap.
-  cachedFontDir = ''
-  return null
-}
-
-/**
- * Render a Mermaid diagram (source string or ValidDiagram) to a PNG byte array.
- * Deterministic within one runtime; cross-runtime parity is guarded for
- * same-machine Bun ≡ Node on x86_64/ARM64 when Node + built dist are present.
- *
- * Synchronous: resvg's `.render()` is native-sync, and static import keeps
- * the CLI/MCP integration straightforward. Library consumers can wrap in
- * `Promise.resolve()` if they want async semantics.
- */
-export function renderMermaidPNG(input: ValidDiagram | string, opts: PngOptions = {}): Uint8Array {
-  // SVG input: embedFontImport=false so resvg doesn't try to fetch from
-  // Google Fonts during rasterization. CSS-variable fonts (Loop 8 M2) means
-  // the SVG still declares its font-family preference via --font.
-  const source = typeof input === 'string' ? input : serializeMermaid(input)
-  const svg = inlineFontVarForRaster(
-    renderMermaidSVG(source, { embedFontImport: false, style: opts.style, seed: opts.seed }),
-  )
-
-  const scale = opts.scale ?? 2
-  const fontDir = resolveFontDir()
-  const loadSystemFonts = opts.loadSystemFonts ?? false
-  const fontDirs = [...(fontDir ? [fontDir] : []), ...(opts.fontDirs ?? [])]
-
-  // Loud-tofu guard: characters no loaded font covers rasterize as empty
-  // boxes, so surface them BEFORE the bytes ship. Skipped with system fonts
-  // (their coverage is unknown to the cmap checker). Warnings never affect
-  // the rendered bytes.
-  if (!loadSystemFonts) {
-    const emit = opts.onWarning ?? ((w: PngFontWarning) => process.stderr.write(`agentic-mermaid renderMermaidPNG: warning ${w.code}: ${w.message}\n`))
-    for (const { script, chars } of findUncoveredScripts(svg, fontDirs)) {
-      const examples = chars.slice(0, 5).join(' ')
-      emit({
-        code: 'PNG_FONT_COVERAGE',
-        script,
-        chars,
-        message:
-          `no bundled font covers ${chars.length} ${script} character${chars.length === 1 ? '' : 's'} (${examples}); ` +
-          `they will draw as empty tofu boxes. Point fontDirs (CLI: --font-dirs <dir>) at a font that covers them, ` +
-          `or opt in to system fonts with loadSystemFonts: true (CLI: --system-fonts).`,
-      })
-    }
-  }
-
-  const resvgOpts: ConstructorParameters<typeof Resvg>[1] = {
-    background: opts.background ?? 'white',
-    fitTo: opts.fitTo?.width
-      ? { mode: 'width' as const, value: opts.fitTo.width }
-      : opts.fitTo?.height
-        ? { mode: 'height' as const, value: opts.fitTo.height }
-        : { mode: 'zoom' as const, value: scale },
-    font: {
-      loadSystemFonts,
-      // Bundled fonts (Inter + DejaVu Sans + the faces built-in styles
-      // reference) for cross-runtime determinism, plus caller-supplied
-      // directories. Falls back to resvg's built-in fonts if nothing is found.
-      fontDirs,
-      // Inter is the metrics font: src/text-metrics.ts is calibrated for it
-      // and the SVG @import requests it, so rasterizing with anything else
-      // (DejaVu is ~14% wider) pushes long labels outside their measured
-      // boxes. resvg falls back per-glyph across every loaded font, so
-      // DejaVu still covers glyphs Inter lacks (arrows, math, Armenian, …).
-      defaultFontFamily: 'Inter',
-    },
-  }
-
-  const resvg = new Resvg(svg, resvgOpts)
-  const png = resvg.render().asPng()
-  // resvg returns Buffer in Node; ensure we surface Uint8Array consistently.
-  return new Uint8Array(png.buffer, png.byteOffset, png.byteLength)
-}