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

> Discover what the archify.mjs compare command does. Generate deterministic, three-state diffs for architecture JSON snapshots, identifying added, removed, or modified entities for code review.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: technical-guide
- Published: 2026-08-30

---

**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`](https://github.com/tt-a1i/archify/blob/main/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:

```bash
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:

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

```

Capture only the receipt JSON for CI validation:

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

```

Programmatic usage in Node.js:

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/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.