rman 1.2.2 → 1.2.5

package/cli.js

@@ -27,9 +27,21 @@ import { filterPackages, readPackageFilterOptions, readRootOption } from './util
 import { printableConfig } from './utils/printable-config.js';
 import { runBin } from './utils/run-bin.js';
 export async function runCli(options) {
+    const _argv = options?.argv || hideBin(process.argv);
+    /**
+     * **Answered before the repository is touched**, because neither question is about a repository.
+     *
+     * `rman -v` is what you reach for when something is wrong - to find out which rman is even
+     * installed - and it was the one thing a broken repository took away: resolution happens during
+     * `Repository.create`, long before yargs sees the flag, so `rman -v` in a repository whose
+     * `.rmanrc` named a plugin it could not resolve answered with that error and exit 1. Measured.
+     */
+    if (_argv.some(arg => arg === '-v' || arg === '--version')) {
+        console.log(version);
+        return;
+    }
     try {
         const repository = await Repository.create(options?.cwd);
-        const _argv = options?.argv || hideBin(process.argv);
         const program = yargs(_argv)
             .scriptName('rman')
             .version(version)
@@ -156,6 +168,27 @@ export async function runCli(options) {
             await program.parseAsync();
     }
     catch (e) {
+        /**
+         * **`--help` still answers**, because a broken repository is the moment you most want it. The
+         * command list is the part that genuinely needs the repository - every built-in's `initCli`
+         * closes over it, and a plugin's commands *are* the repository's - so help degrades to the
+         * global options and says plainly why the rest is missing, rather than failing outright.
+         *
+         * The reason goes to stderr, so `rman --help | less` is still just help.
+         */
+        if (_argv.some(arg => arg === '-h' || arg === '--help')) {
+            console.error(colors.yellow(`Repository could not be read: ${e.message}`));
+            console.error(colors.yellow('Commands are not listed - they come from this repository and its plugins.\n'));
+            await yargs(_argv)
+                .scriptName('rman')
+                .version(version)
+                .alias('version', 'v')
+                .usage('$0 <cmd> [options...]')
+                .help('help')
+                .alias('help', 'h')
+                .showHelp(text => console.log(text));
+            return;
+        }
         /** Setup failures - no `package.json` to be found, a `.rman` command shadowing a built-in -
          *  used to be printed and then swallowed, so the shell saw success: `rman info` in the wrong
          *  directory reported failure on stdout and 0 to whatever called it. Printed once (unless the

package/constants.js

@@ -1 +1 @@
-export const version = '1.2.2';
+export const version = '1.2.5';

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_VALUES } from './merge-config.js';
+import { finalizeConfig, mergeConfig, ORIGINS, PREVIOUS_VALUES } from './merge-config.js';
 /**
  * Identity helper for authoring a `.rmanrc.cjs`/`.mjs`/`.js` config with full type-checking and
  * autocomplete - the same `defineConfig` pattern Vite/Vitest use. Returns `config` completely
@@ -71,7 +71,7 @@ export async function readDirConfig(dirname) {
             assertNoSelectorExtends(pkgJson.rman, pkgJsonFile);
             if (EXTENDS_KEY in pkgJson.rman)
                 extendsFrom = pkgJsonFile;
-            mergeConfig(result, pkgJson.rman);
+            mergeConfig(result, pkgJson.rman, pkgJsonFile);
         }
     }
     const ymlFile = path.join(dirname, '.rmanrc.yml');
@@ -81,7 +81,7 @@ export async function readDirConfig(dirname) {
             assertNoSelectorExtends(obj, ymlFile);
             if (EXTENDS_KEY in obj)
                 extendsFrom = ymlFile;
-            mergeConfig(result, obj);
+            mergeConfig(result, obj, ymlFile);
         }
     }
     const rcFile = path.join(dirname, '.rmanrc');
@@ -91,7 +91,7 @@ export async function readDirConfig(dirname) {
             assertNoSelectorExtends(obj, rcFile);
             if (EXTENDS_KEY in obj)
                 extendsFrom = rcFile;
-            mergeConfig(result, obj);
+            mergeConfig(result, obj, rcFile);
         }
     }
     for (const jsFileName of JS_CONFIG_FILES) {
@@ -102,7 +102,7 @@ export async function readDirConfig(dirname) {
                 assertNoSelectorExtends(obj, jsFile);
                 if (EXTENDS_KEY in obj)
                     extendsFrom = jsFile;
-                mergeConfig(result, obj);
+                mergeConfig(result, obj, jsFile);
             }
         }
     }
@@ -350,7 +350,8 @@ export function interpolateConfig(config, scope, options) {
         resolving.push(key);
         try {
             const chain = config[PREVIOUS_VALUES];
-            const value = walkWithPrevious(config[key], chain?.[key], scope, context, [...base, key], skip);
+            const origins = config[ORIGINS];
+            const value = withOrigin(origins?.[key], () => walkWithPrevious(config[key], chain?.[key], scope, context, [...base, key], skip));
             resolved.set(key, value);
             return value;
         }
@@ -526,8 +527,9 @@ function walk(value, scope, context, at, skip) {
         const chain = value[PREVIOUS_VALUES];
         return withScopedVars(value, scope, context, at, skip, () => {
             const result = {};
+            const origins = value[ORIGINS];
             for (const [key, item] of Object.entries(value)) {
-                result[key] = walkWithPrevious(item, chain?.[key], scope, context, [...at, key], skip);
+                result[key] = withOrigin(origins?.[key], () => walkWithPrevious(item, chain?.[key], scope, context, [...at, key], skip));
             }
             return result;
         });
@@ -612,6 +614,42 @@ 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';
+/**
+ * The file the key being walked was written in, for the errors below to name.
+ *
+ * A config is merged from several files before anything reads it - a directory's own forms, an
+ * `extends` base, every `"[selector]"` block, one layer per directory - so `version.commitMessage`
+ * alone does not say where to go and look. `mergeConfig` records the file per key (`ORIGINS`); this
+ * is the depth-first cursor over that, kept in a module variable rather than threaded through
+ * `walk`'s signature because every error site would otherwise have to carry a parameter it only
+ * passes on.
+ *
+ * Nested keys inherit the enclosing file when the merge recorded none of their own, which is what a
+ * nested object in one file means.
+ */
+let currentOrigin;
+function withOrigin(origin, body) {
+    const outer = currentOrigin;
+    if (origin !== undefined)
+        currentOrigin = origin;
+    try {
+        return body();
+    }
+    finally {
+        currentOrigin = outer;
+    }
+}
+/** `"version.commitMessage" (.rmanrc.yml)`, or just the path when nothing recorded a file - a
+ *  caller interpolating a fragment it built itself, say. Relative to the repository when it sits
+ *  inside one, since an absolute path is noise in a message about the repository you are in. */
+function describeAt(at) {
+    const where = at.length ? formatPath(at) : 'the config root';
+    return currentOrigin ? `${where}" (${shortenOrigin(currentOrigin)})` : `${where}"`;
+}
+function shortenOrigin(file) {
+    const relative = path.relative(process.cwd(), file);
+    return !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file;
+}
 /**
  * Walks one key of an object with **`value` bound** to whatever the layers below it resolved to.
  *
@@ -660,10 +698,9 @@ function walkWithPrevious(item, previous, scope, context, at, skip) {
          * 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}".` +
+                `${e.message}\n  \`value\` is undefined here - nothing below this layer sets "${describeAt(at)}.` +
                     `\n  Write \`value ?? []\` (or \`?? ''\`) if it has to work as the first layer too.`;
         }
         throw e;
@@ -733,10 +770,9 @@ function callValueFn(fn, context, at) {
         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 });
+        throw new Error(`Config function in "${describeAt(at)} failed: ${e?.message}`, { cause: e });
     }
 }
 function interpolateString(value, context, at) {
@@ -758,8 +794,7 @@ function interpolateString(value, context, at) {
          *  tag like `app:undefined` that looks plausible and is wrong - the exact silent-mistake shape
          *  this evaluator exists to avoid. `?? 'fallback'` says what was meant. */
         if (result === undefined || result === null) {
-            const where = at.length ? formatPath(at) : 'the config root';
-            throw new Error(`Expression in "${where}" is ${result} inside a string: ${value.trim()}\n` +
+            throw new Error(`Expression in "${describeAt(at)} is ${result} inside a string: ${value.trim()}\n` +
                 `  \${{${expr}}} has no value here - give it a fallback (\${{${expr.trim()} ?? '...'}}).`);
         }
         return String(result);
@@ -772,8 +807,7 @@ function evaluate(expr, source, context, at) {
         return vm.runInContext(expr, context, { timeout: EXPRESSION_TIMEOUT });
     }
     catch (e) {
-        const where = at.length ? formatPath(at) : 'the config root';
-        throw new Error(`Invalid expression in "${where}": ${source.trim()}\n  ${e?.message ?? e}`, { cause: e });
+        throw new Error(`Invalid expression in "${describeAt(at)}: ${source.trim()}\n  ${e?.message ?? e}`, { cause: e });
     }
 }
 function formatPath(at) {

package/core/extends-config.js

@@ -42,7 +42,7 @@ export async function resolveExtends(config, from, seen = []) {
         const loaded = await loadConfigFile(file);
         assertNoSelectorExtends(loaded, file);
         // Recursive: a shared config may itself be built on another.
-        mergeConfig(base, await resolveExtends(loaded, file, [...seen, file]));
+        mergeConfig(base, await resolveExtends(loaded, file, [...seen, file]), file);
     }
     const own = { ...config };
     delete own[EXTENDS_KEY];

package/core/merge-config.d.ts

@@ -31,6 +31,19 @@ export declare const ALWAYS_APPEND: readonly string[];
  * `A <- expr2 <- expr3`, and one slot would have lost `A` the moment `expr3` arrived.
  */
 export declare const PREVIOUS_VALUES: unique symbol;
+/**
+ * Which file each key came from, so an error can name it.
+ *
+ * A config is merged from several files before anything reads it - a directory's own four forms, an
+ * `extends` base, every `"[selector]"` block, and one layer per directory from the root down - so by
+ * the time an expression fails, `version.commitMessage` could have been written in any of them.
+ * Saying only the key sends the reader looking through all of them.
+ *
+ * Recorded the same way `PREVIOUS_VALUES` is, for the same reason: a symbol on the containing
+ * object, invisible to `Object.entries`, `JSON.stringify` and js-yaml, so it travels with the config
+ * without any reader having to know it is there.
+ */
+export declare const ORIGINS: unique symbol;
 /** One link: the raw value this key held, and whatever *it* was derived from. */
 export interface PreviousValue {
     value: unknown;
@@ -69,7 +82,10 @@ export declare function appendTarget(key: string): string | undefined;
  * `key` and `+key` in the same object are both honored, in that order: the replacement happens
  * first, then the append lands on top of it.
  */
-export declare function mergeConfig(target: Record<string, any>, source: Record<string, any>): Record<string, any>;
+export declare function mergeConfig(target: Record<string, any>, source: Record<string, any>, 
+/** The file `source` was read from, recorded per key - see `ORIGINS`. A caller merging a value it
+ *  built rather than read (a selector block already carrying its own origins) passes nothing. */
+origin?: string): Record<string, any>;
 /**
  * Turns any `+key` still outstanding into its plain key, as a list - the "nothing was inherited"
  * case, where an append simply is the whole value.

package/core/merge-config.js

@@ -31,6 +31,19 @@ export const ALWAYS_APPEND = ['plugins'];
  * `A <- expr2 <- expr3`, and one slot would have lost `A` the moment `expr3` arrived.
  */
 export const PREVIOUS_VALUES = Symbol('rman.previousValues');
+/**
+ * Which file each key came from, so an error can name it.
+ *
+ * A config is merged from several files before anything reads it - a directory's own four forms, an
+ * `extends` base, every `"[selector]"` block, and one layer per directory from the root down - so by
+ * the time an expression fails, `version.commitMessage` could have been written in any of them.
+ * Saying only the key sends the reader looking through all of them.
+ *
+ * Recorded the same way `PREVIOUS_VALUES` is, for the same reason: a symbol on the containing
+ * object, invisible to `Object.entries`, `JSON.stringify` and js-yaml, so it travels with the config
+ * without any reader having to know it is there.
+ */
+export const ORIGINS = Symbol('rman.origins');
 /** 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('${{'));
@@ -70,7 +83,10 @@ export function appendTarget(key) {
  * `key` and `+key` in the same object are both honored, in that order: the replacement happens
  * first, then the append lands on top of it.
  */
-export function mergeConfig(target, source) {
+export function mergeConfig(target, source, 
+/** The file `source` was read from, recorded per key - see `ORIGINS`. A caller merging a value it
+ *  built rather than read (a selector block already carrying its own origins) passes nothing. */
+origin) {
     // Plain keys first, so a `+key` alongside its own `key` appends to that replacement rather than
     // to whatever the previous layer had.
     for (const [key, value] of Object.entries(source)) {
@@ -81,7 +97,7 @@ export function mergeConfig(target, source) {
             appendList(target, key, value);
             continue;
         }
-        assignMerged(target, key, value);
+        assignMerged(target, key, value, source, origin);
     }
     for (const [key, value] of Object.entries(source)) {
         const plain = appendTarget(key);
@@ -90,7 +106,7 @@ export function mergeConfig(target, source) {
         // An object merges either way, so the prefix asks for nothing extra - resolve it now and let
         // the two spellings coincide.
         if (isPlainObject(value) || isPlainObject(target[plain])) {
-            assignMerged(target, plain, value);
+            assignMerged(target, plain, value, source, origin);
             continue;
         }
         if (plain in target) {
@@ -131,16 +147,30 @@ export function finalizeConfig(config) {
     }
     /** 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 });
+    for (const carried of [PREVIOUS_VALUES, ORIGINS]) {
+        const value = config[carried];
+        if (value)
+            Object.defineProperty(result, carried, { value });
+    }
     return result;
 }
-function assignMerged(target, key, value) {
+function assignMerged(target, key, value, source, origin) {
+    /** A source that already carries origins wins over the caller's: an `extends` base keeps the file
+     *  its own keys were written in, rather than being attributed to the file that named it. */
+    const from = source[ORIGINS]?.[key] ?? origin;
+    if (from !== undefined) {
+        const carrier = target;
+        /** **Non-enumerable**, like `PREVIOUS_VALUES`: `expect`'s `toEqual` compares symbol properties,
+         *  so a plain assignment turned every config-shape assertion in the suite into a diff about
+         *  bookkeeping (measured, five specs at once). Nothing should see this but the error messages. */
+        if (!carrier[ORIGINS])
+            Object.defineProperty(target, ORIGINS, { value: {}, writable: true });
+        carrier[ORIGINS][key] = from;
+    }
     if (isPlainObject(value)) {
         if (!isPlainObject(target[key]))
             target[key] = {};
-        mergeConfig(target[key], value);
+        mergeConfig(target[key], value, from);
         return;
     }
     /**

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.2",
+  "version": "1.2.5",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {