Skip to content

gen: stamp the codegen-ts engine version into .gen-state and warn on mismatch #232

Closed

Description

@dmealing

Problem

.metaobjects/.gen-state/ records per-file content hashes only — not the @metaobjectsdev/codegen-ts engine version that produced them. Because scaffold-and-own (ADR-0034) copies only thin generator wrappers while the render* primitives + defaults stay in the package, a consumer who runs npm update && meta gen after an engine change can get a surprising diff (or a three-way-merge conflict) with no signal about why the output moved.

This is the mitigation identified in the versioning-policy analysis: under the (correct) pre-1.0 policy, output-changing bugfixes ship as PATCHes and auto-flow through ^ ranges — so the safety net is making every such diff explained, not slowing the cadence.

Proposal

  1. When meta gen writes the gen-state snapshot, record the resolved @metaobjectsdev/codegen-ts version alongside the content hashes.
  2. On the next meta gen, if the recorded engine version differs from the currently-installed one, print one informational line before writing, e.g.:
    meta gen: codegen engine 0.19.3 → 0.20.1 since last gen — generated output may differ; see CHANGELOG.
  3. Purely informational (never blocks); complements the existing per-file merged/conflict/unchanged statuses.

Pointers

  • gen-state / overwrite policy: server/typescript/packages/codegen-ts/src/overwrite-policy.ts, runner.ts
  • gen status surfacing: server/typescript/packages/cli/src/commands/gen.ts
  • policy context: docs/RELEASING.md → "Versioning policy (pre-1.0)"

Follow-up from the versioning-cadence review (2026-07-25).

Activity

  1. added a commit that references this issue on Aug 3, 2026
  2. dmealing commented on Aug 4, 2026

    @dmealing
    MemberAuthor

    Shipped on main via PR #245 (commits 1b40e7e2 + review follow-up 03aacf4b).

    Code

    • server/typescript/packages/codegen-ts/src/runner.ts:67 — engineVersion() reads codegen-ts's own published version from its package.json; returns undefined when unresolvable (compiled standalone binary), in which case the stamp is simply skipped.
    • server/typescript/packages/codegen-ts/src/runner.ts:99-115 — on runGen, a recorded stamp that differs from the installed engine pushes a warning (codegen engine X → Y since last gen — generated output may differ; see CHANGELOG.).

    Two deliberate constraints from review: the version file is separate from .hashes.json and never affects the merge (purely informational), and the stamp only engages when gen-state is persistent (projectRoot or genStateDir supplied) — so programmatic/test callers writing to a process-tmpdir don't stamp or warn.

    Tests — packages/codegen-ts/test/engine-version-stamp.test.ts, 3 pass / 0 fail (re-run just now).

    Release status: not in v0.20.11 (merged 2026-08-03, after the 2026-08-02 cut) — ships in the next npm release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions