rman 1.2.1 → 1.2.4

package/constants.js

@@ -1 +1 @@
-export const version = '1.2.1';
+export const version = '1.2.4';

package/core/config.js

@@ -8,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, PREVIOUS_VALUE } 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
@@ -349,7 +349,8 @@ export function interpolateConfig(config, scope, options) {
         }
         resolving.push(key);
         try {
-            const value = walk(config[key], scope, context, [...base, 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;
         }
@@ -515,17 +516,19 @@ function walk(value, scope, context, at, skip) {
          *  function form exists to draw. */
         if (isCodePath(at))
             return value;
-        return callValueFn(value, scope, context, at, skip);
+        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 = {};
-            for (const [key, item] of Object.entries(value))
-                result[key] = walk(item, scope, context, [...at, key], skip);
+            for (const [key, item] of Object.entries(value)) {
+                result[key] = walkWithPrevious(item, chain?.[key], scope, context, [...at, key], skip);
+            }
             return result;
         });
     }
@@ -609,6 +612,71 @@ function isPlainObject(value) {
  *  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.
@@ -646,12 +714,12 @@ function isCodePath(at) {
  * 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];
+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);
-    /** 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`**.
      *
@@ -661,33 +729,14 @@ function callValueFn(fn, scope, context, at, skip) {
      * 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 });
+        /** 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) {

package/core/merge-config.d.ts

@@ -15,18 +15,29 @@ export declare const APPEND_PREFIX = "+";
  */
 export declare const ALWAYS_APPEND: readonly string[];
 /**
- * Where a value function keeps the value it is replacing, so it can be handed back as `value`.
+ * Where a key keeps what it is replacing, so the replacement can be handed it back as `value`.
  *
- * A **symbol on a forwarding wrapper**, rather than a class or a `{fn, prev}` object, for one
- * concrete reason: every walker in this file and in `config.ts` decides what to do by asking
- * `isPlainObject`, and a wrapper object would answer yes - `finalizeConfig` would rebuild it as a
- * plain object and lose the function, and `mergeConfig` would try to merge into it key by key. A
- * function is not a plain object, so it travels through all of them untouched.
+ * 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.
  *
- * The user's own function is never mutated: two packages inheriting the same shared-config function
- * would otherwise share - and overwrite - one `prev`.
+ * 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_VALUE: unique symbol;
+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

@@ -15,18 +15,26 @@ export const APPEND_PREFIX = '+';
  */
 export const ALWAYS_APPEND = ['plugins'];
 /**
- * Where a value function keeps the value it is replacing, so it can be handed back as `value`.
+ * Where a key keeps what it is replacing, so the replacement can be handed it back as `value`.
  *
- * A **symbol on a forwarding wrapper**, rather than a class or a `{fn, prev}` object, for one
- * concrete reason: every walker in this file and in `config.ts` decides what to do by asking
- * `isPlainObject`, and a wrapper object would answer yes - `finalizeConfig` would rebuild it as a
- * plain object and lose the function, and `mergeConfig` would try to merge into it key by key. A
- * function is not a plain object, so it travels through all of them untouched.
+ * 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.
  *
- * The user's own function is never mutated: two packages inheriting the same shared-config function
- * would otherwise share - and overwrite - one `prev`.
+ * 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_VALUE = Symbol('rman.previousValue');
+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)
@@ -121,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) {
@@ -131,41 +144,24 @@ function assignMerged(target, key, value) {
         return;
     }
     /**
-     * A function **replaces** like any other value - and remembers what it replaced, so it can be
-     * given it back as `value` when the config resolves:
+     * 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 }) => [...value, pkg.basename + '.log'] } }
+     * '[*]':    { 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 (typeof value === 'function') {
-        target[key] = chainValueFn(value, target[key]);
-        return;
+    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;
 }
-/**
- * Wraps `fn` so it carries `previous`, leaving `fn` itself alone.
- *
- * The wrapper forwards every argument unchanged, which is what lets one rule cover both kinds of
- * function a config can hold: a **value** function is called by `interpolateConfig` with the config
- * scope, a **step** function by `RunService` with a `RunStepContext`, and neither needs to know it
- * has been wrapped. `name` is copied over because a step's label is its function's name.
- */
-function chainValueFn(fn, previous) {
-    const wrapper = (...args) => fn(...args);
-    Object.defineProperty(wrapper, 'name', { value: fn.name, configurable: true });
-    /** Only when there *is* one: an own property set to `undefined` is indistinguishable from an
-     *  inherited value that genuinely resolved to nothing. */
-    if (previous !== undefined)
-        Object.defineProperty(wrapper, PREVIOUS_VALUE, { value: previous });
-    return wrapper;
-}
 /**
  * Appends `value` to `target[key]`, de-duplicating **only** an `ALWAYS_APPEND` key.
  *

package/core/resolve-target.d.ts

@@ -10,3 +10,31 @@
  * `label` names the config key in the error, so a failure says which setting to go and look at.
  */
 export declare function resolveConfigTarget(target: string, from: string, label: string): string;
