@arc-e-tect/api-only-publisher 0.18.0 → 0.18.1

package/README.adoc

@@ -6,7 +6,7 @@
 :source-highlighter: rouge
 // The released version of this component: its snippets use it. The release
 // workflow updates it; do not change it by hand.
-:api-only-publisher-version: 0.18.0
+:api-only-publisher-version: 0.18.1
 
 [NOTE]
 .About this documentation
@@ -691,7 +691,8 @@ Configured portfolio: paths=none, location=portfolios
 |`file`
 |A local directory, laid out as `<directory>/<target>/<version>/`.
 Not a distribution mechanism between repositories: it makes the pipeline testable end to end with no infrastructure, lets a library share one build with the projects that implement it, and is a local-iteration escape hatch.
-Like a registry, it never replaces a version it holds with other documents (<<idempotent,Publishing the same version again §>>); with `clean: true` only the version being published is kept, for a directory that is a build output rather than a record of releases.
+Like a registry, it never replaces a version it holds with other documents (<<idempotent,Publishing the same version again §>>).
+With `clean: true` the directory is a build output rather than a record of releases: only the version being published is kept, and it holds the last build, so a version built again with other documents replaces it.
 
 |`maven`
 |A path publishes into a repository layout on disk; an `http(s)` URL deploys to a remote repository with an HTTP `PUT` per file, and keeps its `maven-metadata.xml` (<<maven-remote,Publishing to a remote Maven repository §>>).
@@ -776,7 +777,8 @@ What happens when the destination already has the version:
 |The same documents: nothing is written or sent, and the log says `already published, identical`, or `with the same documents` when the copy came from another commit.
 Other documents: the version is not published to that channel, and the run warns, naming the version -- a published version is never replaced, so publish the change as a new version (<<channel-problems,When a channel cannot take a version §>>).
 A copy that cannot be read, so there is nothing to compare, is treated as one with other documents, saying why it `cannot be compared`.
-`file` compares the `manifest.json` in the version's directory, and with `clean: true` removes the other versions, never this one.
+`file` compares the `manifest.json` in the version's directory.
+With `clean: true`, a build output, it replaces a version with other documents instead, logging `Replaced`, and removes the other versions; what guards a release there is the check before `publish` (<<version-guard,A changed target needs a new version §>>), and a subscriber's lockfile after it.
 `maven` and `gitlab-package` read back every file before uploading any, so a run interrupted half-way is completed by the next one; a GitLab registry that allows duplicate packages, as it does by default, would otherwise replace a version.
 A version completed beside an archive from another commit gets that archive's `manifest.json`, so the two agree on where the version came from; a POM carries no documents, and one already there is left as it is.
 `github-release` reads the manifest in the asset the release has, and never overwrites one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Builds, packs and publishes API description documents from a library of reusable fragments.",
   "license": "MIT",
   "author": "Arc-E-Tect",

package/src/channels.js

@@ -34,7 +34,10 @@ function format(template, manifest) {
  * Not a real distribution mechanism. It exists so the pipeline is testable end
  * to end before any remote exists, and as a local-iteration escape hatch
  * afterwards. Like the registries, it never replaces a version: one it holds with
- * the same documents is left alone, and one with other documents is refused.
+ * the same documents is left alone, and one with other documents is refused --
+ * unless `clean: true` declares the directory a build output, not a record of
+ * releases, where the last build is what it holds. What guards a release is then
+ * the git check before `publish`, and a subscriber's lockfile after it.
  */
 function publishFile(archive, manifest, options, log) {
     // Relative to the library root, not to wherever the CLI happened to be run.
@@ -44,21 +47,29 @@ function publishFile(archive, manifest, options, log) {
     const manifestDest = path.join(targetDir, "manifest.json");
     const files = [archiveDest, manifestDest];
 
+    const buildOutput = options.clean === true;
     const held = fs.existsSync(manifestDest) ? judgeHeld(fs.readFileSync(manifestDest), "json", manifest) : null;
-    if (held && held.verdict !== "same") {
+    const replaced = held && held.verdict !== "same";
+    if (replaced && !buildOutput) {
         throw new ChannelConflict(`${dir} already has ${manifest.target} ${manifest.version}, and it ` +
             `${held.verdict === "different" ? "is not this one" : `cannot be compared: ${held.reason}`}; ` +
             "a published version is never replaced, so publish the change as a new version");
     }
-    // `clean: true` keeps only the version being published. Used where the
-    // directory is a build output rather than a record of releases: an older
-    // version is published again from the commit that declared it.
-    if (options.clean === true && fs.existsSync(path.join(dir, manifest.target))) {
+    // `clean: true` keeps only the version being published, and the last build of it.
+    // Used where the directory is a build output rather than a record of releases: an
+    // older version is published again from the commit that declared it.
+    if (buildOutput && fs.existsSync(path.join(dir, manifest.target))) {
         for (const version of fs.readdirSync(path.join(dir, manifest.target))) {
-            if (version !== manifest.version) fs.rmSync(path.join(dir, manifest.target, version), { recursive: true, force: true });
+            if (version !== manifest.version || replaced) {
+                fs.rmSync(path.join(dir, manifest.target, version), { recursive: true, force: true });
+            }
         }
     }
-    if (held && fs.existsSync(archiveDest)) {
+    if (replaced) {
+        log(`-- Replaced ${manifest.target} ${manifest.version} in ${dir}, which clean: true makes a build output: it held ` +
+            (held.verdict === "different" ? "other documents" : `a copy that cannot be compared (${held.reason})`));
+    }
+    if (held && !replaced && fs.existsSync(archiveDest)) {
         const identical = fs.readFileSync(archiveDest).equals(fs.readFileSync(archive));
         log(`-- ${manifest.target} ${manifest.version} is already published, ` +
             `${identical ? "identical" : "with the same documents"}, in ${dir}; nothing to do`);
@@ -68,7 +79,7 @@ function publishFile(archive, manifest, options, log) {
     fs.copyFileSync(archive, archiveDest);
     fs.writeFileSync(manifestDest, JSON.stringify(manifest, null, 2) + "\n");
 
-    log(`-- Published ${manifest.target} ${manifest.version} to ${archiveDest}`);
+    if (!replaced) log(`-- Published ${manifest.target} ${manifest.version} to ${archiveDest}`);
     return { location: archiveDest, files };
 }