How to Debug Validation Failures with Supported Fixes in Archify

Run archify validate <type> <file>.json --json to expose the supportedFixes array, then apply the first suggestion to resolve schema or repository-evidence errors.

Archify validates diagram JSON against strict JSON-Schema definitions and repository-evidence rules. When validation fails, the tool emits structured diagnostics containing actionable repair suggestions in the supportedFixes property. Understanding how to interpret and apply these fixes—whether generated from schema keywords like additionalProperties or required, or from Git-related repository checks—lets you rapidly resolve diagram errors without guesswork.

---

Where Diagnostics and Supported Fixes Originate

Archify builds validation diagnostics in three core locations. Each attaches supportedFixes based on the specific failure mechanism.

Schema Validation in validator.mjs

The file archify/renderers/shared/validator.mjs executes generated validators (e.g., validators['architecture']) and constructs diagnostic objects on failure. The mapping from JSON-Schema keywords to suggested fixes is defined in the supportedFixes object at lines 56–68:

• additionalProperties → suggests property removal
• required → suggests adding missing properties
• type, enum, pattern, and numeric constraints → suggest value corrections

Repository-Evidence Validation in repository-evidence.mjs

The file archify/renderers/shared/repository-evidence.mjs performs Git-related checks—verifying local repository roots, path validity, and file existence. Each failure includes domain-specific fixes, such as:

• "install Git and ensure it is available on PATH"
• "pass --repo-root with the matching local Git checkout"

See the first failure handling at lines 25–28 for the pattern.

CLI Output in archify.mjs

The CLI entry point at archify/bin/archify.mjs wraps validation and exposes diagnostics when you pass --json or --diagnostic-format=json. Lines 21–23 handle this flag, printing the full diagnostic payload including supportedFixes.

---

Step-by-Step Debugging Workflow

Follow this repeatable process to resolve validation failures using supportedFixes:

1. Run validation with JSON output

   archify validate architecture diagram.json --json

2. Locate the failure path

   Check subject.path (e.g., /components/2/sources/0/path). If subject.identity exists, it annotates the element's ID or label for easier navigation.

3. Read the supportedFixes array

   This contains exact mutations to make the JSON valid—typically one-liners like remove unsupported property "unexpected" or add required property "name".

4. Apply the suggested fix

   Edit manually or use archify repair (if available) to apply automatically.

5. Re-run validation

   Confirm the diagnostic disappears. Repeat for any new errors.

For CI automation, archify repair applies the first fix and re-validates in a loop.

---

Example 1: Fixing an additionalProperties Error

Invalid JSON with an unsupported property:

{
  "components": [
    {
      "id": "auth",
      "type": "service",
      "unexpected": "foo"
    }
  ]
}

Validation command:

archify validate architecture diagram.json --json

Diagnostic output:

{
  "code": "schema/additionalProperties",
  "message": "/components/0 (id: \"auth\") additional property \"unexpected\" is not allowed",
  "subject": {
    "diagramType": "architecture",
    "path": "/components/0",
    "identity": "auth"
  },
  "evidence": {
    "keyword": "additionalProperties",
    "additionalProperty": "unexpected"
  },
  "supportedFixes": [
    "remove unsupported property \"unexpected\""
  ]
}

Apply the fix:

sed -i '/\"unexpected\"/d' diagram.json

Re-run validation—the error is resolved.

---

Example 2: Repository Evidence Missing --repo-root

Diagram with source evidence but no local repository specified:

{
  "meta": {
    "repository": {
      "url": "https://github.com/example/project",
      "revision": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t"
    }
  },
  "components": []
}

Validation without --repo-root:

archify validate architecture diagram.json --json

Diagnostic output:

{
  "code": "repository-evidence/root-required",
  "message": "This diagram declares source evidence. Pass --repo-root <repository> so Archify can verify it before rendering.",
  "subject": { "path": "/meta/repository" },
  "supportedFixes": [
    "pass --repo-root with the matching local Git checkout"
  ]
}

Apply the fix:

archify validate architecture diagram.json --repo-root /path/to/local/checkout --json

Archify now verifies sources; any path or file errors surface with their own supportedFixes.

---

Programmatic Access to Diagnostics

Embed Archify validation in Node.js tooling to build automated repair pipelines:

import { validateSchema } from './archify/renderers/shared/validator.mjs';
import fs from 'fs';

const data = JSON.parse(fs.readFileSync('diagram.json', 'utf8'));

try {
  validateSchema('architecture', data);
  console.log('✅ Diagram is valid');
} catch (e) {
  // e.diagnostics contains the same array as CLI --json output
  for (const d of e.diagnostics) {
    console.error(`❌ ${d.message}`);
    console.error('   Fixes:', d.supportedFixes.join(' | '));
  }
}

The exception's diagnostics property matches CLI output exactly, enabling your tooling to propose or auto-apply fixes.

---

Fix Generator Reference

Keyword	Fix Template (from validator.mjs lines 56–68)
additionalProperties	remove unsupported property "${property}"
required	add required property "${property}"
type	use "${expectedType}" at ${path}
enum	choose one of [${allowedValues}]
pattern	match the required pattern "${pattern}"
minimum / maximum	use a value ${comparison} ${limit}
minItems / maxItems	provide at least/at most ${limit} item(s)
minLength / maxLength	provide at least/at most ${limit} character(s)

Repository-evidence fixes are defined in repository-evidence.mjs and include Git installation, path formatting, and --repo-root guidance.

---

Key Source Files

File	Purpose
archify/renderers/shared/validator.mjs	Core validation driver; builds supportedFixes from JSON-Schema keywords
archify/renderers/shared/repository-evidence.mjs	Git-related checks with domain-specific repair suggestions
archify/bin/archify.mjs	CLI wrapper; exposes diagnostics via --json flag

---

Summary

• Always use --json to expose the full diagnostic payload including supportedFixes
• Read subject.path to locate errors precisely in your diagram JSON
• Apply the first supportedFixes entry—it provides the minimal valid mutation
• For repository issues, provide --repo-root and follow path-related guidance
• Automate repairs by catching exceptions from validateSchema() and acting on diagnostics programmatically

Archify's supportedFixes transform cryptic validation failures into concrete, actionable steps—dramatically reducing debug time for architecture diagrams.

---

Frequently Asked Questions

What is supportedFixes in Archify?

supportedFixes is an array of string suggestions attached to every validation diagnostic. Each suggestion describes a concrete edit—such as removing a property or adding a required field—that will resolve the specific JSON-Schema or repository-evidence failure. The array is generated automatically based on the validation keyword that triggered the error.

How do I see supportedFixes in the CLI?

Pass --json or --diagnostic-format=json to any archify validate command. This prints the full diagnostic structure including code, message, subject, evidence, and supportedFixes. Without this flag, Archify may render a human-readable summary that omits the structured fix suggestions.

Can I automate fixes using supportedFixes?

Yes. The archify repair command (when available) applies the first fix automatically and re-validates. For custom tooling, catch exceptions from validateSchema() in validator.mjs and parse e.diagnostics[].supportedFixes to drive automated mutations. Most fixes are simple string templates you can translate directly to JSON patch operations or direct file edits.

Why does repository validation fail without --repo-root?

Archify verifies declared source evidence against an actual Git repository on disk. If your diagram contains meta.repository or component-level source references, the tool needs a local checkout to validate paths, commits, and file existence. The supportedFixes array will explicitly suggest passing --repo-root with the appropriate local path when this requirement is unmet.

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