rman 1.0.2 → 1.0.5

package/README.md

@@ -9,7 +9,7 @@
 Changesets, and a handful of shell scripts glued together. One tool for running scripts across
 packages, computing semantic version bumps from your commit history, publishing, changelogs,
 importing external repos with history intact, and more - all driven by a single, cascading
-`.rmanrc`/`.rman.yml` config.
+`.rmanrc`/`.rmanrc.yml` config.
 
 Every command is also available as a **programmatic API** - see [docs/api.md](docs/api.md) if you
 want to call `rman`'s logic directly from a Node.js script instead of shelling out to the CLI.
@@ -243,6 +243,7 @@ rman version --changelog         # also write/fold in each bumped package's CHAN
 rman version patch --push        # commit, tag, and push in one go
 rman version patch --message "chore(release): {version}"
 rman version --ignore-dirty      # exclude dirty packages instead of aborting the whole run
+rman version patch --show        # preview what an explicit patch bump would do, without applying it
 ```
 
 Severity, when not given explicitly, is auto-detected per package/group from
@@ -298,12 +299,13 @@ covered, then run `rman ci` to install it.
 
 `rman` reads config cascaded from the repository root down to each package's own directory (the
 same way a `tsconfig.json` `extends` chain works) - a value set closer to a package overrides the
-same key set further up. Three file forms are supported per directory, merged in increasing
-precedence: `package.json`'s own `"rman"` key, `.rman.yml` (YAML), and `.rmanrc` (**JSON**, despite
-the dotfile-style name).
+same key set further up. Several file forms are supported per directory, merged in increasing
+precedence: `package.json`'s own `"rman"` key, `.rmanrc.yml` (YAML), `.rmanrc` (**JSON**, despite
+the dotfile-style name), and `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js` for config that needs real
+logic (a JS module's default export).
 
 ```yaml
