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

package/core/classes/workspace.d.ts

@@ -0,0 +1,275 @@
+import type { RmanConfig } from '../../interfaces/rman-config.interface.js';
+import type { RmanApplication } from '../application.js';
+import { ConfigReader } from '../config/config-reader.js';
+import { type Platform, type Plugin } from '../interfaces/plugin.js';
+import { Package } from './package.js';
+/**
+ * A repository's layout, resolved: which directories hold packages, which technology claims each of
+ * them, what each one answers to, and the **raw** config each one ends up with.
+ *
+ * Built with {@link Workspace.create}, which runs the whole resolution; the constructor is
+ * protected, so there is no such thing as a half-built workspace.
+ *
+ * The configs it produces are **raw** - every `${{ }}` and every value function is still
+ * unevaluated. Resolving one needs `pkg`, `repository` and `git`, which belong to the repository
+ * rather than to its layout; `ConfigInterpolator` is the step after this.
+ */
+export declare class Workspace {
+    protected readonly options: Workspace.Options;
+    /** The repository root - where the walk starts and what every directory chain is relative to. */
+    readonly rootDir: string;
+    /** Every plugin in play, in load order: the ones passed in first, then each level's own. */
+    readonly plugins: Plugin[];
+    /** Every technology in play, in contribution order - which is what decides who claims a
+     *  directory, since the first that recognizes it wins. */
+    readonly platforms: Platform[];
+    /** The root directory's own package. Not one of `packages`, which holds the members. */
+    rootPackage: Package;
+    /** Every package below the root, depth-first. */
+    readonly packages: Package[];
+    /** Each directory's own config, read once - see `_readLevel`. */
+    private _levels;
+    /** The packages whose selector came from a `"name"` declaration rather than from their platform,
+     *  for the clash message alone. */
+    private _declaredSelectors;
+    /** Built on first use, unless `options.reader` supplied one. */
+    private _configReader?;
+    /**
+     * Builds a workspace and resolves it: discovery, selectors, and every package's raw config.
+     *
+     * A subclass inherits this and gets an instance of itself. Its declared return type stays
+     * `Workspace`, so a subclass wanting its own declares a one-line `create` that calls this.
+     *
+     * @param rootDir the repository root
+     */
+    static create(rootDir: string, options: Workspace.Options): Promise<Workspace>;
+    /** Use {@link Workspace.create}. */
+    protected constructor(rootDir: string, options: Workspace.Options);
+    /** The package at a directory, root included, or `undefined` for one that holds none. */
+    packageAt(dirname: string): Package | undefined;
+    /** The whole resolution, in the one order the steps admit. */
+    protected _init(): Promise<void>;
+    /**
+     * Descends from the root, asking each directory's own technology where its children are, and
+     * fills `rootPackage` and `packages`.
+     *
+     * One step, repeated: read the directory's config (which loads whatever plugins it names and
+     * decides its platform), then ask *that* platform's `getWorkspace` for the directories below it
+     * holding packages. A directory is visited once, and `options.deep` bounds the descent.
+     */
+    protected _discover(): Promise<void>;
+    /**
+     * Gives every package the selector it answers to - its `.rmanrc "name"` when it declares one, and
+     * what its platform says otherwise.
+     *
+     * `"[glob]"` and `--scope` match this, never the package's name: a name is an *ecosystem's*
+     * promise rather than rman's.
+     */
+    protected _resolveSelectors(): Promise<void>;
+    /**
+     * Refuses two packages answering to one selector. The root is exempt - a glob never matches it and
+     * `"[/]"` needs no name, so it shares an address with nobody.
+     */
+    protected _assertUniqueSelectors(): void;
+    /** Cascades every package's config into `Package.rawConfig`, now that the selectors are known.
+     *  Still raw - `Repository` is what interpolates it into `Package.config`. */
+    protected _resolveConfigs(): Promise<void>;
+    /**
+     * Every directory from the root down to `pkg`, layered into one config.
+     *
+     * Two layers per level: the level's unmarked keys first, then the `"[selector]"` blocks that
+     * speak for this package, in the order they were written - later wins, as `overrides` does in
+     * eslint and prettier.
+     *
+     * @param selector what the blocks are matched against; `undefined` skips them, except `"[/]"` for
+     *   the root, which is structural and needs no selector.
+     */
+    protected _cascade(pkg: Package, selector: string | undefined): Promise<RmanConfig>;
+    /** One directory's own config, read once and cached. Plugins the level names are loaded here and
+     *  accumulated into `plugins`. */
+    protected _readLevel(dirname: string): Promise<ConfigReader.ResolveResult>;
+    /** Appends a technology unless one already answers to its name. */
+    protected _addPlatform(platform: Platform): void;
+    /** The reader levels are read with - `options.reader`, or a default one. */
+    protected _reader(): ConfigReader;
+    /** Root, then every directory down to `targetDir`, inclusive. A target outside the root is the
+     *  root alone. */
+    protected _dirChain(targetDir: string): string[];
+    /** A level's own settings - everything that is not a `"[...]"` block. */
+    protected _stripSelectors(config: RmanConfig): RmanConfig;
+    /**
+     * The blocks in `config` that speak for this package, in declaration order.
+     *
+     * `"[/]"` matches the root and nothing else; a glob matches a package's selector and never the
+     * root.
+     */
+    protected _matchingSelectors(config: RmanConfig, audience: Workspace.Audience): RmanConfig[];
+    /**
+     * Whether one selector block speaks for this package.
+     *
+     * `"[/]"` asks only whether this *is* the root. Everything else matches packages **below** the
+     * root and never the root itself, which is addressed structurally or not at all.
+     */
+    protected _speaksFor(scope: ConfigReader.ParsedSelector['scope'], test: (value: string) => boolean, audience: Workspace.Audience): boolean;
+    /**
+     * The platform that claims a directory - the one its config names, or the first loaded platform
+     * whose manifest provider recognizes it. `basePlatform` when none does, so a caller needs no
+     * guard; a *declared* platform no plugin provides is an error.
+     */
+    protected _platformFor(dirname: string, config: RmanConfig): Platform;
+    /** A platform named unmarked or under `"[/]"` - both are the directory saying what it is. */
+    protected _declaredPlatformName(config: RmanConfig): string | undefined;
+    /** Which file a key came from, for an error that can be acted on. */
+    protected _originOf(config: RmanConfig, key: string): string;
+    /** Where a `Package` is made, and the only place - override it to build a subclass of `Package`
+     *  and keep the rest of the walk. */
+    protected _createPackage(dirname: string, platform: Platform): Package;
+}
+/**
+ * How a repository is laid out, and who decides.
+ *
+ * A namespace for the same reason `Manifest` is one: it is what a plugin can *augment*
+ * (`declare module 'rman' { namespace Workspace { ... } }`), so whatever this seam grows later
+ * arrives as a member here rather than as another top-level export. It merges with the class above,
+ * so `Workspace.walk` and `Workspace.create` are reached the same way.
+ */
+export declare namespace Workspace {
+    /** Who a selector block is being matched against - one package, as the three questions a block
+     *  can ask about it. */
+    interface Audience {
+        /** Whether this is the root package, which `"[/]"` asks and every other block refuses. */
+        isRoot: boolean;
+        /** What a glob matches. `undefined` on the first cascade pass, where the selector is still
+         *  being worked out - see `_resolveSelectors` - so glob blocks are skipped. */
+        selector: string | undefined;
+        /** What `"[platform:...]"` matches. `''` for a package no technology claimed. */
+        platform: string;
+    }
+    interface Options {
+        /** The application every `Package` is constructed against. */
+        app: RmanApplication;
+        /** Plugins to start with - typically the built-ins. They come first, so a repository's own
+         *  additions are appended after them. */
+        plugins?: Plugin[];
+        /** Technologies to start with - typically a preset's. They come first, so a repository's own
+         *  additions are appended after them. */
+        platforms?: Platform[];
+        /**
+         * rman's own presets, laid under the **root**'s config. Defaults to {@link DEFAULT_PRESETS}; an
+         * empty list is a caller asking for a bare core, with nothing but what it registered itself.
+         */
+        presets?: readonly string[];
+        /** How far the walk descends before giving up. Defaults to 10. */
+        deep?: number;
+        /** The reader levels are read with. Supply one to read from somewhere other than the disk. */
+        reader?: ConfigReader;
+    }
+    /**
+     * **Where one directory's own child packages are** - the directories immediately below it that
+     * hold a package, as absolute paths. `undefined` for "this is not a directory I recognize".
+     *
+     * **A provider answers for one directory, not for the repository**, and that is the whole
+     * correction. It used to be `(root) => { root, packageDirs }`: asked once, at the top, by the
+     * first platform that recognized it - so in a polyglot repository the technology listed first in
+     * `plugins` decided which directories were packages *at all*. Measured, and documented as a known
+     * limitation for a year: a `Cargo.toml`-only package was simply not found until a provider that
+     * looks for both was listed first.
+     *
+     * Asked per directory, each platform only ever answers about its own packages - which is all a
+     * platform knows - and the recursion is the core's (see `walk`). A Cargo workspace nested inside
+     * a Node monorepo is then just a node in the tree whose children came from a different platform.
+     *
+     * **Children, not descendants.** A provider returning the whole subtree would have to know what
+     * the platforms below it consider a package; returning one level means it never has to. npm's
+     * `workspaces` globs are already one level by construction (`deep: 0`).
+     *
+     * Still directories rather than `Package` objects, for the reason it always was: discovery runs
+     * before any package exists, so a provider returning packages would make discovery the owner of
+     * identity too. A path is also unique by construction, where a name is only unique if the
+     * ecosystem says so.
+     */
+    type Provider = (dir: string) => string[] | undefined;
+    /**
+     * One directory in the walk's result: which technology claimed it, and what sits below it.
+     *
+     * A plain tree rather than `Package`s, keeping the line `Provider` draws: `Repository.create`
+     * turns this into packages, so identity stays with the manifest provider and discovery stays
+     * with this one.
+     */
+    interface Node {
+        /** Absolute path to the directory. */
+        dirname: string;
+        /** The technology that claimed it - `basePlatform` when none did, so a reader needs no guard. */
+        platform: Platform;
+        /** The nodes for the package directories directly below it, in the order the platform gave
+         *  them. Empty for a leaf. */
+        children: Node[];
+    }
+    /**
+     * What a directory's `.rmanrc "platform"` resolves to, when it declares one - `undefined` when
+     * it says nothing, so the walk falls back to the guess.
+     *
+     * **A callback rather than config knowledge in here**, which keeps this namespace answering one
+     * question. Reading a directory's cascaded config, deciding that a declared name has to be
+     * loaded, and refusing one that cannot be, are all the repository's business; where the packages
+     * are is this one's. `Repository.create` supplies it - and it is also the seam a spec uses to
+     * drive the declaration path without writing a config file.
+     */
+    type DeclaredPlatform = (dir: string) => Promise<Platform | undefined>;
+    /**
+     * **The walk**: descend from `rootDir`, asking each directory's own technology where its children
+     * are, and repeating for each answer.
+     *
+     * One step, applied recursively:
+     *
+     * 1. take the directory's **declared** platform if it has one, and otherwise the first registered
+     *    platform whose manifest provider recognizes it (`app.platformFor`, `basePlatform` if none);
+     * 2. ask **that** platform's `getWorkspace` for the directories below it holding packages;
+     * 3. do the same for each of them.
+     *
+     * **A declaration wins, and is then held to it.** A platform named for a directory it does not
+     * recognize is a statement that is simply untrue, and the failure it would otherwise become is
+     * invisible: the manifest reads as nothing, so the package is named after its directory at
+     * `0.0.0` and the repository looks like it works. The error names the directory, the platform and
+     * the file that platform looked for.
+     *
+     * The root node always exists - a repository is a package whatever its technology - so this never
+     * returns `undefined`. A repository nobody recognizes is a root with no children, which is the
+     * single-package answer arrived at rather than guessed.
+     *
+     * **A directory is visited once.** A provider may legitimately name a directory another one
+     * already claimed (two globs overlapping, a symlinked package), and a provider naming an ancestor
+     * would otherwise recurse forever. First visit wins, so a package sits where it was first found.
+     *
+     * `deep` bounds the descent for the same reason `findRoot` bounds its climb: a provider computing
+     * paths rather than reading them can produce a chain that never ends, and a guessed depth is
+     * better than a hang with nothing printed.
+     */
+    function walk(app: RmanApplication, rootDir: string, options?: {
+        deep?: number;
+        declared?: DeclaredPlatform;
+    }): Promise<Node>;
+    /** Every node below `node`, depth-first, excluding `node` itself - the flat list `Repository`
+     *  reports as its packages, since the root is not one of its own members. */
+    function flatten(node: Node): Node[];
+    /**
+     * Where the repository starts, decided **without knowing anything about any ecosystem** - it has
+     * to be, because the plugins that do know are named in the config file this walk is looking for.
+     *
+     * Walking up from `from`, stopping after a directory holding `.git`, the root is:
+     *
+     * 1. the **outermost** directory in that chain holding an `.rmanrc*` - outermost, because a
+     *    *package* may have its own `.rmanrc` (that is a supported thing), and from inside such a
+     *    package the nearest one is the package's, not the repository's;
+     * 2. otherwise the `.git` directory itself, the ordinary meaning of "repository root";
+     * 3. otherwise `from`, which is all that is left to go on.
+     *
+     * **What "outermost" costs**, since the two cases genuinely conflict and only one can win: a
+     * self-contained project nested inside a larger git repository *and sharing its `.git`* resolves
+     * to the outer root, not to itself (measured). That is the same repository by any definition git
+     * recognizes, so it is the defensible answer - and a nested project with a `.git` of its own is
+     * found correctly, because the walk stops there before the outer `.rmanrc` is ever seen (also
+     * measured). A per-package `.rmanrc` is the common case and it is the one served.
+     */
+    function findRoot(from: string, deep?: number): string;
+}