Archify JSON Diagnostic Format: Structure, Schema, and Usage

Archify reports validation and runtime errors through a structured JSON diagnostic object containing code, severity, subject, evidence, and supportedFixes fields, embedded in the receipt's diagnostics[] array.

The tt-a1i/archify repository uses a machine-readable JSON diagnostic format to communicate precise problem reports during validation, delivery, and preview operations. Every command execution returns a receipt containing a diagnostics array that details exactly what went wrong, where it occurred, and how to resolve it.

Core Schema of the JSON Diagnostic Format

Each diagnostic object in receipt.diagnostics[] follows a strict contract enforced by the test suite and architectural documentation.

Required Fields

Every diagnostic must include three core fields:

• code: A stable string identifier for the rule that triggered the issue (e.g., input/json-parse, viewer/visual-check-runtime). As implemented in archify/test/repair-receipt.test.mjs, this field appears at index 0 of the diagnostics array.
• severity: One of "error", "warning", or "info", indicating the criticality of the problem and whether the operation should halt.
• subject: An object describing the target of the diagnostic, such as a file path, JSON pointer, or UI element. The exact shape varies by diagnostic type.

Contextual and Optional Fields

Additional fields provide debugging context and remediation paths:

• message: An optional human-readable description, often generated dynamically from evidence data. The visual-check test suite references this via diagnostic?.message in archify/test/visual-check.test.mjs.
• evidence: An object containing concrete data explaining the failure, such as offending JSON tokens, pixel measurements, or system reason strings like ECONNRESET. Accessed in archify/test/visual-check.test.mjs as diagnostic?.evidence?.reason.
• supportedFixes: An array of deterministic fix suggestions that clients can apply automatically without guessing. Each entry is either a command-line flag or a descriptive action like "increase-gap-size" or "regenerate-layout".

Real-World Diagnostic Examples

The test files demonstrate the format in practice. A typical validation failure receipt structure appears in archify/test/repair-receipt.test.mjs:

{
  "receipt": {
    "stage": "validate",
    "diagnostics": [
      {
        "code": "viewer/visual-check-runtime",
        "severity": "error",
        "subject": { "input": "..." },
        "evidence": { 
          "reason": "ECONNRESET", 
          "scrollWidth": 1601 
        },
        "supportedFixes": [
          "increase-gap-size", 
          "regenerate-layout"
        ]
      }
    ]
  }
}

Visual validation failures in archify/test/visual-check.test.mjs utilize the same schema, accessing fields like diagnostic?.evidence?.reason and diagnostic?.supportedFixes to verify that the system generates actionable repair suggestions.

Processing Diagnostics in JavaScript

When consuming Archify's JSON output programmatically, parse the receipt and iterate over the diagnostics array to handle issues appropriately.

Reading and displaying all diagnostics:

import { readFileSync } from 'fs';

const receipt = JSON.parse(readFileSync('archify-output.json', 'utf8'));

if (receipt.diagnostics?.length) {
  for (const d of receipt.diagnostics) {
    console.log(`${d.severity.toUpperCase()}: ${d.code}`);
    console.log('  Subject:', d.subject);
    console.log('  Evidence:', d.evidence);
    console.log('  Fixes:', d.supportedFixes?.join(', ') || 'None');
  }
}

Filtering for blocking errors only:

const errors = receipt.diagnostics.filter(d => d.severity === 'error');
if (errors.length) {
  console.error(`Found ${errors.length} critical errors. Aborting.`);
  process.exit(1);
}

Stability and Deterministic Ordering

The JSON diagnostic format guarantees long-term stability for automation. According to docs/research-architecture-delta-pr-proof-2026-07-23.md, diagnostic codes never change for existing rules, ensuring backwards compatibility. Furthermore, Archify sorts diagnostics by Unicode code-point order to produce deterministic output across runs. This prevents noisy diffs in version-controlled receipts and enables reliable diff-based testing.

Summary

• The JSON diagnostic format in Archify uses a fixed schema with code, severity, subject, evidence, and supportedFixes fields.
• Diagnostics reside in receipt.diagnostics[] and appear in both success and failure receipts according to docs/authoring-cookbook.md.
• Severity levels are strictly "error", "warning", or "info".
• The format guarantees stable codes and deterministic Unicode sorting for reliable automation.
• Reference implementations appear in archify/test/repair-receipt.test.mjs and archify/test/visual-check.test.mjs.

Frequently Asked Questions

What fields are required in every Archify diagnostic object?

Every diagnostic must contain code, severity, and subject. The code identifies the rule (e.g., input/json-parse), severity indicates the impact level, and subject points to the affected resource. Optional fields like message, evidence, and supportedFixes provide additional context but are not guaranteed in every entry.

How does Archify sort diagnostics in the JSON output?

Archify sorts diagnostics by Unicode code-point order to ensure deterministic output. This prevents arbitrary reordering between runs, making diffs predictable in version-controlled environments as documented in docs/research-architecture-delta-pr-proof-2026-07-23.md.

Can I rely on diagnostic codes remaining stable across Archify versions?

Yes. The diagnostic contract guarantees that code values remain immutable for existing rules. New diagnostics receive unique codes (e.g., output/input-alias), ensuring forwards and backwards compatibility for automated parsers and CI pipelines.

Where is the JSON diagnostic format documented in the source code?

The definitive reference appears in archify/test/repair-receipt.test.mjs, which validates the diagnostics[] array structure including supportedFixes. Visual validation examples exist in archify/test/visual-check.test.mjs, while architectural stability guarantees are outlined in docs/research-architecture-delta-pr-proof-2026-07-23.md and docs/authoring-cookbook.md.

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