Skip to content

feat(codegen): skip generation when the model and generators are unchanged (ADR-0064) - #590

Merged
dmealing merged 8 commits into
mainfrom
fm/mo-codegen-skip-main
Nov 15, 2026
Merged

dmealing merged 8 commits into
mainfrom
fm/mo-codegen-skip-main

Conversation

@dmealing

@dmealing dmealing commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

Forward-port of PR 585

This is a forward-port to main of #585 (commit b9bc9c733 on release/1.2), so 1.3 skips generation when metadata, templates and generator settings are unchanged, in every port. It is meant to be a faithful port: behavior PR 585 already has on release/1.2 is carried over unchanged.

  • Skip ADR: numbered ADR-0064 on main (it was ADR-0062 on release/1.2; main already uses 0062 and 0063, which are not renumbered). Every reference was updated.
  • Includes b6dec3694: the merge fast-path tests (merge-fastpath.test.ts) from that commit are part of this change.
  • Kept from main: PR 584 (manifest written once, ctx.selected) and PR 588 (uniform entity selection). The skip layers on top of both.
  • Narrowed runs, uniform in all ports: a run that names entities (meta gen A B, --entities, -Dmeta.entities) forces exactly those entities. It never skips, never stores a key, and leaves the stored full-run key alone. A test per port covers it.
  • Changelog: one 1.3.0 entry: generation now skips when nothing changed.

Hand-resolved files (31 files that conflicted against main)

  • Docs and fixtures: AGENTS.md, CHANGELOG.md, agent-context/skills/metaobjects-fit-assessment/references/capability-sheet.md, docs/CONFORMANCE.md, docs/features/cli.md, docs/llms/llms-full.txt, docs/recipes/write-your-own-generator.md, examples/showcase/site-payload.json, spec/decisions/README.md, and the two fixtures/agent-context-conformance/ts-requirements/ reference files (resolved by dropping them, since main does not have that fixture).
  • TypeScript: server/typescript/packages/cli/src/{commands/gen.ts,commands/verify.ts,index.ts,lib/args.ts,lib/codegen-drift.ts}, cli/test/unit/args-verify.test.ts, codegen-ts/src/{index.ts,overwrite-policy.ts,runner.ts,generators/docs-site-file.ts}.
  • Python: server/python/src/metaobjects/{cli.py,codegen/overwrite_policy.py,codegen/runner.py}.
  • C#: server/csharp/MetaObjects.Cli/Program.cs, MetaObjects.Codegen/{CodegenCli.cs,CodegenDrift.cs,CodegenRunner.cs,Generator.cs}.
  • Java: server/java/maven-plugin/src/main/java/com/metaobjects/mojo/{MetaDataGeneratorMojo.java,MetaDataVerifyMojo.java}.

Ports a regression fix not present in 585

A skipped meta gen in TypeScript returned before the ADR-0023 unknown-attribute advisory, so a typo'd attribute produced no warning on a skipped run (Python and C# already warned before skipping). The advisory is now printed before the skip, the skipped --format json document carries the warnings, and a regression test covers both. This is not in PR 585. The one other main-specific gap found and fixed: the C# agent-context conformance fixture (a file release/1.2 does not have) now says "regenerate in memory".

Known residuals (carried from 585, not changed here)

  • Java model key: ModelKey keys its nodes by type and name, so two root nodes with the same type and name in different packages would collide. It is latent: the whole-run skip uses only the model-level hash, and the per-object keys that would need package-qualified node keys are not part of this change. The other ports key by resolution key. Changing Java's key here would make it diverge from 1.2.
  • Outputs outside the project root: these are guarded by existence only, in every port (ADR-0064 sections 3 and 4). A hand edit to such a file after the last run is skipped over by gen, and a local verify --codegen may answer "no drift" from the key. CI always renders.

Validation runs

One no-mistakes validation run (review and test fix rounds happened inside that same run; one run per PR). The "2 runs" in the Testing block below refers to rounds inside it.


