rman 1.3.0 → 2.0.0-beta.2

package/plugins/node/services/clean.service.d.ts

@@ -0,0 +1,53 @@
+import type { Repository } from '../../../core/repository.js';
+import type { LogLevel } from '../../../utils/logger.js';
+import type { PackageFilterOptions } from '../../../utils/package-filter.js';
+export declare namespace CleanService {
+    interface Options extends PackageFilterOptions {
+        /** Show the live progress panel. Default true; auto-disabled when stdout isn't a TTY. */
+        progress?: boolean;
+        /** Report what would be removed without actually removing anything. Default false. */
+        dryRun?: boolean;
+        /** Clean the whole repository even when the current directory is inside a single package
+         *  (which otherwise scopes cleaning to just that package - see `Repository.currentPackage`).
+         *  Has no effect when already at the repository root, or outside any known package. */
+        fromRoot?: boolean;
+        /** Verbosity of the classic per-item log (only applies when the live panel is off). Falls back
+         *  to the root's `.rmanrc logLevel`, then 'info' - see `resolveRootLogLevel`. */
+        logLevel?: LogLevel;
+    }
+    /**
+     * `clean`: removes build output across every package (root included) - the replacement for
+     * `ts-cleanup`, plus whatever else `.rmanrc clean.include`/`clean.exclude` says to remove.
+     *
+     * **The `node` built-in's rather than always present, because what it knows how to delete is not
+     * repository-shaped knowledge but TypeScript-shaped**: a compiled `.js`/`.js.map`/`.d.ts` beside
+     * its `.ts` source, a `*.tsbuildinfo`, and a `node_modules` to skip while looking. A Cargo or Go
+     * repository has `cargo clean` and `go clean` and nothing here would fire for it, so a core
+     * `clean` was a command that only appeared to be general.
+     *
+     * The `clean.include`/`clean.exclude` globs move with it, and that is the one cost worth naming:
+     * they are ecosystem-neutral, so a repository wanting only those now has to name this plugin (or
+     * write the two `rm` lines as a `run` script). Keeping a stub `clean` in core for them would mean
+     * two commands with one name and a precedence rule between them - worse than the honest move.
+     *
+     * For every package not opted out via its own (cascaded) `clean.skip: true`:
+     *  - deletes compiled `.js`/`.js.map`/`.d.ts` files under its `src`/`test` (see `cleanTsArtifacts`);
+     *  - deletes any `*.tsbuildinfo` incremental-build cache file anywhere in it;
+     *  - deletes anything matching its own (cascaded) `clean.include` glob(s), minus `clean.exclude`.
+     *
+     * `include`/`exclude` are resolved relative to *that* package's own directory - a root-level
+     * `.rmanrc` pattern like `packages/*\/build` is naturally evaluated from the repository root
+     * (spanning every package in one pass), while a package's own override in its own `.rmanrc`
+     * (e.g. `include: ./cache`) only ever reaches that one package, since a package normally
+     * overrides rather than merges with the root's value for the same key.
+     *
+     * Never touches `node_modules` - that's `ci`'s job, not this one.
+     *
+     * Run from inside a single package's own directory, it only cleans that package unless
+     * `options.fromRoot` says otherwise (see `Repository.currentPackage`).
+     *
+     * Uses the same live progress panel as `run`/`build` (see `../utils/progress-panel.ts`) - unlike
+     * `ci`, cleaning genuinely is independent per-package work, so the final per-package tally stays.
+     */
+    function clean(repository: Repository, options?: Options): Promise<void>;
+}

package/plugins/node/services/clean.service.js

