Skip to content

Commit 5438969

Browse files
committed
chore(config): delete cap-major-bumps.mjs, changesets 3 removed its cause
Скрипт срезал любой мажор, пришедший без явного major-changeset. Он жил ради changesets/changesets#822: на 0.x пакете peer-диапазон workspace:^ patch-only, поэтому минор ядра выводил peer из диапазона, и changesets эскалировал зависимого до мажора. Сам файл был помечен PENDING REMOVAL с гейтом «первый реальный релиз с минором ядра без всплывшего мажора» — гейт прошёл и остался непрочитанным. Три замера на реальном дереве (git archive HEAD в чистый воркспейс, changeset version под @changesets/cli 3.0.3): 1. Гейт, который скрипт назначил себе сам: минор ядра 0.136.5 -> 0.137.0 тронул 23 манифеста и дал НОЛЬ мажоров, вердикт самого скрипта — «No major bumps detected». Кроме ядра двинулся только router-benchmarks, патчем, через ребро dependencies. 2. Инструмент дискриминирует: инъекция 1.0.0 в пост-version манифест дала «Blocked major bump ... Capped 1». Значит вердикт из (1) — это измерение, а не no-op. 3. Причины больше нет в апстриме: откат peer одного адаптера на до-фиксовый workspace:^ всё равно даёт патч (0.36.0 -> 0.36.1), а не мажор. changesets/changesets#822 и changesets/changesets#2090 закрыты completed 2026-06-24, мажор v3 несёт фикс. Миной на дороге к 1.0 он не был: applyBump возвращал null на уровне major, вызывающий делал continue, поэтому явный major-changeset проходил насквозь. Правило «pre-1.0 не берёт мажор» сохраняет единственного живого исполнителя в .changeset/check-changeset.mjs. Попутно сняты две повисшие ссылки на удалённый файл (syncpack.config.mjs, check-changeset.mjs) и исправлены два утверждения CLAUDE.md: «minor bump триггерит мажор от changesets» опровергнуто замером (3), а «each declares workspace:>=0.1.0» — неверно, changeset version двигает peer-пол на каждом релизе для пакетов с ребром devDependencies на ядро. Claude-Session: https://claude.ai/code/session_01Ws4eQ4YAetztqb4HPg86Sj
1 parent bc37705 commit 5438969

7 files changed

Lines changed: 37 additions & 229 deletions

File tree

‎.changeset/cap-major-bumps.mjs‎

Lines changed: 0 additions & 214 deletions
This file was deleted.

