rman 1.0.12 → 1.2.1

package/core/config.d.ts

@@ -1,3 +1,4 @@
+import path from 'path';
 import semver from 'semver';
 import type { RmanConfig } from '../interfaces/rman-config.interface.js';
 /**
@@ -32,9 +33,10 @@ export declare function readDirConfig(dirname: string): Promise<RmanConfig>;
  *   `.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,
- *   `"[*-dialect]"` for a glob over package names). This is the only way a directory speaks about
- *   anything but its own package.
+ * - **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
@@ -42,21 +44,98 @@ export declare function readDirConfig(dirname: string): Promise<RmanConfig>;
  * 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 (resolving the root's own config, say)
- * selector blocks contribute nothing at all.
+ * `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.
  */
 export declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, RmanConfig>, packageName?: string): Promise<RmanConfig>;
-/** A config key naming packages rather than settings: `"[*]"`, `"[*-dialect]"`, `"[pkg-a]"`. The
+/** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[ws:*]"`, `"[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:
+ *
+ * | | |
+ * | --- | --- |
+ * | `"[/]"` | the **root package** only |
+ * | `"[*]"`, `"[pkg-a]"`, `"[*-dialect]"` | **every** package the glob matches, root included |
+ * | `"[ws:*]"`, `"[workspace:pkg-*]"` | every **non-root** package 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.
+ */
+export declare function parseSelector(key: string): {
+    scope: 'root' | 'all' | 'workspace';
+    test: (name: string) => boolean;
+};
 /** The glob inside a selector key, as a `RegExp` anchored at both ends - so `"[*-dialect]"` matches
  *  `mysql-dialect` but not `my-dialect-helper`. Glob rather than regex, to match every other
  *  pattern in rman (`allowBranch`, `changelog.tagPattern`, `clean.include`). */
 export declare function selectorToRegExp(key: string): RegExp;
 /** One package, as an expression sees it - the same shape for the package the config belongs to
  *  and for the repository itself, so `${{ repository.basename }}` reads the way `${{ pkg.basename }}` does. */
