rman 1.3.0 → 2.0.0-beta.3

package/core/config.js

@@ -1,939 +0,0 @@
-import { DOMParser } from '@xmldom/xmldom';
-import fs from 'fs';
-import ini from 'ini';
-import * as yaml from 'js-yaml';
-import { createRequire } from 'module';
-import path from 'path';
-import semver from 'semver';
-import { pathToFileURL } from 'url';
-import vm from 'vm';
-import { assertNoSelectorExtends, EXTENDS_KEY, resolveExtends } from './extends-config.js';
-import { finalizeConfig, mergeConfig, ORIGINS, PREVIOUS_VALUES } from './merge-config.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
- * unchanged; this exists purely so TypeScript can infer/check against `RmanConfig`, not for any
- * runtime behavior:
- *
- *   // .rmanrc.mjs
- *   import { defineConfig } from 'rman';
- *   export default defineConfig({ packageManager: 'pnpm' });
- *
- *   // .rmanrc.cjs
- *   const { defineConfig } = require('rman');
- *   module.exports = defineConfig({ packageManager: 'pnpm' });
- */
-export function defineConfig(config) {
-    return config;
-}
-/** `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js`, checked in this order - a JS module whose default
- *  export (or, lacking one, the module's own exports object) is the config. Both CommonJS (`.cjs`,
- *  or a `.js` under a `"type": "commonjs"` package.json) and native ESM (`.mjs`, or a `.js` under
- *  `"type": "module"`) are supported - the reason `readDirConfig`/`resolveConfig` are async at all. */
-const JS_CONFIG_FILES = ['.rmanrc.cjs', '.rmanrc.mjs', '.rmanrc.js'];
-const requireJsConfig = createRequire(import.meta.url);
-/**
- * Loads `file`'s config object. Tries `require()` first - not just an optimization: a CommonJS
- * module's `module.exports` is more reliably observed this way than through dynamic `import()`'s
- * CJS-interop synthesis, which some ESM loader hooks (e.g. ts-node/swc-node-style transpilers
- * registered via `--import`) can end up short-circuiting into an empty object. `require()` throws
- * `ERR_REQUIRE_ESM` for a genuinely-ESM file (`.mjs`, or `.js` under `"type": "module"`) - only
- * then does this fall back to `import()`, the one case that actually needs it. Either path can
- * hand back an ES module namespace instead of a plain object (Node's `require(esm)` support does
- * this too, not just `import()`), so `.default` is preferred whenever present.
- */
-async function loadJsConfig(file) {
-    let mod;
-    try {
-        mod = requireJsConfig(file);
-    }
-    catch (e) {
-        if (e?.code !== 'ERR_REQUIRE_ESM')
-            throw e;
-        mod = await import(pathToFileURL(file).href);
-    }
-    return mod?.default ?? mod;
-}
-/**
- * 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).
- */
-export async function readDirConfig(dirname) {
-    const result = {};
-    /** The file an `extends` in this directory resolves relative to. The last form that actually
-     *  declared one wins, which matters only for the unusual directory holding several. */
-    let extendsFrom = path.join(dirname, '.rmanrc');
-    const pkgJsonFile = path.join(dirname, 'package.json');
-    if (fs.existsSync(pkgJsonFile)) {
-        const pkgJson = JSON.parse(fs.readFileSync(pkgJsonFile, 'utf-8'));
-        if (pkgJson && typeof pkgJson.rman === 'object') {
-            assertNoSelectorExtends(pkgJson.rman, pkgJsonFile);
-            if (EXTENDS_KEY in pkgJson.rman)
-                extendsFrom = pkgJsonFile;
-            mergeConfig(result, pkgJson.rman, pkgJsonFile);
-        }
-    }
-    const ymlFile = path.join(dirname, '.rmanrc.yml');
-    if (fs.existsSync(ymlFile)) {
-        const obj = yaml.load(fs.readFileSync(ymlFile, 'utf-8'));
-        if (obj && typeof obj === 'object') {
-            assertNoSelectorExtends(obj, ymlFile);
-            if (EXTENDS_KEY in obj)
-                extendsFrom = ymlFile;
-            mergeConfig(result, obj, ymlFile);
-        }
-    }
-    const rcFile = path.join(dirname, '.rmanrc');
-    if (fs.existsSync(rcFile)) {
-        const obj = JSON.parse(fs.readFileSync(rcFile, 'utf-8'));
-        if (obj && typeof obj === 'object') {
-            assertNoSelectorExtends(obj, rcFile);
-            if (EXTENDS_KEY in obj)
-                extendsFrom = rcFile;
-            mergeConfig(result, obj, rcFile);
-        }
-    }
-    for (const jsFileName of JS_CONFIG_FILES) {
-        const jsFile = path.join(dirname, jsFileName);
-        if (fs.existsSync(jsFile)) {
-            const obj = await loadJsConfig(jsFile);
-            if (obj && typeof obj === 'object') {
-                assertNoSelectorExtends(obj, jsFile);
-                if (EXTENDS_KEY in obj)
-                    extendsFrom = jsFile;
-                mergeConfig(result, obj, jsFile);
-            }
-        }
-    }
-    /** Resolved per directory, once its own forms have been combined: `extends` is the base every
-     *  one of them sits on, and the directory chain then layers on top as it always did. Each form
-     *  was checked for a misplaced `extends` as it was read, so that error can name the file holding
-     *  it rather than whichever form happened to declare the real one. */
-    return resolveExtends(result, extendsFrom);
-}
-/**
- * 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:
- *
- * - **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.
- *
- * `packageName` is what selectors match against; without it, selector blocks contribute nothing at
- * all. The root package passes its own, since `"[/]"` speaks to it.
- */
-export async function resolveConfig(rootDir, targetDir, cache = new Map(), packageName) {
-    const result = {};
-    const target = path.resolve(targetDir);
-    /** The root *package* is the one whose directory is the repository root - no other test is
-     *  needed, and none would be as reliable: a name can be anything. In a single-package repository
-     *  that is the only package, so `"[/]"` reaches it and `"[*]"` reaches nothing. */
-    const isRoot = target === path.resolve(rootDir);
-    for (const dir of dirChain(rootDir, targetDir)) {
-        let local = cache.get(dir);
-        if (!local) {
-            local = await readDirConfig(dir);
-            cache.set(dir, local);
-        }
-        /**
-         * **Unmarked first, because it is the widest thing this level says** - and that is an inversion
-         * of the order this loop used to run in, where a directory's own plain config beat a selector
-         * declared beside it. Under the old reading "unmarked" meant *this package* and so was the
-         * narrower of the two; it now means *this package and everything below*, which is the wider.
-         * Precedence follows the audience, not the spelling, so it had to move.
-         *
-         * Its position in the file is deliberately not consulted: a selector block written above the
-         * plain keys still wins. Unmarked is not a fourth selector - it is the level's floor, and the
-         * layer that feeds the directories below it.
-         */
-        mergeConfig(result, stripSelectors(local));
-        /** Then the selector blocks, **in the order they were written** - see `matchingSelectors`. */
-        if (packageName) {
-            for (const block of matchingSelectors(local, packageName, isRoot))
-                mergeConfig(result, block);
-        }
-    }
-    /** Every layer has had its turn, so an append still outstanding has nothing left to attach to
-     *  and becomes the value itself. Done here rather than per layer: until the chain is finished,
-     *  the key it appends to may still be coming. */
-    return finalizeConfig(result);
-}
-/** 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 function isSelectorKey(key) {
-    return key.length > 2 && key.startsWith('[') && key.endsWith(']');
-}
-/**
- * **Which packages a selector speaks for.** Two audiences, and the second is a glob:
- *
- * | | |
- * | --- | --- |
- * | `"[/]"` | 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.
- *
- * **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 function parseSelector(key) {
-    const inner = key.slice(1, -1);
-    if (inner === ROOT_SELECTOR_INNER)
-        return { scope: 'root', test: () => true };
-    const re = globToRegExp(stripWorkspacePrefix(inner));
-    return { scope: 'package', test: name => re.test(name) };
-}
-/** 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 function selectorToRegExp(key) {
-    return globToRegExp(stripWorkspacePrefix(key.slice(1, -1)));
-}
-/**
- * Every selector block in `config` that speaks for this package, **in the order they were written**
- * - later wins, the way `overrides` works in eslint, prettier and babel, and the way a `.gitignore`
- * rule does.
- *
- * **There used to be a ranking** (`"[*]"` lowest, then a catch-all `"[ws:*]"`, then the rest by
- * declaration), so that "everything" could not beat a rule about one package by being written last.
- * It was dropped because the ordering it implies does not exist: specificity only ranks sets that
- * nest, and globs do not. For a package called `pkg-dialect`, neither `"[pkg-*]"` nor
- * `"[*-dialect]"` contains the other, so any answer is an invented tiebreak - and an invented
- * tiebreak is worse than the order the author typed. What was left was already declaration order
- * with one case lifted out of it; this removes the exception rather than generalizing it.
- *
- * The cost, which the docs state rather than hide: a catch-all written *below* a narrower block now
- * overrides it. Writing catch-alls first is a convention, not a rule - the file reads top to bottom.
- */
-function matchingSelectors(config, packageName, isRoot) {
-    const matches = [];
-    for (const [key, value] of Object.entries(config)) {
-        if (!isSelectorKey(key) || !value || typeof value !== 'object')
-            continue;
-        const { scope, test } = parseSelector(key);
-        if (scope === 'root' ? !isRoot : isRoot || !test(packageName))
-            continue;
-        matches.push(value);
-    }
-    return matches;
-}
-/** `"[ws:*]"` and `"[workspace:*]"` are the pre-2.x spelling of "not the root", kept working
- *  because they now name the same set a bare glob does. Stripped here so one code path serves both. */
-function stripWorkspacePrefix(inner) {
-    for (const prefix of WORKSPACE_PREFIXES)
-        if (inner.startsWith(prefix))
-            return inner.slice(prefix.length);
-    return inner;
-}
-function globToRegExp(glob) {
-    const source = glob
-        .split('*')
-        .map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
-        .join('.*');
-    return new RegExp(`^${source}$`);
-}
-function stripSelectors(config) {
-    const result = {};
-    for (const [key, value] of Object.entries(config))
-        if (!isSelectorKey(key))
-            result[key] = value;
-    return result;
-}
-/** `"[/]"` - the root package, spelled the way a repository root is spelled everywhere else, and
- *  unable to collide with a package name. */
-const ROOT_SELECTOR_INNER = '/';
-/** Accepted spellings of the retired "not the root" qualifier - see `stripWorkspacePrefix`. */
-const WORKSPACE_PREFIXES = ['workspace:', 'ws:'];
-function dirChain(rootDir, targetDir) {
-    const rel = path.relative(rootDir, targetDir);
-    if (!rel || rel === '.' || rel.startsWith('..'))
-        return [rootDir];
-    const dirs = [rootDir];
-    let dir = rootDir;
-    for (const segment of rel.split(path.sep)) {
-        dir = path.join(dir, segment);
-        dirs.push(dir);
-    }
-    return dirs;
-}
-export function interpolateConfig(config, scope, options) {
-    const skip = options?.skip ?? [];
-    /**
-     * Where `config` sits in the whole config, when a caller hands over a fragment rather than the
-     * root - `version` interpolates its own `version.<slot>` value on its own, those three paths being
-     * in `DEFERRED_PATHS`.
-     *
-     * It matters because the path is what decides whether a function is a value to compute or a step
-     * to leave alone (`STEP_PATHS`). Without it, a fragment starts at the root and matches nothing, so
-     * a function in a `version` hook was called while the hook was being *prepared* - measured, and it
-     * failed inside the user's own code with `path.join` receiving undefined.
-     */
-    const base = options?.at ?? [];
-    /**
-     * Built from `scope`'s property **descriptors**, never `{ ...scope }`.
-     *
-     * A spread reads every property, so a lazy getter on the scope is no longer lazy the moment one
-     * is added - and `git` is exactly that: it shells out to `git rev-parse`, and a spread here would
-     * do it on `rman list`, `rman info` and every other command, in a repository whose config never
-     * mentions git. (The same trap `pkg.targetVersion` documents from the other side: it is a
-     * *throwing* getter, and being enumerable is what made a spread fire it.)
-     */
-    const context = vm.createContext(Object.defineProperties({}, Object.getOwnPropertyDescriptors(scope)));
-    if (!config || typeof config !== 'object' || Array.isArray(config))
-        return walk(config, scope, context, base, skip);
-    /**
-     * The config's own top-level keys, readable bare: `${{ publish.directory }}`. So a value that
-     * restates another - `after: "cp README.md ${{ publish.directory }}/"` - stops being a second
-     * copy that drifts when the first one changes.
-     *
-     * Resolved **on demand**, one key at a time, and memoized. Interpolating the config in tree order
-     * and handing an expression whatever was ready would make the answer depend on key order in the
-     * file, which is exactly the kind of quiet wrongness this evaluator exists to prevent: a key
-     * declared above would read as resolved and one below as raw. On demand, each key is resolved
-     * when first read and the order in the file means nothing.
-     */
-    const resolved = new Map();
-    const resolving = [];
-    /**
-     * A cycle is **recorded here rather than thrown from the getter**, and that is not a style
-     * choice: a host getter that throws inside a `vm` property interceptor has its exception
-     * swallowed, and V8 then reports the global as absent - so a self-referencing key came out as
-     * `publish is not defined`, which sends the reader looking for a missing key instead of a loop
-     * (measured). The getter returns `undefined`, the resulting `ReferenceError` is caught below, and
-     * this replaces it.
-     */
-    let cycle;
-    const resolve = (key) => {
-        if (resolved.has(key))
-            return resolved.get(key);
-        if (resolving.includes(key)) {
-            cycle ??= new Error(`Config expression forms a cycle: ${[...resolving, key].join(' -> ')}\n` +
-                `  A value cannot be derived from itself, directly or through another key.`);
-            return undefined;
-        }
-        resolving.push(key);
-        try {
-            const chain = config[PREVIOUS_VALUES];
-            const origins = config[ORIGINS];
-            const value = withOrigin(origins?.[key], () => walkWithPrevious(config[key], chain?.[key], scope, context, [...base, key], skip));
-            resolved.set(key, value);
-            return value;
-        }
-        catch (e) {
-            /** Not cleared: a cycle aborts the whole interpolation, and each level up would otherwise
-             *  re-swallow its own replacement the same way - leaving it set lets the outermost frame,
-             *  the one with a real stack to throw from, report it. */
-            if (cycle)
-                throw new Error(`${String(e?.message).split('\n')[0]}\n  ${cycle.message}`, { cause: e });
-            throw e;
-        }
-        finally {
-            resolving.pop();
-        }
-    };
-    for (const key of Object.keys(config)) {
-        /** A scope binding wins: `pkg`/`repository`/`env`/`semver` are not config keys, so nothing
-         *  collides today, and a future key that did must not silently take over the namespace. */
-        if (key in scope || !IDENTIFIER.test(key))
-            continue;
-        Object.defineProperty(context, key, { enumerable: true, configurable: true, get: () => resolve(key) });
-    }
-    /** Built through the same memo the getters use, so every key is walked exactly once whether an
-     *  expression asked for it first or the result did. */
-    const result = {};
-    for (const key of Object.keys(config))
-        result[key] = resolve(key);
-    return result;
-}
-/**
- * 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 const DEFERRED_PATHS = ['version.before', 'version.exec', 'version.after'];
-/**
- * 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
- * '[*]': {
- *   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 const STEP_PATHS = [
-    /** The bare-value shorthand: `run: { build: fn }` means `{ exec: fn }`, as `run: { build: 'cmd' }`
-     *  means `{ exec: 'cmd' }`. Missing it made the two spellings disagree about *when* the function
-     *  runs, which is worse than not supporting the short one at all. */
-    'run.*',
-    'run.*.before',
-    'run.*.exec',
-    'run.*.after',
-    /** A condition, evaluated per package by `RunService` when the run reaches it. Called here
-     *  instead, it collapsed to the boolean it happened to return at load time - and `parseIfExpr`
-     *  then read that boolean as "no condition given", so the script ran unconditionally (measured). */
-    'run.*.if',
-    'version.before',
-    'version.exec',
-    'version.after',
-];
-/**
- * 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 const CODE_SUBTREES = ['plugins'];
-const EXPRESSION = /\$\{\{([\s\S]*?)\}\}/g;
-/** A config key an expression could actually name. Anything else - a `"[selector]"` block, a
- *  `"lint:fix"` - is unreachable as a bare identifier anyway, so it is not bound. */
-const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-/** 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 function createReadScope(dirname, cache) {
-    return (target, format) => {
-        if (typeof target !== 'string' || !target.trim()) {
-            throw new Error('read() needs a path - it was given ' + JSON.stringify(target));
-        }
-        return readStructuredFile(path.resolve(dirname, target), format, cache);
-    };
-}
-export function createFileScope(dirname) {
-    const locate = (target) => {
-        if (typeof target !== 'string' || !target.trim()) {
-            throw new Error('file.exists()/file.resolve() need a path - they were given ' + JSON.stringify(target));
-        }
-        const resolved = path.resolve(dirname, target);
-        return { path: resolved, found: fs.existsSync(resolved) };
-    };
-    return {
-        exists(target) {
-            const { path: resolved, found } = locate(target);
-            return found ? resolved : '';
-        },
-        resolve(target) {
-            const { path: resolved, found } = locate(target);
-            if (!found) {
-                throw new Error(`file.resolve("${target}") found nothing at ${resolved}\n` +
-                    `  Use file.exists() instead if its absence is a case to handle rather than a mistake.`);
-            }
-            return resolved;
-        },
-        resolveFirst(...targets) {
-            if (!targets.length)
-                throw new Error('file.resolveFirst() needs at least one path');
-            for (const target of targets) {
-                const { path: resolved, found } = locate(target);
-                if (found)
-                    return resolved;
-            }
-            throw new Error(`file.resolveFirst() found none of: ${targets.map(t => `"${t}"`).join(', ')}\n` + `  Looked in ${dirname}.`);
-        },
-    };
-}
-function walk(value, scope, context, at, skip) {
-    /** Compared on the key path rather than the value, so a deferred key's whole subtree - a single
-     *  command or an array of them - is handed on untouched. */
-    if (at.length && skip.includes(at.filter(p => typeof p === 'string').join('.')))
-        return value;
-    if (typeof value === 'function') {
-        /** Code, not a value: a step for `run`/`version` to call in its own time, or a plugin's own
-         *  function. Carried through exactly as a command string would be - calling it here would run
-         *  build-time work while merely *loading* the repository, which is the whole distinction the
-         *  function form exists to draw. */
-        if (isCodePath(at))
-            return value;
-        return callValueFn(value, context, at);
-    }
-    if (typeof value === 'string')
-        return interpolateString(value, context, at);
-    if (Array.isArray(value))
-        return value.map((item, i) => walk(item, scope, context, [...at, i], skip));
-    if (value && typeof value === 'object') {
-        const chain = value[PREVIOUS_VALUES];
-        return withScopedVars(value, scope, context, at, skip, () => {
-            const result = {};
-            const origins = value[ORIGINS];
-            for (const [key, item] of Object.entries(value)) {
-                result[key] = withOrigin(origins?.[key], () => walkWithPrevious(item, chain?.[key], scope, context, [...at, key], skip));
-            }
-            return result;
-        });
-    }
-    return value;
-}
-/**
- * Runs `body` with `vars` scoped to this node: **a fresh copy at every level**, with the node's own
- * `vars` block - if it declares one - merged over what the level above resolved to.
- *
- * ```yaml
- * vars: { x: 1 }
- * run:
- *   vars: { x: 2 }
- *   clean: { before: '${{ read(vars.x + ".json") }}' }     # 2.json
- *   build:
- *     vars: { x: 3 }
- *     before: '${{ read(vars.x + ".json") }}'              # 3.json
- * ```
- *
- * **Copied at every node, not only where a `vars` block appears**, and that is the difference
- * between scoping and leaking: a value function is handed this object, so one that writes to it
- * (`vars.built = Date.now()`) must not be writing into the level above. Without a copy per node,
- * a write inside `run.build` would land in `run`'s object and `run.clean` would see it. Merged per
- * key rather than replaced, so redeclaring one var keeps the rest - the rule the top-level `vars`
- * has always followed.
- *
- * The node's own block is resolved **against the outer scope** before being installed, so
- * `vars: { out: '${{ vars.x }}/dist' }` reads the `x` it is refining rather than itself.
- *
- * Installed as a plain property over the context's lazy top-level getter and restored afterwards -
- * `walk` is depth-first and synchronous, so the window is exactly this subtree, and a value function
- * called inside it reads the same object through its prototype.
- */
-function withScopedVars(node, scope, context, at, skip, body) {
-    /**
-     * **A `vars` block does not scope itself.** Resolving one walks its own values, and without this
-     * that walk asks for the scope it is in the middle of producing - which the cycle guard catches
-     * and reports as `vars -> vars`. It recovered (the guard returns `undefined`, so the block simply
-     * saw no outer scope, which is what it should see anyway), but it left the cycle *flag* set, and
-     * the next genuine error in that key came out wearing `Config expression forms a cycle` - found by
-     * running a real shared config, whose `[...value]` mistake arrived with a loop attached that had
-     * nothing to do with it.
-     *
-     * Any path with a `vars` segment is inside a block: its contents are values, not config nodes.
-     */
-    if (at.some(segment => segment === VARS_KEY))
-        return body();
-    const outer = context[VARS_KEY];
-    const own = node[VARS_KEY];
-    /** Nothing to shadow and nothing to protect: a node with no object below it can hold no function
-     *  either, so the copy would be pure cost. */
-    if (own === undefined && !hasObjectChild(node))
-        return body();
-    const resolvedOwn = own === undefined ? undefined : walk(own, scope, context, [...at, VARS_KEY], skip);
-    const scoped = { ...outer, ...(isPlainObject(resolvedOwn) ? resolvedOwn : undefined) };
-    const previous = Object.getOwnPropertyDescriptor(context, VARS_KEY);
-    Object.defineProperty(context, VARS_KEY, { value: scoped, enumerable: true, configurable: true, writable: true });
-    try {
-        return body();
-    }
-    finally {
-        if (previous)
-            Object.defineProperty(context, VARS_KEY, previous);
-        else
-            delete context[VARS_KEY];
-    }
-}
-function hasObjectChild(node) {
-    for (const item of Object.values(node)) {
-        if (typeof item === 'function')
-            return true;
-        if (item && typeof item === 'object')
-            return true;
-    }
-    return false;
-}
-function isPlainObject(value) {
-    return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-/** The one key that scopes rather than configures - see `withScopedVars`. Reserved at **every**
- *  level, which costs a script that would have been called `vars`: `run.vars` is a scope, not a
- *  script. Nothing enumerates `run`'s keys as a list of script names, so the cost stops there. */
-const VARS_KEY = 'vars';
-/**
- * The file the key being walked was written in, for the errors below to name.
- *
- * A config is merged from several files before anything reads it - a directory's own forms, an
- * `extends` base, every `"[selector]"` block, one layer per directory - so `version.commitMessage`
- * alone does not say where to go and look. `mergeConfig` records the file per key (`ORIGINS`); this
- * is the depth-first cursor over that, kept in a module variable rather than threaded through
- * `walk`'s signature because every error site would otherwise have to carry a parameter it only
- * passes on.
- *
- * Nested keys inherit the enclosing file when the merge recorded none of their own, which is what a
- * nested object in one file means.
- */
-let currentOrigin;
-function withOrigin(origin, body) {
-    const outer = currentOrigin;
-    if (origin !== undefined)
-        currentOrigin = origin;
-    try {
-        return body();
-    }
-    finally {
-        currentOrigin = outer;
-    }
-}
-/** `"version.commitMessage" (.rmanrc.yml)`, or just the path when nothing recorded a file - a
- *  caller interpolating a fragment it built itself, say. Relative to the repository when it sits
- *  inside one, since an absolute path is noise in a message about the repository you are in. */
-function describeAt(at) {
-    const where = at.length ? formatPath(at) : 'the config root';
-    return currentOrigin ? `${where}" (${shortenOrigin(currentOrigin)})` : `${where}"`;
-}
-function shortenOrigin(file) {
-    const relative = path.relative(process.cwd(), file);
-    return !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file;
-}
-/**
- * Walks one key of an object with **`value` bound** to whatever the layers below it resolved to.
- *
- * Bound on the interpolation context rather than passed as an argument, because an expression reads
- * it as a global (`"${{ [...value, 'x'] }}"`) - a function then picks the same binding up through
- * its prototype, so the two spellings cannot disagree about what `value` is. It was function-only
- * at first, on the reasoning that a string cannot carry an array back; that was wrong, since a
- * string which is *nothing but* one expression keeps the value's own type.
- *
- * **Always bound, even with nothing underneath.** Left unbound, an expression naming it fails with
- * V8's `value is not defined`, which reads as "there is no such thing" rather than "nothing below
- * this layer set it" - two different mistakes needing two different fixes.
- *
- * The chain resolves bottom-up, so a layer deriving from a layer that itself derived from something
- * is handed the finished value rather than a half-resolved expression.
- */
-function walkWithPrevious(item, previous, scope, context, at, skip) {
-    const resolved = previous === undefined ? undefined : walkWithPrevious(previous.value, previous.previous, scope, context, at, skip);
-    const outer = Object.getOwnPropertyDescriptor(context, VALUE_KEY);
-    /** A getter, so the catch below can tell whether the value **actually read `value`**: the hint is
-     *  irrelevant to any other failure, and attaching it anyway is the send-the-reader-to-the-wrong-
-     *  place mistake it exists to prevent. Recorded, never matched on V8's wording. */
-    let wasRead = false;
-    Object.defineProperty(context, VALUE_KEY, {
-        configurable: true,
-        enumerable: true,
-        get: () => {
-            wasRead = true;
-            return resolved;
-        },
-    });
-    try {
-        return walk(item, scope, context, at, skip);
-    }
-    catch (e) {
-        /**
-         * **`value` is `undefined` when no layer underneath set this key**, and a value written to
-         * extend an inherited list is also the *first* layer in a repository that inherits nothing.
-         * V8 reports that as `value is not iterable`, naming neither the key nor the reason.
-         *
-         * Here rather than in `callValueFn`, so the expression and the function spelling get the same
-         * sentence from the same place. `rmanValueHint` keeps a rethrow from stacking it twice as the
-         * error passes back up through the enclosing keys.
-         *
-         * Not papered over by defaulting `value` to `[]`: that would be a guess about the key's type,
-         * and wrong for every key that is not a list.
-         */
-        if (wasRead && resolved === undefined && !e?.rmanValueHint) {
-            e.rmanValueHint = true;
-            e.message =
-                `${e.message}\n  \`value\` is undefined here - nothing below this layer sets "${describeAt(at)}.` +
-                    `\n  Write \`value ?? []\` (or \`?? ''\`) if it has to work as the first layer too.`;
-        }
-        throw e;
-    }
-    finally {
-        if (outer)
-            Object.defineProperty(context, VALUE_KEY, outer);
-        else
-            delete context[VALUE_KEY];
-    }
-}
-/** What a layer deriving from the one below it reads - see `walkWithPrevious`. */
-const VALUE_KEY = 'value';
-/**
- * Whether a function at `at` is **code** - a step to run later, or part of a plugin - rather than a
- * value to compute now.
- *
- * Array indices are dropped before matching, so a function inside a *list* of steps is still a
- * step; `*` in a `STEP_PATHS` entry matches any one segment (`run.<script>.exec`).
- */
-function isCodePath(at) {
-    const segments = at.filter((p) => typeof p === 'string');
-    if (CODE_SUBTREES.includes(segments[0]))
-        return true;
-    return STEP_PATHS.some(pattern => {
-        const parts = pattern.split('.');
-        return parts.length === segments.length && parts.every((part, i) => part === '*' || part === segments[i]);
-    });
-}
-/**
- * Calls a **value** function: the JS spelling of a `${{ }}` expression, and it answers the same
- * question at the same moment.
- *
- * It receives one object carrying everything an expression can name - `pkg`, `repository`, `file`,
- * `env`, `semver`, `path`, plus the config's own top-level keys - and, in addition, **`value`**: what
- * this key resolved to in the layers underneath, which is what makes a derived value possible
- * without restating the base.
- *
- * Built with the interpolation context as its **prototype**, not copied from it. The top-level keys
- * are lazy getters (`resolve`, memoized, so key order in the file means nothing and a cycle is
- * reported rather than half-resolved); spreading them into a new object would fire every one of
- * them on every call, including the ones a function never reads - and one of those throwing would
- * blame the wrong key.
- *
- * **It must compute and return, never act.** This runs while the repository's config resolves,
- * which *every* command does - so a value function that writes a file writes it on `rman list`,
- * `rman info` and `rman config` too, N times for N packages, with no command having asked for
- * anything. That is the same reason `FileScope` offers no way to change anything. Work goes in a
- * step, which is the one thing rman runs on purpose and which can also be a function.
- */
-function callValueFn(fn, context, at) {
-    /** `value` arrives through the prototype, bound by `walkWithPrevious` for exactly this key - so
-     *  nothing here may *read* it. Passing it in as an argument did, which tripped the "was it read"
-     *  getter before the function ran and put the `value` hint on every unrelated failure (caught by
-     *  the spec that exists for precisely that). */
-    const arg = Object.create(context);
-    /**
-     * A getter only so the catch below can tell whether the function **actually read `value`**.
-     *
-     * Without that, the "value is undefined" hint went out with *every* failure of a first-layer
-     * function - a frozen-object `TypeError` from `read()` arrived wearing advice about spreading an
-     * inherited list, which is precisely the send-the-reader-to-the-wrong-place mistake the hint
-     * exists to prevent. Recorded rather than inferred from the message, because matching on V8's
-     * wording is the other way to get this wrong.
-     */
-    try {
-        return fn(arg);
-    }
-    catch (e) {
-        /** The `value` hint comes from `walkWithPrevious`, which wraps this call and is the one place
-         *  that knows whether `value` was read - so the expression spelling gets the same sentence. */
-        throw new Error(`Config function in "${describeAt(at)} failed: ${e?.message}`, { cause: e });
-    }
-}
-function interpolateString(value, context, at) {
-    if (!value.includes('${{'))
-        return value;
-    const found = [...value.matchAll(EXPRESSION)];
-    if (!found.length)
-        return value;
-    /** Counted rather than matched with an anchored `^...$` regex: a lazy quantifier still backtracks
-     *  to satisfy an end anchor, so `"${{ a }} and ${{ b }}"` looked like *one* expression whose body
-     *  ran from `a` to `b`, brace-ends and all - invalid JavaScript. */
-    const soleExpression = found.length === 1 && found[0][0] === value.trim();
-    // Alone, a nullish result is just "this setting is unset" - a legitimate answer.
-    if (soleExpression)
-        return evaluate(found[0][1], value, context, at);
-    return value.replace(EXPRESSION, (_, expr) => {
-        const result = evaluate(expr, value, context, at);
-        /** Embedded in text, though, it never is: splicing in the word "undefined" produces a path or
-         *  tag like `app:undefined` that looks plausible and is wrong - the exact silent-mistake shape
-         *  this evaluator exists to avoid. `?? 'fallback'` says what was meant. */
-        if (result === undefined || result === null) {
-            throw new Error(`Expression in "${describeAt(at)} is ${result} inside a string: ${value.trim()}\n` +
-                `  \${{${expr}}} has no value here - give it a fallback (\${{${expr.trim()} ?? '...'}}).`);
-        }
-        return String(result);
-    });
-}
-/** Names the config path as well as the expression: an error saying only "x is not defined" sends
- *  the reader hunting through a file that may hold dozens of them. */
-function evaluate(expr, source, context, at) {
-    try {
-        return vm.runInContext(expr, context, { timeout: EXPRESSION_TIMEOUT });
-    }
-    catch (e) {
-        throw new Error(`Invalid expression in "${describeAt(at)}: ${source.trim()}\n  ${e?.message ?? e}`, { cause: e });
-    }
-}
-function formatPath(at) {
-    return at.reduce((acc, part) => (typeof part === 'number' ? `${acc}[${part}]` : acc ? `${acc}.${part}` : String(part)), '');
-}
-/** Guards against an expression that never returns (`while(true)`) taking the whole command with
- *  it - a typo, not an attack, but the failure mode is identical. */
-const EXPRESSION_TIMEOUT = 1000;
-/**
- * Reads and parses one structured file, memoized against **the identity of its contents** rather
- * than its path alone: the cache key is `mtimeNs:size`.
- *
- * Both halves of that were chosen against a measurement.
- *
- * - **A stat rather than a re-read**: `statSync` is 1.3µs where `readFileSync` + `JSON.parse` is
- *   16.1µs on a 2KB manifest - so the check costs a thirteenth of what it saves, and the same file
- *   read by twenty packages is parsed once. (`interpolateConfig` runs once *per package*, so a
- *   cache living in one pass would not have helped across them at all.)
- * - **Keyed on the stat rather than held for the run**: rman writes JSON files while it is running
- *   - `version` rewrites every bumped manifest, then re-interpolates its own deferred hooks. A
- *   cache that only remembered the path would hand those back as they were before the write.
- *   `mtimeNs` is nanoseconds, so a rewrite within the same millisecond does not slip through; the
- *   size is in the key as well because it costs nothing.
- *
- * **Frozen, deeply, once on the way into the cache.** Every package is handed the same object, so
- * one config mutating it would quietly change what the next package sees - the reason `pkg.manifest`
- * has always been a copy. Freezing is better than copying here: a copy costs 5.6µs on *every* call,
- * freezing costs ~1µs *once*, and it turns the mistake into a `TypeError` instead of an effect at a
- * distance. A caller that wants to change something spreads it first.
- */
-function readStructuredFile(file, format, cache) {
-    let stat;
-    try {
-        stat = fs.statSync(file, { bigint: true });
-    }
-    catch {
-        throw new Error(`read("${path.basename(file)}") found nothing at ${file}\n` +
-            `  Use file.exists() first if its absence is a case to handle rather than a mistake.`);
-    }
-    if (stat.isDirectory())
-        throw new Error(`read() was given a directory, not a file: ${file}`);
-    const stamp = `${stat.mtimeNs}:${stat.size}`;
-    const cached = cache.get(file);
-    if (cached?.stamp === stamp)
-        return cached.value;
-    const resolved = format ?? formatOf(file);
-    const text = fs.readFileSync(file, 'utf-8');
-    let value;
-    try {
-        value = parseStructured(text, resolved);
-    }
-    catch (e) {
-        /** The parser's own message says what is wrong with the syntax but never which file it was
-         *  reading - and an expression can name several. */
-        throw new Error(`read("${path.basename(file)}") could not parse ${file} as ${resolved}: ${e?.message}`, {
-            cause: e,
-        });
-    }
-    deepFreeze(value);
-    cache.set(file, { stamp, value });
-    return value;
-}
-/** The extension decides, because the caller already wrote it - naming the parser as well would
- *  restate it and let the two disagree (`json("x.yml")`). A name that says nothing takes the
- *  explicit argument instead. */
-function formatOf(file) {
-    const ext = path.extname(file).toLowerCase();
-    if (ext === '.json')
-        return 'json';
-    if (ext === '.yml' || ext === '.yaml')
-        return 'yaml';
-    if (ext === '.ini')
-        return 'ini';
-    if (XML_EXTENSIONS.has(ext))
-        return 'xml';
-    throw new Error(`read() cannot tell what "${path.basename(file)}" is from its name.\n` +
-        `  Name the format: read("${path.basename(file)}", "json" | "yaml" | "ini" | "xml").`);
-}
-/** The XML family worth recognizing by name: a project file is XML whatever its extension calls
- *  itself, and `.csproj`/`.pom` are what a .NET or Maven repository actually holds. Anything else
- *  still reads with an explicit `read(p, 'xml')`. */
-const XML_EXTENSIONS = new Set(['.xml', '.csproj', '.vbproj', '.fsproj', '.props', '.targets', '.nuspec', '.plist']);
-function parseStructured(text, format) {
-    if (format === 'json')
-        return JSON.parse(text);
-    /** `load`, not `loadAll`: a multi-document stream has no single value to be, and js-yaml says so
-     *  clearly enough ("expected a single document in the stream") to leave alone. */
-    if (format === 'yaml')
-        return yaml.load(text);
-    if (format === 'xml')
-        return parseXml(text);
-    return ini.parse(text);
-}
-/**
- * A **DOM**, not an object - and the asymmetry with the other three formats is the honest shape
- * rather than an omission.
- *
- * XML has no lossless object form: an element can repeat, carry attributes and hold text at the
- * same time, so any flattening has to pick a convention (`$`? `_text`? array-or-not?) and be wrong
- * for somebody. A DOM is the shape XML actually has, so a config reads it the way every other XML
- * tool does:
- *
- * ```yaml
- * version: '${{ read("pom.xml").getElementsByTagName("version")[0].textContent }}'
- * ```
- *
- * **Freezing it is safe** - measured, not assumed: a frozen `@xmldom/xmldom` document still answers
- * `getElementsByTagName` for a tag first asked about *after* the freeze (the live-collection case
- * that would have broken it), reads attributes, resolves namespaces, walks `childNodes` and
- * serialises back.
- */
-function parseXml(text) {
-    /** xmldom reports a malformed document through a handler and otherwise carries on with whatever
-     *  it could salvage - so without this, a broken file would come back as a half-parsed DOM and the
-     *  expression reading it would simply find nothing. `read()` throws for a broken JSON file; it has
-     *  to throw for this one too. */
-    const problems = [];
-    const doc = new DOMParser({
-        onError: (level, message) => {
-            if (level !== 'warning')
-                problems.push(message.split('\n')[0]);
-        },
-    }).parseFromString(text, 'text/xml');
-    if (problems.length)
-        throw new Error(problems[0]);
-    return doc;
-}
-function deepFreeze(value) {
-    if (!value || typeof value !== 'object' || Object.isFrozen(value))
-        return;
-    Object.freeze(value);
-    for (const item of Object.values(value))
-        deepFreeze(item);
-}