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

> Explore Archify's layout reporting with 11 composition checks. Validate visual quality using metrics like edge crossings, label clearance, and segment lengths. Learn more.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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**:

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

```

The resulting JSON structure:

```json
{
  "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`).