rman 2.0.0-beta.2 → 2.0.0-beta.4

package/services/github-release.service.js

@@ -1,9 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import fastGlob from 'fast-glob';
-import { Package } from '../core/package.js';
-import { Repository } from '../core/repository.js';
-import { Service } from '../core/service.js';
+import { Package } from '../core/classes/package.js';
+import { Repository } from '../core/classes/repository.js';
+import { Service } from '../core/classes/service.js';
 import { GitHelper } from '../utils/git.js';
 import { expandReleaseTag, isCalendarVersion, releaseTagPattern } from '../utils/release-version.js';
 import { ChangeHashService } from './change-hash.service.js';

package/services/import.service.d.ts

@@ -1,4 +1,4 @@
-import { Service } from '../core/service.js';
+import { Service } from '../core/classes/service.js';
 /**
  * A service class - see `ListService` for the shape and `Service` for the three measured
  * consequences a namespace had. `repository` left the signature because the application carries it.
@@ -34,7 +34,7 @@ export declare namespace ImportService {
         commitCount: number;
     }
 }
-declare module '../core/service.js' {
+declare module '../core/classes/service.js' {
     interface ServiceMap {
         import: ImportService;
     }

package/services/import.service.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { Service } from '../core/service.js';
+import { Service } from '../core/classes/service.js';
 import { GitHelper } from '../utils/git.js';
 /**
  * A service class - see `ListService` for the shape and `Service` for the three measured

package/services/list.service.d.ts

@@ -1,7 +1,7 @@
-import { type PublishTargetName } from '../core/publish-target.js';
-import type { Repository } from '../core/repository.js';
-import { Service } from '../core/service.js';
-import type { DockerPublishOptions } from '../targets/docker.target.js';
+import type { DockerPublishOptions } from '../builtins/publish-targets/docker/docker.target.js';
+import type { Repository } from '../core/classes/repository.js';
+import { Service } from '../core/classes/service.js';
+import { type PublishTargetName } from '../core/interfaces/publish-target.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 /**
  * **A class, and the shape every service follows now.**
@@ -39,8 +39,10 @@ export declare namespace ListService {
          * what it saw before.
          */
         includeRoot?: boolean;
-        /** Only include packages that have changed since the last publish (dirty or committed but
-         *  not yet published) - or, with `changedSince`, since that specific commit/hash. */
+        /** Only include packages the developer has touched but not pushed (dirty, or committed and not
+         *  yet on the upstream branch) - or, with `changedSince`, since that specific commit/hash.
+         *  **Question C, never a release question**: after a push `git cherry` is empty and everything
+         *  reads `clean`, which does not mean there is nothing left to release. */
         changed?: boolean;
         changedSince?: string;
     }
@@ -79,7 +81,7 @@ export declare namespace ListService {
         docker?: DockerPublishOptions;
     }
 }
