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

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.16.2
+:api-only-publisher-version: 0.18.0
 
 [NOTE]
 .About this documentation
@@ -191,11 +191,16 @@ Without `--target`, it also fails on a fragment no target reaches, as <<unrefere
 |Report which targets' closures changed between a git ref and the working tree.
 A target whose closure is untouched needs no new version, however much else in the repository moved.
 
+|`check [--target <t>]... [--pre-release <ids>] [--since <ref>]`
+|Fail on every published target that changed without a new version, from git alone, as <<version-guard,A changed target needs a new version §>> describes.
+Made for a pull request's pipeline: no network, no credentials, nothing built.
+
 |`pack [--pre-release <ids>] [--target <t>]... [--out <dir>]`
 |Archive each built, published target with a `manifest.json`, at the version its version file declares.
 
-|`publish [--pre-release <ids>] [--target <t>]... [--channel <c>]... [--out <dir>]`
-|Pack each target once, then ship those same bytes to each of its channels, or only to those of them each `--channel` names (<<channel-routing,Which channels a target goes to §>>).
+|`publish [--pre-release <ids>] [--target <t>]... [--channel <c>]... [--since <ref>] [--out <dir>]`
+|Check every target as `check` does, then pack each target once and ship those same bytes to each of its channels, or only to those of them each `--channel` names (<<channel-routing,Which channels a target goes to §>>).
+A channel that cannot take a version is a warning, not a failure (<<channel-problems,When a channel cannot take a version §>>).
 
 |`split [--out <dir>] [--by kind\|target]`
 |Make the library safe to break into separate repositories.
@@ -212,6 +217,7 @@ A target whose closure is untouched needs no new version, however much else in t
 npm run apionly -- build --target orders --openapi
 npm run apionly -- publish --target orders --pre-release rc.1
 npm run apionly -- changed --since origin/main --quiet
