@arc-e-tect/api-only-publisher 0.1.0 → 0.3.0

package/README.adoc

@@ -11,64 +11,63 @@ 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.
+[NOTE]
+.Where the links in this document go
+====
+Every link ends with a marker saying where it leads, so you can tell before you follow it:
+
+[horizontal]
+`↗`:: An *external* site, outside this repository.
+`→`:: *Another file* in this repository.
+`§`:: *A section of this same file.*
+====
 
 // 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.
+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]
 == What it is
 
-`api-only-publisher` turns a library of small, reusable API description
-fragments into one complete, self-contained document per target, and distributes
-each to whoever needs it.
-
-It is the producer half of a pair. The consumer half, `API-Only Subscriber`,
-fetches a published document into an implementation project and verifies that it
-has not drifted. The two are coupled only by the published artifact and its
-manifest -- neither knows anything else about the other.
-
-A *target* is whatever gets its own contract document: a microservice, a modular
-monolith, a backend-for-frontend, or a documentation aggregate spanning all of
-them. It need not be a deployable, which is why this is not called `services`.
-
-== Why it is not a shell script
+`api-only-publisher` turns a library of small, reusable API description fragments into one complete, self-contained document per target, and distributes each to whoever needs it.
 
-It was one, and the shell showed through in three places.
+It is the producer half of a pair.
+The consumer half, the link:../api-only-subscriber/README.adoc[API-Only Subscriber →], fetches a published document into an implementation project and verifies that it has not drifted.
+The two are coupled only by the published artifact and its manifest; neither knows anything else about the other.
 
-The target list was a plain Bash array with a comment explaining that it avoided
-associative arrays for the Bash 3.2 that macOS still ships. Both scripts carried
-a write-to-a-temp-file-and-move dance to work around the difference between BSD
-and GNU `sed -i`. And neither could parse YAML, which is why setting a version
-was a regular expression that silently did nothing when it failed to match.
+A *target* is whatever gets its own contract document: a microservice, a modular monolith, a backend-for-frontend, or a documentation aggregate spanning all of them.
+It need not be a deployable, which is why this is not called `services`.
 
-Node was never an optional dependency either: `@redocly/cli` and `@asyncapi/cli`
-are Node tools, so a Node runtime was already required to run the pipeline at all.
+This document is the reference for the Publisher alone.
+To set it up for your situation, start at link:../docs/README.adoc[the documentation →].
 
