@arc-e-tect/api-only-publisher 0.0.2 → 0.2.0

package/README.adoc

@@ -11,6 +11,16 @@ image:https://img.shields.io/github/v/release/Arc-E-Tect/SoftwareEngineeringDone
 image:https://img.shields.io/badge/Node-22%2B-339933?logo=node.js[Node 22+,link=https://nodejs.org]
 image:https://img.shields.io/badge/License-MIT-blue[MIT,link=LICENSE]
 
+Links say where they go: § jumps to a section of this page, → opens another file in this repository, and ↗ leaves it.
+
+// Remove this notice when 1.0.0 is released.
+[IMPORTANT]
+====
+Until 1.0.0 is released, any release may change the command line, `apionly.yaml` or the published artifacts incompatibly, without a major version bump.
+There are no users to break yet, and the interface is still being settled; 1.0.0 is the first release whose interface is kept stable.
+Pin an exact version, and read the changelog before upgrading.
+====
+
 == What it is
 
 `api-only-publisher` turns a library of small, reusable API description
@@ -53,23 +63,65 @@ pins, so they need no installation, and the only runtime dependency is `yaml`.
 
 == Installation
 
-As a command, without installing anything:
+The Publisher behaves the same however it is started.
+What differs is where its version is pinned, and what checks that pin.
+
+=== As a development dependency
+
+The better fit for a specification library, and for any build that runs the Publisher more than once.
+
+[source,console]
+----
+npm install --save-dev --save-exact @arc-e-tect/api-only-publisher
+----
+
+.package.json
+[source,json]
+----
+{
+  "private": true,
+  "scripts": {
+    "apionly": "api-only-publisher"
+  },
+  "devDependencies": {
+    "@arc-e-tect/api-only-publisher": "<version>"
+  }
+}
+----
 
 [source,console]
 ----
-npx @arc-e-tect/api-only-publisher build
+npm ci
+npm run apionly -- build
+npm run apionly -- publish --target user-account
 ----
 
-As a dependency of a specification library:
+* The version is pinned in one place, `package.json`, and every command and every CI job runs that one.
+* `package-lock.json` records the integrity hash of what was installed, so `npm ci` installs exactly those bytes or fails.
+* A CI job can cache the installation, keyed on `package-lock.json`, instead of resolving the tool on every run.
+* Renovate and Dependabot see the dependency, so an upgrade arrives as a pull request that moves the pin.
+* The cost is a `package.json` and a `package-lock.json` in the library, and an `npm ci` before the first command.
+
+=== With `npx`, installing nothing
+
+The better fit for trying the tool, for scaffolding a library with `init`, and for a one-off command.
 
 [source,console]
 ----
-npm install --save-dev @arc-e-tect/api-only-publisher
+npx @arc-e-tect/api-only-publisher@<version> init my-api-library
+npx @arc-e-tect/api-only-publisher@<version> build -C my-api-library
 ----
 
-Pin it exactly rather than with a range. This tool's output is expected to be
-reproducible — a specification library's golden fixtures assert it byte for byte
-— and a floating version quietly breaks that guarantee.
+* Nothing is added to the repository.
+* The version is pinned in every command instead, so each script and CI job that runs the Publisher has to name the same version, and nothing checks that they do.
+* Without a version, `npx` runs whatever it resolves at that moment, which is not reproducible.
+* Nothing records an integrity hash, and nothing notices when a newer version is released.
+
+Either way, pin an exact version rather than a range.
+This tool's output is expected to be reproducible — a specification library's golden fixtures assert it byte for byte — and a floating version quietly breaks that guarantee.
+
+The bundlers are a separate matter.
+However the Publisher itself is started, it fetches them with `npx`, at the versions `toolchain` in `apionly.yaml` pins.
 
 == Commands
 
@@ -82,10 +134,11 @@ reproducible — a specification library's golden fixtures assert it byte for by
 stands. This is how the *conventions* become reusable, as opposed to the code.
 
 |`build`
-|Stage, substitute placeholders, bundle, stamp the version, lint, and distribute.
+|Stage, substitute placeholders, bundle, stamp each published target's version, lint, and distribute.
 
 |`lint`
 |Lint what is already built, without rebuilding, for fast local feedback.
+Without `--target`, it also fails on a fragment no target reaches, as <<unreferenced,A fragment no target reaches fails the lint §>> describes.
 
 |`targets`
 |List the declared targets, what each one builds, and whether it is distributed.
@@ -99,10 +152,10 @@ of their content.
 drives a release: a target whose closure is untouched is not released, however
 much else in the repository moved.
 
