rman 1.2.5 → 2.0.0-beta.2

package/core/command-builder.js

@@ -0,0 +1,78 @@
+/**
+ * Turns a command's **declaration** into the yargs registration it describes.
+ *
+ * This is the one place that knows how the two relate, which is the point of declaring commands
+ * instead of building them: a command says what it has, and only this function says what yargs is
+ * told. Everything a `builder` used to do by hand - options, positionals, examples, parser
+ * switches - arrives as data now, so a typo in any of it is a compile error at the command rather
+ * than a flag that silently never existed.
+ */
+export function toYargsCommand(meta) {
+    return {
+        command: meta.command,
+        aliases: meta.aliases,
+        describe: meta.describe,
+        configKeys: configKeysOf(meta),
+        builder: (cmd) => {
+            if (meta.parserConfiguration)
+                cmd.parserConfiguration(meta.parserConfiguration);
+            for (const [name, spec] of Object.entries(meta.positionals ?? {}))
+                cmd.positional(name, spec);
+            for (const [key, option] of Object.entries(meta.config ?? {})) {
+                /**
+                 * **`target: 'config'` means "a `.rmanrc` key, and not a flag"** - `githubRelease.draft` is
+                 * the first of those. Skipping it here is what makes the field mean something rather than
+                 * being documentation.
+                 */
+                if (option.target === 'config')
+                    continue;
+                /** `target` and `cliName` are rman's, not yargs' - dropped rather than passed through. */
+                const { cliName, ...rest } = option;
+                delete rest.target;
+                /**
+                 * Registered under `cliName` when the flag and the config key are spelled differently
+                 * (`--ignore-dirty` for `ignoreDirty`). yargs expands the hyphenated form back to camelCase
+                 * in argv, so the handler reads the key it declared either way.
+                 */
+                cmd.option(cliName ?? key, rest);
+            }
+            for (const example of meta.examples ?? [])
+                cmd.example(example.command, example.description ?? '');
+            return cmd;
+        },
+        /**
+         * Cast because the two descriptions of argv disagree on purpose: yargs types it as an index
+         * signature of `unknown`, and a command annotates it with the options it actually declared. The
+         * narrower one is the useful one, and this is the single place the widening is admitted -
+         * previously it was an `as` per option read, in every handler.
+         */
+        handler: meta.handler,
+    };
+}
+/** A command's own name - the first word of its `command` string, before any positional. */
+export function commandName(command) {
+    return command.split(/\s+/)[0];
+}
+/**
+ * Which `.rmanrc` keys `--config` shows for a command: the ones it declared reading, plus **its own
+ * key when it has one**.
+ *
+ * `configKeys` is the read-only list on purpose - a command should not have to repeat the key it
+ * already owns, and `version` listing `'version'` beside `'changelog'` said nothing about which of
+ * the two it defines. Measured before this existed: `rman version --config` reported
+ * `changelog, group, allowBranch, ignoreBranch` and left out `version` itself.
+ *
+ * **Own key only when the command actually declares a config option.** `build` and `test` own
+ * nothing - their settings live in `run.build`/`run.test`, which they merely read - so prepending
+ * their names would print an empty `build: {}` that reads as "nothing is configured" about a key
+ * that does not exist. A `configKeys` given as a *function* is left alone entirely: `run` computes
+ * `run.<script>` from argv, which is narrower than its own key and deliberately so.
+ */
+function configKeysOf(meta) {
+    if (typeof meta.configKeys === 'function')
+        return meta.configKeys;
+    const ownsConfig = Object.values(meta.config ?? {}).some(o => o.target !== 'cli');
+    const own = ownsConfig ? [meta.configKey ?? commandName(meta.command)] : [];
+    const keys = [...own, ...(meta.configKeys ?? [])];
+    return keys.length ? keys : undefined;
+}

package/core/config.d.ts

@@ -1,6 +1,8 @@
 import path from 'path';
 import semver from 'semver';
 import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import { type DetectedBuiltin } from '../plugins/detect.js';
