# Archify Validate Command Diagnostic Codes and Fixes: A Complete Guide to Automated Diagram Verification

> Master Archify validate command diagnostic codes and fixes. Automate diagram repair with structured JSON diagnostics and supportedFixes arrays for efficient troubleshooting.

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

---

**The `archify validate` command runs the renderer in diagnostic-only mode to emit structured JSON diagnostics containing specific codes like `clean-flow/edge-through-node` and actionable `supportedFixes` arrays that enable automated diagram repair.**

The `archify validate` command serves as the formal verification stage for diagram specifications, translating geometric and composition errors into machine-readable diagnostic objects. According to the tt-a1i/archify source code, this CLI tool parses low-level rendering failures and presents them as namespaced codes with explicit fix suggestions, enabling both manual correction and automated repair pipelines.

## How the Validate Command Parses Environment and Flags

### CLI Entry Point and Quality Flags

In `archify/bin/archify.mjs`, the `validate` sub-command initializes the rendering environment through the `rendererEnv()` function. This utility constructs the process environment by conditionally injecting the `ARCHIFY_QUALITY_PROFILE`, `ARCHIFY_REPO_ROOT`, and `ARCHIFY_DIAGNOSTIC_FORMAT` variables based on CLI flags.

```javascript
// archify/bin/archify.mjs
function rendererEnv(quality, repoRoot, diagnosticJson = false) {
  return {
    ...(quality ? { ARCHIFY_QUALITY_PROFILE: quality } : {}),
    ...(repoRoot ? { ARCHIFY_REPO_ROOT: repoRoot } : {}),
    ...(diagnosticJson ? { ARCHIFY_DIAGNOSTIC_FORMAT: 'json' } : {}),
  };
}

```

The function accepts a `diagnosticJson` boolean that triggers JSON diagnostic output when the user passes the `--json` flag.

### JSON Diagnostic Mode Activation

When validation runs, the CLI spawns the renderer binary with `stdio: 'pipe'` and the prepared environment. Setting `ARCHIFY_DIAGNOSTIC_FORMAT: 'json'` instructs the renderer to emit structured diagnostic payloads on **stderr** instead of generating image files.

```javascript
const render = runNode([rendererPath(type), inputPath, outputPath], {
  stdio: 'pipe',
  env: rendererEnv(quality, repoRoot, true),
});

```

## Running the Renderer in Diagnostic-Only Mode

### Capturing Renderer Failures

If the renderer exits with a non-zero status, the `rendererFailure()` function in `archify.mjs` parses the stderr JSON payload. It extracts the `diagnostics` array only when the payload contains `ok: false` and a valid array of diagnostic objects.

```javascript
function rendererFailure(result) {
  if (result.error) { … }
  try {
    const payload = JSON.parse((result.stderr || '').trim());
    if (payload?.ok === false && Array.isArray(payload.diagnostics)) {
      return { error: payload.error, diagnostics: payload.diagnostics };
    }
  } catch { /* fail-closed */ }
  …
}

```

This fail-closed approach ensures that malformed JSON does not crash the validator, while valid diagnostic arrays propagate upstream for processing.

## Core Diagnostic Data Structure

### The Diagnostic Object Schema

All diagnostics share a uniform shape created by the `diagnostic()` factory function defined at lines 49-58 of `archify.mjs`. The schema includes six required fields that provide complete context for automated fix engines.

```javascript
function diagnostic({ code, message, subject = {}, evidence = {}, supportedFixes = [], severity = 'error' }) {
  return { code, severity, message, subject, evidence, supportedFixes };
}

```

- **`code`**: A short, namespaced identifier (e.g., `clean-flow/edge-through-node`).
- **`subject`**: Identifies the offending object via relationship index, edge ID, or composition check name.
- **`evidence`**: Raw values triggering the failure, including coordinates, clearance distances, and direction vectors.
- **`supportedFixes`**: An array of human-readable suggestions that downstream tools translate into concrete JSON edits.

### Severity Levels and Subject Identification

The `severity` field accepts `error`, `warning`, or `info` values, though thevalidate command primarily emits `error` level diagnostics for blocking issues. The `subject` object varies by diagnostic type but consistently provides enough metadata to locate the problematic diagram element without parsing the message string.

## Geometry-Level Diagnostics: The Clean-Flow Suite

The renderer's geometry module at `archify/renderers/shared/geometry.mjs` performs low-level geometric validation, emitting **clean-flow** namespaced codes when relationship routing violates layout constraints.

