rman 1.3.0 → 2.0.0-beta.2

package/core/merge-config.d.ts

@@ -1,8 +1,19 @@
-/** The prefix that turns a key into an append instead of a replacement: `+before` adds to whatever
- *  `before` already resolved to, rather than taking its place. */
-export declare const APPEND_PREFIX = "+";
+/** Where a repository keeps command modules of its own, as a glob or a list of them. */
+export declare const COMMANDS_KEY = "commands";
 /**
- * Keys that **append whether or not you ask** - `+plugins` is accepted and means nothing extra.
+ * Keys that **append rather than replace**, which is the only append rman has.
+ *
+ * **There used to be a `+key` prefix on every key, and it is gone.** It said "add to what this
+ * resolved to below", which is exactly what `value` says - and `value` says it better: it composes
+ * (three layers each deriving from the one under them), it can reorder or filter rather than only
+ * append, and it does not need the merge to keep an append *outstanding* until the layer it belongs
+ * to turns up. The prefix also carried a bug `value` does not: appending onto a value that was a
+ * sole `${{ }}` expression returning an array nested it, because the merge promoted the expression
+ * *string* to a list and interpolation only later turned that element into the array (measured,
+ * `[['a','b'],'c']` where a literal list gave `['a','b','c']`).
+ *
+ * What is left is this list, where appending is not a choice the author makes per layer but what
+ * the key *means*.
  *
  * `plugins` is the whole list because it is the one key where replacing is never what anyone meant:
  * every other setting has a value a closer layer can sensibly overrule, while a plugin *adds
@@ -10,6 +21,12 @@ export declare const APPEND_PREFIX = "+";
  * brought. Replacing was the silent failure - `extends`-ing a toolchain config and then adding a
  * plugin of your own dropped the toolchain's, and what you noticed was `Unknown argument: publish`.
  *
+ * `commands` and `publishTargets` are the same kind of statement - what this repository has, in
+ * instances or in globs naming them - so they append for the same reason: a repository adding one
+ * of its own never means "and stop loading the ones my shared config brought". All three are what
+ * a config *contributes*, and a contribution list is exactly the case where replacing is never
+ * what anyone meant.
+ *
  * Do not extend this list casually: a key that always appends can never be *un*-said by a closer
  * layer, which is only acceptable where the value is a set of contributions rather than a decision.
  */
@@ -24,7 +41,7 @@ export declare const ALWAYS_APPEND: readonly string[];
  * carry one.
  *
  * A symbol is invisible to `Object.entries`, `JSON.stringify` and js-yaml, so the chain travels
- * through `mergeConfig`, `finalizeConfig` and `rman config` without any of them having to know it
+ * through `mergeConfig` and `rman config` without either of them having to know it
  * is there.
  *
  * Each entry is a link, not a single slot: three layers each deriving from the one below need
@@ -51,47 +68,29 @@ export interface PreviousValue {
 }
 /** Only these two can ask for `value`, so only these two are worth remembering a previous for. */
 export declare function carriesPreviousValue(value: unknown): boolean;
