rman 1.2.4 → 1.3.0

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.4';
+export const version = '1.3.0';

package/core/config.d.ts

@@ -27,52 +27,61 @@ export declare function readDirConfig(dirname: string): Promise<RmanConfig>;
  * it (inclusive) - each directory level overrides the ones above it, the way tsconfig's `extends`
  * chain does.
  *
- * Every level contributes in two ways, and the difference is the whole model:
- *
- * - **Unmarked keys configure the package of the directory that declares them.** The root's own
- *   `.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 (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
- * its own directory; on the root it's a repo-wide bookend run once at the repository root. A
- * cascade that fed one declaration to both ran a package-relative command (`node
- * ../../support/postbuild.cjs`) at the root, where it cannot resolve.
+ * Every level contributes in two ways:
+ *
+ * - **An unmarked key configures that directory and every package under it.** What a parent says
+ *   reaches the children, which is what every directory-scoped config in the ecosystem does and
+ *   what a reader expects without being told.
+ * - **A `"[selector]"` block narrows the audience** - `"[/]"` to the root package alone, `"[*]"` or
+ *   a glob to the packages below (never the root, which is nobody's child). See `parseSelector`.
+ *
+ * **The root used to be the one directory whose unmarked config did *not* cascade**, on the
+ * reasoning that a setting means different things to a package and to the repository - and the
+ * reasoning is sound, but the rule it produced was not readable: an intermediate `packages/`
+ * cascaded while the root did not, so what a file meant depended on whether a `package.json` sat
+ * beside it. `vars` then had to be carved out as an exception, which is what a rule fighting itself
+ * looks like. One sentence now covers both: what is written above reaches below, and `"[/]"` is how
+ * a statement stays at the root.
+ *
+ * **The cost is real and lands on one subtree.** `run.<script>`'s hooks on the root are a repo-wide
+ * bookend, run once at the repository root; on a package they are that package's own hook, run in
+ * its directory. Cascaded, one declaration is both - once at the root and once per package. A
+ * repo-wide bookend therefore belongs under `"[/]"`, where its audience is visible; that is the
+ * migration this change asks for, and the only one that is not mechanical.
  *
  * `packageName` is what selectors match against; without it, selector blocks contribute nothing at
- * all. The root package passes its own, since `"[/]"` and `"[*]"` speak to it.
+ * all. The root package passes its own, since `"[/]"` speaks to it.
  */
 export declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, RmanConfig>, packageName?: string): Promise<RmanConfig>;
-/** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[ws:*]"`, `"[pkg-a]"`. The
+/** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[pkg-a]"`. The
  *  brackets are what keep this space from colliding with real config keys - no setting starts with
  *  one - and in YAML they also mean the key always needs quoting (`"[*]":`), since a bare `[*]`
  *  parses as a flow sequence. */
 export declare function isSelectorKey(key: string): boolean;
 /**
- * **Which packages a selector speaks for.** Three audiences, because a repository has three:
+ * **Which packages a selector speaks for.** Two audiences, and the second is a glob:
  *
  * | | |
  * | --- | --- |
- * | `"[/]"` | the **root package** only |
- * | `"[*]"`, `"[pkg-a]"`, `"[*-dialect]"` | **every** package the glob matches, root included |
- * | `"[ws:*]"`, `"[workspace:pkg-*]"` | every **non-root** package the glob matches |
+ * | `"[/]"` | the **root package** alone |
+ * | `"[*]"`, `"[pkg-a]"`, `"[*-dialect]"` | the packages **below** this directory that the glob matches |
  *
  * `/` for the root because that is what a repository root is called everywhere else, and it cannot
- * collide with a package name. `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.
+ * collide with a package name.
+ *
+ * **The root is never selected by name, and that one rule removes two traps.** A glob matches
+ * package names, and the root is nobody's child - so `"[my-*]"` cannot quietly pick up a repository
+ * whose root package happens to be called `my-repo`, and `"[*]"` cannot hand a package-shaped
+ * setting to a root that has no build directory to apply it to. The root is addressed structurally
+ * or not at all.
+ *
+ * **`"[ws:*]"` / `"[workspace:*]"` is accepted and means exactly `"[*]"`.** The qualifier existed to
+ * say "not the root" back when a bare glob included it; the shape of the set says that now, so it
+ * has nothing left to add. Accepted rather than rejected because the two spellings resolve to the
+ * same packages - an error would be friction with no reader to protect.
  */
 export declare function parseSelector(key: string): {
-    scope: 'root' | 'all' | 'workspace';
+    scope: 'root' | 'package';
     test: (name: string) => boolean;
 };
 /** The glob inside a selector key, as a `RegExp` anchored at both ends - so `"[*-dialect]"` matches
@@ -330,7 +339,7 @@ export declare const DEFERRED_PATHS: string[];
  * 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`
  * }

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);
             }
         }
     }
@@ -117,32 +117,37 @@ export async function readDirConfig(dirname) {
  * it (inclusive) - each directory level overrides the ones above it, the way tsconfig's `extends`
  * chain does.
  *
- * Every level contributes in two ways, and the difference is the whole model:
+ * Every level contributes in two ways:
  *
- * - **Unmarked keys configure the package of the directory that declares them.** The root's own
- *   `.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 (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.
+ * - **An unmarked key configures that directory and every package under it.** What a parent says
+ *   reaches the children, which is what every directory-scoped config in the ecosystem does and
+ *   what a reader expects without being told.
+ * - **A `"[selector]"` block narrows the audience** - `"[/]"` to the root package alone, `"[*]"` or
+ *   a glob to the packages below (never the root, which is nobody's child). See `parseSelector`.
  *
- * 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
- * its own directory; on the root it's a repo-wide bookend run once at the repository root. A
- * cascade that fed one declaration to both ran a package-relative command (`node
- * ../../support/postbuild.cjs`) at the root, where it cannot resolve.
+ * **The root used to be the one directory whose unmarked config did *not* cascade**, on the
+ * reasoning that a setting means different things to a package and to the repository - and the
+ * reasoning is sound, but the rule it produced was not readable: an intermediate `packages/`
+ * cascaded while the root did not, so what a file meant depended on whether a `package.json` sat
+ * beside it. `vars` then had to be carved out as an exception, which is what a rule fighting itself
+ * looks like. One sentence now covers both: what is written above reaches below, and `"[/]"` is how
+ * a statement stays at the root.
+ *
+ * **The cost is real and lands on one subtree.** `run.<script>`'s hooks on the root are a repo-wide
+ * bookend, run once at the repository root; on a package they are that package's own hook, run in
+ * its directory. Cascaded, one declaration is both - once at the root and once per package. A
+ * repo-wide bookend therefore belongs under `"[/]"`, where its audience is visible; that is the
+ * migration this change asks for, and the only one that is not mechanical.
  *
  * `packageName` is what selectors match against; without it, selector blocks contribute nothing at
- * all. The root package passes its own, since `"[/]"` and `"[*]"` speak to it.
+ * all. The root package passes its own, since `"[/]"` speaks to it.
  */
 export async function resolveConfig(rootDir, targetDir, cache = new Map(), packageName) {
     const result = {};
     const target = path.resolve(targetDir);
     /** The root *package* is the one whose directory is the repository root - no other test is
      *  needed, and none would be as reliable: a name can be anything. In a single-package repository
-     *  that is the only package, so `"[/]"` reaches it and `"[ws:*]"` reaches nothing. */
+     *  that is the only package, so `"[/]"` reaches it and `"[*]"` reaches nothing. */
     const isRoot = target === path.resolve(rootDir);
     for (const dir of dirChain(rootDir, targetDir)) {
         let local = cache.get(dir);
@@ -150,39 +155,30 @@ export async function resolveConfig(rootDir, targetDir, cache = new Map(), packa
             local = await readDirConfig(dir);
             cache.set(dir, local);
         }
-        // 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'));
-        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.
+         * **Unmarked first, because it is the widest thing this level says** - and that is an inversion
+         * of the order this loop used to run in, where a directory's own plain config beat a selector
+         * declared beside it. Under the old reading "unmarked" meant *this package* and so was the
+         * narrower of the two; it now means *this package and everything below*, which is the wider.
+         * Precedence follows the audience, not the spelling, so it had to move.
          *
-         * Merged *before* this directory's selector blocks, so `"[*]": {vars: ...}` - which names the
-         * packages explicitly - overrides the same directory's plainer statement.
+         * Its position in the file is deliberately not consulted: a selector block written above the
+         * plain keys still wins. Unmarked is not a fourth selector - it is the level's floor, and the
+         * layer that feeds the directories below it.
          */
-        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".
+        mergeConfig(result, stripSelectors(local));
+        /** Then the selector blocks, **in the order they were written** - see `matchingSelectors`. */
         if (packageName) {
             for (const block of matchingSelectors(local, packageName, isRoot))
                 mergeConfig(result, block);
         }
-        if (speaksForTarget)
-            mergeConfig(result, stripSelectors(local));
     }
     /** 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: `"[*]"`, `"[/]"`, `"[ws:*]"`, `"[pkg-a]"`. The
+/** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[pkg-a]"`. The
  *  brackets are what keep this space from colliding with real config keys - no setting starts with
  *  one - and in YAML they also mean the key always needs quoting (`"[*]":`), since a bare `[*]`
  *  parses as a flow sequence. */
@@ -190,50 +186,55 @@ 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:
+ * **Which packages a selector speaks for.** Two audiences, and the second is a glob:
  *
  * | | |
  * | --- | --- |
- * | `"[/]"` | the **root package** only |
- * | `"[*]"`, `"[pkg-a]"`, `"[*-dialect]"` | **every** package the glob matches, root included |
- * | `"[ws:*]"`, `"[workspace:pkg-*]"` | every **non-root** package the glob matches |
+ * | `"[/]"` | the **root package** alone |
+ * | `"[*]"`, `"[pkg-a]"`, `"[*-dialect]"` | the packages **below** this directory that the glob matches |
  *
  * `/` for the root because that is what a repository root is called everywhere else, and it cannot
- * collide with a package name. `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.
+ * collide with a package name.
+ *
+ * **The root is never selected by name, and that one rule removes two traps.** A glob matches
+ * package names, and the root is nobody's child - so `"[my-*]"` cannot quietly pick up a repository
+ * whose root package happens to be called `my-repo`, and `"[*]"` cannot hand a package-shaped
+ * setting to a root that has no build directory to apply it to. The root is addressed structurally
+ * or not at all.
+ *
+ * **`"[ws:*]"` / `"[workspace:*]"` is accepted and means exactly `"[*]"`.** The qualifier existed to
+ * say "not the root" back when a bare glob included it; the shape of the set says that now, so it
+ * has nothing left to add. Accepted rather than rejected because the two spellings resolve to the
+ * same packages - an error would be friction with no reader to protect.
  */
 export function parseSelector(key) {
     const inner = key.slice(1, -1);
     if (inner === ROOT_SELECTOR_INNER)
         return { scope: 'root', test: () => true };
-    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) };
+    const re = globToRegExp(stripWorkspacePrefix(inner));
+    return { scope: 'package', test: name => re.test(name) };
 }
 /** The glob inside a selector key, as a `RegExp` anchored at both ends - so `"[*-dialect]"` matches
  *  `mysql-dialect` but not `my-dialect-helper`. Glob rather than regex, to match every other
  *  pattern in rman (`allowBranch`, `changelog.tagPattern`, `clean.include`). */
 export function selectorToRegExp(key) {
-    return globToRegExp(key.slice(1, -1));
+    return globToRegExp(stripWorkspacePrefix(key.slice(1, -1)));
 }
 /**
- * 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.
+ * Every selector block in `config` that speaks for this package, **in the order they were written**
+ * - later wins, the way `overrides` works in eslint, prettier and babel, and the way a `.gitignore`
+ * rule does.
+ *
+ * **There used to be a ranking** (`"[*]"` lowest, then a catch-all `"[ws:*]"`, then the rest by
+ * declaration), so that "everything" could not beat a rule about one package by being written last.
+ * It was dropped because the ordering it implies does not exist: specificity only ranks sets that
+ * nest, and globs do not. For a package called `pkg-dialect`, neither `"[pkg-*]"` nor
+ * `"[*-dialect]"` contains the other, so any answer is an invented tiebreak - and an invented
+ * tiebreak is worse than the order the author typed. What was left was already declaration order
+ * with one case lifted out of it; this removes the exception rather than generalizing it.
+ *
+ * The cost, which the docs state rather than hide: a catch-all written *below* a narrower block now
+ * overrides it. Writing catch-alls first is a convention, not a rule - the file reads top to bottom.
  */
 function matchingSelectors(config, packageName, isRoot) {
     const matches = [];
@@ -241,23 +242,19 @@ function matchingSelectors(config, packageName, isRoot) {
         if (!isSelectorKey(key) || !value || typeof value !== 'object')
             continue;
         const { scope, test } = parseSelector(key);
-        if (scope === 'root' && !isRoot)
+        if (scope === 'root' ? !isRoot : isRoot || !test(packageName))
             continue;
-        if (scope === 'workspace' && isRoot)
-            continue;
-        if (!test(packageName))
-            continue;
-        matches.push([selectorRank(key), value]);
+        matches.push(value);
     }
-    return matches.sort((a, b) => a[0] - b[0]).map(([, block]) => block);
+    return matches;
 }
-/** 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;
+/** `"[ws:*]"` and `"[workspace:*]"` are the pre-2.x spelling of "not the root", kept working
+ *  because they now name the same set a bare glob does. Stripped here so one code path serves both. */
+function stripWorkspacePrefix(inner) {
+    for (const prefix of WORKSPACE_PREFIXES)
+        if (inner.startsWith(prefix))
+            return inner.slice(prefix.length);
+    return inner;
 }
 function globToRegExp(glob) {
     const source = glob
@@ -273,12 +270,10 @@ function stripSelectors(config) {
             result[key] = value;
     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. */
+/** Accepted spellings of the retired "not the root" qualifier - see `stripWorkspacePrefix`. */
 const WORKSPACE_PREFIXES = ['workspace:', 'ws:'];
 function dirChain(rootDir, targetDir) {
     const rel = path.relative(rootDir, targetDir);
@@ -350,7 +345,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;
         }
@@ -398,7 +394,7 @@ export const DEFERRED_PATHS = ['version.before', 'version.exec', 'version.after'
  * 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`
  * }
