diff --git a/AGENTS.md b/AGENTS.md index eec83c4b17..8808485aa9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 933b82d2c9..f3a4d4e40b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,25 @@ loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersi ### Changed +- **Breaking, TypeScript: a value object is never renamed; one claim registry refuses real + collisions** (amending ADR-0044 and ADR-0056). `acme::alpha::Note` is declared as `Note` in its + own module; the `AcmeAlphaNote` derived name, `assignEmittedNames` and its + `ERR_PAYLOAD_NAME_COLLISION` backstop (`naming/collision-names.ts`) are removed — the + entity-tier `ERR_COLLECTION_NAME_COLLISION` pre-pass (`naming/collection-name-collision.ts`) + stays, refusing two objects that claim one collection name — + and `RenderContext.valueObjectNames` and `RenderContext.packageOf` are `@deprecated` identity + shims for one release. Each generator claims what it emits through + `ctx.claim(scope, name, claimant, remedy)`: `entityFile()` and `queriesFile()` a module's type + and collection names in its directory, `barrel()` its re-exports, the routes generators their + REST segments per entry. A second claimant fails with `ERR_NAME_COLLISION` (a codegen-time code + declared by `@metaobjectsdev/codegen-ts`), naming both. A file that meets two same-named value + objects binds each under a package-qualified local alias (`import type { Note as AcmeAlphaNote } + from "../alpha/Note.js"`); the extract tier's mirrors and mappers are named by that alias + (`AcmeAlphaNoteExtracted`). `valueObjectModuleSpecifier` takes the value object's node. + **Upgrade note:** two same-named value objects in two packages under the flat layout (or behind + a barrel) now fail with the collision error; set `outputLayout: "package"` (and drop the barrel, + or rename one), and update imports of the old `AcmeAlphaNote` names. An owned generator copy is + refreshed with `meta eject --list`. - **Agent context routes report work to the reporting vocabulary.** The `meta init` agent guide and the `metaobjects-authoring` skill now send grouped totals, dashboard numbers and read-only report views to `object.report` (`references/declaring-reports.md`) before the `@sql` escape, @@ -50,6 +69,12 @@ loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersi `scripts/check-peer-ranges.ts` now fails a publishable package that requires `@biomejs/biome` through `dependencies` or a non-optional peer. +### Deprecated + +- **C#: `ValueObjectNames.Names(root)`.** A value object is never renamed, so it now returns the + identity map (resolution key to PascalCase name) and is `[Obsolete]` for one release, matching + the TypeScript and Python shims. Use `ValueObjectNames.TypeName(obj, root)`. + ### Fixed - **A projection view keeps the columns a reverse `@via` hop feeds.** An origin `@via` that walks @@ -99,13 +124,23 @@ Each item below is described in full under Added, Changed or Fixed; this list is - **A template that names a variable not on its payload now raises at render time** instead of rendering the variable as empty. Regenerate, and fix the name the error reports. - **C#, EF Core migrations.** The first `dotnet ef migrations add` after upgrading scaffolds the - indexes and comments the context now declares, and a Postgres context that declares - `@sequenceStart` needs `UseIdentityStartMigrations()` registered after `UseNpgsql(...)`. A - self-hosted codegen runner sets `GenConfig.Dialect`. A nullable enum with `@default` now starts - at its default instead of NULL. See the four C# upgrade notes under Changed. -- **`@sequenceStart` records a start; in 1.3.0 it does not move an existing counter.** A later - release is planned to move a counter that sits below the declared start forward to it, never - backward. + indexes, comments and CHECK constraints the context now declares. A Postgres context gets + generated design-time services that scaffold a changed `@sequenceStart` safely; in EF's default + layout they need no code, and `dotnet meta gen` prints the one line to add when the migrations + live in another project. A self-hosted codegen runner sets `GenConfig.Dialect`. A nullable enum + with `@default` now starts at its default instead of NULL. See the C# upgrade notes under + Changed. +- **A changed `@sequenceStart` moves an existing counter forward only.** It records the start and, + when the next id would be below `GREATEST(start, max(id) + 1)`, moves the counter there. It never + restarts and never moves a counter back. +- **A value object is never renamed.** One that shared its short name with a value object in + another package used to be generated under a package-qualified name (`AcmeAlphaNote`); it now + keeps its own name everywhere. Two objects that would emit one name into one scope are refused + with `ERR_NAME_COLLISION`, naming both. Place them apart: `outputLayout: "package"` in + TypeScript and Python, `csharp.packageNamespaces` in C#. Java and Kotlin never renamed. +- **`meta init` and `metaobjects init` scaffold the package output layout.** New projects get + `outputLayout: "package"` (one directory per metadata package); `dotnet meta init` writes the + matching C# keys. An existing project changes nothing: the engine default stays flat. - **`@dbSetName` is `@collectionName`.** The attr was never published under its first name, so there is no alias: a model that set `@dbSetName` in a pre-release build renames it. - **`metamodelVersion` is `1.3`.** Upgrade every port together. @@ -156,12 +191,13 @@ Each item below is described in full under Added, Changed or Fixed; this list is `[csharp-only]`) and its JSON carries `ports`. `@objectAdapter` is the one there is. - **`@collectionName`, and the `naming.collections` pluralizer.** An `object.entity`, `object.projection` or `object.report` may name its collection in its own casing - (`"@collectionName": "CaseHistory"`); it need not be a grammatical plural. In C# and TypeScript it + (`"@collectionName": "CaseHistory"`); it need not be a grammatical plural. In every port it names the REST collection segment, snake_cased with an acronym-aware split (`FAQs` serves - `/faqs`, shared by `fixtures/naming-conformance/collection-segments.json`), and the reverse - finders; in C# also the DbSet property (in place of the derived plural, which the api reference - reads through it), and in TypeScript the list function, the list hook and the Drizzle table - variable. Two objects whose collection names meet are refused by name. A project that declares + `/faqs`, shared by `fixtures/naming-conformance/collection-segments.json`, which every port + runs), and the api reference and report export follow it. In C#, TypeScript and Python it also + names the reverse finders (Java and Kotlin name a finder by its foreign-key field); in C# the + DbSet property (in place of the derived plural, which the api reference reads through it), and + in TypeScript the list function, the list hook and the Drizzle table variable. Two objects whose collection names meet are refused by name. A project that declares neither the attr nor `naming.collections` keeps every generated name and URL. Absent, the project's pluralizer derives the name: `"naming": { "collections": "standard" }` (the default) or `"none"` in `.metaobjects/config.json`, or one the application registers (`registerPluralizer` in @@ -226,11 +262,17 @@ Each item below is described in full under Added, Changed or Fixed; this list is - **A view the lowering cannot express is refused, not shortened.** The TypeScript view extractor skipped any origin it could not lower, so a projection loaded clean and `meta migrate` created a view missing a column its generated type declares. Each such shape now fails, naming the - projection and the field: an origin `@segment`, a base-row operand in an origin `@filter`, a - computed node the lowering does not support, and an unknown origin or aggregate. A projection - that extends another projection now fails too, naming the projection: the lowering reads only - the fields and `@filter` declared on the projection itself, so the view it created dropped the - inherited columns and the inherited row gate. + projection and the field: an aggregate-derived entity field read where a row-level value is + needed, a computed reference cycle, a relative date on a field that is not temporal, and an + unknown origin or aggregate. +- **The view vocabulary lowers to SQL.** `meta migrate` builds every port's views, and it now + writes the shapes the loaders accept: an entity's derived `origin.first` / `origin.computed` + field is inlined wherever a projection reaches it (a `@filter` key or path, a passthrough + `@from`, a field bound with `extends`); an origin's `@segment` is ANDed with its `@filter`; + a base-row operand compares in place, with `isDistinctFrom` / `isNotDistinctFrom` written as + `IS [NOT] DISTINCT FROM` on Postgres and `IS NOT` / `IS` on SQLite; relative dates lower in + projection and origin filters; searched and simple `case` and a `now` leaf lower in a computed + expression, and a computed field may read the projection's other fields. - **A reference over a flattened member reads the member's column.** A reference whose `@fields` names a member of a flattened value object (`"address.countryId"`) now resolves to that member's real column in the foreign key `meta migrate` emits, a view's join, a passthrough `@from` onto @@ -495,12 +537,13 @@ Each item below is described in full under Added, Changed or Fixed; this list is a table rename. On Postgres `meta migrate` creates `GENERATED BY DEFAULT AS IDENTITY (SEQUENCE NAME "…" START WITH n)`, reads the live sequence back from the catalog, and alters one whose declared start or name differs in place: a new - start is recorded (`ALTER SEQUENCE … START WITH n`), and in 1.3.0 the existing counter is not - moved, because live rows hold the ids it handed out; a new name is a rename. Every port gives - `@sequenceStart` this one meaning, the first value of a fresh sequence; the persistence - migration scenario `sequence-start-change-keeps-counter` pins it on live Postgres. A later - release is planned to strengthen this to a forward-only move (a counter below the declared - start moves up to it, never down), so do not build on the counter staying where it is. Only what + start is recorded (`ALTER SEQUENCE … START WITH n`) and the counter moves forward only, to + `GREATEST(n, max(id) + 1)` when it sits below that, never back and never by `RESTART`, because + live rows hold the ids it handed out; a new name is a rename. The persistence migration scenarios + `sequence-start-change-moves-counter-forward` and `sequence-start-change-below-max-id` pin both + cases on live Postgres. The Drizzle schema template carries the start and name in the identity + column's options, the C# context and the Kotlin Exposed table carry them too, and Java and + Python, which write no DDL, leave schema to `meta migrate`. Only what the model declares is compared, on the live, shadow and snapshot paths alike, so a model that declares neither sees no new change and writes the same SQL and snapshots. Every port registers both attributes and refuses either without `@generation: increment` @@ -637,8 +680,52 @@ Each item below is described in full under Added, Changed or Fixed; this list is and Kotlin) and `reset_naming_strategies_for_testing()` (Python) forget the strategies the application registered and keep the built-ins. +- **C#: the generated EF context declares the CHECK constraints `meta migrate` creates**, with the + same names and expression text: every scalar `field.enum` and every validator that can carry one + (`numeric`, `length`, `regex`, `comparison`, `requiredWhen`, `presentIff`, `atLeastOne`, + `exactlyOne`), with `@constraintName` and `@condition`. They are declared when `migrate.dialect` is + `postgres`, `sqlite` or `d1`, and `migrate.checks.skipRedundant` is followed. A new shared corpus, + `fixtures/check-constraint-conformance/`, pins the names and text per dialect; `meta migrate` is + its reference, and the C# context passes the same files (and creates them on live Postgres). +- **C#: a value object stored as JSON carries its comment into the database.** Its `@description` + (else its value object's) is an owned-type annotation, and the generated design-time services + scaffold it as `COMMENT ON COLUMN`, Up and Down; a change to that comment alone is a pending model + change, so `has-pending-model-changes` and `migrations add` see it. Off Postgres the run warns. +- **C#: the package output layout and per-package namespaces, as opt-ins.** `csharp.outputLayout: + "package"` in `.metaobjects/config.json` writes each per-object file under its metadata package + (`acme::blog::Author` is `acme/blog/Author.g.cs`), and each shared enum becomes its own + `/.g.cs`. `csharp.packageNamespaces: true` puts each packaged type in its + package's namespace even when `csharp.namespace` is set (an object maps packages explicitly), and + every reference across namespaces is written `global::`-qualified. `dotnet meta init` writes + both for a new project; a project that sets neither gets byte-identical output + ([#546](https://github.com/metaobjectsdev/metaobjects/issues/546)). +- **Python: the package output layout.** `outputLayout: "package"` in `metaobjects.config.yaml` + (`GenConfig(output_layout=...)` for a self-hosted run) writes each object in the directory of its + metadata package (`acme::blog::Author` is `generated/acme/blog/Author.py`), with relative imports + and package `__init__.py` files. The default stays flat. Two objects that would generate one module + in one directory are refused with `ERR_NAME_COLLISION`, naming both. So is a tree Python could not + import: a package directory beside a module of the same name (a top-level package `enums` would + shadow the shared `enums.py`), and a package segment that is not a Python identifier (`my-co`) + ([#546](https://github.com/metaobjectsdev/metaobjects/issues/546)). +- **Java and Kotlin: output paths keyed by metadata package, with a refusal.** Every per-object file + already landed in the directory of its metadata package; two metadata packages that would land in + one directory (a case-only difference, or `a.b` beside `a::b`) are now refused before any + generator runs, with `ERR_NAME_COLLISION` naming both objects, instead of one file overwriting the + other. Tests pin that two same-named objects in two packages are two files + ([#546](https://github.com/metaobjectsdev/metaobjects/issues/546)). +- **Kotlin: Exposed tables begin at `@sequenceStart`.** An increment key that declares + `@sequenceStart` or `@sequenceName` is `autoIncrement(Sequence("", startWith = n))` on both + Exposed lines, so a table Exposed creates begins at the start; pinned on live Postgres + ([#544](https://github.com/metaobjectsdev/metaobjects/issues/544)). + ### Documentation +- **ADR-0015 Amendment 1: EF Core Migrations is a supported second C# path.** `meta migrate` stays + the reference engine; the EF context is held to it by the shared CHECK corpus and the identity + start rule. +- **ADR-0044 Amendment 1 and ADR-0056 Amendment 2: a value object is never renamed.** The + package-qualified collision name is gone in every port; one claim registry per run refuses a real + clash with `ERR_NAME_COLLISION`. - **Index names and list-hook names, corrected.** The authoring reference's index examples are table-scoped (`userByEmail`, not `byEmail`) and say an index name is schema-wide, so a repeated one fails `meta migrate` with `ERR_DUPLICATE_SQL_NAME`. The generated list hook is @@ -668,6 +755,40 @@ Each item below is described in full under Added, Changed or Fixed; this list is ### Changed +- **`meta init` and `metaobjects init` write `outputLayout: "package"`.** A new project gets one + directory per metadata package (`acme::blog` writes `src/generated/acme/blog/Author.ts`), so two + objects with one name in two packages are two files. The engine default stays `flat`, so an + existing project changes nothing. The Mongo document-store recipe's generator follows the layout. +- **The codegen-compile gate and the generated-server api-contract lanes run in both output + layouts**, flat and package, so a defect that only the non-default layout shows fails a gate. +- **TypeScript: one claim registry for every emitted name.** A generator claims each name it + writes into a shared scope (a module's exported types, an output file, a barrel entry, a route) + through `ctx.claim(scope, name, claimant, remedy)`; a second claimant of one name in one scope is + refused with `ERR_NAME_COLLISION`, naming both and the remedy. A collection-name clash keeps the + shared-ledger code `ERR_COLLECTION_NAME_COLLISION`, checked before any generator runs. The + `RenderContext` members `valueObjectNames` (now the identity map) and `packageOf` are deprecated + and kept one release so owned generator copies keep compiling; a referencing file reads the + local name through `resolveValueObjectName`. Re-eject an owned copy to drop them. +- **C#: the same claim registry, and value objects keep their names.** Each generator claims the + names it emits (a type per namespace, a file per output path, a DbSet per context, a route segment + per routes entry, a finder per class); a second claimant is refused with `ERR_NAME_COLLISION`, + naming both and the remedy. The package-qualified value-object rename and its + `ERR_PAYLOAD_NAME_COLLISION` are gone. +- **TypeScript and Python: two shared enums with one name are `ERR_NAME_COLLISION`.** Every shared + enum is generated into one module under its own name, so a second `Tier` from another package + was dropped and its fields typed with the first one's members. The pair is now refused, naming + both declarations. C# with package namespaces generates each in its own namespace. +- **A collection-name clash is `ERR_COLLECTION_NAME_COLLISION` in every port.** Java's refusal (which + Kotlin shares) and C#'s DbSet and route-segment refusals now lead with the shared-ledger code + that TypeScript and Python already raise, and name `@collectionName` as the remedy. +- **Every join a generated view or report makes is `LEFT OUTER`.** A row whose reference is null, + or whose related row is missing, used to vanish from a view that inner-joined it; it now appears + with nulls in the joined columns. A report dimension's `required` flag is read from the model, + and no longer changes the join. Expect the regenerated view bodies to differ in `meta migrate`. +- **A Postgres view qualifies a relation only when its entity declares `@schema`.** A table in the + default schema stays unqualified, so the view follows the connection's `search_path` as the + table DDL does; SQLite and MySQL view bodies are never qualified. + - **Quieter `meta verify` advisories.** The anti-pattern scanner skips comment lines; it flags minor-unit math (`* 100`, `/ 100`, `.toFixed(2)`, `parseFloat`) only when the operand is money-named, so hours formatted to two places no longer read as money; and a `.reduce` counts @@ -769,17 +890,18 @@ Each item below is described in full under Added, Changed or Fixed; this list is exist under other names, rename them in the database or in the metadata first. Comments re-apply harmlessly. A database built from the model (`EnsureCreated`, or a fresh migration chain) is unaffected. An `@expr` index is never an EF index; `meta migrate` creates it. -- **C#, upgrade note: identity starts never RESTART, and need one registration call.** A Postgres - project's context now carries `identity.primary @sequenceStart` in its model, and every start-only - change — a start added, changed or removed — is written `SET START WITH n` (a removed start goes - back to the identity default), never `RESTART`, so the current value never moves under ids live - rows hold. The first migration after upgrading shows, for each table that declares a start, an - `AlterColumn` (or, when scaffolded through the rewrite, a `Sql("ALTER TABLE … SET START WITH n")`) - that records the start and changes nothing else; it is safe to apply. Register the rewrite where - the context is configured, after `UseNpgsql(...)`: `options.UseNpgsql(cs).UseIdentityStartMigrations()` - (pooled or not, in an `IDesignTimeDbContextFactory`, or in a partial context's own - `OnConfiguring`). A context that declares a start throws as its model is built on Npgsql without - it, naming the call. +- **C#, upgrade note: identity starts never RESTART, through generated design-time services.** A + Postgres project's context now carries `identity.primary @sequenceStart` in its model, and a + generated `DesignTimeServices` makes `dotnet ef migrations add` scaffold every + start-only change (a start added, changed or removed) as SQL: `SET START WITH n` (a removed start + goes back to the identity default) and, for a declared start, a forward-only move of the counter + to `GREATEST(n, max(id) + 1)` when it sits below that. It never writes `RESTART`. The first + migration after upgrading shows that SQL for each table that declares a start; it is safe to + apply. EF finds the services through an `[assembly: DesignTimeServicesReference]` generated + beside them when the migrations live in the context's project, EF's default; for any other + migrations or startup project, `dotnet meta gen` warns and prints the line to add there. Nothing + is registered at runtime. `UseIdentityStartMigrations()` is kept as an `[Obsolete]` no-op so a + call to it compiles; remove it. - **C#, upgrade note: a self-hosted codegen runner sets `GenConfig.Dialect`.** `@sequenceStart` and the identity-start rewrite are emitted only when the dialect is `postgres`. `CodegenCli` reads it from `.metaobjects/config.json` `migrate.dialect`; a runner that builds its own `GenConfig` must @@ -821,6 +943,34 @@ Each item below is described in full under Added, Changed or Fixed; this list is ### Fixed +- **No CHECK for a derived field.** A validator on a field that carries an `origin` (or a + cross-field validator naming one) made `meta migrate` emit a CHECK on a column that does not + exist, and `CREATE TABLE` failed. The derived field is skipped; the C# context does the same. +- **View lowering, in TypeScript (which builds every port's views):** + - an origin `@filter` keeps every operator of a field clause (`{ "gte": 1, "lt": 10 }` lost + all but the first, so the view counted rows it should not); + - a projection that extends a projection outputs the inherited fields and applies the base's + `@filter`; + - a `@filter` on a base field the view does not output, or on a path of to-one hops, joins only + what it names; + - a multi-hop `origin.first` `@via` is lowered along its path, correlated on the first hop; + - a view over a TPH subtype, or a join onto one, is scoped by its discriminator, and an abstract + level by `IN` over its concrete subtypes; + - a Postgres view column takes its declared type (a bare `NULL` computed column, an `@convert` + passthrough); + - two aggregates through two references onto one target each read their own join. +- **The Zod template's shared-enum import resolves in the package layout** when the owning object's + package is inherited from its file or root (`./enums` was one directory short). +- **A docs page's References and identity-reference links reach the target page** when the target + lives in another package. +- **An entity's derived field is not a column, in every port.** A projection-reached + `origin.first` / `origin.computed` on an entity with no read source is left out of table reads + and writes by the C# entity and DbContext, the Kotlin entity, Exposed table, repository and + controller, Java OMDB's mapping and Python's `ObjectManager`. +- **C#: a reference over a member of a flattened value object** configures the foreign key on the + owned type instead of emitting a property EF rejects. A `field.duration` mapping names framework + types `global::`-qualified. + - **Generated routes on Postgres answer 400, not 500, for bad uuid input.** On an entity with a uuid foreign key, `?search=` ran ILIKE against the uuid column (the allowlist carries it as `subType: "string", format: "uuid"`), and Postgres has no `uuid ~~* text` operator. The search @@ -883,17 +1033,15 @@ Each item below is described in full under Added, Changed or Fixed; this list is names). A new persistence scenario, `schema-qualified-same-name`, maps `ledger_entries` and `archive.ledger_entries` to two entities and runs on Postgres in every port. - **C#: `identity.primary @sequenceStart` reaches the EF model, and no start-only change ever - restarts**. On Npgsql a fresh database's identity begins at `@sequenceStart`. A - Postgres context with an increment key gets a generated rewrite, registered with - `UseIdentityStartMigrations()` (see Changed), that writes a start added, changed or removed as - `SET START WITH n`, both when the migration is scaffolded and when its SQL is generated: Npgsql's - own generator writes `RESTART WITH n` (or `RESTART WITH 1` for a removed start), which hands out - ids live rows already hold. It references Npgsql at compile time, so it and the start are emitted - only for a project whose `migrate.dialect` is `postgres`; any other project gets a warning and - needs no Npgsql package. TypeScript's `meta migrate` writes the same `START WITH`-only change; - Java and Kotlin do not yet carry the start - ([#544](https://github.com/metaobjectsdev/metaobjects/issues/544)); see `docs/CONFORMANCE.md`, - "Split coverage". + restarts**. On Npgsql a fresh database's identity begins at `@sequenceStart`. A Postgres + context's generated design-time services (see Changed) scaffold a start added, changed or + removed as `SET START WITH n` plus the forward-only counter move, where Npgsql's own generator + writes `RESTART WITH n` (or `RESTART WITH 1` for a removed start), which hands out ids live rows + already hold. The start and the services are emitted only for a project whose + `migrate.dialect` is `postgres`; any other project gets a warning and needs no Npgsql package. + TypeScript's `meta migrate` writes the same change, and the Kotlin Exposed table begins a fresh + table at the start ([#544](https://github.com/metaobjectsdev/metaobjects/issues/544)); see + `docs/CONFORMANCE.md`, "Split coverage". - **C#: the EF model carries the index vocabulary and `@description`.** A field's `@unique`, an `identity.secondary` and an `index.lookup` are EF indexes under the names `meta migrate` gives them, with `@where` (`HasFilter`), `@orders` (`IsDescending`) and `@using` (the Npgsql index diff --git a/agent-context/skills/metaobjects-codegen/references/typescript-document-store.md b/agent-context/skills/metaobjects-codegen/references/typescript-document-store.md index 31e8f8ab0d..20fb079ce3 100644 --- a/agent-context/skills/metaobjects-codegen/references/typescript-document-store.md +++ b/agent-context/skills/metaobjects-codegen/references/typescript-document-store.md @@ -55,7 +55,7 @@ What the repository does, built on the generated contract: // its wire contract (InsertSchema, UpdateSchema, 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 { @@ -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 (`./.js`), in either output layout. + generate: perEntity((obj, ctx) => ({ + path: entityOutputPath(ctx.renderContext?.outputLayout ?? "flat", effectivePackage(obj), `${obj.name}.repository.ts`), + content: render(obj), + })), }; } ``` diff --git a/docs/CONFORMANCE.md b/docs/CONFORMANCE.md index 010d55867f..da030620d9 100644 --- a/docs/CONFORMANCE.md +++ b/docs/CONFORMANCE.md @@ -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 @@ -57,9 +57,10 @@ regenerate with `ls -d fixtures//*/ | 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) | — | — | — | — | @@ -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. + `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("", 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 @@ -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 @@ -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. @@ -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`) diff --git a/docs/features/api-contract.md b/docs/features/api-contract.md index 461dacf19b..f74a9c4ad7 100644 --- a/docs/features/api-contract.md +++ b/docs/features/api-contract.md @@ -91,7 +91,10 @@ every field. The TS mounts can restrict the update to one verb with `` 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 | |---|---|---| diff --git a/docs/features/cube-export.md b/docs/features/cube-export.md index 21847a4aea..be9542dcb8 100644 --- a/docs/features/cube-export.md +++ b/docs/features/cube-export.md @@ -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. | diff --git a/docs/features/field-types.md b/docs/features/field-types.md index 4cd13888bd..6fa9356d3a 100644 --- a/docs/features/field-types.md +++ b/docs/features/field-types.md @@ -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` diff --git a/docs/features/migrations-and-drift.md b/docs/features/migrations-and-drift.md index 540b7ecfe8..552010f8c8 100644 --- a/docs/features/migrations-and-drift.md +++ b/docs/features/migrations-and-drift.md @@ -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, @@ -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 diff --git a/docs/features/migrations/physical-naming.md b/docs/features/migrations/physical-naming.md index 888a3b69fb..7ba8c87712 100644 --- a/docs/features/migrations/physical-naming.md +++ b/docs/features/migrations/physical-naming.md @@ -76,13 +76,12 @@ the port's reset when it is done (`resetNamingStrategiesForTesting()`, ### Collection names An object's collection name is its own `@collectionName`, else the `collections` pluralizer over -its name. C# and TypeScript generators read it (the other ports load and type-check both, and -act on neither yet, #549): +its name. Every port's generators read it: | Artifact | Port | `Faq` with `@collectionName: "FAQs"` | `Order` under `collections: "none"` | |---|---|---|---| -| REST collection segment | C#, TypeScript | `/faqs` | `/order` | -| Reverse finder | C#, TypeScript | `FindFAQsByOwner` / `findFAQsByOwner` | `FindOrderByFaq` / `findOrderByFaq` | +| REST collection segment | every port | `/faqs` | `/order` | +| Reverse finder | C#, TypeScript, Python | `FindFAQsByOwner` / `findFAQsByOwner` / `find_faqs_by_owner` | `FindOrderByFaq` / `findOrderByFaq` / `find_order_by_faq` | | DbSet property | C# | `FAQs` | `Order` | | List function, list hook, Drizzle table variable | TypeScript | `listFAQs`, `useFAQs`, `fAQs` | `listOrder`, `useOrderList`, `order` | @@ -90,8 +89,12 @@ The REST segment is the collection name snake_cased, with a trailing plural `s` kept on it (`FAQs` serves `/faqs`, `TaxIDs` serves `/tax_ids`). With neither `@collectionName` nor a `collections` setting, every name is what it has always been: the segment is the snake_cased name made plural, as every port serves it. A list hook whose name would equal the detail hook's -takes a `List` suffix. The cases both ports run are in -`fixtures/naming-conformance/collection-segments.json`. Changing either one changes URLs and +takes a `List` suffix. Java and Kotlin name a reverse finder by its foreign-key field +(`findByOwnerId`), so a collection name does not change it. The cases every port runs are in +`fixtures/naming-conformance/collection-segments.json`. Two objects that would take one +collection name — the same REST segment, or (in C#) one DbSet property — are refused before +anything is written, with `ERR_COLLECTION_NAME_COLLISION` naming both and `@collectionName` as +the remedy, in every port. Changing either one changes URLs and generated names an application calls, so treat it as an API change. A name nothing registered fails when the file is read, naming the setting, the name, the port, diff --git a/docs/features/migrations/value-object-types-are-generated-once.md b/docs/features/migrations/value-object-types-are-generated-once.md index b819a7c97c..6e757d7f22 100644 --- a/docs/features/migrations/value-object-types-are-generated-once.md +++ b/docs/features/migrations/value-object-types-are-generated-once.md @@ -44,10 +44,16 @@ nullability rule and enum naming, so "the same shape" disagreed with itself. ## Names and locations -A value object's type is named after the value object, never the template. Where the port -emits every value object into one flat namespace or directory (TypeScript, C#, Python), a value -object whose short name collides is package-qualified: `acme::alpha::Note` → `AcmeAlphaNote`. -Java and Kotlin keep `Note` in `acme.alpha`, because the package tells them apart. +A value object's type is named after the value object, never the template, and it is never +renamed. Java and Kotlin keep `Note` in `acme.alpha`, because the package tells them apart. +TypeScript and Python do the same with `outputLayout: package`: each `Note` has its own module +or directory, and with the flat layout the clash is refused with `ERR_NAME_COLLISION` (see +[the Python port](../../ports/python.md)). C# does it with package namespaces +(`csharp.packageNamespaces`, see [the C# port](../../ports/csharp.md)): each `Note` sits in its +package's namespace, and two in one namespace are refused with `ERR_NAME_COLLISION`. A file that +meets both `Note`s imports them under package-qualified local aliases (TypeScript +`import type { Note as AcmeAlphaNote }`, Python `import Note as AcmeAlphaNote`), and TypeScript's +inbound-tier lenient mirrors take the alias (`AcmeAlphaNoteExtracted`). | Port | Before | After | |---|---|---| @@ -110,8 +116,9 @@ The tolerant tier's all-nullable mirror is named after the value object too: `.py`. A value object whose short name - another top-level object shares — a second value object, or an entity — is now - package-qualified (`AcmeAlphaNote.py`); before, both wrote the same module. + another top-level object shares — a second value object, or an entity — is no longer + renamed. The flat layout refuses the pair with `ERR_NAME_COLLISION`; `outputLayout: package` + gives each its own directory. Before, both wrote the same module. - A field with a `default:` is typed as its plain type with that default (`user_id: str = ""`), where the copy typed it `str | None = None`. Passing `None` to it now fails validation: a caller that relied on `None` must pass a value, or the field must drop its `default:` so it diff --git a/docs/features/reporting.md b/docs/features/reporting.md index 2fea4c10a3..001f08b549 100644 --- a/docs/features/reporting.md +++ b/docs/features/reporting.md @@ -269,7 +269,7 @@ physical column name is your naming strategy applied to the **derived field name | Item | Column | Type | Never null? | |---|---|---|---| -| `dimension.attribute` | the dimension's name | the `@of` field's type | only when the `@of` field is required (`@required: true` or a `validator.required` child) and the dimension has no `@via`, or every hop of its `@via` is a required reference the view joins `INNER` (below) | +| `dimension.attribute` | the dimension's name | the `@of` field's type | only when the `@of` field is required (`@required: true` or a `validator.required` child) and the dimension has no `@via`, or every hop of its `@via` is an enforced belongs-to reference over a required foreign key (below) | | `dimension.time` at `hour` | `Hour` | `timestamp` | same rule | | `dimension.time` at `day`, `week`, `month`, `quarter`, `year` | `` | `date`, the first day of the bucket | same rule | | `count` (with or without `@distinct`) | the measure's name | `long` | yes: a count is never null | @@ -287,17 +287,19 @@ physical column name is your naming strategy applied to the **derived field name | any measure above except `count`, declaring `@default` | the measure's name | as above | yes: it reads its `@default` instead of null | | in a `@spine` report, a dimension over a column of the spine entity | the dimension's name | the `@of` field's type | yes when the `@of` field is required (`@required` or a `validator.required` child) or one of the spine entity's `identity.primary` `@fields`; no for a dimension reached beyond the spine entity | -The last two rows, and the `INNER` rule above, are the only ways a measure other than `count`, -or a dimension reached through `@via`, is never null. The key clause applies only under +The last two rows, and the enforced-reference rule above, are the only ways a measure other than +`count`, or a dimension reached through `@via`, is never null. The key clause applies only under `@spine`, where the key is the row's own. Without `@spine`, a dimension reached through `@via` is never null when its `@of` field is -required and **every hop is a belongs-to reference over a required foreign key**: the entity the -hop leaves holds the `identity.reference`, and its first `@fields` entry is required. The view -joins such a hop `INNER`, so every row has a match, whatever the reference's `@enforce` says (an -unenforced required reference still joins `INNER`; make its field optional to keep unmatched -rows). A hop over an optional foreign key, a to-one relationship whose foreign key the other -entity holds, or any hop under `@spine` is joined `LEFT OUTER`, and the dimension stays nullable. Every port derives the same answer +required and **every hop is an enforced belongs-to reference over a required foreign key**: the +entity the hop leaves holds the `identity.reference`, its first `@fields` entry is required, and +the reference is enforced (`@enforce` defaults to true), so the join always finds a match. Every +hop a view or report makes joins `LEFT OUTER` (this changed — a required reference is no longer +inner-joined), so a join never drops a base row, whatever the reference's `@enforce` says; for +these hops the match is guaranteed, so the outer join never nulls the column either. A hop over +an optional foreign key, a to-one relationship whose foreign +key the other entity holds, or any hop under `@spine` stays nullable. Every port derives the same answer (`fixtures/persistence-conformance/report-shapes.json`). A derived column carries the type-shaping attributes of its `@of` field where they apply @@ -412,12 +414,11 @@ The Cube exporter writes a derived measure over measures as a `number` member re - **`@via`** reaches a column of a to-one related entity, through a join. Every hop is joined through an `identity.reference` the model declares between the two entities; a hop without one - loads, and then fails `meta migrate` naming the hop. The join type is the - projection rule, unchanged: a required belongs-to foreign key joins `INNER`, anything else - `LEFT OUTER`, and an `INNER` survives only when every join above it is `INNER`. The - consequence to know: **a dimension reached through a required reference drops a fact row - whose reference matches no row, from that report.** A dimension that is not listed in - `@dimensions` adds no join. In a `@spine` report every join is `LEFT OUTER`. + loads, and then fails `meta migrate` naming the hop. **Every join is `LEFT OUTER`** — with or + without `@spine` (this changed: a required reference is no longer inner-joined, so a fact row + whose reference matches no row stays in the report, with nulls in the joined columns, where it + used to vanish). A dimension that is not listed in + `@dimensions` adds no join. - **Grains** are `hour, day, week, month, quarter, year`. A bucket is the first instant (for `hour`) or first day (for the rest) of the period. **Weeks start on Monday (ISO-8601)** on every engine: the week of Sunday 2026-05-17 starts 2026-05-11, and Monday 2026-06-01 starts @@ -469,8 +470,8 @@ program. count of `0`. Both still name fields of `@from`. - **A fact row with no spine row is in no row.** A purchase whose `programId` is null, or matches no program, has no spine row to sit in. Without `@spine`, such a row still counts: it - falls in a null group through a nullable reference (`LEFT OUTER` join) and is dropped through - a required one (`INNER` join; see [Dimensions, time grains and joins](#dimensions-time-grains-and-joins)). + falls in a null group through the `LEFT OUTER` join (every join is `LEFT OUTER` now; see + [Dimensions, time grains and joins](#dimensions-time-grains-and-joins)). - **A row with no facts** reads `0` for a `count`, and null for a `sum`, `avg`, `min`, `max` and a ratio, unless the measure declares `@default` (next section). This holds even for a measure whose `@filter` is `isNull: true` on a fact column: the empty row's `@of` column is diff --git a/docs/features/source-kinds.md b/docs/features/source-kinds.md index be42e4381b..5e564bafc5 100644 --- a/docs/features/source-kinds.md +++ b/docs/features/source-kinds.md @@ -96,10 +96,16 @@ emitter, two hosts. A derived field must be **providable** — a read-capable source must be able to carry it. A derived field on a table-only entity (no read source) is a load error -(`ERR_DERIVED_FIELD_NO_READ_SOURCE`), with one exception: an `origin.first` or `origin.computed` -that a projection reaches through its `@filter` or a passthrough `@from` is inlined there, so it -needs no read source. The entity's table then gets no column for it: generated entity, DbContext, -Kotlin, Python `ObjectManager` and Java OMDB mappings leave such a field out of table reads and writes. +(`ERR_DERIVED_FIELD_NO_READ_SOURCE`), with one exception: an entity's `origin.first` or +`origin.computed` field that some projection **reaches** — through a `@filter` key or to-one +path, a passthrough `@from`, or a field bound to it with `extends` — needs no read source of its +own. The projection's view inlines it where it is reached (an `origin.computed` as its expression +over the reached row, an `origin.first` as a correlated subquery keyed on it); an +`origin.aggregate` has no row-level form and is refused there. The entity's table gets no column +for it: the generated entity, DbContext, Kotlin, Python `ObjectManager` and Java OMDB mappings +leave such a field out of table reads and writes. `fixtures/conformance/entity-derived-filter-gate` +pins the shape: an agreement flag declared once on `Member` and filtered on by every gated +projection. ### Entity read-view vs projection — which to reach for @@ -215,6 +221,11 @@ related rows by a `@segment` declared on that entity (ANDed with its `@filter`), (`ERR_INVALID_ORIGIN` for a `@segment` the entity does not declare, `ERR_BAD_ATTR_FILTER` for an unknown base field or another op). +All of the above lowers into the view `meta migrate` creates, which every port reads: a segment's +predicate is ANDed into the related rows' scope, a base-row operand compares against the base +alias (`IS [NOT] DISTINCT FROM` on Postgres, `IS NOT` / `IS` on SQLite), and a relative date is +evaluated when the view is queried, on the UTC clock. + **Projection row-scope `@filter` (#207).** Distinct from the *per-aggregate* `@filter` above, an **object-level `@filter` on an `object.projection`** scopes the whole view's rows — it lowers to the view's outer `WHERE`. This is the metadata-managed way to express a @@ -260,6 +271,13 @@ outside the tool — see [migrations-and-drift.md](migrations-and-drift.md) and Postgres default is `public`; SQLite rejects non-default `@schema` values at load time. +A generated view follows the tables it reads: on Postgres a projection or report +view qualifies a relation — its base table and every joined one — with that +entity's `@schema` only when the entity declares one, so a table in the default +schema stays unqualified and the view resolves it through the connection's +`search_path`, exactly as the table DDL does. SQLite and MySQL view bodies never +qualify. + ## Multi-source via `@role` An entity may have multiple `source.rdb` children. `@role` is exactly diff --git a/docs/ports/csharp.md b/docs/ports/csharp.md index 8723d47ffc..5816d2c53d 100644 --- a/docs/ports/csharp.md +++ b/docs/ports/csharp.md @@ -237,8 +237,50 @@ convention applies: each `::` segment PascalCased and joined with `.` (`acme::bi the namespace all the packages share. When they share no root, generation stops and asks for a namespace. Setting `--namespace` or `csharp.namespace` switches the default off and puts every type no binding places in that one flat namespace. The namespace must be a dotted path of C# -identifiers. `dotnet meta gen` and `verify` set only that flat namespace; the per-package bindings -are `GenConfig` properties, set when you run codegen from your own code with `CodegenRunner`. +identifiers. `dotnet meta gen` and `verify` read that flat namespace and, through +`csharp.packageNamespaces`, the package bindings (below). The finer per-package bindings +(`TypeOverrides`, `Convention`, `UnmappedStrategy`) are `GenConfig` properties, set when you run +codegen from your own code with `CodegenRunner`. + +**Package-keyed output (opt-in).** Two more `csharp` keys change where files land and which +namespace a packaged type takes; a project that sets neither keeps the flat layout and the +namespace rule above, byte for byte. + +```json +{ "schema_version": 1, "csharp": { "outDir": "Generated", "namespace": "Acme.Blog", + "outputLayout": "package", "packageNamespaces": true } } +``` + +- `outputLayout`: `"flat"` (the default) writes every file at the root of the output directory; + `"package"` writes each per-object file under its metadata package, one directory per `::` + segment (`acme::blog::Author` is `acme/blog/Author.g.cs`). That covers the entity, value object, + shared enum, names, filter allowlist, routes, reverse finders, callable, report export, the extract + mirrors and the template tier. A root-level object, `AppDbContext` and the run-wide helpers stay + at the root. +- `packageNamespaces`: `true` puts each packaged type in its metadata package's namespace + (PascalCased `::` segments) even when `csharp.namespace` is set; that namespace then places only + package-less objects and the run-wide artifacts. An object (`{ "acme::blog": "Acme.Blog" }`) maps + packages to namespaces explicitly, the same as `GenConfig.PackageNamespaces`. Absent or `false` + keeps the earlier rule, where a configured namespace turns the per-package derivation off. With + `true`, every generated reference to a type in another namespace is written `global::`-qualified, + so two same-named types never bind to each other. + +`dotnet meta init` writes `.metaobjects/config.json` with both opt-ins for a new project, and never +edits one that exists. `gen` and `verify` read the same keys, so the drift gate agrees with `gen`. + +**A type is never renamed to make room.** Two nodes that would generate the same name in the same +scope fail, naming both nodes and the remedy. A DbSet property in one context and a REST +collection segment in one routes entry raise `ERR_COLLECTION_NAME_COLLISION` (the shared-ledger +code, the same in every port); a type in one C# namespace, a file in one output path, a finder +in one class and the other scopes raise `ERR_NAME_COLLISION`. The remedy is: map the packages to distinct namespaces, write them apart with +`outputLayout`, or rename one (`@collectionName` for a DbSet and its route). The earlier +package-qualified rename of a value object (`AcmeAlphaNote`) is gone; a value object keeps its name +and sits in its package's namespace. An extract-tier private mapper may carry the package in a +member name (`FromAcmeAlphaNoteExtracted`), because it is private to its class. +Each package's shared enum is its own `/.g.cs` under the package layout, with its +`@intValueMap` integers as member values and `@description` as its XML doc; the flat layout keeps +the one `Enums.g.cs`. An entry narrowed with `Include` declares only the shared enums it uses, and +an enum several narrowed entries use is declared by exactly one of them. With that, `dotnet meta gen` writes there, `dotnet meta verify --codegen` diffs against it, and a plain `dotnet meta verify` in CI runs the codegen gate with no flags. `--out ` still works @@ -458,26 +500,28 @@ so a new entity carries the CLR default and EF sends it. `identity.primary @sequenceStart` on a single-field `increment` key is the identity's START on Npgsql (a fresh database begins there). No start-only change ever restarts the sequence: Npgsql alone writes a start added as `RESTART WITH n`, a changed one as `RESTART WITH m`, and a removed one -as `RESTART WITH 1`, each handing out ids live rows may hold. A Postgres context with an increment -key gets `IdentityStartMigrationsSqlGenerator.g.cs`, which carries the rewrite: every start-only -change is `ALTER TABLE … ALTER COLUMN … SET START WITH n` (a removed start is set back to the -identity default), and in 1.3 the current value does not move (a later release is planned to move a counter below the declared start forward to it). Register it after `UseNpgsql(...)`, wherever -the context is configured — the app's registration (pooled or not), an -`IDesignTimeDbContextFactory`, or the context's own `OnConfiguring`: - -```csharp -services.AddDbContextPool(o => o.UseNpgsql(cs).UseIdentityStartMigrations()); -``` - -It applies at both ends: the differ scaffolds the change as that SQL, so a migration added through -it is safe wherever it runs, and the SQL generator rewrites a migration scaffolded without it. A -context that declares a start refuses to build its model on Npgsql when the rewrite is not -registered (an `InvalidOperationException` that names the call), so a missing registration fails at -`dotnet ef migrations add`, never as a silent RESTART. The file references -`Npgsql.EntityFrameworkCore.PostgreSQL` at compile time, so it (and the start in the model) is -emitted only for a project whose `.metaobjects/config.json` names -`"migrate": { "dialect": "postgres" }` (a self-hosted runner sets `GenConfig.Dialect`). Any other -project gets neither, with a warning, and never needs the Npgsql package. +as `RESTART WITH 1`, each handing out ids live rows may hold. A Postgres context gets +`DesignTimeServices.g.cs`, an `IDesignTimeServices` that wraps the model differ, so +`dotnet ef migrations add` scaffolds every start-only change as SQL, Up and Down: `ALTER TABLE … +ALTER COLUMN … SET START WITH n` (a removed start goes back to the identity default) and, for a +declared start, a move of the counter FORWARD to `GREATEST(n, max(id) + 1)` when it sits below that, +never back. A database rebuilt by replaying migrations begins at `n` as a fresh one does, and no +migration hands out an id a live row holds. The same services scaffold a JSON column's comment. + +It is design time only: nothing is registered at runtime, and `Migrate()` runs what the migration +already holds. EF finds the services through `[assembly: DesignTimeServicesReference(...)]`, which +is generated beside the class when the context's assembly name is known (the single `.csproj` in +the output directory or above it, or `GenConfig.ContextAssemblyName`). That covers EF's default +layout, where the migrations live in the context's project. When the migrations or startup project +is another one, `dotnet meta gen` warns and prints the one line to add to that project; without it +a changed start scaffolds as `RESTART`. `dotnet ef migrations add --verbose` prints "Using +design-time services from assembly …" when they are found. + +The start in the model, and the services, are emitted only for a project whose +`.metaobjects/config.json` names `"migrate": { "dialect": "postgres" }` (a self-hosted runner sets +`GenConfig.Dialect`). Any other project gets neither, with a warning, and never needs the Npgsql +package. `UseIdentityStartMigrations()`, the registration of an earlier runtime SQL rewrite, is +kept as an `[Obsolete]` no-op so a call to it still compiles; remove the call. ### Decimals and null members on the wire diff --git a/docs/ports/java.md b/docs/ports/java.md index ba2c998a6b..dd55508be2 100644 --- a/docs/ports/java.md +++ b/docs/ports/java.md @@ -464,6 +464,22 @@ the pattern and its `**` replacement, so output cannot vanish silently. Upgrade: matching direct children as `acme::*Store`; nested children need `acme::**::*Store` as a second entry. `@` becomes `*`. +### Output paths and REST collection names + +Every per-object file lands in the directory of its metadata package: `acme::blog::Author` is the +Java package `acme.blog` and the file `acme/blog/Author.java`, so two objects named `Note` in two +packages are two files. Two different metadata packages that would land in one directory (names +that differ only in letter case, or `a.b` beside `a::b`) are refused before any generator runs, +with `ERR_NAME_COLLISION` naming both objects. Nothing is renamed to avoid a clash. + +A controller's REST collection segment is the object's `@collectionName` when it declares one +(snake_cased: `CaseHistory` is `/case_history`), else the pluralizer `naming.collections` names in +`.metaobjects/config.json`, else the rule every port has always served (`/authors`). A pluralizer +applies only when the project configures one, so an unconfigured project's routes do not move. +The api-docs, report export and collision check read the same segment. Reverse finders are named +by the foreign-key field (`findByAuthorId`), so a collection name does not change them. The Kotlin +generators share this rule. + ### Shared and `@provided` enums A package-level abstract `field.enum` that fields extend is one top-level Java `enum`, @@ -529,8 +545,9 @@ like a keyless read-only projection. Four generators write one file each for a r `@GetMapping`, a `@PostMapping` answering 405, no `/{id}` mapping). Every derived field with filter operators is filterable and sortable. A DTO component that can never be null carries `@NotNull`, as any required field does: a `count`, a measure with `@default`, a dimension -reached through `@via` whose `@of` field is required and whose every hop is a belongs-to -reference over a required foreign key (the view joins it `INNER`), and in a `@spine` report a +reached through `@via` whose `@of` field is required and whose every hop is an enforced belongs-to +reference over a required foreign key (the join always finds a match, so the view's `LEFT OUTER` +join never nulls the column), and in a `@spine` report a key or `@required` column of the spine entity (`@NotNull Long programKey`). No other generator emits for a report: no names class, no entity class. `gen` fails, naming the report and the dimension or measure, when a diff --git a/docs/ports/kotlin.md b/docs/ports/kotlin.md index 3dc4f382d7..f093af6ace 100644 --- a/docs/ports/kotlin.md +++ b/docs/ports/kotlin.md @@ -536,6 +536,18 @@ object AuthorTable : Table("authors") { } ``` +An increment key that declares `@sequenceStart` or `@sequenceName` gets a named Exposed sequence, +so a table Exposed creates begins at the declared start (on both the Exposed 0.x and 1.x lines): + +```kotlin +val id = long("id").autoIncrement(Sequence("Ticket_Id_seq", startWith = 1000000000L)) +``` + +With neither declared the column stays a bare `autoIncrement()`. Generated Exposed code has no +migration path, so a start changed on an existing database is `meta migrate`'s job, which moves +the counter forward only. Output paths and REST collection names follow the Java rules +([java.md, "Output paths and REST collection names"](java.md#output-paths-and-rest-collection-names)). + …and the Spring wiring is also generated, so consumer Kotlin code is purely business logic: @@ -595,7 +607,8 @@ object ProgramMinutesTable : Table("v_program_minutes") { or ratio, a dimension over an optional field, and a dimension reached through `@via` when a hop can leave a row without a match. Three cases are never null: a measure that declares `@default`; a dimension reached through `@via` whose `@of` field is required and whose every - hop is a belongs-to reference over a required foreign key, which the view joins `INNER`; and + hop is an enforced belongs-to reference over a required foreign key (the join always finds a + match, so the view's `LEFT OUTER` join never nulls the column); and in a `@spine` report a dimension over a `@required` or primary-key column of the spine entity. Each gets a column with no `.nullable()` and a property with no `?` and no `= null`. The rule is the report's, not Kotlin's: see diff --git a/docs/ports/python.md b/docs/ports/python.md index 28006a7212..eb105b4bdb 100644 --- a/docs/ports/python.md +++ b/docs/ports/python.md @@ -359,6 +359,55 @@ The generated `get_repository` raises until you override it. Any object with the `AuthorRepository` methods above works, including an in-memory dict while you try it out. Serve the app with `uvicorn my_app.main:app --reload` (`pip install uvicorn`). +### Output layout and name collisions + +By default every generated module lands flat in the target's `outDir`. Set `outputLayout` +at the top level of `metaobjects.config.yaml` to place each module in the directory of its +metadata package instead: + +```yaml +# metaobjects.config.yaml +metadata: metaobjects +outputLayout: package # "flat" (the default) or "package" +``` + +`metaobjects init` writes `outputLayout: package` into a new project. Delete the line for the +flat layout. Any other value is refused. Embedding the generators in code uses the matching +`GenConfig(output_layout="package")`. + +With the package layout, `acme::blog::Author` is generated as `generated/acme/blog/Author.py`, +and an object with no package stays at the root of `outDir`. Each directory gets an +`@generated` `__init__.py` (when `emit_package_init` is on). Imports between generated modules +become relative: from `acme/blog` to `acme/beta` is `from ..beta.Note import Note`, and a +module shared by all packages, such as the generated enums, is `from ...enums import ...`. The +orphan sweep removes a subdirectory when it empties it. The flat layout is unchanged byte for +byte. + +Two objects that would write one module into one directory are refused with +`ERR_NAME_COLLISION`. The message names both nodes, for example `"acme::alpha::Note" and +"acme::beta::Note" both generate "Note" in the generated package directory "."`. A value +object is never renamed to avoid the clash. The remedy is the package layout, which gives +each its own directory, or renaming one of them. + +### REST collection segments and reverse finders + +A route is mounted at `/`. With nothing configured the segment is the +object name in snake_case, then pluralized (`PostCategory` -> `post_categories`). Two things +change it: + +- `@collectionName` on the object, for example `@collectionName: PDFBoxes` serves + `/pdf_boxes`. +- `naming.collections` in `.metaobjects/config.json`, the name of a pluralizer: `standard`, + `none` (keep the object name), or one registered with `register_pluralizer`. + +A declared name wins over the pluralizer. Either one is snake_cased with an acronym-aware +split, so `FAQs` becomes `faqs`, not `fa_qs`. The router, the API docs, the M:N routes and the +collision check all read one function, `collection_segment`. The same name also gives the +reverse finders: `@collectionName: CaseHistory` on an object turns +`find__by_` into `find_case_history_by_` (and `..._in`). A project that sets +neither keeps every route and finder name it has today. The shared cases are in +`fixtures/naming-conformance/collection-segments.json`. + ### Decimals and null members on the wire What the generated routers write is the project setting `wire` in `.metaobjects/config.json` @@ -813,9 +862,11 @@ each as `.py`. So the prompt+parse story is two generators: - `entity` emits one Pydantic v2 `BaseModel` per value object — and per sourceless `object.projection` — including every `@payloadRef` and `@responseRef` target and every - value object nested in them (`field.object @objectRef`). The package is flat, so a value - object whose short name another top-level object shares is package-qualified: - `acme::alpha::Note` emits `AcmeAlphaNote.py` / `class AcmeAlphaNote`. + value object nested in them (`field.object @objectRef`). A value object is never + renamed. Two with the same short name need the package layout (see "Output layout and + name collisions"): `acme::alpha::Note` and `acme::beta::Note` each emit `Note.py` into + their own directory, and a module that uses both imports them under local aliases such as + `Note as AcmeAlphaNote`. - `output_parser_generator` emits one `_response_parser.py` per responding `template.prompt` (one declaring `@responseRef`, ADR-0052). It imports the `@responseRef` value object's model from its `.py`. `template.output` gets no diff --git a/docs/ports/typescript.md b/docs/ports/typescript.md index 51e88478ff..a75500615b 100644 --- a/docs/ports/typescript.md +++ b/docs/ports/typescript.md @@ -652,9 +652,13 @@ with the literal types intact. The entity module imports only Drizzle and Zod; the generated routes mount through `@metaobjectsdev/runtime-ts`, an ordinary Apache-2.0 package, and Drizzle, Zod and -Fastify are direct user-app deps. With the default (flat) -`outputLayout`, entity output lands directly under `outDir` — `src/generated/Author.ts`, -`Author.queries.ts`, `Author.routes.ts` — with no per-package subdirectory. +Fastify are direct user-app deps. `meta init` writes `outputLayout: "package"`, so entity +output lands under one directory per metadata package — `acme::blog` gives +`src/generated/acme/blog/Author.ts`, `Author.queries.ts`, `Author.routes.ts` — and two +objects with one name in two packages are two files (a `barrel()`, which exports every +name from one module, still refuses that pair as `ERR_NAME_COLLISION`). A config without the key gets the +engine default, `flat`: everything directly under `outDir`, with no per-package +subdirectory. The generated `Author.routes.ts` imports a module-level `db` singleton from the path configured by `dbImport` in `metaobjects.config.ts` (the generated queries take diff --git a/docs/recipes/generators/typescript/mongo-repository.ts b/docs/recipes/generators/typescript/mongo-repository.ts index 398b0f7228..2712d0e137 100644 --- a/docs/recipes/generators/typescript/mongo-repository.ts +++ b/docs/recipes/generators/typescript/mongo-repository.ts @@ -3,7 +3,7 @@ // its wire contract (InsertSchema, UpdateSchema, 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 { @@ -103,6 +103,10 @@ 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 (`./.js`), in either output layout. + generate: perEntity((obj, ctx) => ({ + path: entityOutputPath(ctx.renderContext?.outputLayout ?? "flat", effectivePackage(obj), `${obj.name}.repository.ts`), + content: render(obj), + })), }; } diff --git a/docs/recipes/write-your-own-generator.md b/docs/recipes/write-your-own-generator.md index fe3265453f..22c453d34d 100644 --- a/docs/recipes/write-your-own-generator.md +++ b/docs/recipes/write-your-own-generator.md @@ -294,6 +294,21 @@ class KtFieldListGenerator : FileEmittingGenerator() { Wire it with `com.acme.codegen.KtFieldListGenerator` from a module built with `kotlin-maven-plugin`. +A generator that emits a type, module, barrel entry, route segment or file path into a scope +it shares with other generators should claim each name as it emits it, so a real clash is +refused with `ERR_NAME_COLLISION` naming both claimants instead of one file silently +overwriting another. The call: TypeScript `ctx.claim?.(scope, name, claimant, remedy)` +(optional — absent on a direct `.generate(ctx)` call outside `runGen`), C# +`ctx.Claim(scope, name, claimant, remedy)`, Python `ctx.claim(scope, name, claimant, +remedy)`. The `scope` is a short label for where the name lives (a generated package +directory, the barrel of a target), the `claimant` the metadata node as its +`resolutionKey()` (C# `ResolutionKey()`, Python `resolution_key()`), and the `remedy` the +sentence the refusal prints. +The same claimant claiming again is not a collision, and one name in two scopes is two +names. The JVM ports take no claim call: their file writer refuses an output path two +generators emit with different content in one run (byte-identical duplicates collapse), and +nothing checks emitted names. + ## Safety-relevant output: set `handEdits: "overwrite"` A generator whose output enforces something (a redaction rule, an audit log, an auth check) diff --git a/examples/advanced-modeling/codegen/generators/barrel.ts b/examples/advanced-modeling/codegen/generators/barrel.ts index a19c86154f..2c82677ac3 100644 --- a/examples/advanced-modeling/codegen/generators/barrel.ts +++ b/examples/advanced-modeling/codegen/generators/barrel.ts @@ -28,6 +28,7 @@ import { GENERATED_HEADER, GENERATED_EDIT_NOTE, effectivePackage, + claimBarrelNames, } from "@metaobjectsdev/codegen-ts/engine"; interface BarrelEntry { @@ -61,11 +62,13 @@ export const barrel = function barrel(opts?: BarrelOpts): Generator { throw new Error("barrel: renderContext is required (provided by runGen)"); } const rc = ctx.renderContext; + // Every name the barrel re-exports lives in its one namespace. + for (const e of entities) claimBarrelNames(ctx, e); return { path: "index.ts", content: await formatTs( renderBarrel( - entities.map((e) => ({ name: rc.valueObjectEmittedName(e), package: effectivePackage(e) })), + entities.map((e) => ({ name: e.name, package: effectivePackage(e) })), rc.extStyle, rc.selfTarget, rc.entityModuleTarget, diff --git a/examples/advanced-modeling/codegen/generators/entity.ts b/examples/advanced-modeling/codegen/generators/entity.ts index 6919ae8d3c..ced0ea9be7 100644 --- a/examples/advanced-modeling/codegen/generators/entity.ts +++ b/examples/advanced-modeling/codegen/generators/entity.ts @@ -63,6 +63,7 @@ import { GENERATED_EDIT_NOTE, sidecarLine, isTphSubtype, + claimModuleNames, } from "@metaobjectsdev/codegen-ts/engine"; import { renderDrizzleSchema } from "../templates/drizzle-schema.js"; import { renderEntityConstants } from "../templates/entity-constants.js"; @@ -176,6 +177,9 @@ export const entityFile = function entityFile(opts?: EntityFileOpts): Generator if (isAbstract(entity) && !ctx.renderContext.emitAbstractShapes) { return []; } + // Claim the module's type name in its directory: two objects + // emitting one name there are refused, naming both. + claimModuleNames(ctx, entity); const renderContext: RenderContext = { ...ctx.renderContext, httpRuntimeImport: opts?.runtimeImport diff --git a/examples/advanced-modeling/codegen/generators/queries.ts b/examples/advanced-modeling/codegen/generators/queries.ts index 3be4632cbb..6933c4c227 100644 --- a/examples/advanced-modeling/codegen/generators/queries.ts +++ b/examples/advanced-modeling/codegen/generators/queries.ts @@ -49,6 +49,7 @@ import { GENERATED_EDIT_NOTE, sidecarLine, isTphSubtype, + claimModuleNames, } from "@metaobjectsdev/codegen-ts/engine"; import { renderQueriesFile } from "../templates/queries-file.js"; import { @@ -168,6 +169,7 @@ export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generat if (!ctx.renderContext) { throw new Error("queries-file: renderContext is required (provided by runGen)"); } + claimModuleNames(ctx, entity); return { path: entityOutputPath(ctx.config.outputLayout ?? "flat", effectivePackage(entity), `${entity.name}.queries.ts`), content: await formatTs(renderQueries(entity, ctx.renderContext)), diff --git a/examples/advanced-modeling/codegen/generators/routes.ts b/examples/advanced-modeling/codegen/generators/routes.ts index 08d409771c..c4765ce5cd 100644 --- a/examples/advanced-modeling/codegen/generators/routes.ts +++ b/examples/advanced-modeling/codegen/generators/routes.ts @@ -91,6 +91,7 @@ import { isTphSubtype, tphDiscriminatorPin, tphStorageObject, + claimRouteSegment, } from "@metaobjectsdev/codegen-ts/engine"; import { renderRoutesIndex, routesIndexFileName } from "../templates/routes-index.js"; import { isTphDiscriminatorBase, tphPlan } from "../templates/tph-discriminator.js"; @@ -757,6 +758,7 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator if (!ctx.renderContext) { throw new Error("routes-file: renderContext is required (provided by runGen)"); } + claimRouteSegment(ctx, entity); const renderContext: RenderContext = { ...ctx.renderContext, httpRuntimeImport: opts?.runtimeImport diff --git a/examples/advanced-modeling/codegen/templates/drizzle-schema.ts b/examples/advanced-modeling/codegen/templates/drizzle-schema.ts index 16457c7dab..f943b82eff 100644 --- a/examples/advanced-modeling/codegen/templates/drizzle-schema.ts +++ b/examples/advanced-modeling/codegen/templates/drizzle-schema.ts @@ -5,7 +5,7 @@ import { code, imp, joinCode, type Code } from "@metaobjectsdev/codegen-ts/engine"; import { MetaObject, MetaField, MetaIndex, isMetaObject } from "@metaobjectsdev/metadata"; import { - IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION, + IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION, IDENTITY_ATTR_SEQUENCE_START, IDENTITY_ATTR_SEQUENCE_NAME, IDENTITY_ATTR_EXPR, IDENTITY_ATTR_USING, IDENTITY_ATTR_ORDERS, IDENTITY_ATTR_WHERE, GENERATION_INCREMENT, GENERATION_UUID, FIELD_ATTR_AUTO_SET, @@ -16,7 +16,7 @@ import { refTarget, } from "@metaobjectsdev/metadata"; import type { RenderContext } from "@metaobjectsdev/codegen-ts/engine"; -import { crossEntitySpecifier, valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; +import { crossEntitySpecifier, valueObjectFieldImport, valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; import { mapColumnType, PG_IDENTITY_CAPABLE_FNS, DURATION_COLUMN_FN, type ColumnSpec, type EnumIntCustomType, @@ -152,6 +152,14 @@ export function renderDrizzleSchema( : []; const pkFieldNames = new Set(pkFieldsList); const pkGeneration = primary?.attr(IDENTITY_ATTR_GENERATION) as string | undefined; + // #544 — the increment key's declared sequence (ADR-0039: resolving reads), carried into + // Drizzle's identity options so a schema Drizzle creates begins at `@sequenceStart` too. + const seqStart = primary?.attr(IDENTITY_ATTR_SEQUENCE_START); + const seqName = primary?.attr(IDENTITY_ATTR_SEQUENCE_NAME); + const pkSequence = { + ...(typeof seqStart === "number" ? { start: seqStart } : {}), + ...(typeof seqName === "string" ? { name: seqName } : {}), + }; const fkMap = buildFkMapForEntity(obj, ctx); @@ -263,7 +271,7 @@ export function renderDrizzleSchema( } if (spec.durationCustomType !== undefined) usesDurationCodec = true; const fieldDocs = renderDocsFor(child); - const columnLine = renderColumn(spec, columnNameExpr(child, spec.dbName), child, ctx, isPk, pkGeneration, fkInfo, isComposite, pkg, obj.name); + const columnLine = renderColumn(spec, columnNameExpr(child, spec.dbName), child, ctx, isPk, pkGeneration, fkInfo, isComposite, pkg, obj.name, false, child.name, pkSequence); columnLines.push(fieldDocs ? code` ${fieldDocs}\n${columnLine}` : columnLine); if (spec.checkConstraint !== undefined) checkConstraints.push(checkEntry(child, spec)); } @@ -554,6 +562,8 @@ function renderColumn( // `field.object @storage: flattened`: the Drizzle KEY of a member's column (`shipToStreet`); // absent, the key is the field's own name. keyName: string = field.name, + // An increment key's declared `@sequenceStart` / `@sequenceName` (#544); absent, none. + pkSequence: { start?: number | undefined; name?: string | undefined } = {}, ): Code { // An int-backed field.enum's column function is a LOCAL generated const (the // customType helper emitted into this same file), so it must not be imported @@ -613,7 +623,7 @@ function renderColumn( spec.enumIntCustomType === undefined && PG_IDENTITY_CAPABLE_FNS.has(spec.fnName) ) { - pkSuffix += ".generatedByDefaultAsIdentity()"; + pkSuffix += `.generatedByDefaultAsIdentity(${identityOptionsLiteral(pkSequence)})`; } } } else if (pkGeneration === GENERATION_UUID) { @@ -743,19 +753,14 @@ function renderColumn( // immediately after the baseCall so the chain reads `.text(...).$type<...>().notNull()...` // which Drizzle accepts in any order but is conventional for "type narrowing // first." - // Resolve a VO name → an imported type symbol (shared layout/package/extStyle-aware - // helper, so the .$type import matches the field's TS type + Zod schema). - // ADR-0044/#228 — resolve the field's @objectRef to the value object's EMITTED - // name (bare when unique in the run, package-qualified on a cross-package - // short-name collision), resolved package-locally from the FIELD's declaring - // package. `name` (the bare dollarTypeRef name) is the byte-identical fallback - // when the ref doesn't resolve to an emitted value object. + // The field's `@objectRef` → an imported type symbol, through the shared + // layout/package/extStyle-aware helper so the .$type import matches the field's TS type + // + Zod schema. An unresolved ref falls back to the bare dollarTypeRef `name` in this package. const voSym = (name: string) => { const refRaw = field.attr(FIELD_ATTR_OBJECT_REF); - const emitted = typeof refRaw === "string" - ? ctx.resolveValueObjectName(field) - : name; - return imp(`t:${emitted}@${valueObjectModuleSpecifier(emitted, ctx.packageOf, entityPackage, ctx.outputLayout, ctx.extStyle)}`); + return typeof refRaw === "string" + ? valueObjectFieldImport(ctx, field, entityPackage, "", true) + : imp(`t:${name}@${valueObjectModuleSpecifier(undefined, name, entityPackage, ctx.outputLayout, ctx.extStyle)}`); }; let dollarTypeSegment: Code | string = ""; @@ -779,3 +784,14 @@ function renderColumn( ? code` // ${spec.leadingComment}\n${columnLine}` : columnLine; } + +/** + * Drizzle's identity options for what the model declares, the same two meta migrate writes + * (`SEQUENCE NAME … START WITH n`): `{ name: "Old_Id_seq", startWith: 1000 }`, or nothing. + */ +function identityOptionsLiteral(seq: { start?: number | undefined; name?: string | undefined }): string { + const parts: string[] = []; + if (seq.name !== undefined) parts.push(`name: ${JSON.stringify(seq.name)}`); + if (seq.start !== undefined) parts.push(`startWith: ${seq.start}`); + return parts.length === 0 ? "" : `{ ${parts.join(", ")} }`; +} diff --git a/examples/advanced-modeling/codegen/templates/entity-file.ts b/examples/advanced-modeling/codegen/templates/entity-file.ts index 7e460dbc63..c5dddf6d1c 100644 --- a/examples/advanced-modeling/codegen/templates/entity-file.ts +++ b/examples/advanced-modeling/codegen/templates/entity-file.ts @@ -28,7 +28,7 @@ import { } from "@metaobjectsdev/codegen-ts/engine"; import { renderExistingViewDecl, renderViewReadZodObject } from "./view-decl.js"; import { renderDocsFor } from "./jsdoc.js"; -import { valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; +import { valueObjectFieldImport } from "@metaobjectsdev/codegen-ts/engine"; import { namesRef, namesConstArg, physicalNameExpr, sourceSchemaExpr } from "@metaobjectsdev/codegen-ts/engine"; import { hasWritableRdbSource } from "@metaobjectsdev/codegen-ts/engine"; import { renderValueObjectFile } from "./value-object-file.js"; @@ -160,15 +160,10 @@ export function renderEntityFile( const camel = entity.name.charAt(0).toLowerCase() + entity.name.slice(1); const fields = entity.fields(); const entityPkg = effectivePackage(entity); - // ADR-0044/#228 — resolve a view column's `@objectRef` to the value object's - // EMITTED name + module TOGETHER (lock-step), so the read-view artifact imports - // `AcmeAlphaNote` from `./AcmeAlphaNote.js` (not a bare `Note` → `./Note.js`) - // under a cross-package short-name collision. - const voRef = (field: MetaField): { name: string; module: string } => { - const name = ctx.resolveValueObjectName(field); - const module = valueObjectModuleSpecifier(name, ctx.packageOf, entityPkg, ctx.outputLayout, ctx.extStyle); - return { name, module }; - }; + // A view column's `@objectRef`: the bound value object's import under its local name, + // through the same helper the entity's own columns use. + const voRef = (field: MetaField, suffix: string, typeOnly: boolean) => + valueObjectFieldImport(ctx, field, entityPkg, suffix, typeOnly); // ONE selection of the replica source: `projectionViewName` names it, and this is the // role its entry has in Names.sources. Hardcoding "replica" here would be a // second derivation of the very thing extract-view-spec.ts exists to decide once. diff --git a/examples/advanced-modeling/codegen/templates/inferred-types.ts b/examples/advanced-modeling/codegen/templates/inferred-types.ts index def5fb0499..ce3637de26 100644 --- a/examples/advanced-modeling/codegen/templates/inferred-types.ts +++ b/examples/advanced-modeling/codegen/templates/inferred-types.ts @@ -36,7 +36,7 @@ import { DB_COLUMN_TYPE_JSONB, } from "@metaobjectsdev/metadata"; import { variableNameFromEntity, toPascalCase } from "@metaobjectsdev/codegen-ts/engine"; -import { valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; +import { valueObjectFieldImport } from "@metaobjectsdev/codegen-ts/engine"; import { stripPackage } from "@metaobjectsdev/metadata"; import { enumValues } from "@metaobjectsdev/codegen-ts/engine"; import { sharedEnumZodConstName } from "./enums-file.js"; @@ -307,24 +307,19 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render if (field.subType === FIELD_SUBTYPE_OBJECT) { const ref = field.attr(FIELD_ATTR_OBJECT_REF); if (typeof ref === "string" && ref.length > 0) { - // @objectRef may be authored fully-qualified (acme::sales::Brief) or bare. - // ADR-0044/#228 — the referenced interface is named by its EMITTED name - // (bare when unique in the run, package-qualified on a cross-package - // short-name collision), resolved package-locally from the FIELD's declaring - // package. The import MODULE is resolved through the shared - // layout/package/extStyle-aware helper (the SAME one the Zod schema + - // Drizzle .$type<> use) so all three agree. Without a ctx (bare unit-test - // calls) fall back to the bare name + flat same-dir specifier. - const entityPkg = effectivePackage(entity); - const refName = ctx ? ctx.resolveValueObjectName(field) : stripPackage(ref); - const moduleSpec = ctx - ? valueObjectModuleSpecifier(refName, ctx.packageOf, entityPkg, ctx.outputLayout, ctx.extStyle) - : `./${refName}.js`; + // @objectRef may be authored fully-qualified (acme::sales::Brief) or bare. The + // referenced interface is the bound value object's, imported under its local name + // (aliased when another object shares the short name) through the + // shared layout/package/extStyle-aware helper the Zod schema + Drizzle .$type<> + // use, so all three agree. Without a ctx (bare unit-test calls) fall back to the + // bare name + flat same-dir specifier. // `t:` — the interface is a TYPE. Without it ts-poet merges it with the Zod // `InsertSchema` VALUE from the same module into one value import, which is // TS1484 under `verbatimModuleSyntax` (on in a fresh `tsc --init`). Same rule as // the shared-enum branch below (#341). - const refImp = imp(`t:${refName}@${moduleSpec}`); + const refImp = ctx + ? valueObjectFieldImport(ctx, field, effectivePackage(entity), "", true) + : imp(`t:${stripPackage(ref)}@./${stripPackage(ref)}.js`); return field.resolvedIsArray() ? code`${refImp}[]` : code`${refImp}`; } return field.resolvedIsArray() ? code`unknown[]` : code`unknown`; @@ -334,12 +329,9 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render if (field.subType === FIELD_SUBTYPE_MAP) { const ref = field.attr(FIELD_ATTR_OBJECT_REF); if (typeof ref === "string" && ref.length > 0) { - const entityPkg = effectivePackage(entity); - const refName = ctx ? ctx.resolveValueObjectName(field) : stripPackage(ref); - const moduleSpec = ctx - ? valueObjectModuleSpecifier(refName, ctx.packageOf, entityPkg, ctx.outputLayout, ctx.extStyle) - : `./${refName}.js`; - const refImp = imp(`t:${refName}@${moduleSpec}`); + const refImp = ctx + ? valueObjectFieldImport(ctx, field, effectivePackage(entity), "", true) + : imp(`t:${stripPackage(ref)}@./${stripPackage(ref)}.js`); return code`Record`; } const vt = field.attr(FIELD_ATTR_VALUE_TYPE); diff --git a/examples/advanced-modeling/codegen/templates/projection-decl.ts b/examples/advanced-modeling/codegen/templates/projection-decl.ts index a7ccbf0f93..57eed67274 100644 --- a/examples/advanced-modeling/codegen/templates/projection-decl.ts +++ b/examples/advanced-modeling/codegen/templates/projection-decl.ts @@ -10,7 +10,7 @@ // - Zod Insert/Update schemas // - Insert/Update types -import { code, imp, joinCode, type Code } from "@metaobjectsdev/codegen-ts/engine"; +import { code, imp, joinCode, type Code, type Import } from "@metaobjectsdev/codegen-ts/engine"; import { MetaField, MetaObject, type MetaRoot, isMetaObject, FIELD_ATTR_OBJECT_REF, stripPackage, resolveColumnName, resolveTableSchema, @@ -19,7 +19,7 @@ import { projectionViewName } from "@metaobjectsdev/codegen-ts/engine"; import { GENERATED_HEADER, GENERATED_EDIT_NOTE } from "@metaobjectsdev/codegen-ts/engine"; import type { ColumnNamingStrategy } from "@metaobjectsdev/codegen-ts/engine"; import type { RenderContext } from "@metaobjectsdev/codegen-ts/engine"; -import { valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; +import { valueObjectFieldImport } from "@metaobjectsdev/codegen-ts/engine"; import type { Dialect } from "@metaobjectsdev/codegen-ts/engine"; import { columnExpr, physicalNameExpr, sourceSchemaExpr, type ObjectNames } from "@metaobjectsdev/codegen-ts/engine"; import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js"; @@ -103,22 +103,15 @@ export function renderProjectionDecl( ): string { const { dialect, columnNamingStrategy, timestampMode = "string", allowlists = true, ctx, includeViewDecl = true, names } = opts; - // ADR-0044/#228 — resolve a projection field's `@objectRef` to the value object's - // EMITTED name + module TOGETHER (lock-step): bare when unique in the run, - // package-qualified on a cross-package short-name collision, so the projection's - // VO import matches the entity's. Layout/package/extStyle-aware when a render - // context is present, else a flat same-dir import (zodFieldExpr's fallback). + // A projection field's `@objectRef`: the bound value object's import, under its local name, + // so the projection's VO import matches the entity's. Layout/package/extStyle-aware when a + // render context is present, else a flat same-dir import (zodFieldExpr's fallback). const projectionPkg = effectivePackage(projection); - const voRef = (field: MetaField): { name: string; module: string } => { + const voRef = (field: MetaField, suffix: string, typeOnly: boolean): Import => { + if (ctx) return valueObjectFieldImport(ctx, field, projectionPkg, suffix, typeOnly); const ref = field.attr(FIELD_ATTR_OBJECT_REF); - const rawRef = typeof ref === "string" ? ref : ""; - const name = ctx - ? ctx.resolveValueObjectName(field) - : stripPackage(rawRef); - const module = ctx - ? valueObjectModuleSpecifier(name, ctx.packageOf, projectionPkg, ctx.outputLayout, ctx.extStyle) - : `./${name}.js`; - return { name, module }; + const name = stripPackage(typeof ref === "string" ? ref : ""); + return imp(`${typeOnly ? "t:" : ""}${name}${suffix}@./${name}.js`); }; const z = imp("z@zod"); diff --git a/examples/advanced-modeling/codegen/templates/view-decl.ts b/examples/advanced-modeling/codegen/templates/view-decl.ts index eec5e9ed44..9770bc091d 100644 --- a/examples/advanced-modeling/codegen/templates/view-decl.ts +++ b/examples/advanced-modeling/codegen/templates/view-decl.ts @@ -7,7 +7,7 @@ // attempt DDL (the SQL view is created/owned by migrate-ts). Both hosts emit the // SAME declaration shape, so it lives here once (extracted from projection-decl). -import { code, imp, joinCode, type Code } from "@metaobjectsdev/codegen-ts/engine"; +import { code, imp, joinCode, type Code, type Import } from "@metaobjectsdev/codegen-ts/engine"; import { dialectModule } from "@metaobjectsdev/codegen-ts/engine"; import type { Dialect } from "@metaobjectsdev/codegen-ts/engine"; import { @@ -35,14 +35,12 @@ export interface ViewDeclOpts { */ readonly declaredEnumIntCodecs?: ReadonlySet; /** - * ADR-0044/#228 — resolve a `field.object` / `field.map`'s `@objectRef` to the - * value object's EMITTED name (bare when unique in the run, package-qualified on - * a cross-package short-name collision) AND its import module, TOGETHER, so the - * imported symbol and its module can never diverge (a bare `Note` symbol pointing - * at an `./AcmeAlphaNote.js` module, or vice-versa). Callers build this from - * `RenderContext.resolveValueObjectName` + `valueObjectModuleSpecifier`. + * The import of `` for a `field.object` / `field.map`'s `@objectRef` (the + * interface with `suffix` "", the Zod schema with "InsertSchema"): the bound value object's + * module, under its local name, so the symbol and its module can never diverge. Callers + * build this from `valueObjectFieldImport`. */ - readonly voRef: (field: MetaField) => { name: string; module: string }; + readonly voRef: (field: MetaField, suffix: string, typeOnly: boolean) => Import; /** * Field names of the owning object's PRIMARY identity (see * `primaryIdentityFieldNames` in zod-validators). A PK column sits on the FROM @@ -135,15 +133,13 @@ function viewColumnLine( dollarType = `.$type<${dtr.tsType}${dtr.array ? "[]" : ""}>()`; } else if (dtr?.kind === "objectRef") { // #228 — emitted name + module resolved together (lock-step) from the field's ref. - const vo = opts.voRef(f); - const voTypeSym = imp(`t:${vo.name}@${vo.module}`); + const voTypeSym = opts.voRef(f, "", true); dollarType = dtr.array ? code`.$type<${voTypeSym}[]>()` : code`.$type<${voTypeSym}>()`; } else if (dtr?.kind === "map") { if ("scalar" in dtr.value) { dollarType = `.$type>()`; } else { - const vo = opts.voRef(f); - dollarType = code`.$type>()`; + dollarType = code`.$type>()`; } } // A6 — reference the constant whenever the artifact is in the run AND carries this @@ -241,8 +237,7 @@ export function renderViewReadZodObject(fields: readonly MetaField[], opts: View if (hasObjectRef) { // #228 — the InsertSchema symbol + its module resolved together from the // field's ref, so a cross-package collision qualifies both consistently. - const vo = opts.voRef(f); - const schemaSym = imp(`${vo.name}InsertSchema@${vo.module}`); + const schemaSym = opts.voRef(f, "InsertSchema", false); const base = f.resolvedIsArray() ? code`${z}.array(${schemaSym})` : code`${schemaSym}`; return code` ${f.name}: ${base}${nullable}`; } diff --git a/examples/advanced-modeling/codegen/templates/zod-validators.ts b/examples/advanced-modeling/codegen/templates/zod-validators.ts index 2e421a0819..3624dd7db3 100644 --- a/examples/advanced-modeling/codegen/templates/zod-validators.ts +++ b/examples/advanced-modeling/codegen/templates/zod-validators.ts @@ -57,7 +57,7 @@ import { sharedEnumForField } from "@metaobjectsdev/codegen-ts/engine"; import { sharedEnumImportSpecifier } from "@metaobjectsdev/codegen-ts/engine"; import { sharedEnumZodConstName } from "./enums-file.js"; import type { RenderContext } from "@metaobjectsdev/codegen-ts/engine"; -import { valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; +import { valueObjectFieldImport } from "@metaobjectsdev/codegen-ts/engine"; // FR-035: the SAME required-predicate that drives the Drizzle column's .notNull() // drives the UpdateSchema's .nullable() exclusion — shared so they cannot drift. import { isRequired } from "@metaobjectsdev/codegen-ts/engine"; @@ -976,20 +976,15 @@ function zodFieldExpr( if (field.subType === FIELD_SUBTYPE_OBJECT) { const ref = field.attr(FIELD_ATTR_OBJECT_REF); if (typeof ref === "string" && ref.length > 0) { - // @objectRef may be authored fully-qualified or bare. ADR-0044/#228 — the - // referenced InsertSchema is named by the value object's EMITTED name - // (bare when unique in the run, package-qualified on a cross-package - // short-name collision), resolved package-locally from the FIELD's declaring - // package. The import MODULE is resolved via the shared - // layout/package/extStyle-aware helper (the SAME one the field's TS type + - // Drizzle .$type<> use) so all three agree. Without owner/ctx (bare - // unit-test calls) fall back to the bare name + flat same-dir. - const ownerPkg = (ctx && owner) ? effectivePackage(owner) : undefined; - const refName = (ctx && owner) ? ctx.resolveValueObjectName(field) : stripPackage(ref); - const moduleSpec = (ctx && owner) - ? valueObjectModuleSpecifier(refName, ctx.packageOf, ownerPkg, ctx.outputLayout, ctx.extStyle) - : `./${refName}.js`; - const refImp = imp(`${refName}InsertSchema@${moduleSpec}`); + // @objectRef may be authored fully-qualified or bare. The referenced + // InsertSchema is the bound value object's, imported under its local name + // (aliased when another object shares the short name) through the + // shared layout/package/extStyle-aware helper the field's TS type + Drizzle + // .$type<> use, so all three agree. Without owner/ctx (bare unit-test calls) + // fall back to the bare name + flat same-dir. + const refImp = (ctx && owner) + ? valueObjectFieldImport(ctx, field, effectivePackage(owner), "InsertSchema", false) + : imp(`${stripPackage(ref)}InsertSchema@./${stripPackage(ref)}.js`); let base: Code = code`${refImp}`; if (field.resolvedIsArray()) base = code`z.array(${base})`; return appendValidatorChain(base, field, forceRequired); @@ -1006,12 +1001,9 @@ function zodFieldExpr( if (field.subType === FIELD_SUBTYPE_MAP) { const ref = field.attr(FIELD_ATTR_OBJECT_REF); if (typeof ref === "string" && ref.length > 0) { - const ownerPkg = (ctx && owner) ? effectivePackage(owner) : undefined; - const refName = (ctx && owner) ? ctx.resolveValueObjectName(field) : stripPackage(ref); - const moduleSpec = (ctx && owner) - ? valueObjectModuleSpecifier(refName, ctx.packageOf, ownerPkg, ctx.outputLayout, ctx.extStyle) - : `./${refName}.js`; - const refImp = imp(`${refName}InsertSchema@${moduleSpec}`); + const refImp = (ctx && owner) + ? valueObjectFieldImport(ctx, field, effectivePackage(owner), "InsertSchema", false) + : imp(`${stripPackage(ref)}InsertSchema@./${stripPackage(ref)}.js`); return appendValidatorChain(code`z.record(z.string(), ${refImp})`, field, forceRequired); } const vt = field.attr(FIELD_ATTR_VALUE_TYPE); @@ -1087,7 +1079,7 @@ function zodFieldExpr( const shared = sharedEnumForField(field); if (shared !== undefined && !shared.provided) { const constName = sharedEnumZodConstName(shared.name); - const spec = sharedEnumImportSpecifier(ctx, owner?.package); + const spec = sharedEnumImportSpecifier(ctx, owner ? effectivePackage(owner) : undefined); const sharedConst = imp(`${constName}@${spec}`); let base: Code = code`${sharedConst}`; if (field.resolvedIsArray()) base = code`z.array(${base})`; diff --git a/examples/showcase/codegen/generators/barrel.ts b/examples/showcase/codegen/generators/barrel.ts index a19c86154f..2c82677ac3 100644 --- a/examples/showcase/codegen/generators/barrel.ts +++ b/examples/showcase/codegen/generators/barrel.ts @@ -28,6 +28,7 @@ import { GENERATED_HEADER, GENERATED_EDIT_NOTE, effectivePackage, + claimBarrelNames, } from "@metaobjectsdev/codegen-ts/engine"; interface BarrelEntry { @@ -61,11 +62,13 @@ export const barrel = function barrel(opts?: BarrelOpts): Generator { throw new Error("barrel: renderContext is required (provided by runGen)"); } const rc = ctx.renderContext; + // Every name the barrel re-exports lives in its one namespace. + for (const e of entities) claimBarrelNames(ctx, e); return { path: "index.ts", content: await formatTs( renderBarrel( - entities.map((e) => ({ name: rc.valueObjectEmittedName(e), package: effectivePackage(e) })), + entities.map((e) => ({ name: e.name, package: effectivePackage(e) })), rc.extStyle, rc.selfTarget, rc.entityModuleTarget, diff --git a/examples/showcase/codegen/generators/entity.ts b/examples/showcase/codegen/generators/entity.ts index 6919ae8d3c..ced0ea9be7 100644 --- a/examples/showcase/codegen/generators/entity.ts +++ b/examples/showcase/codegen/generators/entity.ts @@ -63,6 +63,7 @@ import { GENERATED_EDIT_NOTE, sidecarLine, isTphSubtype, + claimModuleNames, } from "@metaobjectsdev/codegen-ts/engine"; import { renderDrizzleSchema } from "../templates/drizzle-schema.js"; import { renderEntityConstants } from "../templates/entity-constants.js"; @@ -176,6 +177,9 @@ export const entityFile = function entityFile(opts?: EntityFileOpts): Generator if (isAbstract(entity) && !ctx.renderContext.emitAbstractShapes) { return []; } + // Claim the module's type name in its directory: two objects + // emitting one name there are refused, naming both. + claimModuleNames(ctx, entity); const renderContext: RenderContext = { ...ctx.renderContext, httpRuntimeImport: opts?.runtimeImport diff --git a/examples/showcase/codegen/generators/queries.ts b/examples/showcase/codegen/generators/queries.ts index 3be4632cbb..6933c4c227 100644 --- a/examples/showcase/codegen/generators/queries.ts +++ b/examples/showcase/codegen/generators/queries.ts @@ -49,6 +49,7 @@ import { GENERATED_EDIT_NOTE, sidecarLine, isTphSubtype, + claimModuleNames, } from "@metaobjectsdev/codegen-ts/engine"; import { renderQueriesFile } from "../templates/queries-file.js"; import { @@ -168,6 +169,7 @@ export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generat if (!ctx.renderContext) { throw new Error("queries-file: renderContext is required (provided by runGen)"); } + claimModuleNames(ctx, entity); return { path: entityOutputPath(ctx.config.outputLayout ?? "flat", effectivePackage(entity), `${entity.name}.queries.ts`), content: await formatTs(renderQueries(entity, ctx.renderContext)), diff --git a/examples/showcase/codegen/generators/routes.ts b/examples/showcase/codegen/generators/routes.ts index 08d409771c..c4765ce5cd 100644 --- a/examples/showcase/codegen/generators/routes.ts +++ b/examples/showcase/codegen/generators/routes.ts @@ -91,6 +91,7 @@ import { isTphSubtype, tphDiscriminatorPin, tphStorageObject, + claimRouteSegment, } from "@metaobjectsdev/codegen-ts/engine"; import { renderRoutesIndex, routesIndexFileName } from "../templates/routes-index.js"; import { isTphDiscriminatorBase, tphPlan } from "../templates/tph-discriminator.js"; @@ -757,6 +758,7 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator if (!ctx.renderContext) { throw new Error("routes-file: renderContext is required (provided by runGen)"); } + claimRouteSegment(ctx, entity); const renderContext: RenderContext = { ...ctx.renderContext, httpRuntimeImport: opts?.runtimeImport diff --git a/examples/showcase/codegen/templates/drizzle-schema.ts b/examples/showcase/codegen/templates/drizzle-schema.ts index 16457c7dab..f943b82eff 100644 --- a/examples/showcase/codegen/templates/drizzle-schema.ts +++ b/examples/showcase/codegen/templates/drizzle-schema.ts @@ -5,7 +5,7 @@ import { code, imp, joinCode, type Code } from "@metaobjectsdev/codegen-ts/engine"; import { MetaObject, MetaField, MetaIndex, isMetaObject } from "@metaobjectsdev/metadata"; import { - IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION, + IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION, IDENTITY_ATTR_SEQUENCE_START, IDENTITY_ATTR_SEQUENCE_NAME, IDENTITY_ATTR_EXPR, IDENTITY_ATTR_USING, IDENTITY_ATTR_ORDERS, IDENTITY_ATTR_WHERE, GENERATION_INCREMENT, GENERATION_UUID, FIELD_ATTR_AUTO_SET, @@ -16,7 +16,7 @@ import { refTarget, } from "@metaobjectsdev/metadata"; import type { RenderContext } from "@metaobjectsdev/codegen-ts/engine"; -import { crossEntitySpecifier, valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; +import { crossEntitySpecifier, valueObjectFieldImport, valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; import { mapColumnType, PG_IDENTITY_CAPABLE_FNS, DURATION_COLUMN_FN, type ColumnSpec, type EnumIntCustomType, @@ -152,6 +152,14 @@ export function renderDrizzleSchema( : []; const pkFieldNames = new Set(pkFieldsList); const pkGeneration = primary?.attr(IDENTITY_ATTR_GENERATION) as string | undefined; + // #544 — the increment key's declared sequence (ADR-0039: resolving reads), carried into + // Drizzle's identity options so a schema Drizzle creates begins at `@sequenceStart` too. + const seqStart = primary?.attr(IDENTITY_ATTR_SEQUENCE_START); + const seqName = primary?.attr(IDENTITY_ATTR_SEQUENCE_NAME); + const pkSequence = { + ...(typeof seqStart === "number" ? { start: seqStart } : {}), + ...(typeof seqName === "string" ? { name: seqName } : {}), + }; const fkMap = buildFkMapForEntity(obj, ctx); @@ -263,7 +271,7 @@ export function renderDrizzleSchema( } if (spec.durationCustomType !== undefined) usesDurationCodec = true; const fieldDocs = renderDocsFor(child); - const columnLine = renderColumn(spec, columnNameExpr(child, spec.dbName), child, ctx, isPk, pkGeneration, fkInfo, isComposite, pkg, obj.name); + const columnLine = renderColumn(spec, columnNameExpr(child, spec.dbName), child, ctx, isPk, pkGeneration, fkInfo, isComposite, pkg, obj.name, false, child.name, pkSequence); columnLines.push(fieldDocs ? code` ${fieldDocs}\n${columnLine}` : columnLine); if (spec.checkConstraint !== undefined) checkConstraints.push(checkEntry(child, spec)); } @@ -554,6 +562,8 @@ function renderColumn( // `field.object @storage: flattened`: the Drizzle KEY of a member's column (`shipToStreet`); // absent, the key is the field's own name. keyName: string = field.name, + // An increment key's declared `@sequenceStart` / `@sequenceName` (#544); absent, none. + pkSequence: { start?: number | undefined; name?: string | undefined } = {}, ): Code { // An int-backed field.enum's column function is a LOCAL generated const (the // customType helper emitted into this same file), so it must not be imported @@ -613,7 +623,7 @@ function renderColumn( spec.enumIntCustomType === undefined && PG_IDENTITY_CAPABLE_FNS.has(spec.fnName) ) { - pkSuffix += ".generatedByDefaultAsIdentity()"; + pkSuffix += `.generatedByDefaultAsIdentity(${identityOptionsLiteral(pkSequence)})`; } } } else if (pkGeneration === GENERATION_UUID) { @@ -743,19 +753,14 @@ function renderColumn( // immediately after the baseCall so the chain reads `.text(...).$type<...>().notNull()...` // which Drizzle accepts in any order but is conventional for "type narrowing // first." - // Resolve a VO name → an imported type symbol (shared layout/package/extStyle-aware - // helper, so the .$type import matches the field's TS type + Zod schema). - // ADR-0044/#228 — resolve the field's @objectRef to the value object's EMITTED - // name (bare when unique in the run, package-qualified on a cross-package - // short-name collision), resolved package-locally from the FIELD's declaring - // package. `name` (the bare dollarTypeRef name) is the byte-identical fallback - // when the ref doesn't resolve to an emitted value object. + // The field's `@objectRef` → an imported type symbol, through the shared + // layout/package/extStyle-aware helper so the .$type import matches the field's TS type + // + Zod schema. An unresolved ref falls back to the bare dollarTypeRef `name` in this package. const voSym = (name: string) => { const refRaw = field.attr(FIELD_ATTR_OBJECT_REF); - const emitted = typeof refRaw === "string" - ? ctx.resolveValueObjectName(field) - : name; - return imp(`t:${emitted}@${valueObjectModuleSpecifier(emitted, ctx.packageOf, entityPackage, ctx.outputLayout, ctx.extStyle)}`); + return typeof refRaw === "string" + ? valueObjectFieldImport(ctx, field, entityPackage, "", true) + : imp(`t:${name}@${valueObjectModuleSpecifier(undefined, name, entityPackage, ctx.outputLayout, ctx.extStyle)}`); }; let dollarTypeSegment: Code | string = ""; @@ -779,3 +784,14 @@ function renderColumn( ? code` // ${spec.leadingComment}\n${columnLine}` : columnLine; } + +/** + * Drizzle's identity options for what the model declares, the same two meta migrate writes + * (`SEQUENCE NAME … START WITH n`): `{ name: "Old_Id_seq", startWith: 1000 }`, or nothing. + */ +function identityOptionsLiteral(seq: { start?: number | undefined; name?: string | undefined }): string { + const parts: string[] = []; + if (seq.name !== undefined) parts.push(`name: ${JSON.stringify(seq.name)}`); + if (seq.start !== undefined) parts.push(`startWith: ${seq.start}`); + return parts.length === 0 ? "" : `{ ${parts.join(", ")} }`; +} diff --git a/examples/showcase/codegen/templates/entity-file.ts b/examples/showcase/codegen/templates/entity-file.ts index 7e460dbc63..c5dddf6d1c 100644 --- a/examples/showcase/codegen/templates/entity-file.ts +++ b/examples/showcase/codegen/templates/entity-file.ts @@ -28,7 +28,7 @@ import { } from "@metaobjectsdev/codegen-ts/engine"; import { renderExistingViewDecl, renderViewReadZodObject } from "./view-decl.js"; import { renderDocsFor } from "./jsdoc.js"; -import { valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; +import { valueObjectFieldImport } from "@metaobjectsdev/codegen-ts/engine"; import { namesRef, namesConstArg, physicalNameExpr, sourceSchemaExpr } from "@metaobjectsdev/codegen-ts/engine"; import { hasWritableRdbSource } from "@metaobjectsdev/codegen-ts/engine"; import { renderValueObjectFile } from "./value-object-file.js"; @@ -160,15 +160,10 @@ export function renderEntityFile( const camel = entity.name.charAt(0).toLowerCase() + entity.name.slice(1); const fields = entity.fields(); const entityPkg = effectivePackage(entity); - // ADR-0044/#228 — resolve a view column's `@objectRef` to the value object's - // EMITTED name + module TOGETHER (lock-step), so the read-view artifact imports - // `AcmeAlphaNote` from `./AcmeAlphaNote.js` (not a bare `Note` → `./Note.js`) - // under a cross-package short-name collision. - const voRef = (field: MetaField): { name: string; module: string } => { - const name = ctx.resolveValueObjectName(field); - const module = valueObjectModuleSpecifier(name, ctx.packageOf, entityPkg, ctx.outputLayout, ctx.extStyle); - return { name, module }; - }; + // A view column's `@objectRef`: the bound value object's import under its local name, + // through the same helper the entity's own columns use. + const voRef = (field: MetaField, suffix: string, typeOnly: boolean) => + valueObjectFieldImport(ctx, field, entityPkg, suffix, typeOnly); // ONE selection of the replica source: `projectionViewName` names it, and this is the // role its entry has in Names.sources. Hardcoding "replica" here would be a // second derivation of the very thing extract-view-spec.ts exists to decide once. diff --git a/examples/showcase/codegen/templates/inferred-types.ts b/examples/showcase/codegen/templates/inferred-types.ts index def5fb0499..ce3637de26 100644 --- a/examples/showcase/codegen/templates/inferred-types.ts +++ b/examples/showcase/codegen/templates/inferred-types.ts @@ -36,7 +36,7 @@ import { DB_COLUMN_TYPE_JSONB, } from "@metaobjectsdev/metadata"; import { variableNameFromEntity, toPascalCase } from "@metaobjectsdev/codegen-ts/engine"; -import { valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; +import { valueObjectFieldImport } from "@metaobjectsdev/codegen-ts/engine"; import { stripPackage } from "@metaobjectsdev/metadata"; import { enumValues } from "@metaobjectsdev/codegen-ts/engine"; import { sharedEnumZodConstName } from "./enums-file.js"; @@ -307,24 +307,19 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render if (field.subType === FIELD_SUBTYPE_OBJECT) { const ref = field.attr(FIELD_ATTR_OBJECT_REF); if (typeof ref === "string" && ref.length > 0) { - // @objectRef may be authored fully-qualified (acme::sales::Brief) or bare. - // ADR-0044/#228 — the referenced interface is named by its EMITTED name - // (bare when unique in the run, package-qualified on a cross-package - // short-name collision), resolved package-locally from the FIELD's declaring - // package. The import MODULE is resolved through the shared - // layout/package/extStyle-aware helper (the SAME one the Zod schema + - // Drizzle .$type<> use) so all three agree. Without a ctx (bare unit-test - // calls) fall back to the bare name + flat same-dir specifier. - const entityPkg = effectivePackage(entity); - const refName = ctx ? ctx.resolveValueObjectName(field) : stripPackage(ref); - const moduleSpec = ctx - ? valueObjectModuleSpecifier(refName, ctx.packageOf, entityPkg, ctx.outputLayout, ctx.extStyle) - : `./${refName}.js`; + // @objectRef may be authored fully-qualified (acme::sales::Brief) or bare. The + // referenced interface is the bound value object's, imported under its local name + // (aliased when another object shares the short name) through the + // shared layout/package/extStyle-aware helper the Zod schema + Drizzle .$type<> + // use, so all three agree. Without a ctx (bare unit-test calls) fall back to the + // bare name + flat same-dir specifier. // `t:` — the interface is a TYPE. Without it ts-poet merges it with the Zod // `InsertSchema` VALUE from the same module into one value import, which is // TS1484 under `verbatimModuleSyntax` (on in a fresh `tsc --init`). Same rule as // the shared-enum branch below (#341). - const refImp = imp(`t:${refName}@${moduleSpec}`); + const refImp = ctx + ? valueObjectFieldImport(ctx, field, effectivePackage(entity), "", true) + : imp(`t:${stripPackage(ref)}@./${stripPackage(ref)}.js`); return field.resolvedIsArray() ? code`${refImp}[]` : code`${refImp}`; } return field.resolvedIsArray() ? code`unknown[]` : code`unknown`; @@ -334,12 +329,9 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render if (field.subType === FIELD_SUBTYPE_MAP) { const ref = field.attr(FIELD_ATTR_OBJECT_REF); if (typeof ref === "string" && ref.length > 0) { - const entityPkg = effectivePackage(entity); - const refName = ctx ? ctx.resolveValueObjectName(field) : stripPackage(ref); - const moduleSpec = ctx - ? valueObjectModuleSpecifier(refName, ctx.packageOf, entityPkg, ctx.outputLayout, ctx.extStyle) - : `./${refName}.js`; - const refImp = imp(`t:${refName}@${moduleSpec}`); + const refImp = ctx + ? valueObjectFieldImport(ctx, field, effectivePackage(entity), "", true) + : imp(`t:${stripPackage(ref)}@./${stripPackage(ref)}.js`); return code`Record`; } const vt = field.attr(FIELD_ATTR_VALUE_TYPE); diff --git a/examples/showcase/codegen/templates/projection-decl.ts b/examples/showcase/codegen/templates/projection-decl.ts index a7ccbf0f93..57eed67274 100644 --- a/examples/showcase/codegen/templates/projection-decl.ts +++ b/examples/showcase/codegen/templates/projection-decl.ts @@ -10,7 +10,7 @@ // - Zod Insert/Update schemas // - Insert/Update types -import { code, imp, joinCode, type Code } from "@metaobjectsdev/codegen-ts/engine"; +import { code, imp, joinCode, type Code, type Import } from "@metaobjectsdev/codegen-ts/engine"; import { MetaField, MetaObject, type MetaRoot, isMetaObject, FIELD_ATTR_OBJECT_REF, stripPackage, resolveColumnName, resolveTableSchema, @@ -19,7 +19,7 @@ import { projectionViewName } from "@metaobjectsdev/codegen-ts/engine"; import { GENERATED_HEADER, GENERATED_EDIT_NOTE } from "@metaobjectsdev/codegen-ts/engine"; import type { ColumnNamingStrategy } from "@metaobjectsdev/codegen-ts/engine"; import type { RenderContext } from "@metaobjectsdev/codegen-ts/engine"; -import { valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; +import { valueObjectFieldImport } from "@metaobjectsdev/codegen-ts/engine"; import type { Dialect } from "@metaobjectsdev/codegen-ts/engine"; import { columnExpr, physicalNameExpr, sourceSchemaExpr, type ObjectNames } from "@metaobjectsdev/codegen-ts/engine"; import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js"; @@ -103,22 +103,15 @@ export function renderProjectionDecl( ): string { const { dialect, columnNamingStrategy, timestampMode = "string", allowlists = true, ctx, includeViewDecl = true, names } = opts; - // ADR-0044/#228 — resolve a projection field's `@objectRef` to the value object's - // EMITTED name + module TOGETHER (lock-step): bare when unique in the run, - // package-qualified on a cross-package short-name collision, so the projection's - // VO import matches the entity's. Layout/package/extStyle-aware when a render - // context is present, else a flat same-dir import (zodFieldExpr's fallback). + // A projection field's `@objectRef`: the bound value object's import, under its local name, + // so the projection's VO import matches the entity's. Layout/package/extStyle-aware when a + // render context is present, else a flat same-dir import (zodFieldExpr's fallback). const projectionPkg = effectivePackage(projection); - const voRef = (field: MetaField): { name: string; module: string } => { + const voRef = (field: MetaField, suffix: string, typeOnly: boolean): Import => { + if (ctx) return valueObjectFieldImport(ctx, field, projectionPkg, suffix, typeOnly); const ref = field.attr(FIELD_ATTR_OBJECT_REF); - const rawRef = typeof ref === "string" ? ref : ""; - const name = ctx - ? ctx.resolveValueObjectName(field) - : stripPackage(rawRef); - const module = ctx - ? valueObjectModuleSpecifier(name, ctx.packageOf, projectionPkg, ctx.outputLayout, ctx.extStyle) - : `./${name}.js`; - return { name, module }; + const name = stripPackage(typeof ref === "string" ? ref : ""); + return imp(`${typeOnly ? "t:" : ""}${name}${suffix}@./${name}.js`); }; const z = imp("z@zod"); diff --git a/examples/showcase/codegen/templates/view-decl.ts b/examples/showcase/codegen/templates/view-decl.ts index eec5e9ed44..9770bc091d 100644 --- a/examples/showcase/codegen/templates/view-decl.ts +++ b/examples/showcase/codegen/templates/view-decl.ts @@ -7,7 +7,7 @@ // attempt DDL (the SQL view is created/owned by migrate-ts). Both hosts emit the // SAME declaration shape, so it lives here once (extracted from projection-decl). -import { code, imp, joinCode, type Code } from "@metaobjectsdev/codegen-ts/engine"; +import { code, imp, joinCode, type Code, type Import } from "@metaobjectsdev/codegen-ts/engine"; import { dialectModule } from "@metaobjectsdev/codegen-ts/engine"; import type { Dialect } from "@metaobjectsdev/codegen-ts/engine"; import { @@ -35,14 +35,12 @@ export interface ViewDeclOpts { */ readonly declaredEnumIntCodecs?: ReadonlySet; /** - * ADR-0044/#228 — resolve a `field.object` / `field.map`'s `@objectRef` to the - * value object's EMITTED name (bare when unique in the run, package-qualified on - * a cross-package short-name collision) AND its import module, TOGETHER, so the - * imported symbol and its module can never diverge (a bare `Note` symbol pointing - * at an `./AcmeAlphaNote.js` module, or vice-versa). Callers build this from - * `RenderContext.resolveValueObjectName` + `valueObjectModuleSpecifier`. + * The import of `` for a `field.object` / `field.map`'s `@objectRef` (the + * interface with `suffix` "", the Zod schema with "InsertSchema"): the bound value object's + * module, under its local name, so the symbol and its module can never diverge. Callers + * build this from `valueObjectFieldImport`. */ - readonly voRef: (field: MetaField) => { name: string; module: string }; + readonly voRef: (field: MetaField, suffix: string, typeOnly: boolean) => Import; /** * Field names of the owning object's PRIMARY identity (see * `primaryIdentityFieldNames` in zod-validators). A PK column sits on the FROM @@ -135,15 +133,13 @@ function viewColumnLine( dollarType = `.$type<${dtr.tsType}${dtr.array ? "[]" : ""}>()`; } else if (dtr?.kind === "objectRef") { // #228 — emitted name + module resolved together (lock-step) from the field's ref. - const vo = opts.voRef(f); - const voTypeSym = imp(`t:${vo.name}@${vo.module}`); + const voTypeSym = opts.voRef(f, "", true); dollarType = dtr.array ? code`.$type<${voTypeSym}[]>()` : code`.$type<${voTypeSym}>()`; } else if (dtr?.kind === "map") { if ("scalar" in dtr.value) { dollarType = `.$type>()`; } else { - const vo = opts.voRef(f); - dollarType = code`.$type>()`; + dollarType = code`.$type>()`; } } // A6 — reference the constant whenever the artifact is in the run AND carries this @@ -241,8 +237,7 @@ export function renderViewReadZodObject(fields: readonly MetaField[], opts: View if (hasObjectRef) { // #228 — the InsertSchema symbol + its module resolved together from the // field's ref, so a cross-package collision qualifies both consistently. - const vo = opts.voRef(f); - const schemaSym = imp(`${vo.name}InsertSchema@${vo.module}`); + const schemaSym = opts.voRef(f, "InsertSchema", false); const base = f.resolvedIsArray() ? code`${z}.array(${schemaSym})` : code`${schemaSym}`; return code` ${f.name}: ${base}${nullable}`; } diff --git a/examples/showcase/codegen/templates/zod-validators.ts b/examples/showcase/codegen/templates/zod-validators.ts index 2e421a0819..3624dd7db3 100644 --- a/examples/showcase/codegen/templates/zod-validators.ts +++ b/examples/showcase/codegen/templates/zod-validators.ts @@ -57,7 +57,7 @@ import { sharedEnumForField } from "@metaobjectsdev/codegen-ts/engine"; import { sharedEnumImportSpecifier } from "@metaobjectsdev/codegen-ts/engine"; import { sharedEnumZodConstName } from "./enums-file.js"; import type { RenderContext } from "@metaobjectsdev/codegen-ts/engine"; -import { valueObjectModuleSpecifier } from "@metaobjectsdev/codegen-ts/engine"; +import { valueObjectFieldImport } from "@metaobjectsdev/codegen-ts/engine"; // FR-035: the SAME required-predicate that drives the Drizzle column's .notNull() // drives the UpdateSchema's .nullable() exclusion — shared so they cannot drift. import { isRequired } from "@metaobjectsdev/codegen-ts/engine"; @@ -976,20 +976,15 @@ function zodFieldExpr( if (field.subType === FIELD_SUBTYPE_OBJECT) { const ref = field.attr(FIELD_ATTR_OBJECT_REF); if (typeof ref === "string" && ref.length > 0) { - // @objectRef may be authored fully-qualified or bare. ADR-0044/#228 — the - // referenced InsertSchema is named by the value object's EMITTED name - // (bare when unique in the run, package-qualified on a cross-package - // short-name collision), resolved package-locally from the FIELD's declaring - // package. The import MODULE is resolved via the shared - // layout/package/extStyle-aware helper (the SAME one the field's TS type + - // Drizzle .$type<> use) so all three agree. Without owner/ctx (bare - // unit-test calls) fall back to the bare name + flat same-dir. - const ownerPkg = (ctx && owner) ? effectivePackage(owner) : undefined; - const refName = (ctx && owner) ? ctx.resolveValueObjectName(field) : stripPackage(ref); - const moduleSpec = (ctx && owner) - ? valueObjectModuleSpecifier(refName, ctx.packageOf, ownerPkg, ctx.outputLayout, ctx.extStyle) - : `./${refName}.js`; - const refImp = imp(`${refName}InsertSchema@${moduleSpec}`); + // @objectRef may be authored fully-qualified or bare. The referenced + // InsertSchema is the bound value object's, imported under its local name + // (aliased when another object shares the short name) through the + // shared layout/package/extStyle-aware helper the field's TS type + Drizzle + // .$type<> use, so all three agree. Without owner/ctx (bare unit-test calls) + // fall back to the bare name + flat same-dir. + const refImp = (ctx && owner) + ? valueObjectFieldImport(ctx, field, effectivePackage(owner), "InsertSchema", false) + : imp(`${stripPackage(ref)}InsertSchema@./${stripPackage(ref)}.js`); let base: Code = code`${refImp}`; if (field.resolvedIsArray()) base = code`z.array(${base})`; return appendValidatorChain(base, field, forceRequired); @@ -1006,12 +1001,9 @@ function zodFieldExpr( if (field.subType === FIELD_SUBTYPE_MAP) { const ref = field.attr(FIELD_ATTR_OBJECT_REF); if (typeof ref === "string" && ref.length > 0) { - const ownerPkg = (ctx && owner) ? effectivePackage(owner) : undefined; - const refName = (ctx && owner) ? ctx.resolveValueObjectName(field) : stripPackage(ref); - const moduleSpec = (ctx && owner) - ? valueObjectModuleSpecifier(refName, ctx.packageOf, ownerPkg, ctx.outputLayout, ctx.extStyle) - : `./${refName}.js`; - const refImp = imp(`${refName}InsertSchema@${moduleSpec}`); + const refImp = (ctx && owner) + ? valueObjectFieldImport(ctx, field, effectivePackage(owner), "InsertSchema", false) + : imp(`${stripPackage(ref)}InsertSchema@./${stripPackage(ref)}.js`); return appendValidatorChain(code`z.record(z.string(), ${refImp})`, field, forceRequired); } const vt = field.attr(FIELD_ATTR_VALUE_TYPE); @@ -1087,7 +1079,7 @@ function zodFieldExpr( const shared = sharedEnumForField(field); if (shared !== undefined && !shared.provided) { const constName = sharedEnumZodConstName(shared.name); - const spec = sharedEnumImportSpecifier(ctx, owner?.package); + const spec = sharedEnumImportSpecifier(ctx, owner ? effectivePackage(owner) : undefined); const sharedConst = imp(`${constName}@${spec}`); let base: Code = code`${sharedConst}`; if (field.resolvedIsArray()) base = code`z.array(${base})`; diff --git a/examples/showcase/site-payload.json b/examples/showcase/site-payload.json index c716780b2b..27136c6867 100644 --- a/examples/showcase/site-payload.json +++ b/examples/showcase/site-payload.json @@ -8,7 +8,7 @@ }, "counts": { "fixtures": 510, - "corpora": 38, + "corpora": 39, "baseTypes": 17 }, "snippets": { diff --git a/fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-codegen/references/typescript-document-store.md b/fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-codegen/references/typescript-document-store.md index 31e8f8ab0d..20fb079ce3 100644 --- a/fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-codegen/references/typescript-document-store.md +++ b/fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-codegen/references/typescript-document-store.md @@ -55,7 +55,7 @@ What the repository does, built on the generated contract: // its wire contract (InsertSchema, UpdateSchema, 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 { @@ -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 (`./.js`), in either output layout. + generate: perEntity((obj, ctx) => ({ + path: entityOutputPath(ctx.renderContext?.outputLayout ?? "flat", effectivePackage(obj), `${obj.name}.repository.ts`), + content: render(obj), + })), }; } ``` diff --git a/fixtures/api-contract-conformance/report/schema.mysql.sql b/fixtures/api-contract-conformance/report/schema.mysql.sql index 4d23105b26..eb861ba776 100644 --- a/fixtures/api-contract-conformance/report/schema.mysql.sql +++ b/fixtures/api-contract-conformance/report/schema.mysql.sql @@ -111,7 +111,7 @@ CREATE VIEW `v_sales_by_category` AS MAX(s.`amountCents`) AS `maxCents`, COUNT(CASE WHEN s.`amountCents` >= 10000 THEN s.`id` END) AS `largeSales` FROM `sales` s - INNER JOIN `products` p ON p.`id` = s.`productId` + LEFT OUTER JOIN `products` p ON p.`id` = s.`productId` LEFT OUTER JOIN `categories` c ON c.`id` = p.`categoryId` GROUP BY c.`name`; @@ -121,7 +121,7 @@ CREATE VIEW `v_sales_by_sku` AS COUNT(s.`id`) AS `sales`, CAST(SUM(s.`amountCents`) AS SIGNED) AS `revenueCents` FROM `sales` s - INNER JOIN `products` p ON p.`id` = s.`productId` + LEFT OUTER JOIN `products` p ON p.`id` = s.`productId` GROUP BY p.`sku`; CREATE VIEW `v_product_refunds` AS diff --git a/fixtures/api-contract-conformance/report/schema.postgres.sql b/fixtures/api-contract-conformance/report/schema.postgres.sql index 02bbe59001..be0813f3a0 100644 --- a/fixtures/api-contract-conformance/report/schema.postgres.sql +++ b/fixtures/api-contract-conformance/report/schema.postgres.sql @@ -126,10 +126,10 @@ CREATE VIEW "v_sales_by_category" AS MAX(s."amountCents") AS "maxCents", COUNT(s."id") FILTER (WHERE s."amountCents" >= 10000) AS "largeSales" FROM "sales" s - INNER JOIN "products" p ON p."id" = s."productId" + LEFT OUTER JOIN "products" p ON p."id" = s."productId" LEFT OUTER JOIN "categories" c ON c."id" = p."categoryId" GROUP BY c."name"; -COMMENT ON VIEW "v_sales_by_category" IS 'metaobjects:v1:sha256:02e75adfdefcc1605e134fb92ac35fb2a1cc827d99c47c876e120c11ccbf4b0f'; +COMMENT ON VIEW "v_sales_by_category" IS 'metaobjects:v1:sha256:71901b874d860e44f0ce7d7bbd2d2258fca3b9317f6181872bd15be2dfa74b2a'; CREATE VIEW "v_sales_by_sku" AS SELECT @@ -137,9 +137,9 @@ CREATE VIEW "v_sales_by_sku" AS COUNT(s."id") AS "sales", CAST(SUM(s."amountCents") AS BIGINT) AS "revenueCents" FROM "sales" s - INNER JOIN "products" p ON p."id" = s."productId" + LEFT OUTER JOIN "products" p ON p."id" = s."productId" GROUP BY p."sku"; -COMMENT ON VIEW "v_sales_by_sku" IS 'metaobjects:v1:sha256:921fbbbb5285e6e313e12c1c4bf44427c0a3c5226e86fcd04c95bf23f2fd5379'; +COMMENT ON VIEW "v_sales_by_sku" IS 'metaobjects:v1:sha256:b60ca9c2d26bb2a9edcfd0cad6b52b19731bf0fced4c00cdd30f906399469822'; CREATE VIEW "v_product_refunds" AS SELECT diff --git a/fixtures/api-contract-conformance/report/schema.sqlite.sql b/fixtures/api-contract-conformance/report/schema.sqlite.sql index f79147afa0..7b3c1259eb 100644 --- a/fixtures/api-contract-conformance/report/schema.sqlite.sql +++ b/fixtures/api-contract-conformance/report/schema.sqlite.sql @@ -111,7 +111,7 @@ CREATE VIEW "v_sales_by_category" AS MAX(s."amountCents") AS "maxCents", COUNT(CASE WHEN s."amountCents" >= 10000 THEN s."id" END) AS "largeSales" FROM "sales" s - INNER JOIN "products" p ON p."id" = s."productId" + LEFT OUTER JOIN "products" p ON p."id" = s."productId" LEFT OUTER JOIN "categories" c ON c."id" = p."categoryId" GROUP BY c."name"; @@ -121,7 +121,7 @@ CREATE VIEW "v_sales_by_sku" AS COUNT(s."id") AS "sales", SUM(s."amountCents") AS "revenueCents" FROM "sales" s - INNER JOIN "products" p ON p."id" = s."productId" + LEFT OUTER JOIN "products" p ON p."id" = s."productId" GROUP BY p."sku"; CREATE VIEW "v_product_refunds" AS diff --git a/fixtures/check-constraint-conformance/README.md b/fixtures/check-constraint-conformance/README.md new file mode 100644 index 0000000000..d467d90252 --- /dev/null +++ b/fixtures/check-constraint-conformance/README.md @@ -0,0 +1,34 @@ +# CHECK constraint conformance + +The CHECK constraints `meta migrate` derives from a model, pinned by name and by expression +text, per dialect, with and without `migrate.checks.skipRedundant`. A port that declares CHECKs +in its own generated model must declare exactly these, so one model builds one database whether +`meta migrate` or the port's own migrations create it. + +## Layout + +- `input/meta.checks.json`: the model. `Gadget` carries one of every CHECK source: scalar enums + (string and int-backed), an enum array (no CHECK), `validator.numeric`, `validator.length`, + `validator.regex`, `validator.comparison` (with `@condition`), `validator.requiredWhen`, + `validator.presentIff`, `validator.exactlyOne` and `validator.atLeastOne`, plus explicit + `@constraintName`s. It also has a replica view, so its derived field `band` exists, and + `band` gets no CHECK (nor does the `requiredWhen` that names it). `Parcel` adds an + `origin.passthrough` field (`ownerName`, from `Owner.name`) that carries a length validator: + a derived field is no column, so it gets no CHECK either. +- `expected..json`: `{ "": [{ "name", "expression" }] }` for every table with a + CHECK, in the order `meta migrate` emits them. `postgres`, `sqlite` and `d1` (SQLite and D1 are + identical), and `*.skip-redundant.json` for `migrate.checks.skipRedundant: true`. + +## Runners + +- TypeScript: `server/typescript/packages/migrate-ts/test/check-constraint-conformance.test.ts` + builds the expected schema with `buildExpectedSchema` and compares each file. It is the reference: + `META_WRITE_CHECKS=1 bun test test/check-constraint-conformance.test.ts` (in `migrate-ts`) + rewrites the files after a deliberate change, which is then reviewed by hand. +- C#: `server/csharp/MetaObjects.Codegen.Tests/CheckConstraintConformanceTests.cs` reads the + `HasCheckConstraint` declarations the generated EF context makes and compares them with the + same files. `MetaObjects.IntegrationTests` also creates the schema with `EnsureCreated` on a + live Postgres and checks the constraint names and that a violating row is refused. + +Java, Kotlin and Python declare no CHECK in a generated model (schema comes from `meta migrate`, +ADR-0015), so they do not run it. diff --git a/fixtures/check-constraint-conformance/expected.d1.json b/fixtures/check-constraint-conformance/expected.d1.json new file mode 100644 index 0000000000..610a5ec8f9 --- /dev/null +++ b/fixtures/check-constraint-conformance/expected.d1.json @@ -0,0 +1,74 @@ +{ + "gadgets": [ + { + "name": "gadgets_status_chk", + "expression": "\"status\" IN ('DRAFT', 'LIVE')" + }, + { + "name": "gadgets_level_chk", + "expression": "\"level\" IN (1, 2)" + }, + { + "name": "gadgets_score_numeric_chk", + "expression": "\"score\" >= 1 AND \"score\" <= 5" + }, + { + "name": "gadgets_floor_numeric_chk", + "expression": "\"floor\" >= 0" + }, + { + "name": "gadgets_code_length_chk", + "expression": "length(\"code\") >= 2 AND length(\"code\") <= 20" + }, + { + "name": "gadgets_label_length_chk", + "expression": "length(\"label\") >= 0 AND length(\"label\") <= 30" + }, + { + "name": "gadgets_channel_chk", + "expression": "\"channel\" IN ('EMAIL', 'SMS')" + }, + { + "name": "gadgets_channel_length_chk", + "expression": "length(\"channel\") >= 1 AND length(\"channel\") <= 5" + }, + { + "name": "gadgets_ref_fits", + "expression": "length(\"ref\") <= 10" + }, + { + "name": "gadgets_starts_at_cmp_chk", + "expression": "\"starts_at\" <= \"ends_at\"" + }, + { + "name": "gadgets_ends_at_cmp_chk", + "expression": "((\"status\" <> 'LIVE') OR (\"level\" IS NULL)) OR (\"ends_at\" > \"starts_at\")" + }, + { + "name": "gadgets_notes_reqwhen_chk", + "expression": "(\"kind\" IS NOT 'custom') OR (\"notes\" IS NOT NULL)" + }, + { + "name": "gadgets_reason_reqwhen_chk", + "expression": "(\"timeout\" IS NOT 5400000000) OR (\"reason\" IS NOT NULL)" + }, + { + "name": "gadgets_shipped_at_presentiff_chk", + "expression": "(\"shipped_at\" IS NOT NULL) = (\"shipped\" IS 1)" + }, + { + "name": "gadgets_email_exactlyone_chk", + "expression": "((\"email\" IS NOT NULL) + (\"phone\" IS NOT NULL)) = 1" + }, + { + "name": "gadgets_phone_atleastone_chk", + "expression": "(\"level\" <> 2) OR (\"phone\" IS NOT NULL OR \"fax\" IS NOT NULL)" + } + ], + "parcels": [ + { + "name": "parcels_label_length_chk", + "expression": "length(\"label\") >= 1 AND length(\"label\") <= 20" + } + ] +} diff --git a/fixtures/check-constraint-conformance/expected.postgres.json b/fixtures/check-constraint-conformance/expected.postgres.json new file mode 100644 index 0000000000..69ed35e209 --- /dev/null +++ b/fixtures/check-constraint-conformance/expected.postgres.json @@ -0,0 +1,78 @@ +{ + "gadgets": [ + { + "name": "gadgets_status_chk", + "expression": "\"status\" IN ('DRAFT', 'LIVE')" + }, + { + "name": "gadgets_level_chk", + "expression": "\"level\" IN (1, 2)" + }, + { + "name": "gadgets_score_numeric_chk", + "expression": "\"score\" >= 1 AND \"score\" <= 5" + }, + { + "name": "gadgets_floor_numeric_chk", + "expression": "\"floor\" >= 0" + }, + { + "name": "gadgets_code_length_chk", + "expression": "length(\"code\") >= 2 AND length(\"code\") <= 20" + }, + { + "name": "gadgets_label_length_chk", + "expression": "length(\"label\") >= 0 AND length(\"label\") <= 30" + }, + { + "name": "gadgets_sku_shape", + "expression": "\"sku\" ~ '^[A-Z]{3}-''\\d+$'" + }, + { + "name": "gadgets_channel_chk", + "expression": "\"channel\" IN ('EMAIL', 'SMS')" + }, + { + "name": "gadgets_channel_length_chk", + "expression": "length(\"channel\") >= 1 AND length(\"channel\") <= 5" + }, + { + "name": "gadgets_ref_fits", + "expression": "length(\"ref\") <= 10" + }, + { + "name": "gadgets_starts_at_cmp_chk", + "expression": "\"starts_at\" <= \"ends_at\"" + }, + { + "name": "gadgets_ends_at_cmp_chk", + "expression": "((\"status\" <> 'LIVE') OR (\"level\" IS NULL)) OR (\"ends_at\" > \"starts_at\")" + }, + { + "name": "gadgets_notes_reqwhen_chk", + "expression": "(\"kind\" IS DISTINCT FROM 'custom') OR (\"notes\" IS NOT NULL)" + }, + { + "name": "gadgets_reason_reqwhen_chk", + "expression": "(\"timeout\" IS DISTINCT FROM '01:30:00') OR (\"reason\" IS NOT NULL)" + }, + { + "name": "gadgets_shipped_at_presentiff_chk", + "expression": "(\"shipped_at\" IS NOT NULL) = (\"shipped\" IS NOT DISTINCT FROM TRUE)" + }, + { + "name": "gadgets_email_exactlyone_chk", + "expression": "num_nonnulls(\"email\", \"phone\") = 1" + }, + { + "name": "gadgets_phone_atleastone_chk", + "expression": "(\"level\" <> 2) OR (\"phone\" IS NOT NULL OR \"fax\" IS NOT NULL)" + } + ], + "parcels": [ + { + "name": "parcels_label_length_chk", + "expression": "length(\"label\") >= 1 AND length(\"label\") <= 20" + } + ] +} diff --git a/fixtures/check-constraint-conformance/expected.postgres.skip-redundant.json b/fixtures/check-constraint-conformance/expected.postgres.skip-redundant.json new file mode 100644 index 0000000000..86ccaa2a9d --- /dev/null +++ b/fixtures/check-constraint-conformance/expected.postgres.skip-redundant.json @@ -0,0 +1,78 @@ +{ + "gadgets": [ + { + "name": "gadgets_status_chk", + "expression": "\"status\" IN ('DRAFT', 'LIVE')" + }, + { + "name": "gadgets_level_chk", + "expression": "\"level\" IN (1, 2)" + }, + { + "name": "gadgets_score_numeric_chk", + "expression": "\"score\" >= 1 AND \"score\" <= 5" + }, + { + "name": "gadgets_floor_numeric_chk", + "expression": "\"floor\" >= 0" + }, + { + "name": "gadgets_code_length_chk", + "expression": "length(\"code\") >= 2" + }, + { + "name": "gadgets_label_length_chk", + "expression": "length(\"label\") <= 30" + }, + { + "name": "gadgets_sku_shape", + "expression": "\"sku\" ~ '^[A-Z]{3}-''\\d+$'" + }, + { + "name": "gadgets_channel_chk", + "expression": "\"channel\" IN ('EMAIL', 'SMS')" + }, + { + "name": "gadgets_channel_length_chk", + "expression": "length(\"channel\") >= 1 AND length(\"channel\") <= 5" + }, + { + "name": "gadgets_ref_fits", + "expression": "length(\"ref\") <= 10" + }, + { + "name": "gadgets_starts_at_cmp_chk", + "expression": "\"starts_at\" <= \"ends_at\"" + }, + { + "name": "gadgets_ends_at_cmp_chk", + "expression": "((\"status\" <> 'LIVE') OR (\"level\" IS NULL)) OR (\"ends_at\" > \"starts_at\")" + }, + { + "name": "gadgets_notes_reqwhen_chk", + "expression": "(\"kind\" IS DISTINCT FROM 'custom') OR (\"notes\" IS NOT NULL)" + }, + { + "name": "gadgets_reason_reqwhen_chk", + "expression": "(\"timeout\" IS DISTINCT FROM '01:30:00') OR (\"reason\" IS NOT NULL)" + }, + { + "name": "gadgets_shipped_at_presentiff_chk", + "expression": "(\"shipped_at\" IS NOT NULL) = (\"shipped\" IS NOT DISTINCT FROM TRUE)" + }, + { + "name": "gadgets_email_exactlyone_chk", + "expression": "num_nonnulls(\"email\", \"phone\") = 1" + }, + { + "name": "gadgets_phone_atleastone_chk", + "expression": "(\"level\" <> 2) OR (\"phone\" IS NOT NULL OR \"fax\" IS NOT NULL)" + } + ], + "parcels": [ + { + "name": "parcels_label_length_chk", + "expression": "length(\"label\") >= 1" + } + ] +} diff --git a/fixtures/check-constraint-conformance/expected.sqlite.json b/fixtures/check-constraint-conformance/expected.sqlite.json new file mode 100644 index 0000000000..610a5ec8f9 --- /dev/null +++ b/fixtures/check-constraint-conformance/expected.sqlite.json @@ -0,0 +1,74 @@ +{ + "gadgets": [ + { + "name": "gadgets_status_chk", + "expression": "\"status\" IN ('DRAFT', 'LIVE')" + }, + { + "name": "gadgets_level_chk", + "expression": "\"level\" IN (1, 2)" + }, + { + "name": "gadgets_score_numeric_chk", + "expression": "\"score\" >= 1 AND \"score\" <= 5" + }, + { + "name": "gadgets_floor_numeric_chk", + "expression": "\"floor\" >= 0" + }, + { + "name": "gadgets_code_length_chk", + "expression": "length(\"code\") >= 2 AND length(\"code\") <= 20" + }, + { + "name": "gadgets_label_length_chk", + "expression": "length(\"label\") >= 0 AND length(\"label\") <= 30" + }, + { + "name": "gadgets_channel_chk", + "expression": "\"channel\" IN ('EMAIL', 'SMS')" + }, + { + "name": "gadgets_channel_length_chk", + "expression": "length(\"channel\") >= 1 AND length(\"channel\") <= 5" + }, + { + "name": "gadgets_ref_fits", + "expression": "length(\"ref\") <= 10" + }, + { + "name": "gadgets_starts_at_cmp_chk", + "expression": "\"starts_at\" <= \"ends_at\"" + }, + { + "name": "gadgets_ends_at_cmp_chk", + "expression": "((\"status\" <> 'LIVE') OR (\"level\" IS NULL)) OR (\"ends_at\" > \"starts_at\")" + }, + { + "name": "gadgets_notes_reqwhen_chk", + "expression": "(\"kind\" IS NOT 'custom') OR (\"notes\" IS NOT NULL)" + }, + { + "name": "gadgets_reason_reqwhen_chk", + "expression": "(\"timeout\" IS NOT 5400000000) OR (\"reason\" IS NOT NULL)" + }, + { + "name": "gadgets_shipped_at_presentiff_chk", + "expression": "(\"shipped_at\" IS NOT NULL) = (\"shipped\" IS 1)" + }, + { + "name": "gadgets_email_exactlyone_chk", + "expression": "((\"email\" IS NOT NULL) + (\"phone\" IS NOT NULL)) = 1" + }, + { + "name": "gadgets_phone_atleastone_chk", + "expression": "(\"level\" <> 2) OR (\"phone\" IS NOT NULL OR \"fax\" IS NOT NULL)" + } + ], + "parcels": [ + { + "name": "parcels_label_length_chk", + "expression": "length(\"label\") >= 1 AND length(\"label\") <= 20" + } + ] +} diff --git a/fixtures/check-constraint-conformance/expected.sqlite.skip-redundant.json b/fixtures/check-constraint-conformance/expected.sqlite.skip-redundant.json new file mode 100644 index 0000000000..9ff57adba4 --- /dev/null +++ b/fixtures/check-constraint-conformance/expected.sqlite.skip-redundant.json @@ -0,0 +1,74 @@ +{ + "gadgets": [ + { + "name": "gadgets_status_chk", + "expression": "\"status\" IN ('DRAFT', 'LIVE')" + }, + { + "name": "gadgets_level_chk", + "expression": "\"level\" IN (1, 2)" + }, + { + "name": "gadgets_score_numeric_chk", + "expression": "\"score\" >= 1 AND \"score\" <= 5" + }, + { + "name": "gadgets_floor_numeric_chk", + "expression": "\"floor\" >= 0" + }, + { + "name": "gadgets_code_length_chk", + "expression": "length(\"code\") >= 2 AND length(\"code\") <= 20" + }, + { + "name": "gadgets_label_length_chk", + "expression": "length(\"label\") <= 30" + }, + { + "name": "gadgets_channel_chk", + "expression": "\"channel\" IN ('EMAIL', 'SMS')" + }, + { + "name": "gadgets_channel_length_chk", + "expression": "length(\"channel\") >= 1 AND length(\"channel\") <= 5" + }, + { + "name": "gadgets_ref_fits", + "expression": "length(\"ref\") <= 10" + }, + { + "name": "gadgets_starts_at_cmp_chk", + "expression": "\"starts_at\" <= \"ends_at\"" + }, + { + "name": "gadgets_ends_at_cmp_chk", + "expression": "((\"status\" <> 'LIVE') OR (\"level\" IS NULL)) OR (\"ends_at\" > \"starts_at\")" + }, + { + "name": "gadgets_notes_reqwhen_chk", + "expression": "(\"kind\" IS NOT 'custom') OR (\"notes\" IS NOT NULL)" + }, + { + "name": "gadgets_reason_reqwhen_chk", + "expression": "(\"timeout\" IS NOT 5400000000) OR (\"reason\" IS NOT NULL)" + }, + { + "name": "gadgets_shipped_at_presentiff_chk", + "expression": "(\"shipped_at\" IS NOT NULL) = (\"shipped\" IS 1)" + }, + { + "name": "gadgets_email_exactlyone_chk", + "expression": "((\"email\" IS NOT NULL) + (\"phone\" IS NOT NULL)) = 1" + }, + { + "name": "gadgets_phone_atleastone_chk", + "expression": "(\"level\" <> 2) OR (\"phone\" IS NOT NULL OR \"fax\" IS NOT NULL)" + } + ], + "parcels": [ + { + "name": "parcels_label_length_chk", + "expression": "length(\"label\") >= 1 AND length(\"label\") <= 20" + } + ] +} diff --git a/fixtures/check-constraint-conformance/input/meta.checks.json b/fixtures/check-constraint-conformance/input/meta.checks.json new file mode 100644 index 0000000000..cac7994440 --- /dev/null +++ b/fixtures/check-constraint-conformance/input/meta.checks.json @@ -0,0 +1,84 @@ +{ + "metadata.root": { + "package": "acme::checks", + "children": [ + { + "object.entity": { + "name": "Gadget", + "children": [ + { "source.rdb": { "@table": "gadgets" } }, + { "source.rdb": { "@role": "replica", "@kind": "view", "@table": "v_gadgets" } }, + { "field.long": { "name": "id" } }, + { "field.enum": { "name": "status", "@values": ["DRAFT", "LIVE"] } }, + { "field.enum": { "name": "level", "@values": ["LOW", "HIGH"], "@intValueMap": { "LOW": 1, "HIGH": 2 } } }, + { "field.enum": { "name": "tags", "isArray": true, "@values": ["A", "B"] } }, + { "field.string": { "name": "kind", "@required": true } }, + { "field.int": { "name": "score", "children": [ { "validator.numeric": { "@min": 1, "@max": 5 } } ] } }, + { "field.int": { "name": "floor", "children": [ { "validator.numeric": { "@min": 0 } } ] } }, + { "field.string": { "name": "code", "@maxLength": 10, "children": [ { "validator.length": { "@min": 2, "@max": 20 } } ] } }, + { "field.string": { "name": "label", "@maxLength": 40, "children": [ { "validator.length": { "@min": 0, "@max": 30 } } ] } }, + { "field.string": { "name": "sku", "children": [ { "validator.regex": { "@pattern": "^[A-Z]{3}-'\\d+$", "@constraintName": "gadgets_sku_shape" } } ] } }, + { "field.string": { "name": "notes" } }, + { "field.boolean": { "name": "shipped" } }, + { "field.timestamp": { "name": "shippedAt" } }, + { "field.timestamp": { "name": "startsAt" } }, + { "field.timestamp": { "name": "endsAt" } }, + { "field.duration": { "name": "timeout" } }, + { "field.string": { "name": "reason" } }, + { "field.string": { "name": "email" } }, + { "field.string": { "name": "phone" } }, + { "field.string": { "name": "fax" } }, + { "field.enum": { "name": "channel", "@values": ["EMAIL", "SMS"], "children": [ { "validator.length": { "@min": 1, "@max": 5 } } ] } }, + { "field.string": { "name": "ref", "@maxLength": 10, "children": [ { "validator.length": { "@max": 10, "@constraintName": "gadgets_ref_fits" } } ] } }, + { "field.string": { "name": "band", "children": [ + { "validator.length": { "@max": 4 } }, + { "origin.computed": { "@expr": { "case": [ { "when": { "op": "gte", "left": { "field": "score" }, "right": { "value": 4 } }, "then": { "value": "HIGH" } } ], + "else": { "value": "LOW" } } } } ] } }, + { "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } }, + { "validator.comparison": { "name": "window", "@left": "startsAt", "@op": "lte", "@right": "endsAt" } }, + { "validator.comparison": { "name": "liveWindow", "@left": "endsAt", "@op": "gt", "@right": "startsAt", + "@condition": { "op": "and", "args": [ + { "op": "eq", "left": { "field": "status" }, "right": { "value": "LIVE" } }, + { "op": "isNotNull", "arg": { "field": "level" } } ] } } }, + { "validator.requiredWhen": { "name": "customNotes", "@field": "notes", "@when": "kind", "@equals": "custom" } }, + { "validator.requiredWhen": { "name": "slowReason", "@field": "reason", "@when": "timeout", "@equals": "PT1H30M" } }, + { "validator.presentIff": { "name": "shippedAtIff", "@field": "shippedAt", "@when": "shipped", "@equals": true } }, + { "validator.exactlyOne": { "name": "contact", "@fields": ["email", "phone"] } }, + { "validator.atLeastOne": { "name": "anyContact", "@fields": ["phone", "fax"], + "@condition": { "op": "eq", "left": { "field": "level" }, "right": { "value": "HIGH" } } } }, + { "validator.requiredWhen": { "name": "bandFax", "@field": "fax", "@when": "band", "@equals": "HIGH" } } + ] + } + }, + { + "object.entity": { + "name": "Parcel", + "children": [ + { "source.rdb": { "@table": "parcels" } }, + { "source.rdb": { "@role": "replica", "@kind": "view", "@table": "v_parcel_with_owner" } }, + { "field.long": { "name": "id" } }, + { "field.long": { "name": "ownerId", "@required": true } }, + { "field.string": { "name": "label", "@maxLength": 20, "children": [ { "validator.length": { "@min": 1, "@max": 20 } } ] } }, + { "field.string": { "name": "ownerName", "children": [ + { "validator.length": { "@max": 30 } }, + { "origin.passthrough": { "@from": "Owner.name" } } ] } }, + { "relationship.association": { "name": "owner", "@objectRef": "Owner", "@cardinality": "one" } }, + { "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } }, + { "identity.reference": { "name": "ref_owner", "@fields": ["ownerId"], "@references": "Owner" } } + ] + } + }, + { + "object.entity": { + "name": "Owner", + "children": [ + { "source.rdb": { "@table": "owners" } }, + { "field.long": { "name": "id" } }, + { "field.string": { "name": "name" } }, + { "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } } + ] + } + } + ] + } +} diff --git a/fixtures/codegen-conformance/xpkg-value-object-refs/README.md b/fixtures/codegen-conformance/xpkg-value-object-refs/README.md new file mode 100644 index 0000000000..22fd9f53e0 --- /dev/null +++ b/fixtures/codegen-conformance/xpkg-value-object-refs/README.md @@ -0,0 +1,23 @@ +# `xpkg-value-object-refs/` — one file meets two same-named types from two packages + +One metadata input every port's codegen test loads. Nothing is renamed: each +object keeps its short name in its own package, so the generated code that meets two of them +must tell them apart without a rename. + +| Object | Package | Meets | +|---|---|---| +| `Host` (entity) | `acme::app` | `acme::alpha::Note` (`fromAlpha`) and `acme::beta::Note` (`fromBeta`, an array; `byKey`, a map) — the routes' and the entity's value-object types | +| `Summary` (a stored-procedure read model) | `acme::app` | its own arguments object, `acme::alpha::Summary` — the callable wrapper names both | + +A port that writes every package into one namespace or module directory refuses this model +with `ERR_NAME_COLLISION` (two `Note`s, two `Summary`s); the corpus is run with the packages +kept apart — C# by default (each package is its own namespace), TypeScript `outputLayout: "package"` (the default). With them apart, every +generated file that names one of the pair must name it unambiguously: + +- **C#:** every generated file names a type of another namespace `global::`-qualified (a bare + `Note` or `Summary` under `using`s of both namespaces is `CS0104`). +- **TypeScript:** a file that imports both binds each under a package-qualified local alias + (`import type { Note as AcmeAlphaNote }`). + +The C# runner compiles every file except the routes (which need the ASP.NET Core shared +framework, see `CodegenCompileConformanceTests`) and asserts the routes' type references. diff --git a/fixtures/codegen-conformance/xpkg-value-object-refs/input/meta.alpha.json b/fixtures/codegen-conformance/xpkg-value-object-refs/input/meta.alpha.json new file mode 100644 index 0000000000..84d900b394 --- /dev/null +++ b/fixtures/codegen-conformance/xpkg-value-object-refs/input/meta.alpha.json @@ -0,0 +1,9 @@ +{ + "metadata.root": { + "package": "acme::alpha", + "children": [ + { "object.value": { "name": "Note", "children": [{ "field.string": { "name": "alphaText", "@required": true } }] } }, + { "object.value": { "name": "Summary", "children": [{ "field.long": { "name": "minId" } }] } } + ] + } +} diff --git a/fixtures/codegen-conformance/xpkg-value-object-refs/input/meta.app.json b/fixtures/codegen-conformance/xpkg-value-object-refs/input/meta.app.json new file mode 100644 index 0000000000..8d08ac7ac2 --- /dev/null +++ b/fixtures/codegen-conformance/xpkg-value-object-refs/input/meta.app.json @@ -0,0 +1,76 @@ +{ + "metadata.root": { + "package": "acme::app", + "children": [ + { + "object.entity": { + "name": "Host", + "children": [ + { + "source.rdb": { + "@table": "hosts" + } + }, + { + "field.long": { + "name": "id" + } + }, + { + "field.object": { + "name": "fromAlpha", + "@objectRef": "acme::alpha::Note", + "@storage": "jsonb" + } + }, + { + "field.object": { + "name": "fromBeta", + "@objectRef": "acme::beta::Note", + "@storage": "jsonb", + "isArray": true + } + }, + { + "field.map": { + "name": "byKey", + "@objectRef": "acme::beta::Note" + } + }, + { + "identity.primary": { + "name": "pk", + "@fields": "id", + "@generation": "increment" + } + } + ] + } + }, + { + "object.projection": { + "name": "Summary", + "children": [ + { + "source.rdb": { + "@kind": "storedProc", + "@proc": "fn_summary", + "@parameterRef": "acme::alpha::Summary" + } + }, + { + "field.long": { + "name": "id" + } + }, + { + "field.long": { + "name": "total" + } + } + ] + } + } + ] + } +} diff --git a/fixtures/codegen-conformance/xpkg-value-object-refs/input/meta.beta.json b/fixtures/codegen-conformance/xpkg-value-object-refs/input/meta.beta.json new file mode 100644 index 0000000000..0fa7268d03 --- /dev/null +++ b/fixtures/codegen-conformance/xpkg-value-object-refs/input/meta.beta.json @@ -0,0 +1,8 @@ +{ + "metadata.root": { + "package": "acme::beta", + "children": [ + { "object.value": { "name": "Note", "children": [{ "field.string": { "name": "betaText", "@required": true } }] } } + ] + } +} diff --git a/fixtures/conformance/ERROR-CODES.json b/fixtures/conformance/ERROR-CODES.json index 60e4bd240c..eda6d07de6 100644 --- a/fixtures/conformance/ERROR-CODES.json +++ b/fixtures/conformance/ERROR-CODES.json @@ -44,8 +44,8 @@ "ERR_INVALID_RELATIONSHIP": "FR-017: a M:N relationship's slim vocabulary is invalid — @through does not resolve to a junction declaring two identity.reference children (ADR-0042: @through resolves package-locally when bare, exactly when FQN — a bare cross-package @through no longer binds elsewhere), @sourceRefField does not match one of them, or a M:N-only attr (@through/@sourceRefField/@symmetric) is set on a non-M:N (1:N / @cardinality:one) relationship; OR a relationship's @objectRef does not resolve to any object in the loaded tree (a dangling target).", "ERR_INVALID_REFERENCE": "An identity.reference @references names an FK target object that does not resolve to any object in the loaded tree (a dangling cross-reference between metadata).", "ERR_VAR_NOT_ON_PAYLOAD": "Build-time verify: a template variable references a field the (contextual) payload view-object does not declare.", - "ERR_PAYLOAD_NAME_COLLISION": "Codegen (ADR-0044): two distinct value-object FQNs in one payload artifact's reference closure derive the same emitted payload record name even after package-qualification — rename one value-object or move it to a package that derives a distinct name.", - "ERR_COLLECTION_NAME_COLLISION": "Codegen: two distinct entities/projections in one generation run pluralize to the same API-surface collection name (REST path, generated hook/query/finder/list names, DbSet/collection variable name) — rename one entity so its pluralized name is distinct.", + "ERR_PAYLOAD_NAME_COLLISION": "Codegen (ADR-0044): no port raises it since 1.3.0, because a value object is never renamed (ADR-0044 Amendment 1, ADR-0056 Amendment 2); a short-name clash is the port-local ERR_NAME_COLLISION instead. Kept in the ledger so code that matches on it still compiles. Before 1.3.0: two distinct value-object FQNs in one payload artifact's reference closure derived the same emitted payload record name even after package-qualification.", + "ERR_COLLECTION_NAME_COLLISION": "Codegen: two distinct entities/projections in one generation run take the same API-surface collection name (REST path, generated hook/query/finder/list names, DbSet/collection variable name), after `@collectionName` and the `naming.collections` pluralizer apply — set `@collectionName` on one, or rename it, so the two differ.", "ERR_PARTIAL_UNRESOLVED": "Build-time verify: a template partial ({{> group/source}}) does not resolve in the configured provider.", "ERR_REQUIRED_SLOT_UNUSED": "Build-time verify (warning): a template's declared @requiredSlots slot is never referenced by the template text.", "ERR_OUTPUT_TAG_MISSING": "Build-time verify: a template declares @requiredTags but its text (including provider-resolved partials) omits a required output tag's opening () form. path = the tag name.", diff --git a/fixtures/generator-registry-conformance/registry.json b/fixtures/generator-registry-conformance/registry.json index 3a32d6ac4b..f01caa68ef 100644 --- a/fixtures/generator-registry-conformance/registry.json +++ b/fixtures/generator-registry-conformance/registry.json @@ -373,6 +373,7 @@ "codegen-ts/src/metaobjects-config.ts", "codegen-ts/src/names.ts", "codegen-ts/src/naming.ts", + "codegen-ts/src/naming/name-claims.ts", "codegen-ts/src/owned-runtime.ts", "codegen-ts/src/pk-resolver.ts", "codegen-ts/src/projection/build-projection-views.ts", @@ -400,11 +401,14 @@ "codegenPackages": ["MetaObjects.Codegen.**"], "engine": [ "MetaObjects.Codegen.CSharpNaming", + "MetaObjects.Codegen.DesignTimeServicesReferences", "MetaObjects.Codegen.EmittedFile", "MetaObjects.Codegen.FieldNames", "MetaObjects.Codegen.GenConfig", "MetaObjects.Codegen.GenContext", "MetaObjects.Codegen.GeneratorApplicability", + "MetaObjects.Codegen.Generators.CheckConstraint", + "MetaObjects.Codegen.Generators.CheckConstraints", "MetaObjects.Codegen.Generators.FindInbound", "MetaObjects.Codegen.Generators.InboundShape", "MetaObjects.Codegen.Generators.TphPlan", @@ -414,7 +418,10 @@ "MetaObjects.Codegen.IRequirementTestRenderer", "MetaObjects.Codegen.InstanceArtifacts", "MetaObjects.Codegen.KeyNames", + "MetaObjects.Codegen.NameClaims", "MetaObjects.Codegen.ObjectNames", + "MetaObjects.Codegen.OutputLayout", + "MetaObjects.Codegen.OutputPaths", "MetaObjects.Codegen.PackageBindingResolver", "MetaObjects.Codegen.PerEntityGenerator", "MetaObjects.Codegen.RenderedTest", @@ -510,8 +517,10 @@ "metaobjects.codegen.generator_registry", "metaobjects.codegen.generators.find_inbound", "metaobjects.codegen.generators.tph_plan", + "metaobjects.codegen.import_path", "metaobjects.codegen.instance_artifacts", "metaobjects.codegen.model_walk", + "metaobjects.codegen.name_claims", "metaobjects.codegen.project_config", "metaobjects.codegen.requirement_hooks", "metaobjects.codegen.requirement_walk", diff --git a/fixtures/metamodel-docs/expected/types/object.md b/fixtures/metamodel-docs/expected/types/object.md index 36b03043a3..78000a784f 100644 --- a/fixtures/metamodel-docs/expected/types/object.md +++ b/fixtures/metamodel-docs/expected/types/object.md @@ -46,7 +46,7 @@ An object that owns its data: own identity, writable sources, and lifecycle. The | Attribute | Type | Required | Default | Allowed values | Provider | Description | | --- | --- | --- | --- | --- | --- | --- | -| `@collectionName` | string | no | | | metaobjects-core-types | The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own). | +| `@collectionName` | string | no | | | metaobjects-core-types | The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own). | | `@discriminator` | string | no | | | metaobjects-core-types | FR-014: names the field on this entity (resolvable via extends:) that holds the subtype-discriminator value. Subtypes of this entity declare @discriminatorValue to bind their rows to a discriminator value. The discriminator field itself is an ordinary field declaration (typically field.enum or field.int / field.string). | | `@discriminatorValue` | string | no | | | metaobjects-core-types | FR-014: on a subtype of an entity with @discriminator — the value that identifies rows of this subtype in the shared discriminator field. Wire form is always a string; the underlying field's subtype (enum / int / string) controls codegen + storage coercion. Required on every concrete subtype of a discriminated entity. | | `@object` | string | no | | | metaobjects-core-types | The native class an object binds to (ADR-0001), in place of its default runtime class: on the JVM, a fully-qualified class name. Cross-port vocabulary only Java implements so far; every port loads and type-checks it, and the others do not act on it yet. | @@ -80,7 +80,7 @@ A derived read-only representation of entities. Its fields are extends-bound / o | Attribute | Type | Required | Default | Allowed values | Provider | Description | | --- | --- | --- | --- | --- | --- | --- | -| `@collectionName` | string | no | | | metaobjects-core-types | The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own). | +| `@collectionName` | string | no | | | metaobjects-core-types | The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own). | | `@filter` | filter | no | | | metaobjects-core-types | Optional row-scope predicate (a portable attr.filter object: eq/ne/gt/gte/lt/lte/like/in/isNull with and/or, desugared to { field: { op: value } } at parse time) selecting which rows the view returns — lowered to an outer SQL WHERE. A key names one of the projection's own fields, else a field of its base entity the view need not output, else a PATH of to-one hops (identity.reference or @cardinality one relationship names) from the base then a field of the entity reached ('orderId.customerId.isActive'), joined but not output. A reached entity field may itself be derived (entity-derived: an origin.computed or origin.first declared on the entity, inlined where the filter reaches it). An aggregate-derived field is not addressable (fail-closed); a to-many hop is refused. A value may be a relative date ({ now: "", startOf? }) on a date or timestamp field. | | `@object` | string | no | | | metaobjects-core-types | The native class an object binds to (ADR-0001), in place of its default runtime class: on the JVM, a fully-qualified class name. Cross-port vocabulary only Java implements so far; every port loads and type-checks it, and the others do not act on it yet. | | `@objectAdapter` | string | no | | | metaobjects-core-types | JVM-only (ADR-0005): the fully-qualified name of an ObjectAdapter that takes over value access for this object's instances. Every port loads and type-checks it; only Java and Kotlin act on it. | @@ -106,7 +106,7 @@ A declared report (FR-044): a fixed combination of dimensions and measures of ON | Attribute | Type | Required | Default | Allowed values | Provider | Description | | --- | --- | --- | --- | --- | --- | --- | -| `@collectionName` | string | no | | | metaobjects-core-types | The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own). | +| `@collectionName` | string | no | | | metaobjects-core-types | The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own). | | `@dimensions` | string[] | no | | | metaobjects-core-types | Dimension names of @from; a time dimension is written 'name:grain'. Absent means one global row. | | `@filter` | filter | no | | | metaobjects-core-types | Optional row scope over @from's fields; may use relative-date values. | | `@from` | string | yes | | | metaobjects-core-types | The object.entity whose rows the report aggregates. | diff --git a/fixtures/naming-conformance/README.md b/fixtures/naming-conformance/README.md index 2542c818be..50ec72bcf8 100644 --- a/fixtures/naming-conformance/README.md +++ b/fixtures/naming-conformance/README.md @@ -120,10 +120,10 @@ the schema layer (`meta migrate`'s `ERR_DUPLICATE_SQL_NAME`). object is served under, given its name, the `@collectionName` it declares and the project's `naming.collections` pluralizer. With neither, the segment is the rule above (snake_case, then the API pluralizer), unchanged. A declared name, or a configured pluralizer's output, is -snake_cased with an acronym-aware split (`FAQs` -> `faqs`). TypeScript -(`metadata/test/naming.test.ts`) and C# (`MetaObjects.Codegen.Tests/CollectionSegmentTests.cs`) -run it: they are the two ports whose generators read `@collectionName` and `naming.collections` -(the other ports are tracked in #549). +snake_cased with an acronym-aware split (`FAQs` -> `faqs`). Every port runs it: TypeScript +(`metadata/test/naming.test.ts`), C# (`MetaObjects.Codegen.Tests/CollectionSegmentTests.cs`), +Java and Kotlin (`codegen-base` `RouteNamingTest.java`, the one rule both JVM generators read) and +Python (`tests/codegen/test_collection_segments.py`). ## Per-port runner diff --git a/fixtures/naming-conformance/collection-segments.json b/fixtures/naming-conformance/collection-segments.json index f1a9656053..f67d44cec7 100644 --- a/fixtures/naming-conformance/collection-segments.json +++ b/fixtures/naming-conformance/collection-segments.json @@ -1,5 +1,5 @@ { - "_comment": "Cross-port REST collection segments. For each case, `segment` is the REST collection segment the object is served under, given its name, the @collectionName it declares (`collectionName`, absent when none) and the project's `naming.collections` (`pluralizer`, absent when none). With neither, the segment is the rule every port has always served: snake_case the name, then pluralize. A declared name, or a configured pluralizer's output over the name, is snake_cased with an acronym-aware split: a trailing plural `s`/`es` after a capital is a suffix, not a word (`FAQs` -> `faqs`, not `fa_qs`). Run by TypeScript (metadata/test/naming.test.ts) and C# (MetaObjects.Codegen.Tests/CollectionSegmentTests.cs), the two ports whose generators read @collectionName and naming.collections (#549).", + "_comment": "Cross-port REST collection segments. For each case, `segment` is the REST collection segment the object is served under, given its name, the @collectionName it declares (`collectionName`, absent when none) and the project's `naming.collections` (`pluralizer`, absent when none). With neither, the segment is the rule every port has always served: snake_case the name, then pluralize. A declared name, or a configured pluralizer's output over the name, is snake_cased with an acronym-aware split: a trailing plural `s`/`es` after a capital is a suffix, not a word (`FAQs` -> `faqs`, not `fa_qs`). Run by TypeScript (metadata/test/naming.test.ts), C# (MetaObjects.Codegen.Tests/CollectionSegmentTests.cs), Java (codegen-base RouteNamingTest, whose rule the Kotlin generators share) and Python (tests/codegen/test_collection_segments.py): every port's generators read @collectionName and naming.collections.", "cases": [ { "name": "Author", "segment": "authors" }, { "name": "PostCategory", "segment": "post_categories" }, diff --git a/fixtures/persistence-conformance/canonical/schema.mysql.sql b/fixtures/persistence-conformance/canonical/schema.mysql.sql index f1eb4337ea..b0126bc272 100644 --- a/fixtures/persistence-conformance/canonical/schema.mysql.sql +++ b/fixtures/persistence-conformance/canonical/schema.mysql.sql @@ -127,7 +127,7 @@ CREATE VIEW `v_program_minutes` AS MAX(w.`durationMinutes`) AS `maxMinutes`, COUNT(CASE WHEN w.`durationMinutes` >= 60 THEN w.`id` END) / NULLIF(COUNT(w.`id`), 0) AS `longShare` FROM `weeks` w - INNER JOIN `programs` p ON p.`id` = w.`programId` + LEFT OUTER JOIN `programs` p ON p.`id` = w.`programId` GROUP BY w.`programId`, p.`title`; CREATE VIEW `v_fitness_totals` AS @@ -306,7 +306,7 @@ CREATE VIEW `v_week_shapes` AS COUNT(CASE WHEN (w.`durationMinutes` > 30 AND w.`durationMinutes` <= 60) THEN w.`id` END) AS `midWeeks`, CAST(SUM(CASE WHEN (w.`durationMinutes` >= 60 AND w.`label` LIKE 'W%') THEN w.`durationMinutes` END) AS SIGNED) AS `longWMinutes` FROM `weeks` w - INNER JOIN `programs` p ON p.`id` = w.`programId` + LEFT OUTER JOIN `programs` p ON p.`id` = w.`programId` GROUP BY p.`title`; CREATE VIEW `v_sessions_by_program` AS @@ -316,8 +316,8 @@ CREATE VIEW `v_sessions_by_program` AS COUNT(s.`id`) AS `sessions`, CAST(SUM(s.`minutes`) AS SIGNED) AS `sessionMinutes` FROM `sessions` s - INNER JOIN `weeks` w ON w.`id` = s.`weekId` - INNER JOIN `programs` p ON p.`id` = w.`programId` + LEFT OUTER JOIN `weeks` w ON w.`id` = s.`weekId` + LEFT OUTER JOIN `programs` p ON p.`id` = w.`programId` GROUP BY p.`title`, w.`id`; CREATE VIEW `v_program_sessions` AS @@ -354,7 +354,7 @@ CREATE VIEW `v_gadget_events_by_label` AS g0.`gadget_code` AS `gadgetLabel`, COUNT(g.`id`) AS `gadgetEvents` FROM `gadget_events` g - INNER JOIN `gadgets` g0 ON g0.`id` = g.`gadgetId` + LEFT OUTER JOIN `gadgets` g0 ON g0.`id` = g.`gadgetId` GROUP BY g0.`gadget_code`; CREATE VIEW `v_entry_totals` AS diff --git a/fixtures/persistence-conformance/canonical/schema.postgres.sql b/fixtures/persistence-conformance/canonical/schema.postgres.sql index 69674a624c..592c569126 100644 --- a/fixtures/persistence-conformance/canonical/schema.postgres.sql +++ b/fixtures/persistence-conformance/canonical/schema.postgres.sql @@ -245,9 +245,9 @@ CREATE VIEW "v_program_minutes" AS MAX(w."durationMinutes") AS "maxMinutes", CAST(COUNT(w."id") FILTER (WHERE w."durationMinutes" >= 60) AS NUMERIC) / NULLIF(COUNT(w."id"), 0) AS "longShare" FROM "weeks" w - INNER JOIN "programs" p ON p."id" = w."programId" + LEFT OUTER JOIN "programs" p ON p."id" = w."programId" GROUP BY w."programId", p."title"; -COMMENT ON VIEW "v_program_minutes" IS 'metaobjects:v1:sha256:06b54e731e0221acab4b6e0a7cb7f5914662eff39af6ca57031a7df69cbbec93'; +COMMENT ON VIEW "v_program_minutes" IS 'metaobjects:v1:sha256:0efca584388ab2840076b71e68d137d6218b67baa90ff8151a01cb018c503d63'; CREATE VIEW "v_fitness_totals" AS SELECT @@ -442,9 +442,9 @@ CREATE VIEW "v_week_shapes" AS COUNT(w."id") FILTER (WHERE (w."durationMinutes" > 30 AND w."durationMinutes" <= 60)) AS "midWeeks", CAST(SUM(w."durationMinutes") FILTER (WHERE (w."durationMinutes" >= 60 AND w."label" LIKE 'W%')) AS BIGINT) AS "longWMinutes" FROM "weeks" w - INNER JOIN "programs" p ON p."id" = w."programId" + LEFT OUTER JOIN "programs" p ON p."id" = w."programId" GROUP BY p."title"; -COMMENT ON VIEW "v_week_shapes" IS 'metaobjects:v1:sha256:d45ae0c03233df8ba4109d7c45a132e60185a96aaacdefe6e61de445286f6840'; +COMMENT ON VIEW "v_week_shapes" IS 'metaobjects:v1:sha256:14a52bb4c22b9d458efd70d8932533b711d1560a2c8d57efd072787d6ea04312'; CREATE VIEW "v_sessions_by_program" AS SELECT @@ -453,10 +453,10 @@ CREATE VIEW "v_sessions_by_program" AS COUNT(s."id") AS "sessions", CAST(SUM(s."minutes") AS BIGINT) AS "sessionMinutes" FROM "sessions" s - INNER JOIN "weeks" w ON w."id" = s."weekId" - INNER JOIN "programs" p ON p."id" = w."programId" + LEFT OUTER JOIN "weeks" w ON w."id" = s."weekId" + LEFT OUTER JOIN "programs" p ON p."id" = w."programId" GROUP BY p."title", w."id"; -COMMENT ON VIEW "v_sessions_by_program" IS 'metaobjects:v1:sha256:2df2051342861240b2ddc4d2d1cbdab012a4a255f0191c35a863b9cfa5754e14'; +COMMENT ON VIEW "v_sessions_by_program" IS 'metaobjects:v1:sha256:b07c1d3271ccb826c99e73c37d5a49923babc4489f4e613187032d5d1fac2a0d'; CREATE VIEW "v_program_sessions" AS SELECT @@ -495,9 +495,9 @@ CREATE VIEW "v_gadget_events_by_label" AS g0."gadget_code" AS "gadgetLabel", COUNT(g."id") AS "gadgetEvents" FROM "gadget_events" g - INNER JOIN "gadgets" g0 ON g0."id" = g."gadgetId" + LEFT OUTER JOIN "gadgets" g0 ON g0."id" = g."gadgetId" GROUP BY g0."gadget_code"; -COMMENT ON VIEW "v_gadget_events_by_label" IS 'metaobjects:v1:sha256:ce353e347259448fb4055d7b20cb3de6210ce157c6824d3ab2b0b2dba661cc82'; +COMMENT ON VIEW "v_gadget_events_by_label" IS 'metaobjects:v1:sha256:2d9226e9ded3a64712a5ffcb250b58fc03d68f7e8324e434ee2aca778c60cf4c'; CREATE VIEW "v_entry_totals" AS SELECT diff --git a/fixtures/persistence-conformance/canonical/schema.sqlite.sql b/fixtures/persistence-conformance/canonical/schema.sqlite.sql index c66bf32e10..8bf2efa396 100644 --- a/fixtures/persistence-conformance/canonical/schema.sqlite.sql +++ b/fixtures/persistence-conformance/canonical/schema.sqlite.sql @@ -207,7 +207,7 @@ CREATE VIEW "v_program_minutes" AS MAX(w."durationMinutes") AS "maxMinutes", CAST(COUNT(CASE WHEN w."durationMinutes" >= 60 THEN w."id" END) AS REAL) / NULLIF(COUNT(w."id"), 0) AS "longShare" FROM "weeks" w - INNER JOIN "programs" p ON p."id" = w."programId" + LEFT OUTER JOIN "programs" p ON p."id" = w."programId" GROUP BY w."programId", p."title"; CREATE VIEW "v_fitness_totals" AS @@ -386,7 +386,7 @@ CREATE VIEW "v_week_shapes" AS COUNT(CASE WHEN (w."durationMinutes" > 30 AND w."durationMinutes" <= 60) THEN w."id" END) AS "midWeeks", SUM(CASE WHEN (w."durationMinutes" >= 60 AND w."label" LIKE 'W%') THEN w."durationMinutes" END) AS "longWMinutes" FROM "weeks" w - INNER JOIN "programs" p ON p."id" = w."programId" + LEFT OUTER JOIN "programs" p ON p."id" = w."programId" GROUP BY p."title"; CREATE VIEW "v_sessions_by_program" AS @@ -396,8 +396,8 @@ CREATE VIEW "v_sessions_by_program" AS COUNT(s."id") AS "sessions", SUM(s."minutes") AS "sessionMinutes" FROM "sessions" s - INNER JOIN "weeks" w ON w."id" = s."weekId" - INNER JOIN "programs" p ON p."id" = w."programId" + LEFT OUTER JOIN "weeks" w ON w."id" = s."weekId" + LEFT OUTER JOIN "programs" p ON p."id" = w."programId" GROUP BY p."title", w."id"; CREATE VIEW "v_program_sessions" AS @@ -434,7 +434,7 @@ CREATE VIEW "v_gadget_events_by_label" AS g0."gadget_code" AS "gadgetLabel", COUNT(g."id") AS "gadgetEvents" FROM "gadget_events" g - INNER JOIN "gadgets" g0 ON g0."id" = g."gadgetId" + LEFT OUTER JOIN "gadgets" g0 ON g0."id" = g."gadgetId" GROUP BY g0."gadget_code"; CREATE VIEW "v_entry_totals" AS diff --git a/fixtures/persistence-conformance/migrations/sequence-start-change-below-max-id.yaml b/fixtures/persistence-conformance/migrations/sequence-start-change-below-max-id.yaml new file mode 100644 index 0000000000..62c816d3c5 --- /dev/null +++ b/fixtures/persistence-conformance/migrations/sequence-start-change-below-max-id.yaml @@ -0,0 +1,22 @@ +name: sequence-start-change-below-max-id +description: | + An existing table's increment key gains `@sequenceStart: 1000`, but a live row already holds + id 5000 (inserted with an explicit id, so the sequence never handed it out). The counter moves + forward to `max(id) + 1`, not to the start: the start would hand out ids up to 5000 again. + Companion of `sequence-start-change-moves-counter-forward`. + +seed-metadata: ./states/program-v1/ +seed-data: | + INSERT INTO "programs" ("title") VALUES ('Foundations'); + INSERT INTO "programs" ("id", "title") VALUES (5000, 'Imported'); + +target-metadata: ./states/program-seq-v2/ + +expect: + blocked: [] + up-contains: + - 'ALTER SEQUENCE "programs_id_seq" START WITH 1000;' + apply-up-then-query: + sql: SELECT nextval('"programs_id_seq"') AS "next" + rows: + - { next: "5001" } diff --git a/fixtures/persistence-conformance/migrations/sequence-start-change-keeps-counter.yaml b/fixtures/persistence-conformance/migrations/sequence-start-change-keeps-counter.yaml deleted file mode 100644 index f817bf16f5..0000000000 --- a/fixtures/persistence-conformance/migrations/sequence-start-change-keeps-counter.yaml +++ /dev/null @@ -1,25 +0,0 @@ -name: sequence-start-change-keeps-counter -description: | - An existing table's increment key gains `@sequenceStart: 1000`. The migration records the - new start (`ALTER SEQUENCE … START WITH 1000`) and nothing else: it never RESTARTs the - sequence and never moves its current value, because the live rows already hold the ids it - handed out. Every port applies `@sequenceStart` with this one meaning — the start of a - fresh sequence, never a reset of a live one. - - The seed inserts two rows WITHOUT ids, so the sequence itself hands out 1 and 2. After the - up migration the counter still stands at 2 and the next insert takes 3. - -seed-metadata: ./states/program-v1/ -seed-data: | - INSERT INTO "programs" ("title") VALUES ('Foundations'), ('Strength'); - -target-metadata: ./states/program-seq-v2/ - -expect: - blocked: [] - up-contains: - - 'ALTER SEQUENCE "programs_id_seq" START WITH 1000;' - apply-up-then-query: - sql: SELECT nextval('"programs_id_seq"') AS "next" - rows: - - { next: "3" } diff --git a/fixtures/persistence-conformance/migrations/sequence-start-change-moves-counter-forward.yaml b/fixtures/persistence-conformance/migrations/sequence-start-change-moves-counter-forward.yaml new file mode 100644 index 0000000000..b6ade6839b --- /dev/null +++ b/fixtures/persistence-conformance/migrations/sequence-start-change-moves-counter-forward.yaml @@ -0,0 +1,27 @@ +name: sequence-start-change-moves-counter-forward +description: | + An existing table's increment key gains `@sequenceStart: 1000`. The migration records the + new start (`ALTER SEQUENCE … START WITH 1000`) and moves the counter FORWARD to + `GREATEST(1000, max(id) + 1)`, because the next value the sequence would hand out (3) is below + it. It never RESTARTs and never moves a counter back, so no id a live row holds is handed out + again. Every port that changes a live sequence applies `@sequenceStart` with this one meaning, + so a database that gains the start later (a replayed chain) hands out ids from the start on, + as a fresh one does. + + The seed inserts two rows WITHOUT ids, so the sequence itself hands out 1 and 2. After the + up migration the next insert takes 1000. + +seed-metadata: ./states/program-v1/ +seed-data: | + INSERT INTO "programs" ("title") VALUES ('Foundations'), ('Strength'); + +target-metadata: ./states/program-seq-v2/ + +expect: + blocked: [] + up-contains: + - 'ALTER SEQUENCE "programs_id_seq" START WITH 1000;' + apply-up-then-query: + sql: SELECT nextval('"programs_id_seq"') AS "next" + rows: + - { next: "1000" } diff --git a/fixtures/registry-conformance/expected-registry.json b/fixtures/registry-conformance/expected-registry.json index 1e85bfee65..b1f7ab8ea0 100644 --- a/fixtures/registry-conformance/expected-registry.json +++ b/fixtures/registry-conformance/expected-registry.json @@ -3525,11 +3525,7 @@ "valueType": "string", "isArray": false, "required": false, - "implementedIn": [ - "csharp", - "typescript" - ], - "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." + "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." }, { "name": "discriminator", @@ -3659,11 +3655,7 @@ "valueType": "string", "isArray": false, "required": false, - "implementedIn": [ - "csharp", - "typescript" - ], - "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." + "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." }, { "name": "filter", @@ -3750,11 +3742,7 @@ "valueType": "string", "isArray": false, "required": false, - "implementedIn": [ - "csharp", - "typescript" - ], - "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." + "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." }, { "name": "dimensions", diff --git a/fixtures/template-output-render-conformance/README.md b/fixtures/template-output-render-conformance/README.md index 802f77b963..dbd6816630 100644 --- a/fixtures/template-output-render-conformance/README.md +++ b/fixtures/template-output-render-conformance/README.md @@ -147,27 +147,29 @@ for it, in addition to gating the `@objectRef` **resolver** above: it erases `@required` and lets a typo against either real shape type-check. Construct the render-time payload instance from the port's REAL generated value-object types for this fixture. -2. **Naming rule:** a value object's type lives at the value object's own location. - Where that location is a package the language keeps separate (Java, Kotlin), the - package disambiguates and nothing is renamed. Where every value object lands in one - flat namespace or directory (TypeScript's flat layout, C#'s default package - binding, Python's flat generated package), a value object whose short name - collides emits under its package-qualified derived name — PascalCase each - `::`-segment of its package, concatenate, append the bare short name. - TypeScript counts a collision among value objects; C# and Python count it against - every top-level object, because an entity shares their namespace or module - directory. A still-colliding derived name is a hard generator error, - `ERR_PAYLOAD_NAME_COLLISION`. +2. **Naming rule:** a value object's type lives at the value object's own location, and + it is never renamed (ADR-0044 Amendment 1, ADR-0056 Amendment 2). Where that location + is a package the language keeps separate (Java, Kotlin), the package tells the two + apart. Where the port can write one flat namespace or directory, the two are placed + apart by configuration: TypeScript and Python by the package output layout (one + module per package directory), C# by package namespaces (each type in its package's + namespace, references across namespaces written `global::`-qualified). A file that + meets both binds them under package-qualified local aliases (TypeScript + `Note as AcmeAlphaNote`, Python `from ..alpha.Note import Note as AcmeAlphaNote`); the + types themselves keep the name `Note`. Two objects that would still emit one name + into one scope (the flat layout, or one C# namespace) are refused with + `ERR_NAME_COLLISION`, naming both. C# and Python count a clash against every + top-level object, because an entity shares their namespace or module directory. 3. **Expected emitted names for this fixture, per port** (`Digest` itself does not collide and stays bare in every port): | Port | `acme::alpha::Note` | `acme::beta::Note` | |---|---|---| - | TypeScript (`interface`) | `AcmeAlphaNote` | `AcmeBetaNote` | - | C# (POCO) | `AcmeAlphaNote` | `AcmeBetaNote` | + | TypeScript (`interface`, package layout) | `acme/alpha/Note.ts` `Note` | `acme/beta/Note.ts` `Note` | + | C# (POCO, package layout + package namespaces) | `acme/alpha/Note.g.cs` `Acme.Alpha.Note` | `acme/beta/Note.g.cs` `Acme.Beta.Note` | | Java (`record`) | `acme.alpha.Note` | `acme.beta.Note` | | Kotlin (data class) | `acme.alpha.Note` | `acme.beta.Note` | - | Python (Pydantic model, `.py`) | `AcmeAlphaNote` | `AcmeBetaNote` | + | Python (Pydantic model, package layout) | `acme/alpha/Note.py` `Note` | `acme/beta/Note.py` `Note` | The render-output pins above (`"Alpha=AA Beta=BB"`) are UNCHANGED by this contract — the render engine and the build-time verify field-tree resolve against @@ -200,10 +202,10 @@ inbound artifacts named for `DigestPrompt`, not `DigestDoc`. The generated render helper, collision-aware value-object naming, and render output remain identical — see [Cross-package short-name collision](#cross-package-short-name-collision--xpkg-collision-digestdoc) -above for the full contract and expected names (`AcmeAlphaNote`/`AcmeBetaNote` for -TS/C#/Python; `acme.alpha.Note`/`acme.beta.Note` for Java/Kotlin). The inbound tier's -lenient mirrors follow the same names (`AcmeAlphaNoteExtracted` in the flat ports), -keyed by the value object rather than the template (ADR-0056 rule 3). +above for the full contract and expected names (`Note` in its own package in every +port). The inbound tier's lenient mirrors are keyed by the value object rather than the +template (ADR-0056 rule 3): in TypeScript, declarations of one module named by the value +object's local alias (`AcmeAlphaNoteExtracted`). ## Expected build-time drift FAILURE — `drift/` diff --git a/server/csharp/MetaObjects.Cli.Tests/PackageLayoutConfigTests.cs b/server/csharp/MetaObjects.Cli.Tests/PackageLayoutConfigTests.cs new file mode 100644 index 0000000000..09b32bdcf0 --- /dev/null +++ b/server/csharp/MetaObjects.Cli.Tests/PackageLayoutConfigTests.cs @@ -0,0 +1,73 @@ +using MetaObjects.Cli; +using MetaObjects.Codegen; +using MetaObjects.Config; +using MetaObjects.Meta; +using Xunit; + +namespace MetaObjects.Cli.Tests; + +public sealed class PackageLayoutConfigTests : IDisposable +{ + private readonly string _root = Path.Combine(Path.GetTempPath(), "mo-layout-" + Guid.NewGuid().ToString("N")); + + public PackageLayoutConfigTests() => Directory.CreateDirectory(Path.Combine(_root, ".metaobjects")); + public void Dispose() { try { Directory.Delete(_root, true); } catch (IOException) { } } + + private NeutralConfig Read(string json) + { + File.WriteAllText(Path.Combine(_root, ".metaobjects", "config.json"), json); + return NeutralConfig.Read(_root, validateNaming: false)!; + } + + [Fact] + public void Absent_keys_read_as_the_default_layout_and_the_earlier_namespace_rule() + { + var cfg = Read("""{ "schema_version": 1, "csharp": { "namespace": "Acme.Gen" } }"""); + Assert.Equal("flat", cfg.OutputLayout); + Assert.Equal(PackageNamespaceSetting.Off, cfg.PackageNamespaces); + var gen = new GenConfig { OutDir = "/tmp", Namespace = "Acme.Gen" }.WithCSharpLayout(cfg); + Assert.Equal(OutputLayout.Flat, gen.OutputLayout); + Assert.False(gen.PackageNamespacesFromMetadata); + } + + [Fact] + public void The_true_form_binds_each_packaged_type_to_its_package_namespace() + { + var cfg = Read("""{ "schema_version": 1, "csharp": { "namespace": "Acme.Gen", "outputLayout": "package", "packageNamespaces": true } }"""); + var gen = new GenConfig { OutDir = "/tmp", Namespace = "Acme.Gen" }.WithCSharpLayout(cfg); + Assert.Equal(OutputLayout.Package, gen.OutputLayout); + Assert.True(gen.PackageNamespacesFromMetadata); + } + + [Fact] + public void The_map_form_is_an_explicit_package_to_namespace_mapping() + { + var cfg = Read("""{ "schema_version": 1, "csharp": { "packageNamespaces": { "acme::alpha": "Acme.Alpha" } } }"""); + var gen = new GenConfig { OutDir = "/tmp", Namespace = "Acme.Gen" }.WithCSharpLayout(cfg); + Assert.False(gen.PackageNamespacesFromMetadata); + Assert.Equal("Acme.Alpha", gen.PackageNamespaces["acme::alpha"]); + } + + [Theory] + [InlineData("""{ "schema_version": 1, "csharp": { "outputLayout": "tree" } }""")] + [InlineData("""{ "schema_version": 1, "csharp": { "packageNamespaces": "yes" } }""")] + [InlineData("""{ "schema_version": 1, "csharp": { "packageNamespaces": { "acme": 3 } } }""")] + public void A_wrong_shaped_value_is_refused(string json) => + Assert.Throws(() => Read(json)); + + [Fact] + public void Init_writes_the_opt_ins_for_a_new_project_and_leaves_an_existing_config_alone() + { + var fresh = Path.Combine(_root, "fresh"); + Directory.CreateDirectory(fresh); + var lines = InitCommand.Run(fresh); + Assert.Contains(lines, l => l.Contains(".metaobjects/config.json")); + var cfg = NeutralConfig.Read(fresh, validateNaming: false)!; + Assert.Equal("package", cfg.OutputLayout); + Assert.True(cfg.PackageNamespaces.FromMetadata); + + File.WriteAllText(Path.Combine(fresh, ".metaobjects", "config.json"), "{ \"schema_version\": 1 }"); + InitCommand.Run(fresh); + Assert.Equal("{ \"schema_version\": 1 }", File.ReadAllText(Path.Combine(fresh, ".metaobjects", "config.json"))); + } +} diff --git a/server/csharp/MetaObjects.Cli/InitCommand.cs b/server/csharp/MetaObjects.Cli/InitCommand.cs index 3caf2eebc9..1083a08e13 100644 --- a/server/csharp/MetaObjects.Cli/InitCommand.cs +++ b/server/csharp/MetaObjects.Cli/InitCommand.cs @@ -120,6 +120,14 @@ private static string DocsEntry(string root) => (Path.GetFileName(Path.GetFullPath(root).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar)) is { Length: > 0 } n ? n.Replace("\\", "").Replace("\"", "") : "project") + "\" }"; + /// The project config a new project starts with: files written under their metadata + /// package, and each packaged type in its package's namespace. An existing config is the + /// project's and is never edited. + public const string ConfigRel = ".metaobjects/config.json"; + + public const string ConfigJson = + "{\n \"schema_version\": 1,\n \"csharp\": {\n \"outputLayout\": \"package\",\n \"packageNamespaces\": true\n }\n}\n"; + public static IReadOnlyList Run(string root, bool withDocs = false) { var csprojPath = Path.Combine(root, "codegen", "Codegen.csproj"); @@ -130,6 +138,18 @@ public static IReadOnlyList Run(string root, bool withDocs = false) var lines = new List(); foreach (var rel in CodegenScaffold.Files) lines.Add(written.Contains(rel) ? $" wrote {rel}" : $" kept {rel} (already yours)"); + var configPath = Path.Combine(root, ".metaobjects", "config.json"); + if (File.Exists(configPath)) + lines.Add( + $" kept {ConfigRel} (already yours). Add \"csharp\": {{ \"outputLayout\": \"package\", " + + "\"packageNamespaces\": true }} to it to write each file under its metadata package and bind each " + + "packaged type to its package's namespace; without them gen keeps the flat layout."); + else + { + Directory.CreateDirectory(Path.GetDirectoryName(configPath)!); + File.WriteAllText(configPath, ConfigJson); + lines.Add($" wrote {ConfigRel} (outputLayout \"package\", packageNamespaces true)"); + } lines.Add(""); lines.Add( "codegen/Generators.cs is the generator list `dotnet meta gen` runs. It declares nothing yet, " + diff --git a/server/csharp/MetaObjects.Cli/VerifyCommand.cs b/server/csharp/MetaObjects.Cli/VerifyCommand.cs index 81dcb12fa5..a647029848 100644 --- a/server/csharp/MetaObjects.Cli/VerifyCommand.cs +++ b/server/csharp/MetaObjects.Cli/VerifyCommand.cs @@ -441,6 +441,7 @@ private static Codegen.CodegenDrift.Result RunCodegenDrift(Options opts, out boo // selection that excludes `names` would reference `Names.*` while `gen` // itself emits the literal for that identical selection — spurious drift in one // direction, a false-clean pass in the other. + var neutralConfig = MetaObjects.Config.NeutralConfig.Read(GenCommand.ProjectRootFor(opts.MetadataDir), validateNaming: false); var config = new GenConfig { OutDir = opts.OutDir, Namespace = opts.Namespace ?? opts.ConfiguredNamespace, @@ -452,7 +453,11 @@ private static Codegen.CodegenDrift.Result RunCodegenDrift(Options opts, out boo // The manifest gen keeps: an extra file is classified by what gen recorded writing. GenStateDir = Path.Combine(GenCommand.ProjectRootFor(opts.MetadataDir), ".metaobjects", ".gen-state"), ProjectRoot = GenCommand.ProjectRootFor(opts.MetadataDir), - }; + // The dialect gen read: without it a Postgres project's identity start and its design-time + // services read as drift. + Dialect = neutralConfig?.MigrateDialect, + SkipRedundantChecks = neutralConfig?.MigrateSkipRedundantChecks ?? false, + }.WithCSharpLayout(neutralConfig); return Codegen.CodegenDrift.Compute(config, load.Root, generators); } diff --git a/server/csharp/MetaObjects.Codegen.Tests/CSharpNamingTests.cs b/server/csharp/MetaObjects.Codegen.Tests/CSharpNamingTests.cs index 27be88dadf..eba4a368ce 100644 --- a/server/csharp/MetaObjects.Codegen.Tests/CSharpNamingTests.cs +++ b/server/csharp/MetaObjects.Codegen.Tests/CSharpNamingTests.cs @@ -294,6 +294,7 @@ private static MetaRoot PackagedObjects(params NamedObject[] objects) Config = new GenConfig { OutDir = "/unused", Namespace = "Acme.Generated", + OutputLayout = OutputLayout.Package, PackageNamespacesFromMetadata = true, PackageNamespaces = new() { ["enterprise"] = "Acme.Enterprise", ["core"] = "Acme.Core" }, }, }; @@ -371,7 +372,8 @@ public void NamingConformance_two_emitting_entities_in_one_context_are_refused_b { var root = PackagedObjects(ReadObject(c.GetProperty("entityA")), ReadObject(c.GetProperty("entityB"))); var ex = Assert.Throws(() => Run(new DbContextGenerator(), root)); - Assert.Contains($"DbSet property \"{c.GetProperty("collidesOn").GetString()}\"", ex.Message); + Assert.Contains("ERR_COLLECTION_NAME_COLLISION", ex.Message); + Assert.Contains($"both generate \"{c.GetProperty("collidesOn").GetString()}\" in the DbSet properties", ex.Message); Assert.Contains("@collectionName", ex.Message); } } @@ -381,7 +383,8 @@ public void Two_emitting_entities_in_one_routes_entry_are_refused_by_segment() { var root = PackagedObjects(new("enterprise", "Payer", false, true, "enterprise"), new("core", "Payer", false, true, "core")); var ex = Assert.Throws(() => Run(new RoutesGenerator(), root)); - Assert.Contains("REST collection segment \"payers\"", ex.Message); + Assert.Contains("ERR_COLLECTION_NAME_COLLISION", ex.Message); + Assert.Contains("both generate \"payers\" in the REST collection segments", ex.Message); } [Fact] @@ -391,7 +394,7 @@ public void One_name_in_two_packages_two_schemas_two_contexts_and_two_route_entr foreach (var pkg in new[] { "enterprise", "core" }) { var context = Assert.Single(Run(new DbContextGenerator { Include = InPackage(pkg) }, root)).Content; - Assert.Contains("DbSet Payers", context); + Assert.Contains("Payers { get; set; }", context); Assert.NotEmpty(Run(new RoutesGenerator { Include = InPackage(pkg) }, root)); } var entities = Run(new EntityGenerator(), root).Select(f => f.Content).ToList(); @@ -425,9 +428,9 @@ public void A_dbSetName_that_cannot_be_the_property_is_refused_at_codegen(string Assert.Contains($"\"{bad}\"", ex.Message); } - // One context, one relation per (schema, name). Two objects that map to one - // table would silently share it; the DbSet rule no longer catches them once @collectionName splits - // the property names. + // One context, one relation per (schema, name). Two objects that map to one table would + // silently share it; the DbSet rule no longer catches them once @collectionName splits the + // property names. [Theory] [InlineData("billing")] [InlineData(null)] @@ -440,7 +443,33 @@ public void Two_objects_mapping_one_relation_in_one_context_are_refused_naming_b Assert.Contains("ERR_DUPLICATE_SQL_NAME", ex.Message); Assert.Contains("\"enterprise::Payer\"", ex.Message); Assert.Contains("\"core::Payer\"", ex.Message); - Assert.Contains(schema is null ? "\"payers\"" : "\"billing\".\"payers\"", ex.Message); + Assert.Contains(schema is null ? "\"payers\"" : "\"billing.payers\"", ex.Message); + } + + [Fact] + public void Two_objects_mapping_one_routine_in_one_context_are_refused_naming_both() + { + const string json = """ + { "metadata.root": { "package": "acme", "children": [ + { "object.entity": { "name": "Alpha", "children": [ + { "source.rdb": { "@role": "primary", "@kind": "table", "@table": "alphas" } }, + { "source.rdb": { "@role": "replica", "@kind": "storedProc", "@proc": "refresh_totals" } }, + { "field.long": { "name": "id" } }, + { "identity.primary": { "@fields": "id" } } ] } }, + { "object.entity": { "name": "Beta", "children": [ + { "source.rdb": { "@role": "primary", "@kind": "table", "@table": "betas" } }, + { "source.rdb": { "@role": "replica", "@kind": "storedProc", "@proc": "refresh_totals" } }, + { "field.long": { "name": "id" } }, + { "identity.primary": { "@fields": "id" } } ] } } + ] } } + """; + var r = new MetaDataLoader().Load([new InMemoryStringSource(json, id: "routine.json")]); + Assert.Empty(r.Errors); + var ex = Assert.Throws(() => Run(new DbContextGenerator(), r.Root)); + Assert.Contains("ERR_DUPLICATE_SQL_NAME", ex.Message); + Assert.Contains("acme::Alpha", ex.Message); + Assert.Contains("acme::Beta", ex.Message); + Assert.Contains("refresh_totals", ex.Message); } [Fact] diff --git a/server/csharp/MetaObjects.Codegen.Tests/CheckConstraintConformanceTests.cs b/server/csharp/MetaObjects.Codegen.Tests/CheckConstraintConformanceTests.cs new file mode 100644 index 0000000000..983e897ee0 --- /dev/null +++ b/server/csharp/MetaObjects.Codegen.Tests/CheckConstraintConformanceTests.cs @@ -0,0 +1,111 @@ +// The generated EF model declares the CHECKs `meta migrate` derives — +// every validator that can carry one, and every scalar field.enum — with migrate's names and +// expression text, so one model builds one database through either delivery path (an EF +// migration or `meta migrate`). The names and text are pinned by the shared corpus +// fixtures/check-constraint-conformance/, which the TypeScript migrate suite passes too. + +using System.Text.Json; +using MetaObjects.Codegen.Generators; +using MetaObjects.Loader; +using MetaObjects.Meta; +using Xunit; + +namespace MetaObjects.Codegen.Tests; + +public class CheckConstraintConformanceTests +{ + private static string Corpus() + { + var dir = new DirectoryInfo(AppContext.BaseDirectory); + while (dir is not null && !Directory.Exists(Path.Combine(dir.FullName, "fixtures"))) + dir = dir.Parent; + Assert.NotNull(dir); + return Path.Combine(dir!.FullName, "fixtures", "check-constraint-conformance"); + } + + private static MetaRoot Load() + { + var load = MetaDataLoader.FromDirectory(Path.Combine(Corpus(), "input")); + Assert.Empty(load.Errors); + return load.Root; + } + + private static GenContext Ctx(MetaRoot root, string? dialect, bool skipRedundant = false) => new() + { + Entities = root.Objects(), + Root = root, + Config = new GenConfig { OutDir = "/tmp", Namespace = "Acme.Checks", Dialect = dialect, SkipRedundantChecks = skipRedundant }, + }; + + public static TheoryData Cases => new() + { + { "expected.postgres.json", "postgres", false }, + { "expected.postgres.skip-redundant.json", "postgres", true }, + { "expected.sqlite.json", "sqlite", false }, + { "expected.d1.json", "d1", false }, + { "expected.sqlite.skip-redundant.json", "sqlite", true }, + }; + + private static Dictionary> Expected(string file) + { + using var doc = JsonDocument.Parse(File.ReadAllText(Path.Combine(Corpus(), file))); + return doc.RootElement.EnumerateObject().ToDictionary( + t => t.Name, + t => t.Value.EnumerateArray().Select(c => (c.GetProperty("name").GetString()!, c.GetProperty("expression").GetString()!)).ToList()); + } + + [Theory] + [MemberData(nameof(Cases))] + public void The_checks_are_meta_migrates_names_and_text(string file, string dialect, bool skipRedundant) + { + var ctx = Ctx(Load(), dialect, skipRedundant); + var actual = ctx.Root.Objects() + .Where(o => o.IsEntity() && o.DbTable is not null) + .Select(o => (Table: CSharpNaming.Table(o), Checks: CheckConstraints.For(o, ctx.Config))) + .Where(t => t.Checks.Count > 0) + .ToDictionary(t => t.Table, t => t.Checks.Select(c => (c.Name, c.Expression)).ToList()); + var expected = Expected(file); + Assert.Equal(expected.Keys.OrderBy(k => k), actual.Keys.OrderBy(k => k)); + foreach (var (table, checks) in expected) + Assert.Equal(checks, actual[table]); + } + + [Fact] + public void The_context_declares_each_check_on_its_table() + { + var ctx = Ctx(Load(), "postgres"); + var context = new DbContextGenerator().Generate(ctx).Single(f => f.Path.EndsWith("AppDbContext.g.cs", StringComparison.Ordinal)).Content; + Assert.Contains("modelBuilder.Entity().ToTable(t => t.HasCheckConstraint(\"gadgets_status_chk\", \"\\\"status\\\" IN ('DRAFT', 'LIVE')\"));", context); + Assert.Contains("t.HasCheckConstraint(\"gadgets_sku_shape\", ", context); + Assert.Contains("t.HasCheckConstraint(\"gadgets_email_exactlyone_chk\", \"num_nonnulls(\\\"email\\\", \\\"phone\\\") = 1\")", context); + // A derived field is no column of the table: no CHECK names it, nor a cross-field CHECK over it. + Assert.DoesNotContain("band", context); + Assert.DoesNotContain("owner_name", context); + } + + [Fact] + public void A_project_naming_no_dialect_declares_no_check() + { + var context = new DbContextGenerator().Generate(Ctx(Load(), dialect: null)).Single(f => f.Path.EndsWith("AppDbContext.g.cs", StringComparison.Ordinal)).Content; + Assert.DoesNotContain("HasCheckConstraint", context); + } + + [Fact] + public void The_context_with_its_checks_compiles_against_EF_Core_8() + { + var ctx = Ctx(Load(), "postgres"); + var sources = new EntityGenerator().Generate(ctx) + .Concat(new DbContextGenerator().Generate(ctx)) + .Concat(new NamesGenerator().Generate(ctx)) + .Where(f => f.Path.EndsWith(".cs", StringComparison.Ordinal)) + .Select(f => Microsoft.CodeAnalysis.CSharp.CSharpSyntaxTree.ParseText(f.Content, + new Microsoft.CodeAnalysis.CSharp.CSharpParseOptions(Microsoft.CodeAnalysis.CSharp.LanguageVersion.CSharp12))) + .ToList(); + var comp = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("checks_" + Guid.NewGuid().ToString("N"), sources, + DbContextCompileTests.BuildReferences(), + new Microsoft.CodeAnalysis.CSharp.CSharpCompilationOptions(Microsoft.CodeAnalysis.OutputKind.DynamicallyLinkedLibrary)); + var errors = comp.GetDiagnostics().Where(d => d.Severity == Microsoft.CodeAnalysis.DiagnosticSeverity.Error) + .Select(d => $"{d.Id}: {d.GetMessage()}").ToList(); + Assert.True(errors.Count == 0, string.Join("\n", errors)); + } +} diff --git a/server/csharp/MetaObjects.Codegen.Tests/CodegenCompileConformanceTests.cs b/server/csharp/MetaObjects.Codegen.Tests/CodegenCompileConformanceTests.cs index addc7d18d3..c913fb5b39 100644 --- a/server/csharp/MetaObjects.Codegen.Tests/CodegenCompileConformanceTests.cs +++ b/server/csharp/MetaObjects.Codegen.Tests/CodegenCompileConformanceTests.cs @@ -66,6 +66,13 @@ public class CodegenCompileConformanceTests private static string CorpusMetadata => CorpusPaths.FitnessMetadata; + private static string Leaf(string path) => path[(path.LastIndexOf('/') + 1)..]; + + // Every package of the corpus, bound to a namespace with a System segment. + private static Dictionary CorpusPackageNamespaces(MetaRoot root) => + root.Objects().Select(o => PackageBindingResolver.EffectivePackage(o)).Where(p => !string.IsNullOrEmpty(p)).Distinct() + .ToDictionary(p => p!, p => "MetaObjects.CompileConformance.System." + string.Concat(p!.Split("::").Select(CSharpNaming.Pascal))); + private static MetaRoot LoadCorpus() { var result = new MetaDataLoader().Load([new FileSource(CorpusMetadata)]); @@ -100,9 +107,27 @@ private static MetaRoot LoadCorpus() { "entity,db-context,filter-allowlist,callable,names,render-helper,output-prompt,output-parser,extractor", true }, }; + /// The same selections under the opt-in package layout, with the corpus package bound to + /// a namespace that has a System segment: a bare System.* reference in a file in + /// it resolves into that namespace, which is what the runner's framework qualification exists for. + public static TheoryData PackageSelections => new() + { + { "entity,db-context,filter-allowlist,callable,names", true }, + { "entity,db-context,filter-allowlist,callable", false }, + { "entity,db-context,filter-allowlist,callable,names,render-helper,output-prompt,output-parser,extractor", true }, + }; + [Theory] [MemberData(nameof(Selections))] - public void Every_generated_file_compiles_with_zero_errors(string selection, bool includeNames) + public void Every_generated_file_compiles_with_zero_errors(string selection, bool includeNames) => + CompileSelection(selection, includeNames, package: false); + + [Theory] + [MemberData(nameof(PackageSelections))] + public void Every_generated_file_compiles_with_zero_errors_in_the_package_layout(string selection, bool includeNames) => + CompileSelection(selection, includeNames, package: true); + + private static void CompileSelection(string selection, bool includeNames, bool package) { var root = LoadCorpus(); var ctx = new GenContext @@ -117,6 +142,9 @@ public void Every_generated_file_compiles_with_zero_errors(string selection, boo ColumnNamingStrategy = CorpusPaths.Naming.Columns, IncludeNames = includeNames, EmitAbstractShapes = false, + OutputLayout = package ? OutputLayout.Package : OutputLayout.Flat, + PackageNamespacesFromMetadata = package, + PackageNamespaces = package ? CorpusPackageNamespaces(root) : new(), }, }; @@ -147,7 +175,8 @@ public void Every_generated_file_compiles_with_zero_errors(string selection, boo generators.Add(new ExtractorGenerator()); } - var files = generators.SelectMany(g => g.Generate(ctx)).ToList(); + // The runner's post-pass: every file goes through it before it is written. + var files = generators.SelectMany(g => g.Generate(ctx)).Select(f => FrameworkQualifier.Apply(ctx.Config, f)).ToList(); Assert.True(files.Count > 0, $"selection '{selection}' generated no files at all"); // FR-044 — every view-backed report of the corpus (twenty-five today) generates a keyless @@ -165,10 +194,10 @@ public void Every_generated_file_compiles_with_zero_errors(string selection, boo "ProgramsEmptyScope", "WeekShapes", "SessionsByProgram", "ProgramSessions", "NodesByParent", "AuthsByKind", }) { - Assert.True(files.Any(f => f.Path == report + ".g.cs"), $"no row class was generated for report {report}"); - Assert.True(files.Any(f => f.Path == report + "FilterAllowlist.g.cs"), + Assert.True(files.Any(f => Leaf(f.Path) == report + ".g.cs"), $"no row class was generated for report {report}"); + Assert.True(files.Any(f => Leaf(f.Path) == report + "FilterAllowlist.g.cs"), $"no filter allowlist was generated for report {report}"); - Assert.False(files.Any(f => f.Path.StartsWith(report + "Names", StringComparison.Ordinal)), + Assert.False(files.Any(f => Leaf(f.Path).StartsWith(report + "Names", StringComparison.Ordinal)), $"report {report} leaked into the names tier"); } @@ -176,7 +205,7 @@ public void Every_generated_file_compiles_with_zero_errors(string selection, boo { // A compile gate passes trivially on an empty emit, so name what this selection // must have produced rather than trusting a file count. - var emitted = files.Select(f => Path.GetFileName(f.Path)).ToHashSet(StringComparer.Ordinal); + var emitted = files.Select(f => Leaf(f.Path)).ToHashSet(StringComparer.Ordinal); // This port names a template artifact `..cs` — the authored // template name as the stem, as the TS port does, while the JVM ports use // `` because a JVM file name must match its public type. diff --git a/server/csharp/MetaObjects.Codegen.Tests/ColumnCommentCodegenTests.cs b/server/csharp/MetaObjects.Codegen.Tests/ColumnCommentCodegenTests.cs new file mode 100644 index 0000000000..84c2778f88 --- /dev/null +++ b/server/csharp/MetaObjects.Codegen.Tests/ColumnCommentCodegenTests.cs @@ -0,0 +1,115 @@ +// Every column a description reaches carries its comment in the EF model. +// A field.map is a converted scalar property and takes SetComment like any column, found with +// GetProperty (a property the generator configures and cannot find is a bug, said loudly). A +// field.object stored as JSON (ToJson) cannot carry a comment in EF 8, so the text — the field's +// @description, else its value object's — rides on the owned type as an annotation that the +// generated design-time differ scaffolds as COMMENT ON COLUMN (live test: EfModelGapsTests). + +using MetaObjects.Codegen.Generators; +using MetaObjects.Loader; +using Xunit; + +namespace MetaObjects.Codegen.Tests; + +public sealed class ColumnCommentCodegenTests +{ + private const string Model = """ + { "metadata.root": { "package": "acme", "children": [ + { "object.value": { "name": "Meta", "@description": "Free-form tags.", "children": [ { "field.string": { "name": "tag" } } ] } }, + { "object.entity": { "name": "Ticket", "children": [ + { "source.rdb": { "@table": "tickets" } }, + { "field.string": { "name": "code", "@maxLength": 20 } }, + { "field.object": { "name": "meta", "@objectRef": "Meta", "@storage": "jsonb" } }, + { "field.map": { "name": "labels", "@valueType": "string", "@description": "Labels by key." } }, + { "identity.primary": { "@fields": "code", "@generation": "assigned" } } + ] } } + ] } } + """; + + private static (List Files, List Warnings) Run(string? dialect, DbContextGenerator? generator = null) + { + var load = new MetaDataLoader().Load([new InMemoryStringSource(Model, id: "m.json")]); + Assert.Empty(load.Errors); + var warnings = new List(); + var ctx = new GenContext + { + Entities = load.Root.Objects(), Root = load.Root, Warn = warnings.Add, + Config = new GenConfig { OutDir = "/unused", Namespace = "Acme", Dialect = dialect, ContextAssemblyName = "Acme.Data" }, + }; + return ((generator ?? new DbContextGenerator()).Generate(ctx).ToList(), warnings); + } + + [Fact] + public void A_map_takes_its_comment_through_GetProperty() + { + var (files, _) = Run("postgres"); + var context = files.Single(f => f.Path == "AppDbContext.g.cs").Content; + Assert.Contains("modelBuilder.Entity().Metadata.GetProperty(\"Labels\").SetComment(\"Labels by key.\");", context); + Assert.DoesNotContain("FindProperty(", context); + } + + [Fact] + public void A_json_column_takes_its_value_objects_description_as_an_annotation_the_design_time_differ_scaffolds() + { + var (files, warnings) = Run("postgres"); + // Its outDir is no project on disk, so only the "cannot tell" reference warning is expected. + Assert.Empty(warnings.Where(w => !w.Contains("cannot tell whether EF reads the DesignTimeServicesReference", StringComparison.Ordinal))); + var context = files.Single(f => f.Path == "AppDbContext.g.cs").Content; + Assert.Contains("modelBuilder.Entity().Metadata.FindNavigation(\"Meta\")!.TargetEntityType" + + ".SetAnnotation(\"MetaObjects:JsonColumnComment\", \"Free-form tags.\");", context); + // No increment key here: the services are emitted for the comment alone. + var services = Assert.Single(files, f => f.Path.EndsWith("DesignTimeServices.g.cs", StringComparison.Ordinal)).Content; + Assert.Contains("COMMENT ON COLUMN", services); + } + + [Fact] + public void Off_postgres_a_json_column_comment_is_said_and_left_to_meta_migrate() + { + var (files, warnings) = Run("sqlite"); + Assert.DoesNotContain("MetaObjects:JsonColumnComment", files.Single(f => f.Path == "AppDbContext.g.cs").Content); + Assert.Contains(warnings, w => w.Contains("Ticket.meta is not in the EF model", StringComparison.Ordinal)); + } + + // An OwnedTypeConfig override decides the mapping, and the comment follows it. + private sealed class Hook(string line) : DbContextGenerator + { + protected override string? OwnedTypeConfig(string owner, MetaObjects.Meta.MetaObject entity, MetaObjects.Meta.MetaField field, GenContext ctx) => + field.Name == "meta" ? line.Replace("__OWNER__", owner) : base.OwnedTypeConfig(owner, entity, field, ctx); + } + + [Fact] + public void A_json_column_a_hook_maps_as_a_property_takes_its_comment_through_GetProperty() + { + var (files, warnings) = Run("postgres", new Hook( + " modelBuilder.Entity<__OWNER__>().Property(x => x.Meta).HasColumnName(\"meta\").HasColumnType(\"jsonb\");")); + var context = files.Single(f => f.Path == "AppDbContext.g.cs").Content; + Assert.Contains("modelBuilder.Entity().Metadata.GetProperty(\"Meta\").SetComment(\"Free-form tags.\");", context); + Assert.DoesNotContain("FindNavigation(", context); + Assert.DoesNotContain("MetaObjects:JsonColumnComment", context); + // No JSON-column annotation, so no design-time services for it. + Assert.DoesNotContain(files, f => f.Path.EndsWith("DesignTimeServices.g.cs", StringComparison.Ordinal)); + Assert.DoesNotContain(warnings, w => w.Contains("Ticket.meta", StringComparison.Ordinal)); + } + + [Fact] + public void A_json_column_a_hook_maps_some_other_way_gets_no_comment_line_and_is_said() + { + var (files, warnings) = Run("postgres", new Hook(" modelBuilder.Entity<__OWNER__>().Ignore(x => x.Meta);")); + var context = files.Single(f => f.Path == "AppDbContext.g.cs").Content; + Assert.DoesNotContain("Free-form tags.", context); + Assert.Contains(warnings, w => w.Contains("Ticket.meta is not in the EF model", StringComparison.Ordinal) + && w.Contains("OwnedTypeConfig", StringComparison.Ordinal)); + } + + [Fact] + public void A_hook_that_keeps_the_stock_owned_mapping_keeps_the_annotation_byte_for_byte() + { + var (stock, _) = Run("postgres"); + // The hook returns the stock line itself, as an override that delegates to base does. + var owned = stock.Single(f => f.Path == "AppDbContext.g.cs").Content.Split('\n') + .Single(l => l.Contains("OwnsOne(x => x.Meta", StringComparison.Ordinal)).TrimEnd('\r'); + Assert.Contains(".ToJson(", owned); + var (hooked, _) = Run("postgres", new Hook(owned)); + Assert.Equal(stock.Single(f => f.Path == "AppDbContext.g.cs").Content, hooked.Single(f => f.Path == "AppDbContext.g.cs").Content); + } +} diff --git a/server/csharp/MetaObjects.Codegen.Tests/CrossPackageBindingConformanceTests.cs b/server/csharp/MetaObjects.Codegen.Tests/CrossPackageBindingConformanceTests.cs index 87cdf2a3e1..b14c965475 100644 --- a/server/csharp/MetaObjects.Codegen.Tests/CrossPackageBindingConformanceTests.cs +++ b/server/csharp/MetaObjects.Codegen.Tests/CrossPackageBindingConformanceTests.cs @@ -117,7 +117,7 @@ private static Dictionary Generated(MetaRoot root) { Entities = root.Objects(), Root = root, - Config = new GenConfig { OutDir = "/tmp", Namespace = "Acme.Gen" }, + Config = new GenConfig { OutDir = "/tmp", Namespace = "Acme.Gen", OutputLayout = OutputLayout.Package, PackageNamespacesFromMetadata = true }, }; var files = new Dictionary(); foreach (var gen in new IGenerator[] { new EntityGenerator(), new DbContextGenerator(), new RoutesGenerator() }) @@ -132,7 +132,7 @@ public void Generated_routes_and_entities_use_the_bound_target_of_each_navigatio var root = Load(); var files = Generated(root); string navigating = string.Concat( - files["Post.g.cs"], files["PostRoutes.g.cs"], files["Order.g.cs"], files["OrderRoutes.g.cs"], files["AppDbContext.g.cs"]); + files["a/Post.g.cs"], files["a/PostRoutes.g.cs"], files["acme/Order.g.cs"], files["acme/OrderRoutes.g.cs"], files["AppDbContext.g.cs"]); // The same-short-named objects in the wrong package own a string key and these tables. Assert.DoesNotContain("a_tags", navigating); @@ -140,26 +140,26 @@ public void Generated_routes_and_entities_use_the_bound_target_of_each_navigatio Assert.DoesNotContain("acme_customers", navigating); Assert.DoesNotContain("EF.Property", navigating); - string post = files["PostRoutes.g.cs"]; + string post = files["a/PostRoutes.g.cs"]; Assert.Contains("/posts/{id}/tags", post); Assert.Contains("relatedIds.Contains(EF.Property(t, \"Id\"))", post); Assert.DoesNotContain("\"Code\"", post); - Assert.Contains("ICollection Tags", files["Post.g.cs"]); - Assert.Contains("FeaturedTagId", files["Post.g.cs"]); + Assert.Contains("ICollection Tags", files["a/Post.g.cs"]); + Assert.Contains("FeaturedTagId", files["a/Post.g.cs"]); - string order = files["OrderRoutes.g.cs"]; + string order = files["acme/OrderRoutes.g.cs"]; Assert.Contains("/orders/{id}/labels", order); Assert.Contains("relatedIds.Contains(EF.Property(t, \"Id\"))", order); Assert.DoesNotContain("\"Code\"", order); - string orderEntity = files["Order.g.cs"]; - Assert.Contains("ICollection - + @@ -197,7 +197,7 @@

object.projection

- + @@ -260,7 +260,7 @@

object.report

- + diff --git a/spec/decisions/ADR-0015-single-shared-migrate-engine.md b/spec/decisions/ADR-0015-single-shared-migrate-engine.md index e302bf766e..2d89aa6e2e 100644 --- a/spec/decisions/ADR-0015-single-shared-migrate-engine.md +++ b/spec/decisions/ADR-0015-single-shared-migrate-engine.md @@ -86,6 +86,7 @@ migrations, not SQL): - **Explicitly out of scope:** EF Core Migrations, FluentMigrator (C#-coded), Alembic, Django (Python-coded) — emitting those means generating per-language migration *code* and they are ORM-coupled (EF↔EF Core, Alembic↔SQLAlchemy), which MetaObjects users need not adopt. + **EF Core Migrations is no longer out of scope; see Amendment 1.** - MetaObjects does **not** reimplement an external runner's history / checksums / ordering — that is the runner's job (or the homegrown apply's journal for the zero-dep path). @@ -238,6 +239,34 @@ final step of each port's cutover. Inventory (as of 2026-05-30): emit) for an external runner; the **`pg_try_advisory_lock` + backoff** contention refinement (the shipped lock is blocking); and the **`info`/`state`/`validate`/`repair`/`baseline`** command surfaces. +## Amendment 1 (2026-11-12): EF Core Migrations is a supported second C# path + +**Context.** A C# adopter whose schema is owned by EF Core Migrations (`dotnet ef migrations add`, +`dotnet ef database update`) cannot hand it to `meta migrate` without giving up a chain they +already run in production. The generated `DbContext` is the model EF diffs, so whatever the +context declares is what EF scaffolds. Leaving that path unsupported did not keep adopters on +`meta migrate`. It meant the generated context described a schema that differed from the one +`meta migrate` would build. + +**Decision.** EF Core Migrations is a supported second schema path for C#, beside `meta migrate`, +and the adopter picks one per database. The engine in Decision 5 stays the single shared engine: +MetaObjects does not generate migration code, and no port grows a diff engine. What changes is +that the generated EF model is held to the schema `meta migrate` would build from the same +metadata. It declares the same CHECKs, indexes, comments, identity starts and column types, so a +`dotnet ef migrations add` scaffolds the schema the metadata describes. Where EF's own +migration SQL would contradict a cross-port rule, the generated design-time services replace that +operation's SQL. The case in point is an identity start: Npgsql writes `RESTART WITH n`, and +`@sequenceStart` never moves a counter backward. + +**Consequences.** +- `fixtures/check-constraint-conformance/` gates the CHECKs the EF model declares against the + ones `meta migrate` emits. A CHECK one path has and the other lacks is a defect on that path. +- `meta verify --db` still reads any live database, whichever path built it. It is the drift + gate for both. +- Python, Java and Kotlin are unaffected: ADR-0015's single engine stays their only schema path. +- Removing the C# migrate engine (Decision 7) stands. The EF path is EF's own engine, not a + MetaObjects one. + ## Conformance note Migrate behavior is gated by the **persistence-conformance** corpus. Post-consolidation, the diff --git a/spec/decisions/ADR-0044-payload-record-naming-cross-package-collision.md b/spec/decisions/ADR-0044-payload-record-naming-cross-package-collision.md index 100a7f3fd9..6f16cb2598 100644 --- a/spec/decisions/ADR-0044-payload-record-naming-cross-package-collision.md +++ b/spec/decisions/ADR-0044-payload-record-naming-cross-package-collision.md @@ -54,3 +54,38 @@ This ADR extends, rather than introduces, house doctrine: ADR-0041/0042 already - **Corpus contract strengthened, not weakened.** `fixtures/template-output-render-conformance/xpkg-collision/README.md` now states plainly: a port's conformance runner must construct its render-time payload from **generator-emitted** types — never hand-author or otherwise reconcile the payload record. The corpus's render-output pins (`"Alpha=AA Beta=BB"`) are untouched: the render engine and the build-time verify field-tree resolve against **metadata**, never against record names, so this ADR does not touch them. - **Stage 1 (this decision):** the TS reference implementation (`codegen-ts/src/payload-codegen.ts`) and the C# port (`MetaObjects.Codegen/PayloadCodegen.cs`, fixing #219's wrong-node resolution as part of the same pass) ship together. **Stage 2/3 (tracked separately, not in this change):** Python, then Java + Kotlin (the heavier lift — per-output-package closure plumbing plus #220's new collision-conformance suite), followed by a coordinated bug-fix release across all four package registries. - **Follow-up, explicitly out of scope here:** #219's own note that the C# port's `CSharpNaming.StripPkg` + bare-short-name-match convention recurs in roughly seven other C# generators (routes, entity, M:N navigation, output-parser, DbContext, reverse-finders, package-binding-resolver) — the same disease, a different blast radius (entity/route naming rather than payload naming), deserving its own audit and ruling. **Update (#228):** the *output-parser* member of that list — the extract/output-parser tier's own collision-scoped payload naming, plus the package-blind build-time `@payloadRef`/`@responseRef` resolvers it shares with the render-helper, output-prompt, and (JVM) `meta:verify` template-drift generators — is now fixed, cross-port (all five ports, not scoped to C#). The other six C#-specific generators in that list (routes, entity, M:N navigation, DbContext, reverse-finders, package-binding-resolver) remain open, tracked separately. + +## Amendment 1 (2026-11-12): no rename; one claim registry + +The package-qualified derived name is **removed** in every port. A value object's type is its own +name and is never rewritten. The rename carried this ADR's admitted instability (decision §6: +adding an unrelated object renamed an existing type), and ADR-0056's model-wide widening made it +worse: an **abstract** object that emits nothing could force a concrete value object elsewhere to +be renamed. + +A real collision is refused instead, by one claim registry per run. A generator claims each name +when it emits it, in the scope the name lives in: a type per C# namespace, a module per +TypeScript or Python output directory, a file per output path, a finder per class. A second +claimant of one name in one scope fails with `ERR_NAME_COLLISION`, naming both metadata nodes and +the remedy. A collection name (a REST segment, a C# DbSet) keeps the shared-ledger code +`ERR_COLLECTION_NAME_COLLISION` in every port, with `@collectionName` as the remedy. The same claimant claiming again +is not a collision, and an object that emits nothing claims nothing, so the check follows the +generator wiring by construction. + +The cross-package case this ADR exists for still works, without a rename: + +- **TypeScript and Python**: the package output layout (`outputLayout: "package"`) writes each + object in the directory of its metadata package. A file that meets two same-named value objects + binds them under local import aliases (`import type { Note as AcmeAlphaNote }`); no module + declares a renamed type. In the flat layout the clash is refused, and the remedy names the + package layout. +- **C#**: map the packages to distinct namespaces (`csharp.packageNamespaces` in + `.metaobjects/config.json`, or `GenConfig.PackageNamespaces` in a self-hosted runner). Every + reference to a type in another namespace is written `global::`-qualified. +- **Java and Kotlin** never renamed: each metadata package maps to its own JVM package and + directory. The one clash those ports can meet, two metadata packages mapping to one directory + (a case-only difference, or `a.b` beside `a::b`), is refused before any generator runs with the + same `ERR_NAME_COLLISION`. + +`ERR_PAYLOAD_NAME_COLLISION` is no longer raised by any port. `ERR_NAME_COLLISION` is a +codegen-time code, like it. diff --git a/spec/decisions/ADR-0056-value-object-types-are-generated-once.md b/spec/decisions/ADR-0056-value-object-types-are-generated-once.md index 904ab0cf22..b70ad2a9b3 100644 --- a/spec/decisions/ADR-0056-value-object-types-are-generated-once.md +++ b/spec/decisions/ADR-0056-value-object-types-are-generated-once.md @@ -152,6 +152,20 @@ implementation proved wrong. example Kotlin's `KotlinTemplateTierValueObjectTest`, Java's `OutputParserExtractTierCollisionTest`, and Python's `test_extract_tier_collision.py`. +## Amendment 2 (2026-11-12): value-object names are never rewritten + +Rule 2's collision-aware name (the package-qualified `AcmeAlphaNote`) is removed in every port; +see [ADR-0044 Amendment 1](ADR-0044-payload-record-naming-cross-package-collision.md). The type is +generated once, under its own name, in its own namespace, module or package, and every tier +references that name. Two objects that would emit one type into one scope are refused by the +run's claim registry (`ERR_NAME_COLLISION`), with the remedy of placing the packages apart (the +package output layout in TypeScript and Python, `csharp.packageNamespaces` in C#). A private member +of a generated class that is keyed by a value object (C#'s extract-tier mappers) may still carry the +package to stay unique inside that class; that is a member name, never a type. Likewise a file that +meets two same-named value objects binds them under local import aliases, and the extract tier's +mirrors and mappers, declarations of that one module, take the alias (`AcmeAlphaNoteExtracted`). +No module declares a renamed type. + ## Alternatives considered - **One copy per consuming package (the #387 proposal).** Rejected: it fixes the compile error by diff --git a/spec/metamodel/object.json b/spec/metamodel/object.json index c633eaa653..244fd1655a 100644 --- a/spec/metamodel/object.json +++ b/spec/metamodel/object.json @@ -31,7 +31,7 @@ { "type": "segment", "subType": "*", "name": "*", "min": 0, "max": null }, { "type": "attr", "subType": "string", "name": "discriminator", "min": 0, "max": 1, "description": "FR-014: names the field on this entity (resolvable via extends:) that holds the subtype-discriminator value. Subtypes of this entity declare @discriminatorValue to bind their rows to a discriminator value. The discriminator field itself is an ordinary field declaration (typically field.enum or field.int / field.string)." }, { "type": "attr", "subType": "string", "name": "discriminatorValue", "min": 0, "max": 1, "description": "FR-014: on a subtype of an entity with @discriminator — the value that identifies rows of this subtype in the shared discriminator field. Wire form is always a string; the underlying field's subtype (enum / int / string) controls codegen + storage coercion. Required on every concrete subtype of a discriminated entity." }, - { "type": "attr", "subType": "string", "name": "collectionName", "min": 0, "max": 1, "implementedIn": ["csharp", "typescript"], "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." } + { "type": "attr", "subType": "string", "name": "collectionName", "min": 0, "max": 1, "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." } ] }, { @@ -54,7 +54,7 @@ "rules": "object.projection is a derived read-only representation: every field is extends-bound, origin-derived, or self-declared-under-external-assembly, and all are read-only at the subtype level. Identity is optional and, when present, MUST extend an entity identity. Sources are restricted to read-only @kinds. The declared field set IS the exposure — an inclusive list, fail-closed. A projection NEVER declares relationships (derivation is expressed via @via, not a relationship child) and NEVER co-locates templates — hence its child set omits both relationship and template. The assembly origins (origin.aggregate / origin.computed / origin.first) live HERE, not on object.value; a SOURCELESS projection is the legal shape for a wire-assembled read model, and a template-level @payloadRef/@responseRef may target one (#210). See ADR-0028 (object taxonomy, projection).", "children": [ { "type": "attr", "subType": "filter", "name": "filter", "min": 0, "max": 1, "description": "Optional row-scope predicate (a portable attr.filter object: eq/ne/gt/gte/lt/lte/like/in/isNull with and/or, desugared to { field: { op: value } } at parse time) selecting which rows the view returns — lowered to an outer SQL WHERE. A key names one of the projection's own fields, else a field of its base entity the view need not output, else a PATH of to-one hops (identity.reference or @cardinality one relationship names) from the base then a field of the entity reached ('orderId.customerId.isActive'), joined but not output. A reached entity field may itself be derived (entity-derived: an origin.computed or origin.first declared on the entity, inlined where the filter reaches it). An aggregate-derived field is not addressable (fail-closed); a to-many hop is refused. A value may be a relative date ({ now: \"\", startOf? }) on a date or timestamp field." }, - { "type": "attr", "subType": "string", "name": "collectionName", "min": 0, "max": 1, "implementedIn": ["csharp", "typescript"], "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." } + { "type": "attr", "subType": "string", "name": "collectionName", "min": 0, "max": 1, "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." } ] }, { @@ -70,7 +70,7 @@ { "type": "attr", "subType": "string", "name": "segment", "min": 0, "max": 1, "description": "Optional segment of @from scoping the rows." }, { "type": "attr", "subType": "filter", "name": "filter", "min": 0, "max": 1, "description": "Optional row scope over @from's fields; may use relative-date values." }, { "type": "attr", "subType": "string", "name": "spine", "min": 0, "max": 1, "description": "Optional to-one path from @from to the entity whose rows supply the report's rows (e.g. 'Purchase.program'), written like a dimension's @via. With it the report has one row per distinct dimension tuple among THAT entity's rows, including the ones no row of @from refers to: a count there is 0 and any other measure is null unless it declares @default. Every listed dimension must be reached through this path. @segment and @filter still scope the rows of @from and never remove a row. A row of @from whose reference is null or matches nothing is in no row of the report." }, - { "type": "attr", "subType": "string", "name": "collectionName", "min": 0, "max": 1, "implementedIn": ["csharp", "typescript"], "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." } + { "type": "attr", "subType": "string", "name": "collectionName", "min": 0, "max": 1, "description": "The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own)." } ] } ]
metaobjects-core-typesThe name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own).The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own).
@discriminator metaobjects-core-typesThe name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own).The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own).
@filter metaobjects-core-typesThe name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) and the reverse-finder names in C# and TypeScript, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own).The name of this object's collection, in the object's own casing (e.g. 'CaseHistory', 'Queues'): the REST collection segment (snake_cased) in every port, the reverse-finder names in C#, TypeScript and Python, the C# DbSet property, and the TypeScript list function, list hook and Drizzle table variable. It need not be a grammatical plural. Absent, the project's pluralizer derives it from the object's name (naming.collections in .metaobjects/config.json; built in: standard, none; an application may register its own).
@dimensions