rman 2.0.0-beta.2 → 2.0.0-beta.3

package/core/config/config-paths.js

@@ -0,0 +1,78 @@
+/**
+ * **Which config paths are code rather than data**, and which are left for later.
+ *
+ * Three lists, read by `ConfigInterpolator` as it walks and by the commands that own the keys. Not
+ * members of that class, and that is the exception CLAUDE.md records: `CodeSubtree` is derived from
+ * `CODE_SUBTREES` with `(typeof ...)[number]`, and a class field has no type to derive from. The
+ * test is whether a *type* reads the value, not whether the value feels constant.
+ */
+/**
+ * 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 const CODE_SUBTREES = ['plugins', 'platforms', 'commands', 'publishTargets'];
+/**
+ * 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 const STEP_PATHS = [
+    /** The bare-value shorthand: `run: { build: fn }` means `{ exec: fn }`, as `run: { build: 'cmd' }`
+     *  means `{ exec: 'cmd' }`. Missing it made the two spellings disagree about *when* the function
+     *  runs, which is worse than not supporting the short one at all. */
+    'run.*',
+    'run.*.before',
+    'run.*.exec',
+    'run.*.after',
+    /** A condition, evaluated per package by `RunService` when the run reaches it. Called here
+     *  instead, it collapsed to the boolean it happened to return at load time - and `parseIfExpr`
+     *  then read that boolean as "no condition given", so the script ran unconditionally (measured). */
+    'run.*.if',
+    'version.before',
+    'version.exec',
+    'version.after',
+];
+/**
+ * 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 const DEFERRED_PATHS = ['version.before', 'version.exec', 'version.after'];

package/core/config/config-reader.d.ts

@@ -0,0 +1,192 @@
+import type { RmanConfig } from '../../interfaces/rman-config.interface.js';
+import type { Package } from '../classes/package.js';
+import type { Repository } from '../classes/repository.js';
+import { type Platform, type Plugin } from '../interfaces/plugin.js';
+export declare class ConfigReader {
+    /**
+     *
+     * @protected
+     */
+    protected readonly configFiles: readonly string[];
+    /**
+     * Whether a config key names **packages** rather than a setting: `"[*]"`, `"[/]"`, `"[pkg-a]"`.
+     */
+    static isSelectorKey(key: string): boolean;
+    /**
+     * **Which packages a selector key speaks for.** Two audiences, and the second is a glob:
+     *
+     * | | matches | `test` is given |
+     * | --- | --- | --- |
+     * | `"[/]"` | the **root package** alone, structurally | - |
+     * | `"[platform:node]"`, `"[platform:node,cargo]"` | packages of those **technologies** | `pkg.platform.name` |
+     * | `"[*]"`, `"[pkg-a]"`, `"[*-dialect]"` | the packages **below** this directory the glob matches | `pkg.selector` |
+     *
+     * The glob is anchored at both ends, so `"[*-dialect]"` matches `mysql-dialect` but not
+     * `my-dialect-helper`. `"[ws:*]"` and `"[workspace:*]"` are accepted and mean exactly `"[*]"`.
+     */
+    static parseSelector(key: string): ConfigReader.ParsedSelector;
+    /**
+     *
+     */
+    resolve(dirname: string, options?: ConfigReader.Options): Promise<ConfigReader.ResolveResult>;
+    /**
+     *
+     * @protected
+     */
+    protected _resolve(context: ConfigReader.Context, options?: ConfigReader.Options): Promise<RmanConfig>;
+    protected _getDeclaredPlatform(config: RmanConfig): string | undefined;
+    /**
+     * The one config file `dirname` declares, or `undefined` for a directory that declares none.
+     *
+     * **Several is an error**, which is the whole point of reading the directory rather than probing
+     * the names in a fixed order: a probe cannot tell "this one" from "this one, and three others I
+     * am quietly folding in underneath". The message lists what it found, because the fix is to
+     * delete one and the reader has to know which are in play.
+     *
+     * Public because it answers a question a *reader* has and not only the resolver: `rman config`
+     * heads its output with the file you would open to change what it prints.
+     */
+    findConfigSource(dirname: string): string | undefined;
+    /** @see {@link ConfigReader.findConfigSource} */
+    protected _findConfigSource(dirname: string): string | undefined;
+    /** Reads one config file into a plain object. Nothing is merged and nothing is checked here
+     *  beyond the file being an object at all - a config that is a list or a string is a mistake
+     *  worth naming before any key of it is read. */
+    protected _readConfigFile(file: string): Promise<RmanConfig>;
+    /**
+     * Loads a config module - a `.rmanrc.cjs`/`.mjs`/`.js`, or an `extends` target that is one. The
+     * default export when there is one, the module's own exports object otherwise.
+     */
+    protected _loadConfigModule(file: string): Promise<any>;
+    protected _assertSelectorBlocks(config: RmanConfig, file: string): void;
+    protected _resolveExtends(context: ConfigReader.Context, config: RmanConfig, from: string, seen?: string[]): Promise<RmanConfig>;
+    /**
+     * Lays `options.presets` underneath this level's own config, exactly as an `extends` naming them
+     * would - so a repository that declares nothing still has rman's own technologies, commands and
+     * publish targets, and one that declares something still wins every key.
+     *
+     * Nothing happens without `options.presets`, which is how a level that is not the root - and a
+     * caller wanting a bare core - says so.
+     */
+    protected _applyPresets(config: RmanConfig, context: ConfigReader.Context, options?: ConfigReader.Options): Promise<RmanConfig>;
+    /**
+     * Loads the technologies a level's `platforms` names, into `context.platforms`.
+     *
+     * An entry is a `Platform`, or a glob naming `.js` modules that `export default` one. Already
+     * present by name, it is skipped - two layers naming one technology is ordinary rather than a
+     * mistake, and registering it twice would have two objects answering for one name.
+     */
+    protected _loadPlatforms(config: RmanConfig, context: ConfigReader.Context): Promise<void>;
+    /** Appends a technology unless one already answers to its name. */
+    protected _addPlatform(platform: Platform, context: ConfigReader.Context): void;
+    /** Appends a plugin unless one already answers to that name. */
+    protected _addPlugin(plugin: Plugin, context: ConfigReader.Context): void;
+    protected _loadPlugins(config: RmanConfig, context: ConfigReader.Context): Promise<void>;
+    /**
+     * Refuses a plugin that did not come through `definePlatform`/`definePlugin`.
+     *
+     * @param from where the entry came from, for the message - the config key for one written into
+     *   the config, and the file for one a glob loaded.
+     */
+    protected _assertDeclaredPlugin(value: Plugin, from: string): void;
+    /**
+     * Loads the plugins a **string** `plugins` entry names.
+     *
+     * The string is a glob - never a package name, and already absolute by the time it arrives - so
+     * it may match several modules and this returns a list. An entry written as an instance does not
+     * come through here; it is already the plugin.
+     *
+     * Each match must `export default` a plugin declared through `definePlatform`/`definePlugin`.
+     * A glob matching nothing is an error.
+     */
+    protected _loadPluginsByEntry(entry: string): Promise<Plugin[]>;
+    /**
+     * Refuses whatever a glob matched when it is not the kind the key takes, naming what it *is*.
+     *
+     * @param want which key is being loaded, so the message can point at the other one.
+     */
+    protected _assertLoaded(value: unknown, file: string, want: Plugin.DeclaredKind): void;
+    /**
+     * Every default export a **glob** entry names, with the file each came from.
+     *
+     * Shared by `plugins` and `platforms`, which take the same two forms and differ only in what they
+     * accept back - so the caller checks the shape and this one only finds and imports.
+     *
+     * The glob is absolute by the time it arrives: `mergeConfig` anchors a contribution glob to the
+     * file that declared it (`anchorContributions`). Nothing here resolves a path, and a resolution
+     * step would make a preset's `'./x.js'` look in the consumer's directory. `.js` only - these are
+     * imported into rman's own process with no loader registered, so a `.ts` module cannot be one.
+     */
+    protected _loadByGlob(entry: string, key: string): Promise<{
+        value: unknown;
+        file: string;
+    }[]>;
+    /**
+     *
+     * @protected
+     */
+    protected _resolveExtendTarget(target: string, from: string, label: string): string;
+    /**
+     * Where one of rman's own presets lives - `extends: "rman:node"`.
+     *
+     * A preset is an ordinary config that happens to ship with rman: it contributes a technology, the
+     * commands that belong to it and its publish target, and it reaches a repository the same way any
+     * other config does.
+     */
+    protected _resolvePreset(name: string, label: string): string;
+}
+export declare namespace ConfigReader {
+    /** What a `"[...]"` key resolves to - see {@link ConfigReader.parseSelector}. */
+    interface ParsedSelector {
+        /**
+         * What `test` is asked about:
+         *
+         * - `'root'` - nothing; the root is matched by *being* the root.
+         * - `'platform'` - the package's `platform.name`.
+         * - `'package'` - the package's `selector`.
+         *
+         * A glob and a platform block both match packages below the root, never the root itself - its
+         * address is `"[/]"`.
+         */
+        scope: 'root' | 'package' | 'platform';
+        /** Whether a package's selector is one this key speaks for. Always `true` for a root key, which
+         *  is matched by *being* the root rather than by name. */
+        test(name: string): boolean;
+    }
+    interface Options {
+        /** Plugins to start with - the application's. Optional like `platforms`, which it was not: a
+         *  plugin used to be how a technology arrived, so a caller always had one. */
+        plugins?: Plugin[];
+        /**
+         * rman's own presets to lay **underneath** this level's config - `['node']`, the bare names
+         * `extends: "rman:node"` would have spelled. Omitted or empty, none are applied, which is what
+         * every level below the root passes and what a caller wanting a bare core passes too.
+         *
+         * They are loaded **after** whatever the config declared, so a repository's own technology is
+         * asked about a directory first.
+         */
+        presets?: readonly string[];
+        /** Technologies to start with - typically the application's. They come first, so a repository's
+         *  own additions are appended after them. */
+        platforms?: Platform[];
+    }
+    interface Context {
+        dirname: string;
+        plugins: Plugin[];
+        platforms: Platform[];
+    }
+    interface ResolveResult {
+        config: RmanConfig;
+        /** Every plugin in play after this read - the ones passed in, plus whatever the config named. */
+        plugins: Plugin[];
+        /** Every technology in play, in the order it was contributed. A `platforms` entry comes before
+         *  one a plugin carried, since a config naming a technology outright is the more direct
+         *  statement. */
+        platforms: Platform[];
+    }
+    interface InterpolateArgs<T = RmanConfig> {
+        config: T;
+        repository: Repository;
+        pkg: Package;
+    }
+}