Repository navigation
feat(codegen): skip gen when nothing changed, in every port - #585
Merged
Merged
Conversation
- gen builds a key from the loaded model (each root node in canonical effective form, rolled up per package) plus the generators' identity (built engine code, config, owned generators, templates, declared extra inputs, project config, output-changing flags), before anything renders. When it matches the last successful run and every generated file still holds that run's bytes, gen renders and writes nothing. --force (Maven: -Dmetaobjects.force=true) turns it off; a generator that cannot declare its inputs opts out (cache: false or the port's equivalent). - verify --codegen always renders in CI; locally it may answer "no drift" from the key and the manifest, --full forces a render. When it renders, every port compares in memory: no rendered temp tree (Java/Kotlin now capture through GeneratedFileWriter). - The hash manifest is loaded once and written once per run, only when it changed (TypeScript, Python, C#). Identical bytes are never rewritten in any port. Python gen no longer reports unchanged files as written. - TypeScript runs git merge-file only for a file edited by hand, and deletes its temporaries in a finally, under $DEV_SCRATCH when set. - fixtures/codegen-skip-conformance/cases.json: 25 shared cases run by every port.
… when unchanged Two targets, four generators: a forced run over unchanged output keeps every mtime and saves no manifest; a first run saves it once. Also corrects a stale comment in verify --codegen, which renders in memory.
The skill references in agent-context/ now describe verify --codegen as rendering in memory. Refresh the byte-for-byte expected mirrors to match.
dmealing
added a commit
that referenced
this pull request
Nov 15, 2026
…and a thrown merge leaves no temp file #585 added the fast path and per-merge temp cleanup; these decideAndWrite-level tests pin the two cases it left untested: an unedited file regenerates with META_GEN_GIT pointing at a missing binary (so any spawn would throw) and advances its snapshot and hash, and a merge that throws GitMissingError leaves nothing in mergeTempDir(). Clean merge and conflict are re-asserted at the same level.
This was referenced Nov 15, 2026
dmealing
added a commit
that referenced
this pull request
Nov 15, 2026
…anged (ADR-0064) (#590) * feat(codegen): skip gen when nothing changed, in every port (ADR-0064) 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. * no-mistakes(review): apply reviewer inline fixes * no-mistakes(review): apply reviewer inline fixes * no-mistakes(review): warn unknown attrs before gen skip; add regression test * no-mistakes(review): apply reviewer inline fixes * no-mistakes(review): Carry warnings in skipped gen json/toon document * no-mistakes(test): Align C# agent-context fixture wording; sdk suite green * no-mistakes(document): align codegen-skip docs with ADR-0064
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What Changed
genin every port (TypeScript, Python, C#, Java, Kotlin) computes a skip key from the loaded model and the generator inputs (ADR-0062), before anything renders. When the key matches the last successful run and every generated file still matches its record, the run renders and writes nothing. The key is stored in.metaobjects/.gen-state/.fingerprint-<port>.json,--forceregenerates everything, and a localverify --codegenanswers "no drift" from the same key (CI and--fullstill render and compare). When it does render, the rendered bytes are compared with disk in memory..metaobjects/.gen-state/.hashes.json) is loaded once and saved once per run, and only when an entry changed. TypeScript, Python and C# previously rewrote it per file. A file whose fresh bytes already equal what is on disk is no longer rewritten, so its timestamp is preserved.git merge-fileonly for a file edited by hand since it was generated, and deletes its merge temporary files in every case (under$DEV_SCRATCHwhen set).Validation
Risk Assessment
✅ Low: The only change since the starting head is a narrow docs-site fix: the raw metadata source roots join the skip key, so a comment-only edit makes gen render again. The earlier refused-orphan fix is also correct. I found no defect in either, but I did not re-read the rest of the large branch in this round.
Testing
The TypeScript and Python CLIs were driven live against disposable projects built under $DEV_SCRATCH. The TypeScript CLI ran from worktree source through bun, not the built dist. Every scenario the ADR says must render did render, and the no-change run skipped with the render counter and output mtimes unchanged. Local
verify --codegenanswered without rendering after a no-change run, andCI=1rendered. The adversarial cases also passed: an edited orphan the sweep refuses stores no key, an output outside the project root is restored when deleted, and a comment-only docs-site edit reaches the published page. Java/Kotlin and C# were not driven live. The regression suite did not complete: the TypeScript serverbun testwas killed before reporting, and the Python unit run was stopped at about 5% with three environment-only failures. The baseline ts-fast and ts-unit lanes passed. Verdict is inconclusive because a required regression check has no result. Separately, my process cleanup killed sixbun test --shard=N/6processes that this step did not start.meta genwrites generated files and stores a skip keymeta genskips: no render, outputs and .hashes.json mtimes unchangedverify --codegenafter no change answers without rendering;CI=1rendersgen --forcewith nothing changed rendersverify --codegenrenders and classifies itmetaobjects gen, then no-change run skips with output and manifest mtimes unchangedgen --forceon clean output renders (no 'nothing changed')mvn -oin server/java/maven-plugin, nor the GenSkipConformanceTest or RefusedOrphanSkipTest runners. The time budget went to the TS and Python live drives. The…dotnet meta genskip, force and verify behaviourdotnet test). Dotnet is on PATH, so this was a time-budget decision, not a missing tool.bun testin server/typescript was started in the background and killed before it reported a result, so its outcome is unknown. Required check outstanding; see the regression-incomplete finding.Evidence: Live CLI transcripts for TS and Python ADR-0062 scenarios (S3, S12, outside-root, docs-site, Python P1 to P6)
Live end-to-end scenarios (run by hand on the pushed head, after the PR opened)
Both scenarios ran against the canonical fitness model (
fixtures/persistence-conformance/canonical/meta.fitness.json), with each tool built from this branch's head.Maven plugin (
mvn metaobjects:generate/metaobjects:verify, Java + Kotlin generators)generategenerate, nothing changedgenerate -Dmetaobjects.force=trueverify, nothing changedverifywithCI=trueverify -Dmetaobjects.verify.full=trueverifyafter a hand edit to a generated file[content-differs]on that file, BUILD FAILURE (exit 1)generateafter the hand edithandEdits: keep)generateafter a metadata edit (@maxLength)generateafter reverting the metadatagenerateskips againC# (
dotnet meta gen/dotnet meta verify --codegen, owned generator list)gen --forcegen, nothing changedgen --forceverify --codegen, nothing changedverify --codegenwithCI=trueverify --codegen --fullverify --codegenafter a hand edit to a generated filegenafter the hand editgenafter a metadata edit (@maxLength)genafter reverting the metadatagenskips againAll 20 steps behaved as expected.
Pipeline
Updates from git push no-mistakes
✅ **Intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
🔧 **Review** - 1 issue found → auto-fixed ✅
server/typescript/packages/cli/src/lib/gen-fingerprint.ts:347- TypeScript can skip a run it should render, which is the unsafe direction ADR-0062 §3 forbids. Thedocs-sitegenerator reads raw YAML metadata files through its own scan, and the skip key does not cover that read.harvestCommentsindocs-site/src/yaml-comments.tswalks every*.yaml/*.ymlunderctx.sourceRootsand turns the#comment above an- object.*:line, and the trailing# ...on afield.*line, into the description and note text in the output-payload pages (builders/output-data.ts:34,45).computeGenInputshashes only.mustachefiles under the source roots (line 347 onward). The model half hashes the loaded model, which carries no comments.docsSiteFiledeclaresinputsonly forprompts. Concrete sequence: a project wiresdocsSiteFile()and runsmeta gen, which stores the key. Someone edits only the comment above a payload object inmeta.*.yaml, with no description attribute. The loaded model is unchanged, the key matches, anddecideGenSkipreturns skip. The nextgenprints 'nothing changed', andmeta verify --codegenanswers no drift locally throughdecideVerifyNoDrift. The docs page is stale. Theshared-modelgenerator is not affected: it re-loads the same source files, so the model hash already covers it. Smallest fix: hash the.yaml/.ymlfiles under the source roots as raw entries next to the.mustacheones (an over-count is the safe direction). If a comment-only edit must not change the key, markdocs-sitecache: falseinstead. Add a test where a comment-only edit makesgenrender whendocs-siteis wired.🔧 Fix applied.
✅ Re-checked - no issues remain.
server/typescript/packages/cli/src/commands/gen.ts:425- Regression suite is incomplete. The TypeScript serverbun testrun (server/typescript) was killed before it reported a result, and the Python unit run was stopped at about 5%. Java/Kotlin, C# and Python integration suites were not run. The change cannot be cleared as regression-safe from this step. The outer executor should run the conventional full command (scripts/ci-local.sh, or the server test suite) to completion.n/a (host process state)- While stopping this step's background suites, I killed sixbun test --timeout 60000 --shard=N/6processes (PIDs 3961618 to 3961624 range, shards 1 to 6) that this step did not start. They look like a separate run on this machine. Their results are lost. Whoever owns them should check whether they need rerunning.server/typescript/packages/cli/src/lib/gen-fingerprint.ts:426- When an existing project moves outDir from inside the project to outside, its stale manifest entries (recorded paths that no longer exist) make writeStoredFingerprint return early, so no key is ever stored and every run renders. This is the safe direction and performance only, with no wrong skip. I observed it in a copied project and did not find an automatic cleanup of stale manifest entries.dotnet meta genskip, force and verify behaviour, Regression: full TypeScript server suite, Regression: full Python unit suitemeta genwrites generated files and stores a skip keymeta genskips: no render, outputs and .hashes.json mtimes unchangedverify --codegenafter no change answers without rendering;CI=1rendersgen --forcewith nothing changed rendersverify --codegenrenders and classifies itmetaobjects gen, then no-change run skips with output and manifest mtimes unchangedgen --forceon clean output renders (no 'nothing changed')mvn -oin server/java/maven-plugin, nor the GenSkipConformanceTest or RefusedOrphanSkipTest runners. The time budget went to the TS and Python live drives. The…dotnet meta genskip, force and verify behaviourdotnet test). Dotnet is on PATH, so this was a time-budget decision, not a missing tool.bun testin server/typescript was started in the background and killed before it reported a result, so its outcome is unknown. Required check outstanding; see the regression-incomplete finding.scripts/ci-local.sh --only ts-fast --only ts-unit --strict-toolchainsbaseline (given):scripts/ci-local.sh --only ts-fast --only ts-unit --strict-toolchainsTS live:bun server/typescript/packages/cli/bin/meta.ts gen(first run, no-change run,--force) in a disposable project under $DEV_SCRATCH, with an owned probe generator that appends to renders.log on each render (render counter is the oracle)TS live:meta verify --codegenlocally (no-change: no render) and withCI=1(renders)TS live: metadata reformatted with child order kept plus unrelated README edit -> skipTS live: metadata edit (field added) -> render, field present in generated/Order.tsTS live: declared extra input edited -> render, generated/mine.txt updatedTS live: hand edit to generated/Order.ts -> render and merged (edit kept)TS live: generated/mine.txt deleted -> render and restoredTS live: fingerprint file deleted -> renderTS live: metadata file added -> render, Customer.ts writtenTS live adversarial: edited orphan with entity removed -> warning, no fingerprint stored, second run renders and re-warnsTS live adversarial: outDir outside project root (fresh project) -> no-change skip, deleted outside output -> re-render and restoreTS live adversarial: docs-site wired, comment-only edit above a template.output payload object -> render, output page shows revised comment; no-change control skipsTS live: hand edit after last gen thenmeta verify --codegen-> renders and classifies the hand editPython live:metaobjects gen(viafrom metaobjects.cli import main, PYTHONPATH=server/python/src) first run, no-change run (outputs and manifest mtimes unchanged), metadata edit, hand-edited file (refused, not skipped), restore then no-change and--forcePYTHONPATH=src python3 -m pytest -q tests/test_gen_skip_conformance.py tests/codegen/test_gen_unchanged.py-> 35 passedbun testin server/typescript: started, killed before completion, no resultpython3 -m pytest -q tests --ignore=tests/integration: stopped at ~5%; three failures in tests/codegen/test_cli_surface.py::test_a_version_flag_prints_the_bare_version are environmental (packagemetaobjectsnot installed, so importlib.metadata cannot find it)Not run: Java/Kotlin maven-plugin GenSkipConformanceTest, C# GenSkipConformanceTests, Python tests/integration (needs pg8000 and Postgres), fullscripts/ci-local.shWorktree check:git status --shortis empty after cleanup; scratch project removed🔧 **Document** - 3 issues found → auto-fixed ✅
server/java/maven-plugin/src/main/java/com/metaobjects/mojo/MetaDataVerifyMojo.java:414- JavaMetaDataVerifyMojostill creates an empty virtual root directory under a temp path (createTempDirectory, deleted infinally), and its inline comments still say the regenerate 'writes to a temp dir'. No rendered file is written, so the docs' 'no rendered temp tree is written' is accurate. The Javadoc was corrected. The remaining code comments describe the real mechanism, so I left them. Judgement call: decide whether the empty root should go too.docs/llms/llms-full.txt-docs/llms/llms-full.txtis a hand-maintained mirror of the docs (the site copies it verbatim). I corrected its one stale temp-dir line, but it does not carry the newgenskip behaviour or thecodegen-skip-conformancecorpus, so it now lagsdocs/features/cli.mdanddocs/CONFORMANCE.md. A follow-up should either add the skip section to the mirror or decide that the mirror is exempt.AGENTS.md- AGENTS.md and CLAUDE.md still say 'Biome for format pass' under codegen substrate, and their.hashes.jsonstorage line predates the new stored key in.gen-state/.fingerprint-<port>.json. This branch does not make either fact false, and both are agent memory files that only a human should edit, so I did not touch them. If the formatter removal lands in this release line, that human edit is needed.🔧 Fix applied.
✅ Re-checked - no issues remain.
🔧 **Lint** - 1 issue found → auto-fixed ✅
🔧 Fix applied.
✅ Re-checked - no issues remain.
✅ **Push** - passed
✅ No issues found.