dsh-model-everything 0.4.1 → 0.5.1

package/src/render/text.ts

@@ -0,0 +1,86 @@
+/**
+ * Text as the layout sees it: measured, broken into lines, and turned into a box.
+ *
+ * Mermaid and Graphviz both measure a label in the platform's own text engine and then lay out around that
+ * measurement - a node's size is its text plus padding, and a label too long for its maximum width is wrapped
+ * before anything is placed. There is no DOM here, so the measurement is an estimate over a per-character width
+ * table; what matters is that the *order* is the same: text first, geometry second. A renderer that fixes the box
+ * and pours text into it cannot help overflowing.
+ *
+ * Explicit breaks (`<br>`, `<br/>`, `<br />`, a real newline) are honoured as written, because a source that put
+ * one there wanted that line to end.
+ */
+
+/** Average advance per character, in the drawing's units, at the 11px font the writer emits. */
+const CHAR_WIDTH = 6.6
+
+/** A line longer than this wraps on a space, or breaks in the middle when it has none. */
+export const MAX_LINE_CHARS = 30
+
+/** Height of one line of box text, and the breathing room around the block. */
+export const LINE_HEIGHT = 15
+export const TEXT_PADDING = 12
+
+/** The smallest and largest box a label may produce. */
+export const MIN_NODE_WIDTH = 88
+export const MAX_NODE_WIDTH = 260
+
+/** `<br>`, `<br/>`, `<br />` and a real newline all end a line. */
+const BREAK = /<br\s*\/?>|\r?\n/gi
+
+/** The lines a label asks for, before wrapping: an explicit break is a line end, not a space. */
+export function explicitLines(label: string): string[] {
+  return label.split(BREAK).map((line) => line.trim())
+}
+
+/**
+ * Wrap one line to the maximum width.
+ *
+ * A word longer than the limit is broken rather than allowed to overflow: a single token with no spaces is the
+ * common case in identifiers, and letting it run off the box is the defect this function exists to prevent.
+ */
+export function wrapLine(line: string, limit: number = MAX_LINE_CHARS): string[] {
+  if (line === '') return ['']
+  const out: string[] = []
+  let current = ''
+  for (const word of line.split(/\s+/).filter((part) => part !== '')) {
+    const candidate = current === '' ? word : current + ' ' + word
+    if (candidate.length <= limit) {
+      current = candidate
+      continue
+    }
+    if (current !== '') out.push(current)
+    if (word.length <= limit) {
+      current = word
+      continue
+    }
+    let rest = word
+    while (rest.length > limit) {
+      out.push(rest.slice(0, limit))
+      rest = rest.slice(limit)
+    }
+    current = rest
+  }
+  if (current !== '') out.push(current)
+  return out.length === 0 ? [''] : out
+}
+
+export interface Measured {
+  lines: string[]
+  width: number
+  height: number
+}
+
+/** The text block a label produces: its lines, and the box it needs. */
+export function measure(label: string): Measured {
+  const lines = explicitLines(label).flatMap((line) => wrapLine(line))
+  const longest = lines.reduce((max, line) => Math.max(max, line.length), 0)
+  const width = Math.min(MAX_NODE_WIDTH, Math.max(MIN_NODE_WIDTH, longest * CHAR_WIDTH + TEXT_PADDING * 2))
+  const height = lines.length * LINE_HEIGHT + TEXT_PADDING
+  return { lines, width, height }
+}
+
+/** Rough width of a single-line piece of text, for placing an edge label without a box. */
+export function textWidth(text: string): number {
+  return text.length * CHAR_WIDTH
+}

package/src/render/viewmodel.ts