-|`pack --version <v>`
-|Archive each built target with a `manifest.json`.
+|`pack`
+|Archive each built, published target with a `manifest.json`, at the version its version file declares.
 
-|`publish --version <v>`
+|`publish`
 |Pack once, then ship those same bytes to every configured channel.
 
 |`split --out <dir>`
@@ -112,13 +165,15 @@ much else in the repository moved.
 [source,console]
 ----
 api-only-publisher init my-api-library
-api-only-publisher build -C my-api-library --version 2.3.1
+api-only-publisher build -C my-api-library
 api-only-publisher build --target user-account --openapi
+api-only-publisher publish --target user-account --pre-release rc.1
 api-only-publisher targets
 ----
 
 `--target` may be repeated. `-C <dir>` runs as if started in `<dir>`; without it
 the configuration is found by walking up from the current directory.
+`--pre-release <ids>` appends pre-release identifiers to each target's version, as <<versions,Versions §>> describes.
 
 == What `build` actually does
 
@@ -139,13 +194,48 @@ indented YAML scalar.
 . **Bundle.** `@redocly/cli bundle` or `@asyncapi/cli bundle` resolves every
 `$ref` into one flat, self-contained document under `dist/<target>/`.
 
-. **Stamp the version**, if `--version` was given, on the *finished* document.
+. **Stamp the version** of each published target on its *finished* document: the version its version file declares, with any `--pre-release` identifiers appended.
+A `publish: false` target keeps the version its source declares.
 
 . **Lint** the finished document, so a broken fragment surfaces against the
 target it actually affects rather than at deploy time.
 
 . **Distribute**, unless the target is `publish: false`.
 
+[[versions]]
+== Versions
+
+Every published target has a version of its own, and it is kept in the library, beside the fragments it describes.
+
+.specs/openapi/bundles/user-account.bundle.properties
+[source,properties]
+----
+# The version of the user-account contract, for every document it builds.
+# Semantic: major for a breaking change, minor for an additive one, patch for
+# anything else. Change it in the same commit as the fragments it describes.
+version=2.1.0
+----
+
+By convention the file is `<target>.bundle.properties`, beside the target's first bundle root: its OpenAPI one, or its AsyncAPI one when it has no OpenAPI document.
+A target that keeps its version elsewhere names the file with `versionFile`, relative to `apionly.yaml`.
+The syntax is that of a Java properties file, so a JVM build can read the same file.
+
+`build`, `pack` and `publish` read the version of every target they act on before they act on any of them.
+A missing file, a file without a `version`, or a version that is not semantic stops the command before anything has been built or shipped.
+A `publish: false` target is never shipped, so it needs no version file.
+
+The version is not a command-line argument, and that is deliberate.
+A version on the command line lets two builds of the same commit publish different versions, and lets through a version nobody reviewed.
+A version in the library changes in the same commit as the fragments it describes, is reviewed with them, and is the same whoever builds that commit.
+
+The file holds a release version.
+A pre-release is that version with identifiers appended when it is built: `publish --pre-release rc.1` publishes `2.1.0-rc.1`.
+Cutting one never means editing the file, and then remembering to edit it back, which is why a version file that declares a pre-release is refused.
+
+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.
+
 == Independent versioning, and the dependency closure
 
 Giving each target its own version has one non-obvious consequence, and the
@@ -245,9 +335,9 @@ rather than a silent overwrite.
 |Channel |What it is for
 
 |`file`
-|A local directory. Not a distribution mechanism -- it exists so the pipeline is
-testable end to end with no infrastructure, and as a local-iteration escape
-hatch afterwards.
+|A local directory, laid out as `<directory>/<target>/<version>/`.
+Not a distribution mechanism between repositories: it exists so the pipeline is testable end to end with no infrastructure, so a library can share one build with the projects that implement it, and as a local-iteration escape hatch.
+Publishing a version again replaces that version and keeps the others; 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
@@ -290,6 +380,7 @@ guarantees.
 
 So a pre-release version is first-class: `2.1.0-rc.1`, or Maven's `-SNAPSHOT`
 spelling, which is not semver-legal but is what Maven consumers expect.
+It is cut from the version in the target's version file: `publish --pre-release rc.1` publishes `2.1.0-rc.1` when the file declares `2.1.0`.
 
 The hard rule is the other half of it. A pre-release must never quietly satisfy a
 production build:
@@ -328,13 +419,24 @@ defaults:
 build:
   staging: build/staging
   dist: dist
