rman 1.1.1 → 1.2.2

package/core/config.js

@@ -1,4 +1,6 @@
+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';
@@ -6,7 +8,7 @@ import semver from 'semver';
 import { pathToFileURL } from 'url';
 import vm from 'vm';
 import { assertNoSelectorExtends, EXTENDS_KEY, resolveExtends } from './extends-config.js';
-import { finalizeConfig, mergeConfig } from './merge-config.js';
+import { finalizeConfig, mergeConfig, 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
@@ -290,53 +292,31 @@ function dirChain(rootDir, targetDir) {
     }
     return dirs;
 }
-/**
- * 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 function interpolateConfig(config, scope, options) {
     const skip = options?.skip ?? [];
-    const context = vm.createContext({ ...scope });
+    /**
+     * 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, [], skip);
+        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
@@ -369,7 +349,8 @@ export function interpolateConfig(config, scope, options) {
         }
         resolving.push(key);
         try {
-            const value = walk(config[key], scope, context, [key], skip);
+            const chain = config[PREVIOUS_VALUES];
+            const value = walkWithPrevious(config[key], chain?.[key], scope, context, [...base, key], skip);
             resolved.set(key, value);
             return value;
         }
@@ -409,11 +390,87 @@ export function interpolateConfig(config, scope, options) {
  * 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
+ * '[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 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()) {
@@ -452,18 +509,236 @@ function walk(value, scope, context, at, skip) {
      *  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 result = {};
-        for (const [key, item] of Object.entries(value))
-            result[key] = walk(item, scope, context, [...at, key], skip);
-        return result;
+        const chain = value[PREVIOUS_VALUES];
+        return withScopedVars(value, scope, context, at, skip, () => {
+            const result = {};
+            for (const [key, item] of Object.entries(value)) {
+                result[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';
+/**
+ * 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) {
+            const where = at.length ? formatPath(at) : 'the config root';
+            e.rmanValueHint = true;
+            e.message =
+                `${e.message}\n  \`value\` is undefined here - nothing below this layer sets "${where}".` +
+                    `\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) {
+        const where = at.length ? formatPath(at) : 'the config root';
+        /** 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 "${where}" failed: ${e?.message}`, { cause: e });
+    }
+}
 function interpolateString(value, context, at) {
     if (!value.includes('${{'))
         return value;
@@ -507,3 +782,129 @@ function formatPath(at) {
 /** 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);
+}

package/core/merge-config.d.ts

@@ -14,6 +14,30 @@ export declare const APPEND_PREFIX = "+";
  * layer, which is only acceptable where the value is a set of contributions rather than a decision.
  */
 export declare const ALWAYS_APPEND: readonly string[];
+/**
+ * Where a key keeps what it is replacing, so the replacement can be handed it back as `value`.
+ *
+ * A **symbol-keyed chain on the containing object**, one entry per key, rather than something
+ * attached to the value itself. It started as a wrapper around a *function*, which is the only kind
+ * of value you can hang a property on - and that is exactly why it had to change: `value` belongs to
+ * an expression (`"${{ [...value, 'x'] }}"`) just as much as to a function, and a string cannot
+ * carry one.
+ *
+ * A symbol is invisible to `Object.entries`, `JSON.stringify` and js-yaml, so the chain travels
+ * through `mergeConfig`, `finalizeConfig` and `rman config` without any of them having to know it
+ * is there.
+ *
+ * Each entry is a link, not a single slot: three layers each deriving from the one below need
+ * `A <- expr2 <- expr3`, and one slot would have lost `A` the moment `expr3` arrived.
+ */
+export declare const PREVIOUS_VALUES: unique symbol;
+/** One link: the raw value this key held, and whatever *it* was derived from. */
+export interface PreviousValue {
+    value: unknown;
+    previous?: PreviousValue;
+}
+/** Only these two can ask for `value`, so only these two are worth remembering a previous for. */
+export declare function carriesPreviousValue(value: unknown): boolean;
 /** `"+before"` -> `"before"`, or `undefined` for a key that isn't an append. */
 export declare function appendTarget(key: string): string | undefined;
 /**

package/core/merge-config.js

@@ -14,6 +14,27 @@ export const APPEND_PREFIX = '+';
  * layer, which is only acceptable where the value is a set of contributions rather than a decision.
  */
 export const ALWAYS_APPEND = ['plugins'];
+/**
+ * Where a key keeps what it is replacing, so the replacement can be handed it back as `value`.
+ *
+ * A **symbol-keyed chain on the containing object**, one entry per key, rather than something
+ * attached to the value itself. It started as a wrapper around a *function*, which is the only kind
+ * of value you can hang a property on - and that is exactly why it had to change: `value` belongs to
+ * an expression (`"${{ [...value, 'x'] }}"`) just as much as to a function, and a string cannot
+ * carry one.
+ *
+ * A symbol is invisible to `Object.entries`, `JSON.stringify` and js-yaml, so the chain travels
+ * through `mergeConfig`, `finalizeConfig` and `rman config` without any of them having to know it
+ * is there.
+ *
+ * Each entry is a link, not a single slot: three layers each deriving from the one below need
+ * `A <- expr2 <- expr3`, and one slot would have lost `A` the moment `expr3` arrived.
+ */
+export const PREVIOUS_VALUES = Symbol('rman.previousValues');
+/** Only these two can ask for `value`, so only these two are worth remembering a previous for. */
+export function carriesPreviousValue(value) {
+    return typeof value === 'function' || (typeof value === 'string' && value.includes('${{'));
+}
 /** `"+before"` -> `"before"`, or `undefined` for a key that isn't an append. */
 export function appendTarget(key) {
     return key.length > APPEND_PREFIX.length && key.startsWith(APPEND_PREFIX)
@@ -108,6 +129,11 @@ export function finalizeConfig(config) {
         const pending = finalizeConfig(value);
         result[plain] = plain in result ? [...toList(result[plain]), ...toList(pending)] : toList(pending);
     }
+    /** Carried across by hand: this rebuilds the object from `Object.entries`, which does not see a
+     *  symbol - and dropping it here would lose every `value` chain the merge just recorded. */
+    const chain = config[PREVIOUS_VALUES];
+    if (chain)
+        Object.defineProperty(result, PREVIOUS_VALUES, { value: chain });
     return result;
 }
 function assignMerged(target, key, value) {
@@ -117,6 +143,23 @@ function assignMerged(target, key, value) {
         mergeConfig(target[key], value);
         return;
     }
+    /**
+     * A value that can ask for `value` **replaces** like any other - and remembers what it replaced:
+     *
+     * ```js
+     * '[*]':    { clean: { include: ({ vars }) => [vars.buildDir] } }
+     * '[ws:*]': { clean: { include: "${{ [...value, pkg.basename + '.log'] }}" } }
+     * ```
+     *
+     * Chained here rather than at resolution time because only the merge knows the order of the
+     * layers - by the time `interpolateConfig` sees the config they have collapsed into one object,
+     * and whatever a closer layer said has already taken the place of what it was derived from.
+     */
+    if (carriesPreviousValue(value) && key in target) {
+        const carrier = target;
+        const chain = (carrier[PREVIOUS_VALUES] ??= {});
+        chain[key] = { value: target[key], previous: chain[key] };
+    }
     target[key] = Array.isArray(value) ? [...value] : value;
 }
 /**