rman 1.3.0 → 2.0.0-beta.3

package/commands/config.command.js

@@ -1,26 +1,39 @@
 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 { printableConfig } from '../utils/printable-config.js';
-export function initCli(repository, program) {
-    program.command({
-        command: 'config',
+import { DEFERRED_PATHS } from '../core/config/config-paths.js';
+import { ConfigReader } from '../core/config/config-reader.js';
+import { registerCommand } from '../interfaces/rman-config.interface.js';
+import { colorYaml } from '../utils/color-yaml.js';
+import { fromRootOption, readFromRootOption } from '../utils/package-filter.js';
+import { printableConfig, withoutContributions } from '../utils/printable-config.js';
+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;
+            const settings = withoutContributions(target.config);
             if (args.json) {
-                console.log(JSON.stringify(printableConfig(target.config), undefined, 2));
+                console.log(JSON.stringify(printableConfig(settings), undefined, 2));
                 return;
             }
             /**
@@ -31,18 +44,34 @@ export function initCli(repository, program) {
              * itself off for a pipe here). The repository's own convention for this is
              * `process.stdout.isTTY`, as `run`/`exec`'s progress panel uses.
              */
-            const comment = (text) => (process.stdout.isTTY ? colors.gray(text) : text);
+            const tty = !!process.stdout.isTTY;
+            const comment = (text) => (tty ? colors.gray(text) : text);
             const relativeDir = path.relative(repository.dirname, target.dirname) || '.';
+            /**
+             * **The file you would open to change this**, headed first because that is the next thing a
+             * reader wants. Omitted for a directory that declares none - naming a file that is not there
+             * would send them to create one when the answer is a level above.
+             *
+             * It is the package's **own** file and the printed config is more than it: the directory
+             * chain above, every `extends` base and each `"[selector]"` block are all in there. The
+             * per-key answer is `ORIGINS`, which is what a failing expression's message already names -
+             * this line is the starting point, not the whole provenance.
+             */
+            const source = new ConfigReader().findConfigSource(target.dirname);
+            if (source)
+                console.log(comment(`# ${path.basename(source)}`));
             console.log(comment(`# ${target.name} (${relativeDir})`));
             for (const note of deferredNotes(target))
                 console.log(comment(`# ${note}`));
             /** `noRefs`: a value appearing twice in the config is the *same object* after merging, and
              *  js-yaml would otherwise emit the second as an `*anchor` reference - valid YAML that reads
              *  as a mistake in something meant to be looked at. */
-            console.log(yaml.dump(printableConfig(target.config), { noRefs: true, lineWidth: 100 }).trimEnd());
+            const body = yaml.dump(printableConfig(settings), { noRefs: true, lineWidth: 100 }).trimEnd();
+            console.log(tty ? colorYaml(body) : body);
         },
-    });
-}
+    };
+});
+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 +85,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;

package/commands/exec.command.js

@@ -1,67 +1,68 @@
-import { ExecService } from '../services/exec.service.js';
-import { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
-import { applyPackageFilterOptions, applyRootOption, readPackageFilterOptions } from '../utils/package-filter.js';
-export function initCli(repository, program) {
-    program.command({
-        command: 'exec [command..]',
+import { registerCommand } from '../interfaces/rman-config.interface.js';
+import { assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
+import { readPackageFilterOptions } from '../utils/package-filter.js';
+import { runOptions } from '../utils/run-options.js';
+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.
+ */
+const config = {
+    ...runOptions,
+    bail: { target: 'cli', describe: 'Stop on first failure (default: true)', type: 'boolean' },
+    topo: {
+        target: 'cli',
+        describe: 'Respect package dependency order: a package waits for its dependencies and is skipped if one ' +
+            'fails. Set false to run in every matching package independently, alphabetically. Default: true.',
+        type: 'boolean',
+    },
+    progress: {
+        target: 'cli',
+        describe: 'Show a live progress panel (default: true; auto-disabled when not a TTY)',
+        type: 'boolean',
+    },
+};
+const execCommand = registerCommand(app => {
+    const repository = app.repository;
+    return {
+        command: COMMAND,
         describe: 'Runs an arbitrary shell command in each package - unlike run, not tied to any npm script',
-        builder: cmd => applyRootOption(applyBranchGuardOptions(applyPackageFilterOptions(cmd)), 'Run')
-            .parserConfiguration({ 'populate--': true, 'unknown-options-as-args': true })
-            .example('$0 exec rm -rf dist', '# Not an npm script - runs directly in every package')
-            .example('$0 exec --scope pkg-a -- ls -la', '# "--" needed only if the command shares a flag name with exec\'s own')
-            .positional('command', {
-            describe: "The command (and its own arguments) to run in each package - its own flags don't need to be " +
-                'escaped unless one happens to share a name with one of these options below, in which case put ' +
-                '"--" first',
-            type: 'string',
-        })
-            .option('parallel', {
-            describe: 'Max packages at once: omit/true for CPU count, a number for that many, false to run serially. ' +
-                'Packages always run in dependency order unless --no-topo.',
-            coerce: (v) => {
-                if (v === undefined)
-                    return undefined;
-                if (v === 'false' || v === false)
-                    return false;
-                if (v === 'true' || v === true)
-                    return true;
-                const n = Number(v);
-                return Number.isFinite(n) ? n : true;
+        /**
+         * 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,
+        positionals: {
+            command: {
+                describe: "The command (and its own arguments) to run in each package - its own flags don't need to be " +
+                    'escaped unless one happens to share a name with one of these options below, in which case put ' +
+                    '"--" first',
+                type: 'string',
             },
-        })
-            .option('bail', {
-            describe: 'Stop on first failure (default: true)',
-            type: 'boolean',
-        })
-            .option('topo', {
-            describe: 'Respect package dependency order: a package waits for its dependencies and is skipped if one ' +
-                'fails. Set false to run in every matching package independently, alphabetically. Default: true.',
-            type: 'boolean',
-        })
-            .option('progress', {
-            describe: 'Show a live progress panel (default: true; auto-disabled when not a TTY)',
-            type: 'boolean',
-        })
-            .option('changed', {
-            alias: 'c',
-            describe: 'Only run in packages that have changed since the last publish',
-            type: 'boolean',
-        })
-            .option('changed-since', {
-            describe: 'Only run in packages that have changed since the given git commit/hash',
-            type: 'string',
-        })
-            .conflicts('changed', 'changed-since'),
+        },
+        examples: [
+            { command: '$0 exec rm -rf dist', description: '# Not an npm script - runs directly in every package' },
+            {
+                command: '$0 exec --scope pkg-a -- ls -la',
+                description: '# "--" needed only if the command shares a flag name with exec\'s own',
+            },
+        ],
         handler: async (args) => {
             await assertAllowedBranch(repository, readBranchGuardOptions(args));
             const afterDashDash = args['--'];
-            const tokens = afterDashDash?.length ? afterDashDash : args.command;
+            /** `command` is variadic (`[command..]`), so it arrives as a list - `ArgsOf` reads that off the
+             *  command string rather than being told. */
+            const tokens = afterDashDash?.length ? afterDashDash.map(String) : args.command;
             if (!tokens?.length) {
                 const err = new Error('No command given - e.g. "rman exec ls" or "rman exec -- eslint --bail"');
                 throw err;
             }
-            const command = tokens.join(' ');
-            await ExecService.exec(repository, command, {
+            await app.getService('exec').exec(tokens.join(' '), {
                 ...readPackageFilterOptions(args),
                 parallel: args.parallel,
                 topo: args.topo,
@@ -70,8 +71,9 @@ export function initCli(repository, program) {
                 changed: args.changed,
                 changedSince: args.changedSince,
                 logLevel: args.logLevel,
-                root: args.root,
+                fromRoot: args.fromRoot,
             });
         },
-    });
-}
+    };
+});
+export default execCommand;