Skip to content

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

fix(workflow): preserve crossing diagnostics and normalize HTML analysis

sunsunsun2e01d7898d0d
diff --git a/archify.zip b/archify.zip
index 8b8459cf..e2b48471 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/renderers/shared/geometry.mjs b/archify/renderers/shared/geometry.mjs
index eaaed2b3..07f89306 100644
--- a/archify/renderers/shared/geometry.mjs
+++ b/archify/renderers/shared/geometry.mjs
@@ -590,9 +590,12 @@ export function cleanCrossingProblems({
mergeForwardCollinearWaypoints = false,
includeSharedEndpoints = () => false,
crossingResolved = () => false,
+ warnInStandard = false,
+ onDiagnostic = recordDiagnostic,
routeHint = 'adjust route/via or channel coordinates so the relationships use separate corridors'
}) {
- if (qualityProfileForGate(profile, profileIsAuthoritative) !== 'showcase') return [];
+ const severity = qualityProfileForGate(profile, profileIsAuthoritative) === 'showcase' ? 'error' : 'warning';
+ if (severity === 'warning' && !warnInStandard) return [];
const routed = asArray(relations).map((relation, index) => {
if (!relation || !endpointIds.has(relation.from) || !endpointIds.has(relation.to)) return null;
const points = pathFor(relation)?.points;
@@ -645,10 +648,10 @@ export function cleanCrossingProblems({
};
const point = hit.point.map((value) => Math.round(value * 10) / 10).join(', ');
const hint = rePlanHint([left.relation, right.relation], routeHint);
- const message = `[composition/proper-crossing] showcase ${diagramType} ${describe(left)} crosses ${describe(right)} at [${point}] (segments ${hit.leftSegment} and ${hit.rightSegment}) — ${hint}.`;
- recordDiagnostic({
+ const message = `[composition/proper-crossing] ${severity === 'error' ? 'showcase' : 'standard'} ${diagramType} ${describe(left)} crosses ${describe(right)} at [${point}] (segments ${hit.leftSegment} and ${hit.rightSegment}) — ${hint}.`;
+ onDiagnostic({
code: 'composition/proper-crossing',
- severity: 'error',
+ severity,
message,
subject: relationshipSubject(diagramType, relationCollection, left.index, left.relation),
evidence: {
@@ -659,7 +662,7 @@ export function cleanCrossingProblems({
},
supportedFixes: [hint],
});
- problems.push(message);
+ if (severity === 'error') problems.push(message);
}
}
return problems;
@@ -671,6 +674,8 @@ export function cleanCrossingProblems({
// automatic architecture routes opt in because they promise separate ports.
// Workflow v2 opts into shared-endpoint checks with a bounded terminal-trunk
// exception. Other callers keep their existing authored-junction contract.
+// The counterflow-only opt-in serves older workflow exports without a root
+// readable-v2 contract; full shared-endpoint checking takes precedence.
// Tiny overlaps below the route rhythm
// floor are ignored to avoid turning sub-pixel rounding into a quality debt.
export function collectAmbiguousCorridors({
diff --git a/archify/renderers/workflow/README.md b/archify/renderers/workflow/README.md
index a1c56056..9fb72290 100644
--- a/archify/renderers/workflow/README.md
+++ b/archify/renderers/workflow/README.md
@@ -284,6 +284,18 @@ The SVG carries `data-layout-contract="readable-v2"` and each edge's role so
artifact checks apply the same classification to actual visible path geometry,
not stale composition-point metadata. These internal output attributes do not
add authoring schema fields. Other diagram types retain their existing rules.
+V2 proper-crossing diagnostics retain the relationship IDs, intersection point,
+and supported fixes in both compiler/layout-JSON receipts and final HTML checks;
+`standard` reports warnings while `showcase` rejects the crossing. Both analyses
+merge forward-collinear waypoints without rewriting authored paths; real bends
+and reversals remain endpoint touches rather than being merged into an X.
+
+The older per-edge `data-composition-routing="workflow-v2-auto"` marker remains
+for compatibility with first-round exported HTML that has no root layout
+contract and with older artifact checkers. Marker-only artifacts retain their
+narrower automatic-pair crossing/counterflow policy; the root `readable-v2`
+contract is authoritative when present and also checks explicit routes. Do not
+remove the marker-only path as dead code without retiring that export format.
Showcase also
rejects any route segment below 8px and any interior turn segment below 16px;
ordinary 8–15px endpoint stubs remain valid for fixed lane gaps.
diff --git a/archify/renderers/workflow/workflow-compiler.mjs b/archify/renderers/workflow/workflow-compiler.mjs
index 33623da7..b372ce92 100644
--- a/archify/renderers/workflow/workflow-compiler.mjs
+++ b/archify/renderers/workflow/workflow-compiler.mjs
@@ -2454,6 +2454,8 @@ function validateWorkflow() {
profileIsAuthoritative: true,
mergeForwardCollinearWaypoints: workflow.schema_version === 2,
includeSharedEndpoints: () => workflow.schema_version === 2,
+ warnInStandard: workflow.schema_version === 2,
+ ...(workflow.schema_version === 2 ? { onDiagnostic: diagnostic => workflowDiagnostics.push(diagnostic) } : {}),
routeHint: 'adjust route/via, bias, or channel coordinates so the edges use separate lane corridors'
}));
problems.push(...cleanAmbiguousCorridorProblems({
diff --git a/archify/scripts/check-render-output.mjs b/archify/scripts/check-render-output.mjs
index ffd317e2..3c29ee2b 100644
--- a/archify/scripts/check-render-output.mjs
+++ b/archify/scripts/check-render-output.mjs
@@ -3,7 +3,7 @@
import fs from 'node:fs';
import { createHash } from 'node:crypto';
import path from 'node:path';
-import { collectAmbiguousCorridors, collectArrowheadCollisions, collectBorderRuns, collectLabelCanvasOverflow, collectLabelRouteClearance, collectRouteRhythmIssues, describeLabelCanvasOverflow, formatRect, minimumLabelRouteClearance, routeBudgetMetrics } from '../renderers/shared/geometry.mjs';
+import { collectAmbiguousCorridors, collectArrowheadCollisions, collectBorderRuns, collectLabelCanvasOverflow, collectLabelRouteClearance, collectRouteRhythmIssues, describeLabelCanvasOverflow, formatRect, forwardCollinearAnalysisSegments, minimumLabelRouteClearance, routeBudgetMetrics } from '../renderers/shared/geometry.mjs';
import {
DESKTOP_READABILITY_VIEWPORT,
DESKTOP_READER_DIAGRAM_WIDTH,
@@ -476,8 +476,9 @@ function collectArrows(fragment, useActualPoints = false) {
&& (tag[1].toLowerCase() === 'line' || /^\s*M\s+[-+\d.eE]+\s+[-+\d.eE]+\s+L\s+[-+\d.eE]+\s+[-+\d.eE]+\s*$/.test(attrs.d || '')),
crossoverHalo: verifiedCrossoverHalo,
independentPorts: verifiedCrossoverHalo && attrs['data-composition-independent'] === 'true',
- // This opt-in only tightens shared-endpoint checks. It does not certify
- // a crossover halo or exempt any existing artifact-quality rule.
+ // Compatibility with first-round exports lacking a root layout contract.
+ // Readable-v2's root contract supersedes this narrower automatic-pair rule.
+ // This marker never certifies a crossover halo or waives a quality rule.
automaticWorkflowRoute: attrs['data-composition-routing'] === 'workflow-v2-auto',
width: routeStrokeWidth,
variant: raw.match(/\ba-(default|emphasis|security|dashed)\b/)?.[1] || 'default',
@@ -566,7 +567,12 @@ function parseRoutePoints(value) {
}
function collectRelationshipCrossings(arrows, includeSharedEndpoints = false) {
- const relationships = arrows.filter((arrow) => arrow.from && arrow.to && arrow.segments.length);
+ const relationships = arrows.filter((arrow) => arrow.from && arrow.to && arrow.segments.length).map(arrow => ({
+ ...arrow,
+ // Readable-v2 routePoints come from the visible path, never its metadata.
+ // A straight-through via is not a visual endpoint; preserve real bends.
+ segments: includeSharedEndpoints ? forwardCollinearAnalysisSegments(arrow.routePoints) : arrow.segments,
+ }));
const crossings = [];
for (let leftIndex = 0; leftIndex < relationships.length; leftIndex += 1) {
const left = relationships[leftIndex];
diff --git a/archify/test/workflow-shared-trunks.test.mjs b/archify/test/workflow-shared-trunks.test.mjs
index 2c421e72..a5614cba 100644
--- a/archify/test/workflow-shared-trunks.test.mjs
+++ b/archify/test/workflow-shared-trunks.test.mjs
@@ -9,6 +9,80 @@ import { compileWorkflow } from '../renderers/workflow/workflow-compiler.mjs';
const checker = fileURLToPath(new URL('../scripts/check-render-output.mjs', import.meta.url));
+function sharedCrossingWorkflow() {
+ return {
+ schema_version: 2, diagram_type: 'workflow',
+ meta: { title: 'Shared crossing', output: 'crossing.html' },
+ 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: 2, type: 'backend', label: 'B' },
+ { id: 'c', lane: 'bottom', col: 2, type: 'backend', label: 'C' },
+ ],
+ edges: [
+ { id: 'ab', from: 'a', to: 'b', fromSide: 'bottom', toSide: 'left', via: [[94, 165], [260, 165], [260, 119]] },
+ { id: 'ac', from: 'a', to: 'c', fromSide: 'right', toSide: 'left', via: [[180, 119], [180, 243]] },
+ ],
+ };
+}
+
+test('shared crossings retain actionable diagnostics in public compilation and layout JSON', (t) => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-crossing-diagnostics-'));
+ t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+ const renderer = fileURLToPath(new URL('../renderers/workflow/render-workflow.mjs', import.meta.url));
+ for (const profile of ['standard', 'showcase']) {
+ const workflow = sharedCrossingWorkflow();
+ workflow.meta.quality_profile = profile;
+ const compiled = compileWorkflow({ workflow, qualityProfile: profile });
+ assert.equal(compiled.ok, profile === 'standard');
+ const diagnostic = compiled.receipt.diagnostics.find(d => d.code === 'composition/proper-crossing');
+ assert.ok(diagnostic, JSON.stringify(compiled.receipt.diagnostics));
+ assert.equal(diagnostic.severity, profile === 'showcase' ? 'error' : 'warning');
+ assert.equal(diagnostic.subject.id, 'ab');
+ assert.equal(diagnostic.evidence.otherRelationship.id, 'ac');
+ assert.deepEqual(diagnostic.evidence.point, [180, 165]);
+ assert.ok(diagnostic.supportedFixes.some(fix => /route\/via/.test(fix)));
+
+ const input = path.join(dir, `${profile}.workflow.json`);
+ fs.writeFileSync(input, JSON.stringify(workflow));
+ const child = spawnSync(process.execPath, [renderer, input, path.join(dir, `${profile}.html`), '--layout-json'], {
+ encoding: 'utf8', env: { ...process.env, ARCHIFY_QUALITY_PROFILE: profile },
+ });
+ assert.equal(child.status, profile === 'showcase' ? 1 : 0, child.stderr);
+ assert.deepEqual(JSON.parse(child.stdout).diagnostics, compiled.receipt.diagnostics);
+ }
+});
+
+test('workflow v2 compiler and final HTML agree on crossings at redundant via points', (t) => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-crossing-waypoints-'));
+ t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+ for (const split of ['neither', 'left', 'right', 'both']) {
+ const workflow = sharedCrossingWorkflow();
+ if (split === 'left' || split === 'both') workflow.edges[0].via.splice(1, 0, [180, 165]);
+ if (split === 'right' || split === 'both') workflow.edges[1].via.splice(1, 0, [180, 165]);
+ const compiled = compileWorkflow({ workflow, qualityProfile: 'standard' });
+ assert.equal(compiled.ok, true);
+ assert.equal(compileWorkflow({ workflow, qualityProfile: 'showcase' }).ok, false);
+ const actualGeometry = compiled.receipt.edges.map(edge => edge.points);
+ assert.deepEqual(actualGeometry[0].slice(1, -1), workflow.edges[0].via);
+ assert.deepEqual(actualGeometry[1].slice(1, -1), workflow.edges[1].via);
+
+ for (const profile of ['standard', 'showcase']) {
+ const file = path.join(dir, `${split}-${profile}.html`);
+ // Keep the generated strokes intact; only set the checker's quality profile.
+ const svg = compiled.svg.replace('data-quality-profile="standard"', `data-quality-profile="${profile}"`);
+ fs.writeFileSync(file, `<html><body>${svg}</body></html>`);
+ const checked = spawnSync(process.execPath, [checker, file], { encoding: 'utf8' });
+ const receipt = JSON.parse(checked.stdout);
+ assert.equal(checked.status, profile === 'showcase' ? 1 : 0, `${split}/${profile}`);
+ assert.equal(receipt.composition.metrics.properCrossings, 1, `${split}/${profile}`);
+ const diagnostic = receipt.composition.issues.find(d => d.code === 'composition/proper-crossing');
+ assert.deepEqual(diagnostic.point, [180, 165]);
+ assert.equal(diagnostic.severity, profile === 'showcase' ? 'error' : 'warning');
+ }
+ }
+});
+
test('workflow v2 separates long trunks without changing authored return geometry', () => {
const workflow = JSON.parse(fs.readFileSync(new URL('./fixtures/workflow-shared-trunks.workflow.json', import.meta.url)));
const result = compileWorkflow({ workflow, qualityProfile: 'showcase' });
@@ -139,6 +213,26 @@ test('workflow v2 does not exempt proper crossings between explicit paths sharin
assert.equal(result.receipt.composition.metrics.properCrossings,1);
});
+test('via crossing analysis preserves real touches and the v1 shared-endpoint contract', (t) => {
+ const arrow = (to, d) => `<path data-edge-from="a" data-edge-to="${to}" d="${d}" class="a-default" marker-end="url(#arrowhead)"/>`;
+ const vertical = arrow('c', 'M 150 40 L 150 180');
+ for (const path of [
+ 'M 40 100 L 150 100', // Endpoint touch.
+ 'M 40 100 L 150 100 L 150 180', // Real bend, not a straight-through via.
+ 'M 40 100 L 150 100 L 80 100 L 80 180', // Reversal.
+ ]) {
+ const result = checkSvg(t, arrow('b', path) + vertical);
+ assert.equal(result.receipt.composition.metrics.properCrossings, 0, path);
+ }
+ const crossing = arrow('b', 'M 40 100 L 150 100 L 220 100') + vertical;
+ const legacy = checkSvg(t, crossing, 'showcase', 'fixed-v1');
+ assert.equal(legacy.receipt.composition.metrics.properCrossings, 0);
+ const stale = crossing.replaceAll('class="a-default"', 'data-composition-points="20,20;60,20" class="a-default"');
+ const readable = checkSvg(t, stale);
+ assert.equal(readable.code, 1);
+ assert.equal(readable.receipt.composition.metrics.properCrossings, 1, 'actual strokes override stale points');
+});
+
test('compiler and artifact checks both report independent shared arrowheads', (t) => {
const workflow = {
schema_version:2, diagram_type:'workflow', meta:{title:'Pinned arrivals',output:'arrivals.html'},
diff --git a/docs/specs/workflow-routing-clarity-validation.md b/docs/specs/workflow-routing-clarity-validation.md
index ae1e01fb..13ee1a79 100644
--- a/docs/specs/workflow-routing-clarity-validation.md
+++ b/docs/specs/workflow-routing-clarity-validation.md
@@ -90,3 +90,36 @@ was actually re-recorded by the user, not merely rehashed. The distributable
`archify.zip` must be rebuilt with Node 22 from the combined tracked sources
after integrating dev's independent lifecycle fixes. Remote CI remains a
separate requirement; local success does not imply CI or maintainer approval.
+
+## PR #558 review follow-up
+
+The follow-up to reviewed head `6def29f9` fixes two reproduced P2 findings:
+
+- Shared-endpoint proper crossings now reach public compiler/layout-JSON
+ receipts as `composition/proper-crossing`, with relationship IDs, intersection
+ coordinates and supported fixes. V2 standard warnings and showcase errors
+ are both covered; v1 and other callers retain the default shared-helper policy.
+- The final HTML checker uses the same forward-collinear analysis as the
+ compiler for readable-v2. Adding a redundant via at an intersection no longer
+ hides it. Regression coverage includes splits on either/both strokes, real
+ bends, reversals, endpoint touches, stale metadata and the v1 exemption.
+
+The P3 opt-in simplification was investigated rather than applied blindly:
+first-round delivered HTML exists with only `workflow-v2-auto` edge markers and
+no root contract. The marker-only compatibility path is retained and documented
+in the workflow renderer README; the root contract remains authoritative.
+
+Both new failure reproductions were observed red before fixing. The six focused
+test files now pass 282 tests with no failures or skips. Removing diagnostic
+forwarding reproduces the empty-diagnostic failure; removing collinear analysis
+reproduces the missed crossing. Removing marker-only counterflow handling fails
+the existing legacy-export regression. Each removal was restored; no production
+mechanism was permanently deleted in this follow-up.
+
+Compared with `6def29f9`, all six previously measured fixed inputs produce
+byte-identical SVG and identical compile receipts. The three accepted frozen
+OpenPI/Maka HTML artifacts and bundled workflow example pass the revised final
+HTML checker. No route, Viewer or visual output changed, so the previous browser
+evidence is reused, not described as a new browser run. Gallery, examples and
+README animation are unchanged; only the ZIP is rebuilt from revised sources.
+The final full-suite result and revision are recorded in the PR follow-up.