rman 1.3.0 → 2.0.0-beta.2

package/core/publish-target.d.ts

@@ -0,0 +1,124 @@
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import type { PackageFilterOptions } from '../utils/package-filter.js';
+import type { RmanApplication } from './application.js';
+import type { Package } from './package.js';
+import type { Repository } from './repository.js';
+/**
+ * **Where a package's artifact ships, as a contribution.**
+ *
+ * `publish` used to be `rman-node`'s command, and that was backwards in a way worth stating: the
+ * command itself is about a *repository* - which packages are candidates, which versions are
+ * already out there, what order to push them in, what to print - and none of that is npm's. What is
+ * npm's is one answer to "is this version on the registry, and how do I push it", which is exactly
+ * the size of this interface. Docker publishing was in the core all along and could only be reached
+ * through a Node plugin's command; a Cargo repository could reach neither.
+ *
+ * So: the core ships `publish` and the `docker` target, the `node` built-in contributes `npm`, and a
+ * repository in any other ecosystem contributes its own without either package knowing about it.
+ *
+ * A target owns three things and no more:
+ *
+ * - **Which packages are its own by default** (`claims`) - see below.
+ * - **Its own CLI options**, merged into `publish`'s by the command. Every flag that only meant
+ *   something to npm (`--access`, `--tag`, `--otp`, `--registry`, `--userconfig`, `--contents`,
+ *   `--package-manager`) is declared here now instead of on a command the core would otherwise have
+ *   to know them all in advance.
+ * - **`getPlan`/`applyPlan`** - the same two-step shape every other rman service uses, and the
+ *   reason `--dry-run` and the confirmation prompt are the command's business rather than each
+ *   target's.
+ */
+export interface PublishTarget {
+    /** The name `publish.target` and `--target` use, and the label printed beside a package. */
+    readonly name: string;
+    /** One line for `--target`'s help - a reader asking `rman publish --help` in a polyglot
+     *  repository has no other way to find out which targets are even installed. */
+    readonly describe?: string;
+    /**
+     * This target's own flags, merged into `publish`'s options.
+     *
+     * Flat, not namespaced: `--tag` reads better than `--npm-tag`, and two targets colliding on a
+     * name is refused loudly by the command rather than resolved by a rule nobody would remember.
+     * Name a flag for the target when it genuinely belongs to one (`--docker-namespace`).
+     */
+    readonly options?: Record<string, RmanConfig.CommandOption>;
+    /**
+     * Whether a package that declares **no** `publish.target` at all ships here.
+     *
+     * Absent means never - the target is opt-in, which is what `docker` is. `npm`'s answer is
+     * `pkg.provider === 'node'`, and that is the fix for a real bug rather than a nicety: the default
+     * used to be a hardcoded `['npm']` in the core, so `rman list --json` reported
+     * `publishTargets: ["npm"]` for a Cargo package and `publish` treated it as an npm candidate.
+     * A default only the ecosystem can state had been written down by someone who could not know it.
+     */
+    claims?(pkg: Package): boolean;
+    /** What this target *would* do - never publishes. Called even under `--dry-run`, which is the
+     *  whole point of the split. */
+    getPlan(ctx: PublishTarget.Context): Promise<PublishTarget.Entry[]>;
+    /** Publishes every `'publish'` entry in `plan`, and returns what it did. */
+    applyPlan(ctx: PublishTarget.Context, plan: PublishTarget.Entry[]): Promise<PublishTarget.Entry[]>;
+}
+export declare namespace PublishTarget {
+    /**
+     * What a target is handed, once per call.
+     *
+     * `args` is the parsed argv, untyped on purpose: a target declared its own options, so it is the
+     * only thing that knows their names and types, and the core cannot be made to know them without
+     * becoming the thing this interface exists to stop it being.
+     */
+    interface Context {
+        readonly app: RmanApplication;
+        readonly repository: Repository;
+        /** The filters every target shares, read off argv once by the command. */
+        readonly options: Options;
+        /** The whole parsed argv - a target reads the options it declared out of this. */
+        readonly args: Record<string, any>;
+    }
+    interface Options extends PackageFilterOptions {
+        /** A package with uncommitted local changes is excluded (`'skip'`) instead of aborting the
+         *  whole plan (`'error'`). */
+        ignoreDirty?: boolean;
+    }
+    /**
+     * One package's outcome for one target.
+     *
+     * `'skip'` and `'error'` differ in what they do to the run: an error aborts before anything is
+     * published, a skip is a package the plan deliberately leaves alone. A target may add fields of
+     * its own (docker carries the resolved image reference); `detail` is the one the command prints,
+     * so whatever a target wants shown beside a package goes there.
+     */
+    interface Entry {
+        package: Package;
+        version: string;
+        status: 'publish' | 'skip' | 'up-to-date' | 'error';
+        /** Printed after the package name - docker's resolved `<namespace>/<image>`, for instance. */
+        detail?: string;
+        reason?: string;
+    }
+}
+/**
+ * **A target's name, and deliberately not a union.**
+ *
+ * It was `'npm' | 'docker'`, the type half of a bug whose runtime half was a hardcoded `['npm']`
+ * default, so `rman list --json` reported `publishTargets: ["npm"]` for a Cargo package. Both are
+ * gone together - which targets exist is whatever the repository's plugins contribute
+ * (`RmanApplication.publishTargets`), so a union here would mean the core naming plugins it cannot
+ * know about, exactly as `Package.provider` must not.
+ *
+ * A name nothing implements is caught where the facts are, by `publish` itself, naming the targets
+ * this repository does have.
+ */
+export type PublishTargetName = string;
+/**
+ * The targets a package **declares**, or `undefined` when it declares none - which is not the same
+ * as an empty list, and the difference is what `claims` is asked about.
+ */
+export declare function declaredTargets(pkg: Package): string[] | undefined;
+/** Whether `pkg` ships to `target`: its own `publish.target` decides when it has one, and the
+ *  target's own `claims` decides when it does not. */
+export declare function shipsTo(pkg: Package, target: PublishTarget): boolean;
+/** Every registered target `pkg` ships to, in registration order. The single answer to "where does
+ *  this package go", so `publish` and `list --json` cannot disagree about it. */
+export declare function targetsOf(app: RmanApplication, pkg: Package): PublishTarget[];
+/** Names in a package's `publish.target` that no registered target answers to - a misconfiguration
+ *  that used to be caught by a `choices: ['npm', 'docker']` the core can no longer write down. */
+export declare function unknownTargets(app: RmanApplication, pkg: Package): string[];

