Archify Composition Checks: Complete Guide to Layout Reporting in Diagram Validation

Archify's layout reporting includes 11 composition checks that validate visual quality through metrics like edge crossings, corridor ambiguity, label clearance, and segment lengths.

Every diagram that Archify processes goes through a composition validation phase after layout. This phase produces a composition receipt containing a status (pass, warn, or fail) and detailed metric values. According to the tt-a1i/archify source code, these checks ensure diagrams meet readability standards—ranging from basic desktop viewing to stricter "showcase" quality profiles.

The 11 Composition Checks in Archify

Archify's layout reporting enumerates specific validation codes. Each check corresponds to a metric field in the receipt and includes defined thresholds for warnings or failures.

Crossing and Corridor Checks

• composition/proper-crossing — Counts proper edge-to-edge crossings. Diagrams must contain at least one correct crossing for a "showcase" layout. Metric: properCrossings.

• composition/ambiguous-corridor — Detects long, straight corridors where edges overlap ambiguously. Metric: ambiguousCorridors.

• composition/container-border-run — Ensures the outer container border is not intersected by edges. Metric: containerBorderRuns.

Label and Readability Checks

• composition/label-route-clearance — Verifies edge-label routes maintain minimum distance from other elements. Metrics: labelRouteClearanceIssues, minLabelRouteClearance.

• composition/desktop-readability — Issues warnings when diagrams readable on desktop fail stricter showcase criteria. Metrics: profile (e.g., standard), status (warn/fail).

Segment and Bend Quality Checks

• composition/micro-segment-count — Counts very short line segments that degrade readability. Metric: microSegmentCount.

• composition/short-interior-segment-count — Counts short interior segments indicating cramped turns. Metric: shortInteriorSegmentCount.

• composition/max-bends — Tracks maximum bend count on any single route. Metric: maxBends.

• composition/routes-over-suggested-bends — Counts routes exceeding suggested bend thresholds. Metric: routesOverSuggestedBends.

• composition/min-segment-px — Measures minimum pixel length of any segment. Metric: minSegmentPx.

• composition/short-segment-count — Totals segments ≤ 8 pixels. Metric: shortSegmentCount.

Where Composition Checks Are Tested

The test suite in archify/test/render-output-checks.test.mjs exercises every composition metric and verifies corresponding messages:

• Proper-crossing warning: lines 166–172 (test file)
• Ambiguous-corridor detection: lines 325–328 (test file)
• Container-border-run failures: lines 366–370 (test file)
• Label-route-clearance metrics: lines 210–214 (test file)

Desktop-readability warnings are covered separately in archify/test/v1-compatibility.test.mjs at lines 291–298, ensuring legacy composition findings surface as warnings rather than silent failures.

Accessing Composition Reports

JSON Output

Run validation with --quality showcase --json to retrieve the full composition receipt:

node archify/bin/archify.mjs validate workflow path/to/my.workflow.json \
  --quality showcase --json

The resulting JSON structure:

{
  "layout": { /* …layout info… */ },
  "composition": {
    "profile": "showcase",
    "status": "warn",
    "summary": { "errors": 0, "warnings": 1 },
    "metrics": {
      "properCrossings": 1,
      "ambiguousCorridors": 0,
      "containerBorderRuns": 0,
      "labelRouteClearanceIssues": 1,
      "minLabelRouteClearance": 4,
      "maxBends": 3,
      "routesOverSuggestedBends": 1,
      "minSegmentPx": 8,
      "shortSegmentCount": 1,
      "microSegmentCount": 0,
      "shortInteriorSegmentCount": 0
    },
    "issues": [
      {
        "code": "composition/label-route-clearance",
        "severity": "warning",
        "threshold": 4,
        "message": "Label route clearance too low – increase spacing"
      }
    ]
  }
}

HTML Gallery Output

The CLI generates HTML artifacts via scripts/build-gallery.mjs (lines 228–233). Open any .html file and locate the Composition table row, which displays the profile, status, and a tooltip with all metric values.

Key Source Files for Composition Validation

File	Role
archify/test/render-output-checks.test.mjs	Exercises every composition metric and verifies messages
archify/test/v1-compatibility.test.mjs	Validates legacy v1 composition findings appear as warnings
archify/test/layout-rules.test.mjs	Drives hand-written layout rule violations
scripts/build-gallery.mjs	Renders composition status and metric tooltips in HTML
archify/bin/archify.mjs	CLI entry point producing JSON composition receipts

Summary

• Archify composition checks in layout reporting validate 11 visual quality aspects through automated metrics
• Each check generates specific codes (composition/*) with associated thresholds and severity levels
• Reports are available as structured JSON or human-readable HTML gallery outputs
• The full test suite guarantees every check produces expected messages and numeric values
• Quality profiles (standard, showcase) apply different thresholds to the same metrics

Frequently Asked Questions

What triggers a composition warning versus a failure?

Warnings occur when metrics exceed comfortable thresholds but the diagram remains usable—such as label clearance at 4px when 5px is suggested. Failures happen when hard limits are breached, like container border runs that break visual containment. The status field in the receipt indicates pass, warn, or fail accordingly.

How do I enable stricter composition validation?

Add --quality showcase to your validation command. This activates stricter thresholds for all 11 checks, including the requirement for at least one proper edge crossing and tighter limits on short segments and bend counts.

Where is the composition status displayed in HTML outputs?

The HTML receipt builder in scripts/build-gallery.mjs (lines 228–233) creates a Composition table row showing the profile, overall status, and a hover tooltip with all metric values. This appears in every generated gallery page alongside layout and routing sections.

Can composition checks be disabled individually?

The source analysis shows no configuration flags for disabling specific checks. All 11 composition checks run during every layout validation. However, you can filter by severity in post-processing since each issue includes a severity field (warning or error).

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