dsh-model-everything 0.5.0 → 0.5.1

package/src/render/layer.ts

@@ -0,0 +1,98 @@
+/**
+ * Layering: which row each box is in.
+ *
+ * The graph is acyclic by the time it gets here. A layered drawing needs every edge to span at least one layer, so it
+ * always travels downwards, and it wants the total of the layers every edge spans beyond one to be as small as
+ * possible: those are the edges that have to be drawn through a row of placeholders instead of going straight down a
+ * gap.
+ *
+ * Longest paths are the first guess: every source on the top row, every other node one layer below its latest
+ * predecessor. It is feasible and it is not optimal, because it puts every node as high as it can go - a node whose
+ * edges leave it with slack above the boxes it points at is a node that could have moved down and shortened them.
+ * `network-simplex.ts` solves the program the mature layering implementations solve: the ranking that minimises the
+ * total length, found by exchanging edges in a tight tree until no exchange is left that shortens it.
+ *
+ * The initial state is layer zero. It is a node with no predecessor - cycle breaking has turned around every edge
+ * that ran into it - so a source, and every source is a candidate for the top row. The pin is passed to the solver as
+ * a constraint, so the search never trades it away: an initial state that moved down the page would be a machine
+ * diagram read from the wrong end.
+ *
+ * Pure: the graph in, one layer per node out.
+ */
+
+import type { LayoutEdge, LayoutGraph } from './layout.js'
+import { minimumLength, type RankEdge } from './network-simplex.js'
+
+export interface Layering {
+  /** The ids of each layer, top to bottom. A layer holds at least one node. */
+  layers: string[][]
+  layerOf: Map<string, number>
+}
+
+/**
+ * The longest-path ranking: the highest layer each node can possibly take.
+ *
+ * Every source starts on layer zero and every other node one below its latest predecessor, which is the shortest
+ * ranking that is feasible at all - and, because no node can then move up, the starting point the exchange search
+ * needs. A node the walk never reaches is part of a cycle and is put on layer zero: the stage is defined on a DAG,
+ * and a graph that arrived cyclic is laid out as far as it can be rather than losing the boxes of the cycle.
+ */
+function longestPath(ids: string[], edges: LayoutEdge[], index: Map<string, number>): number[] {
+  const rank = new Array<number>(ids.length).fill(0)
+  const pending = new Array<number>(ids.length).fill(0)
+  const outgoing: number[][] = ids.map(() => [])
+  for (const edge of edges) {
+    outgoing[index.get(edge.from) as number].push(index.get(edge.to) as number)
+    pending[index.get(edge.to) as number] += 1
+  }
+  const queue: number[] = []
+  for (let node = 0; node < ids.length; node += 1) if (pending[node] === 0) queue.push(node)
+  for (let head = 0; head < queue.length; head += 1) {
+    const node = queue[head]
+    for (const target of outgoing[node]) {
+      rank[target] = Math.max(rank[target], rank[node] + 1)
+      pending[target] -= 1
+      if (pending[target] === 0) queue.push(target)
+    }
+  }
+  return rank
+}
+
+export function layer(graph: LayoutGraph, edges: LayoutEdge[]): Layering {
+  // A model is data: the same box may be written twice, and an edge may name a box this level does not have.
+  const ids: string[] = []
+  const seen = new Set<string>()
+  for (const node of graph.nodes) {
+    if (seen.has(node.id)) continue
+    seen.add(node.id)
+    ids.push(node.id)
+  }
+  const index = new Map(ids.map((id, offset) => [id, offset] as const))
+  const forward = edges.filter((edge) => index.has(edge.from) && index.has(edge.to) && edge.from !== edge.to)
+  const rankEdges: RankEdge[] = forward.map((edge) => ({
+    from: index.get(edge.from) as number,
+    to: index.get(edge.to) as number,
+    minLength: 1,
+    weight: 1,
+  }))
+
+  // The pin only means something for a node that could be on the top row. A node with a predecessor cannot be: it is
+  // forced below it, and no ranking puts it first while keeping the edge that points at it.
+  let pinned: number | undefined
+  if (graph.init !== undefined && index.has(graph.init)) {
+    const start = index.get(graph.init) as number
+    const forced = forward.some((edge) => edge.to === graph.init)
+    if (!forced) pinned = start
+  }
+
+  const rank = minimumLength({ count: ids.length, edges: rankEdges, start: longestPath(ids, forward, index), ...(pinned === undefined ? {} : { pinned }) })
+
+  const layers: string[][] = []
+  for (const [offset, id] of ids.entries()) {
+    const depth = rank[offset]
+    while (layers.length <= depth) layers.push([])
+    layers[depth].push(id)
+  }
+  const layerOf = new Map(ids.map((id, offset) => [id, rank[offset]] as const))
+  return { layers, layerOf }
+}

