rman 1.0.12 → 1.2.1

package/services/version.service.d.ts

@@ -1,33 +1,18 @@
 import type { Package } from '../core/package.js';
 import type { Repository } from '../core/repository.js';
-import { type PackageFilterOptions } from '../utils/package-filter.js';
+import type { RunStepValue } from '../core/run-step.js';
+import { VersionPlanService } from './version-plan.service.js';
+/**
+ * Applying a version plan: the writes. Every manifest edit, dependency-range refresh, stamp,
+ * commit and tag lives here; **what** to write is `VersionPlanService`'s answer.
+ *
+ * Nothing here knows what a `package.json` is, names an npm script, or runs a command: the version
+ * goes through `Manifest`/`ManifestProvider`, refreshing a sibling's dependency range goes through
+ * the same provider, and the lifecycle hooks around the write go through
+ * `RunService.runLifecycleSlot` - this module only supplies the `.rmanrc version.<slot>` fallback,
+ * which is its own config. What is left is git, that config, and the version stamps.
+ */
 export declare namespace VersionService {
-    type BumpKeyword = 'patch' | 'minor' | 'major';
-    function isBumpKeyword(value: unknown): value is BumpKeyword;
-    interface Options extends PackageFilterOptions {
-        /** A release-type keyword (applied as the severity for every group that has real changes) or
-         *  a concrete semver version (applied as the literal new version wherever something changed) -
-         *  either way, this replaces auto-detection entirely. Omit to auto-detect the severity per
-         *  group from conventional-commit subjects since each package's/group's last release tag. */
-        bump?: string;
-        /** A package with uncommitted local changes is excluded from bumping (status `'skip'`)
-         *  instead of aborting the whole plan (status `'error'`). Default false. */
-        ignoreDirty?: boolean;
-        /** Makes every computed bump a prerelease (`1.2.3` -> `1.3.0-beta.0` for a `minor`, say)
-         *  tagged with this identifier, instead of a normal release - same idea as `npm version
-         *  <type> --preid <name>`. A group already sitting on a matching prerelease (same identifier)
-         *  just has its prerelease counter incremented instead of jumping to a new base version - see
-         *  `incVersion`. Has no effect when `bump` is an explicit semver version rather than a keyword
-         *  (there's no severity left to "pre-fix" at that point). */
-        preid?: string;
-        /** Overrides the npm registry lookup `detectChangeHash` falls back to for a package that has
-         *  no release tag yet - mainly for tests, so they don't depend on network access or a real
-         *  published package. Same shape as `ChangelogService.Deps`/`PublishService.Deps`' own. */
-        npmViewVersion?: (name: string, cwd: string) => Promise<string | undefined>;
-        /** Clock behind a monorepo root's calendar release version - injectable so tests are
-         *  deterministic. Default `() => new Date()`. */
-        now?: () => Date;
-    }
     interface ApplyOptions {
         /** Push the resulting commit(s) and tag(s) to the remote once applied. Default false - same
          *  as a plain `npm version`, which never pushes on its own either. */
@@ -40,67 +25,102 @@ export declare namespace VersionService {
          *  same per-group commit, instead of requiring a separate `rman changelog --write` run. */
         changelog?: boolean;
     }
-    /** One package's outcome in a version plan - see `getPlan`. */
-    interface Entry {
-        package: Package;
-        /** Internal group identity packages are batched by (not for display) - see `resolveGroupKey`. */
-        groupKey: string;
-        /** Human-readable group name: `'default'` for the implicit repo-wide group, the configured
-         *  name for a named `group`, or the package's own name when it isn't grouped with anyone. */
-        group: string;
-        status: 'bump' | 'skip' | 'error' | 'no-change';
-        from: string;
-        /** Only set when `status === 'bump'`. */
-        to?: string;
-        /** Human-readable explanation - e.g. why a package was skipped, or why it's being bumped
-         *  despite having no commits of its own (a dependency of it changed elsewhere). */
-        reason?: string;
-    }
     /**
-     * Computes what a version bump *would* do, across every package `.rmanrc group` puts together -
-     * never writes anything (no package.json edits, no git commits/tags) and safe to call any time,
-     * including as the "preview" a bare `rman version` (no bump given) stops at.
-     *
-     * Packages are partitioned into groups by their resolved `group` value (cascaded): `true`
-     * (the default) puts every such package into one implicit repo-wide group; a string joins
-     * exactly the other packages sharing that same string, regardless of the repo's default; `false`
-     * makes a package its own solo group. Each group's "current version" is always the highest
-     * version currently found among its own members (never persisted anywhere) - see
-     * `resolveGroupKey`.
+     * **What `applyPlan` actually did** - which is not derivable from the plan it was given.
      *
-     * Within a group, a member with real commits since its own last release (or an explicit `bump`)
-     * sets the group's severity to the highest found among changed members; the new version
-     * is that current version bumped by that severity. Which members actually receive it depends on
-     * the severity: **patch** only the changed member(s) (a caret dependency range already tolerates
-     * a patch bump, no republish needed downstream); **minor** also every transitive in-group
-     * dependent; **major** the entire group, changed or not - see `computeGroupPlan`.
+     * It used to return that plan, untouched, so the one caller could only re-print the table it had
+     * already shown while the commits, the tags and the push stayed silent - the three things a
+     * reader does not already know. A `version` run can produce several commits (one per group, plus
+     * the root's informational one), tag each group, add a repository release tag, and skip a tag that
+     * already existed; none of that is visible from the outside.
+     */
+    interface ApplyResult {
+        /** The plan, as given - `'bump'` entries included, so a caller can still relate the rest to it. */
+        entries: VersionPlanService.Entry[];
+        /** The entries whose manifest was actually written. **Not every `'bump'` entry**: a monorepo
+         *  root's is informational, and `updated` is the number worth reporting. */
+        updated: VersionPlanService.Entry[];
+        commits: Commit[];
+        /** Every tag this run considered, in creation order. `created: false` means it was already
+         *  there and left alone - which is a different outcome from having made it. */
+        tags: Tag[];
+        /** Whether `git push` ran. `false` is the default and the common case, and saying so is the
+         *  point: a release that is committed but not pushed looks identical otherwise. */
+        pushed: boolean;
+    }
+    interface Commit {
+        /** Short sha. */
+        sha: string;
+        message: string;
+        /** The packages whose version this commit carries - empty for the root's informational sync. */
+        packages: string[];
+    }
+    interface Tag {
+        name: string;
+        created: boolean;
+        /** True for the repository's own release tag, which belongs to no single package. */
+        release?: boolean;
+    }
+    /**
+     * Writes every `'bump'` entry's new version into its own manifest (and refreshes any other bumped
+     * package's dependency range on it), runs that package's own version-lifecycle hooks or its
+     * `.rmanrc version.before`/`.exec`/`.after` around the write - see the `hook` closure below -
+     * then commits and tags **once per group** - so independently-versioned groups each get their own clean commit/tag rather than one entangled
+     * commit spanning unrelated version lines. Pushes only when `options.push` is set - same as a
+     * plain `npm version`, this never reaches the network on its own otherwise.
+     */
+    function applyPlan(repository: Repository, plan: VersionPlanService.Entry[], options?: ApplyOptions): Promise<ApplyResult>;
+    /** `.rmanrc version.commitMessage` (root-level; `{version}` is replaced when every bumped package
+     *  in this commit shares one version) - defaults to `"chore(release): v{version}"`, or a plain
+     *  listing of `name@version` pairs when this particular commit spans different versions (a
+     *  cross-group ripple can land a lone forced patch in a group that otherwise didn't move). */
+    function buildCommitMessage(repository: Repository, entries: VersionPlanService.Entry[], messageOverride?: string): string;
+    /**
+     * A `version.<slot>` value: one step, or several to run in sequence - the same shape, and now the
+     * same function, as `run.<script>.before`/`.exec`/`.after`.
      *
-     * Across groups: a package depending on another group's bumped package always gets exactly a
-     * **patch** bump of its own (never inheriting the source's severity) - the dependency reference
-     * itself is the only thing that changed for it. This never re-triggers *its own* group's
-     * minor/major cascade (a patch never cascades), but can itself ripple into a third group, and so
-     * on, until nothing new is affected - see `rippleCrossGroup`.
+     * It used to be a second implementation living here, and it differed in two ways that both had to
+     * go. It **joined an array with `' && '`** into one shell line, which a function step cannot be
+     * part of and which was not even right for shell steps - `cd x && y` in one process is not two
+     * processes. And it **dropped anything it did not recognize**, so a function here was silently
+     * never run. (The doc comment also still named `.script`/`.preScript`/`.postScript`, three keys
+     * that have been `before`/`exec`/`after` for a long time.)
+     */
+    function normalizeScriptValue(value: unknown, at: string): RunStepValue[];
+    /**
+     * Keeps a package's Dockerfile `org.opencontainers.image.version` label in step with the version
+     * just written, returning the absolute path when it actually changed (so the caller can fold it
+     * into the same commit) and `undefined` otherwise.
      *
-     * A monorepo's root package is never a real member of any group (it's never published on its
-     * own) - it gets one trailing entry instead, carrying the repository's own release identity: the
-     * single group's version when there is one, a calendar version once there are several - see
-     * `buildRootEntry`.
+     * Here rather than in a build script: the label is a *statement of the package's version*, so it
+     * belongs to whatever writes that version - which keeps it in the bump commit, leaves the tree
+     * clean, and makes it right for anyone building the Dockerfile by hand. A build-time rewrite is
+     * both later than it needs to be and invisible to git.
      *
-     * "Since its own last release" is resolved by the shared `detectChangeHash` - the same boundary
-     * `changelog` measures from, so the two never disagree about which commits are unreleased.
+     * The same path `publish --target docker` builds from (`publish.docker.dockerfile`, default
+     * `Dockerfile`), so the two can never disagree about which file this is. Opt out with `.rmanrc
+     * "version": { "stampDockerfile": false }`; a package with no Dockerfile, or one that doesn't
+     * declare the label, is a no-op either way.
      */
-    function getPlan(repository: Repository, options?: Options): Promise<Entry[]>;
+    function stampDockerfile(pkg: Package, version: string): string | undefined;
     /**
-     * Same as `getPlan`, and additionally writes every `'bump'` entry's new version into its own
-     * `package.json` (and refreshes any other bumped package's dependency range on it), runs that
-     * package's `version.preScript`/`.script`/`.postScript` (or its own real `preversion`/`version`/
-     * `postversion` npm scripts) around the write, then commits and tags **once per group** - so
-     * independently-versioned groups each get their own clean commit/tag rather than one entangled
-     * commit spanning unrelated version lines. Pushes only when `options.push` is set - same as a
-     * plain `npm version`, this never reaches the network on its own otherwise.
+     * Keeps every `.rmanrc "version.stamp"` file's hard-coded version in step with the one just
+     * written, returning the absolute paths of the ones that actually changed.
+     *
+     * Explicitly listed rather than discovered: unlike the OCI Dockerfile label there is no standard
+     * saying "this file holds the version". **A listed file a package does not have stays a silent
+     * no-op** - that is what lets one `"[*]"` declaration cover a repo where only some packages carry
+     * one.
+     *
+     * **A listed file that exists and cannot be stamped throws.** It used to be the same silent
+     * no-op as a missing file, and the two are not the same thing at all: the second means "not this
+     * package", the first means the repository asked for something and did not get it. Measured, and
+     * it is the bad kind of quiet - a package listing a file holding `const VERSION` (capital, so the
+     * pattern missed it) released a tagged commit with a stale constant and said nothing. The error
+     * names the file and, when the package's ecosystem declared none, says so.
+     *
+     * *How* a version is declared is the provider's (`ManifestProvider.stampVersion`); *which* files
+     * hold one is the repository's, which is why the list is config and the rewrite is a seam.
      */
-    function applyPlan(repository: Repository, plan: Entry[], options?: ApplyOptions): Promise<Entry[]>;
+    function stampSourceFiles(pkg: Package, version: string): string[];
 }
-/** Every `package.json` field holding dependency ranges - shared with `PublishService`'s own
- *  `"workspace:"` rewrite-for-publish step, since it needs to scan the same fields. */
-export declare const DEPENDENCY_KEYS: readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];