package/core/publish-target.js

@@ -0,0 +1,30 @@
+/**
+ * The targets a package **declares**, or `undefined` when it declares none - which is not the same
+ * as an empty list, and the difference is what `claims` is asked about.
+ */
+export function declaredTargets(pkg) {
+    const declared = pkg.config.publish?.target;
+    if (declared === undefined)
+        return undefined;
+    return Array.isArray(declared) ? [...declared] : [declared];
+}
+/** Whether `pkg` ships to `target`: its own `publish.target` decides when it has one, and the
+ *  target's own `claims` decides when it does not. */
+export function shipsTo(pkg, target) {
+    const declared = declaredTargets(pkg);
+    return declared ? declared.includes(target.name) : !!target.claims?.(pkg);
+}
+/** Every registered target `pkg` ships to, in registration order. The single answer to "where does
+ *  this package go", so `publish` and `list --json` cannot disagree about it. */
+export function targetsOf(app, pkg) {
+    return app.publishTargets.all.filter(target => shipsTo(pkg, target));
+}
+/** Names in a package's `publish.target` that no registered target answers to - a misconfiguration
+ *  that used to be caught by a `choices: ['npm', 'docker']` the core can no longer write down. */
+export function unknownTargets(app, pkg) {
+    const declared = declaredTargets(pkg);
+    if (!declared)
+        return [];
+    const known = new Set(app.publishTargets.all.map(t => t.name));
+    return declared.filter(name => !known.has(name));
+}

package/core/registry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * An ordered collection of contributions, held **on the application** rather than in a module.
+ *
+ * Every registry rman had was a module-level array (`const providers: Provider[] = []` in
+ * `manifest.ts`, `workspace.ts`, `bin-path.ts`, `run.service.ts`), which made it process-global:
+ * two repositories in one process shared it. The test suite needed a root hook emptying five of
+ * them before every single test, and without it whichever spec ran first decided the answer for
+ * the rest - so the core appeared to work in tests that had registered nothing.
+ *
+ * An instance per `RmanApplication` closes the whole class: a new application starts empty, and
+ * nothing has to be cleaned up afterwards - the root hook is deleted.
+ *
+ * **Registry, not service.** The distinction is multiplicity: a registry is for a question whose
+ * answer is the *sum* of what was contributed (every provider's bin directories, the first provider
+ * that recognizes a directory). A question with exactly one answer is a service, replaceable
+ * through `RmanApplication.getService`.
+ */
+export declare class Registry<T> implements Iterable<T> {
+    private readonly items;
+    /** Contributions in registration order, which for a plugin is `plugins` declaration order. */
+    get all(): readonly T[];
+    get size(): number;
+    /** Idempotent by identity: a plugin may both declare a contribution and register it itself, and
+     *  the same function arriving twice would make the registry lie about what is in it. */
+    add(item: T): this;
+    /** The first contribution `ask` gives an answer for - "first that recognizes it" resolution,
+     *  which is how a directory finds the manifest reader and the workspace layout that claim it. */
+    first<R>(ask: (item: T) => R | undefined): R | undefined;
+    [Symbol.iterator](): Iterator<T>;
+}

package/core/registry.js

@@ -0,0 +1,47 @@
+/**
+ * An ordered collection of contributions, held **on the application** rather than in a module.
+ *
+ * Every registry rman had was a module-level array (`const providers: Provider[] = []` in
+ * `manifest.ts`, `workspace.ts`, `bin-path.ts`, `run.service.ts`), which made it process-global:
+ * two repositories in one process shared it. The test suite needed a root hook emptying five of
+ * them before every single test, and without it whichever spec ran first decided the answer for
+ * the rest - so the core appeared to work in tests that had registered nothing.
+ *
+ * An instance per `RmanApplication` closes the whole class: a new application starts empty, and
+ * nothing has to be cleaned up afterwards - the root hook is deleted.
+ *
+ * **Registry, not service.** The distinction is multiplicity: a registry is for a question whose
+ * answer is the *sum* of what was contributed (every provider's bin directories, the first provider
+ * that recognizes a directory). A question with exactly one answer is a service, replaceable
+ * through `RmanApplication.getService`.
+ */
+export class Registry {
+    items = [];
+    /** Contributions in registration order, which for a plugin is `plugins` declaration order. */
+    get all() {
+        return this.items;
+    }
+    get size() {
+        return this.items.length;
+    }
+    /** Idempotent by identity: a plugin may both declare a contribution and register it itself, and
+     *  the same function arriving twice would make the registry lie about what is in it. */
+    add(item) {
+        if (!this.items.includes(item))
+            this.items.push(item);
+        return this;
+    }
+    /** The first contribution `ask` gives an answer for - "first that recognizes it" resolution,
+     *  which is how a directory finds the manifest reader and the workspace layout that claim it. */
+    first(ask) {
+        for (const item of this.items) {
+            const answer = ask(item);
+            if (answer !== undefined)
+                return answer;
+        }
+        return undefined;
+    }
+    [Symbol.iterator]() {
+        return this.items[Symbol.iterator]();
+    }
+}

package/core/repository.d.ts

@@ -1,6 +1,10 @@
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import { type DetectedBuiltin } from '../plugins/detect.js';
+import { RmanApplication } from './application.js';
 import { type ConfigScope, type GitScope, type PackageScope, type RepositoryScope } from './config.js';
-import type { LoadedCommand } from './custom-command.js';
 import { Package } from './package.js';
