How the Archify Pipeline Handles Errors During Validation: Structured Diagnostics Deep Dive

The Archify validation pipeline converts every failure—from JSON syntax errors to composition violations—into a structured, machine-readable JSON receipt with precise remediation steps, ensuring deterministic error handling instead of raw Node.js stack traces.

The tt-a1i/archify repository validates diagram specifications through a deterministic pipeline that captures failures at three distinct stages: input parsing, renderer execution, and artifact verification. Understanding how the Archify pipeline handles errors during validation is essential for integrating the tool into CI/CD workflows and building automated remediation systems.

The Six-Stage Validation Pipeline

The commandValidate function in archify/bin/archify.mjs orchestrates a strict sequence that transforms runtime exceptions into reproducible diagnostic reports.

1. Argument Parsing and Environment Setup

The pipeline begins by extracting the --json and --layout-json flags from the command line, then isolates the diagram type (e.g., architecture, workflow) and input file path. It sets the environment variable ARCHIFY_DIAGNOSTIC_FORMAT=json to force all subprocesses to emit structured diagnostics rather than human-readable text.

2. Renderer Invocation

Archify invokes the type-specific renderer (such as render-architecture.mjs) as a subprocess. The renderer validates the input JSON against schemas defined in renderers/shared/generated-validators.mjs before attempting to generate the diagram.

3. Renderer Failure Processing

When a renderer exits with a non-zero status, the rendererFailure() function (lines 41-70 in archify/bin/archify.mjs) captures the JSON payload from stderr. If stderr contains no parseable JSON, the function falls back to a generic internal error. It constructs a list of diagnostic objects containing:

• code: A machine-stable identifier (e.g., input/json-parse, render/layout-failed)
• message: A human-readable description of the failure
• subject: The object reference (e.g., { input: 'diagram.json' })
• evidence: Additional context such as system error codes or parsing locations
• supportedFixes: An array of precise remediation instructions

// archify/bin/archify.mjs – renderer failure processing
function rendererFailure(result) { … }

4. Artifact Verification

On successful render, Archify executes scripts/check-render-output.mjs to validate the generated HTML/SVG against layout and composition rules (e.g., label clearance, minimum distances, edge crossings). When this checker fails, the checkerDiagnostics() function transforms its JSON receipt into standardized diagnostic entries.

const check = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), out], { stdio: 'pipe' });
// … if check.status !== 0 → reportValidateFailure({ …, stage: 'check', diagnostics: checkerDiagnostics(checker) })

5. Unified Error Reporting

The reportValidateFailure() function (lines 30-35 in archify/bin/archify.mjs) wraps all failure contexts into a unified JSON receipt by calling reportArtifactFailure() with the command: 'validate' option. This receipt includes:

• command: Always set to 'validate'
• stage: One of input, render, or check
• error: The original error message string
• diagnostics[]: The complete array of diagnostic objects
• status: The original exit code from the renderer or checker

// archify/bin/archify.mjs – validation error wrapper
function reportValidateFailure(options) {
  reportArtifactFailure({ ...options, command: 'validate' });
}

6. Exit Code Propagation

After the validation block completes, Archify assigns the renderer or checker's exit status to process.exitCode. This guarantees that any validation failure results in a non-zero exit code, making the tool compatible with standard Unix pipeline conventions and CI/CD failure detection.

The Diagnostic Schema

Every validation error follows a consistent schema designed for automated parsing. The diagnostic objects included in the diagnostics array contain:

• code: Machine-stable identifier (examples: input/json-parse, artifact/check-failed, composition/proper-crossing)
• severity: Typically error for validation failures
• message: Human-readable description suitable for console output
• subject: The specific entity the diagnostic refers to, such as { input: 'diagram.json' } or { relationship: 'edge-123' }
• evidence: Contextual data including system error codes, file paths, or parsing tokens
• supportedFixes: Actionable remediation steps (e.g., "repair the JSON syntax and run validation again")

Practical Validation Examples

Successful Validation

