rman 1.3.0 → 2.0.0-beta.3

package/utils/version-group.d.ts

@@ -0,0 +1,31 @@
+import type { Package } from '../core/classes/package.js';
+/**
+ * The identity packages are batched by when `version` plans a release - `.rmanrc group`, cascaded
+ * like every unmarked key. `true` (the default) puts a package in the implicit repo-wide group, a
+ * non-empty string joins exactly the packages naming the same one, and `false` makes it a group of
+ * itself.
+ *
+ * **It lives here rather than on the planner because two unrelated things need the same answer.**
+ * `VersionPlanService.resolveGroupKey` batches the plan with it; `ChangeHashService.tagPattern`
+ * asks how many lines the repository releases along, which decides whether a repo-wide tag can
+ * name a release at all. Two copies of five lines would be easy to write and impossible to keep in
+ * step, and the failure they would produce is silent - a boundary computed under one answer and a
+ * tag written under the other.
+ *
+ * `resolveGroupKey` stays `protected` and delegates here, so a planner can still override the
+ * batching; what it cannot do is leave the tag pattern behind, which is the point.
+ */
+export declare function groupKeyOf(pkg: Package): string;
+/**
+ * How many distinct version lines this package's repository releases along - 1 when every package
+ * moves together, more once anything is grouped apart.
+ *
+ * **Structural, exactly like `usesCalendarVersion`'s group count**, and for the same reason: two
+ * lines can hold the same number today and diverge tomorrow, so reading the versions would move
+ * the answer under the repository's feet.
+ *
+ * `1` for a package belonging to no repository yet - a bare `new Package(dir, app)`, which the test
+ * fixtures build. One line is the answer that changes nothing, which is what an unknown should
+ * resolve to here.
+ */
+export declare function versionLineCount(pkg: Package): number;

package/utils/version-group.js

@@ -0,0 +1,43 @@
+/**
+ * The identity packages are batched by when `version` plans a release - `.rmanrc group`, cascaded
+ * like every unmarked key. `true` (the default) puts a package in the implicit repo-wide group, a
+ * non-empty string joins exactly the packages naming the same one, and `false` makes it a group of
+ * itself.
+ *
+ * **It lives here rather than on the planner because two unrelated things need the same answer.**
+ * `VersionPlanService.resolveGroupKey` batches the plan with it; `ChangeHashService.tagPattern`
+ * asks how many lines the repository releases along, which decides whether a repo-wide tag can
+ * name a release at all. Two copies of five lines would be easy to write and impossible to keep in
+ * step, and the failure they would produce is silent - a boundary computed under one answer and a
+ * tag written under the other.
+ *
+ * `resolveGroupKey` stays `protected` and delegates here, so a planner can still override the
+ * batching; what it cannot do is leave the tag pattern behind, which is the point.
+ */
+export function groupKeyOf(pkg) {
+    const g = pkg.config?.group;
+    if (g === false)
+        return `solo:${pkg.name}`;
+    if (typeof g === 'string' && g)
+        return `named:${g}`;
+    return 'default';
+}
+/**
+ * How many distinct version lines this package's repository releases along - 1 when every package
+ * moves together, more once anything is grouped apart.
+ *
+ * **Structural, exactly like `usesCalendarVersion`'s group count**, and for the same reason: two
+ * lines can hold the same number today and diverge tomorrow, so reading the versions would move
+ * the answer under the repository's feet.
+ *
+ * `1` for a package belonging to no repository yet - a bare `new Package(dir, app)`, which the test
+ * fixtures build. One line is the answer that changes nothing, which is what an unknown should
+ * resolve to here.
+ */
+export function versionLineCount(pkg) {
+    const repository = pkg.repository;
+    const packages = repository?.packages;
+    if (!packages?.length)
+        return 1;
+    return new Set(packages.map(groupKeyOf)).size;
+}

package/utils/version-stamp.d.ts

