rman 2.0.0-beta.2 → 2.0.0-beta.4

package/{targets → builtins/publish-targets/docker}/docker.target.d.ts

@@ -1,6 +1,5 @@
-import type { ConfigValue } from '../core/config.js';
-import type { PublishTarget } from '../core/publish-target.js';
-import type { ScopedVars } from '../interfaces/rman-config.interface.js';
+import type { PublishTarget } from '../../../core/interfaces/publish-target.js';
+import type { ConfigValue, ScopedVars } from '../../../interfaces/rman-config.interface.js';
 /**
  * **`publish.docker.*`** - this target's own config block, declared here rather than centrally.
  *
@@ -23,8 +22,10 @@ export interface DockerPublishOptionsKeys {
     image: ConfigValue<string>;
     /** Relative to the package's own directory. Default `"Dockerfile"`. */
     dockerfile?: ConfigValue<string>;
-    /** Default `["linux/amd64"]`. */
-    platforms?: ConfigValue<string[]>;
+    /**
+     * The architectures to build for - `docker buildx build --platform`. Default `["linux/amd64"]`.
+     */
+    architectures?: ConfigValue<string[]>;
     /** Build `cwd` override, relative to the repository root - only needed when the Dockerfile's
      *  own `COPY`/`ADD` paths expect something other than the package's own directory (rare). */
     cwd?: ConfigValue<string>;

package/{targets → builtins/publish-targets/docker}/docker.target.js

