# How to Debug Validation Failures with Supported Fixes in Archify

> Debug Archify validation failures effectively. Use json diagnostics and apply supported fixes manually or automatically with npx archify validate.

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

---

**Use `npx archify validate <type> <path> --json` to capture structured diagnostics with human-readable repair suggestions, then apply fixes manually or with `--repair` for automatic correction.**

Archify enforces strict correctness on every architecture, workflow, and data-flow document through a **three-stage validation pipeline**. When validation fails, the CLI surfaces detailed diagnostics including `supportedFixes`—actionable repair hints grounded directly in the source code rules. This guide walks through interpreting these failures and applying the recommended corrections efficiently.

## Understanding Archify's Three-Stage Validation Pipeline

Validation in Archify proceeds sequentially, with each stage acting as a gate:

### Stage 1: Parse to Intermediate Representation (IR)

Raw JSON documents are normalized into a canonical IR that standardizes node IDs, lane/column positions, and edge semantics. This transformation ensures downstream rules operate on consistent data structures regardless of input formatting variations.

### Stage 2: AJV Schema Validation (Fail-Closed)

The IR feeds into **AJV**, a high-performance JSON Schema validator. As noted in the repository's architecture example, *"ajv schema validation sits on the IR (fail‑closed)"*. If schema checks fail, the pipeline halts immediately—no rendering attempts occur.

This behavior is documented in [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) at line 193, where the AJV integration is explicitly called out within the validation pipeline description.

### Stage 3: Renderer-Specific Checks

Post-schema validation, renderers enforce additional constraints: grid placement validity, label width limits, edge spacing requirements, and orthogonal routing rules. Failures here produce diagnostics identical in structure to schema violations, enabling uniform error handling across all validation layers.

## Running Validation and Capturing Diagnostics

### Basic CLI Invocation

```bash
npx archify validate <type> <path> [options]

```

**Supported types:**
- `architecture`
- `workflow`
- `dataflow`
- `engineering-profile`

The `scripts/package-smoke.mjs` file demonstrates this command in practice, exercising validation at lines 104-105 as part of the test suite's smoke tests.

### Essential Options for Debugging

| Option | Purpose |
|--------|---------|
| `--json` | Emit structured diagnostics instead of HTML |
| `--quality=<profile>` | Override the quality profile (`standard`, `showcase`, etc.) |
| `--repair` | Apply automatic fixes when available |

### Capturing Structured Output

```bash
npx archify validate architecture my-diagram.json --json > validation.json

```

The JSON diagnostic envelope contains a top-level `diagnostics` array. Each entry follows a consistent schema designed for programmatic consumption and human readability alike.

## Reading the Diagnostic Payload

Every diagnostic object contains four critical fields:

| Field | Description |
|-------|-------------|
| `code` | Rule identifier (e.g., `schema/additionalProperties`, `grid/duplicate-cell`) |
| `subject` | The affected element—node ID, edge reference, or legend entry |
| `evidence` | Context that triggered the violation (unexpected property names, coordinate values, etc.) |
| `supportedFixes` | **Human-readable repair suggestions** implementable automatically or manually |

### Example Diagnostic from repair-receipt.test.mjs

The test at lines 72-80 of `archify/test/repair-receipt.test.mjs` asserts this exact structure:

```json
{
  "code": "schema/additionalProperties",
  "subject": { "id": "someNode" },
  "evidence": { "additionalProperty": "unexpected" },
  "supportedFixes": ["remove unsupported property \"unexpected\""]
}

```

The CLI surfaces these suggestions unconditionally, giving developers immediate repair guidance without source code inspection.

## Common Failure Categories and Their Fixes

| Category | Code Prefix | Typical Cause | Example `supportedFixes` |
|----------|-------------|---------------|--------------------------|
| **Schema violations** | `schema/*` | Missing required fields, type mismatches, extra properties | `remove unsupported property "foo"`; `add required property "label"` |
| **Grid placement** | `grid/*` | Duplicate coordinates, missing `row`/`col` values | `move node to an empty cell` |
| **Legend/label issues** | `legend/*` | Excessive text length, missing legend entries | `shorten label`; `increase column width` |
| **Edge routing** | `edge/*` | Prohibited crossings, missing orthogonal turns | `add intermediate waypoint` |
| **Repository evidence** | `repository-evidence/*` | Document references mismatch `--repo-root` | `pass --repo-root with the matching local Git checkout` |

The repository evidence fix is explicitly tested at lines 143-146 of `repair-receipt.test.mjs`, confirming Archify's ability to detect and suggest corrections for environment configuration mismatches.

## Step-by-Step Debugging Workflow

### Step 1: Generate JSON Diagnostics

```bash
npx archify validate architecture my-diagram.json --json > validation.json

```

### Step 2: Filter and Inspect

Use `jq` for rapid drill-down:

```bash
jq '.diagnostics[] | {code, subject, evidence, supportedFixes}' validation.json

```

Or extract human-readable summaries:

```bash
jq '.diagnostics[] | "\(.code): \(.subject.id // .subject.path) → \(.supportedFixes[])"' validation.json

```

