rman 1.0.12 → 1.2.1

package/core/config.js

@@ -1,11 +1,14 @@
+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 merge from 'putil-merge';
 import semver from 'semver';
 import { pathToFileURL } from 'url';
 import vm from 'vm';
+import { assertNoSelectorExtends, EXTENDS_KEY, resolveExtends } from './extends-config.js';
+import { finalizeConfig, mergeConfig, PREVIOUS_VALUE } 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
@@ -58,33 +61,56 @@ async function loadJsConfig(file) {
  */
 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')
-            merge(result, pkgJson.rman, { deep: true });
+        if (pkgJson && typeof pkgJson.rman === 'object') {
+            assertNoSelectorExtends(pkgJson.rman, pkgJsonFile);
+            if (EXTENDS_KEY in pkgJson.rman)
+                extendsFrom = pkgJsonFile;
+            mergeConfig(result, pkgJson.rman);
+        }
     }
     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')
-            merge(result, obj, { deep: true });
+        if (obj && typeof obj === 'object') {
+            assertNoSelectorExtends(obj, ymlFile);
+            if (EXTENDS_KEY in obj)
+                extendsFrom = ymlFile;
+            mergeConfig(result, obj);
+        }
     }
     const rcFile = path.join(dirname, '.rmanrc');
     if (fs.existsSync(rcFile)) {
         const obj = JSON.parse(fs.readFileSync(rcFile, 'utf-8'));
-        if (obj && typeof obj === 'object')
-            merge(result, obj, { deep: true });
+        if (obj && typeof obj === 'object') {
+            assertNoSelectorExtends(obj, rcFile);
+            if (EXTENDS_KEY in obj)
+                extendsFrom = rcFile;
+            mergeConfig(result, obj);
+        }
     }
     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')
-                merge(result, obj, { deep: true });
+            if (obj && typeof obj === 'object') {
+                assertNoSelectorExtends(obj, jsFile);
+                if (EXTENDS_KEY in obj)
+                    extendsFrom = jsFile;
+                mergeConfig(result, obj);
+            }
         }
     }
-    return result;
+    /** 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
@@ -97,9 +123,10 @@ export async function readDirConfig(dirname) {
  *   `.rmanrc` therefore configures the *root package* - which is where repo-wide settings
  *   (`packageManager`, `allowBranch`, `version.*`, `githubRelease.*`) are read from anyway - and
  *   not, silently, every package under it.
- * - **A `"[selector]"` block configures the packages it names** (`"[*]"` for all of them,
- *   `"[*-dialect]"` for a glob over package names). This is the only way a directory speaks about
- *   anything but its own package.
+ * - **A `"[selector]"` block configures the packages it names** - `"[*]"` for all of them (the root
+ *   included), `"[ws:*]"` for every one but the root, `"[/]"` for the root alone, `"[*-dialect]"`
+ *   for a glob over package names. See `parseSelector`. This is the only way a directory speaks
+ *   about anything but its own package.
  *
  * Splitting the two matters because the same key means different things to the two audiences. The
  * clearest case is `run.<script>.postScript`: on a package it's that package's build hook, run in
@@ -107,64 +134,137 @@ export async function readDirConfig(dirname) {
  * cascade that fed one declaration to both ran a package-relative command (`node
  * ../../support/postbuild.cjs`) at the root, where it cannot resolve.
  *
- * `packageName` is what selectors match against; without it (resolving the root's own config, say)
- * selector blocks contribute nothing at all.
+ * `packageName` is what selectors match against; without it, selector blocks contribute nothing at
+ * all. The root package passes its own, since `"[/]"` and `"[*]"` speak to it.
  */
 export 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 `"[ws:*]"` 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);
         }
-        // Selectors first, so a directory's own unmarked config still wins over a selector declared
-        // alongside it - "this package" is a more specific statement than "packages matching a glob".
-        if (packageName) {
-            for (const block of matchingSelectors(local, packageName))
-                merge(result, block, { deep: true });
-        }
         // A directory holding a package speaks for that package only - which is what keeps the root's
         // own config off every package under it. A directory that holds none (an intermediate
         // `packages/`, say) has no package to speak for, so its unmarked config can only mean
         // "everything below" and still cascades.
         const ownsAPackage = fs.existsSync(path.join(dir, 'package.json'));
