dsh-model-everything 0.4.1 → 0.5.1

package/src/render/coords.ts

@@ -0,0 +1,328 @@
+/**
+ * Coordinate assignment: how far right each box sits. Brandes-Kopf.
+ *
+ * The layers are rows and the order inside them is settled; the only freedom left is the x of each box. Three
+ * properties make a drawing readable:
+ *
+ * - A box sits over what it is connected to, and a chain of boxes sits on one vertical line. Brandes and Kopf get
+ *   this by *aligning*: every box is offered the median of its neighbours in the layer just above (or just below) and
+ *   is joined to that neighbour's block when the join crosses no other edge. A block is then one node of a smaller
+ *   graph, and a box that aligned downwards through five rows comes out as one straight segment.
+ * - Nothing overlaps, and the empty strip between two boxes in a row is the same everywhere. The blocks are compacted
+ *   against each other by the least distance their rows allow, which is a longest path over the block graph: a block
+ *   sits as far left as the block to its left permits, and no further.
+ * - The drawing is balanced rather than packed to one side. Aligning downwards alone would lean everything left, so
+ *   the same two passes are run from the bottom up, and each pair is run once more mirrored left to right. The four
+ *   layouts are then averaged. Averaging is a convex combination, and the separation constraints are linear, so the
+ *   average of four layouts that keep the boxes apart also keeps them apart - the balance is free of overlaps by
+ *   construction. A pass that starts at the top and one that starts at the bottom compact their blocks from opposite
+ *   ends, so each side is first slid onto the origin of the first pass of that side, and only then averaged.
+ *
+ * Three things this module owes the rest of the pipeline rather than the paper:
+ *
+ * - A long edge's dummies share one x. They are one lane, not one point per row, so each lane is collapsed to the mean
+ *   of the x its two ends want - the straight drop a reader follows. Collapsing can put a lane where a box already is,
+ *   so the last pass spends the lane's space: boxes are pushed right past it and never the other way, and a row keeps
+ *   the width its placeholders were given, which is the width a corridor needs when the lane has to go around a box.
+ *   The lane is a proposal either way - the channel stage moves a lane into a free corridor when routing needs it, and
+ *   a box never moves for a lane.
+ * - A lane is not a neighbour to be aligned with. A box that aligned itself to a lane passing through its row would be
+ *   pulled off the boxes it does connect to, which is how a decision with one long edge comes out as a staircase. Lanes
+ *   are placed by the compaction and then by the channel stage, which is where a lane belongs.
+ * - The empty strip between two rows is the caller's, not this module's: the y of a row is a running sum with one gap.
+ *
+ * Pure: layers and chains in, coordinates out.
+ */
+
+import type { Chain } from './dummy.js'
+
+export interface Sized {
+  width: number
+  height: number
+}
+
+export interface CoordInput {
+  layers: string[][]
+  chains: Chain[]
+  sizeOf: (id: string) => Sized
+  /** A dummy instance, and the shared lane it belongs to. */
+  chainOf: ReadonlyMap<string, string>
+}
+
+export interface CoordOptions {
+  /** The empty space between two side-by-side boxes. */
+  gap: number
+  /** The empty strip between two layers. */
+  layerGap: number
+}
+
+export interface Coordinates {
+  /** Centre x, keyed by node id and by lane id. A long edge's dummies share one entry. */
+  x: Map<string, number>
+  /** The top y of each layer. */
+  layerY: number[]
+  layerHeight: number[]
+  layerWidth: number[]
+  width: number
+  height: number
+}
+
+/** What one pass needs: the rows in its own order, and where each id's neighbours in the row above it are. */
+interface Frame {
+  /** The rows, top to bottom in this pass's frame, each already in the pass's left-to-right order. */
+  rows: string[][]
+  /** For each id, the ids it is joined to in the previous row of this frame. */
+  near: ReadonlyMap<string, string[]>
+  /** True when this pass reads the rows mirror-image, so its coordinates have to be flipped back. */
+  mirrored: boolean
+}
+
+/** Where each id sits inside its row, in the row's own order. */
+function positions(rows: string[][]): Map<string, number> {
+  const at = new Map<string, number>()
+  for (const row of rows) row.forEach((id, index) => at.set(id, index))
+  return at
+}
+
+/**
+ * Join each id to the median of its neighbours in the row above, unless that join would cross another edge.
+ *
+ * One block per chain of joins, reported as the block's root per id. The `previous` cursor is the whole of the
+ * crossing test: as ids are taken left to right, a neighbour has to be strictly right of the one the previous id was
+ * joined to, and since the ids are taken in order that is exactly "the joins do not cross".
+ */
+function alignBlocks(frame: Frame, at: Map<string, number>): Map<string, string> {
+  const root = new Map<string, string>()
+  const joined = new Map<string, string>()
+  for (const row of frame.rows) {
+    for (const id of row) {
+      root.set(id, id)
+      joined.set(id, id)
+    }
+  }
+  for (let depth = 1; depth < frame.rows.length; depth += 1) {
+    let previous = -1
+    for (const id of frame.rows[depth]) {
+      const close = frame.near.get(id) ?? []
+      if (close.length === 0) continue
+      const sorted = [...close].sort((left, right) => (at.get(left) as number) - (at.get(right) as number))
+      const middle = (sorted.length - 1) / 2
+      // An even number of neighbours has two medians. Both are tried, nearest first, so a box with two parents is as
+      // happy under either as the paper's version.
+      for (let cursor = Math.floor(middle); cursor <= Math.ceil(middle); cursor += 1) {
+        if (joined.get(id) !== id) break
+        const target = sorted[cursor]
+        if (previous >= (at.get(target) as number)) continue
+        joined.set(target, id)
+        root.set(id, root.get(target) as string)
+        joined.set(id, root.get(id) as string)
+        previous = at.get(target) as number
+      }
+    }
+  }
+  return root
+}
+
+/**
+ * Place the blocks: each one as far left as the block to its left in any row allows.
+ *
+ * That is a longest path over the block graph, whose edges run from a block to the block it has to clear, weighted by
+ * the least distance between the two ids that forced the edge. Blocks cannot cross by construction, so the graph has
+ * no cycle; the guard is there because a cycle would otherwise be an infinite recursion rather than a wrong drawing.
+ */
+function compactBlocks(rows: string[][], root: Map<string, string>, widthOf: (id: string) => number, gap: number): Map<string, number> {
+  const clears = new Map<string, Array<{ block: string; space: number }>>()
+  for (const row of rows) {
+    for (let index = 1; index < row.length; index += 1) {
+      const left = row[index - 1]
+      const right = row[index]
+      const leftBlock = root.get(left) as string
+      const rightBlock = root.get(right) as string
+      const space = (widthOf(left) + widthOf(right)) / 2 + gap
+      clears.set(rightBlock, [...(clears.get(rightBlock) ?? []), { block: leftBlock, space }])
+    }
+  }
+  const placed = new Map<string, number>()
+  const place = (block: string): number => {
+    const known = placed.get(block)
+    if (known !== undefined) return known
+    let value = 0
+    for (const step of clears.get(block) ?? []) value = Math.max(value, place(step.block) + step.space)
+    placed.set(block, value)
+    return value
+  }
+  const x = new Map<string, number>()
+  for (const row of rows) {
+    for (const id of row) {
+      const block = root.get(id) as string
+      if (!placed.has(block)) place(block)
+      x.set(id, placed.get(block) as number)
+    }
+  }
+  return x
+}
+
+/** The left edge of the leftmost box and the right edge of the rightmost, in one pass's coordinates. */
+function extentOf(x: Map<string, number>, rows: string[][], widthOf: (id: string) => number): { left: number; right: number } {
+  let left = Infinity
+  let right = -Infinity
+  for (const row of rows) {
+    for (const id of row) {
+      const value = x.get(id) as number
+      left = Math.min(left, value - widthOf(id) / 2)
+      right = Math.max(right, value + widthOf(id) / 2)
+    }
+  }
+  return { left, right }
+}
+
+/** One pass: align the rows in this frame, compact the blocks, and flip the answer back if the frame is mirrored. */
+function onePass(frame: Frame, widthOf: (id: string) => number, gap: number): Map<string, number> {
+  const at = positions(frame.rows)
+  const root = alignBlocks(frame, at)
+  const x = compactBlocks(frame.rows, root, widthOf, gap)
+  if (!frame.mirrored) return x
+  const mirrored = new Map<string, number>()
+  for (const [id, value] of x) mirrored.set(id, -value)
+  return mirrored
+}
+
+/** The four passes a balanced layout needs: down and up, each read left to right and right to left. */
+function frames(layers: string[][], above: ReadonlyMap<string, string[]>, below: ReadonlyMap<string, string[]>): Frame[] {
+  const fromTop = layers
+  const fromBottom = [...layers].reverse()
+  const flip = (rows: string[][]): string[][] => rows.map((row) => [...row].reverse())
+  return [
+    { rows: fromTop, near: above, mirrored: false },
+    { rows: flip(fromTop), near: above, mirrored: true },
+    { rows: fromBottom, near: below, mirrored: false },
+    { rows: flip(fromBottom), near: below, mirrored: true },
+  ]
+}
+
+export function assignCoordinates(input: CoordInput, options: CoordOptions): Coordinates {
+  const { layers, chains, sizeOf, chainOf } = input
+  const gap = options.gap
+  const laneIds = new Set<string>(chainOf.values())
+  const isDummy = (id: string): boolean => chainOf.has(id)
+  const isPoint = (id: string): boolean => isDummy(id) || laneIds.has(id)
+  const widthOf = (id: string): number => (isPoint(id) ? 0 : sizeOf(id).width)
+  const heightOf = (id: string): number => (isPoint(id) ? 0 : sizeOf(id).height)
+  const laneOf = (id: string): string => chainOf.get(id) ?? id
+  const x = new Map<string, number>()
+  const read = (id: string): number => x.get(laneOf(id)) as number
+
+  const above = new Map<string, string[]>()
+  const below = new Map<string, string[]>()
+  const laneEnds = new Map<string, string[]>()
+  const link = (into: Map<string, string[]>, id: string, other: string): void => {
+    into.set(id, [...(into.get(id) ?? []), other])
+  }
+  for (const chain of chains) {
+    for (let cursor = 0; cursor + 1 < chain.path.length; cursor += 1) {
+      const top = chain.path[cursor]
+      const bottom = chain.path[cursor + 1]
+      // A lane is not a neighbour to align with: only two boxes are, which is what keeps a box over the boxes it
+      // connects to when a long edge crosses its row.
+      if (!isDummy(top) && !isDummy(bottom)) {
+        link(below, top, bottom)
+        link(above, bottom, top)
+      }
+    }
+    if (chain.path.length > 2) {
+      const lane = chainOf.get(chain.path[1])
+      if (lane !== undefined) laneEnds.set(lane, [chain.path[0], chain.path[chain.path.length - 1]])
+    }
+  }
+
+  // The four layouts, averaged. A pass that starts at the top and a pass that starts at the bottom compact their
+  // blocks from opposite ends, so the four answers do not share an origin: each side is first slid onto the origin of
+  // the first pass of that side, and only then are they averaged. Averaging is what balances them - a box that aligned
+  // in one pass and not in another keeps the part the passes agreed on, which is the paper's last step, at the cost of
+  // one average.
+  const candidates = frames(layers, above, below).map((frame) => onePass(frame, widthOf, gap))
+  const leftOrigin = extentOf(candidates[0], layers, widthOf).left
+  const rightOrigin = extentOf(candidates[1], layers, widthOf).right
+  for (const [index, candidate] of candidates.entries()) {
+    const extent = extentOf(candidate, layers, widthOf)
+    const shift = index % 2 === 0 ? leftOrigin - extent.left : rightOrigin - extent.right
+    for (const [id, value] of candidate) candidate.set(id, value + shift)
+  }
+  for (const row of layers) {
+    for (const id of row) {
+      let total = 0
+      for (const candidate of candidates) total += candidate.get(id) as number
+      x.set(id, total / candidates.length)
+    }
+  }
+
+  // What each row has to make room for. The boxes are one part; the space the lane's placeholders were given by the
+  // compaction is the other, because that is where a corridor can run when the lane's own proposal lands on a box. A
+  // row that reserved nothing for its lanes is as wide as its boxes; a row whose lane had to go around a box keeps the
+  // width that detour needed, so the page is planned for the drawing that will be painted rather than the boxes alone.
+  const reserved = layers.map((layer) => {
+    let lowest = Infinity
+    let highest = -Infinity
+    for (const id of layer) {
+      const value = x.get(id) as number
+      lowest = Math.min(lowest, value - widthOf(id) / 2)
+      highest = Math.max(highest, value + widthOf(id) / 2)
+    }
+    return { lowest, highest }
+  })
+
+  // A lane is one variable across every row it crosses. The four passes give each of its dummies its own x; the lane
+  // takes the mean of what its two ends want, because the straight drop between them is what a reader follows. The rows
+  // it crosses are the channel stage's to keep it clear of. It stays a proposal either way: `channels.ts` moves a lane
+  // that lands on a box.
+  for (const [lane, ends] of laneEnds) x.set(lane, ((x.get(ends[0]) as number) + (x.get(ends[1]) as number)) / 2)
+  for (const id of chainOf.keys()) x.delete(id)
+
+  // The rows keep their order and their gap. A lane in a row does not move a box out of the way; a box does move for
+  // the box before it, because two boxes on top of each other is the one thing a drawing may not do.
+  for (const row of layers) {
+    let cursor = -Infinity
+    for (const id of row) {
+      if (isDummy(id)) {
+        cursor = Math.max(cursor, read(id))
+        continue
+      }
+      const width = widthOf(id)
+      const centre = Math.max(x.get(id) as number, cursor + width / 2)
+      x.set(id, centre)
+      cursor = centre + width / 2 + gap
+    }
+  }
+
+  let left = 0
+  for (const [id, value] of x) left = Math.min(left, value - widthOf(id) / 2)
+  for (const [id, value] of x) x.set(id, value - left)
+
+  const layerHeight = layers.map((layer) => Math.max(0, ...layer.map((id) => heightOf(id))))
+  const layerWidth = layers.map((layer, depth) => {
+    let lowest = (reserved[depth].lowest as number) - left
+    let highest = (reserved[depth].highest as number) - left
+    for (const id of layer) {
+      const value = read(id)
+      lowest = Math.min(lowest, value - widthOf(id) / 2)
+      highest = Math.max(highest, value + widthOf(id) / 2)
+    }
+    return highest - lowest
+  })
+  const layerY: number[] = []
+  let top = 0
+  for (const [depth, height] of layerHeight.entries()) {
+    layerY.push(top)
+    top += height + options.layerGap
+  }
+  let width = 0
+  for (const [id, value] of x) width = Math.max(width, value + widthOf(id) / 2)
+  return {
+    x,
+    layerY,
+    layerHeight,
+    layerWidth,
+    width,
+    height: layerY.length === 0 ? 0 : (layerY[layerY.length - 1] as number) + (layerHeight[layerHeight.length - 1] as number),
+  }
+}

