rman 2.3.1 → 2.4.0

package/builtins/platforms/node/services/version-plan.service.d.ts

@@ -27,9 +27,7 @@ export declare class NodeVersionPlanService extends VersionPlanService {
      * npm's dependency ranges, read as a release policy. What decides each case is whether a
      * dependent's **range floor** has to move for a consumer to get a correct install:
      *
-     * - **patch** - only the changed packages. A dependent's `^1.2.0` already resolves to `1.2.1`,
-     *   and a patch adds nothing for the dependent to require, so nothing downstream has to ship for
-     *   consumers to receive it.
+     * - **patch** - the changed packages **and** every transitive in-group dependent.
      * - **minor** - also every transitive in-group dependent. A minor adds API; a dependent that uses
      *   it is only correct once its own published range requires the new floor, and a range lives in
      *   a manifest, which only a release puts on the registry.

package/builtins/platforms/node/services/version-plan.service.js

@@ -28,9 +28,7 @@ export class NodeVersionPlanService extends VersionPlanService {
      * npm's dependency ranges, read as a release policy. What decides each case is whether a
      * dependent's **range floor** has to move for a consumer to get a correct install:
      *
-     * - **patch** - only the changed packages. A dependent's `^1.2.0` already resolves to `1.2.1`,
-     *   and a patch adds nothing for the dependent to require, so nothing downstream has to ship for
-     *   consumers to receive it.
+     * - **patch** - the changed packages **and** every transitive in-group dependent.
      * - **minor** - also every transitive in-group dependent. A minor adds API; a dependent that uses
      *   it is only correct once its own published range requires the new floor, and a range lives in
      *   a manifest, which only a release puts on the registry.
@@ -41,6 +39,30 @@ export class NodeVersionPlanService extends VersionPlanService {
      * versions instead has to release every dependent for a patch as well, and one that resolves
      * dependencies from source may not need a release for any of it.
      */
+    /* **`patch` answered `'changed'` until 2.4, on reasoning that is correct and too narrow.** The
+     * range argument holds: `^1.2.0` resolves to `1.2.1`, so a consumer receives the fix with no
+     * dependent republished, and the floor a dependent declares stays true. What it leaves out is
+     * that a dependent's *published artifact* was built against the old code - anything that bundles,
+     * vendors, or type-checks against its dependency ships the pre-fix version until it is released
+     * again, and under this default nothing ever released it.
+     *
+     * So the two answers differ in which failure they prefer, and the cheaper one is now the default:
+     * releasing a dependent that strictly did not need it is visible churn, while not releasing one
+     * that did is invisible - the same asymmetry `cascade`'s own doc states and `cascadeFor` already
+     * resolves by taking the widest.
+     *
+     * **`patch` and `minor` are now the same answer, and that is a real loss of resolution**, not a
+     * tidy-up: the table no longer distinguishes them, so a future reason to treat a patch
+     * differently has nowhere to live. It is kept as two entries rather than collapsed for exactly
+     * that reason.
+     *
+     * **It also makes `'changed'` unreachable under npm.** Nothing here returns it any more, and a
+     * repository writing `version.cascade: changed` gets no narrowing, because that key is a floor
+     * and never a ceiling. The value stays meaningful - it says "no floor of my own", which is what
+     * an ecosystem answering `'changed'` would still honour - but in a Node repository it is a no-op.
+     *
+     * A repository wanting the whole group on a patch writes `version.cascade: group`; one wanting
+     * the old narrow behaviour cannot ask for it, and has to say so if that turns out to matter. */
     cascade(bump) {
         /** Only semver's three can arrive - `getPlan` validates against `bumpNames` and
          *  `packageJsonManifest` leaves the scheme at the semver default. The fallback is for a scheme
@@ -52,7 +74,7 @@ export class NodeVersionPlanService extends VersionPlanService {
 }
 /** semver's bump names against how far each has to reach - see `NodeVersionPlanService.cascade`. */
 const CASCADE_BY_BUMP = {
-    patch: 'changed',
+    patch: 'dependents',
     minor: 'dependents',
     major: 'group',
 };

package/commands/version.command.d.ts

@@ -73,6 +73,12 @@ declare const config: {
         describe: string;
         type: "string";
     };
+    cascade: {
+        target: "config";
+        describe: string;
+        type: "string";
+        choices: readonly ["changed", "dependents", "group"];
+    };
     releaseTagPattern: {
         target: "config";
         describe: string;
@@ -266,6 +272,12 @@ declare const versionCommand: (app: import("../index.js").RmanApplication) => {
             describe: string;
             type: "string";
         };
+        cascade: {
+            target: "config";
+            describe: string;
+            type: "string";
+            choices: readonly ["changed", "dependents", "group"];
+        };
         releaseTagPattern: {
             target: "config";
             describe: string;

package/commands/version.command.js

@@ -94,6 +94,18 @@ const config = {
             'commit\'s own group shares one version. Default "chore(release): v{version}".',
         type: 'string',
     },
+    cascade: {
+        target: 'config',
+        describe: 'The narrowest this repository is willing to release a group: "changed" (only packages with ' +
+            'commits of their own, i.e. no floor of your own), "dependents" (those plus in-group ' +
+            'packages depending on them), or "group" (every member, so the group stays in lockstep). ' +
+            'A floor, not a ceiling: the technology still widens it where a narrower release would ' +
+            "leave a dependent's published artifact or range floor behind - under npm that is " +
+            '"dependents" for a patch or a minor and the whole group for a major, so "changed" is a ' +
+            'no-op there. Per-package cascaded; a group whose members disagree takes the widest.',
+        type: 'string',
+        choices: ['changed', 'dependents', 'group'],
+    },
     releaseTagPattern: {
         target: 'config',
         describe: "Tag naming the repository's own release, as opposed to the per-package tags " +

package/constants.js

@@ -1 +1 @@
-export const version = '2.3.1';
+export const version = '2.4.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {

package/services/version-plan.service.d.ts

@@ -123,6 +123,12 @@ export declare abstract class VersionPlanService {
      * a dependent that pins exact versions is a broken install.
      */
     protected cascadeFor(members: Package[], bump: string): VersionPlanService.Cascade;
+    /**
+     * `.rmanrc "version.cascade"` for a group, or `undefined` where no member declares one - in which
+     * case the technology's own `cascade` answers. Members disagreeing take the widest, the same rule
+     * and the same direction `cascadeFor` applies to two technologies.
+     */
+    protected declaredCascade(members: Package[]): VersionPlanService.Cascade | undefined;
     /**
      * The largest bump `commits` ask for, in `scheme`'s own names.
      *
@@ -157,8 +163,15 @@ export declare abstract class VersionPlanService {
      * bump (or `undefined` for one with no real commits since its last boundary) - `undefined`
      * here always means "unchanged", never "explicit version" (that path is handled separately).
      *
-     * How wide the bump goes is `cascade`'s answer, and only its answer: an explicit
-     * `rman version <v>` has no bump left to consult, so it reaches the changed members alone.
+     * How wide the bump goes is `cascade`'s answer, and only its answer.
+     *
+     * **An explicit `rman version <v>` reaches every member of the group, and the old wording here
+     * said the opposite.** It read "so it reaches the changed members alone", which is true of the
+     * code and false as a sentence: `getPlan` marks *every* eligible package changed with reason
+     * `explicit version <v>`, and a group's members are drawn from `eligible`, so "the changed
+     * members" is all of them. Measured while adding `version.cascade` - a spec asserting the
+     * narrow reading failed. A repository in lockstep therefore keeps it when the number is chosen
+     * by hand, with no cascade involved.
      */
     protected computeGroupPlan(key: string, members: Package[], changeByPackage: Map<string, VersionPlanService.Change>, explicitVersion: string | undefined, preid: string | undefined, entries: Map<string, VersionPlanService.Entry>): void;
     /**

package/services/version-plan.service.js

@@ -218,12 +218,63 @@ export class VersionPlanService {
      * a dependent that pins exact versions is a broken install.
      */
     cascadeFor(members, bump) {
+        /** **A declared cascade is a floor, never a ceiling** - see `declaredCascade`. It joins the
+         *  technologies' answers and the widest of the set wins, which is the rule already applied to
+         *  two technologies disagreeing. */
         const answers = new Set(members.map(m => this.plannerFor(m).cascade(bump)));
+        const declared = this.declaredCascade(members);
+        if (declared)
+            answers.add(declared);
         for (const widest of CASCADE_WIDEST_FIRST)
             if (answers.has(widest))
                 return widest;
         return 'changed';
     }
+    /**
+     * `.rmanrc "version.cascade"` for a group, or `undefined` where no member declares one - in which
+     * case the technology's own `cascade` answers. Members disagreeing take the widest, the same rule
+     * and the same direction `cascadeFor` applies to two technologies.
+     */
+    /* **Why a repository gets to say this at all.** `cascade` is abstract because two of its inputs
+     * are an ecosystem's: whether a caret range already carries a patch to a dependent, and whether
+     * a floor left behind is a broken install. Those npm answers are right. What they cannot answer
+     * is whether a repository wants **one number across its whole product** - which is a release
+     * identity decision, not a fact about a package manager, and there was nowhere to state it.
+     *
+     * Measured on `panates/sqb`: 17 packages, `group: true`, every one published at 6.0.10 since it
+     * moved off rman 1.x's `version.unified: true` - and a `fix:` in two of them planned
+     * `6.0.10 -> 6.0.11` for those two and `no-change` for the other fifteen. Correct on ranges (all
+     * 39 internal edges are caret peers, so the fix reaches dependents with no republish) and still
+     * the wrong answer for that repository: the divergence is permanent, since a group's next
+     * baseline is `highestVersion(members)`, and every README and issue there is written in terms of
+     * one number.
+     *
+     * **The default is unchanged**, so this costs nothing to a repository that never writes the key.
+     *
+     * **It is not a safety valve, and must not be documented as one.** A change that can break a
+     * dependent is a `feat:` or a `feat!:`; republishing the dependent under a new number does not
+     * make a behavioural break safe, it only renumbers it. The lever for that is the bump size, which
+     * comes from the commit message.
+     *
+     * **A floor, never a ceiling, and that asymmetry is the whole safety of the key.** `cascadeFor`
+     * adds this answer to the technologies' and takes the widest, so a repository can ask for a
+     * *wider* release than npm requires and cannot ask for a narrower one. The direction matters
+     * because the two mistakes are not symmetric, which this class's own doc already records: too
+     * wide republishes a package that did not need it - visible and harmless - while too narrow
+     * leaves a dependent's published range floor wrong, which is a broken install. Concretely, a
+     * repository writing `cascade: changed` still gets the whole group on a **major**, because
+     * `^1.0.0` does not admit `2.0.0` and an in-group dependent left at the old number would declare
+     * a range its own group no longer satisfies. So `changed` means "no floor of my own", not "never
+     * more than the changed packages". */
+    declaredCascade(members) {
+        const declared = new Set(members.map(m => m.config?.version?.cascade).filter((c) => !!c));
+        if (!declared.size)
+            return undefined;
+        for (const widest of CASCADE_WIDEST_FIRST)
+            if (declared.has(widest))
+                return widest;
+        return undefined;
+    }
     /**
      * The largest bump `commits` ask for, in `scheme`'s own names.
      *
@@ -284,8 +335,15 @@ export class VersionPlanService {
      * bump (or `undefined` for one with no real commits since its last boundary) - `undefined`
      * here always means "unchanged", never "explicit version" (that path is handled separately).
      *
-     * How wide the bump goes is `cascade`'s answer, and only its answer: an explicit
-     * `rman version <v>` has no bump left to consult, so it reaches the changed members alone.
+     * How wide the bump goes is `cascade`'s answer, and only its answer.
+     *
+     * **An explicit `rman version <v>` reaches every member of the group, and the old wording here
+     * said the opposite.** It read "so it reaches the changed members alone", which is true of the
+     * code and false as a sentence: `getPlan` marks *every* eligible package changed with reason
+     * `explicit version <v>`, and a group's members are drawn from `eligible`, so "the changed
+     * members" is all of them. Measured while adding `version.cascade` - a spec asserting the
+     * narrow reading failed. A repository in lockstep therefore keeps it when the number is chosen
+     * by hand, with no cascade involved.
      */
     computeGroupPlan(key, members, changeByPackage, explicitVersion, preid, entries) {
         const label = this.groupLabel(key);
@@ -313,6 +371,12 @@ export class VersionPlanService {
             to = scheme.next(current, bump, { preid });
         }
         const bumping = new Set(changed);
+        /** **`'changed'` with no bump is not a narrowing, because there is nothing left to narrow.** An
+         *  explicit `rman version <v>` puts *every* eligible package into `changeByPackage` (see
+         *  `getPlan`), and a group's members are drawn from `eligible` alone - so `changed` already
+         *  holds all of them and no cascade could add one. Measured while wiring `version.cascade`: a
+         *  declared cascade consulted here is dead code, and the spec written for it asserted a reason
+         *  string that never renders. */
         const cascade = bump ? this.cascadeFor(members, bump) : 'changed';
         if (cascade === 'group') {
             for (const m of members)
@@ -334,6 +398,11 @@ export class VersionPlanService {
         }
         /** Why a member with no commits of its own is being bumped. `'group'` reaches members that
          *  depend on nothing at all, so calling those a "dependent" was simply untrue. */
+        /* `bump` is always set where this string is *read*: a member reaches it only through
+         * `own?.reason ?? inherited`, and the one path with no bump - an explicit version - gives every
+         * member an `own.reason` of its own (`explicit version <v>`). So there is no
+         * `a undefined change` to guard against here. Checked rather than assumed, because the
+         * template reads as though there were. */
         const inherited = cascade === 'group' ? `in-group member of a ${bump} change` : `in-group dependent of a ${bump} change`;
         for (const m of members) {
             if (bumping.has(m)) {