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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,27 @@ loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersi
one over measures as a `number` member (one reading a dimension is refused). Loader rule M11,
report rule R13 and a conformance fixture per refusal, in every loader port.

- **`verify.handEdits`: a hand-edited generated file can fail `meta verify`.** `meta verify
--codegen` already listed each generated file carrying a hand edit, but always exited 0, so a
rule changed by hand in generated code (a `max(32)` made `max(64)`) passed the gate. Set
`"verify": { "handEdits": "fail" }` in `.metaobjects/config.json` and it exits 1; `"notice"`
keeps the report and exit 0. `--allow-hand-edits` relaxes `fail` for one run, and the existing
`--forbid-hand-edits` still forces a failure for one run (passing both is refused). The report
names each file, how to see the edit, how to drop it (or move a changed rule into the
metadata), and how to keep it. A project without the key behaves exactly as before. The C#,
Java, Kotlin and Python gates compare generated files byte for byte and already fail on any
edit; the docs now say so.
- **`migrate.foreignKeyIndexes`: an index on every foreign key, without the `efcore` renames.**
With it on, `meta migrate` gives each enforced foreign key that the primary key, a unique key or
an index does not already lead with a `<table>_<columns>_idx` index. The Drizzle and Prisma
generators, the C# `AppDbContext` and the Kotlin Exposed tables declare the same indexes under
the same names; Java and Python map no indexes. It adds nothing under the `efcore` conventions
(which already index every foreign key) or on MySQL. A project without the key is unchanged and
keeps the unindexed-foreign-key advisory, which now names the option. Gated by two new
persistence-corpus migration scenarios (adding the indexes to an existing schema, and the
converged no-op). Java's config reader now carries the `migrate` block's
`foreignKeyIndexes`, `conventions` and `dialect` on the loaded root (`MigrateSettings`).

