@arc-e-tect/api-only-publisher 0.18.4 → 0.18.5

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.4
+:api-only-publisher-version: 0.18.5
 
 [NOTE]
 .About this documentation
@@ -23,6 +23,8 @@ image:https://img.shields.io/github/v/release/Arc-E-Tect/SoftwareEngineeringDone
 image:https://img.shields.io/badge/Node-22.14%2B-339933?logo=node.js[Node 22.14+,link=https://nodejs.org]
 image:https://img.shields.io/badge/License-MIT-blue[MIT,link=LICENSE]
 
+Current release: *{api-only-publisher-version}*, as link:CHANGELOG.md[the changelog →] records it.
+
 [NOTE]
 .Where the links in this document go
 ====
@@ -385,6 +387,19 @@ Only `build` does this; `lint` does not, and no report file is written.
 [#versions]
 == Versions
 
+[WARNING]
+.You maintain the version files yourself
+====
+The Publisher never writes a version file.
+It does not raise a version when it builds, packs or publishes, and it does not work one out from commit messages the way semantic-release does.
+The version it publishes is whatever the target's version file says.
+It only writes that version into the built document's `info.version`.
+
+So when you change a target's fragments, raise the version in that target's version file yourself, in the same commit.
+The Publisher checks that you did: `check` and `publish` refuse a target that changed without a new version (<<version-guard,A changed target needs a new version §>>).
+A `pre-push` git hook runs the same check on your own machine, before anything leaves it (<<version-hook,Checking versions before every push §>>).
+====
+
 Every published target has a version of its own, and it is kept in the library, beside the fragments it describes.
 
 .specs/openapi/bundles/orders.bundle.properties
@@ -434,34 +449,131 @@ Both read only git: the target's release tags, its history, and the working tree
 |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.
+|Compared with the merge-base with the base 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.
+The base branch is `versioning.baseBranch`, `main` by default; its remote-tracking branch, `origin/<base branch>`, is preferred, as that is what a CI checkout has.
+Set it to the branch that holds the release you validate against, which need not be `main`.
+A library whose default branch is `pre-prod` cuts a release there and deploys it to staging, and later merges `pre-prod` into `main` only to record that the production deployment was approved.
+For that library the last reviewed versions live on `pre-prod`, so that is the branch to compare with:
+
+[source,yaml]
+----
+versioning:
+  baseBranch: pre-prod   # compared with origin/pre-prod, or pre-prod when there is no remote copy
+----
+
 
 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.
+* Its version file need not change: `--pre-release rc.2` already makes a new version, so a target changed since the base 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.
+A target with no release tag, in a checkout that has no merge-base with the base branch -- a shallow clone, or no such 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.
+Without release tags, the check on the base branch itself compares the base branch with itself, so it is in the pull request that it catches a missing bump; the tags are what make it exact everywhere.
+
+[#version-hook]
+=== Checking versions before every push
 
-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:
+The pipeline catches a missing version bump, but only after you have pushed.
+A git hook catches it before then.
+A hook is a script that git runs on your machine at a fixed moment.
+A `pre-push` hook runs when you type `git push`, and if it fails, git sends nothing.
+The steps below set one up so that it runs `check`.
+They need no hook manager and nothing outside git and the Publisher.
 
+. *Create the hook* as `.githooks/pre-push` in the repository, the one that holds `apionly.yaml`.
+The file has no extension.
+Pick the variant for the way the library runs the Publisher (<<installation,Installation §>>):
++
+.`.githooks/pre-push`, with the Publisher in `package.json`
 [source,sh]
 ----
 #!/bin/sh
+# Refuse the push when a target changed without a new version in its version file.
+# The branch versioning.baseBranch names in apionly.yaml: main unless it says otherwise.
+BASE_BRANCH=main
+# The check compares with origin/$BASE_BRANCH and the release tags, so bring them up to date first.
+git fetch --quiet --tags origin "$BASE_BRANCH" || echo "pre-push: could not fetch origin/$BASE_BRANCH; checking against what is here" >&2
 exec npx --no-install api-only-publisher check
 ----
++
+.`.githooks/pre-push`, with the Docker image
+[source,sh,subs="attributes+"]
+----
+#!/bin/sh
+# Refuse the push when a target changed without a new version in its version file.
+# The branch versioning.baseBranch names in apionly.yaml: main unless it says otherwise.
+BASE_BRANCH=main
+# The check compares with origin/$BASE_BRANCH and the release tags, so bring them up to date first.
+git fetch --quiet --tags origin "$BASE_BRANCH" || echo "pre-push: could not fetch origin/$BASE_BRANCH; checking against what is here" >&2
+exec docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" \
+  arcetect/api-only-publisher:{api-only-publisher-version} check
+----
++
+Set `BASE_BRANCH` to the branch `versioning.baseBranch` names, `pre-prod` for the library above.
+The hook only fetches that branch; `check` reads which branch to compare with from `apionly.yaml`, so the two must name the same one.
++
+Git runs a hook from the top of the repository.
+When `apionly.yaml` is in a subdirectory, add `-C <that directory>` after `check`.
+
+. *Make it executable*, and commit it, so that everyone who clones the repository gets it:
++
+[source,sh]
+----
+chmod +x .githooks/pre-push
+git add .githooks/pre-push
+git commit -m "chore: check API versions before every push"
+----
++
+On Windows, `chmod` has no effect.
+Use `git update-index --chmod=+x .githooks/pre-push` before the commit instead.
+Git for Windows runs the hook with its own `sh`, so the script works there as it is.
+
+. *Tell git to use the directory.*
+Git only looks in `.git/hooks` by default, and that directory is never committed.
+Every clone has to run this once:
++
+[source,sh]
+----
+git config core.hooksPath .githooks
+----
++
+Put this line in the library's own README, or in its setup script, so nobody has to remember it.
+A hook manager such as husky or lefthook does this step for you when its dependencies are installed.
+If you already use one, call the same `check` command from its `pre-push` entry instead.
+
+. *Try it.*
+Change a fragment of a published target and commit it without changing its version file.
+`git push` should now stop, and the message names the target and its version file:
++
+[source,console]
+----
+$ git push
+orders             2.1.0          VIOLATION  orders changed since the merge-base with main (3f2a91c0d4e1), but its version is still 2.1.0: raise it in specs/openapi/bundles/orders.bundle.properties
+Error: 1 target(s) changed without a new version:
+  orders 2.1.0: orders changed since the merge-base with main (3f2a91c0d4e1), but its version is still 2.1.0: raise it in specs/openapi/bundles/orders.bundle.properties
+A published version is never replaced: a changed specification needs a changed version.
+error: failed to push some refs to 'origin'
+----
++
+Raise the version, commit, and push again.
+
+Some things to know about the hook:
+
+* `check` looks at the working tree, and that includes changes you have not committed yet.
+Commit or stash them before you push, so it checks what you are actually pushing.
+* It needs neither credentials nor a network beyond the `git fetch`, and it builds nothing, so it takes seconds.
+* `git push --no-verify` skips the hook.
+The pipeline still runs the same check, so skipping it only means you find out later.
 
 [#closure]
 == Independent versioning, and the dependency closure
@@ -952,7 +1064,7 @@ It publishes each target to a GitLab project's Generic Package Registry, on gitl
 [source,yaml]
 ----
 channels:
-  gitlab-package:                          # in a GitLab CI job, nothing below is needed
+  gitlab-package:                          # in a GitLab CI job, nothing below is needed, unless it inherits a GITLAB_TOKEN
     # url: https://gitlab.example.com/api/v4  # default: $CI_API_V4_URL, else https://gitlab.com/api/v4
     # project: group/subgroup/api-library     # an ID or a path; default: $CI_PROJECT_ID
     # tokenEnv: GITLAB_TOKEN                  # default; when unset, $CI_JOB_TOKEN is used
@@ -985,6 +1097,10 @@ link:pipelines/gitlab-ci.yml[The reference pipeline →] publishes this way, fro
 |===
 
 Without either, nothing is sent to GitLab, and `publish` warns, naming both (<<channel-problems,When a channel cannot take a version §>>).
+
+*A `GITLAB_TOKEN` the job inherits wins over `CI_JOB_TOKEN`*, whether it comes from the project, a parent group or the instance, and is sent as a personal or project access token.
+When it is expired or lacks the `api` scope, the read-back fails with `401 Unauthorized` or `403 insufficient_scope`, although the job token itself would have worked.
+Set `tokenEnv: CI_JOB_TOKEN` and `tokenType: job` on the channel to use the job token regardless (link:../docs/guides/publishing-to-gitlab/overview.adoc#token-shadowed[When the job fails with 401 or 403 →]).
 A deploy token is the least privilege for packages alone: it reaches one project's package registry and nothing else.
 
 *The same version again.*
@@ -1135,7 +1251,7 @@ portfolio:                # absent is fine; an aggregate builds on documented de
 
 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
+  baseBranch: main        # compared with when a target has no release tag; the default
 ----
 
 `targets` is the single source of truth for what gets built.

package/package.json

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

package/src/config.js

@@ -36,7 +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"];
+const VERSIONING_KEYS = ["tagFormat", "baseBranch"];
 
 // 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
@@ -206,6 +206,9 @@ function load(configPath) {
     }
 
     const versioning = parsed.versioning || {};
+    if (versioning && typeof versioning === "object" && "mainBranch" in versioning) {
+        throw new ConfigError("versioning.mainBranch was renamed to versioning.baseBranch: rename the key, its value stays the same");
+    }
     checkKeys(versioning, VERSIONING_KEYS, "versioning");
     if (versioning.tagFormat !== undefined) {
         const format = requireString(versioning.tagFormat, "versioning.tagFormat");
@@ -213,7 +216,7 @@ function load(configPath) {
             throw new ConfigError(`versioning.tagFormat must contain {target} and {version}, not ${JSON.stringify(format)}`);
         }
     }
-    if (versioning.mainBranch !== undefined) requireString(versioning.mainBranch, "versioning.mainBranch");
+    if (versioning.baseBranch !== undefined) requireString(versioning.baseBranch, "versioning.baseBranch");
 
     const channels = parsed.channels || {};
     const types = channelTypes(channels);
@@ -347,8 +350,8 @@ function load(configPath) {
         tagFormat() {
             return this.versioning.tagFormat || "{target}-v{version}";
         },
-        mainBranch() {
-            return this.versioning.mainBranch || "main";
+        baseBranch() {
+            return this.versioning.baseBranch || "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.

package/src/version-guard.js

@@ -62,13 +62,13 @@ function fallbackBaseline(config, repoRoot, since) {
         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();
+    const branch = config.baseBranch();
     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. ` +
+    return { missing: `no merge-base with ${branch}, the branch versioning.baseBranch 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>." };
 }