Skip to content

Commit 26a841f

Browse files
committed
feat: fail verify on hand edits and index foreign keys on request (1.3.0 PRs 6-7)
verify.handEdits in .metaobjects/config.json: "fail" makes `meta verify --codegen` exit 1 on a hand-edited generated file, naming the file and both remedies; --allow-hand-edits relaxes it for one run, --forbid-hand-edits still forces it. A project without the key keeps the notice and exit 0; `meta init` writes "fail". The C#, Java, Kotlin and Python gates already byte-compare and fail; the docs now say so. migrate.foreignKeyIndexes: every foreign key nothing already leads with gets a plain <table>_<columns>_idx index, separate from the efcore preset (which indexes them already and so adds nothing). Honoured by meta migrate / verify --db, the Drizzle reference template, the C# DbContext generator and the Kotlin Exposed table generator; Java OMDB and Python map no indexes. `meta init` writes it on; projects without it are unchanged and keep the advisory, which now names the option. Persistence corpus gains two migration scenarios. C# gen and both verify --codegen paths pass foreignKeyIndexes and conventions.
1 parent f8a1dc5 commit 26a841f

68 files changed

Lines changed: 1629 additions & 149 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,27 @@ loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersi
3535
one over measures as a `number` member (one reading a dimension is refused). Loader rule M11,
3636
report rule R13 and a conformance fixture per refusal, in every loader port.
3737

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

4061
- **Breaking, TypeScript: a value object is never renamed; one claim registry refuses real
@@ -56,6 +77,10 @@ loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersi
5677
a barrel) now fail with the collision error; set `outputLayout: "package"` (and drop the barrel,
5778
or rename one), and update imports of the old `AcmeAlphaNote` names. An owned generator copy is
5879
refreshed with `meta eject --list`.
80+
- **`meta init` writes stricter defaults for a new project.** The scaffolded
81+
`.metaobjects/config.json` now carries `"verify": { "handEdits": "fail" }` and (except on
82+
MySQL) `"migrate": { "foreignKeyIndexes": true }`, each as its own visible setting. An existing
83+
config is left as it is.
5984
- **Agent context routes report work to the reporting vocabulary.** The `meta init` agent guide
6085
and the `metaobjects-authoring` skill now send grouped totals, dashboard numbers and read-only
6186
report views to `object.report` (`references/declaring-reports.md`) before the `@sql` escape,

‎agent-context/skills/metaobjects-verify/SKILL.md‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -150,16 +150,20 @@ with `ERR_DEPENDENCY_SNAPSHOT_STALE` naming the fix: run `meta deps sync`.
150150
- **`--codegen`** — regeneration drift. Re-runs generation and diffs the result
151151
against the committed generated files; a stale generated part (someone skipped a
152152
regen) fails the build. Wire it into CI so a stale `@generated` file fails.
153-
**A hand edit inside a generated file is NOT drift** — `meta gen` three-way-merges
154-
hand edits by design, and the Node gate judges the *generated contribution* against
155-
the committed `.metaobjects/.gen-state/.hashes.json`, not the bytes. So a weakened
156-
validator passes this gate. The Node `meta verify --codegen` therefore LISTS every
157-
generated file carrying a hand edit (count + paths, a notice that does not change
158-
the exit code), and `--forbid-hand-edits` turns any hand edit into a failure for a
159-
team that wants generated code untouchable. Read that list at review time. To see
160-
one edit: delete the file, run `meta gen` (it re-emits the pristine generation),
161-
then `git diff -R -- <file>`; `git checkout -- <file>` restores it. The one
162-
exception is an `<Entity>.names.ts` artifact: a hand edit there always fails.
153+
**A hand edit inside a generated file is reported apart from drift** — `meta gen`
154+
three-way-merges hand edits by design, and the Node gate judges the *generated
155+
contribution* against the committed `.metaobjects/.gen-state/.hashes.json`, not the
156+
bytes, then lists every generated file carrying a hand edit (count + paths). Whether
157+
that list fails the build is `verify.handEdits` in `.metaobjects/config.json`:
158+
`"fail"` exits 1 (what `meta init` writes for a new project), `"notice"` (and a
159+
project without the key) exits 0, so a weakened validator passes there. Check the
160+
key; `--allow-hand-edits` relaxes `fail` for one run, `--forbid-hand-edits` forces it
161+
for one run. If an edit changed a rule the model declares (a length, a range, a
162+
required field), make the change in the metadata instead, so the database and every
163+
port follow it. To see one edit: delete the file, run `meta gen` (it re-emits the
164+
pristine generation), then `git diff -R -- <file>`; `git checkout -- <file>`
165+
restores it. An `<Entity>.names.ts` artifact always fails on a hand edit. The C#,
166+
Java, Kotlin and Python gates compare bytes, so any edit fails there.
163167