+import type { RunConditionFn, RunStepFn } from './run-step.js';
 /**
  * Identity helper for authoring a `.rmanrc.cjs`/`.mjs`/`.js` config with full type-checking and
  * autocomplete - the same `defineConfig` pattern Vite/Vitest use. Returns `config` completely
@@ -20,59 +22,93 @@ export declare function defineConfig(config: RmanConfig): RmanConfig;
  * Reads the rman configuration defined at a single directory level, merging
  * (in increasing precedence): `package.json#rman`, `.rmanrc.yml`, `.rmanrc`,
  * then `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js` (whichever exist, in that order).
+ *
+ * `options.inject` supplies a built-in for a repository that declared no technology - **already
+ * decided**, rather than a "please detect" flag. The decision needs the application (a programmatic
+ * caller or a spec may have registered a technology without writing it in a config), which this
+ * function has no business knowing about; `Repository.create` makes it once and hands the answer
+ * to every read that has to agree with it. See `detectBuiltin`.
  */
-export declare function readDirConfig(dirname: string): Promise<RmanConfig>;
+export declare function readDirConfig(dirname: string, options?: {
+    inject?: DetectedBuiltin;
+}): Promise<RmanConfig>;
 /**
  * Resolves the effective config for the package at `targetDir`, cascading from `rootDir` down to
  * it (inclusive) - each directory level overrides the ones above it, the way tsconfig's `extends`
  * chain does.
  *
- * Every level contributes in two ways, and the difference is the whole model:
- *
- * - **Unmarked keys configure the package of the directory that declares them.** The root's own
- *   `.rmanrc` therefore configures the *root package* - which is where repo-wide settings
- *   (`packageManager`, `allowBranch`, `version.*`, `githubRelease.*`) are read from anyway - and
- *   not, silently, every package under it.
- * - **A `"[selector]"` block configures the packages it names** - `"[*]"` for all of them (the root
- *   included), `"[ws:*]"` for every one but the root, `"[/]"` for the root alone, `"[*-dialect]"`
- *   for a glob over package names. See `parseSelector`. This is the only way a directory speaks
- *   about anything but its own package.
- *
- * Splitting the two matters because the same key means different things to the two audiences. The
- * clearest case is `run.<script>.postScript`: on a package it's that package's build hook, run in
- * its own directory; on the root it's a repo-wide bookend run once at the repository root. A
- * cascade that fed one declaration to both ran a package-relative command (`node
- * ../../support/postbuild.cjs`) at the root, where it cannot resolve.
- *
- * `packageName` is what selectors match against; without it, selector blocks contribute nothing at
- * all. The root package passes its own, since `"[/]"` and `"[*]"` speak to it.
+ * Every level contributes in two ways:
+ *
+ * - **An unmarked key configures that directory and every package under it.** What a parent says
+ *   reaches the children, which is what every directory-scoped config in the ecosystem does and
+ *   what a reader expects without being told.
+ * - **A `"[selector]"` block narrows the audience** - `"[/]"` to the root package alone, `"[*]"` or
+ *   a glob to the packages below (never the root, which is nobody's child). See `parseSelector`.
+ *
+ * **The root used to be the one directory whose unmarked config did *not* cascade**, on the
+ * reasoning that a setting means different things to a package and to the repository - and the
+ * reasoning is sound, but the rule it produced was not readable: an intermediate `packages/`
+ * cascaded while the root did not, so what a file meant depended on whether a `package.json` sat
+ * beside it. `vars` then had to be carved out as an exception, which is what a rule fighting itself
+ * looks like. One sentence now covers both: what is written above reaches below, and `"[/]"` is how
+ * a statement stays at the root.
+ *
+ * **The cost is real and lands on one subtree.** `run.<script>`'s hooks on the root are a repo-wide
+ * bookend, run once at the repository root; on a package they are that package's own hook, run in
+ * its directory. Cascaded, one declaration is both - once at the root and once per package. A
+ * repo-wide bookend therefore belongs under `"[/]"`, where its audience is visible; that is the
+ * migration this change asks for, and the only one that is not mechanical.
+ *
+ * **`selector` is what a `"[glob]"` block matches** - `Package.selector`, which is the package's
+ * `.rmanrc "name"` if it declares one and its platform's answer otherwise. Without it, glob blocks
+ * contribute nothing: the walk resolves config for a directory *before* the package exists, since
+ * that is where `platform` and `name` are read from, and a glob has nothing to match against yet.
+ *
+ * **`"[/]"` needs no selector, and that is the documented rule rather than an exception.** The root
+ * is addressed structurally - its directory *is* the repository root - which is the whole reason it
+ * is `/` and not a name. So a root block applies whenever the target is the root, named or not, and
+ * `platform` under `"[/]"` therefore works during the walk. It did not until this was noticed: the
+ * gate was `if (packageName)`, so the walk skipped every selector block including that one, and the
+ * key documented as "keeps it on the root package alone" silently did nothing.
+ *
+ * It was called `packageName`, which was wrong twice over: a package is not guaranteed to have a
+ * name (that is an ecosystem's promise, not rman's), and what this matches is the selector, which a
+ * repository can assign itself.
  */
