Skip to content

Commit 56a4d89

Browse files
authored
feat(codegen): uniform entity selection across ports and a linear Java metadata loader (#588)
* feat: Java loader handles large models; even out object selection across ports Java loader (also Kotlin): - Remove the quadratic child-key check (list -> set) and resolve references through the per-type name index. 20 copies of the canonical model (1,160 objects) load in about 2 s CPU; it previously exceeded the 30 s timeout. - The 30 s init timeout is now a setting: LoaderOptions.setInitTimeoutMs, loader arg initTimeoutMs, -Dmeta.loaderTimeoutMs on the Maven plugin, or -Dmetaobjects.loader.initTimeoutMs. LargeModelLoadTest holds a CPU budget. Selection parity: - codegen-spring and codegen-kotlin generators now honour <filters> (confirmed by running that they ignored them before). - mvn metaobjects:generate -Dmeta.entities=A,B narrows per-object output for Java and Kotlin; whole-model files still render from the whole model, a narrowed run sweeps no orphans, and blank or unknown names fail the goal. - C# dotnet meta gen/verify --codegen --entities, with the same semantics. - Python gen lists only the files it changed and counts the rest unchanged. - Selection documented on every port page; CHANGELOG under [Unreleased]. * feat(cli): meta gen refuses a positional name that matches no object Every other port refuses an unknown --entities / meta.entities name; TypeScript dropped it silently when another name matched and only warned when none did. Now exit 2 with the same wording, before anything is written. * no-mistakes(review): apply reviewer inline fixes * no-mistakes(review): apply reviewer inline fixes * no-mistakes(review): Narrow template scopes; keep C# shared files whole * no-mistakes(document): Fix stale entity-selection references in docs
1 parent 624a54c commit 56a4d89

54 files changed

Lines changed: 1406 additions & 110 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.

‎CHANGELOG.md‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@ loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersi
2525
assigned one (`row.Role = ...`) no longer compiles. The value belongs to the server: set it
2626
through a database default or EF Core (`db.Entry(row).Property(r => r.Role).CurrentValue`),
2727
which writes private setters.
28+
- **Java and Kotlin: `<filters>` now narrow every generator.** The `codegen-spring` and
29+
`codegen-kotlin` generators ignored a generator's `<filters>` and wrote every object; they now
30+
honour them, as the `codegen-base` generators always did. A pom whose filters were inert
31+
generates fewer files: remove the `<filters>` that no longer describe what you want.
2832

2933
### Security
3034

@@ -92,6 +96,21 @@ loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersi
9296
the new `fixtures/writer-conformance/` corpus. No shipped generator uses the writer yet, so
9397
generated output does not change in this release.
9498

99+
- **Select objects to regenerate in every port.** C# `dotnet meta gen --entities A,B` (and
100+
`verify --codegen --entities`) and, for Java and Kotlin, `mvn metaobjects:generate
101+
-Dmeta.entities=A,B` regenerate only the named objects' files, like TypeScript's
102+
`meta gen A B` and Python's `--entities`. Names are short object names. A file built from the
103+
whole model (C#'s `AppDbContext`, the Java and Kotlin validator registry, report export writer
104+
and binding provider) still renders from the whole model, a narrowed run neither deletes nor
105+
forgets the other objects' files, and a blank selection or a name that matches no object is
106+
refused (exit 2 in C#, a failed goal in Maven).
107+
- **`meta gen <Name>...` refuses a name that matches no object**, with exit 2 and nothing
108+
written, as Python, C# and the Maven plugin do. It used to drop the unknown name silently
109+
when another name matched, and only warn when none did.
110+
- **The Java loader's initialization timeout is a setting.** It stays 30 seconds by default. Raise
111+
it with `-Dmeta.loaderTimeoutMs` (or `<loaderTimeoutMs>`) on the Maven plugin,
112+
`LoaderOptions.setInitTimeoutMs`, the loader argument `initTimeoutMs`, or the system property
113+
`metaobjects.loader.initTimeoutMs`; the timeout error names them.
95114
- **A page size for generated list routes: `api.pagination`, in every port.** An external review
96115
of 1.2.0 found that list endpoints had no hard cap: the TypeScript and C# routes returned the
97116
whole table when `limit` was omitted, and `?limit=100000` was accepted in every port. The new
@@ -322,15 +341,21 @@ loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersi
322341

323342
### Fixed
324343

344+
- **The Java loader loads a large model.** Each child added to a node was checked against a
345+
list of the keys already added, so a root with 1,160 objects took more than the 30-second
346+
timeout to load and failed. The check is a set lookup now, and a reference resolves through
347+
the per-type name index instead of a scan of the root. Twenty copies of the canonical
348+
conformance model (1,160 objects) load in about 2 seconds of CPU, and `LargeModelLoadTest`
349+
holds that to a budget. Java and Kotlin.
325350
- **`gen <Entity>` no longer shrinks the files rendered from the whole model.** Narrowing a run
326351
to some entities (`meta gen Post`, Python `metaobjects gen --entities Post`) handed every
327352
generator only the named entities, so a whole-model file (the TypeScript barrel and Cube
328353
model, Python's shared enums module, duration codec and report writers, and the object index
329354
Python's entity and route generators resolve relations through) was rendered from just them. A narrowed run now writes only the named entities' own files,
330355
and every whole-model file it writes is byte-identical to a full run's. A generator sees the
331356
whole model in `ctx.entities` and the narrowing as `ctx.selected`; `perEntity` (`per_entity`)
332-
applies it. A Python target's declared `entities` still bounds that target's model. C# and
333-
Java take no entity filter and were not affected. Two consequences to expect: a narrowed run
357+
applies it. A Python target's declared `entities` still bounds that target's model. The C# and
358+
Maven entity selection added in this release follows the same rule. Two consequences to expect: a narrowed run
334359
checks the whole model as a full run does (a sourced object with no `dialect`, colliding
335360
collection names), because the files it writes are rendered from it; and an owned generator
336361
that writes one file per object by looping over `ctx.entities` itself, instead of through

‎docs/features/metadata-dependencies.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -708,8 +708,11 @@ the snapshots first under `dep:<name>/<artifact>` source ids. It never writes ei
708708
POCO of a *value object* (and the shared enums it uses) that a generated type reaches — an entity
709709
or local value object that holds it, or a local template whose `@payloadRef` / `@responseRef` names
710710
it — because that generated type needs it to compile. `inScope` is Python's formula (no `matchesScope` on the
711-
project's own objects), and C# has no entity-name positional on `gen`, so the TypeScript
712-
"refuse an explicitly named imported object" check has no C# surface. Known edge: a local entity
711+
project's own objects). `dotnet meta gen --entities` resolves names against the in-scope
712+
objects only, so naming an excluded import is refused the way TypeScript's "refuse an
713+
explicitly named imported object" check refuses it (exit 2, `--entities names 'X', which
714+
matches no object in the metadata.` — C#'s wording, not TypeScript's imported-specific
715+
message). Known edge: a local entity
713716
that `extends` an imported concrete entity in a table-per-hierarchy mapping is not specially handled.
714717

715718
## Vendoring vs. depending

‎docs/features/own-your-codegen.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -593,7 +593,8 @@ handles those files by one rule:
593593

594594
- **Only a full run cleans up.** A run of the project's whole generator list decides; a run
595595
narrowed to some generators (`--generators`), to some entities (`meta gen <Entity>`,
596-
`metaobjects gen --entities`), or to a target that shares its directory with a target left
596+
`metaobjects gen --entities`, `dotnet meta gen --entities`, Maven `-Dmeta.entities`), or to
597+
a target that shares its directory with a target left
597598
out, deletes nothing, because the files of the part it skipped would all look stale. So
598599
does `--baseline=adopt`, which writes nothing by definition.
599600
- **A candidate is a file the manifest says `gen` wrote.** It lies under an output directory
@@ -614,8 +615,10 @@ handles those files by one rule:
614615
that name is not mistaken for generated output.
615616
- **A dry run** (`meta gen --dry-run`) reports what it would remove and removes nothing.
616617

617-
On **Java and Kotlin** every `mvn metaobjects:generate` execution is a full run, since its
618-
`<generators>` list is always complete. Every manifest entry names its owner: the generator's
618+
On **Java and Kotlin** every `mvn metaobjects:generate` execution runs the whole
619+
`<generators>` list, since there is no `--generators` narrowing; a run narrowed by
620+
`meta.entities` is the one exception, and it deletes no orphaned file (see
621+
[Select objects](../ports/java.md#generate) on the Java page). Every manifest entry names its owner: the generator's
619622
registry id and its output directory within the module, not the Maven execution, so
620623
`default-cli`, a renamed execution and the lifecycle execution agree. A recorded file no
621624
generator emitted in this build is an orphan when this run's own generators own it, or when

‎docs/ports/csharp.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,21 @@ reference their output; `gen` warns when one is missing from the list, since the
295295
would not compile. `--generators <names>` narrows a run to the declared entries named; it
296296
never adds one, and naming an entry the list does not declare is refused.
297297

298+
**Select objects.** `dotnet meta gen --entities Product,Supplier` (comma-separated short object
299+
names, the `name` of the object without its package, as TypeScript's positional names and
300+
Python's `--entities` match) regenerates only those objects' files; `dotnet meta verify --codegen
301+
--entities ...` checks only the same files. Only per-object output narrows. A file built from
302+
the whole model, such as `AppDbContext.g.cs`, still renders from the whole model and is
303+
byte-identical to an unfiltered run, and a shared file (a shared enum, a helper) is the
304+
whole-model rendering too. A generator that reads the model root rather than the object list
305+
(`api-docs`, `requirement-tests`, template entries) is not narrowed. A narrowed run never
306+
deletes a stale file and never drops the manifest entry of a file it did not write, so the
307+
unselected objects' files are left as they are; run `gen` without the flag to sweep. Two
308+
refusals, both exit 2: `--entities` naming nothing (`error: dotnet meta gen: --entities names no
309+
object.`) and a name that matches no object (`error: dotnet meta gen: --entities names 'X',
310+
which matches no object in the metadata.`). An owned generator whose output is a single
311+
whole-model file declares `public bool WholeModel => true;`.
312+
298313
**Own a generator.** `dotnet meta eject <name>...` copies a reference generator into
299314
`codegen/generators/`. Every generator `dotnet meta gen --list` shows is ejectable except
300315
`template`, the Mustache primitive, which has no emit logic of its own to own. An ejected

‎docs/ports/java.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,27 @@ mvn metaobjects:generate # or run it alone
295295
The generators write the DTO records, the Spring controller, the repository and the filter
296296
allowlist under `target/generated-sources/java`, which Maven compiles with your code.
297297

298+
**Select objects.** `mvn metaobjects:generate -Dmeta.entities=Program,Week` (or
299+
`<entities>Program,Week</entities>` in the plugin `<configuration>`) regenerates only those
300+
objects' files: comma-separated short object names, the selection TypeScript's
301+
`meta gen Program Week` and the `--entities` flag in Python and C# make. Only per-object output
302+
narrows. A file built from the whole model (a validator registry, the report export writer,
303+
the class-binding provider, a package's wire support classes) still renders from the whole model
304+
and is byte-identical to an unnarrowed run. A narrowed run deletes no orphaned file and keeps
305+
the manifest entry of every file it did not write; run without the property to sweep. Two
306+
refusals fail the goal: a blank selection (`mvn metaobjects:generate: meta.entities names no
307+
object.`) and a name that matches no object (`... meta.entities names 'X', which matches no
308+
object in the metadata.`). Each generator's `<filters>` apply on top. Unlike the selection, a
309+
generator's `<filters>` narrow its whole-model files too, since they configure that generator.
310+
Through 8.2.x the `codegen-spring` and `codegen-kotlin` generators ignored `<filters>`; from
311+
8.3.0 they honour them, so a pom whose filters were inert now generates less.
312+
313+
**Large models.** The loader gives initialization 30 seconds by default. A model large enough
314+
to need longer sets `-Dmeta.loaderTimeoutMs=120000` (or `<loaderTimeoutMs>` in the plugin
315+
`<configuration>`). Outside Maven, the same setting is `LoaderOptions.setInitTimeoutMs`, the
316+
loader argument `initTimeoutMs`, or the system property `metaobjects.loader.initTimeoutMs`.
317+
The timeout error names all three.
318+
298319
## Verify
299320

300321
```bash

‎docs/ports/kotlin.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -507,6 +507,12 @@ mvn metaobjects:generate # or run the codegen alone
507507
mvn metaobjects:verify # fails, naming the files, when generated code is stale against the model
508508
```
509509

510+
`-Dmeta.entities=Program,Week` regenerates only those objects' files, and each generator's
511+
`<filters>` narrow what it writes; `-Dmeta.loaderTimeoutMs` raises the loader's 30-second
512+
initialization timeout for a large model. Both are the Maven plugin's, shared with Java: see
513+
[Select objects](java.md#generate) on the Java page for what narrows, what stays whole-model,
514+
and the refusals.
515+
510516
Schema migrations are owned by the TypeScript toolchain — see the
511517
[Migrations section](../features/migrations-and-drift.md#kotlin) for the `meta migrate` commands.
512518

‎docs/ports/python.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,17 @@ config is refused. Column naming is not a Python setting at all: it is `naming`
186186
([physical-naming.md](../features/migrations/physical-naming.md)). See [the migration section](../features/migrations/docs-are-generators.md#python)
187187
and the [config reference](../features/cli.md).
188188

189+
**Select objects.** `metaobjects gen --entities Program,Week` (comma-separated short object
190+
names) regenerates only those objects' files; a target that lists `entities` keeps only the
191+
names in both. `metaobjects verify --codegen --entities ...` checks the same files. A narrowed
192+
run deletes no orphaned file; run without the flag to sweep. Two refusals, both exit 2:
193+
`--entities` naming nothing (`error: metaobjects gen: --entities names no object.`) and a
194+
name that matches no object (`error: metaobjects gen: --entities names 'X', which matches no
195+
object in the metadata.`). The same selection is a positional name list in TypeScript
196+
(`meta gen Program Week`), `--entities` in C#, and `-Dmeta.entities` on the Maven plugin.
197+
`gen` lists the files it changed and counts the rest separately
198+
(`metaobjects gen: wrote 2 file(s) across 1 target(s). 40 file(s) left as they were.`).
199+
189200
**Start a project.** `metaobjects init` writes `metaobjects.config.yaml` (one `app` target
190201
with no generators) and an empty, loadable `metaobjects/meta.app.yaml`, and reports what it
191202
wrote. It never overwrites a file it finds; it says it kept it. `metaobjects init --with-docs`

‎docs/ports/typescript.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -319,6 +319,12 @@ meta verify --codegen # committed output, docs included, vs a fresh regen
319319
meta verify --db <url> # live DB schema vs metadata
320320
```
321321

322+
`meta gen Author Post` names objects by their short name (without the package). Each
323+
generator's `filter` option applies on top. A name that matches no object is refused with
324+
exit 2 before anything is written, even beside names that match (`meta gen: names 'Ordr',
325+
which matches no object in the metadata.`). Every port has the same selection: `--entities` in Python and C#,
326+
`-Dmeta.entities` on the Maven plugin for Java and Kotlin.
327+
322328
### Schema — first migration on a brand-new database
323329

324330
`meta migrate` diffs your metadata against a **committed schema snapshot**,

0 commit comments

Comments
 (0)