dsh-model-everything 0.4.1 → 0.5.0

package/src/render/collapse.ts

@@ -0,0 +1,155 @@
+/**
+ * Collapsing a group: the drawing with one boundary folded into a single box.
+ *
+ * A fold is a transform on the model, not a mode of the painter. That keeps the painter's rules unchanged -
+ * it still draws boxes and edges it is given - and it makes the behaviour testable without a browser: feed a
+ * diagram in, assert what came out.
+ *
+ * Folding is what makes a hierarchy usable: a reader who has understood a package wants it out of the way, and
+ * an architecture diagram that cannot be folded is read at one zoom level forever.
+ */
+
+import type { Diagram, DiagramEdge, DiagramGroup, DiagramNode } from './model.js'
+
+/** How many nodes a group holds, counting the whole subtree - what the folded box offers to unfold. */
+function subtreeSize(diagram: Diagram, groupId: string, seen: Set<string>): number {
+  if (seen.has(groupId)) return 0
+  seen.add(groupId)
+  const groups = diagram.groups ?? []
+  const group = groups.find((entry) => entry.id === groupId)
+  if (group === undefined) return 0
+  const children = groups.filter((entry) => entry.parent === groupId)
+  return group.members.length + children.reduce((total, child) => total + subtreeSize(diagram, child.id, seen), 0)
+}
+
+/** The group that directly holds a node, when one does. */
+function ownerOf(diagram: Diagram, nodeId: string): string | undefined {
+  return (diagram.groups ?? []).find((group) => group.members.includes(nodeId))?.id
+}
+
+/**
+ * Fold the named groups.
+ *
+ * A folded group becomes a node carrying its name and how many nodes it holds; its members - and every group
+ * inside it - leave the drawing. An edge that pointed at something inside the fold is re-aimed at the fold's
+ * box, and an edge between two members of the same fold disappears: both ends are now the same box, and a
+ * self-loop would be a claim the source never made.
+ *
+ * Ids nobody declared are ignored, and folding a group whose contents are already gone changes nothing, so the
+ * function is total on any diagram and any set of names.
+ */
+export function collapse(diagram: Diagram, folded: Iterable<string>): Diagram {
+  const asked = new Set(folded)
+  const groups: DiagramGroup[] = diagram.groups ?? []
+  if (asked.size === 0 || groups.length === 0) return diagram
+
+  // Only groups that exist, and that still have contents, can be folded.
+  const byId = new Map(groups.map((group) => [group.id, group] as const))
+  const targets = new Set<string>()
+  for (const id of asked) {
+    const group = byId.get(id)
+    if (group !== undefined && subtreeSize(diagram, id, new Set()) > 0) targets.add(id)
+  }
+  if (targets.size === 0) return diagram
+
+  // A fold inside another fold is served by the outer one: the inner box would not be drawn anyway.
+  for (const id of [...targets]) {
+    let cursor = byId.get(id)?.parent
+    const seen = new Set<string>()
+    while (cursor !== undefined && !seen.has(cursor)) {
+      seen.add(cursor)
+      if (targets.has(cursor)) {
+        targets.delete(id)
+        break
+      }
+      cursor = byId.get(cursor)?.parent
+    }
+  }
+
+  const removedNodes = new Set<string>()
+  const removedGroups = new Set<string>()
+  const descend = (groupId: string, seen: Set<string>): void => {
+    if (seen.has(groupId)) return
+    seen.add(groupId)
+    removedGroups.add(groupId)
+    const group = byId.get(groupId)
+    if (group === undefined) return
+    for (const member of group.members) removedNodes.add(member)
+    for (const child of groups.filter((entry) => entry.parent === groupId)) descend(child.id, seen)
+  }
+  for (const id of targets) descend(id, new Set())
+
+  /** The innermost fold that swallowed this id, if any. */
+  const foldOf = (id: string): string | undefined => {
+    for (const target of targets) {
+      const inSubtree = (groupId: string, seen: Set<string>): boolean => {
+        if (seen.has(groupId)) return false
+        seen.add(groupId)
+        if (groupId === target) return true
+        return groups.filter((entry) => entry.parent === groupId).some((child) => inSubtree(child.id, seen))
+      }
+      const group = byId.get(target) as DiagramGroup
+      if (group.members.includes(id) || inSubtree(ownerOf(diagram, id) ?? '', new Set())) return target
+    }
+    return undefined
+  }
+
+  // The box that replaces a fold takes the place of its first member, so the drawing keeps the order the source
+  // gave it: a folded package belongs where the package was, not at the end of the page.
+  const nodes: DiagramNode[] = []
+  const emitted = new Set<string>()
+  for (const node of diagram.nodes) {
+    if (!removedNodes.has(node.id)) {
+      nodes.push(node)
+      continue
+    }
+    const fold = foldOf(node.id)
+    if (fold === undefined || emitted.has(fold)) continue
+    emitted.add(fold)
+    const group = byId.get(fold) as DiagramGroup
+    nodes.push({ id: fold, label: group.label + ' (' + String(subtreeSize(diagram, fold, new Set())) + ')', role: 'normal' })
+  }
+  // A fold whose members are not in `nodes` at all still deserves a box rather than vanishing.
+  for (const id of targets) {
+    if (emitted.has(id)) continue
+    const group = byId.get(id) as DiagramGroup
+    nodes.push({ id, label: group.label + ' (' + String(subtreeSize(diagram, id, new Set())) + ')', role: 'normal' })
+  }
+
+  const edges: DiagramEdge[] = []
+  const seenEdges = new Set<string>()
+  for (const edge of diagram.edges) {
+    const from = removedNodes.has(edge.from) ? foldOf(edge.from) : edge.from
+    const to = removedNodes.has(edge.to) ? foldOf(edge.to) : edge.to
+    if (from === undefined || to === undefined) continue
+    if (from === to) continue
+    const key = from + '>' + to + ':' + edge.label
+    if (seenEdges.has(key)) continue
+    seenEdges.add(key)
+    edges.push({ ...edge, from, to })
+  }
+
+  // A folded box stands where its group stood, so it belongs to that group's parent: without this the box that
+  // replaced an inner boundary would be drawn outside the outer one, which reads as "it left the package".
+  const adopted = new Map<string, string[]>()
+  for (const id of targets) {
+    const parent = byId.get(id)?.parent
+    if (parent === undefined || targets.has(parent) || removedGroups.has(parent)) continue
+    adopted.set(parent, [...(adopted.get(parent) ?? []), id])
+  }
+  const remaining = groups
+    .filter((group) => !removedGroups.has(group.id) && targets.has(group.id) === false)
+    .map((group) => {
+      const extra = adopted.get(group.id)
+      if (extra === undefined) return group
+      return { ...group, members: [...group.members.filter((member) => !removedNodes.has(member)), ...extra] }
+    })
+  const caption = diagram.caption + (targets.size === 1 ? ', 1 group folded' : ', ' + String(targets.size) + ' groups folded')
+  return {
+    ...diagram,
+    nodes,
+    edges,
+    ...(remaining.length === 0 ? { groups: undefined } : { groups: remaining }),
+    caption,
+  }
+}