+npm run apionly -- check
 ----
 
 [#init]
@@ -408,7 +414,54 @@ Cutting one never means editing the file, and then remembering to edit it back,
 
 A version names one set of documents.
 Publishing different documents under a version that was published before, after editing a fragment without changing the version file, is refused by the API-Only Subscriber in every project that locked the earlier ones.
-Change the version in the same commit as the fragments instead.
+Change the version in the same commit as the fragments instead; `check` and `publish` refuse a target that does not (<<version-guard,A changed target needs a new version §>>).
+
+[#version-guard]
+=== A changed target needs a new version
+
+`check` decides, for every published target, whether its version may be published, and fails naming each one that may not.
+`publish` decides the same before it packs or sends anything, so a target that fails it is never published anywhere.
+Both read only git: the target's release tags, its history, and the working tree, changes not yet committed included.
+
+[cols="1,3", options="header"]
+|===
+|What git tells |What `check` requires
+
+|A release tag for this exact version
+|The target unchanged since that tag: the version was released from what the tag points at, and publishing it again is safe only with the same specifications.
+
+|Release tags, but none for this version
+|A version above the latest release; one below it is refused.
+
+|No release tags at all
+|Compared with the merge-base with the main branch, or with the ref `--since` names: a target changed since then needs a higher version than its version file declared there, and a version lower than it was there is refused.
+A target whose version file was not there yet is new, and passes.
+|===
+
+Release tags are named by `versioning.tagFormat`, `{target}-v{version}` by default: `orders-v2.1.0`.
+The Publisher never creates them: the pipeline that publishes does, after it has published, because a tool that pushes to git needs write access to the repository it builds from.
+The reference pipelines show the step, and the `gitlab-package` channel's `release: true` creates the tag with the release.
+The main branch is `versioning.mainBranch`, `main` by default; its remote-tracking branch, `origin/main`, is preferred, as that is what a CI checkout has.
+
+A pre-release follows the same rules, by its full version:
+
+* Its version file need not change: `--pre-release rc.2` already makes a new version, so a target changed since the main branch passes with an unchanged file.
+* A pre-release that was released before -- a tag `orders-v2.1.0-rc.1` -- is refused when the target changed since, as a release is.
+* A pre-release of a version already released is refused: `2.1.0-rc.1` sorts before `2.1.0`, so it can never be the next version.
+
+Where the guard cannot decide, it says so, and only `check` fails on it: `check` is the gate, while `publish` fails on a proven violation alone.
+Outside a git repository, `check` fails and `publish` warns that the versions were not checked.
+A target with no release tag, in a checkout that has no merge-base with the main branch -- a shallow clone, or no main branch at all -- is `undecided`: `check` fails naming it, and `publish` warns and publishes it; a target with a release tag is decided all the same.
+In CI, fetch the full history and the tags -- `actions/checkout` with `fetch-depth: 0`, or `GIT_DEPTH: 0` on GitLab -- so that nothing is left undecided.
+Without release tags, the check on the main branch itself compares the main branch with itself, so it is in the pull request that it catches a missing bump; the tags are what make it exact everywhere.
+
+To catch it before a push, call `check` from whatever runs the repository's git hooks -- a `pre-push` hook, or a hook manager such as husky or lefthook:
+
+[source,sh]
+----
+#!/bin/sh
+exec npx --no-install api-only-publisher check
+----
 
 [#closure]
 == Independent versioning, and the dependency closure
@@ -638,7 +691,7 @@ 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.
-Publishing a version again writes it again and keeps the others (<<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` only the version being published is kept, for a directory that is a build output rather than a record of releases.
 
 |`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 §>>).
@@ -716,13 +769,14 @@ What happens when the destination already has the version:
 |===
 |Destination |Already has the version
 
-|`file`; `maven` and `nuget` to a directory; `npm` with `publish: false`
+|`maven` and `nuget` to a directory; `npm` with `publish: false`
 |Written again. With the same content the bytes are the same; with different content the version is replaced, and every subscriber whose lockfile recorded the old bytes fails its build until the change is published as a new version.
 
-|`maven` and `nuget` to a URL, `npm`, `github-release`, `gitlab-package`
-|The same documents: nothing is sent, and the log says `already published, identical`, or `with the same documents` when the copy came from another commit.
-Other documents: `publish` fails, naming the version -- a published version is never replaced, so publish the change as a new version.
-A copy that cannot be read, so there is nothing to compare, fails as one with other documents would, saying why it `cannot be compared`.
+|`file`; `maven` and `nuget` to a URL, `npm`, `github-release`, `gitlab-package`
+|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.
 `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.
@@ -731,6 +785,27 @@ Its files are packed with fixed modes, so the package is the same bytes whatever
 `nuget` reads the manifest in the package the feed returns.
 |===
 
+[#channel-problems]
+=== When a channel cannot take a version
+
+A channel is an external party, so what it does or does not do never fails `publish` on its own.
+When a channel holds the version with other documents, cannot be reached, refuses the request, or has no credential in this run, the target is not published to that channel; the run warns, naming the target, the version, the channel and the reason, and goes on with every other channel and target:
+
+[source,text]
+----
+warning: orders 2.1.0 was not published to partner: no credential in $PARTNER_TOKEN, which channels.maven.tokenEnv names. ...
+
+Published 3 artifact(s).
+Listed 2 file(s) in build/packages/packages.sha256.
+Channel problems: 1 of 4 publication(s) did not complete.
+----
+
+The last line appears only when something did not complete, and ends `Nothing was published.` when nothing did; `publish` still exits 0.
+In GitHub Actions each problem is also a `::warning` annotation on the run.
+The hand-off records every channel's outcome (<<handoff,The hand-off §>>), and publishing is idempotent, so running `publish` again completes what is missing.
+
+What fails the run is the library's to fix: a channel's settings in `apionly.yaml`, such as a `maven` channel without a `groupId`; the remote switch (<<remote-switch,Refusing remote publishing §>>); and a target changed without a new version (<<version-guard,A changed target needs a new version §>>), which is checked before anything is sent.
+
 [#remote-switch]
 === Refusing remote publishing
 
@@ -774,6 +849,7 @@ Every `publish` run lists each file its channels wrote locally, with its SHA-256
 
 | `packages.json`
 | `schemaVersion`, and `files`: for each file, its `path`, `sha256`, `target`, `version`, `channel` -- the channel's name -- and `type`, the channel's type.
+And `outcomes`: for each target and channel of the run, its `target`, `version`, `channel`, `type` and `outcome` -- `published`, `already-published`, `conflict` or `unavailable` -- with the `reason` for the last two.
 
 | `packages.sha256`
 | The same files in the format `sha256sum -c` checks.
@@ -781,7 +857,7 @@ Every `publish` run lists each file its channels wrote locally, with its SHA-256
 
 Paths are relative to the library root, with forward slashes, so `sha256sum -c build/packages/packages.sha256` checks them from there.
 A run replaces both files.
-A channel in a remote mode writes nothing locally, so it adds nothing.
+A channel in a remote mode writes nothing locally, so it adds no files; a channel that did not take the version adds none either, only its outcome.
 
 The hand-off is for a later step that publishes those files itself -- the second of <<docker-two-steps,the image's two steps §>> -- so that it ships exactly the bytes the Publisher produced, and nothing else.
 
@@ -840,7 +916,7 @@ A .NET build uses it with `dotnet nuget add source <repository>`, or a `nuget.co
 *A remote feed* is configured by its service index, the URL a feed's settings show and that ends in `index.json`, such as `https://api.nuget.org/v3/index.json`.
 The Publisher reads the service index for its `PackagePublish/2.0.0` endpoint, then pushes the package there with one `PUT`, as `multipart/form-data`, with the key from the environment variable `tokenEnv` names in the `X-NuGet-ApiKey` header.
 The `PUT` goes to that endpoint with a trailing `/`, as `dotnet nuget push` sends it; a GitLab feed recognises the upload only there.
-Before the push, the Publisher reads the feed's copy of the version back (its `PackageBaseAddress/3.0.0` resource): a package with the same documents succeeds without a push, one with other documents fails, and a copy that cannot be read, other than one the feed does not have, fails rather than being pushed over (<<idempotent,Publishing the same version again §>>).
+Before the push, the Publisher reads the feed's copy of the version back (its `PackageBaseAddress/3.0.0` resource): a package with the same documents succeeds without a push, one with other documents is not pushed over, and neither is a copy that cannot be read, other than one the feed does not have; `publish` warns about both (<<idempotent,Publishing the same version again §>>).
 The check comes first because a feed may accept a different package under a version it already has: GitLab does, by default, and serves the new one from then on.
 A feed that answers the push with 409 -- the version appeared in the meantime -- is read back and compared the same way.
 Without the variable set, the push fails before anything is sent, naming it.
@@ -906,12 +982,12 @@ link:pipelines/gitlab-ci.yml[The reference pipeline →] publishes this way, fro
 | A GitLab CI job publishing to its own project.
 |===
 
-Without either, `publish` fails before anything is sent, naming both.
+Without either, nothing is sent to GitLab, and `publish` warns, naming both (<<channel-problems,When a channel cannot take a version §>>).
 A deploy token is the least privilege for packages alone: it reaches one project's package registry and nothing else.
 
 *The same version again.*
 GitLab allows duplicate packages by default: it accepts a different file under a version it already has, and serves that one from then on.
-So the channel reads every file back before uploading any: a file with the same documents is left alone, a missing one is uploaded, and one with other documents fails `publish` (<<idempotent,Publishing the same version again §>>).
+So the channel reads every file back before uploading any: a file with the same documents is left alone, a missing one is uploaded, and one with other documents is never replaced; `publish` warns about it (<<idempotent,Publishing the same version again §>>).
 Turning *Allow duplicates* off for generic packages, in the group's *Settings › Packages and registries*, makes GitLab refuse a replaced file too, from every client; the Publisher keeps a version immutable either way.
 
 *`release: true`* also creates the tag's GitLab release, tagging `$CI_COMMIT_SHA` or, outside CI, the checkout's `HEAD`, and links both files as packages.
@@ -940,13 +1016,13 @@ channels:
 *The token* goes as a bearer token, `Authorization: Bearer <token>`, unless `tokenHeader` names another header, which then carries it as it is.
 GitLab's Maven registry takes a job token as `Job-Token`, a personal or project access token as `Private-Token`, and a deploy token as `Deploy-Token`; a GitLab Maven repository URL needs the project's numeric ID, since Gradle reads `%2F` in a path as `/`.
 
-*Every file is read back* before any is uploaded: the artifact and the manifest with the same documents are left alone, a missing file is uploaded, and other documents fail `publish`, naming the file; the POM carries no documents, and one already there is left alone.
+*Every file is read back* before any is uploaded: the artifact and the manifest with the same documents are left alone, a missing file is uploaded, and other documents are never replaced, and `publish` warns, naming the file; the POM carries no documents, and one already there is left alone.
 
 *`maven-metadata.xml`* lists an artifact's versions, which is how Gradle resolves a version range and how Renovate and Dependabot see a new version.
 Nexus, Artifactory and GitHub Packages keep it themselves; GitLab does not for files uploaded this way.
 So after a version's files, the channel adds the version to it, as `mvn deploy` does: `latest` is the highest version, `release` the highest that is not a pre-release, and `lastUpdated` the time of the commit, so the same commit writes the same file.
 It is written only when it lacks the version, or its `latest` or `release` would change.
-A repository that refuses it fails `publish`, naming `metadata: false`; the version's files are published by then, and a re-run retries only the metadata.
+A repository that refuses it is a warning naming `metadata: false`; the version's files are published by then, and a re-run retries only the metadata.
 
 [#why-registries]
 === Why npm, Maven and NuGet rather than release assets alone
@@ -1054,6 +1130,10 @@ targets:
 
 portfolio:                # absent is fine; an aggregate builds on documented defaults
   location: portfolios    # see Aggregates §
+
+versioning:               # absent is fine; see A changed target needs a new version §
+  tagFormat: "{target}-v{version}"  # the release tags the pipeline creates; the default
+  mainBranch: main        # compared with when a target has no release tag; the default
 ----
 
 `targets` is the single source of truth for what gets built.
@@ -1318,7 +1398,7 @@ A service subscribes to its own contract to implement it, and to the contracts o
 * Versions are per target, so a change to one service's fragments releases only that service's contract.
 A change to a fragment several targets share changes all of them, and `changed` names which, as <<closure,Independent versioning, and the dependency closure §>> describes.
 * Publishing every target on every run is safe: a version that is already published, with the same documents, is left alone, whichever commit it was packed from (<<idempotent,Publishing the same version again §>>).
-What fails is a changed contract whose version was not changed, which is the mistake `changed` exists to catch first.
+What fails is a changed contract whose version was not changed, which is the mistake `check` exists to catch first.
 * `landscape` is optional: a whole-landscape view for reading, generated on every build and never published, as <<aggregates,Aggregates §>> describes.
 
 [#recipe-business-partners]
@@ -2030,8 +2110,9 @@ package:
 [#docker-github-actions]
 ==== Reference pipeline: GitHub Actions
 
-Two jobs: `package` runs the image and hands the files on, `publish` checks them against the hand-off and publishes them to npm, Maven and NuGet on GitHub Packages, and to a GitHub Release, with the job's `GITHUB_TOKEN`.
-Copy it into `.github/workflows/`, then set the digest, the targets and the trigger.
+Two jobs on a tag: `package` runs the image and hands the files on, `publish` checks them against the hand-off, publishes them to npm, Maven and NuGet on GitHub Packages, and to a GitHub Release, with the job's `GITHUB_TOKEN`, and tags each target's release, `<target>-v<version>`.
+On a pull request, a third job, `check`, runs the image's `check` with no network, against the merge-base with the pull request's base branch (<<version-guard,A changed target needs a new version §>>).
+Copy it into `.github/workflows/`, then set the digest, the targets and the trigger, and `TAG_FORMAT` if `versioning.tagFormat` names the tags otherwise.
 The container-job variant above replaces its `package` job.
 
 It is exercised end to end, both variants, by a workflow in this repository that publishes to scratch packages and resolves each one with its ecosystem's own client and with the API-Only Subscriber.
@@ -2043,8 +2124,11 @@ include::pipelines/github-actions.yml[]
 
 What the two steps lose, and how the pipeline makes up for it:
 
-* *Idempotence.* A channel's remote mode leaves a version the registry has alone when it holds the same documents, and refuses it when it does not; `npm publish` or `dotnet nuget push` of an existing version fails instead.
-Each publishing step checks for the version first, compares the bytes, and publishes only what is missing, so a re-run is safe and a real conflict still fails.
+* *Idempotence.* A channel's remote mode leaves a version the registry has alone when it holds the same documents, and does not replace it when it holds others; `npm publish` or `dotnet nuget push` of an existing version fails instead.
+Each publishing step checks for the version first, compares the documents its `manifest.json` lists -- not the bytes, which differ by commit -- and publishes only what is missing, so a re-run is safe.
+A version held with other documents, or a registry that cannot be reached, is a `::warning` on the run, never a failed job, as for the Publisher's own channels (<<channel-problems,When a channel cannot take a version §>>).
+* *History.* Every job that runs the Publisher checks out the full history and the tags, `fetch-depth: 0`, which `check` and `publish` compare each target's version against.
+* *Release tags.* The last step creates each target's release tag at the commit it published, unless it exists; a tag it cannot create is a warning.
 * *Maven checksums and metadata.* The local Maven layout holds the artifact, its POM and its manifest, and no `.md5`, `.sha1` or `maven-metadata.xml`.
 `mvn deploy:deploy-file` writes those when it uploads, so the repository ends up as a remote `maven` channel would leave it, and Gradle resolves it.
 
@@ -2052,6 +2136,8 @@ Each publishing step checks for the version first, compares the bytes, and publi
 ==== Reference pipeline: GitLab CI
 
 One job, on a `v*` tag, as the GitHub Actions pipeline: the image builds, lints and publishes the targets to the project's Generic Package Registry with `gitlab-package`, and, where `apionly.yaml` configures it, to the project's Maven registry, both with the job's `CI_JOB_TOKEN`.
+In a merge request, a `check` job runs the image's `check` against the merge-base with the target branch; both jobs fetch the full history, `GIT_DEPTH: 0`, and the branch they compare with.
+`gitlab-package` with `release: true` creates each target's release, and with it the tag `<target>-v<version>` that `check` reads; without it, nothing creates that tag, and `check` compares with the merge-base alone.
 `apionly.yaml` needs no GitLab settings for it; the pipeline's header says what to add for the Maven registry.
 Copy it to `.gitlab-ci.yml`, then set the digest and the targets.
 The tag pattern keeps out the tag a GitLab release puts on the commit, `<target>-v<version>`, which would otherwise start the pipeline a second time; a library that tags its releases otherwise changes the rule, and keeps that one out.
@@ -2067,6 +2153,8 @@ include::pipelines/gitlab-ci.yml[]
 link:../docs/guides/publishing-to-gitlab/overview.adoc[Publishing to GitLab →] is the guide: tokens, a self-managed GitLab, and what consumers need.
 
 *The two-step variant*, link:pipelines/gitlab-ci-two-step.yml[`pipelines/gitlab-ci-two-step.yml` →], keeps the image sealed: `package` runs in the image, and one `publish:*` job per registry publishes to the project's package registry with that registry's own client and `CI_JOB_TOKEN`: npm, Maven and NuGet, and the archives to the generic package registry.
+As in the GitHub Actions pipeline, each compares documents and warns rather than fails, a merge request runs `check`, and a last job, `release:tags`, creates a GitLab release, and with it the tag, for each target's release; a pre-release gets none, as GitLab would make it the latest release.
+It runs on a `v*` tag, so the tags it creates do not start it again.
 It is validated against GitLab's published CI schema only; no GitLab pipeline has run it yet.
 
 [#docker-mirror-in-pipelines]
@@ -2162,7 +2250,7 @@ docker build -t api-only-publisher:local --build-arg VERSION=0.0.0-local .
 docker/smoke-test.sh api-only-publisher:local 0.0.0-local
 ----
 
-It runs every step with a read-only root and your own user, and all but the last with no network: the version, the help, the toolchain labels against what is installed and against `init`'s pins, a library with two targets built, linted and packaged to every local channel in one run, ownership, byte-identical packaging twice, the hand-off, a foreign toolchain pin failing at once, a remote channel refused while sealed, the shell mode, and a build as an arbitrary UID.
+It runs every step with a read-only root and your own user, and all but the last with no network: the version, the help, the toolchain labels against what is installed and against `init`'s pins, a library with two targets built, linted, checked -- a change without a new version refused -- and packaged to every local channel in one run, ownership, byte-identical packaging twice, the hand-off, a foreign toolchain pin failing at once, a remote channel refused while sealed, the shell mode, and a build as an arbitrary UID.
 The last step publishes with `gitlab-package` and `maven` to a GitLab stand-in, run from the same image, on a Docker network it creates with no route out (`docker network create --internal`) and removes afterwards; it checks every request went to the project's package registries with the job token, and that a re-run uploads nothing.
 
 link:../.github/workflows/api-only-publisher-image-e2e.yml[`api-only-publisher-image-e2e.yml` →] runs the GitHub Actions reference pipeline for real, by hand only.

package/package.json

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

package/src/bundle-version.js

@@ -22,8 +22,12 @@ class BundleVersionError extends Error {}
 // -- so a JVM build can read the same file with java.util.Properties. Only what a
 // version file needs: no escapes, no continuation lines.
 function readProperties(file) {
+    return parseProperties(fs.readFileSync(file, "utf8"));
+}
+
+function parseProperties(text) {
     const properties = {};
-    for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+    for (const raw of text.split(/\r?\n/)) {
         const line = raw.trim();
         if (line === "" || line.startsWith("#") || line.startsWith("!")) continue;
         const separator = line.search(/[=:]/);
@@ -77,4 +81,4 @@ function versionOf(config, target, { preRelease = null } = {}) {
     return version;
 }
 
-module.exports = { versionOf, readProperties, BundleVersionError };
+module.exports = { versionOf, readProperties, parseProperties, BundleVersionError };

package/src/channel-error.js

@@ -1,7 +1,33 @@
 "use strict";
 
-// The error every distribution channel throws, in a module of its own so that a channel
-// implemented outside channels.js can throw it without requiring channels.js back.
+// The errors every distribution channel throws, in a module of its own so that a channel
+// implemented outside channels.js can throw them without requiring channels.js back.
+//
+// A ChannelError is the library's to fix -- a channel's settings in apionly.yaml -- and
+// fails the run. Its two subclasses are about the channel, an external party, and never
+// fail the run on their own: `publish` reports them and goes on with the other channels.
+
 class ChannelError extends Error {}
 
-module.exports = { ChannelError };
+/** The channel holds this version with other documents, or with a copy that cannot be compared. */
+class ChannelConflict extends ChannelError {}
+
+/** The channel could not be reached, refused the request, or this run has no credential for it. */
+class ChannelUnavailable extends ChannelError {}
+
+/**
+ * What became of a publication that threw `error`: `conflict` or `unavailable`, or null
+ * when the error is the library's own and must fail the run. A request that never got an
+ * answer -- fetch's "fetch failed" -- and a registry client that exited with an error,
+ * such as npm or gh, are the channel being unavailable.
+ */
+function outcomeOf(error) {
+    if (error instanceof ChannelConflict) return "conflict";
+    if (error instanceof ChannelUnavailable) return "unavailable";
+    if (error instanceof ChannelError) return null;
+    if (error instanceof TypeError && error.message === "fetch failed") return "unavailable";
+    if (error && typeof error.status === "number" && "stderr" in error) return "unavailable";
+    return null;
+}
+
+module.exports = { ChannelError, ChannelConflict, ChannelUnavailable, outcomeOf };

package/src/channels.js

@@ -13,7 +13,7 @@ const path = require("path");
 const { execFileSync } = require("child_process");
 
 const { parse, compare, isPrerelease, npmDistTag } = require("./version-policy");
-const { ChannelError } = require("./channel-error");
+const { ChannelError, ChannelConflict, ChannelUnavailable } = require("./channel-error");
 const { publishNuget } = require("./nuget");
 const { publishGitlabPackage } = require("./gitlab");
 const { refuseRemote } = require("./remote");
@@ -33,26 +33,43 @@ 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.
+ * 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.
  */
 function publishFile(archive, manifest, options, log) {
     // Relative to the library root, not to wherever the CLI happened to be run.
     const dir = path.resolve(options.baseDir || ".", options.directory || "publish");
     const targetDir = path.join(dir, manifest.target, manifest.version);
+    const archiveDest = path.join(targetDir, path.basename(archive));
+    const manifestDest = path.join(targetDir, "manifest.json");
+    const files = [archiveDest, manifestDest];
+
+    const held = fs.existsSync(manifestDest) ? judgeHeld(fs.readFileSync(manifestDest), "json", manifest) : null;
+    if (held && held.verdict !== "same") {
+        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.rmSync(path.join(dir, manifest.target), { recursive: true, force: true });
+    if (options.clean === true && 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 (held && 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`);
+        return { location: archiveDest, files, alreadyPublished: true };
     }
     fs.mkdirSync(targetDir, { recursive: true });
-
-    const archiveDest = path.join(targetDir, path.basename(archive));
     fs.copyFileSync(archive, archiveDest);
-    fs.writeFileSync(path.join(targetDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    fs.writeFileSync(manifestDest, JSON.stringify(manifest, null, 2) + "\n");
 
     log(`-- Published ${manifest.target} ${manifest.version} to ${archiveDest}`);
-    return { location: archiveDest, files: [archiveDest, path.join(targetDir, "manifest.json")] };
+    return { location: archiveDest, files };
 }
 
 function pom(groupId, artifactId, version, packaging, description = `API description documents for ${artifactId}.`) {
@@ -192,7 +209,7 @@ function publishNpm(archive, manifest, options, log) {
                 log(`-- npm ${name}@${version} is already published, identical; nothing to do`);
                 return { location: name + "@" + version, distTag, name, alreadyPublished: true };
             }
-            const refused = (why) => new ChannelError(`npm already has ${name}@${version}, and it ${why}. ` +
+            const refused = (why) => new ChannelConflict(`npm already has ${name}@${version}, and it ${why}. ` +
                 "A published version is never replaced; publish the change as a new version.");
             const judged = judgeHeld(npmPublishedPackage(name, version, registry), "tgz", manifest);
             if (judged.verdict === "unreadable") throw refused(`cannot be compared: ${judged.reason}`);
@@ -225,7 +242,7 @@ function npmPublishedDist(name, version, registry) {
     } catch (error) {
         const output = `${error.stdout || ""}${error.stderr || ""}`;
         if (/E404/.test(output)) return null;
-        throw new ChannelError(`could not ask npm whether ${name}@${version} is published: ${output.trim() || error.message}`);
+        throw new ChannelUnavailable(`could not ask npm whether ${name}@${version} is published: ${output.trim() || error.message}`);
     }
 }
 
@@ -239,7 +256,7 @@ function npmPublishedPackage(name, version, registry) {
                 { encoding: "utf8", stdio: "pipe" }));
         } catch (error) {
             const output = `${error.stdout || ""}${error.stderr || ""}`.trim();
-            throw new ChannelError(`could not read ${name}@${version} back from npm to compare: ${output || error.message}`);
+            throw new ChannelUnavailable(`could not read ${name}@${version} back from npm to compare: ${output || error.message}`);
         }
         return fs.readFileSync(path.join(dir, packed[0].filename));
     } finally {
@@ -299,7 +316,7 @@ function publishGithubRelease(archive, manifest, options, log) {
         } finally {
             fs.rmSync(dir, { recursive: true, force: true });
         }
-        const refused = (why) => new ChannelError(`${repository} release ${tag} already has ${asset}, and it ${why}. ` +
+        const refused = (why) => new ChannelConflict(`${repository} release ${tag} already has ${asset}, and it ${why}. ` +
             "A published version is never replaced; publish the change as a new version.");
         const judged = judgeHeld(held, "tgz", manifest);
         if (judged.verdict === "unreadable") throw refused(`cannot be compared: ${judged.reason}`);
@@ -336,7 +353,7 @@ async function putFile(url, body, auth, contentType) {
         body,
     });
     if (!response.ok) {
-        throw new ChannelError(
+        throw new ChannelUnavailable(
             `PUT ${url} failed: ${response.status} ${response.statusText}. ` +
             (response.status === 401 || response.status === 403
                 ? "Check the token in the environment variable named by channels.maven.tokenEnv."
@@ -350,7 +367,7 @@ async function getFile(url, auth) {
     const response = await fetch(url, { headers: auth });
     if (response.status === 404) return null;
     if (!response.ok) {
-        throw new ChannelError(`GET ${url} failed: ${response.status} ${response.statusText}. ` +
+        throw new ChannelUnavailable(`GET ${url} failed: ${response.status} ${response.statusText}. ` +
             (response.status === 401 || response.status === 403
                 ? "Check the token in the environment variable named by channels.maven.tokenEnv." : ""));
     }
@@ -398,7 +415,7 @@ async function updateMetadata(url, groupId, artifactId, manifest, auth, log) {
     try {
         await putFile(url, Buffer.from(metadataXml(groupId, artifactId, listed, lastUpdated), "utf8"), auth, "application/xml");
     } catch (error) {
-        throw new ChannelError(`the repository refused maven-metadata.xml for ${groupId}:${artifactId}: ${error.message.trim()} ` +
+        throw new ChannelUnavailable(`the repository refused maven-metadata.xml for ${groupId}:${artifactId}: ${error.message.trim()} ` +
             "The version's files are published; a re-run retries only the metadata. For a repository that generates " +
             "its own maven-metadata.xml, set channels.maven.metadata: false.");
     }
@@ -409,7 +426,7 @@ function publishMavenRemote(archive, manifest, options, log) {
     const tokenEnv = options.tokenEnv || "MAVEN_TOKEN";
     const token = process.env[tokenEnv];
     if (!token) {
-        throw new ChannelError(
+        throw new ChannelUnavailable(
             `no credential in $${tokenEnv}, which channels.maven.tokenEnv names. ` +
             `Remote publication needs one; set it in the release job's environment.`
         );
@@ -443,7 +460,7 @@ function publishMavenRemote(archive, manifest, options, log) {
             { url: `${base}-manifest.json`, type: "application/json", kind: "json",
               bytes: Buffer.from(JSON.stringify(manifest, null, 2) + "\n", "utf8") },
         ];
-        const refused = (file, why) => new ChannelError(
+        const refused = (file, why) => new ChannelConflict(
             `${options.repository} already has ${options.groupId}:${artifactId}:${version}, ` +
             `and its ${file.url.split("/").pop()} ${why}. ` +
             "A published version is never replaced; publish the change as a new version.");

package/src/cli.js

@@ -17,6 +17,8 @@ const { pack, PackError } = require("./pack");
 const { changedSince, ChangedError } = require("./changed");
 const { split, SplitError } = require("./split");
 const { publish, ChannelError } = require("./channels");
+const { outcomeOf } = require("./channel-error");
+const { guard, GuardError } = require("./version-guard");
 const { refuseRemote } = require("./remote");
 const { CHANNEL_TYPES } = require("./channel-types");
 const { VersionError: PolicyError, describe } = require("./version-policy");
@@ -40,6 +42,7 @@ Usage:
   api-only-publisher targets
   api-only-publisher closure [--target <name>]...
   api-only-publisher changed --since <ref>
+  api-only-publisher check [--target <name>]... [--pre-release <ids>] [--since <ref>]
   api-only-publisher pack [--pre-release <ids>] [--target <name>]... [--out <dir>]
   api-only-publisher publish [--pre-release <ids>] [--target <name>]... [--channel <name>]... [--out <dir>]
   api-only-publisher split [--out <dir>] [--by kind|target]
@@ -63,7 +66,9 @@ Options:
                     init only: the value of that question; a flag always wins.
   --portfolio-paths <target-prefix|none>, --portfolio-location <dir>
                     config only: the value of that question; a flag always wins.
-  --since <ref>     changed only: the git ref to compare the working tree against.
+  --since <ref>     changed: the git ref to compare the working tree against.
+                    check/publish: the ref to compare a target without a release
+                    tag against, instead of the merge-base with the main branch.
   --out <dir>       pack/publish/split: where to write, instead of build.packages
                     or build.split in apionly.yaml.
   --channel <name>  publish only: repeat for several. Default: every configured channel.
@@ -76,6 +81,8 @@ Options:
 What gets built, and where each document goes, is declared in apionly.yaml.
 A published target's version is read from its version file:
 <target>.bundle.properties beside its bundle root, or the file its versionFile names.
+A target changed since its release, or since the main branch, needs a new version:
+check says which do not have one, and publish refuses them.
 `;
 
 function parseArgs(argv) {
@@ -289,6 +296,20 @@ async function runConfig(options, positional, io, log) {
     return 0;
 }
 
+/** Fails with every target the guard refused -- and, with `undecided`, every one it could not decide -- each with its reason. */
+function refuseViolations(results, { undecided = false } = {}) {
+    const listed = (verdict) => results.filter((r) => r.verdict === verdict).map((r) => `  ${r.target} ${r.version}: ${r.reason}`);
+    const violations = listed("violation");
+    const unknown = undecided ? listed("undecided") : [];
+    const parts = [];
+    if (violations.length > 0) {
+        parts.push(`${violations.length} target(s) changed without a new version:\n${violations.join("\n")}\n` +
+            "A published version is never replaced: a changed specification needs a changed version.");
+    }
+    if (unknown.length > 0) parts.push(`${unknown.length} target(s) could not be checked:\n${unknown.join("\n")}`);
+    if (parts.length > 0) throw new GuardError(parts.join("\n\n"));
+}
+
 async function main(argv, io = {}) {
     const { options, positional } = parseArgs(argv);
     const command = positional[0];
@@ -425,6 +446,17 @@ async function main(argv, io = {}) {
             log(`\n${changed.length} of ${results.length} target(s) changed since ${options.since}.`);
             return 0;
         }
+        case "check": {
+            for (const target of targets || []) {
+                if (!config.isPublished(target)) throw new ConfigError(`${target} is not published, so it has no version to check`);
+            }
+            const results = guard(config, shippedTargets(config, targets), { preRelease: options.preRelease, since: options.since });
+            for (const r of results) log(`${r.target.padEnd(18)} ${r.version.padEnd(14)} ${r.verdict === "ok" ? "ok" : r.verdict.toUpperCase()}  ${r.reason}`);
+            // check is the gate: a target it cannot decide fails it too.
+            refuseViolations(results, { undecided: true });
+            log(`\n${results.length} target(s) checked.`);
+            return 0;
+        }
         case "pack": {
             const outDir = options.out ? path.resolve(options.dir, options.out) : config.packagesDir();
             const shipped = shippedTargets(config, targets);
@@ -483,9 +515,21 @@ async function main(argv, io = {}) {
             // Every channel this run uses, before anything is read, packed or sent.
             refuseRemote([...new Set(shipped.flatMap((target) => routes.get(target)))], configured);
             const versions = versionsOf(config, shipped, options.preRelease);
+            // A changed target needs a new version: decided before anything is packed or sent.
+            try {
+                const checked = guard(config, shipped, { preRelease: options.preRelease, since: options.since });
+                refuseViolations(checked);
+                for (const r of checked.filter((c) => c.verdict === "undecided")) {
+                    log(`warning: ${r.target} ${r.version}: version not checked: ${r.reason}`);
+                }
+            } catch (error) {
+                if (!(error instanceof GuardError && error.notARepository)) throw error;
+                log(`warning: versions not checked: ${error.message}`);
+            }
             const closures = forTargets(config, undefined, shipped);
             let published = 0;
             const handoff = [];
+            const outcomes = [];
             for (const target of Object.keys(config.targets)) {
                 if (!shipped.includes(target)) continue;
                 const closure = closures.get(target);
@@ -496,18 +540,36 @@ async function main(argv, io = {}) {
                     outDir, log,
                 });
                 for (const name of routes.get(target)) {
-                    // A remote channel returns a promise; a local one does not.
-                    const result = await publish(archive, manifest, name, { ...(configured[name] || {}), baseDir: config.root }, log);
-                    for (const file of result.files || []) {
-                        handoff.push({ file, target, version: manifest.version, channel: name, type: config.channelType(name) });
+                    const entry = { target, version: manifest.version, channel: name, type: config.channelType(name) };
+                    let result;
+                    try {
+                        // A remote channel returns a promise; a local one does not.
+                        result = await publish(archive, manifest, name, { ...(configured[name] || {}), baseDir: config.root }, log);
+                    } catch (error) {
+                        // A channel is an external party: what it cannot take is reported, never fatal.
+                        const outcome = outcomeOf(error);
+                        if (!outcome) throw error;
+                        outcomes.push({ ...entry, outcome, reason: error.message });
+                        log(`warning: ${target} ${manifest.version} was not published to ${name}: ${error.message}`);
+                        if (process.env.GITHUB_ACTIONS === "true") {
+                            console.log(`::warning title=${target} ${manifest.version} not published to ${name}::${error.message.replace(/\r?\n/g, " ")}`);
+                        }
+                        continue;
                     }
+                    outcomes.push({ ...entry, outcome: result.alreadyPublished ? "already-published" : "published" });
+                    for (const file of result.files || []) handoff.push({ file, ...entry });
                     published += 1;
                 }
             }
-            // What a later step publishes byte for byte; README.adoc#handoff.
-            const { sha256: listing } = writeHandoff(config.root, outDir, handoff);
+            // What a later step publishes byte for byte, and what each channel made of it; README.adoc#handoff.
+            const { sha256: listing } = writeHandoff(config.root, outDir, handoff, outcomes);
             log(`\nPublished ${published} artifact(s).`);
             log(`Listed ${handoff.length} file(s) in ${path.relative(config.root, listing)}.`);
+            const problems = outcomes.length - published;
+            if (problems > 0) {
+                log(`Channel problems: ${problems} of ${outcomes.length} publication(s) did not complete.` +
+                    (published === 0 ? " Nothing was published." : ""));
+            }
             return 0;
         }
         case "split": {
@@ -533,7 +595,7 @@ function report(error) {
         error instanceof ClosureError || error instanceof PackError ||
         error instanceof ChangedError || error instanceof SplitError ||
         error instanceof ChannelError || error instanceof PolicyError ||
-        error instanceof BundleVersionError) {
+        error instanceof BundleVersionError || error instanceof GuardError) {
         console.error(`Error: ${error.message}`);
         process.exitCode = 1;
     } else {

package/src/config.js

@@ -21,7 +21,7 @@ const SUPPORTED_SCHEMA_VERSION = 1;
 // often a typo or a bad indent than a value nobody has used yet -- see checkKeys.
 const ROOT_KEYS = [
     "schemaVersion", "sources", "defaults", "build", "reports", "lint",
-    "distribution", "channels", "targets", "toolchain", "portfolio",
+    "distribution", "channels", "targets", "toolchain", "portfolio", "versioning",
 ];
 const SOURCES_KEYS = ["root", "openapi", "asyncapi"];
 const DEFAULTS_KEYS = ["openapi", "asyncapi", "placeholders"];
@@ -36,6 +36,7 @@ const TARGET_KEYS = ["openapi", "asyncapi", "publish", "versionFile", "channels"
 const TARGET_KIND_KEYS = ["bundle", "aggregate", "info"];
 const PORTFOLIO_KEYS = ["openapi", "security", "location"];
 const PORTFOLIO_OPENAPI_KEYS = ["paths", "operationIds", "tags"];
+const VERSIONING_KEYS = ["tagFormat", "mainBranch"];
 
 // What every portfolio setting is when apionly.yaml says nothing: safe for the
 // ordinary case (a gateway routing /<target>/** to each service), and named rather
@@ -204,6 +205,16 @@ function load(configPath) {
         );
     }
 
+    const versioning = parsed.versioning || {};
+    checkKeys(versioning, VERSIONING_KEYS, "versioning");
+    if (versioning.tagFormat !== undefined) {
+        const format = requireString(versioning.tagFormat, "versioning.tagFormat");
+        if (!format.includes("{target}") || !format.includes("{version}")) {
+            throw new ConfigError(`versioning.tagFormat must contain {target} and {version}, not ${JSON.stringify(format)}`);
+        }
+    }
+    if (versioning.mainBranch !== undefined) requireString(versioning.mainBranch, "versioning.mainBranch");
+
     const channels = parsed.channels || {};
     const types = channelTypes(channels);
 
@@ -314,6 +325,7 @@ function load(configPath) {
         distribution: parsed.distribution || null,
         channels,
         portfolio,
+        versioning,
         targets,
 
         // --- derived accessors, so callers never re-derive a path themselves ---
@@ -329,6 +341,15 @@ function load(configPath) {
         stagingDir(kind) {
             return path.join(this.stagingRoot(kind), requireString(this.sources[kind], `sources.${kind}`));
         },
+        // How a target's releases are tagged in git -- by the pipeline that publishes them,
+        // never by the Publisher, which only reads the tags -- and the branch a change is
+        // compared with when a target has no release tag yet.
+        tagFormat() {
+            return this.versioning.tagFormat || "{target}-v{version}";
+        },
+        mainBranch() {
+            return this.versioning.mainBranch || "main";
+        },
         // Where pack and publish write archives, and split its parts, unless --out says
         // otherwise; relative to this configuration, as every other path here is.
         packagesDir() {

package/src/gitlab.js

@@ -16,7 +16,7 @@ const path = require("path");
 const { execFileSync } = require("child_process");
 
 const { isPrerelease } = require("./version-policy");
-const { ChannelError } = require("./channel-error");
+const { ChannelError, ChannelConflict, ChannelUnavailable } = require("./channel-error");
 const { judgeHeld } = require("./held-documents");
 
 const GITLAB_COM = "https://gitlab.com/api/v4";
@@ -35,7 +35,7 @@ function channelSettings(options, env = process.env) {
         tokenType = "job";
     }
     if (!token) {
-        throw new ChannelError(
+        throw new ChannelUnavailable(
             `no token in $${tokenEnv}, which channels.gitlab-package.tokenEnv names, and no $CI_JOB_TOKEN. ` +
             "Set one in the release job's environment, or run in a GitLab CI job.");
     }
@@ -79,14 +79,14 @@ async function readBack(fileUrl, name, headers) {
     const response = await fetch(fileUrl, { headers });
     if (response.status === 404) return null;
     if (!response.ok) {
-        throw new ChannelError(`could not read ${name} back from ${fileUrl}: ${await answered(response)}.` +
+        throw new ChannelUnavailable(`could not read ${name} back from ${fileUrl}: ${await answered(response)}.` +
             (response.status === 401 || response.status === 403 ? TOKEN_HINT : ""));
     }
     return Buffer.from(await response.arrayBuffer());
 }
 
 function refused(name, manifest, why) {
-    return new ChannelError(`GitLab already has ${name} in ${manifest.target} ${manifest.version}, and it ${why}; ` +
+    return new ChannelConflict(`GitLab already has ${name} in ${manifest.target} ${manifest.version}, and it ${why}; ` +
         "a published version is never replaced, so publish the change as a new version");
 }
 
@@ -111,7 +111,7 @@ async function upload(file, manifest, headers) {
     // Refused, perhaps as a duplicate another run published meanwhile: compare that one.
     const now = await readBack(file.url, file.name, headers).catch(() => null);
     if (now) return { held: now, found: sameAs(now, file, manifest) };
-    throw new ChannelError(`GitLab refused ${file.name}: ${answer}.` +
+    throw new ChannelUnavailable(`GitLab refused ${file.name}: ${answer}.` +
         (response.status === 401 || response.status === 403 ? TOKEN_HINT : ""));
 }
 
@@ -137,18 +137,18 @@ async function release(settings, manifest, options, links, ref, log) {
             description: format(options.notes || options.description || DEFAULT_DESCRIPTION, manifest),
             assets: { links },
         });
-        if (!created.ok) throw new ChannelError(`GitLab refused the release ${tag}: ${await answered(created)}`);
+        if (!created.ok) throw new ChannelUnavailable(`GitLab refused the release ${tag}: ${await answered(created)}`);
         log(`-- Created the GitLab release ${tag}`);
         return;
     }
     if (!existing.ok) {
-        throw new ChannelError(`could not read the GitLab release ${tag}: ${await answered(existing)}`);
+        throw new ChannelUnavailable(`could not read the GitLab release ${tag}: ${await answered(existing)}`);
     }
     // A release's link names are unique: one already named, or already pointing here, is left as it is.
     const held = ((await existing.json()).assets || {}).links || [];
     for (const link of links.filter((l) => !held.some((h) => h.url === l.url || h.name === l.name))) {
         const added = await api(`${releases}/${encodeURIComponent(tag)}/assets/links`, settings.headers, "POST", link);
-        if (!added.ok) throw new ChannelError(`GitLab refused a link on the release ${tag}: ${await answered(added)}`);
+        if (!added.ok) throw new ChannelUnavailable(`GitLab refused a link on the release ${tag}: ${await answered(added)}`);
         log(`-- Linked ${link.name} from the GitLab release ${tag}`);
     }
 }

package/src/handoff.js

@@ -21,9 +21,11 @@ const HANDOFF_SCHEMA_VERSION = 1;
 /**
  * Writes packages.json and packages.sha256 into `outDir`, replacing any from an
  * earlier run, listing `entries` -- `{ file, target, version, channel }`, `file`
- * absolute -- sorted by path.
+ * absolute -- sorted by path. packages.json also lists `outcomes`, what each channel
+ * made of each target: `published`, `already-published`, or a channel problem --
+ * `conflict` or `unavailable`, with its reason -- that did not fail the run.
  */
-function writeHandoff(root, outDir, entries) {
+function writeHandoff(root, outDir, entries, outcomes = []) {
     const files = entries
         .map(({ file, target, version, channel, type = channel }) => ({
             path: path.relative(root, file).split(path.sep).join("/"),
@@ -35,7 +37,7 @@ function writeHandoff(root, outDir, entries) {
     fs.mkdirSync(outDir, { recursive: true });
     const json = path.join(outDir, HANDOFF_JSON);
     const sha256 = path.join(outDir, HANDOFF_SHA256);
-    fs.writeFileSync(json, JSON.stringify({ schemaVersion: HANDOFF_SCHEMA_VERSION, files }, null, 2) + "\n");
+    fs.writeFileSync(json, JSON.stringify({ schemaVersion: HANDOFF_SCHEMA_VERSION, files, outcomes }, null, 2) + "\n");
     fs.writeFileSync(sha256, files.map((f) => `${f.sha256}  ${f.path}\n`).join(""));
     return { json, sha256 };
 }

package/src/nuget.js

@@ -24,7 +24,7 @@ const { execFileSync } = require("child_process");
 
 const { parse, isPrerelease } = require("./version-policy");
 const { zip } = require("./zip");
-const { ChannelError } = require("./channel-error");
+const { ChannelError, ChannelConflict, ChannelUnavailable } = require("./channel-error");
 const { judgeHeld } = require("./held-documents");
 
 /** Where the documents and manifest.json sit inside the package. */
@@ -174,13 +174,13 @@ function publishLocal(archive, manifest, options, id, log) {
 async function feedResources(index) {
     const response = await fetch(index);
     if (!response.ok) {
-        throw new ChannelError(`could not read the NuGet service index at ${index}: ${response.status} ${response.statusText}`);
+        throw new ChannelUnavailable(`could not read the NuGet service index at ${index}: ${response.status} ${response.statusText}`);
     }
     const resources = (await response.json()).resources || [];
     const find = (type) => (resources.find((r) => r["@type"] === type) || {})["@id"] || null;
     const publish = find(PUBLISH_RESOURCE);
     if (!publish) {
-        throw new ChannelError(`the NuGet feed at ${index} has no ${PUBLISH_RESOURCE} resource, so it cannot be pushed to`);
+        throw new ChannelUnavailable(`the NuGet feed at ${index} has no ${PUBLISH_RESOURCE} resource, so it cannot be pushed to`);
     }
     return { publish, content: find(CONTENT_RESOURCE) };
 }
@@ -207,7 +207,7 @@ async function readableCopy(content, id, version, key) {
  */
 function judge(held, bytes, id, manifest) {
     if (held.equals(bytes)) return "identical";
-    const refused = (why) => new ChannelError(`the NuGet feed already has ${id} ${manifest.version}, and it ${why}; ` +
+    const refused = (why) => new ChannelConflict(`the NuGet feed already has ${id} ${manifest.version}, and it ${why}; ` +
         "a published version is never replaced, so publish the change as a new version");
     const judged = judgeHeld(held, "zip", manifest);
     if (judged.verdict === "unreadable") throw refused(`cannot be compared: ${judged.reason}`);
@@ -225,7 +225,7 @@ async function publishedCopy(content, id, version, key) {
     const response = await fetch(url, { headers: { "X-NuGet-ApiKey": key } });
     if (response.status === 404) return null;
     if (!response.ok) {
-        throw new ChannelError(`could not read ${id} ${version} back from ${url}: ${response.status} ${response.statusText}`.trim() +
+        throw new ChannelUnavailable(`could not read ${id} ${version} back from ${url}: ${response.status} ${response.statusText}`.trim() +
             (response.status === 401 || response.status === 403
                 ? ". Check the key in the environment variable named by channels.nuget.tokenEnv." : ""));
     }
@@ -243,7 +243,7 @@ function publishRemote(archive, manifest, options, id, log) {
     const tokenEnv = options.tokenEnv || "NUGET_API_KEY";
     const key = process.env[tokenEnv];
     if (!key) {
-        throw new ChannelError(
+        throw new ChannelUnavailable(
             `no API key in $${tokenEnv}, which channels.nuget.tokenEnv names. ` +
             "Remote publication needs one; set it in the release job's environment.");
     }
@@ -290,11 +290,11 @@ function publishRemote(archive, manifest, options, id, log) {
             // Idempotent: the same documents again are success, others are not.
             const held = await readableCopy(content, id, manifest.version, key);
             if (held) return already(judge(held, bytes, id, manifest));
-            throw new ChannelError(`the NuGet feed already has ${id} ${manifest.version}, and it cannot be read back to compare; ` +
+            throw new ChannelConflict(`the NuGet feed already has ${id} ${manifest.version}, and it cannot be read back to compare; ` +
                 "a published version is never replaced, so publish the change as a new version");
         }
         if (!response.ok) {
-            throw new ChannelError(`the NuGet feed refused the package: ${response.status} ${response.statusText}. ` +
+            throw new ChannelUnavailable(`the NuGet feed refused the package: ${response.status} ${response.statusText}. ` +
                 (response.status === 401 || response.status === 403
                     ? "Check the key in the environment variable named by channels.nuget.tokenEnv." : ""));
         }

package/src/version-guard.js

@@ -0,0 +1,158 @@
+"use strict";
+
+// A changed specification comes with a changed version.
+//
+// A subscriber locks a version's documents by their hashes, so a version published again
+// with other documents breaks every build that already locked it. The registries refuse
+// such a version, but only at publish time, only on remote channels, and only when they
+// already hold it; this guard decides it from git alone, before anything is packed, so a
+// pull request can fail on it.
+//
+// What a version was released from is known from the target's release tags, which the
+// pipeline creates after it publishes (`versioning.tagFormat`); the Publisher only reads
+// them. A target with no release tag yet is compared with the merge-base with the main
+// branch, or with the ref `--since` names.
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const { prepare } = require("./pipeline");
+const { changedSince } = require("./changed");
+const { versionOf, parseProperties } = require("./bundle-version");
+const { compare, isPrerelease, SEMVER } = require("./version-policy");
+
+class GuardError extends Error {}
+
+function git(args, cwd) {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function tryGit(args, cwd) {
+    try {
+        return git(args, cwd);
+    } catch {
+        return null;
+    }
+}
+
+function escape(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** The target's release tags, by version: every tag `tagFormat` gives for it with a semver version. */
+function releaseTags(config, target, repoRoot) {
+    const [before, after] = config.tagFormat().replace(/\{target\}/g, target).split("{version}");
+    const pattern = new RegExp(`^${escape(before)}(.+)${escape(after)}$`);
+    const tags = new Map();
+    for (const tag of git(["tag", "--list"], repoRoot).split("\n")) {
+        const match = pattern.exec(tag);
+        if (match && SEMVER.test(match[1])) tags.set(match[1], tag);
+    }
+    return tags;
+}
+
+/**
+ * The ref a target without release tags is compared with, and how to name it; or, when
+ * there is no merge-base -- a shallow checkout, or no main branch -- why not.
+ */
+function fallbackBaseline(config, repoRoot, since) {
+    if (since) {
+        const commit = tryGit(["rev-parse", "--verify", "--quiet", `${since}^{commit}`], repoRoot);
+        if (!commit) throw new GuardError(`--since ${since} is not a commit in this repository`);
+        return { ref: commit, label: `${since} (${commit.slice(0, 12)})` };
+    }
+    const branch = config.mainBranch();
+    for (const candidate of [`origin/${branch}`, branch]) {
+        if (!tryGit(["rev-parse", "--verify", "--quiet", `${candidate}^{commit}`], repoRoot)) continue;
+        const base = tryGit(["merge-base", "HEAD", candidate], repoRoot);
+        if (base) return { ref: base, label: `the merge-base with ${branch} (${base.slice(0, 12)})` };
+    }
+    return { missing: `no merge-base with ${branch}, the branch versioning.mainBranch names, to compare a target without a release tag with. ` +
+        "In CI, fetch the full history and the branch (actions/checkout with fetch-depth: 0, or GIT_DEPTH: 0 on GitLab), " +
+        "or name the ref to compare with: --since <ref>." };
+}
+
+/** The version a target's version file -- `rel`, from the repository root -- declared at `ref`, or null when it was not there. */
+function versionAt(ref, rel, repoRoot) {
+    const text = tryGit(["show", `${ref}:${rel}`], repoRoot);
+    return text === null ? null : parseProperties(text).version || null;
+}
+
+/**
+ * Whether each target's version may be published: a version released before, from other
+ * specifications, may not; nor one lower than what came before it.
+ *
+ * @param {object} config a loaded configuration
+ * @param {string[]} targets the targets to judge; each needs a version file
+ * @param {{preRelease?: string|null, since?: string|null}} options
+ * A target the tags do not decide, with no merge-base to compare with, is `undecided`.
+ *
+ * @returns {Array<{target: string, version: string, verdict: "ok"|"violation"|"undecided", reason: string}>}
+ */
+function guard(config, targets, { preRelease = null, since = null } = {}) {
+    const top = tryGit(["rev-parse", "--show-toplevel"], config.root);
+    if (top === null) {
+        const error = new GuardError(`${config.root} is not in a git repository, so whether a changed target has a ` +
+            "changed version cannot be decided: the guard reads release tags and history from git");
+        error.notARepository = true;
+        throw error;
+    }
+    // Real paths on both sides: git answers with the canonical one, and a checkout reached
+    // through a symlink -- /var on macOS -- would otherwise never match.
+    const repoRoot = fs.realpathSync(top);
+    prepare(config);
+
+    const changes = new Map();
+    const changedSinceRef = (ref, target) => {
+        if (!changes.has(ref)) {
+            changes.set(ref, new Map(changedSince(config, ref).map((r) => [r.target, r.changed])));
+        }
+        return changes.get(ref).get(target) === true;
+    };
+    let fallback = null;
+
+    return targets.map((target) => {
+        const declared = versionOf(config, target);
+        const version = versionOf(config, target, { preRelease });
+        const file = path.relative(repoRoot, fs.realpathSync(config.versionFile(target))).split(path.sep).join("/");
+        const ok = (reason) => ({ target, version, verdict: "ok", reason });
+        const violation = (reason) => ({ target, version, verdict: "violation", reason });
+        const tags = releaseTags(config, target, repoRoot);
+
+        // Released before: exact, whatever else is true.
+        if (tags.has(version)) {
+            const tag = tags.get(version);
+            return changedSinceRef(tag, target)
+                ? violation(`${version} was released as ${tag}, and ${target} has changed since: raise the version in ${file}`)
+                : ok(`unchanged since its release tag ${tag}`);
+        }
+        if (preRelease && tags.has(declared)) {
+            return violation(`${version} is a pre-release of ${declared}, which is already released as ${tags.get(declared)}: ` +
+                `it would sort before the release; declare the next version in ${file}`);
+        }
+        const releases = [...tags.keys()].filter((v) => !isPrerelease(v)).sort(compare);
+        if (releases.length > 0) {
+            const latest = releases[releases.length - 1];
+            return compare(declared, latest) < 0
+                ? violation(`${declared} is lower than its latest release, ${latest} (${tags.get(latest)}): raise the version in ${file}`)
+                : ok(`${declared} is above its latest release, ${latest}`);
+        }
+
+        // Never released, as far as the tags tell: the merge-base, or --since, decides.
+        fallback = fallback || fallbackBaseline(config, repoRoot, since);
+        if (fallback.missing) return { target, version, verdict: "undecided", reason: fallback.missing };
+        const before = versionAt(fallback.ref, file, repoRoot);
+        if (before === null) return ok(`new: no version file at ${fallback.label}`);
+        if (compare(declared, before) < 0) {
+            return violation(`${declared} is lower than ${before} at ${fallback.label}: raise the version in ${file}`);
+        }
+        if (!changedSinceRef(fallback.ref, target)) return ok(`unchanged since ${fallback.label}`);
+        if (compare(declared, before) > 0) return ok(`${before} -> ${declared} since ${fallback.label}`);
+        if (preRelease) return ok(`pre-release ${version}: its identifiers make it a new version`);
+        return violation(`${target} changed since ${fallback.label}, but its version is still ${declared}: ` +
+            `raise it in ${file}`);
+    });
+}
+
+module.exports = { guard, releaseTags, GuardError };