package/src/render/layout.ts

@@ -1,62 +1,101 @@
-/**
- * Ranks for a machine, and the order of states within each rank.
- *
- * Breadth-first from the initial state decides the row: the layout a reader expects, and the one a layered
- * drawing asks for - edges mostly flow down, and a state's row is how far it is from the start. A state
- * nothing reaches goes in a block of its own rather than being dropped.
- *
- * Within a row, states keep the order breadth-first found them in: a row is filled by walking the row above
- * left to right, so a state already sits under the parent that discovered it. A barycentre pass was written
- * and removed - with breadth-first insertion it could never move a state, so it was complexity without an
- * observable effect.
- *
- * Pure, and asserted on the rows themselves.
- */
-
-import type { DiagramEdge, DiagramNode } from './model.js'
-
-export interface Ranked {
-  /** The state ids of each row, top to bottom, already ordered left to right. */
-  rows: string[][]
-  /** States no edge reaches from the initial one. */
-  unreachable: string[]
-}
-
-export function rankStates(nodes: DiagramNode[], edges: DiagramEdge[], init: string | undefined): Ranked {
-  const ids = nodes.map((node) => node.id)
-  const known = new Set(ids)
-  const start = init !== undefined && known.has(init) ? init : ids[0]
-
-  const outgoing = new Map<string, string[]>()
-  const incoming = new Map<string, string[]>()
-  for (const edge of edges) {
-    if (!known.has(edge.from) || !known.has(edge.to)) continue
-    outgoing.set(edge.from, [...(outgoing.get(edge.from) ?? []), edge.to])
-    incoming.set(edge.to, [...(incoming.get(edge.to) ?? []), edge.from])
-  }
-
-  const depth = new Map<string, number>()
-  if (start !== undefined) {
-    depth.set(start, 0)
-    const queue: string[] = [start]
-    while (queue.length > 0) {
-      const id = queue.shift() as string
-      const level = depth.get(id) as number
-      for (const target of outgoing.get(id) ?? []) {
-        if (depth.has(target)) continue
-        depth.set(target, level + 1)
-        queue.push(target)
-      }
-    }
-  }
-
-  const rows: string[][] = []
-  for (const id of ids) {
-    const level = depth.get(id)
-    if (level === undefined) continue
-    while (rows.length <= level) rows.push([])
-    rows[level].push(id)
-  }
-
-  return { rows, unreachable: ids.filter((id) => !depth.has(id)) }
-}
+/**
+ * The graph the layout stages agree on, and the order they start from.
+ *
+ * A layout stage has no business knowing what a diagram is: it sees boxes with a size and edges
+ * between them. That is what `LayoutGraph` is, and it is the whole vocabulary the pipeline shares -
+ * cycle breaking reads it, layering writes layers, ordering and coordinate assignment read those.
+ *
+ * `rankStates` stays: it is the breadth-first order a source's own reading suggests, and it seeds
+ * the ordering stage with the discovery order instead of whatever order the parser happened to
+ * collect. It no longer decides which row a state is in - `layer.ts` does that now - so the rows it
+ * returns are only a first guess at the left-to-right order.
+ *
+ * Pure, and asserted on the answer itself.
+ */
+
+/** A box to place: an id, and the space its text needs. */
+export interface LayoutNode {
+  id: string
+  width: number
+  height: number
+}
+
+/** An edge to draw: which two boxes it joins, and which diagram edge it came from. */
+export interface LayoutEdge {
+  /** The index in the diagram's own edge list, so the drawing can report a lane back for it. */
+  index: number
+  from: string
+  to: string
+}
+
+/** One level of a nested drawing: what is placed together in a single pass of the pipeline. */
+export interface LayoutGraph {
+  nodes: LayoutNode[]
+  edges: LayoutEdge[]
+  /** The box that must stay on layer zero, when the source named one. */
+  init?: string
+}
+
+export interface Ranked {
+  /** The state ids of each row, top to bottom, already ordered left to right. */
+  rows: string[][]
+  /** States no edge reaches from the initial one. */
+  unreachable: string[]
+}
+
+export function rankStates(
+  nodes: ReadonlyArray<{ id: string }>,
+  edges: ReadonlyArray<{ from: string; to: string }>,
+  init: string | undefined,
+): Ranked {
+  const ids = nodes.map((node) => node.id)
+  const known = new Set(ids)
+  const start = init !== undefined && known.has(init) ? init : ids[0]
+
+  const outgoing = new Map<string, string[]>()
+  for (const edge of edges) {
+    if (!known.has(edge.from) || !known.has(edge.to)) continue
+    outgoing.set(edge.from, [...(outgoing.get(edge.from) ?? []), edge.to])
+  }
+
+  const depth = new Map<string, number>()
+  if (start !== undefined) {
+    depth.set(start, 0)
+    const queue: string[] = [start]
+    while (queue.length > 0) {
+      const id = queue.shift() as string
+      const level = depth.get(id) as number
+      for (const target of outgoing.get(id) ?? []) {
+        if (depth.has(target)) continue
+        depth.set(target, level + 1)
+        queue.push(target)
+      }
+    }
+  }
+
+  const rows: string[][] = []
+  for (const id of ids) {
+    const level = depth.get(id)
+    if (level === undefined) continue
+    while (rows.length <= level) rows.push([])
+    rows[level].push(id)
+  }
+
+  return { rows, unreachable: ids.filter((id) => !depth.has(id)) }
+}
+
+/**
+ * The left-to-right seed the ordering stage starts from.
+ *
+ * Breadth-first discovery is what a reader expects a drawing to follow, so it is a better first
+ * guess than the order the parser collected. A state nothing reaches has no discovery order and
+ * keeps the order it was written in, after everything that was reached.
+ */
+export function seedOrder(graph: LayoutGraph): Map<string, number> {
+  const ranked = rankStates(graph.nodes, graph.edges, graph.init)
+  const order = new Map<string, number>()
+  let index = 0
+  for (const row of ranked.rows) for (const id of row) order.set(id, index++)
+  for (const id of ranked.unreachable) order.set(id, index++)
+  return order
+}

