rman 1.0.12 → 1.2.1

package/core/plugin.d.ts

@@ -0,0 +1,112 @@
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import { RunService } from '../services/run.service.js';
+import { VersionPlanService } from '../services/version-plan.service.js';
+import { BinPath } from '../utils/bin-path.js';
+import type { CustomCommand, LoadedCommand } from './custom-command.js';
+import { type ManifestProvider } from './manifest.js';
+import { Workspace } from './workspace.js';
+/** The `.rmanrc` key naming plugin packages to load. */
+export declare const PLUGINS_KEY = "plugins";
+/**
+ * What a plugin package hands rman.
+ *
+ * An object rather than a bare array of commands, for the reason `CommandContext` is one: a plugin
+ * will eventually contribute more than commands (config defaults, publish targets, a package
+ * provider for a non-Node repository), and nothing written against this should have to change when
+ * it does.
+ */
+export interface RmanPlugin {
+    /** For error messages and `--help` grouping. Conventionally the package's own name. */
+    name: string;
+    commands?: CustomCommand[];
+    /**
+     * Where `run` can find a package's steps besides its `.rmanrc` - `rman-node` contributes
+     * `package.json#scripts` here, with npm's `pre`/`post` lifecycle.
+     *
+     * Registered in `plugins` declaration order, and only for plugins the repository actually named:
+     * what a script resolves to is then a function of the config rather than of what happened to be
+     * imported.
+     */
+    runSteps?: RunService.StepSource;
+    /**
+     * How this ecosystem's repositories are laid out - `rman-node` reads `workspaces` from the root
+     * `package.json` here.
+     *
+     * Loaded **before any package is known**, since this is what finds them: `Repository.create`
+     * reads the root config, loads the plugins it names, and only then asks. A repository naming no
+     * plugin therefore has no packages beyond itself.
+     */
+    workspace?: Workspace.Provider;
+    /**
+     * Where a package's name and version are written, and how it is numbered - `rman-node`
+     * contributes `package.json` here.
+     *
+     * Registered before any package is constructed, since `Package` reads through it. A repository
+     * naming no plugin therefore gets packages named after their own directories at version
+     * `0.0.0` - see `readManifest`.
+     */
+    manifest?: ManifestProvider;
+    /**
+     * How a release is planned - which packages have changed since their last release and what
+     * version each gets. `rman-node` contributes `NodeVersionPlanService` here.
+     *
+     * **`VersionPlanService` is abstract, so `version`/`changed` do not work without one** (they fail
+     * naming this key). Unlike `manifest` and `workspace`, which degrade to honest defaults, a plan is
+     * either right or it quietly releases the wrong set of packages - see `VersionPlanService`.
+     *
+     * Consulted when a command asks, not at load time, so this is declared and nothing else has to
+     * happen as the plugin's module is imported.
+     */
+    versionPlanner?: VersionPlanService;
+    /**
+     * Where this ecosystem keeps a repository's locally installed executables - `rman-node`
+     * contributes npm's `node_modules/.bin`, walked up the directory chain.
+     *
+     * Prepended to PATH for every `exec`/`runBin` child process, so a command an author wrote runs
+     * against the repository's own pinned tools. **Every plugin's entries are used**, not just the
+     * first - see `BinPath`.
+     */
+    binPaths?: BinPath.Provider;
+}
+/**
+ * Identity helper for authoring a plugin with full type-checking - the `defineConfig`/
+ * `defineCommand` pattern again, for the same reason. Returns `plugin` unchanged.
+ *
+ * **A plugin package's entry point exports a *config*, not this**, so that a package is an
+ * `.rmanrc` like any other and can carry a second plugin later without changing shape:
+ *
+ * ```js
+ * // rman-node's entry point
+ * import { defineConfig, definePlugin } from 'rman';
+ * import publishCommand from './commands/publish.js';
+ *
+ * export const nodePlugin = definePlugin({ name: 'rman-node', commands: [publishCommand] });
+ * export default defineConfig({ plugins: [nodePlugin] });
+ * ```
+ *
+ * **A module exporting the plugin itself is refused**, with a message saying so. Accepting both
+ * would mean telling a plugin from a config at runtime, and `name` is a key either may have - the
+ * test would be a guess, and guessing "plugin" registers nothing while reporting success.
+ */
+export declare function definePlugin(plugin: RmanPlugin): RmanPlugin;
+/**
+ * Loads every plugin the repository's `.rmanrc "plugins"` declares, in declaration order.
+ *
+ * This is what lets a *package* contribute commands. `.rman/*.mjs` covers one repository's own
+ * commands (see `loadCustomCommands`); a plugin covers a whole class of repository - `rman-node`
+ * carrying everything that only means something because the repository is a Node one, so rman's
+ * core does not have to.
+ *
+ * An entry is a package name, a path, or a plugin object - and a named package's entry point
+ * exports a **config**, whose own `plugins` are then loaded the same way (see `loadInto`).
+ *
+ * Names resolve relative to the repository root's own `node_modules`, the way `extends` resolves -
+ * a plugin is the repository's dependency, not rman's.
+ *
+ * **A plugin that cannot be loaded throws**, unlike a broken `.rman/*.mjs` file, which is warned
+ * about and skipped. The two differ because the consequence does: a skipped local command affects
+ * only itself, while a missing plugin silently removes commands the repository is built around -
+ * `rman publish` would simply not exist, and "not a known command" sends the reader looking in the
+ * wrong place entirely.
+ */
+export declare function loadPlugins(rootDir: string, rootConfig: RmanConfig): Promise<LoadedCommand[]>;

