rman 1.0.12 → 1.2.1

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,70 @@
+/** 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[];
+/**
+ * Where a value function keeps the value it is replacing, so it can be handed back as `value`.
+ *
+ * A **symbol on a forwarding wrapper**, rather than a class or a `{fn, prev}` object, for one
+ * concrete reason: every walker in this file and in `config.ts` decides what to do by asking
+ * `isPlainObject`, and a wrapper object would answer yes - `finalizeConfig` would rebuild it as a
+ * plain object and lose the function, and `mergeConfig` would try to merge into it key by key. A
+ * function is not a plain object, so it travels through all of them untouched.
+ *
+ * The user's own function is never mutated: two packages inheriting the same shared-config function
+ * would otherwise share - and overwrite - one `prev`.
+ */
+export declare const PREVIOUS_VALUE: unique symbol;
+/** `"+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;

package/core/merge-config.js

@@ -0,0 +1,193 @@
+/** 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 = '+';
+/**
+ * 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 const ALWAYS_APPEND = ['plugins'];
+/**
+ * Where a value function keeps the value it is replacing, so it can be handed back as `value`.
+ *
+ * A **symbol on a forwarding wrapper**, rather than a class or a `{fn, prev}` object, for one
+ * concrete reason: every walker in this file and in `config.ts` decides what to do by asking
+ * `isPlainObject`, and a wrapper object would answer yes - `finalizeConfig` would rebuild it as a
+ * plain object and lose the function, and `mergeConfig` would try to merge into it key by key. A
+ * function is not a plain object, so it travels through all of them untouched.
+ *
+ * The user's own function is never mutated: two packages inheriting the same shared-config function
+ * would otherwise share - and overwrite - one `prev`.
+ */
+export const PREVIOUS_VALUE = Symbol('rman.previousValue');
+/** `"+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`:
+ *
+ * ```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 function mergeConfig(target, source) {
+    // 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. */
+        if (ALWAYS_APPEND.includes(key)) {
+            appendList(target, key, value);
+            continue;
+        }
+        assignMerged(target, key, value);
+    }
+    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);
+            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);
+    }
+    return result;
+}
+function assignMerged(target, key, value) {
+    if (isPlainObject(value)) {
+        if (!isPlainObject(target[key]))
+            target[key] = {};
+        mergeConfig(target[key], value);
+        return;
+    }
+    /**
+     * A function **replaces** like any other value - and remembers what it replaced, so it can be
+     * given it back as `value` when the config resolves:
+     *
+     * ```js
+     * '[*]':      { clean: { include: ({ vars }) => [vars.buildDir] } }
+     * '[ws:*]':   { clean: { include: ({ value, pkg }) => [...value, pkg.basename + '.log'] } }
+     * ```
+     *
+     * Chained here rather than at resolution time because only the merge knows the order of the
+     * 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 (typeof value === 'function') {
+        target[key] = chainValueFn(value, target[key]);
+        return;
+    }
+    target[key] = Array.isArray(value) ? [...value] : value;
+}
+/**
+ * Wraps `fn` so it carries `previous`, leaving `fn` itself alone.
+ *
+ * The wrapper forwards every argument unchanged, which is what lets one rule cover both kinds of
+ * function a config can hold: a **value** function is called by `interpolateConfig` with the config
+ * scope, a **step** function by `RunService` with a `RunStepContext`, and neither needs to know it
+ * has been wrapped. `name` is copied over because a step's label is its function's name.
+ */
+function chainValueFn(fn, previous) {
+    const wrapper = (...args) => fn(...args);
+    Object.defineProperty(wrapper, 'name', { value: fn.name, configurable: true });
+    /** Only when there *is* one: an own property set to `undefined` is indistinguishable from an
+     *  inherited value that genuinely resolved to nothing. */
+    if (previous !== undefined)
+        Object.defineProperty(wrapper, PREVIOUS_VALUE, { value: previous });
+    return wrapper;
+}
+/**
+ * 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
+ * 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.
+ *
+ * By identity (`===`), which covers a string by value and a plugin object by reference; two
+ * *different* objects claiming one plugin name are caught where it counts, at registration - see
+ * `loadPlugins`.
+ */
+function appendList(target, key, value) {
+    const merged = [...toList(target[key] ?? []), ...toList(value)];
+    target[key] = ALWAYS_APPEND.includes(key) ? merged.filter((entry, at) => merged.indexOf(entry) === at) : merged;
+}
+function toList(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/** A config object, as opposed to an array or anything with its own prototype - only the former
+ *  merges key by key. */
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}

package/core/package.d.ts

@@ -1,17 +1,83 @@
 import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import { Manifest } from './manifest.js';
+import type { Repository } from './repository.js';
+import { type VersionScheme } from './version-scheme.js';
 export declare class Package {
     readonly dirname: string;
-    private _json;
-    dependencies: string[];
-    /** Effective rman config for this package, cascaded from the repository root. */
+    /**
+     * This package's identity, read through whichever `ManifestProvider` 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
+     * `publishConfig` off it - but the core only ever touches `name`, `version` and `private`.
+     */
+    manifest: Manifest;
+    /**
+     * In-repo packages this one depends on - **the full transitive closure**, not just its direct
+     * dependencies (see `Repository._updateDependencies`).
+     *
+     * References, not names: a name is only an identifier if the ecosystem guarantees uniqueness,
+     * which npm does and others do not - Go identifies a module by import path, and nothing stops a
+     * repository from holding two packages whose short names collide. A `Package` is unambiguous
+     * 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;
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    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.
+     */
+    parent?: Package;
+    /**
+     * How this package's versions are numbered - `pkg.versionScheme.next(pkg.version, 'minor')`.
+     *
+     * Comes from the same provider that read the manifest, because the ecosystem that decides where
+     * a version is written is the one that decides how it is numbered - a `pyproject.toml` read with
+     * semver's arithmetic would be a pair that never occurs in reality.
+     *
+     * Defaults to semver, so this seam existing changes nothing. **A group must not mix schemes** -
+     * a group is one version line, and comparing across schemes is meaningless; `assertOneScheme`
+     * refuses it rather than acting on whatever falls out.
+     */
+    versionScheme: VersionScheme;
+    /** The file the manifest was read from, absolute - for a command that has to say which file it
+     *  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.
+     *
+     * 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.
+     *
+     * 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 basename(): string;
     get name(): string;
     get version(): string;
-    get json(): any;
-    get jsonFileName(): string;
     get isPrivate(): boolean;
-    reloadJson(): any;
-    writeJson(): void;
+    /** Re-reads from disk - for a command that has just written the manifest itself and wants the
+     *  package to agree with the file again. */
+    reloadManifest(): Manifest;
+    /** Writes the current manifest back through its provider. */
+    writeManifest(): void;
 }

package/core/package.js

@@ -1,44 +1,106 @@
-import fs from 'fs';
 import path from 'path';
+import { Manifest } from './manifest.js';
+import { semverScheme } from './version-scheme.js';
 export class Package {
     dirname;
-    _json;
+    /**
+     * This package's identity, read through whichever `ManifestProvider` 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
+     * `publishConfig` off it - but the core only ever touches `name`, `version` and `private`.
+     */
+    manifest;
+    /**
+     * In-repo packages this one depends on - **the full transitive closure**, not just its direct
+     * dependencies (see `Repository._updateDependencies`).
+     *
+     * References, not names: a name is only an identifier if the ecosystem guarantees uniqueness,
+     * which npm does and others do not - Go identifies a module by import path, and nothing stops a
+     * repository from holding two packages whose short names collide. A `Package` is unambiguous
+     * whatever the ecosystem, and comparing by identity removes a lookup from every consumer.
+     */
     dependencies = [];
-    /** Effective rman config for this package, cascaded from the repository root. */
+    /** Effective rman config for this package, cascaded from the repository root, with every
+     *  `${{ ... }}` expression already evaluated. */
     config = {};
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    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.
+     */
+    parent;
+    /**
+     * How this package's versions are numbered - `pkg.versionScheme.next(pkg.version, 'minor')`.
+     *
+     * Comes from the same provider that read the manifest, because the ecosystem that decides where
+     * a version is written is the one that decides how it is numbered - a `pyproject.toml` read with
+     * semver's arithmetic would be a pair that never occurs in reality.
+     *
+     * Defaults to semver, so this seam existing changes nothing. **A group must not mix schemes** -
+     * a group is one version line, and comparing across schemes is meaningless; `assertOneScheme`
+     * refuses it rather than acting on whatever falls out.
+     */
+    versionScheme = semverScheme;
+    /** The file the manifest was read from, absolute - for a command that has to say which file it
+     *  changed (a commit's path list). Empty when no provider recognized this directory. */
+    manifestFileName;
+    /**
+     * **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.
+     *
+     * 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.
+     *
+     * 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;
     constructor(dirname) {
         this.dirname = dirname;
-        this.reloadJson();
+        const { manifest, versionScheme, fileName, provider } = Manifest.read(dirname);
+        this.manifest = manifest;
+        this.versionScheme = versionScheme;
+        this.manifestFileName = fileName ? path.join(dirname, fileName) : '';
+        this.provider = provider;
     }
     get basename() {
         return path.basename(this.dirname);
     }
     get name() {
-        return this._json.name;
+        return this.manifest.name;
     }
     get version() {
-        return this._json.version;
-    }
-    get json() {
-        return this._json;
-    }
-    get jsonFileName() {
-        return path.join(this.dirname, 'package.json');
+        return this.manifest.version;
     }
     get isPrivate() {
-        return !!this._json.private;
+        return !!this.manifest.private;
     }
-    reloadJson() {
-        const f = this.jsonFileName;
-        if (!fs.existsSync(f)) {
-            throw new Error(`Package.json not found at ${f}`);
-        }
-        this._json = JSON.parse(fs.readFileSync(f, 'utf-8'));
-        return this._json;
+    /** Re-reads from disk - for a command that has just written the manifest itself and wants the
+     *  package to agree with the file again. */
+    reloadManifest() {
+        const { manifest, versionScheme, fileName, provider } = Manifest.read(this.dirname);
+        this.manifest = manifest;
+        this.versionScheme = versionScheme;
+        this.manifestFileName = fileName ? path.join(this.dirname, fileName) : '';
+        this.provider = provider;
+        return this.manifest;
     }
-    writeJson() {
-        const f = this.jsonFileName;
-        const data = JSON.stringify(this._json, undefined, 2);
-        fs.writeFileSync(f, data, 'utf-8');
+    /** Writes the current manifest back through its provider. */
+    writeManifest() {
+        Manifest.write(this.dirname, this.manifest);
     }
 }