Generated output needs provenance metadata + a built-in staleness check
To trust generated code as a true build artifact (git-ignored, regenerated in CI/build instead of committed), consumers need to (a) detect drift and (b) prove an artifact was generated from a specific contract. typeDiagram gives us neither today, so we hand-rolled both in a wrapper script.
Asks
- Provenance header in every generated file (as a language-appropriate comment): source path, SHA-256 of the source
.td, typediagram version, and the --to/flags used. Lets CI assert "this artifact matches this contract" with a grep, and makes a stale checkout obvious.
- First-class
--check mode: typediagram --check --to LANG file exits non-zero (with a diff) if regeneration would change the output. We currently reimplement this in scripts/gen_contracts.py because the CLI only writes-or-prints.
- Deterministic, stable ordering of types/fields/
__all__ across runs and versions, so (1) and (2) are reliable rather than churn-prone.
- Optional:
--emit-hash to print just the content hash for cache keys / build fingerprinting.
Why
We want to delete generated DTOs from version control and regenerate them in the build — but only if the build can guarantee the regenerated artifact matches the committed contract. Provenance + --check + determinism are exactly the metadata that makes "generated code lives outside git" safe. Without it, a stale or mismatched artifact ships silently.
Generated output needs provenance metadata + a built-in staleness check
To trust generated code as a true build artifact (git-ignored, regenerated in CI/build instead of committed), consumers need to (a) detect drift and (b) prove an artifact was generated from a specific contract. typeDiagram gives us neither today, so we hand-rolled both in a wrapper script.
Asks
.td, typediagram version, and the--to/flags used. Lets CI assert "this artifact matches this contract" with agrep, and makes a stale checkout obvious.--checkmode:typediagram --check --to LANG fileexits non-zero (with a diff) if regeneration would change the output. We currently reimplement this inscripts/gen_contracts.pybecause the CLI only writes-or-prints.__all__across runs and versions, so (1) and (2) are reliable rather than churn-prone.--emit-hashto print just the content hash for cache keys / build fingerprinting.Why
We want to delete generated DTOs from version control and regenerate them in the build — but only if the build can guarantee the regenerated artifact matches the committed contract. Provenance +
--check+ determinism are exactly the metadata that makes "generated code lives outside git" safe. Without it, a stale or mismatched artifact ships silently.