package/core/plugin.js

@@ -0,0 +1,189 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { RunService } from '../services/run.service.js';
+import { VersionPlanService } from '../services/version-plan.service.js';
+import { BinPath } from '../utils/bin-path.js';
+import { Manifest } from './manifest.js';
+import { resolveConfigTarget } from './resolve-target.js';
+import { Workspace } from './workspace.js';
+/** The `.rmanrc` key naming plugin packages to load. */
+export const PLUGINS_KEY = 'plugins';
+/**
+ * Identity helper for authoring a plugin with full type-checking - the `defineConfig`/
+ * `defineCommand` pattern again, for the same reason. Returns `plugin` unchanged.
+ *
+ * **A plugin package's entry point exports a *config*, not this**, so that a package is an
+ * `.rmanrc` like any other and can carry a second plugin later without changing shape:
+ *
+ * ```js
+ * // rman-node's entry point
+ * import { defineConfig, definePlugin } from 'rman';
+ * import publishCommand from './commands/publish.js';
+ *
+ * export const nodePlugin = definePlugin({ name: 'rman-node', commands: [publishCommand] });
+ * export default defineConfig({ plugins: [nodePlugin] });
+ * ```
+ *
+ * **A module exporting the plugin itself is refused**, with a message saying so. Accepting both
+ * would mean telling a plugin from a config at runtime, and `name` is a key either may have - the
+ * test would be a guess, and guessing "plugin" registers nothing while reporting success.
+ */
+export function definePlugin(plugin) {
+    return plugin;
+}
+/**
+ * Loads every plugin the repository's `.rmanrc "plugins"` declares, in declaration order.
+ *
+ * This is what lets a *package* contribute commands. `.rman/*.mjs` covers one repository's own
+ * commands (see `loadCustomCommands`); a plugin covers a whole class of repository - `rman-node`
+ * carrying everything that only means something because the repository is a Node one, so rman's
+ * core does not have to.
+ *
+ * An entry is a package name, a path, or a plugin object - and a named package's entry point
+ * exports a **config**, whose own `plugins` are then loaded the same way (see `loadInto`).
+ *
+ * Names resolve relative to the repository root's own `node_modules`, the way `extends` resolves -
+ * a plugin is the repository's dependency, not rman's.
+ *
+ * **A plugin that cannot be loaded throws**, unlike a broken `.rman/*.mjs` file, which is warned
+ * about and skipped. The two differ because the consequence does: a skipped local command affects
+ * only itself, while a missing plugin silently removes commands the repository is built around -
+ * `rman publish` would simply not exist, and "not a known command" sends the reader looking in the
+ * wrong place entirely.
+ */
+export async function loadPlugins(rootDir, rootConfig) {
+    const commands = [];
+    /** Resolved against the repository root, where the `.rmanrc` declaring them lives. */
+    await loadInto(commands, rootConfig, path.join(rootDir, '.rmanrc'), { files: new Set(), names: new Set() });
+    return commands;
+}
+/**
+ * One config's `plugins`, in declaration order.
+ *
+ * Recursive because a plugin package **exports a config**, not a plugin: `rman-node`'s entry point
+ * is `export default defineConfig({ plugins: [ ... ] })`, so resolving a name lands on another
+ * config whose own `plugins` are the ones to register. That also means a plugin package can name a
+ * plugin of its own and it simply works.
+ *
+ * `from` is the file the entries are resolved against, and it changes as it descends - an entry in
+ * `rman-node`'s config resolves through *its* `node_modules`, not the repository's, the same rule
+ * `extends` follows.
+ *
+ * **Only `plugins` is read out of an imported config.** Its other keys are not merged: a config's
+ * way into a repository is `extends`, which is the key that says "merge this underneath mine".
+ * Reading them here would make a plugin able to configure a repository by being installed.
+ */
+async function loadInto(commands, config, from, seen) {
+    const declared = config?.[PLUGINS_KEY];
+    if (declared === undefined)
+        return;
+    for (const entry of Array.isArray(declared) ? declared : [declared]) {
+        /**
+         * The object form: a JS config handing a plugin over directly, and what a plugin package's own
+         * config holds. Nothing to resolve or import.
+         *
+         * An object here **is** a plugin - it is not guessed at. The one thing checked is that it has a
+         * `name`, because everything downstream (the registration guard, `--help` grouping, every error
+         * message) is keyed by it.
+         */
+        if (isPlainObject(entry)) {
+            if (typeof entry.name !== 'string' || !entry.name) {
+                throw new Error(`A plugin object in "${PLUGINS_KEY}" has no "name" - every other message is keyed by it.`);
+            }
+            register(commands, entry, entry.name, from, seen);
+            continue;
+        }
+        if (typeof entry !== 'string' || !entry.trim()) {
+            throw new Error(`"${PLUGINS_KEY}" takes a package name, a path, or a plugin object - not ${JSON.stringify(entry)}`);
+        }
+        const file = resolveConfigTarget(entry, from, PLUGINS_KEY);
+        /** A config naming itself, or two naming each other, would otherwise recurse forever. Keyed by
+         *  resolved file, so the same package reached by two names is still loaded once. */
+        if (seen.files.has(file))
+            continue;
+        seen.files.add(file);
+        const mod = await import(pathToFileURL(file).href);
+        const exported = mod?.default ?? mod?.plugin;
+        /**
+         * **A module exports one thing: an rman config.** Not a plugin, and not either-or.
+         *
+         * Accepting both meant having to *tell them apart*, and there is no reliable way to - `name` is
+         * a key a config may have as well, so the test came down to "a name plus at least one of the
+         * things a plugin contributes", which is a guess. Guess wrong in the direction of "plugin" and
+         * nothing is registered while the command reports success, which is the worst outcome on offer.
+         * One shape, one rule, one error.
+         */
+        if (!isPlainObject(exported) || exported.plugins === undefined) {
+            throw new Error(`Plugin "${entry}" must export an rman config - \`export default defineConfig({ plugins: [ ... ] })\`. ` +
+                describeExport(exported));
+        }
+        await loadInto(commands, exported, file, seen);
+    }
+}
+/**
+ * Everything a plugin contributes, in one place - so the object and the imported forms cannot drift
+ * apart in what they support.
+ *
+ * **One registration per plugin name.** `plugins` appends at every layer now, so the same plugin
+ * arriving twice is an ordinary consequence of `extends` rather than a mistake to report - and
+ * registering it twice would define its commands twice, which yargs does not survive. The config
+ * merge already drops an identical entry; this catches the rest, including two objects claiming one
+ * name and an object that duplicates a named package.
+ */
+function register(commands, plugin, label, specifier, seen) {
+    if (seen.names.has(plugin.name))
+        return;
+    seen.names.add(plugin.name);
+    if (plugin.runSteps)
+        RunService.addStepSource(plugin.runSteps);
+    if (plugin.manifest)
+        Manifest.addProvider(plugin.manifest);
+    if (plugin.workspace)
+        Workspace.addProvider(plugin.workspace);
+    if (plugin.binPaths)
+        BinPath.addProvider(plugin.binPaths);
+    if (plugin.versionPlanner)
+        VersionPlanService.setPlanner(plugin.versionPlanner);
+    for (const command of plugin.commands ?? []) {
+        commands.push(toLoadedCommand(command, label || specifier, specifier));
+    }
+}
+/**
+ * The second half of the error above - what the module *did* export, so the author can see how far
+ * off it was.
+ *
+ * It recognizes a plugin object only to **say so in a message**. That is the one safe use for this
+ * shape test: it decides nothing, so a wrong guess costs a slightly less helpful sentence rather
+ * than a plugin that silently does not load.
+ */
+function describeExport(exported) {
+    if (exported === undefined)
+        return 'It has no default export.';
+    if (!isPlainObject(exported))
+        return `Its default export is a ${typeof exported}.`;
+    const looksLikePlugin = PLUGIN_SEAMS.some(seam => exported[seam] !== undefined);
+    return looksLikePlugin
+        ? `Its default export looks like the plugin itself - put it in a config's "${PLUGINS_KEY}".`
+        : `Its default export has no "${PLUGINS_KEY}".`;
+}
+const PLUGIN_SEAMS = ['commands', 'runSteps', 'workspace', 'manifest', 'versionPlanner', 'binPaths'];
+/** A config object, as opposed to an array or anything with its own prototype. */
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** A plugin's command, checked the same way a `.rman/*.mjs` one is - the name it answers to comes
+ *  from its own `command` string, since a plugin has no file name to fall back on. */
+function toLoadedCommand(command, pluginName, specifier) {
+    const declared = command?.command?.trim();
+    if (!declared) {
+        throw new Error(`Plugin "${pluginName}" has a command with no "command" name - it cannot be registered.`);
+    }
+    if (typeof command.handler !== 'function') {
+        throw new Error(`Plugin "${pluginName}" command "${declared}" has no "handler" function.`);
+    }
+    if (typeof command.describe !== 'string' || !command.describe) {
+        throw new Error(`Plugin "${pluginName}" command "${declared}" has no "describe" - \`rman --help\` would have ` +
+            `nothing to list it by.`);
+    }
+    return { ...command, command: declared, name: declared.split(/\s+/)[0], file: specifier };
+}