package/src/render/model.ts

@@ -1,67 +1,86 @@
-/**
- * The diagram a renderer draws, in the notation it came from being nobody's business.
- *
- * Every source - a verification report, a Mermaid file, a PlantUML component diagram, a dependency scan -
- * is reduced to this one shape before anything is laid out. A renderer that understood notations would have
- * to be changed for each of them; a renderer that understands this does not.
- *
- * Pure data, no functions: a model can be serialised, compared and asserted.
- */
-
-/** What a node is, as far as colour is concerned. */
-export type NodeRole = 'normal' | 'error' | 'warning' | 'muted'
-
-export interface DiagramNode {
-  id: string
-  /** The text drawn inside the box. Defaults to the id when a notation labelled it. */
-  label?: string
-  role: NodeRole
-}
-
-export interface DiagramEdge {
-  from: string
-  to: string
-  label: string
-  /** A dashed edge, for notations that distinguish one. */
-  dashed?: boolean
-}
-
-export interface DiagramGroup {
-  id: string
-  label: string
-  /**
-   * The nodes declared directly inside it: a group is a box around boxes, and its own members are the ones a
-   * source named there. A node inside a nested group is that group's member, not this one's.
-   */
-  members: string[]
-  /**
-   * The group that contains this one, when the source said so.
-   *
-   * Only a parser can know this - nesting is a property of where the text put the boundary - so the layout does
-   * not guess it. Left absent, the painter falls back to inferring containment from member sets, which is the
-   * best a hand-written model can offer.
-   */
-  parent?: string
-}
-
-export interface Diagram {
-  kind: 'machine' | 'graph' | 'none'
-  /** The state the machine starts in, when the source declared one. */
-  init?: string
-  title: string
-  nodes: DiagramNode[]
-  edges: DiagramEdge[]
-  groups?: DiagramGroup[]
-  /** One line under the drawing: what was decided, in words the drawing cannot carry. */
-  caption: string
-}
-
-/** An empty drawing, for a source that produced no nodes. */
-export function emptyDiagram(title: string, caption: string): Diagram {
-  return { kind: 'none', title, nodes: [], edges: [], caption }
-}
-
-/** The label to draw for a node: its own label when the notation gave one, else its id. */
-export function labelOf(node: DiagramNode): string {
-  return node.label !== undefined && node.label !== '' ? node.label : node.id
-}
+/**
+ * The diagram a renderer draws, in the notation it came from being nobody's business.
+ *
+ * Every source - a verification report, a Mermaid file, a PlantUML component diagram, a dependency scan -
+ * is reduced to this one shape before anything is laid out. A renderer that understood notations would have
+ * to be changed for each of them; a renderer that understands this does not.
+ *
+ * Pure data, no functions: a model can be serialised, compared and asserted.
+ */
+
+/** What a node is, as far as colour is concerned. */
+export type NodeRole = 'normal' | 'error' | 'warning' | 'muted'
+
+/** The symbol a node is drawn as. UML and Mermaid both distinguish these; the notation decides which one applies. */
+export type NodeShape = 'rect' | 'diamond' | 'cylinder' | 'stadium' | 'circle' | 'subroutine' | 'hexagon'
+
+export interface DiagramNode {
+  id: string
+  /** The text drawn inside the box. Defaults to the id when a notation labelled it. */
+  label?: string
+  role: NodeRole
+  /** Defaults to a rectangle: a node the source gave no shape has no shape to draw. */
+  shape?: NodeShape
+}
+
+/**
+ * What an edge's head means, when the notation distinguished it.
+ *
+ * The painter draws the meaning: a plain arrow for an association, a hollow triangle for a generalisation or a
+ * realisation, a filled diamond at the source for a composition, a hollow one for an aggregation, and a dashed
+ * line for the two dependency-flavoured kinds.
+ */
+export type EdgeArrow = 'association' | 'dependency' | 'generalization' | 'realization' | 'composition' | 'aggregation'
+
+export interface DiagramEdge {
+  from: string
+  to: string
+  label: string
+  /** A dashed edge, for notations that distinguish one. */
+  dashed?: boolean
+  /**
+   * The arrow the notation stated. Absent means the plain arrow every edge has been drawn with: a Mermaid edge
+   * states no arrow type, so it carries no field and is drawn exactly as before.
+   */
+  arrow?: EdgeArrow
+}
+
+export interface DiagramGroup {
+  id: string
+  label: string
+  /**
+   * The nodes declared directly inside it: a group is a box around boxes, and its own members are the ones a
+   * source named there. A node inside a nested group is that group's member, not this one's.
+   */
+  members: string[]
+  /**
+   * The group that contains this one, when the source said so.
+   *
+   * Only a parser can know this - nesting is a property of where the text put the boundary - so the layout does
+   * not guess it. Left absent, the painter falls back to inferring containment from member sets, which is the
+   * best a hand-written model can offer.
+   */
+  parent?: string
+}
+
+export interface Diagram {
+  kind: 'machine' | 'graph' | 'none'
+  /** The state the machine starts in, when the source declared one. */
+  init?: string
+  title: string
+  nodes: DiagramNode[]
+  edges: DiagramEdge[]
+  groups?: DiagramGroup[]
+  /** One line under the drawing: what was decided, in words the drawing cannot carry. */
+  caption: string
+}
+
+/** An empty drawing, for a source that produced no nodes. */
+export function emptyDiagram(title: string, caption: string): Diagram {
+  return { kind: 'none', title, nodes: [], edges: [], caption }
+}
+
+/** The label to draw for a node: its own label when the notation gave one, else its id. */
+export function labelOf(node: DiagramNode): string {
+  return node.label !== undefined && node.label !== '' ? node.label : node.id
+}