-/** `"+before"` -> `"before"`, or `undefined` for a key that isn't an append. */
-export declare function appendTarget(key: string): string | undefined;
 /**
  * Merges `source` onto `target` in place, the way every layer of rman config is combined - a
  * directory's own file forms, the directory chain, `"[selector]"` blocks, and an `extends` base.
  * One implementation for all of them, so they cannot disagree about what an append means.
  *
- * Plain keys replace, and nested objects merge recursively, as a deep merge always has. What this
- * adds is `+key`:
+ * Plain keys replace and nested objects merge recursively, as a deep merge always has. The two
+ * things it adds are the contribution keys, which append instead (`ALWAYS_APPEND`), and the record
+ * of what each key held underneath, so a closer layer can derive from it as `value`.
  *
  * ```yaml
- * # the root says          before: "rm ./build"
- * # a package adds        +before: "rm ./cache"
- * # it resolves to         before: ["rm ./build", "rm ./cache"]
+ * # the root says   before: "rm ./build"
+ * # a package says  before: "${{ [...value, 'rm ./cache'] }}"
+ * # it resolves to   before: ["rm ./build", "rm ./cache"]
  * ```
  *
- * Appending is the half a shared config can't live without: a base that declares
- * `before: ["rm ./build"]` otherwise forces every repository wanting one more step to restate the
- * whole list - which is a copy of the base, silently frozen at the version it was copied from.
- *
- * A scalar is promoted to a list on the way, so neither side has to be written as an array. With
- * nothing inherited, `+key` simply produces a one-element list.
+ * That is the half a shared config cannot live without: a base declaring `before: ["rm ./build"]`
+ * otherwise forces every repository wanting one more step to restate the whole list - which is a
+ * copy of the base, silently frozen at the version it was copied from.
  *
- * On a value that isn't a list, the prefix is **ignored** rather than an error, because there the
- * two spellings already mean the same thing: objects merge whether or not you asked them to, and a
- * scalar has nothing to append to, so `+key` behaves exactly as `key` would. Nothing is silently
- * dropped - the value still lands.
- *
- * `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.
+ * **A `+key` prefix used to mean this and is refused now**, naming the key and what to write
+ * instead - see the check at the top of the loop.
  */
 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.
- *
- * Called once on a fully resolved config, and only there: until then an outstanding append may
- * still find the layer it belongs to, and a config handed to a command must carry no `+key` at all
- * or every reader would have to know about them.
- */
-export declare function finalizeConfig<T>(config: T): T;

package/core/merge-config.js

@@ -1,8 +1,23 @@
-/** The prefix that turns a key into an append instead of a replacement: `+before` adds to whatever
- *  `before` already resolved to, rather than taking its place. */
-export const APPEND_PREFIX = '+';
+import path from 'node:path';
+/** Where a repository keeps command modules of its own, as a glob or a list of them. */
+export const COMMANDS_KEY = 'commands';
+/** The keys whose string entries are globs, and so have to be anchored to the file that wrote
+ *  them - see `anchorContributions`. The same three that always append. */
+const GLOB_KEYS = ['plugins', COMMANDS_KEY, 'publishTargets'];
 /**
- * Keys that **append whether or not you ask** - `+plugins` is accepted and means nothing extra.
+ * Keys that **append rather than replace**, which is the only append rman has.
+ *
+ * **There used to be a `+key` prefix on every key, and it is gone.** It said "add to what this
+ * resolved to below", which is exactly what `value` says - and `value` says it better: it composes
+ * (three layers each deriving from the one under them), it can reorder or filter rather than only
+ * append, and it does not need the merge to keep an append *outstanding* until the layer it belongs
+ * to turns up. The prefix also carried a bug `value` does not: appending onto a value that was a
+ * sole `${{ }}` expression returning an array nested it, because the merge promoted the expression
+ * *string* to a list and interpolation only later turned that element into the array (measured,
+ * `[['a','b'],'c']` where a literal list gave `['a','b','c']`).
+ *
+ * What is left is this list, where appending is not a choice the author makes per layer but what
+ * the key *means*.
  *
  * `plugins` is the whole list because it is the one key where replacing is never what anyone meant:
  * every other setting has a value a closer layer can sensibly overrule, while a plugin *adds
@@ -10,10 +25,16 @@ export const APPEND_PREFIX = '+';
  * brought. Replacing was the silent failure - `extends`-ing a toolchain config and then adding a
  * plugin of your own dropped the toolchain's, and what you noticed was `Unknown argument: publish`.
  *
+ * `commands` and `publishTargets` are the same kind of statement - what this repository has, in
+ * instances or in globs naming them - so they append for the same reason: a repository adding one
+ * of its own never means "and stop loading the ones my shared config brought". All three are what
+ * a config *contributes*, and a contribution list is exactly the case where replacing is never
+ * what anyone meant.
+ *
  * Do not extend this list casually: a key that always appends can never be *un*-said by a closer
  * layer, which is only acceptable where the value is a set of contributions rather than a decision.
  */
