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 { compileWorkflow } from '../archify/renderers/workflow/workflow-compiler.mjs';
import { spawnSync } from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
function clone(value) {
return JSON.parse(JSON.stringify(value));
}
function workflow({ lanes, nodes, edges }) {
return {
schema_version: 2,
diagram_type: 'workflow',
meta: {
title: 'Workflow compiler hard-contract fixture',
output: 'workflow-hard-contract.html',
legend: { mode: 'hidden' },
},
lanes,
nodes,
edges,
};
}
function oneLaneWorkflow(edges) {
return workflow({
lanes: [{ id: 'main', label: 'M' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
],
edges,
});
}
function nestedOutsideRightCorridorWorkflow() {
return workflow({
lanes: [0, 1, 2, 3].map((index) => ({ id: `l${index}`, label: `Lane ${index}` })),
nodes: [
{ id: 'outer-from', lane: 'l0', col: 0, type: 'backend', label: 'Outer from' },
{ id: 'inner-from', lane: 'l1', col: 0, type: 'backend', label: 'Inner from' },
{ id: 'inner-to', lane: 'l2', col: 2, type: 'database', label: 'Inner to' },
{ id: 'outer-to', lane: 'l3', col: 2, type: 'database', label: 'Outer to' },
],
edges: [
{
id: 'outer',
from: 'outer-from',
to: 'outer-to',
route: 'outside-right',
channelX: 800,
fromSide: 'right',
toSide: 'right',
},
{
id: 'inner',
from: 'inner-from',
to: 'inner-to',
route: 'outside-right',
channelX: 800,
fromSide: 'right',
toSide: 'right',
},
],
});
}
function crossingAtForwardCollinearViaWorkflow({ pinHorizontal = false } = {}) {
return workflow({
lanes: [
{ id: 'top', label: 'Top' },
{ id: 'middle', label: 'Middle' },
{ id: 'bottom', label: 'Bottom' },
],
nodes: [
{ id: 'left', lane: 'middle', col: 0, type: 'backend', label: 'Left' },
{ id: 'right', lane: 'middle', col: 4, type: 'backend', label: 'Right' },
{ id: 'above', lane: 'top', col: 2, type: 'backend', label: 'Above' },
{ id: 'below', lane: 'bottom', col: 2, type: 'backend', label: 'Below' },
],
edges: [
{
id: pinHorizontal ? 'a-pinned' : 'a-auto',
from: 'left',
to: 'right',
...(pinHorizontal ? { via: [[334, 243]] } : {}),
},
{
id: 'z-pinned',
from: 'above',
to: 'below',
via: [[334, 243]],
},
],
});
}
function oneLaneAnchors() {
const result = compileWorkflow({ workflow: oneLaneWorkflow([]), qualityProfile: 'standard' });
assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
const source = result.receipt.nodes.find(({ id }) => id === 'a');
const target = result.receipt.nodes.find(({ id }) => id === 'b');
assert.ok(source && target);
return {
start: [source.x + source.width, source.y + source.height / 2],
end: [target.x, target.y + target.height / 2],
};
}
function assertExplicitPinConflict(result, context) {
assert.equal(result.ok, false, `${context} must not produce an SVG`);
assert.equal(result.svg, undefined);
assert.ok(Array.isArray(result.diagnostics) && result.diagnostics.length > 0);
assert.ok(
result.diagnostics.some(({ code }) => code === 'workflow/explicit-pin-conflict'),
`${context} must report workflow/explicit-pin-conflict:\n${JSON.stringify(result.diagnostics, null, 2)}`,
);
assert.deepEqual(result.receipt, { contract: result.receipt.contract, diagnostics: result.diagnostics });
}
function assertSupportedFixesNameChangedEdge(diagnostic, edgeIds) {
assert.ok(diagnostic.supportedFixes.length > 0, JSON.stringify(diagnostic, null, 2));
for (const fix of diagnostic.supportedFixes) {
assert.ok(
edgeIds.some((edgeId) => fix.includes(`edge "${edgeId}"`)),
`supported fix must name its changed edge (${edgeIds.join(', ')}): ${fix}`,
);
}
}
function assertOrthogonal(points) {
for (let index = 0; index < points.length - 1; index += 1) {
const [x1, y1] = points[index];
const [x2, y2] = points[index + 1];
assert.ok(x1 === x2 || y1 === y2, `segment ${index} must be orthogonal`);
assert.notDeepEqual(points[index], points[index + 1], `segment ${index} must be non-zero`);
}
}
function routeContainsChannel(points, field, value) {
return points.slice(0, -1).some((start, index) => {
const end = points[index + 1];
if (field === 'channelX') {
return start[0] === value && end[0] === value && start[1] !== end[1];
}
return start[1] === value && end[1] === value && start[0] !== end[0];
});
}
function segmentMeetsRect(start, end, rect, clearance = 2) {
const left = rect.x - clearance;
const right = rect.x + rect.width + clearance;
const top = rect.y - clearance;
const bottom = rect.y + rect.height + clearance;
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;
}
return true;
}
test('readable-v2 auto routing selects a feasible corridor around a same-lane obstacle', () => {
const document = workflow({
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' },
{ id: 'obstacle', lane: 'main', col: 2, type: 'database', label: 'Obstacle' },
{ id: 'b', lane: 'main', col: 5, type: 'backend', label: 'B' },
],
edges: [{ id: 'ab', from: 'a', to: 'b' }],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(
result.ok,
true,
`a feasible automatic corridor must compile:\n${JSON.stringify(result.diagnostics, null, 2)}`,
);
const points = result.receipt.edges.find(({ id }) => id === 'ab')?.points;
const obstacle = result.receipt.nodes.find(({ id }) => id === 'obstacle');
assert.ok(points && obstacle);
assert.ok(points.length >= 3, 'the route must bend around the intervening node');
assertOrthogonal(points);
for (let index = 0; index < points.length - 1; index += 1) {
assert.equal(
segmentMeetsRect(points[index], points[index + 1], obstacle),
false,
`segment ${index} must clear the unrelated obstacle`,
);
}
});
test('readable-v2 evaluates automatic endpoint sides against the complete labeled route', () => {
const document = workflow({
lanes: [{ id: 'source', label: 'Source' }, { id: 'target', label: 'Target' }],
nodes: [
{ id: 'a', lane: 'source', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'target', col: 1, type: 'backend', label: 'B' },
],
edges: [{ id: 'ab', from: 'a', to: 'b', label: 'L'.repeat(50) }],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
assert.deepEqual(result.receipt.viewBox, [768, 404]);
assert.deepEqual(result.receipt.edges[0].points, [
[94, 145], [94, 166], [214, 166], [214, 217],
]);
});
test('readable-v2 retries automatic endpoint sides against already planned routes', () => {
const document = workflow({
lanes: [0, 1, 2].map((index) => ({ id: `l${index}`, label: `Lane ${index}` })),
nodes: [
{ id: 'a', lane: 'l0', col: 2, type: 'backend', label: 'A' },
{ id: 'b', lane: 'l0', col: 3, type: 'backend', label: 'B', yOffset: -1 },
{ id: 'c', lane: 'l2', col: 4, type: 'backend', label: 'C' },
],
edges: [
{ id: 'e0', from: 'a', to: 'b', label: 'L'.repeat(17) },
{ id: 'e1', from: 'a', to: 'c' },
],
});
const first = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
const second = compileWorkflow({ workflow: clone(document), qualityProfile: 'standard' });
assert.equal(first.ok, true, JSON.stringify(first.diagnostics, null, 2));
assert.equal(second.ok, true, JSON.stringify(second.diagnostics, null, 2));
assert.equal(second.svg, first.svg);
assert.equal(JSON.stringify(second.receipt), JSON.stringify(first.receipt));
assertOrthogonal(first.receipt.edges.find(({ id }) => id === 'e1').points);
});
test('readable-v2 expands an outside corridor for deterministic labeled fan-out', () => {
const document = workflow({
lanes: Array.from({ length: 5 }, (_, index) => ({
id: `l${index}`,
label: `Lane ${index}`,
})),
nodes: [
{ id: 'hub', lane: 'l0', col: 0, type: 'backend', label: 'Hub', width: 64 },
{ id: 't0', lane: 'l1', col: 2, type: 'external', label: 'T0', width: 160 },
{ id: 't1', lane: 'l2', col: 4, type: 'database', label: 'T1', width: 160 },
{ id: 't2', lane: 'l3', col: 3, type: 'external', label: 'T2', width: 64 },
{ id: 't3', lane: 'l4', col: 4, type: 'database', label: 'T3', width: 120 },
],
edges: [
{ id: 'e0', from: 'hub', to: 't0', label: 'A'.repeat(80) },
{ id: 'e1', from: 'hub', to: 't1', label: 'B'.repeat(80) },
{ id: 'e2', from: 'hub', to: 't2', label: 'C'.repeat(12) },
{ id: 'e3', from: 'hub', to: 't3', label: 'D'.repeat(24) },
],
});
const first = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
const second = compileWorkflow({ workflow: clone(document), qualityProfile: 'standard' });
assert.equal(first.ok, true, JSON.stringify(first.diagnostics, null, 2));
assert.deepEqual(second, first);
const route = first.receipt.edges.find(({ id }) => id === 'e3')?.points;
assert.ok(route);
assertOrthogonal(route);
assert.ok(
Math.max(...route.map(([x]) => x)) > 764,
`the final fan-out edge must escape the occupied route/label region: ${JSON.stringify(route)}`,
);
});
test('readable-v2 expands an outside corridor without moving the lane geometry', () => {
const document = workflow({
lanes: Array.from({ length: 5 }, (_, index) => ({
id: `l${index}`,
label: `Lane ${index}`,
})),
nodes: [
{ id: 'hub', lane: 'l0', col: 1, type: 'backend', label: 'Hub', width: 92 },
{ id: 't0', lane: 'l1', col: 2, type: 'external', label: 'T0', width: 120 },
{ id: 't1', lane: 'l2', col: 1, type: 'database', label: 'T1', width: 160 },
{ id: 't2', lane: 'l3', col: 1, type: 'external', label: 'T2', width: 120 },
{ id: 't3', lane: 'l4', col: 2, type: 'database', label: 'T3', width: 120 },
],
edges: [
{ id: 'e0', from: 'hub', to: 't0', label: 'A'.repeat(120) },
{ id: 'e1', from: 'hub', to: 't1', label: 'B'.repeat(48) },
{ id: 'e2', from: 'hub', to: 't2', label: 'C'.repeat(24) },
{ id: 'e3', from: 'hub', to: 't3', label: 'D'.repeat(84) },
],
});
const first = compileWorkflow({ workflow: document, qualityProfile: 'showcase' });
const second = compileWorkflow({ workflow: clone(document), qualityProfile: 'showcase' });
assert.equal(first.ok, true, JSON.stringify(first.diagnostics, null, 2));
assert.deepEqual(second, first);
const route = first.receipt.edges.find(({ id }) => id === 'e3')?.points;
assert.ok(route);
assertOrthogonal(route);
assert.ok(Math.max(...route.map(([x]) => x)) > 1200, JSON.stringify(route));
assert.ok(first.receipt.viewBox[0] < 1400, JSON.stringify(first.receipt.viewBox));
});
test('readable-v2 may expand an unlabeled edge around already placed labels', () => {
const document = workflow({
lanes: Array.from({ length: 4 }, (_, index) => ({
id: `l${index}`,
label: `Lane ${index}`,
})),
nodes: [
{ id: 'hub', lane: 'l0', col: 0, type: 'backend', label: 'Hub', width: 120 },
{ id: 't0', lane: 'l1', col: 1, type: 'backend', label: 'T0', width: 92, yOffset: -4 },
{ id: 't1', lane: 'l2', col: 3, type: 'backend', label: 'T1', width: 92, yOffset: 4 },
{ id: 't2', lane: 'l3', col: 1, type: 'external', label: 'T2', width: 120, yOffset: -4 },
{ id: 't3', lane: 'l1', col: 5, type: 'backend', label: 'T3', width: 92, yOffset: -12 },
{ id: 't4', lane: 'l2', col: 1, type: 'backend', label: 'T4', width: 120, yOffset: -12 },
],
edges: [
{ id: 'e00', from: 'hub', to: 't0', label: 'Z'.repeat(80) },
{ id: 'e01', from: 'hub', to: 't1', label: 'Q'.repeat(120) },
{ id: 'e02', from: 'hub', to: 't2', label: 'Q'.repeat(120) },
{ id: 'e03', from: 'hub', to: 't3', label: 'Z'.repeat(80) },
{ id: 'e04', from: 'hub', to: 't4' },
],
});
const first = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
const second = compileWorkflow({ workflow: clone(document), qualityProfile: 'standard' });
assert.equal(first.ok, true, JSON.stringify(first.diagnostics, null, 2));
assert.deepEqual(second, first);
const route = first.receipt.edges.find(({ id }) => id === 'e04')?.points;
assert.ok(route);
assertOrthogonal(route);
// Straight-first reservation may push the unlabeled edge left (return-left)
// or right (outside-right); either escape clears the labeled fan-out region.
assert.ok(
Math.max(...route.map(([x]) => x)) > 764
|| Math.min(...route.map(([x]) => x)) < 40,
JSON.stringify(route),
);
// An authored canvas at least as large as the intrinsic requirement still
// compiles; the exact width may grow when straight-first reorders fan-out.
const boundedDocument = clone(document);
boundedDocument.meta.viewBox = [...first.receipt.requiredViewBox];
const bounded = compileWorkflow({ workflow: boundedDocument, qualityProfile: 'standard' });
assert.equal(bounded.ok, true, JSON.stringify(bounded.diagnostics, null, 2));
assert.deepEqual(bounded.receipt.viewBox, first.receipt.requiredViewBox);
});
test('readable-v2 feeds a measured outside-channel constraint back into layout', () => {
const document = workflow({
lanes: [{ id: 'source', label: 'Source' }, { id: 'target', label: 'Target' }],
nodes: [
{ id: 'a', lane: 'source', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'target', col: 0, type: 'backend', label: 'B' },
],
edges: [{ id: 'ab', from: 'a', to: 'b', label: 'L'.repeat(120) }],
});
document.meta.quality_profile = 'showcase';
const first = compileWorkflow({ workflow: document });
const second = compileWorkflow({ workflow: clone(document) });
assert.equal(first.ok, true, JSON.stringify(first.diagnostics, null, 2));
assert.deepEqual(first.receipt.viewBox, [780, 404]);
assert.deepEqual(first.receipt.requiredViewBox, [780, 404]);
assert.deepEqual(first.receipt.edges[0].points, [
[140, 119], [764, 119], [764, 243], [140, 243],
]);
assert.deepEqual(
{ x: first.receipt.labels[0].x, y: first.receipt.labels[0].y },
{ x: 452, y: 109 },
);
assert.equal(second.svg, first.svg);
assert.equal(JSON.stringify(second.receipt), JSON.stringify(first.receipt));
});
test('readable-v2 feeds a measured adjacent-rank gutter back into layout', () => {
const document = workflow({
lanes: [{ id: 'l0', label: 'Lane 0' }, { id: 'l1', label: 'Lane 1' }],
nodes: [
{ id: 'a', lane: 'l0', col: 0, type: 'backend', label: 'A' },
{ id: 'obstacle', lane: 'l0', col: 1, type: 'database', label: 'Obstacle' },
{ id: 'b', lane: 'l1', col: 1, type: 'backend', label: 'B' },
],
edges: [{ id: 'ab', from: 'a', to: 'b', fromSide: 'right', toSide: 'left' }],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
assert.deepEqual(result.receipt.columns.slice(0, 2), [94, 218]);
assert.deepEqual(result.receipt.edges[0].points, [
[140, 119], [156, 119], [156, 243], [172, 243],
]);
});
test('readable-v2 feeds a measured lane gap back into layout', () => {
const document = workflow({
lanes: [0, 1, 2].map((index) => ({ id: `l${index}`, label: `Lane ${index}` })),
nodes: [0, 1, 2].map((index) => ({
id: `n${index}`, lane: `l${index}`, col: 5, type: 'backend', label: `N${index}`,
})),
edges: [
{
id: 'e0', from: 'n1', to: 'n2', fromSide: 'bottom', toSide: 'right', label: 'LLLLLLLLLL',
},
{
id: 'e2', from: 'n2', to: 'n1', fromSide: 'left', toSide: 'right', label: 'x',
},
],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'showcase' });
assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
assert.deepEqual(result.receipt.columns, [94, 214, 334, 454, 574, 694]);
assert.deepEqual(result.receipt.nodes.map(({ id, y }) => ({ id, y })), [
{ id: 'n0', y: 93 }, { id: 'n1', y: 229 }, { id: 'n2', y: 365 },
]);
assert.deepEqual(result.receipt.edges.map(({ id, points }) => ({ id, points })), [
{
id: 'e0',
points: [[694, 281], [694, 308], [756, 308], [756, 391], [740, 391]],
},
{
id: 'e2',
points: [[648, 391], [632, 391], [632, 172], [756, 172], [756, 255], [740, 255]],
},
]);
assert.deepEqual(result.receipt.requiredViewBox, [772, 552]);
});
for (const { name, makeDocument } of [
{
name: 'duplicate authored via points',
makeDocument: () => {
const { start } = oneLaneAnchors();
const pin = [start[0] + 60, start[1]];
return oneLaneWorkflow([{
id: 'ab', from: 'a', to: 'b', via: [pin, [...pin]],
}]);
},
},
{
name: 'diagonal authored via geometry',
makeDocument: () => {
const { start } = oneLaneAnchors();
return oneLaneWorkflow([{
id: 'ab', from: 'a', to: 'b', via: [[start[0] + 60, start[1] + 31]],
}]);
},
},
]) {
test(`readable-v2 rejects ${name} with a typed explicit-pin diagnostic`, () => {
const result = compileWorkflow({ workflow: makeDocument(), qualityProfile: 'standard' });
assertExplicitPinConflict(result, name);
});
}
test('readable-v2 duplicate evidence excludes a compatible channel assertion', () => {
const document = oneLaneWorkflow([{
id: 'ab',
from: 'a',
to: 'b',
via: [[200, 119], [200, 180], [200, 180], [260, 180], [260, 119]],
channelY: 180,
}]);
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assertExplicitPinConflict(result, 'duplicate via with compatible channelY');
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'non-zero route segments');
assert.deepEqual(diagnostic.evidence.conflictingPins, [{
edge: 'ab', field: 'via', path: '/edges/0/via',
value: [[200, 119], [200, 180], [200, 180], [260, 180], [260, 119]],
}]);
assert.ok(diagnostic.supportedFixes.length > 0, JSON.stringify(diagnostic, null, 2));
});
test('readable-v2 obstacle evidence excludes a compatible channel assertion', () => {
const document = workflow({
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' },
{ id: 'obstacle', lane: 'main', col: 1, type: 'database', label: 'Obstacle' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
],
edges: [{
id: 'ab',
from: 'a',
to: 'b',
via: [[156, 119], [156, 180], [200, 180], [200, 119], [276, 119]],
channelY: 180,
}],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assertExplicitPinConflict(result, 'node collision with compatible channelY');
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'node clearance');
assert.deepEqual(diagnostic.evidence.conflictingPins, [{
edge: 'ab', field: 'via', path: '/edges/0/via',
value: [[156, 119], [156, 180], [200, 180], [200, 119], [276, 119]],
}]);
assert.ok(diagnostic.supportedFixes.length > 0, JSON.stringify(diagnostic, null, 2));
});
test('readable-v2 infers omitted endpoint sides around an authored via', () => {
const expected = [[94, 93], [94, 77], [334, 77], [334, 93]];
for (const qualityProfile of ['standard', 'showcase']) {
for (const sides of [
{},
{ fromSide: 'top' },
{ toSide: 'top' },
{ fromSide: 'top', toSide: 'top' },
]) {
const document = oneLaneWorkflow([{
id: 'ab', from: 'a', to: 'b', via: [[94, 77], [334, 77]], ...sides,
}]);
const result = compileWorkflow({ workflow: document, qualityProfile });
assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
assert.deepEqual(result.receipt.edges[0].points, expected);
}
}
const restricted = oneLaneWorkflow([{
id: 'ab',
from: 'a',
to: 'b',
fromSide: 'right',
via: [[94, 77], [334, 77]],
}]);
assertExplicitPinConflict(
compileWorkflow({ workflow: restricted, qualityProfile: 'standard' }),
'authored fromSide must remain a hard restriction',
);
const duplicate = oneLaneWorkflow([{
id: 'ab',
from: 'a',
to: 'b',
via: [[94, 77], [94, 77], [334, 77]],
}]);
const duplicateResult = compileWorkflow({ workflow: duplicate, qualityProfile: 'standard' });
assertExplicitPinConflict(duplicateResult, 'inferred top ports around duplicate via geometry');
assert.equal(duplicateResult.diagnostics[0].evidence.invariant, 'non-zero route segments');
assert.deepEqual(duplicateResult.diagnostics[0].evidence.from, [94, 77]);
assert.deepEqual(duplicateResult.diagnostics[0].evidence.to, [94, 77]);
});
test('readable-v2 reports an infeasible authored target side with its verified single-pin repair', () => {
const document = workflow({
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: 0, type: 'backend', label: 'B' },
],
edges: [{ id: 'ab', from: 'a', to: 'b', toSide: 'top' }],
});
document.groups = [{
id: 'g', label: 'Very long group label', lane: 'bottom', fromCol: 0, toCol: 0,
}];
const result = compileWorkflow({ workflow: document, 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/explicit-pin-conflict');
assert.deepEqual(diagnostic.subject, {
diagramType: 'workflow',
edge: 'ab',
from: 'a',
to: 'b',
path: '/edges/0/toSide',
});
assert.equal(
diagnostic.evidence.invariant,
'readable route feasibility with authored endpoint sides',
);
assert.deepEqual(diagnostic.evidence.conflictingPins, [{
edge: 'ab',
field: 'toSide',
path: '/edges/0/toSide',
value: 'top',
}]);
assert.deepEqual(diagnostic.supportedFixes, [
'remove toSide from edge "ab" so readable-v2 can replan the remaining endpoint-side pins',
]);
assert.deepEqual(result.receipt.diagnostics, result.diagnostics);
const repaired = clone(document);
delete repaired.edges[0].toSide;
const verified = compileWorkflow({ workflow: repaired, qualityProfile: 'showcase' });
assert.equal(verified.ok, true, JSON.stringify(verified.diagnostics, null, 2));
});
test('readable-v2 reports via and fromSide as a minimal conflict with two verified repairs', () => {
const document = oneLaneWorkflow([{
id: 'ab',
from: 'a',
to: 'b',
fromSide: 'right',
toSide: 'top',
via: [[20, 119], [20, 50], [334, 50]],
}]);
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
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/explicit-pin-conflict');
assert.equal(diagnostic.evidence.invariant, 'perpendicular endpoint-side direction');
assert.deepEqual(diagnostic.evidence.conflictingPins, [
{
edge: 'ab',
field: 'fromSide',
path: '/edges/0/fromSide',
value: 'right',
},
{
edge: 'ab',
field: 'via',
path: '/edges/0/via',
value: [[20, 119], [20, 50], [334, 50]],
},
]);
assert.deepEqual(diagnostic.supportedFixes, [
'remove fromSide from edge "ab" and replan the remaining explicit pins',
'remove via from edge "ab" and replan the remaining explicit pins',
]);
for (const field of ['fromSide', 'via']) {
const repaired = clone(document);
delete repaired.edges[0][field];
const verified = compileWorkflow({ workflow: repaired, qualityProfile: 'standard' });
assert.equal(
verified.ok,
true,
`removing ${field} must recompile:\n${JSON.stringify(verified.diagnostics, null, 2)}`,
);
}
});
test('readable-v2 infers endpoint sides for auto channel pins', () => {
const cases = [
{
edge: { channelY: 77 },
document: oneLaneWorkflow([]),
expected: [[94, 93], [94, 77], [334, 77], [334, 93]],
},
{
edge: { channelX: 20 },
document: workflow({
lanes: [{ id: 'l0', label: 'L0' }, { id: 'l1', label: 'L1' }],
nodes: [
{ id: 'a', lane: 'l0', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'l1', col: 2, type: 'backend', label: 'B' },
],
edges: [],
}),
expected: [[48, 119], [20, 119], [20, 243], [288, 243]],
},
{
edge: { channelX: 20, channelY: 181 },
document: workflow({
lanes: [{ id: 'l0', label: 'L0' }, { id: 'l1', label: 'L1' }],
nodes: [
{ id: 'a', lane: 'l0', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'l1', col: 2, type: 'backend', label: 'B' },
],
edges: [],
}),
expected: [[48, 119], [20, 119], [20, 181], [334, 181], [334, 217]],
},
];
for (const qualityProfile of ['standard', 'showcase']) {
for (const fixture of cases) {
fixture.document.edges = [{ id: 'ab', from: 'a', to: 'b', ...fixture.edge }];
const result = compileWorkflow({ workflow: clone(fixture.document), qualityProfile });
assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
assert.deepEqual(result.receipt.edges[0].points, fixture.expected);
for (const [field, value] of Object.entries(fixture.edge)) {
assert.ok(routeContainsChannel(result.receipt.edges[0].points, field, value));
}
}
}
});
test('readable-v2 treats an omitted preset side as a solver choice', () => {
const crossLane = (route, extra = {}) => workflow({
lanes: [{ id: 'l0', label: 'X' }, { id: 'l1', label: 'Y' }],
nodes: [
{ id: 'a', lane: 'l0', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'l1', col: 2, type: 'backend', label: 'B' },
],
edges: [{ id: 'ab', from: 'a', to: 'b', route, ...extra }],
});
const cases = [
{
route: 'straight',
document: oneLaneWorkflow([{ id: 'ab', from: 'a', to: 'b', route: 'straight' }]),
expected: [[140, 119], [288, 119]],
},
{ route: 'drop', document: crossLane('drop'), expected: [[94, 145], [94, 166], [334, 166], [334, 217]] },
{ route: 'outside-right', document: crossLane('outside-right'), expected: [[140, 119], [764, 119], [764, 243], [380, 243]] },
{ route: 'return-left', document: crossLane('return-left'), expected: [[48, 119], [20, 119], [20, 243], [288, 243]] },
{ route: 'bottom-channel', document: crossLane('bottom-channel'), expected: [[94, 145], [94, 301], [334, 301], [334, 269]] },
{ route: 'up-channel', document: crossLane('up-channel'), expected: [[94, 93], [94, 65], [334, 65], [334, 217]] },
{ route: 'outside-right partial', document: crossLane('outside-right', { fromSide: 'right' }), expected: [[140, 119], [764, 119], [764, 243], [380, 243]] },
];
for (const fixture of cases) {
const result = compileWorkflow({ workflow: fixture.document, qualityProfile: 'standard' });
assert.equal(result.ok, true, `${fixture.route}: ${JSON.stringify(result.diagnostics, null, 2)}`);
assert.deepEqual(result.receipt.edges[0].points, fixture.expected);
}
});
test('readable-v2 treats an infeasible route preset as a candidate-family conflict, not a coordinate pin', () => {
const document = workflow({
lanes: [{ id: 'source', label: 'Source' }, { id: 'target', label: 'Target' }],
nodes: [
{ id: 'a', lane: 'source', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'target', col: 2, type: 'backend', label: 'B' },
],
edges: [{ id: 'ab', from: 'a', to: 'b', route: 'straight' }],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/route-preset-conflict');
assert.ok(diagnostic);
assert.ok(result.diagnostics.every(({ code }) => code !== 'workflow/explicit-pin-conflict'));
assert.ok(diagnostic.supportedFixes.length > 0);
assert.ok(diagnostic.supportedFixes.every((fix) => /^set edge |^remove route /.test(fix)));
for (const fix of diagnostic.supportedFixes) {
const repaired = clone(document);
const preset = fix.match(/verified preset "([^"]+)"/)?.[1];
if (preset) repaired.edges[0].route = preset;
else delete repaired.edges[0].route;
const verified = compileWorkflow({ workflow: repaired, qualityProfile: 'standard' });
assert.equal(verified.ok, true, `advertised fix must recompile: ${fix}`);
}
});
test('readable-v2 verifies preset repairs with the public straight-route reservation', () => {
const document = workflow({
lanes: [{ id: 'top', label: 'Top' }, { id: 'middle', label: 'Middle' }, { id: 'bottom', label: 'Bottom' }],
nodes: [
{ id: 'left', lane: 'middle', col: 0, type: 'backend', label: 'Left' },
{ id: 'right', lane: 'middle', col: 3, type: 'backend', label: 'Right' },
{ id: 'above', lane: 'top', col: 1, type: 'backend', label: 'Above' },
{ id: 'below', lane: 'bottom', col: 1, type: 'backend', label: 'Below' },
],
edges: [
{ id: 'a-preset', from: 'left', to: 'right', label: 'PIN', route: 'outside-right', fromSide: 'right', toSide: 'right' },
{ id: 'z-auto', from: 'above', to: 'below' },
],
});
// Source indexes also differ from canonical edge order in the reversed input.
for (const edges of [document.edges, [...document.edges].reverse()]) {
const authored = { ...clone(document), edges: clone(edges) };
const original = clone(authored);
const result = compileWorkflow({ workflow: authored, qualityProfile: 'showcase' });
assert.equal(result.ok, false);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/route-preset-conflict');
assert.ok(diagnostic, JSON.stringify(result.diagnostics, null, 2));
const routeOnly = clone(authored);
const routeOnlyEdge = routeOnly.edges.find(({ id }) => id === 'a-preset');
delete routeOnlyEdge.route;
const retainedSides = compileWorkflow({ workflow: routeOnly, qualityProfile: 'showcase' });
assertExplicitPinConflict(retainedSides, 'removing the preset does not remove authored right/right sides');
assert.equal(retainedSides.diagnostics[0].evidence.invariant, 'explicit route-route crossing');
assert.equal(routeOnlyEdge.fromSide, 'right');
assert.equal(routeOnlyEdge.toSide, 'right');
for (const fix of diagnostic.supportedFixes) {
const repaired = clone(authored);
const target = repaired.edges.find(({ id }) => id === 'a-preset');
const replacement = fix.match(/^set edge "a-preset" route to verified preset "([^"\n]+)"$/);
if (replacement) target.route = replacement[1];
else {
assert.match(fix, /^remove route from edge "a-preset" so readable-v2 can use its verified automatic candidate$/);
delete target.route;
}
const { route: oldRoute, ...originalAssertions } = original.edges.find(({ id }) => id === 'a-preset');
const { route: newRoute, ...remainingAssertions } = target;
assert.deepEqual(remainingAssertions, originalAssertions, 'a route suggestion preserves sides, label and topology');
const verified = compileWorkflow({ workflow: repaired, qualityProfile: 'showcase' });
assert.equal(verified.ok, true, `advertised preset repair must pass public compilation: ${fix}\n${JSON.stringify(verified.diagnostics, null, 2)}`);
}
const automatic = clone(routeOnly);
const automaticEdge = automatic.edges.find(({ id }) => id === 'a-preset');
delete automaticEdge.fromSide;
delete automaticEdge.toSide;
const unpinned = compileWorkflow({ workflow: automatic, qualityProfile: 'showcase' });
assert.equal(unpinned.ok, true, 'the same topology and label are repairable when all route assertions are removed');
assert.deepEqual(authored, original, 'fix discovery preserves the authored input');
}
});
test('a preset that crosses a node reports the blocked segment before a label-only repair', () => {
const document = workflow({
lanes: [{ id: 'top', label: 'Top' }, { id: 'bottom', label: 'Bottom' }],
nodes: [
{ id: 'target', lane: 'top', col: 4, type: 'backend', label: 'Target' },
{ id: 'obstacle', lane: 'top', col: 5, type: 'backend', label: 'Obstacle' },
{ id: 'source', lane: 'bottom', col: 4, width: 104, type: 'backend', label: 'Source' },
],
edges: [{ id: 'retry', from: 'source', to: 'target', route: 'outside-right',
fromSide: 'right', toSide: 'right', role: 'return', label: 'Try payment again', variant: 'dashed' }],
});
const original = clone(document);
for (const qualityProfile of ['standard', 'showcase']) {
const result = compileWorkflow({ workflow: document, qualityProfile });
assert.equal(result.ok, false);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/route-preset-conflict');
assert.equal(diagnostic.evidence.invariant, 'node clearance');
assert.equal(diagnostic.evidence.obstacleNode, 'obstacle');
const { points, segmentIndex, from, to } = diagnostic.evidence;
assert.deepEqual([from, to], points.slice(segmentIndex, segmentIndex + 2));
assert.ok(diagnostic.supportedFixes.every(fix => !fix.startsWith('set labelSegment')));
const movedLabel = clone(document);
movedLabel.edges[0].labelSegment = 1;
const stillBlocked = compileWorkflow({ workflow: movedLabel, qualityProfile });
assert.equal(stillBlocked.ok, false);
const later = stillBlocked.diagnostics.find(({ code }) => code === 'workflow/route-preset-conflict');
assert.equal(later.evidence.obstacleNode, diagnostic.evidence.obstacleNode);
assert.deepEqual([later.evidence.from, later.evidence.to], [from, to]);
}
assert.deepEqual(document, original);
});
function outsideRightLabelWorkflow() {
return workflow({
lanes: [{ id: 'undo', label: 'Undo' }, { id: 'return', label: 'Follow-up' }],
nodes: [
{ id: 'receipt', lane: 'undo', col: 5, type: 'database', label: 'Receipt' },
{ id: 'rescan', lane: 'return', col: 5, type: 'backend', label: 'Rescan' },
],
edges: [{
id: 'follow-up', from: 'receipt', to: 'rescan', label: '成功后按需另行 Scan',
role: 'branch', variant: 'dashed', route: 'outside-right', fromSide: 'right', toSide: 'right',
}],
});
}
function presetLabelDiagnostic(result) {
assert.equal(result.ok, false);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/route-preset-conflict');
assert.ok(diagnostic, JSON.stringify(result.diagnostics, null, 2));
assert.equal(diagnostic.evidence.invariant, 'edge-label node clearance');
return diagnostic;
}
function applySegmentSuggestion(document, diagnostic) {
const suggestions = diagnostic.supportedFixes.filter((fix) => fix.startsWith('set labelSegment '));
assert.equal(suggestions.length, 1, JSON.stringify(diagnostic.supportedFixes));
assert.equal(diagnostic.supportedFixes[0], suggestions[0], 'prefer the verified local repair before route changes');
const match = suggestions[0].match(/^set labelSegment on edge "follow-up" to (\d+)$/);
assert.ok(match, `the segment repair must identify the edge and an executable index: ${suggestions[0]}`);
const segment = Number(match[1]);
assert.ok(segment < diagnostic.evidence.points.length - 1, 'only an actual route segment may be advertised');
const repaired = clone(document);
repaired.edges[0].labelSegment = segment;
return repaired;
}
for (const qualityProfile of ['standard', 'showcase']) {
test(`readable-v2 preset label repair preserves the explicit route and semantic content (${qualityProfile})`, () => {
const document = outsideRightLabelWorkflow();
const original = clone(document);
const diagnostic = presetLabelDiagnostic(compileWorkflow({ workflow: document, qualityProfile }));
const repaired = applySegmentSuggestion(document, diagnostic);
assert.ok(diagnostic.supportedFixes.slice(1).includes(
'remove route from edge "follow-up" so readable-v2 can use its verified automatic candidate',
), 'retain the original verified route suggestion after the local repair');
const verified = compileWorkflow({ workflow: repaired, qualityProfile });
assert.equal(verified.ok, true, JSON.stringify(verified.diagnostics, null, 2));
assert.deepEqual(document, original, 'suggestion discovery must not mutate the authored input');
assert.deepEqual(repaired, {
...original, edges: [{ ...original.edges[0], labelSegment: repaired.edges[0].labelSegment }],
}, 'applying the suggestion changes only labelSegment');
const unlabeled = clone(original);
delete unlabeled.edges[0].label;
const baseline = compileWorkflow({ workflow: unlabeled, qualityProfile });
assert.equal(baseline.ok, true);
assert.deepEqual(verified.receipt.edges, baseline.receipt.edges, 'the explicit preset route must remain intact');
assert.deepEqual(verified.receipt.nodes, baseline.receipt.nodes);
assert.match(verified.svg, />成功后按需另行 Scan<\/text>/);
const label = verified.receipt.labels[0];
const rect = { x: label.x - label.width / 2, y: label.y - 10, width: label.width, height: label.height };
for (const node of verified.receipt.nodes) {
assert.ok(rect.x + rect.width <= node.x || rect.x >= node.x + node.width
|| rect.y + rect.height <= node.y || rect.y >= node.y + node.height,
`the complete semantic label mask must clear node ${node.id}`);
}
});
}
test('readable-v2 preset label repair requires a complete same-profile pass', () => {
const document = outsideRightLabelWorkflow();
document.nodes[0].width = 132;
document.nodes[0].sublabel = 'chain / debate / synthesis 调度';
for (const col of [0, 1, 2, 3, 4]) {
document.nodes.push({ id: `wide-${col}`, lane: 'undo', col, type: 'backend', label: `Step ${col}`, width: 200 });
}
const original = clone(document);
const manuallyRepaired = clone(document);
manuallyRepaired.edges[0].labelSegment = 1;
const stillFailing = compileWorkflow({ workflow: manuallyRepaired, qualityProfile: 'showcase' });
assert.equal(stillFailing.ok, false);
assert.ok(stillFailing.diagnostics.some(({ code }) => code === 'workflow/sublabel-readability'));
assert.ok(stillFailing.diagnostics.every(({ code }) => code !== 'workflow/route-preset-conflict'));
const diagnostic = presetLabelDiagnostic(compileWorkflow({ workflow: document, qualityProfile: 'showcase' }));
assert.ok(diagnostic.supportedFixes.every((fix) => !fix.startsWith('set labelSegment ')),
'clearing only the current label collision is not a verified full-workflow repair');
assert.deepEqual(document, original);
});
test('readable-v2 preset label repair respects authored zero-valued controls', () => {
for (const field of ['labelSegment', 'labelDx', 'labelDy']) {
const document = outsideRightLabelWorkflow();
document.edges[0][field] = 0;
const original = clone(document);
const diagnostic = presetLabelDiagnostic(compileWorkflow({ workflow: document, qualityProfile: 'standard' }));
assert.ok(diagnostic.supportedFixes.every((fix) => !fix.startsWith('set labelSegment ')), `${field}: 0 is authored`);
assert.deepEqual(document, original);
}
});
test('workflow validate JSON exposes an executable preset label repair', (t) => {
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-preset-label-repair-'));
t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
const input = path.join(directory, 'workflow.json');
const cli = fileURLToPath(new URL('../archify/bin/archify.mjs', import.meta.url));
const document = outsideRightLabelWorkflow();
const original = JSON.stringify(document);
fs.writeFileSync(input, original);
const validate = () => spawnSync(process.execPath, [
cli, 'validate', 'workflow', input, '--quality', 'showcase', '--json',
], { encoding: 'utf8' });
const failed = validate();
assert.equal(failed.status, 1, failed.stdout + failed.stderr);
const receipt = JSON.parse(failed.stdout);
const diagnostic = receipt.diagnostics.find(({ code }) => code === 'workflow/route-preset-conflict');
assert.ok(diagnostic, failed.stdout);
assert.equal(fs.readFileSync(input, 'utf8'), original);
fs.writeFileSync(input, JSON.stringify(applySegmentSuggestion(document, diagnostic)));
const passed = validate();
assert.equal(passed.status, 0, passed.stdout + passed.stderr);
const verified = JSON.parse(passed.stdout);
assert.equal(verified.ok, true);
assert.ok(verified.checks.length > 0 && verified.checks.every((check) => check.ok));
});
test('readable-v2 never accepts a same-lane drop through the preset-only fallback', () => {
const document = oneLaneWorkflow([{
id: 'ab',
from: 'a',
to: 'b',
route: 'drop',
fromSide: 'top',
toSide: 'top',
}]);
document.nodes.forEach((node) => { node.yOffset = 20; });
for (const qualityProfile of ['standard', 'showcase']) {
const result = compileWorkflow({ workflow: clone(document), qualityProfile });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.ok(result.diagnostics.some(({ code }) => code === 'workflow/route-preset-conflict'));
assert.ok(result.diagnostics.every(({ code }) => code !== 'workflow/explicit-pin-conflict'));
assert.equal(result.diagnostics[0].evidence.invariant, 'route preset compatibility');
}
});
test('readable-v2 preset diagnostics identify the blocked node rather than blaming segment rhythm', () => {
const document = workflow({
lanes: [{ id: 'upper', label: 'Upper' }, { id: 'lower', label: 'Lower' }],
nodes: [
{ id: 'blocker', lane: 'upper', col: 0, type: 'backend', label: 'Blocker' },
{ id: 'target', lane: 'upper', col: 2, type: 'backend', label: 'Target' },
{ id: 'source', lane: 'lower', col: 0, type: 'backend', label: 'Source' },
],
edges: [{ id: 'return', from: 'source', to: 'target', route: 'up-channel', fromSide: 'top', toSide: 'top' }],
});
for (const qualityProfile of ['standard', 'showcase']) {
const result = compileWorkflow({ workflow: clone(document), qualityProfile });
assert.equal(result.ok, false);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/route-preset-conflict');
assert.ok(diagnostic);
assert.equal(diagnostic.evidence.invariant, 'node clearance');
assert.equal(diagnostic.evidence.obstacleNode, 'blocker');
assert.equal(diagnostic.evidence.obstacleRole, 'unrelated');
assert.equal(diagnostic.evidence.segmentIndex, 0);
assert.equal(diagnostic.evidence.clearancePx, 2);
assert.deepEqual(diagnostic.evidence.from, diagnostic.evidence.points[0]);
assert.deepEqual(diagnostic.evidence.to, diagnostic.evidence.points[1]);
assert.match(diagnostic.message, /segment 0 intersects node "blocker"/);
assert.doesNotMatch(diagnostic.message, /minimum 8px/);
assert.deepEqual(document.edges[0], {
id: 'return', from: 'source', to: 'target', route: 'up-channel', fromSide: 'top', toSide: 'top',
});
}
});
test('readable-v2 preset diagnostics measure the segment that actually violates rhythm', () => {
const document = workflow({
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A', yOffset: -30 },
{ id: 'b', lane: 'main', col: 0, type: 'backend', label: 'B', yOffset: 30 },
],
edges: [{ id: 'ab', from: 'a', to: 'b', route: 'straight', fromSide: 'bottom', toSide: 'top' }],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/route-preset-conflict');
assert.ok(diagnostic);
assert.equal(diagnostic.evidence.invariant, 'readable segment rhythm');
assert.equal(diagnostic.evidence.segmentIndex, 0);
assert.equal(diagnostic.evidence.actualSegmentPx, 8);
assert.equal(diagnostic.evidence.requiredSegmentPx, 28);
});
test('readable-v2 direct rhythm rejection and acceptance agree at the 28px boundary', () => {
for (const qualityProfile of ['standard', 'showcase']) {
for (const gap of [27.9998, 28]) {
const document = workflow({
lanes: [{ id: 'main', label: 'M' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A', yOffset: -(52 + gap) / 2 },
{ id: 'b', lane: 'main', col: 0, type: 'backend', label: 'B', yOffset: (52 + gap) / 2 },
],
edges: [{ id: 'ab', from: 'a', to: 'b', route: 'straight', fromSide: 'bottom', toSide: 'top' }],
});
const result = compileWorkflow({ workflow: document, qualityProfile });
assert.equal(result.ok, gap === 28, JSON.stringify(result.diagnostics));
if (result.ok) {
assert.deepEqual(result.receipt.edges[0].points, [[94, 138], [94, 166]]);
} else {
const { evidence } = result.diagnostics.find(({ code }) => code === 'workflow/route-preset-conflict');
assert.equal(evidence.invariant, 'readable segment rhythm');
assert.equal(evidence.requiredSegmentPx, 28);
assert.equal(evidence.segmentIndex, 0);
assert.ok(Math.abs(evidence.actualSegmentPx - gap) < 1e-9);
}
}
}
});
test('readable-v2 endpoint rhythm runs before the separate preset-family rejection', () => {
for (const qualityProfile of ['standard', 'showcase']) {
for (const offset of [18.9998, 19]) {
const document = oneLaneWorkflow([{
id: 'ab', from: 'a', to: 'b', route: 'drop', fromSide: 'top', toSide: 'top',
}]);
document.nodes.forEach((node) => { node.yOffset = offset; });
const result = compileWorkflow({ workflow: document, qualityProfile });
assert.equal(result.ok, false);
const { evidence } = result.diagnostics.find(({ code }) => code === 'workflow/route-preset-conflict');
assert.equal(evidence.invariant, offset === 19 ? 'route preset compatibility' : 'readable segment rhythm');
if (offset < 19) {
assert.equal(evidence.segmentIndex, 0);
assert.equal(evidence.requiredSegmentPx, 8);
assert.ok(Math.abs(evidence.actualSegmentPx - 7.9998) < 1e-9);
} else {
assert.equal(evidence.points[0][1] - evidence.points[1][1], 8);
}
}
}
});
test('readable-v2 interior rhythm precedes node clearance and accepts a cleared 16px segment', () => {
for (const qualityProfile of ['standard', 'showcase']) {
for (const gap of [15.9998, 16, 16.0002]) {
const document = workflow({
lanes: [{ id: 'main', label: 'M' }],
nodes: [
{ id: 'a', lane: 'main', col: 2, type: 'backend', label: 'A', height: 32 },
{ id: 'b', lane: 'main', col: 0, type: 'backend', label: 'B', height: 32, yOffset: gap },
],
edges: [{ id: 'ab', from: 'a', to: 'b', route: 'outside-right', fromSide: 'right', toSide: 'right' }],
});
const result = compileWorkflow({ workflow: document, qualityProfile });
assert.equal(result.ok, gap > 16, JSON.stringify(result.diagnostics));
if (result.ok) {
const points = result.receipt.edges[0].points;
assert.ok(Math.abs(points[2][1] - points[1][1] - gap) < 1e-9);
} else {
const { evidence } = result.diagnostics.find(({ code }) => code === 'workflow/route-preset-conflict');
assert.equal(evidence.invariant, gap === 16 ? 'node clearance' : 'readable segment rhythm');
if (gap < 16) {
assert.equal(evidence.segmentIndex, 1);
assert.equal(evidence.requiredSegmentPx, 16);
assert.ok(Math.abs(evidence.actualSegmentPx - gap) < 1e-9);
} else {
assert.equal(evidence.obstacleNode, 'a');
assert.equal(evidence.obstacleRole, 'source-endpoint');
}
}
}
}
});
test('readable-v2 never silently ignores coordinate pins that conflict with a route preset', () => {
const cases = [
{
name: 'straight with channelY',
document: oneLaneWorkflow([{
id: 'ab', from: 'a', to: 'b', route: 'straight', channelY: 300,
}]),
},
{
name: 'straight with channelX',
document: oneLaneWorkflow([{
id: 'ab', from: 'a', to: 'b', route: 'straight', channelX: 300,
}]),
},
{
name: 'drop with channelX',
document: workflow({
lanes: [{ id: 'source', label: 'Source' }, { id: 'target', label: 'Target' }],
nodes: [
{ id: 'a', lane: 'source', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'target', col: 0, type: 'backend', label: 'B' },
],
edges: [{ id: 'ab', from: 'a', to: 'b', route: 'drop', channelX: 777 }],
}),
},
...[
['outside-right', 'channelY'],
['return-left', 'channelY'],
['bottom-channel', 'channelX'],
['up-channel', 'channelX'],
].map(([route, field]) => ({
name: `${route} with ${field}`,
document: oneLaneWorkflow([{
id: 'ab', from: 'a', to: 'b', route, [field]: 300,
}]),
})),
];
for (const { name, document } of cases) {
let result;
assert.doesNotThrow(() => {
result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
}, `${name} must stay inside the public compiler result boundary`);
assertExplicitPinConflict(result, name);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/explicit-pin-conflict');
assert.equal(diagnostic.evidence.route, document.edges[0].route);
assert.ok(diagnostic.evidence.conflictingPins.length > 0);
}
});
test('readable-v2 preset compatibility reports both authored causal paths and verified repairs', () => {
const document = oneLaneWorkflow([{
id: 'ab', from: 'a', to: 'b', route: 'straight', channelY: 300,
}]);
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assertExplicitPinConflict(result, 'straight preset with channelY');
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'route preset compatibility');
assert.deepEqual(diagnostic.evidence.conflictingPins, [
{
edge: 'ab', field: 'route', path: '/edges/0/route', value: 'straight',
},
{
edge: 'ab', field: 'channelY', path: '/edges/0/channelY', value: 300,
},
]);
assert.deepEqual(diagnostic.supportedFixes, [
'remove route from edge "ab" and keep the remaining verified route assertions',
'remove channelY from edge "ab" and keep the remaining verified route assertions',
]);
for (const field of ['route', 'channelY']) {
const repaired = clone(document);
delete repaired.edges[0][field];
const verified = compileWorkflow({ workflow: repaired, qualityProfile: 'standard' });
assert.equal(
verified.ok,
true,
`removing ${field} must recompile:\n${JSON.stringify(verified.diagnostics, null, 2)}`,
);
}
});
test('readable-v2 rejects a raw via that does not belong to its route preset family', () => {
const { start, end } = oneLaneAnchors();
const document = oneLaneWorkflow([{
id: 'ab',
from: 'a',
to: 'b',
route: 'straight',
via: [
[start[0] + 20, start[1]],
[start[0] + 20, start[1] + 40],
[end[0] - 20, start[1] + 40],
[end[0] - 20, end[1]],
],
}]);
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assertExplicitPinConflict(result, 'straight preset with a detouring via');
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/explicit-pin-conflict');
assert.equal(diagnostic.evidence.route, 'straight');
assert.equal(diagnostic.evidence.invariant, 'route preset compatibility');
});
for (const fixture of [
{
preset: 'straight',
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
],
edge: { via: [[180, 119], [240, 119]] },
expected: [[140, 119], [180, 119], [240, 119], [288, 119]],
},
{
preset: 'drop',
lanes: [{ id: 'source', label: 'Source' }, { id: 'target', label: 'Target' }],
nodes: [
{ id: 'a', lane: 'source', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'target', col: 2, type: 'backend', label: 'B' },
],
edge: { fromSide: 'bottom', toSide: 'top', via: [[94, 181], [334, 181]] },
expected: [[94, 145], [94, 181], [334, 181], [334, 217]],
},
{
preset: 'outside-right',
lanes: [{ id: 'source', label: 'Source' }, { id: 'target', label: 'Target' }],
nodes: [
{ id: 'a', lane: 'source', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'target', col: 2, type: 'backend', label: 'B' },
],
edge: { fromSide: 'right', toSide: 'right', via: [[720, 119], [720, 243]] },
expected: [[140, 119], [720, 119], [720, 243], [380, 243]],
},
{
preset: 'return-left',
lanes: [{ id: 'source', label: 'Source' }, { id: 'target', label: 'Target' }],
nodes: [
{ id: 'a', lane: 'source', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'target', col: 2, type: 'backend', label: 'B' },
],
edge: { fromSide: 'left', toSide: 'left', via: [[20, 119], [20, 243]] },
expected: [[48, 119], [20, 119], [20, 243], [288, 243]],
},
{
preset: 'bottom-channel',
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
],
edge: { fromSide: 'bottom', toSide: 'bottom', via: [[94, 200], [334, 200]] },
expected: [[94, 145], [94, 200], [334, 200], [334, 145]],
},
{
preset: 'up-channel',
lanes: [{ id: 'main', label: 'M' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
],
edge: { fromSide: 'top', toSide: 'top', via: [[94, 20], [334, 20]] },
expected: [[94, 93], [94, 20], [334, 20], [334, 93]],
},
]) {
test(`readable-v2 preserves a compatible ${fixture.preset} via without normalization`, () => {
const document = workflow({
lanes: fixture.lanes,
nodes: fixture.nodes,
edges: [{
id: 'ab', from: 'a', to: 'b', route: fixture.preset, ...fixture.edge,
}],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
assert.deepEqual(result.receipt.edges[0].points, fixture.expected);
});
}
test('readable-v2 keeps a compatible channel pin authoritative inside its route preset', () => {
const document = workflow({
lanes: [{ id: 'source', label: 'Source' }, { id: 'target', label: 'Target' }],
nodes: [
{ id: 'a', lane: 'source', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'target', col: 2, type: 'backend', label: 'B' },
],
edges: [{
id: 'ab',
from: 'a',
to: 'b',
route: 'drop',
channelY: 181,
fromSide: 'bottom',
toSide: 'top',
}],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
const points = result.receipt.edges.find(({ id }) => id === 'ab').points;
assert.ok(
points.slice(0, -1).some((point, index) => (
point[1] === 181 && points[index + 1][1] === 181
)),
`the final path must contain the authored channelY: ${JSON.stringify(points)}`,
);
});
for (const fixture of [
{
preset: 'outside-right', field: 'channelX', value: 720,
lanes: [{ id: 'source', label: 'Source' }, { id: 'target', label: 'Target' }],
nodes: [
{ id: 'a', lane: 'source', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'target', col: 2, type: 'backend', label: 'B' },
],
sides: { fromSide: 'right', toSide: 'right' },
},
{
preset: 'return-left', field: 'channelX', value: 20,
lanes: [{ id: 'source', label: 'Source' }, { id: 'target', label: 'Target' }],
nodes: [
{ id: 'a', lane: 'source', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'target', col: 2, type: 'backend', label: 'B' },
],
sides: { fromSide: 'left', toSide: 'left' },
},
{
preset: 'bottom-channel', field: 'channelY', value: 200,
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
],
sides: { fromSide: 'bottom', toSide: 'bottom' },
},
{
preset: 'up-channel', field: 'channelY', value: 20,
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
],
sides: { fromSide: 'top', toSide: 'top' },
},
]) {
test(`readable-v2 keeps ${fixture.field} authoritative for ${fixture.preset}`, () => {
const document = workflow({
lanes: fixture.lanes,
nodes: fixture.nodes,
edges: [{
id: 'ab',
from: 'a',
to: 'b',
route: fixture.preset,
[fixture.field]: fixture.value,
...fixture.sides,
}],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
const points = result.receipt.edges[0].points;
assert.ok(routeContainsChannel(points, fixture.field, fixture.value));
});
}
for (const fixture of [
{
preset: 'outside-right', field: 'channelX', value: 20,
sides: { fromSide: 'left', toSide: 'left' },
crossLane: true,
},
{
preset: 'return-left', field: 'channelX', value: 720,
sides: { fromSide: 'right', toSide: 'right' },
crossLane: true,
},
{
preset: 'bottom-channel', field: 'channelY', value: 20,
sides: { fromSide: 'top', toSide: 'top' },
},
{
preset: 'up-channel', field: 'channelY', value: 340,
sides: { fromSide: 'bottom', toSide: 'bottom' },
},
{
preset: 'drop', field: 'channelY', value: 20,
sides: { fromSide: 'top', toSide: 'top' },
},
]) {
test(`readable-v2 rejects ${fixture.preset} when its channel belongs to another route family`, () => {
for (const qualityProfile of ['standard', 'showcase']) {
const edges = [{
id: 'ab',
from: 'a',
to: 'b',
route: fixture.preset,
[fixture.field]: fixture.value,
...fixture.sides,
}];
const document = fixture.crossLane
? workflow({
lanes: [{ id: 'source', label: 'Source' }, { id: 'target', label: 'Target' }],
nodes: [
{ id: 'a', lane: 'source', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'target', col: 2, type: 'backend', label: 'B' },
],
edges,
})
: oneLaneWorkflow(edges);
const result = compileWorkflow({ workflow: document, qualityProfile });
assertExplicitPinConflict(result, `${fixture.preset} ${fixture.field} under ${qualityProfile}`);
const diagnostic = result.diagnostics.find(({ code }) => (
code === 'workflow/explicit-pin-conflict'
));
assert.equal(diagnostic.evidence.invariant, 'route preset compatibility');
}
});
}
test('readable-v2 treats channels beside via as assertions over the authored path', () => {
const { start, end } = oneLaneAnchors();
const document = oneLaneWorkflow([{
id: 'ab',
from: 'a',
to: 'b',
channelX: start[0] + 40,
channelY: start[1] + 61,
via: [
[start[0] + 40, start[1]],
[start[0] + 40, start[1] + 61],
[end[0] - 48, start[1] + 61],
[end[0] - 48, end[1]],
],
}]);
const matching = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(matching.ok, true, JSON.stringify(matching.diagnostics, null, 2));
assert.deepEqual(matching.receipt.edges[0].points, [start, ...document.edges[0].via, end]);
const mismatched = clone(document);
mismatched.edges[0].channelX += 1;
const result = compileWorkflow({ workflow: mismatched, qualityProfile: 'standard' });
assertExplicitPinConflict(result, 'via missing its asserted channelX');
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/explicit-pin-conflict');
assert.equal(diagnostic.evidence.invariant, 'channel pin preservation');
assert.deepEqual(
diagnostic.evidence.conflictingPins.map(({ edge, field, path }) => ({ edge, field, path })),
[
{ edge: 'ab', field: 'via', path: '/edges/0/via' },
{ edge: 'ab', field: 'channelX', path: '/edges/0/channelX' },
],
);
const nearButNotExact = clone(document);
nearButNotExact.edges[0].channelX += 0.00005;
const nearResult = compileWorkflow({
workflow: nearButNotExact,
qualityProfile: 'standard',
});
assertExplicitPinConflict(nearResult, 'channel assertions must preserve exact authored numbers');
assert.equal(nearResult.diagnostics[0].evidence.invariant, 'channel pin preservation');
});
test('readable-v2 reports via and channelY as a minimal assertion conflict with two verified repairs', () => {
const document = oneLaneWorkflow([{
id: 'ab',
from: 'a',
to: 'b',
via: [[94, 77], [334, 77]],
channelY: 200,
}]);
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
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/explicit-pin-conflict');
assert.equal(diagnostic.evidence.invariant, 'channel pin preservation');
assert.deepEqual(diagnostic.evidence.conflictingPins, [
{
edge: 'ab',
field: 'via',
path: '/edges/0/via',
value: [[94, 77], [334, 77]],
},
{
edge: 'ab',
field: 'channelY',
path: '/edges/0/channelY',
value: 200,
},
]);
assert.deepEqual(diagnostic.supportedFixes, [
'remove via from edge "ab" and replan the remaining explicit route assertions',
'remove channelY from edge "ab" and replan the remaining explicit route assertions',
]);
for (const field of ['via', 'channelY']) {
const repaired = clone(document);
delete repaired.edges[0][field];
const verified = compileWorkflow({ workflow: repaired, qualityProfile: 'standard' });
assert.equal(
verified.ok,
true,
`removing ${field} must recompile:\n${JSON.stringify(verified.diagnostics, null, 2)}`,
);
}
});
test('readable-v2 reports conflicts between absolute label and route pins as typed geometry', () => {
const document = workflow({
lanes: [{ id: 'top', label: 'Top' }, { id: 'bottom', label: 'Bottom' }],
nodes: [
{ id: 'a', lane: 'top', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'top', col: 4, type: 'backend', label: 'B' },
{ id: 'c', lane: 'bottom', col: 0, type: 'backend', label: 'C' },
{ id: 'd', lane: 'bottom', col: 4, type: 'backend', label: 'D' },
],
edges: [
{ id: 'labelpin', from: 'a', to: 'b', label: 'PIN', labelAt: [334, 243] },
{ id: 'routepin', from: 'c', to: 'd', via: [[334, 243]] },
],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'showcase' });
assertExplicitPinConflict(result, 'labelAt crossing an authored via');
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'explicit label-route clearance');
assert.deepEqual(diagnostic.evidence.conflictingPins.map(({ edge, field }) => ({ edge, field })), [
{ edge: 'labelpin', field: 'labelAt' },
{ edge: 'routepin', field: 'via' },
]);
assert.equal(diagnostic.evidence.clearancePx, 0);
assertSupportedFixesNameChangedEdge(diagnostic, ['labelpin', 'routepin']);
assert.ok(
diagnostic.supportedFixes.some((fix) => fix.includes('edge "routepin"')),
`a routepin repair must identify routepin: ${diagnostic.supportedFixes}`,
);
assert.doesNotMatch(diagnostic.supportedFixes.join('\n'), /remove (?:one |the )?label(?!At)/i);
});
test('readable-v2 derives label-route pins from joint verified removals when route plans first', () => {
const document = workflow({
lanes: [{ id: 'top', label: 'Top' }, { id: 'bottom', label: 'Bottom' }],
nodes: [
{ id: 'a', lane: 'top', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'top', col: 4, type: 'backend', label: 'B' },
{ id: 'c', lane: 'bottom', col: 0, type: 'backend', label: 'C' },
{ id: 'd', lane: 'bottom', col: 4, type: 'backend', label: 'D' },
],
edges: [
{ id: 'a-route', from: 'c', to: 'd', via: [[334, 243]] },
{ id: 'z-label', from: 'a', to: 'b', label: 'PIN', labelAt: [334, 243] },
],
});
document.meta.quality_profile = 'showcase';
const result = compileWorkflow({ workflow: document });
assertExplicitPinConflict(result, 'route-first joint label-route conflict');
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'explicit label-route clearance');
assert.deepEqual(diagnostic.evidence.conflictingPins, [{
edge: 'z-label', field: 'labelAt', path: '/edges/1/labelAt', value: [334, 243],
}]);
assert.ok(diagnostic.supportedFixes.length > 0, JSON.stringify(diagnostic, null, 2));
for (const fix of diagnostic.supportedFixes) {
const replacement = fix.match(/^set labelAt on edge "z-label" to \[(-?\d+(?:\.\d+)?), (-?\d+(?:\.\d+)?)\]$/);
assert.ok(replacement, `route removal is not causal and must not be advertised: ${fix}`);
const repaired = clone(document);
repaired.edges[1].labelAt = replacement.slice(1).map(Number);
const verified = compileWorkflow({ workflow: repaired });
assert.equal(verified.ok, true, `advertised label repair must recompile: ${fix}\n${JSON.stringify(verified.diagnostics, null, 2)}`);
}
});
test('readable-v2 derives both causal pins when label plans before the authored route', () => {
const document = workflow({
lanes: [{ id: 'top', label: 'Top' }, { id: 'bottom', label: 'Bottom' }],
nodes: [
{ id: 'a', lane: 'top', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'top', col: 4, type: 'backend', label: 'B' },
{ id: 'c', lane: 'bottom', col: 0, type: 'backend', label: 'C' },
{ id: 'd', lane: 'bottom', col: 4, type: 'backend', label: 'D' },
],
edges: [
{ id: 'z-route', from: 'c', to: 'd', via: [[334, 243]] },
{ id: 'a-label', from: 'a', to: 'b', label: 'PIN', labelAt: [334, 243] },
],
});
document.meta.quality_profile = 'showcase';
const result = compileWorkflow({ workflow: document });
assertExplicitPinConflict(result, 'label-first joint label-route conflict');
const diagnostic = result.diagnostics[0];
assert.deepEqual(diagnostic.evidence.conflictingPins, [
{ edge: 'a-label', field: 'labelAt', path: '/edges/1/labelAt', value: [334, 243] },
{ edge: 'z-route', field: 'via', path: '/edges/0/via', value: [[334, 243]] },
]);
assert.ok(
diagnostic.supportedFixes.some((fix) => fix.startsWith('set labelAt on edge "a-label"')),
JSON.stringify(diagnostic.supportedFixes, null, 2),
);
assert.ok(
diagnostic.supportedFixes.includes('remove via from edge "z-route" so readable-v2 can replan the remaining authored label-route pins'),
JSON.stringify(diagnostic.supportedFixes, null, 2),
);
for (const fix of diagnostic.supportedFixes) {
const repaired = clone(document);
const replacement = fix.match(/^set labelAt on edge "a-label" to \[(-?\d+(?:\.\d+)?), (-?\d+(?:\.\d+)?)\]$/);
if (replacement) repaired.edges[1].labelAt = replacement.slice(1).map(Number);
else {
assert.equal(fix, 'remove via from edge "z-route" so readable-v2 can replan the remaining authored label-route pins');
delete repaired.edges[0].via;
}
const verified = compileWorkflow({ workflow: repaired });
assert.equal(verified.ok, true, `advertised causal pin repair must pass public compilation: ${fix}\n${JSON.stringify(verified.diagnostics, null, 2)}`);
}
});
test('readable-v2 classifies an authored labelAt colliding with an earlier automatic route', () => {
const document = workflow({
lanes: [{ id: 'top', label: 'Top' }, { id: 'bottom', label: 'Bottom' }],
nodes: [
{ id: 'a', lane: 'top', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'top', col: 4, type: 'backend', label: 'B' },
{ id: 'c', lane: 'bottom', col: 0, type: 'backend', label: 'C' },
{ id: 'd', lane: 'bottom', col: 4, type: 'backend', label: 'D' },
],
edges: [
{ id: 'a-route', from: 'c', to: 'd' },
{ id: 'z-label', from: 'a', to: 'b', label: 'PIN', labelAt: [334, 243] },
],
});
document.meta.quality_profile = 'showcase';
const result = compileWorkflow({ workflow: document });
assertExplicitPinConflict(result, 'labelAt colliding with an earlier automatic route');
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'explicit label-route clearance');
assert.equal(diagnostic.subject.path, '/edges/1/labelAt');
assert.deepEqual(diagnostic.evidence.conflictingPins, [{
edge: 'z-label',
field: 'labelAt',
path: '/edges/1/labelAt',
value: [334, 243],
}]);
assert.deepEqual(diagnostic.evidence.labelAt, [334, 243]);
assert.deepEqual(diagnostic.evidence.collidedRoute, {
edge: 'a-route',
from: 'c',
to: 'd',
points: [[140, 243], [528, 243]],
});
assert.deepEqual(diagnostic.evidence.routeSegment, {
from: [140, 243],
to: [528, 243],
});
for (const fix of diagnostic.supportedFixes) {
const replacement = fix.match(/^set labelAt on edge "z-label" to \[(-?\d+(?:\.\d+)?), (-?\d+(?:\.\d+)?)\]$/);
assert.ok(replacement, `only a concrete labelAt alternative may be advertised: ${fix}`);
const repaired = clone(document);
repaired.edges[1].labelAt = replacement.slice(1).map(Number);
const verified = compileWorkflow({ workflow: repaired });
assert.equal(verified.ok, true, `advertised labelAt alternative must recompile: ${fix}\n${JSON.stringify(verified.diagnostics, null, 2)}`);
}
});
test('readable-v2 classifies an automatic label colliding with a later authored route', () => {
const document = workflow({
lanes: [
{ id: 'top', label: 'Top' },
{ id: 'mid', label: 'Mid' },
{ id: 'bottom', label: 'Bottom' },
],
nodes: [
{ id: 'a', lane: 'mid', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'mid', col: 4, type: 'backend', label: 'B' },
{ id: 'c', lane: 'top', col: 2, type: 'backend', label: 'C' },
{ id: 'd', lane: 'bottom', col: 2, type: 'backend', label: 'D' },
],
edges: [
{ id: 'a-label', from: 'a', to: 'b', label: 'AUTO' },
{ id: 'z-route', from: 'c', to: 'd', via: [[334, 243]] },
],
});
document.meta.quality_profile = 'showcase';
const result = compileWorkflow({ workflow: document });
assertExplicitPinConflict(result, 'automatic label colliding with a later authored route');
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'explicit label-route clearance');
assert.equal(diagnostic.subject.path, '/edges/1/via');
assert.deepEqual(diagnostic.evidence.conflictingPins, [{
edge: 'z-route',
field: 'via',
path: '/edges/1/via',
value: [[334, 243]],
}]);
assert.deepEqual(diagnostic.evidence.collidedRoute, {
edge: 'z-route',
from: 'c',
to: 'd',
points: [[334, 145], [334, 243], [334, 341]],
});
assert.deepEqual(diagnostic.evidence.routeSegment, {
from: [334, 145],
to: [334, 341],
});
assert.ok(diagnostic.supportedFixes.length > 0, JSON.stringify(diagnostic, null, 2));
for (const fix of diagnostic.supportedFixes) {
assert.equal(
fix,
'remove via from edge "z-route" so readable-v2 can replan the remaining authored route assertions',
);
const repaired = clone(document);
delete repaired.edges[1].via;
const verified = compileWorkflow({ workflow: repaired });
assert.equal(verified.ok, true, `advertised route alternative must recompile: ${fix}\n${JSON.stringify(verified.diagnostics, null, 2)}`);
}
});
test('readable-v2 classifies an authored labelAt colliding with an earlier automatic label', () => {
const document = oneLaneWorkflow([
{ id: 'a-auto', from: 'a', to: 'b', label: 'AUTO' },
{ id: 'z-pin', from: 'a', to: 'b', label: 'PIN', labelAt: [214, 119] },
]);
document.meta.quality_profile = 'showcase';
const result = compileWorkflow({ workflow: document });
assertExplicitPinConflict(result, 'labelAt colliding with an earlier automatic label');
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'explicit label-label clearance');
assert.equal(diagnostic.subject.path, '/edges/1/labelAt');
assert.deepEqual(diagnostic.evidence.conflictingPins, [{
edge: 'z-pin',
field: 'labelAt',
path: '/edges/1/labelAt',
value: [214, 119],
}]);
assert.deepEqual(diagnostic.evidence.labelRects.map(({ edge, ...rect }) => ({ edge, ...rect })), [
{ edge: 'z-pin', x: 199, y: 109, width: 30, height: 14 },
{ edge: 'a-auto', x: 199, y: 99, width: 30, height: 14 },
]);
for (const fix of diagnostic.supportedFixes) {
const replacement = fix.match(/^set labelAt on edge "z-pin" to \[(-?\d+(?:\.\d+)?), (-?\d+(?:\.\d+)?)\]$/);
assert.ok(replacement, `only a concrete labelAt alternative may be advertised: ${fix}`);
const repaired = clone(document);
repaired.edges[1].labelAt = replacement.slice(1).map(Number);
const verified = compileWorkflow({ workflow: repaired });
assert.equal(verified.ok, true, `advertised labelAt alternative must recompile: ${fix}\n${JSON.stringify(verified.diagnostics, null, 2)}`);
}
});
test('readable-v2 derives the causal labelAt from joint verified label removals', () => {
const document = workflow({
lanes: [{ id: 'top', label: 'Top' }, { id: 'bottom', label: 'Bottom' }],
nodes: [
{ id: 'a', lane: 'top', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'top', col: 4, type: 'backend', label: 'B' },
{ id: 'c', lane: 'bottom', col: 0, type: 'backend', label: 'C' },
{ id: 'd', lane: 'bottom', col: 4, type: 'backend', label: 'D' },
],
edges: [
{ id: 'a-label', from: 'a', to: 'b', label: 'FIRST', labelAt: [334, 119] },
{ id: 'z-label', from: 'c', to: 'd', label: 'SECOND', labelAt: [334, 119] },
],
});
document.meta.quality_profile = 'showcase';
const result = compileWorkflow({ workflow: document });
assertExplicitPinConflict(result, 'joint causal label-label conflict');
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'explicit label-label clearance');
assert.deepEqual(diagnostic.evidence.conflictingPins, [{
edge: 'z-label', field: 'labelAt', path: '/edges/1/labelAt', value: [334, 119],
}]);
assert.ok(diagnostic.supportedFixes.length > 0, JSON.stringify(diagnostic, null, 2));
for (const fix of diagnostic.supportedFixes) {
const replacement = fix.match(/^set labelAt on edge "z-label" to \[(-?\d+(?:\.\d+)?), (-?\d+(?:\.\d+)?)\]$/);
assert.ok(replacement, `only the causal label pin may be changed: ${fix}`);
const repaired = clone(document);
repaired.edges[1].labelAt = replacement.slice(1).map(Number);
const verified = compileWorkflow({ workflow: repaired });
assert.equal(verified.ok, true, `advertised label repair must recompile: ${fix}\n${JSON.stringify(verified.diagnostics, null, 2)}`);
}
});
test('readable-v2 reports conflicts between two absolute label pins without deleting semantics', () => {
const document = oneLaneWorkflow([
{
id: 'one', from: 'a', to: 'b', label: 'ONE', via: [[214, 119]], labelAt: [214, 80],
},
{
id: 'two', from: 'a', to: 'b', label: 'TWO', via: [[214, 119]], labelAt: [214, 80],
},
]);
for (const qualityProfile of ['standard', 'showcase']) {
const result = compileWorkflow({ workflow: clone(document), qualityProfile });
assertExplicitPinConflict(result, `overlapping labelAt pins under ${qualityProfile}`);
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'explicit label-label clearance');
assert.deepEqual(diagnostic.evidence.conflictingPins.map(({ edge, field }) => ({ edge, field })), [
{ edge: 'one', field: 'labelAt' },
{ edge: 'two', field: 'labelAt' },
]);
if (qualityProfile === 'standard') {
assertSupportedFixesNameChangedEdge(diagnostic, ['one', 'two']);
} else {
// Moving either label alone still leaves two fully coincident fixed
// routes. The stricter v2 contract must not advertise that as a repair.
assert.deepEqual(diagnostic.supportedFixes, []);
}
assert.doesNotMatch(diagnostic.supportedFixes.join('\n'), /remove (?:one |the )?label(?!At)/i);
}
});
test('readable-v2 reports showcase crossings between two absolute route pins', () => {
const document = workflow({
lanes: [
{ id: 'top', label: 'Top' },
{ id: 'middle', label: 'Middle' },
{ id: 'bottom', label: 'Bottom' },
],
nodes: [
{ id: 'left', lane: 'middle', col: 0, type: 'backend', label: 'Left' },
{ id: 'right', lane: 'middle', col: 4, type: 'backend', label: 'Right' },
{ id: 'above', lane: 'top', col: 2, type: 'backend', label: 'Above' },
{ id: 'below', lane: 'bottom', col: 2, type: 'backend', label: 'Below' },
],
edges: [
{ id: 'horizontal', from: 'left', to: 'right', via: [[250, 243]] },
{ id: 'vertical', from: 'above', to: 'below', via: [[334, 200]] },
],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'showcase' });
assertExplicitPinConflict(result, 'two crossing absolute routes');
const [diagnostic] = result.diagnostics;
assert.equal(diagnostic.evidence.invariant, 'explicit route-route crossing');
assert.deepEqual(diagnostic.evidence.point, [334, 243]);
assertSupportedFixesNameChangedEdge(diagnostic, ['horizontal', 'vertical']);
assert.ok(
diagnostic.supportedFixes.some((fix) => fix.includes('edge "vertical"')),
`a vertical repair must identify vertical: ${diagnostic.supportedFixes}`,
);
});
test('readable-v2 catches an automatic route crossing exactly at an authored straight-through via', () => {
const document = crossingAtForwardCollinearViaWorkflow();
const standard = compileWorkflow({ workflow: clone(document), qualityProfile: 'standard' });
assert.equal(standard.ok, true, JSON.stringify(standard.diagnostics, null, 2));
assert.deepEqual(
standard.receipt.edges.find(({ id }) => id === 'z-pinned').points,
[[334, 145], [334, 243], [334, 341]],
'analysis must not remove the authored via from the receipt',
);
const result = compileWorkflow({ workflow: document, qualityProfile: 'showcase' });
assertExplicitPinConflict(result, 'an automatic route crossing at an authored straight-through via');
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/explicit-pin-conflict');
assert.equal(diagnostic.evidence.invariant, 'explicit route-route crossing');
assert.deepEqual(diagnostic.evidence.point, [334, 243]);
assert.deepEqual(diagnostic.evidence.conflictingPins, [{
edge: 'z-pinned',
field: 'via',
path: '/edges/1/via',
value: [[334, 243]],
}]);
assert.equal(diagnostic.subject.edge, 'z-pinned');
assert.equal(diagnostic.subject.path, '/edges/1/via');
assertSupportedFixesNameChangedEdge(diagnostic, ['z-pinned']);
});
test('readable-v2 catches two pinned routes crossing exactly at their straight-through vias', () => {
const document = crossingAtForwardCollinearViaWorkflow({ pinHorizontal: true });
const standard = compileWorkflow({ workflow: clone(document), qualityProfile: 'standard' });
assert.equal(standard.ok, true, JSON.stringify(standard.diagnostics, null, 2));
assert.deepEqual(
standard.receipt.edges.map(({ id, points }) => ({ id, points })),
[
{ id: 'a-pinned', points: [[140, 243], [334, 243], [528, 243]] },
{ id: 'z-pinned', points: [[334, 145], [334, 243], [334, 341]] },
],
'analysis must retain both authored straight-through vias in the receipt',
);
const result = compileWorkflow({ workflow: document, qualityProfile: 'showcase' });
assertExplicitPinConflict(result, 'two pinned routes crossing at straight-through vias');
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/explicit-pin-conflict');
assert.equal(diagnostic.evidence.invariant, 'explicit route-route crossing');
assert.deepEqual(diagnostic.evidence.point, [334, 243]);
assert.deepEqual(diagnostic.evidence.conflictingPins, [
{ edge: 'a-pinned', field: 'via', path: '/edges/0/via', value: [[334, 243]] },
{ edge: 'z-pinned', field: 'via', path: '/edges/1/via', value: [[334, 243]] },
]);
assertSupportedFixesNameChangedEdge(diagnostic, ['a-pinned', 'z-pinned']);
});
test('readable-v2 classifies a side-only authored route crossing an automatic route', () => {
const document = workflow({
lanes: ['l0', 'l1', 'l2'].map((id) => ({ id, label: id })),
nodes: [
{ id: 'n00', lane: 'l0', col: 0, type: 'backend', label: 'N00' },
{ id: 'n01', lane: 'l0', col: 1, type: 'backend', label: 'N01' },
{ id: 'n02', lane: 'l0', col: 2, type: 'backend', label: 'N02' },
{ id: 'n11', lane: 'l1', col: 1, type: 'backend', label: 'N11' },
],
edges: [
{ id: 'a-auto', from: 'n00', to: 'n01' },
{ id: 'z-side', from: 'n02', to: 'n11', fromSide: 'top', toSide: 'left' },
],
});
document.meta.quality_profile = 'showcase';
const result = compileWorkflow({ workflow: document });
assertExplicitPinConflict(result, 'side-only route crossing an automatic route');
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'explicit route-route crossing');
assert.ok(diagnostic.evidence.conflictingPins.length > 0);
assert.ok(diagnostic.evidence.conflictingPins.every(({ edge, field, path, value }) => (
edge === 'z-side'
&& ['fromSide', 'toSide'].includes(field)
&& path === `/edges/1/${field}`
&& value === document.edges[1][field]
)), JSON.stringify(diagnostic.evidence.conflictingPins, null, 2));
assert.ok(diagnostic.supportedFixes.length > 0, JSON.stringify(diagnostic, null, 2));
for (const fix of diagnostic.supportedFixes) {
const removal = fix.match(/^remove (fromSide|toSide)(?: and (fromSide|toSide))? from edge "z-side" /);
assert.ok(removal, `supported fix must be a concrete side-pin removal: ${fix}`);
const repaired = clone(document);
for (const field of removal.slice(1).filter(Boolean)) delete repaired.edges[1][field];
const verified = compileWorkflow({ workflow: repaired });
assert.equal(verified.ok, true, `advertised side-pin repair must recompile: ${fix}\n${JSON.stringify(verified.diagnostics, null, 2)}`);
}
});
test('readable-v2 classifies a side-only authored route sharing an automatic corridor', () => {
const document = workflow({
lanes: ['l0', 'l1', 'l2'].map((id) => ({ id, label: id })),
nodes: [
{ id: 'n00', lane: 'l0', col: 0, type: 'backend', label: 'N00' },
{ id: 'n02', lane: 'l0', col: 2, type: 'backend', label: 'N02' },
{ id: 'n01', lane: 'l0', col: 1, type: 'backend', label: 'N01' },
{ id: 'n03', lane: 'l0', col: 3, type: 'backend', label: 'N03' },
],
edges: [
{ id: 'a-auto', from: 'n00', to: 'n02' },
{ id: 'z-side', from: 'n01', to: 'n03', fromSide: 'bottom', toSide: 'top' },
],
});
document.meta.quality_profile = 'showcase';
const result = compileWorkflow({ workflow: document });
assertExplicitPinConflict(result, 'side-only route sharing an automatic corridor');
const diagnostic = result.diagnostics[0];
assert.equal(diagnostic.evidence.invariant, 'explicit route-route corridor clearance');
assert.deepEqual(diagnostic.evidence.overlapStart, [218, 161]);
assert.deepEqual(diagnostic.evidence.overlapEnd, [342, 161]);
assert.equal(diagnostic.evidence.overlapLengthPx, 124);
assert.ok(diagnostic.evidence.conflictingPins.length > 0);
assert.ok(diagnostic.evidence.conflictingPins.every(({ edge, field, path, value }) => (
edge === 'z-side'
&& ['fromSide', 'toSide'].includes(field)
&& path === `/edges/1/${field}`
&& value === document.edges[1][field]
)), JSON.stringify(diagnostic.evidence.conflictingPins, null, 2));
assert.ok(diagnostic.supportedFixes.length > 0, JSON.stringify(diagnostic, null, 2));
for (const fix of diagnostic.supportedFixes) {
const removal = fix.match(/^remove (fromSide|toSide)(?: and (fromSide|toSide))? from edge "z-side" /);
assert.ok(removal, `supported fix must be a concrete side-pin removal: ${fix}`);
const repaired = clone(document);
for (const field of removal.slice(1).filter(Boolean)) delete repaired.edges[1][field];
const verified = compileWorkflow({ workflow: repaired });
assert.equal(verified.ok, true, `advertised side-pin repair must recompile: ${fix}\n${JSON.stringify(verified.diagnostics, null, 2)}`);
}
});
test('readable-v2 routes an automatic edge clear of a preset channel', () => {
// The column gap leaves the automatic edge a corridor of its own, so it no
// longer shares the bottom channel the preset route claims.
const document = workflow({
lanes: [{ id: 'l0', label: 'l0' }, { id: 'l1', label: 'l1' }],
nodes: [
{ id: 'n00', lane: 'l0', col: 0, type: 'backend', label: 'N00' },
{ id: 'n11', lane: 'l1', col: 1, type: 'backend', label: 'N11' },
{ id: 'n01', lane: 'l0', col: 1, type: 'backend', label: 'N01' },
{ id: 'n02', lane: 'l0', col: 2, type: 'backend', label: 'N02' },
],
edges: [
{ id: 'a-auto', from: 'n00', to: 'n11' },
{ id: 'z-route', from: 'n01', to: 'n02', route: 'bottom-channel' },
],
});
document.meta.quality_profile = 'showcase';
const result = compileWorkflow({ workflow: document });
assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
const auto = result.receipt.edges.find(({ id }) => id === 'a-auto');
const preset = result.receipt.edges.find(({ id }) => id === 'z-route');
const presetLeft = Math.min(...preset.points.map(([x]) => x));
assert.ok(auto.points.every(([x]) => x < presetLeft), JSON.stringify({ auto: auto.points, preset: preset.points }));
});
test('readable-v2 reports unknown edge endpoints with a precise semantic diagnostic', () => {
const document = oneLaneWorkflow([{ id: 'ab', from: 'a', to: 'ghost' }]);
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
assert.equal(result.diagnostics.length, 1);
assert.equal(result.diagnostics[0].code, 'workflow/unknown-edge-endpoint');
assert.equal(result.diagnostics[0].subject.edge, 'ab');
assert.equal(result.diagnostics[0].subject.path, '/edges/0/to');
assert.deepEqual(result.diagnostics[0].evidence, {
endpoint: 'target',
unknownNodeId: 'ghost',
availableNodeIds: ['a', 'b'],
fixVerification: 'each candidate was verified by applying every listed repoint together and recompiling',
});
});
test('unknown endpoint diagnostics retain the authored edge pointer after canonical sorting', () => {
const document = oneLaneWorkflow([
{ id: 'z-valid', from: 'a', to: 'b' },
{ id: 'a-invalid', from: 'a', to: 'ghost' },
]);
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.equal(result.diagnostics.length, 1);
const [diagnostic] = result.diagnostics;
assert.equal(diagnostic.code, 'workflow/unknown-edge-endpoint');
assert.equal(diagnostic.subject.edge, 'a-invalid');
assert.equal(diagnostic.subject.path, '/edges/1/to');
assert.equal(diagnostic.evidence.endpoint, 'target');
assert.equal(diagnostic.evidence.unknownNodeId, 'ghost');
assert.ok(diagnostic.supportedFixes.length > 0);
});
test('unknown-endpoint supportedFixes list the complete verified edit set and recompile verbatim', () => {
// "ghost" is referenced from an edge AND mainPath; the verified repair
// repoints every reference to the same candidate.
const document = workflow({
lanes: [{ id: 'main', label: 'M' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' },
{ id: 'b', lane: 'main', col: 1, type: 'backend', label: 'B' },
{ id: 'c', lane: 'main', col: 2, type: 'backend', label: 'C' },
],
edges: [
{ id: 'ab', from: 'a', to: 'ghost' },
{ id: 'bc', from: 'b', to: 'c' },
{ id: 'ac', from: 'a', to: 'c' },
],
});
document.mainPath = ['a', 'ghost', 'c'];
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
const diagnostic = result.diagnostics.find((entry) => entry.code === 'workflow/unknown-edge-endpoint');
assert.ok(diagnostic);
const fixesByCandidate = new Map();
for (const fix of diagnostic.supportedFixes) {
const match = fix.match(/^set (\S+) to verified node id "([^"]+)"$/);
assert.ok(match, `fix must be executable verbatim: ${fix}`);
if (!fixesByCandidate.has(match[2])) fixesByCandidate.set(match[2], []);
fixesByCandidate.get(match[2]).push(match[1]);
}
assert.ok(fixesByCandidate.size > 0, 'expected at least one verified candidate');
for (const [nodeId, pointers] of fixesByCandidate) {
assert.ok(pointers.includes('/edges/0/to'), `candidate "${nodeId}" must cover the edge reference`);
assert.ok(pointers.includes('/mainPath/1'), `candidate "${nodeId}" must cover the mainPath reference`);
assert.equal(pointers.length, 2);
const repaired = clone(document);
for (const pointer of pointers) {
const segments = pointer.split('/').filter(Boolean);
let target = repaired;
for (const segment of segments.slice(0, -1)) target = target[segment];
target[segments.at(-1)] = nodeId;
}
const verified = compileWorkflow({ workflow: repaired });
assert.equal(verified.ok, true, `applying every suggested edit for "${nodeId}" must recompile: ${JSON.stringify(verified.diagnostics, null, 2)}`);
}
});
test('unknown node lane diagnostics retain the authored node pointer after canonical sorting', () => {
const document = oneLaneWorkflow([]);
document.nodes[0].lane = 'ghost';
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.equal(result.diagnostics.length, 1);
const [diagnostic] = result.diagnostics;
assert.equal(diagnostic.code, 'workflow/unknown-node-lane');
assert.equal(diagnostic.subject.node, 'a');
assert.equal(diagnostic.subject.path, '/nodes/0/lane');
assert.deepEqual(diagnostic.evidence, {
unknownLaneId: 'ghost',
availableLaneIds: ['main'],
});
assert.ok(diagnostic.supportedFixes.length > 0);
});
for (const fixture of [
{
name: 'lane id',
code: 'workflow/duplicate-lane-id',
expectedSubject: { lane: 'main', path: '/lanes/1/id' },
expectedEvidence: {
duplicateLaneId: 'main',
firstPath: '/lanes/0/id',
duplicatePath: '/lanes/1/id',
},
mutate(document) {
document.lanes.push({ id: 'main', label: 'Duplicate Main' });
},
},
{
name: 'node id',
code: 'workflow/duplicate-node-id',
expectedSubject: { node: 'a', path: '/nodes/2/id' },
expectedEvidence: {
duplicateNodeId: 'a',
firstPath: '/nodes/0/id',
duplicatePath: '/nodes/2/id',
},
mutate(document) {
document.nodes.push({
id: 'a', lane: 'main', col: 4, type: 'database', label: 'Duplicate A',
});
},
},
]) {
test(`duplicate ${fixture.name} diagnostics name both authored source pointers`, () => {
const document = oneLaneWorkflow([]);
fixture.mutate(document);
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.equal(result.diagnostics.length, 1);
const [diagnostic] = result.diagnostics;
assert.equal(diagnostic.code, fixture.code);
assert.deepEqual(
diagnostic.subject,
{ diagramType: 'workflow', ...fixture.expectedSubject },
);
assert.deepEqual(diagnostic.evidence, fixture.expectedEvidence);
assert.ok(diagnostic.supportedFixes.length > 0);
});
}
test('showcase rejects nested authored outside-right corridors while standard permits them', () => {
const document = nestedOutsideRightCorridorWorkflow();
const standard = compileWorkflow({ workflow: clone(document), qualityProfile: 'standard' });
assert.equal(standard.ok, true, JSON.stringify(standard.diagnostics, null, 2));
const showcase = compileWorkflow({ workflow: clone(document), qualityProfile: 'showcase' });
assertExplicitPinConflict(showcase, 'nested authored outside-right corridors');
const diagnostic = showcase.diagnostics.find(({ code }) => (
code === 'workflow/explicit-pin-conflict'
));
assertSupportedFixesNameChangedEdge(diagnostic, ['inner', 'outer']);
assert.deepEqual(
diagnostic.evidence.conflictingPins.map(({ edge, field, value }) => ({ edge, field, value })),
[{ edge: 'inner', field: 'channelX', value: 800 }],
);
assert.deepEqual(diagnostic.supportedFixes, [
'remove channelX from edge "inner" so readable-v2 can replan the remaining authored route assertions',
]);
const repaired = clone(document);
delete repaired.edges.find(({ id }) => id === 'inner').channelX;
const verified = compileWorkflow({ workflow: repaired, qualityProfile: 'showcase' });
assert.equal(verified.ok, true, JSON.stringify(verified.diagnostics, null, 2));
});
test('an explicit standard profile overrides an ambient showcase profile', () => {
const document = nestedOutsideRightCorridorWorkflow();
document.meta.quality_profile = 'showcase';
const previousProfile = process.env.ARCHIFY_QUALITY_PROFILE;
try {
process.env.ARCHIFY_QUALITY_PROFILE = 'showcase';
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(
result.ok,
true,
`the explicit standard profile must win:\n${JSON.stringify(result.diagnostics, null, 2)}`,
);
assert.match(result.svg, /data-quality-profile="standard"/);
} finally {
if (previousProfile === undefined) delete process.env.ARCHIFY_QUALITY_PROFILE;
else process.env.ARCHIFY_QUALITY_PROFILE = previousProfile;
}
});
test('failed automatic routes retain diagnostics when an earlier route has a label pin', () => {
const document = oneLaneWorkflow([
{ id: 'a-pinned', from: 'a', to: 'b', label: 'Pinned', labelAt: [94, 30] },
{ id: 'z-self', from: 'b', to: 'b', label: 'Retry' },
]);
const authored = clone(document);
for (const qualityProfile of ['standard', 'showcase']) {
// The earlier label pin is valid. The unsolved route must identify itself,
// not crash while inspecting rejected candidates or blame the other edge.
const result = compileWorkflow({ workflow: document, qualityProfile });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.deepEqual(document, authored);
assert.deepEqual(result.diagnostics.map(({ code }) => code), ['workflow/solver-budget-exhausted']);
const [diagnostic] = result.diagnostics;
assert.equal(diagnostic.subject.edge, 'z-self');
assert.ok(diagnostic.evidence.candidateCount > 0);
assert.deepEqual(diagnostic.supportedFixes, [], 'do not advertise an unverified repair');
assert.deepEqual(result.receipt.diagnostics, result.diagnostics);
}
});
test('readable-v2 never advertises an unverified blocking-node repair', () => {
const document = workflow({
lanes: [{ id: 'main', label: 'Main' }],
nodes: [{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' }],
edges: [{ id: 'self', from: 'a', to: 'a' }],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/solver-budget-exhausted');
assert.ok(diagnostic, JSON.stringify(result.diagnostics, null, 2));
assert.deepEqual(result.receipt, { contract: result.receipt.contract, diagnostics: result.diagnostics });
assert.deepEqual(diagnostic.supportedFixes, []);
});
for (const { name, makeVia } of [
{
name: 'a 4px endpoint stub',
makeVia: ({ start, end }) => [
[start[0] + 4, start[1]],
[start[0] + 4, start[1] + 41],
[end[0], start[1] + 41],
],
},
{
name: 'a 12px interior turn segment',
makeVia: ({ start }) => [
[start[0] + 20, start[1]],
[start[0] + 20, start[1] + 31],
[start[0] + 32, start[1] + 31],
[start[0] + 32, start[1]],
],
},
]) {
test(`standard profile rejects ${name} as a hard route constraint`, () => {
const via = makeVia(oneLaneAnchors());
const result = compileWorkflow({
workflow: oneLaneWorkflow([{ id: 'ab', from: 'a', to: 'b', via }]),
qualityProfile: 'standard',
});
assert.equal(result.ok, false, `${name} must be invalid in standard as well as showcase`);
assert.ok(Array.isArray(result.diagnostics) && result.diagnostics.length > 0);
});
}
test('readable-v2 reports collapsed channel pins without escaping the compiler boundary', () => {
const { start } = oneLaneAnchors();
for (const pin of [
{ channelX: start[0] },
{ channelY: start[1] },
]) {
let result;
assert.doesNotThrow(() => {
result = compileWorkflow({
workflow: oneLaneWorkflow([{ id: 'ab', from: 'a', to: 'b', ...pin }]),
qualityProfile: 'standard',
});
});
assertExplicitPinConflict(result, JSON.stringify(pin));
assert.ok(result.diagnostics.some(({ evidence }) => (
evidence?.invariant === 'non-zero route segments'
)));
}
});
test('parallel anonymous edges remain byte-deterministic when their input order changes', () => {
const document = oneLaneWorkflow([
{ from: 'a', to: 'b', variant: 'default', role: 'main' },
{ from: 'a', to: 'b', variant: 'dashed', role: 'async' },
]);
const reordered = clone(document);
reordered.edges.reverse();
const first = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
const second = compileWorkflow({ workflow: reordered, qualityProfile: 'standard' });
assert.equal(first.ok, true, JSON.stringify(first.diagnostics, null, 2));
assert.equal(second.ok, true, JSON.stringify(second.diagnostics, null, 2));
assert.equal(second.svg, first.svg);
assert.equal(JSON.stringify(second.receipt), JSON.stringify(first.receipt));
});
test('compileWorkflow returns a diagnostic result instead of throwing when meta is absent', () => {
const document = oneLaneWorkflow([]);
delete document.meta;
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.ok(Array.isArray(result.diagnostics) && result.diagnostics.length > 0);
});
test('compileWorkflow returns typed failures for non-document public inputs without throwing', () => {
for (const input of [undefined, null, [], {}]) {
const result = compileWorkflow({ workflow: input });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.ok(Array.isArray(result.diagnostics) && result.diagnostics.length > 0);
assert.ok(result.diagnostics.every(({ code }) => code !== 'internal/unclassified'));
assert.ok(result.diagnostics.every(({ supportedFixes }) => (
Array.isArray(supportedFixes) && supportedFixes.length === 0
)));
assert.deepEqual(result.receipt.diagnostics, result.diagnostics);
}
});
test('compileWorkflow enforces the canonical workflow schema at its public boundary', () => {
for (const { expectedCode, mutate, qualityProfile } of [
{ expectedCode: 'schema/additionalProperties', mutate: (document) => { document.unsupported = true; } },
{ expectedCode: 'schema/enum', mutate: (document) => { document.nodes[0].type = 'bogus'; } },
{ expectedCode: 'schema/minimum', mutate: (document) => { document.nodes[0].width = 31; } },
{ expectedCode: 'schema/required', mutate: (document) => { delete document.nodes[0].label; } },
{ expectedCode: 'schema/enum', mutate: () => {}, qualityProfile: 'impossible' },
]) {
const document = oneLaneWorkflow([]);
mutate(document);
const result = compileWorkflow({ workflow: document, qualityProfile });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.ok(
result.diagnostics.some(({ code }) => code === expectedCode),
JSON.stringify(result.diagnostics, null, 2),
);
assert.ok(result.diagnostics.every(({ code }) => code !== 'internal/unclassified'));
assert.ok(result.diagnostics.every(({ supportedFixes }) => (
Array.isArray(supportedFixes) && supportedFixes.length === 0
)));
assert.deepEqual(result.receipt, { contract: result.receipt.contract, diagnostics: result.diagnostics });
}
});
function validationParityWorkflow() {
return workflow({
lanes: [{ id: 'main', label: 'Main' }],
nodes: ['a', 'b', 'c'].map((id, index) => ({
id, lane: 'main', col: index * 2, type: 'backend', label: id,
})),
edges: [
{ id: 'first', from: 'a', to: 'b' },
{ id: 'second', from: 'b', to: 'c' },
],
});
}
test('compileWorkflow applies the shared cross-collection contracts the renderer enforces', (t) => {
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-compiler-parity-'));
t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
for (const { expectedCode, mutate } of [
{
expectedCode: 'relationship/duplicate-id',
mutate: (document) => { document.edges[1].id = document.edges[0].id; },
},
]) {
const document = validationParityWorkflow();
mutate(document);
const input = path.join(directory, 'input.json');
fs.writeFileSync(input, JSON.stringify(document));
const rendered = spawnSync(process.execPath, [
fileURLToPath(new URL('../archify/renderers/workflow/render-workflow.mjs', import.meta.url)),
input, path.join(directory, 'output.html'),
], {
encoding: 'utf8',
env: { ...process.env, ARCHIFY_DIAGNOSTIC_FORMAT: 'json', ARCHIFY_QUALITY_PROFILE: 'standard' },
});
assert.equal(rendered.status, 1, rendered.stderr);
assert.deepEqual(JSON.parse(rendered.stderr).diagnostics.map(({ code }) => code), [expectedCode]);
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.equal(result.receipt.contract, 'readable-v2');
assert.deepEqual(
result.diagnostics.map(({ code }) => code),
[expectedCode],
JSON.stringify(result.diagnostics, null, 2),
);
assert.ok(result.diagnostics.every(({ code }) => code !== 'internal/unclassified'));
assert.ok(result.diagnostics.every(({ supportedFixes }) => (
Array.isArray(supportedFixes) && supportedFixes.length === 0
)));
assert.deepEqual(result.receipt.diagnostics, result.diagnostics);
}
});
test('readable-v2 rejects a negative absolute label pin without an explicit viewBox', () => {
const document = oneLaneWorkflow([{
id: 'ab', from: 'a', to: 'b', label: 'pinned', labelAt: [-20, 80],
}]);
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
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/explicit-pin-conflict');
assert.deepEqual(diagnostic.subject, {
diagramType: 'workflow',
edge: 'ab',
from: 'a',
to: 'b',
path: '/edges/0/labelAt',
});
assert.equal(diagnostic.evidence.invariant, 'viewBox-origin containment');
assert.deepEqual(diagnostic.evidence.conflictingPins, [{
edge: 'ab',
field: 'labelAt',
path: '/edges/0/labelAt',
value: [-20, 80],
}]);
assert.deepEqual(diagnostic.evidence.offendingRect, {
x: -39.4,
y: 70,
width: 38.8,
height: 14,
});
assert.deepEqual(result.receipt.diagnostics, result.diagnostics);
assert.ok(diagnostic.supportedFixes.length > 0);
for (const fix of diagnostic.supportedFixes) {
const repaired = clone(document);
const target = repaired.edges.find(({ id }) => fix.includes(`edge "${id}"`));
assert.ok(target, `supported fix must name an existing edge: ${fix}`);
const replacement = fix.match(/^set labelAt on edge "[^"]+" to \[(-?\d+(?:\.\d+)?), (-?\d+(?:\.\d+)?)\]$/);
if (replacement) {
target.labelAt = replacement.slice(1).map(Number);
} else {
assert.match(fix, /^remove labelAt from edge "[^"]+" /);
delete target.labelAt;
}
const verified = compileWorkflow({ workflow: repaired, qualityProfile: 'standard' });
assert.equal(verified.ok, true, `advertised fix must recompile: ${fix}\n${JSON.stringify(verified.diagnostics, null, 2)}`);
}
});
test('readable-v2 rejects an explicit channel that crosses the measured legend', () => {
const document = oneLaneWorkflow([{
id: 'ab',
from: 'a',
to: 'b',
route: 'bottom-channel',
channelY: 200,
fromSide: 'bottom',
toSide: 'bottom',
}]);
document.meta.legend = { mode: 'all' };
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assertExplicitPinConflict(result, 'legend-crossing channelY');
assert.ok(result.diagnostics.some(({ evidence }) => evidence?.invariant === 'legend clearance'));
});
test('readable-v2 explicit-pin diagnostics name the first intersected node and segment', () => {
const document = workflow({
lanes: [{ id: 'main', label: 'Main' }],
nodes: [
{ id: 'a', lane: 'main', col: 0, type: 'backend', label: 'A' },
{ id: 'obstacle', lane: 'main', col: 1, type: 'database', label: 'Obstacle' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
],
edges: [{
id: 'ab',
from: 'a',
to: 'b',
fromSide: 'right',
toSide: 'left',
via: [[200, 119], [260, 119]],
}],
});
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assertExplicitPinConflict(result, 'unrelated node collision');
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/explicit-pin-conflict');
assert.equal(diagnostic.evidence.invariant, 'node clearance');
assert.deepEqual({
obstacleNode: diagnostic.evidence.obstacleNode,
obstacleRole: diagnostic.evidence.obstacleRole,
segmentIndex: diagnostic.evidence.segmentIndex,
from: diagnostic.evidence.from,
to: diagnostic.evidence.to,
clearancePx: diagnostic.evidence.clearancePx,
}, {
obstacleNode: 'obstacle',
obstacleRole: 'unrelated',
segmentIndex: 0,
from: [140, 119],
to: [200, 119],
clearancePx: 2,
});
});
test('fixed-v1 publishes only repairs that survive complete replanning', () => {
const document = {
schema_version: 1,
diagram_type: 'workflow',
meta: {
title: 'Verified fixes', output: 'verified-fixes.html', legend: { mode: 'hidden' },
},
lanes: [{ id: 'main', label: 'Main' }],
groups: [{ id: 'target-only', label: 'Target', lane: 'main', fromCol: 2, toCol: 2 }],
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 = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
const diagnostic = result.diagnostics.find(({ code }) => code === 'workflow/column-capacity');
assert.ok(diagnostic);
assert.ok(
diagnostic.supportedFixes.every((fix) => !/^move node /.test(fix)),
`moving the group's only node must not be advertised as verified: ${diagnostic.supportedFixes}`,
);
});
test('fixed-v1 verifies the exact serialized values in every rounded-width repair', () => {
const document = {
schema_version: 1,
diagram_type: 'workflow',
meta: {
title: 'Rounded verified widths', output: 'rounded-verified-widths.html', legend: { mode: 'hidden' },
},
lanes: [{ id: 'main', label: 'M' }],
nodes: [
{ id: 'a', lane: 'main', col: 1, type: 'backend', label: 'A', width: 52.006 },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B', width: 51.995 },
],
edges: [{ id: 'ab', from: 'a', to: 'b' }],
};
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
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/column-capacity');
assert.deepEqual(diagnostic.evidence.nodeWidthsPx, [52.006, 51.995]);
assert.ok(diagnostic.supportedFixes.length > 0);
assert.ok(
diagnostic.supportedFixes.includes('set node widths "a"=52px and "b"=51.99px'),
JSON.stringify(diagnostic.supportedFixes, null, 2),
);
for (const fix of diagnostic.supportedFixes) {
const repaired = clone(document);
if (fix === 'migrate this workflow to schema_version 2') {
repaired.schema_version = 2;
} else {
const move = fix.match(/^move node "([^"]+)" to verified free column (\d+)$/);
const widths = [...fix.matchAll(/"([^"]+)"=([\d.]+)px/g)];
if (move) {
repaired.nodes.find(({ id }) => id === move[1]).col = Number(move[2]);
} else {
assert.ok(widths.length > 0, `unsupported advertised repair: ${fix}`);
for (const [, nodeId, width] of widths) {
repaired.nodes.find(({ id }) => id === nodeId).width = Number(width);
}
}
}
const verified = compileWorkflow({ workflow: repaired, qualityProfile: 'standard' });
assert.equal(
verified.ok,
true,
`advertised fix must recompile: ${fix}\n${JSON.stringify(verified.diagnostics, null, 2)}`,
);
}
});
function rejectedLabelWorkflow() {
const document = oneLaneWorkflow([{
id: 'ab', from: 'a', to: 'b', label: 'send', labelAt: [88, 119],
}]);
document.schema_version = 1;
document.meta.quality_profile = 'showcase';
return document;
}
const rejectedLabelDiagnostic = {
code: 'layout/constraint', severity: 'error',
message: 'Label "send" overlaps node "a" — adjust labelDx/labelDy/labelSegment or set labelAt.\n label rect: [73, 109, 30, 14]\n node "a" rect: [42, 93, 92, 52]\n Suggested fix: set labelAt [88, 159] (below); or set labelAt [88, 85] (above)',
subject: { diagramType: 'workflow' }, evidence: {}, supportedFixes: [],
};
test('rejected layout receipt retains complete fixed-v1 geometry and authored label coordinates', () => {
const document = rejectedLabelWorkflow();
const original = clone(document);
for (const collection of [document.lanes, document.nodes, document.edges]) {
collection.forEach(Object.freeze);
Object.freeze(collection);
}
Object.freeze(document);
const result = compileWorkflow({ workflow: document });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.deepEqual(result.diagnostics, [rejectedLabelDiagnostic]);
assert.equal(result.receipt.ok, false);
assert.deepEqual(result.receipt.diagnostics, result.diagnostics);
assert.equal(result.receipt.nodes.length, 2);
assert.deepEqual(result.receipt.nodes[0], {
id: 'a', lane: 'main', col: 0, x: 42, y: 93, width: 92, height: 52,
});
assert.deepEqual(result.receipt.edges, [{
id: 'ab', from: 'a', to: 'b', points: [[134, 119], [254, 119]],
}]);
assert.deepEqual(result.receipt.labels, [{
edge: 'ab', label: 'send', x: 88, y: 119, width: 30, height: 14,
}]);
assert.deepEqual(document, original);
assert.equal(compileWorkflow({ workflow: oneLaneWorkflow([]) }).ok, true);
assert.deepEqual(compileWorkflow({ workflow: document }).receipt, result.receipt);
});
test('rejected layout CLI receipt preserves failure diagnostics and writes no HTML', (t) => {
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-rejected-layout-'));
t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
const input = path.join(directory, 'workflow.json');
const document = rejectedLabelWorkflow();
document.meta.output = 'must-not-write.html';
const original = JSON.stringify(document);
fs.writeFileSync(input, original);
const cli = fileURLToPath(new URL('../archify/bin/archify.mjs', import.meta.url));
for (const flags of [['--layout-json'], ['--layout-json', '--json']]) {
const result = spawnSync(process.execPath, [cli, 'validate', 'workflow', input, ...flags], {
encoding: 'utf8', cwd: directory,
});
assert.equal(result.status, 1, result.stdout + result.stderr);
assert.equal(result.stderr, '');
const receipt = JSON.parse(result.stdout);
assert.equal(receipt.ok, false);
assert.deepEqual(receipt.diagnostics, [rejectedLabelDiagnostic]);
assert.equal(receipt.nodes.length, 2);
assert.equal(receipt.edges.length, 1);
assert.deepEqual(receipt.labels[0], {
edge: 'ab', label: 'send', x: 88, y: 119, width: 30, height: 14,
});
assert.equal(fs.readFileSync(input, 'utf8'), original);
assert.deepEqual(fs.readdirSync(directory), ['workflow.json']);
}
});
test('rejected layout receipt retains the attempted readable-v2 frame and measured required frame', () => {
const document = oneLaneWorkflow([{ id: 'ab', from: 'a', to: 'b', label: 'send' }]);
document.meta.viewBox = [700, 300];
document.nodes[1].col = 5;
document.nodes[0].width = 200;
document.nodes[1].width = 200;
const result = compileWorkflow({ workflow: document, qualityProfile: 'standard' });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.deepEqual(result.diagnostics.map(({ code }) => code), ['workflow/viewbox-capacity']);
assert.equal(result.receipt.ok, false);
assert.deepEqual(result.receipt.viewBox, document.meta.viewBox);
assert.deepEqual(result.receipt.requiredViewBox, result.diagnostics[0].evidence.requiredViewBox);
assert.ok(result.receipt.requiredViewBox[0] > result.receipt.viewBox[0]);
assert.equal(result.receipt.nodes.length, document.nodes.length);
assert.equal(result.receipt.edges.length, document.edges.length);
assert.equal(result.receipt.labels.length, 1);
assertOrthogonal(result.receipt.edges[0].points);
});
test('early causal failures retain diagnostic-only receipts after a complete rejected layout', () => {
compileWorkflow({ workflow: rejectedLabelWorkflow() });
for (const document of [
{ ...oneLaneWorkflow([]), semanticChecks: { allowedRoots: ['missing'] } },
oneLaneWorkflow([{ id: 'unknown', from: 'a', to: 'missing' }]),
{ ...rejectedLabelWorkflow(), nodes: [
{ id: 'a', lane: 'main', col: 1, type: 'backend', label: 'A' },
{ id: 'b', lane: 'main', col: 2, type: 'backend', label: 'B' },
] },
]) {
const result = compileWorkflow({ workflow: document });
assert.equal(result.ok, false);
assert.deepEqual(result.receipt, { contract: result.receipt.contract, diagnostics: result.diagnostics });
}
});
test('rejected layout receipt belongs to the selected best route-order attempt', (t) => {
// K3,3 cannot be drawn without a crossing or shared corridor. A better
// automatic route may change the failure, but cannot make this graph planar.
// This keeps receipt/diagnostic binding covered without freezing an avoidable
// routing failure that a later planner can legitimately solve.
const document = workflow({
lanes: [0, 1, 2].map(index => ({ id: `l${index}`, label: `Lane ${index}` })),
nodes: [0, 1, 2].flatMap(index => ['a', 'b'].map(side => ({
id: `${side}${index}`, lane: `l${index}`, col: side === 'a' ? 0 : 3,
width: 140, type: 'backend', label: `${side}${index}`,
}))),
edges: [0, 1, 2].flatMap(from => [0, 1, 2].map(to => ({
id: `e${from}${to}`, from: `a${from}`, to: `b${to}`,
}))),
});
document.meta.quality_profile = 'showcase';
const original = clone(document);
const result = compileWorkflow({ workflow: document });
assert.equal(result.ok, false);
assert.equal(result.receipt.ok, false);
assert.ok(result.diagnostics.length > 0);
assert.equal(result.receipt.nodes.length, document.nodes.length);
assert.equal(result.receipt.edges.length, document.edges.length);
for (const diagnostic of result.diagnostics) {
assert.ok(['composition/proper-crossing', 'composition/ambiguous-corridor'].includes(diagnostic.code));
const first = result.receipt.edges.find(({ id }) => id === diagnostic.subject.id).points;
const other = result.receipt.edges.find(({ id }) => id === diagnostic.evidence.otherRelationship.id).points;
const [a, b] = first.slice(diagnostic.evidence.segmentIndex, diagnostic.evidence.segmentIndex + 2);
const [c, d] = other.slice(diagnostic.evidence.otherSegmentIndex, diagnostic.evidence.otherSegmentIndex + 2);
if (diagnostic.code === 'composition/proper-crossing') {
const [horizontal, vertical] = a[1] === b[1] ? [[a, b], [c, d]] : [[c, d], [a, b]];
const crossing = [vertical[0][0], horizontal[0][1]];
assert.deepEqual(crossing, diagnostic.evidence.point);
assert.ok(crossing[0] > Math.min(horizontal[0][0], horizontal[1][0])
&& crossing[0] < Math.max(horizontal[0][0], horizontal[1][0]));
assert.ok(crossing[1] > Math.min(vertical[0][1], vertical[1][1])
&& crossing[1] < Math.max(vertical[0][1], vertical[1][1]));
} else {
const axis = a[1] === b[1] ? 0 : 1;
assert.equal(c[1 - axis], d[1 - axis]);
assert.equal(a[1 - axis], c[1 - axis]);
const low = Math.max(Math.min(a[axis], b[axis]), Math.min(c[axis], d[axis]));
const high = Math.min(Math.max(a[axis], b[axis]), Math.max(c[axis], d[axis]));
assert.ok(high > low);
assert.equal(high - low, diagnostic.evidence.overlapLengthPx);
const expectedFrom = [...a], expectedTo = [...a];
expectedFrom[axis] = low;
expectedTo[axis] = high;
assert.deepEqual(diagnostic.evidence.from, expectedFrom);
assert.deepEqual(diagnostic.evidence.to, expectedTo);
}
}
assert.deepEqual(document, original);
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-selected-workflow-attempt-'));
t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
const input = path.join(directory, 'workflow.json');
const inputBytes = JSON.stringify(document);
fs.writeFileSync(input, inputBytes);
const cli = fileURLToPath(new URL('../archify/bin/archify.mjs', import.meta.url));
const failures = [[], ['--layout-json']].map((flags) => {
const validation = spawnSync(process.execPath, [
cli, 'validate', 'workflow', input, '--quality', 'showcase', '--json', ...flags,
], { encoding: 'utf8', cwd: directory });
assert.equal(validation.status, 1, validation.stdout + validation.stderr);
assert.equal(validation.stderr, '');
const failure = JSON.parse(validation.stdout);
assert.equal(failure.ok, false);
assert.equal(fs.readFileSync(input, 'utf8'), inputBytes);
assert.deepEqual(fs.readdirSync(directory), ['workflow.json']);
return failure;
});
// Both public views must describe the selected routes. Discarded attempts
// cannot contribute a repair target absent from the returned layout.
assert.deepEqual(failures[1].diagnostics, result.diagnostics);
assert.deepEqual(failures[0].diagnostics, failures[1].diagnostics);
});
test('rejected fixed-v1 label overflow reports its footprint without changing the attempted canvas', () => {
const document = rejectedLabelWorkflow();
document.edges[0].labelAt = [760, 220];
const result = compileWorkflow({ workflow: document });
assert.equal(result.ok, false);
assert.equal(result.svg, undefined);
assert.equal(result.receipt.ok, false);
assert.equal(result.receipt.viewBox[0], 720);
// 760px anchor + half the 30px mask + the existing 16px canvas margin.
assert.equal(result.receipt.requiredViewBox[0], 791);
assert.deepEqual(result.receipt.labels[0], {
edge: 'ab', label: 'send', x: 760, y: 220, width: 30, height: 14,
});
assert.equal(result.diagnostics[0].code, 'layout/constraint');
assert.match(result.diagnostics[0].message, /composition\/label-canvas-containment.*right edge by 55px/);
});