rman 1.3.0 → 2.0.0-beta.2

package/services/github-release.service.d.ts

@@ -1,35 +1,10 @@
 import { Package } from '../core/package.js';
-import { Repository } from '../core/repository.js';
-export declare namespace GithubReleaseService {
-    /** Injectable "does this release already exist" check - mainly for tests, so they don't depend
-     *  on network access or a real GitHub token. Same shape as `DockerPublishService.Deps`' own
-     *  `imageExists`. */
-    interface Deps {
-        releaseExists?: (repository: string, tag: string) => Promise<boolean>;
-    }
-    interface Options {
-        /** Uncommitted local changes anywhere in the repository make the release `'skip'` instead of
-         *  `'error'` - same as `version`/`publish`'s other targets. */
-        ignoreDirty?: boolean;
-        /** `owner/repo` override - otherwise the root's own `githubRelease.repository`, falling back
-         *  to the `origin` remote's URL. */
-        repository?: string;
-    }
-    /** The repository's release outcome - see `getPlan`. At most one of these: a GitHub Release
-     *  belongs to the repository, not to a package. */
-    interface Entry {
-        /** Always the repository root - a release covers the whole source tree, not one package. */
-        package: Package;
-        /** The repository's own release version (see `buildRootEntry`). */
-        version: string;
-        status: 'publish' | 'skip' | 'up-to-date' | 'error';
-        /** The tag this release belongs to - the repository release tag on a calendar version, the
-         *  single shared version's tag otherwise. */
-        tag?: string;
-        /** `owner/repo` this release lands in - unset only when it couldn't be resolved (an `'error'`). */
-        repository?: string;
-        reason?: string;
-    }
+import { Service } from '../core/service.js';
+/**
+ * A service class - see `ListService` for the shape and `Service` for the three measured
+ * consequences a namespace had. `repository` left the signature because the application carries it.
+ */
+export declare class GithubReleaseService extends Service {
     /**
      * Computes what `github-release` *would* do - **one** release per run.
      *
@@ -51,7 +26,7 @@ export declare namespace GithubReleaseService {
      * such release", is `'error'` too - a blocking misconfiguration rather than a silent "not
      * released yet" that only fails later.
      */
-    function getPlan(repository: Repository, options?: Options, deps?: Deps): Promise<Entry[]>;
+    getPlan(options?: GithubReleaseService.Options, deps?: GithubReleaseService.Deps): Promise<GithubReleaseService.Entry[]>;
     /**
      * Creates the repository's GitHub Release, then uploads whatever `githubRelease.assets` globs
      * match, across every package. The body covers **every** package that shipped under this
@@ -65,5 +40,41 @@ export declare namespace GithubReleaseService {
      * An existing release for the tag is updated rather than treated as a failure, so a re-run after
      * a partial failure converges.
      */
-    function applyPlan(repository: Repository, plan: Entry[]): Promise<Entry[]>;
+    applyPlan(plan: GithubReleaseService.Entry[]): Promise<GithubReleaseService.Entry[]>;
+}
+export declare namespace GithubReleaseService {
+    /** Injectable "does this release already exist" check - mainly for tests, so they don't depend
+     *  on network access or a real GitHub token. Same shape as `DockerPublishService.Deps`' own
+     *  `imageExists`. */
+    interface Deps {
+        releaseExists?: (repository: string, tag: string) => Promise<boolean>;
+    }
+    interface Options {
+        /** Uncommitted local changes anywhere in the repository make the release `'skip'` instead of
+         *  `'error'` - same as `version`/`publish`'s other targets. */
+        ignoreDirty?: boolean;
+        /** `owner/repo` override - otherwise the root's own `githubRelease.repository`, falling back
+         *  to the `origin` remote's URL. */
+        repository?: string;
+    }
+    /** The repository's release outcome - see `getPlan`. At most one of these: a GitHub Release
+     *  belongs to the repository, not to a package. */
+    interface Entry {
+        /** Always the repository root - a release covers the whole source tree, not one package. */
+        package: Package;
+        /** The repository's own release version (see `buildRootEntry`). */
+        version: string;
+        status: 'publish' | 'skip' | 'up-to-date' | 'error';
+        /** The tag this release belongs to - the repository release tag on a calendar version, the
+         *  single shared version's tag otherwise. */
+        tag?: string;
+        /** `owner/repo` this release lands in - unset only when it couldn't be resolved (an `'error'`). */
+        repository?: string;
+        reason?: string;
+    }
+}
+declare module '../core/service.js' {
+    interface ServiceMap {
+        githubRelease: GithubReleaseService;
+    }
 }

package/services/github-release.service.js

@@ -3,12 +3,15 @@ import path from 'node:path';
 import fastGlob from 'fast-glob';
 import { Package } from '../core/package.js';
 import { Repository } from '../core/repository.js';
+import { Service } from '../core/service.js';
 import { GitHelper } from '../utils/git.js';
 import { expandReleaseTag, isCalendarVersion, releaseTagPattern } from '../utils/release-version.js';
 import { ChangeHashService } from './change-hash.service.js';
-import { ChangelogService } from './changelog.service.js';
-export var GithubReleaseService;
-(function (GithubReleaseService) {
+/**
+ * A service class - see `ListService` for the shape and `Service` for the three measured
+ * consequences a namespace had. `repository` left the signature because the application carries it.
+ */
+export class GithubReleaseService extends Service {
     /**
      * Computes what `github-release` *would* do - **one** release per run.
      *
@@ -30,7 +33,8 @@ export var GithubReleaseService;
      * such release", is `'error'` too - a blocking misconfiguration rather than a silent "not
      * released yet" that only fails later.
      */
-    async function getPlan(repository, options = {}, deps = {}) {
+    async getPlan(options = {}, deps = {}) {
+        const repository = this.repository;
         const root = repository.rootPackage;
         const git = new GitHelper({ cwd: repository.dirname });
         const base = { package: root, version: root.version };
@@ -88,7 +92,6 @@ export var GithubReleaseService;
             return [{ ...base, tag, repository: repo, status: 'error', reason: e.message }];
         }
     }
-    GithubReleaseService.getPlan = getPlan;
     /**
      * Creates the repository's GitHub Release, then uploads whatever `githubRelease.assets` globs
      * match, across every package. The body covers **every** package that shipped under this
@@ -102,7 +105,8 @@ export var GithubReleaseService;
      * An existing release for the tag is updated rather than treated as a failure, so a re-run after
      * a partial failure converges.
      */
-    async function applyPlan(repository, plan) {
+    async applyPlan(plan) {
+        const repository = this.repository;
         const entry = plan.find(e => e.status === 'publish');
         if (!entry)
             return plan;
@@ -122,8 +126,7 @@ export var GithubReleaseService;
             return plan.map(e2 => (e2 === entry ? { ...e2, status: 'error', reason: e.message } : e2));
         }
     }
-    GithubReleaseService.applyPlan = applyPlan;
-})(GithubReleaseService || (GithubReleaseService = {}));
+}
 const GITHUB_API = 'https://api.github.com';
 const GITHUB_UPLOADS = 'https://uploads.github.com';
 /** The tag naming this repository's release. A calendar root version means several version lines,
@@ -198,9 +201,9 @@ async function buildReleaseNotes(repository, git, releaseTag) {
         return '';
     const sections = [];
     for (const pkg of [...repository.getPackages(), root]) {
-        const entries = await ChangelogService.getEntries(repository, {
+        const entries = await repository.app.getService('changelog').getEntries({
             from: previous,
-            root: true,
+            fromRoot: true,
             includeSkipped: true,
             scope: pkg.name,
             version: pkg.version,

package/services/import.service.d.ts

@@ -1,16 +1,9 @@
-import type { Repository } from '../core/repository.js';
-export declare namespace ImportService {
-    interface Options {
-        /** Subdirectory (relative to the repository root) the new package is placed under - default `'packages'`. */
-        dest?: string;
-    }
-    interface Result {
-        /** The imported package's name (from its own `package.json`, or its directory basename). */
-        name: string;
-        /** Where it was placed, absolute. */
-        targetDir: string;
-        commitCount: number;
-    }
+import { Service } from '../core/service.js';
+/**
+ * A service class - see `ListService` for the shape and `Service` for the three measured
+ * consequences a namespace had. `repository` left the signature because the application carries it.
+ */
+export declare class ImportService extends Service {
     /**
      * Imports `sourcePath` (a local clone of some other git repository) as a new package under this
      * repository, preserving its **entire commit history** - every original commit, author, date and
@@ -26,5 +19,23 @@ export declare namespace ImportService {
      * merge (which real `git subtree` would give, at the cost of far less predictable behavior
      * across git versions - the reason this - and lerna - avoid it).
      */
-    function importRepo(repository: Repository, sourcePath: string, options?: Options): Promise<Result>;
+    importRepo(sourcePath: string, options?: ImportService.Options): Promise<ImportService.Result>;
+}
+export declare namespace ImportService {
+    interface Options {
+        /** Subdirectory (relative to the repository root) the new package is placed under - default `'packages'`. */
+        dest?: string;
+    }
+    interface Result {
+        /** The imported package's name (from its own `package.json`, or its directory basename). */
+        name: string;
+        /** Where it was placed, absolute. */
+        targetDir: string;
+        commitCount: number;
+    }
+}
+declare module '../core/service.js' {
+    interface ServiceMap {
+        import: ImportService;
+    }
 }