What Changed

  • Forward-ports the 1.2.x generation-skip change (ADR-0064, numbered ADR-0062 on release/1.2) to main: every port's gen (meta gen, metaobjects gen, dotnet meta gen, mvn metaobjects:generate) now builds a fingerprint from the loaded model (canonical effective form per root node), each generator's identity (built engine code, config, owned generators, templates, declared extra inputs) and the output-changing flags — and skips rendering and writing entirely when it matches the last successful run and every recorded generated file still holds its bytes. The key lives uncommitted in .metaobjects/.gen-state/.fingerprint-<port>.json; --force (JVM: -Dmetaobjects.force=true) renders everything, and a generator that cannot declare its inputs opts out via cache: false. Runs that name entities never skip and never touch the full-run key. Behavior is carried over unchanged from release/1.2, including the Java model key (nodes keyed by type and name) and the existence-only guard for generated files outside the project root.
  • Hardened the write path in every port: the .hashes.json manifest is now loaded once and saved at most once per run (only when an entry changed), a generated file whose fresh bytes equal what is on disk is never rewritten, TypeScript runs git merge-file only for hand-edited files, and Python no longer reports unchanged files as written. Local verify --codegen may answer "no drift" from the same fingerprint (--full forces a render; CI always renders), and rendered comparisons happen in memory with no temp tree.
  • Added the shared fixtures/codegen-skip-conformance/ case table (cases.json), run by all five ports (TS, Python, C#, Java/Kotlin Maven) with per-port test suites, plus ADR-0064, the --force flag on every port's CLI, and documentation updates (docs/features/cli.md, codegen-concepts.md, port docs, agent-context skill references and their conformance fixtures).
Validation

Risk Assessment

✅ Low: The uncertified fix-round commits are small and correct: the advisory and warnings now precede and accompany the skip, with regression tests asserting real CLI output and state. The only open items are two explicitly user-ignored, intent-sanctioned PR 585 carry-overs.

Testing

Baseline regression came from the configured command scripts/ci-local.sh --affected --strict-toolchains, which passed at this commit. I then drove the changed behavior directly: built a disposable metadata project in $DEV_SCRATCH and ran the real meta CLI (via bun on the worktree bin) six times — first run generates, unchanged rerun skips, a metadata change regenerates, deleting a recorded output re-emits instead of skipping, and a typo'd unknown attribute on a skipped run is still warned on stderr and carried in the json document. Every scenario passed; the CLI surface is text-only so no visual artifacts apply, and transcripts plus the raw stderr/json outputs are saved as evidence.

  • Live validation: ✅ go - 3 of 3 scenarios driven live against the product
Scenario Result Live Evidence
meta gen skips when metadata is unchanged and regenerates when it changes (disposable project, sqlite entity generator) ✅ pass live meta-gen-skip-transcript.md RUNS 1-4: fresh run writes 2 files; immediate rerun answers skipped:true/upToDate:2 with nothing rendered; adding a room field regenerates Talk.ts (4 occurrences of room)…
Adversarial: deleting a recorded generated output defeats the skip (wrong-direction guard) — gen re-emits instead of skipping ✅ pass live meta-gen-skip-transcript.md RUN 5: after rm generated/Talk.ts, gen answers generated/Talk.ts,new — 1 written and the file is restored on disk
A typo'd unknown attribute added after the stored key still gets named on a skipped run, on stderr and in the --format json document ✅ pass live meta-gen-skip-transcript.md RUN 6 plus the two raw artifacts: skipped:true while stderr and the json document both carry the ERR_UNKNOWN_ATTR isAbstrakt warning and the ADR-0023 verify advice
Evidence: Live CLI transcript: gen → skip → regen → skip → deleted-output regen → typo-warn-on-skip
# meta gen skip (ADR-0064 forward-port) — live CLI transcript
CLI: bun <worktree>/server/typescript/packages/cli/bin/meta.ts  (target commit 8ef2c85a3)
Disposable project: $DEV_SCRATCH/mo-skip-live-164928 (entity Talk extends abstract BaseThing, generators: ["entity"])

## RUN 1 — fresh project
$ bun meta.ts gen --cwd $PROJ   → exit 0
  generated/BaseThing.ts,new  generated/Talk.ts,new  — summary: 2 written

## RUN 2 — unchanged → SKIP
$ bun meta.ts gen --cwd $PROJ   → exit 0
  summary: "nothing changed since the last meta gen, so nothing was rendered or written"
  skipped: true   upToDate: 2

## RUN 3 — metadata changed (room field added to Talk) → REGEN
  generated/Talk.ts,overwrite  — summary: 1 written, 1 unchanged; regenerated Talk.ts contains room (4 occurrences)

## RUN 4 — unchanged again → SKIP (skipped: true, upToDate: 2)

## RUN 5 — deleted generated/Talk.ts → REGEN not skip
  generated/Talk.ts,new  — summary: 1 written, 1 unchanged; Talk.ts restored on disk

## RUN 6 — bare typo'd key isAbstrakt:true added (lenient load drops it; skip key still matches) → SKIP that still warns
text mode stderr:
  meta: warning: ERR_UNKNOWN_ATTR: Unknown key 'isAbstrakt' on object.entity 'BaseThing' ... in meta.app.json ...
  meta: warning: ... `meta verify` rejects this metadata (ADR-0023) ... `meta gen --strict` stops the run instead.
json mode document:
  skipped: true
  warnings[0]: "ERR_UNKNOWN_ATTR: Unknown key isAbstrakt on object.entity BaseThing ..."
  warnings[1]: "meta gen loads leniently and generated anyway, but `meta verify` rejects this metadata (ADR-0023) ..."
Evidence: Skipped-run json document carrying warnings (isAbstrakt advisory)

{ "gen": [], "summary": "nothing changed since the last meta gen...", "skipped": true, "upToDate": 2, "warnings": [ "ERR_UNKNOWN_ATTR: Unknown key 'isAbstrakt' on object.entity 'BaseThing' ... in meta.app.json ...", "meta gen loads leniently and generated anyway, but meta verify rejects this metadata (ADR-0023) ..." ] }

{
  "gen": [],
  "summary": "nothing changed since the last meta gen, so nothing was rendered or written",
  "help": [
    "meta gen --force regenerates everything"
  ],
  "antiPatterns": {
    "status": "skipped",
    "note": "not run: nothing changed since the last meta gen",
    "total": 0,
    "rows": []
  },
  "skipped": true,
  "upToDate": 2,
  "warnings": [
    "ERR_UNKNOWN_ATTR: Unknown key 'isAbstrakt' on object.entity 'BaseThing' at metadata.root.children[0].object.entity (must be reserved or @-prefixed)\n  in meta.app.json at $['metadata.root'].children[0]['object.entity']",
    "meta gen loads leniently and generated anyway, but `meta verify` rejects this metadata (ADR-0023): fix or remove the attribute — a typo'd one (`isAbstrakt`, `@requird`) silently changes what is generated. `meta gen --strict` stops the run instead."
  ]
}
Evidence: Skipped-run stderr in text mode (same two warnings)
meta: warning: ERR_UNKNOWN_ATTR: Unknown key 'isAbstrakt' on object.entity 'BaseThing' at metadata.root.children[0].object.entity (must be reserved or @-prefixed)
  in meta.app.json at $['metadata.root'].children[0]['object.entity']
meta: warning: meta gen loads leniently and generated anyway, but `meta verify` rejects this metadata (ADR-0023): fix or remove the attribute — a typo'd one (`isAbstrakt`, `@requird`) silently changes what is generated. `meta gen --strict` stops the run instead.
  • Outcome: 🔧 3 issues found → auto-fixed ✅ across 2 runs (1h17m36s)

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 4 issues found → auto-fixed (2) → no changes applied (3) ✅
  • ⚠️ docs/features/own-your-codegen.md:373 - The edit that replaced "writes into a temporary tree and ctx.projectRoot is that tree" left a stray "tree." behind, garbling the sentence ("...ctx.projectRoot is the real project root, tree."). Fixed inline during this pass: the sentence now reads "...is the real project root." with the leftover removed.
  • ⚠️ server/typescript/packages/cli/README.md:130 - The new --force bullet links to docs/features/cli.md with the anchor suffix adr-0062 (the 1.2.x ADR number), but the heading on main is "(ADR-0064)" — a broken deep link. Fixed inline during this pass: anchor changed from adr-0062 to adr-0064.
  • ⚠️ server/java/maven-plugin/src/main/java/com/metaobjects/mojo/ModelKey.java:41 - ModelKey.of keys its nodes map by unqualified type.subType + &#34; &#34; + name, so two root-level nodes with the same type and name in different packages collide and the last silently overwrites the first in nodes. Today this is latent: the whole-run skip uses only tree.model(), and the per-package lines that feed it carry both entries, so no wrong skip is reachable. But ADR-0064 §6 plans per-object/per-package keys built from exactly these node hashes, and there a same-name cross-package pair drops one sibling — the wrong-direction failure the ADR forbids. The other ports do not share the flaw: TS model-hash.ts keys nodes by resolutionKey(), Python model_key.py by resolution_key(), C# ModelHash keeps both nodes (package is a separate record field). Remedy: key the Java map by the child's resolution key (package-qualified), matching the siblings.
  • ⚠️ server/typescript/packages/cli/src/lib/gen-fingerprint.ts:483 - Generated files written outside the project root (the manifest records none of them) are guarded by existence only, in every port: gen-fingerprint.ts:483-485 (TS), skip.py untracked_exist (Python), GenFingerprint.cs CanSkipGen stored.Untracked.All(File.Exists) (C#), AbstractMetaDataMojo.java fingerprintMatches untracked loop (Java). So a hand EDIT to an outside-project output after the last run is skipped over by gen (pre-ADR gen would have restored it via the outside-file auto-overwrite policy) and, because it is not in the manifest, a local verify --codegen may also answer "no drift" from the key without rendering. This is the behavior ADR-0064 §3/§4 explicitly specify ("the manifest records none of them, so a skip needs each to still exist"), and CI always renders — so it is a documented residual, not a contradiction. A cheap follow-up that closes it: at store time also record the sha256 of each untracked path as the run left it (the run knows the bytes it wrote) and compare content, not just existence. Reported for the record; no action required for this PR.

🔧 No changes applied.
4 issues (3 warnings, 1 info) still open:

  • ⚠️ server/java/maven-plugin/src/main/java/com/metaobjects/mojo/ModelKey.java:41 - ModelKey.of keys its nodes map by unqualified type.subType + &#34; &#34; + name, so two root-level nodes with the same type and name in different packages collide and the last silently overwrites the first in nodes. Today this is latent: the whole-run skip uses only tree.model(), and the per-package lines that feed it carry both entries, so no wrong skip is reachable. But ADR-0064 §6 plans per-object/per-package keys built from exactly these node hashes, and there a same-name cross-package pair drops one sibling — the wrong-direction failure the ADR forbids. The other ports do not share the flaw: TS model-hash.ts keys nodes by resolutionKey(), Python model_key.py by resolution_key(), C# ModelHash keeps both nodes (package is a separate record field). Remedy: key the Java map by the child's resolution key (package-qualified), matching the siblings.
  • ⚠️ server/typescript/packages/cli/src/lib/gen-fingerprint.ts:483 - Generated files written outside the project root (the manifest records none of them) are guarded by existence only, in every port: gen-fingerprint.ts:483-485 (TS), skip.py untracked_exist (Python), GenFingerprint.cs CanSkipGen stored.Untracked.All(File.Exists) (C#), AbstractMetaDataMojo.java fingerprintMatches untracked loop (Java). So a hand EDIT to an outside-project output after the last run is skipped over by gen (pre-ADR gen would have restored it via the outside-file auto-overwrite policy) and, because it is not in the manifest, a local verify --codegen may also answer "no drift" from the key without rendering. This is the behavior ADR-0064 §3/§4 explicitly specify ("the manifest records none of them, so a skip needs each to still exist"), and CI always renders — so it is a documented residual, not a contradiction. A cheap follow-up that closes it: at store time also record the sha256 of each untracked path as the run left it (the run knows the bytes it wrote) and compare content, not just existence. Reported for the record; no action required for this PR.
  • ⚠️ server/typescript/packages/cli/src/commands/gen.ts:241 - The ADR-0064 skip block returns 0 at gen.ts:241-244, BEFORE the ADR-0023 unknown-attribute advisory is built and printed at gen.ts:247-257 — so a run that skips renders no warning. Concrete reachable sequence: a project whose last meta gen stored a key; the user adds a typo'd attribute (isAbstrakt: true or @requird: true) to a metadata file and runs meta gen. The lenient loader drops the unknown attribute from the loaded tree (sdk/src/memory.ts:192-195 — findings come from a separate strict pass), so modelHashTree(loaded.root) is unchanged, the key still matches, the recorded outputs are untouched, and gen answers "nothing changed since the last meta gen" — silently. The advisory whose whole purpose is to name that typo on the gen path never prints. This is both a regression of established behavior (the ADR-0023 advisory was added precisely because "the typo changed what was generated" and gen is the command users run) and a cross-port divergence: Python prints _print_unknown_attr_warnings at server/python/src/metaobjects/cli.py:2017, before its skip check at cli.py:2052, and C# calls WarnUnknownAttrs(meta) at server/csharp/MetaObjects.Codegen/CodegenCli.cs:809, before its skip at CodegenCli.cs:826. Sibling sites checked and NOT affected: C# (CodegenCli.cs:809→826) and Python (cli.py:2017→2052) both warn-then-skip; the Java mojo loads strictly per its own config and has no lenient-warning path to lose. Fix: move the skip decision below the warning-emission block (or print the collected warnings before the skip return) in gen.ts; the skip itself is correct — only its position relative to the advisory is wrong.
  • ℹ️ server/java/maven-plugin/src/main/java/com/metaobjects/mojo/AbstractMetaDataMojo.java:576 - The Javadoc on planWholeRun said "Decide, before anything loads, whether this run can be skipped", contradicting both the code (the model IS loaded for its key, via ModelKey.of(loader) inside fingerprintInputs) and the call-site comment at AbstractMetaDataMojo.java:504-506 ("the metadata is loaded (the model key is made of it)"). A leftover from an earlier iteration. Fixed inline during this pass: the comment now says the metadata is loaded and nothing has rendered yet, and names ModelKey#of.

🔧 Fix applied.
4 issues (3 warnings, 1 info) still open:

  • ⚠️ server/java/maven-plugin/src/main/java/com/metaobjects/mojo/ModelKey.java:41 - ModelKey.of keys its nodes map by unqualified type.subType + &#34; &#34; + name, so two root-level nodes with the same type and name in different packages collide and the last silently overwrites the first in nodes. Today this is latent: the whole-run skip uses only tree.model(), and the per-package lines that feed it carry both entries, so no wrong skip is reachable. But ADR-0064 §6 plans per-object/per-package keys built from exactly these node hashes, and there a same-name cross-package pair drops one sibling — the wrong-direction failure the ADR forbids. The other ports do not share the flaw: TS model-hash.ts keys nodes by resolutionKey(), Python model_key.py by resolution_key(), C# ModelHash keeps both nodes (package is a separate record field). Remedy: key the Java map by the child's resolution key (package-qualified), matching the siblings.
  • ⚠️ server/typescript/packages/cli/src/lib/gen-fingerprint.ts:483 - Generated files written outside the project root (the manifest records none of them) are guarded by existence only, in every port: gen-fingerprint.ts:483-485 (TS), skip.py untracked_exist (Python), GenFingerprint.cs CanSkipGen stored.Untracked.All(File.Exists) (C#), AbstractMetaDataMojo.java fingerprintMatches untracked loop (Java). So a hand EDIT to an outside-project output after the last run is skipped over by gen (pre-ADR gen would have restored it via the outside-file auto-overwrite policy) and, because it is not in the manifest, a local verify --codegen may also answer "no drift" from the key without rendering. This is the behavior ADR-0064 §3/§4 explicitly specify ("the manifest records none of them, so a skip needs each to still exist"), and CI always renders — so it is a documented residual, not a contradiction. A cheap follow-up that closes it: at store time also record the sha256 of each untracked path as the run left it (the run knows the bytes it wrote) and compare content, not just existence. Reported for the record; no action required for this PR.
  • ⚠️ server/typescript/packages/cli/src/commands/gen.ts:241 - The ADR-0064 skip block returns 0 at gen.ts:241-244, BEFORE the ADR-0023 unknown-attribute advisory is built and printed at gen.ts:247-257 — so a run that skips renders no warning. Concrete reachable sequence: a project whose last meta gen stored a key; the user adds a typo'd attribute (isAbstrakt: true or @requird: true) to a metadata file and runs meta gen. The lenient loader drops the unknown attribute from the loaded tree (sdk/src/memory.ts:192-195 — findings come from a separate strict pass), so modelHashTree(loaded.root) is unchanged, the key still matches, the recorded outputs are untouched, and gen answers "nothing changed since the last meta gen" — silently. The advisory whose whole purpose is to name that typo on the gen path never prints. This is both a regression of established behavior (the ADR-0023 advisory was added precisely because "the typo changed what was generated" and gen is the command users run) and a cross-port divergence: Python prints _print_unknown_attr_warnings at server/python/src/metaobjects/cli.py:2017, before its skip check at cli.py:2052, and C# calls WarnUnknownAttrs(meta) at server/csharp/MetaObjects.Codegen/CodegenCli.cs:809, before its skip at CodegenCli.cs:826. Sibling sites checked and NOT affected: C# (CodegenCli.cs:809→826) and Python (cli.py:2017→2052) both warn-then-skip; the Java mojo loads strictly per its own config and has no lenient-warning path to lose. Fix: move the skip decision below the warning-emission block (or print the collected warnings before the skip return) in gen.ts; the skip itself is correct — only its position relative to the advisory is wrong.
  • ℹ️ server/typescript/packages/cli/src/commands/gen.ts:234 - The fix round (a7e0116) that moved the skip decision below the ADR-0023 warning block left the 4-line ADR-0064 skip-decision comment duplicated: one copy above the skipInputs computation (gen.ts:234-237, where it inaccurately described the decision as happening there) and an identical copy above the actual if (skipInputs !== undefined &amp;&amp; genMaySkip(flags)) block at gen.ts:252-255. Fixed inline during this pass: the first copy now says it is the skip key's model half from the same load the warnings come from, and that the decision runs below, after the advisory is printed. Comment-only, no behavior change.

🔧 No changes applied.
3 warnings still open:

  • ⚠️ server/java/maven-plugin/src/main/java/com/metaobjects/mojo/ModelKey.java:41 - ModelKey.of keys its nodes map by unqualified type.subType + &#34; &#34; + name, so two root-level nodes with the same type and name in different packages collide and the last silently overwrites the first in nodes. Today this is latent: the whole-run skip uses only tree.model(), and the per-package lines that feed it carry both entries, so no wrong skip is reachable. But ADR-0064 §6 plans per-object/per-package keys built from exactly these node hashes, and there a same-name cross-package pair drops one sibling — the wrong-direction failure the ADR forbids. The other ports do not share the flaw: TS model-hash.ts keys nodes by resolutionKey(), Python model_key.py by resolution_key(), C# ModelHash keeps both nodes (package is a separate record field). Remedy: key the Java map by the child's resolution key (package-qualified), matching the siblings.
  • ⚠️ server/typescript/packages/cli/src/lib/gen-fingerprint.ts:483 - Generated files written outside the project root (the manifest records none of them) are guarded by existence only, in every port: gen-fingerprint.ts:483-485 (TS), skip.py untracked_exist (Python), GenFingerprint.cs CanSkipGen stored.Untracked.All(File.Exists) (C#), AbstractMetaDataMojo.java fingerprintMatches untracked loop (Java). So a hand EDIT to an outside-project output after the last run is skipped over by gen (pre-ADR gen would have restored it via the outside-file auto-overwrite policy) and, because it is not in the manifest, a local verify --codegen may also answer "no drift" from the key without rendering. This is the behavior ADR-0064 §3/§4 explicitly specify ("the manifest records none of them, so a skip needs each to still exist"), and CI always renders — so it is a documented residual, not a contradiction. A cheap follow-up that closes it: at store time also record the sha256 of each untracked path as the run left it (the run knows the bytes it wrote) and compare content, not just existence. Reported for the record; no action required for this PR.
  • ⚠️ server/typescript/packages/cli/src/lib/gen-skip.ts:22 - A skipped meta gen prints its warnings to stderr but leaves them out of the json/toon document. gen.ts:160-165 states the invariant: every warning is also collected because the structured result carries them, and on a pipe the default format is the document. The skip returns at gen.ts:254-258, after the stale-agent-context, manifest-ignored, stock-copy and ADR-0023 unknown-attribute warnings are collected into warnings. reportGenSkip(fmt, verdict.recorded.length) takes no warnings, and the doc built at gen-skip.ts:22-29 has no warnings key. Concrete sequence: the user adds a typo'd isAbstrakt, runs meta gen --format json or pipes it, and the key still matches. The run skips. stderr carries the advisory, but a reader of the document sees skipped: true with no caveats. A normal run's document (gen.ts:442) does carry them. The previous round (a7e0116) moved the skip below the warning block, so this is the same invariant that round addressed, left unfinished at the output layer. No other site in the changed code collects a warning and then returns early. Fix: pass warnings to reportGenSkip and add warnings: fmt === &#34;text&#34; ? [] : warnings to the doc, matching gen.ts:442. Extend the regression test in gen-unknown-attr-warning.test.ts with a --format json case that asserts the unknown-attribute advisory appears in the document.

🔧 Fix applied.
2 warnings still open:

  • ⚠️ server/java/maven-plugin/src/main/java/com/metaobjects/mojo/ModelKey.java:41 - ModelKey.of keys its nodes map by unqualified type.subType + &#34; &#34; + name, so two root-level nodes with the same type and name in different packages collide and the last silently overwrites the first in nodes. Today this is latent: the whole-run skip uses only tree.model(), and the per-package lines that feed it carry both entries, so no wrong skip is reachable. But ADR-0064 §6 plans per-object/per-package keys built from exactly these node hashes, and there a same-name cross-package pair drops one sibling — the wrong-direction failure the ADR forbids. The other ports do not share the flaw: TS model-hash.ts keys nodes by resolutionKey(), Python model_key.py by resolution_key(), C# ModelHash keeps both nodes (package is a separate record field). Remedy: key the Java map by the child's resolution key (package-qualified), matching the siblings.
  • ⚠️ server/typescript/packages/cli/src/lib/gen-fingerprint.ts:483 - Generated files written outside the project root (the manifest records none of them) are guarded by existence only, in every port: gen-fingerprint.ts:483-485 (TS), skip.py untracked_exist (Python), GenFingerprint.cs CanSkipGen stored.Untracked.All(File.Exists) (C#), AbstractMetaDataMojo.java fingerprintMatches untracked loop (Java). So a hand EDIT to an outside-project output after the last run is skipped over by gen (pre-ADR gen would have restored it via the outside-file auto-overwrite policy) and, because it is not in the manifest, a local verify --codegen may also answer "no drift" from the key without rendering. This is the behavior ADR-0064 §3/§4 explicitly specify ("the manifest records none of them, so a skip needs each to still exist"), and CI always renders — so it is a documented residual, not a contradiction. A cheap follow-up that closes it: at store time also record the sha256 of each untracked path as the run left it (the run knows the bytes it wrote) and compare content, not just existence. Reported for the record; no action required for this PR.

🔧 No changes applied.
2 warnings still open:

  • ⚠️ server/java/maven-plugin/src/main/java/com/metaobjects/mojo/ModelKey.java:41 - ModelKey.of keys its nodes map by unqualified type.subType + &#34; &#34; + name, so two root-level nodes with the same type and name in different packages collide and the last silently overwrites the first in nodes. Today this is latent: the whole-run skip uses only tree.model(), and the per-package lines that feed it carry both entries, so no wrong skip is reachable. But ADR-0064 §6 plans per-object/per-package keys built from exactly these node hashes, and there a same-name cross-package pair drops one sibling — the wrong-direction failure the ADR forbids. The other ports do not share the flaw: TS model-hash.ts keys nodes by resolutionKey(), Python model_key.py by resolution_key(), C# ModelHash keeps both nodes (package is a separate record field). Remedy: key the Java map by the child's resolution key (package-qualified), matching the siblings.
  • ⚠️ server/typescript/packages/cli/src/lib/gen-fingerprint.ts:483 - Generated files written outside the project root (the manifest records none of them) are guarded by existence only, in every port: gen-fingerprint.ts:483-485 (TS), skip.py untracked_exist (Python), GenFingerprint.cs CanSkipGen stored.Untracked.All(File.Exists) (C#), AbstractMetaDataMojo.java fingerprintMatches untracked loop (Java). So a hand EDIT to an outside-project output after the last run is skipped over by gen (pre-ADR gen would have restored it via the outside-file auto-overwrite policy) and, because it is not in the manifest, a local verify --codegen may also answer "no drift" from the key without rendering. This is the behavior ADR-0064 §3/§4 explicitly specify ("the manifest records none of them, so a skip needs each to still exist"), and CI always renders — so it is a documented residual, not a contradiction. A cheap follow-up that closes it: at store time also record the sha256 of each untracked path as the run left it (the run knows the bytes it wrote) and compare content, not just existence. Reported for the record; no action required for this PR.

✅ No issues found.

🔧 **Test** - 3 issues found → auto-fixed ✅
  • 🚨 configured test command failed with exit code 1
  • ⚠️ The configured test command scripts/ci-local.sh --affected --strict-toolchains exited 1 on this change (it passes on the base commit). I could not find which lane failed. The ts-fast lane passes on its own, and the focused skip-conformance tests pass in TypeScript, Python and C#, so the failure is probably in the TypeScript unit lane, the Java reactor, or a full-suite Python or C# test outside the skip tests. Run those lanes one at a time and read the failing output.
  • ⚠️ live validation verdict: inconclusive (3 of 4 scenarios were driven live against the product); untested: Broad regression: the TypeScript unit, Java, Python and C# lanes of the affected CI selection complete green
  • Live validation: ⚠️ inconclusive - 3 of 4 scenarios driven live against the product
Scenario Result Live Evidence
Run meta gen twice on a disposable TypeScript project with nothing changed: the second run renders and writes nothing and says so ✅ pass live Live CLI transcript: run 1 wrote 3 files, run 2 printed 'nothing changed since the last meta gen, so nothing was rendered or written (3 generated file(s) up to date)'.
Change the metadata, a generator setting, the generator code or a generated output, then run meta gen: it regenerates, and the following unchanged run skips again ✅ pass live Live CLI transcript: a new field gave 2 OVERWRITE and the next run skipped. A deleted output came back as NEW. Removing the barrel generator removed index.ts. An edit to an ejected template triggere…
Cross-port shared skip-conformance cases (fixtures/codegen-skip-conformance/cases.json) hold in the TypeScript, Python and C# ports ✅ pass live TypeScript: 88 pass. Python: 36 passed. C#: 29 passed.
Broad regression: the TypeScript unit, Java, Python and C# lanes of the affected CI selection complete green ⏸️ untested no I started the lanes in a detached process group, but the turn had to end before they finished, so I terminated the group. Only ts-fast completed (passed). To resolve this, re-run `scripts/ci-local.s…
  • scripts/ci-local.sh --affected --strict-toolchains
  • Live meta gen on a disposable TypeScript project: an unchanged second run skipped and printed 'nothing changed since the last meta gen'
  • Live meta gen: adding a metadata field regenerated 2 files, and the next unchanged run skipped again
  • Live meta gen: deleting a generated output regenerated it as NEW, and removing a generator from the config regenerated and REMOVED its output
  • Live meta gen: a hand edit to a generated file was MERGED rather than skipped, --force ran a full pass, and --format json on a skip returned skipped: true with a warnings key
  • Live meta eject names, then an edit to the ejected template: gen regenerated, and the following unchanged run skipped
  • bun test in server/typescript/packages/cli over gen-skip-conformance, gen-unknown-attr-warning, gen-docs-site, args-gen and args-verify: 88 pass, 0 fail
  • python3 -m pytest tests/test_gen_skip_conformance.py tests/codegen/test_gen_unchanged.py in server/python: 36 passed
  • dotnet test MetaObjects.Cli.Tests --filter FullyQualifiedName~GenSkip in server/csharp: 29 passed
  • scripts/ci-local.sh --only ts-fast --strict-toolchains: LOCAL CI PASSED (exit 0, about 7m)
  • scripts/ci-local.sh --affected --strict-toolchains and --only ts-unit --only java-slow --only python --only csharp: started, stopped before any lane result was printed

🔧 Fix applied.
✅ Re-checked - no issues remain.

  • Live validation: ✅ go - 3 of 3 scenarios driven live against the product
Scenario Result Live Evidence
meta gen skips when metadata is unchanged and regenerates when it changes (disposable project, sqlite entity generator) ✅ pass live meta-gen-skip-transcript.md RUNS 1-4: fresh run writes 2 files; immediate rerun answers skipped:true/upToDate:2 with nothing rendered; adding a room field regenerates Talk.ts (4 occurrences of room)…
Adversarial: deleting a recorded generated output defeats the skip (wrong-direction guard) — gen re-emits instead of skipping ✅ pass live meta-gen-skip-transcript.md RUN 5: after rm generated/Talk.ts, gen answers generated/Talk.ts,new — 1 written and the file is restored on disk
A typo'd unknown attribute added after the stored key still gets named on a skipped run, on stderr and in the --format json document ✅ pass live meta-gen-skip-transcript.md RUN 6 plus the two raw artifacts: skipped:true while stderr and the json document both carry the ERR_UNKNOWN_ATTR isAbstrakt warning and the ADR-0023 verify advice
  • scripts/ci-local.sh --affected --strict-toolchains
  • Broad regression (baseline, already run at this target): scripts/ci-local.sh --affected --strict-toolchains — passed
  • Live: bun &lt;worktree&gt;/server/typescript/packages/cli/bin/meta.ts gen --cwd &lt;scratch&gt; — fresh generate, then skip on unchanged (skipped:true, upToDate:2)
  • Live: metadata edit (add room field) defeats skip → Talk.ts regenerated with the new field; rerun skips again
  • Live adversarial: delete generated/Talk.ts → gen re-emits it (new) instead of skipping
  • Live: bare typo'd key isAbstrakt:true after stored key → run skips yet ERR_UNKNOWN_ATTR warning prints to stderr (text) and appears in the --format json document's warnings array
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

Forward-port of #585 from release/1.2 (b9bc9c7) onto main, merged with the
manifest written once per run (#584) and the uniform entity selection (#588).
The skip ADR is numbered ADR-0064 here: ADR-0062 and ADR-0063 are taken on main.

- gen builds a key from the loaded model (each root node in canonical effective
  form), the generators' identity (built engine code, config, owned generators,
  templates, declared extra inputs, project config) and the output-changing
  flags, before anything renders. A match with the last successful run, with
  every generated file still holding that run's bytes, renders and writes
  nothing. --force (Maven: -Dmetaobjects.force=true) turns it off; a generator
  that cannot declare its inputs opts out.
- A run that names entities (positional, --entities, -Dmeta.entities) forces
  exactly those: it never skips, never stores a key and leaves the stored
  full-run key alone, in every port.
- verify --codegen may answer "no drift" locally from the key; CI and --full
  always render, and every port compares in memory.
- The hash manifest stays loaded once and written once, and only when an entry
  changed; identical bytes are never rewritten; TypeScript runs git merge-file
  only for a hand-edited file.
- fixtures/codegen-skip-conformance/cases.json: the shared case table.

Hand-resolved: TypeScript runner, overwrite-policy, gen/verify/args/index and
codegen-drift; Python cli, runner, overwrite_policy; C# CodegenRunner,
CodegenCli, CodegenDrift, Generator, Program; Java generate and verify mojos;
docs, changelog and the ADR index.
@dmealing
dmealing merged commit 3514686 into main Nov 15, 2026
9 checks passed
@dmealing
dmealing deleted the fm/mo-codegen-skip-main branch November 15, 2026 19:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant