rman 1.3.0 → 2.0.0-beta.2

package/commands/changelog.command.js

@@ -1,44 +1,88 @@
 import colors from 'ansi-colors';
+import { registerCommand } from '../interfaces/rman-config.interface.js';
 import { ChangeHashService } from '../services/change-hash.service.js';
-import { ChangelogService } from '../services/changelog.service.js';
 import { Logger, resolveRootLogLevel } from '../utils/logger.js';
-import { applyPackageFilterOptions, applyRootOption, readPackageFilterOptions } from '../utils/package-filter.js';
-export function initCli(repository, program) {
-    program.command({
-        command: 'changelog',
-        configKeys: ['changelog', 'publish.skip'],
+import { fromRootOption, packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+const COMMAND = 'changelog';
+const config = {
+    ...packageFilterOptions,
+    ...fromRootOption('Generate'),
+    from: {
+        target: 'cli',
+        describe: 'Generate the changelog since this commit/hash, applied the same way to every package. ' +
+            'Default (also "auto" explicitly): auto-detect per package from its own most recent release ' +
+            'tag - same as "version"/"changed" - falling back to the version its own ecosystem\'s ' +
+            "registry reports (no tag yet), then to its whole history for a package that's never been " +
+            'released at all',
+        type: 'string',
+    },
+    write: {
+        target: 'cli',
+        describe: "Prepend the entry into each package's own changelog file instead of printing it",
+        type: 'boolean',
+    },
+    /** The one option here that is also a config key - hence `'both'`, and hence this command
+     *  contributing `changelog.filePath` to `RmanConfig`. */
+    filePath: {
+        target: 'both',
+        cliName: 'file-path',
+        describe: "With --write, the file to prepend into, relative to each package's own directory " +
+            '(default: "CHANGELOG.md", or .rmanrc "changelog.filePath")',
+        type: 'string',
+    },
+    includeSkipped: {
+        target: 'cli',
+        cliName: 'include-skipped',
+        describe: 'Also generate for a package with .rmanrc "publish.skip" - excluded by default',
+        type: 'boolean',
+    },
+    releaseVersion: {
+        target: 'cli',
+        cliName: 'release-version',
+        describe: 'The version these notes are for - what the entry heading shows. Default: read back from ' +
+            "each package's own latest release tag, which is only right once that release is tagged. " +
+            'Pass it when generating notes ahead of the bump (e.g. from "changed --json" in CI), ' +
+            'otherwise the heading shows the previous release.',
+        type: 'string',
+    },
+    /**
+     * Config-only, from here down - `.rmanrc "changelog.*"` keys with no reason to be a flag. All
+     * three are plain strings or a string list, so this command needs no `Extra` at all: its whole
+     * config block is derived from what is declared here.
+     */
+    ignoreTypes: {
+        target: 'config',
+        describe: 'Conventional-commit types to leave out of the notes entirely (e.g. ["chore", "ci"])',
+        type: 'string',
+        array: true,
+    },
+    template: {
+        target: 'config',
+        describe: "Path to a template file for one package's entry, relative to the repository root. Its own " +
+            "{{package}}/{{version}} placeholders are that file's content, not config expressions.",
+        type: 'string',
+    },
+    tagPattern: {
+        target: 'config',
+        describe: "The release tag naming scheme each package's changelog boundary is detected from - " +
+            '"{name}" is replaced with the package name (e.g. "{name}@*" for independent versioning). ' +
+            'Default "v*", one repo-wide tag resolved through git describe.',
+        type: 'string',
+    },
+};
+const changelogCommand = registerCommand(app => {
+    const repository = app.repository;
+    return {
+        command: COMMAND,
         describe: 'Generates a changelog per package from unreleased commits',
-        builder: cmd => applyRootOption(applyPackageFilterOptions(cmd), 'Generate')
-            .example('$0 changelog', "# Auto-detects each package's own last release tag (or npm version)")
-            .example('$0 changelog --from <hash> --write', '# Since a specific commit, written to file')
-            .option('from', {
-            describe: 'Generate the changelog since this commit/hash, applied the same way to every package. ' +
-                'Default (also "auto" explicitly): auto-detect per package from its own most recent release ' +
-                'tag - same as "version"/"changed" - falling back to the version its own ecosystem\'s ' +
-                "registry reports (no tag yet), then to its whole history for a package that's never been " +
-                'released at all',
-            type: 'string',
-        })
-            .option('write', {
-            describe: "Prepend the entry into each package's own changelog file instead of printing it",
-            type: 'boolean',
-        })
-            .option('file-path', {
-            describe: "With --write, the file to prepend into, relative to each package's own directory " +
-                '(default: "CHANGELOG.md", or .rmanrc "changelog.filePath")',
-            type: 'string',
-        })
-            .option('include-skipped', {
-            describe: 'Also generate for a package with .rmanrc "publish.skip" - excluded by default',
-            type: 'boolean',
-        })
-            .option('release-version', {
-            describe: 'The version these notes are for - what the entry heading shows. Default: read back from ' +
-                "each package's own latest release tag, which is only right once that release is tagged. " +
-                'Pass it when generating notes ahead of the bump (e.g. from "changed --json" in CI), ' +
-                'otherwise the heading shows the previous release.',
-            type: 'string',
-        }),
+        /** Read, not owned: `publish.skip` is `publish`'s key, reused here on purpose - a package that is
+         *  never distributed gets no release notes either. */
+        configKeys: ['publish.skip'],
+        config,
+        examples: [
+            { command: '$0 changelog', description: "# Auto-detects each package's own last release tag (or npm version)" },
+            { command: '$0 changelog --from <hash> --write', description: '# Since a specific commit, written to file' },
+        ],
         handler: async (args) => {
             const from = args.from;
             const write = args.write;
@@ -54,13 +98,12 @@ export function initCli(repository, program) {
                 ...readPackageFilterOptions(args),
                 from,
                 filePath: args.filePath,
-                root: args.root,
+                fromRoot: args.fromRoot,
                 includeSkipped: args.includeSkipped,
                 version: args.releaseVersion,
             };
-            const entries = args.write
-                ? await ChangelogService.generateToFile(repository, options)
-                : await ChangelogService.getEntries(repository, options);
+            const changelog = app.getService('changelog');
+            const entries = write ? await changelog.generateToFile(options) : await changelog.getEntries(options);
             if (!entries.length) {
                 logger.info(colors.gray('No unreleased changes.'));
                 return;
@@ -72,5 +115,6 @@ export function initCli(repository, program) {
                     console.log(entry.content);
             }
         },
-    });
-}
+    };
+});
+export default changelogCommand;

package/commands/config.command.d.ts

@@ -1,3 +1,44 @@
-import type { Argv } from 'yargs';
-import type { Repository } from '../core/repository.js';
-export declare function initCli(repository: Repository, program: Argv): void;
+import { type RmanConfig } from '../interfaces/rman-config.interface.js';
+declare const COMMAND: "config";
+declare const config: {
+    json: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+        default: boolean;
+    };
+    fromRoot: {
+        target: "cli";
+        cliName: string;
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+};
+type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
+/** Prints config; declares none of its own, so it contributes nothing to `RmanConfig`. */
+declare const configCommand: (app: import("../index.js").RmanApplication) => {
+    command: "config";
+    describe: string;
+    config: {
+        json: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+            default: boolean;
+        };
+        fromRoot: {
+            target: "cli";
+            cliName: string;
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+    };
+    examples: {
+        command: string;
+        description: string;
+    }[];
+    handler: (args: Args) => void;
+};
+export default configCommand;

package/commands/config.command.js

@@ -2,23 +2,33 @@ import path from 'node:path';
 import colors from 'ansi-colors';
 import * as yaml from 'js-yaml';
 import { DEFERRED_PATHS } from '../core/config.js';
-import { applyRootOption, readRootOption } from '../utils/package-filter.js';
+import { registerCommand } from '../interfaces/rman-config.interface.js';
+import { fromRootOption, readFromRootOption } from '../utils/package-filter.js';
 import { printableConfig } from '../utils/printable-config.js';
-export function initCli(repository, program) {
-    program.command({
-        command: 'config',
+const COMMAND = 'config';
+const config = {
+    ...fromRootOption('Print the config for'),
+    json: {
+        target: 'cli',
+        describe: 'Print as JSON instead of YAML - nothing else on stdout, so it can be piped.',
+        type: 'boolean',
+        default: false,
+    },
+};
+/** Prints config; declares none of its own, so it contributes nothing to `RmanConfig`. */
+const configCommand = registerCommand(app => {
+    const repository = app.repository;
+    return {
+        command: COMMAND,
         describe: 'Prints the effective .rmanrc config for the package of the current directory',
-        builder: cmd => applyRootOption(cmd, 'Print the config for')
-            .example('$0 config', '# The config of the package you are standing in')
-            .example('$0 config --root', "# The repository root's own config instead")
-            .example('$0 config --json | jq .version', '# Machine-readable')
-            .option('json', {
-            describe: 'Print as JSON instead of YAML - nothing else on stdout, so it can be piped.',
-            type: 'boolean',
-            default: false,
-        }),
-        handler: args => {
-            const target = (!readRootOption(args) && repository.currentPackage) || repository.rootPackage;
+        config,
+        examples: [
+            { command: '$0 config', description: '# The config of the package you are standing in' },
+            { command: '$0 config --from-root', description: "# The repository root's own config instead" },
+            { command: '$0 config --json | jq .version', description: '# Machine-readable' },
+        ],
+        handler: (args) => {
+            const target = (!readFromRootOption(args) && repository.currentPackage) || repository.rootPackage;
             if (args.json) {
                 console.log(JSON.stringify(printableConfig(target.config), undefined, 2));
                 return;
@@ -41,8 +51,9 @@ export function initCli(repository, program) {
              *  as a mistake in something meant to be looked at. */
             console.log(yaml.dump(printableConfig(target.config), { noRefs: true, lineWidth: 100 }).trimEnd());
         },
-    });
-}
+    };
+});
+export default configCommand;
 /**
  * The one honest caveat about this output: **`version.before`/`.exec`/`.after` are printed raw**,
  * expressions and all, because they are the paths in `DEFERRED_PATHS` - `${{ pkg.targetVersion }}`
@@ -56,6 +67,6 @@ function deferredNotes(pkg) {
         return [];
     return [`${raw.join(', ')}: printed raw - evaluated by "version" itself, once it knows the target version`];
 }
-function valueAt(config, dotted) {
-    return dotted.split('.').reduce((node, key) => (node == null ? undefined : node[key]), config);
+function valueAt(node, dotted) {
+    return dotted.split('.').reduce((current, key) => (current == null ? undefined : current[key]), node);
 }

package/commands/diff.command.d.ts

@@ -1,3 +1,37 @@
-import type { Argv } from 'yargs';
-import type { Repository } from '../core/repository.js';
-export declare function initCli(repository: Repository, program: Argv): void;
+import { type RmanConfig } from '../interfaces/rman-config.interface.js';
+declare const COMMAND: "diff [package]";
+declare const config: {
+    fromRoot: {
+        target: "cli";
+        cliName: string;
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+};
+type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
+declare const diffCommand: (app: import("../index.js").RmanApplication) => {
+    command: "diff [package]";
+    describe: string;
+    config: {
+        fromRoot: {
+            target: "cli";
+            cliName: string;
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+    };
+    positionals: {
+        package: {
+            describe: string;
+            type: "string";
+        };
+    };
+    examples: {
+        command: string;
+        description: string;
+    }[];
+    handler: (args: Args) => Promise<void>;
+};
+export default diffCommand;

package/commands/diff.command.js

@@ -1,21 +1,29 @@
 import path from 'node:path';
 import colors from 'ansi-colors';
+import { registerCommand } from '../interfaces/rman-config.interface.js';
 import { ChangeHashService } from '../services/change-hash.service.js';
 import { GitHelper } from '../utils/git.js';
-import { applyRootOption, readRootOption } from '../utils/package-filter.js';
-export function initCli(repository, program) {
-    program.command({
-        command: 'diff [package]',
+import { fromRootOption, readFromRootOption } from '../utils/package-filter.js';
+const COMMAND = 'diff [package]';
+const config = fromRootOption('Diff');
+const diffCommand = registerCommand(app => {
+    const repository = app.repository;
+    return {
+        command: COMMAND,
         describe: "Shows the git diff since a package's (or the whole repository's) last release tag",
-        builder: cmd => applyRootOption(cmd, 'Diff')
-            .example('$0 diff', "# Since the repository's own last tag")
-            .example('$0 diff pkg-a', "# Since pkg-a's own last tag, scoped to its directory")
-            .example('$0 diff --root', '# The whole repository, from inside a package')
-            .positional('package', {
-            describe: 'Package name - diffs just that package, since its own last tag. Omit to diff the whole ' +
-                "repository since its own last tag (or the current directory's package, if standing inside one).",
-            type: 'string',
-        }),
+        config,
+        positionals: {
+            package: {
+                describe: 'Package name - diffs just that package, since its own last tag. Omit to diff the whole ' +
+                    "repository since its own last tag (or the current directory's package, if standing inside one).",
+                type: 'string',
+            },
+        },
+        examples: [
+            { command: '$0 diff', description: "# Since the repository's own last tag" },
+            { command: '$0 diff pkg-a', description: "# Since pkg-a's own last tag, scoped to its directory" },
+            { command: '$0 diff --from-root', description: '# The whole repository, from inside a package' },
+        ],
         handler: async (args) => {
             const git = new GitHelper({ cwd: repository.dirname });
             const packageName = args.package;
@@ -33,7 +41,7 @@ export function initCli(repository, program) {
                 target = pkg;
                 pathspec = path.relative(repository.dirname, pkg.dirname);
             }
-            else if (!readRootOption(args) && repository.currentPackage) {
+            else if (!readFromRootOption(args) && repository.currentPackage) {
                 /** The measured gap this closes: `diff` narrowed to the current package like `run` and
                  *  `changelog` do, but offered no way to say "the whole repository" without naming a
                  *  package - and no package name means the repository, so there was nothing to type. */
@@ -52,5 +60,6 @@ export function initCli(repository, program) {
             }
             console.log(text);
         },
-    });
-}
+    };
+});
+export default diffCommand;

package/commands/exec.command.d.ts

@@ -1,3 +1,193 @@
-import type { Argv } from 'yargs';
-import type { Repository } from '../core/repository.js';
-export declare function initCli(repository: Repository, program: Argv): void;
+import { type RmanConfig } from '../interfaces/rman-config.interface.js';
+declare const COMMAND: "exec [command..]";
+/**
+ * `runOptions` with three texts replaced - the override case the spread order exists for.
+ *
+ * `exec` takes the same scheduling flags as `run`, but not the same *explanations*: `run`'s mention
+ * `.rmanrc run.<script>.bail` and friends, and `exec` runs no script, so there is no such block to
+ * point at. The declarations are shared; only the sentences that would be untrue differ.
+ */
+declare const config: {
+    bail: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    topo: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    progress: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    parallel: {
+        target: "cli";
+        describe: string;
+        coerce: (v: unknown) => boolean | number | undefined;
+    };
+    changed: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    changedSince: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+        conflicts: string;
+    };
+    fromRoot: {
+        target: "cli";
+        cliName: string;
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    allowBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    ignoreBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    scope: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    ignore: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    platform: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    deps: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    dependents: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+};
+type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
+declare const execCommand: (app: import("../index.js").RmanApplication) => {
+    command: "exec [command..]";
+    describe: string;
+    /**
+     * The two parser switches this command cannot work without: `populate--` keeps everything after
+     * `--` out of `exec`'s own options, and `unknown-options-as-args` passes the flags of the command
+     * being run through untouched.
+     */
+    parserConfiguration: {
+        'populate--': true;
+        'unknown-options-as-args': true;
+    };
+    config: {
+        bail: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        topo: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        progress: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        parallel: {
+            target: "cli";
+            describe: string;
+            coerce: (v: unknown) => boolean | number | undefined;
+        };
+        changed: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        changedSince: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+            conflicts: string;
+        };
+        fromRoot: {
+            target: "cli";
+            cliName: string;
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        allowBranch: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+        };
+        ignoreBranch: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+        };
+        scope: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        ignore: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        platform: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        deps: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        dependents: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+    };
+    positionals: {
+        command: {
+            describe: string;
+            type: "string";
+        };
+    };
+    examples: {
+        command: string;
+        description: string;
+    }[];
+    handler: (args: Args) => Promise<void>;
+};
+export default execCommand;