Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix(dataflow): re-plan a crossing unpinned showcase flow on a clear detour

tt-a1i2a2beada2493
diff --git a/archify/renderers/dataflow/render-dataflow.mjs b/archify/renderers/dataflow/render-dataflow.mjs
index f792b7ef..00b9bee9 100644
--- a/archify/renderers/dataflow/render-dataflow.mjs
+++ b/archify/renderers/dataflow/render-dataflow.mjs
@@ -9,6 +9,7 @@ import { brandLabelFitWidth, brandMarkFor, brandMetadataFor, brandTopRailProblem
import { translateMessage as i18nText } from '../shared/i18n.mjs';
import { minimumReadableSourceTextPx } from '../shared/desktop-readability.mjs';
import { placeAutomaticLabels } from '../shared/automatic-labels.mjs';
+import { shortestOrthogonalGridRoute } from '../shared/route-quality.mjs';
import {
asArray,
isFinitePoint,
@@ -40,7 +41,8 @@ import {
componentFill,
componentText,
arrowClassMap,
- edgeLabelAccent
+ edgeLabelAccent,
+ properSegmentIntersection
} from '../shared/geometry.mjs';
const nodeTextFit = {
@@ -481,6 +483,72 @@ function pathFor(flow) {
return routed;
}
+// The preset auto routes are planned one flow at a time and know nothing of
+// each other, so a flow skipping a stage can cut straight through a vertical
+// flow inside that stage. The showcase gate rejects every proper crossing, so
+// for an unpinned showcase draft a crossing auto route is re-planned on the
+// shared obstacle grid with every unrelated flow treated as a wall. The
+// detour is used only when it crosses nothing; otherwise the preset route and
+// its crossing diagnostic stay.
+if (automaticShowcase) {
+ const routable = asArray(dataflow.flows).filter(flow => nodes.has(flow.from) && nodes.has(flow.to));
+ const segmentsOf = points => points.slice(1).map((end, index) => ({ start: points[index], end }));
+ const related = (left, right) => [left.from, left.to].some(id => id === right.from || id === right.to);
+ const crosses = (left, right) => segmentsOf(pathFor(left).points).some(a => segmentsOf(pathFor(right).points).some(b => (
+ properSegmentIntersection(a.start, a.end, b.start, b.end))));
+ const pinned = flow => flow.via || (flow.route && flow.route !== 'auto') || flow.channelX !== undefined || flow.channelY !== undefined;
+ const unrelated = flow => routable.filter(other => other !== flow && !related(flow, other));
+ const length = points => segmentsOf(points).reduce((sum, { start, end }) => sum + Math.abs(end[0] - start[0]) + Math.abs(end[1] - start[1]), 0);
+ const DETOUR_NODE_GAP = 12;
+ function detourFor(flow) {
+ const { points } = pathFor(flow);
+ const { fromSide, toSide } = flowSides(flow);
+ const others = unrelated(flow);
+ const detour = shortestOrthogonalGridRoute({
+ start: points[0],
+ end: points.at(-1),
+ points: [points[0], points.at(-1)],
+ // Keep a detour a readable gap away from the nodes it passes; only its
+ // own endpoints are held to the grid's 2-unit clearance.
+ obstacles: [...nodes.values()].map(node => (node.id === flow.from || node.id === flow.to ? node : {
+ x: node.x - DETOUR_NODE_GAP, y: node.y - DETOUR_NODE_GAP,
+ width: node.width + DETOUR_NODE_GAP * 2, height: node.height + DETOUR_NODE_GAP * 2,
+ })),
+ fromSide,
+ toSide,
+ clearance: 2,
+ maximumObstacleCount: 80,
+ endpointStubPx: 24,
+ maximumGridNodes: 4096,
+ avoidedSegments: others.flatMap(other => segmentsOf(pathFor(other).points)),
+ allowAvoidedCrossings: false,
+ minimumAvoidedOverlapPx: 8,
+ routeSeparationPx: 8,
+ minimumSegmentPx: 16,
+ bendPenaltyPx: 48,
+ });
+ if (!detour) return null;
+ const normalized = normalizeRoutePoints(detour.points);
+ return { flow, routed: { d: polylinePath(normalized), points: normalized }, cost: length(normalized) - length(points) };
+ }
+ // Of the flows in a crossing, re-plan the one whose clear detour adds the
+ // least length, so a short straight flow is not bent around a long one.
+ for (let pass = 0; pass < routable.length; pass += 1) {
+ const crossing = routable.filter(flow => !pinned(flow) && unrelated(flow).some(other => crosses(flow, other)));
+ const options = crossing.map(detourFor).filter(Boolean).sort((left, right) => left.cost - right.cost);
+ const before = routable.filter(flow => unrelated(flow).some(other => crosses(flow, other))).length;
+ const chosen = options.find(({ flow, routed }) => {
+ const previous = pathCache.get(flow);
+ pathCache.set(flow, routed);
+ const after = routable.filter(other => unrelated(other).some(next => crosses(other, next))).length;
+ if (after < before) return true;
+ pathCache.set(flow, previous);
+ return false;
+ });
+ if (!chosen) break;
+ }
+}
+
const resolvedLabelPoints = new Map();
const twoLineOcclusions = new Set();
const initialLabelRects = asArray(dataflow.flows).flatMap((flow, relationIndex) => {
diff --git a/test/dataflow-first-draft-crossing.test.mjs b/test/dataflow-first-draft-crossing.test.mjs
new file mode 100644
index 00000000..8164a041
--- /dev/null
+++ b/test/dataflow-first-draft-crossing.test.mjs
@@ -0,0 +1,69 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+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';
+
+import { properSegmentIntersection } from '../archify/renderers/shared/geometry.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..', 'archify');
+const renderer = path.join(skillRoot, 'renderers', 'dataflow', 'render-dataflow.mjs');
+const cli = path.join(skillRoot, 'bin', 'archify.mjs');
+const fixture = path.join(__dirname, 'fixtures', 'dataflow-first-draft', 'ml-features.dataflow.json');
+
+function render(diagram) {
+ const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-dataflow-first-draft-'));
+ const input = path.join(directory, 'candidate.json');
+ const output = path.join(directory, 'candidate.html');
+ fs.writeFileSync(input, JSON.stringify(diagram));
+ const result = spawnSync(process.execPath, [renderer, input, output], { cwd: directory, encoding: 'utf8' });
+ return { ...result, input, html: result.status === 0 ? fs.readFileSync(output, 'utf8') : '' };
+}
+
+const attrs = (tag) => Object.fromEntries([...tag.matchAll(/([a-zA-Z-]+)="([^"]*)"/g)].map((match) => [match[1], match[2]]));
+
+function routes(html) {
+ return [...html.matchAll(/<path\b[^>]*data-composition-points="[^"]*"[^>]*>/g)].map((match) => attrs(match[0]))
+ .filter((route) => route['data-edge-from'])
+ .map((route) => ({
+ from: route['data-edge-from'],
+ to: route['data-edge-to'],
+ points: route['data-composition-points'].split(';').map((pair) => pair.split(',').map(Number)),
+ }));
+}
+
+function properCrossings(html) {
+ const all = routes(html);
+ const crossings = [];
+ for (const [index, left] of all.entries()) {
+ for (const right of all.slice(index + 1)) {
+ if ([left.from, left.to].some((id) => id === right.from || id === right.to)) continue;
+ if (left.points.slice(1).some((end, i) => right.points.slice(1).some((otherEnd, j) => (
+ properSegmentIntersection(left.points[i], end, right.points[j], otherEnd))))) crossings.push([`${left.from}->${left.to}`, `${right.from}->${right.to}`]);
+ }
+ }
+ return crossings;
+}
+
+test('an unpinned dataflow draft re-plans a stage-skipping flow around a vertical flow instead of crossing it', () => {
+ const diagram = JSON.parse(fs.readFileSync(fixture, 'utf8'));
+ const result = render(diagram);
+ assert.equal(result.status, 0, result.stdout + result.stderr);
+ assert.ok(routes(result.html).length >= diagram.flows.length);
+ assert.deepEqual(properCrossings(result.html), []);
+ const validation = spawnSync(process.execPath, [cli, 'validate', 'dataflow', result.input, '--quality', 'showcase', '--json'], { encoding: 'utf8' });
+ assert.equal(validation.status, 0, validation.stdout + validation.stderr);
+});
+
+test('a pinned dataflow route keeps its geometry and its crossing diagnostic', () => {
+ const diagram = JSON.parse(fs.readFileSync(fixture, 'utf8'));
+ for (const flow of diagram.flows) flow.route = 'auto';
+ diagram.flows.find((flow) => flow.from === 'store' && flow.to === 'serve').route = 'straight';
+ diagram.flows.find((flow) => flow.from === 'train' && flow.to === 'registry').route = 'straight';
+ const result = render(diagram);
+ assert.notEqual(result.status, 0);
+ assert.match(result.stdout + result.stderr, /proper-crossing/);
+});
diff --git a/test/fixtures/dataflow-first-draft/README.md b/test/fixtures/dataflow-first-draft/README.md
new file mode 100644
index 00000000..9018a2ef
--- /dev/null
+++ b/test/fixtures/dataflow-first-draft/README.md
@@ -0,0 +1,9 @@
+# Dataflow first-draft regressions
+
+`ml-features.dataflow.json` is an unedited first draft written from the
+Skill's Dataflow defaults (stage/row grid, automatic routes, no viewBox). On
+`dev` its "online lookup" flow from stage 2 to stage 4 cut straight through
+the vertical "model" flow inside stage 3, and `validate --quality showcase`
+rejected the proper crossing. The test asserts that the unpinned draft now
+renders with a clear detour, and that a pinned route keeps its geometry and
+its crossing diagnostic.
diff --git a/test/fixtures/dataflow-first-draft/ml-features.dataflow.json b/test/fixtures/dataflow-first-draft/ml-features.dataflow.json
new file mode 100644
index 00000000..4fc7d0a1
--- /dev/null
+++ b/test/fixtures/dataflow-first-draft/ml-features.dataflow.json
@@ -0,0 +1,121 @@
+{
+ "schema_version": 1,
+ "diagram_type": "dataflow",
+ "meta": {
+ "title": "ML feature pipeline",
+ "locale": "en",
+ "quality_profile": "showcase",
+ "output": "ml-features.html"
+ },
+ "stages": [
+ {
+ "label": "Raw data"
+ },
+ {
+ "label": "Features"
+ },
+ {
+ "label": "Training"
+ },
+ {
+ "label": "Serving"
+ }
+ ],
+ "nodes": [
+ {
+ "id": "events",
+ "type": "database",
+ "label": "Event logs",
+ "sublabel": "S3",
+ "stage": 0,
+ "row": 0
+ },
+ {
+ "id": "crm",
+ "type": "database",
+ "label": "CRM export",
+ "sublabel": "nightly",
+ "stage": 0,
+ "row": 2
+ },
+ {
+ "id": "fe",
+ "type": "backend",
+ "label": "Feature jobs",
+ "sublabel": "Spark",
+ "stage": 1,
+ "row": 1
+ },
+ {
+ "id": "store",
+ "type": "database",
+ "label": "Feature store",
+ "sublabel": "online + offline",
+ "stage": 1,
+ "row": 3
+ },
+ {
+ "id": "train",
+ "type": "backend",
+ "label": "Trainer",
+ "sublabel": "GPU pool",
+ "stage": 2,
+ "row": 1
+ },
+ {
+ "id": "registry",
+ "type": "database",
+ "label": "Model registry",
+ "sublabel": "versions",
+ "stage": 2,
+ "row": 3
+ },
+ {
+ "id": "serve",
+ "type": "backend",
+ "label": "Inference API",
+ "sublabel": "p99 40ms",
+ "stage": 3,
+ "row": 2
+ }
+ ],
+ "flows": [
+ {
+ "from": "events",
+ "to": "fe",
+ "label": "click logs"
+ },
+ {
+ "from": "crm",
+ "to": "fe",
+ "label": "accounts"
+ },
+ {
+ "from": "fe",
+ "to": "store",
+ "label": "write features",
+ "variant": "emphasis"
+ },
+ {
+ "from": "store",
+ "to": "train",
+ "label": "training set"
+ },
+ {
+ "from": "train",
+ "to": "registry",
+ "label": "model"
+ },
+ {
+ "from": "registry",
+ "to": "serve",
+ "label": "deploy",
+ "variant": "dashed"
+ },
+ {
+ "from": "store",
+ "to": "serve",
+ "label": "online lookup"
+ }
+ ]
+}