@@ -526,8 +522,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 +609,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 +693,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 +765,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 +789,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 +802,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;
     }
     /**
@@ -148,7 +178,7 @@ function assignMerged(target, key, value) {
      *
      * ```js
      * '[*]':    { clean: { include: ({ vars }) => [vars.buildDir] } }
-     * '[ws:*]': { clean: { include: "${{ [...value, pkg.basename + '.log'] }}" } }
+     * '[*]': { clean: { include: "${{ [...value, pkg.basename + '.log'] }}" } }
      * ```
      *
      * Chained here rather than at resolution time because only the merge knows the order of the

package/core/repository.js

@@ -208,9 +208,10 @@ export class Repository extends Package {
          * second `rawConfig` copy of every package's config for that one reader; measured identical.
          */
         /**
-         * The root is resolved **with its name**, like every other package, because selectors now speak
-         * to it: `"[/]"` names it and `"[*]"` includes it. It used to be resolved without one, which is
-         * what made `"[*]"` quietly mean "the workspace packages" - `"[ws:*]"` is that, spelled.
+         * The root is resolved **with its name**, like every other package. Not because a glob could
+         * match it - `"[*]"` and every other name pattern speak only to the packages below - but because
+         * `resolveConfig` needs a name to run `matchingSelectors` at all, and `"[/]"` is a selector.
+         * Passing none would silently drop the root's own block.
          */
         const rootRaw = await resolveConfig(this.dirname, this.dirname, cache, this.rootPackage.name);
         this.config = interpolateConfig(rootRaw, this.configScope(this.rootPackage), { skip: DEFERRED_PATHS });