-export declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, RmanConfig>, packageName?: string): Promise<RmanConfig>;
-/** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[ws:*]"`, `"[pkg-a]"`. The
+export declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, RmanConfig>, selector?: string, 
+/** The built-in `Repository.create` decided on, for a repository that declared no technology.
+ *  Applied at the **root level only** - `plugins` is read nowhere else, and this is the read whose
+ *  result becomes `pkg.config`, which is where `cli.ts` finds a built-in's `commands`. */
+inject?: DetectedBuiltin): Promise<RmanConfig>;
+/** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[pkg-a]"`. The
  *  brackets are what keep this space from colliding with real config keys - no setting starts with
  *  one - and in YAML they also mean the key always needs quoting (`"[*]":`), since a bare `[*]`
  *  parses as a flow sequence. */
 export declare function isSelectorKey(key: string): boolean;
 /**
- * **Which packages a selector speaks for.** Three audiences, because a repository has three:
+ * **Which packages a selector speaks for.** Two audiences, and the second is a glob:
  *
  * | | |
  * | --- | --- |
- * | `"[/]"` | the **root package** only |
- * | `"[*]"`, `"[pkg-a]"`, `"[*-dialect]"` | **every** package the glob matches, root included |
- * | `"[ws:*]"`, `"[workspace:pkg-*]"` | every **non-root** package the glob matches |
+ * | `"[/]"` | the **root package** alone |
+ * | `"[*]"`, `"[pkg-a]"`, `"[*-dialect]"` | the packages **below** this directory that the glob matches |
  *
  * `/` for the root because that is what a repository root is called everywhere else, and it cannot
- * collide with a package name. `ws:` is a qualifier on the glob rather than a separate spelling of
- * `*`, so `"[ws:pkg-*]"` means what it looks like.
- *
- * **`"[*]"` includes the root, and that is a change from how it used to read.** Before, selectors
- * were not applied to the root at all, so `"[*]"` silently meant "the workspace packages" - a
- * catch-all with an exception nothing in the syntax mentioned. The three names above say which
- * audience is meant; `"[ws:*]"` is the old behaviour, now spelled.
+ * collide with a package name.
+ *
+ * **The root is never selected by name, and that one rule removes two traps.** A glob matches
+ * package names, and the root is nobody's child - so `"[my-*]"` cannot quietly pick up a repository
+ * whose root package happens to be called `my-repo`, and `"[*]"` cannot hand a package-shaped
+ * setting to a root that has no build directory to apply it to. The root is addressed structurally
+ * or not at all.
+ *
+ * **`"[ws:*]"` / `"[workspace:*]"` is accepted and means exactly `"[*]"`.** The qualifier existed to
+ * say "not the root" back when a bare glob included it; the shape of the set says that now, so it
+ * has nothing left to add. Accepted rather than rejected because the two spellings resolve to the
+ * same packages - an error would be friction with no reader to protect.
  */
 export declare function parseSelector(key: string): {
-    scope: 'root' | 'all' | 'workspace';
+    scope: 'root' | 'package';
     test: (name: string) => boolean;
 };
 /** The glob inside a selector key, as a `RegExp` anchored at both ends - so `"[*-dialect]"` matches
@@ -153,7 +189,7 @@ export interface PackageScope {
      *  addressing another package from the root usually needs. Empty string for the root itself. */
     relativeDir: string;
     /**
-     * Which ecosystem this package belongs to - `'node'` for one read by `rman-node`, empty when no
+     * Which ecosystem this package belongs to - `'node'` for one the `node` built-in read, empty when no
      * plugin claimed it. The same `Package.provider`, so one declaration can address a single
      * ecosystem in a polyglot repository (`if: "${{ pkg.provider === 'node' }}"`).
      */
