feat(schemas): generate the schema-change report

[LKSNDRTMLKV]

Closes #234.

A schema version bump left no machine-readable record of what it changed. The CHANGELOG entry beside it is written by hand — a restatement of a fact that lives in the JSON — so it was both the only account and the only thing that could be wrong.

docs/architecture/SCHEMA-CHANGES.md is now generated from the schema files: one section per product group, one table per version bump, naming every property added, removed, retyped or re-constrained, plus what became required. Regenerate with just schema-changes; the test that produces it fails if the committed copy has drifted.

Committed rather than attached to a CI run, for the reason this org's engine commits its bundled OpenAPI: an artifact reviewable in the diff that causes it gets read; one that lives only in a run does not.

What it turned up on the first run

The report is not decorative — it disagrees with how these bumps read at a glance:

• Six product groups renamed their country field (countryOfProduction / countryOfManufacture / countryOfManufacturing → countryOfOrigin). Every one of those is a removal plus an addition plus a required-set change, not an addition. That is now visible in one line per group instead of being inferrable only by opening two files.
• electronics v1.1.0 → v1.2.0 narrowed productCategory from eleven enum values to four. A pure constraint tightening, previously described only in prose.
• battery v2.5.0 → v2.6.0 carries 36 changes including one type change and one dropped maximum, alongside a required removal.

Only three of the twelve bumps that exist are purely additive.

New public surface

dpp-domain::schemas gains diff_schemas, SchemaDiff, PropertyChange, ChangeKind. Additive — nothing existing changed.

The walk recurses through nested objects and array items, so a field added inside a sub-object is reported at its full path (materials/[]/weightKg, repairabilityScore/overall) rather than as an opaque change to its container.

Two things it deliberately does not do

It is not a compatibility verdict. is_purely_additive() is a statement about shape. Whether stored documents still read is answered by the frozen fixtures in schema_compat.rs, which test it rather than infer it. Two answers to one question is how they come to disagree, so the report says which one it is, in the file header and in the doc comment.

It does not walk oneOf / anyOf / allOf branches. Battery's stateOfHealth is the live example — it shows as added with no type, which is honest, but a field added inside one of its branches in a later version would show as no change at all. Walking branches means pairing them across two versions, and a wrong pairing produces a confidently wrong diff, which is worse than a gap that is written down. It is written down, in the module doc.

Tests

• schemas/diff_tests.rs — eight cases, including the one the issue asked for by name: an added property classified as an addition, and a changed pattern classified as a constraint change rather than an addition. Plus nested and array-item paths, and the fact that adding a property is additive while requiring it is not.
• tests/schema_changes.rs — the drift check, a coverage check that fails if the report ever stops containing a section per bump (an empty report would otherwise pass a drift check against an equally empty file), and one assertion against the shipped schemas rather than fixtures.

The drift check was confirmed to bite: injecting a line into the committed file turns it red, and it goes green again on restore.

Layout

ChangeKind and PropertyChange live in schemas/change.rs rather than beside SchemaDiff, because rule 1 caps a file at two public types and rule 12 forbids a filename repeating its directory. No LAYOUT-DEVIATION marker — the repository has none today and this change did not warrant being the first.

just check green, 1286 tests.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 46 complexity · 6 duplication

Metric	Results
Complexity	46
Duplication	6

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[LKSNDRTMLKV]

Reviewed. The generator, the diff engine and the drift gate are sound — the combinator blind spot is named in diff.rs rather than papered over, and the split from schema_compat.rs (what changed vs whether stored documents still read) is the right line.

One change, in 0b6820c: the drift test moved from dpp-domain/tests/ to dpp-tests/tests/.

It reads docs/architecture/SCHEMA-CHANGES.md, a path outside any crate. dpp-domain is published and cargo package carries tests/ along, so the same test vendored from crates.io would find no report — read_to_string(...).unwrap_or_default() yields "" — and fail asserting the schemas had drifted. A false accusation, in a checkout with nothing wrong with it.

dpp-tests is publish = false and already the home of the gates that read repository paths (domain_concerns.rs, ports_inventory.rs both do exactly this with manifest_relative("../../docs/architecture/...")). diff.rs/change.rs stay in dpp-domain — they are real API and read nothing outside the crate.

just schema-changes and the report's own header now point at -p dpp-tests. just check green.

Title retitled to the commit subject — the conventional-commit gate was the only thing blocking merge.