@@ -29,7 +29,7 @@ export declare function stampVersionLabel(content: string, version: string): str
  * ```
  *
  * **A helper, not a policy**: which shape a language declares a version in is
- * `ManifestProvider.stampVersion`'s answer, and this is the one most of them share, exported so
+ * `Plugin.stampVersion`'s answer, and this is the one most of them share, exported so
  * every provider need not re-derive the same regex. Measured, it reaches a Go `const version =
  * "…"`, a Gradle/TOML `version = "…"` and a JS/TS `const version = '…'`.
  *

package/utils/version-stamp.js

@@ -51,7 +51,7 @@ export function stampVersionLabel(content, version) {
  * ```
  *
  * **A helper, not a policy**: which shape a language declares a version in is
- * `ManifestProvider.stampVersion`'s answer, and this is the one most of them share, exported so
+ * `Plugin.stampVersion`'s answer, and this is the one most of them share, exported so
  * every provider need not re-derive the same regex. Measured, it reaches a Go `const version =
  * "…"`, a Gradle/TOML `version = "…"` and a JS/TS `const version = '…'`.
  *

package/commands/changed.command.d.ts

@@ -1,3 +0,0 @@
-import type { Argv } from 'yargs';
-import type { Repository } from '../core/repository.js';
-export declare function initCli(repository: Repository, program: Argv): void;

package/commands/changed.command.js

@@ -1,29 +0,0 @@
-import colors from 'ansi-colors';
-import { VersionPlanService } from '../services/version-plan.service.js';
-import { applyPackageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
-export function initCli(repository, program) {
-    program.command({
-        command: 'changed',
-        describe: 'Shows which packages the next "version" run would bump, without changing anything',
-        builder: cmd => applyPackageFilterOptions(cmd).example('$0 changed', '').example('$0 changed --json', '').option('json', {
-            alias: 'j',
-            describe: 'Print output as JSON',
-            type: 'boolean',
-        }),
-        handler: async (args) => {
-            const plan = await VersionPlanService.getPlanner().getPlan(repository, readPackageFilterOptions(args));
-            const changed = plan.filter(e => e.status === 'bump');
-            if (args.json) {
-                console.log(JSON.stringify(changed.map(e => ({ name: e.package.name, group: e.group, from: e.from, to: e.to, reason: e.reason })), undefined, 2));
-                return;
-            }
-            if (!changed.length) {
-                console.log(colors.gray('Nothing has changed.'));
-                return;
-            }
-            for (const e of changed) {
-                console.log(colors.green('changed'), colors.cyan(e.package.name), colors.gray(`(${e.group})`), e.from, '->', colors.yellow(e.to));
-            }
-        },
-    });
-}

package/core/config.d.ts

@@ -1,409 +0,0 @@
-import path from 'path';
-import semver from 'semver';
-import type { RmanConfig } from '../interfaces/rman-config.interface.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).
- */
-export declare function readDirConfig(dirname: string): 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.
- *
- * `packageName` is what selectors match against; without it, selector blocks contribute nothing at
- * all. The root package passes its own, since `"[/]"` speaks to it.
- */
-export declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, RmanConfig>, packageName?: string): Promise<RmanConfig>;
-/** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[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 read by `rman-node`, 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 `ManifestProvider`), 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 `${{ ... }}` 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** (`${{ publish.directory }}`,
- * `${{ 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 ${{ publish.directory }}/"
- * ```
- *
- * 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[];
-}
-export declare function interpolateConfig<T>(config: T, scope: ConfigScope, options?: InterpolateOptions): 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.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. `plugins` is the only one, and it has to be here: an entry may be the plugin *object*
- * itself, and an `RmanPlugin` is almost entirely functions - `manifest.read`, `workspace.resolve`,
- * `versionPlanner`, `binPaths`, and every command's `builder` and `handler`.
- *
- * Measured, and it is why this exists: with `plugins` walked like any other key, resolving the
- * config of a repository that named a plugin called that plugin's yargs builder with the config
- * scope - `Config function in "plugins[0].commands[0].builder" failed: cmd.option is not a
- * function`. A `plugins` entry is loaded by `loadPlugins`, never read as a setting.
- */
-export declare const CODE_SUBTREES: string[];
-/** 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;