dsh-model-everything 0.4.1 → 0.5.1

package/src/render/dummy.ts

@@ -0,0 +1,65 @@
+/**
+ * Dummy nodes: the placeholders a long edge stands on.
+ *
+ * An edge from layer 0 to layer 3 has to cross layers 1 and 2. The router can go around whatever is in the way, but a
+ * drawing reads better if the edge owns a lane through those layers: then ordering can keep other edges off it, and
+ * coordinate assignment can give the whole lane one x. A dummy node is that lane: one per layer the edge crosses.
+ *
+ * A lane is one variable, not one variable per layer. The instances keep their own id (`#d<edge>_<layer>`) so the
+ * ordering stage can sort them inside their layer, and they all point at one lane id (`#e<edge>`) so coordinate
+ * assignment cannot give the same edge three different x values.
+ *
+ * Pure: the layers, the chains, and the map between the two.
+ */
+
+import type { LayoutEdge } from './layout.js'
+import type { Layering } from './layer.js'
+
+/** One edge, as the id it passes through in each layer it crosses. */
+export interface Chain {
+  /** The diagram edge's index. */
+  index: number
+  /** The ids from the layout source to the layout target: the endpoints plus one dummy per crossed layer. */
+  path: string[]
+}
+
+export interface Augmented {
+  /** The layers with the dummies inserted; each dummy sits in the layer it crosses. */
+  layers: string[][]
+  chains: Chain[]
+  /** A dummy instance's lane id: the variable coordinate assignment shares between a long edge's dummies. */
+  chainOf: Map<string, string>
+  /** The lane id of every edge that needed dummies. */
+  laneOf: Map<number, string>
+}
+
+export function addDummies(layering: Layering, edges: LayoutEdge[]): Augmented {
+  const layers = layering.layers.map((layer) => [...layer])
+  const chains: Chain[] = []
+  const chainOf = new Map<string, string>()
+  const laneOf = new Map<number, string>()
+  for (const edge of edges) {
+    if (edge.from === edge.to) {
+      chains.push({ index: edge.index, path: [edge.from, edge.to] })
+      continue
+    }
+    const from = layering.layerOf.get(edge.from)
+    const to = layering.layerOf.get(edge.to)
+    if (from === undefined || to === undefined || to <= from) {
+      chains.push({ index: edge.index, path: [edge.from, edge.to] })
+      continue
+    }
+    const path = [edge.from]
+    for (let cursor = from + 1; cursor < to; cursor += 1) {
+      const instance = '#d' + String(edge.index) + '_' + String(cursor)
+      const lane = '#e' + String(edge.index)
+      chainOf.set(instance, lane)
+      laneOf.set(edge.index, lane)
+      layers[cursor].push(instance)
+      path.push(instance)
+    }
+    path.push(edge.to)
+    chains.push({ index: edge.index, path })
+  }
+  return { layers, chains, chainOf, laneOf }
+}

package/src/render/from-mermaid.ts