-        if (!ownsAPackage || path.resolve(dir) === target)
-            merge(result, stripSelectors(local), { deep: true });
+        const speaksForTarget = !ownsAPackage || path.resolve(dir) === target;
+        /**
+         * `vars` is the **one** unmarked key that cascades past the package its directory speaks for,
+         * and it is not a hole in that rule - it is a key the rule was never about. The rule exists
+         * because a setting means different things to the two audiences (`run.build.after` on the root
+         * is a repo-wide bookend, on a package its own hook), so one declaration cannot serve both.
+         * `vars: {x: 1}` means the number 1 to everyone; there is no second audience to be wrong for.
+         *
+         * Merged *before* this directory's selector blocks, so `"[*]": {vars: ...}` - which names the
+         * packages explicitly - overrides the same directory's plainer statement.
+         */
+        if (!speaksForTarget && local.vars !== undefined)
+            mergeConfig(result, { vars: local.vars });
+        // Selectors next, so a directory's own unmarked config still wins over a selector declared
+        // alongside it - "this package" is a more specific statement than "packages matching a glob".
+        if (packageName) {
+            for (const block of matchingSelectors(local, packageName, isRoot))
+                mergeConfig(result, block);
+        }
+        if (speaksForTarget)
+            mergeConfig(result, stripSelectors(local));
     }
-    return result;
+    /** 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: `"[*]"`, `"[*-dialect]"`, `"[pkg-a]"`. The
+/** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[ws:*]"`, `"[pkg-a]"`. The
  *  brackets are what keep this space from colliding with real config keys - no setting starts with
  *  one - and in YAML they also mean the key always needs quoting (`"[*]":`), since a bare `[*]`
  *  parses as a flow sequence. */
 export function isSelectorKey(key) {
     return key.length > 2 && key.startsWith('[') && key.endsWith(']');
 }