- **`meta init --skills-dir <dir>` and `meta agent-docs --skills-dir <dir>`: install the skills
for any coding assistant.** The `metaobjects-*` skills went only to `.claude/skills/`, which
Claude Code reads. `--skills-dir .agents/skills` (or any project-relative directory) puts them
Expand Down Expand Up @@ -89,6 +110,10 @@ loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersi
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`.
- **`meta init` writes stricter defaults for a new project.** The scaffolded
`.metaobjects/config.json` now carries `"verify": { "handEdits": "fail" }` and (except on
MySQL) `"migrate": { "foreignKeyIndexes": true }`, each as its own visible setting. An existing
config is left as it is.
- **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,
Expand Down
24 changes: 14 additions & 10 deletions agent-context/skills/metaobjects-verify/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,16 +150,20 @@ with `ERR_DEPENDENCY_SNAPSHOT_STALE` naming the fix: run `meta deps sync`.
- **`--codegen`** — regeneration drift. Re-runs generation and diffs the result
against the committed generated files; a stale generated part (someone skipped a
regen) fails the build. Wire it into CI so a stale `@generated` file fails.
**A hand edit inside a generated file is NOT drift** — `meta gen` three-way-merges
hand edits by design, and the Node gate judges the *generated contribution* against
the committed `.metaobjects/.gen-state/.hashes.json`, not the bytes. So a weakened
validator passes this gate. The Node `meta verify --codegen` therefore LISTS every
generated file carrying a hand edit (count + paths, a notice that does not change
the exit code), and `--forbid-hand-edits` turns any hand edit into a failure for a
team that wants generated code untouchable. Read that list at review time. To see
one edit: delete the file, run `meta gen` (it re-emits the pristine generation),
then `git diff -R -- <file>`; `git checkout -- <file>` restores it. The one
exception is an `<Entity>.names.ts` artifact: a hand edit there always fails.
**A hand edit inside a generated file is reported apart from drift** — `meta gen`
three-way-merges hand edits by design, and the Node gate judges the *generated
contribution* against the committed `.metaobjects/.gen-state/.hashes.json`, not the
bytes, then lists every generated file carrying a hand edit (count + paths). Whether
that list fails the build is `verify.handEdits` in `.metaobjects/config.json`:
`"fail"` exits 1 (what `meta init` writes for a new project), `"notice"` (and a
project without the key) exits 0, so a weakened validator passes there. Check the
key; `--allow-hand-edits` relaxes `fail` for one run, `--forbid-hand-edits` forces it
for one run. If an edit changed a rule the model declares (a length, a range, a
required field), make the change in the metadata instead, so the database and every
port follow it. To see one edit: delete the file, run `meta gen` (it re-emits the
pristine generation), then `git diff -R -- <file>`; `git checkout -- <file>`
restores it. An `<Entity>.names.ts` artifact always fails on a hand edit. The C#,
Java, Kotlin and Python gates compare bytes, so any edit fails there.

- **`--templates`** — prompt/payload drift. For every `template.prompt` /
`template.output`, resolves the text, parses each `{{...}}` reference, and fails
Expand Down
8 changes: 4 additions & 4 deletions docs/CONFORMANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l` for directory-shaped corpor
| [`fixtures/jinja-verify-conformance/`](../fixtures/jinja-verify-conformance/) (ADR-0061 — the payload check over a Jinja body) | 31 | ✓ | refuses Jinja | refuses, via Java | refuses Jinja | ✓ |
| [`fixtures/extract-conformance/`](../fixtures/extract-conformance/) | 58 | ✓ | ✓ | inherits the shared JVM engine | ✓ | ✓ |
| [`fixtures/output-prompt-conformance/`](../fixtures/output-prompt-conformance/) | 17 | ✓ | ✓ | ✓ | ✓ | ✓ |
| [`fixtures/persistence-conformance/`](../fixtures/persistence-conformance/) | 62 (55 query + 7 migration) | all 62; the 24 `report-*` and the `-15` decimal scenarios also on SQLite, MySQL and D1, `decimal-exact` also on MySQL (a scenario's `engines:` key is exact) | 55 query (migrations TS-only, ADR-0015); the `report-*` and `engines:` scenarios also on SQLite and MySQL | 55 query (via Exposed); the `report-*` and `engines:` scenarios also on SQLite and MySQL | 55 query; the `report-*` and `engines:` scenarios also on SQLite and MySQL | 55 query (pg8000); the `report-*` and `engines:` scenarios also on SQLite (`sqlite3`) and MySQL (PyMySQL) |
| [`fixtures/persistence-conformance/`](../fixtures/persistence-conformance/) | 64 (55 query + 9 migration) | all 64; the 24 `report-*` and the `-15` decimal scenarios also on SQLite, MySQL and D1, `decimal-exact` also on MySQL (a scenario's `engines:` key is exact) | 55 query (migrations TS-only, ADR-0015); the `report-*` and `engines:` scenarios also on SQLite and MySQL | 55 query (via Exposed); the `report-*` and `engines:` scenarios also on SQLite and MySQL | 55 query; the `report-*` and `engines:` scenarios also on SQLite and MySQL | 55 query (pg8000); the `report-*` and `engines:` scenarios also on SQLite (`sqlite3`) and MySQL (PyMySQL) |
| [`fixtures/api-contract-conformance/`](../fixtures/api-contract-conformance/) | 123 (31 core + 10 tph + 9 m2m + 5 jsonb + 2 write-through + 2 secret-fields + 2 enum-default + 12 projection + 37 report + 11 decimal + 2 duration) | ✓ (Fastify reference + generated lane); `report/`, `decimal/` and `duration/` also on SQLite, MySQL and D1 | ✓ (embedded HTTP + JDBC); `report/`, `decimal/` and `duration/` generated controllers over OMDB on Postgres, SQLite and MySQL | ✓ (embedded HTTP + Exposed); `report/`, `decimal/` and `duration/` also on SQLite and MySQL | ✓ (Kestrel + Npgsql); `report/`, `decimal/` and `duration/` also on SQLite and MySQL | ✓ (FastAPI + pg8000); `report/`, `decimal/` and `duration/` also on SQLite and MySQL |
| [`fixtures/decimal-wire/`](../fixtures/decimal-wire/) | 1 vector file (format, parse, filter operand, 15-digit read) | ✓ (`runtime-ts` and the generated helper) | ✓ (`CanonicalDecimal`) | ✓ (the generated wire file) | ✓ (`DecimalWire`) | ✓ (`decimal_wire`) |
| [`fixtures/duration-wire/`](../fixtures/duration-wire/) | 1 vector file: the `wire` vectors (parse, precision, refused) every port passes, and the `codecs` groups (Postgres text read and write, stored microseconds) each port passes only for the codecs it has | ✓ (`metadata` / `runtime-ts` and the generated helper) | ✓ | ✓ | ✓ | ✓ |
Expand Down Expand Up @@ -423,9 +423,9 @@ All 37 fixtures → [features/migrations-and-drift.md](features/migrations-and-d
may carry `"isArray": true`; with `fields` it is a list of objects, without it a list of
scalars. The six `verify-positional-accessor-*` cases pin where `-last` is available.

### `fixtures/persistence-conformance/` (62 — 55 query + 7 migration)
### `fixtures/persistence-conformance/` (64 — 55 query + 9 migration)

- `migrations/*` (7) → [features/migrations-and-drift.md](features/migrations-and-drift.md) (schema migration section)
- `migrations/*` (9) → [features/migrations-and-drift.md](features/migrations-and-drift.md) (schema migration section)
- `queries/*` (55) → [features/source-kinds.md](features/source-kinds.md) (query semantics against `source.rdb`)

**Engines beyond Postgres (FR-044 reports, decimals).** The twenty-four `queries/report-*.yaml`
Expand Down Expand Up @@ -725,7 +725,7 @@ JSON and verify payload feeds it unchanged.
## Orphaned fixtures (tested but not yet documented)

The fixtures in the nine corpora mapped above (metamodel 510 + yaml 16 + verify 45
+ render 18 + persistence 62 + api-contract 123 + source-resolution 25 + scope 10 +
+ render 18 + persistence 64 + api-contract 123 + source-resolution 25 + scope 10 +
dependency 47) each map to a feature doc, and so do the two requirement corpora, `shared-model-conformance`, the
`cube-model` corpus and `explorer-conformance`, whose case lists live in their own READMEs. None are orphaned today. The remaining
corpora in the totals table gate tooling contracts (registry manifests, provider
Expand Down
2 changes: 1 addition & 1 deletion docs/features/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ vocabulary everywhere, each port implementing the modes it supports.
| Subverb | What it checks | Touches a DB? |
|---|---|---|
| `verify --db` | **Schema drift** — does the live database (or snapshot) match the metadata? (migrate engine, ADR-0015) | yes |
| `verify --codegen` | **Codegen drift** — regenerate from metadata into a temp dir and fail if it differs from the committed generated output. Catches "metadata changed but `meta gen` wasn't re-run". A hand-edited generated file is NOT drift — `meta gen` three-way-merges hand edits by design, so the gate compares the *generated contribution* against the committed `.gen-state/.hashes.json` rather than the file byte-for-byte. It still LISTS every generated file carrying a hand edit (count + paths, and how to see the edit) as a notice that does not change the exit code; `--forbid-hand-edits` makes any hand edit fail the build, for teams that want generated code untouchable (Node `meta` only). | no |
| `verify --codegen` | **Codegen drift** — regenerate from metadata into a temp dir and fail if it differs from the committed generated output. Catches "metadata changed but `meta gen` wasn't re-run". **A hand-edited generated file** (Node `meta`): `meta gen` three-way-merges hand edits, so the gate compares the *generated contribution* against the committed `.gen-state/.hashes.json` and reports each edited file separately, by path, with how to see the edit and how to drop it. What that report does to the exit code is the `verify.handEdits` key in `.metaobjects/config.json`: `"fail"` exits 1, `"notice"` (and a project without the key, as before 1.3) prints it and exits 0. `meta init` writes `"fail"` for a new project. `--allow-hand-edits` relaxes `fail` to a notice for one run; `--forbid-hand-edits` makes a hand edit fail for one run whatever the key says. The other ports compare the generated files byte for byte, so any edit is drift and fails: `dotnet meta verify --codegen`, `mvn metaobjects:verify` (Java and Kotlin) and `metaobjects verify --codegen` each exit non-zero and name the file. | no |
| `verify --templates` | **Template/prompt drift** — `Renderer.verify` checks each `template.*` node's `{{field}}` references against its payload VO (FR-004). A Jinja body (Python and TypeScript, ADR-0061) is checked the same way. | no |
| `verify --docs` | **Removed in 1.1.0** (ADR-0034 Amendment 9). It prints where the check went and exits 2: documentation is written by entries in `generators`, so `verify --codegen` checks it with the rest of the declared output. | — |
| `verify --deps` | **Dependency drift** (FR-023) — re-resolves each declared dependency (its `path`, its installed `npm` / `python` package, or its `maven` / `nuget` package in the local cache) and compares its installed artifact's hash against `.metaobjects/deps.lock.json`, same comparison as `meta deps check`. Needs the publisher reachable, so it is never part of the bare-`verify` default. A `drifted` or `unresolved` dependency fails with `ERR_DEPENDENCY_UPSTREAM_DRIFT`. **Node `meta`; Python (`metaobjects verify --deps`, plus `metaobjects deps check`), C# (`dotnet meta verify --deps`), and Java and Kotlin (`-Dmeta.verify.mode=deps`) have the `path`-only counterpart.** See [`metadata-dependencies.md`](metadata-dependencies.md). | no |
Expand Down
5 changes: 3 additions & 2 deletions docs/features/cube-export.md
Original file line number Diff line number Diff line change
Expand Up @@ -582,8 +582,9 @@ there.
**`meta verify --codegen`** regenerates the configured output into a temporary directory and
compares it with the committed files. The Cube project is a target, so its files are checked
like any other generated output: a changed model that was not regenerated, a missing cube file
and a stale one are drift. A hand edit to a generated file is not drift, but the gate lists it, and
`meta verify --codegen --forbid-hand-edits` makes it fail.
and a stale one are drift. A hand edit to a generated file is reported by path, and fails the gate
when `.metaobjects/config.json` sets `"verify": { "handEdits": "fail" }` (what `meta init` writes)
or the run passes `--forbid-hand-edits`.

**The mapping corpus** is [`fixtures/cube-model/`](../../fixtures/cube-model/): 46 cases, each
the smallest model for one rule, 36 with the exact tree the generator writes and 10 with the
Expand Down
2 changes: 2 additions & 0 deletions docs/features/language-differences.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ project.
| **Field names on the wire** | The model's names, in every port | | | | |
| **Decimals and null members on the wire** | Each port writes its serializer's default; a `wire` setting makes them identical. The per-port table is under [The wire setting](api-contract.md#the-wire-setting) | | | | |
| **Hand edits to a generated file** | Merged (three-way) on the machine that generated it; refused by name elsewhere | Refused by name, or overwritten with `WithHandEdits(HandEdits.Overwrite)` | Refused by name, or overwritten with `<handEdits>overwrite</handEdits>` | Same as Java | Refused by name, or overwritten with `handEdits: overwrite` |
| **`verify --codegen` on a hand-edited generated file** | Set by `verify.handEdits`: `"fail"` (what `meta init` writes) exits 1, `"notice"` or no key reports the file and exits 0; `--allow-hand-edits` / `--forbid-hand-edits` change it for one run | Byte comparison: any edit is drift and fails | Same as C# | Same as C# | Same as C# |
| **Foreign-key indexes (`migrate.foreignKeyIndexes`)** | `meta migrate` creates them; the Drizzle and Prisma mappings declare them | The `AppDbContext` declares them | No index mapping to declare | The Exposed tables declare them | No index mapping to declare |
| **Own a generator** | `npx meta eject` | `dotnet meta eject` | `mvn metaobjects:eject` | `mvn metaobjects:eject` | `metaobjects eject` |
| **Requirement authoring lint** | Yes (advisory) | No | No | No | No |

Expand Down
5 changes: 3 additions & 2 deletions docs/features/metadata-sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -355,8 +355,9 @@ out-of-scope table that already exists would become a proposed `DROP TABLE`.
### `migrate.conventions` — names for objects no code addresses

Beside `scope`, the `migrate` block takes `conventions`: the name of a schema-conventions preset
that decides primary-key and foreign-key constraint names, whether a foreign key gets an index,
and whether a unique key is an index or a constraint. `default` (absent) is what migrate has
that decides primary-key and foreign-key constraint names, whether a foreign key gets an index
(without a preset, [`migrate.foreignKeyIndexes`](migrations-and-drift.md#foreign-key-indexes-migrateforeignkeyindexes)
indexes foreign keys), and whether a unique key is an index or a constraint. `default` (absent) is what migrate has
always emitted; `efcore` is a reference preset that reproduces EF Core's naming. A project can
supply its own conventions from `metaobjects.config.ts` instead. Table, view and column names are
not conventions: they come from `naming`. See
Expand Down
Loading
Loading