-# .rman.yml, at the repository root
+# .rmanrc.yml, at the repository root
 packageManager: pnpm
 logLevel: info
 allowBranch: [main, release/*]
@@ -337,14 +339,23 @@ run:
 { "group": "plugins" }
 ```
 
-See [docs/api.md#configuration-rmanrc-rmanyml](docs/api.md#configuration-rmanrc-rmanyml) for the
+See [docs/api.md#configuration-rmanrc-rmanrcyml](docs/api.md#configuration-rmanrc-rmanrcyml) for the
 full key reference (every `run.<script>.*` sub-key, `clean.*`, `changelog.*`, precedence rules,
 and which keys are root-level-only today).
 
-**Editor autocomplete:** `rman` ships a JSON Schema for `.rmanrc`/`.rman.yml` at
+**Editor autocomplete:** `rman` ships a JSON Schema for `.rmanrc`/`.rmanrc.yml` at
 `rman/rmanrc.schema.json` - add `"$schema": "./node_modules/rman/rmanrc.schema.json"` to your
-`.rmanrc` (or the equivalent `# yaml-language-server: $schema=...` comment in `.rman.yml`) to get
-autocomplete and validation in VS Code/WebStorm. See
+`.rmanrc` (or the equivalent `# yaml-language-server: $schema=...` comment in `.rmanrc.yml`) to get
+autocomplete and validation in VS Code/WebStorm. For a `.rmanrc.cjs`/`.mjs`/`.js` config, wrap it in
+the exported `defineConfig()` helper instead for the same autocomplete via the `RmanConfig` type:
+
+```js
+// .rmanrc.mjs
+import { defineConfig } from 'rman';
+export default defineConfig({ packageManager: 'pnpm' });
+```
+
+See
 [docs/api.md#editor-support-json-schema](docs/api.md#editor-support-json-schema) for details,
 including a WebStorm setup that needs no changes to the config file itself.
 
@@ -356,7 +367,7 @@ from your own Node.js scripts without shelling out to the `rman` binary:
 ```ts
 import { Repository, VersionService } from 'rman';
 
-const repository = Repository.create();
+const repository = await Repository.create();
 const plan = await VersionService.getPlan(repository);
 await VersionService.applyPlan(repository, plan, { changelog: true, push: true });
 ```

package/cli.js

@@ -23,7 +23,7 @@ import { Repository } from './core/repository.js';
 import { LOG_LEVELS } from './utils/logger.js';
 export async function runCli(options) {
     try {
-        const repository = Repository.create(options?.cwd);
+        const repository = await Repository.create(options?.cwd);
         const _argv = options?.argv || hideBin(process.argv);
         const program = yargs(_argv)
             .scriptName('rman')

package/commands/version.command.js

@@ -1,5 +1,6 @@
 import readline from 'node:readline/promises';
 import colors from 'ansi-colors';
+import EasyTable from 'easy-table';
 import { VersionService } from '../services/version.service.js';
 import { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
 import { applyPackageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
@@ -11,6 +12,7 @@ export function initCli(repository, program) {
             .example('$0 version patch', '# Bump patch severity directly, applied immediately')
             .example('$0 version', "# Auto-detect severity from commits, show the plan, don't write anything")
             .example('$0 version --interactive', '# Show the plan either way, then ask for confirmation')
+            .example('$0 version patch --show', '# Preview what an explicit patch bump would do, without applying it')
             .positional('bump', {
             describe: 'A release-type keyword ("patch"/"minor"/"major") or an explicit semver version. ' +
                 'Omit to auto-detect from commits and only preview the plan.',
@@ -21,6 +23,13 @@ export function initCli(repository, program) {
             describe: 'Show the plan and ask for confirmation before applying (with or without an explicit bump)',
             type: 'boolean',
         })
+            .option('show', {
+            describe: 'Show the resulting plan for the given bump without applying it - unlike omitting bump ' +
+                'entirely, this still uses the given release-type keyword/version to compute the plan, ' +
+                'just never writes it.',
+            type: 'boolean',
+        })
+            .conflicts('show', 'interactive')
             .option('ignore-dirty', {
             describe: 'Exclude a package with uncommitted local changes instead of aborting the whole run',
             type: 'boolean',
@@ -70,6 +79,10 @@ export function initCli(repository, program) {
                 console.log(colors.gray('Nothing to version.'));
                 return;
             }
+            if (args.show) {
+                console.log(colors.gray('Preview only (--show) - nothing was written.'));
+                return;
+            }
             let apply = !!bump;
             if (args.interactive) {
                 apply = await confirm('Apply these changes?');
@@ -94,23 +107,29 @@ export function initCli(repository, program) {
     });
 }
 function printPlan(entries) {
+    const table = new EasyTable();
     for (const e of entries) {
-        const name = colors.cyan(e.package.name);
-        const group = colors.gray(`(${e.group})`);
-        switch (e.status) {
-            case 'bump':
-                console.log(colors.green('bump'), name, group, e.from, '->', colors.yellow(e.to), colors.gray(e.reason ?? ''));
-                break;
-            case 'no-change':
-                console.log(colors.gray('no-change'), name, group, e.from);
-                break;
-            case 'skip':
-                console.log(colors.cyan('skip'), name, group, colors.gray(e.reason ?? ''));
-                break;
-            case 'error':
-                console.log(colors.red('error'), name, group, colors.red(e.reason ?? ''));
-                break;
-        }
+        table.cell('Status', statusLabel(e.status));
+        table.cell('Package', colors.cyan(e.package.name));
+        table.cell('Group', colors.gray(`(${e.group})`));
+        table.cell('From', e.from);
+        table.cell('', e.status === 'bump' ? '->' : '');
+        table.cell('To', e.status === 'bump' ? colors.yellow(e.to) : '');
+        table.cell('Reason', e.status === 'error' ? colors.red(e.reason ?? '') : colors.gray(e.reason ?? ''));
+        table.newRow();
+    }
+    console.log(table.toString().trim());
+}
+function statusLabel(status) {
+    switch (status) {
+        case 'bump':
+            return colors.green('bump');
+        case 'no-change':
+            return colors.gray('no-change');
+        case 'skip':
+            return colors.cyan('skip');
+        case 'error':
+            return colors.red('error');
     }
 }
 async function confirm(question) {

package/constants.js

@@ -1 +1 @@
-export const version = '1.0.2';
+export const version = '1.0.5';

package/core/config.d.ts

@@ -1,8 +1,82 @@
+/**
+ * The shape of `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` (and `package.json`'s own
+ * `"rman"` key) - see docs/api.md#configuration-rmanrc-rmanrcyml for the full reference. Every
+ * field is optional and cascades from the repository root down to each package's own directory.
+ * Purely a typing aid (used by `defineConfig` below, and importable on its own for a `.rmanrc.ts`/
+ * `.mts` authored config, or a plain `: RmanConfig` annotation) - never read by rman itself, which
+ * only ever sees the plain JS object a JS config file exports.
+ */
+export interface RmanConfig {
+    packageManager?: 'npm' | 'yarn' | 'pnpm' | 'bun';
+    logLevel?: 'silent' | 'error' | 'info' | 'verbose';
+    allowBranch?: string | string[];
+    ignoreBranch?: string | string[];
+    group?: boolean | string;
+    version?: RmanConfig.VersionOptions;
+    changelog?: RmanConfig.ChangelogOptions;
+    clean?: RmanConfig.CleanOptions;
+    /** Keyed by npm script name (e.g. `"build"`, `"lint"`, `"test"`). */
+    run?: Record<string, RmanConfig.RunScriptOptions>;
+    /** Keyed by the in-repo package's own name. */
+    packages?: Record<string, RmanConfig.PackageOptions>;
+}
+export declare namespace RmanConfig {
+    interface VersionOptions {
+        commitMessage?: string;
+        script?: string | string[];
+        preScript?: string | string[];
+        postScript?: string | string[];
+    }
+    interface ChangelogOptions {
+        ignoreTypes?: string[];
+        template?: string;
+        filePath?: string;
+        tagPattern?: string;
+    }
+    interface CleanOptions {
+        include?: string | string[];
+        exclude?: string | string[];
+        skip?: boolean;
+    }
+    interface RunScriptOptions {
+        concurrency?: number;
+        topo?: boolean;
+        bail?: boolean;
+        progress?: boolean;
+        logLevel?: 'silent' | 'error' | 'info' | 'verbose';
+        changedSince?: string;
+        skip?: boolean;
+        if?: string;
+        script?: string | string[];
+        preScript?: string | string[];
+        postScript?: string | string[];
+        override?: boolean;
+    }
+    interface PackageOptions {
+        dependencies?: string[] | Record<string, string>;
+    }
+}
+/**
+ * Identity helper for authoring a `.rmanrc.cjs`/`.mjs`/`.js` config with full type-checking and
+ * autocomplete - the same `defineConfig` pattern Vite/Vitest use. Returns `config` completely
+ * unchanged; this exists purely so TypeScript can infer/check against `RmanConfig`, not for any
+ * runtime behavior:
+ *
+ *   // .rmanrc.mjs
+ *   import { defineConfig } from 'rman';
+ *   export default defineConfig({ packageManager: 'pnpm' });
+ *
+ *   // .rmanrc.cjs
+ *   const { defineConfig } = require('rman');
+ *   module.exports = defineConfig({ packageManager: 'pnpm' });
+ */
+export declare function defineConfig(config: RmanConfig): RmanConfig;
 /**
  * Reads the rman configuration defined at a single directory level, merging
- * (in increasing precedence): `package.json#rman`, `.rman.yml`, `.rmanrc`.
+ * (in increasing precedence): `package.json#rman`, `.rmanrc.yml`, `.rmanrc`,
+ * then `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js` (whichever exist, in that order).
  */
-export declare function readDirConfig(dirname: string): any;
+export declare function readDirConfig(dirname: string): Promise<RmanConfig>;
 /**
  * Resolves the effective config for `targetDir` by cascading from `rootDir`
  * down to `targetDir` (inclusive), the same way tsconfig's `extends` chain
@@ -10,4 +84,4 @@ export declare function readDirConfig(dirname: string): any;
  * package (or any intermediate directory) narrow or override the repository's
  * root configuration for itself and everything below it.
  */
-export declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, any>): any;
+export declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, RmanConfig>): Promise<RmanConfig>;

package/core/config.js

@@ -1,12 +1,60 @@
 import fs from 'fs';
 import * as yaml from 'js-yaml';
+import { createRequire } from 'module';
 import path from 'path';
 import merge from 'putil-merge';
+import { pathToFileURL } from 'url';
+/**
+ * Identity helper for authoring a `.rmanrc.cjs`/`.mjs`/`.js` config with full type-checking and
+ * autocomplete - the same `defineConfig` pattern Vite/Vitest use. Returns `config` completely
+ * unchanged; this exists purely so TypeScript can infer/check against `RmanConfig`, not for any
+ * runtime behavior:
+ *
+ *   // .rmanrc.mjs
+ *   import { defineConfig } from 'rman';
+ *   export default defineConfig({ packageManager: 'pnpm' });
+ *
+ *   // .rmanrc.cjs
+ *   const { defineConfig } = require('rman');
+ *   module.exports = defineConfig({ packageManager: 'pnpm' });
+ */
+export function defineConfig(config) {
+    return config;
+}
+/** `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js`, checked in this order - a JS module whose default
+ *  export (or, lacking one, the module's own exports object) is the config. Both CommonJS (`.cjs`,
+ *  or a `.js` under a `"type": "commonjs"` package.json) and native ESM (`.mjs`, or a `.js` under
+ *  `"type": "module"`) are supported - the reason `readDirConfig`/`resolveConfig` are async at all. */
+const JS_CONFIG_FILES = ['.rmanrc.cjs', '.rmanrc.mjs', '.rmanrc.js'];
+const requireJsConfig = createRequire(import.meta.url);
+/**
+ * Loads `file`'s config object. Tries `require()` first - not just an optimization: a CommonJS
+ * module's `module.exports` is more reliably observed this way than through dynamic `import()`'s
+ * CJS-interop synthesis, which some ESM loader hooks (e.g. ts-node/swc-node-style transpilers
+ * registered via `--import`) can end up short-circuiting into an empty object. `require()` throws
+ * `ERR_REQUIRE_ESM` for a genuinely-ESM file (`.mjs`, or `.js` under `"type": "module"`) - only
+ * then does this fall back to `import()`, the one case that actually needs it. Either path can
+ * hand back an ES module namespace instead of a plain object (Node's `require(esm)` support does
+ * this too, not just `import()`), so `.default` is preferred whenever present.
+ */
+async function loadJsConfig(file) {
+    let mod;
+    try {
+        mod = requireJsConfig(file);
+    }
+    catch (e) {
+        if (e?.code !== 'ERR_REQUIRE_ESM')
+            throw e;
+        mod = await import(pathToFileURL(file).href);
+    }
+    return mod?.default ?? mod;
+}
 /**
  * Reads the rman configuration defined at a single directory level, merging
- * (in increasing precedence): `package.json#rman`, `.rman.yml`, `.rmanrc`.
+ * (in increasing precedence): `package.json#rman`, `.rmanrc.yml`, `.rmanrc`,
+ * then `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js` (whichever exist, in that order).
  */