@@ -0,0 +1,237 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import colors from 'ansi-colors';
+import fg from 'fast-glob';
+import { Logger, resolveRootLogLevel } from '../../../utils/logger.js';
+import { filterPackages } from '../../../utils/package-filter.js';
+import { ProgressPanel } from '../../../utils/progress-panel.js';
+export var CleanService;
+(function (CleanService) {
+    /**
+     * `clean`: removes build output across every package (root included) - the replacement for
+     * `ts-cleanup`, plus whatever else `.rmanrc clean.include`/`clean.exclude` says to remove.
+     *
+     * **The `node` built-in's rather than always present, because what it knows how to delete is not
+     * repository-shaped knowledge but TypeScript-shaped**: a compiled `.js`/`.js.map`/`.d.ts` beside
+     * its `.ts` source, a `*.tsbuildinfo`, and a `node_modules` to skip while looking. A Cargo or Go
+     * repository has `cargo clean` and `go clean` and nothing here would fire for it, so a core
+     * `clean` was a command that only appeared to be general.
+     *
+     * The `clean.include`/`clean.exclude` globs move with it, and that is the one cost worth naming:
+     * they are ecosystem-neutral, so a repository wanting only those now has to name this plugin (or
+     * write the two `rm` lines as a `run` script). Keeping a stub `clean` in core for them would mean
+     * two commands with one name and a precedence rule between them - worse than the honest move.
+     *
+     * For every package not opted out via its own (cascaded) `clean.skip: true`:
+     *  - deletes compiled `.js`/`.js.map`/`.d.ts` files under its `src`/`test` (see `cleanTsArtifacts`);
+     *  - deletes any `*.tsbuildinfo` incremental-build cache file anywhere in it;
+     *  - deletes anything matching its own (cascaded) `clean.include` glob(s), minus `clean.exclude`.
+     *
+     * `include`/`exclude` are resolved relative to *that* package's own directory - a root-level
+     * `.rmanrc` pattern like `packages/*\/build` is naturally evaluated from the repository root
+     * (spanning every package in one pass), while a package's own override in its own `.rmanrc`
+     * (e.g. `include: ./cache`) only ever reaches that one package, since a package normally
+     * overrides rather than merges with the root's value for the same key.
+     *
+     * Never touches `node_modules` - that's `ci`'s job, not this one.
+     *
+     * Run from inside a single package's own directory, it only cleans that package unless
+     * `options.fromRoot` says otherwise (see `Repository.currentPackage`).
+     *
+     * Uses the same live progress panel as `run`/`build` (see `../utils/progress-panel.ts`) - unlike
+     * `ci`, cleaning genuinely is independent per-package work, so the final per-package tally stays.
+     */
+    async function clean(repository, options = {}) {
+        /** Standing inside a single package's own directory scopes cleaning to just that package
+         *  (root's own artifacts included) unless `--from-root` asks for the whole repository anyway - a
+         *  no-op when already at the root, or outside any known package. */
+        const cwdScope = options.fromRoot ? undefined : repository.currentPackage;
+        const packages = repository.getPackages().filter(p => p !== repository.rootPackage);
+        const allTargets = cwdScope ? [cwdScope] : [repository.rootPackage, ...packages];
+        const targets = filterPackages(allTargets, options).filter(pkg => !cleanConfig(pkg).skip);
+        const dryRun = options.dryRun ?? false;
+        const progress = options.progress ?? true;
+        const logger = new Logger(options.logLevel ?? resolveRootLogLevel(repository));
+        const panel = new ProgressPanel(dryRun ? 'CLEAN (dry-run)' : 'CLEAN', !!process.stdout.isTTY && progress);
+        panel.start();
+        let failed = false;
+        try {
+            const results = await Promise.allSettled(targets.map(pkg => {
+                const label = pkg === repository.rootPackage ? 'root' : pkg.name;
+                return cleanPackage(pkg, panel.addItem(label), panel.enabled, dryRun, logger);
+            }));
+            if (results.some(r => r.status === 'rejected'))
+                failed = true;
+        }
+        finally {
+            panel.stop();
+        }
+        panel.printSummary();
+        if (failed) {
+            const err = new Error('"clean" failed');
+            err.logged = true;
+            throw err;
+        }
+    }
+    CleanService.clean = clean;
+})(CleanService || (CleanService = {}));
+/** Directories a package's TypeScript output gets cleaned from, mirroring `ts-cleanup -s src`
+ *  and `-s test` (the only way it was ever actually invoked in this project's own scripts). */
+const TS_SOURCE_DIRS = ['src', 'test'];
+/** A package's (cascaded) `.rmanrc clean.include`/`clean.exclude`/`clean.skip` - a package that
+ *  declares its own `clean` block replaces the root's entirely for itself (same as any other
+ *  rman config key), rather than combining with it. `include`/`exclude` accept a single glob
+ *  string or an array of them. */
+function cleanConfig(pkg) {
+    const cfg = pkg.config?.clean;
+    const normalize = (v) => {
+        if (Array.isArray(v))
+            return v.map(String);
+        return typeof v === 'string' && v ? [v] : [];
+    };
+    return { include: normalize(cfg?.include), exclude: normalize(cfg?.exclude), skip: cfg?.skip === true };
+}
+/** Deletes `file`, unless `dryRun` - either way the caller treats it as removed for reporting. */
+async function remove(file, dryRun) {
+    if (!dryRun)
+        await fs.promises.rm(file, { force: true });
+}
+/** Removes now-empty directories under `dir`, deepest first (so a parent left empty once its
+ *  only child is removed gets caught in the same pass). Also removes `dir` itself once empty
+ *  when `includeSelf` is set - used when `dir` is itself something the user asked to delete
+ *  (e.g. an `include: build` match), as opposed to a source root like `src`/`test` that should
+ *  stay even if everything inside it was cleaned out. No-op in dry-run mode: nothing was actually
+ *  deleted, so there's nothing that could have been left empty. */
+function pruneEmptyDirs(dir, includeSelf, dryRun) {
+    if (dryRun || !fs.existsSync(dir))
+        return;
+    const entries = fg.sync('**', { cwd: dir, onlyDirectories: true, dot: true });
+    entries.sort((a, b) => b.split(path.sep).length - a.split(path.sep).length);
+    for (const rel of entries) {
+        const abs = path.join(dir, rel);
+        if (fs.existsSync(abs) && fs.readdirSync(abs).length === 0)
+            fs.rmdirSync(abs);
+    }
+    if (includeSelf && fs.readdirSync(dir).length === 0)
+        fs.rmdirSync(dir);
+}
+/**
+ * Deletes every path matched by `include` (minus `exclude`) under `dirname` - files and
+ * directories alike, gulp-`src()`-style. Returns what was actually removed (or, in dry-run mode,
+ * what *would* be), relative to `dirname`, so the caller only logs what really happened.
+ *
+ * `exclude` protects at two levels: a pattern matching a whole `include` result directly (e.g.
+ * `packages/pkg1/*` against a matched `packages/pkg1/build` directory) drops that result before
+ * anything under it is touched; a finer pattern (e.g. `build/*.json`) instead protects just the
+ * matching files *inside* an otherwise-deleted directory, leaving the rest of it gone and the
+ * protected files (and their now non-empty parent) in place.
+ */
+async function cleanGlobs(dirname, include, exclude, dryRun) {
+    if (!include.length)
+        return [];
+    const matches = await fg(include, { cwd: dirname, ignore: exclude, onlyFiles: false, dot: true, absolute: true });
+    const protectedFiles = exclude.length
+        ? new Set(await fg(exclude, { cwd: dirname, onlyFiles: true, dot: true, absolute: true }))
+        : new Set();
+    const removed = [];
+    for (const m of matches) {
+        const stat = await fs.promises.stat(m).catch(() => undefined);
+        if (!stat)
+            continue;
+        if (stat.isDirectory()) {
+            const filesInside = await fg('**', { cwd: m, onlyFiles: true, dot: true, absolute: true });
+            for (const f of filesInside) {
+                if (protectedFiles.has(f))
+                    continue;
+                await remove(f, dryRun);
+                removed.push(path.relative(dirname, f));
+            }
+            pruneEmptyDirs(m, true, dryRun);
+        }
+        else if (!protectedFiles.has(m)) {
+            await remove(m, dryRun);
+            removed.push(path.relative(dirname, m));
+        }
+    }
+    return removed;
+}
+/**
+ * Removes compiled TypeScript output (`.js`, `.js.map`, `.d.ts`) sitting next to its `.ts`
+ * source under `src`/`test` - the same job `ts-cleanup -s <dir> --all` did (the only mode this
+ * project ever actually used it in). A `.d.ts` with no matching `.ts`/`.tsx` is left alone - it's
+ * presumably a hand-written declaration file, not build output. Prunes directories left empty
+ * afterward.
+ */
+async function cleanTsArtifacts(dirname, dryRun) {
+    const removed = [];
+    for (const sub of TS_SOURCE_DIRS) {
+        const dir = path.join(dirname, sub);
+        if (!fs.existsSync(dir))
+            continue;
+        const files = await fg('**/*.{js,js.map,d.ts}', { cwd: dir, onlyFiles: true, dot: true, absolute: true });
+        for (const f of files) {
+            if (f.endsWith('.d.ts')) {
+                const base = f.slice(0, -'.d.ts'.length);
+                if (!fs.existsSync(base + '.ts') && !fs.existsSync(base + '.tsx'))
+                    continue;
+            }
+            await remove(f, dryRun);
+            removed.push(path.relative(dirname, f));
+        }
+        pruneEmptyDirs(dir, false, dryRun);
+    }
+    return removed;
+}
+/**
+ * Removes TypeScript's incremental-build cache files (`*.tsbuildinfo`) anywhere under `dirname` -
+ * `tsc --build`/`composite`/`incremental` output that `ts-cleanup` never touched, but which can
+ * leave a project in a stale state if a clean rebuild is expected to start from nothing. Skips
+ * `node_modules` (dependencies may ship their own, irrelevant to this package's own build).
+ */
+async function cleanTsBuildInfo(dirname, dryRun) {
+    const files = await fg('**/*.tsbuildinfo', {
+        cwd: dirname,
+        ignore: ['**/node_modules/**'],
+        onlyFiles: true,
+        dot: true,
+        absolute: true,
+    });
+    for (const f of files)
+        await remove(f, dryRun);
+    return files.map(f => path.relative(dirname, f));
+}
+async function cleanPackage(pkg, item, panelEnabled, dryRun, logger) {
+    item.status = 'running';
+    item.startedAt = Date.now();
+    try {
+        item.currentStep = 'ts';
+        const tsRemoved = await cleanTsArtifacts(pkg.dirname, dryRun);
+        const buildInfoRemoved = await cleanTsBuildInfo(pkg.dirname, dryRun);
+        item.currentStep = 'glob';
+        const { include, exclude } = cleanConfig(pkg);
+        const globRemoved = await cleanGlobs(pkg.dirname, include, exclude, dryRun);
+        const removed = [...tsRemoved, ...buildInfoRemoved, ...globRemoved];
+        const verb = dryRun ? 'would rm' : 'rm';
+        if (panelEnabled) {
+            item.lastLine = removed.length
+                ? `${dryRun ? 'would remove' : 'removed'} ${removed.length} item(s)`
+                : 'already clean';
+        }
+        else if (removed.length) {
+            for (const r of removed)
+                logger.info(colors.yellow(verb), colors.cyan(item.name), r);
+        }
+        else {
+            logger.info(colors.gray('clean'), colors.cyan(item.name));
+        }
+        item.status = 'success';
+    }
+    catch (e) {
+        item.status = 'failed';
+        item.log.push(e?.message ?? String(e));
+        throw e;
+    }
+    finally {
+        item.finishedAt = Date.now();
+    }
+}

