rman 1.0.12 → 1.1.1

package/core/extends-config.d.ts

@@ -0,0 +1,27 @@
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+/** The key naming configs to inherit from, the way eslint and tsconfig spell it. */
+export declare const EXTENDS_KEY = "extends";
+/**
+ * Resolves `config`'s own `extends` into it: every named config is loaded, merged in declaration
+ * order, and `config`'s own keys land on top. Returns a new object with no `extends` left in it.
+ *
+ * The point is a shared package - `extends: "@panates/rman-monorepo"` - so a repository declares
+ * its house rules once instead of restating them. `+key` is what makes that liveable (see
+ * `mergeConfig`): without it, adding one step to a base's list means copying the list.
+ *
+ * `from` is the file the `extends` was written in, and everything resolves relative to **it**: a
+ * bare specifier through that file's own `node_modules`, a relative path against its directory.
+ * Resolving from rman's own location instead would look in rman's dependencies, where a
+ * repository's shared config has no reason to be.
+ *
+ * `seen` carries the chain being resolved, so a config that extends its way back to itself is
+ * reported rather than recursed into forever.
+ */
+export declare function resolveExtends(config: RmanConfig, from: string, seen?: string[]): Promise<RmanConfig>;
+/**
+ * Refuses `extends` inside a `"[selector]"` block. A selector block is typed as a whole
+ * `RmanConfig`, so writing one there looks valid and would simply never be resolved - and a config
+ * that quietly does nothing is worse than one that won't load. Inheritance is a statement about
+ * the file, not about the packages it happens to name.
+ */
+export declare function assertNoSelectorExtends(config: RmanConfig, file: string): void;

package/core/extends-config.js

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import * as yaml from 'js-yaml';
+import { isSelectorKey } from './config.js';
+import { mergeConfig } from './merge-config.js';
+import { resolveConfigTarget } from './resolve-target.js';
+/** The key naming configs to inherit from, the way eslint and tsconfig spell it. */
+export const EXTENDS_KEY = 'extends';
+/**
+ * Resolves `config`'s own `extends` into it: every named config is loaded, merged in declaration
+ * order, and `config`'s own keys land on top. Returns a new object with no `extends` left in it.
+ *
+ * The point is a shared package - `extends: "@panates/rman-monorepo"` - so a repository declares
+ * its house rules once instead of restating them. `+key` is what makes that liveable (see
+ * `mergeConfig`): without it, adding one step to a base's list means copying the list.
+ *
+ * `from` is the file the `extends` was written in, and everything resolves relative to **it**: a
+ * bare specifier through that file's own `node_modules`, a relative path against its directory.
+ * Resolving from rman's own location instead would look in rman's dependencies, where a
+ * repository's shared config has no reason to be.
+ *
+ * `seen` carries the chain being resolved, so a config that extends its way back to itself is
+ * reported rather than recursed into forever.
+ */
+export async function resolveExtends(config, from, seen = []) {
+    const declared = config[EXTENDS_KEY];
+    if (declared === undefined)
+        return config;
+    const targets = Array.isArray(declared) ? declared : [declared];
+    for (const target of targets) {
+        if (typeof target !== 'string' || !target.trim()) {
+            throw new Error(`"extends" in "${from}" must be a config name or path, or an array of them`);
+        }
+    }
+    const base = {};
+    for (const target of targets) {
+        const file = resolveConfigTarget(target, from, EXTENDS_KEY);
+        if (seen.includes(file)) {
+            throw new Error(`"extends" forms a cycle: ${[...seen, file].map(f => path.basename(f)).join(' -> ')}`);
+        }
+        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]));
+    }
+    const own = { ...config };
+    delete own[EXTENDS_KEY];
+    return mergeConfig(base, own);
+}
+/**
+ * Refuses `extends` inside a `"[selector]"` block. A selector block is typed as a whole
+ * `RmanConfig`, so writing one there looks valid and would simply never be resolved - and a config
+ * that quietly does nothing is worse than one that won't load. Inheritance is a statement about
+ * the file, not about the packages it happens to name.
+ */
+export function assertNoSelectorExtends(config, file) {
+    for (const [key, value] of Object.entries(config)) {
+        if (!isSelectorKey(key) || !value || typeof value !== 'object')
+            continue;
+        if (EXTENDS_KEY in value) {
+            throw new Error(`"${key}" in "${file}" cannot use "extends" - it belongs at the top level, where it is a ` +
+                `statement about this config rather than about the packages the selector names.`);
+        }
+    }
+}
+/** Loads one resolved target. YAML and JSON are read directly; anything else goes through the
+ *  module loader, so a shared config can be a `defineConfig` module with real logic in it. */
+async function loadConfigFile(file) {
+    const ext = path.extname(file);
+    if (ext === '.yml' || ext === '.yaml') {
+        const obj = yaml.load(fs.readFileSync(file, 'utf-8'));
+        return asConfig(obj, file);
+    }
+    if (ext === '.json')
+        return asConfig(JSON.parse(fs.readFileSync(file, 'utf-8')), file);
+    const mod = await import(pathToFileURL(file).href);
+    return asConfig(mod?.default ?? mod, file);
+}
+function asConfig(value, file) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`"${file}" does not export an rman config object`);
+    }
+    const config = { ...value };
+    // Editor tooling only - meaningless once merged, and `additionalProperties` would reject it
+    // wherever it ended up.
+    delete config.$schema;
+    return config;
+}