@@ -1,4 +1,4 @@
-import { DOCKER_TARGET } from '../services/docker-publish.service.js';
+import { DOCKER_TARGET } from './docker-publish.service.js';
 /**
  * **Docker, as a publish target** - the core's own, and the reason `PublishTarget` is in the core
  * rather than in a plugin.

package/builtins/publish-targets/docker/index.d.ts

@@ -0,0 +1,2 @@
+export * from './docker.target.js';
+export * from './docker-publish.service.js';

package/builtins/publish-targets/docker/index.js

@@ -0,0 +1,2 @@
+export * from './docker.target.js';
+export * from './docker-publish.service.js';

package/builtins/publish-targets/npm/index.d.ts

@@ -0,0 +1,2 @@
+export * from './npm-publish-target.js';
+export * from './npm-view.js';

package/builtins/publish-targets/npm/index.js

@@ -0,0 +1,2 @@
+export * from './npm-publish-target.js';
+export * from './npm-view.js';

package/{plugins/node → builtins/publish-targets/npm}/npm-publish-target.d.ts

@@ -1,6 +1,5 @@
-import type { Package } from '../../core/package.js';
-import type { PublishTarget } from '../../core/publish-target.js';
-import { PublishService } from './services/publish.service.js';
+import type { PublishTarget } from '../../../core/interfaces/publish-target.js';
+import { PublishService } from '../../platforms/node/services/publish.service.js';
 /** The name this target answers to in `publish.target` and `--target`. */
 export declare const NPM_TARGET = "npm";
 /**
@@ -26,7 +25,8 @@ export declare const NPM_TARGET = "npm";
 export declare class NpmPublishTarget implements PublishTarget {
     name: string;
     describe: string;
-    claims(pkg: Package): boolean;
+    /** npm's alone: a package rman read through the `node` platform. */
+    platforms: string[];
     options: {
         packageManager: {
             target: "cli";

package/{plugins/node → builtins/publish-targets/npm}/npm-publish-target.js

@@ -1,5 +1,5 @@
-import { CiService } from './services/ci.service.js';
-import { PublishService } from './services/publish.service.js';
+import { CiService } from '../../platforms/node/services/ci.service.js';
+import { PublishService } from '../../platforms/node/services/publish.service.js';
 /** The name this target answers to in `publish.target` and `--target`. */
 export const NPM_TARGET = 'npm';
 /**
@@ -25,9 +25,8 @@ export const NPM_TARGET = 'npm';
 export class NpmPublishTarget {
     name = NPM_TARGET;
     describe = 'Publish to an npm registry (npm/yarn/pnpm/bun publish)';
-    claims(pkg) {
-        return pkg.provider === 'node';
-    }
+    /** npm's alone: a package rman read through the `node` platform. */
+    platforms = ['node'];
     options = {
         packageManager: {
             target: 'cli',

package/cli.d.ts

@@ -7,4 +7,7 @@ export declare function runCli(options?: {
     argv?: string[];
     cwd?: string;
     app?: RmanApplication;
+    /** Forwarded to {@link Repository.create} - see its `presets`. `[]` is a caller with an
+     *  ecosystem of its own, which is what the core's own fixture is. */
+    presets?: readonly string[];
 }): Promise<void>;

package/cli.js

@@ -11,14 +11,15 @@ import yargs, {} from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { version } from './constants.js';
 import { RmanApplication } from './core/application.js';
+import { Repository } from './core/classes/repository.js';
 import { commandName, toYargsCommand } from './core/command-builder.js';
-import { assertNoBuiltinShadowing, defaultCommandGlobs, loadCustomCommands, } from './core/custom-command.js';
+import { assertNoBuiltinShadowing, defaultCommandGlobs, loadCustomCommands, } from './core/interfaces/custom-command.js';
 import { checkCustomCommand } from './core/plugin-loader.js';
-import { Repository } from './core/repository.js';
 import { commandRegistry } from './interfaces/rman-config.interface.js';
+import { colorYaml } from './utils/color-yaml.js';
 import { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
 import { filterPackages, readFromRootOption, readPackageFilterOptions } from './utils/package-filter.js';
-import { printableConfig } from './utils/printable-config.js';
+import { printableConfig, withoutContributions } from './utils/printable-config.js';
 import { runBin } from './utils/run-bin.js';
 export async function runCli(options) {
     const _argv = options?.argv || hideBin(process.argv);
@@ -38,7 +39,7 @@ export async function runCli(options) {
         /** One application per run, made here so `--log-level` reaches its logger, and handed to
          *  `Repository.create` rather than found through a global. */
         const app = options?.app ?? new RmanApplication();
-        const repository = await Repository.create(options?.cwd, { app });
+        const repository = await Repository.create(options?.cwd, { app, presets: options?.presets });
         const program = yargs(_argv)
             .scriptName('rman')
             .version(version)
@@ -338,9 +339,17 @@ function printCommandConfig(repository, spec, args) {
     if (!shown.some(p => p === repository.rootPackage))
         shown.push(repository.rootPackage);
     const config = {};
-    for (const pkg of shown)
-        config[pkg.name] = keys?.length ? pick(pkg.config, keys) : pkg.config;
-    console.log(indent(yaml.dump(printableConfig(config), { noRefs: true, lineWidth: 100 }).trimEnd()));
+    /** `withoutContributions` for the same reason `rman config` uses it: `plugins`, `platforms`,
+     *  `commands` and `publishTargets` are code, and a command's config section is about settings.
+     *  Only the "in full" branch needs it - `pick` already narrows to the keys the command reads. */
+    for (const pkg of shown) {
+        config[pkg.name] = keys?.length ? pick(pkg.config, keys) : withoutContributions(pkg.config);
+    }
+    /** Coloured after indenting, not before: `indent` prefixes each line, and an escape sequence
+     *  already sitting at the start of one is what it would be measuring. Gated on a terminal for the
+     *  reason `rman config` documents - the section is YAML and has to survive being redirected. */
+    const body = indent(yaml.dump(printableConfig(config), { noRefs: true, lineWidth: 100 }).trimEnd());
+    console.log(process.stdout.isTTY ? colorYaml(body) : body);
     if (!targets.includes(repository.rootPackage)) {
         console.log(comment(`# "${repository.rootPackage.name}" is the root - listed because repo-wide keys are read there.`));
     }

package/commands/changelog.command.d.ts

@@ -1,4 +1,4 @@
-import { type RmanConfig } from '../interfaces/rman-config.interface.js';
+import type { ConfigValue, RmanConfig } from '../interfaces/rman-config.interface.js';
 declare const COMMAND: "changelog";
 declare const config: {
     from: {
@@ -52,6 +52,41 @@ declare const config: {
         describe: string;
         type: "string";
     };
+    /**
+     * **Where a package's history starts being worth documenting**, as one key taking whichever form
+     * the answer naturally has - a version or tag, a date, or a commit.
+     *
+     * `'both'`, because it is a lasting fact about the package ("we do not publish what happened
+     * before 2.0"), not a decision per run. That is also what separates it from `--from`, which those
+     * three forms would otherwise duplicate: `--from` is this run's boundary and applies identically
+     * to every package, while this lives in `.rmanrc`, is cascaded per package, and still holds on
+     * the run after next.
+     */
+    /**
+     * **Default `true`, so the flag that does something is `--no-unreleased`** - and that is the one
+     * place this deliberately differs from `auto-changelog`, which defaults it off.
+     *
+     * There, a changelog is generated from a finished history and the unreleased section is the
+     * unusual thing to want. Here it is the *ordinary* one: `rman changelog` exists to answer what is
+     * not released yet, down to the message it prints when there is nothing ("No unreleased
+     * changes."), and `version --changelog` writes the entry for the release it is about to cut -
+     * which is that segment. Defaulting it off would make the common case need a flag, and make
+     * `version --changelog` silently write nothing.
+     *
+     * What it *is* for is the other direction, which only became possible once `--write` started
+     * backfilling: a changelog of released history, with the work in progress left out.
+     */
+    unreleased: {
+        target: "both";
+        describe: string;
+        type: "boolean";
+    };
+    startingAt: {
+        target: "both";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
     fromRoot: {
         target: "cli";
         cliName: string;
@@ -85,6 +120,40 @@ declare const config: {
         type: "boolean";
     };
 };
+/**
+ * **What a `CommandOption` cannot say**, which is the only thing `Extra` is for: `titles` is a map
+ * from commit type to section heading, and an option says `type: 'string'`.
+ */
+export interface ChangelogExtraKeys {
+    /**
+     * The heading each Conventional Commits type is listed under - `{ feat: 'New Features', dev:
+     * 'Development Changes' }`. Per-package cascaded.
+     *
+     * **Merged over the defaults per key, not replacing them**, the way `vars` merges: naming `dev`
+     * adds a section without silently costing you `feat` and `fix`, and renaming `feat` leaves it
+     * where it was in the order. The cost, stated rather than hidden - you cannot *remove* a default
+     * section by leaving it out; `changelog.ignoreTypes` is the key that drops a type entirely.
+     *
+     * Two types sharing a heading share one section. `'*'` is the heading for every type that is not
+     * named here, and is always rendered last; a subject that is not Conventional Commits at all has
+     * no type to key off and lands there too.
+     *
+     * Sections come out in the order the types were declared, defaults first - so a repository
+     * chooses both the wording and the running order.
+     */
+    titles?: ConfigValue<Record<string, string>>;
+    /**
+     * The order the sections come out in, as a list of commit **types** - `['fix', 'feat', 'docs']`.
+     * Per-package cascaded.
+     *
+     * Separate from `titles` because they are separate decisions, and letting one key do both was
+     * the wrong shape: `titles` patches a heading's *wording*, so a repository renaming `feat` would
+     * otherwise also be silently re-deciding where it sits. A type left out keeps its place after the
+     * listed ones; `'*'` is always last whatever this says, since a catch-all in the middle swallows
+     * the sections after it.
+     */
+    sortTitles?: ConfigValue<string[]>;
+}
 type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
 declare const changelogCommand: (app: import("../index.js").RmanApplication) => {
     command: "changelog";
@@ -144,6 +213,41 @@ declare const changelogCommand: (app: import("../index.js").RmanApplication) =>
             describe: string;
             type: "string";
         };
+        /**
+         * **Where a package's history starts being worth documenting**, as one key taking whichever form
+         * the answer naturally has - a version or tag, a date, or a commit.
+         *
+         * `'both'`, because it is a lasting fact about the package ("we do not publish what happened
+         * before 2.0"), not a decision per run. That is also what separates it from `--from`, which those
+         * three forms would otherwise duplicate: `--from` is this run's boundary and applies identically
+         * to every package, while this lives in `.rmanrc`, is cascaded per package, and still holds on
+         * the run after next.
+         */
+        /**
+         * **Default `true`, so the flag that does something is `--no-unreleased`** - and that is the one
+         * place this deliberately differs from `auto-changelog`, which defaults it off.
+         *
+         * There, a changelog is generated from a finished history and the unreleased section is the
+         * unusual thing to want. Here it is the *ordinary* one: `rman changelog` exists to answer what is
+         * not released yet, down to the message it prints when there is nothing ("No unreleased
+         * changes."), and `version --changelog` writes the entry for the release it is about to cut -
+         * which is that segment. Defaulting it off would make the common case need a flag, and make
+         * `version --changelog` silently write nothing.
+         *
+         * What it *is* for is the other direction, which only became possible once `--write` started
+         * backfilling: a changelog of released history, with the work in progress left out.
+         */
+        unreleased: {
+            target: "both";
+            describe: string;
+            type: "boolean";
+        };
+        startingAt: {
+            target: "both";
+            cliName: string;
+            describe: string;
+            type: "string";
+        };
         fromRoot: {
             target: "cli";
             cliName: string;
@@ -186,7 +290,7 @@ declare const changelogCommand: (app: import("../index.js").RmanApplication) =>
 export default changelogCommand;
 declare module '../interfaces/rman-config.interface.js' {
     namespace RmanConfig {
-        interface CommandConfigs extends RmanConfig.CommandContribution<ReturnType<typeof changelogCommand>> {
+        interface CommandConfigs extends RmanConfig.CommandContribution<ReturnType<typeof changelogCommand>, ChangelogExtraKeys> {
         }
     }
 }

package/commands/changelog.command.js

@@ -69,6 +69,44 @@ const config = {
             'Default "v*", one repo-wide tag resolved through git describe.',
         type: 'string',
     },
+    /**
+     * **Where a package's history starts being worth documenting**, as one key taking whichever form
+     * the answer naturally has - a version or tag, a date, or a commit.
+     *
+     * `'both'`, because it is a lasting fact about the package ("we do not publish what happened
+     * before 2.0"), not a decision per run. That is also what separates it from `--from`, which those
+     * three forms would otherwise duplicate: `--from` is this run's boundary and applies identically
+     * to every package, while this lives in `.rmanrc`, is cascaded per package, and still holds on
+     * the run after next.
+     */
+    /**
+     * **Default `true`, so the flag that does something is `--no-unreleased`** - and that is the one
+     * place this deliberately differs from `auto-changelog`, which defaults it off.
+     *
+     * There, a changelog is generated from a finished history and the unreleased section is the
+     * unusual thing to want. Here it is the *ordinary* one: `rman changelog` exists to answer what is
+     * not released yet, down to the message it prints when there is nothing ("No unreleased
+     * changes."), and `version --changelog` writes the entry for the release it is about to cut -
+     * which is that segment. Defaulting it off would make the common case need a flag, and make
+     * `version --changelog` silently write nothing.
+     *
+     * What it *is* for is the other direction, which only became possible once `--write` started
+     * backfilling: a changelog of released history, with the work in progress left out.
+     */
+    unreleased: {
+        target: 'both',
+        describe: 'Include the entry for commits that are not released yet (default true) - pass ' +
+            '--no-unreleased for a changelog of released history only',
+        type: 'boolean',
+    },
+    startingAt: {
+        target: 'both',
+        cliName: 'starting-at',
+        describe: "Where this package's changelog begins: a version or release tag (inclusive), a YYYY-MM-DD " +
+            'date, or a commit. Releases older than it are left out - for a package whose early ' +
+            'development does not belong in its changelog',
+        type: 'string',
+    },
 };
 const changelogCommand = registerCommand(app => {
     const repository = app.repository;
@@ -101,6 +139,8 @@ const changelogCommand = registerCommand(app => {
                 fromRoot: args.fromRoot,
                 includeSkipped: args.includeSkipped,
                 version: args.releaseVersion,
+                startingAt: args.startingAt,
+                unreleased: args.unreleased,
             };
             const changelog = app.getService('changelog');
             const entries = write ? await changelog.generateToFile(options) : await changelog.getEntries(options);

package/commands/config.command.js

@@ -1,10 +1,12 @@
 import path from 'node:path';
 import colors from 'ansi-colors';
 import * as yaml from 'js-yaml';
-import { DEFERRED_PATHS } from '../core/config.js';
+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 } from '../utils/printable-config.js';
+import { printableConfig, withoutContributions } from '../utils/printable-config.js';
 const COMMAND = 'config';
 const config = {
     ...fromRootOption('Print the config for'),
@@ -29,8 +31,9 @@ const configCommand = registerCommand(app => {
         ],
         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;
             }
             /**
@@ -41,15 +44,30 @@ const configCommand = registerCommand(app => {
              * 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);
         },
     };
 });

package/commands/list.command.js

@@ -29,7 +29,7 @@ const config = {
     changed: {
         target: 'cli',
         alias: 'c',
-        describe: 'Only list packages that have changed since the last publish (dirty or committed but not yet published)',
+        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: {

package/commands/publish.command.d.ts

@@ -1,6 +1,6 @@
+import type { DockerPublishOptions } from '../builtins/publish-targets/docker/docker.target.js';
 import type { RmanApplication } from '../core/application.js';
 import { type RmanConfig } from '../interfaces/rman-config.interface.js';
-import type { DockerPublishOptions } from '../targets/docker.target.js';
 /** Hoisted for `ArgsOf` - see `version.command.ts` and `RmanConfig.ArgsOf` for why. */
 declare const COMMAND: "publish";
 /**

package/commands/publish.command.js

@@ -1,6 +1,6 @@
 import readline from 'node:readline/promises';
 import colors from 'ansi-colors';
-import { unknownTargets } from '../core/publish-target.js';
+import { unknownTargets } from '../core/interfaces/publish-target.js';
 import { registerCommand } from '../interfaces/rman-config.interface.js';
 import { assertAllowedBranch, branchGuardOptions, readBranchGuardOptions } from '../utils/branch-guard.js';
 import { packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';

package/commands/run.command.js

@@ -20,7 +20,7 @@ const runCommand = registerCommand(app => {
         },
         examples: [
             { command: '$0 run build' },
-            { command: '$0 run build --changed', description: '# Only in packages changed since the last publish' },
+            { command: '$0 run build --changed', description: '# Only in packages you have touched but not pushed' },
         ],
         handler: async (args) => {
             await assertAllowedBranch(repository, readBranchGuardOptions(args));

package/commands/version.command.d.ts

@@ -1,6 +1,5 @@
-import type { ConfigValue } from '../core/config.js';
-import type { RunStepValue } from '../core/run-step.js';
-import { type RmanConfig } from '../interfaces/rman-config.interface.js';
+import type { RunStepValue } from '../core/interfaces/run-step.js';
+import type { ConfigValue, RmanConfig } from '../interfaces/rman-config.interface.js';
 /**
  * Hoisted out of the metadata literal so the handler can be annotated against them - see
  * `RmanConfig.ArgsOf` for why an inferred `argv` and the metadata's own typo checking cannot both
@@ -30,6 +29,13 @@ declare const config: {
         type: "boolean";
         conflicts: string;
     };
+    json: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+        conflicts: string[];
+    };
     ignoreDirty: {
         target: "cli";
         cliName: string;
@@ -203,6 +209,13 @@ declare const versionCommand: (app: import("../index.js").RmanApplication) => {
             type: "boolean";
             conflicts: string;
         };
+        json: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+            conflicts: string[];
+        };
         ignoreDirty: {
             target: "cli";
             cliName: string;