How to Get Repair Guidance for Archify Validation Errors

When Archify validation fails, the CLI returns a machine-readable JSON receipt containing a diagnostics array that lists specific supportedFixes, guiding you through the exact repairs needed for each error.

Archify validates every typed JSON architecture diagram before generating interactive HTML artifacts in the tt-a1i/archify repository. When validation errors occur, the tool provides structured repair guidance through JSON receipts rather than opaque error messages, enabling precise fixes for issues like missing fromSide properties or label collisions. Understanding how to generate and interpret these receipts allows you to quickly resolve errors and produce valid diagrams.

Validating Diagrams with Machine-Readable Output

To obtain detailed repair guidance, run the validation command with the --json flag. According to the source code in archify/bin/archify.mjs, this mode returns a structured receipt rather than plain text errors, enabling programmatic parsing of validation failures.

node archify/bin/archify.mjs validate path/to/your/diagram.json --json

The command outputs a receipt with the following structure:

{
  "ok": false,
  "stage": "layout",
  "diagnostics": [
    {
      "subject": "edges[0].fromSide",
      "message": "Missing fromSide on edge",
      "supportedFixes": ["addFromSide"]
    },
    {
      "subject": "edges[0].label",
      "message": "Label collision",
      "supportedFixes": ["renameLabel","moveEdge"]
    }
  ]
}

Decoding the Diagnostics Array

Each object in the diagnostics array provides three critical fields that constitute the repair guidance:

• subject: A JSON pointer indicating the exact location of the error (e.g., edges[0].fromSide)
• message: A human-readable description of the validation failure
• supportedFixes: An array of concrete repair actions (e.g., addFromSide, renameLabel) that Archify recognizes as valid resolutions

The subject field uses JSON pointer syntax to pinpoint the specific property causing the failure, while supportedFixes enumerates the only safe repair actions the validator recognizes.

Applying Supported Fixes to Resolve Errors

Once you identify the supportedFixes for a diagnostic entry, manually edit your source JSON according to the suggested repair. For example, to resolve a missing fromSide error indicated by the subject edges[0].fromSide, add the property to your diagram definition:

"fromSide": "left"

After applying the fix, re-run the validation command. Archify's validator is fail-closed, meaning it blocks artifact generation until the receipt shows "ok": true and the diagnostics array is empty. Continue this iterative process—applying fixes and re-validating—until all errors are resolved.

Human-Readable Repair Guidance with the doctor Command

For quick debugging without parsing JSON, use the doctor sub-command implemented in archify/bin/archify.mjs. This command runs the same validation logic but formats the repair guidance for console readability:

node archify/bin/archify.mjs doctor path/to/diagram.json

The doctor command displays the same subject, message, and supportedFixes information in a human-friendly format, making it ideal for rapid debugging sessions.

Source Code Reference

The JSON receipt format is documented in docs/authoring-cookbook.md, which explains the stage, diagnostics, and supportedFixes fields in detail. Implementation details and example assertions appear in archify/test/workflow-compiler.test.mjs, while scripts/package-smoke.mjs contains integration tests verifying that validation receipts are properly generated during the build process. The README.md provides general usage guidelines for the validate --json workflow.

Summary

• JSON Mode: Use validate --json to receive machine-readable repair receipts from Archify
• Diagnostic Fields: Each error includes a subject (JSON pointer), message, and supportedFixes array
• Fail-Closed Validation: Archify prevents artifact generation until all diagnostics are cleared
• Doctor Command: Use doctor for human-readable repair guidance in the terminal
• Source References: Receipt format is documented in docs/authoring-cookbook.md and implemented in archify/bin/archify.mjs

Frequently Asked Questions

What is the structure of an Archify validation receipt?

The receipt contains three top-level fields: ok (boolean indicating success), stage (the validation phase that failed), and diagnostics (an array of error objects). Each diagnostic includes subject (JSON pointer), message (description), and supportedFixes (repair actions), as documented in docs/authoring-cookbook.md.

Where is the validation logic implemented in the Archify source code?

The CLI entry point at archify/bin/archify.mjs implements both the validate and doctor commands that generate repair guidance. Test coverage demonstrating how receipts are generated and asserted appears in archify/test/workflow-compiler.test.mjs.

Can Archify automatically apply the supported fixes to my diagram?

No, Archify currently identifies validation errors and suggests supportedFixes but does not automatically modify your JSON. You must manually edit the source file according to the suggested repairs and re-validate until the receipt returns "ok": true.

How do I interpret the subject field in a diagnostic entry?

The subject field uses JSON pointer syntax to indicate the exact path to the problematic property (e.g., edges[0].fromSide). This tells you precisely which object and property need modification to resolve the validation error.

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