archify validate architecture examples/web-app.architecture.json --json

Returns a receipt with ok: true and an empty or passed-checks diagnostics array.

Input Syntax Error

archify validate workflow bad.json --json

Produces a structured receipt identifying the parse failure:

{
  "schemaVersion": 1,
  "ok": false,
  "command": "validate",
  "stage": "input",
  "type": "workflow",
  "input": "/path/bad.json",
  "error": "Input JSON could not be parsed: Unexpected token ...",
  "diagnostics": [
    {
      "code": "input/json-parse",
      "severity": "error",
      "message": "Input JSON could not be parsed: Unexpected token ...",
      "subject": {"input": "/path/bad.json"},
      "evidence": {"reason": "Unexpected token ..."},
      "supportedFixes": ["repair the JSON syntax and run validation again"]
    }
  ]
}

Renderer Failure (Missing Field)

archify validate architecture missing-field.json

Console output shows the error message, while the internal pipeline captures structured diagnostics via rendererFailure().

Composition Check Failure

archify validate architecture overlapping.json --json

Returns diagnostics for layout violations:

{
  "code": "composition/proper-crossing",
  "severity": "error",
  "message": "Final artifact failed composition/proper-crossing.",
  "subject": {"relationship": "edge-123"},
  "evidence": {"details": ["Edge crosses another relationship"]},
  "supportedFixes": ["adjust route/via or channel coordinates so unrelated relationships use separate corridors"]
}

Summary

• Renderer crash handling via rendererFailure() in archify/bin/archify.mjs parses JSON from stderr or falls back to generic errors, ensuring no raw stack traces escape.
• Artifact verification through scripts/check-render-output.mjs catches layout and composition violations, converting them via checkerDiagnostics() into the standard schema.
• Unified reporting by reportValidateFailure() produces consistent JSON receipts with ok: false, explicit stage indicators (input, render, check), and full diagnostic arrays.
• CI/CD compatibility is guaranteed by setting process.exitCode to the subprocess exit status, ensuring reliable failure detection in automated pipelines.
• Machine-consumable output through the ARCHIFY_DIAGNOSTIC_FORMAT=json environment variable enables automated agents to implement self-healing workflows based on code and supportedFixes values.

Frequently Asked Questions

What is the structure of an Archify validation error receipt?

Archify validation error receipts follow a standardized JSON object containing schemaVersion, ok: false, the command name (validate), the failure stage (input, render, or check), the diagram type, the input file path, an error message string, and a diagnostics array. Each diagnostic includes code, severity, message, subject, evidence, and supportedFixes fields to enable programmatic error handling and automated remediation.

How does Archify differentiate between renderer crashes and validation logic errors?

Renderer crashes are captured by the rendererFailure() function in archify/bin/archify.mjs, which attempts to parse structured JSON from the renderer's stderr stream. If parsing fails, it generates a generic internal error diagnostic. Validation logic errors—such as schema violations from renderers/shared/generated-validators.mjs or composition failures from scripts/check-render-output.mjs—are generated as native JSON and forwarded through the same reportValidateFailure() pipeline, ensuring consistent formatting regardless of whether the error originated from a subprocess crash or a validation rule violation.

What exit codes does Archify return when validation fails?

Archify propagates the exact exit code from the failing renderer or checker subprocess to process.exitCode. For example, if the architecture renderer exits with code 1 due to a JSON parse error, Archify exits with code 1. This direct propagation ensures that shell scripts and CI systems can detect failures through standard Unix exit code conventions without needing to parse the JSON output.

How can automated tools programmatically respond to Archify validation errors?

Automated tools should invoke Archify with the --json flag and ensure ARCHIFY_DIAGNOSTIC_FORMAT=json is set. By parsing the resulting receipt's diagnostics array, tools can map the code field (e.g., input/json-parse, composition/proper-crossing) to specific remediation actions. The supportedFixes array provides human-readable guidance, while the subject and evidence fields provide the context needed to implement automatic fixes, enabling self-healing diagram generation workflows.

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