+/**
+ * `file` in a `${{ ... }}` expression: what is actually on disk, resolved against **the package
+ * the config was resolved for** - so one declaration in a `"[*]"` block asks each package about
+ * its own directory.
+ *
+ * The pair exists because a config has two different questions about a path, and answering both
+ * with one function would mean picking a wrong default for the other:
+ *
+ * ```yaml
+ * "[*]":
+ *   run:
+ *     build:
+ *       # first of these that exists, and an error naming the config path if none do
+ *       exec: 'tsc -b ${{ file.exists("tsconfig-build.json") || file.resolve("tsconfig.json") }}'
+ * ```
+ *
+ * **Every member asks a question, and none may ever change anything - no `copy`, no `write`, no
+ * `mkdir`.** Not a matter of taste: this is evaluated when the config *resolves*, which every
+ * command does, so a member that acted would act on `rman list`, `rman info` and `rman config`.
+ *
+ * That has been tried, in the only way a missing function can be: a shared config reaching for a
+ * `file.copyMany(...)` that does not exist made **every** rman command exit 1 - and had it existed,
+ * the quieter outcome would have been files copied by `rman list`. Work belongs in a step
+ * (`run.<script>`'s slots, `version`'s hooks), which is the one place rman runs anything, and a
+ * step can now be a function - so there is nothing this would enable that is not already possible
+ * at the right moment.
+ */
+export interface FileScope {
+    /**
+     * The absolute path if it exists, **`''` if it does not** - so `a || b || c` picks the first one
+     * present, and so a miss never reaches the "nullish inside a string" guard that `undefined` would
+     * trip. Accepts a relative path (against the package directory) or an absolute one.
+     *
+     * It returns a path rather than a boolean on purpose: the caller almost always wants the path,
+     * and a separate `file.path()` to fetch it after a boolean test would read the disk twice and
+     * invite the two calls to disagree.
+     */
+    exists(target: string): string;
+    /** The absolute path, or **throws** - for a file whose absence is a mistake rather than a case to
+     *  handle. The error names the config path holding the expression, like any other. */
+    resolve(target: string): string;
+    /**
+     * The first of several that exists, or **throws** naming every candidate it tried:
+     *
+     * ```yaml
+     * exec: 'tsc -b ${{ file.resolveFirst("tsconfig-build.json", "tsconfig.build.json", "tsconfig.json") }}'
+     * ```
+     *
+     * The same thing an `exists() || exists() || resolve()` chain does, said once - and it cannot be
+     * got subtly wrong the way that chain can: ending it in `exists()` leaves `tsc -b ` with no
+     * argument when nothing matches, and tsc then silently falls back to the directory's default
+     * rather than reporting that the package has no build config.
+     */
+    resolveFirst(...targets: string[]): string;
+}
 export interface PackageScope {
     /** The package's own name, scope included (`@sqb/builder`). */
     name: string;
@@ -73,9 +152,29 @@ export interface PackageScope {
     /** That directory relative to the repository root (`packages/builder`), which is what a command
      *  addressing another package from the root usually needs. Empty string for the root itself. */
     relativeDir: string;
-    /** The whole `package.json`, as a copy - so an expression can reach a field rman itself has no
-     *  opinion about (`pkg.json.engines.node`). */
-    json: Record<string, unknown>;
+    /**
+     * Which ecosystem this package belongs to - `'node'` for one read by `rman-node`, 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' }}"`).
+     */
+    provider: string;
+    /**
+     * The whole manifest, as a copy - so an expression can reach a field rman itself has no opinion
+     * 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
+     * remaining user-facing name. A config written against `${{ pkg.json... }}` needs the rename.
+     */
+    manifest: Record<string, unknown>;
+    /**
+     * The version this run is about to write - **bound only during `version`**, and only once its
+     * plan is computed. Reading it anywhere else throws rather than yielding `undefined`: no other
+     * command has a target version, so an expression asking for one has been put in the wrong place,
+     * and a config that quietly evaluates to "undefined" is the failure this evaluator exists to
+     * prevent.
+     */
+    targetVersion: string;
 }
 /** Facts about the repository, on top of the root package's own - because the repository root *is*
  *  a package (`repository.name` is what its `package.json` says, `repository.basename` the directory
@@ -87,10 +186,6 @@ export interface RepositoryScope extends PackageScope {
     packages: PackageScope[];
     /** One package by name, or `undefined` - for reaching a sibling's directory. */
     package(name: string): PackageScope | undefined;
-    /** Read from git only if an expression actually asks for it, then remembered: a repository that
-     *  never mentions these pays nothing, and every command resolves config. All `undefined` outside
-     *  a git checkout, which is a legitimate state rather than an error. */
-    git: GitScope;
 }
 export interface GitScope {
     branch: string | undefined;
@@ -99,18 +194,74 @@ export interface GitScope {
     /** Whether the working tree has uncommitted changes. */
     dirty: boolean | undefined;
 }
-/** 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. */
+/**
+ * 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 }}`,
+ * `${{ 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.
+ *
+ * **Trap: bare `${{ version }}` is the `version` *options block*, not the package's version
+ * string** - that is `${{ pkg.version }}`. Same word, two different things, and the plain one
+ * belongs to the config because every other config key is reachable that way.
+ */
 export interface ConfigScope {
     /** The package the config was resolved for - which is what lets one declaration at the root
      *  still say something package-specific. */
     pkg: PackageScope;
     repository: RepositoryScope;
+    /** Paths, resolved against the package the config was resolved for. */
+    file: FileScope;
+    /**
+     * The **contents** of a structured file - `${{ read('tsconfig.json').compilerOptions.outDir }}` -
+     * where `file` answers only where one is. Resolved against `pkg.dirname` like `file`, so a
+     * `"[*]"` block asks each package about its own; a repository-level file is reached through
+     * `read(path.join(repository.dirname, ...))`.
+     *
+     * `.json`, `.yml`/`.yaml` and `.ini` by extension, or name it for a file that does not say
+     * (`read('.npmrc', 'ini')`). **Throws** when the file is absent, as `file.resolve` does - compose
+     * with `file.exists` when its absence is a case to handle.
+     *
+     * **A manifest is `pkg.manifest`, not this.** `read('package.json')` works and is the wrong
+     * answer: which file a package's identity lives in belongs to the ecosystem, so that expression
+     * is already wrong in a Cargo package sitting beside a Node one.
+     *
+     * The result is **deeply frozen and shared** - see `readStructuredFile`. Spread it to change it.
+     */
+    read: ReadFile;
     env: Record<string, string | undefined>;
     /** rman's own `semver`, for the arithmetic every release config eventually wants
      *  (`semver.major(pkg.version)`). */
     semver: typeof semver;
+    /**
+     * Node's own `node:path` - `${{ path.join(pkg.dirname, 'LICENSE') }}`, rather than gluing
+     * strings with `+ "/" +` and getting a double separator or none.
+     *
+     * The platform's flavour, not `path.posix`, so a joined path is the one the shell on *this*
+     * machine understands; `path.posix` and `path.win32` are reachable through it when a config
+     * genuinely needs one of them (a Docker image path, say, which is always posix).
+     */
+    path: typeof path;
+    /**
+     * The checkout: branch, sha, whether the tree is dirty.
+     *
+     * **Top level, not `repository.git`** - which is where it used to be, and the move is the point.
+     * `repository` shares its shape with `pkg` because the repository root *is* a package, and its
+     * only other members (`monorepo`, `packages`, `package()`) say something about the repository as
+     * a container of packages. A branch name says nothing about any package; it describes the
+     * working tree every one of them happens to be sitting in - the same kind of ambient fact as
+     * `env`, and it belongs beside it.
+     *
+     * **Read from git only if an expression actually asks**, then remembered for the whole run: every
+     * command resolves config, and a repository that never mentions git must not pay for one. See
+     * `Repository.configScope` for the getter, and `interpolateConfig` for why the context is built
+     * from property descriptors rather than a spread - a spread would fire this getter on every
+     * command, which is exactly what moving it up here risked.
+     */
+    git: GitScope;
 }
 /**
  * Evaluates every `${{ ... }}` expression in **every** string value of a resolved config, against
@@ -121,8 +272,13 @@ export interface ConfigScope {
  *   clean:
  *     include: ["build", "../../coverage/${{ pkg.basename }}"]
  *   publish:
+ *     directory: build
  *     docker:
  *       image: "panates/${{ pkg.basename }}:${{ semver.major(pkg.version) }}"
+ *   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 }}/"
  * ```
  *
  * Every string, with no list of "interpolated keys" to memorize - a rule with exceptions is a rule
@@ -149,4 +305,96 @@ export interface ConfigScope {
  * A failing expression throws with the config path that holds it, rather than being left in place:
  * silently passing through a mistake is how a config ends up quietly doing nothing.
  */
-export declare function interpolateConfig<T>(config: T, scope: ConfigScope): T;
+export interface InterpolateOptions {
+    /** Config paths to leave entirely untouched - `DEFERRED_PATHS`, when the whole config is walked. */
+    skip?: string[];
+    /** 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;
+/**
+ * Config paths left untouched when a repository's config is first resolved, and evaluated only by
+ * the command that runs them.
+ *
+ * `version`'s own hooks are the one place `${{ pkg.targetVersion }}` makes sense, and the version
+ * being written is not known until `version` has computed its plan - long after the config was
+ * resolved. Evaluating these eagerly would throw while merely *loading* the repository, so any
+ * command at all would fail on a config that mentions it.
+ */
+export declare const DEFERRED_PATHS: string[];
+/**
+ * Paths whose value is a **step** - something to run later - rather than a setting to compute now.
+ * `*` matches one path segment (`run.<script>.exec`).
+ *
+ * This is what tells a step function from a value function, and the two live side by side in one
+ * 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
+ * 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:
+ * guessing wrong here means running build-time code while merely loading the repository, or
+ * silently never running it.
+ *
+ * A **string** at one of these paths is still interpolated - `exec: 'tsc -b ${{ file.resolve(...) }}'`
+ * has to keep working - so this is narrower than `DEFERRED_PATHS`, which skips its paths entirely.
+ */
+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.
+ */
+export declare const CODE_SUBTREES: string[];
+/** The `file` namespace for one package's directory - see `FileScope`. */
+/**
+ * `read` in a `${{ ... }}` expression (and in a value function): a structured file's **contents**,
+ * parsed - where `file` answers only where a path is.
+ *
+ * ```yaml
+ * "[*]":
+ *   run:
+ *     build:
+ *       exec: 'tsc --outDir ${{ read("tsconfig.json").compilerOptions.outDir }}'
+ * ```
+ *
+ * `cache` is shared across every package (see `Repository.configScope`) and keyed by what the file
+ * *is*, not merely where - so the same file read by twenty packages is parsed once, and a file rman
+ * itself rewrites mid-run is re-read rather than remembered. See `readStructuredFile`.
+ */
+export declare function createReadScope(dirname: string, cache: Map<string, CachedFile>): ReadFile;
+/**
+ * What `read` can parse.
+ *
+ * **`.env` is deliberately absent, and that is the durable part of this list**: `env` is already in
+ * scope, and a `.env` file exists to be loaded *into* an environment by something else - a config
+ * reading one as data would mean two different things called the environment.
+ *
+ * Nothing else is excluded on principle. `xml` arrived because a `pom.xml` or a `.csproj` holds a
+ * version exactly the way a `package.json` does, and rman is language-agnostic; the earlier line
+ * ("no new parsers") did not survive it, since xmldom *is* a new one.
+ */
+export type FileFormat = 'json' | 'yaml' | 'ini' | 'xml';
+/** `read(path)`, or `read(path, 'ini')` for a file whose name does not say what it is (`.npmrc`). */
+export type ReadFile = (target: string, format?: FileFormat) => unknown;
+/** One parsed file, kept against the identity of the bytes it came from - see `readStructuredFile`. */
+export interface CachedFile {
+    /** `mtimeNs:size`. */
+    stamp: string;
+    value: unknown;
+}
+export declare function createFileScope(dirname: string): FileScope;