rman 1.0.9 → 1.0.12

package/services/run.service.js

@@ -26,14 +26,21 @@ export var RunService;
      * `getScriptSteps`:
      *   run:
      *     build:
-     *       script: tsc -b
-     *       preScript: [node ./generate.js, node ./validate.js]
-     *       postScript: node ./copy-assets.js
+     *       before: [node ./generate.js, node ./validate.js]
+     *       exec: tsc -b
+     *       after: node ./copy-assets.js
      *       override: true   # use these even if the package *does* define its own
+     *
+     * A bare string is shorthand for `exec`, which is by far the common case - a script that is just
+     * a command, with nothing to configure about how it runs:
+     *   run:
+     *     test: mocha          # same as   test: { exec: mocha }
      */
     function getConfig(pkg, script) {
         const runCfg = pkg.config?.run;
         const cfg = runCfg && typeof runCfg === 'object' ? runCfg[script] : undefined;
+        if (typeof cfg === 'string' || Array.isArray(cfg))
+            return { exec: cfg };
         return cfg && typeof cfg === 'object' ? cfg : {};
     }
     RunService.getConfig = getConfig;
@@ -197,10 +204,14 @@ export var RunService;
         const ifStatusCache = new Map();
         /** Repo-wide bookend: root's own pre/post hooks run once each, exclusively, around every package
          *  (unless root itself opts out via `run.<script>.skip`, fails its own `run.<script>.if`, or the
-         *  run is scoped to a single package by `cwdScope` - a repo-wide bookend has no place there). */
-        const rootIf = !cwdScope && parseIfExpr(rootCfg.if);
+         *  run is scoped to a single package by `cwdScope` - a repo-wide bookend has no place there).
+         *
+         *  Only in a monorepo. Without one the root *is* the single package, already in the loop below
+         *  with the same hooks and the same directory - a bookend would simply run each of them a
+         *  second time. */
+        const rootIf = !cwdScope && repository.monorepo && parseIfExpr(rootCfg.if);
         const rootIfPasses = rootIf ? await evaluateIf(repository, repository.rootPackage, rootIf, ifStatusCache) : true;
-        const rootSkipped = !!cwdScope || rootCfg.skip === true || !rootIfPasses;
+        const rootSkipped = !!cwdScope || !repository.monorepo || rootCfg.skip === true || !rootIfPasses;
         const rootSteps = rootSkipped ? [] : getScriptSteps(repository.rootPackage, script);
         const rootPre = rootSteps.filter(s => s.name === 'pre' + script);
         const rootPost = rootSteps.filter(s => s.name === 'post' + script);
@@ -255,11 +266,36 @@ export var RunService;
             }));
         }
         if (!children.length) {
-            console.log(colors.gray(`No package defines a "${script}" script.`));
-            return;
+            /**
+             * Two different nothings, and only one of them is fine.
+             *
+             * Nobody in the repository defines this script at all: the name is a mistake - a typo, or a
+             * script that used to exist - and `npm run` fails on exactly this. Staying silent is how
+             * `rman run qc` sat in a CI pipeline for months reporting success while running nothing, with
+             * `qc` defined only on the root (whose own scripts a monorepo never runs, only its
+             * `pre`/`post` bookends).
+             *
+             * Everything was filtered out instead - `--scope`, `--changed`, `run.<script>.skip`, an
+             * `if:` that didn't match: zero is the correct answer to what was asked, and asking "build
+             * only what changed" when nothing changed must not fail a pipeline.
+             */
+            /** `getPackages()` and nothing else - in a monorepo that excludes the root, which is the
+             *  point: the root contributes only `pre`/`post` bookends, never the script itself, so a
+             *  `qc` defined *only* there is exactly the mistake above rather than an excuse for it. (And
+             *  had the root contributed a bookend, `children` wouldn't be empty.) In a single-package
+             *  repository the root *is* the one package, and is covered. */
+            const definedSomewhere = repository.getPackages().some(pkg => getScriptSteps(pkg, script).length > 0);
+            if (definedSomewhere) {
+                console.log(colors.gray(`Nothing to run - every package was filtered out of "${script}".`));
+                return;
+            }
+            const message = `No package defines a "${script}" script.`;
+            console.log(colors.red(message));
+            const err = new Error(message);
+            err.logged = true;
+            throw err;
         }
         panel.start();
