How to Interpret Archify's Diagnostic Codes and Messages

Archify emits structured JSON diagnostics containing stable error codes, human-readable messages, JSON pointers to offending elements, and actionable repair suggestions that enable both manual debugging and programmatic error resolution.

When you validate architecture diagrams with tt-a1i/archify, the tool returns detailed diagnostic feedback through its CLI. Understanding how to interpret Archify's diagnostic codes and messages allows you to rapidly identify and repair issues in your typed JSON Intermediate Representation (IR) before rendering. The diagnostic system is designed to be deterministic and machine-readable, making it ideal for CI/CD pipelines and automated tooling.

Anatomy of an Archify Diagnostic Object

Each diagnostic entry in the diagnostics array follows a strict schema. When you run Archify with the --json flag, the CLI outputs an object containing this array, with each element providing five critical fields:

• code: A stable, uppercase identifier (e.g., MISSING_LABEL, INVALID_ROUTE) that remains consistent across runs for programmatic filtering.
• message: Human-readable text explaining the validation failure, typically including specific node or edge IDs affected by the error.
• subject: A JSON Pointer (RFC 6901) such as /nodes/5 that pinpoints the exact location of the problematic element in your IR file.
• supportedFixes: An array of permissible repair actions (e.g., addLabel, removeEdge) that the CLI will accept during subsequent validation or delivery attempts.
• evidence: Optional contextual data such as source code snippets or Git commit references that help trace the error to its origin.

According to the README.md in tt-a1i/archify (lines 223–226), this structure ensures diagnostics are self-contained and environment-agnostic, functioning identically across Cursor, Claude Code, Codex CLI, and OpenCode.

Retrieving Diagnostics with the --json Flag

To capture diagnostic output in a parseable format, append the --json flag to any validate or deliver command. The archify/bin/archify.mjs entry point handles all CLI commands including validate, compare, and deliver. For example, validating an architecture file produces a JSON object you can inspect programmatically:

node archify/bin/archify.mjs validate architecture examples/web-app.json \
    --quality showcase --json > result.json

When validation fails, the resulting JSON object's diagnostics field contains the array of error descriptions, as documented in README.md (lines 232–236).

Resolving Errors Using the Diagnostic Workflow

Follow this systematic approach to interpret and fix validation failures:

1. Extract the diagnostic dump: Run your command with --json and pipe the output to a file for inspection.
2. Locate the failure point: Check the subject field to identify the JSON Pointer path (e.g., /nodes/3) requiring modification.
3. Interpret the requirement: Review the code and message fields to understand what constraint was violated.
4. Select a fix: Choose one option from the supportedFixes array—such as addLabel for a MISSING_LABEL error—and apply the corresponding change to your IR.
5. Re-validate: Execute the validation command again. If the diagnostics array is empty, Archify will proceed to render the diagram.

For batch processing, use jq to filter specific error types from the output:

jq '.diagnostics[] | select(.code == "MISSING_LABEL") | {message, subject, supportedFixes}' result.json

Programmatic Consumption in Node.js

You can integrate Archify's diagnostic system directly into Node.js scripts by invoking the CLI and parsing the JSON response:

const { execSync } = require('child_process');

const result = JSON.parse(execSync(
  'node archify/bin/archify.mjs validate architecture examples/web-app.json --quality showcase --json'
));

for (const d of result.diagnostics) {
  console.log(`[${d.code}] ${d.message} (at ${d.subject})`);
  console.log('Suggested fixes:', d.supportedFixes.join(', '));
}

This pattern enables automated error reporting in CI pipelines or LLM-driven code editors that can propose fixes based on the supportedFixes metadata.

Key Source Files and Schema Definitions

Understanding these files in the tt-a1i/archify repository provides deeper context for diagnostic interpretation:

• README.md (lines 223–236): Documents the CLI --json output format and the complete structure of the diagnostics array.
• archify/bin/archify.mjs: The main CLI entry point that instantiates the validation engine and formats diagnostic output.
• archify/schemas/diagnostic.json: If present, contains the formal JSON Schema defining valid diagnostic object shapes and enumerated fix types.
• archify/examples/web-app.json: Sample IR file that demonstrates common validation scenarios and corresponding diagnostic triggers.
• archify/docs/authoring-cookbook.md: Provides guidance on authoring IR files and interpreting validation feedback in complex architectures.

Summary

• Archify's diagnostic system returns machine-readable JSON through the --json CLI flag, enabling both manual and automated error handling.
• Each diagnostic contains a stable code, descriptive message, JSON Pointer subject, and actionable supportedFixes array.
• The validate and deliver commands in archify/bin/archify.mjs never mutate source files, allowing safe iterative debugging.
• Integration with tools like jq or Node.js child_process supports CI/CD automation and LLM-assisted repair workflows.

Frequently Asked Questions

What do Archify diagnostic codes look like?

Diagnostic codes are uppercase, snake-case strings such as MISSING_LABEL or INVALID_ROUTE. These codes are stable identifiers defined in the Archify validation engine, allowing you to filter logs or write conditional logic that handles specific error types consistently across different versions of the tool.

How do I find which element caused a diagnostic?

Inspect the subject field in the diagnostic object, which contains a JSON Pointer (e.g., /nodes/5/label) referencing the exact location in your IR file. This pointer follows RFC 6901 syntax and can be used with JSON parsing libraries or manual navigation to locate the offending node or edge.

Can I automate fixes based on Archify diagnostics?

Yes. The supportedFixes array lists permissible repair actions for each diagnostic, such as addLabel or removeEdge. Your automation scripts can map these codes to specific code transformations, then re-run the validation command to confirm resolution without manual intervention.

Where are diagnostic definitions stored in the repository?

While the runtime logic resides in archify/bin/archify.mjs, the schema definitions and documentation are located in README.md (lines 232–236) and potentially archify/schemas/diagnostic.json. The archify/docs/authoring-cookbook.md file provides additional context on how validation rules generate specific diagnostic patterns.

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