rman 2.13.0 → 2.15.0

package/README.md

@@ -88,6 +88,7 @@ worked examples of every single command, see **[docs/cli-rman.md](https://github
 | [`config`](#rman-config) | Prints the effective `.rmanrc` config for the current directory's package. |
 | [`diff [package]`](#rman-diff-package) | Shows the git diff since a package's (or the repo's) last release tag. |
 | [`changelog`](#rman-changelog) | Generates a changelog per package from unreleased commits. |
+| [`deps [names..]`](#rman-deps-names) | Lists dependencies with a newer version; `-u` upgrades them. |
 | [`version [bump]`](#rman-version-bump) | Bumps versions of changed packages (and their dependents). |
 | [`publish`](#rman-publish) | Publishes every package whose version isn't on its registry yet. |
 | [`github-release`](#rman-github-release) | Creates the repository's GitHub Release for its release tag. |
@@ -129,16 +130,17 @@ Options shared across several commands:
 
 - **`skip`** (`.rmanrc`, per package): leave this package alone - honoured by every command that
   *acts* on packages, ignored by `list`, which reports on them.
-- **Package filtering** (`list`, `run`/`build`/`test`, `exec`, `version`, `changelog`, and a
-  plugin's own commands): `--scope <glob>`, `--ignore <glob>`, `--deps`, `--dependents` - see
-  [Package filtering](https://github.com/panates/rman/blob/main/docs/rman.md#package-filtering-scopeignoredepsdependents)
+- **Package filtering** (`list`, `run`/`build`/`test`, `exec`, `version`, `changelog`, `publish`,
+  `deps`, `clean`, `ci`, and a plugin's own commands): `--scope <glob>`, `--ignore <glob>`, `--deps`, `--dependents` - see
+  [Package filtering](https://github.com/panates/rman/blob/main/docs/rman.md#package-filtering-scopeignoreplatformdepsdependents)
   for the full semantics. **`--scope /` is the repository's own root package** - the same `/`
   `.rmanrc`'s `"[/]"` block uses, and not a glob, so `--scope '*'` means the members and a glob
   never picks up the root by name.
 - **`--from-root`/`-r`** (every command that narrows to the package you are standing in -
-  `run`/`build`/`test`, `exec`, `changelog`, `diff`): run against the whole repository instead.
+  `run`/`build`/`test`, `exec`, `clean`, `changelog`, `diff`, `config`): run against the whole
+  repository instead.
 - **Branch guard** (every command that mutates state or runs scripts - `run`/`build`/`test`,
-  `exec`, `version`): `--allow-branch <glob>`, `--ignore-branch <glob>` -
+  `exec`, `version`, `publish`, `github-release`, `clean`, `ci`): `--allow-branch <glob>`, `--ignore-branch <glob>` -
   refuses to run unless (or if) the current git branch matches, the same idea as GitHub Actions'
   own `branches`/`branches-ignore` workflow filters.
 
@@ -147,7 +149,7 @@ Options shared across several commands:
 Lists packages in the repository (alias: `ls`).
 
 ```bash
-rman list                       # table: Package / Version / Private / Changed / Path
+rman list                       # table: Package / Version / Group / Platform / Private / Publish / Changed / Path
 rman ls --short                 # just the bare package names
 rman list --json                # full detail as JSON
 rman list --parseable           # location::name::version::PRIVATE::STATUS lines, for scripting
@@ -158,12 +160,16 @@ rman list --changed-since HEAD~5
 rman list --scope '@myorg/*' --ignore '*-internal'
 ```
 
+The table keeps each release group together, in `version`'s plan order (root, then groups, then
+packages in no group), and indents a package by how deep it sits. `Group` appears only when it says
+something; `Publish` names the targets a package ships to, or `-` when none is left. `--toposort`
+orders by dependencies instead, and `--json` keeps the inventory's own order.
+
 ### `rman info`
 
 Prints local environment (OS/CPU/memory, Node, git) and repository information. A platform adds its
 own ecosystem's part - the `node` built-in reports whichever package manager
-`.rmanrc "packageManager"` names, plus the installed `rman` packages, and only in a repository that
-asked for it.
+`.rmanrc "packageManager"` names (`npm` by default), plus the installed `rman` and `typescript`.
 
 ```bash
 rman info
@@ -239,16 +245,38 @@ rman diff pkg-a          # since pkg-a's own last tag, scoped to its directory
 
 ### `rman changelog`
 
-Generates a changelog per package from unreleased commits, grouped into ✨ Features / 🐛 Bug Fixes
-/ 🔧 Other Changes.
+Generates a changelog per package from unreleased commits, with a section per Conventional Commits
+type (✨ Features, 🐛 Bug Fixes, ⚡ Performance, ...; anything else under 💬 General Changes) -
+renamed or extended with `.rmanrc "changelog.titles"`. With `changelog.groupBy: group`, one file per
+release group instead of per package.
 
 ```bash
 rman changelog                          # auto-detects each package's own last release
 rman changelog --from a1b2c3d           # since a specific commit, for every package
 rman changelog --write                  # prepend into each package's own CHANGELOG.md
 rman changelog --write --file-path docs/CHANGELOG.md
+rman changelog --rebuild                # regenerate the files from scratch instead of appending
+```
+
+### `rman deps [names..]`
+
+Lists the dependencies that have a newer version on their registry - every package, the monorepo
+root's own tooling included - and with `-u` writes the new ranges to the manifests, then checks that
+they still install.
+
+```bash
+rman deps                       # what could move, and what holds it back
+rman deps -u                    # write the new ranges, then check that they install
+rman deps --target major        # across a major too
+rman deps '@types/*'            # only the dependencies matching this glob
 ```
 
+**A dependency stays inside its major by default** (`deps.target: minor`). Taking a major is a
+decision a person makes: `--target major` for one run, `.rmanrc "deps.target"` for a standing
+answer, or `deps.targets` for one dependency. Only a caret or tilde range is rewritten; a version is
+offered only when every rule rman can see allows it. See
+[docs/cli/deps.md](https://github.com/panates/rman/blob/main/docs/cli/deps.md).
+
 ### `rman version [bump]`
 
 Bumps versions of changed packages (and their in-group dependents), grouped via `.rmanrc "group"`.
@@ -394,10 +422,11 @@ precedence: `package.json`'s own `"rman"` key, `.rmanrc.yml` (YAML), `.rmanrc` (
 the dotfile-style name), and `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js` for config that needs real
 logic (a JS module's default export).
 
-**Who a declaration is about** follows one rule: unmarked keys configure the package of the
-directory declaring them, and a `"[selector]"` block configures the packages it names. So the
-repository root's own keys are the *root package's* - which is where repo-wide settings are read
-from anyway - and they reach the other packages only through a selector.
+**Who a declaration is about** follows one rule: what is written above reaches below, and a
+`"[selector]"` block narrows the audience. An unmarked key configures its directory's package and
+every package under it, so the repository root's own keys are the baseline for the whole repository.
+`"[/]"` is the root package alone, `"[platform:node]"` every package of that technology, and a glob
+such as `"[*]"` the packages below.
 
 ```yaml
 # .rmanrc.yml, at the repository root
@@ -405,6 +434,11 @@ packageManager: pnpm
 logLevel: info
 allowBranch: [main, release/*]
 
+'[/]': # the root package alone - run's scheduling keys are read from here
+  run:
+    build:
+      concurrency: 4
+
 version:
   commitMessage: 'chore(release): v{version}'
 
@@ -418,7 +452,6 @@ version:
   run:
     test: mocha # a bare string is shorthand for { exec: mocha }
     build:
-      concurrency: 4
       before: [rman run lint]
       exec: tsc -b tsconfig-build.json
       after: node ../../support/postbuild.cjs
@@ -462,15 +495,15 @@ used to cover them was removed.
 
 ## Programmatic API
 
-Every command above is a thin wrapper around an exported service function - call them directly
+Every command above is a thin wrapper around an exported service - call them directly
 from your own Node.js scripts without shelling out to the `rman` binary:
 
 ```ts
-import { Repository, VersionService } from 'rman';
+import { Repository, VersionPlanService } from 'rman';
 
 const repository = await Repository.create();
-const plan = await VersionService.getPlan(repository);
-await VersionService.applyPlan(repository, plan, { changelog: true, push: true });
+const plan = await VersionPlanService.getPlanner(repository.app).getPlan(repository);
+await repository.app.getService('version').applyPlan(plan, { changelog: true, push: true });
 ```
 
 Full reference, with detailed examples for every service (`VersionService`, `PublishService`,

package/builtins/platforms/node/node-dependency-updater.d.ts

@@ -0,0 +1,116 @@
+import type { Package } from '../../../core/classes/package.js';
+import { DependencyUpdater } from '../../../core/interfaces/dependency-updater.js';
+import { type NpmRelease, type NpmReleases } from '../../publish-targets/npm/npm-view.js';
+/**
+ * npm's answer to `rman deps`: which of a `package.json`'s dependencies have a newer version on the
+ * registry, and which of those can be taken without breaking a rule another dependency states.
+ *
+ * Only a caret or tilde range on a plain version moves (`^1.2.3`, `~1.2.3`), keeping its prefix. An
+ * exact version, a compound range (`>=1 <2`, `a || b`), a dist-tag, a URL, an alias and an in-repo
+ * package are left as they are - but every one of them still counts as a rule the others must keep.
+ */
+export declare class NodeDependencyUpdater implements DependencyUpdater {
+    /** `.rmanrc "deps.types"`'s short spellings, as `npm-check-updates` named them. The field names
+     *  themselves are accepted too. */
+    protected readonly kindAliases: Readonly<Record<string, string>>;
+    /** The ranges that move: `^` or `~`, then a plain version. The prefix is kept on the rewrite. */
+    protected readonly movablePattern: RegExp;
+    /** The plan each `'update'` entry was made from, for `applyPlan`. */
+    protected readonly planned: WeakMap<DependencyUpdater.Entry, NodeDependencyUpdater.Decision>;
+    getPlan(ctx: DependencyUpdater.Context, packages: readonly Package[]): Promise<DependencyUpdater.Entry[]>;
+    applyPlan(ctx: DependencyUpdater.Context, plan: readonly DependencyUpdater.Entry[]): Promise<DependencyUpdater.Applied>;
+    /**
+     * `npm install --dry-run` at the repository root: npm's own resolver, which refuses a peer
+     * conflict anywhere in the tree with `ERESOLVE`, and writes nothing.
+     *
+     * Another package manager is not asked - its dry run is not the same question - and a note says so.
+     */
+    verify(ctx: DependencyUpdater.Context): Promise<string | undefined>;
+    /** One decision per dependency name `pkg` declares, whether or not it may move - one that may not
+     *  still states rules the others have to keep. */
+    protected collect(pkg: Package, settings: DependencyUpdater.Settings, options: DependencyUpdater.Options, inRepo: ReadonlySet<string>): NodeDependencyUpdater.Decision[];
+    /** Every name's releases, from the lowest version any declaration of it can mean - once per name,
+     *  however many packages declare it, `concurrency` at a time. */
+    protected fetchAll(ctx: DependencyUpdater.Context, decisions: readonly NodeDependencyUpdater.Decision[], withTime: boolean): Promise<Map<string, NpmReleases | undefined>>;
+    /** The registry's answer about one name - the seam a spec replaces. */
+    protected fetchReleases(name: string, range: string, cwd: string, withTime: boolean): Promise<NpmReleases | undefined>;
+    /** Fills in what `d` may move to, from its own settings and the rules that do not depend on what
+     *  else moves (steps 1-3). */
+    protected prepare(d: NodeDependencyUpdater.Decision, info: NpmReleases | undefined): void;
+    /** Whether the registry offers `release` as a move at all: newer than what is declared, not
+     *  deprecated, not above the `latest` tag, and not a prerelease unless the range is on one. */
+    protected offerable(d: NodeDependencyUpdater.Decision, release: NpmRelease): boolean;
+    /** Step 1: why the package's own settings leave `release` out - `deps.target` or `deps.minAge` -
+     *  or `undefined` when they do not. */
+    protected settingRefusal(d: NodeDependencyUpdater.Decision, release: NpmRelease, time?: Record<string, string>): string | undefined;
+    /**
+     * How big a move from `from` to `to` is, **as npm's caret reads it**: anything a `^from` range
+     * would not accept is a `major`, so `0.1.0 -> 0.2.0` is one.
+     */
+    protected sizeOf(from: string, to: string): string;
+    /** Steps 2 and 3: the package's own other declarations of this name, and the runtime it supports.
+     *  The rule `release` breaks, or `undefined`. */
+    protected staticRefusal(d: NodeDependencyUpdater.Decision, release: NpmRelease): string | undefined;
+    /**
+     * The Node versions a newer release has to keep covering: those the package supports **and** the
+     * lowest release its declaration allows now (`current`) already runs on.
+     */
+    protected nodeCoverage(pkg: Package, current: NpmRelease | undefined): string | undefined;
+    /** The Node versions `pkg` supports - its own `engines.node`, else the repository root's. */
+    protected supportedNode(pkg: Package): string | undefined;
+    /**
+     * Steps 4 and 5: while any peer range is broken by a version that moved, one side steps down.
+     *
+     * The side that steps down is the one the range is *about* - for "`parser` needs `typescript`
+     * below 6", `typescript` - to the newest candidate the range allows; only when none is left does
+     * the side stating the range step down instead.
+     */
+    protected resolve(decisions: readonly NodeDependencyUpdater.Decision[], ctx: DependencyUpdater.Context): void;
+    /** One broken rule, mended by one step down. Whether anything moved. */
+    protected settle(about: NodeDependencyUpdater.Decision, stating: NodeDependencyUpdater.Decision | undefined, range: string, rule: string): boolean;
+    /** Moves `d` down to `index` (`-1` keeps what is declared), remembering why it left its newest. */
+    protected stepTo(d: NodeDependencyUpdater.Decision, index: number, rule: string): void;
+    /** The version `d` resolves to: the one it moves to, or else the newest release its declarations
+     *  already allow, which is what an install picks. */
+    protected effective(d: NodeDependencyUpdater.Decision): string | undefined;
+    /** What `d` declares in `field` once it has moved. */
+    protected rangeFor(d: NodeDependencyUpdater.Decision, field: string): string;
+    /** The in-repo packages `pkg` declares a dependency on. */
+    protected siblingsOf(pkg: Package, repoPackages: ReadonlyMap<string, Package>): Package[];
+    protected toEntry(d: NodeDependencyUpdater.Decision): DependencyUpdater.Entry;
+    protected manifestFile(pkg: Package): string;
+    /** `fn` over `items`, at most `limit` at a time. */
+    protected mapConcurrent<T>(items: readonly T[], limit: number, fn: (item: T) => Promise<void>): Promise<void>;
+}
+export declare namespace NodeDependencyUpdater {
+    /** One dependency name of one package, and where planning has got to with it. */
+    interface Decision {
+        pkg: Package;
+        name: string;
+        settings: DependencyUpdater.Settings;
+        /** Every field declaring the name, and its range there. */
+        fields: Map<string, string>;
+        /** The fields whose range is rewritten. */
+        movable: string[];
+        /** Whether this name is planned at all - rather than only stating rules for the others. */
+        wanted: boolean;
+        /** What is declared now, as a version: the highest floor among the movable ranges. */
+        floor?: string;
+        /** The newest version the registry offers at all, before the package's own settings. */
+        available?: string;
+        /** Why the settings leave `available` out, when they do. */
+        skipReason?: string;
+        /** Newer versions the package's own settings allow, newest first. */
+        allowed: string[];
+        /** `allowed`, less the ones another of the package's own rules refuses. */
+        candidates: string[];
+        /** Into `candidates`; `-1` keeps what is declared. */
+        index: number;
+        releases?: Map<string, NpmRelease>;
+        latestTag?: string;
+        /** The Node versions a newer release has to keep covering - see `nodeCoverage`. */
+        baselineNode?: string;
+        reason?: string;
+        error?: string;
+    }
+}