-        let failed = false;
         try {
             /** bail:false here - each package's own resolved bail setting decides whether to call
              *  `rootTask.abort()` itself (see `runSteps`), since power-tasks' own `bail` can't vary per package. */
@@ -267,13 +303,25 @@ export var RunService;
             await rootTask.toPromise();
         }
         catch {
-            failed = true;
+            // Swallowed on purpose: whether the root promise rejected says nothing reliable about the
+            // run - see below. The per-package tallies are what decide.
         }
         finally {
+            /** A package's own `bail` aborts the root task, which settles its promise *immediately* while
+             *  the packages already in flight keep running. Waiting for every child here is what makes
+             *  the summary below describe a finished run rather than a snapshot of one still going -
+             *  measured: it printed "0 succeeded, 1 failed, 3 skipped" and then three of those "skipped"
+             *  packages went on to succeed. */
+            await Promise.allSettled(children.map(child => child.toPromise()));
             panel.stop();
         }
-        panel.printSummary();
-        if (failed) {
+        const summary = panel.printSummary();
+        /** The tallies, never `rootTask.toPromise()`'s own outcome: with a sibling still in flight at
+         *  the moment one package failed, that promise *resolves*, and this command used to exit 0 on a
+         *  run it had just reported as failed - non-deterministically, since it came down to which
+         *  packages happened to still be running (measured: `1 0 1 1 0` across five identical runs).
+         *  A single failed package must fail the command, every time. */
+        if (summary.failedCount > 0) {
             const err = new Error(`"${script}" failed`);
             err.logged = true;
             throw err;
@@ -336,9 +384,9 @@ function getScriptSteps(pkg, script) {
         if (cfg.override === true || !hasOwn)
             json.scripts[key] = value;
     };
-    applyConfigScript(script, cfg.script);
-    applyConfigScript('pre' + script, cfg.preScript);
-    applyConfigScript('post' + script, cfg.postScript);
+    applyConfigScript(script, cfg.exec);
+    applyConfigScript('pre' + script, cfg.before);
+    applyConfigScript('post' + script, cfg.after);
     json.scripts[script] = json.scripts[script] || '#';
     const info = parseNpmScript(json, 'npm run ' + script);
     if (!info?.raw?.length)

package/services/version.service.js

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import path from 'node:path';
 import semver from 'semver';
 import { detectChangeHash, expandTag } from '../utils/change-hash.js';
@@ -6,6 +7,7 @@ import { exec } from '../utils/exec.js';
 import { GitHelper } from '../utils/git.js';
 import { filterPackages } from '../utils/package-filter.js';
 import { expandReleaseTag, findLastReleaseVersion, formatCalendarVersion, isCalendarVersion, usesCalendarVersion, } from '../utils/release-version.js';
+import { stampVersionConstant, stampVersionLabel } from '../utils/version-stamp.js';
 import { parseWorkspaceRange } from '../utils/workspace-range.js';
 import { ChangelogService } from './changelog.service.js';
 export var VersionService;
@@ -133,9 +135,13 @@ export var VersionService;
         const isRealEntry = (e) => !(repository.monorepo && e.package === repository.rootPackage);
         const bumped = plan.filter(e => e.status === 'bump' && isRealEntry(e));
         const bumpedByName = new Map(bumped.map(e => [e.package.name, e]));
+        /** Repo-relative paths of every file stamped with the new version below (a Dockerfile label, a
+         *  source constant), so each lands in the same commit as the bump that made it stale - keyed by
+         *  package, the way `changelogFileByPackage` is. */
+        const stampedByPackage = new Map();
         for (const entry of bumped) {
             const pkg = entry.package;
-            await runVersionScript(pkg, 'preScript', 'preversion');
+            await runVersionScript(pkg, 'before', 'preversion');
             pkg.json.version = entry.to;
             for (const depKey of DEPENDENCY_KEYS) {
                 const deps = pkg.json[depKey];
@@ -157,9 +163,14 @@ export var VersionService;
                     deps[depName] = '^' + depEntry.to;
                 }
             }
-            await runVersionScript(pkg, 'script', 'version');
+            await runVersionScript(pkg, 'exec', 'version');
             pkg.writeJson();
-            await runVersionScript(pkg, 'postScript', 'postversion');
+            // Before `postversion`, so a script that reacts to the bump sees the whole new state.
+            const stamped = [stampDockerfile(pkg, entry.to), ...stampSourceFiles(pkg, entry.to)].filter((f) => !!f);
+            if (stamped.length) {
+                stampedByPackage.set(pkg.name, stamped.map(f => path.relative(repository.dirname, f)));
+            }
+            await runVersionScript(pkg, 'after', 'postversion');
         }
         const rootEntry = repository.monorepo ? plan.find(e => e.package === repository.rootPackage) : undefined;
         if (rootEntry?.status === 'bump') {
@@ -218,6 +229,7 @@ export var VersionService;
                 const changelogFile = changelogFileByPackage.get(e.package.name);
                 if (changelogFile)
                     files.push(changelogFile);
+                files.push(...(stampedByPackage.get(e.package.name) ?? []));
             }
             await git.commit(files, buildCommitMessage(repository, groupEntries, options.message));
             const tags = new Set(groupEntries.map(e => expandTag(e.package, e.to)));
@@ -490,3 +502,55 @@ async function runVersionScript(pkg, cfgKey, npmScriptName) {
     if (command)
         await exec(command, { cwd: pkg.dirname, stdio: 'inherit' });
 }
+/**
+ * Keeps a package's Dockerfile `org.opencontainers.image.version` label in step with the version
+ * just written, returning the absolute path when it actually changed (so the caller can fold it
+ * into the same commit) and `undefined` otherwise.
+ *
+ * Here rather than in a build script: the label is a *statement of the package's version*, so it
+ * belongs to whatever writes that version - which keeps it in the bump commit, leaves the tree
+ * clean, and makes it right for anyone building the Dockerfile by hand. A build-time rewrite is
+ * both later than it needs to be and invisible to git.
+ *
+ * The same path `publish --target docker` builds from (`publish.docker.dockerfile`, default
+ * `Dockerfile`), so the two can never disagree about which file this is. Opt out with `.rmanrc
+ * "version": { "stampDockerfile": false }`; a package with no Dockerfile, or one that doesn't
+ * declare the label, is a no-op either way.
+ */
+function stampDockerfile(pkg, version) {
+    if (pkg.config?.version?.stampDockerfile === false)
+        return undefined;
+    const file = path.resolve(pkg.dirname, pkg.config?.publish?.docker?.dockerfile || 'Dockerfile');
+    if (!fs.existsSync(file))
+        return undefined;
+    const stamped = stampVersionLabel(fs.readFileSync(file, 'utf-8'), version);
+    if (stamped === undefined)
+        return undefined;
+    fs.writeFileSync(file, stamped, 'utf-8');
+    return file;
+}
+/**
+ * Keeps every `.rmanrc "version.stamp"` source file's `version` constant in step with the version
+ * just written, returning the absolute paths of the ones that actually changed.
+ *
+ * Explicitly listed rather than discovered: unlike the OCI Dockerfile label there is no standard
+ * saying "this file holds the version", and the assignment this matches is deliberately broad. A
+ * listed file a package doesn't have is a silent no-op, which is what lets one `"[*]"` declaration
+ * cover a repo where only some packages carry one.
+ */
+function stampSourceFiles(pkg, version) {
+    const configured = pkg.config?.version?.stamp;
+    const patterns = typeof configured === 'string' ? [configured] : (configured ?? []);
+    const stamped = [];
+    for (const rel of patterns) {
+        const file = path.resolve(pkg.dirname, rel);
+        if (!fs.existsSync(file))
+            continue;
+        const next = stampVersionConstant(fs.readFileSync(file, 'utf-8'), version);
+        if (next === undefined)
+            continue;
+        fs.writeFileSync(file, next, 'utf-8');
+        stamped.push(file);
+    }
+    return stamped;
+}

package/utils/change-hash.d.ts

@@ -15,8 +15,8 @@ export declare function tagPattern(pkg: Package): string;
 export declare function findLatestTag(git: GitHelper, pkg: Package): Promise<string | undefined>;
 /** The forward direction of `findLatestTag`: expands `pkg`'s (cascaded) `.rmanrc
  *  changelog.tagPattern` into the concrete tag name `version` belongs under - `{name}` becomes the
- *  package's own name, `*` becomes `version`. Shared by `version` (creating the tag), `publish
- *  --target github` (finding the release that tag belongs to), and `detectChangeHash`'s own npm
+ *  package's own name, `*` becomes `version`. Shared by `version` (creating the tag),
+ *  `github-release` (finding the release that tag belongs to), and `detectChangeHash`'s own npm
  *  fallback (mapping a published version back onto a tag), so all three name tags identically. */
 export declare function expandTag(pkg: Package, version: string): string;
 /** The pattern expansion `expandTag` performs, on any pattern - `{name}` becomes `name`, `*` becomes

package/utils/change-hash.js

@@ -22,8 +22,8 @@ export async function findLatestTag(git, pkg) {
 }
 /** The forward direction of `findLatestTag`: expands `pkg`'s (cascaded) `.rmanrc
  *  changelog.tagPattern` into the concrete tag name `version` belongs under - `{name}` becomes the
- *  package's own name, `*` becomes `version`. Shared by `version` (creating the tag), `publish
- *  --target github` (finding the release that tag belongs to), and `detectChangeHash`'s own npm
+ *  package's own name, `*` becomes `version`. Shared by `version` (creating the tag),
+ *  `github-release` (finding the release that tag belongs to), and `detectChangeHash`'s own npm
  *  fallback (mapping a published version back onto a tag), so all three name tags identically. */
 export function expandTag(pkg, version) {
     return applyTagPattern(tagPattern(pkg), pkg.name, version);

package/utils/npm-run-path.d.ts

@@ -63,5 +63,5 @@ export declare function npmRunPath(options?: RunPathOptions): string;
  ```
  */
 export declare function npmRunPathEnv(options?: EnvOptions): {
-    [x: string]: string | undefined;
+    [key: string]: string | undefined;
 };

package/utils/version-stamp.d.ts

@@ -0,0 +1,40 @@
+/** Keeping a package's version truthful wherever the package itself declares it - its Dockerfile's
+ *  OCI label, and any source file that hard-codes it as a constant. Both are `version`'s job rather
+ *  than a build step's: a version is being written, these are places it is written, and doing it
+ *  here puts them in the bump commit instead of leaving the repository disagreeing with itself. */
+/** The OCI label whose value is, by specification, "version of the packaged software" - so a
+ *  package's own `package.json` version is the only correct value it can hold, which is what makes
+ *  stamping it automatic rather than something to configure. */
+export declare const OCI_VERSION_LABEL = "org.opencontainers.image.version";
+/**
+ * Rewrites every `org.opencontainers.image.version` value in a Dockerfile's `LABEL` instructions to
+ * `version`, returning the new content - or `undefined` when there was nothing to change (no such
+ * label, or it already holds this version), so a caller can skip writing the file at all.
+ *
+ * Only ever *rewrites*: a Dockerfile that doesn't declare the label is left exactly as it is rather
+ * than having one inserted. Which labels an image carries is the author's decision; keeping one
+ * they already declared truthful is not.
+ *
+ * The existing quoting style is preserved, so the diff is the version and nothing else.
+ */
+export declare function stampVersionLabel(content: string, version: string): string | undefined;
+/**
+ * Rewrites the string assigned to a `name` constant (default `version`) in a source file to
+ * `version`, returning the new content - or `undefined` when there was nothing to change, so a
+ * caller can skip writing the file at all. Both an assignment and an object property are matched:
+ *
+ * ```ts
+ * export const version = '1';   ->   export const version = '6.0.10';
+ * { name: 'app', version: '1' } ->   { name: 'app', version: '6.0.10' }
+ * ```
+ *
+ * Unlike the Dockerfile label there is no standard naming a file as holding the version, so this
+ * only ever runs against files `.rmanrc "version.stamp"` explicitly lists - which is also what
+ * keeps a match this broad safe.
+ *
+ * Stamping the *source* rather than the build output is the point: a build-time rewrite leaves the
+ * checked-in file claiming some placeholder, so anything running from source (tests, ts-node, the
+ * dev loop) reports that placeholder, git never records the released version, and the rewrite has
+ * to be redone on every build.
+ */
+export declare function stampVersionConstant(content: string, version: string, name?: string): string | undefined;

package/utils/version-stamp.js

@@ -0,0 +1,76 @@
+/** Keeping a package's version truthful wherever the package itself declares it - its Dockerfile's
+ *  OCI label, and any source file that hard-codes it as a constant. Both are `version`'s job rather
+ *  than a build step's: a version is being written, these are places it is written, and doing it
+ *  here puts them in the bump commit instead of leaving the repository disagreeing with itself. */
+/** The OCI label whose value is, by specification, "version of the packaged software" - so a
+ *  package's own `package.json` version is the only correct value it can hold, which is what makes
+ *  stamping it automatic rather than something to configure. */
+export const OCI_VERSION_LABEL = 'org.opencontainers.image.version';
+/**
+ * Rewrites every `org.opencontainers.image.version` value in a Dockerfile's `LABEL` instructions to
+ * `version`, returning the new content - or `undefined` when there was nothing to change (no such
+ * label, or it already holds this version), so a caller can skip writing the file at all.
+ *
+ * Only ever *rewrites*: a Dockerfile that doesn't declare the label is left exactly as it is rather
+ * than having one inserted. Which labels an image carries is the author's decision; keeping one
+ * they already declared truthful is not.
+ *
+ * The existing quoting style is preserved, so the diff is the version and nothing else.
+ */
+export function stampVersionLabel(content, version) {
+    const lines = content.split('\n');
+    let changed = false;
+    // A LABEL's key=value pairs can spill over several lines via trailing backslashes, so the
+    // instruction a line belongs to is tracked rather than assumed from the line itself. Anything
+    // outside a LABEL is left alone - the same key in an ARG, an ENV or a comment is not a label.
+    let continuing = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const inLabel = continuing || /^\s*LABEL\b/i.test(line);
+        continuing = inLabel && /\\\s*$/.test(line);
+        if (!inLabel)
+            continue;
+        lines[i] = line.replace(LABEL_VALUE, (whole, key, value) => {
+            const quote = value[0] === '"' || value[0] === "'" ? value[0] : '';
+            const next = `${key}${quote}${version}${quote}`;
+            if (next !== whole)
+                changed = true;
+            return next;
+        });
+    }
+    return changed ? lines.join('\n') : undefined;
+}
+/**
+ * Rewrites the string assigned to a `name` constant (default `version`) in a source file to
+ * `version`, returning the new content - or `undefined` when there was nothing to change, so a
+ * caller can skip writing the file at all. Both an assignment and an object property are matched:
+ *
+ * ```ts
+ * export const version = '1';   ->   export const version = '6.0.10';
+ * { name: 'app', version: '1' } ->   { name: 'app', version: '6.0.10' }
+ * ```
+ *
+ * Unlike the Dockerfile label there is no standard naming a file as holding the version, so this
+ * only ever runs against files `.rmanrc "version.stamp"` explicitly lists - which is also what
+ * keeps a match this broad safe.
+ *
+ * Stamping the *source* rather than the build output is the point: a build-time rewrite leaves the
+ * checked-in file claiming some placeholder, so anything running from source (tests, ts-node, the
+ * dev loop) reports that placeholder, git never records the released version, and the rewrite has
+ * to be redone on every build.
+ */
+export function stampVersionConstant(content, version, name = 'version') {
+    let changed = false;
+    const pattern = new RegExp(`(\\b${escapeRegExp(name)}\\s*[:=]\\s*)(['"\`])([^'"\`\\n]*)\\2`, 'g');
+    const result = content.replace(pattern, (whole, prefix, quote) => {
+        const next = `${prefix}${quote}${version}${quote}`;
+        if (next !== whole)
+            changed = true;
+        return next;
+    });
+    return changed ? result : undefined;
+}
+const LABEL_VALUE = new RegExp(`(${OCI_VERSION_LABEL.replace(/\./g, '\\.')}\\s*=\\s*)("[^"\\n]*"|'[^'\\n]*'|[^\\s\\\\]+)`, 'g');
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}