How Archify Detects Cosmetic Reformatting Changes in Architecture Diffs

Archify detects cosmetic reformatting changes by first canonicalizing architecture JSON artifacts to strip visual and layout metadata, then computing a structural diff via architectureDeltaChangeRows(), and finally filtering out any deltas that affect only rendering properties like node coordinates, themes, or presets.

In the tt-a1i/archify repository, architecture diffs must distinguish between substantive structural modifications and superficial visual adjustments. The tool achieves this distinction by normalizing JSON artifacts before comparison, ensuring that shifts in node positioning or color schemes do not trigger false semantic alerts while genuine structural changes remain visible.

The Canonicalization Strategy

Before any comparison occurs, Archify applies a canonicalization step to both the previous and current architecture snapshots. This process systematically removes fields that are purely visual or layout-oriented.

The normalization strips attributes such as:

• Node coordinates (x, y positioning values)
• Theme selections (color palettes and styling configurations)
• Preset identifiers (viewer presets like "Classic" or "Signal Flow")
• Rendering metadata (any fields under layout or view schema sections)

By removing these volatile visual properties, Archify produces a normalized structural representation that reflects only the architectural topology—nodes, edges, and their semantic relationships.

Deep Diff Computation

Once both artifacts are canonicalized, Archify executes a deep JSON diff to identify changes. This logic is implemented in archify/delta/architecture-delta.mjs.

The architectureDeltaChangeRows() function performs the comparison, traversing the normalized object trees to detect additions, deletions, and modifications. At this stage, the diff captures every structural variance between the two snapshots.

The Cosmetic Filter

After generating the raw diff, Archify applies a cosmetic-filter layer. This filter examines each detected change to determine whether the modified fields belong to the visual metadata category removed during canonicalization.

If a change entry differs only in properties related to positioning, themes, or presets, the filter discards it from the final output. Changes affecting structural identifiers, connection mappings, or node types remain flagged as semantic changes and are surfaced in the diff view.

Implementation in Source Code

Core Module: architecture-delta.mjs

The primary diff logic resides in archify/delta/architecture-delta.mjs. This module exports architectureDeltaChangeRows(), which orchestrates the canonicalization, comparison, and filtering pipeline.

According to the source structure, the CLI entry point at archify/bin/archify.mjs imports this delta module to execute diff operations from the command line. The test suite in archify/test/architecture-delta.test.mjs validates that cosmetic changes are properly suppressed while structural changes are accurately reported.

Practical Usage Example

import { architectureDeltaChangeRows } from 'archify/delta/architecture-delta.mjs';

// Load two architecture JSON snapshots
const oldArch = await fetch('/path/to/old/architecture.json').then(r => r.json());
const newArch = await fetch('/path/to/new/architecture.json').then(r => r.json());

// Compute diff rows with automatic cosmetic filtering
const diffRows = architectureDeltaChangeRows({ before: oldArch, after: newArch });

// Output contains only semantic changes; visual reformatting is omitted
console.log(diffRows);

When executed, this code processes the inputs through the canonicalization pipeline. Changing a node's x/y coordinates updates only the layout section, which is stripped during normalization, resulting in no diff entry. Conversely, modifying a node's type or connection triggers a semantic change that appears in diffRows.

Summary

• Canonicalization strips visual noise from architecture JSON before comparison.
• Deep diff identifies structural changes between normalized snapshots via architectureDeltaChangeRows().
• Cosmetic filtering discards changes affecting only coordinates, themes, or presets.
• Source implementation is concentrated in archify/delta/architecture-delta.mjs with CLI support in archify/bin/archify.mjs.

Frequently Asked Questions

What qualifies as a cosmetic change in Archify?

Cosmetic changes include modifications to node positioning coordinates, theme selections, color palettes, and viewer preset identifiers. These properties reside in layout or view sections of the architecture schema and affect only visual rendering, not structural topology.

How does Archify handle node coordinate changes?

Node coordinate changes are removed during the canonicalization phase that precedes diff computation. Since x and y values are stripped from both snapshots, positional shifts produce no delta entries in the final output.

Where is the diff logic implemented?

The core diff engine is implemented in archify/delta/architecture-delta.mjs, specifically within the architectureDeltaChangeRows() function. The module is imported by the CLI entry point at archify/bin/archify.mjs and tested in archify/test/architecture-delta.test.mjs.

Can developers customize which fields are considered cosmetic?

While the canonicalization logic follows a fixed schema targeting layout and view properties, the modular structure of architecture-delta.mjs allows for configuration of stripped fields. Developers can modify the normalization rules to include additional visual metadata or retain specific layout attributes if their use case requires them.

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