From 6f75bdcf522e7cc1c37f1c27b880cf5587d2e744 Mon Sep 17 00:00:00 2001 From: jonaslagoni Date: Sat, 1 Aug 2026 20:46:47 +0200 Subject: [PATCH] chore: make generate:assets idempotent `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) --- docs/README.md | 41 -------------- docs/contributing.md | 91 ------------------------------- docs/migrations/v0.md | 31 ----------- docs/usage.md | 2 +- package.json | 3 +- scripts/normalizeGeneratedDocs.js | 53 ++++++++++++++++++ 6 files changed, 56 insertions(+), 165 deletions(-) create mode 100644 scripts/normalizeGeneratedDocs.js diff --git a/docs/README.md b/docs/README.md index e33093d8..940cc50b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -66,44 +66,3 @@ Get an overview of how telemetry works for this project ### [AI Assistants](./ai-assistants.md) Connect AI assistants like Claude Code, Cursor, and Windsurf to The Codegen Project via MCP (Model Context Protocol) for intelligent code generation assistance. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/contributing.md b/docs/contributing.md index 781352fd..9f8c6871 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -134,94 +134,3 @@ Pull requests should have a title that follows the specification, otherwise, mer What about MAJOR release? just add `!` to the prefix, like `fix!: ` or `refactor!: ` Prefix that follows specification is not enough though. Remember that the title must be clear and descriptive with usage of [imperative mood](https://chris.beams.io/posts/git-commit/#imperative). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/migrations/v0.md b/docs/migrations/v0.md index 35bc87ac..6b1ca3b1 100644 --- a/docs/migrations/v0.md +++ b/docs/migrations/v0.md @@ -222,34 +222,3 @@ import * as NodeFetch from 'node-fetch'; 1. Regenerate your code. 2. Remove `node-fetch` and `@types/node-fetch` from your project's dependencies if they were only used by the generated client. 3. Ensure your runtime provides a global `fetch` (Node.js 18+). If you need a custom HTTP implementation, supply it through the `makeRequest` hook instead of relying on the default. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/usage.md b/docs/usage.md index 48cda2a0..61018564 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -8,7 +8,7 @@ $ npm install -g @the-codegen-project/cli $ codegen COMMAND running command... $ codegen (--version) -@the-codegen-project/cli/0.81.1 linux-x64 node-v22.23.1 +@the-codegen-project/cli/0.81.1 node- $ codegen --help [COMMAND] USAGE $ codegen COMMAND diff --git a/package.json b/package.json index 70db2b7d..58503fa7 100644 --- a/package.json +++ b/package.json @@ -109,7 +109,8 @@ "build:browser:minify": "node esbuild.browser.mjs --minify", "dev": "tsc --watch", "generate:readme:commands": "oclif readme --readme-path=\"./docs/usage.md\" --output-dir=\"./docs\"", - "generate:assets": "npm run generate:readme:toc && npm run generate:commands && npm run generate:schema && npm run format && npm run generate:examples", + "generate:assets": "npm run generate:readme:toc && npm run generate:commands && npm run generate:docs:normalize && npm run generate:schema && npm run format && npm run generate:examples", + "generate:docs:normalize": "node scripts/normalizeGeneratedDocs.js", "generate:schema": "node scripts/generateSchemaFiles.js", "generate:playground": "npm run build:browser && cd website && npm run copy:bundle && npm run copy:schema", "generate:mcp:docs": "cd mcp-server && npm ci && npm run bundle-docs", diff --git a/scripts/normalizeGeneratedDocs.js b/scripts/normalizeGeneratedDocs.js new file mode 100644 index 00000000..38b5dda7 --- /dev/null +++ b/scripts/normalizeGeneratedDocs.js @@ -0,0 +1,53 @@ +/** + * Makes `npm run generate:assets` idempotent for the markdown docs it rewrites. + * + * Two upstream tools leave non-deterministic output behind: + * + * 1. `markdown-toc -i` appends one blank line every time it actually rewrites a + * file, so each release grew docs/README.md, docs/contributing.md and + * docs/migrations/v0.md by one trailing newline. + * 2. `oclif readme` renders the sample `codegen --version` output using the + * platform and Node.js version of whoever ran it, so the line flipped + * between machines (and between Node.js patch releases on CI). + */ + +const fs = require('fs'); +const path = require('path'); + +const repoRoot = path.resolve(__dirname, '..'); + +/** Files rewritten by `generate:readme:toc` / `generate:commands`. */ +const docs = [ + 'README.md', + 'docs/usage.md', + 'docs/README.md', + 'docs/contributing.md', + 'docs/migrations/v0.md' +]; + +/** `@the-codegen-project/cli/1.2.3 darwin-arm64 node-v24.15.0` */ +const versionSample = /^(@the-codegen-project\/cli\/\S+) \S+ node-\S+$/m; +const versionSampleReplacement = '$1 node-'; + +const changed = []; + +for (const relativePath of docs) { + const filePath = path.join(repoRoot, relativePath); + const original = fs.readFileSync(filePath, 'utf8'); + + let normalized = `${original.replace(/\s+$/, '')}\n`; + if (relativePath === 'docs/usage.md') { + normalized = normalized.replace(versionSample, versionSampleReplacement); + } + + if (normalized !== original) { + fs.writeFileSync(filePath, normalized); + changed.push(relativePath); + } +} + +console.log( + changed.length > 0 + ? `Normalized:\n ${changed.join('\n ')}` + : 'Normalized: no changes needed' +);