package/src/render/diff.ts

@@ -0,0 +1,162 @@
+/**
+ * Structural diff between two drawings.
+ *
+ * A text diff of two diagrams tells a reader that a line moved; it does not tell them that `Cache` left the
+ * `Platform` package, or that `Core` gained a nested boundary. Those are the changes a design review is about,
+ * and they are decided by comparing the containment tree, not the source.
+ *
+ * The diff judges movement, not merit: a group that moved, a member that changed owner, a boundary added or
+ * removed. Whether the new arrangement is better is the reader's call, so the verdict only says whether anything
+ * changed and whether the comparison could run at all.
+ */
+
+import type { Diagram, DiagramGroup } from './model.js'
+
+export type ChangeKind = 'added' | 'removed' | 'renamed' | 'moved' | 'regrouped'
+
+export interface StructuralChange {
+  code: string
+  severity: 'error' | 'warning' | 'info'
+  kind: ChangeKind
+  /** What changed, by id: a group id or a node id. */
+  subject: string
+  message: string
+}
+
+export interface DiffReport {
+  verdict: 'pass' | 'pass_with_findings' | 'fail'
+  changes: StructuralChange[]
+  /** Both sides, so an empty change list cannot be confused with a comparison that never ran. */
+  measured: { before: { nodes: number; groups: number }; after: { nodes: number; groups: number } }
+}
+
+/** The group that directly holds a node, from the side's own declarations. */
+function ownerOf(groups: DiagramGroup[], nodeId: string): string | undefined {
+  return groups.find((group) => group.members.includes(nodeId))?.id
+}
+
+function labels(groups: DiagramGroup[]): Map<string, string> {
+  return new Map(groups.map((group) => [group.id, group.label] as const))
+}
+
+function parents(groups: DiagramGroup[]): Map<string, string | undefined> {
+  return new Map(groups.map((group) => [group.id, group.parent] as const))
+}
+
+/** How a group is named in a finding: its label, falling back to its id when the other side has no label. */
+function nameOf(labelsById: Map<string, string>, id: string): string {
+  return labelsById.get(id) ?? id
+}
+
+/**
+ * Compare the containment structure of two drawings.
+ *
+ * Renames are reported by id: a group that kept its id but changed its text is a rename, while a group whose id
+ * is gone and another whose id is new are an unrelated removal and addition, because the ids are what a caller
+ * tracks across versions.
+ */
+export function diffStructure(before: Diagram, after: Diagram): DiffReport {
+  const beforeGroups = before.groups ?? []
+  const afterGroups = after.groups ?? []
+  const changes: StructuralChange[] = []
+
+  const beforeIds = new Set(beforeGroups.map((group) => group.id))
+  const afterIds = new Set(afterGroups.map((group) => group.id))
+  const beforeLabels = labels(beforeGroups)
+  const afterLabels = labels(afterGroups)
+  const beforeParents = parents(beforeGroups)
+  const afterParents = parents(afterGroups)
+
+  for (const group of afterGroups) {
+    if (beforeIds.has(group.id)) continue
+    changes.push({
+      code: 'H1_GROUP_ADDED',
+      severity: 'info',
+      kind: 'added',
+      subject: group.id,
+      message: 'group "' + group.label + '" is new' + (group.parent === undefined ? '' : ' inside "' + nameOf(afterLabels, group.parent) + '"'),
+    })
+  }
+  for (const group of beforeGroups) {
+    if (afterIds.has(group.id)) continue
+    changes.push({
+      code: 'H2_GROUP_REMOVED',
+      severity: 'info',
+      kind: 'removed',
+      subject: group.id,
+      message: 'group "' + group.label + '" is gone',
+    })
+  }
+
+  for (const group of afterGroups) {
+    if (!beforeIds.has(group.id)) continue
+    const wasCalled = nameOf(beforeLabels, group.id)
+    if (wasCalled !== group.label) {
+      changes.push({
+        code: 'H3_GROUP_RENAMED',
+        severity: 'info',
+        kind: 'renamed',
+        subject: group.id,
+        message: 'group "' + wasCalled + '" is now called "' + group.label + '"',
+      })
+    }
+    const was = beforeParents.get(group.id)
+    const now = group.parent
+    if (was !== now) {
+      const from = was === undefined ? 'the top level' : '"' + nameOf(afterLabels, was) + '"'
+      const to = now === undefined ? 'the top level' : '"' + nameOf(afterLabels, now) + '"'
+      changes.push({
+        code: 'H4_GROUP_MOVED',
+        severity: 'warning',
+        kind: 'moved',
+        subject: group.id,
+        message: 'group "' + group.label + '" moved from ' + from + ' to ' + to,
+      })
+    }
+  }
+
+  const beforeNodes = new Set(before.nodes.map((node) => node.id))
+  const afterNodes = new Set(after.nodes.map((node) => node.id))
+  for (const node of after.nodes) {
+    if (beforeNodes.has(node.id)) continue
+    changes.push({ code: 'H5_NODE_ADDED', severity: 'info', kind: 'added', subject: node.id, message: 'node "' + node.id + '" is new' })
+  }
+  for (const node of before.nodes) {
+    if (afterNodes.has(node.id)) continue
+    changes.push({ code: 'H6_NODE_REMOVED', severity: 'info', kind: 'removed', subject: node.id, message: 'node "' + node.id + '" is gone' })
+  }
+
+  // Movement is only meaningful for a node that exists on both sides.
+  for (const node of after.nodes) {
+    if (!beforeNodes.has(node.id)) continue
+    const was = ownerOf(beforeGroups, node.id)
+    const now = ownerOf(afterGroups, node.id)
+    if (was === now) continue
+    const from = was === undefined ? 'no group' : '"' + nameOf(beforeLabels, was) + '"'
+    const to = now === undefined ? 'no group' : '"' + nameOf(afterLabels, now) + '"'
+    changes.push({
+      code: 'H7_NODE_REGROUPED',
+      severity: 'warning',
+      kind: 'regrouped',
+      subject: node.id,
+      message: 'node "' + node.id + '" moved from ' + from + ' to ' + to,
+    })
+  }
+
+  const measured = {
+    before: { nodes: before.nodes.length, groups: beforeGroups.length },
+    after: { nodes: after.nodes.length, groups: afterGroups.length },
+  }
+  // Nothing to compare is not a pass: an empty report from an empty pair would read as "unchanged".
+  if (before.nodes.length === 0 && after.nodes.length === 0) {
+    return {
+      verdict: 'fail',
+      changes: [
+        { code: 'D0_NO_NODES', severity: 'error', kind: 'removed', subject: '-', message: 'neither side holds a node, so there was nothing to compare' },
+        ...changes,
+      ],
+      measured,
+    }
+  }
+  return { verdict: changes.length === 0 ? 'pass' : 'pass_with_findings', changes, measured }
+}

package/src/render/from-mermaid.ts

@@ -0,0 +1,236 @@
+/**
+ * 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): void {
+  const existing = builder.nodes.get(id)
+  if (existing === undefined) {
+    builder.nodes.set(id, { id, role: 'normal', ...(label === undefined ? {} : { label }) })
+    // 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 } | 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() !== '')
+  return { id, ...(label === undefined ? {} : { label: label.trim().replace(/^["']|["']$/g, '') }) }
+}
+
+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)
+      ensure(builder, right.id, right.label)
+      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)
+      ensure(builder, right.id, right.label)
+      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)
+      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 }
+}