rman 2.0.0-beta.2 → 2.0.0-beta.4

package/core/config.d.ts

@@ -1,530 +0,0 @@
-import path from 'path';
-import semver from 'semver';
-import type { RmanConfig } from '../interfaces/rman-config.interface.js';
-import { type DetectedBuiltin } from '../plugins/detect.js';
-import type { RunConditionFn, RunStepFn } from './run-step.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
- * unchanged; this exists purely so TypeScript can infer/check against `RmanConfig`, not for any
- * runtime behavior:
- *
- *   // .rmanrc.mjs
- *   import { defineConfig } from 'rman';
- *   export default defineConfig({ packageManager: 'pnpm' });
- *
- *   // .rmanrc.cjs
- *   const { defineConfig } = require('rman');
- *   module.exports = defineConfig({ packageManager: 'pnpm' });
- */
-export declare function defineConfig(config: RmanConfig): RmanConfig;
-/**
- * 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 declare function readDirConfig(dirname: string, options?: {
-    inject?: DetectedBuiltin;
-}): Promise<RmanConfig>;
-/**
- * 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:
- *
- * - **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 declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, RmanConfig>, selector?: string, 
-/** 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?: DetectedBuiltin): Promise<RmanConfig>;
-/** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[pkg-a]"`. The
- *  brackets are what keep this space from colliding with real config keys - no setting starts with
- *  one - and in YAML they also mean the key always needs quoting (`"[*]":`), since a bare `[*]`
- *  parses as a flow sequence. */
-export declare function isSelectorKey(key: string): boolean;
-/**
- * **Which packages a selector speaks for.** Two audiences, and the second is a glob:
- *
- * | | |
- * | --- | --- |
- * | `"[/]"` | 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.
- *
- * **The root is never selected by name, and that one rule removes two traps.** A glob matches
- * package names, and the root is nobody's child - so `"[my-*]"` cannot quietly pick up a repository
- * whose root package happens to be called `my-repo`, and `"[*]"` cannot hand a package-shaped
- * setting to a root that has no build directory to apply it to. The root is addressed structurally
- * or not at all.
- *
- * **`"[ws:*]"` / `"[workspace:*]"` is accepted and means exactly `"[*]"`.** The qualifier existed to
- * say "not the root" back when a bare glob included it; the shape of the set says that now, so it
- * has nothing left to add. Accepted rather than rejected because the two spellings resolve to the
- * same packages - an error would be friction with no reader to protect.
- */
-export declare function parseSelector(key: string): {
-    scope: 'root' | 'package';
-    test: (name: string) => boolean;
-};
-/** 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 declare function selectorToRegExp(key: string): RegExp;
-/** One package, as an expression sees it - the same shape for the package the config belongs to
- *  and for the repository itself, so `${{ repository.basename }}` reads the way `${{ pkg.basename }}` does. */
-/**
- * `file` in a `${{ ... }}` expression: what is actually on disk, resolved against **the package
- * the config was resolved for** - so one declaration in a `"[*]"` block asks each package about
- * its own directory.
- *
- * The pair exists because a config has two different questions about a path, and answering both
- * with one function would mean picking a wrong default for the other:
- *
- * ```yaml
- * "[*]":
- *   run:
- *     build:
- *       # first of these that exists, and an error naming the config path if none do
- *       exec: 'tsc -b ${{ file.exists("tsconfig-build.json") || file.resolve("tsconfig.json") }}'
- * ```
- *
- * **Every member asks a question, and none may ever change anything - no `copy`, no `write`, no
- * `mkdir`.** Not a matter of taste: this is evaluated when the config *resolves*, which every
- * command does, so a member that acted would act on `rman list`, `rman info` and `rman config`.
- *
- * That has been tried, in the only way a missing function can be: a shared config reaching for a
- * `file.copyMany(...)` that does not exist made **every** rman command exit 1 - and had it existed,
- * the quieter outcome would have been files copied by `rman list`. Work belongs in a step
- * (`run.<script>`'s slots, `version`'s hooks), which is the one place rman runs anything, and a
- * step can now be a function - so there is nothing this would enable that is not already possible
- * at the right moment.
- */
-export interface FileScope {
-    /**
-     * The absolute path if it exists, **`''` if it does not** - so `a || b || c` picks the first one
-     * present, and so a miss never reaches the "nullish inside a string" guard that `undefined` would
-     * trip. Accepts a relative path (against the package directory) or an absolute one.
-     *
-     * It returns a path rather than a boolean on purpose: the caller almost always wants the path,
-     * and a separate `file.path()` to fetch it after a boolean test would read the disk twice and
-     * invite the two calls to disagree.
-     */
-    exists(target: string): string;
-    /** The absolute path, or **throws** - for a file whose absence is a mistake rather than a case to
-     *  handle. The error names the config path holding the expression, like any other. */
-    resolve(target: string): string;
-    /**
-     * The first of several that exists, or **throws** naming every candidate it tried:
-     *
-     * ```yaml
-     * exec: 'tsc -b ${{ file.resolveFirst("tsconfig-build.json", "tsconfig.build.json", "tsconfig.json") }}'
-     * ```
-     *
-     * The same thing an `exists() || exists() || resolve()` chain does, said once - and it cannot be
-     * got subtly wrong the way that chain can: ending it in `exists()` leaves `tsc -b ` with no
-     * argument when nothing matches, and tsc then silently falls back to the directory's default
-     * rather than reporting that the package has no build config.
-     */
-    resolveFirst(...targets: string[]): string;
-}
-export interface PackageScope {
-    /** The package's own name, scope included (`@sqb/builder`). */
-    name: string;
-    /** Just the scope (`@sqb`), or `undefined` for an unscoped package. */
-    scope: string | undefined;
-    /** The name with its scope stripped (`builder`). */
-    unscopedName: string;
-    version: string;
-    /** The package directory's last segment (`builder`) - not always the same as `unscopedName`,
-     *  which is why both exist, and usually what a sibling path (`../../coverage/builder`) is keyed on. */
-    basename: string;
-    /** Absolute path to the package's own directory - named as rman's own `Package.dirname` is. */
-    dirname: string;
-    /** That directory relative to the repository root (`packages/builder`), which is what a command
-     *  addressing another package from the root usually needs. Empty string for the root itself. */
-    relativeDir: string;
-    /**
-     * Which ecosystem this package belongs to - `'node'` for one the `node` built-in read, empty when no
-     * plugin claimed it. The same `Package.provider`, so one declaration can address a single
-     * ecosystem in a polyglot repository (`if: "${{ pkg.provider === 'node' }}"`).
-     */
-    provider: string;
-    /**
-     * The whole manifest, as a copy - so an expression can reach a field rman itself has no opinion
-     * about (`${{ pkg.manifest.engines.node }}`).
-     *
-     * Named `manifest`, not `json`: which file a package's identity lives in is the ecosystem's
-     * business now (see `Plugin`'s manifest members), and `json` was that assumption showing through the one
-     * remaining user-facing name. A config written against `${{ pkg.json... }}` needs the rename.
-     */
-    manifest: Record<string, unknown>;
-    /**
-     * The version this run is about to write - **bound only during `version`**, and only once its
-     * plan is computed. Reading it anywhere else throws rather than yielding `undefined`: no other
-     * command has a target version, so an expression asking for one has been put in the wrong place,
-     * and a config that quietly evaluates to "undefined" is the failure this evaluator exists to
-     * prevent.
-     */
-    targetVersion: string;
-}
-/** Facts about the repository, on top of the root package's own - because the repository root *is*
- *  a package (`repository.name` is what its `package.json` says, `repository.basename` the directory
- *  it sits in, and the two genuinely differ). Sharing `PackageScope`'s shape is what makes
- *  `repository.version` read the way `pkg.version` does. */
-export interface RepositoryScope extends PackageScope {
-    monorepo: boolean;
-    /** Every package in the repository - the root included only when it *is* the one package. */
-    packages: PackageScope[];
-    /** One package by name, or `undefined` - for reaching a sibling's directory. */
-    package(name: string): PackageScope | undefined;
-}
-export interface GitScope {
-    branch: string | undefined;
-    sha: string | undefined;
-    shortSha: string | undefined;
-    /** Whether the working tree has uncommitted changes. */
-    dirty: boolean | undefined;
-}
-/**
- * What a **value function** is handed - `clean: { include: ({ value, pkg }) => [...] }`.
- *
- * The same scope a `${{ }}` expression sees, plus `value`. There is no asymmetry between the two
- * spellings and that is an invariant with a spec on it: the argument *is* the expression context
- * with `value` on it, so a member defined straight onto the argument would split them silently and
- * a config author would meet a name that works in one spelling and not the other.
- *
- * **The config's own top-level keys are bound bare too**, and they cannot be typed here - they come
- * from the config being interpolated rather than from this object. Reach them through `pkg.config`
- * when a type matters, or accept `any` from the bare name.
- *
- * **Not what a *step* function is handed.** `run.<script>.exec` and `version.<slot>` take a
- * `RunStepFn`, which gets a `RunStepContext` (`pkg`, `repository`, `cwd`, `runBin`, `logger`) when
- * its turn comes - a different object at a different time, which is the whole distinction the two
- * forms exist to draw. Never widen a step key to accept this one.
- */
-export interface ConfigValueContext extends ConfigScope {
-    /**
-     * What this key resolved to in the layers **below** this one - the list form of it, so
-     * `[...value, 'x']` needs no guard. `any` rather than a generic: the key's own type is what the
-     * function must return, while `value` is whatever the layers underneath happened to produce, and
-     * a scalar underneath arrives as a one-element list. See `previousValue`.
-     */
-    value: any;
-    /** The config's own top-level keys, bound bare - `vars`, `publish`, `clean`, … */
-    [key: string]: any;
-}
-/**
- * A config value that may be **written as a function instead**, computed per package at the moment
- * the config resolves.
- *
- * `T` is what the function has to return, so the same checking applies either way - measured, with
- * a control: a typo inside a wrapped object is still caught, and so is one inside an object a value
- * function *returns*.
- *
- * **Not for a step key.** `run.<script>.before`/`.exec`/`.after`, `run.<script>.if` and
- * `version.<slot>` already take a function, and it means something else there - code for `run` to
- * call in its own time, with its own context. Wrapping one of those would produce a type that
- * accepts a value function where a step is what actually runs. The key path decides which a
- * function is (`STEP_PATHS`, `CODE_SUBTREES`), and the type can only follow that split by hand.
- */
-export type ConfigValue<T> = T | ((ctx: ConfigValueContext) => T);
-/**
- * The same config **after** it resolves: every `ConfigValue<T>` is just `T`, because
- * `interpolateConfig` has already called it.
- *
- * **This is the half that lets `RmanConfig` be the author's type.** One type cannot answer both
- * "what may I write?" (a function is fine - rman calls it) and "what do I get?" (never a function -
- * it was already called), so it used to answer only the second, and writing a value function was a
- * compile error the docs themselves committed. Widening `RmanConfig` alone just moves the problem:
- * measured, six read sites needed a cast. The author's type widens and the *reader's* is computed
- * from it - one derived type, applied at `Package.config`, rather than a second one to keep in step
- * by hand.
- *
- * **Two guards, and each was measured by leaving it out.**
- *
- * - **Steps are named first.** A value function is recognised by its parameter, and
- *   `ConfigValueContext` carries an index signature - so `RunStepFn` is assignable to it and a
- *   `run.build.exec` function collapsed to its *return type*, leaving `RunService` nothing to call.
- * - **`CODE_SUBTREES` is skipped, at every level.** `plugins`/`commands`/`publishTargets` hold code
- *   all the way down, and the selector index (`[selector]: RmanConfig`) re-enters the config, so a
- *   top-level-only guard misses the copy inside a `"[*]"` block. Left out, the walk reached
- *   `Plugin.manifestProvider.versionScheme` and rewrote its **methods**: `smallestBump(): string`
- *   became `string`, `bumpFor`/`isValid`/`compare`/`next` became `{}`. A function with *fewer*
- *   parameters is assignable to one with more, so a zero-argument method matches the value-function
- *   pattern - which makes this transform unsafe over any object carrying methods, and the guard the
- *   only thing keeping one out of its way.
- *
- * Both lists are the runtime's own (`STEP_PATHS`' function types, `CODE_SUBTREES` itself), so the
- * type follows the rule rather than restating it - the drift `ScopedVars` already demonstrated is
- * not available here.
- */
-export type Resolved<T> = T extends RunStepFn | RunConditionFn ? T : T extends (ctx: ConfigValueContext) => infer R ? R : T extends object ? {
-    [K in keyof T]: K extends CodeSubtree ? T[K] : Resolved<T[K]>;
-} : T;
-/** `pkg.config`'s type: what every command reads, with the value functions already called. */
-export type ResolvedConfig = Resolved<RmanConfig>;
-/**
- * What a `${{ ... }}` expression can see - the bindings of the fresh global it is evaluated in.
- * Namespaced rather than a flat bag of loose names: one obvious place per fact, and room to add
- * helpers to `pkg`/`repository` later without crowding the global.
- *
- * Alongside these, **the config's own top-level keys are bound bare** (`${{ changelog.filePath }}`,
- * `${{ clean.include }}`) - see `interpolateConfig`. They are not listed here because they come
- * from the config being interpolated, not from this object; a name here wins over a config key of
- * the same name.
- *
- * **Trap: bare `${{ version }}` is the `version` *options block*, not the package's version
- * string** - that is `${{ pkg.version }}`. Same word, two different things, and the plain one
- * belongs to the config because every other config key is reachable that way.
- */
-export interface ConfigScope {
-    /** The package the config was resolved for - which is what lets one declaration at the root
-     *  still say something package-specific. */
-    pkg: PackageScope;
-    repository: RepositoryScope;
-    /** Paths, resolved against the package the config was resolved for. */
-    file: FileScope;
-    /**
-     * The **contents** of a structured file - `${{ read('tsconfig.json').compilerOptions.outDir }}` -
-     * where `file` answers only where one is. Resolved against `pkg.dirname` like `file`, so a
-     * `"[*]"` block asks each package about its own; a repository-level file is reached through
-     * `read(path.join(repository.dirname, ...))`.
-     *
-     * `.json`, `.yml`/`.yaml` and `.ini` by extension, or name it for a file that does not say
-     * (`read('.npmrc', 'ini')`). **Throws** when the file is absent, as `file.resolve` does - compose
-     * with `file.exists` when its absence is a case to handle.
-     *
-     * **A manifest is `pkg.manifest`, not this.** `read('package.json')` works and is the wrong
-     * answer: which file a package's identity lives in belongs to the ecosystem, so that expression
-     * is already wrong in a Cargo package sitting beside a Node one.
-     *
-     * The result is **deeply frozen and shared** - see `readStructuredFile`. Spread it to change it.
-     */
-    read: ReadFile;
-    env: Record<string, string | undefined>;
-    /** rman's own `semver`, for the arithmetic every release config eventually wants
-     *  (`semver.major(pkg.version)`). */
-    semver: typeof semver;
-    /**
-     * Node's own `node:path` - `${{ path.join(pkg.dirname, 'LICENSE') }}`, rather than gluing
-     * strings with `+ "/" +` and getting a double separator or none.
-     *
-     * The platform's flavour, not `path.posix`, so a joined path is the one the shell on *this*
-     * machine understands; `path.posix` and `path.win32` are reachable through it when a config
-     * genuinely needs one of them (a Docker image path, say, which is always posix).
-     */
-    path: typeof path;
-    /**
-     * The checkout: branch, sha, whether the tree is dirty.
-     *
-     * **Top level, not `repository.git`** - which is where it used to be, and the move is the point.
-     * `repository` shares its shape with `pkg` because the repository root *is* a package, and its
-     * only other members (`monorepo`, `packages`, `package()`) say something about the repository as
-     * a container of packages. A branch name says nothing about any package; it describes the
-     * working tree every one of them happens to be sitting in - the same kind of ambient fact as
-     * `env`, and it belongs beside it.
-     *
-     * **Read from git only if an expression actually asks**, then remembered for the whole run: every
-     * command resolves config, and a repository that never mentions git must not pay for one. See
-     * `Repository.configScope` for the getter, and `interpolateConfig` for why the context is built
-     * from property descriptors rather than a spread - a spread would fire this getter on every
-     * command, which is exactly what moving it up here risked.
-     */
-    git: GitScope;
-}
-/**
- * Evaluates every `${{ ... }}` expression in **every** string value of a resolved config, against
- * the package it was resolved for:
- *
- * ```yaml
- * "[*]":
- *   clean:
- *     include: ["build", "../../coverage/${{ pkg.basename }}"]
- *   publish:
- *     directory: build
- *     docker:
- *       image: "panates/${{ pkg.basename }}:${{ semver.major(pkg.version) }}"
- *   run:
- *     build:
- *       # the config's own keys are in scope, so this is not a second copy of "build"
- *       after: "cp README.md ${{ changelog.filePath }}/"
- * ```
- *
- * Every string, with no list of "interpolated keys" to memorize - a rule with exceptions is a rule
- * nobody remembers.
- *
- * The contents are **real JavaScript**, not a template mini-language, so there is no growing list
- * of substitutions to keep adding (`{{major}}`, `{{scope}}`, ...) - see `ConfigScope` for what is
- * in scope.
- *
- * **`${{ }}`, deliberately not `{{ }}`.** A config value may legitimately carry `{{...}}` meant for
- * something else entirely (`helm template --set tag={{.Values.tag}}`); with the plainer delimiter
- * rman would try to evaluate it. To emit a literal, let an expression produce it, the way GitHub
- * Actions does: `${{ '${{' }}`.
- *
- * A string that is *nothing but* one expression keeps the value's own type (`"${{ pkg.private }}"`
- * -> a boolean), since otherwise this could only ever produce strings and settings like
- * `run.<script>.skip` would be unreachable. Embedded in surrounding text it is stringified.
- *
- * Evaluation happens in a fresh V8 context holding only the scope's bindings. That is a clean
- * scope, **not a sandbox** - `node:vm` is explicitly not a security mechanism, and no sandbox is
- * called for here anyway: a `.rmanrc` that can say `exec: "..."` already runs arbitrary shell, so
- * the expression evaluator adds no trust boundary that wasn't already wide open.
- *
- * A failing expression throws with the config path that holds it, rather than being left in place:
- * silently passing through a mistake is how a config ends up quietly doing nothing.
- */
-export interface InterpolateOptions {
-    /** Config paths to leave entirely untouched - `DEFERRED_PATHS`, when the whole config is walked. */
-    skip?: string[];
-    /** Where `config` sits in the whole config, for a caller interpolating a fragment. */
-    at?: string[];
-}
-/**
- * **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 declare function interpolateConfig<T>(config: T, scope: ConfigScope, options?: InterpolateOptions): Resolved<T>;
-/**
- * Config paths left untouched when a repository's config is first resolved, and evaluated only by
- * the command that runs them.
- *
- * `version`'s own hooks are the one place `${{ pkg.targetVersion }}` makes sense, and the version
- * being written is not known until `version` has computed its plan - long after the config was
- * resolved. Evaluating these eagerly would throw while merely *loading* the repository, so any
- * command at all would fail on a config that mentions it.
- */
-export declare const DEFERRED_PATHS: string[];
-/**
- * Paths whose value is a **step** - something to run later - rather than a setting to compute now.
- * `*` matches one path segment (`run.<script>.exec`).
- *
- * This is what tells a step function from a value function, and the two live side by side in one
- * config:
- *
- * ```js
- * '[*]': {
- *   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.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:
- * guessing wrong here means running build-time code while merely loading the repository, or
- * silently never running it.
- *
- * A **string** at one of these paths is still interpolated - `exec: 'tsc -b ${{ file.resolve(...) }}'`
- * has to keep working - so this is narrower than `DEFERRED_PATHS`, which skips its paths entirely.
- */
-export declare const STEP_PATHS: string[];
-/**
- * Keys whose **whole subtree** is code rather than config, so no function under them is a value to
- * 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 declare const CODE_SUBTREES: readonly ["plugins", "commands", "publishTargets"];
-/** The `file` namespace for one package's directory - see `FileScope`. */
-/**
- * `read` in a `${{ ... }}` expression (and in a value function): a structured file's **contents**,
- * parsed - where `file` answers only where a path is.
- *
- * ```yaml
- * "[*]":
- *   run:
- *     build:
- *       exec: 'tsc --outDir ${{ read("tsconfig.json").compilerOptions.outDir }}'
- * ```
- *
- * `cache` is shared across every package (see `Repository.configScope`) and keyed by what the file
- * *is*, not merely where - so the same file read by twenty packages is parsed once, and a file rman
- * itself rewrites mid-run is re-read rather than remembered. See `readStructuredFile`.
- */
-export declare function createReadScope(dirname: string, cache: Map<string, CachedFile>): ReadFile;
-/**
- * What `read` can parse.
- *
- * **`.env` is deliberately absent, and that is the durable part of this list**: `env` is already in
- * scope, and a `.env` file exists to be loaded *into* an environment by something else - a config
- * reading one as data would mean two different things called the environment.
- *
- * Nothing else is excluded on principle. `xml` arrived because a `pom.xml` or a `.csproj` holds a
- * version exactly the way a `package.json` does, and rman is language-agnostic; the earlier line
- * ("no new parsers") did not survive it, since xmldom *is* a new one.
- */
-export type FileFormat = 'json' | 'yaml' | 'ini' | 'xml';
-/** `read(path)`, or `read(path, 'ini')` for a file whose name does not say what it is (`.npmrc`). */
-export type ReadFile = (target: string, format?: FileFormat) => unknown;
-/** One parsed file, kept against the identity of the bytes it came from - see `readStructuredFile`. */
-export interface CachedFile {
-    /** `mtimeNs:size`. */
-    stamp: string;
-    value: unknown;
-}
-export declare function createFileScope(dirname: string): FileScope;
-/** The `CODE_SUBTREES` entries as a type, so the runtime list and `Resolved`'s guard cannot name
- *  different keys. */
-type CodeSubtree = (typeof CODE_SUBTREES)[number];
-export {};