‎.changeset/check-changeset.mjs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -150,8 +150,8 @@ function validateChangeset(name, content, registry) {
150150
`"${pkg}" is private — changeset the public consumer whose behavior changed`,
151151
);
152152
}
153-
// Pre-1.0 (0.x) packages never take a major bump (README pre-1.0 guideline;
154-
// mirrors cap-major-bumps.mjs). Auto-relaxes once a package reaches 1.0.
153+
// Pre-1.0 (0.x) packages never take a major bump (README pre-1.0 guideline).
154+
// This is the only thing enforcing it. Auto-relaxes once a package reaches 1.0.
155155
if (level === "major" && /^0\./.test(meta.version)) {
156156
errors.push(
157157
`"${pkg}" is pre-1.0 (${meta.version}) — use "minor" for breaking changes, not "major"`,

‎CLAUDE.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -131,8 +131,8 @@ pnpm resolve:dependabot <PR#> # Rebase+dedupe a Dependabot PR — conflicting O
131131
- knip uses `ignoreWorkspaces: ["examples/**", "benchmarks"]` — example apps are excluded from unused code analysis
132132
- Vue examples use `vue-tsc -b` (not `tsc -b`) for SFC type checking
133133
- Svelte examples use `vite build` only (no tsc step — Svelte compiler handles types)
134-
- Never use `workspace:^` for `peerDependencies` on 0.x packages — in semver `^0.x.y` is patch-only range, so any minor bump breaks the range and triggers a major bump from changesets
135-
- A peer-dependent takes a **`patch`**, and only when the new version leaves its declared range. Changesets 3 has no "peer bump ⇒ major" rule and no `onlyUpdatePeerDependentsWhenOutOfRange` flag (changesets#2090); `.changeset/config.json` carries neither. ⚠ The count of internal peers is deliberately not repeated here — `grep -l '@real-router/core' packages/*/package.json` and read their `peerDependencies`. Each declares `workspace:>=0.1.0`, a range a core release cannot leave, so a core bump reaches them through `dependencies` or not at all
134+
- Never use `workspace:^` for `peerDependencies` on 0.x packages — `^0.x.y` is patch-only in semver, so a core minor leaves the range and every consumer hits a peer conflict. ⚠ It no longer escalates to a **major**: changesets 3 dropped that rule (changesets#822, closed `completed` 2026-06-24) — measured, a `workspace:^` peer-dependent takes a `patch`. The rule stands on the consumer's range, not on the bump level
135+
- A peer-dependent takes a **`patch`**, and only when the new version leaves its declared range. Changesets 3 has no "peer bump ⇒ major" rule and no `onlyUpdatePeerDependentsWhenOutOfRange` flag (changesets#2090); `.changeset/config.json` carries neither. ⚠ The count of internal peers is deliberately not repeated here — `grep -l '@real-router/core' packages/*/package.json` and read their `peerDependencies`. Each declares `workspace:>=`, a range a core release cannot leave, so a core bump reaches them through `dependencies` or not at all. ⚠ The floor itself is not stable: `changeset version` rewrites it to the new core version on every release, but only for packages that ALSO carry the `devDependencies` edge on core — the one package without that edge still sits on its original floor. Read the manifests; they do not share a value
136136
- Runtime validation is opt-in via `@real-router/validation-plugin` — core ships with structural guards plus a small always-on set, enumerated in [packages/core/CLAUDE.md](packages/core/CLAUDE.md) § _Invariant Guards_. ⚠ Neither the count nor the members are repeated here — a second copy of an enumerable set goes stale on its own schedule, and this one did, twice: it still read `five` after #1888 and after #2088 had each added one. Separately, an always-on **mode gate** (#1575) normalises rather than detects — a query key the active `queryParamsMode` will not print never enters `state.search`, so `state.search` ⊆ what `state.path` shows, in every mode
137137
- Plugins publish per-route data via `state.context.<namespace>` using `api.claimContextNamespace()` + `claim.write()` + `claim.release()` — mirrors `extendRouter()` pattern. Module augmentation on `@real-router/core/types` for typed namespaces
138138
- **A boolean parameter is a hypothesis, not a decision — study before adding one.** Wanting to add a `boolean` argument (positional, defaulted, or a `boolean` field on an options bag) means running `.claude/prompts/boolean-flag-audit.md` over the signature FIRST. The four signals it looks for are all measured against the CALL SITES, never read off the signature: the flag partitions callers into disjoint sets that never pass both polarities; some OTHER parameter gets the same constant from most callers; the flag names a role the caller already declared further up the chain; or 2^k combinations exist and only k+1 are reachable. Any of them means the function is two functions, and naming them removes more than the flag. Measured precedent: #1928 added `freezeResult` to `mergeWithDefault`; the audit found seven call sites in two disjoint sets, five of them passing `undefined` to the parameter the function is NAMED after, and the split (`mergePathChannel` / `mergeQueryChannel` / `adoptForeignBag`) removed **three** parameters plus a footgun the old signature could only warn about. ⚠ Moving a positional boolean into an options object is NOT the fix — a named field cures readability at the call site and none of the four signals

‎IMPLEMENTATION_NOTES.md‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -702,9 +702,8 @@ pnpm version # runs changeset version + sync + changelog aggregation
702702
Scripts executed:
703703

704704
1. `changeset version` — updates package versions and changelogs
705-
2. `.changeset/cap-major-bumps.mjs` — prevents accidental major bumps in pre-1.0 packages (caps at minor)
706-
3. `.changeset/sync-version.mjs` — syncs root package.json version from core
707-
4. `.changeset/aggregate-changelog.mjs` — aggregates package changelogs to root CHANGELOG.md
705+
2. `.changeset/sync-version.mjs` — syncs root package.json version from core
706+
3. `.changeset/aggregate-changelog.mjs` — aggregates package changelogs to root CHANGELOG.md
708707

709708
Root package is private and never published (cosmetic only).
710709

@@ -10009,3 +10008,25 @@ carries none of it and this line is the only record that they existed.
1000910008
⚠ `CHANGELOG.md` and `packages/core/CHANGELOG.md` keep their probe paths. A
1001010009
published changelog records what was measured on the day it shipped; rewriting it
1001110010
to hide that the artefact is gone would falsify the release record.
10011+
10012+
## `cap-major-bumps.mjs` is deleted — changesets 3 removed the cause it guarded (2026-09-15)
10013+
10014+
### Problem
10015+
10016+
The 204-line post-`version` script capped any major bump that arrived without an explicit `major` changeset. It existed for [changesets#822](https://github.com/changesets/changesets/issues/822): on a 0.x package a `workspace:^` peer range is patch-only, so a core minor took the peer out of range and changesets escalated the dependent to a **major**. The section "peerDep range fix — `workspace:^` → `workspace:>=0.1.0`" above narrowed the cause at the source and marked this file PENDING REMOVAL, gated on the first real release with a core minor bump confirming no major surfaces. The gate passed and went unread.
10017+
10018+
Its header had gone stale on two independent claims. The three plugins it named no longer declare `>=0.1.0` — `changeset version` rewrites a `>=` peer floor to the new core version on every release, for every package that also carries a `devDependencies` edge on core, so they sit on the current core minor. And `onlyUpdatePeerDependentsWhenOutOfRange: true`, which the header called load-bearing, is not in `.changeset/config.json` at all.
10019+
10020+
### Solution
10021+
10022+
Deleted, and dropped from the root `version` script. Three measurements on the real tree (`git archive HEAD` into a scratch workspace, `changeset version` under @changesets/cli 3.0.3):
10023+
10024+
1. **The gate it set for itself.** A core minor (0.136.5 → 0.137.0) touched 23 manifests and produced **zero** majors; the script's own verdict was `No major bumps detected`. The only other package that moved was `router-benchmarks`, by a `patch`, through its `dependencies` edge — no public peer-dependent was bumped at all.
10025+
2. **The instrument discriminates.** Injecting `1.0.0` into a post-version manifest produced `Blocked major bump … Capped 1`, so the verdict in (1) is a measurement rather than a no-op.
10026+
3. **The cause is gone upstream.** Forcing one adapter's peer back to the pre-fix `workspace:^` still produced a `patch` (0.36.0 → 0.36.1), not a major. changesets#822 and changesets#2090 are both closed `completed` (2026-06-24), and the v3 major ships that fix.
10027+
10028+
It was never a hazard on the road to 1.0: `applyBump` returned `null` for level `major` and the caller skipped, so an explicit `major` changeset always passed through. The pre-1.0 "no major" rule keeps its only live enforcer in `.changeset/check-changeset.mjs`, which rejects a `major` changeset for any package still on `0.x` and auto-relaxes once a package reaches 1.0.
10029+
10030+
### Why
10031+
10032+
Measurement (3) is what makes this a deletion rather than a bet. The range-shape fix and the upstream fix are two independent layers over one cause, and the control shows the upstream layer alone now carries it — reverting our range shape would not resurrect the major. What the guard still cost is a reader: a 204-line script in the release critical path whose header reasons about a config option the repo does not set, and about peer floors that have since moved.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@
4848
"size": "size-limit",
4949
"commit": "czg",
5050
"changeset": "changeset",
51-
"version": "changeset version && node .changeset/cap-major-bumps.mjs && node .changeset/sync-version.mjs && node .changeset/aggregate-changelog.mjs",
51+
"version": "changeset version && node .changeset/sync-version.mjs && node .changeset/aggregate-changelog.mjs",
5252
"danger:local": "danger local --dangerfile dangerfile.ts",
5353
"lint:published-versions": "node scripts/check-published-versions.mjs",
5454
"lint:anchors": "pnpm -F @real-router/core exec vitest run tests/functional/line-anchor-authority.test.ts --coverage.enabled=false"

‎packages/core/tests/functional/claim-census-ledger.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1398,8 +1398,9 @@
13981398
"d46204beacb8",
13991399
"97c03e73c3d4",
14001400
"40caf8a6c420",
1401-
"7c5dcca68645",
1402-
"5be710f2607b",
1401+
"6e00795bbb1a",
1402+
"546608363777",
1403+
"8d5592bdde67",
14031404
"668d782f1141",
14041405
"c47f391e0256"
14051406
],

‎syncpack.config.mjs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -123,11 +123,11 @@ export default {
123123
dependencies: [
124124
"@real-router/*",
125125
],
126-
// prod/dev only — peer deps must NOT be pinned to workspace:^ (on 0.x,
127-
// ^0.x.y is patch-only → minor bump → unwanted major via changesets #822;
128-
// this is the root the cap-major-bumps.mjs workaround papered over). Peer
129-
// ranges are governed by the ">= ranges" semverGroup instead. Without this
130-
// exclusion the pin overrode that intent (DiffersToPin).
126+
// prod/dev only — peer deps must NOT be pinned to workspace:^: on 0.x,
127+
// ^0.x.y is patch-only, so a core minor leaves the range and every
128+
// consumer sees a peer conflict. Peer ranges are governed by the
129+
// ">= ranges" semverGroup instead. Without this exclusion the pin
130+
// overrode that intent (DiffersToPin).
131131
dependencyTypes: ["prod", "dev"],
132132
pinVersion: "workspace:^",
133133
policy: "pinned",

0 commit comments

Comments
 (0)