package/src/render/cycle-break.ts

@@ -0,0 +1,164 @@
+/**
+ * Cycle breaking, in the order a layered layout does it.
+ *
+ * A layered drawing is a drawing of a DAG: an edge that runs back up the page has no layer to go to. The fix is to
+ * lay such an edge out backwards and draw its arrow the way the source wrote it - but *which* edges to turn around
+ * is a decision, and deciding it edge by edge is what makes two back edges of one cycle end up pointing opposite
+ * ways.
+ *
+ * So the graph is decomposed first. Tarjan's algorithm finds the strongly connected components; contracting each to
+ * a node gives the condensation, which is a DAG, so every edge between components already points one way and nothing
+ * between them needs reversing. Only inside a component - where by definition every edge lies on a cycle - is there
+ * an order to choose: the nodes are ranked once, greedily, and every edge inside the component is oriented along that
+ * single ranking. One ranking per component is what "consistently" means: after the pass, every surviving edge of a
+ * component points from a lower rank to a higher one, so the component cannot contain a cycle any more.
+ *
+ * The initial state is a special case: it is layer zero by definition, so an edge that runs into it is a back edge
+ * before the decomposition even starts. Turning those around leaves the state with no predecessor, so the ranking
+ * of its component puts it first and nothing is ever oriented back into it.
+ *
+ * Pure: the same graph in, the same edge directions out.
+ */
+
+import type { LayoutEdge, LayoutGraph } from './layout.js'
+
+/** One strongly connected component: a set of nodes that can all reach each other. */
+export interface Component {
+  /** The component's index in the condensation, numbered in topological order. */
+  id: number
+  members: string[]
+}
+
+export interface BrokenGraph {
+  /** The same edges, in the same order, with the ones that close a cycle turned around. */
+  edges: LayoutEdge[]
+  /** The diagram edges whose direction the layout changed. */
+  reversed: Set<number>
+  /** The strongly connected components, numbered in topological order. */
+  components: Component[]
+  componentOf: Map<string, number>
+  /** Each node's rank inside its own component: every intra-component edge points from a lower rank to a higher. */
+  rank: Map<string, number>
+  /** The condensation: an edge per pair of components that has at least one edge between them. Always acyclic. */
+  condensation: Array<{ from: number; to: number }>
+}
+
+/** Tarjan's strongly connected components, iterative enough to be read: the recursion is the algorithm. */
+function tarjan(nodes: string[], outgoing: Map<string, string[]>): string[][] {
+  let counter = 0
+  const index = new Map<string, number>()
+  const low = new Map<string, number>()
+  const stack: string[] = []
+  const onStack = new Set<string>()
+  const found: string[][] = []
+  const visit = (node: string): void => {
+    index.set(node, counter)
+    low.set(node, counter)
+    counter += 1
+    stack.push(node)
+    onStack.add(node)
+    for (const next of outgoing.get(node) ?? []) {
+      if (!index.has(next)) {
+        visit(next)
+        low.set(node, Math.min(low.get(node) as number, low.get(next) as number))
+        continue
+      }
+      if (onStack.has(next)) low.set(node, Math.min(low.get(node) as number, index.get(next) as number))
+    }
+    if (low.get(node) !== index.get(node)) return
+    const component: string[] = []
+    let member: string
+    do {
+      member = stack.pop() as string
+      onStack.delete(member)
+      component.push(member)
+    } while (member !== node)
+    found.push(component)
+  }
+  for (const node of nodes) if (!index.has(node)) visit(node)
+  return found
+}
+
+export function breakCycles(graph: LayoutGraph): BrokenGraph {
+  const known = new Set(graph.nodes.map((node) => node.id))
+  const position = new Map(graph.nodes.map((node, offset) => [node.id, offset] as const))
+  const edges = graph.edges.map((edge) => ({ ...edge }))
+  const reversed = new Set<number>()
+  const flip = (index: number): void => {
+    const edge = edges[index]
+    const next = edge.from
+    edge.from = edge.to
+    edge.to = next
+  }
+
+  // The initial state is layer zero: every edge running into it is a back edge already.
+  if (graph.init !== undefined && known.has(graph.init)) {
+    for (const [index, edge] of edges.entries()) {
+      if (edge.to === graph.init && edge.from !== graph.init) flip(index)
+    }
+  }
+
+  const outgoing = new Map<string, string[]>()
+  for (const edge of edges) {
+    if (!known.has(edge.from) || !known.has(edge.to) || edge.from === edge.to) continue
+    outgoing.set(edge.from, [...(outgoing.get(edge.from) ?? []), edge.to])
+  }
+  const nodes = graph.nodes.map((node) => node.id)
+  const raw = tarjan(nodes, outgoing)
+  // Tarjan emits a component after everything it reaches, which is the reverse of a topological order.
+  raw.reverse()
+
+  const componentOf = new Map<string, number>()
+  const components: Component[] = raw.map((members, id) => {
+    for (const member of members) componentOf.set(member, id)
+    return { id, members }
+  })
+
+  const condensation: Array<{ from: number; to: number }> = []
+  const seen = new Set<string>()
+  for (const edge of edges) {
+    const from = componentOf.get(edge.from)
+    const to = componentOf.get(edge.to)
+    if (from === undefined || to === undefined || from === to) continue
+    const key = String(from) + '>' + String(to)
+    if (seen.has(key)) continue
+    seen.add(key)
+    condensation.push({ from, to })
+  }
+
+  // Inside each component: one ranking, decided greedily by how much of the flow leaves the node rather than enters
+  // it. That is the order the edges are made to follow, so no two decisions can contradict each other.
+  const rank = new Map<string, number>()
+  for (const component of components) {
+    if (component.members.length < 2) {
+      rank.set(component.members[0], 0)
+      continue
+    }
+    const inside = new Set(component.members)
+    const score = new Map<string, number>()
+    for (const member of component.members) score.set(member, 0)
+    for (const edge of edges) {
+      if (!inside.has(edge.from) || !inside.has(edge.to) || edge.from === edge.to) continue
+      score.set(edge.from, (score.get(edge.from) as number) + 1)
+      score.set(edge.to, (score.get(edge.to) as number) - 1)
+    }
+    const ordered = [...component.members].sort((left, right) => {
+      const difference = (score.get(right) as number) - (score.get(left) as number)
+      return difference !== 0 ? difference : (position.get(left) as number) - (position.get(right) as number)
+    })
+    ordered.forEach((member, offset) => rank.set(member, offset))
+  }
+
+  for (const [index, edge] of edges.entries()) {
+    const from = rank.get(edge.from)
+    const to = rank.get(edge.to)
+    if (from === undefined || to === undefined || edge.from === edge.to) continue
+    if (componentOf.get(edge.from) !== componentOf.get(edge.to)) continue
+    if (from > to) flip(index)
+  }
+
+  edges.forEach((edge, index) => {
+    if (graph.edges[index].from !== edge.from) reversed.add(edge.index)
+  })
+  return { edges, reversed, components, componentOf, rank, condensation }
+}

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 }
+}