Skip to content

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

fix: harden ordinary-model visual quality gates

tt-a1i3f68bd260469
diff --git a/archify.zip b/archify.zip
index c9576556..160b03fe 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/renderers/dataflow/render-dataflow.mjs b/archify/renderers/dataflow/render-dataflow.mjs
index 078977a7..8d4defb8 100644
--- a/archify/renderers/dataflow/render-dataflow.mjs
+++ b/archify/renderers/dataflow/render-dataflow.mjs
@@ -162,6 +162,17 @@ function validateDataflow() {
const [start, end] = [routed.points[0], routed.points[routed.points.length - 1]];
const distance = Math.hypot(end[0] - start[0], end[1] - start[1]);
if (distance < 34) problems.push(`Flow "${flow.label}" is too short (${Math.round(distance)}px; minimum 34px) — route it through a channel or spread its nodes.`);
+ if (Array.isArray(flow.via)) {
+ for (let segmentIndex = 0; segmentIndex < routed.points.length - 1; segmentIndex += 1) {
+ const segmentStart = routed.points[segmentIndex];
+ const segmentEnd = routed.points[segmentIndex + 1];
+ const isDiagonal = Math.abs(segmentStart[0] - segmentEnd[0]) > 0.01
+ && Math.abs(segmentStart[1] - segmentEnd[1]) > 0.01;
+ if (!isDiagonal) continue;
+ const viaIndex = Math.min(segmentIndex, flow.via.length - 1);
+ problems.push(`Flow "${flow.label}" has a diagonal segment from (${segmentStart.join(', ')}) to (${segmentEnd.join(', ')}) — align via[${viaIndex}] with its adjacent point by sharing the same x or y coordinate.`);
+ }
+ }
}
}
diff --git a/archify/renderers/workflow/render-workflow.mjs b/archify/renderers/workflow/render-workflow.mjs
index 7bd90d5e..16f69cef 100644
--- a/archify/renderers/workflow/render-workflow.mjs
+++ b/archify/renderers/workflow/render-workflow.mjs
@@ -246,6 +246,7 @@ function validateWorkflow() {
}
}
+ const phaseRanges = [];
for (const phase of asArray(workflow.phases)) {
if (!Number.isInteger(phase.fromCol) || !Number.isInteger(phase.toCol)) {
problems.push(`Phase "${phase.id}" must use integer fromCol/toCol values.`);
@@ -253,6 +254,8 @@ function validateWorkflow() {
}
if (phase.fromCol < 0 || phase.toCol >= layout.colXs.length || phase.fromCol > phase.toCol) {
problems.push(`Phase "${phase.id}" uses invalid columns ${phase.fromCol}..${phase.toCol}; use an ordered range within 0..${layout.colXs.length - 1}.`);
+ } else {
+ phaseRanges.push(phase);
}
const estLabelW = textUnits(phase.label) * 5.6;
const width = spanForCols(phase.fromCol, phase.toCol).width;
@@ -260,6 +263,15 @@ function validateWorkflow() {
problems.push(`Phase label "${phase.label}" (~${Math.round(estLabelW)}px) is wider than its ${Math.round(width)}px span — shorten the label or widen the phase range.`);
}
}
+ phaseRanges.sort((a, b) => a.fromCol - b.fromCol || a.toCol - b.toCol);
+ for (let i = 0; i < phaseRanges.length; i += 1) {
+ for (let j = i + 1; j < phaseRanges.length; j += 1) {
+ const earlier = phaseRanges[i];
+ const later = phaseRanges[j];
+ if (later.fromCol > earlier.toCol) break;
+ problems.push(`Phase "${later.id}" (${later.fromCol}..${later.toCol}) overlaps phase "${earlier.id}" (${earlier.fromCol}..${earlier.toCol}) — start at col ${earlier.toCol + 1} or later, or end the earlier phase at col ${later.fromCol - 1}.`);
+ }
+ }
for (const group of asArray(workflow.groups)) {
if (!laneIds.has(group.lane)) {
diff --git a/archify/scripts/check-render-output.mjs b/archify/scripts/check-render-output.mjs
index 3b592725..6730dbf5 100644
--- a/archify/scripts/check-render-output.mjs
+++ b/archify/scripts/check-render-output.mjs
@@ -68,11 +68,11 @@ if (svgMatches.length === 1) {
const legendStart = svg.indexOf('<!-- Legend -->');
const beforeLegend = legendStart >= 0 ? svg.slice(0, legendStart) : svg;
const arrows = collectArrows(beforeLegend);
- const diagonal = arrows.filter((arrow) => isTwoPointDiagonal(arrow));
+ const diagonal = arrows.flatMap((arrow) => diagonalStraightSegments(arrow).map((segment) => ({ arrow, ...segment })));
addCheck(
'orthogonal_arrows',
diagonal.length === 0,
- diagonal.map((arrow) => `${arrow.kind} ${arrow.index}: ${arrow.raw}`),
+ diagonal.map(({ arrow, segmentIndex }) => `${arrow.kind} ${arrow.index} segment ${segmentIndex + 1}: ${arrow.raw}`),
);
const relationshipCrossings = collectRelationshipCrossings(arrows);
const compositionFrames = collectCompositionFrames(beforeLegend);
@@ -526,10 +526,12 @@ function straightPathSegments(d) {
return segments.filter(({ start: a, end: b }) => isPoint(a) && isPoint(b));
}
-function isTwoPointDiagonal(arrow) {
- if (arrow.segments.length !== 1) return false;
- const { start, end } = arrow.segments[0];
- return Math.abs(start[0] - end[0]) > 0.01 && Math.abs(start[1] - end[1]) > 0.01;
+function diagonalStraightSegments(arrow) {
+ return arrow.borderSegments.flatMap(({ start, end }, segmentIndex) => (
+ Math.abs(start[0] - end[0]) > 0.01 && Math.abs(start[1] - end[1]) > 0.01
+ ? [{ segmentIndex, start, end }]
+ : []
+ ));
}
function collectLegendBoxes(fragment) {
diff --git a/archify/test/layout-rules.test.mjs b/archify/test/layout-rules.test.mjs
index df085ecd..04e59767 100644
--- a/archify/test/layout-rules.test.mjs
+++ b/archify/test/layout-rules.test.mjs
@@ -76,6 +76,8 @@ const CASES = [
(d) => { d.mainPath = ['user', 'planner']; }, ['mainPath step "user" -> "planner" has no matching edge']],
['workflow: mainPath moves backward', 'workflow',
(d) => { d.mainPath = ['external', 'trace']; }, ['moves backward from col']],
+ ['workflow: phase ranges overlap', 'workflow',
+ (d) => { d.phases[2].fromCol = d.phases[1].toCol; }, ['overlaps phase', 'start at col 4 or later']],
// ---- sequence layout rules ----
['sequence: message references unknown participant', 'sequence',
@@ -90,6 +92,10 @@ const CASES = [
(d) => { delete d.flows[0].label; }, ['label']],
['dataflow: flow references unknown node', 'dataflow',
(d) => { d.flows[0].to = 'ghost'; }, ['unknown target "ghost"']],
+ ['dataflow: explicit via keeps every route segment orthogonal', 'dataflow',
+ (d) => {
+ d.flows[0].via = [[195, 140], [195, 260]];
+ }, ['diagonal segment', 'align via[0]']],
// ---- lifecycle layout rules ----
['lifecycle: missing reserved main lane', 'lifecycle',
diff --git a/archify/test/ordinary-model-floor.test.mjs b/archify/test/ordinary-model-floor.test.mjs
index c3b17f10..ffccfd76 100644
--- a/archify/test/ordinary-model-floor.test.mjs
+++ b/archify/test/ordinary-model-floor.test.mjs
@@ -475,6 +475,20 @@ test('benchmark semantic requirements bind by accepted technical labels instead
test('checked-in cases accept equivalent ordinary-model vocabulary without weakening required topology', () => {
const suiteRoot = path.join(repoRoot, 'benchmarks/ordinary-model-floor');
const fixtures = [
+ {
+ type: 'architecture',
+ example: 'web-app.architecture.json',
+ caseFile: 'web-runtime.architecture.case.json',
+ mapping: new Map([
+ ['users', 'browser-clients'], ['cdn', 'cdn-edge'], ['api', 'app-api'],
+ ['cache', 'redis-store'], ['db', 'postgres-primary'],
+ ]),
+ mutate(candidate) {
+ candidate.components.find((node) => node.id === 'browser-clients').label = 'Browser Clients';
+ candidate.components.find((node) => node.id === 'cdn-edge').label = 'CDN Edge';
+ candidate.components.find((node) => node.id === 'app-api').label = 'App API';
+ },
+ },
{
type: 'workflow',
example: 'agent-tool-call.workflow.json',
@@ -488,7 +502,7 @@ test('checked-in cases accept equivalent ordinary-model vocabulary without weake
candidate.nodes.find((node) => node.id === 'consent-check').label = 'Human Approval';
candidate.nodes.find((node) => node.id === 'tool-runner').label = 'Tool Executor';
candidate.nodes.find((node) => node.id === 'request-blocked').label = 'Denied';
- candidate.nodes.find((node) => node.id === 'service-provider').label = 'Provider API';
+ candidate.nodes.find((node) => node.id === 'service-provider').label = 'Remote API';
},
},
{
@@ -514,18 +528,19 @@ test('checked-in cases accept equivalent ordinary-model vocabulary without weake
example: 'product-analytics.dataflow.json',
caseFile: 'product-analytics.dataflow.case.json',
mapping: new Map([
- ['edge', 'ingest-gateway'], ['consent', 'consent-filter'], ['stream', 'event-stream'],
+ ['edge', 'edge-collector'], ['consent', 'consent-policy'], ['stream', 'event-stream'],
['pii', 'identity-vault'], ['warehouse', 'facts-warehouse'], ['dashboard', 'metric-dashboards'],
]),
mutate(candidate) {
- candidate.nodes.find((node) => node.id === 'ingest-gateway').label = 'Ingestion Gateway';
- candidate.nodes.find((node) => node.id === 'consent-filter').label = 'Consent Filter';
+ candidate.nodes.find((node) => node.id === 'edge-collector').label = 'Edge Collector';
+ candidate.nodes.find((node) => node.id === 'consent-policy').label = 'Consent Policy';
candidate.nodes.find((node) => node.id === 'identity-vault').label = 'Identity Vault';
- candidate.nodes.find((node) => node.id === 'facts-warehouse').label = 'Facts Warehouse';
+ candidate.nodes.find((node) => node.id === 'facts-warehouse').label = 'Analytics Warehouse';
candidate.nodes.find((node) => node.id === 'metric-dashboards').label = 'Metric Dashboards';
candidate.flows.find((flow) => flow.id === 'consent-enrichment').label = 'identity claims';
- candidate.flows.find((flow) => flow.id === 'identity-map').label = 'consented identity';
- candidate.flows.find((flow) => flow.id === 'metrics-query').label = 'KPI reads';
+ candidate.flows.find((flow) => flow.id === 'accepted-events').label = 'cleared events';
+ candidate.flows.find((flow) => flow.id === 'identity-map').label = 'encrypted identity';
+ candidate.flows.find((flow) => flow.id === 'metrics-query').label = 'metric queries';
},
},
{
diff --git a/archify/test/render-output-checks.test.mjs b/archify/test/render-output-checks.test.mjs
index e3fd2c60..8a91c73b 100644
--- a/archify/test/render-output-checks.test.mjs
+++ b/archify/test/render-output-checks.test.mjs
@@ -46,6 +46,19 @@ test('render output check: rejects two-point diagonal arrows', () => {
assert.match(check.details[0], /path 1/);
});
+test('render output check: rejects a diagonal segment inside a polyline', () => {
+ const { code, result } = checkHtml('polyline-diagonal', `
+ <path d="M 20 20 L 60 35 L 120 35" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+ <!-- Legend -->
+ <text x="40" y="120" class="t-primary" font-size="10">Legend</text>
+ `);
+ assert.notEqual(code, 0);
+ const check = result.checks.find((item) => item.name === 'orthogonal_arrows');
+ assert.equal(check.ok, false);
+ assert.match(check.details[0], /path 1/);
+ assert.match(check.details[0], /segment 1/);
+});
+
test('render output check: rejects arrows crossing legend text', () => {
const { code, result } = checkHtml('legend-crossing', `
<path d="M 20 112 L 180 112" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
diff --git a/benchmarks/ordinary-model-floor/cases/agent-tool-call.workflow.case.json b/benchmarks/ordinary-model-floor/cases/agent-tool-call.workflow.case.json
index a9ebc464..1aa0fce1 100644
--- a/benchmarks/ordinary-model-floor/cases/agent-tool-call.workflow.case.json
+++ b/benchmarks/ordinary-model-floor/cases/agent-tool-call.workflow.case.json
@@ -10,7 +10,7 @@
{ "key": "approval", "labels": ["Approval Gate", "Human Approval"], "type": "security" },
{ "key": "tool", "labels": ["Tool Call", "Tool Execution", "Tool Executor", "Tool Runner"], "type": "messagebus" },
{ "key": "blocked", "labels": ["Blocked", "Denied"], "type": "security" },
- { "key": "external", "labels": ["External API", "Provider API"], "type": "cloud" }
+ { "key": "external", "labels": ["External API", "Provider API", "Remote API"], "type": "cloud" }
],
"relationships": [
{ "from": "planner", "to": "router" },
diff --git a/benchmarks/ordinary-model-floor/cases/product-analytics.dataflow.case.json b/benchmarks/ordinary-model-floor/cases/product-analytics.dataflow.case.json
index 084ce8d2..0b009930 100644
--- a/benchmarks/ordinary-model-floor/cases/product-analytics.dataflow.case.json
+++ b/benchmarks/ordinary-model-floor/cases/product-analytics.dataflow.case.json
@@ -5,19 +5,19 @@
"quality_profile": "showcase",
"requirements": {
"nodes": [
- { "key": "edge", "labels": ["Edge API", "Ingestion API", "Ingestion Gateway", "Ingest Gateway"], "type": "cloud" },
- { "key": "consent", "labels": ["Consent Gate", "Consent Check", "Consent Filter"], "type": "security" },
+ { "key": "edge", "labels": ["Edge API", "Ingestion API", "Ingestion Gateway", "Ingest Gateway", "Edge Collector"], "type": "cloud" },
+ { "key": "consent", "labels": ["Consent Gate", "Consent Check", "Consent Filter", "Consent Policy"], "type": "security" },
{ "key": "stream", "labels": ["Event Stream", "Event Bus"], "type": "messagebus" },
{ "key": "pii", "labels": ["PII Vault", "Identity Vault"], "type": "security" },
- { "key": "warehouse", "labels": ["Warehouse", "Data Warehouse"], "type": "database" },
+ { "key": "warehouse", "labels": ["Warehouse", "Data Warehouse", "Analytics Warehouse"], "type": "database" },
{ "key": "dashboard", "labels": ["Dashboards", "Analytics Dashboard"], "type": "backend" }
],
"relationships": [
{ "from": "edge", "to": "consent", "labels": ["identity + consent", "consent check", "identity claims"] },
- { "from": "edge", "to": "stream", "labels": ["accepted events", "validated events"] },
- { "from": "consent", "to": "pii", "labels": ["identity map", "approved identity", "consented identity"] },
+ { "from": "edge", "to": "stream", "labels": ["accepted events", "validated events", "cleared events"] },
+ { "from": "consent", "to": "pii", "labels": ["identity map", "approved identity", "consented identity", "encrypted identity"] },
{ "from": "stream", "to": "warehouse", "labels": ["normalized facts", "normalized events"] },
- { "from": "warehouse", "to": "dashboard", "labels": ["metrics SQL", "analytics query", "KPI reads"] }
+ { "from": "warehouse", "to": "dashboard", "labels": ["metrics SQL", "analytics query", "KPI reads", "metric queries"] }
]
}
}
diff --git a/benchmarks/ordinary-model-floor/cases/web-runtime.architecture.case.json b/benchmarks/ordinary-model-floor/cases/web-runtime.architecture.case.json
index c31fe468..ff2cc0c3 100644
--- a/benchmarks/ordinary-model-floor/cases/web-runtime.architecture.case.json
+++ b/benchmarks/ordinary-model-floor/cases/web-runtime.architecture.case.json
@@ -7,7 +7,7 @@
"nodes": [
{ "key": "users", "labels": ["Users", "Browser Clients"], "type": "external" },
{ "key": "cdn", "labels": ["CloudFront", "CDN", "Content Delivery Network"], "type": "cloud" },
- { "key": "api", "labels": ["API Server", "Application API"], "type": "backend" },
+ { "key": "api", "labels": ["API Server", "Application API", "App API"], "type": "backend" },
{ "key": "cache", "labels": ["Redis", "Redis Cache"], "type": "database" },
{ "key": "db", "labels": ["PostgreSQL", "Postgres", "Primary Database"], "type": "database" }
],