rman 2.1.0 → 2.2.0

package/commands/version.command.d.ts

@@ -148,7 +148,9 @@ export interface VersionExtraKeys {
     /** Files whose hard-coded version is rewritten to the version being written, in the same commit
      *  as the bump - paths relative to the package's own directory (e.g. `["src/constants.ts"]`).
      *  Per-package cascaded; a listed file a package doesn't have is a silent no-op, so one `"[*]"`
-     *  declaration covers a repo where only some packages carry one.
+     *  declaration covers a repo where only some packages carry one. A file that *exists* and holds
+     *  nothing rewritable is an error instead - unless the entry is `{ file, optional: true }`, which
+     *  is how a shared preset says "stamp it where there is one".
      *
      *  Stamping the source, not the build output: a build-time rewrite leaves the checked-in file
      *  claiming a placeholder, so anything running from source reports that placeholder, git never
@@ -168,11 +170,22 @@ export interface VersionExtraKeys {
     /** Same, after it (`postversion` in a Node repository). */
     after?: RunStepValue | RunStepValue[];
 }
-/** One `version.stamp` entry: a path, or a path plus the identifier to rewrite when it is not
- *  spelled `version`. */
+/**
+ * One `version.stamp` entry: a path, or a path plus the identifier to rewrite when it is not spelled
+ * `version` and whether the entry is `optional`.
+ *
+ * **`optional` marks an entry whose author cannot know whether the file holds a version.** A file
+ * that exists and has nothing to rewrite is otherwise an error - that is what catches a typo'd path
+ * or a renamed identifier before it silently ships a stale constant on every release. The case it
+ * is wrong for is a *shared preset* naming one path for every package of a technology, which is
+ * saying "stamp it where there is one" and cannot know which repositories keep a constant there.
+ * A bare string still throws; the asker chooses, the way `file.exists()` and `file.resolve()`
+ * already split the same question.
+ */
 export type VersionStampEntry = string | {
     file: string;
     constant?: string;
+    optional?: boolean;
 };
 type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
 declare const versionCommand: (app: import("../index.js").RmanApplication) => {

package/constants.js

@@ -1 +1 @@
-export const version = '2.1.0';
+export const version = '2.2.0';

package/package.json

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

package/services/version.service.js

@@ -291,6 +291,10 @@ export class VersionService extends Service {
             const before = fs.readFileSync(file, 'utf-8');
             const next = Manifest.stampVersion(pkg, file, before, version, { constant: entry.constant });
             if (next === undefined) {
+                /** Unreachable in a normal run - `assertStampable` already refused, before any write. Kept
+                 *  because this function is exported and a caller may reach it directly. */
+                if (entry.optional)
+                    continue;
                 const relative = path.relative(pkg.dirname, file);
                 throw new Error(`"version.stamp" lists "${relative}" for "${pkg.name}", but nothing in it could be ` +
                     `rewritten to ${version}.\n` +
@@ -320,12 +324,26 @@ export class VersionService extends Service {
 const VERSION_LIFECYCLE = 'version';
 /**
  * `.rmanrc "version.stamp"`, normalized: a bare string is the file, an object may also name the
- * identifier that holds the version (`{ file: 'src/version.go', constant: 'Version' }`).
+ * identifier that holds the version (`{ file: 'src/version.go', constant: 'Version' }`) and may
+ * mark the entry `optional`.
  *
  * The object form exists because the identifier was unnameable: `stampVersionConstant` took a
  * `name` and nothing ever passed it, so only the exact lowercase word `version` was ever matched -
  * `VERSION`, `Version` and `appVersion` were all silently skipped.
  */
+/* **`optional` exists because the entry and the expectation can have different authors.** A file
+ * that exists and holds nothing rewritable is an error precisely because it means somebody asked
+ * for something and did not get it - but "somebody" is not always the repository. A *shared preset*
+ * naming `src/constants.ts` for every package of a technology is saying "stamp it where there is
+ * one", and it cannot know which of forty repositories actually keeps a version constant there.
+ * Measured on `panates/postgrejs`, which extends `@panates/rman-preset`: the file exists, has never
+ * held a version constant, and `rman version` therefore refused the release for a line no one in
+ * that repository wrote.
+ *
+ * So the *asker* says which it meant, and the two spellings keep their own failure modes: a bare
+ * string still throws, which is what catches a typo'd path or a renamed identifier before it
+ * silently ships a stale constant on every release from then on. It is the `file.exists()` /
+ * `file.resolve()` split again - the optional form and the throwing form, chosen by the caller. */
 function readStampEntries(pkg) {
     const configured = pkg.config?.version?.stamp;
     const list = Array.isArray(configured) ? configured : configured ? [configured] : [];
@@ -334,7 +352,11 @@ function readStampEntries(pkg) {
         if (typeof item === 'string')
             entries.push({ file: item });
         else if (item && typeof item === 'object' && typeof item.file === 'string') {
-            entries.push({ file: item.file, constant: item.constant });
+            entries.push({
+                file: item.file,
+                constant: item.constant,
+                optional: item.optional === true,
+            });
         }
     }
     return entries;
@@ -355,6 +377,10 @@ function assertStampable(pkg, version) {
         });
         if (next !== undefined)
             continue;
+        /** The entry said "stamp it if there is one", so there being none is the answer rather than a
+         *  mistake - see `readStampEntries`. */
+        if (entry.optional)
+            continue;
         const relative = path.relative(pkg.dirname, file);
         throw new Error(`"version.stamp" lists "${relative}" for "${pkg.name}", but nothing in it could be ` +
             `rewritten to ${version}.\n` +