### Endpoint Side Direction Errors (`clean-flow/endpoint-side-direction`)

When a relationship's source or target side annotation conflicts with the actual geometric direction of the rendered segment, the validator records a `clean-flow/endpoint-side-direction` diagnostic. The check compares the declared `fromSide` or `toSide` against the segment's axis and direction.

```javascript
recordDiagnostic({
  code: 'clean-flow/endpoint-side-direction',
  severity: 'error',
  message,
  subject: relationshipSubject(...),
  evidence: { … },
  supportedFixes: [routeHint],
});

```

**Trigger condition**: The rendered segment runs opposite to the declared side annotation.
**Suggested fix**: Adjust the `fromSide`/`toSide` properties or modify `route`/`via` coordinates to align the segment with the expected axis.

### Edge Through Node Violations (`clean-flow/edge-through-node`)

If a relationship line crosses the bounding box of an opaque node that is **not** its source or target, the renderer flags `clean-flow/edge-through-node`. This check prevents visual ambiguity by ensuring edges do not pass through unrelated containers.

```javascript
recordDiagnostic({
  code: 'clean-flow/edge-through-node',
  severity: 'error',
  message,
  subject: relationshipSubject(...),
  evidence: {
    obstacleKind,
    obstacleId: obstacle.id,
    segmentIndex: hitSegment,
    from: points[hitSegment],
    to: points[hitSegment + 1],
    clearancePx: clearance,
  },
  supportedFixes: [routeHint],
});

```

The `evidence` object includes the `obstacleId`, segment coordinates, and `clearancePx` value, providing precise data for algorithms that automatically reroute the edge around the obstacle.

## Composition-Level Validation Codes

After successful rendering, `archify/scripts/check-render-output.mjs` executes a composition checker that validates higher-level visual rules. The `checkerDiagnostics` function in `archify.mjs` maps these checks to Archify diagnostic codes.

### Artifact and Layout Diagnostics

Composition diagnostics cover layout quality rather than geometric correctness. Key codes include:

- **`artifact/label-route-clearance`**: Labels overlap routed edges.
- **`composition/desktop-readability`**: Diagram density exceeds 1440px viewport limits.
- **`composition/micro-segment`**: Segment shorter than 8px.
- **`composition/short-interior-segment`**: Interior turn shorter than 16px.
- **`composition/proper-crossing`** / **`composition/ambiguous-corridor`**: Edge corridors intersect improperly.

### Mapping Fixes to Composition Issues

The `COMPOSITION_FIXES` map in `archify.mjs` (lines 22-34) associates each composition code with specific `supportedFixes` arrays. For example, `artifact/label_route_clearance` suggests enlarging the viewBox, moving the label, or increasing clearance values.

```javascript
for (const issue of checker?.composition?.issues || []) {
  if (issue.severity !== 'error') continue;
  diagnostics.push(diagnostic({
    code,
    severity,
    message: `Final artifact failed ${code}.`,
    subject: relationship ? { relationship } : { check: 'composition' },
    evidence,
    supportedFixes: COMPOSITION_FIXES[code] || [],
  }));
}

```

## Formatting and Reporting Diagnostic Output

### Human-Readable vs JSON Output Modes

The `reportValidateFailure` function routes diagnostics through `formatDiagnostics()`, which produces either structured JSON or plain text based on the `--json` flag. In text mode, the function concatenates codes, messages, and fix suggestions into readable lines.

```javascript
function formatDiagnostics(error, diagnostics = []) {
  if (!diagnostics.length) return error;
  return [
    error,
    ...diagnostics.map(entry => {
      const fix = entry.supportedFixes?.length ? ` Fix: ${entry.supportedFixes.join('; ')}.` : '';
      return `[${entry.code}] ${entry.message}${fix}`;
    })
  ].join('\n');
}

```

### JSON Receipt Structure

When `--json` is specified, the command outputs a complete receipt object:

```json
{
  "schemaVersion": 1,
  "ok": false,
  "command": "validate",
  "stage": "render",
  "type": "architecture",
  "input": "/path/diagram.json",
  "error": "Validated snapshot failed validation",
  "diagnostics": [
    {
      "code": "clean-flow/edge-through-node",
      "severity": "error",
      "message": "[clean-flow/edge-through-node] architecture connections[0] \"checkout\" -> \"database\" crosses container \"auth\" ...",
      "subject": { "relationship": { "collection": "connections", "index": 0, "id": "checkout" } },
      "evidence": {
        "obstacleKind": "container",
        "obstacleId": "auth",
        "segmentIndex": 2,
        "from": [120, 84],
        "to": [140, 100],
        "clearancePx": 2
      },
      "supportedFixes": [
        "adjust fromSide/toSide, set route/via or channel coordinates, or move the obstacle"
      ]
    }
  ]
}

```

