@arc-e-tect/api-only-publisher 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iwan Eising
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.adoc

@@ -0,0 +1,498 @@
+= API-Only Publisher
+:toc: left
+:toc-title: Contents
+:toclevels: 2
+:icons: font
+:source-highlighter: rouge
+
+image:https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml/badge.svg[Vulnerability Scan,link=https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml]
+image:https://img.shields.io/npm/v/@arc-e-tect/api-only-publisher[npm,link=https://www.npmjs.com/package/@arc-e-tect/api-only-publisher]
+image:https://img.shields.io/github/v/release/Arc-E-Tect/SoftwareEngineeringDoneRight-API?filter=api-only-publisher-v*[GitHub release,link=https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/releases?q=api-only-publisher]
+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]
+
+== 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
+
+It was one, and the shell showed through in three places.
+
+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.
+
+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.
+
+== Requirements
+
+[cols="1,1",options="header"]
+|===
+| Requirement | Version
+| Node        | 22 +
+| npm         | 10 +
+|===
+
+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`.
+
+== Installation
+
+As a command, without installing anything:
+
+[source,console]
+----
+npx @arc-e-tect/api-only-publisher build
+----
+
+As a dependency of a specification library:
+
+[source,console]
+----
+npm install --save-dev @arc-e-tect/api-only-publisher
+----
+
+Pin it exactly rather than with a range. This tool's output is expected to be
+reproducible — a specification library's golden fixtures assert it byte for byte
+— and a floating version quietly breaks that guarantee.
+
+== 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.
+
+|`build`
+|Stage, substitute placeholders, bundle, stamp the version, lint, and distribute.
+
+|`lint`
+|Lint what is already built, without rebuilding, for fast local feedback.
+
+|`targets`
+|List the declared targets, what each one builds, and whether it is distributed.
+
+|`closure`
+|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.
+
+|`pack --version <v>`
+|Archive each built target with a `manifest.json`.
+
+|`publish --version <v>`
+|Pack once, then ship those same bytes to every configured channel.
+
+|`split --out <dir>`
+|Make the library safe to break into separate repositories.
+|===
+
+[source,console]
+----
+api-only-publisher init my-api-library
+api-only-publisher build -C my-api-library --version 2.3.1
+api-only-publisher build --target user-account --openapi
+api-only-publisher targets
+----
+
+`--target` may be repeated. `-C <dir>` runs as if started in `<dir>`; without it
+the configuration is found by walking up from the current directory.
+
+== What `build` actually does
+
+. **Stage.** The whole source root is copied to `build/staging/<type>/`. 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.
+
+. **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.
+
+. **Bundle.** `@redocly/cli bundle` or `@asyncapi/cli bundle` resolves every
+`$ref` into one flat, self-contained document under `dist/<target>/`.
+
+. **Stamp the version**, if `--version` was given, on the *finished* document.
+
+. **Lint** the finished document, so a broken fragment surfaces against the
+target it actually affects rather than at deploy time.
+
+. **Distribute**, unless the target is `publish: false`.
+
+== 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.
+
+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 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:
+
+[source,console]
+----
+api-only-publisher 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.
+
+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 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.
+
+[source,console]
+----
+api-only-publisher 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.
+
+`--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.
+
+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
+
+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.
+
+So it is generated instead. Declare the members and the aggregate's own identity:
+
+[source,yaml]
+----
+portfolio:
+  publish: false
+  asyncapi:
+    bundle: portfolio_asyncapi_structure.yaml
+    aggregate:
+      - user-account
+    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.
+
+== Channels
+
+[cols="1,3", options="header"]
+|===
+|Channel |What it is for
+
+|`file`
+|A local directory. Not a distribution mechanism -- it exists so the pipeline is
+testable end to end with no infrastructure, and as a local-iteration escape
+hatch afterwards.
+
+|`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.
+
+|`npm`
+|Real semver, integrity hashes for free, private scopes available, and the
+toolchain here is already Node.
+
+|`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.
+|===
+
+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.
+
+=== 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.
+
+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
+
+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.
+
+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.
+
+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.
+
+== 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
+  openapi: openapi
+  asyncapi: asyncapi
+
+defaults:
+  openapi:
+    lint: .redocly.yaml
+    outputName: openapi.yaml
+  asyncapi:
+    outputName: asyncapi.yaml
+  placeholders:
+    strict: true       # an unresolved {{token}} fails the build
+
+build:
+  staging: build/staging
+  dist: dist
+
+toolchain:
+  redocly: "@redocly/cli@2.52.0"
+  asyncapi: "@asyncapi/cli@6.0.2"
+
+targets:
+  user-account:
+    openapi:
+      bundle: bundles/user-account_openapi_structure.yaml
+    asyncapi:
+      bundle: user-account_asyncapi_structure.yaml
+  portfolio:
+    publish: false     # built and linted, never distributed
+    openapi:
+      bundle: bundles/portfolio_openapi_structure.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.
+
+=== 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.
+
+== Behaviour worth knowing about
+
+=== 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.
+
+=== 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.
+
+=== 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.
+
+=== `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.
+
+== 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:
+
+[cols="2,3", options="header"]
+|===
+|What |Where
+
+|Which documents get built
+|`targets`
+
+|Where the fragments live
+|`sources`
+
+|What each document is called
+|`defaults.<type>.outputName`
+
+|The lint rules
+|`defaults.openapi.lint`
+
+|Where built documents go
+|`build.dist`, and `distribution` while it still exists
+
+|Where artifacts are published
+|`channels`
+|===
+
+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.
+
+Placeholders are optional too. A library with no `{{token}}` anywhere simply has
+nothing substituted.
+
+== 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.
+
+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.
+
+== 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:
+
+[source,javascript]
+----
+const { loadFrom, prepare, forTargets, changedSince } =
+    require('@arc-e-tect/api-only-publisher');
+
+const config = loadFrom('.');
+prepare(config);
+
+for (const result of changedSince(config, 'origin/main')) {
+    if (result.changed) {
+        console.log(`${result.target} changed: ${result.files.join(', ')}`);
+    }
+}
+----
+
+== 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.
+|===
+
+Anything else is a bug; please report it.
+
+== Tests
+
+[source,console]
+----
+npm test
+----
+
+Covers placeholder substitution (including each of the three defects fixed on
+the way in), version stamping, configuration parsing, 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.
+
+== 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.
+
+== License
+
+MIT. See link:LICENSE[LICENSE].

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@arc-e-tect/api-only-publisher",
+  "version": "0.0.0",
+  "description": "Builds, packs and publishes API description documents from a library of reusable fragments.",
+  "license": "MIT",
+  "author": "Arc-E-Tect",
+  "homepage": "https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/tree/main/api-only-publisher",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API.git",
+    "directory": "api-only-publisher"
+  },
+  "bugs": {
+    "url": "https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/issues"
+  },
+  "keywords": [
+    "openapi",
+    "asyncapi",
+    "api-first",
+    "api-only",
+    "contract",
+    "specification",
+    "publish"
+  ],
+  "type": "commonjs",
+  "main": "src/index.js",
+  "bin": {
+    "api-only-publisher": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.adoc"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test --experimental-test-coverage --test-coverage-lines=90 --test-coverage-functions=90 --test-coverage-branches=80 test/*.test.js",
+    "test:quick": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^11.0.1",
+    "@semantic-release/github": "^12.0.9",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "semantic-release": "^25.0.9"
+  },
+  "engines": {
+    "node": "^22.14.0 || ^24.10.0 || >=26.0.0"
+  }
+}

package/src/aggregate.js

@@ -0,0 +1,118 @@
+"use strict";
+
+// Generated aggregate bundles.
+//
+// A portfolio view of the OpenAPI surface is just another bundle root: every
+// path body already lives in a $ref'd fragment, so a whole-landscape table of
+// contents costs one hand-written file that duplicates no contract text.
+//
+// AsyncAPI cannot be written that way. Its operations use document-root pointers
+// -- `channel: {$ref: '#/channels/auditV1'}` -- and `#` resolves against whatever
+// file contains it, so moving an operation into a fragment breaks it. A
+// hand-written async portfolio would therefore have to copy every operation
+// verbatim, and that copy would start rotting the moment a member changed.
+//
+// So it is generated instead: the aggregate's bundle root is synthesised into the
+// staged tree from its members, immediately before bundling. Nothing is
+// duplicated in the source, and the view cannot fall behind its members.
+
+const fs = require("fs");
+const path = require("path");
+const YAML = require("yaml");
+
+class AggregateError extends Error {}
+
+/**
+ * Merge one section of a member's document into the aggregate.
+ *
+ * `agree` marks sections where members are expected to say the same thing.
+ * Several services publishing to one broker all declare that broker, and that is
+ * the ordinary case rather than a conflict -- so an identical definition merges
+ * silently and only a genuine disagreement is an error.
+ *
+ * Everywhere else a repeated key is an error even when the definitions match,
+ * because it makes ownership ambiguous: two members both defining a channel means
+ * one of them would silently not appear in the aggregate.
+ */
+function mergeSection(into, from, section, member, seen, { agree = false } = {}) {
+    if (!from[section]) return;
+    for (const [key, value] of Object.entries(from[section])) {
+        const previous = seen[section] && seen[section][key];
+        if (previous) {
+            const identical = JSON.stringify(into[section][key]) === JSON.stringify(value);
+            if (!agree || !identical) {
+                throw new AggregateError(
+                    `aggregate: '${member}' ${agree && !identical ? "disagrees about" : "redefines"} ` +
+                    `${section}.${key}, already contributed by '${previous}'. ` +
+                    (agree
+                        ? "Members may share a server, but not define it differently."
+                        : "Rename it, or leave it out of the aggregate.")
+                );
+            }
+            continue;
+        }
+        into[section] = into[section] || {};
+        into[section][key] = value;
+        seen[section] = seen[section] || {};
+        seen[section][key] = member;
+    }
+}
+
+/**
+ * Synthesise an aggregate AsyncAPI bundle root into the staged tree.
+ *
+ * @returns {string} the path of the generated bundle root
+ */
+function generateAsyncApi(config, target, { log = () => {} } = {}) {
+    const spec = config.targets[target].asyncapi;
+    const members = spec.aggregate;
+    if (!Array.isArray(members) || members.length === 0) {
+        throw new AggregateError(`target '${target}': asyncapi.aggregate must list at least one target`);
+    }
+
+    const merged = { asyncapi: null, info: null, servers: {}, channels: {}, operations: {} };
+    const seen = {};
+
+    for (const member of members) {
+        if (!config.targets[member] || !config.targets[member].asyncapi) {
+            throw new AggregateError(
+                `target '${target}': aggregate member '${member}' declares no asyncapi bundle`
+            );
+        }
+        const file = path.join(config.stagingDir("asyncapi"), config.targets[member].asyncapi.bundle);
+        if (!fs.existsSync(file)) {
+            throw new AggregateError(`aggregate member '${member}': bundle root not found at ${file}`);
+        }
+        const doc = YAML.parse(fs.readFileSync(file, "utf8"));
+
+        merged.asyncapi = merged.asyncapi || doc.asyncapi;
+        mergeSection(merged, doc, "servers", member, seen, { agree: true });
+        mergeSection(merged, doc, "channels", member, seen);
+        mergeSection(merged, doc, "operations", member, seen);
+    }
+
+    // The aggregate's own identity, not any member's.
+    merged.info = spec.info || {
+        title: `${target} (aggregate)`,
+        version: "0.0.0",
+        description: `Every event contract published across ${members.join(", ")}.`,
+    };
+
+    const out = path.join(config.stagingDir("asyncapi"), spec.bundle);
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.writeFileSync(
+        out,
+        `# GENERATED by api-only-publisher from: ${members.join(", ")}\n` +
+        `# Do not edit, and do not commit: it is rebuilt into the staging tree on every build.\n` +
+        YAML.stringify(merged)
+    );
+    log(`-- Generated aggregate ${path.basename(out)} from ${members.join(", ")}`);
+    return out;
+}
+
+function isAggregate(config, target, kind) {
+    const spec = config.targets[target][kind];
+    return Boolean(spec && spec.aggregate);
+}
+
+module.exports = { generateAsyncApi, isAggregate, AggregateError };