@@ -0,0 +1,136 @@
+/**
+ * What a tool card shows, reduced to a drawing.
+ *
+ * The input is what the host hands a settled tool view: a phase and a block whose shape differs per phase.
+ * A settled call carries the paired call's arguments as a **lazy view** (`PartialArguments`) and the result
+ * as content blocks, so nothing here reads `block.args.model`: the view is asked, and the report text is
+ * parsed for the two facts a drawing needs. Every reader is total - an absent field removes a shape rather
+ * than throwing, because the same view renders during streaming.
+ *
+ * Pure. Everything decided here is a fact a test can assert: which nodes exist, which edges, why they are
+ * coloured the way they are.
+ */
+
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined
+
+const array = (value: unknown): unknown[] => (Array.isArray(value) ? value : [])
+
+const text = (value: unknown): string | undefined => (typeof value === 'string' && value !== '' ? value : undefined)
+
+/** The report text a settled call carries, joined: a card reads words, not blocks. */
+function reportText(content: unknown): string {
+  const parts: string[] = []
+  for (const entry of array(content)) {
+    const block = record(entry)
+    const body = text(block?.text)
+    if (body !== undefined) parts.push(body)
+  }
+  return parts.join(String.fromCharCode(10))
+}
+
+/** Two facts out of this plugin's own report format: the verdict, and the first error it named. */
+function readReport(content: unknown): { verdict?: string; code?: string; message?: string } {
+  const body = reportText(content)
+  if (body === '') return {}
+  const verdict = /verdict=(\w+)/.exec(body)?.[1]
+  const named = /\[error\/([A-Z0-9_]+)\]\s*(.*)/.exec(body)
+  if (named !== null) return { verdict, code: named[1], message: named[2] }
+  const first = /first error:\s*([A-Z0-9_]+)/.exec(body)
+  return first === null ? { verdict } : { verdict, code: first[1] }
+}
+
+/**
+ * The `model` argument out of the host's lazy arguments view.
+ *
+ * A settled call exposes `value(key)`; a plain object (a test, or an older shape) is read directly. The
+ * view answers `undefined` until the field closes, which is exactly when a drawing should be attempted.
+ */
+function readModel(args: unknown): Record<string, unknown> | undefined {
+  const view = record(args)
+  if (view === undefined) return undefined
+  const read = view.value
+  if (typeof read === 'function') return record((read as (key: string) => unknown)('model'))
+  return record(view.model)
+}
+
+/** The states of a model: a machine, or nothing when the call carried none. */
+function machineOf(model: Record<string, unknown> | undefined): { nodes: DiagramNode[]; edges: DiagramEdge[]; init?: string } | undefined {
+  if (model === undefined) return undefined
+  const states = array(model.states).map(record).filter((entry): entry is Record<string, unknown> => entry !== undefined && typeof entry.id === 'string')
+  if (states.length === 0) return undefined
+  const edges = array(model.transitions)
+    .map(record)
+    .filter((entry): entry is Record<string, unknown> => entry !== undefined && typeof entry.from === 'string' && typeof entry.to === 'string')
+    .map((entry) => ({ from: String(entry.from), to: String(entry.to), label: text(entry.event) ?? '' }))
+  return {
+    nodes: states.map((state) => ({ id: String(state.id), role: 'normal' as const })),
+    edges,
+    ...(typeof model.init === 'string' ? { init: model.init } : {}),
+  }
+}
+
+/** The caption: the verdict, then the first error's code and message when the report named one. */
+function captionOf(report: { verdict?: string; code?: string; message?: string }): string {
+  const verdict = report.verdict ?? 'no report yet'
+  if (report.code === undefined) return verdict
+  const message = report.message ?? ''
+  return verdict + ' — ' + report.code + (message === '' ? '' : ': ' + message)
+}
+
+/**
+ * Which nodes the report blames.
+ *
+ * A finding names a state inside its message as `"x"`; matching that is a heuristic, so it only ever *adds*
+ * emphasis and never decides the verdict.
+ */
+function blame(nodes: DiagramNode[], report: { message?: string }): DiagramNode[] {
+  if (report.message === undefined) return nodes
+  const message = report.message
+  // Whole words only: a report does not quote the state, and a state called `do` must not match `done`.
+  const named = nodes
+    .filter((node) => {
+      const escaped = node.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      return new RegExp('(?<![A-Za-z0-9_])' + escaped + '(?![A-Za-z0-9_])').test(message)
+    })
+    .map((node) => node.id)
+  if (named.length === 0) return nodes
+  return nodes.map((node) => (named.includes(node.id) ? { ...node, role: 'error' as const } : node))
+}
+
+import type { Diagram, DiagramEdge, DiagramNode } from './model.js'
+
+export interface ViewInput {
+  phase?: unknown
+  toolName?: unknown
+  /** The whole block the host hands a view; its shape depends on the phase. */
+  block?: unknown
+}
+
+export function viewModel(input: ViewInput): Diagram {
+  const block = record(input.block)
+  const title = text(block?.name) ?? text(input.toolName) ?? 'tool'
+  const report = readReport(block?.content)
+  // A shape that still carries a parsed report object is read from there; it is what older callers pass.
+  const parsed = record(block?.result)
+  const findings = array(parsed?.findings).map(record)
+  const firstError = findings.find((finding) => finding?.severity === 'error')
+  const merged = {
+    verdict: text(parsed?.verdict) ?? report.verdict,
+    ...(report.code === undefined && typeof firstError?.code === 'string' ? { code: firstError.code } : { code: report.code }),
+    ...(report.message === undefined && typeof firstError?.message === 'string' ? { message: firstError.message } : { message: report.message }),
+  }
+  const caption = captionOf(merged)
+  const machine = machineOf(readModel(block?.args))
+  if (machine === undefined) {
+    return { kind: 'none', title, nodes: [], edges: [], caption }
+  }
+  return {
+    kind: 'machine',
+    title,
+    ...(machine.init === undefined ? {} : { init: machine.init }),
+    nodes: blame(machine.nodes, merged),
+    edges: machine.edges,
+    caption,
+  }
+}

package/src/render/wrap.ts