@@ -163,7 +199,7 @@ export interface PackageScope {
      * about (`${{ pkg.manifest.engines.node }}`).
      *
      * Named `manifest`, not `json`: which file a package's identity lives in is the ecosystem's
-     * business now (see `ManifestProvider`), and `json` was that assumption showing through the one
+     * business now (see `Plugin`'s manifest members), and `json` was that assumption showing through the one
      * remaining user-facing name. A config written against `${{ pkg.json... }}` needs the rename.
      */
     manifest: Record<string, unknown>;
@@ -194,12 +230,90 @@ export interface GitScope {
     /** Whether the working tree has uncommitted changes. */
     dirty: boolean | undefined;
 }
+/**
+ * What a **value function** is handed - `clean: { include: ({ value, pkg }) => [...] }`.
+ *
+ * The same scope a `${{ }}` expression sees, plus `value`. There is no asymmetry between the two
+ * spellings and that is an invariant with a spec on it: the argument *is* the expression context
+ * with `value` on it, so a member defined straight onto the argument would split them silently and
+ * a config author would meet a name that works in one spelling and not the other.
+ *
+ * **The config's own top-level keys are bound bare too**, and they cannot be typed here - they come
+ * from the config being interpolated rather than from this object. Reach them through `pkg.config`
+ * when a type matters, or accept `any` from the bare name.
+ *
+ * **Not what a *step* function is handed.** `run.<script>.exec` and `version.<slot>` take a
+ * `RunStepFn`, which gets a `RunStepContext` (`pkg`, `repository`, `cwd`, `runBin`, `logger`) when
+ * its turn comes - a different object at a different time, which is the whole distinction the two
+ * forms exist to draw. Never widen a step key to accept this one.
+ */
+export interface ConfigValueContext extends ConfigScope {
+    /**
+     * What this key resolved to in the layers **below** this one - the list form of it, so
+     * `[...value, 'x']` needs no guard. `any` rather than a generic: the key's own type is what the
+     * function must return, while `value` is whatever the layers underneath happened to produce, and
+     * a scalar underneath arrives as a one-element list. See `previousValue`.
+     */
+    value: any;
+    /** The config's own top-level keys, bound bare - `vars`, `publish`, `clean`, … */
+    [key: string]: any;
+}
+/**
+ * A config value that may be **written as a function instead**, computed per package at the moment
+ * the config resolves.
+ *
+ * `T` is what the function has to return, so the same checking applies either way - measured, with
+ * a control: a typo inside a wrapped object is still caught, and so is one inside an object a value
+ * function *returns*.
+ *
+ * **Not for a step key.** `run.<script>.before`/`.exec`/`.after`, `run.<script>.if` and
+ * `version.<slot>` already take a function, and it means something else there - code for `run` to
+ * call in its own time, with its own context. Wrapping one of those would produce a type that
+ * accepts a value function where a step is what actually runs. The key path decides which a
+ * function is (`STEP_PATHS`, `CODE_SUBTREES`), and the type can only follow that split by hand.
+ */
+export type ConfigValue<T> = T | ((ctx: ConfigValueContext) => T);
+/**
+ * The same config **after** it resolves: every `ConfigValue<T>` is just `T`, because
+ * `interpolateConfig` has already called it.
+ *
+ * **This is the half that lets `RmanConfig` be the author's type.** One type cannot answer both
+ * "what may I write?" (a function is fine - rman calls it) and "what do I get?" (never a function -
+ * it was already called), so it used to answer only the second, and writing a value function was a
+ * compile error the docs themselves committed. Widening `RmanConfig` alone just moves the problem:
+ * measured, six read sites needed a cast. The author's type widens and the *reader's* is computed
+ * from it - one derived type, applied at `Package.config`, rather than a second one to keep in step
+ * by hand.
+ *
+ * **Two guards, and each was measured by leaving it out.**
+ *
+ * - **Steps are named first.** A value function is recognised by its parameter, and
+ *   `ConfigValueContext` carries an index signature - so `RunStepFn` is assignable to it and a
+ *   `run.build.exec` function collapsed to its *return type*, leaving `RunService` nothing to call.
+ * - **`CODE_SUBTREES` is skipped, at every level.** `plugins`/`commands`/`publishTargets` hold code
+ *   all the way down, and the selector index (`[selector]: RmanConfig`) re-enters the config, so a
+ *   top-level-only guard misses the copy inside a `"[*]"` block. Left out, the walk reached
+ *   `Plugin.manifestProvider.versionScheme` and rewrote its **methods**: `smallestBump(): string`
+ *   became `string`, `bumpFor`/`isValid`/`compare`/`next` became `{}`. A function with *fewer*
+ *   parameters is assignable to one with more, so a zero-argument method matches the value-function
+ *   pattern - which makes this transform unsafe over any object carrying methods, and the guard the
+ *   only thing keeping one out of its way.
+ *
+ * Both lists are the runtime's own (`STEP_PATHS`' function types, `CODE_SUBTREES` itself), so the
+ * type follows the rule rather than restating it - the drift `ScopedVars` already demonstrated is
+ * not available here.
+ */
+export type Resolved<T> = T extends RunStepFn | RunConditionFn ? T : T extends (ctx: ConfigValueContext) => infer R ? R : T extends object ? {
+    [K in keyof T]: K extends CodeSubtree ? T[K] : Resolved<T[K]>;
+} : T;
+/** `pkg.config`'s type: what every command reads, with the value functions already called. */
+export type ResolvedConfig = Resolved<RmanConfig>;
 /**
  * What a `${{ ... }}` expression can see - the bindings of the fresh global it is evaluated in.
  * Namespaced rather than a flat bag of loose names: one obvious place per fact, and room to add
  * helpers to `pkg`/`repository` later without crowding the global.
  *
- * Alongside these, **the config's own top-level keys are bound bare** (`${{ publish.directory }}`,
+ * Alongside these, **the config's own top-level keys are bound bare** (`${{ changelog.filePath }}`,
  * `${{ clean.include }}`) - see `interpolateConfig`. They are not listed here because they come
  * from the config being interpolated, not from this object; a name here wins over a config key of
  * the same name.
@@ -278,7 +392,7 @@ export interface ConfigScope {
  *   run:
  *     build:
  *       # the config's own keys are in scope, so this is not a second copy of "build"
- *       after: "cp README.md ${{ publish.directory }}/"
+ *       after: "cp README.md ${{ changelog.filePath }}/"
  * ```
  *
  * Every string, with no list of "interpolated keys" to memorize - a rule with exceptions is a rule
@@ -311,7 +425,12 @@ export interface InterpolateOptions {
     /** Where `config` sits in the whole config, for a caller interpolating a fragment. */
     at?: string[];
 }
-export declare function interpolateConfig<T>(config: T, scope: ConfigScope, options?: InterpolateOptions): T;
+/**
+ * **Returns `Resolved<T>`, not `T`, because resolving is what it does.** Calling every value
+ * function is half this function's job, so the type it hands back is the one where they are gone -
+ * which is what makes `pkg.config` a `ResolvedConfig` without a cast anywhere between.
+ */
+export declare function interpolateConfig<T>(config: T, scope: ConfigScope, options?: InterpolateOptions): Resolved<T>;
 /**
  * Config paths left untouched when a repository's config is first resolved, and evaluated only by
  * the command that runs them.
@@ -330,14 +449,14 @@ export declare const DEFERRED_PATHS: string[];
  * config:
  *
  * ```js
- * '[ws:*]': {
+ * '[*]': {
  *   clean: { include: ({ vars, value }) => [...value, vars.buildDir] },   // a value: called here
  *   run: { build: { after: ({ pkg }) => copyDocs(pkg) } },                // a step: called by `run`
  * }
  * ```
  *
  * **The key decides, and it already did.** `run.build.exec: 'tsc -b'` is a shell command and
- * `publish.directory: 'build'` is a path - not because of anything about the strings, but because of
+ * `publish.npm.directory: 'build'` is a path - not because of anything about the strings, but because of
  * where they sit. A function inherits the same rule, so nothing new has to be learned and no marker
  * has to be remembered. The alternative was inspecting the function (arity, parameter names), which
  * is the kind of guess `loadPlugins` refuses to make about a module's export for the same reason:
@@ -350,16 +469,23 @@ export declare const DEFERRED_PATHS: string[];
 export declare const STEP_PATHS: string[];
 /**
  * Keys whose **whole subtree** is code rather than config, so no function under them is a value to
- * compute. `plugins` is the only one, and it has to be here: an entry may be the plugin *object*
- * itself, and an `RmanPlugin` is almost entirely functions - `manifest.read`, `workspace.resolve`,
- * `versionPlanner`, `binPaths`, and every command's `builder` and `handler`.
- *
- * Measured, and it is why this exists: with `plugins` walked like any other key, resolving the
- * config of a repository that named a plugin called that plugin's yargs builder with the config
- * scope - `Config function in "plugins[0].commands[0].builder" failed: cmd.option is not a
- * function`. A `plugins` entry is loaded by `loadPlugins`, never read as a setting.
+ * compute.
+ *
+ * The three contribution keys, and each has to be here: an entry may be the *instance* itself, and
+ * a `Plugin` is almost entirely functions - `manifestProvider.read`, `getWorkspace`,
+ * `getBinPaths`, `versionPlanner` - while a command is often a bare factory and a publish target
+ * carries `getPlan`/`applyPlan`.
+ *
+ * Measured twice, once per shape. With `plugins` walked like any other key, resolving the config
+ * of a repository that named a plugin called that plugin's yargs builder with the config scope:
+ * `Config function in "plugins[0].commands[0].builder" failed: cmd.option is not a function`. And
+ * with `commands` left out of this list, a declarative command - which *is* a function - was
+ * invoked with the interpolation scope instead of the application, so its handler closed over a
+ * repository that was not one: `repository.getPackages is not a function`, from inside `clean`.
+ *
+ * These entries are loaded by `loadPlugins` and `cli.ts`, never read as settings.
  */
-export declare const CODE_SUBTREES: string[];
+export declare const CODE_SUBTREES: readonly ["plugins", "commands", "publishTargets"];
 /** The `file` namespace for one package's directory - see `FileScope`. */
 /**
  * `read` in a `${{ ... }}` expression (and in a value function): a structured file's **contents**,
@@ -398,3 +524,7 @@ export interface CachedFile {
     value: unknown;
 }
 export declare function createFileScope(dirname: string): FileScope;
+/** The `CODE_SUBTREES` entries as a type, so the runtime list and `Resolved`'s guard cannot name
+ *  different keys. */
+type CodeSubtree = (typeof CODE_SUBTREES)[number];
+export {};