Add `vimanam diff <old> <new>` for spec version comparison

[nrynss]

Summary

A first-class command/engine to compare two versions of a spec and report what changed. It has two delivery surfaces: a low-friction local one (the TUI drift pane, #43) and CI (for teams with the plumbing).

vimanam diff old.json new.json                 # human-readable markdown diff
vimanam diff old.json new.json --report        # diff + hygiene/token deltas
vimanam diff old.json new.json --fail-on-breaking   # nonzero exit for CI

Why this is the strategic centerpiece

A spec is a versioned artifact. Whether it's improving or regressing over time is a first-order question that no current tool in our space answers. The consumer who feels this most is an LLM (or the engineer maintaining a client against a moving API): "what changed since the version my code was written against?"

What it reports

Structural changes

• Endpoints added / removed
• Methods added/removed on an existing path
• Parameters added, removed, or changed (type, required-ness, location)
• Response codes added/removed
• operationId changes (renames break codegen)
• Deprecations (newly deprecated, or removed-while-deprecated)

Breaking vs. non-breaking classification

• Removed endpoint, newly-required param, removed response, changed param type = breaking
• Added optional param, added endpoint, new response code = non-breaking
• --fail-on-breaking exits nonzero when any breaking change is present

Deltas (when --report)

• Hygiene delta: did documentation completeness improve or regress? (ties to Add --no-report flag for spec hygiene summary #44)
• Token-cost delta: did the spec get more/less expensive for a machine to consume? (ties to Add token-cost analysis and budget-aware output #47)

Delivery surfaces (primary: TUI; secondary: CI)

Primary — TUI drift pane (#43). The lowest-friction way to get this in front of an engineer: run vimanam --tui locally, pick two git refs (tags ≈ releases), see the drift. No pipeline, no approvals, no infra. This is the front door.

Secondary — CI, for teams that already have the plumbing:

vimanam diff main-spec.json pr-spec.json --report --fail-on-breaking

• Emits a markdown report suitable for posting as a PR comment
• Nonzero exit on breaking changes so the check goes red
• One-line summary an architect reads: "3 endpoints added, 1 removed (breaking), spec +12k tokens to consume, 4 newly-undescribed endpoints"

CI is valuable but organizationally expensive (pipeline edits, devops approval, secrets, a merge-blocking check). It is not the headline use case — it's an export path. The headline is self-service local drift.

Implementation notes

• New src/diff.rs — diff(old: &ApiDocumentation, new: &ApiDocumentation) -> SpecDiff
• Operates entirely on the existing IR; both specs parse through parse_openapi
• New diff subcommand — first real subcommand, so Cli grows a command enum
• See the design note below: diff must operate on resolved schemas (couples this with Add --inline-refs to fully resolve $refs in output #46), or it goes blind to the most common kind of drift.

[nrynss]

Design requirement: diff must operate on resolved schemas

A diff can compare specs at three levels, and each higher level is blind to drift the level below it catches:

1. Path-set diff — which METHOD path pairs were added/removed. Misses everything about shape.
2. Operation-object diff — byte/structural compare of each operation object. Still misses shape drift, because operations reference shapes by $ref — the pointer string is unchanged even when its target changes.
3. Resolved-schema diff — compare each operation's request/response shapes after inlining all $refs. This is the only level that sees the truth.

Why levels 1–2 are insufficient

The most common real-world drift is a change behind a $ref: a shared schema gains a field, tightens a required-ness, or changes a type. Every endpoint that references that schema now returns a different shape — but:

• its path is unchanged (path-set diff says "no change")
• its operation object is byte-identical, since it only holds {"$ref": "#/components/schemas/Foo"} (operation diff says "no change")

Only by resolving the ref and comparing the materialized shape does the change become visible.

Illustration (hypothetical): GET /widgets responds with #/components/schemas/Widget. Between v1 and v2, Widget gains a nested pricing object. The /widgets path and its operation JSON are identical across versions; a naive diff reports "unchanged" — yet a client deserializing the response sees a genuinely different shape. This is exactly the case a consumer (human or LLM) most needs flagged.

Requirement

• The diff engine walks resolved request/response shapes, not path sets or raw operation objects.
• This makes ref resolution (Add --inline-refs to fully resolve $refs in output #46) load-bearing infrastructure for diff, not just an output convenience — the two issues share the same resolution + cycle-detection machinery.
• Report shape drift on otherwise-"unchanged" endpoints as a distinct category, e.g. "path stable, response schema changed."