@@ -0,0 +1,103 @@
+/**
+ * Wrapping: turning one endless column into a page.
+ *
+ * A chain of twelve boxes has twelve layers, and layering alone draws it as a single column taller than anything a
+ * reader can take in - a strip, not a drawing. Graphviz and ELK both answer this with a wrapping pass: cut the layer
+ * sequence into bands and stand the bands side by side, so reading order becomes "down the page, then the next
+ * column", the way text wraps.
+ *
+ * The cut is chosen, not guessed: each candidate number of bands is scored by how close the packed page gets to the
+ * aspect ratio a page and a landscape screen share, and the best one wins. A drawing that is already close to that
+ * shape is left alone - wrapping exists for the strip, not for every tall drawing.
+ *
+ * Pure: layer sizes in, band ranges and offsets out. The caller applies them.
+ */
+
+/** The aspect ratio a page and a landscape screen share. */
+const PAGE_ASPECT = 1.6
+
+/** A drawing shorter than this many layers is read better stacked, whatever its proportions. */
+const MIN_LAYERS_TO_WRAP = 4
+
+/** A drawing that is not this tall relative to its width is not a strip. */
+const STRIP_RATIO = 2
+
+export interface BandRange {
+  /** The first and last layer the band holds, inclusive. */
+  first: number
+  last: number
+  /** How far right the band stands, relative to the first one. */
+  offsetX: number
+}
+
+export interface BandPlan {
+  bands: BandRange[]
+  width: number
+  height: number
+}
+
+/** The height of a run of layers with the gap between them. */
+function runHeight(layerHeight: number[], first: number, last: number, gap: number): number {
+  let total = 0
+  for (let index = first; index <= last; index += 1) {
+    total += layerHeight[index]
+    if (index < last) total += gap
+  }
+  return total
+}
+
+/** The width of a run of layers: the widest layer sets it. */
+function runWidth(layerWidth: number[], first: number, last: number): number {
+  let widest = 0
+  for (let index = first; index <= last; index += 1) widest = Math.max(widest, layerWidth[index])
+  return widest
+}
+
+/** How far the packed page is from the target shape, in log space so half and double count the same. */
+function shapeError(width: number, height: number, aspect: number): number {
+  if (width <= 0 || height <= 0) return Infinity
+  const ratio = Math.max(width, height) / Math.min(width, height)
+  return Math.abs(Math.log(ratio / aspect))
+}
+
+export function planBands(layerWidth: number[], layerHeight: number[], gap: number, aspect: number = PAGE_ASPECT): BandPlan {
+  const count = layerWidth.length
+  if (count === 0) return { bands: [], width: 0, height: 0 }
+  const single: BandPlan = {
+    bands: [{ first: 0, last: count - 1, offsetX: 0 }],
+    width: runWidth(layerWidth, 0, count - 1),
+    height: runHeight(layerHeight, 0, count - 1, gap),
+  }
+  if (count < MIN_LAYERS_TO_WRAP || single.height <= single.width * STRIP_RATIO) return single
+
+  const columnGap = gap * 2
+  let best = single
+  let bestError = shapeError(single.width, single.height, aspect)
+  for (let bands = 2; bands < count; bands += 1) {
+    const base = Math.floor(count / bands)
+    const extra = count % bands
+    const ranges: Array<{ first: number; last: number }> = []
+    let cursor = 0
+    for (let band = 0; band < bands; band += 1) {
+      const size = base + (band < extra ? 1 : 0)
+      ranges.push({ first: cursor, last: cursor + size - 1 })
+      cursor += size
+    }
+    let width = columnGap * (bands - 1)
+    let height = 0
+    for (const range of ranges) {
+      width += runWidth(layerWidth, range.first, range.last)
+      height = Math.max(height, runHeight(layerHeight, range.first, range.last, gap))
+    }
+    if (shapeError(width, height, aspect) >= bestError) continue
+    const planned: BandRange[] = []
+    let offsetX = 0
+    for (const range of ranges) {
+      planned.push({ first: range.first, last: range.last, offsetX })
+      offsetX += runWidth(layerWidth, range.first, range.last) + columnGap
+    }
+    best = { bands: planned, width, height }
+    bestError = shapeError(width, height, aspect)
+  }
+  return best
+}

package/src/render/write.ts

@@ -0,0 +1,17 @@
+/**
+ * Writing a drawing to disk: the CLI's job, kept out of the renderer.
+ *
+ * `render/index.ts` is bundled into the page as well as run in Node, so it may not import a filesystem;
+ * everything that touches one lives here, where only the host reaches it.
+ */
+
+import { writeFileSync } from 'node:fs'
+import { render, type RenderInput, type Rendered } from './index.js'
+import type { Palette, PaletteOptions } from './palette.js'
+
+/** Write the drawing where a document can link to it. Returns the path, the byte count and the render. */
+export function writeSvg(input: RenderInput, path: string, overrides: Partial<Palette> = {}, options: PaletteOptions = {}): { path: string; bytes: number; rendered: Rendered } {
+  const rendered = render(input, overrides, options)
+  writeFileSync(path, rendered.markup, 'utf8')
+  return { path, bytes: rendered.markup.length, rendered }
+}