rman 1.2.5 → 2.0.0-beta.2

package/core/config.js

@@ -2,13 +2,13 @@ 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 semver from 'semver';
-import { pathToFileURL } from 'url';
 import vm from 'vm';
-import { assertNoSelectorExtends, EXTENDS_KEY, resolveExtends } from './extends-config.js';
-import { finalizeConfig, mergeConfig, ORIGINS, PREVIOUS_VALUES } from './merge-config.js';
+import { DETECTED_BUILTIN } from '../plugins/detect.js';
+import { assertSelectorBlocks, EXTENDS_KEY, resolveExtends } from './extends-config.js';
+import { loadConfigModule } from './load-config-module.js';
+import { 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
@@ -31,35 +31,18 @@ export function defineConfig(config) {
  *  or a `.js` under a `"type": "commonjs"` package.json) and native ESM (`.mjs`, or a `.js` under
  *  `"type": "module"`) are supported - the reason `readDirConfig`/`resolveConfig` are async at all. */
 const JS_CONFIG_FILES = ['.rmanrc.cjs', '.rmanrc.mjs', '.rmanrc.js'];
-const requireJsConfig = createRequire(import.meta.url);
-/**
- * Loads `file`'s config object. Tries `require()` first - not just an optimization: a CommonJS
- * module's `module.exports` is more reliably observed this way than through dynamic `import()`'s
- * CJS-interop synthesis, which some ESM loader hooks (e.g. ts-node/swc-node-style transpilers
- * registered via `--import`) can end up short-circuiting into an empty object. `require()` throws
- * `ERR_REQUIRE_ESM` for a genuinely-ESM file (`.mjs`, or `.js` under `"type": "module"`) - only
- * then does this fall back to `import()`, the one case that actually needs it. Either path can
- * hand back an ES module namespace instead of a plain object (Node's `require(esm)` support does
- * this too, not just `import()`), so `.default` is preferred whenever present.
- */
-async function loadJsConfig(file) {
-    let mod;
-    try {
-        mod = requireJsConfig(file);
-    }
-    catch (e) {
-        if (e?.code !== 'ERR_REQUIRE_ESM')
-            throw e;
-        mod = await import(pathToFileURL(file).href);
-    }
-    return mod?.default ?? mod;
-}
 /**
  * Reads the rman configuration defined at a single directory level, merging
  * (in increasing precedence): `package.json#rman`, `.rmanrc.yml`, `.rmanrc`,
  * then `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js` (whichever exist, in that order).
+ *
+ * `options.inject` supplies a built-in for a repository that declared no technology - **already
+ * decided**, rather than a "please detect" flag. The decision needs the application (a programmatic
+ * caller or a spec may have registered a technology without writing it in a config), which this
+ * function has no business knowing about; `Repository.create` makes it once and hands the answer
+ * to every read that has to agree with it. See `detectBuiltin`.
  */
-export async function readDirConfig(dirname) {
+export async function readDirConfig(dirname, options) {
     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. */
@@ -68,7 +51,7 @@ export async function readDirConfig(dirname) {
     if (fs.existsSync(pkgJsonFile)) {
         const pkgJson = JSON.parse(fs.readFileSync(pkgJsonFile, 'utf-8'));
         if (pkgJson && typeof pkgJson.rman === 'object') {
-            assertNoSelectorExtends(pkgJson.rman, pkgJsonFile);
+            assertSelectorBlocks(pkgJson.rman, pkgJsonFile);
             if (EXTENDS_KEY in pkgJson.rman)
                 extendsFrom = pkgJsonFile;
             mergeConfig(result, pkgJson.rman, pkgJsonFile);
@@ -78,7 +61,7 @@ export async function readDirConfig(dirname) {
     if (fs.existsSync(ymlFile)) {
         const obj = yaml.load(fs.readFileSync(ymlFile, 'utf-8'));
         if (obj && typeof obj === 'object') {
-            assertNoSelectorExtends(obj, ymlFile);
+            assertSelectorBlocks(obj, ymlFile);
             if (EXTENDS_KEY in obj)
                 extendsFrom = ymlFile;
             mergeConfig(result, obj, ymlFile);
@@ -88,7 +71,7 @@ export async function readDirConfig(dirname) {
     if (fs.existsSync(rcFile)) {
         const obj = JSON.parse(fs.readFileSync(rcFile, 'utf-8'));
         if (obj && typeof obj === 'object') {
-            assertNoSelectorExtends(obj, rcFile);
+            assertSelectorBlocks(obj, rcFile);
             if (EXTENDS_KEY in obj)
                 extendsFrom = rcFile;
             mergeConfig(result, obj, rcFile);
@@ -97,9 +80,9 @@ export async function readDirConfig(dirname) {
     for (const jsFileName of JS_CONFIG_FILES) {
         const jsFile = path.join(dirname, jsFileName);
         if (fs.existsSync(jsFile)) {
-            const obj = await loadJsConfig(jsFile);
+            const obj = await loadConfigModule(jsFile);
             if (obj && typeof obj === 'object') {
-                assertNoSelectorExtends(obj, jsFile);
+                assertSelectorBlocks(obj, jsFile);
                 if (EXTENDS_KEY in obj)
                     extendsFrom = jsFile;
                 mergeConfig(result, obj, jsFile);
@@ -110,79 +93,192 @@ export async function readDirConfig(dirname) {
      *  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);
+    const resolved = await resolveExtends(result, extendsFrom);
+    /**
+     * **After `extends`, because a base may be what declares the technology** - a shared config
+     * naming `plugins` is a statement, and detecting on top of it would be guessing over an answer.
+     * `plugins` being *present* is what counts, so `plugins: []` is a repository saying "none".
+     */
+    const detected = options?.inject && resolved.plugins === undefined ? options.inject : undefined;
+    if (detected)
+        resolved.plugins = [detected.name];
+    const expanded = await expandBuiltinPlugins(resolved);
+    /**
+     * **Marked after the expansion, not before, because the expansion rebuilds the object.**
+     * `expandBuiltinPlugins` merges the built-in's config underneath and returns a *new* config, so a
+     * symbol set on the way in is simply gone on the way out - measured: detection worked and the
+     * "detected" line never printed. The same trap `PREVIOUS_VALUES` and `ORIGINS` document from the
+     * other side, where `mergeConfig` has to copy them across by hand.
+     */
+    if (detected) {
+        Object.defineProperty(expanded, DETECTED_BUILTIN, { value: detected, enumerable: false, configurable: true });
+    }
+    return expanded;
+}
+/**
+ * Turns a built-in **name** in `plugins` into what that built-in contributes - `['node']` into the
+ * node plugin, its two commands and its publish target.
+ *
+ * **Here, beside `extends`, because it is the same operation**: something named brings a config,
+ * and that config sits *underneath* the one naming it. Doing it anywhere later would not reach far
+ * enough - `commands` is read off the resolved root package by `cli.ts`, not off the raw config
+ * `Repository.create` hands to `loadPlugins`, so a built-in expanded only there would register its
+ * technology and silently lose its commands.
+ *
+ * **The name is consumed.** `plugins` always appends, so leaving the string beside the instance it
+ * expanded into would hand `loadPlugins` a glob that matches no file - the built-in would load and
+ * then the run would fail saying it did not.
+ *
+ * Runs per directory, like `extends`, but only the root's `plugins` is ever read (`loadPlugins`
+ * needs the technologies before any package exists). The cost of walking a key that is almost
+ * always absent is one `Array.isArray`.
+ */
+async function expandBuiltinPlugins(config) {
+    const declared = config.plugins;
+    const own = Array.isArray(declared) ? declared : declared === undefined ? [] : [declared];
+    const platform = declaredPlatform(config);
+    if (!own.some(e => typeof e === 'string') && platform === undefined)
+        return config;
+    /**
+     * **Imported here rather than at the top, and that is a cycle rather than a style.** A built-in
+     * pulls in its commands and services, which read config - so a static import would have
+     * `config.ts` and the plugin subtree initialising each other, which in ESM half-works and fails
+     * silently. Node caches the module, so the cost is one resolution on a config that names one.
+     */
+    const { BUILTIN_PLUGINS, isBuiltinPlugin } = await import('../plugins/builtins.js');
+    /**
+     * **A `platform` naming a built-in puts it at the front of `plugins`.**
+     *
+     * Saying which technology this repository is *is* saying it has it, so making the author write
+     * both was a distinction only rman could see. Measured on the repository this was noticed in:
+     * `platform: 'node'` alone gave a working `rman list` with a `node` column and
+     * `Unknown arguments: clean`, because the technology had loaded and its commands had not.
+     *
+     * **At the front, not the back**, and that is what makes it a statement rather than an addition:
+     * `platformFor` takes the first registered platform that recognizes a directory, so the one this
+     * repository says it *is* should win over anything a shared config brought along.
+     *
+     * **Only a built-in**, checked after the import above for exactly this reason: a `platform` naming
+     * a third-party technology is answered by the `plugins` entry that loads it, and pushing the bare
+     * name in here would hand `loadPlugins` a glob matching no file - the failure would read as the
+     * plugin being missing when it is registered perfectly well.
+     *
+     * Already named, and nothing happens: `plugins` de-duplicates, and this keeps the author's own
+     * ordering rather than promoting an entry they placed deliberately.
+     */
+    const entries = platform !== undefined && isBuiltinPlugin(platform) && !own.includes(platform) ? [platform, ...own] : own;
+    const named = entries.filter((e) => typeof e === 'string' && isBuiltinPlugin(e));
+    if (!named.length)
+        return config;
+    const base = {};
+    /** De-duplicated first: two layers naming the same built-in is ordinary (a shared config and the
+     *  repository that inherits it), and registering a plugin twice defines its commands twice. */
+    for (const name of [...new Set(named)])
+        mergeConfig(base, BUILTIN_PLUGINS[name].contribute());
+    const result = { ...config };
+    result.plugins = entries.filter(e => !(typeof e === 'string' && isBuiltinPlugin(e)));
+    return mergeConfig(base, result);
+}
+/**
+ * The **root's** declared platform, however it was spelled - unmarked, or inside a `"[/]"` block.
+ *
+ * Both, because both are the root saying what it is and a reader would not expect one to bring the
+ * built-in and the other not. `"[/]"` is the precise spelling (it speaks for the root package
+ * alone, where an unmarked key also cascades to every package below), so leaving it out would have
+ * punished the more careful author.
+ *
+ * A glob block is not consulted and cannot be: `assertSelectorBlocks` refuses `platform` there,
+ * since the glob matches a selector the key is upstream of.
+ */
+function declaredPlatform(config) {
+    const root = config[`[${ROOT_SELECTOR_INNER}]`];
+    const declared = config.platform ?? (root && typeof root === 'object' ? root.platform : undefined);
+    return typeof declared === 'string' && declared.trim() ? declared.trim() : undefined;
 }
 /**
  * Resolves the effective config for the package at `targetDir`, cascading from `rootDir` down to
  * 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.
- *
- * `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.
+ * 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.
+ *
+ * **`selector` is what a `"[glob]"` block matches** - `Package.selector`, which is the package's
+ * `.rmanrc "name"` if it declares one and its platform's answer otherwise. Without it, glob blocks
+ * contribute nothing: the walk resolves config for a directory *before* the package exists, since
+ * that is where `platform` and `name` are read from, and a glob has nothing to match against yet.
+ *
+ * **`"[/]"` needs no selector, and that is the documented rule rather than an exception.** The root
+ * is addressed structurally - its directory *is* the repository root - which is the whole reason it
+ * is `/` and not a name. So a root block applies whenever the target is the root, named or not, and
+ * `platform` under `"[/]"` therefore works during the walk. It did not until this was noticed: the
+ * gate was `if (packageName)`, so the walk skipped every selector block including that one, and the
+ * key documented as "keeps it on the root package alone" silently did nothing.
+ *
+ * It was called `packageName`, which was wrong twice over: a package is not guaranteed to have a
+ * name (that is an ecosystem's promise, not rman's), and what this matches is the selector, which a
+ * repository can assign itself.
  */
-export async function resolveConfig(rootDir, targetDir, cache = new Map(), packageName) {
+export async function resolveConfig(rootDir, targetDir, cache = new Map(), selector, 
+/** The built-in `Repository.create` decided on, for a repository that declared no technology.
+ *  Applied at the **root level only** - `plugins` is read nowhere else, and this is the read whose
+ *  result becomes `pkg.config`, which is where `cli.ts` finds a built-in's `commands`. */
+inject) {
     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);
         if (!local) {
-            local = await readDirConfig(dir);
+            local = await readDirConfig(dir, {
+                inject: path.resolve(dir) === path.resolve(rootDir) ? inject : undefined,
+            });
             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".
-        if (packageName) {
-            for (const block of matchingSelectors(local, packageName, isRoot))
+        mergeConfig(result, stripSelectors(local));
+        /** Then the selector blocks, **in the order they were written** - see `matchingSelectors`.
+         *  Reached for the root even with no selector, since `"[/]"` is structural. */
+        if (selector !== undefined || isRoot) {
+            for (const block of matchingSelectors(local, selector, 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);
+    return 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,74 +286,77 @@ 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.
+ * collide with a package name.
  *
- * **`"[*]"` 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.
+ * **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.
+ * 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.
  *
- * 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.
+ * 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) {
+function matchingSelectors(config, selector, isRoot) {
     const matches = [];
     for (const [key, value] of Object.entries(config)) {
         if (!isSelectorKey(key) || !value || typeof value !== 'object')
             continue;
         const { scope, test } = parseSelector(key);
-        if (scope === 'root' && !isRoot)
+        /** A root block asks only whether this *is* the root - no selector needed, which is what makes
+         *  `/` structural. A glob has to have something to match, and during the walk it does not. */
+        if (scope === 'root' ? !isRoot : isRoot || selector === undefined || !test(selector))
             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 +372,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);
@@ -292,6 +389,11 @@ function dirChain(rootDir, targetDir) {
     }
     return dirs;
 }
+/**
+ * **Returns `Resolved<T>`, not `T`, because resolving is what it does.** Calling every value
+ * function is half this function's job, so the type it hands back is the one where they are gone -
+ * which is what makes `pkg.config` a `ResolvedConfig` without a cast anywhere between.
+ */
 export function interpolateConfig(config, scope, options) {
     const skip = options?.skip ?? [];
     /**
@@ -318,8 +420,8 @@ export function interpolateConfig(config, scope, options) {
     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
+     * The config's own top-level keys, readable bare: `${{ changelog.filePath }}`. So a value that
+     * restates another - `after: "cp README.md ${{ changelog.filePath }}/"` - 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
@@ -379,6 +481,13 @@ export function interpolateConfig(config, scope, options) {
     const result = {};
     for (const key of Object.keys(config))
         result[key] = resolve(key);
+    /**
+     * **The one cast in the whole two-view split, and it is here rather than at every read.** No type
+     * can prove that a runtime walk turned `T` into `Resolved<T>`; this walk is what makes it true.
+     * Putting it at this single return is what keeps `pkg.config` honest without a cast in any of the
+     * commands - which is the arrangement the alternative (widening `RmanConfig` alone) gave up, six
+     * read sites at a time.
+     */
     return result;
 }
 /**
@@ -399,14 +508,14 @@ 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`
  * }
  * ```
  *
  * **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
+ * `publish.npm.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:
@@ -434,16 +543,23 @@ export const STEP_PATHS = [
 ];
 /**
  * Keys whose **whole subtree** is code rather than config, so no function under them is a value to
- * compute. `plugins` is the only one, and it has to be here: an entry may be the plugin *object*
- * itself, and an `RmanPlugin` is almost entirely functions - `manifest.read`, `workspace.resolve`,
- * `versionPlanner`, `binPaths`, and every command's `builder` and `handler`.
- *
- * Measured, and it is why this exists: with `plugins` walked like any other key, resolving the
- * config of a repository that named a plugin called that plugin's yargs builder with the config
- * scope - `Config function in "plugins[0].commands[0].builder" failed: cmd.option is not a
- * function`. A `plugins` entry is loaded by `loadPlugins`, never read as a setting.
+ * compute.
+ *
+ * The three contribution keys, and each has to be here: an entry may be the *instance* itself, and
+ * a `Plugin` is almost entirely functions - `manifestProvider.read`, `getWorkspace`,
+ * `getBinPaths`, `versionPlanner` - while a command is often a bare factory and a publish target
+ * carries `getPlan`/`applyPlan`.
+ *
+ * Measured twice, once per shape. 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`. And
+ * with `commands` left out of this list, a declarative command - which *is* a function - was
+ * invoked with the interpolation scope instead of the application, so its handler closed over a
+ * repository that was not one: `repository.getPackages is not a function`, from inside `clean`.
+ *
+ * These entries are loaded by `loadPlugins` and `cli.ts`, never read as settings.
  */
-export const CODE_SUBTREES = ['plugins'];
+export const CODE_SUBTREES = ['plugins', 'commands', 'publishTargets'];
 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. */
@@ -661,13 +777,14 @@ function shortenOrigin(file) {
  *
  * **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.
+ * this layer set it" - two different mistakes needing two different fixes. With nothing underneath
+ * it is `unsetValue()` rather than `undefined` - see there.
  *
  * 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 resolved = previousValue(previous === undefined ? undefined : walkWithPrevious(previous.value, previous.previous, scope, context, at, skip), at);
     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-
@@ -686,22 +803,18 @@ function walkWithPrevious(item, previous, 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.
+         * **The hint is only about *reading* `value`**, so it is attached only when the value did -
+         * recorded through the getter above, never matched on V8's wording. Attaching it to any other
+         * failure is the send-the-reader-to-the-wrong-place mistake it exists to prevent.
          *
-         * 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.
+         * The sentence itself comes from `unsetValue`, which knows the key and throws at the exact
+         * point of misuse; all this adds is the case the sentinel cannot catch, where a value reads
+         * `value` and fails for a reason of its own. `rmanValueHint` keeps a rethrow from stacking it
+         * twice as the error passes back up through the enclosing keys.
          */
-        if (wasRead && resolved === undefined && !e?.rmanValueHint) {
+        if (wasRead && isUnsetValue(resolved) && !e?.rmanValueHint) {
             e.rmanValueHint = true;
-            e.message =
-                `${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.`;
+            e.message = `${e.message}\n  Note: nothing below this layer sets "${describeAt(at)}, so \`value\` is empty.`;
         }
         throw e;
     }
@@ -942,3 +1055,69 @@ function deepFreeze(value) {
     for (const item of Object.values(value))
         deepFreeze(item);
 }
+/**
+ * What a layer is handed as `value`: **the list form of whatever is underneath it.**
+ *
+ * `value` exists for one job - extending what a closer layer inherited, the general form of `+key`,
+ * and `+key` only ever meant append. So the shape a spread wants is the shape to hand over:
+ * `[...value, 'x']` works with no guard whether the layers below said nothing, said `'build'`, or
+ * said `['build']`.
+ *
+ * **Coercing a scalar into a one-element list is not a guess about the key's type.** Every key this
+ * is reached for is declared `X | X[]` - `clean.include`, `clean.exclude`, `version.stamp`,
+ * `version.before`/`.exec`/`.after` - where the list is the type and the scalar is *shorthand*.
+ * `CleanService` and `RunService` already normalize it; doing it here as well decides nothing new.
+ * And spreading a string into its characters, which is what handing the raw value over did, is not
+ * something any key wants.
+ *
+ * It reads as the scalar wherever a scalar is what makes sense, through `Symbol.toPrimitive`:
+ * `` `${value}-x` `` is `'build-x'` and `value + 1` is `6`. A *list* underneath refuses both, since
+ * splicing `a,b` into a sentence is a mistake worth naming; so does nothing-underneath.
+ *
+ * **A boolean is handed over as itself**, the one carve-out, because it is never a list nor a
+ * list's shorthand - and an object cannot be fixed up for it: `!value` and `value ? :` use
+ * ToBoolean, which has no hook and answers `true` for every object, so a wrapped `false` would read
+ * as `true`. Measured. `[...value]` on one then throws, which is right - spreading a boolean means
+ * nothing.
+ *
+ * **The cost, stated rather than hidden: strict equality and string methods on an inherited
+ * scalar.** `value === 'build'` is `false` and `value.includes('bui')` is `false` (an array's
+ * `includes` matches elements, not substrings). `value == 'build'`, `` `${value}` === 'build' `` and
+ * `String(value).includes('bui')` all work, and `value.length` is the number of layers' worth of
+ * entries rather than a string's length. That is the trade for the append case never needing a
+ * guard; `value` was introduced for the append case.
+ */
+function previousValue(raw, at) {
+    /** Never a list, and unfixable as one - see above. */
+    if (typeof raw === 'boolean')
+        return raw;
+    const list = raw === undefined ? [] : Array.isArray(raw) ? [...raw] : [raw];
+    Object.defineProperty(list, UNSET_MARKER, { value: raw === undefined });
+    return Object.defineProperty(list, Symbol.toPrimitive, {
+        value: (hint) => {
+            if (raw === undefined) {
+                throw unusable(at, 'nothing below this layer sets it, so it is empty', "`value ?? ''`, `value ?? 0`");
+            }
+            if (typeof raw !== 'string' && typeof raw !== 'number') {
+                throw unusable(at, `the layer below it is ${Array.isArray(raw) ? 'a list' : 'an object'}`, '`value.join(", ")` for a list');
+            }
+            return hint === 'string' ? String(raw) : raw;
+        },
+    });
+}
+/** The one sentence both refusals share: what was asked for, why it cannot be done, what to write
+ *  instead. Marked `rmanValueHint` so `walkWithPrevious`'s catch leaves it alone - that note exists
+ *  to explain an empty `value` to an error that does not mention it, and this error *is* that
+ *  explanation. */
+function unusable(at, because, instead) {
+    const error = new Error(`\`value\` cannot be used as a string or a number here - ${because}, for "${describeAt(at)}. ` +
+        `It spreads as a list (\`[...value, x]\`); to use it as something else, say what it should be - ${instead}.`);
+    error.rmanValueHint = true;
+    return error;
+}
+/** Whether `value` stands for "no layer underneath set this key" - by the marker `previousValue`
+ *  puts on it, never by emptiness, since a layer may legitimately resolve to `[]`. */
+function isUnsetValue(value) {
+    return Array.isArray(value) && value[UNSET_MARKER] === true;
+}
+const UNSET_MARKER = Symbol('rman.valueUnset');