+reports:
+  lint: build/reports/lint
+lint:
+  unreferenced: error  # a fragment no target reaches: error, warn or off
 
 toolchain:
   redocly: "@redocly/cli@2.52.0"
   asyncapi: "@asyncapi/cli@6.0.2"
 
+channels:
+  file:
+    directory: build/publish
+    clean: true        # keep only the version being published
+
 targets:
   user-account:
+    # versionFile: versions/user-account.properties
+    #              default: user-account.bundle.properties beside the first bundle root
     openapi:
       bundle: bundles/user-account_openapi_structure.yaml
     asyncapi:
@@ -374,6 +476,21 @@ from the directory it was told to use, so a snippet one level up was invisible
 and the workaround was to move the Markdown files. The search now starts at the
 staged source root.
 
+[[unreferenced]]
+=== A fragment no target reaches fails the lint
+
+A linter checks documents, and a fragment reaches a document only through a `$ref`.
+A fragment that no target references is therefore never linted, however wrong it is, until the day a target starts to use it.
+
+So `lint`, run without `--target`, also lists every YAML file under the source root that no target's closure reaches, in `build/reports/lint/unreferenced.txt`, and fails when there is one.
+Every target counts, `publish: false` ones included, because they are linted too.
+That reports a fragment that does not comply before anything uses it, and finds a definition left behind by a change that stopped using it.
+
+`lint.unreferenced` in `apionly.yaml` sets what happens: `error` by default, `warn` to report without failing, or `off` not to look.
+`lint --target` does not look, because an unreferenced fragment belongs to no target.
+
+`lint` lints every document even when one of them fails, and names every failure at the end, so a single run reports all of them.
+
 === Version stamping edits one scalar
 
 `info.version` is located structurally and that one scalar is spliced. It is
@@ -411,11 +528,17 @@ layout. In order of what usually needs changing:
 |The lint rules
 |`defaults.openapi.lint`
 
+|Where lint reports go
+|`reports.lint`, defaulting to `build/reports/lint/<target>/<kind>.txt`
+
 |Where built documents go
 |`build.dist`, and `distribution` while it still exists
 
 |Where artifacts are published
 |`channels`
+
+|Where a target's version is kept
+|Its version file, or `targets.<target>.versionFile`
 |===
 
 Beyond that: the `common/` versus `<product>/<target>/` split is one convention
@@ -435,6 +558,8 @@ commit altered, and every manifest records the closure hash of what was
 published, so the hooks a diff gate would need already exist -- but the gate
 itself is deliberately not built.
 
+A breaking change is declared where it is made: the major version in the target's version file changes in the same commit as the fragments it breaks.
+
 A specification library should write down its own policy. The one this repository
 uses is at `usable-suspects/docs/breaking-changes.adoc`, and is a reasonable
 starting point to copy.
@@ -480,7 +605,7 @@ npm test
 ----
 
 Covers placeholder substitution (including each of the three defects fixed on
-the way in), version stamping, configuration parsing, and the scaffold.
+the way in), version stamping, version files, configuration parsing, every command, and the scaffold.
 
 The end-to-end guarantee lives elsewhere, in the specification library's own
 golden fixtures: they assert that the documents this tool produces are unchanged,
@@ -493,6 +618,18 @@ fetches and verifies. They share one seam — an archive plus a `manifest.json`
 and nothing else, which is why they can be versioned independently while living
 in one repository.
 
+This document is a reference for this half alone. For how the two are put
+together in a real project, see link:../docs/README.adoc[the manuals], which are
+organised by where the API descriptions live relative to the code that implements
+them: link:../docs/in-the-implementation-project.adoc[in the implementation
+project], link:../docs/elsewhere-in-the-repository.adoc[elsewhere in the same
+repository], link:../docs/in-its-own-repository.adoc[in a repository of their
+own]. The first uses only `build` and reads the result directly; the second
+publishes to the `file` channel, and the third to a registry. If you are
+replacing a script that copies a document into `src/main/resources`, start at
+link:../docs/migrating-a-checked-in-document.adoc[Migrating a checked-in
+document].
+
 == License
 
 MIT. See link:LICENSE[LICENSE].

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.0.2",
+  "version": "0.2.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

