dsh-model-everything 0.5.0 → 0.5.2

package/lib/render/coords.js

@@ -0,0 +1,288 @@
+/**
+ * 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.
+ */
+/** Where each id sits inside its row, in the row's own order. */
+function positions(rows) {
+    const at = new Map();
+    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, at) {
+    const root = new Map();
+    const joined = new Map();
+    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) - at.get(right));
+            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))
+                    continue;
+                joined.set(target, id);
+                root.set(id, root.get(target));
+                joined.set(id, root.get(id));
+                previous = at.get(target);
+            }
+        }
+    }
+    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, root, widthOf, gap) {
+    const clears = new Map();
+    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);
+            const rightBlock = root.get(right);
+            const space = (widthOf(left) + widthOf(right)) / 2 + gap;
+            clears.set(rightBlock, [...(clears.get(rightBlock) ?? []), { block: leftBlock, space }]);
+        }
+    }
+    const placed = new Map();
+    const place = (block) => {
+        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();
+    for (const row of rows) {
+        for (const id of row) {
+            const block = root.get(id);
+            if (!placed.has(block))
+                place(block);
+            x.set(id, placed.get(block));
+        }
+    }
+    return x;
+}
+/** The left edge of the leftmost box and the right edge of the rightmost, in one pass's coordinates. */
+function extentOf(x, rows, widthOf) {
+    let left = Infinity;
+    let right = -Infinity;
+    for (const row of rows) {
+        for (const id of row) {
+            const value = x.get(id);
+            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, widthOf, gap) {
+    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();
+    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, above, below) {
+    const fromTop = layers;
+    const fromBottom = [...layers].reverse();
+    const flip = (rows) => 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, options) {
+    const { layers, chains, sizeOf, chainOf } = input;
+    const gap = options.gap;
+    const laneIds = new Set(chainOf.values());
+    const isDummy = (id) => chainOf.has(id);
+    const isPoint = (id) => isDummy(id) || laneIds.has(id);
+    const widthOf = (id) => (isPoint(id) ? 0 : sizeOf(id).width);
+    const heightOf = (id) => (isPoint(id) ? 0 : sizeOf(id).height);
+    const laneOf = (id) => chainOf.get(id) ?? id;
+    const x = new Map();
+    const read = (id) => x.get(laneOf(id));
+    const above = new Map();
+    const below = new Map();
+    const laneEnds = new Map();
+    const link = (into, id, other) => {
+        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);
+            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);
+            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]) + x.get(ends[1])) / 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), 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 - left;
+        let highest = reserved[depth].highest - 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 = [];
+    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] + layerHeight[layerHeight.length - 1],
+    };
+}

package/lib/render/cycle-break.js

@@ -0,0 +1,147 @@
+/**
+ * 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.
+ */
+/** Tarjan's strongly connected components, iterative enough to be read: the recursion is the algorithm. */
+function tarjan(nodes, outgoing) {
+    let counter = 0;
+    const index = new Map();
+    const low = new Map();
+    const stack = [];
+    const onStack = new Set();
+    const found = [];
+    const visit = (node) => {
+        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), low.get(next)));
+                continue;
+            }
+            if (onStack.has(next))
+                low.set(node, Math.min(low.get(node), index.get(next)));
+        }
+        if (low.get(node) !== index.get(node))
+            return;
+        const component = [];
+        let member;
+        do {
+            member = stack.pop();
+            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) {
+    const known = new Set(graph.nodes.map((node) => node.id));
+    const position = new Map(graph.nodes.map((node, offset) => [node.id, offset]));
+    const edges = graph.edges.map((edge) => ({ ...edge }));
+    const reversed = new Set();
+    const flip = (index) => {
+        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();
+    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();
+    const components = raw.map((members, id) => {
+        for (const member of members)
+            componentOf.set(member, id);
+        return { id, members };
+    });
+    const condensation = [];
+    const seen = new Set();
+    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();
+    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();
+        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) + 1);
+            score.set(edge.to, score.get(edge.to) - 1);
+        }
+        const ordered = [...component.members].sort((left, right) => {
+            const difference = score.get(right) - score.get(left);
+            return difference !== 0 ? difference : position.get(left) - position.get(right);
+        });
+        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/lib/render/dummy.js

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+export function addDummies(layering, edges) {
+    const layers = layering.layers.map((layer) => [...layer]);
+    const chains = [];
+    const chainOf = new Map();
+    const laneOf = new Map();
+    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/lib/render/from-mermaid.js

@@ -40,10 +40,15 @@ const UNSUPPORTED = new Set([
     'requirementdiagram',
     'sankey-beta',
 ]);
-function ensure(builder, id, label) {
+function ensure(builder, id, label, shape) {
     const existing = builder.nodes.get(id);
     if (existing === undefined) {
-        builder.nodes.set(id, { id, role: 'normal', ...(label === undefined ? {} : { label }) });
+        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];
@@ -60,7 +65,26 @@ function nodeFrom(token) {
         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, '') }) };
+    // 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 = 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, title = 'mermaid') {
     const lines = source.split(/\r?\n/);
@@ -78,13 +102,13 @@ export function fromMermaid(source, title = 'mermaid') {
             return;
         const where = 'line ' + String(index + 1) + ': ';
         const lower = line.toLowerCase();
-        const keyword = lower.split(/[\s{}]/)[0] ?? '';
+        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');
+            refused.push(where + '`' + line.split(/\s/)[0] + '` is a directive this renderer ignores');
             return;
         }
         if (/^(graph|flowchart)\b/.test(lower)) {
@@ -160,8 +184,8 @@ export function fromMermaid(source, title = 'mermaid') {
                 refused.push(where + '`' + line + '` does not name two nodes');
                 return;
             }
-            ensure(builder, left.id, left.label);
-            ensure(builder, right.id, right.label);
+            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;
         }
@@ -173,8 +197,8 @@ export function fromMermaid(source, title = 'mermaid') {
                 refused.push(where + '`' + line + '` does not name two nodes');
                 return;
             }
-            ensure(builder, left.id, left.label);
-            ensure(builder, right.id, right.label);
+            ensure(builder, left.id, left.label, left.shape);
+            ensure(builder, right.id, right.label, right.shape);
             push({
                 from: left.id,
                 to: right.id,
@@ -185,7 +209,7 @@ export function fromMermaid(source, title = 'mermaid') {
         }
         const single = nodeFrom(line);
         if (single !== undefined) {
-            ensure(builder, single.id, single.label);
+            ensure(builder, single.id, single.label, single.shape);
             return;
         }
         refused.push(where + '`' + line + '` is not something this renderer draws');