@@ -0,0 +1,261 @@
+/**
+ * Mermaid text to a diagram, for the subset this renderer can actually draw.
+ *
+ * The subset is chosen by what a reader of an architecture document writes: a flowchart of boxes and
+ * arrows, a state diagram with a start marker, and the group syntax that turns a flat graph into a layered
+ * one. Everything outside it is refused **with its line number** rather than half-drawn: a picture that
+ * silently drops a lifeline or an interaction is worse than no picture, because it looks complete.
+ *
+ * Supported:
+ *
+ * - `graph TD|TB|LR` and `flowchart TD|TB|LR`, with direction carried into the layout as a hint;
+ * - node declarations `A[text]`, `A(text)`, `A{text}`, `A((text))`, and a bare `A`;
+ * - edges `-->`, `---`, `-.->`, `==>`, with a label as `-->|text|` or `-- text -->`;
+ * - `stateDiagram` / `stateDiagram-v2`: `[*] --> A`, `A --> B: event`, `state "text" as id`;
+ * - `subgraph name ... end`, which becomes a group;
+ * - `%%` comments and blank lines.
+ *
+ * Refused, by name: `sequenceDiagram`, `classDiagram`, `erDiagram`, `gantt`, `pie`, `journey`, `mindmap`,
+ * `timeline`, `quadrantChart`, `gitGraph`, `C4Context`, and `click`/`style`/`classDef` directives.
+ */
+
+import { emptyDiagram, type Diagram, type DiagramEdge, type DiagramGroup, type DiagramNode } from './model.js'
+
+export interface Parsed {
+  diagram: Diagram
+  /** Lines the parser refused to interpret, with the reason. Empty when the whole source was understood. */
+  refused: string[]
+}
+
+const CURVED_EDGE = /^(.+?)\s*(-->|---|-\.->|==>)\s*(?:\|([^|]*)\|\s*)?(.+)$/
+const LABELLED_EDGE = /^(.+?)\s*--\s*([^->]+?)\s*-->\s*(.+)$/
+const NODE = /^([A-Za-z_][\w-]*)\s*(?:\[\((.*)\)\]|\[\[(.*)\]\]|\[(.*)\]|\((.*)\)|\{(.*)\}|<<(.*)>>)?$/
+const TRANSITION = /^([A-Za-z_][\w-]*|\[\*\])\s*-->\s*([A-Za-z_][\w-]*|\[\*\])\s*(?::\s*(.*))?$/
+const STATE_ALIAS = /^state\s+["'](.+?)["']\s+as\s+([A-Za-z_][\w-]*)$/
+const DIRECTIVE = /^(click|style|classDef|class|linkStyle|accTitle|accDescr)\b/
+const UNSUPPORTED = new Set([
+  'sequencediagram',
+  'classdiagram',
+  'erdiagram',
+  'gantt',
+  'pie',
+  'journey',
+  'mindmap',
+  'timeline',
+  'quadrantchart',
+  'gitgraph',
+  'c4context',
+  'requirementdiagram',
+  'sankey-beta',
+])
+
+interface Builder {
+  nodes: Map<string, DiagramNode>
+  edges: DiagramEdge[]
+  groups: DiagramGroup[]
+  /** The boundaries currently open, outermost first. */
+  open: DiagramGroup[]
+}
+
+function ensure(builder: Builder, id: string, label?: string, shape?: DiagramNode['shape']): void {
+  const existing = builder.nodes.get(id)
+  if (existing === undefined) {
+    builder.nodes.set(id, {
+      id,
+      role: 'normal',
+      ...(label === undefined ? {} : { label }),
+      ...(shape === undefined ? {} : { shape }),
+    })
+    // Membership is decided where the node is first written: the innermost open boundary. Naming it again
+    // later from an outer boundary does not move it - the outer boundary holds it through `parent`.
+    const innermost = builder.open[builder.open.length - 1]
+    if (innermost !== undefined && !innermost.members.includes(id)) innermost.members.push(id)
+    return
+  }
+  if (label !== undefined && (existing.label === undefined || existing.label === '')) existing.label = label
+}
+
+function nodeFrom(token: string): { id: string; label?: string; shape?: DiagramNode['shape'] } | undefined {
+  const match = NODE.exec(token.trim())
+  if (match === null) return undefined
+  const id = match[1]
+  const label = [match[2], match[3], match[4], match[5], match[6], match[7]].find((value) => value !== undefined && value.trim() !== '')
+  // Group 2 `[(x)]` is a datastore, 3 `[[x]]` a subroutine, 4 `[x]` a rectangle, 5 `(x)` a rounded box, 6 `{x}` a
+  // decision, 7 `<<x>>` a hexagon. Mermaid's own mapping; a shape the notation did not state stays undefined.
+  const shape: DiagramNode['shape'] | undefined =
+    match[2] !== undefined
+      ? 'cylinder'
+      : match[3] !== undefined
+        ? 'subroutine'
+        : match[4] !== undefined
+          ? 'rect'
+          : match[5] !== undefined
+            ? 'stadium'
+            : match[6] !== undefined
+              ? 'diamond'
+              : match[7] !== undefined
+                ? 'hexagon'
+                : undefined
+  return {
+    id,
+    ...(label === undefined ? {} : { label: label.trim().replace(/^["']|["']$/g, '') }),
+    ...(shape === undefined ? {} : { shape }),
+  }
+}
+
+export function fromMermaid(source: string, title = 'mermaid'): Parsed {
+  const lines = source.split(/\r?\n/)
+  const refused: string[] = []
+  const builder: Builder = { nodes: new Map(), edges: [], groups: [], open: [] }
+  let mode: 'none' | 'graph' | 'state' = 'none'
+  let startId: string | undefined
+  let endCount = 0
+
+  const push = (edge: DiagramEdge): void => {
+    builder.edges.push(edge)
+  }
+
+  lines.forEach((raw, index) => {
+    const line = raw.replace(/%%(.*)$/, '').trim()
+    if (line === '') return
+    const where = 'line ' + String(index + 1) + ': '
+    const lower = line.toLowerCase()
+    const keyword = lower.split(/[\s{}]/)[0]
+
+    if (UNSUPPORTED.has(keyword)) {
+      refused.push(where + '`' + keyword + '` is not a diagram this renderer draws')
+      return
+    }
+    if (DIRECTIVE.test(line)) {
+      refused.push(where + '`' + line.split(/\s/)[0] + '` is a directive this renderer ignores')
+      return
+    }
+    if (/^(graph|flowchart)\b/.test(lower)) {
+      mode = 'graph'
+      return
+    }
+    if (/^statediagram(-v2)?\b/.test(lower)) {
+      mode = 'state'
+      return
+    }
+    if (/^subgraph\b/.test(lower)) {
+      const label = line.replace(/^subgraph\b/i, '').trim().replace(/^["']|["']$/g, '')
+      const id = 'subgraph-' + String(++endCount)
+      builder.open.push({ id, label: label === '' ? id : label, members: [] })
+      return
+    }
+    if (lower === 'end') {
+      const closed = builder.open.pop()
+      if (closed !== undefined) {
+        const container = builder.open[builder.open.length - 1]
+        if (container !== undefined) closed.parent = container.id
+        builder.groups.push(closed)
+      }
+      return
+    }
+
+    if (mode === 'state') {
+      const alias = STATE_ALIAS.exec(line)
+      if (alias !== null) {
+        ensure(builder, alias[2], alias[1])
+        return
+      }
+      const transition = TRANSITION.exec(line)
+      if (transition === null) {
+        // A bare `state X` declaration, or a state named on its own line.
+        const bare = /^state\s+([A-Za-z_][\w-]*)$/.exec(line)
+        if (bare !== null) {
+          ensure(builder, bare[1])
+          return
+        }
+        if (/^[A-Za-z_][\w-]*$/.test(line)) {
+          ensure(builder, line)
+          return
+        }
+        refused.push(where + '`' + line + '` is not a state transition this renderer draws')
+        return
+      }
+      const from = transition[1]
+      const to = transition[2]
+      const label = (transition[3] ?? '').trim()
+      if (from === '[*]') {
+        // A start marker names the state it enters, not a box of its own.
+        ensure(builder, to)
+        if (startId === undefined) startId = to
+        return
+      }
+      if (to === '[*]') {
+        ensure(builder, from)
+        push({ from, to: from, label: label === '' ? 'end' : label, dashed: true })
+        return
+      }
+      ensure(builder, from)
+      ensure(builder, to)
+      push({ from, to, label })
+      return
+    }
+
+    const labelled = LABELLED_EDGE.exec(line)
+    if (labelled !== null) {
+      const left = nodeFrom(labelled[1])
+      const right = nodeFrom(labelled[3])
+      if (left === undefined || right === undefined) {
+        refused.push(where + '`' + line + '` does not name two nodes')
+        return
+      }
+      ensure(builder, left.id, left.label, left.shape)
+      ensure(builder, right.id, right.label, right.shape)
+      push({ from: left.id, to: right.id, label: labelled[2].trim() })
+      return
+    }
+
+    const edge = CURVED_EDGE.exec(line)
+    if (edge !== null) {
+      const left = nodeFrom(edge[1])
+      const right = nodeFrom(edge[4])
+      if (left === undefined || right === undefined) {
+        refused.push(where + '`' + line + '` does not name two nodes')
+        return
+      }
+      ensure(builder, left.id, left.label, left.shape)
+      ensure(builder, right.id, right.label, right.shape)
+      push({
+        from: left.id,
+        to: right.id,
+        label: (edge[3] ?? '').trim(),
+        ...(edge[2] === '-.->' || edge[2] === '==>' ? { dashed: true } : {}),
+      })
+      return
+    }
+
+    const single = nodeFrom(line)
+    if (single !== undefined) {
+      ensure(builder, single.id, single.label, single.shape)
+      return
+    }
+
+    refused.push(where + '`' + line + '` is not something this renderer draws')
+  })
+
+  if (mode === 'none') {
+    return { diagram: emptyDiagram(title, 'no mermaid diagram found'), refused }
+  }
+
+  if (builder.nodes.size === 0) {
+    return { diagram: emptyDiagram(title, 'no nodes found'), refused }
+  }
+
+  const diagram: Diagram = {
+    kind: mode === 'state' ? 'machine' : 'graph',
+    title,
+    ...(startId === undefined ? {} : { init: startId }),
+    nodes: [...builder.nodes.values()],
+    edges: builder.edges,
+    ...(builder.groups.length === 0 ? {} : { groups: builder.groups }),
+    caption:
+      mode + ', ' + String(builder.nodes.size) + ' box' + (builder.nodes.size === 1 ? '' : 'es') + ', ' +
+      String(builder.edges.length) + ' arrow' + (builder.edges.length === 1 ? '' : 's') +
+      (refused.length === 0 ? '' : ', ' + String(refused.length) + ' line(s) refused'),
+  }
+  return { diagram, refused }
+}