@@ -0,0 +1,80 @@
+"use strict";
+
+// A target's version.
+//
+// It is read from a version file kept with the target's specification, rather
+// than passed in by whatever runs the build. A version given on the command line
+// lets two builds of one commit publish different versions, and lets through a
+// version nobody reviewed. A version in the library changes in the same commit as
+// the fragments it describes, and is reviewed with them.
+//
+// The file holds a release version. A pre-release is that version with
+// identifiers appended when it is built, so cutting one never means editing the
+// file -- and then remembering to edit it back.
+
+const fs = require("fs");
+
+const { parse, isPrerelease } = require("./version-policy");
+
+class BundleVersionError extends Error {}
+
+// Java-properties style -- `key=value` or `key: value`, with `#` and `!` comments
+// -- 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) {
+    const properties = {};
+    for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === "" || line.startsWith("#") || line.startsWith("!")) continue;
+        const separator = line.search(/[=:]/);
+        if (separator < 0) continue;
+        properties[line.slice(0, separator).trim()] = line.slice(separator + 1).trim();
+    }
+    return properties;
+}
+
+/**
+ * The version `target` is built, packed and published as.
+ *
+ * @param {object} config a loaded configuration
+ * @param {string} target the target whose version to read
+ * @param {{preRelease?: string|null}} options pre-release identifiers to append, such as `rc.1`
+ * @returns {string}
+ */
+function versionOf(config, target, { preRelease = null } = {}) {
+    const file = config.versionFile(target);
+    if (!fs.existsSync(file)) {
+        throw new BundleVersionError(
+            `target '${target}': no version file at ${file}. Create it with a line such as 'version=1.0.0', ` +
+            `or point targets.${target}.versionFile at the file that holds its version.`
+        );
+    }
+    const declared = readProperties(file).version;
+    if (!declared) {
+        throw new BundleVersionError(`target '${target}': ${file} declares no version`);
+    }
+    try {
+        parse(declared);
+    } catch (error) {
+        throw new BundleVersionError(`target '${target}': ${file}: ${error.message}`);
+    }
+    if (isPrerelease(declared)) {
+        throw new BundleVersionError(
+            `target '${target}': ${file} declares '${declared}', but a version file holds a release version. ` +
+            `Declare the release it leads to, and cut the pre-release with --pre-release <identifiers>.`
+        );
+    }
+    if (!preRelease) return declared;
+
+    const version = `${declared}-${preRelease}`;
+    try {
+        parse(version);
+    } catch (error) {
+        throw new BundleVersionError(
+            `--pre-release '${preRelease}' does not make a semantic version of ${declared}: ${error.message}`
+        );
+    }
+    return version;
+}
+
+module.exports = { versionOf, readProperties, BundleVersionError };

package/src/channels.js

@@ -27,6 +27,12 @@ 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);
+    // `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 });
+    }
     fs.mkdirSync(targetDir, { recursive: true });
 
     const archiveDest = path.join(targetDir, path.basename(archive));

package/src/cli.js

@@ -14,23 +14,27 @@ const { changedSince, ChangedError } = require("./changed");
 const { split, SplitError } = require("./split");
 const { publish, ChannelError } = require("./channels");
 const { VersionError: PolicyError, describe } = require("./version-policy");
