How to Debug Validation Failures with Supported Fixes in Archify

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

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

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:

{
  "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

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

Step 2: Filter and Inspect

Use jq for rapid drill-down:

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

Or extract human-readable summaries:

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:

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

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:

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	AJV pipeline documentation and comprehensive example	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, 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 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.

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