chore: make generate:assets idempotent - #450
Merged
Merged
Conversation
`npm run generate:assets` was not idempotent, so `prepare:pr` never left a clean tree and the release workflow committed churn on every version bump. Two upstream tools produced non-deterministic output: - `markdown-toc -i` appends one blank line every time it rewrites a file. Because the version-bump workflow runs `generate:assets` and commits the result on every release, this compounded across releases: 92 trailing blank lines had accumulated in docs/contributing.md, 42 in docs/README.md and 32 in docs/migrations/v0.md. - `oclif readme` renders the sample `codegen --version` output using the platform and Node.js version of the machine that ran it. That flipped between contributors (linux-x64 vs darwin-arm64), and also churned on CI whenever a new Node 22 patch landed, since engines only pins ">=22.0.0". Add scripts/normalizeGeneratedDocs.js, wired in as `generate:docs:normalize` directly after `generate:commands` (the last step that touches these docs). It trims each generated doc to exactly one trailing newline and replaces the machine-specific segments of the sample version line with placeholders, keeping the package version so version bumps still update it. Running `generate:assets` four times in a row now produces a byte-identical result; the diff here includes the one-time cleanup of the 163 accumulated blank lines. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Author
|
🎉 This PR is included in version 0.82.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
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
1 participant
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
npm run generate:assetswas not idempotent. Every run mutated the docs again, soprepare:prnever left a clean tree — and because the version-bump workflow runsgenerate:assetsand commits the result on every release, the churn was being committed on each version bump.Why it happened
Two upstream tools produce non-deterministic output:
1.
markdown-toc -iappends one blank line every time it rewrites a file.This compounded across releases. Before this PR:
docs/contributing.mddocs/README.mddocs/migrations/v0.md(
README.mdwas spared only because it has no<!-- toc -->marker, so markdown-toc no-ops and never writes it.)2.
oclif readmebakes the build machine into the samplecodegen --versionoutput.That flips between contributors (
linux-x64↔darwin-arm64), but it is not only a local-platform issue:engines.nodeis>=22.0.0with no.nvmrc, so CI resolves to whatever the latest 22.x is and the line churns on every Node 22 patch release too.The fix
Adds
scripts/normalizeGeneratedDocs.js, wired in asgenerate:docs:normalizeimmediately aftergenerate:commands(the last step that touches these docs). It:The package version is preserved, so the release version bump still updates it meaningfully.
Verification
generate:assetsfour times. Run 1 produced the one-time cleanup; runs 2, 3 and 4 produced a byte-identical diff. Idempotent.npm run lint— clean.npm test— 64 suites, 772 passed, 1 skipped, 80 snapshots passed.The
164 deletionsin this diff are the one-time sweep of the 163 accumulated blank lines plus the version line.Notes for the reviewer
runtime:typescript:generate(part ofprepare:pr) was deliberately skipped: it is blocked by pre-existing lockfile drift intest/runtime/typescript, unrelated to this change, and this PR touches no generator code so regenerated runtime output cannot be affected.linux-x64plus a fixed Node version, because pinning would still drift as Node 22 patches land. If you would rather the docs show a concrete sample, the alternative is adding an.nvmrcand normalizing to those exact values.chore:so it does not trigger a release — this is tooling only.🤖 Generated with Claude Code