+const { versionOf, BundleVersionError } = require("./bundle-version");
+const { unreferenced } = require("./unreferenced");
 
 const USAGE = `api-only-publisher -- build and distribute API description documents
 
 Usage:
   api-only-publisher init [dir] [--force]
-  api-only-publisher build [--target <name>]... [--version <v>] [--openapi|--asyncapi]
+  api-only-publisher build [--target <name>]... [--pre-release <ids>] [--openapi|--asyncapi]
   api-only-publisher lint  [--target <name>]...
   api-only-publisher targets
   api-only-publisher closure [--target <name>]...
   api-only-publisher changed --since <ref>
-  api-only-publisher pack --version <v> [--target <name>]... [--out <dir>]
-  api-only-publisher publish --version <v> [--channel <name>]... [--out <dir>]
+  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]
 
 Options:
   --target <name>   Restrict to one target; repeat for several. Default: all.
-  --version <v>     Stamp info.version on every built document.
+  --pre-release <ids>
+                    build/pack/publish: append pre-release identifiers, such as
+                    rc.1, to each target's version.
   --openapi         Only build OpenAPI documents.
   --asyncapi        Only build AsyncAPI documents.
   --force           init only: overwrite files that already exist.
@@ -43,11 +47,13 @@ Options:
   -h, --help        Show this help.
 
 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.
 `;
 
 function parseArgs(argv) {
     const options = {
-        targets: [], kinds: null, version: null, quiet: false, force: false,
+        targets: [], kinds: null, preRelease: null, quiet: false, force: false,
         dir: process.cwd(), since: null, out: null, channels: null, by: "kind",
     };
     const positional = [];
@@ -60,7 +66,13 @@ function parseArgs(argv) {
         };
         switch (arg) {
             case "--target": options.targets.push(next()); break;
-            case "--version": options.version = next(); break;
+            case "--pre-release": options.preRelease = next(); break;
+            case "--version":
+                throw new ConfigError(
+                    "--version is no longer accepted: each published target's version is read from its version " +
+                    "file, <target>.bundle.properties beside its bundle root. Pass --pre-release <ids> to cut a " +
+                    "pre-release of it."
+                );
             case "--openapi": options.kinds = (options.kinds || []).concat("openapi"); break;
             case "--asyncapi": options.kinds = (options.kinds || []).concat("asyncapi"); break;
             case "--force": options.force = true; break;
@@ -79,6 +91,21 @@ function parseArgs(argv) {
     return { options, positional };
 }
 
+// The targets pack and publish write an archive for: those selected, less any
+// that are never published. Only these need a closure, so only these need to have
+// been staged -- building one target must not depend on every other being staged.
+function shippedTargets(config, targets) {
+    return Object.keys(config.targets)
+        .filter((target) => (!targets || targets.includes(target)) && config.isPublished(target));
+}
+
+// The version of each target in `names`, keyed by target. Every one is resolved
+// before any target is acted on, so a missing or malformed version file stops the
+// command before it has built or shipped anything.
+function versionsOf(config, names, preRelease) {
+    return new Map(names.map((target) => [target, versionOf(config, target, { preRelease })]));
+}
+
 async function main(argv) {
     const { options, positional } = parseArgs(argv);
     const command = positional[0];
@@ -121,29 +148,76 @@ async function main(argv) {
             return 0;
         }
         case "build": {
-            const results = build(config, { targets, version: options.version, kinds: options.kinds || undefined, log });
+            // A target is stamped only if it is published: a documentation view has no
+            // version of its own, and needs no version file.
+            const kinds = options.kinds || ["openapi", "asyncapi"];
+            const stamped = Object.keys(config.targets).filter((target) =>
+                (!targets || targets.includes(target)) && config.isPublished(target) &&
+                kinds.some((kind) => config.targets[target][kind]));
+            const versions = versionsOf(config, stamped, options.preRelease);
+            const results = build(config, {
+                targets, kinds, log, versionOf: (target) => versions.get(target) || null,
+            });
             log(`\nBuilt ${results.length} document(s).`);
             return 0;
         }
         case "lint": {
             // Lint without rebuilding, for fast local feedback on what is already
-            // in dist/.
+            // in dist/. Every selected document is linted even when one fails, so
+            // one run reports every failure rather than only the first.
             const fs = require("fs");
             const { lint } = require("./pipeline");
+            const failures = [];
             let linted = 0;
             for (const kind of ["openapi", "asyncapi"]) {
                 for (const target of config.targetsFor(kind)) {
                     if (targets && !targets.includes(target)) continue;
                     const file = path.join(config.distDir(target), config.outputName(kind));
                     if (!fs.existsSync(file)) {
-                        throw new BuildError(`${file} does not exist; run 'build' first`);
+                        failures.push(`${target} (${kind}): ${file} does not exist; run 'build' first`);
+                        continue;
                     }
                     log(`=== ${target} (${kind}) ===`);
-                    lint(config, kind, file, log);
+                    try {
+                        lint(config, kind, file, log, {
+                            report: true,
+                            reportFile: config.lintReport(target, kind),
+                        });
+                    } catch (error) {
+                        if (!(error instanceof BuildError)) throw error;
+                        console.error(error.message);
+                        failures.push(`${target} (${kind})`);
+                    }
                     linted += 1;
                 }
             }
             log(`\nLinted ${linted} document(s).`);
+
+            // A fragment no target reaches is never linted, so it is looked for
+            // here -- only when every target is linted, since it belongs to none.
+            const mode = config.lintUnreferenced();
+            let orphaned = null;
+            if (!targets && mode !== "off") {
+                prepare(config);
+                const orphans = unreferenced(config);
+                const reportFile = config.unreferencedReport();
+                fs.mkdirSync(path.dirname(reportFile), { recursive: true });
+                fs.writeFileSync(reportFile, orphans.map((file) => `${file}\n`).join(""));
+                if (orphans.length > 0) {
+                    orphaned =
+                        `${orphans.length} fragment(s) not reachable from any target, so nothing lints them:\n` +
+                        orphans.map((file) => `  ${file}`).join("\n") +
+                        "\nReference each one from a target's bundle, or delete it.";
+                    if (mode === "warn") log(orphaned);
+                }
+            }
+
+            const problems = [];
+            if (failures.length > 0) {
+                problems.push(`lint failed for ${failures.length} document(s): ${failures.join("; ")}`);
+            }
+            if (orphaned && mode === "error") problems.push(orphaned);
+            if (problems.length > 0) throw new BuildError(problems.join("\n\n"));
             return 0;
         }
         case "closure": {
@@ -167,9 +241,10 @@ async function main(argv) {
             return 0;
         }
         case "pack": {
-            if (!options.version) throw new ConfigError("pack requires --version <v>");
             const outDir = path.resolve(options.dir, options.out || "build/packages");
-            const closures = forTargets(config);
+            const shipped = shippedTargets(config, targets);
+            const versions = versionsOf(config, shipped, options.preRelease);
+            const closures = forTargets(config, undefined, shipped);
             let packed = 0;
             for (const target of Object.keys(config.targets)) {
                 if (targets && !targets.includes(target)) continue;
@@ -179,7 +254,7 @@ async function main(argv) {
                 }
                 const closure = closures.get(target);
                 pack(config, target, {
-                    version: options.version,
+                    version: versions.get(target),
                     closureSha256: closure ? closure.sha256 : null,
                     outDir, log,
                 });
@@ -189,14 +264,15 @@ async function main(argv) {
             return 0;
         }
         case "publish": {
-            if (!options.version) throw new ConfigError("publish requires --version <v>");
             const outDir = path.resolve(options.dir, options.out || "build/packages");
             const configured = config.channels || {};
             const names = options.channels || Object.keys(configured);
             if (names.length === 0) {
                 throw new ConfigError("no channels configured; add a `channels:` block or pass --channel");
             }
-            const closures = forTargets(config);
+            const shipped = shippedTargets(config, targets);
+            const versions = versionsOf(config, shipped, options.preRelease);
+            const closures = forTargets(config, undefined, shipped);
             let published = 0;
             for (const target of Object.keys(config.targets)) {
                 if (targets && !targets.includes(target)) continue;
@@ -204,7 +280,7 @@ async function main(argv) {
                 const closure = closures.get(target);
                 // Packed once, then shipped unchanged to every channel.
                 const { archive, manifest } = pack(config, target, {
-                    version: options.version,
+                    version: versions.get(target),
                     closureSha256: closure ? closure.sha256 : null,
                     outDir, log,
                 });
@@ -239,7 +315,8 @@ function report(error) {
         error instanceof PlaceholderError || error instanceof VersionError ||
         error instanceof ClosureError || error instanceof PackError ||
         error instanceof ChangedError || error instanceof SplitError ||
-        error instanceof ChannelError || error instanceof PolicyError) {
+        error instanceof ChannelError || error instanceof PolicyError ||
+        error instanceof BundleVersionError) {
         console.error(`Error: ${error.message}`);
         process.exitCode = 1;
     } else {

package/src/closure.js

@@ -92,15 +92,18 @@ function hash(files, root) {
  * Closures for every target that declares a bundle of the given kinds.
  *
  * The staged tree must already exist; callers stage first so that the closure
- * covers substituted content.
+ * covers substituted content. Pass `only` to compute closures for those targets
+ * alone: a target outside it is never read, so its bundle root need not be staged.
  *
+ * @param {string[]|null} only the targets to compute closures for; every target when null
  * @returns {Map<string, {files: string[], sha256: string, byKind: object}>}
  */
-function forTargets(config, kinds = ["openapi", "asyncapi"]) {
+function forTargets(config, kinds = ["openapi", "asyncapi"], only = null) {
     const result = new Map();
 
     for (const kind of kinds) {
         for (const target of config.targetsFor(kind)) {
+            if (only && !only.includes(target)) continue;
             const entry = config.bundlePath(target, kind);
             if (!fs.existsSync(entry)) {
                 throw new ClosureError(

package/src/config.js

@@ -92,6 +92,8 @@ function load(configPath) {
         defaults: parsed.defaults || {},
         toolchain: parsed.toolchain || {},
         build: parsed.build || {},
+        reports: parsed.reports || {},
+        lint: parsed.lint || {},
         distribution: parsed.distribution || null,
         channels: parsed.channels || {},
         targets,
@@ -121,6 +123,25 @@ function load(configPath) {
             const lint = (this.defaults[kind] || {}).lint;
             return lint ? path.resolve(this.root, lint) : null;
         },
+        lintReport(target, kind) {
+            const reports = this.reports.lint || "build/reports/lint";
+            return path.resolve(this.root, reports, target, `${kind}.txt`);
+        },
+        // Where lint lists the fragments no target reaches.
+        unreferencedReport() {
+            const reports = this.reports.lint || "build/reports/lint";
+            return path.resolve(this.root, reports, "unreferenced.txt");
+        },
+        // What lint does about a fragment no target reaches: `error`, the default,
+        // fails the lint; `warn` reports it; `off` does not look.
+        lintUnreferenced() {
+            const configured = this.lint.unreferenced;
+            const mode = configured === undefined ? "error" : configured === false ? "off" : configured;
+            if (!["error", "warn", "off"].includes(mode)) {
+                throw new ConfigError(`lint.unreferenced must be error, warn or off, not ${JSON.stringify(configured)}`);
+            }
+            return mode;
+        },
         tool(name) {
             return requireString(this.toolchain[name], `toolchain.${name}`);
         },
@@ -136,6 +157,20 @@ function load(configPath) {
         bundlePath(target, kind) {
             return path.join(this.stagingDir(kind), this.targets[target][kind].bundle);
         },
+        // The file a target's version is read from: the target's own `versionFile`,
+        // relative to this configuration, or else <target>.bundle.properties beside
+        // the target's first bundle root in the hand-authored tree -- so a version
+        // sits with the fragments it describes, and changes in the same commit.
+        versionFile(target) {
+            const spec = this.targets[target];
+            if (spec.versionFile !== undefined) {
+                return path.resolve(this.root, requireString(spec.versionFile, `targets.${target}.versionFile`));
+            }
+            const kind = ["openapi", "asyncapi"].find((k) => spec[k]);
+            const bundleRoot = path.join(
+                this.sourceRoot(), requireString(this.sources[kind], `sources.${kind}`), spec[kind].bundle);
+            return path.join(path.dirname(bundleRoot), `${target}.bundle.properties`);
+        },
         // Where a distributed document is copied to, from the transitional
         // `distribution` block. Null once that block is gone.
         destinationDir(target) {

package/src/index.js

@@ -3,16 +3,18 @@
 // The programmatic surface.
 //
 // The CLI is the usual way in, but a release job that wants to decide something
-// for itself -- which targets changed, what a closure hashes to, whether a
-// version is a pre-release -- should not have to parse console output to find
-// out. Everything the CLI does is available here directly.
+// for itself -- which targets changed, what a closure hashes to, which version a
+// target is at, whether a version is a pre-release -- should not have to parse
+// console output to find out. Everything the CLI does is available here directly.
 
 module.exports = {
     ...require("./config"),
     ...require("./placeholders"),
     ...require("./version"),
     ...require("./version-policy"),
+    ...require("./bundle-version"),
     ...require("./closure"),
+    ...require("./unreferenced"),
     ...require("./aggregate"),
     ...require("./pipeline"),
     ...require("./pack"),

package/src/init.js

@@ -147,6 +147,12 @@ dist/
 node_modules/
 `;
 
+const VERSION = `# The version of the example-service contract, for every document it builds.
+# Semantic: major for a breaking change, minor for an additive one, patch for
+# anything else. Change it in the same commit as the fragments it describes.
+version=0.1.0
+`;
+
 const FILES = {
     "apionly.yaml": CONFIG,
     ".redocly.yaml": REDOCLY,
@@ -155,6 +161,7 @@ const FILES = {
     "specs/openapi/shared/conventions.md": CONVENTIONS,
     "specs/openapi/shared/servers.yaml": SERVERS,
     "specs/openapi/bundles/example-service_openapi_structure.yaml": BUNDLE,
+    "specs/openapi/bundles/example-service.bundle.properties": VERSION,
     "specs/openapi/paths/example/ExamplesV1.yaml": PATH_FRAGMENT,
     "specs/openapi/components/common/security/BearerAuth.yaml": SECURITY_SCHEME,
     "specs/openapi/components/common/responses/errors/InvalidRequestProblemV1.yaml": PROBLEM,

package/src/pack.js

@@ -96,7 +96,8 @@ function pack(config, target, { version, closureSha256, outDir, log = () => {} }
         if (declared !== String(version)) {
             throw new PackError(
                 `target '${target}': ${path.basename(document)} declares info.version '${declared}' ` +
-                `but is being packed as '${version}'. Build with --version ${version} first.`
+                `but is being packed as '${version}'. Build it again first: its version file, or the ` +
+                `--pre-release it was built with, has changed since.`
             );
         }
     }

package/src/pipeline.js

@@ -12,11 +12,20 @@ const { generateAsyncApi, isAggregate } = require("./aggregate");
 
 class BuildError extends Error {}
 
-function run(command, args, { quiet }) {
+function run(command, args, { quiet, reportFile = null } = {}) {
     try {
         const out = execFileSync(command, args, { encoding: "utf8", stdio: quiet ? "pipe" : "inherit" });
+        if (reportFile) {
+            fs.mkdirSync(path.dirname(reportFile), { recursive: true });
+            fs.writeFileSync(reportFile, out);
+        }
         return out;
     } catch (error) {
+        const output = (error.stdout || "") + (error.stderr || "");
+        if (reportFile) {
+            fs.mkdirSync(path.dirname(reportFile), { recursive: true });
+            fs.writeFileSync(reportFile, output);
+        }
         throw new BuildError(
             `${command} ${args.join(" ")} failed` + (error.stdout ? `\n${error.stdout}` : "") +
             (error.stderr ? `\n${error.stderr}` : "")
@@ -91,13 +100,14 @@ function bundle(config, target, kind, outFile, log) {
     }
 }
 
-function lint(config, kind, file, log) {
+function lint(config, kind, file, log, { report = false, reportFile = null } = {}) {
     const tool = kind === "openapi" ? config.tool("redocly") : config.tool("asyncapi");
     const args = kind === "openapi"
         ? ["--yes", tool, "lint"].concat(config.lintConfig("openapi") ? ["--config", config.lintConfig("openapi")] : []).concat([file])
         : ["--yes", tool, "validate", file];
     log(`-- Validating ${path.basename(file)}`);
-    run("npx", args, { quiet: true });
+    const output = run("npx", args, { quiet: true, reportFile });
+    if (report && output.trim()) log(output.trimEnd());
 }
 
 /**
@@ -145,9 +155,12 @@ function prepare(config, { kinds = ["openapi", "asyncapi"], log = () => {} } = {
 /**
  * Build every requested target.
  *
+ * `versionOf(target)` names the version to stamp on a target's documents; a target
+ * it returns nothing for keeps the version its source declares.
+ *
  * @returns {Array<{target, kind, file, distributed}>}
  */
-function build(config, { targets, version, kinds = ["openapi", "asyncapi"], log = () => {} } = {}) {
+function build(config, { targets, versionOf = () => null, kinds = ["openapi", "asyncapi"], log = () => {} } = {}) {
     const results = [];
     for (const kind of kinds) {
         const all = config.targetsFor(kind).filter((t) => !targets || targets.includes(t));
@@ -172,6 +185,7 @@ function build(config, { targets, version, kinds = ["openapi", "asyncapi"], log
             }
             const outFile = path.join(config.distDir(target), config.outputName(kind));
             bundle(config, target, kind, outFile, log);
+            const version = versionOf(target);
             if (version) {
                 log(`-- Stamping version '${version}'`);
                 stampFile(outFile, version);

package/src/unreferenced.js

@@ -0,0 +1,53 @@
+"use strict";
+
+// Fragments no target reaches.
+//
+// A linter checks documents, and a fragment reaches a document only through a
+// $ref. A fragment that no target references is therefore never linted, however
+// wrong it is, until the day a target starts to use it. Looking for unreferenced
+// fragments is how that is caught before then -- and how a definition left behind
+// by a change that stopped using it is found at all.
+
+const fs = require("fs");
+const path = require("path");
+
+const { forTargets } = require("./closure");
+
+function yamlFiles(dir) {
+    const files = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) files.push(...yamlFiles(full));
+        else if (entry.isFile() && /\.ya?ml$/.test(entry.name)) files.push(full);
+    }
+    return files;
+}
+
+const portable = (file) => file.split(path.sep).join("/");
+
+/**
+ * Every YAML file under the source root that no target's closure reaches,
+ * relative to the source root and sorted.
+ *
+ * Every target counts, `publish: false` ones included: a documentation view is
+ * linted like any other target, so whatever it reaches is linted too. The staged
+ * tree must already exist, as for forTargets.
+ *
+ * @returns {string[]}
+ */
+function unreferenced(config) {
+    const reached = new Set();
+    for (const [, entry] of forTargets(config)) {
+        for (const [kind, files] of Object.entries(entry.byKind)) {
+            const stagingRoot = config.stagingRoot(kind);
+            for (const file of files) reached.add(portable(path.relative(stagingRoot, file)));
+        }
+    }
+    const sourceRoot = config.sourceRoot();
+    return yamlFiles(sourceRoot)
+        .map((file) => portable(path.relative(sourceRoot, file)))
+        .filter((file) => !reached.has(file))
+        .sort();
+}
+
+module.exports = { unreferenced };