Skip to content

Commit 3514686

Browse files
authored
feat(codegen): skip generation when the model and generators are unchanged (ADR-0064) (#590)
* feat(codegen): skip gen when nothing changed, in every port (ADR-0064) Forward-port of #585 from release/1.2 (b9bc9c7) onto main, merged with the manifest written once per run (#584) and the uniform entity selection (#588). The skip ADR is numbered ADR-0064 here: ADR-0062 and ADR-0063 are taken on main. - gen builds a key from the loaded model (each root node in canonical effective form), the generators' identity (built engine code, config, owned generators, templates, declared extra inputs, project config) and the output-changing flags, before anything renders. A match with the last successful run, with every generated file still holding that run's bytes, renders and writes nothing. --force (Maven: -Dmetaobjects.force=true) turns it off; a generator that cannot declare its inputs opts out. - A run that names entities (positional, --entities, -Dmeta.entities) forces exactly those: it never skips, never stores a key and leaves the stored full-run key alone, in every port. - verify --codegen may answer "no drift" locally from the key; CI and --full always render, and every port compares in memory. - The hash manifest stays loaded once and written once, and only when an entry changed; identical bytes are never rewritten; TypeScript runs git merge-file only for a hand-edited file. - fixtures/codegen-skip-conformance/cases.json: the shared case table. Hand-resolved: TypeScript runner, overwrite-policy, gen/verify/args/index and codegen-drift; Python cli, runner, overwrite_policy; C# CodegenRunner, CodegenCli, CodegenDrift, Generator, Program; Java generate and verify mojos; docs, changelog and the ADR index. * no-mistakes(review): apply reviewer inline fixes * no-mistakes(review): apply reviewer inline fixes * no-mistakes(review): warn unknown attrs before gen skip; add regression test * no-mistakes(review): apply reviewer inline fixes * no-mistakes(review): Carry warnings in skipped gen json/toon document * no-mistakes(test): Align C# agent-context fixture wording; sdk suite green * no-mistakes(document): align codegen-skip docs with ADR-0064
1 parent 56a4d89 commit 3514686

109 files changed

Lines changed: 6636 additions & 646 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ PyPI has had no product change since `0.25.0` — nothing is broken.
7171
- **Kotlin** — `codegen-kotlin` (KotlinPoet on JVM): entity + Exposed table + Spring controller + payload + relations + filter allowlist + validator + stored-proc + output-parser generators. `integration-tests-kotlin` runs the persistence-conformance corpus through Exposed against Testcontainers Postgres.
7272

7373
**Cross-port conformance corpora** (every port runs the shared corpus):
74-
- Metamodel: `fixtures/conformance/` (510 fixtures; 41 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
74+
- Metamodel: `fixtures/conformance/` (510 fixtures; 42 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
7575
- Render: `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
7676
- Persistence: `fixtures/persistence-conformance/`. **Query** scenarios run on every port (TS / C# / Java / Kotlin / Python), each provisioning its test DB by executing the committed, TS-produced `canonical/schema.postgres.sql` (Postgres only — Derby dropped for the cross-port query corpus, ADR-0015; the FR-044 `report-*` scenarios also run on SQLite, MySQL and D1 where a port has the engine, see [docs/CONFORMANCE.md](docs/CONFORMANCE.md)). The **migration** scenarios are exercised by **TS only** (TS owns schema migrations). **The corpus now gates WRITES, not just reads (SP-H):** an `op: roundtrip` scenario type INSERTs through each port's runtime/ORM write codec (NOT raw SQL), reads the row back, and asserts the wire-normalized value. The `AllTypes` entity (`roundtrip-all-types.yaml`) carries one field of **every** persistable `field.*` subtype — string/int/long/double/float/decimal/boolean/date/time/timestamp(+tz)/currency/enum/uuid/object — plus an **array-of-VO** `field.object @isArray @storage:jsonb` column (`labels`, written as 2-element / empty-`[]` / single-element arrays across the three rows) — so every subtype write+read (incl. the array-of-value-object jsonb codec) round-trips through every port against Testcontainers PG. (`field.byte`/`field.short`/`field.class` were cut as non-functional registration-only stubs — the matrix tracks only genuinely-supported subtypes; see `fixtures/registry-conformance/README.md` → "Per-subtype write-round-trip matrix".)
7777
- API-contract: `fixtures/api-contract-conformance/`. TS / C# / Java / Kotlin / Python all green — each port runs **two lanes**: a hand-rolled reference server AND its **generated** API artifact booted over HTTP (the deployed controller/routes; TS+C# full-stack vs Testcontainers PG, Java/Kotlin/Python generated controller + in-memory repo behind the consumer seam). The generated fan-out found 10 real deployment bugs golden snapshots missed. Three sub-corpora run the **generated lane only, on all five ports** — `write-through/`, `projection/` (F22: a view-only `object.projection` serves GET list + GET by id and answers every write verb with `405 {"error": "method_not_allowed"}`) and `report/` (FR-044: a view-backed `object.report` serves GET list, answers `POST` with that same `405`, and mounts no `/{id}` route). That is deliberate, not a gap: what is under test is whether a port's GENERATOR emits those routes, and a hand-rolled reference server would answer every scenario by construction. The `m2m/` sub-corpus also gates **TPH x M:N together** (base-declared, subtype-declared, abstract-mid-declared, a non-subtype source onto a subtype TARGET, and the cross-subtype source id answering `200 []`) — the two corpora were originally built disjoint (`tph/` had no relationships, `m2m/` no discriminators), which is precisely how that defect class survived.

‎CHANGELOG.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,23 @@ loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersi
195195

196196
### Changed
197197

198+
- **Generation now skips when nothing changed, in every port (ADR-0064).** `meta gen`,
199+
`metaobjects gen`, `dotnet meta gen` and `mvn metaobjects:generate` build a key from the loaded
200+
model (each root node in canonical effective form), the generators' identity (built engine code,
201+
config, owned generators, templates, declared extra inputs, project config) and the output-changing
202+
flags, before anything renders. When it matches the last successful run and
203+
every generated file still holds the bytes that run left, nothing renders and nothing is
204+
written. The key is kept, uncommitted, in `.metaobjects/.gen-state/.fingerprint-<port>.json`. A
205+
run that names entities forces exactly those: it never skips, and it neither writes nor
206+
satisfies the full-run key. `--force`
207+
(`-Dmetaobjects.force=true` on Maven) renders everything, and a generator that cannot declare
208+
what it reads opts out with `cache: false` or its port's equivalent. Locally, `verify --codegen`
209+
may answer "no drift" from the same key (`--full` renders; CI always renders), and compares in
210+
memory, with no temp tree, whenever it renders. The hash manifest is written once per run in every
211+
port, only when an entry changed; a file whose fresh bytes equal what is on disk is never
212+
rewritten; TypeScript runs `git merge-file` only for a file edited by hand. A forward-port of
213+
the 1.2.x change, with the skip ADR numbered ADR-0064 on this line.
214+
198215
- **A write with a key the entity does not declare is refused by default: `api.unknownFields`.
199216
Existing projects get `reject` when they regenerate.** Until now every port dropped an
200217
undeclared body key silently, so a client that misspelled a field (`emial`) got a 200 and lost

‎agent-context/skills/metaobjects-audit/references/csharp.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ dotnet meta gen metaobjects --out Generated --namespace Acme.Generated
4040
dotnet meta gen --list # list all registered generators
4141
dotnet meta gen metaobjects --out Generated --generators entity # narrow to declared entries
4242

43-
dotnet meta verify --codegen # regenerate to temp, diff vs committed output
43+
dotnet meta verify --codegen # regenerate in memory, diff vs committed output
4444
dotnet meta verify --templates # check {{field}} refs vs payload VO (bare default)
4545
dotnet meta verify --deps # shared-model dependencies vs deps.lock.json (opt-in)
4646
```

‎agent-context/skills/metaobjects-audit/references/java.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ goal bound to `generate-sources` in `pom.xml`.
3636
```bash
3737
mvn metaobjects:generate # codegen goal directly
3838
mvn compile # also runs it (bound to generate-sources)
39-
mvn metaobjects:verify -Dmeta.verify.mode=codegen # regen to temp, diff vs committed output
39+
mvn metaobjects:verify -Dmeta.verify.mode=codegen # regen in memory, diff vs committed output
4040
mvn metaobjects:verify -Dmeta.verify.mode=templates # {{field}} refs vs payload VO
4141
```
4242

‎agent-context/skills/metaobjects-audit/references/kotlin.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ committed — confirm the plugin is wired and the goal bound to `generate-source
4040
```bash
4141
mvn metaobjects:generate # codegen goal directly
4242
mvn compile # also runs it (bound to generate-sources)
43-
mvn metaobjects:verify -Dmeta.verify.mode=codegen # regen to temp, diff vs committed output
43+
mvn metaobjects:verify -Dmeta.verify.mode=codegen # regen in memory, diff vs committed output
4444
mvn metaobjects:verify -Dmeta.verify.mode=templates # {{field}} refs vs payload VO
4545
```
4646

‎agent-context/skills/metaobjects-audit/references/python.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ directory structure beyond the target's `outDir`.
3838
```bash
3939
metaobjects gen # run every target's generators (metaobjects.config.yaml)
4040
metaobjects gen --generators entity # narrow to declared entries
41-
metaobjects verify --codegen # regenerate to temp, diff vs each committed outDir (bare default)
41+
metaobjects verify --codegen # regenerate in memory, diff vs each committed outDir (bare default)
4242
metaobjects verify --templates # {{field}} refs vs payload VO
4343
metaobjects deps check # shared-model dependencies vs deps.lock.json (also: verify --deps)
4444
```

‎agent-context/skills/metaobjects-audit/references/typescript.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ the default single-target config, generated files land at the one configured
4040
meta gen # render → 3-way merge → write (overwrites @generated files only)
4141
meta gen --dry-run # preview without writing
4242
meta gen Author Post # scope to named entities
43-
meta verify --codegen # regenerate to temp, diff vs committed output
43+
meta verify --codegen # regenerate in memory, diff vs committed output
4444
meta verify --templates # check {{field}} refs vs payload VO (a bare `meta verify` runs this and `--codegen`)
4545
meta verify --db # schema drift — live DB vs metadata (requires DB connection)
4646
meta verify --codegen --templates --db # all three drift checks in one pass

‎agent-context/skills/metaobjects-codegen/references/python.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ the config's `templates` is refused.
6161
```bash
6262
metaobjects gen # runs every target's generators into its outDir
6363
metaobjects gen --generators entity # narrow to declared entries (never adds one)
64-
metaobjects verify --codegen # regenerate the same list into a temp dir + diff
64+
metaobjects verify --codegen # regenerate the same list in memory + diff
6565
```
6666

6767
With no `metaobjects.config.yaml`, `gen` and `verify --codegen` exit 2 and write nothing.

‎agent-context/skills/metaobjects-codegen/references/typescript.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -162,8 +162,8 @@ Some ejectable entries behave differently from the rest:
162162
every consumer.
163163

164164
In an owned generator, read the project's own files through `ctx.inputRoot`. Under
165-
`meta verify --codegen` the run writes into a temporary tree and `ctx.projectRoot` is that
166-
tree; under a plain `meta gen` it is the directory that holds `metaobjects.config.ts`.
165+
`meta verify --codegen` the run renders in memory; `ctx.projectRoot` is the real project root,
166+
the directory that holds `metaobjects.config.ts`, as it is under a plain `meta gen`.
167167

168168
**`requirementTests()` — one test stub per requirement the model claims.** A recommended
169169
approach, not a contract: a `live` or `partial` requirement gets a stub that fails until

‎agent-context/skills/metaobjects-fit-assessment/references/capability-sheet.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ building block. Every generator is a reference helper an adopter selects, ejects
2525
type and nothing else: no table, no migration, no routes (#248; `docs/features/libraries.md`).
2626
A TypeScript model of only value objects and sourceless projections needs no `dialect`
2727
(`server/typescript/packages/codegen-ts/src/db-emitting.ts`).
28-
- **The drift gate per port** — regenerate into a temp tree and diff: `meta verify --codegen`
28+
- **The drift gate per port** — regenerate in memory and diff: `meta verify --codegen`
2929
(TS); `mvn metaobjects:verify` (Java/Kotlin; unset `meta.verify.mode` runs both the codegen and the template gate); `dotnet meta
3030
verify --codegen` (C#; bare `verify` runs it when `csharp.outDir` (or `--out`) and `codegen/Generators.cs` are present);
3131
`metaobjects verify` (Python; `--codegen` is part of the default). Since 1.2 a bare `verify` runs

0 commit comments

Comments
 (0)