rman 1.3.0 → 2.0.0-beta.3

package/commands/lint.command.d.ts

@@ -0,0 +1,176 @@
+import { type RmanConfig } from '../interfaces/rman-config.interface.js';
+declare const COMMAND: "lint";
+declare const config: {
+    parallel: {
+        target: "cli";
+        describe: string;
+        coerce: (v: unknown) => boolean | number | undefined;
+    };
+    bail: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    topo: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    progress: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    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>;
+/**
+ * `rman lint` - an alias for `rman run lint`, the third of the trio beside `build` and `test`.
+ */
+declare const lintCommand: (app: import("../index.js").RmanApplication) => {
+    command: "lint";
+    describe: string;
+    /** Read, not owned - see the note above. */
+    configKeys: string[];
+    config: {
+        parallel: {
+            target: "cli";
+            describe: string;
+            coerce: (v: unknown) => boolean | number | undefined;
+        };
+        bail: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        topo: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        progress: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        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";
+        };
+    };
+    examples: {
+        command: string;
+        description: string;
+    }[];
+    handler: (args: Args) => Promise<void>;
+};
+export default lintCommand;

package/commands/lint.command.js

@@ -0,0 +1,34 @@
+import { registerCommand } from '../interfaces/rman-config.interface.js';
+import { assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
+import { readRunOptions, runOptions } from '../utils/run-options.js';
+const COMMAND = 'lint';
+const config = runOptions;
+/**
+ * `rman lint` - an alias for `rman run lint`, the third of the trio beside `build` and `test`.
+ */
+/* **Core, not the `node` preset, and the test is what the command *knows*.** It knows a script
+ * name and nothing else: a Cargo repository declaring `lint: 'cargo clippy'` and a Go one
+ * declaring `golangci-lint run` are served by exactly this file. That is the line `clean` is on the
+ * other side of - everything `clean` knows how to delete is a TypeScript fact - and it is why
+ * `build` and `test` are here too.
+ *
+ * **It owns no config key**, for the reason `build` documents: `lint` is `run lint` under another
+ * name, so its settings are `run.lint`, which belongs to `run`. Two commands cannot contribute
+ * under one top-level key - interface merging is not a deep merge - and these three never needed
+ * to. */
+const lintCommand = registerCommand(app => {
+    const repository = app.repository;
+    return {
+        command: COMMAND,
+        describe: 'Alias for "run lint"',
+        /** Read, not owned - see the note above. */
+        configKeys: ['run.lint'],
+        config,
+        examples: [{ command: '$0 lint', description: '# Lints packages' }],
+        handler: async (args) => {
+            await assertAllowedBranch(repository, readBranchGuardOptions(args));
+            await app.getService('run').runScript('lint', { ...readRunOptions(args), commandName: 'lint' });
+        },
+    };
+});
+export default lintCommand;

package/commands/list.command.d.ts

@@ -1,3 +1,163 @@
-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';
+/** `[options...]` is yargs-meaningless - its variadic marker is two dots, and this command declares
+ *  no positional for it. Left as it is rather than fixed in passing: dropping it makes
+ *  `rman list foo` start failing, which is a behaviour change and belongs in its own commit. */
+declare const COMMAND: "list [options...]";
+declare const config: {
+    short: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    parseable: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    toposort: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    graph: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+        /** Declared on the option instead of as separate `.conflicts()` calls - what a flag is and what
+         *  it cannot be combined with end up in one place. */
+        conflicts: string[];
+    };
+    json: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    changed: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    changedSince: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+        conflicts: 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 listCommand: (app: import("../index.js").RmanApplication) => {
+    command: "list [options...]";
+    aliases: string[];
+    describe: string;
+    config: {
+        short: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        parseable: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        toposort: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        graph: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+            /** Declared on the option instead of as separate `.conflicts()` calls - what a flag is and what
+             *  it cannot be combined with end up in one place. */
+            conflicts: string[];
+        };
+        json: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        changed: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        changedSince: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+            conflicts: 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";
+        };
+    };
+    examples: {
+        command: string;
+        description: string;
+    }[];
+    handler: (args: Args) => Promise<void>;
+};
+export default listCommand;

package/commands/list.command.js

@@ -1,7 +1,91 @@
 import colors from 'ansi-colors';
 import EasyTable from 'easy-table';
-import { ListService } from '../services/list.service.js';
-import { applyPackageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+import { registerCommand } from '../interfaces/rman-config.interface.js';
+import { packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+/** `[options...]` is yargs-meaningless - its variadic marker is two dots, and this command declares
+ *  no positional for it. Left as it is rather than fixed in passing: dropping it makes
+ *  `rman list foo` start failing, which is a behaviour change and belongs in its own commit. */
+const COMMAND = 'list [options...]';
+const config = {
+    ...packageFilterOptions,
+    short: { target: 'cli', alias: 's', describe: 'Do not show extended information', type: 'boolean' },
+    parseable: { target: 'cli', alias: 'p', describe: 'Show parseable output', type: 'boolean' },
+    toposort: {
+        target: 'cli',
+        alias: 't',
+        describe: 'Sort packages in topological order (dependencies before dependents) instead of lexical by directory',
+        type: 'boolean',
+    },
+    graph: {
+        target: 'cli',
+        alias: 'g',
+        describe: 'Show dependency graph as a JSON-formatted adjacency list',
+        type: 'boolean',
+        /** Declared on the option instead of as separate `.conflicts()` calls - what a flag is and what
+         *  it cannot be combined with end up in one place. */
+        conflicts: ['parseable', 'json'],
+    },
+    json: { target: 'cli', alias: 'j', describe: 'Show output in JSON format', type: 'boolean' },
+    changed: {
+        target: 'cli',
+        alias: 'c',
+        describe: 'Only list packages you have touched but not pushed - uncommitted, or committed and not yet on the upstream branch. Not a release question; see "version --json" for that',
+        type: 'boolean',
+    },
+    changedSince: {
+        target: 'cli',
+        cliName: 'changed-since',
+        describe: 'Only list packages that have changed since the given git commit/hash',
+        type: 'string',
+        conflicts: 'changed',
+    },
+};
+const listCommand = registerCommand(app => {
+    return {
+        command: COMMAND,
+        aliases: ['ls'],
+        describe: 'Lists packages in repository',
+        config,
+        examples: [
+            { command: '$0 list', description: '# List all packages' },
+            { command: '$0 list --json', description: '# List all packages in JSON format' },
+        ],
+        handler: async (args) => {
+            /**
+             * **Only the table asks for the root**, and that is why the option exists rather than the
+             * service always including it. The table draws a tree, which needs the row its members are
+             * nested under; the other four forms are the inventory a script parses, and the inventory is
+             * the workspace members - which is also what the count line reports.
+             */
+            const table = !args.graph && !args.json && !args.parseable && !args.short;
+            const items = await app.getService('list').getPackages({
+                ...readPackageFilterOptions(args),
+                toposort: args.toposort,
+                changed: args.changed,
+                changedSince: args.changedSince,
+                includeRoot: table,
+            });
+            if (args.graph)
+                printGraph(items);
+            else if (args.json)
+                console.log(JSON.stringify(items, undefined, 2));
+            else if (args.parseable)
+                printParseable(items);
+            else if (args.short)
+                for (const it of items)
+                    console.log(it.name);
+            /**
+             * **Whether a root row was added is asked here, not inferred from the rows.** `isRoot` is
+             * true of the one package in a *single-package* repository too - it genuinely is the root -
+             * so counting rows that are not the root reported `0 Package(s) found` there (measured). The
+             * condition is the same one the service applies, and it is one line.
+             */
+            else
+                printTable(items, table && app.repository.monorepo);
+        },
+    };
+});
+export default listCommand;
 function statusLabel(status) {
     switch (status) {
         case 'dirty':
@@ -14,11 +98,31 @@ function statusLabel(status) {
             return '';
     }
 }
-function printTable(items) {
+/**
+ * **The tree, as a table**: the root first, then each package indented by how far below it sits.
+ *
+ * Indentation rather than box-drawing characters, which was the cheaper answer to the same
+ * question and stays legible when the output is pasted somewhere without a monospace font, copied
+ * into a `--scope` argument, or read by eye for the one name someone is looking for. The nesting is
+ * `Item.depth`, a fact about the package - so `--toposort` reorders the rows and leaves each one's
+ * indentation telling the truth about where it lives.
+ *
+ * **`Platform` is a column because a package's technology is now a per-package answer.** A polyglot
+ * repository is the whole point of the walk finding nested packages of another platform, and until
+ * this column existed `rman list` was the one place that showed every package and could not say
+ * which technology each belonged to. Blank rather than a word when none claimed it: `Package.provider`
+ * is an empty string there, and inventing `unknown` would read as a technology's name.
+ *
+ * **The count is the members**, root excluded, which is what `repository.packages` means and what
+ * every other form of this command reports.
+ */
+function printTable(items, withRoot) {
     const table = new EasyTable();
     for (const it of items) {
-        table.cell('Package', colors.yellowBright(it.name));
+        const indent = '  '.repeat(it.depth);
+        table.cell('Package', indent + (it.isRoot ? colors.whiteBright(it.selector) : colors.yellowBright(it.selector)));
         table.cell('Version', colors.yellow(it.version));
+        table.cell('Platform', it.platform ? colors.cyan(it.platform) : '');
         table.cell('Private', it.private ? colors.magentaBright('yes') : '');
         table.cell('Changed', statusLabel(it.status));
         table.cell('Path', it.location);
@@ -26,7 +130,7 @@ function printTable(items) {
     }
     console.log(table.toString().trim());
     console.log('');
-    console.log(colors.gray(`${items.length} Package(s) found`));
+    console.log(colors.gray(`${items.length - (withRoot ? 1 : 0)} Package(s) found`));
 }
 function printParseable(items) {
     for (const it of items) {
@@ -45,69 +149,3 @@ function printGraph(items) {
         graph[it.name] = it.dependencies;
     console.log(JSON.stringify(graph, undefined, 2));
 }
-export function initCli(repository, program) {
-    program.command({
-        command: 'list [options...]',
-        aliases: ['ls'],
-        describe: 'Lists packages in repository',
-        builder: cmd => applyPackageFilterOptions(cmd)
-            .example('$0 list', '# List all packages')
-            .example('$0 list --json', '# List all packages in JSON format')
-            .conflicts('graph', ['parseable', 'json'])
-            .conflicts('short', ['parseable', 'json'])
-            .conflicts('changed', 'changed-since')
-            .option('short', {
-            alias: 's',
-            describe: 'Do not show extended information',
-            type: 'boolean',
-        })
-            .option('parseable', {
-            alias: 'p',
-            describe: 'Show parseable output',
-            type: 'boolean',
-        })
-            .option('toposort', {
-            alias: 't',
-            describe: 'Sort packages in topological order (dependencies before dependents) instead of lexical by directory',
-            type: 'boolean',
-        })
-            .option('graph', {
-            alias: 'g',
-            describe: 'Show dependency graph as a JSON-formatted adjacency list',
-            type: 'boolean',
-        })
-            .option('json', {
-            alias: 'j',
-            describe: 'Show output in JSON format',
-            type: 'boolean',
-        })
-            .option('changed', {
-            alias: 'c',
-            describe: 'Only list packages that have changed since the last publish (dirty or committed but not yet published)',
-            type: 'boolean',
-        })
-            .option('changed-since', {
-            describe: 'Only list packages that have changed since the given git commit/hash',
-            type: 'string',
-        }),
-        handler: async (args) => {
-            const items = await ListService.getPackages(repository, {
-                ...readPackageFilterOptions(args),
-                toposort: args.toposort,
-                changed: args.changed,
-                changedSince: args.changedSince,
-            });
-            if (args.graph)
-                printGraph(items);
-            else if (args.json)
-                console.log(JSON.stringify(items, undefined, 2));
-            else if (args.parseable)
-                printParseable(items);
-            else if (args.short)
-                for (const it of items)
-                    console.log(it.name);
-            else
-                printTable(items);
-        },
-    });
-}