@rtorcato/repo-tooling 3.10.2 → 3.11.1

package/dist/base/github-settings.js

@@ -115,7 +115,15 @@ async function probeRepo(exec) {
             autoMerge: d.allow_auto_merge === true,
             squashMerge: d.allow_squash_merge === true,
             deleteOnMerge: d.delete_branch_on_merge === true,
-            mergeVisible: ['allow_auto_merge', 'allow_squash_merge', 'delete_branch_on_merge'].every((k) => typeof d[k] === 'boolean'),
+            mergeCommit: d.allow_merge_commit === true,
+            rebaseMerge: d.allow_rebase_merge === true,
+            mergeVisible: [
+                'allow_auto_merge',
+                'allow_squash_merge',
+                'delete_branch_on_merge',
+                'allow_merge_commit',
+                'allow_rebase_merge',
+            ].every((k) => typeof d[k] === 'boolean'),
         },
     };
 }
@@ -197,6 +205,16 @@ async function checkBranchProtection(exec, nwo, branch) {
         };
     return { check, status: 'ok', detail: `${branch} protected per standard` };
 }
+/**
+ * Squash is required *and exclusive* (#410). Leaving merge-commit or rebase
+ * enabled only makes them available on the merge button, and one mis-click puts
+ * every intermediate branch commit on the default branch: semantic-release then
+ * reads subjects nobody reviewed (a stray `fix:` inside a docs PR cuts a
+ * release), and `ai-issue-loop`'s Pass 2 stops finding the `(#N)` squash subject
+ * it uses to confirm work landed, so worktrees leak. Observed on `js-common`
+ * #204, whose CONTRIBUTING already said squash-only — the rule existed, nothing
+ * enforced it.
+ */
 function checkMergeSettings(info) {
     const check = 'Merge settings';
     // The token can't see the merge-setting fields (no admin:read) — skip rather
@@ -210,14 +228,18 @@ function checkMergeSettings(info) {
         deltas.push('squash-merge disabled');
     if (!info.deleteOnMerge)
         deltas.push('delete-branch-on-merge disabled');
+    if (info.mergeCommit)
+        deltas.push('merge commits allowed (squash only)');
+    if (info.rebaseMerge)
+        deltas.push('rebase merging allowed (squash only)');
     if (deltas.length)
         return {
             check,
             status: 'drift',
             detail: deltas.join('; '),
-            hint: 'Enable auto-merge, squash-merge, and delete-branch-on-merge in repo settings',
+            hint: 'Enable auto-merge and delete-branch-on-merge, and make squash the only merge method',
         };
-    return { check, status: 'ok', detail: 'auto-merge, squash-merge, delete-on-merge all on' };
+    return { check, status: 'ok', detail: 'squash-only, auto-merge and delete-on-merge on' };
 }
 async function checkWorkflowPermissions(exec, nwo) {
     const check = 'Workflow permissions';
@@ -370,7 +392,7 @@ export function buildGhApplyCommands(state) {
     const commands = [];
     if (state.merge)
         commands.push({
-            label: 'merge settings (auto-merge, squash, delete-on-merge)',
+            label: 'merge settings (squash-only, auto-merge, delete-on-merge)',
             args: [
                 'api',
                 '-X',
@@ -382,6 +404,10 @@ export function buildGhApplyCommands(state) {
                 'allow_squash_merge=true',
                 '-F',
                 'delete_branch_on_merge=true',
+                '-F',
+                'allow_merge_commit=false',
+                '-F',
+                'allow_rebase_merge=false',
             ],
         });
     if (state.protection)

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.10.2",
+	"version": "3.11.1",
 	"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/skills/ai-issue-loop/SKILL.md

@@ -806,10 +806,14 @@ times against one trivial issue and watch the labels advance.
 ## Repo prerequisites
 
 ```bash
-gh api repos/$OWNER_REPO --jq '{allow_squash_merge, allow_auto_merge, delete_branch_on_merge}'
+gh api repos/$OWNER_REPO --jq '{allow_squash_merge, allow_merge_commit, allow_rebase_merge, allow_auto_merge, delete_branch_on_merge}'
 gh api repos/$OWNER_REPO/branches/main/protection --jq '{contexts: .required_status_checks.contexts, reviews: .required_pull_request_reviews}'
 ```
 
-Need: squash + auto-merge + delete-on-merge all true, at least one required
-status check, and `required_pull_request_reviews: null`. See the
-`github-pr-workflow` skill for the one-time bootstrap.
+Need: auto-merge + delete-on-merge + squash all true, **`allow_merge_commit` and
+`allow_rebase_merge` both false**, at least one required status check, and
+`required_pull_request_reviews: null`. Squash has to be the *only* method, not
+merely an available one: Pass 2 confirms a PR landed by finding its `(#N)` squash
+subject on `main`, and a merge commit leaves nothing to find — the worktree then
+survives every tick and its `ai-wip` slot leaks. See the `github-pr-workflow`
+skill for the one-time bootstrap.

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',
 // 	{