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(workflow): preserve crossing diagnostics and normalize HTML analysis
sunsunsun2e01d7898d0d
diff --git a/archify.zip b/archify.zipindex 8b8459cf..e2b48471 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/renderers/shared/geometry.mjs b/archify/renderers/shared/geometry.mjsindex 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.mdindex 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 soartifact checks apply the same classification to actual visible path geometry,not stale composition-point metadata. These internal output attributes do notadd 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 alsorejects 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.mjsindex 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.mjsindex 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.mjsindex 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 sharinassert.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.mdindex 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 sourcesafter integrating dev's independent lifecycle fixes. Remote CI remains aseparate 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.