package/core/repository.d.ts

@@ -1,3 +1,5 @@
+import { type ConfigScope, type GitScope, type PackageScope, type RepositoryScope } from './config.js';
+import type { LoadedCommand } from './custom-command.js';
 import { Package } from './package.js';
 export declare class Repository extends Package {
     readonly dirname: string;
@@ -8,6 +10,32 @@ export declare class Repository extends Package {
      *  really was. Used by `currentPackage` to scope commands to "the package I'm standing in". */
     readonly cwd: string;
     readonly rootPackage: Package;
+    /** Commands the repository's plugins contributed, loaded during `create` because the workspace
+     *  providers they bring are needed before any package can be found. `cli.ts` registers them. */
+    pluginCommands: LoadedCommand[];
+    /**
+     * Cached repository scope - see `_repositoryScope`.
+     *
+     * **Non-enumerable**, and for the same reason `targetVersion` itself is: this cache holds a
+     * `PackageScope` per package, each carrying that throwing getter, and it hangs off a `Repository`
+     * which every `Package` points back at. Left enumerable, *any* deep walk of a package reached it
+     * and threw - measured through a test's own `toEqual` diff, but a `JSON.stringify` or a debugger
+     * would do it too, with an error about `version` that has nothing to do with what the caller did.
+     * An internal cache has no business being walked anyway.
+     */
+    private _repoScope?;
+    /** Cached `${{ git.* }}` facts - see `_gitScope`. Non-enumerable for the same reason as above,
+     *  and because reading it is a subprocess: a deep walk of a package must not spawn one. */
+    private _git?;
+    /**
+     * Files `${{ read(...) }}` has parsed, shared by every package's scope and keyed by the identity
+     * of the bytes - see `readStructuredFile`.
+     *
+     * **On the repository rather than per scope, and that is the whole point of it**: `configScope`
+     * is built once per package, so a cache living there would re-read a repository-level file once
+     * for every package that mentions it.
+     */
+    private readonly _readCache;
     protected constructor(dirname: string, monorepo: boolean, packages: Package[], 
     /** The directory `Repository.create()` was actually invoked from - unlike `dirname` (the
      *  resolved repository root, possibly several levels up), this is where the user's shell
@@ -36,6 +64,20 @@ export declare class Repository extends Package {
     listStatus(options?: {
         hash?: string;
     }): Promise<Record<string, Repository.PackageStatus>>;
+    /**
+     * The scope a `${{ ... }}` expression is evaluated against for `pkg`, optionally with the version
+     * a run is about to write bound into it.
+     *
+     * `version` is the only caller that passes one, and it has to: the config was resolved before its
+     * plan existed, so `pkg.targetVersion` had nothing to be. Re-evaluating that raw value against
+     * this is how that one binding gets filled in, without every other command paying for it - or
+     * seeing a value that means nothing to them.
+     */
+    configScope(pkg: Package, options?: {
+        targetVersion?: string;
+    }): ConfigScope;
+    /** `${{ git.* }}`, read at most once per repository per process. */
+    protected _gitScope(): GitScope;
     /**
      * Resolves the effective rman config for the repository root and every package, cascading
      * root -> intermediate directories -> package directory, so a `.rmanrc` placed anywhere along
@@ -46,8 +88,57 @@ export declare class Repository extends Package {
      * single-package repository it *is* the one package, so `"[*]"` has to reach it; in a monorepo
      * nothing under `getPackages()` is the root, so only its own unmarked config applies.
      */
+    /**
+     * Gives every package its `repository` and `parent`, before any config is resolved - a config
+     * expression or a provider may already want to navigate from a package outwards.
+     *
+     * A repository's own `repository` is itself, which reads oddly and is the honest answer:
+     * `Repository extends Package`, so the repository *is* a package of its own repository.
+     */
+    protected _linkPackages(): void;
     protected _resolveConfigs(): Promise<void>;
+    protected _topoSortPackages(packages: Package[]): void;
+    protected _packageScope(pkg: Package, targetVersion?: string): PackageScope;
+    /** Built once and reused: it is the same for every package, and its `git` getter caches too, so a
+     *  repository whose config never mentions git spawns none. */
+    protected _repositoryScope(): RepositoryScope;
+    /**
+     * One `.rmanrc "dependencies"` entry to a package: its **name** first, then a
+     * **repository-relative directory**.
+     *
+     * The path form is what makes the key usable outside npm. A name identifies a package only where
+     * the ecosystem guarantees uniqueness - the same reason `Package.dependencies` holds references
+     * and `Workspace.Layout` carries paths - so a repository whose names collide, or whose packages
+     * have no names rman can read, states the edge by directory instead.
+     *
+     * Name first because that is what a Node repository writes and there is no ambiguity in practice:
+     * a package name that is also an existing directory path in the same repository does not occur.
+     * An entry matching neither is ignored, as an unknown name always was - the graph is a statement
+     * about packages that exist.
+     */
+    protected _resolveDeclaredPackage(entry: string): Package | undefined;
     protected _updateDependencies(): void;
+    /** `git` facts for a `${{ git.* }}` expression. Synchronous on purpose: it backs a lazy
+     *  getter, and a getter cannot await. Everything is `undefined` outside a git checkout - not an
+     *  error, just a repository without one. */
+    protected _readGitScope(dirname: string): GitScope;
+    /**
+     * Opens the repository containing `root` (default: the current directory).
+     *
+     * Three steps, in this order because each needs the one before it:
+     *
+     * 1. **Find the root** without knowing any ecosystem - see `Workspace.findRoot`. It cannot be
+     *    otherwise: the plugins that know what a package is are named in the config file this step
+     *    is looking for.
+     * 2. **Load the plugins** the root's config names, which registers their workspace providers
+     *    (and their commands, handed on via `pluginCommands` - `cli.ts` registers those).
+     * 3. **Ask the providers** for the layout. None recognizing it means a repository that is itself
+     *    the one package.
+     *
+     * **A repository whose `.rmanrc` names no plugin has no packages beyond itself**, and that is the
+     * boundary working rather than failing: `workspaces` in a `package.json` is npm's idea, so it
+     * takes `plugins: ['rman-node']` to be read as one.
+     */
     static create(root?: string, options?: {
         deep?: number;
     }): Promise<Repository>;
@@ -55,7 +146,6 @@ export declare class Repository extends Package {
      *  `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` config (which may need a dynamic `import()`)
      *  before the dependency graph is built from it. */
     private static _init;
-    protected static _resolvePackages(dirname: string, patterns: string[]): Package[];
 }
 export declare namespace Repository {
     type PackageStatus = 'dirty' | 'committed' | 'changed' | 'clean';