History button: compare the diagram with a past commit #1

New Issue

2026-10-04T10:52:51-07:00

root-at-skic commented

2026-10-04 10:52:51 -07:00

Add a History action that lets the user pick a past commit of the open diagram and compare it with the current version.

Background

Archify can already visualize changes:

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

It produces a Before / Delta / After page: added / removed / changed / moved components, connections and boundaries, a step-through Review mode, and a JSON receipt with counts. Archify does not get the two versions itself: the caller supplies two JSON files. It has no git access.

The extension fills that gap. It knows the file, the git repo, the current (unsaved) text, and already converts YAML to JSON for every preview.

Proposed flow

History button:
- In archify's viewer toolbar next to Export (<div class="toolbar"> in assets/template.html), injected by the existing bridge script and posting a message like Export does.
- The same action as an editor-title button next to Show Source.
A QuickPick lists the commits that changed this file (date, author, message), via the built-in vscode.git extension API. Follow renames.
Picked commit:
- architecture: convert both versions (commit content and current editor text) to JSON in temp files, run compare, and open the HTML in a new tab such as web.archify ↔ a1b2c3d.
- workflow / sequence / dataflow / lifecycle: compare is architecture-only, so render that commit's version read-only beside the current diagram.

Caveats (evaluated)

The injected button depends on archify markup. Low risk.
- The renderer is vendored and only changes when scripts/sync-archify.mjs runs, so a markup change shows up when we re-sync, not in a released extension.
- The toolbar markup has existed since archify's first viewer template (2026-04-15).
- Mitigation: an integration test that checks the button is present, plus the editor-title button as a fallback.
Connection ids. The real issue.
- compare requires an id on every connection, even though the schema makes it optional. Our fixture web-platform.archify has 12 connections and none has an id, so most existing files would fail with delta/relationship-id-required.
- Plan: always generate missing ids on both versions before comparing, from from→to plus a counter for duplicate pairs. This needs no change to the user's file and works on old commits.
- Known imprecisions:
  - Changing a connection's endpoint shows as removed + added rather than changed.
  - Two connections between the same pair can be matched the wrong way round if their order changes.
- Optional follow-up: a quick fix that writes ids into the file, and ask diagram generators (e.g. the cognitive-architect-2-archify skill) to emit them.
No git, untracked file, or no commits. Trivial. Show a clear message, and also when the git extension is disabled.
Old commits may not validate. Medium risk.
- compare validates both versions with the current archify, so an old version written for older rules, or with broken YAML, makes it refuse ("Base snapshot failed validation").
- Mitigation: show that error clearly and fall back to rendering the old version alone if it renders.
Speed. Low risk. Each compare renders both diagrams in a separate process (seconds), which is fine on demand. Per-commit "+2 −1 ~3" summaries over long histories are out of scope for v1.
Architecture only. Accepted limitation. Other types get the side-by-side view, without highlighted changes.

Scope for v1

History button (toolbar + editor title), commit picker, and the architecture compare with generated connection ids.
Side-by-side view of a past version for the other types.
Messages for the git and validation failure cases.

Done when

An integration test compares two versions of an architecture fixture without connection ids and gets a page with the expected counts.
A test checks that the History button is present in the viewer toolbar.

Add a **History** action that lets the user pick a past commit of the open diagram and compare it with the current version. ## Background Archify can already visualize changes: ``` archify compare architecture <base.json> <head.json> [output.html] [--json] ``` It produces a Before / Delta / After page: added / removed / changed / moved components, connections and boundaries, a step-through Review mode, and a JSON receipt with counts. Archify does **not** get the two versions itself: the caller supplies two JSON files. It has no git access. The extension fills that gap. It knows the file, the git repo, the current (unsaved) text, and already converts YAML to JSON for every preview. ## Proposed flow 1. **History** button: - In archify's viewer toolbar next to **Export** (`<div class="toolbar">` in `assets/template.html`), injected by the existing bridge script and posting a message like Export does. - The same action as an editor-title button next to **Show Source**. 2. A QuickPick lists the commits that changed this file (date, author, message), via the built-in `vscode.git` extension API. Follow renames. 3. Picked commit: - **architecture:** convert both versions (commit content and current editor text) to JSON in temp files, run `compare`, and open the HTML in a new tab such as `web.archify ↔ a1b2c3d`. - **workflow / sequence / dataflow / lifecycle:** `compare` is architecture-only, so render that commit's version read-only beside the current diagram. ## Caveats (evaluated) 1. **The injected button depends on archify markup.** Low risk. - The renderer is vendored and only changes when `scripts/sync-archify.mjs` runs, so a markup change shows up when we re-sync, not in a released extension. - The toolbar markup has existed since archify's first viewer template (2026-04-15). - Mitigation: an integration test that checks the button is present, plus the editor-title button as a fallback. 2. **Connection ids.** The real issue. - `compare` requires an `id` on every connection, even though the schema makes it optional. Our fixture `web-platform.archify` has 12 connections and none has an id, so most existing files would fail with `delta/relationship-id-required`. - Plan: always generate missing ids on both versions before comparing, from `from`→`to` plus a counter for duplicate pairs. This needs no change to the user's file and works on old commits. - Known imprecisions: - Changing a connection's endpoint shows as removed + added rather than changed. - Two connections between the same pair can be matched the wrong way round if their order changes. - Optional follow-up: a quick fix that writes ids into the file, and ask diagram generators (e.g. the `cognitive-architect-2-archify` skill) to emit them. 3. **No git, untracked file, or no commits.** Trivial. Show a clear message, and also when the git extension is disabled. 4. **Old commits may not validate.** Medium risk. - `compare` validates both versions with the current archify, so an old version written for older rules, or with broken YAML, makes it refuse ("Base snapshot failed validation"). - Mitigation: show that error clearly and fall back to rendering the old version alone if it renders. 5. **Speed.** Low risk. Each compare renders both diagrams in a separate process (seconds), which is fine on demand. Per-commit "+2 −1 ~3" summaries over long histories are out of scope for v1. 6. **Architecture only.** Accepted limitation. Other types get the side-by-side view, without highlighted changes. ## Scope for v1 - History button (toolbar + editor title), commit picker, and the architecture compare with generated connection ids. - Side-by-side view of a past version for the other types. - Messages for the git and validation failure cases. ## Done when - An integration test compares two versions of an architecture fixture without connection ids and gets a page with the expected counts. - A test checks that the History button is present in the viewer toolbar.

root-at-skic changed title from ~~Compare an architecture diagram with its git HEAD version~~ to History button: compare the diagram with a past commit

2026-10-04 11:16:37 -07:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: vscode-extensions/archify-vscode-ext#1