package/core/manifest.d.ts

@@ -0,0 +1,222 @@
+import type { Package } from './package.js';
+import { type VersionScheme } from './version-scheme.js';
+/**
+ * A package's identity, however its ecosystem happens to record it.
+ *
+ * Three fields rman genuinely needs of every package, plus the raw document for the commands that
+ * know what ecosystem they are in. Everything rman's core does - grouping, tagging, changelogs,
+ * release identity - is expressed in terms of these three and nothing else.
+ */
+export interface Manifest {
+    name: string;
+    version: string;
+    /** Excluded from publishing by the package's own declaration (`package.json#private`). Not the
+     *  same as `.rmanrc "publish.skip"`, which is the *repository's* declaration about it. */
+    private?: boolean;
+    /** The document as the ecosystem wrote it. `rman-node`'s own commands read `package.json` fields
+     *  the core has no opinion about (`scripts`, `publishConfig`, `engines`) off this. */
+    raw: any;
+}
+/**
+ * Where a package's identity is written, and how to change it.
+ *
+ * **The core has no provider.** "The name and version live in a `package.json`" is true of npm and
+ * of nothing else - a `Cargo.toml`, a `pyproject.toml` and a `go.mod` each say the same thing
+ * differently, and the version is not even in the same *kind* of place in all of them.
+ * `rman-node` contributes the `package.json` one.
+ *
+ * Paired with `VersionScheme` on purpose: the ecosystem that decides *where* a version is written
+ * is the one that decides *how* it is numbered, so a provider supplies both and a package gets a
+ * matching pair rather than a `pyproject.toml` read with semver's arithmetic.
+ */
+export interface ManifestProvider {
+    /**
+     * **The ecosystem this provider speaks for**, surfaced on every package it reads as
+     * `Package.provider` - `'node'` for `rman-node`. Short and about the technology, not about the
+     * file: `fileName` already says `package.json`, and a name repeating it would tell a caller
+     * nothing it did not have.
+     *
+     * This is what lets code that *does* know one ecosystem check before acting on a package -
+     * `if (pkg.provider === 'node')` - which matters most in a repository holding more than one,
+     * since `read` is asked per directory and two packages can legitimately answer to different
+     * providers.
+     */
+    readonly name: string;
+    /** The file this looks for, relative to a package directory - `'package.json'`. Used to report
+     *  what was missing, and by `import` when grafting an external repository in. */
+    readonly fileName: string;
+    /** `undefined` when this directory holds no package of this kind, so another provider gets a
+     *  turn rather than this one having to throw. */
+    read(dir: string): Manifest | undefined;
+    /** Writes `manifest` back. Only ever called with a manifest this provider produced. */
+    write(dir: string, manifest: Manifest): void;
+    /** How this ecosystem numbers versions. Defaults to semver when a provider has no opinion -
+     *  which is right for Cargo and Go, and wrong for PEP 440, whose provider should say so. */
+    readonly versionScheme?: VersionScheme;
+    /**
+     * The version of `pkg` this ecosystem's registry currently reports, or `undefined` for anything
+     * that is not an answer (never published, no network, private with no access).
+     *
+     * **Read for exactly one purpose, and it is not "has this been published"**: `detectChangeHash`
+     * borrows the version string to *guess a tag name*, and uses it only if a tag by that name
+     * actually exists in git. The case it covers is rman being adopted onto a repository whose
+     * releases predate it - a tag exists but is not in HEAD's ancestry (cut on another branch,
+     * rewritten history, a shallow clone), so `git describe` cannot see it. Never compare this
+     * against the local manifest version; that is `publish`'s question, and mixing the two is the
+     * measured bug the A/B split exists to prevent.
+     *
+     * Here rather than behind a repository-wide hook because a registry belongs to an *ecosystem*: a
+     * polyglot repository asks npm about its `node` packages and crates.io about its `cargo` ones, and
+     * only a per-package provider can do that. Optional - an ecosystem with no registry to ask (or a
+     * repository that would rather not reach the network) simply leaves git tags as the only source,
+     * which is the honest answer rather than a diminished one.
+     */
+    publishedVersion?(pkg: Package): Promise<string | undefined>;
+    /**
+     * Rewrites `content` so the version it hard-codes reads `version`, for a file `.rmanrc
+     * "version.stamp"` lists - returning `undefined` when there is nothing to change, so the caller
+     * writes nothing and can report a file that matched nothing.
+     *
+     * **Here because how a version is *declared* is the language's**, and this provider is already
+     * the ecosystem's representative for exactly that: `write` says where the manifest keeps it,
+     * `versionScheme` says how it is numbered, and this says what it looks like in source. Measured
+     * before it moved: the core's one pattern stamped a Go `const version = "…"` and a Gradle
+     * `version = "…"` but silently missed `const Version`, `__version__`, Rust's
+     * `pub const VERSION: &str = "…"` and `pom.xml`'s `<version>` - and "silently" is the part that
+     * mattered, since a listed file that matches nothing looked exactly like a file with no version
+     * in it.
+     *
+     * `file` is the absolute path, for a provider that keys off the extension (a `.ts` constant and a
+     * `Chart.yaml` are both npm-adjacent and are not the same rewrite). `options.constant` is the
+     * identifier the repository says holds it, from the config - a provider whose format has no
+     * identifier ignores it.
+     *
+     * `stampVersionConstant` is exported for the common case; delegating to it is one line.
+     */
+    stampVersion?(file: string, content: string, version: string, options?: {
+        constant?: string;
+    }): string | undefined;
+    /**
+     * Which of `candidates` this package declares a dependency on.
+     *
+     * The *field names* are the ecosystem's: npm spreads four of them
+     * (`dependencies`/`devDependencies`/`peerDependencies`/`optionalDependencies`), Cargo has
+     * `[dev-dependencies]` and `[build-dependencies]`, `go.mod` has one `require` block. rman only
+     * wants the edges of the graph, so the provider reads its own manifest and returns the packages.
+     *
+     * Returning **packages rather than names** for the same reason `Package.dependencies` holds
+     * them: a name identifies a package only where the ecosystem guarantees uniqueness, and the
+     * provider is the only thing that knows how its own ecosystem refers to a dependency.
+     *
+     * Omit it and a package has no declared dependencies beyond `.rmanrc "dependencies"`.
+     */
+    dependencies?(manifest: Manifest, candidates: readonly Package[]): Package[];
+    /**
+     * Splits a package name into the parts a config expression can ask for - `${{ pkg.scope }}` and
+     * `${{ pkg.unscopedName }}`.
+     *
+     * npm's `@scope/name` is a convention, not a universal: a Go module path (`github.com/x/y`)
+     * split on `/` would report a scope of `github.com/x`, and a Cargo crate has no such notion at
+     * all. Omit it and a name has no scope and is its own unscoped form, which is the honest answer
+     * for an ecosystem without the concept.
+     */
+    splitName?(name: string): {
+        scope?: string;
+        unscopedName: string;
+    };
+    /**
+     * Rewrites this manifest's references to in-repo packages that just got a new version.
+     *
+     * `bumped` maps a package to the version it is being given. What a "reference" looks like is
+     * entirely the ecosystem's: npm has four dependency fields and a `"workspace:"` protocol whose
+     * bare selectors resolve at publish time and must *not* be rewritten; Cargo has `path`
+     * dependencies that carry no version at all. rman only knows that a bump may leave siblings
+     * pointing at the old number.
+     *
+     * Mutates `manifest.raw` in place - the caller writes it out afterwards, in the same pass that
+     * wrote the new version, so there is one file write rather than two.
+     *
+     * Omit it and nothing is rewritten, which is correct for an ecosystem that references siblings
+     * by path.
+     */
+    updateDependencyVersions?(manifest: Manifest, bumped: ReadonlyMap<Package, string>): void;
+}
+/**
+ * The registry, merged onto the `Manifest` interface so one name carries both the shape and the
+ * operations - `Manifest.read(dir)` returns a `Manifest`.
+ *
+ * A namespace rather than loose `addManifestProvider`/`readManifest` functions because a namespace
+ * is what a plugin can *augment*: `declare module 'rman' { namespace Manifest { ... } }` is how
+ * `rman-node` already adds to `SystemInfo`, and anything this seam grows later can arrive the
+ * same way instead of as another top-level export.
+ */
+export declare namespace Manifest {
+    /** Registers a provider. Called by `loadPlugins` for each plugin's `manifest`, in `plugins`
+     *  declaration order - so which one answers is a function of the repository's own config. */
+    function addProvider(provider: ManifestProvider): void;
+    /** For tests, which would otherwise leak a provider into every later case in the process. */
+    function clearProviders(): void;
+    /**
+     * Reads `dir`'s manifest through the first provider that recognizes it, with the scheme that
+     * provider brings.
+     *
+     * **With no provider registered, or none recognizing the directory**, the fallback is a package
+     * named after its own directory at version `0.0.0`. That is deliberately the least it can claim:
+     * the directory name is a fact, and `0.0.0` is the version a thing has when nothing says
+     * otherwise. The alternative - refusing to construct a package at all - would make `rman info` and
+     * `rman list` fail in a repository whose `.rmanrc` simply names no plugin yet, which is exactly
+     * when someone needs to run them.
+     */
+    function read(dir: string): {
+        manifest: Manifest;
+        versionScheme: VersionScheme;
+        fileName: string;
+        provider: string;
+    };
+    /** Writes through whichever provider recognizes `dir`. Throws when none does: a write that lands
+     *  nowhere is worse than one that fails, since the caller has already decided the new version. */
+    function write(dir: string, manifest: Manifest): void;
+    /**
+     * The packages `pkg` declares a dependency on, via whichever provider recognizes it.
+     *
+     * No provider, or one with no opinion, means no declared dependencies - `.rmanrc "dependencies"`
+     * is then the only source, which is exactly right: a repository rman cannot read the manifests
+     * of can still describe its own graph by hand.
+     */
+    function dependenciesOf(pkg: Package, candidates: readonly Package[]): Package[];
+    /** `${{ pkg.scope }}`/`${{ pkg.unscopedName }}`, by whichever provider recognizes `dir` - and
+     *  "no scope, the name is its own unscoped form" when none has an opinion. */
+    function splitName(dir: string, name: string): {
+        scope?: string;
+        unscopedName: string;
+    };
+    /**
+     * Refreshes `pkg`'s references to the packages in `bumped`, via whichever provider recognizes it.
+     *
+     * No provider, or one without an opinion, means nothing to rewrite - a repository whose packages
+     * reference each other by path has nothing here to go stale.
+     */
+    function updateDependencyVersions(pkg: Package, bumped: ReadonlyMap<Package, string>): void;
+    /**
+     * Rewrites a hard-coded version in `content` through `pkg`'s own ecosystem - see
+     * `ManifestProvider.stampVersion`.
+     *
+     * `undefined` covers three cases the caller has to tell apart from each other, and cannot: no
+     * provider claimed the package, the provider has no opinion about stamping, or it looked and found
+     * nothing to change. All three mean "this file was not stamped", which is what `version` reports.
+     */
+    function stampVersion(pkg: Package, file: string, content: string, version: string, options?: {
+        constant?: string;
+    }): string | undefined;
+    /**
+     * What `pkg`'s own ecosystem's registry says its current version is - see
+     * `ManifestProvider.publishedVersion` for the one thing this is for and the one thing it must
+     * never be used for.
+     *
+     * `undefined` when the provider has no opinion, which includes every repository that names no
+     * plugin: git tags then answer the boundary question alone.
+     */
+    function publishedVersion(pkg: Package): Promise<string | undefined>;
+    /** The file names providers look for, for an error message that can say what was expected. */
+    function fileNames(): string[];
+}