### Step 3: Apply the Recommended Fix

**Manual correction:** Edit the source JSON according to `supportedFixes` guidance.

**Automatic repair:** Invoke Archify's built-in repair mode:

```bash
npx archify validate architecture my-diagram.json --json --repair > repaired.json

```

The `--repair` flag triggers automatic application of fixes when the diagnostic indicates a safe, deterministic correction. The repaired document streams to `stdout` for inspection or redirection.

### Step 4: Verify Resolution

Re-run validation to confirm the diagnostic array empties or reduces to acceptable warnings only.

### Step 5: Iterate

Complex documents may cascade multiple errors. Address foundational schema violations first—IR generation depends on valid structure, and downstream diagnostics may disappear once upstream issues resolve.

## CI/CD Integration with Supported Fixes

The JSON diagnostic format enables automated quality gates. Archify's scratch directory cleanup—verified in `archify/test/cli.test.mjs` at lines 621-644—guarantees no temporary file leakage even on validation failure, making it safe for ephemeral CI runners.

### Example GitHub Actions Workflow

```yaml
steps:
  - run: npx archify validate architecture diagram.json --json > result.json
  - run: |
      if jq -e '.diagnostics | length > 0' result.json > /dev/null; then
        echo "Validation failures detected:"
        jq '.diagnostics[] | "\(.code): \(.supportedFixes[])"' result.json
        exit 1
      fi

```

When builds fail, engineers receive precise repair instructions via `supportedFixes` without debugging the validator internals.

## Programmatic Validation in Node.js

For custom tooling, invoke the CLI directly:

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

const result = spawnSync('npx', [
  'archify', 'validate', 'architecture',
  'examples/archify-repo.architecture.json',
  '--json'
], { encoding: 'utf8' });

if (result.status !== 0) {
  const { diagnostics } = JSON.parse(result.stdout);
  diagnostics.forEach(d => {
    console.error(`${d.code} on ${d.subject.id || d.subject.path}`);
    console.error(`Suggested fix: ${d.supportedFixes.join('; ')}`);
  });
  process.exit(1);
}

```

This pattern enables pre-commit hooks, custom reporters, or integration with existing build pipelines.

## Key Source Files for Deep Dives

| File | Role | Location |
|------|------|----------|
| `archify/bin/archify.mjs` | CLI entry point—argument parsing, validation orchestration, JSON envelope construction | `archify/bin/archify.mjs` |
| `archify/renderers/shared/diagnostics.mjs` | `supportedFixes` string generation for low-level errors | `archify/renderers/shared/diagnostics.mjs` |
| `archify/test/repair-receipt.test.mjs` | Diagnostic structure assertions and repair evidence validation | `archify/test/repair-receipt.test.mjs` |
| `archify/test/cli.test.mjs` | Temporary directory cleanup guarantees | `archify/test/cli.test.mjs` |
| [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) | AJV pipeline documentation and comprehensive example | [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) |
| `scripts/package-smoke.mjs` | CLI integration tests demonstrating exit codes and flag behavior | `scripts/package-smoke.mjs` |

These files provide authoritative reference for Archify's validation behavior, repair generation, and operational safety guarantees.

## Summary

- **Archify validates documents through parse → AJV schema → renderer-specific stages**, with strict failure handling at each gate
- **Use `--json` to capture structured diagnostics** containing `code`, `subject`, `evidence`, and `supportedFixes` for every failure
- **Apply fixes manually** by editing source JSON per suggestions, or **automatically** with `--repair` when available
- **Leverage `supportedFixes` in CI pipelines** to provide actionable failure messages without validator internals knowledge
- **Trust the cleanup guarantees**—`cli.test.mjs` verifies no temporary file leakage regardless of failure mode

## Frequently Asked Questions

### What does "fail-closed" mean in Archify's validation pipeline?

Fail-closed means the pipeline terminates immediately upon schema validation failure, preventing any downstream processing or rendering. As implemented in [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json), AJV errors stop execution before the IR reaches renderer-specific checks, ensuring invalid documents never produce partial or misleading outputs.

### How do I handle multiple validation errors at once?

Address diagnostics in order—schema violations first, then grid placement, then edge routing. The `supportedFixes` array for each diagnostic indicates whether the fix is independent or dependent on prior corrections. Run `--repair` iteratively, re-validating after each pass, as automatic fixes may resolve cascading downstream errors.

### Can I customize the validation rules or quality profiles?

Yes. The `--quality=<profile>` flag selects predefined profiles (`standard`, `showcase`). The source architecture in [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) documents where quality gates inject additional constraints, though custom profile definition requires modifying the AJV schema and renderer rule configurations in the source.

### Why doesn't `--repair` fix all my validation errors?

`supportedFixes` only appears for errors with deterministic, safe automatic resolution. Ambiguous placement conflicts, design intent violations, or missing semantic information require human judgment. The `archify/renderers/shared/diagnostics.mjs` module controls which errors generate repair suggestions based on fix confidence thresholds.