Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ PyPI has had no product change since `0.25.0` — nothing is broken.
- **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.

**Cross-port conformance corpora** (every port runs the shared corpus):
- Metamodel: `fixtures/conformance/` (421 fixtures; 34 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
- Metamodel: `fixtures/conformance/` (421 fixtures; 35 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
- Render: `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
- 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".)
- 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.
Expand Down
27 changes: 27 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,33 @@ here.**

## [Unreleased]

### Changed

- **`gen` skips rendering when nothing it is built from changed, in every port (ADR-0062).**
The skip key is computed after the metadata loads and before anything renders. Its model half
hashes each loaded root-level node in its canonical effective form (`extends` and overlays
applied), rolled up per package and for the model, so reformatting or splitting a metadata file
changes nothing while an edit to an inherited parent changes every child. Its generator half
hashes the built engine code, the codegen config and every owned generator, the template
roots, declared extra inputs, the project config and the output-changing flags. `gen` skips
when the key matches the last successful run and every generated file still has the bytes
that run left; a skipped run renders and writes nothing. The key is stored, uncommitted, in
`.metaobjects/.gen-state/.fingerprint-<port>.json`. `--force` (`meta gen`, `metaobjects gen`,
`dotnet meta gen`; `-Dmetaobjects.force=true` on Maven) renders everything, and a generator
that cannot declare what it reads opts out with `cache: false` (or its port's equivalent).
- **`verify --codegen` may answer locally without rendering, and never writes a temp tree.** In
CI (`CI` set) it always renders and compares everything. Locally it answers "no drift" when the
key matches and every generated file still hashes to its record; `--full`
(`-Dmetaobjects.verify.full=true` on Maven) renders. When it renders, every port compares the
rendered bytes with disk in memory.
- **The hash manifest is written once per run, and only when an entry changed** (TypeScript,
Python and C#, matching Java and Kotlin). A file whose fresh bytes equal what is on disk is never
rewritten in any port, so its timestamp stays. Python `gen` no longer reports unchanged files
as written.
- **TypeScript runs `git merge-file` only for a file edited by hand since it was generated**, and
deletes the merge's temporary files in every case, under `$DEV_SCRATCH` when set. An untouched
file is overwritten directly.

## [1.2.2] — 2026-11-13

_npm `1.2.2` (full lockstep across all 14 `@metaobjectsdev/*` publish candidates)._
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ dotnet meta gen metaobjects --out Generated --namespace Acme.Generated
dotnet meta gen --list # list all registered generators
dotnet meta gen metaobjects --out Generated --generators entity # narrow to declared entries

dotnet meta verify --codegen # regenerate to temp, diff vs committed output
dotnet meta verify --codegen # regenerate in memory, diff vs committed output
dotnet meta verify --templates # check {{field}} refs vs payload VO (bare default)
```

Expand Down
2 changes: 1 addition & 1 deletion agent-context/skills/metaobjects-audit/references/java.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ goal bound to `generate-sources` in `pom.xml`.
```bash
mvn metaobjects:generate # codegen goal directly
mvn compile # also runs it (bound to generate-sources)
mvn metaobjects:verify -Dmeta.verify.mode=codegen # regen to temp, diff vs committed output
mvn metaobjects:verify -Dmeta.verify.mode=codegen # regen in memory, diff vs committed output
mvn metaobjects:verify -Dmeta.verify.mode=templates # {{field}} refs vs payload VO
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ committed — confirm the plugin is wired and the goal bound to `generate-source
```bash
mvn metaobjects:generate # codegen goal directly
mvn compile # also runs it (bound to generate-sources)
mvn metaobjects:verify -Dmeta.verify.mode=codegen # regen to temp, diff vs committed output
mvn metaobjects:verify -Dmeta.verify.mode=codegen # regen in memory, diff vs committed output
mvn metaobjects:verify -Dmeta.verify.mode=templates # {{field}} refs vs payload VO
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ directory structure beyond the target's `outDir`.
```bash
metaobjects gen # run every target's generators (metaobjects.config.yaml)
metaobjects gen --generators entity # narrow to declared entries
metaobjects verify --codegen # regenerate to temp, diff vs each committed outDir (bare default)
metaobjects verify --codegen # regenerate in memory, diff vs each committed outDir (bare default)
metaobjects verify --templates # {{field}} refs vs payload VO
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ the default single-target config, generated files land at the one configured
meta gen # render → 3-way merge → write (overwrites @generated files only)
meta gen --dry-run # preview without writing
meta gen Author Post # scope to named entities
meta verify --codegen # regenerate to temp, diff vs committed output
meta verify --codegen # regenerate in memory, diff vs committed output
meta verify --templates # check {{field}} refs vs payload VO (a bare `meta verify` runs this and `--codegen`)
meta verify --db # schema drift — live DB vs metadata (requires DB connection)
meta verify --codegen --templates --db # all three drift checks in one pass
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ the config's `templates` is refused.
```bash
metaobjects gen # runs every target's generators into its outDir
metaobjects gen --generators entity # narrow to declared entries (never adds one)
metaobjects verify --codegen # regenerate the same list into a temp dir + diff
metaobjects verify --codegen # regenerate the same list in memory + diff
```

With no `metaobjects.config.yaml`, `gen` and `verify --codegen` exit 2 and write nothing.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -162,8 +162,8 @@ Some ejectable entries behave differently from the rest:
every consumer.

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

**`requirementTests()` — one test stub per requirement the model claims.** A recommended
approach, not a contract: a `live` or `partial` requirement gets a stub that fails until
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ building block. Every generator is a reference helper an adopter selects, ejects
type and nothing else: no table, no migration, no routes (#248; `docs/features/libraries.md`).
A TypeScript model of only value objects and sourceless projections needs no `dialect`
(`server/typescript/packages/codegen-ts/src/db-emitting.ts`).
- **The drift gate per port** — regenerate into a temp tree and diff: `meta verify --codegen`
- **The drift gate per port** — regenerate in memory and diff: `meta verify --codegen`
(TS); `mvn metaobjects:verify` (Java/Kotlin; `codegen` is the default mode); `dotnet meta
verify --codegen` (C#; bare `verify` runs it when `csharp.outDir` (or `--out`) and `codegen/Generators.cs` are present);
`metaobjects verify` (Python; `--codegen` is part of the default). Source: `docs/features/cli.md`.
Expand Down
5 changes: 3 additions & 2 deletions docs/CONFORMANCE.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Conformance coverage

The MetaObjects standard ships **34 shared conformance corpora** under
The MetaObjects standard ships **35 shared conformance corpora** under
[`fixtures/`](../fixtures/). Every port runs every corpus that is *applicable to
it* and asserts the same expected behaviour against the same fixtures. **This page
is the inverse index**: fixture → feature doc + per-port pass status, and it is the
Expand Down Expand Up @@ -58,6 +58,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l` for directory-shaped corpor
| [`fixtures/requirement-test-identity-conformance/`](../fixtures/requirement-test-identity-conformance/) (the identity, skip state and digest of each generated requirement test, and the filter seam, ADR-0057) | 26 cases | ✓ (reference) | ✓ | identity function inherits via Java; emitted names asserted by its own generator test | ✓ | ✓ |
| [`fixtures/naming-conformance/`](../fixtures/naming-conformance/) | 8 cases | ✓ | ✓ | inherits via Java (`RouteNaming.pluralize`) | ✓ | ✓ |
| [`fixtures/wire-conformance/`](../fixtures/wire-conformance/) (the `wire` setting, ADR-0019 Amendment 2) | 6 cases + 8 refusals | ✓ | ✓ | inherits via Java (one config reader) | ✓ | ✓ |
| [`fixtures/codegen-skip-conformance/`](../fixtures/codegen-skip-conformance/) (when `gen` may skip and what a local `verify --codegen` may answer, ADR-0062) | one case table in `cases.json` | ✓ | ✓ | ✓ (through the Java runner) | ✓ | ✓ |
| [`fixtures/codegen-noop/`](../fixtures/codegen-noop/) (FR-044 — reporting vocabulary: what is lowered, what stays inert) | 1 model pair (`reporting/with` vs `reporting/without`) | ✓ (codegen + migrate) | ✓ | ✓ | ✓ | ✓ |
| [`fixtures/cube-model/`](../fixtures/cube-model/) (FR-044 Plan 4 — the `cube-model` generator's golden Cube files, plus the canonical model's golden) | 46 cases (36 trees + 10 errors) + 1 canonical golden | ✓ (the exporter is TypeScript-only, spec R6; its `cube` lane also loads the files into a real Cube) | — | — | — | — |

Expand Down Expand Up @@ -87,7 +88,7 @@ the corpora above do two different jobs. Only the first is a promise to adopters
(the canonical serializer, surfaced per-file — ADR-0034's "canonical format" is core),
`field-lint-conformance/` (the advisory field lint every port's `verify` prints) and
`requirement-check-conformance/` (the requirement gate every port's `verify` runs; a
drift gate is core, and it is not ejectable in any port).
drift gate is core, and it is not ejectable in any port). `codegen-skip-conformance/` (ADR-0062: which changes make `gen` render, and what a local `verify --codegen` may answer from the stored key) is core for the same reason.
A red cell here is a MetaObjects bug.
- **Template quality checks — not a promise.** The generated lane of
`api-contract-conformance/`, `generator-registry-conformance/` (stable generator names),
Expand Down
30 changes: 27 additions & 3 deletions docs/features/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ vocabulary everywhere, each port implementing the modes it supports.
| Subverb | What it checks | Touches a DB? |
|---|---|---|
| `verify --db` | **Schema drift** — does the live database (or snapshot) match the metadata? (migrate engine, ADR-0015) | yes |
| `verify --codegen` | **Codegen drift** — regenerate from metadata into a temp dir and fail if it differs from the committed generated output. Catches "metadata changed but `meta gen` wasn't re-run". A hand-edited generated file is NOT drift — `meta gen` three-way-merges hand edits by design, so the gate compares the *generated contribution* against the committed `.gen-state/.hashes.json` rather than the file byte-for-byte. It still LISTS every generated file carrying a hand edit (count + paths, and how to see the edit) as a notice that does not change the exit code; `--forbid-hand-edits` makes any hand edit fail the build, for teams that want generated code untouchable (Node `meta` only). | no |
| `verify --codegen` | **Codegen drift** — regenerate from metadata in memory and fail if it differs from the committed generated output. Catches "metadata changed but `meta gen` wasn't re-run". A hand-edited generated file is NOT drift — `meta gen` three-way-merges hand edits by design, so the gate compares the *generated contribution* against the committed `.gen-state/.hashes.json` rather than the file byte-for-byte. It still LISTS every generated file carrying a hand edit (count + paths, and how to see the edit) as a notice that does not change the exit code; `--forbid-hand-edits` makes any hand edit fail the build, for teams that want generated code untouchable (Node `meta` only). | no |
| `verify --templates` | **Template/prompt drift** — `Renderer.verify` checks each `template.*` node's `{{field}}` references against its payload VO (FR-004). A Jinja body (Python and TypeScript, ADR-0061) is checked the same way. | no |
| `verify --docs` | **Removed in 1.1.0** (ADR-0034 Amendment 9). It prints where the check went and exits 2: documentation is written by entries in `generators`, so `verify --codegen` checks it with the rest of the declared output. | — |
| `verify --deps` | **Dependency drift** (FR-023) — re-resolves each declared dependency (its `path`, or its installed `npm` / `python` package) and compares its installed artifact's hash against `.metaobjects/deps.lock.json`, same comparison as `meta deps check`. Needs the publisher reachable, so it is never part of the bare-`verify` default. A `drifted` or `unresolved` dependency fails with `ERR_DEPENDENCY_UPSTREAM_DRIFT`. **Node `meta` only.** See [`metadata-dependencies.md`](metadata-dependencies.md). | no |
Expand Down Expand Up @@ -211,7 +211,7 @@ ADR-0015"). Bare `verify` runs `--codegen` and `--templates` (the template gate
with a note when the run names no config and no `--prompts`). The **C# `dotnet
meta`** port likewise ships the codegen-side subverbs: `verify --templates` (its
historical template/prompt drift gate), `verify
--codegen` (regenerate the configured generators to a temp dir and diff against
--codegen` (regenerate the configured generators in memory and diff against
the committed `--out` tree, never touching it), and a **clean `--db` rejection
(exit 2)** — bare `dotnet meta verify` runs `--templates` and, when an output
directory and `codegen/Generators.cs` are present, `--codegen`. The output directory is
Expand Down Expand Up @@ -253,6 +253,30 @@ that differs refuses the whole call and removes nothing. It never edits your gen
edit that points each entry back at the shipped generator. `--strict` exits 1 and writes
nothing. No port has a `doctor` command: `eject --list` (or the matching goal) is the report.

## `gen` skips a run when nothing changed — and `--force` runs it anyway (ADR-0062)

Every port's `gen` loads the metadata, then computes a key before it renders anything: the
loaded model (each node in its canonical effective form, so reformatting or splitting a metadata
file changes nothing) plus everything the generators are built from (the engine's built code,
the codegen config and every owned generator, the template roots, declared extra inputs, the
project config, the output-changing flags). When the key matches the last successful run and
every generated file still holds the bytes that run left, `gen` says so and renders and writes
nothing. The key lives in `.metaobjects/.gen-state/.fingerprint-<port>.json`, which is not
committed.

| flag | ports | what it does |
|---|---|---|
| `gen --force` | `meta`, `metaobjects`, `dotnet meta` | render everything, even when nothing changed |
| `-Dmetaobjects.force=true` / `<force>true</force>` | Maven (Java, Kotlin) | the same |
| `verify --codegen --full` | `meta`, `metaobjects`, `dotnet meta` | render and compare, even when a local run could answer from the key |
| `-Dmetaobjects.verify.full=true` | Maven (Java, Kotlin) | the same |

A generator that reads something the key does not cover declares it (`inputs: [...]` in
TypeScript, its port's equivalent elsewhere); one that cannot say what it reads sets
`cache: false`, and a run that includes it never skips. In CI (`CI` set) `verify --codegen`
always renders and compares everything, so a key that missed an input is caught before it
ships. When `verify` renders, it compares in memory: no temp tree is written.

## `gen` refuses rather than guesses — and `--baseline` is how you answer it

Every port's `gen` decides per file whether it may overwrite, from a committed hash
Expand Down Expand Up @@ -434,7 +458,7 @@ targets:
the declared entries named (an owned entry matches its registry name too) and refuses a
name no target declares. A target whose `generators` is empty writes nothing and says so.
- **`metaobjects verify --codegen`** — also run by bare `verify`, which adds `--templates`
(see above) — regenerates the same list into a temp tree (the exact `gen`
(see above) — regenerates the same list in memory (the exact `gen`
pipeline, including the cross-target duplicate-output-path guard) and diffs each **unique
`outDir`** against the union of the co-resident targets' regen, aggregating the exit code
(non-zero if *any* outDir has drifted). Targets sharing an `outDir` are verified together,
Expand Down
Loading
Loading