+/**
+ * **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 function parseSelector(key) {
+    const inner = key.slice(1, -1);
+    if (inner === ROOT_SELECTOR_INNER)
+        return { scope: 'root', test: () => true };
+    for (const prefix of WORKSPACE_PREFIXES) {
+        if (inner.startsWith(prefix)) {
+            const re = globToRegExp(inner.slice(prefix.length));
+            return { scope: 'workspace', test: name => re.test(name) };
+        }
+    }
+    const re = globToRegExp(inner);
+    return { scope: 'all', 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) {
-    const glob = key.slice(1, -1);
-    const source = glob
-        .split('*')
-        .map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
-        .join('.*');
-    return new RegExp(`^${source}$`);
+    return globToRegExp(key.slice(1, -1));
 }
-/** Every selector block in `config` matching `packageName`, in increasing precedence: `"[*]"` first
- *  and the rest in declaration order - so a specific glob overrides the catch-all, and two equally
- *  specific ones resolve by the order they were written in. */
-function matchingSelectors(config, packageName) {
+/**
+ * Every selector block in `config` that speaks for this package, in increasing precedence.
+ *
+ * Order, lowest first: **`"[*]"`, then a catch-all `"[ws:*]"`, then the rest in declaration
+ * order** - so narrowing the audience wins over the widest one, a named package or `"[/]"` wins
+ * over both, and two equally specific globs resolve by the order they were written in. A catch-all
+ * is ranked rather than left to declaration order on purpose: where you happen to write "everything"
+ * should not decide whether it beats a rule about one package.
+ */
+function matchingSelectors(config, packageName, isRoot) {
     const matches = [];
     for (const [key, value] of Object.entries(config)) {
         if (!isSelectorKey(key) || !value || typeof value !== 'object')
             continue;
-        if (selectorToRegExp(key).test(packageName))
-            matches.push([key, value]);
+        const { scope, test } = parseSelector(key);
+        if (scope === 'root' && !isRoot)
+            continue;
+        if (scope === 'workspace' && isRoot)
+            continue;
+        if (!test(packageName))
+            continue;
+        matches.push([selectorRank(key), value]);
     }
-    return matches.sort((a, b) => Number(b[0] === CATCH_ALL) - Number(a[0] === CATCH_ALL)).map(([, block]) => block);
+    return matches.sort((a, b) => a[0] - b[0]).map(([, block]) => block);
+}
+/** 0 for `"[*]"`, 1 for a catch-all workspace selector, 2 for anything that names something. Equal
+ *  ranks keep their declaration order, since `Array.prototype.sort` is stable. */
+function selectorRank(key) {
+    if (key === CATCH_ALL)
+        return 0;
+    const inner = key.slice(1, -1);
+    return WORKSPACE_PREFIXES.some(prefix => inner === `${prefix}*`) ? 1 : 2;
+}
+function globToRegExp(glob) {
+    const source = glob
+        .split('*')
+        .map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        .join('.*');
+    return new RegExp(`^${source}$`);
 }
 function stripSelectors(config) {
     const result = {};
@@ -174,6 +274,12 @@ function stripSelectors(config) {
     return result;
 }
 const CATCH_ALL = '[*]';
+/** `"[/]"` - 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 = '/';
+/** Both spellings of "the workspace packages, not the root". The long one reads in a config file
+ *  someone else has to understand; the short one is what gets typed. */
+const WORKSPACE_PREFIXES = ['workspace:', 'ws:'];
 function dirChain(rootDir, targetDir) {
     const rel = path.relative(rootDir, targetDir);
     if (!rel || rel === '.' || rel.startsWith('..'))
@@ -186,61 +292,404 @@ function dirChain(rootDir, targetDir) {
     }
     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 value = walk(config[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;
+}
 /**
- * Evaluates every `${{ ... }}` expression in **every** string value of a resolved config, against
- * the package it was resolved for:
+ * Config paths left untouched when a repository's config is first resolved, and evaluated only by
+ * the command that runs them.
  *
- * ```yaml
- * "[*]":
- *   clean:
- *     include: ["build", "../../coverage/${{ pkg.basename }}"]
- *   publish:
- *     docker:
- *       image: "panates/${{ pkg.basename }}:${{ semver.major(pkg.version) }}"
- * ```
+ * `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`).
  *
- * Every string, with no list of "interpolated keys" to memorize - a rule with exceptions is a rule
- * nobody remembers.
+ * This is what tells a step function from a value function, and the two live side by side in one
+ * config:
  *
- * 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.
+ * ```js
+ * '[ws:*]': {
+ *   clean: { include: ({ vars, value }) => [...value, vars.buildDir] },   // a value: called here
+ *   run: { build: { after: ({ pkg }) => copyDocs(pkg) } },                // a step: called by `run`
+ * }
+ * ```
  *
- * **`${{ }}`, 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: `${{ '${{' }}`.
+ * **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 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.
+ * 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`.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * ```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 interpolateConfig(config, scope) {
-    const context = vm.createContext({ ...scope });
-    return walk(config, scope, context, []);
+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);
+    };
 }
-const EXPRESSION = /\$\{\{([\s\S]*?)\}\}/g;
-function walk(value, scope, context, at) {
+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, scope, context, at, skip);
+    }
     if (typeof value === 'string')
         return interpolateString(value, context, at);
     if (Array.isArray(value))
-        return value.map((item, i) => walk(item, scope, context, [...at, i]));
+        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]);
-        return result;
+        return withScopedVars(value, scope, context, at, skip, () => {
+            const result = {};
+            for (const [key, item] of Object.entries(value))
+                result[key] = walk(item, 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';
+/**
+ * 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, scope, context, at, skip) {
+    const previous = fn[PREVIOUS_VALUE];
+    const arg = Object.create(context);
+    /** Resolved the same way any other value is, so an inherited `${{ }}` string or a function under
+     *  it is already finished by the time this one is handed it. */
+    const resolvedPrevious = previous === undefined ? undefined : walk(previous, scope, context, at, skip);
+    /**
+     * 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.
+     */
+    let valueRead = false;
+    Object.defineProperty(arg, 'value', {
+        enumerable: true,
+        get: () => {
+            valueRead = true;
+            return resolvedPrevious;
+        },
+    });
+    try {
+        return fn(arg);
+    }
+    catch (e) {
+        const where = at.length ? formatPath(at) : 'the config root';
+        /**
+         * **`value` is `undefined` when no layer underneath set this key.** A function written to extend
+         * an inherited list (`[...value, x]`) is also the *first* layer in a repository that inherits
+         * nothing, and V8's report for that is `value is not iterable` - which names neither the key nor
+         * the reason, and sends the reader looking at their spread instead of at what is missing.
+         *
+         * Told rather than papered over: defaulting `value` to `[]` would be a guess about the key's
+         * type, and wrong for every key that is not a list.
+         */
+        const hint = valueRead && resolvedPrevious === undefined
+            ? `\n  \`value\` is undefined here - nothing below this layer sets "${where}".` +
+                `\n  Write \`value ?? []\` (or \`?? ''\`) if the function has to work as the first layer too.`
+            : '';
+        throw new Error(`Config function in "${where}" failed: ${e?.message}${hint}`, { cause: e });
+    }
+}
 function interpolateString(value, context, at) {
     if (!value.includes('${{'))
         return value;
@@ -284,3 +733,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);
+}