164168
- **`--templates`** — prompt/payload drift. For every `template.prompt` /
165169
`template.output`, resolves the text, parses each `{{...}}` reference, and fails

‎docs/CONFORMANCE.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l` for directory-shaped corpor
3535
| [`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 | ✓ |
3636
| [`fixtures/extract-conformance/`](../fixtures/extract-conformance/) | 58 | ✓ | ✓ | inherits the shared JVM engine | ✓ | ✓ |
3737
| [`fixtures/output-prompt-conformance/`](../fixtures/output-prompt-conformance/) | 17 | ✓ | ✓ | ✓ | ✓ | ✓ |
38-
| [`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) |
38+
| [`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) |
3939
| [`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 |
4040
| [`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`) |
4141
| [`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) | ✓ | ✓ | ✓ | ✓ |
@@ -423,9 +423,9 @@ All 37 fixtures → [features/migrations-and-drift.md](features/migrations-and-d
423423
may carry `"isArray": true`; with `fields` it is a list of objects, without it a list of
424424
scalars. The six `verify-positional-accessor-*` cases pin where `-last` is available.
425425

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

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

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

727727
The fixtures in the nine corpora mapped above (metamodel 510 + yaml 16 + verify 45
728-
+ render 18 + persistence 62 + api-contract 123 + source-resolution 25 + scope 10 +
728+
+ render 18 + persistence 64 + api-contract 123 + source-resolution 25 + scope 10 +
729729
dependency 47) each map to a feature doc, and so do the two requirement corpora, `shared-model-conformance`, the
730730
`cube-model` corpus and `explorer-conformance`, whose case lists live in their own READMEs. None are orphaned today. The remaining
731731
corpora in the totals table gate tooling contracts (registry manifests, provider

‎docs/features/cli.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ vocabulary everywhere, each port implementing the modes it supports.
5353
| Subverb | What it checks | Touches a DB? |
5454
|---|---|---|
5555
| `verify --db` | **Schema drift** — does the live database (or snapshot) match the metadata? (migrate engine, ADR-0015) | yes |
56-
| `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 |
56+
| `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 |
5757
| `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 |
5858
| `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. | — |
5959
| `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 |

‎docs/features/cube-export.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -582,8 +582,9 @@ there.
582582
**`meta verify --codegen`** regenerates the configured output into a temporary directory and
583583
compares it with the committed files. The Cube project is a target, so its files are checked
584584
like any other generated output: a changed model that was not regenerated, a missing cube file
585-
and a stale one are drift. A hand edit to a generated file is not drift, but the gate lists it, and
586-
`meta verify --codegen --forbid-hand-edits` makes it fail.
585+
and a stale one are drift. A hand edit to a generated file is reported by path, and fails the gate
586+
when `.metaobjects/config.json` sets `"verify": { "handEdits": "fail" }` (what `meta init` writes)
587+
or the run passes `--forbid-hand-edits`.
587588

588589
**The mapping corpus** is [`fixtures/cube-model/`](../../fixtures/cube-model/): 46 cases, each
589590
the smallest model for one rule, 36 with the exact tree the generator writes and 10 with the

0 commit comments

Comments
 (0)