## Automating Fixes with Diagnostic Receipts

### Shell Script Auto-Repair Example

The JSON output enables automated repair workflows. The following bash script extracts `clean-flow/edge-through-node` diagnostics and applies a coordinate shift to bypass the obstacle:

```bash
#!/usr/bin/env bash
set -euo pipefail

DIAG=$(archify validate architecture diagram.json --json | jq -r '
  .diagnostics[]
  | select(.code=="clean-flow/edge-through-node")
  | .evidence
')

if [[ -n $DIAG ]]; then
  OBSTACLE_ID=$(echo "$DIAG" | jq -r .obstacleId)
  FROM=$(echo "$DIAG" | jq -r '.from | @csv')
  TO=$(echo "$DIAG" | jq -r '.to | @csv')
  jq --argjson from "[$FROM]" \
     --argjson to "[$TO]" \
     --arg obs "$OBSTACLE_ID" \
     '.connections[] |= if .from==$obs or .to==$obs then .route=[($from|.[0]+10),($from|.[1])] else . end' \
     diagram.json > diagram.fixed.json
  echo "Applied a fix → saved as diagram.fixed.json"
fi

```

### Node.js Fix-Engine Implementation

For Node.js environments, consume the receipt programmatically:

```javascript
import fs from 'fs';
import { spawnSync } from 'child_process';

const result = spawnSync('archify', ['validate', 'architecture', 'diagram.json', '--json'], {
  encoding: 'utf8'
});
const receipt = JSON.parse(result.stdout);

receipt.diagnostics
  .filter(d => d.code.startsWith('clean-flow/'))
  .forEach(d => {
    console.log(`Fix needed for ${d.subject.relationship.id}: ${d.supportedFixes[0]}`);
    // Automated fix logic: modify diagram.json based on d.evidence coordinates
  });

```

## Summary

- The `archify validate` command emits **structured diagnostic objects** with stable, namespaced codes rather than unstructured error strings.
- **Geometry diagnostics** (`clean-flow/*`) identify routing violations like edges passing through unrelated nodes or segments contradicting side annotations.
- **Composition diagnostics** (`artifact/*`, `composition/*`) catch layout quality issues such as label overlap or viewport density problems.
- Each diagnostic includes a **`supportedFixes`** array containing actionable suggestions that automated tools or human authors can implement.
- The **`--json`** flag activates machine-readable output suitable for CI/CD pipelines and automated repair scripts.
- The test suite in `archify/test/repair-receipt.test.mjs` guarantees diagnostic consistency between `validate` and `deliver` commands, ensuring reliable downstream integration.

## Frequently Asked Questions

### What triggers the `clean-flow/edge-through-node` diagnostic code?

This code fires when a relationship line segment intersects the bounding box of a node that is neither its source nor target, as implemented in `archify/renderers/shared/geometry.mjs` lines 376-395. The diagnostic includes `evidence` fields for `obstacleId`, `segmentIndex`, and `clearancePx` to pinpoint exactly which segment crosses which obstacle.

### How do I enable JSON output for the validate command?

Pass the `--json` flag when invoking the command. This sets the `ARCHIFY_DIAGNOSTIC_FORMAT=json` environment variable internally, causing the renderer to emit a structured JSON receipt on stdout containing the full `diagnostics` array with codes, evidence, and supported fixes.

### Can Archify automatically fix diagrams, or does it only report issues?

The `validate` command performs diagnostic-only reporting; it does not modify source files. However, the `supportedFixes` array in each diagnostic object provides explicit instructions that external scripts or fix-engines can execute to automate repairs, as demonstrated in the shell and Node.js examples above.

### What is the difference between `validate` and `deliver` diagnostics?

Both commands emit identical diagnostic structures, verified by the test suite at `archify/test/repair-receipt.test.mjs` lines 117-124. While `validate` runs in diagnostic-only mode without producing final artifacts, `deliver` performs the same checks while generating output files, ensuring consistency between pre-flight validation and production builds.