rman 1.0.10 → 1.1.1

package/core/config.d.ts

@@ -1,3 +1,5 @@
+import path from 'path';
+import semver from 'semver';
 import type { RmanConfig } from '../interfaces/rman-config.interface.js';
 /**
  * Identity helper for authoring a `.rmanrc.cjs`/`.mjs`/`.js` config with full type-checking and
@@ -21,10 +23,259 @@ export declare function defineConfig(config: RmanConfig): RmanConfig;
  */
 export declare function readDirConfig(dirname: string): Promise<RmanConfig>;
 /**
- * Resolves the effective config for `targetDir` by cascading from `rootDir`
- * down to `targetDir` (inclusive), the same way tsconfig's `extends` chain
- * works: each directory level overrides the ones above it. This lets a
- * package (or any intermediate directory) narrow or override the repository's
- * root configuration for itself and everything below it.
+ * 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.
+ */
+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
+ *  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") }}'
+ * ```
+ */
+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;
+    /** Just the scope (`@sqb`), or `undefined` for an unscoped package. */
+    scope: string | undefined;
+    /** The name with its scope stripped (`builder`). */
+    unscopedName: string;
+    version: string;
+    /** The package directory's last segment (`builder`) - not always the same as `unscopedName`,
+     *  which is why both exist, and usually what a sibling path (`../../coverage/builder`) is keyed on. */
+    basename: string;
+    /** Absolute path to the package's own directory - named as rman's own `Package.dirname` is. */
+    dirname: string;
+    /** 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;
+    /**
+     * 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
+ *  it sits in, and the two genuinely differ). Sharing `PackageScope`'s shape is what makes
+ *  `repository.version` read the way `pkg.version` does. */
+export interface RepositoryScope extends PackageScope {
+    monorepo: boolean;
+    /** Every package in the repository - the root included only when it *is* the one package. */
+    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;
+    sha: string | undefined;
+    shortSha: string | undefined;
+    /** 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.
+ *
+ * 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;
+    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;
+}
+/**
+ * Evaluates every `${{ ... }}` expression in **every** string value of a resolved config, against
+ * the package it was resolved for:
+ *
+ * ```yaml
+ * "[*]":
+ *   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
+ * nobody remembers.
+ *
+ * The contents are **real JavaScript**, not a template mini-language, so there is no growing list
+ * of substitutions to keep adding (`{{major}}`, `{{scope}}`, ...) - see `ConfigScope` for what is
+ * in scope.
+ *
+ * **`${{ }}`, deliberately not `{{ }}`.** A config value may legitimately carry `{{...}}` meant for
+ * something else entirely (`helm template --set tag={{.Values.tag}}`); with the plainer delimiter
+ * rman would try to evaluate it. To emit a literal, let an expression produce it, the way GitHub
+ * Actions does: `${{ '${{' }}`.
+ *
+ * A string that is *nothing but* one expression keeps the value's own type (`"${{ pkg.private }}"`
+ * -> a boolean), since otherwise this could only ever produce strings and settings like
+ * `run.<script>.skip` would be unreachable. Embedded in surrounding text it is stringified.
+ *
+ * Evaluation happens in a fresh V8 context holding only the scope's bindings. That is a clean
+ * scope, **not a sandbox** - `node:vm` is explicitly not a security mechanism, and no sandbox is
+ * called for here anyway: a `.rmanrc` that can say `exec: "..."` already runs arbitrary shell, so
+ * the expression evaluator adds no trust boundary that wasn't already wide open.
+ *
+ * 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, options?: {
+    skip?: string[];
+}): 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 function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, RmanConfig>): Promise<RmanConfig>;
+export declare const DEFERRED_PATHS: string[];
+/** The `file` namespace for one package's directory - see `FileScope`. */
+export declare function createFileScope(dirname: string): FileScope;