rman 2.9.0 → 2.10.1

package/commands/changelog.command.d.ts

@@ -184,6 +184,21 @@ declare const config: {
  * from commit type to section heading, and an option says `type: 'string'`.
  */
 export interface ChangelogExtraKeys {
+    /**
+     * Where each **named** group's changelog is written under `groupBy: 'group'`, relative to the
+     * repository root - `{ core: 'packages/core/CHANGELOG.md', dialects: 'docs/dialects.md' }`.
+     * Read off the repository root only.
+     *
+     * A group not listed keeps the default rule, `CHANGELOG-<group>.md` beside the default file; the
+     * default group's own file is `changelog.filePath`. A key naming no group, a path outside the
+     * repository, and two groups resolving to one file are all refused before anything is written.
+     * An explicit `--file-path` overrides the whole map for that run.
+     *
+     * **Move an existing file with `git mv`, not by changing the path here.** A file's
+     * `documented-up-to` marker is what the next `--write` starts from; at a new path there is none,
+     * and the write reads the group's entire history.
+     */
+    groupFiles?: ConfigValue<Record<string, string>>;
     /**
      * The heading each Conventional Commits type is listed under - `{ feat: 'New Features', dev:
      * 'Development Changes' }`. Per-package cascaded.

package/commands/version.command.js

@@ -5,6 +5,7 @@ import { registerCommand } from '../interfaces/rman-config.interface.js';
 import { VersionPlanService } from '../services/version-plan.service.js';
 import { assertAllowedBranch, branchGuardOptions, readBranchGuardOptions } from '../utils/branch-guard.js';
 import { packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+import { isSoloGroupKey } from '../utils/version-group.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
@@ -344,13 +345,21 @@ function planBlocks(entries) {
         else
             byGroup.set(e.groupKey, [e]);
     }
+    /**
+     * **Classified by the key, not by how many members a group has.** This was `group.length > 1`,
+     * which stands in for "is this a group" and is wrong in exactly one case: a group the repository
+     * *named* that happens to have a single member. Reported on a real repository - a package alone in
+     * `group: "abisena-iomt"` landed among the ungrouped and printed an empty Group cell, reading
+     * exactly like a package that had opted out. Its name decides its changelog file and its tag, so
+     * it is a line of its own whatever its size.
+     */
     const shared = [];
     const solo = [];
-    for (const group of byGroup.values()) {
-        if (group.length > 1)
-            shared.push({ members: group, shared: true });
+    for (const [key, group] of byGroup) {
+        if (isSoloGroupKey(key))
+            solo.push(...group);
         else
-            solo.push(group[0]);
+            shared.push({ members: group, shared: true });
     }
     return [
         ...(root.length ? [{ members: root, shared: false }] : []),

package/constants.js

@@ -1 +1 @@
-export const version = '2.9.0';
+export const version = '2.10.1';

package/package.json

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

package/services/changelog.service.js

@@ -600,33 +600,139 @@ function resolveFilePath(pkg, optionsFilePath) {
  */
 function partitionTargets(repository, targets, options) {
     const grouping = changelogGroupBy(repository, options);
-    const byKey = new Map();
-    for (const pkg of targets) {
-        const key = grouping === 'group' ? groupKeyOf(pkg) : `solo:${pkg.name}`;
-        const members = byKey.get(key);
-        if (members)
-            members.push(pkg);
-        else
-            byKey.set(key, [pkg]);
-    }
+    const groupFiles = grouping === 'group' ? readGroupFiles(repository, options) : {};
+    /** Checked against the **whole** repository, not against `targets`: a collision is a fact about
+     *  the configuration, and a `--scope` that happens to leave one of the two groups out must not be
+     *  what lets it through. */
+    if (grouping === 'group')
+        assertGroupFiles(repository, groupFiles, options);
     const repositoryLabel = `${path.basename(repository.dirname)} repository`;
-    return [...byKey].map(([key, members]) => {
+    return [...groupTargets(targets, grouping)].map(([key, members]) => {
         /** `targets` starts at the root, so a group holding it has it first - which is what makes the
          *  root the `home` of the default group without a second rule saying so. */
         const home = members[0];
         const grouped = !key.startsWith('solo:');
-        const named = key.startsWith('named:') ? key.slice('named:'.length) : undefined;
-        const filePkg = grouped ? repository.rootPackage : home;
+        const named = namedGroupOf(key);
         return {
             home,
-            filePkg,
+            filePkg: grouped ? repository.rootPackage : home,
             grouped,
             members: new Set(members),
             label: named ?? (home === repository.rootPackage ? repositoryLabel : home.name),
-            file: path.join(filePkg.dirname, suffixFileName(resolveFilePath(home, options.filePath), named)),
+            file: groupFile(repository, key, home, groupFiles, options),
         };
     });
 }
+/** The packages cut into what each file is about - by `.rmanrc group` under `groupBy: 'group'`, one
+ *  package each otherwise. Insertion order, so the first member of each group is the first of
+ *  `packages` to belong to it. */
+function groupTargets(packages, grouping) {
+    const byKey = new Map();
+    for (const pkg of packages) {
+        const key = grouping === 'group' ? groupKeyOf(pkg) : `solo:${pkg.name}`;
+        const members = byKey.get(key);
+        if (members)
+            members.push(pkg);
+        else
+            byKey.set(key, [pkg]);
+    }
+    return byKey;
+}
+/** `named:core` -> `core`; `undefined` for the default group and for a package that is its own. */
+function namedGroupOf(key) {
+    return key.startsWith('named:') ? key.slice('named:'.length) : undefined;
+}
+/**
+ * Where one group's changelog is written, absolute.
+ *
+ * In order: a named group listed in `changelog.groupFiles` goes where it says, relative to the
+ * repository root; any other named group takes the default file's name with its own suffixed
+ * (`CHANGELOG-core.md`), at the root; the default group takes the root's `changelog.filePath`; and a
+ * package that is a group of itself takes its own, in its own directory.
+ *
+ * **An explicit `--file-path` beats `groupFiles`**, as it already beats `changelog.filePath`: it
+ * names this run's file, and a run asking for one shape of name should not find half its groups
+ * somewhere a config put them. Named groups are still suffixed under it, so two cannot collide.
+ */
+function groupFile(repository, key, home, groupFiles, options) {
+    if (key.startsWith('solo:'))
+        return path.join(home.dirname, resolveFilePath(home, options.filePath));
+    const named = namedGroupOf(key);
+    const listed = named && !options.filePath ? groupFiles[named] : undefined;
+    if (listed)
+        return path.resolve(repository.dirname, listed);
+    return path.join(repository.dirname, suffixFileName(resolveFilePath(home, options.filePath), named));
+}
+/**
+ * `.rmanrc changelog.groupFiles`, off the repository root and nowhere else - a map from a named
+ * group to the file its changelog is written to, relative to the repository root.
+ *
+ * **The root's for the reason `groupBy` is the root's**: which file a group shares is a layout, and
+ * cascaded per package two members of one group could disagree about it, which has no answer.
+ */
+function readGroupFiles(repository, options) {
+    /** `--file-path` takes the whole decision - see `groupFile` - so the map is not even read. A
+     *  mistake in it is still a mistake, but not one this run acts on. */
+    if (options.filePath)
+        return {};
+    const declared = repository.rootPackage.config?.changelog?.groupFiles;
+    if (declared === undefined || declared === null)
+        return {};
+    if (typeof declared !== 'object' || Array.isArray(declared)) {
+        throw new Error(`.rmanrc "changelog.groupFiles" must map a group name to a file path, ` +
+            `e.g. { core: "packages/core/CHANGELOG.md" }.`);
+    }
+    for (const [group, file] of Object.entries(declared)) {
+        if (typeof file !== 'string' || !file) {
+            throw new Error(`.rmanrc "changelog.groupFiles.${group}" must be a file path, relative to the repository root.`);
+        }
+    }
+    return declared;
+}
+/**
+ * Refuses a `changelog.groupFiles` that would write somewhere wrong - before anything is written.
+ *
+ * Three ways, and each is silent otherwise:
+ *
+ * - **A key naming no group.** rman drops an unknown config key without a word, so a typo here would
+ *   leave the group on the default rule and nothing would say so. Here the groups are known, so the
+ *   key can be checked against them.
+ * - **A path leaving the repository.** `version --changelog` commits the file with the release; a
+ *   file outside the working tree is one it cannot add.
+ * - **Two groups sharing one file**, including the default group and any package that is a group of
+ *   itself. The `rman:documented-up-to` marker is one per file, so two groups writing into it would
+ *   each read the other's marker as its own boundary - entries missing or written twice, with
+ *   nothing failing. The default rule cannot produce a collision; an explicit map can, and an
+ *   unlisted group's suffixed name can land on a listed one's path.
+ */
+function assertGroupFiles(repository, groupFiles, options) {
+    const all = groupTargets([repository.rootPackage, ...repository.packages], 'group');
+    const named = [...all.keys()].map(namedGroupOf).filter((name) => !!name);
+    for (const [group, file] of Object.entries(groupFiles)) {
+        if (!named.includes(group)) {
+            throw new Error(`.rmanrc "changelog.groupFiles" names a group "${group}" that no package belongs to. ` +
+                (named.length ? `Named groups here: ${named.join(', ')}.` : 'This repository has no named groups.'));
+        }
+        const rel = path.relative(repository.dirname, path.resolve(repository.dirname, file));
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error(`.rmanrc "changelog.groupFiles.${group}" points outside the repository (${file}). ` +
+                `The file is committed with the release, so it has to be inside the working tree.`);
+        }
+    }
+    const owner = new Map();
+    for (const [key, members] of all) {
+        const file = groupFile(repository, key, members[0], groupFiles, options);
+        const label = namedGroupOf(key) ?? (key === 'default' ? 'the default group' : members[0].name);
+        const other = owner.get(file);
+        if (other) {
+            throw new Error(`Two changelogs would be written to one file: ${other} and ${label} both resolve to ` +
+                `${path.relative(repository.dirname, file)}.\n` +
+                `  Each file carries one "documented up to" marker, so two groups sharing it would read each ` +
+                `other's boundary. Give each its own path in .rmanrc "changelog.groupFiles".`);
+        }
+        owner.set(file, label);
+    }
+}
 /** `CHANGELOG.md` + `core` -> `CHANGELOG-core.md`, keeping whatever directory and extension
  *  `changelog.filePath` chose (`docs/HISTORY.md` -> `docs/HISTORY-core.md`). */
 function suffixFileName(filePath, suffix) {

package/utils/version-group.d.ts

@@ -16,6 +16,16 @@ import type { Package } from '../core/classes/package.js';
  * batching; what it cannot do is leave the tag pattern behind, which is the point.
  */
 export declare function groupKeyOf(pkg: Package): string;
+/**
+ * Whether a group key belongs to a package that is in **no** group - `group: false`, a line of its
+ * own that nobody named.
+ *
+ * Here beside `groupKeyOf` so the key's shape is known in one place. The plan table asks it to decide
+ * whether the Group column is worth printing, and it has to ask *this* rather than count members: a
+ * group the repository named is a version line of its own whatever its size, while a package that
+ * opted out of grouping has no group to name.
+ */
+export declare function isSoloGroupKey(key: string): boolean;
 /**
  * How many distinct version lines this package's repository releases along - 1 when every package
  * moves together, more once anything is grouped apart.

package/utils/version-group.js

@@ -22,6 +22,18 @@ export function groupKeyOf(pkg) {
         return `named:${assertGroupName(g, pkg)}`;
     return 'default';
 }
+/**
+ * Whether a group key belongs to a package that is in **no** group - `group: false`, a line of its
+ * own that nobody named.
+ *
+ * Here beside `groupKeyOf` so the key's shape is known in one place. The plan table asks it to decide
+ * whether the Group column is worth printing, and it has to ask *this* rather than count members: a
+ * group the repository named is a version line of its own whatever its size, while a package that
+ * opted out of grouping has no group to name.
+ */
+export function isSoloGroupKey(key) {
+    return key.startsWith('solo:');
+}
 /**
  * How many distinct version lines this package's repository releases along - 1 when every package
  * moves together, more once anything is grouped apart.