-export const ALWAYS_APPEND = ['plugins'];
+export const ALWAYS_APPEND = ['plugins', COMMANDS_KEY, 'publishTargets'];
 /**
  * Where a key keeps what it is replacing, so the replacement can be handed it back as `value`.
  *
@@ -24,7 +45,7 @@ export const ALWAYS_APPEND = ['plugins'];
  * carry one.
  *
  * A symbol is invisible to `Object.entries`, `JSON.stringify` and js-yaml, so the chain travels
- * through `mergeConfig`, `finalizeConfig` and `rman config` without any of them having to know it
+ * through `mergeConfig` and `rman config` without either of them having to know it
  * is there.
  *
  * Each entry is a link, not a single slot: three layers each deriving from the one below need
@@ -48,112 +69,61 @@ export const ORIGINS = Symbol('rman.origins');
 export function carriesPreviousValue(value) {
     return typeof value === 'function' || (typeof value === 'string' && value.includes('${{'));
 }
-/** `"+before"` -> `"before"`, or `undefined` for a key that isn't an append. */
-export function appendTarget(key) {
-    return key.length > APPEND_PREFIX.length && key.startsWith(APPEND_PREFIX)
-        ? key.slice(APPEND_PREFIX.length)
-        : undefined;
-}
 /**
  * Merges `source` onto `target` in place, the way every layer of rman config is combined - a
  * directory's own file forms, the directory chain, `"[selector]"` blocks, and an `extends` base.
  * One implementation for all of them, so they cannot disagree about what an append means.
  *
- * Plain keys replace, and nested objects merge recursively, as a deep merge always has. What this
- * adds is `+key`:
+ * Plain keys replace and nested objects merge recursively, as a deep merge always has. The two
+ * things it adds are the contribution keys, which append instead (`ALWAYS_APPEND`), and the record
+ * of what each key held underneath, so a closer layer can derive from it as `value`.
  *
  * ```yaml
- * # the root says          before: "rm ./build"
- * # a package adds        +before: "rm ./cache"
- * # it resolves to         before: ["rm ./build", "rm ./cache"]
+ * # the root says   before: "rm ./build"
+ * # a package says  before: "${{ [...value, 'rm ./cache'] }}"
+ * # it resolves to   before: ["rm ./build", "rm ./cache"]
  * ```
  *
- * Appending is the half a shared config can't live without: a base that declares
- * `before: ["rm ./build"]` otherwise forces every repository wanting one more step to restate the
- * whole list - which is a copy of the base, silently frozen at the version it was copied from.
- *
- * A scalar is promoted to a list on the way, so neither side has to be written as an array. With
- * nothing inherited, `+key` simply produces a one-element list.
+ * That is the half a shared config cannot live without: a base declaring `before: ["rm ./build"]`
+ * otherwise forces every repository wanting one more step to restate the whole list - which is a
+ * copy of the base, silently frozen at the version it was copied from.
  *
- * On a value that isn't a list, the prefix is **ignored** rather than an error, because there the
- * two spellings already mean the same thing: objects merge whether or not you asked them to, and a
- * scalar has nothing to append to, so `+key` behaves exactly as `key` would. Nothing is silently
- * dropped - the value still lands.
- *
- * `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.
+ * **A `+key` prefix used to mean this and is refused now**, naming the key and what to write
+ * instead - see the check at the top of the loop.
  */
 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)) {
-        if (appendTarget(key))
-            continue;
-        /** `plugins`: additive at every layer, so the closer one adds rather than takes over. */
+        /**
+         * **A retired `+key` is refused, not ignored.** rman validates no config keys at all - there is
+         * no schema behind `.rmanrc`/`.rmanrc.yml` any more - so an unknown key is silent, and a
+         * repository upgrading from 1.x with `+before:` in its config would simply lose that step with
+         * nothing said. Measured before this check: `+include: ['extra']` resolved to the inherited
+         * list unchanged, exactly as if the line were not there.
+         *
+         * Here rather than in a validator, because this is the one function every layer passes through,
+         * and it is the only place that still knows which file the key came from.
+         */
+        if (key.length > 1 && key.startsWith('+')) {
+            const plain = key.slice(1);
+            throw new Error(`"${key}" is no longer a config key${origin ? ` (${origin})` : ''}. The \`+key\` prefix is ` +
+                `gone: write "${plain}" as a value that derives from what it inherited - ` +
+                `\`${plain}: ({ value }) => [...value, 'x']\`, or \`"\${{ [...value, 'x'] }}"\` in YAML. ` +
+                `\`value\` is the layers below this one, and spreads as empty when there are none.`);
+        }
+        /** `plugins`/`commands`/`publishTargets`: additive at every layer, so the closer one adds
+         *  rather than takes over. A glob among them is anchored to its own file on the way in - see
+         *  `anchorContributions`. */
         if (ALWAYS_APPEND.includes(key)) {
-            appendList(target, key, value);
+            appendList(target, key, GLOB_KEYS.includes(key) ? anchorContributions(value, origin) : value);
             continue;
         }
         assignMerged(target, key, value, source, origin);
     }