package/plugins/node/services/publish.service.d.ts

@@ -0,0 +1,114 @@
+import type { Package } from '../../../core/package.js';
+import type { Repository } from '../../../core/repository.js';
+import type { PackageFilterOptions } from '../../../utils/package-filter.js';
+import { type NpmPackageView } from '../utils/npm-view.js';
+import { CiService } from './ci.service.js';
+export declare namespace PublishService {
+    /** Injectable registry lookup - mainly for tests, so they don't depend on network access or a
+     *  real published package. */
+    interface Deps {
+        npmViewPackage?: (name: string, cwd: string) => Promise<NpmPackageView | undefined>;
+    }
+    interface Options extends PackageFilterOptions {
+        /** A package with uncommitted local changes is excluded (status `'skip'`) instead of aborting
+         *  the whole plan (status `'error'`) - same as `version`'s own option. Default false. */
+        ignoreDirty?: boolean;
+        /** Registry to check against (and, in `applyPlan`, publish to) - `.npmrc`'s own configured
+         *  registry is used when omitted. */
+        registry?: string;
+        /** Path to a custom `.npmrc`, for both the registry check and the actual publish. */
+        userconfig?: string;
+        /**
+         * `npm publish --tag <tag>` - the dist-tag to publish under, overriding what the version
+         * itself implies.
+         *
+         * **Usually unnecessary**: a prerelease is published under its own identifier (`2.0.0-beta.1`
+         * -> `beta`) and a release under npm's `latest`, neither needing to be asked for. Pass this to
+         * send a release somewhere other than `latest`, or a prerelease to a tag that is not its
+         * identifier (`next` for every preview, say). See `distTagFor`.
+         *
+         * **A plan option rather than an apply-only one**, because the tag is decided in the plan: it
+         * is printed beside each package and recorded as `Entry.distTag`, so `--dry-run` and the JSON
+         * a release pipeline gates on both show where a version is going.
+         */
+        tag?: string;
+    }
+    interface ApplyOptions extends Options {
+        packageManager?: CiService.PackageManager;
+        /** `npm publish --access <access>` - required by the registry for a *new* scoped package. */
+        access?: 'public' | 'restricted';
+        /** `npm publish --otp <otp>` - a 2FA one-time password, for registries that require it. */
+        otp?: string;
+        /** Subdirectory to publish from, relative to the package's own directory - only consulted when
+         *  the package doesn't already declare its own `package.json` `publishConfig.directory` (npm's
+         *  native mechanism for this, which always wins when present). */
+        contents?: string;
+    }
+    /** One package's outcome in a publish plan - see `getPlan`. */
+    interface Entry {
+        package: Package;
+        version: string;
+        status: 'publish' | 'skip' | 'up-to-date' | 'error';
+        /** What the registry's **`latest` dist-tag** points at, if anything - only set once a registry
+         *  check actually ran. Reported rather than compared: whether *this* version is published is a
+         *  different question, and `getPlan` answers it from the published `versions`. */
+        registryVersion?: string;
+        /**
+         * The dist-tag this entry will publish under - `--tag` when given, otherwise the version's own
+         * prerelease identifier (`2.0.0-beta.1` -> `beta`), and `undefined` for an ordinary release,
+         * which npm puts on `latest`.
+         *
+         * **Decided in the plan and read back by `applyPlan`, rather than recomputed there.** The plan
+         * is what a reader confirms and what a pipeline gates on, so the tag has to be part of what it
+         * says; recomputing at publish time would let the two disagree about where a package is going.
+         */
+        distTag?: string;
+        /** `PublishTarget.Entry`'s own field - what the core's `publish` prints beside the package
+         *  name. Carries the dist-tag, so where a version is going is visible in the plan and in
+         *  `--dry-run --json` without the core knowing anything about npm. */
+        detail?: string;
+        reason?: string;
+    }
+    /**
+     * Computes what `publish` *would* do, across every non-private package (topological order,
+     * dependencies before dependents) - never touches the registry to publish anything, just
+     * queries it to decide, so it's safe to call any time, including as the plan a bare `rman
+     * publish` shows before asking for confirmation.
+     *
+     * A `private: true` package is always `'skip'`ped outright. Each remaining package's **dist-tag**
+     * is settled next (`distTagFor`): usually derived from the version itself, `'error'` in the two
+     * cases with nothing to derive - that one is about the invocation rather than the package, so it
+     * is answered before anything touches the network. A package with uncommitted local changes is
+     * `'error'` too (aborts the whole plan) unless `options.ignoreDirty` downgrades it to `'skip'`
+     * instead - same rule `version` uses, since publishing untracked local edits is worse than a bad
+     * commit.
+     *
+     * Otherwise the registry decides, via one `npmViewPackage` per remaining package (run
+     * concurrently): **the local version being among the published `versions`** is `'up-to-date'`,
+     * anything else - including never having been published at all - is `'publish'`. Deliberately not
+     * a comparison against `latest`, which answers a different question and disagrees with this one
+     * the moment a prerelease ships under its own dist-tag; see `npmViewPackage`.
+     *
+     * Deliberately decoupled from `version`: this only ever looks at what's *currently* on disk and
+     * on the registry, never at whether `version` was just run - so it works equally well right
+     * after a version bump, or standing alone in a release pipeline that bumped days earlier.
+     *
+     * A monorepo's root package is never a candidate at all - `repository.getPackages()` already
+     * excludes it for a real monorepo (it only doubles as "the" package in a single-package repo,
+     * where it's a normal candidate like any other).
+     */
+    function getPlan(repository: Repository, options?: Options, deps?: Deps): Promise<Entry[]>;
+    /**
+     * Publishes every `'publish'` entry in `plan`, topological order (already `plan`'s own order -
+     * see `getPlan`), via the configured `packageManager`'s own `publish` command. Sequential, not
+     * concurrent: unlike `run`/`build`, a package genuinely needs its own dependencies to have
+     * landed on the registry first, and publishing is rare enough (once per release) that the
+     * simplicity is worth more than the parallelism `run` gets from `power-tasks`.
+     *
+     * If a package fails, every other still-pending entry depending on it (transitively) is marked
+     * `'error'` too and never attempted - publishing a package whose own new dependency range points
+     * at a version that never actually reached the registry would hand consumers a broken install.
+     * A package's own failure doesn't stop unrelated packages elsewhere in the plan, though.
+     */
+    function applyPlan(repository: Repository, plan: Entry[], options?: ApplyOptions): Promise<Entry[]>;
+}