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
The table of contents is too big for display.
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/` (510 fixtures; 38 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/` (510 fixtures; 39 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
238 changes: 193 additions & 45 deletions CHANGELOG.md

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ What the repository does, built on the generated contract:
// its wire contract (<E>InsertSchema, <E>UpdateSchema, <E>FilterAllowlist); this emits the
// data access over it. The collection name comes from an author-supplied `@mongo` property
// bag on the entity: `"@mongo": { "collection": "orders" }`.
import { isSourcelessEntity, perEntity, type Generator } from "@metaobjectsdev/codegen-ts";
import { effectivePackage, entityOutputPath, isSourcelessEntity, perEntity, type Generator } from "@metaobjectsdev/codegen-ts";
import type { MetaObject } from "@metaobjectsdev/metadata";

function collectionOf(obj: MetaObject): string {
Expand Down Expand Up @@ -155,7 +155,11 @@ export function mongoRepositoryGenerator(): Generator {
return {
name: "mongo-repository",
filter: isSourcelessEntity,
generate: perEntity((obj) => ({ path: `${obj.name}.repository.ts`, content: render(obj) })),
// Beside the entity file it imports (`./<Entity>.js`), in either output layout.
generate: perEntity((obj, ctx) => ({
path: entityOutputPath(ctx.renderContext?.outputLayout ?? "flat", effectivePackage(obj), `${obj.name}.repository.ts`),
content: render(obj),
})),
};
}
```
61 changes: 33 additions & 28 deletions docs/CONFORMANCE.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Conformance coverage

The MetaObjects standard ships **38 shared conformance corpora** under
The MetaObjects standard ships **39 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 @@ -57,9 +57,10 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l` for directory-shaped corpor
| [`fixtures/field-lint-conformance/`](../fixtures/field-lint-conformance/) (the `verify` field authoring lint) | 15 | ✓ (reference) | ✓ | inherits via Java | ✓ | ✓ |
| [`fixtures/requirement-check-conformance/`](../fixtures/requirement-check-conformance/) (the `verify` requirement gate, ADR-0057) | 43 cases | ✓ (reference) | ✓ | inherits via Java (one Maven `metaobjects:verify` goal) | ✓ | ✓ |
| [`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/naming-conformance/`](../fixtures/naming-conformance/) | 8 cases + 23 collection segments (`@collectionName`, `naming.collections`) | ✓ | ✓ | inherits via Java (`RouteNaming.pluralize`, `RouteNaming.collectionSegment`) | ✓ | ✓ |
| [`fixtures/wire-conformance/`](../fixtures/wire-conformance/) (the `wire` setting, ADR-0019 Amendment 2) | 6 cases + 8 refusals | ✓ | ✓ | inherits via Java (one config reader) | ✓ | ✓ |
| [`fixtures/enum-length-conformance/`](../fixtures/enum-length-conformance/) (a string-stored enum's column length: `@maxLength`, else `enums.maxLength`) | 5 cases + 1 overflow + 5 refusals; run by a port that sizes the column | ✓ | ✓ | inherits via Java (one config reader, one resolver) | ✓ | — (sizes no column: emits no DDL or column type; the config reader accepts and shape-checks the `enums` block) |
| [`fixtures/check-constraint-conformance/`](../fixtures/check-constraint-conformance/) (the CHECK constraints `meta migrate` derives: name and expression text per dialect) | 1 model, 5 expected files (postgres, sqlite, d1, and both skip-redundant variants) | ✓ (reference, `migrate-ts`) | — (no CHECK in a generated model) | — (same) | ✓ (the EF context declares them; live-Postgres `EnsureCreated` lane) | — (same) |
| [`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) | — | — | — | — |
| [`fixtures/contract-conformance/`](../fixtures/contract-conformance/) (FR-022 — the `contract-schema` and `openapi` generators' golden trees and refusals) | 19 cases (14 trees + 5 errors) | ✓ (one neutral engine, ADR-0034 Amendment 10; the generated API lanes also hold real traffic to the documents) | — | — | — | — |
Expand Down Expand Up @@ -111,27 +112,29 @@ corpora, or between its *vocabulary* and its *behaviour* — never gets a row of
own, and its boundary ends up discoverable only from the feature doc. The split ones
are recorded here instead.

**`identity.primary @sequenceStart`** (one semantic in every port): on a fresh
**`identity.primary @sequenceStart`** (one semantic in every port that writes DDL): on a fresh
database the identity or sequence begins at `@sequenceStart`; when the start changes on an
existing database, the change sets `START WITH` only. It never `RESTART`s, and in 1.3 it does
not move the current value, because live rows already hold the ids it has handed out (a later
release is planned to move a counter below the start forward, never backward). The port TODOs below
are tracked in [#544](https://github.com/metaobjectsdev/metaobjects/issues/544).

existing database, the change sets `START WITH n` and moves the counter FORWARD only, to
`GREATEST(n, max(id) + 1)` when it sits below that. It never `RESTART`s and never moves a counter
back, because live rows already hold the ids it handed out. Tracked in
[#544](https://github.com/metaobjectsdev/metaobjects/issues/544).

- *Honoured and pinned:* TypeScript (`meta migrate`). A fresh table is created `START WITH n`, and
the Drizzle schema template carries the start. A changed start writes `ALTER SEQUENCE … START
WITH n` plus an advance-only `setval`. The persistence migration scenarios
`sequence-start-change-moves-counter-forward` and `sequence-start-change-below-max-id` pin on
live Postgres that the next id is the start, or the highest id plus one when a row already
holds an id past the start.
- *Honoured and pinned:* C#. The generated context carries the start on Npgsql, and the generated
rewrite (`UseIdentityStartMigrations()`) writes every start-only change — added, changed or
removed — as `ALTER TABLE … ALTER COLUMN … SET START WITH n`, whether the migration is scaffolded
through it or its SQL is generated through it (Npgsql alone writes `RESTART WITH n`, or
`RESTART WITH 1` for a removed start). `EfModelGapsTests` pins all three transitions on both
paths, and on live Postgres that the next id after the change follows the last row.
- *Honoured and pinned:* TypeScript (`meta migrate`). A fresh table is created `START WITH n`;
a changed start writes `ALTER SEQUENCE … START WITH n` only. The persistence migration
scenario `sequence-start-change-keeps-counter` pins on live Postgres that the next id after
the change follows the last row.
- *TODO, Java (OMDB) and Kotlin (Exposed):* the vocabulary loads; neither emits or honours the
start in its DDL or mapping. Add it with the same semantic and the same pin.
- *TODO, Python:* the vocabulary loads; the runtime has no DDL path. If it gains one, the same
semantic and pin apply.
`<Context>DesignTimeServices` makes `dotnet ef migrations add` scaffold a start-only change as
`SET START WITH n` plus the same advance-only move (Npgsql alone writes `RESTART WITH n`).
`EfModelGapsTests` pins the transitions, and on live Postgres the next id after the change.
- *Honoured and pinned:* Kotlin (Exposed 0.x and 1.x). A declared start or name generates
`autoIncrement(Sequence("<name>", startWith = n))`; a live-Postgres test pins that a fresh
table's first id is the start. Exposed generated code has no migration path, so a changed start
is `meta migrate`'s job.
- *Not applicable:* Java (OMDB is pure data access with no DDL, ADR-0015) and Python (no DDL
path). The vocabulary loads in both; schema comes from `meta migrate`.

**Cross-port vocabulary implemented in some ports so far (`implementedIn`).** Each entry
below is in the shared registry and the registry manifest, marked `implementedIn`. A port that
Expand All @@ -148,12 +151,6 @@ canonical (`fixtures/registry-conformance/expected-registry.json`).
- `view.image`, and its `@accept`, `@aspectRatio`, `@maxBytes`, `@maxEdge`, `@store`
- *Implemented in Java only* (`implementedIn: ["java"]`): `object.* @object` (ADR-0001), the
native class an object binds to. Java's runtime acts on it; Java's own behaviour is unchanged.
- *Implemented in C# and TypeScript* (`implementedIn: ["csharp", "typescript"]`): `object.*
@collectionName`, an object's collection name: the REST collection segment and reverse-finder
names in both, the DbSet in C#, the list function, list hook and Drizzle table variable in
TypeScript. Both apply the `naming.collections` pluralizer to an object that declares none
(`fixtures/naming-conformance/collection-segments.json`); every port registers and type-checks
the attr and the key.
- *Loads strictly in every port.* Each port registers the `metaobjects-ui-web` provider
(`view.textarea @rows`, the `view.image` attrs) and `@object` / `@objectAdapter` on
`object.*`, loads all three fixtures strictly, and emits `implementedIn` in its manifest, which
Expand Down Expand Up @@ -286,6 +283,10 @@ manifest contains without moving these boundaries.
classpath and stubbing them drowns the signal; that tier is compiled and booted over
real HTTP in the api-contract integration lane instead. The boundary is one
cross-port rule, not four local concessions.
- *The gate and the generated-server api-contract lanes run in both output layouts* —
the engine default `flat` and `outputLayout: "package"` (which `meta init` writes) —
so a defect only the non-default layout shows (a relative import one directory short,
two packages landing in one directory) fails a gate rather than an adopter's build.
- *The prompt tier is out of scope here* because the fitness corpus declares no
`template.*` nodes. Including those generators would emit nothing and read as
coverage that is not there.
Expand Down Expand Up @@ -610,7 +611,11 @@ only `KotlinSharedModelGeneratorTest`. **C# runs all 15**, in `SharedModelConfor
> recorded here rather than in a ledger, because ledgering a fixture the design intends to pass
> is how a port quietly stays behind.

### `fixtures/naming-conformance/` (8 cases)
### `fixtures/naming-conformance/` (8 cases + 23 collection segments)

`collection-segments.json` (23 cases) pins the REST collection segment from an object's
`@collectionName` and the project's `naming.collections` pluralizer; every port runs it (see the
corpus README). The pluralize cases:

All 8 cases → the already-plural pluralize fix (CHANGELOG `## [Unreleased]`):
an entity whose name is already a plural noun (`Stats`, `Settings`, `Series`)
Expand Down
5 changes: 4 additions & 1 deletion docs/features/api-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,10 @@ every field. The TS mounts can restrict the update to one verb with

`<entity>` is the **entity name** `snake_case`d and then pluralized. One rule, the
same in all five ports, and derived from the NAME — never from the physical
`@table`:
`@table`. An object that declares `@collectionName` (or a project that configures
`naming.collections`) names its segment instead, in every port; the rule and what
each port names with it live in
[physical-naming.md](migrations/physical-naming.md#collection-names).

| Name | Segment | Why |
|---|---|---|
Expand Down
2 changes: 1 addition & 1 deletion docs/features/cube-export.md
Original file line number Diff line number Diff line change
Expand Up @@ -568,7 +568,7 @@ there.

| Difference | Why | Effect |
|---|---|---|
| Joins | Cube compiles every join to a `LEFT JOIN`. The view joins a required belongs-to reference `INNER`. | A fact row whose reference matches no row forms a null group in Cube and is dropped by the view. A foreign key constraint on the column makes such a row impossible. |
| Joins | Cube compiles every join to a `LEFT JOIN`. The view's joins are `LEFT OUTER` too, everywhere (they inner-joined a required reference before). | A fact row whose reference matches no row forms a null group in Cube and, through the outer join, in the view as well. A foreign key constraint on the column makes such a row impossible on the conformance data. |
| Query time zone | A Cube query may pass `timezone`. The view is UTC only. | With a zone other than `UTC`, Cube re-buckets instants, which is its feature, and also shifts naive timestamps and dates, which the view buckets as stored. |
| Grains | Cube offers every granularity on a time dimension. | `@grains` is carried as `meta.grains`, not enforced. |
| Ad-hoc queries | Cube lets a caller pick any members. | Nothing here checks the numbers for a combination no report declares. |
Expand Down
10 changes: 10 additions & 0 deletions docs/features/field-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,16 @@ Two rules the loader/codegen enforce:
abstract enum is inline as well. Declaring the vocabulary at package level is how
you ask for one type.

**Two package-level shared enums with one name are refused.** TypeScript and Python
generate every shared enum into one shared module under its own name, so a second
`Tier` in another package would keep the first and silently type its fields with the
first's members; the pair is a codegen error, `ERR_NAME_COLLISION`, naming both
declarations. Place them apart: the package output layout does not split the shared
module (rename one). C# puts each in its package's own namespace when
`csharp.packageNamespaces` is on; without it both would declare one type in one
namespace, and the pair is refused the same way. Java and Kotlin write each in its
package's own directory, so the pair never meets.

## Embedded value objects — `field.object` + `@storage`

`field.object` declares an embedded structured value backed by another `object`
Expand Down
17 changes: 10 additions & 7 deletions docs/features/migrations-and-drift.md
Original file line number Diff line number Diff line change
Expand Up @@ -305,12 +305,12 @@ existing column with the same options), and `meta verify --db` reads the live se
from the catalog. A live sequence whose start or name differs from the declaration is altered
in place, never dropped:

- a different start records it (`ALTER SEQUENCE … START WITH n`) and nothing else. It never
restarts the sequence, and in this release it does not move its current value, because live
rows already hold the ids it handed out: `@sequenceStart` is the first value of a fresh
sequence, the same in every port. The down migration restores the old start value, again
without touching the counter. A later release is planned to move a counter that sits below
the declared start forward to it (never backward), so do not rely on the counter staying put.
- a different start records it (`ALTER SEQUENCE … START WITH n`) and moves the counter forward
only: when the next value would be below `GREATEST(n, max(id) + 1)`, a `setval` moves it there.
It never restarts the sequence and never moves a counter back, because live rows already hold
the ids it handed out. The down migration restores the old start value and leaves the counter
where it is. Every port that writes DDL holds the same rule (C# through its generated design-time
services, Kotlin's Exposed table on a fresh database).
- a different name renames it (`ALTER SEQUENCE … RENAME TO …`); the down renames it back.

Only what the model declares is compared, on every path (a live database, a shadow database,
Expand Down Expand Up @@ -415,7 +415,10 @@ the re-diff is empty afterwards. Postgres keeps `IS [NOT] DISTINCT FROM`.

### CHECKs from validators: names, conditions, how many

A `validator.*` node and a `field.enum`'s member list each become a CHECK constraint. Three
A `validator.*` node and a `field.enum`'s member list each become a CHECK constraint. A validator
on a derived field — one carrying an `origin.*`, or a cross-field validator naming one — makes
none: the field is no column of the table, so a CHECK on it would fail `CREATE TABLE`; the C#
context skips the same validators. Three
attributes shape it, all database-only (no generated code reads them):

- **`@constraintName`** names the CHECK, for a database whose CHECKs were named by hand. On the
Expand Down
Loading
Loading