-    for (const [key, value] of Object.entries(source)) {
-        const plain = appendTarget(key);
-        if (!plain)
-            continue;
-        // 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, source, origin);
-            continue;
-        }
-        if (plain in target) {
-            appendList(target, plain, value);
-            continue;
-        }
-        /** Nothing to append to *yet*. Kept as an append rather than collapsed into the plain key,
-         *  because the layer that provides it may still be coming: a directory's own file forms are
-         *  merged into an empty object long before the selector blocks and parent directories they
-         *  append to are. Collapsing here lost both of those - measured. `finalizeConfig` turns
-         *  whatever is still outstanding at the end into a plain list. */
-        target[key] = [...toList(target[key] ?? []), ...toList(value)];
-    }
     return target;
 }
-/**
- * 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.
- *
- * Called once on a fully resolved config, and only there: until then an outstanding append may
- * still find the layer it belongs to, and a config handed to a command must carry no `+key` at all
- * or every reader would have to know about them.
- */
-export function finalizeConfig(config) {
-    if (Array.isArray(config))
-        return config.map(finalizeConfig);
-    if (!isPlainObject(config))
-        return config;
-    const result = {};
-    for (const [key, value] of Object.entries(config)) {
-        const plain = appendTarget(key);
-        if (!plain) {
-            result[key] = finalizeConfig(value);
-            continue;
-        }
-        const pending = finalizeConfig(value);
-        result[plain] = plain in result ? [...toList(result[plain]), ...toList(pending)] : toList(pending);
-    }
-    /** Carried across by hand: this rebuilds the object from `Object.entries`, which does not see a
-     *  symbol - and dropping it here would lose every `value` chain the merge just recorded. */
-    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, 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. */
@@ -185,18 +155,48 @@ function assignMerged(target, key, value, source, origin) {
      * layers - by the time `interpolateConfig` sees the config they have collapsed into one object,
      * and whatever a closer layer said has already taken the place of what it was derived from.
      */
-    if (carriesPreviousValue(value) && key in target) {
+    /**
+     * **A chain already on `source` is carried over**, the way its `ORIGINS` are just above - and for
+     * the same reason: `source` may itself be several layers already merged, and only the merge knows
+     * their order.
+     *
+     * Without this, a chain recorded *inside* a source was silently dropped whenever the key was
+     * absent from the target, because the link below was only ever recorded for a key being
+     * *replaced*. The shape that hit it is the ordinary one for a shared config: a base and its
+     * consumer both writing `"[*]"`. Those two blocks merge into one before `matchingSelectors` sees
+     * them - recording the chain on the merged block - and that block is then merged into a `result`
+     * which has no such key, so the chain went nowhere.
+     *
+     * Measured, on a base declaring `clean.include: ['build']` and a consumer's `"[*]"` deriving from
+     * it: `${{ [...value, 'dist'] }}` answered `['dist']`, losing `build` outright. It answers
+     * `['build', 'dist']` now. Two *different* selectors (`"[*]"` then `"[pkg-a]"`) always worked,
+     * and so did an unmarked key, which is why this went unnoticed - those merge into a target that
+     * already holds the key.
+     */
+    const sourceChain = source[PREVIOUS_VALUES]?.[key];
+    if (carriesPreviousValue(value) && (key in target || sourceChain)) {
         const carrier = target;
         const chain = (carrier[PREVIOUS_VALUES] ??= {});
-        chain[key] = { value: target[key], previous: chain[key] };
+        /** The layer the target itself stands for, bottom-most of the three: what it holds now, over
+         *  whatever *that* was derived from. Absent when the target never had the key. */
+        const below = key in target ? { value: target[key], previous: chain[key] } : chain[key];
+        /** Bottom-up: the target's layer, then `source`'s own intermediate ones, then `value` on top -
+         *  so `source`'s chain keeps its internal order and gets the target's spliced beneath it. */
+        chain[key] = sourceChain ? graftChain(sourceChain, below) : below;
     }
     target[key] = Array.isArray(value) ? [...value] : value;
 }
+/** `node`'s chain, copied with `tail` spliced in beneath its deepest link - so two layer-stacks
+ *  join into one without either being mutated (a chain is shared by every package that resolved
+ *  through it, so grafting in place would rewrite what the others see). */
+function graftChain(node, tail) {
+    return { value: node.value, previous: node.previous ? graftChain(node.previous, tail) : tail };
+}
 /**
  * Appends `value` to `target[key]`, de-duplicating **only** an `ALWAYS_APPEND` key.
  *
  * That asymmetry is the point. `plugins` appends without being asked, so a repository and the config
- * it extends both naming `'rman-node'` is the ordinary case rather than a mistake, and the list is
+ * it extends both naming `'node'` is the ordinary case rather than a mistake, and the list is
  * also what `rman config` prints. An explicit `+before`, by contrast, was *written* - repeating a
  * step that is already there is a strange thing to ask for, but it is what was asked for, and
  * silently collapsing it would make one layer's list depend on another's contents.
@@ -212,6 +212,51 @@ function appendList(target, key, value) {
 function toList(value) {
     return Array.isArray(value) ? value : [value];
 }
+/**
+ * Anchors every glob in `plugins`/`commands`/`publishTargets` to the directory of the file that
+ * declared it, on the way in. A non-string entry - an instance written straight into the config -
+ * passes through untouched.
+ *
+ * **Done here, at the merge, because this is the last moment the answer is known.** `commands`
+ * always appends, so one resolved list ends up holding entries from the repository's own
+ * `.rmanrc`, from each `extends` base, and from every directory above - and `ORIGINS` records one
+ * file per *key*, not per element, so after the merge there is nothing left to attribute them by.
+ * Rewriting each glob as it arrives makes the merge trivially correct and costs one `path.resolve`.
+ *
+ * It is what lets a **shared config ship its own contributions**: `commands: './commands/*.js'`
+ * in a published package means that package's directory, wherever the repository inheriting it
+ * happens to sit. All three keys behave the same way; `plugins` used to resolve every entry
+ * against the repository root instead, whatever file declared it, and that asymmetry is gone.
+ *
+ * `origin` is absent when a caller merges a value it built rather than read (a selector block, the
+ * directory chain layering already-resolved configs); those globs have been anchored already, and
+ * an absolute path is left alone by `path.resolve` anyway.
+ */
+function anchorContributions(value, origin) {
+    if (!origin)
+        return value;
+    const dir = path.dirname(origin);
+    const anchor = (entry) => typeof entry === 'string' && !looksLikePackageName(entry) ? path.resolve(dir, entry) : entry;
+    return Array.isArray(value) ? value.map(anchor) : anchor(value);
+}
+/**
+ * Whether an entry is shaped like a **package name** rather than a glob - `rman-node`,
+ * `@panates/rman-node`, but not `*.js`, `./x.js` or `commands/*.mjs`.
+ *
+ * Such an entry is left unanchored, because it is not a relative path and turning it into one
+ * destroys the only evidence of what the author meant. A package name is never valid in these keys
+ * (a package's config arrives through `extends`), so the whole value of keeping it intact is the
+ * error message: anchored, `plugins: ['rman-node']` failed with `glob ".../rman-node" matched no
+ * file`, which sends the reader to check their paths. `loadPlugins` can now say what they actually
+ * wrote and what to write instead - which two doc pages already promised it did.
+ *
+ * Shape, not a resolver call: decidable without touching the disk, and a wrong guess only chooses
+ * which of two error messages a failing entry gets. An extension is excluded so a bare `plugin.js`
+ * beside the config is still anchored as the relative path it is.
+ */
+function looksLikePackageName(entry) {
+    return /^(?:@[a-z0-9-~][\w.-]*\/)?[a-z0-9-~][\w.-]*$/i.test(entry) && !/\.[cm]?js$/i.test(entry);
+}
 /** A config object, as opposed to an array or anything with its own prototype - only the former
  *  merges key by key. */
 function isPlainObject(value) {

package/core/package.d.ts

@@ -1,15 +1,17 @@
-import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import type { RmanApplication } from './application.js';
+import type { ResolvedConfig } from './config.js';
 import { Manifest } from './manifest.js';
+import type { Platform } from './plugin.js';
 import type { Repository } from './repository.js';
 import { type VersionScheme } from './version-scheme.js';
 export declare class Package {
     readonly dirname: string;
     /**
-     * This package's identity, read through whichever `ManifestProvider` recognizes its directory.
+     * This package's identity, read through whichever `Plugin`'s manifest members recognizes its directory.
      *
      * There is no `json` here any more, and that is the point: `package.json` is npm's answer to
      * "where is a package's name and version written", not rman's. `manifest.raw` is still the whole
-     * document for a command that knows its own ecosystem - `rman-node` reads `scripts` and
+     * document for a command that knows its own ecosystem - the `node` built-in reads `scripts` and
      * `publishConfig` off it - but the core only ever touches `name`, `version` and `private`.
      */
     manifest: Manifest;
@@ -23,9 +25,16 @@ export declare class Package {
      * whatever the ecosystem, and comparing by identity removes a lookup from every consumer.
      */
     dependencies: Package[];
-    /** Effective rman config for this package, cascaded from the repository root, with every
-     *  `${{ ... }}` expression already evaluated. */
-    config: RmanConfig;
+    /**
+     * Effective rman config for this package, cascaded from the repository root, with every
+     * `${{ ... }}` expression already evaluated.
+     *
+     * **`ResolvedConfig`, not `RmanConfig`, and that is the whole two-view split in one line.**
+     * `RmanConfig` is what an *author* writes, where a value may be a function; this is what a
+     * *reader* gets, where it has already been called. Derived from the one the author writes, so
+     * there is no second type to keep in step - see `Resolved`.
+     */
+    config: ResolvedConfig;
     /**
      * The repository this package belongs to - so anything holding a package can reach the whole
      * picture (its siblings, the root's config, git) without being handed it separately.
@@ -33,14 +42,54 @@ export declare class Package {
      * Assigned by `Repository.create` rather than taken as a constructor argument, and it has to be:
      * `Repository extends Package`, so a repository constructing itself runs this constructor before
      * it exists to be passed in. A repository's own is itself.
+     *
+     * **Non-enumerable, and `declare` for the same reason `parent` is** - this is the *other* half of
+     * why a package could not be serialized, and the older half. A `Repository` holds every package,
+     * so one enumerable back-reference makes `JSON.stringify(anyPackage)` a cycle whatever the tree
+     * edges do: measured before `parent` was touched at all, and the error even named it
+     * (`property 'repository' closes the circle`). Making only `parent` non-enumerable would have
+     * delivered a tree that still cannot be dumped, which is the whole reason the asymmetry exists.
+     *
+     * It is the same rule `Repository.app`, `_repoScope` and `_git` already follow: a back-reference
+     * to something that holds everything has no business in a walk of one package.
      */
     repository: Repository;
     /**
      * The package whose directory contains this one - the repository root for an ordinary member, and
      * a genuine enclosing package for one nested inside another (which `Repository.currentPackage`
      * already has to reason about). `undefined` for the root itself, which nothing contains.
+     *
+     * **Non-enumerable, and `children` is not** - the two halves of one edge, and only one of them
+     * can be the one a walk follows. A tree is walked downwards, so `children` has to be visible and
+     * `parent` must not be, or a `toEqual` diff climbs back to the root and down again. Assigned
+     * through `defineProperty` by `Repository._linkPackages`, the same way `Repository.app` and
+     * `ORIGINS` travel.
+     *
+     * **`declare`, and that is load-bearing.** A plain `readonly parent?: Package` is a *class field*
+     * under this target, so TypeScript emits `parent;` and every package gets an **enumerable**
+     * `undefined` that the later `defineProperty` only replaces on the packages that have a parent.
+     * Measured: `Object.keys(rootPackage)` listed `parent` while `Object.keys(pkg-a)` did not, which
+     * is the exact opposite of what either name suggests. `declare` emits nothing, so the property
+     * exists only where it is defined.
+     *
+     * **It does not make a `Package` JSON-serializable, and nothing here claims it does** - see
+     * `repository`, which is enumerable and points back at an object holding every package.
+     */
+    readonly parent?: Package;
+    /**
+     * The packages whose directories sit directly inside this one - **the tree edge**, in the order
+     * the platform that claimed this directory gave them.
+     *
+     * This is the shape discovery actually has, and it used to be flattened away: a provider was
+     * asked once at the repository root and returned one list, so a package nested inside another was
+     * only reconstructible by comparing path prefixes (which `_linkPackages` and `currentPackage`
+     * both did, separately). `Workspace.walk` descends, so the containment is known as it is found -
+     * and `Repository.packages` is now this tree flattened rather than the other way round.
+     *
+     * Empty for a leaf, and for every package in an ordinary flat monorepo - where the root's
+     * `children` is the whole member list.
      */
-    parent?: Package;
+    readonly children: Package[];
     /**
      * How this package's versions are numbered - `pkg.versionScheme.next(pkg.version, 'minor')`.
      *
@@ -57,27 +106,106 @@ export declare class Package {
      *  changed (a commit's path list). Empty when no provider recognized this directory. */
     manifestFileName: string;
     /**
-     * **Which ecosystem this package belongs to** - `'node'` for one read by `rman-node`, from the
-     * `ManifestProvider.name` that claimed the directory. Empty when no provider did.
+     * **What addresses this package**: what a `.rmanrc "[glob]"` block and `--scope`/`--ignore` match
+     * against, and what must be unique within the repository.
+     *
+     * Three sources, first one that answers:
+     *
+     * 1. the package's own `.rmanrc "name"` - the repository assigning one;
+     * 2. its platform's `manifestProvider.selector`;
+     * 3. the manifest's own `name`, which is the default that answer falls back to.
+     *
+     * **Not `name`, and the split is the point.** `name` is what the package calls itself, read from
+     * its manifest, and it is an *ecosystem's* promise that such a thing exists and identifies the
+     * package - npm's promise, not rman's. Selectors matched `pkg.name` until this existed, so a
+     * repository whose technology has no name concept had packages it could not address at all, and
+     * one whose names are not unique (or are import paths) could only address them badly. They
+     * coincide for every Node repository, which is why nothing had to change for one.
+     *
+     * **The root's is nearly unused, deliberately.** A glob never matches the root and `"[/]"` needs
+     * no name - the root is addressed structurally, which is the whole reason it is `/`. It still has
+     * one so that nothing has to special-case it.
+     *
+     * Assigned by `Repository.create`, which is what has the config; a bare `new Package(dir, app)`
+     * gets the manifest's name, which is sources 2 and 3 with no config to consult.
+     */
+    selector: string;
+    /**
+     * **The technology this package belongs to** - the platform whose manifest provider claimed the
+     * directory, or `basePlatform` when none did.
+     *
+     * Per *package*, not per repository: the question is asked per directory, so a polyglot monorepo
+     * can hold a `node` package beside a `cargo` one and a command sweeping `getPackages()` can tell
+     * them apart. It is also what carries the rest of the technology's answers - where its binaries
+     * live, where its scripts come from, how its releases are planned - so anything that used to walk
+     * four separate registries asking "is this yours?" now asks the package it already has.
+     */
+    platform: Platform;
+    /**
+     * **Which ecosystem this package belongs to** - `'node'` for one the `node` built-in read. Empty when
+     * no stack claimed the directory.
      *
      * The escape hatch for code that legitimately knows one technology: `if (pkg.provider === 'node')`
-     * before reaching into `manifest.raw` for something only npm has. Per *package*, not per
-     * repository, because `Manifest.read` asks per directory - a polyglot monorepo can hold a `node`
-     * package beside a `cargo` one, and a command sweeping over `getPackages()` has to be able to
-     * tell.
+     * before reaching into `manifest.raw` for something only npm has.
      *
      * Not a union type on purpose: the set of ecosystems is whatever the repository's `plugins`
      * contribute, so narrowing it here would mean the core listing plugins it cannot know about.
      */
-    provider: string;
-    constructor(dirname: string);
+    get provider(): string;
+    /**
+     * **Takes the application but does not keep it.** A package needs it once, to find out which
+     * technology claims its directory; afterwards it holds only data, so nothing that has a package
+     * can reach a service through it. Data down, behaviour up - the work belongs to services, and a
+     * piece of code holding only a package is not doing any.
+     *
+     * It also keeps the package out of every spread and serialization the application would
+     * otherwise be dragged into: `{...pkg}` and `pkg.manifest.raw` are both real, and an `app` field
+     * here would carry the whole world into them.
+     */
+    constructor(dirname: string, app: RmanApplication, 
+    /**
+     * The technology that claimed this directory, when the caller already knows - which
+     * `Repository.create` does, because the walk that found the directory is what established it.
+     *
+     * Optional so a bare `new Package(dir, app)` still works: that is what the fixtures build, and
+     * it is also the honest fallback for anyone constructing a package outside a walk. It costs one
+     * search of the registry (`app.platformFor`), which is what *every* construction used to do.
+     */
+    platform?: Platform);
+    /** What this package's **platform** says addresses it, before any config is consulted - the
+     *  manifest's own name when the platform has no opinion, and the directory when it has no name
+     *  either (which is unique among siblings and is all there is to go on). */
+    platformSelector(): string;
     get basename(): string;
     get name(): string;
     get version(): string;
     get isPrivate(): boolean;
-    /** Re-reads from disk - for a command that has just written the manifest itself and wants the
-     *  package to agree with the file again. */
+    /**
+     * Whether this is the repository's **own root package** - what `--scope /` and `.rmanrc`'s
+     * `"[/]"` both select.
+     *
+     * **By directory, and deliberately not by name or by identity.** The documented rule is that the
+     * root package is the one whose directory *is* the repository root, because a name can be
+     * anything - and identity (`this === repository.rootPackage`) is not equivalent either:
+     * `Repository extends Package` while holding a separate `rootPackage` instance for the same
+     * directory, so a comparison by reference answers `false` for one of the two objects that are
+     * both, truthfully, the root.
+     *
+     * `false` before `Repository.create` has assigned `repository` - a bare `new Package(dir, app)`
+     * (which the test fixtures build) belongs to no repository yet, so there is no root for it to be.
+     */
+    get isRoot(): boolean;
+    /**
+     * Re-reads from disk - for a command that has just written the manifest itself and wants the
+     * package to agree with the file again.
+     *
+     * Through **its own** technology's provider, like the constructor: the package already knows
+     * which platform claimed it, and a second opinion on a re-read was never wanted.
+     */
     reloadManifest(): Manifest;
     /** Writes the current manifest back through its provider. */
     writeManifest(): void;
+    /** The three fields a manifest read sets, in one place - so construction and `reloadManifest`
+     *  cannot disagree about what "reading the manifest" means. */
+    private _readManifest;
 }