+import type { Platform } from './plugin.js';
+import { Workspace } from './workspace.js';
 export declare class Repository extends Package {
     readonly dirname: string;
     readonly monorepo: boolean;
@@ -10,9 +14,10 @@ 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;
+    /** See the `defineProperty` in the constructor - what detection supplied, when it did. */
+    readonly detectedBuiltin?: DetectedBuiltin;
     /** 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`.
      *
@@ -36,11 +41,24 @@ export declare class Repository extends Package {
      * for every package that mentions it.
      */
     private readonly _readCache;
-    protected constructor(dirname: string, monorepo: boolean, packages: Package[], 
+    /**
+     * The application this repository belongs to - its services, its technologies, its logger.
+     *
+     * **Non-enumerable**, like `_repoScope` and `_git` beside it: the two things that walk a
+     * repository are `{...pkg}` spreads and the config scope, and an enumerable back-reference to the
+     * whole application would be dragged into both. A `Package` deliberately has no such field at
+     * all; a repository is never spread or serialized, which is what makes this one safe - measured,
+     * rather than assumed.
+     */
+    readonly app: RmanApplication;
+    protected constructor(app: RmanApplication, 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
      *  really was. Used by `currentPackage` to scope commands to "the package I'm standing in". */
-    cwd?: string);
+    cwd?: string, 
+    /** The root directory's own technology, from the same walk that found the packages - so the
+     *  repository and its `rootPackage` agree without either searching the registry again. */
+    platform?: Platform);
     /**
      * The package whose own directory contains `cwd` (the deepest match, so a package nested
      * inside another's directory resolves to the innermost one) - or `undefined` when `cwd` *is*
@@ -60,9 +78,21 @@ export declare class Repository extends Package {
      * dirty, the reference point decides the rest: without `hash`, `committed`
      * means committed but not yet in the upstream branch; with `hash`, `changed`
      * means it differs from that commit. Otherwise a package is `clean`.
+     *
+     * **Keyed by `Package.selector`**, which is what addresses a package - it was `name`, and the two
+     * coincide wherever a technology names its packages. A repository whose does not had every such
+     * package answering to `""`, so one entry stood for all of them.
+     *
+     * **`includeRoot` is opt-in, and the reason is that the root's answer means something different.**
+     * Its directory contains every other package, so the same rule - "does a changed file fall under
+     * this directory" - reports `dirty` for the root whenever *anything* in the repository is dirty.
+     * That is the honest reading of the rule rather than a bug, and it is not what `run --changed`
+     * wants, so only a caller that asked for the root gets it (`rman list`'s table, which shows the
+     * root as the tree's own row).
      */
     listStatus(options?: {
         hash?: string;
+        includeRoot?: boolean;
     }): Promise<Record<string, Repository.PackageStatus>>;
     /**
      * The scope a `${{ ... }}` expression is evaluated against for `pkg`, optionally with the version
@@ -89,13 +119,44 @@ export declare class Repository extends Package {
      * 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.
+     * Gives every package its `repository`, and hangs the `parent`/`children` tree off the walk that
+     * found them - before any config is resolved, since a config expression or a provider may already
+     * want to navigate from a package outwards.
+     *
+     * **The containment is read from the tree rather than recomputed from paths.** It used to be an
+     * O(n²) sweep comparing every package's directory against every other's and keeping the longest
+     * prefix - which is the same question `Workspace.walk` answers on the way down, asked again
+     * afterwards with the answer thrown away. Two places deriving one relationship is two places to
+     * disagree; there is one now.
+     *
+     * **`parent` is defined non-enumerably, `children` is a plain field**, which is the one asymmetry
+     * here and it is deliberate: a tree is serialized downwards, so `children` has to be walkable and
+     * `parent` must not be, or every `JSON.stringify` is a cycle. The same way `Repository.app` and
+     * `ORIGINS` travel.
      *
      * 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 _linkPackages(tree: Workspace.Node, nodes: Workspace.Node[], packages: Package[]): void;
+    /**
+     * Gives every package the selector a `"[glob]"` block and `--scope` match it by, and refuses two
+     * packages that would answer to the same one.
+     *
+     * **Its own step, before any config is resolved by a selector**, which is the ordering that makes
+     * the rest work: `_resolveConfigs` asks `resolveConfig` for each package *by selector*, so an
+     * address assigned afterwards would be applied to nothing.
+     *
+     * **`name` comes from the unmarked cascade only** - the same read `platform` gets, from the same
+     * cache, for the same reason. A `"[glob]"` block cannot set it (`assertSelectorBlocks` refuses
+     * one) because the glob matches the very thing the block would be setting.
+     *
+     * **Uniqueness is checked, and the cascade is the mistake it usually catches.** `name` cascades
+     * like every unmarked key, so one declaration above two packages gives both the same address -
+     * and the failure would otherwise be silent in the worst way: the config reaches both and
+     * `getPackage` returns whichever came first. The message names both directories, and says the
+     * cascade out loud when the two got it from one declaration.
+     */
+    protected _assignSelectors(rootDir: string, cache: Map<string, RmanConfig>): Promise<void>;
     protected _resolveConfigs(): Promise<void>;
     protected _topoSortPackages(packages: Package[]): void;
     protected _packageScope(pkg: Package, targetVersion?: string): PackageScope;
@@ -131,16 +192,18 @@ export declare class Repository extends Package {
      *    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).
+     *    (their commands arrive through `.rmanrc "commands"`, which `cli.ts` reads).
      * 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.
+     * takes `plugins: ['node']` - or detection reading the directory as a Node one - for it to be
+     * read as a workspace at all.
      */
     static create(root?: string, options?: {
         deep?: number;
+        app?: RmanApplication;
     }): Promise<Repository>;
     /** Finishes constructing `repo` with the async work a constructor can't do itself - resolving
      *  `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` config (which may need a dynamic `import()`)