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
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.mjsindex 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, brandTopRailProblemimport { 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.mjsnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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"+ }+ ]+}