What Does the archify.mjs Compare Command Do? A Technical Guide

The archify.mjs compare command generates a deterministic, three-state diff between two architecture JSON snapshots, classifying changes into added, removed, or modified entities while producing a machine-readable receipt and visual artifacts for code review.

The archify.mjs compare command serves as the core diffing engine in the tt-a1i/archify repository, enabling developers to track architectural evolution by comparing base and head states. This utility canonicalizes inputs, computes structural deltas, and outputs reproducible artifacts essential for CI/CD validation and architecture governance.

Core Functionality of the archify compare Command

Loading and Canonicalizing Snapshots

When invoked, the command first loads two architecture JSON files representing the base and head states. In archify/bin/archify.mjs, the CLI parser validates these paths before the comparison engine canonicalizes the inputs. This process normalizes the JSON structure by sorting keys and stripping nondeterministic fields, ensuring that only meaningful structural differences are compared.

Computing the Architecture Delta

The compareArchitecture function (tested in archify/test/architecture-delta.test.mjs) walks both graph representations to classify changes into three distinct categories:

• Added or removed entities: New pages, components, or data sources that appear in only one snapshot.
• Modified relationships: Links that now point to different targets or have altered connection types.
• Metadata changes: Updates to descriptions, version tags, or other non-structural attributes.

Generating Deterministic Output

The command produces a deterministic artifact set written to the specified output directory. This includes HTML and JSON visualizations of the delta, plus a archify-compare-receipt.json file containing:

• "command": "compare" — Identifies the operation type.
• "ok": true/false — Boolean indicating overall success.
• "completeness": "complete" — Status flag when validation passes.
• A summary of passed or failed validation checks.

If inputs are invalid—such as malformed JSON or schema mismatches—the command aborts without modifying existing artifacts, ensuring safe operation in automated pipelines.

Command Syntax and Parameters

The CLI expects the following structure:

archify compare architecture <base.json> <head.json> <output-dir> [--json]

Parameter breakdown:

• architecture — Subcommand specifying the comparison domain.
• <base.json> — Path to the older architecture snapshot.
• <head.json> — Path to the newer architecture snapshot.
• <output-dir> — Destination directory for the diff artifact and receipt.
• --json — Optional flag to emit only the receipt JSON to stdout, useful for scripting.

Implementation in the Source Code

The comparison logic is implemented across several key files:

• archify/bin/archify.mjs — The CLI entry point that parses the compare subcommand and dispatches to the core implementation.
• archify/test/architecture-delta.test.mjs — Contains unit tests for the compareArchitecture function, verifying receipt field generation, diff classification accuracy, and error handling.
• archify/test/cli.test.mjs — Validates end-to-end CLI behavior, ensuring the command produces expected output patterns and exit codes.
• archify/scripts/package-smoke.mjs — Demonstrates integration usage, running compare operations as part of packaging smoke tests.

Practical Usage Examples

Compare two snapshots and generate full artifacts:

archify compare architecture ./snapshots/v1.json ./snapshots/v2.json ./diff-output

Capture only the receipt JSON for CI validation:

archify compare architecture base.json head.json ./out --json > validation-receipt.json

Programmatic usage in Node.js:

import { run } from './archify/bin/archify.mjs';

const result = run([
  'compare',
  'architecture',
  'base.json',
  'head.json',
  'output',
  '--json'
]);

const receipt = JSON.parse(result.stdout);
console.log(`Comparison status: ${receipt.ok ? 'pass' : 'fail'}`);

Summary

• The archify.mjs compare command canonicalizes two architecture JSON inputs before comparison to eliminate formatting noise.
• It classifies differences into entity additions/removals, relationship modifications, and metadata updates.
• Output includes a deterministic archify-compare-receipt.json with explicit fields for command, ok, and completeness status.
• The command aborts safely on invalid inputs, making it suitable for CI/CD pipelines.
• Source implementation spans the CLI entry point in archify/bin/archify.mjs and test coverage in architecture-delta.test.mjs.

Frequently Asked Questions

What file formats does the archify compare command support?

The command accepts architecture snapshots as JSON files. Both inputs must conform to the expected schema, and the tool canonicalizes them internally by sorting keys and normalizing structure before comparison.

How does the command ensure deterministic output?

The tool strips nondeterministic fields and sorts JSON keys during canonicalization. This ensures that running the same compare command on identical inputs produces bitwise-identical receipts and artifacts, which is critical for build reproducibility and caching.

Can I integrate archify compare into automated pipelines?

Yes. Use the --json flag to output only the receipt to stdout, allowing scripts to parse the ok and completeness fields. The command exits with error codes on failure and never overwrites existing artifacts if validation fails, ensuring safe unattended operation.

What information does the archify-compare-receipt.json contain?

The receipt records the operation type ("command": "compare"), a boolean success flag ("ok"), a completeness status ("completeness": "complete"), and a summary of validation checks. This metadata allows downstream tools to verify that the diff was generated correctly and comprehensively.

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