Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { compileWorkflow } from '../archify/renderers/workflow/workflow-compiler.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '..', 'archify');
const cli = path.join(skillRoot, 'bin', 'archify.mjs');
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-workflow-compiler-'));
function readJson(file) {
return JSON.parse(fs.readFileSync(file, 'utf8'));
}
function clone(value) {
return JSON.parse(JSON.stringify(value));
}
function sha256(value) {
return createHash('sha256').update(value).digest('hex');
}
// Receipt digests are frozen from pre-styling 7122e1da: they retain node bounds,
// routes, ports, labels and canvas without pinning approved SVG presentation.
function attribute(tag, name) {
const value = tag.match(new RegExp(`\\b${name}="([^"]*)"`))?.[1];
assert.notEqual(value, undefined, `expected ${name} in ${tag}`);
return value;
}
function numericRect(attributes) {
return Object.fromEntries(['x', 'y', 'width', 'height'].map((name) => [
name,
Number(attribute(attributes, name)),
]));
}
function nodeRect(svg, id) {
const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const attributes = svg.match(new RegExp(
`<g\\b[^>]*id="node-${escapedId}"[^>]*>[\\s\\S]*?<rect\\b([^>]*)>`,
))?.[1];
assert.ok(attributes, `expected rendered node ${id}`);
return numericRect(attributes);
}
function edgePoints(svg, id) {
const tag = (svg.match(/<path\b[^>]*>/g) || []).find((candidate) => (
attributeOrUndefined(candidate, 'data-edge-id') === id
));
assert.ok(tag, `expected rendered edge ${id}`);
return attribute(tag, 'data-composition-points')
.split(';')
.map((point) => point.split(',').map(Number));
}
function edgeLabelRect(svg, id) {
const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const attributes = svg.match(new RegExp(
`<g\\b(?=[^>]*data-edge-id="${escapedId}")(?=[^>]*data-edge-label=)[^>]*>[\\s\\S]*?<rect\\b([^>]*)>`,
))?.[1];
assert.ok(attributes, `expected rendered label mask for edge ${id}`);
return numericRect(attributes);
}
function attributeOrUndefined(tag, name) {
return tag.match(new RegExp(`\\b${name}="([^"]*)"`))?.[1];
}
function svgViewBox(svg) {
const tag = svg.match(/<svg\b[^>]*>/)?.[0];
assert.ok(tag, 'expected an SVG root');
return attribute(tag, 'viewBox').split(/\s+/).map(Number);
}
function legendGeometry(svg) {
return svg.match(/<g data-legend-semantic-kind="[^"]+"[^>]*>/g) || [];
}
function assertRectInsideViewBox(rect, viewBox, message) {
const [minX, minY, width, height] = viewBox;
assert.ok(rect.x >= minX, `${message}: left edge ${rect.x} is outside ${minX}`);
assert.ok(rect.y >= minY, `${message}: top edge ${rect.y} is outside ${minY}`);
assert.ok(
rect.x + rect.width <= minX + width,
`${message}: right edge ${rect.x + rect.width} is outside ${minX + width}`,
);
assert.ok(
rect.y + rect.height <= minY + height,
`${message}: bottom edge ${rect.y + rect.height} is outside ${minY + height}`,
);
}
function assertRectInsideRect(rect, container, message) {
assert.ok(rect.x >= container.x, `${message}: left edge ${rect.x} is outside ${container.x}`);
assert.ok(rect.y >= container.y, `${message}: top edge ${rect.y} is outside ${container.y}`);
assert.ok(
rect.x + rect.width <= container.x + container.width,
`${message}: right edge ${rect.x + rect.width} is outside ${container.x + container.width}`,
);
assert.ok(
rect.y + rect.height <= container.y + container.height,
`${message}: bottom edge ${rect.y + rect.height} is outside ${container.y + container.height}`,
);
}
function groupFrameRect(svg, index = 0) {
const attributes = svg.match(new RegExp(
`<rect\\b(?=[^>]*data-composition-frame-kind="group")(?=[^>]*data-composition-frame-id="group-${index}")([^>]*)/>`,
))?.[1];
assert.ok(attributes, `expected rendered group frame ${index}`);
return numericRect(attributes);
}
function laneFrameRect(svg, index = 0) {
const attributes = svg.match(new RegExp(
`<rect\\b(?=[^>]*data-composition-frame-kind="lane")(?=[^>]*data-composition-frame-id="lane-${index}")([^>]*)/>`,
))?.[1];
assert.ok(attributes, `expected rendered lane frame ${index}`);
return numericRect(attributes);
}
function asciiGroupLabelTextRect(svg, label) {
const escapedLabel = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const attributes = svg.match(new RegExp(`<text\\b([^>]*)>${escapedLabel}</text>`))?.[1];
assert.ok(attributes, `expected rendered group label ${label}`);
return {
x: Number(attribute(attributes, 'x')),
y: Number(attribute(attributes, 'y')) - 10,
width: Array.from(label).length * 5.6,
height: 14,
};
}
function rectsOverlap(left, right) {
return !(
left.x + left.width <= right.x
|| right.x + right.width <= left.x
|| left.y + left.height <= right.y
|| right.y + right.height <= left.y
);
}
function orthogonalSegmentIntersectsRect(start, end, rect) {
const left = rect.x;
const right = rect.x + rect.width;
const top = rect.y;
const bottom = rect.y + rect.height;
if (start[1] === end[1]) {
return start[1] >= top && start[1] <= bottom
&& Math.max(start[0], end[0]) >= left
&& Math.min(start[0], end[0]) <= right;
}
if (start[0] === end[0]) {
return start[0] >= left && start[0] <= right
&& Math.max(start[1], end[1]) >= top
&& Math.min(start[1], end[1]) <= bottom;
}
throw new Error(`expected an orthogonal route segment: ${JSON.stringify([start, end])}`);
}
function asciiLaneHeaderTextRect(label, { laneTop = 52, laneIndex = 0 } = {}) {
const prefix = String(laneIndex + 1).padStart(2, '0');
return {
x: 54,
y: laneTop + 12,
width: Array.from(`${prefix} / ${label}`).length * 6.2,
height: 14,
};
}
function compileSuccessfully(workflow, qualityProfile) {
const request = qualityProfile === undefined
? { workflow }
: { workflow, qualityProfile };
const result = compileWorkflow(request);
assert.equal(
result.ok,
true,
`expected workflow compilation to succeed:\n${JSON.stringify(result.diagnostics, null, 2)}`,
);
assert.equal(typeof result.svg, 'string');
assert.match(result.svg, /^\s*<svg\b/, 'compiler should return one canonical renderer SVG');
assert.ok(result.receipt);
assert.deepEqual(result.receipt.diagnostics, []);
return result;
}
function adjacentWorkflow({
fromCol = 1,
toCol = fromCol + 1,
label,
widths = [92, 92],
nodeLabels = ['A', 'B'],
viewBox,
frames = false,
output,
} = {}) {
const workflow = {
schema_version: 2,
diagram_type: 'workflow',
meta: {
title: `Adjacent ranks ${fromCol} to ${toCol}`,
output: output ?? 'adjacent-workflow.html',
legend: { mode: 'hidden' },
...(viewBox ? { viewBox } : {}),
},
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{
id: 'a', lane: 'main', col: fromCol, type: 'backend', label: nodeLabels[0], width: widths[0],
},
{
id: 'b', lane: 'main', col: toCol, type: 'backend', label: nodeLabels[1], width: widths[1],
},
],
edges: [{ id: 'ab', from: 'a', to: 'b', ...(label ? { label } : {}) }],
};
if (frames) {
workflow.phases = [{
id: 'phase', label: 'P', fromCol, toCol,
}];
workflow.groups = [{
id: 'group', label: 'G', lane: 'main', fromCol, toCol,
}];
}
return workflow;
}
function stackedGroupWorkflow({
schemaVersion = 1,
offsets = [0, 90, 180],
includeWorkerLane = false,
} = {}) {
return {
schema_version: schemaVersion,
diagram_type: 'workflow',
meta: {
title: 'Stacked cage',
output: 'stacked-cage.html',
legend: { mode: 'hidden' },
...(schemaVersion === 1 ? { viewBox: [720, 640] } : {}),
},
lanes: [
{ id: 'cage', label: 'One cage' },
...(includeWorkerLane ? [{ id: 'worker', label: 'Worker' }] : []),
],
groups: [{
id: 'group',
label: 'Cage',
lane: 'cage',
fromCol: 1,
toCol: 3,
variant: 'security',
}],
nodes: [
...offsets.map((yOffset, index) => ({
id: String.fromCharCode('a'.charCodeAt(0) + index),
lane: 'cage',
col: 2,
type: 'security',
label: `Stage ${String.fromCharCode('A'.charCodeAt(0) + index)}`,
yOffset,
})),
...(includeWorkerLane ? [{
id: 'worker', lane: 'worker', col: 2, type: 'backend', label: 'Worker',
}] : []),
],
edges: [],
};
}
function assertReadableAdjacentResult(result, { label, widths = [92, 92] } = {}) {
assert.equal(result.receipt.contract, 'readable-v2');
assert.deepEqual(result.receipt.viewBox, svgViewBox(result.svg).slice(2));
assert.ok(Array.isArray(result.receipt.requiredViewBox));
assert.equal(result.receipt.columns.length, 6);
assert.ok(result.receipt.columns.every(Number.isFinite));
for (let index = 1; index < result.receipt.columns.length; index += 1) {
assert.ok(
result.receipt.columns[index] > result.receipt.columns[index - 1],
`column ${index} must be strictly after column ${index - 1}`,
);
}
const source = nodeRect(result.svg, 'a');
const target = nodeRect(result.svg, 'b');
assert.equal(source.width, widths[0]);
assert.equal(target.width, widths[1]);
assert.ok(source.x + source.width <= target.x, 'same-lane nodes must not overlap');
const points = edgePoints(result.svg, 'ab');
assert.deepEqual(points.length, 2, `adjacent facing nodes should use a direct route: ${JSON.stringify(points)}`);
assert.equal(points[0][0], source.x + source.width, 'edge must leave the source right side');
assert.equal(points[1][0], target.x, 'edge must enter the target left side');
assert.equal(points[0][1], points[1][1], 'direct route must be horizontal');
const directClearance = points[1][0] - points[0][0];
assert.ok(directClearance >= 28, `direct clearance ${directClearance}px must be at least 28px`);
if (label) {
const mask = edgeLabelRect(result.svg, 'ab');
assert.ok(
directClearance + 1e-9 >= mask.width + 8,
`labeled direct clearance ${directClearance}px must fit ${mask.width}px mask plus 8px breathing room`,
);
assertRectInsideViewBox(mask, svgViewBox(result.svg), 'edge label mask');
}
}
test('fixed-v1 preserves baseline geometry and content through presentation changes', () => {
const workflow = readJson(path.join(__dirname, 'fixtures', 'v1-baseline', 'agent-tool-call.workflow.json'));
const result = compileSuccessfully(workflow);
assert.equal(result.receipt.contract, 'fixed-v1');
assert.equal(
sha256(JSON.stringify(result.receipt)),
'fa7fe055050cbd43adbb2c56fd5bf6e69b9ae0e66808c4eb6528cb4fb94d8cac',
);
});
test('fixed-v1 compiler preserves the exact 700x400 compatibility geometry', () => {
const workflow = readJson(path.join(
__dirname,
'fixtures',
'v1-workflow-700x400.workflow.json',
));
const result = compileSuccessfully(workflow);
assert.equal(result.receipt.contract, 'fixed-v1');
assert.deepEqual(result.receipt.viewBox, [700, 400]);
assert.deepEqual(svgViewBox(result.svg), [0, 0, 700, 400]);
assert.equal(
sha256(JSON.stringify(result.receipt)),
'95fc3f75b7067ac01c807ba53eae5cb05e122f10c3002560b7a91a4446ea4f6e',
'presentation changes must retain the pre-styling geometry receipt',
);
});
test('readable-v2 separates approval branches in the checked-in workflow example', () => {
const workflow = readJson(path.join(__dirname, '..', 'archify', 'examples', 'agent-tool-call.workflow.json'));
const result = compileSuccessfully(workflow);
assert.equal(result.receipt.contract, 'readable-v2');
// Showcase checks the complete routes for shared corridors and collisions.
// Keep these branches visually distinct without freezing automatic SVG bytes;
// the golden test separately verifies checked-in artifact freshness.
const denied = edgePoints(result.svg, 'approval-denied');
const approved = edgePoints(result.svg, 'approved-tool');
assert.notDeepEqual(denied[0], approved[0], 'approval outcomes need distinct exits');
assert.equal(result.receipt.edges.length, workflow.edges.length);
assert.equal(result.receipt.labels.find(({ edge }) => edge === 'approval-denied').label, 'denied');
});
test('fixed-v1 keeps valid phase and group spans independent of label measurement', () => {
const workflow = {
schema_version: 1,
diagram_type: 'workflow',
meta: {
title: 'Fixed v1 frame geometry', output: 'fixed-v1-frame.html', legend: { mode: 'hidden' },
},
lanes: [{ id: 'main', label: 'Main' }],
phases: [{ id: 'phase', label: 'P'.repeat(17), fromCol: 0, toCol: 0 }],
groups: [{
id: 'group', label: 'G'.repeat(30), lane: 'main', fromCol: 0, toCol: 0,
}],
nodes: [{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' }],
edges: [],
};
const result = compileSuccessfully(workflow);
assert.match(
result.svg,
/<path d="M 50 35 H 126"/,
'v1 phase hairlines retain the fixed span with the approved 8px end inset',
);
assert.match(
result.svg,
/data-composition-frame-kind="group"[^>]* x="38" y="90" width="100"/,
'v1 group spans must retain the legacy fixed 50px padding',
);
});
test('issue #250: fixed-v1 keeps rejecting the original vertical stack unchanged', () => {
const result = compileWorkflow({ workflow: stackedGroupWorkflow() });
assert.equal(result.ok, false);
assert.equal(result.receipt.contract, 'fixed-v1');
assert.match(result.error, /collides with the title or boundary/);
});
test('workflow lane.height remains outside the public schema', () => {
const workflow = adjacentWorkflow();
workflow.lanes[0].height = 104;
const result = compileWorkflow({ workflow });
assert.equal(result.ok, false);
assert.match(result.error, /lanes\/0/);
assert.deepEqual(result.diagnostics[0].supportedFixes, []);
});
test('issue #250: implicit readable-v2 measures a stacked lane independently', () => {
const workflow = stackedGroupWorkflow({
schemaVersion: 2,
offsets: [-90, 0, 90],
includeWorkerLane: true,
});
workflow.lanes.push({ id: 'audit', label: 'Audit' });
workflow.nodes.push({ id: 'audit', lane: 'audit', col: 2, type: 'external', label: 'Audit' });
const result = compileSuccessfully(workflow);
assert.equal(result.receipt.contract, 'readable-v2');
assert.deepEqual([0, 1, 2].map((index) => laneFrameRect(result.svg, index).height), [276, 104, 104]);
assert.deepEqual(result.receipt.viewBox, [768, 700]);
const group = groupFrameRect(result.svg);
for (const id of ['a', 'b', 'c']) {
const node = nodeRect(result.svg, id);
assertRectInsideRect(node, group, `stacked node ${id}`);
assertRectInsideViewBox(node, svgViewBox(result.svg), `stacked node ${id}`);
}
});
test('route presets remain compiler-owned during independent lane measurement', () => {
const workflow = stackedGroupWorkflow({
schemaVersion: 2,
offsets: [-90, 0, 90],
includeWorkerLane: true,
});
workflow.edges = [{
id: 'ab', from: 'a', to: 'b', route: 'straight', fromSide: 'bottom', toSide: 'top',
}];
const result = compileSuccessfully(workflow);
assert.deepEqual([0, 1].map((index) => laneFrameRect(result.svg, index).height), [276, 104]);
assert.deepEqual(result.receipt.edges[0].points.map(([, y]) => y), [143, 181]);
});
test('explicit viewBox retains shared-height readable-v2 geometry', () => {
const workflow = stackedGroupWorkflow({
schemaVersion: 2,
offsets: [-90, 0, 90],
includeWorkerLane: true,
});
workflow.lanes.push({ id: 'audit', label: 'Audit' });
workflow.nodes.push({ id: 'audit', lane: 'audit', col: 2, type: 'external', label: 'Audit' });
workflow.meta.viewBox = [768, 1032];
const result = compileSuccessfully(workflow);
assert.deepEqual([0, 1, 2].map((index) => laneFrameRect(result.svg, index).height), [276, 270, 270]);
const svgRoot = result.svg.match(/<svg\b[^>]*>/)?.[0];
assert.equal(attributeOrUndefined(svgRoot, 'data-reader-fit'), undefined);
});
test('absolute route pins retain shared-height readable-v2 geometry', () => {
const workflow = stackedGroupWorkflow({
schemaVersion: 2,
offsets: [-90, 0, 90],
includeWorkerLane: true,
});
workflow.lanes.push({ id: 'audit', label: 'Audit' });
workflow.nodes.push({ id: 'audit', lane: 'audit', col: 2, type: 'external', label: 'Audit' });
workflow.edges = [{
id: 'pinned',
from: 'worker',
to: 'audit',
fromSide: 'right',
toSide: 'right',
via: [[700, 498], [700, 788]],
}];
const result = compileSuccessfully(workflow);
assert.deepEqual([0, 1, 2].map((index) => laneFrameRect(result.svg, index).height), [276, 270, 270]);
});
test('an automatic readable-v2 vertical stack opts into width-first reader fitting', () => {
const result = compileSuccessfully(stackedGroupWorkflow({
schemaVersion: 2,
offsets: [-90, 0, 90],
}));
const svgRoot = result.svg.match(/<svg\b[^>]*>/)?.[0];
assert.ok(svgRoot, 'expected an SVG root');
assert.equal(attribute(svgRoot, 'data-reader-fit'), 'width-first');
});
test('a readable-v2 node without an authored width grows to fit its label', () => {
const workflow = adjacentWorkflow({ widths: [undefined, undefined], nodeLabels: ['Start', 'TOOL_RESULT 策略'] });
const before = JSON.stringify(workflow);
const result = compileSuccessfully(workflow);
const width = Number(result.svg.match(/data-node-id="b"[\s\S]*?<rect[^>]*width="([\d.]+)"/)[1]);
assert.equal(JSON.stringify(workflow), before, 'the authored document is not rewritten');
assert.equal(width, 104);
});
test('automatic widths are recomputed after editing the same workflow object', () => {
const document = adjacentWorkflow({ widths: [undefined, undefined], nodeLabels: ['Start', 'a'.repeat(29)] });
document.nodes[1].col = 5;
const expanded = compileSuccessfully(document);
assert.equal(expanded.receipt.nodes.find(({ id }) => id === 'b').width, 192);
document.nodes[1].label = 'A';
document.meta.viewBox = [768, 420];
const reused = compileSuccessfully(document);
const fresh = compileSuccessfully(clone(document));
assert.equal(reused.receipt.nodes.find(({ id }) => id === 'b').width, 92);
assert.equal(reused.svg, fresh.svg);
assert.deepEqual(reused.receipt, fresh.receipt);
});
test('switching an edited document to fixed-v1 does not reuse automatic widths', () => {
const document = adjacentWorkflow({ widths: [undefined, undefined], nodeLabels: ['Start', 'a'.repeat(29)] });
document.nodes[1].col = 5;
compileSuccessfully(document);
document.nodes[1].label = 'A';
document.schema_version = 1;
const reused = compileSuccessfully(document);
const fresh = compileSuccessfully(clone(document));
assert.equal(reused.receipt.nodes.find(({ id }) => id === 'b').width, 92);
assert.equal(reused.svg, fresh.svg);
});
test('authored canvases and standard workflows preserve bounded sublabel fonts', () => {
for (const qualityProfile of ['standard', 'showcase']) {
const document = adjacentWorkflow({ widths: [92, 92], viewBox: [10000, 420] });
document.nodes[0].sublabel = 'x';
const result = compileSuccessfully(document, qualityProfile);
assert.match(result.svg, /data-detail="context"[^>]*font-size="8"[^>]*>x<\/text>/);
}
const document = adjacentWorkflow({ widths: [132, 200] });
document.nodes[1].col = 5;
document.nodes[0].sublabel = 'chain / debate / synthesis 调度';
for (const col of [0, 2, 3, 4]) document.nodes.push({ id: `wide-${col}`, lane: 'main', col, type: 'backend', label: `Step ${col}`, width: 200 });
compileSuccessfully(document, 'standard');
});
test('readable-v2 sublabels must fit at the size that stays readable on the final canvas', () => {
const workflow = adjacentWorkflow({ widths: [132, 200] });
workflow.nodes[1].col = 5;
workflow.nodes[0].sublabel = 'chain / debate / synthesis 调度';
for (const col of [0, 2, 3, 4]) {
workflow.nodes.push({ id: `wide-${col}`, lane: 'main', col, type: 'backend', label: `Step ${col}`, width: 200 });
}
const result = compileWorkflow({ workflow, qualityProfile: 'showcase' });
assert.equal(result.ok, false, 'expected a readable-size failure on a canvas wider than the reader');
assert.match(JSON.stringify(result.diagnostics), /minimum that stays readable on this \d+px canvas/);
});
test('automatic showcase rejects a sublabel floor above the fixed row font budget', () => {
const workflow = adjacentWorkflow({ fromCol: 0, widths: [400, 400] });
workflow.nodes[0].sublabel = 'x';
workflow.nodes[1].col = 5;
for (const col of [2, 3, 4]) workflow.nodes.push({ id: `wide-${col}`, lane: 'main', col, type: 'backend', label: `Step ${col}`, width: 400 });
const result = compileWorkflow({ workflow, qualityProfile: 'showcase' });
assert.equal(result.ok, false);
assert.match(JSON.stringify(result.diagnostics), /above the supported 8px text row/);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/sublabel-readability');
assert.equal(diagnostic.subject.path, '/nodes/0/sublabel');
assert.ok(diagnostic.evidence.requiredFontPx > diagnostic.evidence.maximumSlotFontPx);
assert.equal(diagnostic.evidence.maximumSlotFontPx, 8);
assert.ok(diagnostic.supportedFixes.some(fix => /compact column spacing/.test(fix)));
compileSuccessfully(workflow, 'standard');
});
test('an automatic readable-v2 canvas too tall for the desktop page reads at page width', () => {
const workflow = adjacentWorkflow();
workflow.lanes = Array.from({ length: 6 }, (_, index) => ({ id: `lane-${index}`, label: `Lane ${index}` }));
workflow.nodes = workflow.lanes.map((lane, index) => ({ id: `n${index}`, lane: lane.id, col: 1, type: 'backend', label: `Step ${index}` }));
workflow.edges = workflow.nodes.slice(1).map((node, index) => ({ id: `e${index}`, from: workflow.nodes[index].id, to: node.id }));
const result = compileSuccessfully(workflow);
const svgRoot = result.svg.match(/<svg\b[^>]*>/)?.[0];
const [, , width, height] = attribute(svgRoot, 'viewBox').split(' ').map(Number);
assert.ok(width / height < 1.55, `${width}x${height} must be below the wide ratio`);
assert.equal(attribute(svgRoot, 'data-reader-fit'), 'width-first');
});
test('stack reader fitting stays off for authored canvases, fixed-v1, and workflows without a vertical stack', () => {
const authoredCanvas = stackedGroupWorkflow({ schemaVersion: 2, offsets: [-90, 0, 90] });
authoredCanvas.meta.viewBox = [768, 452];
const tallWithoutStack = adjacentWorkflow();
tallWithoutStack.nodes.forEach((node) => { node.height = 130; });
const cases = [
['authored readable-v2 canvas', authoredCanvas],
['fixed-v1 workflow', stackedGroupWorkflow({ offsets: [0] })],
['baseline readable-v2 lane', adjacentWorkflow()],
['tall readable-v2 lane without a vertical stack', tallWithoutStack],
];
for (const [description, workflow] of cases) {
const result = compileSuccessfully(workflow);
if (workflow === tallWithoutStack) assert.ok(laneFrameRect(result.svg, 0).height > 104);
const svgRoot = result.svg.match(/<svg\b[^>]*>/)?.[0];
assert.ok(svgRoot, `${description}: expected an SVG root`);
assert.equal(
attributeOrUndefined(svgRoot, 'data-reader-fit'),
undefined,
`${description}: must retain the established Viewer contract`,
);
}
});
test('independent lane measurement keeps a negative-offset member clear of its group label', () => {
const workflow = stackedGroupWorkflow({ schemaVersion: 2, offsets: [-90, 0, 90] });
workflow.groups[0].fromCol = 2;
workflow.groups[0].toCol = 2;
const result = compileSuccessfully(workflow);
assert.equal(
rectsOverlap(nodeRect(result.svg, 'a'), asciiGroupLabelTextRect(result.svg, 'Cage')),
false,
);
for (const id of ['a', 'b', 'c']) {
assertRectInsideRect(nodeRect(result.svg, id), groupFrameRect(result.svg), `stacked node ${id}`);
}
});
test('structural identity errors remain primary over derivative group containment', () => {
const workflow = stackedGroupWorkflow({ schemaVersion: 2, offsets: [-90, 0, 90] });
workflow.groups.push({
...workflow.groups[0],
label: 'Duplicate identity',
});
const result = compileWorkflow({ workflow });
assert.equal(result.ok, false);
assert.match(result.error, /Group ids must be unique/);
assert.equal(
result.diagnostics.some(({ code }) => code === 'workflow/group-containment'),
false,
);
});
test('fixed-v1 reports one causal column-capacity diagnostic for issue #126', () => {
const workflow = {
schema_version: 1,
diagram_type: 'workflow',
meta: {
title: 'Issue 126 causal diagnostic', output: 'issue-126-causal.html', legend: { mode: 'hidden' },
},
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 1, type: 'backend', label: 'A' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
],
edges: [{ id: 'ab', from: 'a', to: 'b', label: 'liga' }],
};
const result = compileWorkflow({ workflow, qualityProfile: 'showcase' });
assert.equal(result.ok, false);
assert.equal(result.diagnostics.length, 1, JSON.stringify(result.diagnostics, null, 2));
assert.deepEqual(result.receipt.diagnostics, result.diagnostics);
const [diagnostic] = result.diagnostics;
assert.equal(diagnostic.code, 'workflow/column-capacity');
assert.equal(diagnostic.subject.edge, 'ab');
assert.equal(diagnostic.subject.from, 'a');
assert.equal(diagnostic.subject.to, 'b');
assert.equal(diagnostic.subject.fromCol, 1);
assert.equal(diagnostic.subject.toCol, 2);
assert.deepEqual(diagnostic.evidence, {
centerDistancePx: 80,
nodeWidthsPx: [92, 92],
actualSignedClearancePx: -12,
requiredDirectClearancePx: 28,
});
assert.deepEqual(diagnostic.suppresses, [
'workflow/short-edge',
'clean-flow/endpoint-side-direction',
'workflow/label-node-overlap',
]);
assert.ok(diagnostic.supportedFixes.some((fix) => /schema_version 2/.test(fix)));
assert.ok(diagnostic.supportedFixes.some((fix) => /column 3/.test(fix)));
assert.ok(diagnostic.supportedFixes.some((fix) => /width/i.test(fix)));
assert.doesNotMatch(
diagnostic.supportedFixes.join('\n'),
/drop|remove|omit|unlabel|channel/i,
'a causal overlap diagnostic must not propose a label or routing non-fix',
);
});
test('fixed-v1 verifies the real coordinate migration before advertising it', () => {
const workflow = {
schema_version: 1,
diagram_type: 'workflow',
meta: {
title: 'Pinned issue 126 migration',
output: 'pinned-issue-126.html',
viewBox: [720, 400],
legend: { mode: 'hidden' },
},
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 1, type: 'backend', label: 'A' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
],
edges: [{
id: 'ab',
from: 'a',
to: 'b',
fromSide: 'top',
toSide: 'top',
via: [[220, 60], [300, 60]],
}],
};
const result = compileWorkflow({ workflow, qualityProfile: 'showcase' });
assert.equal(result.ok, false);
assert.equal(result.diagnostics[0].code, 'workflow/column-capacity');
assert.ok(
result.diagnostics[0].supportedFixes.includes('migrate this workflow to schema_version 2'),
JSON.stringify(result.diagnostics[0], null, 2),
);
});
test('readable-v2 supports every adjacent rank with and without a semantic label', () => {
for (const qualityProfile of ['standard', 'showcase']) {
for (let fromCol = 0; fromCol < 5; fromCol += 1) {
for (const label of [undefined, 'liga']) {
const result = compileSuccessfully(adjacentWorkflow({ fromCol, label }), qualityProfile);
assertReadableAdjacentResult(result, { label });
}
}
}
});
test('readable-v2 satisfies the complete adjacent-rank acceptance matrix', () => {
let cases = 0;
for (const qualityProfile of ['standard', 'showcase']) {
for (let fromCol = 0; fromCol < 5; fromCol += 1) {
for (const label of [undefined, 'liga']) {
for (const frames of [false, true]) {
for (const width of [900, 1080, 1400, 1600]) {
const result = compileSuccessfully(adjacentWorkflow({
fromCol,
label,
frames,
viewBox: [width, 420],
}), qualityProfile);
assert.deepEqual(result.receipt.viewBox, [width, 420]);
assertReadableAdjacentResult(result, { label });
if (frames) assert.match(result.svg, /data-composition-frame-kind="group"/);
cases += 1;
}
}
}
}
}
assert.equal(cases, 160);
});
test('readable-v2 phase and group frames derive from solved ranks without moving the core geometry', () => {
for (const qualityProfile of ['standard', 'showcase']) {
for (let fromCol = 0; fromCol < 5; fromCol += 1) {
const plain = compileSuccessfully(adjacentWorkflow({ fromCol, label: 'liga' }), qualityProfile);
const framed = compileSuccessfully(
adjacentWorkflow({ fromCol, label: 'liga', frames: true }),
qualityProfile,
);
assert.deepEqual(framed.receipt.columns, plain.receipt.columns);
assert.deepEqual(nodeRect(framed.svg, 'a'), nodeRect(plain.svg, 'a'));
assert.deepEqual(nodeRect(framed.svg, 'b'), nodeRect(plain.svg, 'b'));
assert.deepEqual(edgePoints(framed.svg, 'ab'), edgePoints(plain.svg, 'ab'));
assert.match(framed.svg, /data-composition-frame-kind="group"/);
assertReadableAdjacentResult(framed, { label: 'liga' });
}
}
});
test('readable-v2 treats the phase header mask as a routing obstacle', () => {
const document = {
schema_version: 2,
diagram_type: 'workflow',
meta: {
title: 'Phase route obstacle', output: 'phase-route-obstacle.html', legend: { mode: 'hidden' },
},
lanes: [{ id: 'top', label: 'Top' }, { id: 'bottom', label: 'Bottom' }],
nodes: [
{ id: 'a', lane: 'top', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'bottom', col: 4, type: 'backend', label: 'B' },
],
edges: [{
id: 'ab', from: 'a', to: 'b', fromSide: 'top', toSide: 'top',
}],
};
const withoutPhase = compileSuccessfully(clone(document), 'showcase');
assert.ok(withoutPhase.receipt.edges.find(({ id }) => id === 'ab'));
const withPhaseDocument = clone(document);
withPhaseDocument.phases = [{ id: 'p', label: 'Phase', fromCol: 0, toCol: 5 }];
const withPhase = compileSuccessfully(withPhaseDocument, 'showcase');
const columns = withPhase.receipt.columns;
const phaseMask = {
x: columns[0] - 46,
y: 27,
width: (columns[5] + 46) - (columns[0] - 46),
height: 16,
};
const points = withPhase.receipt.edges.find(({ id }) => id === 'ab').points;
for (let index = 0; index < points.length - 1; index += 1) {
assert.equal(
orthogonalSegmentIntersectsRect(points[index], points[index + 1], phaseMask),
false,
`edge ab segment ${index} must clear the phase mask: ${JSON.stringify(points)}`,
);
}
});
test('readable-v2 never routes through a single-rank group label', () => {
const groupLabel = 'Very long group label';
const document = {
schema_version: 2,
diagram_type: 'workflow',
meta: {
title: 'Group label route obstacle', output: 'group-label-obstacle.html', legend: { mode: 'hidden' },
},
lanes: [{ id: 'top', label: 'Top' }, { id: 'bottom', label: 'Bottom' }],
groups: [{ id: 'g', label: groupLabel, lane: 'top', fromCol: 2, toCol: 2 }],
nodes: [
{ id: 'a', lane: 'top', col: 2, type: 'backend', label: 'A' },
{ id: 'b', lane: 'bottom', col: 4, type: 'database', label: 'B' },
],
edges: [{
id: 'ab', from: 'a', to: 'b', fromSide: 'top', toSide: 'top',
}],
};
const first = compileWorkflow({ workflow: document, qualityProfile: 'showcase' });
const second = compileWorkflow({ workflow: clone(document), qualityProfile: 'showcase' });
assert.deepEqual(second, first, 'repeated compilation must be deterministic');
assert.equal(first.ok, false);
assert.equal(first.svg, undefined);
assert.equal(first.diagnostics.length, 1, JSON.stringify(first.diagnostics, null, 2));
const [diagnostic] = first.diagnostics;
assert.equal(diagnostic.code, 'workflow/explicit-pin-conflict');
assert.equal(diagnostic.subject.path, '/edges/0/fromSide');
assert.equal(
diagnostic.evidence.invariant,
'readable route feasibility with authored endpoint sides',
);
assert.deepEqual(diagnostic.evidence.conflictingPins, [{
edge: 'ab',
field: 'fromSide',
path: '/edges/0/fromSide',
value: 'top',
}]);
assert.ok(diagnostic.supportedFixes.length > 0);
assert.deepEqual(first.receipt.diagnostics, first.diagnostics);
const repaired = clone(document);
delete repaired.edges[0].fromSide;
const rendered = compileWorkflow({ workflow: repaired, qualityProfile: 'showcase' });
assert.equal(rendered.ok, true, JSON.stringify(rendered.diagnostics, null, 2));
const escapedLabel = groupLabel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const attributes = rendered.svg.match(new RegExp(
`<text\\b([^>]*)>${escapedLabel}</text>`,
))?.[1];
assert.ok(attributes, 'expected the rendered group label');
const groupLabelRect = {
x: Number(attribute(attributes, 'x')),
y: Number(attribute(attributes, 'y')) - 10,
width: Array.from(groupLabel).length * 5.6,
height: 14,
};
const points = rendered.receipt.edges.find(({ id }) => id === 'ab').points;
for (let index = 0; index < points.length - 1; index += 1) {
assert.equal(
orthogonalSegmentIntersectsRect(points[index], points[index + 1], groupLabelRect),
false,
`edge ab segment ${index} must clear the group label: ${JSON.stringify(points)}`,
);
}
});
test('readable-v2 shifts top-side routes beyond lane header text deterministically', () => {
const makeDocument = (topLaneLabel) => ({
schema_version: 2,
diagram_type: 'workflow',
meta: {
title: 'Lane header route obstacle', output: 'lane-header-obstacle.html', legend: { mode: 'hidden' },
},
lanes: [
{ id: 'top', label: topLaneLabel },
{ id: 'bottom', label: 'Bottom' },
],
nodes: [
{ id: 'a', lane: 'top', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'bottom', col: 4, type: 'database', label: 'B' },
],
edges: [{
id: 'ab', from: 'a', to: 'b', fromSide: 'top', toSide: 'top',
}],
});
const compiled = new Map();
for (const label of ['Responsibility owner', 'R']) {
const first = compileSuccessfully(makeDocument(label), 'showcase');
const second = compileSuccessfully(makeDocument(label), 'showcase');
assert.deepEqual(second, first, `${label}: repeated compilation must be deterministic`);
const points = first.receipt.edges.find(({ id }) => id === 'ab').points;
const headerRect = asciiLaneHeaderTextRect(label);
for (let index = 0; index < points.length - 1; index += 1) {
assert.equal(
orthogonalSegmentIntersectsRect(points[index], points[index + 1], headerRect),
false,
`${label}: edge ab segment ${index} must clear the top lane header: ${JSON.stringify(points)}`,
);
}
compiled.set(label, first);
}
assert.ok(
compiled.get('Responsibility owner').receipt.columns[0]
> compiled.get('R').receipt.columns[0],
'the wider lane header must move the col-0 top-side corridor farther right',
);
});
test('an authored historical workflow canvas retains its valid rank plan', () => {
const document = readJson(path.join(__dirname, 'fixtures/workflow-viewport/order-overflow.workflow.json'));
document.meta.viewBox = [860, 786];
const before = JSON.stringify(document);
const result = compileSuccessfully(document, 'showcase');
assert.deepEqual(result.receipt.viewBox, [860, 786]);
assert.deepEqual(result.receipt.requiredViewBox, [860, 786]);
assert.equal(JSON.stringify(document), before);
assert.doesNotMatch(result.svg.match(/<svg[^>]*>/)[0], /data-reader-fit=/);
});
test('explicit viewBox width is containment capacity and never stretches its historical readable-v2 geometry', () => {
for (const qualityProfile of ['standard', 'showcase']) {
for (let fromCol = 0; fromCol < 5; fromCol += 1) {
// Compare authored capacities against the same historical rank plan.
// Unpinned drafts may reserve larger optional routing corridors.
const intrinsic = compileSuccessfully(adjacentWorkflow({
fromCol,
label: 'liga',
viewBox: [1600, 420],
}), qualityProfile);
const expectedGeometry = {
columns: intrinsic.receipt.columns,
source: nodeRect(intrinsic.svg, 'a'),
target: nodeRect(intrinsic.svg, 'b'),
edge: edgePoints(intrinsic.svg, 'ab'),
};
for (const width of [900, 1080, 1400, 1600]) {
const result = compileSuccessfully(adjacentWorkflow({
fromCol,
label: 'liga',
viewBox: [width, 420],
}), qualityProfile);
assert.deepEqual(result.receipt.viewBox, [width, 420]);
assert.deepEqual(svgViewBox(result.svg), [0, 0, width, 420]);
assert.deepEqual(result.receipt.requiredViewBox, intrinsic.receipt.requiredViewBox);
assert.deepEqual(result.receipt.columns, expectedGeometry.columns);
assert.deepEqual(nodeRect(result.svg, 'a'), expectedGeometry.source);
assert.deepEqual(nodeRect(result.svg, 'b'), expectedGeometry.target);
assert.deepEqual(edgePoints(result.svg, 'ab'), expectedGeometry.edge);
assertReadableAdjacentResult(result, { label: 'liga' });
}
}
}
});
test('capacity-only viewBox failures preserve historical routes, labels, and requirement', () => {
const document = {
schema_version: 2,
diagram_type: 'workflow',
meta: { title: 'capacity', output: 'capacity.html', legend: { mode: 'hidden' } },
lanes: [{ id: 'top', label: 'Top' }, { id: 'bottom', label: 'Bottom' }],
nodes: [
{ id: 'n0', lane: 'top', col: 0, type: 'backend', label: 'N0' },
{ id: 'n1', lane: 'bottom', col: 1, type: 'backend', label: 'N1' },
{ id: 'n2', lane: 'top', col: 1, type: 'database', label: 'N2' },
{ id: 'n3', lane: 'bottom', col: 3, type: 'database', label: 'N3' },
],
edges: [
{ id: 'e0', from: 'n3', to: 'n0' },
{
id: 'e1',
from: 'n1',
to: 'n2',
label: 'ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ',
},
],
};
const referenceDocument = clone(document);
referenceDocument.meta.viewBox = [1600, 1000];
const intrinsic = compileSuccessfully(referenceDocument, 'showcase');
assert.deepEqual(intrinsic.receipt.requiredViewBox, [768, 404]);
const insufficientDocument = clone(document);
insufficientDocument.meta.viewBox = [700, 1000];
const insufficient = compileWorkflow({
workflow: insufficientDocument,
qualityProfile: 'showcase',
});
assert.equal(insufficient.ok, false);
assert.equal(insufficient.svg, undefined);
assert.equal(insufficient.diagnostics.length, 1, JSON.stringify(insufficient.diagnostics, null, 2));
const [capacity] = insufficient.diagnostics;
assert.equal(capacity.code, 'workflow/viewbox-capacity');
assert.deepEqual(capacity.evidence.actualViewBox, [700, 1000]);
assert.deepEqual(capacity.evidence.requiredViewBox, intrinsic.receipt.requiredViewBox);
const sufficientDocument = clone(document);
sufficientDocument.meta.viewBox = [intrinsic.receipt.requiredViewBox[0], 1000];
const sufficient = compileSuccessfully(sufficientDocument, 'showcase');
assert.deepEqual(sufficient.receipt.requiredViewBox, intrinsic.receipt.requiredViewBox);
assert.deepEqual(sufficient.receipt.edges, intrinsic.receipt.edges);
assert.deepEqual(sufficient.receipt.labels, intrinsic.receipt.labels);
});
test('explicit viewBox capacity names the rank and label constraints that require more width', () => {
const result = compileWorkflow({
workflow: adjacentWorkflow({ fromCol: 1, label: 'liga', viewBox: [700, 420] }),
qualityProfile: 'showcase',
});
assert.equal(result.ok, false);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/viewbox-capacity');
assert.ok(diagnostic, JSON.stringify(result.diagnostics, null, 2));
assert.ok(diagnostic.evidence.contributors.includes('rank 1→2 direct clearance'));
assert.ok(diagnostic.evidence.contributors.includes('edge ab label mask'));
});
test('explicit viewBox capacity names the rank and authored node widths that require more width', () => {
const result = compileWorkflow({
workflow: adjacentWorkflow({
fromCol: 1,
widths: [240, 240],
viewBox: [700, 420],
}),
qualityProfile: 'showcase',
});
assert.equal(result.ok, false);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/viewbox-capacity');
assert.ok(diagnostic, JSON.stringify(result.diagnostics, null, 2));
const contributors = diagnostic.evidence.contributors;
assert.ok(
contributors.some((contributor) => /rank 1→2/i.test(contributor) && /clearance/i.test(contributor)),
`contributors must name the rank 1→2 width constraint: ${JSON.stringify(contributors)}`,
);
for (const nodeId of ['a', 'b']) {
assert.ok(
contributors.some((contributor) => (
new RegExp(`node ${nodeId}\\b`, 'i').test(contributor) && /width/i.test(contributor)
)),
`contributors must name node ${nodeId}'s authored width: ${JSON.stringify(contributors)}`,
);
}
});
test('explicit viewBox height capacity names the authored tall node without naming a hidden legend', () => {
const result = compileWorkflow({
workflow: {
schema_version: 2,
diagram_type: 'workflow',
meta: {
title: 'Tall node height capacity',
output: 'tall-node-capacity.html',
legend: { mode: 'hidden' },
viewBox: [1200, 280],
},
lanes: [{ id: 'main', label: 'M' }],
nodes: [{
id: 'tall', lane: 'main', col: 0, type: 'backend', label: 'Tall', height: 160,
}],
edges: [],
},
qualityProfile: 'showcase',
});
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.equal(result.diagnostics.length, 1, JSON.stringify(result.diagnostics, null, 2));
const [diagnostic] = result.diagnostics;
assert.equal(diagnostic.code, 'workflow/viewbox-capacity');
assert.deepEqual(diagnostic.evidence.actualViewBox, [1200, 280]);
assert.equal(diagnostic.evidence.requiredViewBox[1], 374);
const contributors = diagnostic.evidence.contributors;
assert.ok(
contributors.some((contributor) => (
/node tall\b/i.test(contributor)
&& /height/i.test(contributor)
&& /160px/i.test(contributor)
)),
`contributors must name tall's authored 160px height: ${JSON.stringify(contributors)}`,
);
assert.equal(
contributors.some((contributor) => /legend/i.test(contributor)),
false,
`a hidden legend must not be named as a height contributor: ${JSON.stringify(contributors)}`,
);
});
test('readable-v2 measures asymmetric custom widths and CJK edge labels', () => {
const cases = [
{ widths: [32, 92], label: '同步', nodeLabels: ['甲', '乙'] },
{ widths: [102, 124], label: '資料 ready', nodeLabels: ['入口', '出口'] },
{ widths: [132, 160], label: '审批通过', nodeLabels: ['请求', '执行'] },
{ widths: [92, 240], label: '结果 ✅ 回传', nodeLabels: ['工具', '外部服务'] },
];
for (const current of cases) {
const result = compileSuccessfully(adjacentWorkflow({
fromCol: 1,
label: current.label,
widths: current.widths,
nodeLabels: current.nodeLabels,
viewBox: [1600, 420],
}), 'showcase');
assertReadableAdjacentResult(result, current);
}
});
test('readable-v2 compares long-label gutter growth with a legal automatic channel', () => {
const automaticDocument = adjacentWorkflow({
fromCol: 3,
label: 'L'.repeat(80),
});
const automatic = compileSuccessfully(automaticDocument, 'showcase');
const forcedStraightDocument = clone(automaticDocument);
forcedStraightDocument.edges[0].route = 'straight';
const forcedStraight = compileSuccessfully(forcedStraightDocument, 'showcase');
assert.ok(edgePoints(automatic.svg, 'ab').length > 2, 'the compact plan must use a legal channel');
assert.ok(
automatic.receipt.requiredViewBox[0] < forcedStraight.receipt.requiredViewBox[0],
'the selected channel must require less canvas than forcing the direct gutter',
);
assertRectInsideViewBox(
edgeLabelRect(automatic.svg, 'ab'),
svgViewBox(automatic.svg),
'long automatic edge label',
);
const leftRankDocument = adjacentWorkflow({ fromCol: 0, label: 'X'.repeat(100) });
const leftRank = compileSuccessfully(leftRankDocument, 'showcase');
assertRectInsideViewBox(
edgeLabelRect(leftRank.svg, 'ab'),
svgViewBox(leftRank.svg),
'left-rank long automatic edge label',
);
});
test('readable-v2 property matrix satisfies every adjacent rank across supported representative widths', () => {
const widths = [32, 92, 102, 124, 132, 160, 240];
for (let fromCol = 0; fromCol < 5; fromCol += 1) {
for (const sourceWidth of widths) {
for (const targetWidth of widths) {
const result = compileSuccessfully(adjacentWorkflow({
fromCol,
label: '同步 ✅',
widths: [sourceWidth, targetWidth],
}), 'showcase');
assertReadableAdjacentResult(result, {
label: '同步 ✅',
widths: [sourceWidth, targetWidth],
});
}
}
}
});
test('readable-v2 expands rank spans for measured phase and group label capacity', () => {
const workflow = adjacentWorkflow({ fromCol: 0, frames: true });
workflow.phases[0].label = 'P'.repeat(50);
workflow.groups[0].label = 'G'.repeat(50);
const result = compileSuccessfully(workflow, 'showcase');
assert.ok(result.receipt.columns[1] - result.receipt.columns[0] > 120);
assertReadableAdjacentResult(result);
});
test('readable-v2 contains a long single-rank group label in its frame and intrinsic canvas', () => {
const workflow = {
schema_version: 2,
diagram_type: 'workflow',
meta: {
title: 'Single-rank group capacity', output: 'single-rank-group.html', legend: { mode: 'hidden' },
},
lanes: [{ id: 'main', label: 'Main' }],
groups: [{
id: 'long-group',
label: 'X'.repeat(120),
lane: 'main',
fromCol: 5,
toCol: 5,
}],
nodes: [
{ id: 'outside', lane: 'main', col: 2, type: 'database', label: 'Outside' },
{ id: 'node', lane: 'main', col: 5, type: 'backend', label: 'Node' },
],
edges: [],
};
const result = compileSuccessfully(workflow, 'showcase');
assert.ok(result.receipt.requiredViewBox[0] > 768);
const groupAttributes = result.svg.match(
/<rect\b(?=[^>]*data-composition-frame-id="group-0")[^>]*\b(x="[^"]+"[^>]*)\/>/,
)?.[1];
assert.ok(groupAttributes);
const group = numericRect(groupAttributes);
assert.ok(group.width >= 120 * 5.6 + 20, `group width ${group.width} must contain its label`);
const outside = nodeRect(result.svg, 'outside');
assert.ok(group.x >= outside.x + outside.width, 'single-rank group must not cover an unrelated rank');
const labelBaseline = Number(result.svg.match(/<text\b[^>]*\by="([^"]+)"[^>]*>X{120}<\/text>/)?.[1]);
assert.ok(labelBaseline <= nodeRect(result.svg, 'node').y - 4, 'group label must remain above its node');
});
test('readable-v2 group frames contain custom-width member rectangles on every side', () => {
const workflow = {
schema_version: 2,
diagram_type: 'workflow',
meta: {
title: 'Wide group member', output: 'wide-group-member.html', legend: { mode: 'hidden' },
},
lanes: [{ id: 'main', label: 'Main' }],
groups: [{ id: 'group', label: 'G', lane: 'main', fromCol: 2, toCol: 2 }],
nodes: [{
id: 'wide', lane: 'main', col: 2, type: 'backend', label: 'Wide', width: 240,
}],
edges: [],
};
const result = compileSuccessfully(workflow, 'showcase');
assertRectInsideRect(
nodeRect(result.svg, 'wide'),
groupFrameRect(result.svg),
'custom-width group member',
);
});
test('readable-v2 group frames contain tagged and tall members away from the label rail', () => {
const cases = [
['tagged member', { tag: 'TAG' }],
['120px-tall member', { height: 120 }],
];
for (const [description, authoredGeometry] of cases) {
const workflow = {
schema_version: 2,
diagram_type: 'workflow',
meta: { title: description, output: 'group-member.html', legend: { mode: 'hidden' } },
lanes: [{ id: 'main', label: 'Main' }],
groups: [{ id: 'group', label: 'G', lane: 'main', fromCol: 0, toCol: 1 }],
nodes: [{
id: 'member',
lane: 'main',
col: 1,
type: 'backend',
label: 'Member',
...authoredGeometry,
}],
edges: [],
};
const result = compileSuccessfully(workflow, 'showcase');
const member = nodeRect(result.svg, 'member');
const groupLabel = asciiGroupLabelTextRect(result.svg, 'G');
assert.ok(
member.x >= groupLabel.x + groupLabel.width,
`${description}: fixture must keep the member horizontally clear of its group label`,
);
assertRectInsideRect(member, groupFrameRect(result.svg), description);
}
});
test('readable-v2 keeps a first-rank group label mask clear of its lane header mask', () => {
const workflow = {
schema_version: 2,
diagram_type: 'workflow',
meta: {
title: 'First-rank group labels', output: 'first-rank-labels.html', legend: { mode: 'hidden' },
},
lanes: [{ id: 'main', label: 'Main' }],
groups: [{ id: 'group', label: 'G', lane: 'main', fromCol: 0, toCol: 0 }],
nodes: [{ id: 'member', lane: 'main', col: 0, type: 'backend', label: 'Member' }],
edges: [],
};
const result = compileSuccessfully(workflow, 'showcase');
const laneHeader = asciiLaneHeaderTextRect('Main');
const groupLabel = asciiGroupLabelTextRect(result.svg, 'G');
assert.equal(
rectsOverlap(laneHeader, groupLabel),
false,
`lane header ${JSON.stringify(laneHeader)} must not overlap group label ${JSON.stringify(groupLabel)}`,
);
});
test('readable-v2 measures multi-row legends into intrinsic and explicit viewBox capacity', () => {
const workflow = adjacentWorkflow({ fromCol: 0 });
workflow.meta.legend = {
mode: 'all',
entries: Object.fromEntries([
'frontend', 'backend', 'security', 'messagebus', 'database', 'cloud', 'external',
].map((kind) => [kind, { label: `${kind} contract evidence` }])),
};
const hiddenDocument = clone(workflow);
hiddenDocument.meta.legend = { mode: 'hidden' };
const hidden = compileSuccessfully(hiddenDocument, 'showcase');
const intrinsic = compileSuccessfully(workflow, 'showcase');
assert.ok(intrinsic.receipt.requiredViewBox[1] > hidden.receipt.requiredViewBox[1]);
const tooShortDocument = clone(workflow);
tooShortDocument.meta.viewBox = [
intrinsic.receipt.requiredViewBox[0],
hidden.receipt.requiredViewBox[1],
];
const tooShort = compileWorkflow({ workflow: tooShortDocument, qualityProfile: 'showcase' });
assert.equal(tooShort.ok, false);
assert.ok(tooShort.diagnostics.some(({ code }) => code === 'workflow/viewbox-capacity'));
const sufficientDocument = clone(workflow);
sufficientDocument.meta.viewBox = [...intrinsic.receipt.requiredViewBox];
const sufficient = compileSuccessfully(sufficientDocument, 'showcase');
assert.deepEqual(sufficient.receipt.viewBox, intrinsic.receipt.requiredViewBox);
const referenceDocument = clone(workflow);
referenceDocument.meta.viewBox = [1600, 1000];
const reference = compileSuccessfully(referenceDocument, 'showcase');
assert.deepEqual(reference.receipt.requiredViewBox, [768, 302]);
const expectedGeometry = {
requiredViewBox: reference.receipt.requiredViewBox,
columns: reference.receipt.columns,
nodes: reference.receipt.nodes,
edges: reference.receipt.edges,
labels: reference.receipt.labels,
legend: legendGeometry(reference.svg),
};
for (const width of [900, 1400]) {
const explicitDocument = clone(workflow);
explicitDocument.meta.viewBox = [width, 1000];
const explicit = compileSuccessfully(explicitDocument, 'showcase');
assert.deepEqual(explicit.receipt.requiredViewBox, expectedGeometry.requiredViewBox);
assert.deepEqual(explicit.receipt.columns, expectedGeometry.columns);
assert.deepEqual(explicit.receipt.nodes, expectedGeometry.nodes);
assert.deepEqual(explicit.receipt.edges, expectedGeometry.edges);
assert.deepEqual(explicit.receipt.labels, expectedGeometry.labels);
assert.deepEqual(legendGeometry(explicit.svg), expectedGeometry.legend);
}
});
test('a wide node in an unrelated lane does not expand the adjacent-rank gap', () => {
const baselineDocument = adjacentWorkflow({
fromCol: 1,
label: 'liga',
viewBox: [1600, 520],
});
baselineDocument.lanes.push({ id: 'other', label: 'Other' });
const baseline = compileSuccessfully(baselineDocument, 'showcase');
const withUnrelatedWideNode = clone(baselineDocument);
withUnrelatedWideNode.nodes.push({
id: 'wide', lane: 'other', col: 1, type: 'database', label: 'Wide', width: 240,
});
const widened = compileSuccessfully(withUnrelatedWideNode, 'showcase');
assert.equal(
widened.receipt.columns[2] - widened.receipt.columns[1],
baseline.receipt.columns[2] - baseline.receipt.columns[1],
);
});
test('explicit labelAt participates in readable-v2 viewBox containment', () => {
const workflow = adjacentWorkflow({
fromCol: 0,
label: 'outside',
viewBox: [900, 420],
});
workflow.nodes[1].col = 5;
workflow.edges[0].labelAt = [563, 539];
const result = compileWorkflow({ workflow, qualityProfile: 'showcase' });
assert.equal(result.ok, false);
assert.equal(result.diagnostics.length, 1, JSON.stringify(result.diagnostics, null, 2));
const [diagnostic] = result.diagnostics;
assert.equal(diagnostic.code, 'workflow/viewbox-capacity');
assert.deepEqual(diagnostic.evidence.actualViewBox, [900, 420]);
assert.ok(diagnostic.evidence.requiredViewBox[1] > 420);
assert.ok(
diagnostic.evidence.contributors.some((contributor) => /edge ab label/i.test(contributor)),
JSON.stringify(diagnostic.evidence.contributors),
);
assert.doesNotMatch(diagnostic.supportedFixes.join('\n'), /drop|remove (?:the )?label|unlabel/i);
});
test('sanitized downstream fixtures cover labels, explicit routes, custom widths, and explicit viewBoxes', () => {
const fixtureRoot = path.join(__dirname, 'fixtures', 'issue-126');
const labels = compileSuccessfully(readJson(path.join(fixtureRoot, 'labels.workflow.json')), 'showcase');
assertRectInsideViewBox(
edgeLabelRect(labels.svg, 'request-result'),
svgViewBox(labels.svg),
'sanitized semantic label',
);
const explicitRoute = compileSuccessfully(
readJson(path.join(fixtureRoot, 'explicit-route.workflow.json')),
'showcase',
);
assert.ok(
edgePoints(explicitRoute.svg, 'producer-consumer').some(([x]) => x === 720),
'the authored channelX pin must remain exact',
);
const customWidths = compileSuccessfully(
readJson(path.join(fixtureRoot, 'custom-widths.workflow.json')),
'showcase',
);
assert.equal(nodeRect(customWidths.svg, 'compact').width, 32);
assert.equal(nodeRect(customWidths.svg, 'wide').width, 240);
const explicitViewBox = compileSuccessfully(
readJson(path.join(fixtureRoot, 'explicit-viewbox.workflow.json')),
'showcase',
);
assert.deepEqual(explicitViewBox.receipt.viewBox, [1600, 520]);
});
test('readable-v2 SVG and receipt bytes are deterministic across repeated and reordered input', () => {
const workflow = {
schema_version: 2,
diagram_type: 'workflow',
meta: {
title: 'Deterministic workflow', output: 'deterministic-workflow.html', legend: { mode: 'hidden' },
},
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'frontend', label: 'A' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
{ id: 'c', lane: 'main', col: 4, type: 'database', label: 'C' },
],
edges: [
{ id: 'ab', from: 'a', to: 'b', label: 'one' },
{ id: 'bc', from: 'b', to: 'c', label: 'two' },
],
};
const first = compileSuccessfully(clone(workflow), 'showcase');
for (let iteration = 0; iteration < 3; iteration += 1) {
const repeated = compileSuccessfully(clone(workflow), 'showcase');
assert.equal(repeated.svg, first.svg);
assert.equal(JSON.stringify(repeated.receipt), JSON.stringify(first.receipt));
}
const reordered = clone(workflow);
reordered.nodes.reverse();
reordered.edges.reverse();
const reorderedResult = compileSuccessfully(reordered, 'showcase');
assert.equal(reorderedResult.svg, first.svg);
assert.equal(JSON.stringify(reorderedResult.receipt), JSON.stringify(first.receipt));
});
test('CLI validate workflow --layout-json prints the stable compiler receipt', () => {
const input = path.join(tmp, 'layout-json.workflow.json');
fs.writeFileSync(input, JSON.stringify(adjacentWorkflow({
fromCol: 3,
label: 'liga',
viewBox: [1080, 420],
output: 'layout-json.html',
})));
const result = spawnSync(process.execPath, [
cli,
'validate',
'workflow',
input,
'--layout-json',
'--quality',
'standard',
], { encoding: 'utf8' });
assert.equal(result.status, 0, result.stderr);
const receipt = JSON.parse(result.stdout);
assert.equal(receipt.contract, 'readable-v2');
assert.deepEqual(receipt.viewBox, [1080, 420]);
assert.ok(Array.isArray(receipt.requiredViewBox));
assert.equal(receipt.columns.length, 6);
assert.deepEqual(receipt.diagnostics, []);
});
test('CLI validate workflow --layout-json returns only the causal compiler failure receipt', () => {
const input = path.join(tmp, 'layout-json-failure.workflow.json');
fs.writeFileSync(input, JSON.stringify({
schema_version: 1,
diagram_type: 'workflow',
meta: {
title: 'Issue 126 failure receipt',
output: 'layout-json-failure.html',
legend: { mode: 'hidden' },
},
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 1, type: 'backend', label: 'A' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
],
edges: [{ id: 'ab', from: 'a', to: 'b' }],
}));
const result = spawnSync(process.execPath, [
cli,
'validate',
'workflow',
input,
'--layout-json',
'--json',
], { encoding: 'utf8' });
assert.equal(result.status, 1);
assert.equal(result.stderr, '');
const receipt = JSON.parse(result.stdout);
assert.equal(receipt.contract, 'fixed-v1');
assert.equal(receipt.diagnostics.length, 1, JSON.stringify(receipt.diagnostics, null, 2));
assert.equal(receipt.diagnostics[0].code, 'workflow/column-capacity');
});
test('a dense automatic first draft routes between columns without crossings', () => {
// A generated first draft: five lanes, 150px nodes and no authored routes.
const workflow = readJson(path.join(__dirname, 'fixtures', 'workflow-dense-automatic.json'));
const result = compileWorkflow({ workflow, qualityProfile: 'showcase' });
assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
});
process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));