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

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.5
+:api-only-publisher-version: 0.18.7
 
 [NOTE]
 .About this documentation
@@ -293,6 +293,10 @@ The name becomes file names, a properties key, a Maven artifactId, a git tag and
 |Broker host
 |`--broker-host <host[:port]>`
 |`kafka:9092`. Asked only for a library with AsyncAPI.
+
+|Run the Publisher with
+|`--runner <npm\|docker>`
+|`npm`. How the pre-push hook runs `check`: `npx`, from the library's own `package.json`, or the Docker image of this Publisher's version (<<installation,Installation §>>).
 |===
 
 A flag always wins: its question is not asked, and an invalid value, or a flag for a kind the library does not hold, stops `init` before it writes anything.
@@ -305,6 +309,13 @@ What each kind of library gets::
 * *Both*: both trees, one target building both documents, and one schema they share: `specs/openapi/components/common/schemas/ExampleIdV1.yaml`, which the HTTP response and the event payload both refer to.
 That is the library's convention in miniature -- a definition used by both protocols is one fragment -- and why the whole source root is staged together (<<what-build-does,What `build` does §>>).
 
+What every library gets as well::
+A `pre-push` git hook, `.githooks/pre-push` at the top of the repository, that runs `check` before every push (<<version-hook,Checking versions before every push §>>).
+Inside a git repository, `init` also points this clone's git at it, with `git config core.hooksPath .githooks`, unless `core.hooksPath` is already set.
+When the repository's hooks are run by a hook manager -- a `.husky` directory, a `lefthook.yml`, a `.pre-commit-config.yaml`, or a `core.hooksPath` that points somewhere else -- `init` writes no hook, which would compete with it, and prints the command to add to the manager's `pre-push` entry instead.
+A `core.hooksPath` in your global git configuration counts as well, deliberately: setting one for this repository would quietly switch off the hooks you run everywhere else, such as a company-wide secret scanner.
+Add the command to those hooks, or set `core.hooksPath` for this repository yourself if that is what you want.
+
 What it reports::
 `init` never overwrites what is there unless told to, and says for every file what it did:
 +
@@ -316,6 +327,8 @@ The message names every slot added -- see <<init-additive,Adding a kind to an ex
 `differs`:: The file was there, and does not match: where the library has diverged from the scaffold, usually on purpose.
 It is left alone.
 `overwrote`:: The file differed, and `--force` replaced it.
+`skipped`:: The pre-push hook was not written, because a hook manager runs the repository's hooks.
+`configured`:: `core.hooksPath` was not set, and now points at `.githooks`.
 +
 At a terminal, `--force` first lists the files that still differ -- after any additive update apionly.yaml already got -- and asks once whether to overwrite them; without a terminal, or with `--yes`, it overwrites them without asking.
 
@@ -487,8 +500,15 @@ 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.
+The hook below runs `check`.
+It needs no hook manager and nothing outside git and the Publisher.
+
+`init` writes it, as `.githooks/pre-push` at the top of the repository (<<init,Scaffolding a library §>>).
+`--runner` picks the variant: `npm`, the default, or `docker`.
+When the library is in a subdirectory, the hook goes to the top all the same, because that is where git runs hooks from, and runs `check` in the library's directory.
+A second library in the same repository finds the hook there already and reports it as `differs`: add its `check` to the hook by hand.
+
+For a library that already exists, write the hook yourself:
 
 . *Create the hook* as `.githooks/pre-push` in the repository, the one that holds `apionly.yaml`.
 The file has no extension.