+/**
+ * The fallback: a plugin or shared config installed **beside rman itself**, tried when the
+ * repository cannot resolve it.
+ *
+ * A globally installed rman's siblings *are* the globally installed packages, so this is what makes
+ * `rman ci` work on a fresh clone - the command comes from `rman-node`, and `ci` exists to create
+ * the very `node_modules` the plugin would otherwise have to be found in. Measured: with both
+ * installed globally, a clone answered `"plugins" target "rman-node" could not be resolved ... is
+ * it installed in this repository?`, which was true and useless.
+ *
+ * **The repository is always tried first**, so a repository carrying its own copy is unaffected and
+ * its version always wins. This is a fallback, never a search order: `createRequire` is based on the
+ * config file precisely so a repository's config resolves against the repository.
+ *
+ * It is deliberately *not* gated on whether the repository looks installed. That was tried - fall
+ * back only when there is no `node_modules` anywhere above the config file - on the reasoning that
+ * an installed repository merely *missing* a dependency should keep the honest error. It reads well
+ * and behaves unpredictably: the walk reaches the filesystem root, so a checkout under any directory
+ * that happens to have a `node_modules` (a home directory, a nested clone) silently lost the
+ * fallback. A rule whose answer depends on where the repository was cloned is worse than the
+ * looser one.
+ *
+ * `from` exists for the specs, and is the whole test seam: the answer depends on where **this
+ * module** sits, so a spec running inside this repository could otherwise only ever prove that this
+ * repository can see its own `node_modules`. Given a throwaway layout's URL it exercises the real
+ * resolution - no subprocess, and nothing to keep in step with the source.
+ */
+export declare function resolveBesideRman(target: string, from?: string): string | undefined;

package/core/resolve-target.js

@@ -28,6 +28,44 @@ export function resolveConfigTarget(target, from, label) {
         return createRequire(pathToFileURL(path.join(dir, 'noop.js'))).resolve(target);
     }
     catch {
+        const beside = resolveBesideRman(target);
+        if (beside)
+            return beside;
         throw new Error(`"${label}" target "${target}" could not be resolved from "${from}" - is it installed in this repository?`);
     }
 }
+/**
+ * The fallback: a plugin or shared config installed **beside rman itself**, tried when the
+ * repository cannot resolve it.
+ *
+ * A globally installed rman's siblings *are* the globally installed packages, so this is what makes
+ * `rman ci` work on a fresh clone - the command comes from `rman-node`, and `ci` exists to create
+ * the very `node_modules` the plugin would otherwise have to be found in. Measured: with both
+ * installed globally, a clone answered `"plugins" target "rman-node" could not be resolved ... is
+ * it installed in this repository?`, which was true and useless.
+ *
+ * **The repository is always tried first**, so a repository carrying its own copy is unaffected and
+ * its version always wins. This is a fallback, never a search order: `createRequire` is based on the
+ * config file precisely so a repository's config resolves against the repository.
+ *
+ * It is deliberately *not* gated on whether the repository looks installed. That was tried - fall
+ * back only when there is no `node_modules` anywhere above the config file - on the reasoning that
+ * an installed repository merely *missing* a dependency should keep the honest error. It reads well
+ * and behaves unpredictably: the walk reaches the filesystem root, so a checkout under any directory
+ * that happens to have a `node_modules` (a home directory, a nested clone) silently lost the
+ * fallback. A rule whose answer depends on where the repository was cloned is worse than the
+ * looser one.
+ *
+ * `from` exists for the specs, and is the whole test seam: the answer depends on where **this
+ * module** sits, so a spec running inside this repository could otherwise only ever prove that this
+ * repository can see its own `node_modules`. Given a throwaway layout's URL it exercises the real
+ * resolution - no subprocess, and nothing to keep in step with the source.
+ */
+export function resolveBesideRman(target, from = import.meta.url) {
+    try {
+        return createRequire(from).resolve(target);
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "1.2.1",
+  "version": "1.2.4",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {