What Does Archify Diagnostic Code `composition/label-route-clearance` Mean?

The composition/label-route-clearance diagnostic in Archify fires when a label placed on one relationship sits too close (within 4 px by default) to a segment of a different relationship, risking visual ambiguity.

The composition/label-route-clearance code is a composition-level diagnostic generated by Archify's renderer to catch layout conflicts between labeled and unlabeled relationship paths. This article explains exactly what triggers this error, where it originates in the Archify codebase, and how to resolve it programmatically.

How Label-Route Clearance Problems Occur

Archify diagrams use relationships (arrows, lines, or routes) to connect nodes. When you attach a label to one relationship, it renders as a rectangular text box positioned along that relationship's path. Problems arise when this label's bounding box encroaches on another relationship's line segment.

The diagnostic prevents visual misattribution—readers might mistake which relationship the label describes. The default 4 px clearance threshold ensures sufficient breathing room between textual and graphical elements.

Where the Diagnostic Is Generated

The check lives in archify/renderers/shared/geometry.mjs inside the cleanLabelRouteClearanceProblems function. According to the Archify source code, this function executes three steps:

1. Collects all routed relationships eligible for inspection.
2. Calls collectLabelRouteClearance to compute the Euclidean distance between each label's rectangle and every segment of every other relationship.
3. Creates a diagnostic if the measured clearance falls below the threshold.

When triggered, the diagnostic includes:

• code: 'composition/label-route-clearance'
• severity: 'error'
• A human-readable message with diagram type, label text, offending segment, measured clearance, and route hints
• Detailed evidence with label coordinates, opposing relationship data, segment indices, and exact point positions

Fixing Label-Route Clearance Issues

Archify exposes resolution paths through COMPOSITION_FIXES in archify/bin/archify.mjs (lines 89–96). You have two primary strategies:

• Move the label – Adjust labelAt, labelDx, labelDy, labelSegment, or message y properties
• Reposition the conflicting route – Modify the other relationship's route, via, or channel array

Detecting the Diagnostic Programmatically

import { runArchify } from 'archify/bin/archify.mjs';

const result = await runArchify(diagram, { profile: 'showcase' });

const labelClearanceIssues = result.composition.issues.filter(
  i => i.code === 'composition/label-route-clearance'
);

if (labelClearanceIssues.length) {
  console.log('⚠️  Label-route clearance problems detected:');
  labelClearanceIssues.forEach(issue => {
    console.log(issue.message);
    console.log(issue.evidence);
  });
}

Applying a Fix Via Code

// Shift offending labels 6 pixels away from conflict
labelClearanceIssues.forEach(issue => {
  const { labelRelation } = issue.evidence;
  
  // Move label perpendicular to its relationship
  labelRelation.labelDy = (labelRelation.labelDy || 0) + 6;
});

Re-run runArchify() after modifications. The diagnostic clears once clearance meets or exceeds the threshold.

Configuration and Threshold Adjustment

The 4 px default is configurable via the threshold argument passed to clearance checking functions. For dense diagrams, you might tighten this to 2 px; for accessibility-focused outputs, expand to 8 px or greater.

Source Reference Summary

File	Purpose
archify/renderers/shared/geometry.mjs	Diagnostic generation in cleanLabelRouteClearanceProblems (lines 409–426)
archify/bin/archify.mjs	COMPOSITION_FIXES mapping user-facing suggestions
archify/test/render-output-checks.test.mjs	Test assertions validating diagnostic structure (lines 212–306)

Summary

• composition/label-route-clearance signals a label rectangle within 4 px of an unrelated relationship segment
• Generated in geometry.mjs via Euclidean distance calculation against all route segments
• Fixes involve adjusting label positioning properties or rearranging the conflicting relationship's path
• Diagnostic includes rich evidence for automated remediation pipelines

Frequently Asked Questions

What units does the clearance threshold use?

Archify measures clearance in pixels. The default 4 px threshold applies to rendered output dimensions, not source coordinate units. Scale your diagram's coordinate system accordingly when setting custom thresholds.

Can I suppress this diagnostic entirely?

Yes—filter the composition.issues array after running Archify, or set a threshold of 0 to disable clearance checking. However, this risks producing ambiguous diagrams where labels visually collide with unrelated routes.

Why does this error appear inconsistently across renderings?

Clearance calculation depends on final routed segment positions, which can shift based on automatic layout algorithms, node positions, or routing hints. Minor coordinate changes may push labels into or out of the 4 px exclusion zone.

How do I find which specific segment causes the problem?

Inspect issue.evidence.segmentIndex and issue.evidence.segmentStart/segmentEnd in the diagnostic output. These provide exact coordinates of the offending segment relative to your diagram's coordinate system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}