package/core/manifest.js

@@ -0,0 +1,150 @@
+import path from 'node:path';
+import { semverScheme } from './version-scheme.js';
+/**
+ * The registry, merged onto the `Manifest` interface so one name carries both the shape and the
+ * operations - `Manifest.read(dir)` returns a `Manifest`.
+ *
+ * A namespace rather than loose `addManifestProvider`/`readManifest` functions because a namespace
+ * is what a plugin can *augment*: `declare module 'rman' { namespace Manifest { ... } }` is how
+ * `rman-node` already adds to `SystemInfo`, and anything this seam grows later can arrive the
+ * same way instead of as another top-level export.
+ */
+export var Manifest;
+(function (Manifest) {
+    /** Registers a provider. Called by `loadPlugins` for each plugin's `manifest`, in `plugins`
+     *  declaration order - so which one answers is a function of the repository's own config. */
+    function addProvider(provider) {
+        if (providers.includes(provider))
+            return;
+        providers.push(provider);
+    }
+    Manifest.addProvider = addProvider;
+    /** For tests, which would otherwise leak a provider into every later case in the process. */
+    function clearProviders() {
+        providers.length = 0;
+    }
+    Manifest.clearProviders = clearProviders;
+    /**
+     * Reads `dir`'s manifest through the first provider that recognizes it, with the scheme that
+     * provider brings.
+     *
+     * **With no provider registered, or none recognizing the directory**, the fallback is a package
+     * named after its own directory at version `0.0.0`. That is deliberately the least it can claim:
+     * the directory name is a fact, and `0.0.0` is the version a thing has when nothing says
+     * otherwise. The alternative - refusing to construct a package at all - would make `rman info` and
+     * `rman list` fail in a repository whose `.rmanrc` simply names no plugin yet, which is exactly
+     * when someone needs to run them.
+     */
+    function read(dir) {
+        for (const provider of providers) {
+            const manifest = provider.read(dir);
+            if (manifest) {
+                return {
+                    manifest,
+                    versionScheme: provider.versionScheme ?? semverScheme,
+                    fileName: provider.fileName,
+                    provider: provider.name,
+                };
+            }
+        }
+        return {
+            manifest: { name: path.basename(dir), version: '0.0.0', raw: {} },
+            versionScheme: semverScheme,
+            /** Nothing was read, so nothing can be named - a caller listing "the file I changed" has no
+             *  file to list, which is correct rather than a placeholder that does not exist. */
+            fileName: '',
+            /** Same reasoning: no provider claimed this directory, so it belongs to no ecosystem. Empty
+             *  rather than a sentinel like `'unknown'`, which would read as an ecosystem's name and could
+             *  collide with a real provider's. */
+            provider: '',
+        };
+    }
+    Manifest.read = read;
+    /** Writes through whichever provider recognizes `dir`. Throws when none does: a write that lands
+     *  nowhere is worse than one that fails, since the caller has already decided the new version. */
+    function write(dir, manifest) {
+        for (const provider of providers) {
+            if (provider.read(dir)) {
+                provider.write(dir, manifest);
+                return;
+            }
+        }
+        throw new Error(`No manifest provider recognizes "${dir}", so there is nowhere to write its version.\n` +
+            `  A repository's ".rmanrc" names its providers - see "plugins" (e.g. ['rman-node']).`);
+    }
+    Manifest.write = write;
+    /**
+     * The packages `pkg` declares a dependency on, via whichever provider recognizes it.
+     *
+     * No provider, or one with no opinion, means no declared dependencies - `.rmanrc "dependencies"`
+     * is then the only source, which is exactly right: a repository rman cannot read the manifests
+     * of can still describe its own graph by hand.
+     */
+    function dependenciesOf(pkg, candidates) {
+        return providerOf(pkg)?.dependencies?.(pkg.manifest, candidates) ?? [];
+    }
+    Manifest.dependenciesOf = dependenciesOf;
+    /** `${{ pkg.scope }}`/`${{ pkg.unscopedName }}`, by whichever provider recognizes `dir` - and
+     *  "no scope, the name is its own unscoped form" when none has an opinion. */
+    function splitName(dir, name) {
+        for (const provider of providers) {
+            if (!provider.read(dir))
+                continue;
+            return provider.splitName?.(name) ?? { unscopedName: name };
+        }
+        return { unscopedName: name };
+    }
+    Manifest.splitName = splitName;
+    /**
+     * Refreshes `pkg`'s references to the packages in `bumped`, via whichever provider recognizes it.
+     *
+     * No provider, or one without an opinion, means nothing to rewrite - a repository whose packages
+     * reference each other by path has nothing here to go stale.
+     */
+    function updateDependencyVersions(pkg, bumped) {
+        providerOf(pkg)?.updateDependencyVersions?.(pkg.manifest, bumped);
+    }
+    Manifest.updateDependencyVersions = updateDependencyVersions;
+    /**
+     * Rewrites a hard-coded version in `content` through `pkg`'s own ecosystem - see
+     * `ManifestProvider.stampVersion`.
+     *
+     * `undefined` covers three cases the caller has to tell apart from each other, and cannot: no
+     * provider claimed the package, the provider has no opinion about stamping, or it looked and found
+     * nothing to change. All three mean "this file was not stamped", which is what `version` reports.
+     */
+    function stampVersion(pkg, file, content, version, options) {
+        return providerOf(pkg)?.stampVersion?.(file, content, version, options);
+    }
+    Manifest.stampVersion = stampVersion;
+    /**
+     * What `pkg`'s own ecosystem's registry says its current version is - see
+     * `ManifestProvider.publishedVersion` for the one thing this is for and the one thing it must
+     * never be used for.
+     *
+     * `undefined` when the provider has no opinion, which includes every repository that names no
+     * plugin: git tags then answer the boundary question alone.
+     */
+    async function publishedVersion(pkg) {
+        return providerOf(pkg)?.publishedVersion?.(pkg);
+    }
+    Manifest.publishedVersion = publishedVersion;
+    /** The file names providers look for, for an error message that can say what was expected. */
+    function fileNames() {
+        return providers.map(p => p.fileName);
+    }
+    Manifest.fileNames = fileNames;
+    const providers = [];
+    /**
+     * The provider that claimed `pkg`, found by the name it reported as `pkg.provider` - exact, and
+     * without re-reading the manifest off disk to work it out again.
+     *
+     * The probe is the fallback, not the rule: it covers a package constructed *before* its provider
+     * was registered, which `Repository.create` cannot produce (plugins load first) but a test
+     * arranging providers by hand can.
+     */
+    function providerOf(pkg) {
+        const byName = pkg.provider ? providers.find(p => p.name === pkg.provider) : undefined;
+        return byName ?? providers.find(p => p.read(pkg.dirname));
+    }
+})(Manifest || (Manifest = {}));

package/core/merge-config.d.ts

@@ -0,0 +1,57 @@
+/** 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 = "+";
+/**
+ * Keys that **append whether or not you ask** - `+plugins` is accepted and means nothing extra.
+ *
+ * `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
+ * commands and seams*, and a repository naming one has no wish to lose the ones its shared config
+ * 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`.
+ *
+ * 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 declare const ALWAYS_APPEND: readonly string[];
+/** `"+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`:
+ *
+ * ```yaml
+ * # the root says          before: "rm ./build"
+ * # a package adds        +before: "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.
+ *
+ * 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.
+ */
+export declare function mergeConfig(target: Record<string, any>, source: Record<string, any>): 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;