@arc-e-tect/api-only-publisher 0.18.6 → 0.19.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.18.6
+:api-only-publisher-version: 0.19.0
 
 [NOTE]
 .About this documentation
@@ -190,12 +190,12 @@ Without `--target`, it also fails on a fragment no target reaches, as <<unrefere
 |Show each target's dependency closure: how many files it reaches, and the hash of their content.
 
 |`changed --since <ref>`
-|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.
+|Report which targets' documents changed between a git ref and the working tree.
+A target whose documents are the same 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.
+|Fail on every published target that changed without a new version, as <<version-guard,A changed target needs a new version §>> describes.
+Made for a pull request's pipeline: no credentials, and no network when the bundler is carried, as in the Publisher's image; it builds each target's documents in a temporary copy, and leaves the library's own build output alone.
 
 |`pack [--pre-release <ids>] [--target <t>]... [--out <dir>]`
 |Archive each built, published target with a `manifest.json`, at the version its version file declares.
@@ -449,23 +449,50 @@ Change the version in the same commit as the fragments instead; `check` and `pub
 
 `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.
+Both decide from git: the target's release tags, its history, and the working tree, changes not yet committed included.
+
+A target's version is the version of its documents, so a target has changed when its documents have: what a consumer receives, not the files it is built from.
+`check` builds the target twice, in a temporary copy of the library: as the baseline below has it, and as the working tree has it.
+It compares the two documents as canonical JSON, without the version stamped on them, so the order of keys does not count either.
+
+* An edit that does not reach the documents is no change: a YAML comment, quoting or layout, a part of a shared file the target does not use, or a file that only such a part refers to.
+* An edit that does reach them is a change, wherever it was made: a Markdown snippet a placeholder substitutes, which no `$ref` reaches, counts.
+* Moving a fragment to another directory changes its `x-fragment-path`, so with `fragmentPaths` on it is a change; with it off, and the file name kept, it is not.
+The TranscriberJ names generated classes after that path, so what a consumer gets does differ.
 
 [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.
+|The documents unchanged since that tag: the version was released from what the tag points at, and publishing it again is safe only with the same documents.
 
 |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 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.
+|Compared with the merge-base with the base branch, or with the ref `--since` names: a target whose documents 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.
 |===
 
+A version raised over documents that did not change is a warning, not a failure: it announces a change there is not, and consumers will look for one.
+A release can be cut again on purpose, so `check` passes it with `WARNING`, and `publish` logs it and publishes.
+
+A refused target comes with a hint at the version it needs:
+
+[source,console]
+----
+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; hint: 2.2.0, a minor bump: something was added at /components/schemas/Refund
+----
+
+The hint sorts each difference between the two documents and takes the largest: documentation only -- a description, summary, title or example, or a fragment moved under the same file name -- is a patch; something added is a minor; something removed or changed, or a constraint such as `required`, `pattern` or `maxLength` added, is a major.
+Below 1.0 each moves one place down: a major becomes a minor, a minor a patch.
+It is a hint, not a compatibility analysis: it may call a compatible change a major, and the version you choose is yours.
+
+The baseline is built with its own `apionly.yaml` and its own toolchain pin, so it is the document that was released.
+When that pin cannot be had -- a sealed image carries only today's bundler, and downloading is off -- the baseline is built with today's pin instead, and the reason says so.
+A baseline that cannot be built at all leaves the target `undecided`, saying why.
+
 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.
@@ -585,10 +612,12 @@ 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.
+* It checks every published target, not only those the pushed commits touch: a target that did not change passes.
+The check builds each target twice, so it takes about as long as two builds.
 * `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.
+* It needs no credentials, and no network beyond the `git fetch` once the pinned bundler is on your machine.
+It builds in a temporary copy of the library, and leaves your own build output alone.
 * `git push --no-verify` skips the hook.
 The pipeline still runs the same check, so skipping it only means you find out later.
 
@@ -602,16 +631,16 @@ A change under one target's own fragments affects only that one.
 Under repository-wide versioning the distinction is invisible, because everything bumps together; under per-target versioning a release has to know the difference, or one target's edit releases every other target and the version numbers stop meaning anything.
 
 A target's *closure* is every file reachable from its bundle root by following `$ref`s transitively.
-`changed --since <ref>` resolves each closure and reports which targets a change actually touched:
+`changed --since <ref>` reports which targets a change actually reached:
 
 [source,console]
 ----
 npm run apionly -- changed --since origin/main
 ----
 
-Two things make this correct rather than approximate.
-The closure is computed over the *staged, substituted* tree, so a change to a Markdown snippet, which genuinely changes the published document, counts.
-And a change to the *shape* of a closure always means editing a file already inside it, so a bundle gaining or losing a `$ref` is caught without diffing membership separately.
+It decides as `check` does, by building each target as the ref has it and as the working tree has it, and comparing the documents (<<version-guard,A changed target needs a new version §>>).
+A closure is coarser than that: a file is in it as soon as any part of it is reached, so an edit to a part of a shared file a target does not use touches its closure, but not its documents.
+`changed` therefore names a target only when its documents differ, and still reports the files of its closure that git saw change.
 
 The closure hash is recorded in each release's manifest as `closureSha256`, which is what lets a later commit compare against what was actually published.
 
@@ -1984,7 +2013,7 @@ Choosing the next version is the API designer's responsibility, and this table i
 The policy is the same for both kinds: an AsyncAPI document gains the key exactly as an OpenAPI one does, and the version follows the table above.
 
 Upgrading to a Publisher that stamps the key changes every OpenAPI document that has components built from fragments, and every AsyncAPI document that has fragments at all.
-`changed` does not see that, because a target's closure hash covers the fragments, not the Publisher.
+`changed` and `check` do not see that, because they build both sides of the comparison with the Publisher that runs them.
 Bump each such target's MINOR version in the upgrade's commit, or set `fragmentPaths: false` for the kind until you do: publishing a changed document under a version already published is refused by every Subscriber that locked it (see <<versions,Versions §>>).
 
 [#distribution]

package/package.json

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

package/src/bump-hint.js

@@ -0,0 +1,124 @@
+"use strict";
+
+// Which part of a version a change to a target's documents most likely asks for.
+//
+// A hint, not an analysis: it walks the two documents and sorts each difference into
+// documentation (patch), something added (minor), or something removed or changed
+// (major), and the largest one wins. It knows no compatibility rules beyond that, so a
+// change it calls a major may well be compatible; deciding that properly is #100.
+//
+// Below 1.0 each moves one place down: a breaking change bumps the minor version, an
+// addition the patch version.
+
+const { parse } = require("./version-policy");
+const { canonical } = require("./documents");
+
+const RANK = { patch: 1, minor: 2, major: 3 };
+
+// Keys that only document: changing them changes what a reader is told, not what is accepted.
+const DOCUMENTATION = new Set([
+    "description", "summary", "title", "example", "examples", "externalDocs",
+    "contact", "license", "termsOfService", "x-fragment-path",
+]);
+
+// Keys that narrow what is accepted: adding one is no addition.
+const CONSTRAINTS = new Set([
+    "required", "enum", "const", "type", "format", "pattern", "minimum", "maximum",
+    "exclusiveMinimum", "exclusiveMaximum", "multipleOf", "minLength", "maxLength",
+    "minItems", "maxItems", "uniqueItems", "minProperties", "maxProperties", "additionalProperties",
+]);
+
+// Maps whose keys are names the specification author chose: a property called
+// `description` is a property, not documentation.
+const NAMES = new Set([
+    "properties", "patternProperties", "$defs", "definitions", "paths", "schemas", "responses",
+    "parameters", "headers", "requestBodies", "securitySchemes", "links", "callbacks", "pathItems",
+    "channels", "messages", "operations", "servers", "variables", "mapping", "content",
+]);
+
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function pointer(at) {
+    return "/" + at.map((part) => String(part).replace(/~/g, "~0").replace(/\//g, "~1")).join("/");
+}
+
+function basename(file) {
+    return String(file).split("/").pop();
+}
+
+/** Every difference between `before` and `after`, as {bump, at, what}. */
+function differences(before, after, at = [], parentKey = null, found = []) {
+    const key = at.length > 0 ? at[at.length - 1] : null;
+    const isKeyword = key !== null && typeof key === "string" && !NAMES.has(parentKey);
+    const keyword = isKeyword ? key : null;
+
+    if (canonical(before) === canonical(after)) return found;
+    if (keyword === "x-fragment-path") {
+        const renamed = before !== undefined && after !== undefined && basename(before) !== basename(after);
+        found.push(renamed
+            ? { bump: "major", at, what: "a fragment was renamed, which renames its generated class" }
+            : { bump: "patch", at, what: "a fragment moved" });
+        return found;
+    }
+    if (DOCUMENTATION.has(keyword)) {
+        found.push({ bump: "patch", at, what: "documentation changed" });
+        return found;
+    }
+    if (CONSTRAINTS.has(keyword)) {
+        found.push({ bump: "major", at, what: "a constraint was added, removed or changed" });
+        return found;
+    }
+    if (before === undefined) {
+        found.push({ bump: "minor", at, what: "something was added" });
+        return found;
+    }
+    if (after === undefined) {
+        found.push({ bump: "major", at, what: "something was removed or changed" });
+        return found;
+    }
+    if (isObject(before) && isObject(after)) {
+        for (const k of new Set([...Object.keys(before), ...Object.keys(after)])) {
+            differences(before[k], after[k], [...at, k], key, found);
+        }
+        return found;
+    }
+    if (Array.isArray(before) && Array.isArray(after)) {
+        const kept = before.every((item, i) => i < after.length && canonical(item) === canonical(after[i]));
+        found.push(kept
+            ? { bump: "minor", at: [...at, before.length], what: "something was added" }
+            : { bump: "major", at, what: "something was removed or changed" });
+        return found;
+    }
+    found.push({ bump: "major", at, what: "something was removed or changed" });
+    return found;
+}
+
+/**
+ * The bump a change from `before` to `after` most likely asks for, from `version`.
+ *
+ * @param {Object<string, object>} before a target's documents, by kind, at the baseline
+ * @param {Object<string, object>} after the same target's documents now
+ * @param {string} version the version to bump from
+ * @returns {{bump: "major"|"minor"|"patch", version: string, why: string} | null} null when nothing differs
+ */
+function bumpHint(before, after, version) {
+    const found = [];
+    for (const kind of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()) {
+        differences(before[kind], after[kind], [], null, []).forEach((d) => found.push({ ...d, kind }));
+    }
+    if (found.length === 0) return null;
+    const largest = found.reduce((a, b) => (RANK[b.bump] > RANK[a.bump] ? b : a));
+
+    const v = parse(version);
+    let bump = largest.bump;
+    if (v.major === 0) bump = bump === "major" ? "minor" : "patch";
+    const next = bump === "major" ? `${v.major + 1}.0.0`
+        : bump === "minor" ? `${v.major}.${v.minor + 1}.0`
+            : `${v.major}.${v.minor}.${v.patch + 1}`;
+    const where = largest.at.length > 0 ? ` at ${pointer(largest.at)}` : ` (the ${largest.kind} document)`;
+    return { bump, version: next, why: `${largest.what}${where}` };
+}
+
+module.exports = { bumpHint };

package/src/changed.js

@@ -6,12 +6,17 @@
 // everything bumps together. Under per-target versioning the release job has to
 // answer it, or a change to one service's context releases every other service
 // too, and the version numbers stop meaning anything.
+//
+// A target changed when its documents did (#121): it is built as `since` has it and
+// as the working tree has it, and the two are compared, as the version guard does.
+// The files git saw change in its closure are reported alongside, for the reader.
 
 const fs = require("fs");
 const path = require("path");
 const { execFileSync } = require("child_process");
 
 const { forTargets } = require("./closure");
+const { targetDocuments, sameDocuments } = require("./documents");
 
 class ChangedError extends Error {}
 
@@ -61,7 +66,8 @@ function toSource(config, stagedFile, kinds) {
 }
 
 /**
- * @returns {Array<{target, changed: boolean, files: string[], closureSha256: string}>}
+ * @returns {Array<{target, changed: boolean, files: string[], closureSha256: string}>} `changed` when the
+ *     target's documents differ; `files`, the files in its closure git saw change, whether they did or not
  */
 function changedSince(config, since, { kinds = ["openapi", "asyncapi"], log = () => {} } = {}) {
     const repoRoot = real(git(["rev-parse", "--show-toplevel"], config.root).trim());
@@ -75,6 +81,9 @@ function changedSince(config, since, { kinds = ["openapi", "asyncapi"], log = ()
     );
 
     const closures = forTargets(config, kinds);
+    const targets = [...closures.keys()];
+    const now = targetDocuments(config, targets, { repoRoot }).documents;
+    const then = targetDocuments(config, targets, { ref: since, repoRoot }).documents;
     const results = [];
 
     for (const [target, entry] of closures) {
@@ -82,17 +91,20 @@ function changedSince(config, since, { kinds = ["openapi", "asyncapi"], log = ()
             .map((f) => toSource(config, f, kinds))
             .filter(Boolean)
             .map(real);
-        // A change to the *shape* of a closure -- a bundle gaining or losing a
-        // $ref -- always means editing a file that is already in the closure, so
-        // membership changes are caught without diffing membership itself.
         const touched = [...new Set(sources.filter((f) => diff.has(f)))].sort();
+        const mine = now.get(target);
+        if (mine.error) throw new ChangedError(`${target} could not be built from the working tree: ${mine.error.message}`);
+        const theirs = then.get(target);
+        // A target that does not build as `since` has it cannot be shown unchanged.
+        if (theirs.error) log(`${target}: could not be built at ${since}, so counted as changed: ${theirs.error.message}`);
+        const changed = Boolean(theirs.error) || !sameDocuments(theirs.documents, mine.documents);
         results.push({
             target,
-            changed: touched.length > 0,
+            changed,
             files: touched.map((f) => path.relative(repoRoot, f)),
             closureSha256: entry.sha256,
         });
-        log(`${target.padEnd(18)} ${touched.length > 0 ? "changed" : "unchanged"}  ${entry.sha256.slice(0, 12)}`);
+        log(`${target.padEnd(18)} ${changed ? "changed" : "unchanged"}  ${entry.sha256.slice(0, 12)}`);
     }
     return results;
 }

package/src/cli.js

@@ -552,6 +552,9 @@ async function main(argv, io = {}) {
                 for (const r of checked.filter((c) => c.verdict === "undecided")) {
                     log(`warning: ${r.target} ${r.version}: version not checked: ${r.reason}`);
                 }
+                for (const r of checked.filter((c) => c.verdict === "warning")) {
+                    log(`warning: ${r.target} ${r.version}: ${r.reason}`);
+                }
             } catch (error) {
                 if (!(error instanceof GuardError && error.notARepository)) throw error;
                 log(`warning: versions not checked: ${error.message}`);

package/src/documents.js

@@ -0,0 +1,150 @@
+"use strict";
+
+// A target's documents, as a consumer receives them.
+//
+// Whether a target changed is a question about what it publishes, not about which files
+// git saw change (#121). A comment, a reformatted fragment, a part of a shared file the
+// target never reaches, a fragment moved where the bundle does not show it: none of these
+// changes the document, and none should ask for a new version. A placeholder snippet no
+// $ref reaches does change it, and should.
+//
+// So the documents are built -- from the working tree, or from a ref -- in a copy of the
+// library made for the purpose, never in the library's own build directories, and
+// compared as canonical JSON without the version stamped on them.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const YAML = require("yaml");
+
+const { load } = require("./config");
+const toolchain = require("./toolchain");
+
+/** RFC 8785-style canonical JSON: keys sorted at every level, lists in their order. */
+function canonical(value) {
+    if (value === undefined) return "undefined";
+    if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+
+/** A built document's content, without the version stamped on it. */
+function documentOf(text) {
+    const document = YAML.parse(text);
+    if (document && document.info && typeof document.info === "object") delete document.info.version;
+    return document;
+}
+
+/** Whether two targets' documents, by kind, are the same. */
+function sameDocuments(a, b) {
+    return canonical(a) === canonical(b);
+}
+
+function git(args, cwd, options = {}) {
+    return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], maxBuffer: 1 << 30, ...options });
+}
+
+/** Copy the library as the working tree has it: tracked and untracked files git does not ignore. */
+function exportWorkingTree(repoRoot, libRel, into) {
+    const listed = git(["ls-files", "-z", "-c", "-o", "--exclude-standard", "--", libRel || "."], repoRoot)
+        .toString("utf8").split("\0").filter(Boolean);
+    for (const rel of [...new Set(listed)]) {
+        const from = path.join(repoRoot, rel);
+        let stat;
+        try {
+            stat = fs.lstatSync(from);
+        } catch {
+            continue; // tracked, but deleted in the working tree
+        }
+        const to = path.join(into, rel);
+        fs.mkdirSync(path.dirname(to), { recursive: true });
+        if (stat.isSymbolicLink()) fs.symlinkSync(fs.readlinkSync(from), to);
+        else if (stat.isFile()) fs.copyFileSync(from, to);
+    }
+}
+
+/** Copy the library as `ref` has it. */
+function exportRef(repoRoot, ref, libRel, into) {
+    const archive = git(["archive", "--format=tar", ref, "--", libRel || "."], repoRoot);
+    execFileSync("tar", ["-x", "-f", "-", "-C", into], { input: archive, stdio: ["pipe", "ignore", "pipe"] });
+}
+
+/**
+ * Pin each tool of the copy's configuration to what this installation can run: its own
+ * pin when that can be had, otherwise the one `current` pins. A baseline released with an
+ * older bundler than the sealed image carries is still compared, and the reason says how.
+ */
+function usableToolchain(copy, current, kinds) {
+    const notes = [];
+    for (const kind of kinds) {
+        if (copy.targetsFor(kind).length === 0) continue;
+        const key = toolchain.TOOL_OF_KIND[kind];
+        const own = copy.toolchain && copy.toolchain[key];
+        try {
+            toolchain.resolve(key, copy.tool(key));
+        } catch (error) {
+            const today = current.tool(key);
+            if (!own || own === today) throw error;
+            toolchain.resolve(key, today);
+            copy.toolchain[key] = today;
+            notes.push(`built with ${today}, as ${own} cannot be had`);
+        }
+    }
+    return notes;
+}
+
+/**
+ * Each target's documents, by kind, built from `ref` -- or from the working tree when
+ * `ref` is null -- in a copy of the library.
+ *
+ * A target that does not build is reported with its error rather than failing the rest;
+ * so is every target when the copy's configuration cannot be read.
+ *
+ * @param {object} config the library's loaded configuration
+ * @param {string[]} targets
+ * @param {{ref?: string|null, repoRoot: string}} options
+ * @returns {{documents: Map<string, {documents?: object, error?: Error}>, notes: string[]}}
+ */
+function targetDocuments(config, targets, { ref = null, repoRoot }) {
+    // Required here, not at the top: the pipeline requires modules that require this one.
+    const { build } = require("./pipeline");
+    const libRel = path.relative(repoRoot, fs.realpathSync(config.root)).split(path.sep).join("/");
+    const configRel = path.relative(fs.realpathSync(config.root), fs.realpathSync(config.path));
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "aop-documents-"));
+    const documents = new Map();
+    let notes = [];
+    try {
+        let copy;
+        try {
+            if (ref === null) exportWorkingTree(repoRoot, libRel, scratch);
+            else exportRef(repoRoot, ref, libRel, scratch);
+            copy = load(path.join(scratch, libRel, configRel));
+            notes = usableToolchain(copy, config, ["openapi", "asyncapi"]);
+        } catch (error) {
+            for (const target of targets) documents.set(target, { error });
+            return { documents, notes };
+        }
+        for (const target of targets) {
+            if (!copy.targets[target]) {
+                documents.set(target, { documents: {} });
+                continue;
+            }
+            try {
+                const built = build(copy, { targets: [target], verify: false, distribute: false });
+                const byKind = {};
+                for (const result of built) byKind[result.kind] = documentOf(fs.readFileSync(result.file, "utf8"));
+                documents.set(target, { documents: byKind });
+            } catch (error) {
+                documents.set(target, { error });
+            }
+        }
+        return { documents, notes };
+    } finally {
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+
+module.exports = { canonical, documentOf, sameDocuments, targetDocuments };

package/src/pipeline.js

@@ -301,11 +301,15 @@ 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.
+ * it returns nothing for keeps the version its source declares. Without `verify`, the
+ * documents are not linted and their examples not checked; without `distribute`, they
+ * are copied nowhere -- which is how the version guard builds a document only to read it.
  *
  * @returns {Array<{target, kind, file, distributed}>}
  */
-function build(config, { targets, versionOf = () => null, kinds = ["openapi", "asyncapi"], log = () => {} } = {}) {
+function build(config, {
+    targets, versionOf = () => null, kinds = ["openapi", "asyncapi"], log = () => {}, verify = true, distribute: copy = true,
+} = {}) {
     // Every tool this build needs is found before anything is staged, so a toolchain
     // the installation cannot run fails the build before it has done any work.
     const needed = kinds.filter((kind) => config.targetsFor(kind).some((t) => !targets || targets.includes(t)));
@@ -355,13 +359,15 @@ function build(config, { targets, versionOf = () => null, kinds = ["openapi", "a
                 log(`-- Stamping version '${version}'`);
                 stampFile(outFile, version);
             }
-            lint(config, kind, outFile, log);
-            checkExamples(config, kind, outFile, log);
+            if (verify) {
+                lint(config, kind, outFile, log);
+                checkExamples(config, kind, outFile, log);
+            }
 
             let distributed = null;
-            if (config.isPublished(target)) {
+            if (copy && config.isPublished(target)) {
                 distributed = distribute(config, target, kind, outFile, log);
-            } else {
+            } else if (copy) {
                 log("-- Not distributed (publish: false)");
             }
             results.push({ target, kind, file: outFile, distributed });

package/src/version-guard.js

@@ -1,6 +1,6 @@
 "use strict";
 
-// A changed specification comes with a changed version.
+// A changed specification comes with a changed version, and an unchanged one does not.
 //
 // 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
@@ -8,6 +8,12 @@
 // already hold it; this guard decides it from git alone, before anything is packed, so a
 // pull request can fail on it.
 //
+// "Changed" means the documents a consumer receives changed (#121): the target is built
+// as it was released and as it is now, and the two are compared. An edit that does not
+// reach the documents needs no new version, and a new version over the same documents is
+// a warning, since it announces a change there is not. A refused target carries a hint
+// at the version it needs.
+//
 // 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
@@ -17,8 +23,8 @@ const fs = require("fs");
 const path = require("path");
 const { execFileSync } = require("child_process");
 
-const { prepare } = require("./pipeline");
-const { changedSince } = require("./changed");
+const { targetDocuments, sameDocuments } = require("./documents");
+const { bumpHint } = require("./bump-hint");
 const { versionOf, parseProperties } = require("./bundle-version");
 const { compare, isPrerelease, SEMVER } = require("./version-policy");
 
@@ -81,14 +87,17 @@ function versionAt(ref, rel, repoRoot) {
 
 /**
  * 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.
+ * documents, may not; nor one lower than what came before it. A version raised over the
+ * same documents may, with a warning.
  *
  * @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`.
+ * A target the tags do not decide, with no merge-base to compare with, is `undecided`;
+ * so is one whose documents cannot be built as they were at the baseline.
  *
- * @returns {Array<{target: string, version: string, verdict: "ok"|"violation"|"undecided", reason: string}>}
+ * @returns {Array<{target: string, version: string, verdict: "ok"|"warning"|"violation"|"undecided", reason: string,
+ *     hint: {bump: string, version: string, why: string}|null}>}
  */
 function guard(config, targets, { preRelease = null, since = null } = {}) {
     const top = tryGit(["rev-parse", "--show-toplevel"], config.root);
@@ -101,14 +110,28 @@ function guard(config, targets, { preRelease = null, since = null } = {}) {
     // 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;
+    // Each tree is built once, for every target, and only when a verdict needs it.
+    let current = null;
+    const baselines = new Map();
+    const builtAt = (ref) => {
+        if (ref === null) return current || (current = targetDocuments(config, targets, { repoRoot }));
+        if (!baselines.has(ref)) baselines.set(ref, targetDocuments(config, targets, { ref, repoRoot }));
+        return baselines.get(ref);
+    };
+    /** The target's documents now against those at `ref`: {changed, hint, note} or, when `ref` does not build, {error}. */
+    const compareWith = (ref, target, from) => {
+        const mine = builtAt(null).documents.get(target);
+        if (mine.error) throw new GuardError(`${target} could not be built from the working tree: ${mine.error.message}`);
+        const baseline = builtAt(ref);
+        const theirs = baseline.documents.get(target);
+        if (theirs.error) return { error: theirs.error };
+        const changed = !sameDocuments(theirs.documents, mine.documents);
+        return {
+            changed,
+            hint: changed ? bumpHint(theirs.documents, mine.documents, from) : null,
+            note: baseline.notes.length > 0 ? ` (${baseline.notes.join("; ")})` : "",
+        };
     };
     let fallback = null;
 
@@ -116,16 +139,23 @@ function guard(config, targets, { preRelease = null, since = null } = {}) {
         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 result = (verdict, reason, hint = null) => ({ target, version, verdict, reason, hint });
+        const ok = (reason) => result("ok", reason);
+        const warning = (reason) => result("warning", reason);
+        const undecided = (reason) => result("undecided", reason);
+        const violation = (reason, hint = null) => result("violation",
+            hint ? `${reason}; hint: ${hint.version}, a ${hint.bump} bump: ${hint.why}` : reason, hint);
+        const unbuildable = (label, error) => undecided(`${target} could not be built at ${label}: ${error.message}`);
         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}`);
+            const c = compareWith(tag, target, declared);
+            if (c.error) return unbuildable(`its release tag ${tag}`, c.error);
+            return c.changed
+                ? violation(`${version} was released as ${tag}, and ${target} has changed since${c.note}: raise the version in ${file}`, c.hint)
+                : ok(`unchanged since its release tag ${tag}${c.note}`);
         }
         if (preRelease && tags.has(declared)) {
             return violation(`${version} is a pre-release of ${declared}, which is already released as ${tags.get(declared)}: ` +
@@ -134,24 +164,38 @@ function guard(config, targets, { preRelease = null, since = null } = {}) {
         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}`);
+            const tag = tags.get(latest);
+            if (compare(declared, latest) < 0) {
+                return violation(`${declared} is lower than its latest release, ${latest} (${tag}): raise the version in ${file}`);
+            }
+            const c = compareWith(tag, target, latest);
+            if (c.error) return ok(`${declared} is above its latest release, ${latest}; not compared with it: ${c.error.message}`);
+            return c.changed
+                ? ok(`${declared} is above its latest release, ${latest}${c.note}`)
+                : warning(`${declared} is above its latest release, ${latest} (${tag}), but ${target}'s documents are ` +
+                    `the same as that release's${c.note}: a new version announces a change there is not`);
         }
 
         // 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 };
+        if (fallback.missing) return undecided(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}`);
+        const c = compareWith(fallback.ref, target, declared);
+        if (c.error) return unbuildable(fallback.label, c.error);
+        if (!c.changed) {
+            return compare(declared, before) > 0
+                ? warning(`${declared} is above ${before} at ${fallback.label}, but ${target}'s documents are unchanged ` +
+                    `since${c.note}: a new version announces a change there is not`)
+                : ok(`unchanged since ${fallback.label}${c.note}`);
+        }
+        if (compare(declared, before) > 0) return ok(`${before} -> ${declared} since ${fallback.label}${c.note}`);
         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}`);
+        return violation(`${target} changed since ${fallback.label}${c.note}, but its version is still ${declared}: ` +
+            `raise it in ${file}`, c.hint);
     });
 }