@@ -498,11 +518,9 @@ Pick the variant for the way the library runs the Publisher (<<installation,Inst
 [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
+# Refuses the push when a published target changed without a new version in its version file.
+# check compares with origin's base branch and the release tags: bring them up to date.
+git fetch --quiet --tags origin || echo "pre-push: could not fetch origin; checking against what is here" >&2
 exec npx --no-install api-only-publisher check
 ----
 +
@@ -510,20 +528,18 @@ exec npx --no-install api-only-publisher check
 [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
+# Refuses the push when a published target changed without a new version in its version file.
+# check compares with origin's base branch and the release tags: bring them up to date.
+git fetch --quiet --tags origin || echo "pre-push: could not fetch origin; 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.
+The hook fetches every branch of `origin`, so it never needs to know which one `versioning.baseBranch` names, and changing that setting needs no change to the hook.
+It fetches on your machine, not in the container: the image has no ssh client and none of your credentials.
 +
 Git runs a hook from the top of the repository.
-When `apionly.yaml` is in a subdirectory, add `-C <that directory>` after `check`.
+When `apionly.yaml` is in a subdirectory, add `cd <that directory> || exit 1` before the `npx` line, or `-C <that directory>` after `check` in the Docker variant, which needs the whole repository mounted to read its history.
 
 . *Make it executable*, and commit it, so that everyone who clones the repository gets it:
 +
@@ -534,13 +550,13 @@ git add .githooks/pre-push
 git commit -m "chore: check API versions before every push"
 ----
 +
-On Windows, `chmod` has no effect.
+On Windows, `chmod` has no effect, and neither does the executable bit `init` sets.
 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:
+Every clone has to run this once; `init` runs it for the clone it scaffolds in:
 +
 [source,sh]
 ----
@@ -549,7 +565,7 @@ 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.
+If you already use one, call the same `check` command from its `pre-push` entry instead; `init` prints that command when it finds one.
 
 . *Try it.*
 Change a fragment of a published target and commit it without changing its version file.
@@ -569,9 +585,10 @@ Raise the version, commit, and push again.
 
 Some things to know about the hook:
 
+* It checks every published target, not only those the pushed commits touch: a target that did not change passes, and the whole check takes seconds.
 * `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.
+* It needs neither credentials nor a network beyond the `git fetch`, and it builds nothing.
 * `git push --no-verify` skips the hook.
 The pipeline still runs the same check, so skipping it only means you find out later.
 

package/package.json

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

package/src/cli.js

@@ -9,6 +9,7 @@ const { loadFrom, ConfigError } = require("./config");
 const { build, prepare, BuildError } = require("./pipeline");
 const { init, scaffold, plan } = require("./init");
 const { resolveValues } = require("./init-questions");
+const { planHook, setHooksPath, HOOKS_DIR } = require("./init-hook");
 const { resolvePortfolioValues, writePortfolioSection } = require("./config-command");
 const { PlaceholderError } = require("./placeholders");
 const { VersionError } = require("./version");
@@ -34,7 +35,7 @@ Usage:
                           [--title <text>] [--contract-version <version>]
                           [--contact-name <text>] [--contact-url <url>]
                           [--license <spdx-id>] [--license-url <url>]
-                          [--server-url <url>] [--broker-host <host[:port]>]
+                          [--server-url <url>] [--broker-host <host[:port]>] [--runner <npm|docker>]
   api-only-publisher config [section] [--yes] [--portfolio-paths <target-prefix|none>]
                             [--portfolio-location <dir>]
   api-only-publisher build [--target <name>]... [--pre-release <ids>] [--openapi|--asyncapi]
@@ -64,6 +65,9 @@ Options:
   --title, --contract-version, --contact-name, --contact-url, --license,
   --license-url, --server-url, --broker-host
                     init only: the value of that question; a flag always wins.
+  --runner <npm|docker>
+                    init only: how the pre-push hook init writes runs check.
+                    Default: npm.
   --portfolio-paths <target-prefix|none>, --portfolio-location <dir>
                     config only: the value of that question; a flag always wins.
   --since <ref>     changed: the git ref to compare the working tree against.
@@ -94,7 +98,7 @@ function parseArgs(argv) {
     const INIT_VALUES = {
         "--title": "title", "--contract-version": "contractVersion", "--contact-name": "contactName",
         "--contact-url": "contactUrl", "--license": "license", "--license-url": "licenseUrl",
-        "--server-url": "serverUrl", "--broker-host": "brokerHost",
+        "--server-url": "serverUrl", "--broker-host": "brokerHost", "--runner": "runner",
     };
     const CONFIG_VALUES = { "--portfolio-paths": "paths", "--portfolio-location": "location" };
     const positional = [];
@@ -232,26 +236,52 @@ async function runInit(options, positional, io, log) {
         }
 
         log(`Scaffolding a specification library in ${dir}`);
+        const hook = planHook(dir, values.runner, require("../package.json").version);
+        const scaffolded = { ...scaffold(values), ...hook.files };
         let force = options.force;
         if (terminal && force) {
             // Asked, --force means "after showing me": it overwrites what differs only
             // once the list has been seen and agreed to.
-            const differing = plan(dir, scaffold(values), values, portfolio).filter((entry) => entry.status === "differs");
+            const differing = plan(dir, scaffolded, values, portfolio).filter((entry) => entry.status === "differs");
             if (differing.length > 0) {
                 output.write(`These files differ from the scaffold:\n${differing.map((d) => `  ${d.rel}\n`).join("")}`);
                 const answer = await terminal.question(`Overwrite these ${differing.length} file(s)? [y/N] `);
                 force = /^y(es)?$/i.test(answer.trim());
             }
         }
-        init(dir, { values, force, log, portfolio });
+        init(dir, { values, force, log, portfolio, extra: hook.files, executable: hook.executable });
         if (portfolioStatusThisRun === "present") log("  present    portfolio (already configured; init never changes it)");
+        const next = reportHook(hook, log);
         log(`\nNext: api-only-publisher build -C ${dir}`);
+        for (const line of next) log(line);
     } finally {
         if (terminal) terminal.close();
     }
     return 0;
 }
 
+/**
+ * Reports what init did about the pre-push hook beyond writing its file, and does
+ * the one thing left: pointing this clone's git at .githooks, when nothing else
+ * already decides where its hooks are. README.adoc#version-hook.
+ *
+ * @returns {string[]} the lines to print after "Next:", for what init could not do itself
+ */
+function reportHook(hook, log) {
+    if (hook.manager) {
+        log(`  skipped    ${HOOKS_DIR}/pre-push (${hook.manager} runs this repository's hooks)`);
+        return [`Add to its pre-push hook: ${hook.command}`];
+    }
+    if (!hook.repository) {
+        return [`Once this is a git repository, run the pre-push hook: git config core.hooksPath ${HOOKS_DIR}`];
+    }
+    if (hook.hooksPath === "unset") {
+        setHooksPath(hook.repository);
+        log(`  configured core.hooksPath=${HOOKS_DIR} (this clone runs the pre-push hook)`);
+    }
+    return [`Every other clone runs the pre-push hook after: git config core.hooksPath ${HOOKS_DIR}`];
+}
+
 const CONFIGURABLE_SECTIONS = ["portfolio"];
 
 /**

package/src/init-hook.js

@@ -0,0 +1,135 @@
+"use strict";
+
+// The pre-push hook `init` offers: `check` on the developer's own machine, before a
+// target that changed without a new version leaves it. README.adoc#version-hook.
+//
+// Unlike the rest of the scaffold, where the hook goes and whether it is written at
+// all depends on the repository the library is in, so this is where git is read:
+//
+// - The hook lives in .githooks/ at the top of the repository, committed, because
+//   .git/hooks never is; core.hooksPath points git at it, once per clone.
+// - A repository whose hooks a manager runs -- husky, lefthook, pre-commit, or a
+//   core.hooksPath that points elsewhere -- gets no hook file, which would compete
+//   with the manager, only the command to add to its pre-push entry.
+// - The hook fetches on the host, never inside the Docker image: the image has no
+//   ssh client and no credentials, and origin is what check compares with.
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const HOOKS_DIR = ".githooks";
+const IMAGE = "arcetect/api-only-publisher";
+
+function tryGit(args, cwd) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    } catch {
+        return null;
+    }
+}
+
+/** The closest directory at or above `dir` that exists: init may be scaffolding one that does not yet. */
+function existingAncestor(dir) {
+    let current = dir;
+    while (!fs.existsSync(current)) current = path.dirname(current);
+    return current;
+}
+
+/** A path as a single-quoted shell word. */
+function shellQuote(text) {
+    return /^[A-Za-z0-9_./-]+$/.test(text) ? text : `'${text.replace(/'/g, "'\\''")}'`;
+}
+
+/** The image tag the Docker variant runs: this Publisher's own version, or latest for a build that was never released. */
+function imageTag(version) {
+    return /^\d+\.\d+\.\d+$/.test(version) && version !== "0.0.0" ? version : "latest";
+}
+
+/**
+ * The command a pre-push hook runs, from the top of the repository, for a library
+ * `sub` below it ("" when the library is at the top).
+ *
+ * npx finds the Publisher in the library's own node_modules, so the npm variant
+ * changes into the library first; the Docker variant mounts the whole repository,
+ * .git included, and names the library with -C.
+ */
+function checkCommand(runner, sub, version) {
+    if (runner === "docker") {
+        return `docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" ${IMAGE}:${imageTag(version)} check` +
+            (sub ? ` -C ${shellQuote(sub)}` : "");
+    }
+    return `${sub ? `cd ${shellQuote(sub)} && ` : ""}npx --no-install api-only-publisher check`;
+}
+
+const FETCH = `git fetch --quiet --tags origin || echo "pre-push: could not fetch origin; checking against what is here" >&2`;
+
+/** The hook script itself. */
+function hookScript(runner, sub, version) {
+    const lines = [
+        "#!/bin/sh",
+        "# Written by api-only-publisher init: refuses the push when a published target",
+        "# changed without a new version in its version file. `git push --no-verify` skips it.",
+        "# check compares with origin's base branch and the release tags: bring them up to date.",
+        FETCH,
+    ];
+    // A failed cd must stop the push, not run check somewhere else.
+    if (runner === "npm" && sub) lines.push(`cd ${shellQuote(sub)} || exit 1`, `exec ${checkCommand(runner, "", version)}`);
+    else lines.push(`exec ${checkCommand(runner, sub, version)}`);
+    return lines.join("\n") + "\n";
+}
+
+/** The hook manager this repository already uses, by name, or null. */
+function hookManager(top, hooksPath) {
+    if (fs.existsSync(path.join(top, ".husky"))) return "husky";
+    for (const file of ["lefthook.yml", "lefthook.yaml", ".lefthook.yml", ".lefthook.yaml"]) {
+        if (fs.existsSync(path.join(top, file))) return "lefthook";
+    }
+    if (fs.existsSync(path.join(top, ".pre-commit-config.yaml"))) return "pre-commit";
+    if (hooksPath && path.normalize(hooksPath).replace(/[\\/]+$/, "") !== HOOKS_DIR) return `core.hooksPath (${hooksPath})`;
+    return null;
+}
+
+/**
+ * What init does about the hook for a library in `dir`, run with `runner`.
+ *
+ * @returns {{
+ *     files: Object<string, string>,   the hook file, keyed by its path relative to dir; empty under a manager
+ *     executable: string[],            which of those files to make executable
+ *     manager: string|null,            the hook manager found, if any
+ *     command: string,                 what a manager's pre-push entry should run
+ *     repository: string|null,         the top of the git repository, or null outside one
+ *     hooksPath: "unset"|"set"|null,   whether init should set core.hooksPath; null when it has nothing to do
+ * }}
+ */
+function planHook(dir, runner, version) {
+    const top = tryGit(["rev-parse", "--show-toplevel"], existingAncestor(dir));
+    const repository = top === null ? null : fs.realpathSync(top);
+    // Real paths, as git answers with: a directory reached through a symlink -- /var on macOS -- would never match.
+    const ancestor = existingAncestor(dir);
+    const libraryDir = path.join(fs.realpathSync(ancestor), path.relative(ancestor, dir));
+    // Outside a repository, the library is taken to become the top of one.
+    const root = repository || libraryDir;
+    const sub = path.relative(root, libraryDir).split(path.sep).join("/");
+    const hooksPath = repository ? tryGit(["config", "--get", "core.hooksPath"], repository) : null;
+    const manager = repository ? hookManager(repository, hooksPath) : null;
+    const command = checkCommand(runner, sub, version);
+    if (manager) return { files: {}, executable: [], manager, command, repository, hooksPath: null };
+
+    const rel = path.relative(libraryDir, path.join(root, HOOKS_DIR, "pre-push")).split(path.sep).join("/");
+    return {
+        files: { [rel]: hookScript(runner, sub, version) },
+        executable: [rel],
+        manager: null,
+        command,
+        repository,
+        hooksPath: hooksPath ? "set" : "unset",
+    };
+}
+
+/** Points git at .githooks in this clone. */
+function setHooksPath(repository) {
+    execFileSync("git", ["config", "core.hooksPath", HOOKS_DIR], { cwd: repository, stdio: "ignore" });
+}
+
+module.exports = { planHook, setHooksPath, imageTag, HOOKS_DIR };

package/src/init-questions.js

@@ -100,6 +100,14 @@ const QUESTIONS = [
     },
     { key: "serverUrl", flag: "--server-url", text: "Production server URL", check: checkUrl, when: hasOpenapi },
     { key: "brokerHost", flag: "--broker-host", text: "Broker host, with its port", check: checkHost, when: hasAsyncapi, name: "a broker host" },
+    {
+        // How the pre-push hook runs check: through the library's own npm install, or the image.
+        key: "runner", flag: "--runner", text: "Run the Publisher with: npm or docker",
+        read: (text) => {
+            const runner = text.trim().toLowerCase();
+            return ["npm", "docker"].includes(runner) ? { value: runner } : { problem: `'${text}' is not npm or docker` };
+        },
+    },
 ];
 
 /** Reads an answer to a question: the value, or what is wrong with it. */

package/src/init.js

@@ -29,6 +29,7 @@ const DEFAULTS = Object.freeze({
     licenseUrl: "https://www.apache.org/licenses/LICENSE-2.0.html",
     serverUrl: "https://api.example.invalid",
     brokerHost: "kafka:9092",
+    runner: "npm",
 });
 
 /** A value as a YAML scalar: plain where YAML reads it back unchanged, quoted where it would not. */
@@ -362,9 +363,15 @@ function plan(targetDir, files, values, portfolio) {
  * `portfolio`, given, is added the same way, as one more slot: whether the
  * library is about to have more than one target -- and so whether this is worth
  * asking about at all -- is decided before init is called, not here.
+ *
+ * `extra` are files beyond the scaffold, keyed as it is -- the pre-push hook, whose
+ * place depends on the repository, which init-hook.js reads -- and written by the
+ * same rules; those `executable` names are made executable whenever they are written.
  */
-function init(targetDir, { values = DEFAULTS, force = false, log = () => {}, portfolio = null } = {}) {
-    const files = scaffold(values);
+function init(targetDir, {
+    values = DEFAULTS, force = false, log = () => {}, portfolio = null, extra = {}, executable = [],
+} = {}) {
+    const files = { ...scaffold(values), ...extra };
     const report = { created: [], overwritten: [], identical: [], differing: [], updated: [] };
     const updates = [];
 
@@ -386,6 +393,7 @@ function init(targetDir, { values = DEFAULTS, force = false, log = () => {}, por
         const file = path.join(targetDir, rel);
         fs.mkdirSync(path.dirname(file), { recursive: true });
         fs.writeFileSync(file, files[rel]);
+        if (executable.includes(rel)) fs.chmodSync(file, 0o755);
         (status === "missing" ? report.created : report.overwritten).push(rel);
     }