@rtorcato/repo-tooling 3.11.0 → 3.12.0

package/dist/base/github-settings.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import chalk from 'chalk';
 import fs from 'fs-extra';
 const GH_TIMEOUT_MS = 10_000;
@@ -345,10 +346,55 @@ async function hasCodeScanningRuleset(gh, nwo, branch) {
     }
     return 'no';
 }
+/** Release config filenames semantic-release picks up that we can import. */
+const RELEASE_CONFIG_FILES = ['release.config.mjs', 'release.config.js'];
+/** How to stop the GH013 collision, wherever it is reported. */
+const GIT_PLUGIN_REMEDY = 'Drop `@semantic-release/git` and `@semantic-release/changelog` from the release config (rtorcato/repo-tooling#417) — the shipped `semantic-release/github` preset already has, so a bare re-export of it is enough. Do NOT add a bypass actor to the ruleset: it exempts the one commit nobody reviews';
+/**
+ * Does the repo's release config still resolve `@semantic-release/git`?
+ *
+ * That plugin pushes the release commit straight to the default branch, which a
+ * `code_scanning` ruleset rejects with GH013 — a commit created seconds earlier
+ * can never carry CodeQL results (#417). The two are individually correct and
+ * jointly unwinnable, and the failure is silent, because a merge that produces
+ * no release goes green either way.
+ *
+ * The config is imported rather than grepped, because every cheaper signal is
+ * wrong on a config we ship or recommend: a bare re-export names no plugin at
+ * all; a pinned older repo-tooling re-exports a preset that *does* have it; the
+ * current preset mentions it in a comment explaining its absence; and the
+ * documented way to drop it lists the name in a filter. Only the resolved
+ * `plugins` array distinguishes those. Importing config is what semantic-release
+ * itself does with this file.
+ *
+ * `false` on anything unreadable — a false negative is a missed warning, a false
+ * positive is a wrong one.
+ */
+export async function releaseUsesGitPlugin(dir) {
+    for (const name of RELEASE_CONFIG_FILES) {
+        const file = path.join(dir, name);
+        if (!(await fs.pathExists(file)))
+            continue;
+        try {
+            const mod = await import(pathToFileURL(file).href);
+            const plugins = mod.default?.plugins;
+            if (!Array.isArray(plugins))
+                return false;
+            return plugins.some((p) => (Array.isArray(p) ? p[0] : p) === '@semantic-release/git');
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
 /**
  * The #269 gap: CodeQL results are advisory by default — a High alert still
  * merges unless a branch ruleset requires the code-scanning check. Only
  * meaningful where CodeQL is actually on, so it no-ops otherwise.
+ *
+ * It also reports the #419 collision: a gate that is correctly in place is still
+ * drift when the release config pushes to the branch it guards.
  */
 async function checkCodeScanningRuleset(gh, nwo, branch, dir) {
     const check = CODE_SCANNING_CHECK;
@@ -358,14 +404,25 @@ async function checkCodeScanningRuleset(gh, nwo, branch, dir) {
     const found = await hasCodeScanningRuleset(gh, nwo, branch);
     if (found === 'skip')
         return skip(check, 'could not read rulesets');
+    const gitPlugin = await releaseUsesGitPlugin(dir);
     if (found === 'yes') {
+        if (gitPlugin) {
+            return {
+                check,
+                status: 'drift',
+                detail: `active ruleset requires code-scanning on ${branch}, but the release config still uses \`@semantic-release/git\` — its push to ${branch} will be rejected with GH013, and the release fails silently`,
+                hint: GIT_PLUGIN_REMEDY,
+            };
+        }
         return { check, status: 'ok', detail: `active ruleset requires code-scanning on ${branch}` };
     }
     return {
         check,
         status: 'drift',
         detail: `CodeQL is on but no active ruleset requires code-scanning on ${branch} (High alerts stay advisory)`,
-        hint: 'Run `npx @rtorcato/repo-tooling fix github-settings` to add a code_scanning branch ruleset that blocks merge on High+ CodeQL alerts',
+        hint: gitPlugin
+            ? `Run \`npx @rtorcato/repo-tooling fix github-settings\` to add a code_scanning branch ruleset that blocks merge on High+ CodeQL alerts. That ruleset will reject this repo's release commit with GH013 while the config uses \`@semantic-release/git\`. ${GIT_PLUGIN_REMEDY}`
+            : 'Run `npx @rtorcato/repo-tooling fix github-settings` to add a code_scanning branch ruleset that blocks merge on High+ CodeQL alerts',
     };
 }
 /** The branch-protection body PUT to the API — mirrors the doctor standard. */
@@ -484,9 +541,13 @@ export async function applyGithubSettings(dir, exec) {
             console.error(chalk.yellow(`   could not apply ${cmd.label}: ${r.stderr.trim() || 'gh error'}`));
     }
     // Code-scanning ruleset (#269): POST only when CodeQL is on and no active gate
-    // covers the default branch — the check re-read keeps this idempotent.
-    const cs = await checkCodeScanningRuleset(gh, info.nwo, info.branch, dir);
-    if (cs.status === 'drift') {
+    // covers the default branch. Asked directly rather than via the check's
+    // status, because that status is also `drift` when the gate is already
+    // installed and merely collides with the release config (#419) — keying the
+    // POST off it would file a duplicate ruleset.
+    const codeql = await codeqlEnabled(gh, info.nwo, dir);
+    const ruleset = codeql ? await hasCodeScanningRuleset(gh, info.nwo, info.branch) : 'skip';
+    if (ruleset === 'no') {
         const label = `code-scanning ruleset on ${info.branch}`;
         const r = await gh(['api', '-X', 'POST', `repos/${info.nwo}/rulesets`, '--input', '-'], CODE_SCANNING_RULESET_BODY);
         if (r.ok)
@@ -494,6 +555,14 @@ export async function applyGithubSettings(dir, exec) {
         else
             console.error(chalk.yellow(`   could not apply ${label}: ${r.stderr.trim() || 'gh error'}`));
     }
+    // #419: the gate is right and the release config is wrong, so say so instead
+    // of quietly installing the half that breaks the next release. Warned on
+    // `yes` too — that repo is already broken, it just hasn't released yet.
+    if (ruleset !== 'skip' && (await releaseUsesGitPlugin(dir))) {
+        console.error(chalk.yellow(`   warning: code-scanning is enforced on ${info.branch}, but the release config still uses \`@semantic-release/git\`.\n` +
+            `   Its push to ${info.branch} will be rejected with GH013 and the release will fail silently.\n` +
+            `   ${GIT_PLUGIN_REMEDY}.`));
+    }
     if (applied.length === 0)
         console.error(chalk.gray('   already configured — nothing to apply'));
     return applied;

package/dist/cli/generators/build.js

@@ -123,41 +123,15 @@ export default mergeConfig(preset, defineConfig({ plugins: [react()] }))
 `;
     await fs.writeFile(viteConfigPath, viteConfig);
 }
-// Plugins the github/gitlab preset activates that semantic-release core does
-// NOT bundle (core bundles only commit-analyzer, release-notes-generator, npm,
-// github). Without these in the consumer's deps, `semantic-release` crashes
-// with "Cannot find module '@semantic-release/changelog'" on first run.
-const RELEASE_PLUGIN_DEPS = {
-    '@semantic-release/changelog': '^6.0.0',
-    '@semantic-release/git': '^10.0.0',
-};
 export async function generateSemanticReleaseConfig(targetDir) {
     const releaseConfigPath = path.join(targetDir, 'release.config.mjs');
     const releaseConfig = `export { default } from '@rtorcato/repo-tooling/semantic-release/github'
 `;
+    // No extra plugin deps to inject: the github preset now uses only what
+    // semantic-release core bundles (commit-analyzer, release-notes-generator,
+    // npm, github). The changelog and git plugins are gone — see #417.
     await fs.writeFile(releaseConfigPath, releaseConfig);
-    const written = ['release.config.mjs'];
-    // Ensure the preset's non-bundled plugins are installed; otherwise the
-    // scaffolded release.config.mjs references modules the consumer lacks.
-    const pkgPath = path.join(targetDir, 'package.json');
-    if (await fs.pathExists(pkgPath)) {
-        const pkg = (await fs.readJson(pkgPath));
-        const devDeps = (pkg.devDependencies ?? {});
-        const deps = (pkg.dependencies ?? {});
-        let changed = false;
-        for (const [name, version] of Object.entries(RELEASE_PLUGIN_DEPS)) {
-            if (!devDeps[name] && !deps[name]) {
-                devDeps[name] = version;
-                changed = true;
-            }
-        }
-        if (changed) {
-            pkg.devDependencies = devDeps;
-            await fs.writeJson(pkgPath, pkg, { spaces: 2 });
-            written.push('package.json');
-        }
-    }
-    return written;
+    return ['release.config.mjs'];
 }
 export async function generateChangesetsConfig(targetDir) {
     // Drop the canonical Changesets config into .changeset/config.json. The user

package/dist/cli/generators/docs-site.js

@@ -333,8 +333,12 @@ on:
     branches: [main]
     paths:
       - 'apps/docs/**'
-      - 'CHANGELOG.md'
       - '.github/workflows/docs.yml'
+  # The changelog page is built from GitHub Releases, and no release commit
+  # lands on main any more (see #417) — so a push trigger alone would never
+  # rebuild the site after a release.
+  release:
+    types: [published]
   workflow_dispatch:
 
 jobs:

package/dist/cli/generators/package-json.js

@@ -377,14 +377,12 @@ function getDependencies(config) {
         deps['commitizen'] = '^4.3.1';
         deps['cz-conventional-changelog'] = '^3.3.0';
     }
-    // Semantic release. The shipped github preset activates the changelog and
-    // git plugins (and @semantic-release/github), so they must be installed too
-    // or `semantic-release` crashes with "Cannot find module".
+    // Semantic release. The shipped github preset uses only plugins that
+    // semantic-release core bundles, plus @semantic-release/github — no
+    // changelog/git plugins (see tooling/semantic-release/github.mjs, #417).
     if (config.semanticRelease) {
         deps['semantic-release'] = '^25.0.0';
         deps['@semantic-release/github'] = '^12.0.0';
-        deps['@semantic-release/changelog'] = '^6.0.0';
-        deps['@semantic-release/git'] = '^10.0.0';
     }
     return deps;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.11.0",
+	"version": "3.12.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [
@@ -244,11 +244,9 @@
 		"@ianvs/prettier-plugin-sort-imports": "^4.4.2",
 		"@next/eslint-plugin-next": "^16.2.11",
 		"@playwright/test": "^1.62.0",
-		"@semantic-release/changelog": "^7.0.0",
 		"@rollup/plugin-typescript": "^12.0.0",
 		"@semantic-release/commit-analyzer": "^13.0.1",
 		"@semantic-release/exec": "^7.1.0",
-		"@semantic-release/git": "^11.0.1",
 		"@semantic-release/github": "^12.0.9",
 		"@semantic-release/npm": "^13.1.5",
 		"@semantic-release/release-notes-generator": "^14.1.1",

package/tooling/docusaurus/sync-changelog.mjs

@@ -1,11 +1,19 @@
 // Canonical sync-changelog for @rtorcato/* docs sites (shipped by
 // @rtorcato/repo-tooling — copy via `repo-tooling copy docusaurus-sync-changelog`).
 //
-// Copies the root CHANGELOG.md into the docs site's changelog page with
-// frontmatter, so semantic-release keeps owning a single canonical changelog
-// while the docs site renders it in-nav. The output file is gitignored — it is
-// regenerated on every docs build (wire it into the docs app's `build`/`start`
-// scripts; pnpm 8 doesn't run `pre*` hooks reliably, so chain it explicitly).
+// Builds the docs site's changelog page from **GitHub Releases**, not from
+// CHANGELOG.md. The output file is gitignored — it is regenerated on every docs
+// build (wire it into the docs app's `build`/`start` scripts; pnpm 8 doesn't run
+// `pre*` hooks reliably, so chain it explicitly).
+//
+// Why Releases and not the file: the shipped semantic-release github preset
+// does not use @semantic-release/git, because the `code-scanning-main` ruleset
+// rejects the release commit with GH013 (see tooling/semantic-release/github.mjs
+// and rtorcato/repo-tooling#417). Nothing commits CHANGELOG.md back, so it is
+// frozen at whatever the last release with that plugin wrote — and it freezes at
+// a *real* release, which is why it reads as current. @semantic-release/github
+// writes Releases from the same notes that used to build CHANGELOG.md, so
+// concatenating their bodies reproduces the old page and cannot go stale.
 //
 // The target defaults to Docusaurus's `apps/docs/docs/changelog.md`. Override
 // with the CHANGELOG_TARGET env var (path relative to the repo root) for other
@@ -13,6 +21,9 @@
 //   CHANGELOG_TARGET=apps/web/content/docs/changelog.mdx node scripts/sync-changelog.mjs
 // The title/description frontmatter is framework-neutral (both Docusaurus and
 // Fumadocs read it), so only the path changes between frameworks.
+//
+// The docs workflow must rebuild on `release: types: [published]` — with no
+// release commit landing on the default branch, a `push` trigger never fires.
 
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
@@ -20,21 +31,74 @@ import { fileURLToPath } from 'node:url'
 
 const here = dirname(fileURLToPath(import.meta.url))
 const repoRoot = resolve(here, '..')
-const source = resolve(repoRoot, 'CHANGELOG.md')
 const target = resolve(repoRoot, process.env.CHANGELOG_TARGET ?? 'apps/docs/docs/changelog.md')
 
+/** `owner/name` — from CI, else from package.json `repository`. */
+function resolveRepo() {
+	if (process.env.GITHUB_REPOSITORY) return process.env.GITHUB_REPOSITORY
+	const pkg = JSON.parse(readFileSync(resolve(repoRoot, 'package.json'), 'utf8'))
+	const url = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url
+	const match = /github\.com[/:]([^/]+\/[^/.]+)/.exec(url ?? '')
+	if (!match) throw new Error('no GITHUB_REPOSITORY and no github repository in package.json')
+	return match[1]
+}
+
 const frontmatter = `---
 title: Changelog
-description: Release notes, generated by semantic-release.
+description: Release notes, generated by semantic-release and published to GitHub Releases.
 ---
 
 `
 
-let body = ''
+const footer = (repo, note) =>
+	`\n\n---\n\n${note}Every entry above is generated by semantic-release and published to [GitHub Releases](https://github.com/${repo}/releases). Anything older than the first GitHub Release is recorded in [CHANGELOG.md](https://github.com/${repo}/blob/main/CHANGELOG.md).\n`
+
+async function fetchReleases(repo) {
+	const headers = { Accept: 'application/vnd.github+json' }
+	// Optional: lifts the 60/hr unauthenticated rate limit. CI passes it; local
+	// builds work fine without it at a typical repo's release count.
+	// ponytail: one page of 100. Paginate when a repo outgrows it.
+	const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN
+	if (token) headers.Authorization = `Bearer ${token}`
+
+	const res = await fetch(`https://api.github.com/repos/${repo}/releases?per_page=100`, { headers })
+	if (!res.ok) throw new Error(`GitHub API ${res.status} ${res.statusText}`)
+	return res.json()
+}
+
+function render(releases) {
+	// The API does not guarantee date order, and a release body already carries
+	// its own version heading and date — so sort here and emit bodies verbatim.
+	const sorted = releases
+		.filter((r) => !r.draft && r.body?.trim())
+		.sort((a, b) => new Date(b.published_at) - new Date(a.published_at))
+
+	if (sorted.length === 0) throw new Error('no releases with a body')
+	return sorted.map((r) => r.body.trim()).join('\n\n')
+}
+
+let repo = ''
+let body
 try {
-	body = readFileSync(source, 'utf8')
-} catch {
-	body = '# Changelog\n\nNo releases recorded yet.\n'
+	repo = resolveRepo()
+	body = render(await fetchReleases(repo)) + footer(repo, '')
+	console.log(`sync-changelog: built from ${repo} GitHub Releases`)
+} catch (error) {
+	// Never fail the docs build on a network blip — fall back to the frozen file
+	// and say so on the page rather than shipping a silently truncated one.
+	console.warn(`sync-changelog: ${error.message} — falling back to CHANGELOG.md`)
+	try {
+		body =
+			readFileSync(resolve(repoRoot, 'CHANGELOG.md'), 'utf8').trim() +
+			(repo
+				? footer(
+						repo,
+						'**This page was built from the repository CHANGELOG.md because GitHub Releases could not be reached, and may be out of date.** '
+					)
+				: '')
+	} catch {
+		body = '# Changelog\n\nNo releases recorded yet.\n'
+	}
 }
 
 mkdirSync(dirname(target), { recursive: true })

package/tooling/semantic-release/github.mjs

@@ -41,7 +41,10 @@ export default {
 		[
 			'@semantic-release/github',
 			{
-				assets: ['CHANGELOG.md', 'package.json', 'README.md'],
+				// README.md only. CHANGELOG.md and package.json are frozen on the
+				// default branch (see the note at the bottom of this file), so
+				// attaching them to each release would ship stale artifacts.
+				assets: ['README.md'],
 				message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
 				// Don't label the "release is failing" issue. The default is
 				// ['semantic-release'], and GitHub rejects issue creation outright when
@@ -52,12 +55,6 @@ export default {
 				labels: false,
 			},
 		],
-		[
-			'@semantic-release/changelog',
-			{
-				changelogFile: 'CHANGELOG.md',
-			},
-		],
 		// npm publishing goes through OIDC trusted publishing — no NPM_TOKEN. The
 		// release job runs with `id-token: write` and npm (>=11.5.1) authenticates
 		// via the GitHub Actions trusted publisher configured on the package, and
@@ -65,19 +62,34 @@ export default {
 		// @semantic-release/npm; a public repo that only wants GitHub releases can
 		// opt out with NPM_PUBLISH=false (the version in package.json is still bumped).
 		['@semantic-release/npm', { npmPublish: process.env.NPM_PUBLISH !== 'false', pkgRoot: '.' }],
-		[
-			'@semantic-release/git',
-			{
-				assets: ['package.json', 'CHANGELOG.md'],
-				message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
-				// Skip hooks by disabling Husky
-				skipCommitHooks: true,
-				prepareCmd: 'pnpm exec biome format package.json',
-			},
-		],
 	],
 }
 
+// Two plugins are deliberately absent, and the second follows from the first.
+//
+// @semantic-release/git — it committed package.json + CHANGELOG.md and pushed
+// them straight to the default branch. `fix github-settings` installs a
+// `code-scanning-main` ruleset requiring CodeQL results on that branch, and a
+// commit created seconds earlier can never have them: the push fails with
+// GH013. Unwinnable rather than flaky — the commit must exist to be scanned,
+// and be scanned to exist. See rtorcato/repo-tooling#417.
+//
+// @semantic-release/changelog — it writes CHANGELOG.md, which only
+// @semantic-release/git ever committed back. Without that push it regenerates
+// the file inside the CI workspace and throws it away every release, implying
+// CHANGELOG.md is still maintained when it is frozen. The two are one feature
+// in two plugins; shipping one without the other is the trap, not the fix.
+//
+// The consequence, stated plainly because it is easy to miss: **CHANGELOG.md
+// and the `version` field in package.json stop moving on the default branch.**
+// The git tag, the npm publish and the GitHub Release are unaffected and are
+// the source of truth for what shipped. Build any user-facing changelog from
+// GitHub Releases — `repo-tooling copy docusaurus-sync-changelog` does exactly
+// that — never from the frozen file.
+//
+// Adding a bypass actor to the ruleset would also make the push succeed. It is
+// not the answer: it exempts the one commit nobody reviews.
+
 // [
 // 	'@semantic-release/exec',
 // 	{