-export function readDirConfig(dirname) {
+export async function readDirConfig(dirname) {
     const result = {};
     const pkgJsonFile = path.join(dirname, 'package.json');
     if (fs.existsSync(pkgJsonFile)) {
@@ -14,7 +62,7 @@ export function readDirConfig(dirname) {
         if (pkgJson && typeof pkgJson.rman === 'object')
             merge(result, pkgJson.rman, { deep: true });
     }
-    const ymlFile = path.join(dirname, '.rman.yml');
+    const ymlFile = path.join(dirname, '.rmanrc.yml');
     if (fs.existsSync(ymlFile)) {
         const obj = yaml.load(fs.readFileSync(ymlFile, 'utf-8'));
         if (obj && typeof obj === 'object')
@@ -26,6 +74,14 @@ export function readDirConfig(dirname) {
         if (obj && typeof obj === 'object')
             merge(result, obj, { deep: true });
     }
+    for (const jsFileName of JS_CONFIG_FILES) {
+        const jsFile = path.join(dirname, jsFileName);
+        if (fs.existsSync(jsFile)) {
+            const obj = await loadJsConfig(jsFile);
+            if (obj && typeof obj === 'object')
+                merge(result, obj, { deep: true });
+        }
+    }
     return result;
 }
 /**
@@ -35,12 +91,12 @@ export function readDirConfig(dirname) {
  * package (or any intermediate directory) narrow or override the repository's
  * root configuration for itself and everything below it.
  */
-export function resolveConfig(rootDir, targetDir, cache = new Map()) {
+export async function resolveConfig(rootDir, targetDir, cache = new Map()) {
     const result = {};
     for (const dir of dirChain(rootDir, targetDir)) {
         let local = cache.get(dir);
         if (!local) {
-            local = readDirConfig(dir);
+            local = await readDirConfig(dir);
             cache.set(dir, local);
         }
         merge(result, local, { deep: true });

package/core/package.d.ts

@@ -1,9 +1,10 @@
+import type { RmanConfig } from './config.js';
 export declare class Package {
     readonly dirname: string;
     private _json;
     dependencies: string[];
     /** Effective rman config for this package, cascaded from the repository root. */
-    config: any;
+    config: RmanConfig;
     constructor(dirname: string);
     get basename(): string;
     get name(): string;

package/core/repository.d.ts

@@ -41,11 +41,15 @@ export declare class Repository extends Package {
      * package, cascading root -> intermediate directories -> package directory,
      * so a `.rmanrc` placed anywhere along that path overrides the levels above it.
      */
-    protected _resolveConfigs(): void;
+    protected _resolveConfigs(): Promise<void>;
     protected _updateDependencies(): void;
     static create(root?: string, options?: {
         deep?: number;
-    }): Repository;
+    }): 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()`)
+     *  before the dependency graph is built from it. */
+    private static _init;
     protected static _resolvePackages(dirname: string, patterns: string[]): Package[];
 }
 export declare namespace Repository {

package/core/repository.js

@@ -23,8 +23,9 @@ export class Repository extends Package {
         this.rootPackage = new Package(dirname);
         if (!monorepo)
             this.packages = [this.rootPackage];
-        this._resolveConfigs();
-        this._updateDependencies();
+        // Config resolution can load a `.rmanrc.cjs`/`.mjs`/`.js` module (dynamic `import()`, always
+        // async) - a constructor can't `await`, so `create()` finishes this instance off via `_init()`
+        // once construction itself (synchronous) completes.
     }
     /**
      * The package whose own directory contains `cwd` (the deepest match, so a package nested
@@ -90,15 +91,15 @@ export class Repository extends Package {
      * package, cascading root -> intermediate directories -> package directory,
      * so a `.rmanrc` placed anywhere along that path overrides the levels above it.
      */
-    _resolveConfigs() {
+    async _resolveConfigs() {
         const cache = new Map();
-        const rootConfig = resolveConfig(this.dirname, this.dirname, cache);
+        const rootConfig = await resolveConfig(this.dirname, this.dirname, cache);
         this.config = rootConfig;
         this.rootPackage.config = rootConfig;
         for (const pkg of this.packages) {
             if (pkg === this.rootPackage)
                 continue;
-            pkg.config = resolveConfig(this.dirname, pkg.dirname, cache);
+            pkg.config = await resolveConfig(this.dirname, pkg.dirname, cache);
         }
     }
     _updateDependencies() {
@@ -149,7 +150,7 @@ export class Repository extends Package {
             deepFindDependencies(pkg, pkg.dependencies);
         }
     }
-    static create(root, options) {
+    static async create(root, options) {
         const dirname = root || process.cwd();
         let deep = options?.deep ?? 10;
         let pkgDirname = dirname;
@@ -159,7 +160,7 @@ export class Repository extends Package {
                 const pkgJson = JSON.parse(fs.readFileSync(f, 'utf-8'));
                 if (Array.isArray(pkgJson.workspaces)) {
                     const packages = this._resolvePackages(pkgDirname, pkgJson.workspaces);
-                    return new Repository(pkgDirname, true, packages, dirname);
+                    return Repository._init(new Repository(pkgDirname, true, packages, dirname));
                 }
                 /** If we reach to the root of the project */
                 if (fs.existsSync(path.join(pkgDirname, '.git')))
@@ -167,7 +168,15 @@ export class Repository extends Package {
             }
             pkgDirname = path.resolve(pkgDirname, '..');
         }
-        return new Repository(dirname, false, [], dirname);
+        return Repository._init(new Repository(dirname, false, [], dirname));
+    }
+    /** 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()`)
+     *  before the dependency graph is built from it. */
+    static async _init(repo) {
+        await repo._resolveConfigs();
+        repo._updateDependencies();
+        return repo;
     }
     static _resolvePackages(dirname, patterns) {
         const packages = [];

package/index.d.ts

@@ -8,6 +8,8 @@
  * CLI-only concerns (argv parsing, `--help` text, and all console/file presentation) stay in
  * `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
  */
+export type { RmanConfig } from './core/config.js';
+export { defineConfig } from './core/config.js';
 export { Package } from './core/package.js';
 export { Repository } from './core/repository.js';
 export * from './services.js';

package/index.js

@@ -1,13 +1,4 @@
-/**
- * Programmatic API - the same logic the CLI commands run, importable directly without going
- * through yargs/argv. Each domain's logic lives in a `<Name>` namespace under `./services/*.ts`
- * (e.g. `ChangelogService`, `CiService`, `CleanService`, `ListService`, `RunService`,
- * `SystemInfo`, `VersionService`), re-exported here via `./services.js`. Purpose-specific functions, not one
- * generic `run`/`get` per domain (see e.g. `SystemInfo.getSystemInfo`/`getRepositoryInfo`, kept
- * separate since they're genuinely independent capabilities, not just steps of one operation) -
- * CLI-only concerns (argv parsing, `--help` text, and all console/file presentation) stay in
- * `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
- */
+export { defineConfig } from './core/config.js';
 export { Package } from './core/package.js';
 export { Repository } from './core/repository.js';
 export * from './services.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {

package/rmanrc.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/panates/rman/main/schemas/rmanrc.schema.json",
   "title": "rman configuration",
-  "description": "Schema for rman's .rmanrc (JSON) and .rman.yml (YAML) config files, and the \"rman\" key in package.json. See docs/api.md#configuration-rmanrc-rmanyml for the full reference.",
+  "description": "Schema for rman's .rmanrc (JSON) and .rmanrc.yml (YAML) config files, and the \"rman\" key in package.json. See docs/api.md#configuration-rmanrc-rmanrcyml for the full reference.",
   "type": "object",
   "properties": {
     "$schema": {