package/services/import.service.js

@@ -1,9 +1,13 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { Service } from '../core/service.js';
 import { GitHelper } from '../utils/git.js';
-export var ImportService;
-(function (ImportService) {
+/**
+ * A service class - see `ListService` for the shape and `Service` for the three measured
+ * consequences a namespace had. `repository` left the signature because the application carries it.
+ */
+export class ImportService extends Service {
     /**
      * Imports `sourcePath` (a local clone of some other git repository) as a new package under this
      * repository, preserving its **entire commit history** - every original commit, author, date and
@@ -19,7 +23,8 @@ export var ImportService;
      * merge (which real `git subtree` would give, at the cost of far less predictable behavior
      * across git versions - the reason this - and lerna - avoid it).
      */
-    async function importRepo(repository, sourcePath, options = {}) {
+    async importRepo(sourcePath, options = {}) {
+        const repository = this.repository;
         const absSource = path.resolve(sourcePath);
         if (!fs.existsSync(path.join(absSource, '.git'))) {
             throw new Error(`"${sourcePath}" is not a git repository (no .git found) - clone it locally first`);
@@ -48,8 +53,7 @@ export var ImportService;
             fs.rmSync(patchDir, { recursive: true, force: true });
         }
     }
-    ImportService.importRepo = importRepo;
-})(ImportService || (ImportService = {}));
+}
 /** The source repo's own `package.json` name, or its directory's basename when it has none (or
  *  isn't even a package yet - a plain library repo being folded in). */
 function resolveSourceName(absSource) {

package/services/list.service.d.ts

@@ -1,10 +1,44 @@
+import { type PublishTargetName } from '../core/publish-target.js';
 import type { Repository } from '../core/repository.js';
-import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import { Service } from '../core/service.js';
+import type { DockerPublishOptions } from '../targets/docker.target.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
+/**
+ * **A class, and the shape every service follows now.**
+ *
+ * `repository` is gone from the signature - it comes from the application, which is what always
+ * made the parameter redundant: every caller had one and passed it, and no caller ever had two.
+ * What a namespace could not do is hold state without holding it *globally*, be subclassed, or be
+ * stubbed without mutating the module; `Service` records the three measured consequences.
+ *
+ * **Declared before the namespace below, which is not style.** A namespace merges *into* a class
+ * only when the class comes first - the other order is
+ * `Cannot use namespace 'ListService' as a type`. Merged, `ListService.Options` and
+ * `ListService.Item` still read exactly as they did, so nothing importing a type had to change.
+ */
+export declare class ListService extends Service {
+    /**
+     * `list`: every package in the repository (or, with `changed`/`changedSince`, only the ones that
+     * have actually changed), each with its version, location, private flag, and change status
+     * relative to upstream. Pure data - no console output; `rman list`'s own command decides how to
+     * present it (table, JSON, parseable, names only, or a dependency graph).
+     */
+    getPackages(options?: ListService.Options): Promise<ListService.Item[]>;
+}
 export declare namespace ListService {
     interface Options extends PackageFilterOptions {
         /** Topological order (dependencies before dependents) instead of lexical by directory. */
         toposort?: boolean;
+        /**
+         * Also report the **root package**, first, as the row the members' `depth` is measured from.
+         *
+         * Opt-in rather than always, because it changes what the answer *is*: `repository.packages` is
+         * the workspace members, so every other reader of this list - and the count `rman list` prints -
+         * is about them. `rman list`'s table asks for it because a tree needs a root to hang from; its
+         * `--json`, `--parseable` and `--short` forms do not, and a consumer parsing them sees exactly
+         * what it saw before.
+         */
+        includeRoot?: boolean;
         /** Only include packages that have changed since the last publish (dirty or committed but
          *  not yet published) - or, with `changedSince`, since that specific commit/hash. */
         changed?: boolean;
@@ -12,23 +46,41 @@ export declare namespace ListService {
     }
     interface Item {
         name: string;
+        /** What addresses this package - `"[glob]"` and `--scope` match it. The same as `name` wherever
+         *  the technology names its packages, which is every Node repository; see `Package.selector`. */
+        selector: string;
         version: string;
+        /** The technology that claimed this package's directory - `Package.provider`. Empty when none
+         *  did, which is a repository naming no plugin. */
+        platform: string;
+        /**
+         * How far below the **root package** this one sits: `0` for the root itself, `1` for an ordinary
+         * member, more for a package nested inside another.
+         *
+         * A fact about the package rather than about this list's order, so it is still right under
+         * `--toposort` - which reorders the rows and leaves the nesting where it is.
+         */
+        depth: number;
+        /** Whether this row *is* the root package - present only when `includeRoot` asked for it, or in
+         *  a single-package repository where the root is the one member. */
+        isRoot: boolean;
         location: string;
         private: boolean;
         status: Repository.PackageStatus;
         /** In-repo package names this one depends on - enough to build a dependency graph without a
          *  second call, e.g. `Object.fromEntries(items.map(i => [i.name, i.dependencies]))`. */
         dependencies: string[];
-        /** This package's own (cascaded) `.rmanrc "publish.target"` - `["npm"]` when unset, same
-         *  default `publish` itself uses. */
-        publishTargets: RmanConfig.PublishTarget[];
+        /** Where this package actually ships - its own (cascaded) `.rmanrc "publish.target"` when it
+         *  declares one, otherwise every registered target that claims it, which is the same question
+         *  `publish` asks. Empty in a repository whose plugins contribute no target the package fits. */
+        publishTargets: PublishTargetName[];
         /** Present only when `"docker"` is one of `publishTargets` and `publish.docker` is configured -
          *  the raw `.rmanrc` config, unresolved (no namespace prefixing - see `DockerPublishService`). */
-        docker?: RmanConfig.DockerPublishOptions;
+        docker?: DockerPublishOptions;
+    }
+}
+declare module '../core/service.js' {
+    interface ServiceMap {
+        list: ListService;
     }
-    /** `list`: every package in the repository (or, with `changed`/`changedSince`, only the ones
-     *  that have actually changed), each with its version, location, private flag, and change
-     *  status relative to upstream. Pure data - no console output; `rman list`'s own command
-     *  decides how to present it (table, JSON, parseable, names only, or a dependency graph). */
-    function getPackages(repository: Repository, options?: Options): Promise<Item[]>;
 }

package/services/list.service.js

@@ -1,34 +1,81 @@
 import path from 'path';
+import { targetsOf } from '../core/publish-target.js';
+import { Service } from '../core/service.js';
 import { filterPackages } from '../utils/package-filter.js';
-export var ListService;
-(function (ListService) {
-    /** `list`: every package in the repository (or, with `changed`/`changedSince`, only the ones
-     *  that have actually changed), each with its version, location, private flag, and change
-     *  status relative to upstream. Pure data - no console output; `rman list`'s own command
-     *  decides how to present it (table, JSON, parseable, names only, or a dependency graph). */
-    async function getPackages(repository, options = {}) {
+/**
+ * **A class, and the shape every service follows now.**
+ *
+ * `repository` is gone from the signature - it comes from the application, which is what always
+ * made the parameter redundant: every caller had one and passed it, and no caller ever had two.
+ * What a namespace could not do is hold state without holding it *globally*, be subclassed, or be
+ * stubbed without mutating the module; `Service` records the three measured consequences.
+ *
+ * **Declared before the namespace below, which is not style.** A namespace merges *into* a class
+ * only when the class comes first - the other order is
+ * `Cannot use namespace 'ListService' as a type`. Merged, `ListService.Options` and
+ * `ListService.Item` still read exactly as they did, so nothing importing a type had to change.
+ */
+export class ListService extends Service {
+    /**
+     * `list`: every package in the repository (or, with `changed`/`changedSince`, only the ones that
+     * have actually changed), each with its version, location, private flag, and change status
+     * relative to upstream. Pure data - no console output; `rman list`'s own command decides how to
+     * present it (table, JSON, parseable, names only, or a dependency graph).
+     */
+    async getPackages(options = {}) {
+        const repository = this.repository;
         /** `false`: `list` is the inventory, so a package its own `.rmanrc "skip"` excludes is still
          *  *in* the repository and still listed - hiding it would answer a different question. Every
          *  other caller honours it, being a command that acts rather than reports. */
         const packages = filterPackages(repository.getPackages({ toposort: options.toposort }), options, false);
-        const status = await repository.listStatus({ hash: options.changedSince });
-        let items = packages.map(p => {
-            const target = p.config.publish?.target;
-            const publishTargets = Array.isArray(target) ? target : target ? [target] : ['npm'];
+        const status = await repository.listStatus({ hash: options.changedSince, includeRoot: options.includeRoot });
+        const item = (p) => {
+            /** **Asked, not assumed.** This read the config key directly and defaulted to `['npm']`, so a
+             *  Cargo package in a polyglot repository was reported as shipping to npm - which is what
+             *  `PublishTarget.claims` exists to answer, per target, from the ecosystem that knows. */
+            const publishTargets = targetsOf(this.app, p).map(t => t.name);
             return {
                 name: p.name,
+                selector: p.selector,
                 version: p.version,
+                platform: p.provider,
+                depth: depthOf(p),
+                isRoot: p === repository.rootPackage,
                 location: path.relative(repository.dirname, p.dirname) || '.',
                 private: p.isPrivate,
-                status: status[p.name],
+                status: status[p.selector],
                 dependencies: p.dependencies.map(d => d.name),
                 publishTargets: [...publishTargets],
                 docker: publishTargets.includes('docker') ? p.config.publish?.docker : undefined,
             };
-        });
+        };
+        let items = packages.map(item);
         if (options.changed || options.changedSince)
             items = items.filter(it => it.status !== 'clean');
+        /**
+         * **The root goes on the front, after filtering, and is never filtered out.** It is the tree's
+         * own row - what the members' indentation hangs from - so a `--scope` that narrows the members
+         * still leaves it standing rather than removing the thing they are nested under. A glob never
+         * matches the root anyway (`ROOT_SELECTOR`), so there is no filter here to respect.
+         *
+         * Not in a single-package repository, where `repository.packages` already *is* `[rootPackage]`
+         * and it would appear twice.
+         */
+        if (options.includeRoot && repository.monorepo)
+            items.unshift(item(repository.rootPackage));
         return items;
     }
-    ListService.getPackages = getPackages;
-})(ListService || (ListService = {}));
+}
+/**
+ * How far below the root `pkg` sits, by walking `parent` - `0` for the root itself.
+ *
+ * From the tree edge rather than by counting path segments, which would be a different number: a
+ * package in `packages/a` is two directories down and one *package* down, and it is the second that
+ * the indentation is about.
+ */
+function depthOf(pkg) {
+    let depth = 0;
+    for (let at = pkg.parent; at; at = at.parent)
+        depth++;
+    return depth;
+}

package/services/run.service.d.ts

@@ -1,8 +1,23 @@
 import type { Package } from '../core/package.js';
 import type { Repository } from '../core/repository.js';
 import type { RunStepContext, RunStepFn, RunStepValue } from '../core/run-step.js';
+import { Service } from '../core/service.js';
 import { type LogLevel } from '../utils/logger.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
+/**
+ * A service class - see `ListService` for the shape and `Service` for the three measured
+ * consequences a namespace had.
+ *
+ * **Only `runScript` became a method**, because only it takes a repository. `getConfig`,
+ * `parseIfExpr`, `normalizeScriptValue` and the rest take a `Package` or a raw value and stay
+ * functions on the namespace below - the same rule that leaves `ChangeHashService` a namespace
+ * entirely. Declared before the namespace, which TypeScript requires for the merge.
+ */
+export declare class RunService extends Service {
+    runScript(script: string, options?: RunService.Options & {
+        commandName?: string;
+    }): Promise<void>;
+}
 export declare namespace RunService {
     export interface Options extends PackageFilterOptions {
         /** Max packages built at once: `true`/omitted = CPU count, a number = that many, `false` = serial (1). */
@@ -24,7 +39,7 @@ export declare namespace RunService {
          *  (which otherwise scopes the run to just that package, and skips the root's own pre/post
          *  bookend - see `Repository.currentPackage`). Has no effect when already at the repository
          *  root, or outside any known package. */
-        root?: boolean;
+        fromRoot?: boolean;
     }
     /**
      * A package's `.rmanrc` (cascaded) can configure `run.<script>.*` - e.g.
@@ -89,21 +104,13 @@ export declare namespace RunService {
      *
      * The core knows one source: the config. **`package.json#scripts` is not a source the core has**,
      * because "a script lives in package.json" is true of a Node repository and of nothing else -
-     * `rman-node` contributes that one (with npm's `pre<script>`/`post<script>` convention and its
+     * the `node` built-in contributes that one (with npm's `pre<script>`/`post<script>` convention and its
      * `&&` splitting), and a plugin for another ecosystem would contribute its own.
      *
      * Returns `undefined` for "this package declares nothing", not empty slots - the difference
      * decides whether the config's value applies.
      */
     export type StepSource = (pkg: Package, script: string) => ScriptSlots | undefined;
-    /**
-     * Registers a source. Called by `loadPlugins` for each plugin's `runSteps`, in `plugins`
-     * declaration order - never as an import side effect, so what is registered is exactly what the
-     * repository's `.rmanrc` asked for.
-     */
-    export function addStepSource(source: StepSource): void;
-    /** For tests, which would otherwise leak a source into every later case in the process. */
-    export function clearStepSources(): void;
     /**
      * What the *package itself* declares for the lifecycle `script`, from the contributed sources
      * alone - no `.rmanrc` involved. `undefined` when it declares nothing.
@@ -193,9 +200,6 @@ export declare namespace RunService {
     /** Evaluates a parsed `if` expression for one package. `statusCache` avoids repeat `git` calls
      *  for the same reference hash across packages/scripts in a single run. */
     export function evaluateIf(repository: Repository, pkg: Package, node: IfNode, statusCache: Map<string, Record<string, Repository.PackageStatus>>): Promise<boolean>;
-    export function runScript(repository: Repository, script: string, options?: Options & {
-        commandName?: string;
-    }): Promise<void>;
     export {};
 }
 /** Resolution order: explicit CLI flag > the package's resolved `.rmanrc` > `fallback`. */
@@ -208,3 +212,8 @@ export declare function resolveBool(cliValue: boolean | undefined, pkg: Package,
 export declare function resolveBail(cliValue: boolean | undefined, pkg: Package, script: string, fallback: boolean): boolean;
 export declare function resolveNumber(cliValue: number | undefined, pkg: Package, script: string, key: string, fallback: number): number;
 export declare function resolveLogLevel(cliValue: LogLevel | undefined, pkg: Package, script: string, fallback: LogLevel): LogLevel;
+declare module '../core/service.js' {
+    interface ServiceMap {
+        run: RunService;
+    }
+}