-declare module '../core/service.js' {
+declare module '../core/classes/service.js' {
     interface ServiceMap {
         list: ListService;
     }

package/services/list.service.js

@@ -1,6 +1,6 @@
 import path from 'path';
-import { targetsOf } from '../core/publish-target.js';
-import { Service } from '../core/service.js';
+import { Service } from '../core/classes/service.js';
+import { targetsOf } from '../core/interfaces/publish-target.js';
 import { filterPackages } from '../utils/package-filter.js';
 /**
  * **A class, and the shape every service follows now.**

package/services/run.service.d.ts

@@ -1,7 +1,7 @@
-import type { Package } from '../core/package.js';
-import type { Repository } from '../core/repository.js';
-import type { RunStepContext, RunStepFn, RunStepValue } from '../core/run-step.js';
-import { Service } from '../core/service.js';
+import type { Package } from '../core/classes/package.js';
+import type { Repository } from '../core/classes/repository.js';
+import { Service } from '../core/classes/service.js';
+import type { RunStepContext, RunStepFn, RunStepValue } from '../core/interfaces/run-step.js';
 import { type LogLevel } from '../utils/logger.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 /**
@@ -127,11 +127,15 @@ export declare namespace RunService {
      * Runs one slot of a lifecycle belonging to some operation other than `run` itself - `version`'s
      * hooks around the version write are the only one so far.
      *
-     * **Here rather than in `VersionService`, because the rule it applies is this service's**: the
-     * package's own declaration for `script` wins over the caller's `fallback`, slot by slot, exactly
-     * as `getScriptSteps` decides it for `run`. Kept in two places that rule would drift, and one of
-     * the copies would sit in the file that writes versions - which now runs no command of its own at
-     * all.
+     * **Here rather than in `VersionService`, because the rule it applies is this service's**: how a
+     * package's own declaration for `script` and the caller's `fallback` combine, slot by slot -
+     * `slotValues`, the same function `getScriptSteps` decides it with. Kept in two places that rule
+     * would drift, and one of the copies would sit in the file that writes versions, which now runs
+     * no command of its own at all.
+     *
+     * So npm's `preversion` does **not** replace a repository's `.rmanrc version.before` any more;
+     * both run, the config's first. Only `version.exec` is a single answer, and there the package's
+     * own still wins.
      *
      * `fallback` is the caller's own configured step(s), **already evaluated**: `version`'s three
      * paths are in `DEFERRED_PATHS` precisely because only the caller can bind
@@ -172,7 +176,7 @@ export declare namespace RunService {
      *
      *   run:
      *     build:
-     *       if: changed                                    # changed since the last publish
+     *       if: changed                                    # touched but not pushed
      *     test:
      *       if: changed = a1b2c3d                           # changed since a specific commit
      *       if: changed = {CHANGE_HASH}                     # {NAME} -> process.env.NAME first
@@ -212,7 +216,7 @@ export declare function resolveBool(cliValue: boolean | undefined, pkg: Package,
 export declare function resolveBail(cliValue: boolean | undefined, pkg: Package, script: string, fallback: boolean): boolean;
 export declare function resolveNumber(cliValue: number | undefined, pkg: Package, script: string, key: string, fallback: number): number;
 export declare function resolveLogLevel(cliValue: LogLevel | undefined, pkg: Package, script: string, fallback: LogLevel): LogLevel;
-declare module '../core/service.js' {
+declare module '../core/classes/service.js' {
     interface ServiceMap {
         run: RunService;
     }

package/services/run.service.js

@@ -3,7 +3,7 @@ import { inspect } from 'node:util';
 import colors from 'ansi-colors';
 import { tokenize } from 'fast-tokenizer';
 import { Task } from 'power-tasks';
-import { Service } from '../core/service.js';
+import { Service } from '../core/classes/service.js';
 import { exec } from '../utils/exec.js';
 import { LOG_LEVELS, Logger, resolveRootLogLevel } from '../utils/logger.js';
 import { filterPackages } from '../utils/package-filter.js';
@@ -61,6 +61,12 @@ export class RunService extends Service {
                 for (let i = 0; i < steps.length; i++) {
                     const step = steps[i];
                     ctx.currentStep = step.name;
+                    /** The command for a shell step, the function's own name for a JS one - and a bare
+                     *  marker for an anonymous function, which is still worth saying: the slot label alone
+                     *  does not distinguish a JS step from a shell one. `step.label` is not used directly
+                     *  because for a function it already folds the slot in (`before (js)`), which the row
+                     *  prints two characters to its left. */
+                    ctx.currentCommand = step.command ?? (step.run?.name ? `${step.run.name}()` : '(js function)');
                     ctx.stepIndex = i;
                     if (panel.enabled) {
                         const onLine = (line) => {
@@ -275,11 +281,15 @@ export class RunService extends Service {
      * Runs one slot of a lifecycle belonging to some operation other than `run` itself - `version`'s
      * hooks around the version write are the only one so far.
      *
-     * **Here rather than in `VersionService`, because the rule it applies is this service's**: the
-     * package's own declaration for `script` wins over the caller's `fallback`, slot by slot, exactly
-     * as `getScriptSteps` decides it for `run`. Kept in two places that rule would drift, and one of
-     * the copies would sit in the file that writes versions - which now runs no command of its own at
-     * all.
+     * **Here rather than in `VersionService`, because the rule it applies is this service's**: how a
+     * package's own declaration for `script` and the caller's `fallback` combine, slot by slot -
+     * `slotValues`, the same function `getScriptSteps` decides it with. Kept in two places that rule
+     * would drift, and one of the copies would sit in the file that writes versions, which now runs
+     * no command of its own at all.
+     *
+     * So npm's `preversion` does **not** replace a repository's `.rmanrc version.before` any more;
+     * both run, the config's first. Only `version.exec` is a single answer, and there the package's
+     * own still wins.
      *
      * `fallback` is the caller's own configured step(s), **already evaluated**: `version`'s three
      * paths are in `DEFERRED_PATHS` precisely because only the caller can bind
@@ -291,8 +301,7 @@ export class RunService extends Service {
      * semantics of the shell case too, since `cd x && y` in one process is not the same as two.
      */
     async function runLifecycleSlot(pkg, script, slot, fallback) {
-        const own = contributedSlots(pkg, script)?.[slot] ?? [];
-        const values = own.length ? own : (fallback ?? []);
+        const values = slotValues(slot, contributedSlots(pkg, script)?.[slot] ?? [], fallback ?? [], false);
         for (const value of values) {
             if (typeof value === 'function') {
                 await value(createStepContext(pkg, pkg.dirname));
@@ -575,12 +584,14 @@ async function passesIf(repository, pkg, raw, cwd, statusCache) {
  *
  * 1. `run.<script>.override: true` -> the config, always. The escape hatch for "ignore what the
  *    package says it does".
- * 2. a **contributed** source - `package.json#scripts` via `rman-node`. It wins over the config
- *    because it is the *package's own* declaration, while a config value typically arrives
- *    cascaded from the root or an `extends` base; the more specific statement wins, as everywhere
- *    else in rman.
- * 3. the config's own `before`/`exec`/`after`, letting a package run a script it never declared.
- * 4. nothing - and an empty result is what tells `runScript` this package defines no such script.
+ * 2. for `exec`, a **contributed** source - `package.json#scripts` via `rman-node` - wins over the
+ *    config, because the two are one answer to one question and the more specific statement wins.
+ * 3. for `before`/`after`, the two **compose**: they are hooks at a point rather than answers, so
+ *    the config's bracket the package's own (`config.before -> prebuild -> build -> postbuild ->
+ *    config.after`). See `slotValues` for the measurement behind that.
+ * 4. the config's own `before`/`exec`/`after` alone, letting a package run a script it never
+ *    declared.
+ * 5. nothing - and an empty result is what tells `runScript` this package defines no such script.
  */
 function getScriptSteps(pkg, script) {
     const cfg = RunService.getConfig(pkg, script);
@@ -593,14 +604,47 @@ function getScriptSteps(pkg, script) {
     };
     const steps = [];
     for (const slot of SCRIPT_SLOTS) {
-        const own = contributed?.[slot] ?? [];
-        const configured = fromConfig[slot] ?? [];
-        const values = override ? (configured.length ? configured : own) : own.length ? own : configured;
-        for (const value of values)
+        for (const value of slotValues(slot, contributed?.[slot] ?? [], fromConfig[slot] ?? [], override)) {
             steps.push(toStep(slot, value));
+        }
     }
     return steps;
 }
+/**
+ * The steps for one slot, from the package's own declaration and the config's, in the order they
+ * run.
+ *
+ * **`exec` replaces; `before` and `after` compose.** They are not the same kind of key, and
+ * treating them alike is what this function exists to stop:
+ *
+ * - `exec` is *one answer to one question* - what this script does. A package declaring
+ *   `"build": "tsc -b"` and a config declaring `exec: 'tsc -b'` are the same build stated twice,
+ *   so the more specific statement wins and the other is dropped.
+ * - `before`/`after` are *hooks at a point*, and two of them at one point both belong. npm's
+ *   `prebuild` means "immediately before my own build"; `run.build.before` means "before this
+ *   script, for every package". Neither answers the other.
+ *
+ * **Measured, on a two-line repository**: a root declaring
+ * `"[*]": { run: { build: { before: 'echo CONFIG-BEFORE', after: 'echo CONFIG-AFTER' } } }` and a
+ * package declaring `prebuild`/`build`/`postbuild` ran the package's three and **neither of the
+ * root's** - while the identical repository with `prebuild` deleted ran both. So adding an
+ * unrelated codegen hook to one package silently cancelled a repo-wide `rman clean`, with a stale
+ * build directory as the only symptom.
+ *
+ * **The config brackets the package's own**, which is what the wider statement means and the shape
+ * a bookend already has here: `config.before -> prebuild -> build -> postbuild -> config.after`.
+ *
+ * `override: true` is unchanged - it is the escape hatch for "ignore what the package says it
+ * does", so the config replaces rather than composes, per slot, falling back to the package's own
+ * where the config says nothing about that slot.
+ */
+function slotValues(slot, own, configured, override) {
+    if (override)
+        return configured.length ? configured : own;
+    if (slot === 'exec')
+        return own.length ? own : configured;
+    return slot === 'before' ? [...configured, ...own] : [...own, ...configured];
+}
 /**
  * What this package's own technology says it declares for `script`.
  *

package/services/system-info.d.ts

@@ -1,5 +1,5 @@
 import envinfo from 'envinfo';
-import type { Repository } from '../core/repository.js';
+import type { Repository } from '../core/classes/repository.js';
 export declare namespace SystemInfo {
     interface RepositoryInfo {
         type: 'monorepo' | 'package';

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

@@ -1,7 +1,7 @@
 import { RmanApplication } from '../core/application.js';
-import type { Package } from '../core/package.js';
-import type { Repository } from '../core/repository.js';
-import { VersionScheme } from '../core/version-scheme.js';
+import type { Package } from '../core/classes/package.js';
+import type { Repository } from '../core/classes/repository.js';
+import { VersionScheme } from '../core/classes/version-scheme.js';
 import { type CommitInfo, GitHelper } from '../utils/git.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 /**
@@ -241,7 +241,11 @@ export declare namespace VersionPlanService {
         group: string;
         status: 'bump' | 'skip' | 'error' | 'no-change';
         from: string;
-        /** Only set when `status === 'bump'`. */
+        /** The version this package would receive. Set for `'bump'`, and for an `'error'` entry that
+         *  earned one - a package with uncommitted changes aborts the run, and `--show` exists to say
+         *  what it would get. **Never** set for `'skip'`: `--ignore-dirty` proceeds to write, and a
+         *  version beside an excluded package would name one it is not getting. So `status`, not `to`,
+         *  is what decides whether something is applied. */
         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). */

package/services/version-plan.service.js

@@ -1,9 +1,10 @@
 import path from 'node:path';
 import { RmanApplication } from '../core/application.js';
-import { assertOneScheme, semverScheme, VersionScheme } from '../core/version-scheme.js';
+import { assertOneScheme, semverScheme, VersionScheme } from '../core/classes/version-scheme.js';
 import { GitHelper } from '../utils/git.js';
 import { filterPackages } from '../utils/package-filter.js';
 import { findLastReleaseVersion, formatCalendarVersion, usesCalendarVersion } from '../utils/release-version.js';
+import { groupKeyOf } from '../utils/version-group.js';
 import { ConventionalCommitsService } from './conventional-commits.service.js';
 /**
  * Question A, computed and nothing else: **which packages have changed since their last release,
@@ -96,21 +97,39 @@ export class VersionPlanService {
         const packages = filterPackages(repository.getPackages(), options);
         const dirtyFiles = await git.listDirtyFiles({ absolute: true });
         const isDirty = (pkg) => dirtyFiles.some(f => !path.relative(pkg.dirname, f).startsWith('..'));
+        const dirty = packages.filter(isDirty);
         const entries = new Map();
-        const eligible = [];
-        for (const pkg of packages) {
-            if (isDirty(pkg)) {
-                entries.set(pkg.name, {
-                    package: pkg,
-                    groupKey: this.resolveGroupKey(pkg),
-                    group: this.groupLabel(this.resolveGroupKey(pkg)),
-                    status: options.ignoreDirty ? 'skip' : 'error',
-                    from: pkg.version,
-                    reason: 'uncommitted local changes',
-                });
-                continue;
-            }
-            eligible.push(pkg);
+        /**
+         * **A dirty package is removed from the plan only when the run is going to proceed without it.**
+         * The two answers are not symmetric, and treating them as one is what left the `To` column
+         * blank on the command that exists to show it.
+         *
+         * - `--ignore-dirty` **writes**. The package is deliberately excluded, so it must not reach a
+         *   group either: a number its clean siblings receive cannot be derived from commits nobody is
+         *   releasing, and a `to` printed beside `skip` would name a version that package is not
+         *   getting. Diverted here, before `eligible`.
+         * - Aborting writes **nothing** - `getPlan` is pure and the command throws after printing - so
+         *   there is no number to keep safe, and the one thing the reader wants is what each package
+         *   would have got once it is committed. The plan is computed in full and the dirty entries are
+         *   marked at the very end, below.
+         *
+         * Excluding them from the abort case cost more than the column. `buildRootEntry` reads
+         * `e.to ?? e.from`, and its `groupCount` comes from the groups that were actually built - so a
+         * dirty tree quietly moved the repository's own release identity: measured on a four-package
+         * repo with `group: false`, three dirty packages left one group standing, which is
+         * `usesCalendarVersion`'s "one line" case, and the root reported `0.0.5 -> 2.1.6` on the
+         * *semver* path instead of the calendar version it takes with four.
+         */
+        const eligible = options.ignoreDirty ? packages.filter(pkg => !dirty.includes(pkg)) : packages;
+        for (const pkg of options.ignoreDirty ? dirty : []) {
+            entries.set(pkg.name, {
+                package: pkg,
+                groupKey: this.resolveGroupKey(pkg),
+                group: this.groupLabel(this.resolveGroupKey(pkg)),
+                status: 'skip',
+                from: pkg.version,
+                reason: 'uncommitted local changes',
+            });
         }
         const commitMessage = repository.rootPackage.config?.version?.commitMessage;
         const changeByPackage = new Map();
@@ -151,6 +170,25 @@ export class VersionPlanService {
                 now: options.now ?? (() => new Date()),
             }));
         }
+        /**
+         * The abort case, marked **after** the root entry so the whole table reads as one coherent
+         * "if this were committed" preview rather than a mixture of two.
+         *
+         * `to` survives the overwrite; `status` is what every writer filters on (`VersionService`,
+         * `changed`), so an `'error'` entry carrying a version cannot be applied by any of them - and
+         * `version` throws on the first error before it would reach `applyPlan` anyway. The reason
+         * keeps the boundary it was computed from, because the status column already says `error` and
+         * a reader losing `changed since <tag>` loses the only thing that explains the number.
+         */
+        if (!options.ignoreDirty) {
+            for (const pkg of dirty) {
+                const entry = entries.get(pkg.name);
+                if (!entry)
+                    continue;
+                entry.status = 'error';
+                entry.reason = entry.reason ? `uncommitted local changes (${entry.reason})` : 'uncommitted local changes';
+            }
+        }
         return result;
     }
     /**
@@ -230,12 +268,7 @@ export class VersionPlanService {
      *  group; a non-empty string joins exactly the other packages sharing that string, regardless of
      *  the repo's own default; `false` makes it a solo group of one. */
     resolveGroupKey(pkg) {
-        const g = pkg.config?.group;
-        if (g === false)
-            return `solo:${pkg.name}`;
-        if (typeof g === 'string' && g)
-            return `named:${g}`;
-        return 'default';
+        return groupKeyOf(pkg);
     }
     /** The human-readable name behind a `groupKey` - what a plan's `group` column shows. */
     groupLabel(key) {

package/services/version.service.d.ts

@@ -1,7 +1,7 @@
-import type { Package } from '../core/package.js';
-import type { Repository } from '../core/repository.js';
-import type { RunStepValue } from '../core/run-step.js';
-import { Service } from '../core/service.js';
+import type { Package } from '../core/classes/package.js';
+import type { Repository } from '../core/classes/repository.js';
+import { Service } from '../core/classes/service.js';
+import type { RunStepValue } from '../core/interfaces/run-step.js';
 import { VersionPlanService } from './version-plan.service.js';
 /**
  * Applying a version plan: the writes. Every manifest edit, dependency-range refresh, stamp,
@@ -139,7 +139,7 @@ export declare namespace VersionService {
      */
     function stampSourceFiles(pkg: Package, version: string): string[];
 }
-declare module '../core/service.js' {
+declare module '../core/classes/service.js' {
     interface ServiceMap {
         version: VersionService;
     }

package/services/version.service.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { interpolateConfig } from '../core/config.js';
-import { Manifest } from '../core/manifest.js';
-import { Service } from '../core/service.js';
+import { Service } from '../core/classes/service.js';
+import { ConfigInterpolator } from '../core/config/config-interpolator.js';
+import { Manifest } from '../core/interfaces/manifest.js';
 import { GitHelper } from '../utils/git.js';
 import { expandReleaseTag, isCalendarVersion } from '../utils/release-version.js';
 import { stampVersionLabel } from '../utils/version-stamp.js';
@@ -65,6 +65,9 @@ export class VersionService extends Service {
          */
         for (const entry of bumped)
             assertStampable(entry.package, entry.to);
+        /** One for the whole run: it carries no per-package state, and `defer(...)`'s bookkeeping is
+         *  per call. */
+        const interpolator = new ConfigInterpolator();
         for (const entry of bumped) {
             const pkg = entry.package;
             /** The scope these hooks are evaluated against - the only place `${{ pkg.targetVersion }}`
@@ -80,7 +83,7 @@ export class VersionService extends Service {
             const hook = (slot) => RunService.runLifecycleSlot(pkg, VERSION_LIFECYCLE, slot, RunService.normalizeScriptValue(
             /** `at`: the path is what tells a step function from a value one, and this is a fragment -
              *  without it a function here was called while the hook was being prepared. */
-            interpolateConfig(pkg.config?.version?.[slot], scope, { at: ['version', slot] }), `version.${slot}`));
+            interpolator.interpolate({ config: pkg.config?.version?.[slot], scope, at: ['version', slot] }), `version.${slot}`));
             await hook('before');
             /** Through the manifest, not through a `package.json` field: where a version is written is
              *  the provider's business (see `Plugin`'s manifest members), and this is the one place rman changes

package/services.d.ts

@@ -1,5 +1,5 @@
+export { DockerPublishService } from './builtins/publish-targets/docker/docker-publish.service.js';
 export { ChangelogService } from './services/changelog.service.js';
-export { DockerPublishService } from './services/docker-publish.service.js';
 export { ExecService } from './services/exec.service.js';
 export { GithubReleaseService } from './services/github-release.service.js';
 export { ImportService } from './services/import.service.js';

package/services.js

@@ -1,5 +1,5 @@
+export { DockerPublishService } from './builtins/publish-targets/docker/docker-publish.service.js';
 export { ChangelogService } from './services/changelog.service.js';
-export { DockerPublishService } from './services/docker-publish.service.js';
 export { ExecService } from './services/exec.service.js';
 export { GithubReleaseService } from './services/github-release.service.js';
 export { ImportService } from './services/import.service.js';

package/utils/branch-guard.d.ts

@@ -1,5 +1,5 @@
 import type { Argv } from 'yargs';
-import type { Repository } from '../core/repository.js';
+import type { Repository } from '../core/classes/repository.js';
 /** Same idea as GitHub Actions' own `branches`/`branches-ignore` workflow filters - restricts a
  *  command to running only from certain branches (or refuses certain ones), instead of any. */
 export interface BranchGuardOptions {

package/utils/color-yaml.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A YAML document with syntax colour, for the two commands that print one to be **looked at** -
+ * `rman config` and `--config`.
+ *
+ * **Only call this when `process.stdout.isTTY`.** Colouring a document that is being redirected
+ * makes it unloadable, which is the whole reason the callers gate on a terminal.
+ */
+export declare function colorYaml(text: string): string;

package/utils/color-yaml.js

@@ -0,0 +1,86 @@
+import colors from 'ansi-colors';
+/**
+ * A YAML document with syntax colour, for the two commands that print one to be **looked at** -
+ * `rman config` and `--config`.
+ *
+ * **Only call this when `process.stdout.isTTY`.** Colouring a document that is being redirected
+ * makes it unloadable, which is the whole reason the callers gate on a terminal.
+ */
+/* **Line-based and deliberately shallow.** This is a highlighter, not a parser: it colours what a
+ * reader's eye uses to navigate - the key, the list marker, a literal - and leaves anything it is
+ * not sure about alone. A real parse would have to round-trip js-yaml's own output to gain nothing
+ * a reader would notice, and every extra rule is a new way to mangle a value.
+ *
+ * **What it colours and why that set**:
+ *
+ * - the **key**, in cyan, because that is what you scan a config for;
+ * - **`${{ ... }}`**, in magenta, because rman's configs are full of them and because a `version`
+ *   hook is printed *raw* (`DEFERRED_PATHS`) - the one place an unresolved expression is correct
+ *   rather than a bug, and the colour is what stops it reading as a mistake;
+ * - **numbers, booleans and `null`**, in yellow, since `skip: false` and `skip: "false"` mean
+ *   different things and nothing else in the output tells them apart;
+ * - **`[Function: name]`**, in grey, because it is this printer's placeholder rather than anything
+ *   the config says - the one value in the output that is not a value;
+ * - the **`-`** of a list item and a `#` comment, in grey, as structure rather than content.
+ *
+ * A plain string value is left uncoloured on purpose. It is the *content*, usually the longest
+ * thing on the line, and colouring it competes with the key for attention - which is the failure
+ * mode of a highlighter that paints everything.
+ *
+ * **The two places a shallow pass has to be careful, and neither is hypothetical:**
+ *
+ * - **A `:` inside a value.** js-yaml quotes any scalar holding one, so the line is
+ *   `key: 'a: b'` - and the key pattern stops at the *first* colon, which is the right one. Nothing
+ *   to do, but it is why the pattern is written `[^:]*` rather than anything greedier.
+ * - **A folded block scalar.** `lineWidth: 100` makes js-yaml emit `describe: >-` and continue on
+ *   deeper-indented lines, and a continuation line is prose: one holding `(default: ...)` would
+ *   otherwise have half a sentence coloured as a key. So the block's indent is tracked and its
+ *   content is left alone but for expressions. A `#` there is prose too, not a comment. */
+export function colorYaml(text) {
+    /** The indent of the key that opened a block scalar, while one is open. Anything indented past it
+     *  is that block's content; the first line that is not ends it. */
+    let blockIndent;
+    return text
+        .split('\n')
+        .map(line => {
+        const indent = line.length - line.trimStart().length;
+        if (blockIndent !== undefined) {
+            if (line.trim() === '' || indent > blockIndent)
+                return colorExpressions(line);
+            blockIndent = undefined;
+        }
+        if (BLOCK_SCALAR.test(line))
+            blockIndent = indent;
+        return colorLine(line);
+    })
+        .join('\n');
+}
+/** `key: >-`, `key: |`, `key: >2-`, and the bare `- >-` of a list item. */
+const BLOCK_SCALAR = /:\s*[|>][0-9]*[-+]?\s*$/;
+const EXPRESSION = /\$\{\{[\s\S]*?\}\}/g;
+const LITERAL = /^(true|false|null|~|-?\d+(?:\.\d+)?)$/;
+const FUNCTION = /^"?\[Function(?::[^\]]*)?\]"?$/;
+function colorLine(line) {
+    const comment = /^(\s*)#(.*)$/.exec(line);
+    if (comment)
+        return comment[1] + colors.gray(`#${comment[2]}`);
+    /** `indent`, an optional `- ` for a list item, then either `key:` plus a value or a bare item. */
+    const parsed = /^(\s*)(- )?(?:([^\s:][^:]*):(\s|$))?([\s\S]*)$/.exec(line);
+    if (!parsed)
+        return line;
+    const [, indent = '', dash, key, gap = '', rest = ''] = parsed;
+    return indent + (dash ? colors.gray(dash) : '') + (key ? `${colors.cyan(key)}:${gap}` : '') + colorValue(rest);
+}
+function colorValue(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return value;
+    if (LITERAL.test(trimmed))
+        return value.replace(trimmed, colors.yellow(trimmed));
+    if (FUNCTION.test(trimmed))
+        return value.replace(trimmed, colors.gray(trimmed));
+    return colorExpressions(value);
+}
+function colorExpressions(value) {
+    return value.replace(EXPRESSION, match => colors.magenta(match));
+}

package/utils/git.d.ts

@@ -46,6 +46,19 @@ export declare class GitHelper {
     /** Tag names matching the glob `pattern` (e.g. `"v*"`, `"pkg-a@*"`), newest version first. */
     listTags(pattern: string): Promise<string[]>;
     /** Whether `tag` exists as an exact git tag name (not a glob - a literal ref check). */
+    /**
+     * Every tag matching `pattern`, paired with the **commit** it points at - newest version first,
+     * the same order `listTags` returns.
+     *
+     * `%(*objectname)` is the dereferenced target and is empty for a lightweight tag, so the commit
+     * is that or `%(objectname)`. rman's own tags are lightweight; a repository's existing ones may
+     * not be, and an annotated tag's `objectname` is the *tag object*, which matches no commit and
+     * would make the tag silently invisible to anything comparing shas.
+     */
+    listTagCommits(pattern: string): Promise<{
+        tag: string;
+        sha: string;
+    }[]>;
     tagExists(tag: string): Promise<boolean>;
     /** The most recent commit that changed `file` (tracked history only) - `undefined` if it has
      *  never been committed. Answers "since when has this file last been updated", independent of
@@ -61,6 +74,19 @@ export declare class GitHelper {
     /** The repository's very first commit (the oldest root commit, for a history with several) -
      *  `undefined` for a repository with no commits at all. The "since the beginning" boundary for
      *  a package being released for the first time, with no earlier tag to measure from. */
+    /** HEAD's own sha, or `undefined` in a repository with no commits yet (or none at all) - the
+     *  same "answer nothing rather than throw" shape `rootCommit` and `describeTag` take, because
+     *  every caller here already has a "nothing to go on" branch. */
+    /** The date a ref points at, as `YYYY-MM-DD`. The **committer** date, not the author's: a
+     *  rebased or cherry-picked release commit was authored earlier than it shipped, and what a
+     *  changelog heading states is when the release happened. `undefined` for a ref that resolves to
+     *  nothing. */
+    commitDate(ref: string): Promise<string | undefined>;
+    /** The commit `ref` names - a sha, a tag, a branch - or `undefined` when git does not recognize
+     *  it. `^{commit}` so an annotated tag answers with the commit rather than the tag object, and
+     *  so a tree or blob answers with nothing rather than a sha that matches no commit. */
+    resolveCommit(ref: string): Promise<string | undefined>;
+    headSha(): Promise<string | undefined>;
     rootCommit(): Promise<string | undefined>;
     /**
      * Stages and commits exactly `files` (relative to `cwd`, or absolute) with `message` - never a