package/interfaces/rman-config.interface.d.ts

@@ -166,17 +166,21 @@ export interface RmanConfigKeys {
      */
     dependencies?: string[];
     /**
-     * Config for **other** packages, keyed by a `"[selector]"` naming them - `"[*]"` for every
-     * package in the repository, `"[*-dialect]"` for a glob over package names, `"[pkg-a]"` for one.
-     * Everything else in this object configures the package of the directory declaring it, so this
-     * is the only way a `.rmanrc` speaks about anything but its own package - most usefully the
-     * repository root's, which otherwise configures the root package alone.
+     * Config for a **narrower audience**, keyed by a `"[selector]"` naming it - `"[/]"` for the root
+     * package alone, `"[*]"` for the packages below this directory, `"[*-dialect]"` for a glob over
+     * their names, `"[pkg-a]"` for one. Everything else in this object reaches this directory *and*
+     * every package under it, so a selector is how a statement stops being everyone's.
+     *
+     * A glob never matches the root, which is nobody's child - so a package-shaped setting cannot
+     * reach a root that has no package directory to apply it to, and `"[/]"` is the only way to
+     * address the root.
      *
      * ```yaml
      * # the repository root's own .rmanrc.yml
-     * run:
-     *   build:
-     *     before: node support/generate.cjs   # a repo-wide bookend, run once at the root
+     * "[/]":
+     *   run:
+     *     build:
+     *       before: node support/generate.cjs   # a repo-wide bookend, run once at the root
      * "[*]":
      *   run:
      *     build:
@@ -184,8 +188,8 @@ export interface RmanConfigKeys {
      * ```
      *
      * In YAML the quotes are **required**: a bare `[*]` parses as a flow sequence, and `*` as an
-     * alias indicator. Precedence, lowest first: `"[*]"`, then other selectors in declaration order,
-     * then the package's own unmarked config.
+     * alias indicator. Precedence: the unmarked keys first, then these blocks **in the order they
+     * were written** - later wins. A directory level closer to the package wins over all of them.
      *
      * Recursive, mirroring the schema's own `"$ref": "#"`: whatever a `.rmanrc` may say about its own
      * package it may say here about the ones it names - nested selectors included. Typed as

package/package.json

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