+[#requirements]
 == Requirements
 
 [cols="1,1",options="header"]
 |===
 | Requirement | Version
-| Node        | 22 +
-| npm         | 10 +
+| Node.js     | `^22.14.0`, `^24.10.0` or `>=26.0.0`
+| npm         | The one that comes with Node.js
 |===
 
-Nothing else. The bundlers are fetched by `npx` at the versions `apionly.yaml`
-pins, so they need no installation, and the only runtime dependency is `yaml`.
+Nothing else.
+The bundlers, https://redocly.com/docs/cli/[Redocly CLI ↗] and https://www.asyncapi.com/tools/cli[AsyncAPI CLI ↗], are fetched by `npx` at the versions `apionly.yaml` pins, so they need no installation, and the only runtime dependency is `yaml`.
 
+[#installation]
 == Installation
 
 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]
 === As a development dependency
 
-The better fit for a specification library, and for any build that runs the Publisher more than once.
+The fit for a specification library, and for any build that runs the Publisher more than once.
 
 [source,console]
 ----
@@ -93,7 +92,7 @@ npm install --save-dev --save-exact @arc-e-tect/api-only-publisher
 ----
 npm ci
 npm run apionly -- build
-npm run apionly -- publish --target user-account
+npm run apionly -- publish --target orders
 ----
 
 * The version is pinned in one place, `package.json`, and every command and every CI job runs that one.
@@ -102,9 +101,13 @@ npm run apionly -- publish --target user-account
 * 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.
 
+Run it through the script, as `npm run apionly -- <command>`.
+`npx api-only-publisher`, without the scope, is not this package: npx would look that name up on the public registry.
+
+[#with-npx]
 === With `npx`, installing nothing
 
-The better fit for trying the tool, for scaffolding a library with `init`, and for a one-off command.
+The fit for trying the tool, for scaffolding a library with `init`, and for a one-off command.
 
 [source,console]
 ----
@@ -118,98 +121,90 @@ npx @arc-e-tect/api-only-publisher@<version> build -C my-api-library
 * 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.
+A published contract should change only when its fragments or its version change, and a floating tool version lets it change without either.
 
 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]
 == Commands
 
 [cols="1,3", options="header"]
 |===
 |Command |Purpose
 
-|`init [dir]`
-|Scaffold `apionly.yaml` and a reference directory layout that builds as it
-stands. This is how the *conventions* become reusable, as opposed to the code.
+|`init [dir] [--force]`
+|Scaffold `apionly.yaml` and a reference directory layout that builds as it stands.
 
-|`build`
-|Stage, substitute placeholders, bundle, stamp each published target's version, lint, and distribute.
+|`build [--target <t>]... [--pre-release <ids>] [--openapi\|--asyncapi]`
+|Stage, substitute placeholders, bundle, stamp each published target's version, and lint.
 
-|`lint`
-|Lint what is already built, without rebuilding, for fast local feedback.
+|`lint [--target <t>]...`
+|Lint what is already built, without rebuilding, and write a report per document.
+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.
+|List the declared targets, what each one builds, and whether it is published.
 
-|`closure`
-|Show each target's dependency closure: how many files it reaches, and the hash
-of their content.
+|`closure [--target <t>]...`
+|Show each target's dependency closure: how many files it reaches, and the hash of their content.
 
 |`changed --since <ref>`
-|Report which targets' closures actually changed since a git ref. This is what
-drives a release: a target whose closure is untouched is not released, however
-much else in the repository moved.
+|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.
 
-|`pack`
+|`pack [--pre-release <ids>] [--target <t>]... [--out <dir>]`
 |Archive each built, published target with a `manifest.json`, at the version its version file declares.
 
-|`publish`
-|Pack once, then ship those same bytes to every configured channel.
+|`publish [--pre-release <ids>] [--target <t>]... [--channel <c>]... [--out <dir>]`
+|Pack once, then ship those same bytes to every configured channel, or to each `--channel`.
 
-|`split --out <dir>`
+|`split --out <dir> [--by kind\|target]`
 |Make the library safe to break into separate repositories.
 |===
 
+`--target` and `--channel` may be repeated.
+`-C <dir>` runs as if started in `<dir>`; without it the configuration is found by walking up from the current directory.
+`-q` or `--quiet` reports only errors, which is what a script that reads the output wants.
+`--pre-release <ids>` appends pre-release identifiers to each target's version, as <<versions,Versions §>> describes.
+
 [source,console]
 ----
-api-only-publisher init my-api-library
-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
+npm run apionly -- build --target orders --openapi
+npm run apionly -- publish --target orders --pre-release rc.1
+npm run apionly -- changed --since origin/main --quiet
 ----
 
-`--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
+[#what-build-does]
+== What `build` does
 
-. **Stage.** The whole source root is copied to `build/staging/<type>/`. Nothing
-after this point touches the hand-authored tree.
+. **Stage.** The whole source root is copied to `<build.staging>/<kind>/`.
+Nothing after this point touches the hand-authored tree.
 +
-The *whole* root, not just one specification type's subtree, because the trees
-`$ref` each other -- event schemas reuse the OpenAPI common schemas, so a
-username means the same thing over Kafka as over HTTP. A partial copy breaks
-those references. Each type gets *its own* staging root, so building one never
-invalidates the other's staged tree.
+The *whole* root, not just one specification kind's subtree, because the trees `$ref` each other: an event schema can reuse an OpenAPI component schema, so a field means the same thing in an event as in an HTTP response.
+A partial copy breaks those references.
+Each kind gets *its own* staging root, so building one never invalidates the other's staged tree.
 
-. **Substitute placeholders**, in place, across the staged copy. A `{{token}}`
-is replaced with the contents of `<token>.md`, found by searching the staged
-root. Indentation is preserved, so multi-line Markdown stays valid inside an
-indented YAML scalar.
+. **Substitute placeholders**, in place, across the staged copy.
+A `{{token}}` is replaced with the contents of `<token>.md`, found by searching the staged source root.
+Indentation is preserved, so multi-line Markdown stays valid inside an indented YAML scalar.
 
-. **Bundle.** `@redocly/cli bundle` or `@asyncapi/cli bundle` resolves every
-`$ref` into one flat, self-contained document under `dist/<target>/`.
+. **Bundle.** `@redocly/cli bundle` or `@asyncapi/cli bundle` resolves every `$ref` into one flat, self-contained document under `<build.dist>/<target>/`.
 
 . **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.
+. **Lint** the finished document, so a broken fragment surfaces against the target it actually affects.
 
-. **Distribute**, unless the target is `publish: false`.
-
-[[versions]]
+[#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
+.specs/openapi/bundles/orders.bundle.properties
 [source,properties]
 ----
-# The version of the user-account contract, for every document it builds.
+# The version of the orders 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
@@ -235,79 +230,61 @@ 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.
 
+[#closure]
 == Independent versioning, and the dependency closure
 
-Giving each target its own version has one non-obvious consequence, and the
-`closure` and `changed` commands are what pay for it.
+Giving each target its own version has one non-obvious consequence, and the `closure` and `changed` commands are what pay for it.
 
-A change under `components/common/` affects every target that reaches it. A
-change under one service's own context affects only that one. Under
-repository-wide versioning the distinction is invisible, because everything bumps
-together; under per-target versioning the release job has to know the difference,
-or one service's edit releases every other service and the version numbers stop
-meaning anything.
+A change under `components/common/` affects every target that reaches it.
+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 commit actually touched:
+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:
 
 [source,console]
 ----
-api-only-publisher changed --since origin/main
+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.
+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.
 
-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.
+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.
 
+[#splitting]
 == Splitting the library
 
-A fragment library is one `$ref` graph, and that graph does not respect the
-directory boundaries a repository split would follow. Here, the AsyncAPI event
-schemas reuse `openapi/components/common/schemas/UsernameV1.yaml` -- a username
-means the same thing over Kafka as over HTTP. Move the two trees into separate
-repositories as they stand and every one of those references dangles.
+A fragment library is one `$ref` graph, and that graph does not respect the directory boundaries a repository split would follow.
+When the AsyncAPI documents reuse `openapi/components/common/schemas/`, moving the two trees into separate repositories as they stand leaves every one of those references dangling.
 
 [source,console]
 ----
-api-only-publisher split --out build/split --by kind
+npm run apionly -- split --out build/split --by kind
 ----
 
-Each part is written with its own subtree *plus* a copy of every foreign file it
-reaches, so that afterwards each side is self-contained and builds on its own.
-The copies keep their original path relative to the shared source root, which is
-what makes this safe: every relative `$ref` keeps resolving exactly as it did, so
-nothing is rewritten and no reference can break because a rewrite got the depth
-wrong.
+Each part is written with its own subtree *plus* a copy of every foreign file it reaches, so that afterwards each side is self-contained and builds on its own.
+The copies keep their original path relative to the shared source root, which is what makes this safe: every relative `$ref` keeps resolving exactly as it did, so nothing is rewritten and no reference can break because a rewrite got the depth wrong.
 
-`--by kind` splits along the specification types. `--by target` gives every
-target its own self-contained tree, which is what you want before splitting into
-per-service repositories.
+`--by kind` splits along the specification kinds.
+`--by target` gives every target its own self-contained tree, which is what you want before splitting into per-target repositories.
 
-Any part that received copies gets an `IMPORTED.adoc` listing them and saying
-plainly what it costs: those copies can now drift, and nothing will notice. A
-shared schema that two repositories both define is two schemas that happen to
-agree today. Where that matters, promote the fragment to a contract of its own,
-published and consumed like any other, rather than copied.
+Any part that received copies gets an `IMPORTED.adoc` listing them and saying plainly what it costs: those copies can now drift, and nothing will notice.
+A shared schema that two repositories both define is two schemas that happen to agree today.
+Where that matters, promote the fragment to a contract of its own, published and consumed like any other, rather than copied.
 
+[#aggregates]
 == Aggregates
 
-A whole-landscape OpenAPI view is just another bundle root: every path body
-already lives in a `$ref`'d fragment, so a portfolio costs one hand-written
-table of contents and duplicates no contract text.
+A whole-landscape OpenAPI view is just another bundle root: every path body already lives in a `$ref`'d fragment, so a portfolio costs one hand-written table of contents and duplicates no contract text.
 
-AsyncAPI cannot be written that way. Its operations use document-root pointers
-(`channel: {$ref: '#/channels/auditV1'}`), and `#` resolves against whichever file
-contains it, so moving an operation into a fragment breaks it. A hand-written
-async portfolio would have to copy every operation verbatim, and that copy would
-start rotting the moment a member changed.
+AsyncAPI cannot be written that way.
+Its operations use document-root pointers (`channel: {$ref: '#/channels/orderPlacedV1'}`), and `#` resolves against whichever file contains it, so moving an operation into a fragment breaks it.
+A hand-written async portfolio would have to copy every operation verbatim, and that copy would start rotting the moment a member changed.
 
-So it is generated instead. Declare the members and the aggregate's own identity:
+So it is generated instead.
+Declare the members and the aggregate's own identity:
 
 [source,yaml]
 ----
@@ -316,17 +293,17 @@ portfolio:
   asyncapi:
     bundle: portfolio_asyncapi_structure.yaml
     aggregate:
-      - user-account
+      - orders
+      - payments
     info:
       title: Everything, together
       version: 0.0.0
 ----
 
-The bundle root is synthesised into the staging tree immediately before bundling,
-so nothing is duplicated in the source and the view cannot fall behind its
-members. Two members contributing the same channel or operation key is an error
-rather than a silent overwrite.
+The bundle root is synthesised into the staging tree immediately before bundling, so nothing is duplicated in the source and the view cannot fall behind its members.
+Two members contributing the same channel or operation key is an error rather than a silent overwrite.
 
+[#channels]
 == Channels
 
 [cols="1,3", options="header"]
@@ -335,74 +312,63 @@ rather than a silent overwrite.
 
 |`file`
 |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.
+Not a distribution mechanism between repositories: it makes the pipeline testable end to end with no infrastructure, lets a library share one build with the projects that implement it, and is a local-iteration escape hatch.
 Publishing a version again 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
-real remote. Native for Gradle consumers: version resolution, caching and
-conflict handling come free, which is what lets the Subscriber carry no HTTP
-client of its own.
+|A path publishes into a repository layout on disk; an `http(s)` URL deploys to a remote repository with an HTTP `PUT` per file and a bearer token.
+Native for Gradle consumers: version resolution, caching and conflict handling come free, which is what lets the Subscriber carry no HTTP client of its own.
 
 |`npm`
-|Real semver, integrity hashes for free, private scopes available, and the
-toolchain here is already Node.
+|Real semver, integrity hashes, private scopes, and a toolchain that is already Node.js.
 
 |`github-release`
-|The language-neutral floor: immutable per tag, works for private repositories
-with a token, readable by a consumer with no JVM and no Node. No
-dependency-resolution semantics and no update notification, which is why it is
-the fallback rather than the default.
+|The language-neutral floor: immutable per tag, works for private repositories with a token, readable by a consumer with no JVM and no Node.js.
+No dependency-resolution semantics and no update notification, which is why it is the fallback rather than the default.
 |===
 
 Credentials are read from the environment, never from configuration.
-`channels.maven.tokenEnv` names the variable; a configuration file gets
-committed, and a credential in a committed file is a credential that has leaked.
+`channels.maven.tokenEnv` names the variable, `MAVEN_TOKEN` by default; a configuration file gets committed, and a credential in a committed file is a credential that has leaked.
+
+link:../docs/reference/how-publisher-and-subscriber-work-together.adoc#channels[How the Publisher and the Subscriber work together →] lists each channel's layout and options.
 
+[#why-registries]
 === Why npm and Maven rather than release assets alone
 
-Publishing is passive. The producer releases `2.1.0` and nothing happens in an
-implementation repository until somebody looks.
+Publishing is passive.
+The producer releases `2.1.0` and nothing happens in an implementation repository until somebody looks.
 
-Renovate and Dependabot understand npm and Maven natively, so a contract bump
-arrives downstream as a pull request without any bespoke machinery. That is the
-practical argument for preferring them, and the reason to design the coordinates
-so that standard update bots can read them.
+Renovate and Dependabot understand npm and Maven natively, so a contract bump arrives downstream as a pull request without any bespoke machinery.
+That is the practical argument for preferring them, and the reason to design the coordinates so that standard update bots can read them.
 
+[#pre-releases]
 == Pre-releases
 
-API-Only design means implementation starts against a contract that is not
-finished. If the only way to obtain a bundle were a final release, teams would
-work around the tool by cloning the specification repository -- which is exactly
-the broad read access that publishing artifacts exists to avoid, with none of the
-guarantees.
+API-first design means implementation starts against a contract that is not finished.
+If the only way to obtain a bundle were a final release, teams would work around the tool by cloning the specification repository, which is exactly the broad read access that publishing artifacts exists to avoid, with none of the 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.
+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:
+The hard rule is the other half of it.
+A pre-release must never quietly satisfy a production build:
 
-* npm publishes it under the `next` dist-tag, never `latest`, so `npm install`
-cannot pick one up by accident.
-* A GitHub release is marked as a pre-release, so "latest release" never resolves
-to an unfinished contract.
-* The API-Only Subscriber refuses a pre-release version outright unless the
-subscription sets `allowPrerelease = true` -- a visible, reviewable line in a
-build file rather than a default.
+* npm publishes it under the `next` dist-tag, never `latest`, so `npm install` cannot pick one up by accident.
+* A GitHub release is marked as a pre-release, so "latest release" never resolves to an unfinished contract.
+* The API-Only Subscriber refuses a pre-release version outright unless the subscription sets `allowPrerelease = true`: a visible, reviewable line in a build file rather than a default.
 
+[#configuration]
 == Configuration
 
-Everything project-specific lives in `apionly.yaml`, not in the code. Adapting
-the tool to another project means editing configuration.
+Everything project-specific lives in `apionly.yaml`, not in the code.
+Adapting the tool to another project means editing configuration.
 
 [source,yaml]
 ----
 schemaVersion: 1
 
 sources:
-  root: specs          # staged wholesale; the types share fragments
+  root: specs          # staged wholesale; the kinds share fragments
   openapi: openapi
   asyncapi: asyncapi
 
@@ -417,9 +383,11 @@ defaults:
 
 build:
   staging: build/staging
-  dist: dist
+  dist: build/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"
@@ -431,68 +399,82 @@ channels:
     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
+  orders:
+    # versionFile: versions/orders.properties
+    #              default: orders.bundle.properties beside the first bundle root
     openapi:
-      bundle: bundles/user-account_openapi_structure.yaml
+      bundle: bundles/orders.yaml
     asyncapi:
-      bundle: user-account_asyncapi_structure.yaml
+      bundle: orders_asyncapi.yaml
   portfolio:
-    publish: false     # built and linted, never distributed
+    publish: false     # built and linted, never published
     openapi:
-      bundle: bundles/portfolio_openapi_structure.yaml
+      bundle: bundles/portfolio.yaml
 ----
 
-`targets` is the single source of truth for what gets built. It replaced the
-per-script target arrays and the `apis:` map in `redocly.yaml`, which said
-overlapping things in two places under two different names.
+`targets` is the single source of truth for what gets built.
 
+[#pinning-the-bundlers]
 === Pinning the bundlers
 
-`toolchain` pins the bundler versions. Unpinned, the documents this tool produces
-could change because an upstream release happened, with nothing in the library
-having changed -- which makes any claim that a refactoring preserved output
-unfalsifiable. An upgrade should be a deliberate commit that moves the pin and
-the expected output together.
+`toolchain` pins the bundler versions.
+Unpinned, the documents this tool produces could change because an upstream release happened, with nothing in the library having changed.
+An upgrade should be a deliberate commit that moves the pin, reviewed with whatever it changes in the published documents.
 
+[#behaviour]
 == Behaviour worth knowing about
 
+[#unresolved-placeholders]
 === Unresolved placeholders fail the build
 
-The tool this absorbed emitted the literal string `*MISSING CONTENT*` into the
-document and carried on with a warning, so a broken contract could ship from a
-green build. An unresolved `{{token}}` is now an error. Set
-`defaults.placeholders.strict: false` to get the old leniency, in which case the
-token is left visible rather than replaced with a marker.
+An unresolved `{{token}}` is an error, so a broken contract cannot ship from a green build.
+Set `defaults.placeholders.strict: false` to leave the token visible in the document instead.
 
+[#placeholder-search]
 === Placeholder snippets are found from the source root
 
-The absorbed tool searched downward from the *input file's own directory*, never
-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.
+`<token>.md` is searched for from the staged source root downwards, so a snippet can live anywhere under it.
+
+[#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 `<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.
+
+Configuration is not a fragment, so it may sit anywhere, `sources.root` included.
+The check skips the well-known configuration files of lint tools, wherever they are: `redocly.yaml`, `.redocly.yaml`, `.redocly.lint-ignore.yaml`, `.spectral.yaml`, `.spectral.yml`, and `apionly.yaml`.
+It also skips the lint configurations `defaults.<kind>.lint` names, whatever they are called.
+Any other YAML file under the source root counts.
 
+`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]
 === Version stamping edits one scalar
 
-`info.version` is located structurally and that one scalar is spliced. It is
-deliberately not a re-serialisation: re-emitting a document reformats everything
-around the edit, because the AsyncAPI CLI wraps long descriptions at a width no
-YAML emitter reproduces. Splicing keeps every other byte exactly as the bundler
-wrote it. A document with no `info` block, or no version inside it, is an error.
+`info.version` is located structurally and that one scalar is spliced.
+It is deliberately not a re-serialisation: re-emitting a document reformats everything around the edit, because the AsyncAPI CLI wraps long descriptions at a width no YAML emitter reproduces.
+Splicing keeps every other byte exactly as the bundler wrote it.
+A document with no `info` block, or no version inside it, is an error.
 
+[#distribution]
 === `distribution` is transitional
 
-A producer has no business knowing the directory layout of the projects that
-consume it. The `distribution` block exists so that a specification library can
-adopt this tool without every consumer changing at the same time. The API-Only
-Subscriber replaces it: each consuming project declares where its own copy lands,
-and the block goes away.
+A producer has no business knowing the directory layout of the projects that consume it.
+The `distribution` block copies built documents into such a layout, so that a library can adopt this tool before its consumers adopt the API-Only Subscriber.
+Once they subscribe, each consuming project declares where its own copy lands, and the block goes away.
 
+[#adapting]
 == Adapting it to another project
 
-The tool has no dependency on any particular product, framework or directory
-layout. In order of what usually needs changing:
+The tool has no dependency on any particular product, framework or directory layout.
+In order of what usually needs changing:
 
 [cols="2,3", options="header"]
 |===
@@ -505,7 +487,7 @@ layout. In order of what usually needs changing:
 |`sources`
 
 |What each document is called
-|`defaults.<type>.outputName`
+|`defaults.<kind>.outputName`
 
 |The lint rules
 |`defaults.openapi.lint`
@@ -514,7 +496,7 @@ layout. In order of what usually needs changing:
 |`reports.lint`, defaulting to `build/reports/lint/<target>/<kind>.txt`
 
 |Where built documents go
-|`build.dist`, and `distribution` while it still exists
+|`build.dist`
 
 |Where artifacts are published
 |`channels`
@@ -523,37 +505,30 @@ layout. In order of what usually needs changing:
 |Its version file, or `targets.<target>.versionFile`
 |===
 
-Beyond that: the `common/` versus `<product>/<target>/` split is one convention
-for organising a multi-target fragment library, not a requirement. A single-target
-project can keep every fragment in one flat directory, or skip fragments entirely
-and hand-author one complete document. The tool only needs one bundle root file
-per target; what that file `$ref`s, or whether it `$ref`s anything at all, is
-entirely up to the library.
+Beyond that, a `components/common/` directory beside per-target directories is one convention for organising a multi-target fragment library, not a requirement.
+A single-target project can keep every fragment in one flat directory, or skip fragments entirely and hand-author one complete document.
+The tool only needs one bundle root file per target; what that file `$ref`s, or whether it `$ref`s anything at all, is up to the library.
 
-Placeholders are optional too. A library with no `{{token}}` anywhere simply has
-nothing substituted.
+Placeholders are optional too.
+A library with no `{{token}}` anywhere simply has nothing substituted.
 
+[#breaking-changes]
 == Breaking changes
 
-The tool does not police them. `changed` tells a release job which targets a
-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.
+The tool does not police them.
+`changed` tells a release which targets a 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 for what counts as breaking.
 
-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.
-
+[#as-a-library]
 == Using it as a library
 
-Everything the CLI does is available programmatically, so a release job that
-wants to decide something for itself does not have to parse console output:
+Everything the CLI does is available programmatically, so a release job that wants to decide something for itself does not have to parse console output:
 
 [source,javascript]
 ----
-const { loadFrom, prepare, forTargets, changedSince } =
+const { loadFrom, prepare, changedSince } =
     require('@arc-e-tect/api-only-publisher');
 
 const config = loadFrom('.');
@@ -566,19 +541,20 @@ for (const result of changedSince(config, 'origin/main')) {
 }
 ----
 
+[#exit-codes]
 == Exit codes
 
 [cols="1,3",options="header"]
 |===
 | Code | Meaning
 | `0`  | Success.
-| `1`  | A handled failure: bad configuration, an unresolved placeholder, a
-         document that cannot be stamped, a dangling `$ref`, a channel that
-         refused the artifact. The message says which.
+| `1`  | A handled failure: bad configuration, an unresolved placeholder, a document that cannot be stamped, a dangling `$ref`, a lint failure, a channel that refused the artifact.
+The message says which.
 |===
 
 Anything else is a bug; please report it.
 
+[#tests]
 == Tests
 
 [source,console]
@@ -586,32 +562,22 @@ Anything else is a bug; please report it.
 npm test
 ----
 
-Covers placeholder substitution (including each of the three defects fixed on
-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,
-byte for byte, from the ones the pipeline produced before it existed.
+Covers every module and every command: placeholder substitution, version stamping, version files, configuration parsing, closures, packing, channels, splitting, and the scaffold.
+`build.e2e.test.js` runs the real bundlers.
+The run fails below 90% of lines and functions, or 80% of branches.
 
+[#relationship]
 == Relationship to the API-Only Subscriber
 
-This half publishes; link:../api-only-subscriber/README.adoc[the Subscriber]
-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].
+This half publishes; link:../api-only-subscriber/README.adoc[the Subscriber →] 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.
+
+* link:../docs/README.adoc[The documentation →] helps you pick the use case that fits, with a tutorial and AI prompts for each.
+* link:../docs/reference/how-publisher-and-subscriber-work-together.adoc[How the Publisher and the Subscriber work together →] maps every setting, command and check across the two tools, and says where a change to either belongs.
+* link:../docs/reference/run-book.adoc[The run-book →] covers operating both, and every failure message.
 
+[#license]
 == License
 
-MIT. See link:LICENSE[LICENSE].
+MIT.
+See link:LICENSE[LICENSE →].

package/package.json

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

package/src/cli.js

@@ -15,6 +15,7 @@ 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
 
@@ -162,26 +163,61 @@ async function main(argv) {
         }
         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, {
-                        report: true,
-                        reportFile: config.lintReport(target, kind),
-                    });
+                    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": {

package/src/config.js

@@ -2,9 +2,8 @@
 
 // Reading and validating apionly.yaml.
 //
-// The configuration is the single source of truth for what this library builds:
-// it replaced the per-script SERVICES arrays, and the `apis:` map that said an
-// overlapping thing under a different name.
+// The configuration is the single source of truth for what a library builds:
+// which targets exist, where their fragments live, and where each document goes.
 
 const fs = require("fs");
 const path = require("path");
@@ -93,6 +92,7 @@ function load(configPath) {
         toolchain: parsed.toolchain || {},
         build: parsed.build || {},
         reports: parsed.reports || {},
+        lint: parsed.lint || {},
         distribution: parsed.distribution || null,
         channels: parsed.channels || {},
         targets,
@@ -126,6 +126,21 @@ function load(configPath) {
             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}`);
         },

package/src/index.js

@@ -14,6 +14,7 @@ module.exports = {
     ...require("./version-policy"),
     ...require("./bundle-version"),
     ...require("./closure"),
+    ...require("./unreferenced"),
     ...require("./aggregate"),
     ...require("./pipeline"),
     ...require("./pack"),

package/src/pipeline.js

@@ -55,12 +55,8 @@ function stage(config, kind, log) {
 /**
  * Substitute placeholders across the staged tree, in place.
  *
- * Every YAML file is visited rather than only the bundle roots and info.yaml.
- * The tool this replaces read only the one file it was handed, which is why the
- * shared info block had to be preprocessed as a separate up-front step and why
- * bundles had to $ref a generated merged_info.yaml instead of the file they
- * meant. Visiting the staged tree removes that special case: a placeholder works
- * wherever it is written.
+ * Every YAML file is visited, not only the bundle roots, so a placeholder works
+ * wherever it is written, and no file has to be preprocessed separately first.
  */
 function substituteTree(config, kind, log) {
     const stagingRoot = config.stagingRoot(kind);

package/src/placeholders.js

@@ -2,21 +2,17 @@
 
 // Placeholder substitution.
 //
-// Absorbed from sedr_utils/openapi/prep_openapi's preprocess_openapi.js, with
-// three defects fixed rather than inherited:
+// A {{token}} in a staged YAML file is replaced by the contents of <token>.md.
+// Three choices here are deliberate:
 //
-//   1. Search scope. The original searched for <placeholder>.md recursively
-//      downward from the *input file's own directory*, never from the -d
-//      argument the caller passed. The workaround was to move the Markdown
-//      files next to whatever referenced them, and the gotcha had to be
-//      documented. The search root is now a parameter, defaulting to the source
-//      root the caller actually named.
-//   2. Failure mode. A missing Markdown file produced a warning and the literal
-//      string *MISSING CONTENT* in the output, so a broken document shipped from
-//      a green build. Unresolved placeholders are now an error by default.
-//   3. Token grammar. The pattern \{\{(\w+)\}\} silently excluded '-' and '.'
-//      from placeholder names, so {{status-codes}} was left in the output rather
-//      than reported. The grammar now admits them.
+//   1. Search scope. <token>.md is searched for from the root the caller names,
+//      the staged source root by default, not from the directory of the file
+//      holding the token, so a snippet can live anywhere under that root.
+//   2. Failure mode. An unresolved placeholder is an error by default. Leaving a
+//      marker in the document and carrying on would let a broken contract ship
+//      from a green build.
+//   3. Token grammar. Names may contain '-' and '.', so {{status-codes}} is a
+//      placeholder like any other, never text silently left in the output.
 
 const fs = require("fs");
 const path = require("path");
@@ -103,9 +99,8 @@ function substitute(text, { searchRoot, strict = true, describeAs = "input" } =
 }
 
 /**
- * Substitute a file in place. Unlike the tool this replaces, nothing named
- * merged_* is left behind: the file is rewritten where it stands, which is safe
- * because it is always a staged copy.
+ * Substitute a file in place. The file is rewritten where it stands and nothing
+ * is written beside it, which is safe because it is always a staged copy.
  */
 function substituteFile(file, options) {
     const before = fs.readFileSync(file, "utf8");

package/src/split.js

@@ -4,10 +4,10 @@
 //
 // The problem it solves is real and easy to miss. A fragment library is one $ref
 // graph, and that graph does not respect the directory boundaries a repository
-// split would follow. In this library the AsyncAPI event schemas reuse
-// `openapi/components/common/schemas/UsernameV1.yaml`, so a username means the
-// same thing over Kafka as over HTTP. Move the two trees into separate
-// repositories as they stand and every one of those references dangles.
+// split would follow. An AsyncAPI event schema that reuses an OpenAPI common
+// schema -- a username, say -- means the same thing over a message broker as over
+// HTTP, and that reuse is a reference across the two trees. Move the trees into
+// separate repositories as they stand and every such reference dangles.
 //
 // `split` resolves each part's dependency closure and materialises it whole:
 // each part gets its own subtree *plus* a copy of every foreign file it reaches,

package/src/unreferenced.js

@@ -0,0 +1,72 @@
+"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("/");
+
+// Configuration files of the tools an API library is linted with, and this tool's
+// own. They are YAML, but they describe how to check an API, not the API, so they
+// are never fragments, wherever they sit and whether or not apionly.yaml names them.
+const TOOL_CONFIGS = new Set([
+    "apionly.yaml",
+    "redocly.yaml",
+    ".redocly.yaml",
+    ".redocly.lint-ignore.yaml",
+    ".spectral.yaml",
+    ".spectral.yml",
+]);
+
+/**
+ * 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.
+ *
+ * Configuration is not a fragment: neither the well-known configuration files of
+ * lint tools, nor the lint configuration apionly.yaml names, whatever it is called.
+ *
+ * @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();
+    const own = new Set(["openapi", "asyncapi"]
+        .map((kind) => config.lintConfig(kind))
+        .filter(Boolean)
+        .map((file) => portable(path.relative(sourceRoot, file))));
+    return yamlFiles(sourceRoot)
+        .map((file) => portable(path.relative(sourceRoot, file)))
+        .filter((file) => !reached.has(file) && !own.has(file) && !TOOL_CONFIGS.has(path.posix.basename(file)))
+        .sort();
+}
+
+module.exports = { unreferenced };

package/src/version.js

@@ -2,12 +2,10 @@
 
 // Setting info.version on a bundled document.
 //
-// This replaces two different sed expressions, which between them differed per
-// specification type (OpenAPI quoted the version, AsyncAPI did not), did nothing
-// at all when the pattern missed, and could match a `version:` field elsewhere in
-// the document.
-//
-// The field is located structurally and only that one scalar is spliced. It is
+// A pattern-based substitution would have to differ per specification type,
+// would silently do nothing when its pattern missed, and could match a
+// `version:` field elsewhere in the document. So the field is located
+// structurally, and only that one scalar is spliced. It is
 // deliberately not a re-serialisation: re-emitting the document reformats
 // everything around the edit, because the AsyncAPI CLI wraps long descriptions at
 // a width no YAML emitter reproduces. Splicing keeps every other byte exactly as