@arc-e-tect/api-only-publisher 0.7.1 → 0.8.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.7.1
+:api-only-publisher-version: 0.8.0
 
 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]
@@ -142,6 +142,10 @@ However the Publisher itself is started, it fetches them with `npx`, at the vers
 |Scaffold `apionly.yaml` and a reference directory layout that builds as it stands: OpenAPI, AsyncAPI or both.
 At a terminal it asks for each value first, as <<init,Scaffolding a library §>> describes.
 
+|`config [section] [--yes] [value flags]`
+|Reconfigure a section of `apionly.yaml` that already exists -- `portfolio`, today.
+At a terminal it asks the same shape of question `init` would, offering what is already configured as each default, as <<init-additive,Adding a kind to an existing library §>> and <<aggregates,Aggregates §>> describe.
+
 |`build [--target <t>]... [--pre-release <ids>] [--openapi\|--asyncapi]`
 |Stage, substitute placeholders, bundle, stamp each published target's version, and lint.
 
@@ -303,6 +307,17 @@ $ api-only-publisher init . --yes --openapi --asyncapi --target orders
 Nothing is asked before completing `apionly.yaml`: unlike `--force`, an additive update never discards anything, so there is nothing to confirm.
 Run `init` again with the same kinds, and it reports nothing left to add.
 
+The one slot that is asked about, when it applies, is `portfolio` -- see <<aggregates,Aggregates §>> for what it configures, and why growing past one target is what makes it apply.
+
+[source,console]
+----
+$ api-only-publisher init . --yes --openapi --target payments
+Path prefix strategy for a portfolio: target-prefix or none [target-prefix]:
+Where a portfolio's generated bundle root lands, as a directory beside bundles/ [portfolios]:
+  created    specs/openapi/...
+  updated    apionly.yaml (added targets.payments.openapi, portfolio)
+----
+
 `--force` is the other tool for an apionly.yaml that differs, and it does the opposite of the additive update: it reinitialises the file wholesale, exactly as a first run with these values would write it -- any target or key it holds that these values would not produce is gone, additive or not.
 Use it to discard a customisation on purpose; use a plain `init` to add a kind without touching anything else.
 
@@ -410,31 +425,176 @@ Where that matters, promote the fragment to a contract of its own, published and
 [#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 view -- a portfolio -- used to be maintained by hand for OpenAPI: every path body already lives in a `$ref`'d fragment, so it can be one table of contents that duplicates no contract text.
+It can be written that way, but it does not follow that it should be: nothing stops it silently falling behind the members it lists, the moment a service grows an endpoint and nobody remembers the table of contents is a second place to add it.
 
-AsyncAPI cannot be written that way.
+AsyncAPI never had the choice.
 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 both are generated.
+Declare the members on the target that is the aggregate; nothing here says where its generated root lands, because that is the tool's decision, not the author's -- see <<portfolio-location,Where a generated portfolio lands §>>:
 
 [source,yaml]
 ----
-portfolio:
-  publish: false
-  asyncapi:
-    bundle: bundles/portfolio_asyncapi_structure.yaml
-    aggregate:
-      - orders
-      - payments
-    info:
-      title: Everything, together
-      version: 0.0.0
+targets:
+  orders:
+    openapi:
+      bundle: bundles/orders_openapi_structure.yaml
+  payments:
+    openapi:
+      bundle: bundles/payments_openapi_structure.yaml
+  portfolio:
+    openapi:
+      aggregate:
+        - 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.
+`info` is the aggregate's own identity; omit it and a generated one names the members instead.
+Where every member agrees, an AsyncAPI aggregate looks the same, with `asyncapi.aggregate` in place of `openapi.aggregate`.
+
+[#aggregates-merge]
+=== How members merge
+
+A repeated key across members is not always the same kind of event, so there are three modes:
+
+[cols="1,2,2", options="header"]
+|===
+|Mode |A repeat with an identical value |A repeat that differs
+
+|`unique` (the default)
+|Error.
+Ownership would be ambiguous even when both members agree, because one of the two would silently not appear in the aggregate.
+|Error.
+
+|`agree`
+|Merges silently.
+Several services publishing to one broker, or defining the same shared security scheme, is the ordinary case, not a conflict.
+|Error, naming both members.
+Members may share a definition; they may not define it differently.
+
+|`reconcile`
+|Merges silently.
+|Merges too: reported, and the first contributing member's value wins, deterministically -- an inconsistency to notice and fix, not a defect that fails the build.
+|===
+
+What each section of an OpenAPI aggregate uses:
+
+[cols="1,2", options="header"]
+|===
+|Section |Mode
+
+|`paths`
+|Prefixed with the member's target, so a repeat is unreachable in practice; `unique` regardless, so a member listed twice is still caught by name.
+
+|`tags`
+|`reconcile`, keyed by the tag's `name`.
+Two members `$ref`ing the same shared tag fragment -- the ordinary case -- are one tag in the portfolio; two members describing a tag of the same name differently are reconciled, reported, and the first wins.
+
+|`servers`
+|`agree`, the same as an AsyncAPI aggregate already used.
+
+|`security`
+|Not merged at all -- pushed down. See <<aggregates-security,Security §>>.
+
+|`components.securitySchemes`
+|`agree`. A pushed-down operation's `security` names a scheme, so the name has to mean one thing; rename one of them if two members disagree.
+
+|`components.*` (every other sub-map)
+|`agree`, per sub-map.
+|===
+
+Every operation id is prefixed with its path's member too, in PascalCase: `orders` contributes `OrdersGetOrder`, `payments` contributes `PaymentsGetOrder`, however each member itself spelled its own id.
+Two members sharing an operation id is coincidence rather than intent -- an operation id identifies an operation within its own document -- so this is not configurable.
+
+Paths and operation ids are pass-2 work: the merge above happens on what a member's bundle root shows unresolved, before the aggregate's own output is bundled, because that is the only point at which it is still known which member a path came from.
+Prefixing paths and pushing security down happen afterwards, on the aggregate's own bundled document, once every `$ref` -- the members' and its own -- has resolved into something with a name to prefix, reconcile or push onto.
+Neither pass changes a fragment: this only ever merges documents.
+
+Prefixing paths assumes path-based routing -- a gateway mapping `/orders/**` to that service.
+Where routing is by host instead, and a prefixed path would exist nowhere, `portfolio.openapi.paths: none` leaves every path exactly as its member wrote it; a repeated path is then a genuine, reachable conflict, refused by name.
+
+[#aggregates-security]
+=== Security
+
+Root-level `security` is an array of Security Requirement Objects -- an OR, where any one entry satisfies the requirement, and AND within one entry, across several schemes.
+`security: []` means explicitly nothing required.
+Operation-level `security` *replaces* the root's value; it does not merge with it.
+
+Members legitimately differ: one service requires a bearer token, another's login endpoint cannot.
+Three ways to merge that were rejected, and the one that is used:
+
+* *Union the arrays.* Looks natural, and is dangerous: because the array is OR, unioning `[{bearerAuth: []}]` with `[]` says every operation may be called with a bearer token *or with nothing*, weakening every member to its least-authenticated one.
+* *Intersect the arrays.* Wrong for the same family of reasons: it silently strips a requirement a member actually has.
+* *Require every member to agree* (`agree` mode, as `servers` uses). Safe, but different services legitimately having different authentication is normal, not a mistake, so this would make an ordinary landscape unbuildable.
+* *Push each member's root security down onto the operations it contributes* (used). Meaning is preserved exactly, per operation: the portfolio keeps no root `security`, and every operation carries its own -- its member's root, unless the operation already declared one of its own, in which case that one is left alone, since it already replaces the root.
+A member whose root is explicitly `security: []` has `[]` pushed down explicitly too, rather than left absent: absent means "inherit", and inheriting from an absent root only *coincidentally* means the same thing.
+
+The portfolio is more verbose than its members for this, which is the fair price of being accurate about each one.
+Because a YAML comment does not survive bundling -- it parses and re-serialises -- the portfolio says so twice: `info.description` gains a line, for a reader, and `x-security-note` carries the same text machine-readably.
+
+[#aggregates-never-published]
+=== An aggregate is never published
+
+A portfolio is a catalogue.
+You do not ship a catalogue; you ship the things in it, each on its own, with its own version and its own owner.
+
+* Declaring `aggregate` for a kind means the target is never published for that kind, whatever `publish` says; writing `publish: false` beside it is accepted but no longer necessary.
+* `publish: true` alongside an aggregate is refused, naming why: prefixed operation ids match no member's, so a subscriber locking one builds against a name nothing uses; the TranscriberJ names a class after `operationId`, so transcribing a portfolio makes `OrdersGetOrderOperation` where the member makes `GetOrderOperation`; and a portfolio's version answers no useful question, since it moves whenever anything anywhere moves.
+A combined surface that genuinely needs publishing is a bundle somebody authors deliberately, with its own owner and version, not a by-product of aggregation.
+* A target may not declare both `aggregate` and `bundle` for the same kind: an aggregate is generated whole, so there is no hand-written base to merge into.
+* A target aggregating one kind must aggregate every kind it declares; mixing an aggregate for one kind with a hand-written bundle for another is refused.
+Somebody who wants a hand-written AsyncAPI portfolio writes an ordinary bundle that happens to look like one, in the bundles location, as an ordinary published target -- which is then a bundle, not a portfolio, the honest description of what they made.
+* An aggregate cannot list itself, directly or through another aggregate: nesting is not supported, so listing one aggregate as another's member is refused by name.
+
+[#portfolio-location]
+=== Where a generated portfolio lands
+
+Outside the bundles directory, at the same depth: `specs/openapi/portfolios/` beside `specs/openapi/bundles/`, `specs/asyncapi/portfolios/` beside `specs/asyncapi/bundles/`.
+
+That depth matters more than it looks.
+The merged document carries each member's `$ref` strings over verbatim -- `../paths/common/RootV1.yaml` -- and those resolve correctly only from the same directory depth the member's own bundle root sat at.
+Putting the generated root anywhere else would mean rewriting every such reference, which is work with a subtle failure mode and no benefit, so the directory is fixed at that depth instead.
+
+Keeping generated portfolios out of `bundles/` also makes them visibly separate from what is hand-authored -- nothing hand-written should ever `$ref` into a portfolio, since it is regenerated, and can change shape, on every build.
+
+[#portfolio-config]
+=== Configuring a portfolio
+
+Every strategy above has a documented default and a name in `apionly.yaml`'s `portfolio` section, which is absent by default -- an aggregate with no section builds on the defaults, and needs none added to work:
+
+[source,yaml]
+----
+portfolio:
+  openapi:
+    paths: target-prefix       # target-prefix (default) | none
+    operationIds: target-prefix  # the only value today; named for room to grow
+    tags: reconcile               # the only value today
+  security: push-down             # the only value today
+  location: portfolios            # the directory name, beside bundles/, under each kind
+----
+
+Because a portfolio is regenerated on every build, changing a setting here needs no migration: the next build simply produces a different portfolio.
+
+`init` writes this section -- asking, at a terminal, about `paths` and `location` -- once a library is about to have more than one target and does not have the section yet, the same way it writes a kind's own configuration; see <<init-additive,Adding a kind to an existing library §>>.
+It never changes a section that already exists, and says so rather than passing over it in silence: `  present    portfolio (already configured; init never changes it)`.
+
+`config portfolio` is the other side of that: it always asks, offering what is already configured as each default, and always rewrites the keys it asked about, whatever else the section or the file holds:
+
+[source,console]
+----
+$ api-only-publisher config portfolio
+Path prefix strategy for a portfolio: target-prefix or none [target-prefix]: none
+Where a portfolio's generated bundle root lands, as a directory beside bundles/ [portfolios]:
+Configured portfolio: paths=none, location=portfolios
+----
+
+`--portfolio-paths` and `--portfolio-location` answer those questions from the command line, for both `init` and `config`, the same way `init`'s other value flags do.
 
 [#channels]
 == Channels
@@ -549,13 +709,21 @@ targets:
       # Relative to specs/asyncapi/; built into build/dist/orders/asyncapi.yaml.
       bundle: bundles/orders_asyncapi_structure.yaml
   portfolio:
-    publish: false     # built and linted, never published
     openapi:
-      bundle: bundles/portfolio_openapi_structure.yaml
+      # Generated, not hand-written: never a bundle, never published -- see
+      # Aggregates §, below.
+      aggregate:
+        - orders
+
+portfolio:                # absent is fine; an aggregate builds on documented defaults
+  location: portfolios    # see Aggregates §
 ----
 
 `targets` is the single source of truth for what gets built.
 
+Every key here is checked against what that level of `apionly.yaml` allows -- a `portfolio:` block that lands under `build:` by a bad indent is `unknown key 'portfolio' in build`, not a silently ignored typo.
+`channels` and `toolchain` are the two exceptions: a channel's settings depend on its type and a tool's name is whatever the author calls it, so neither has a closed vocabulary to check against.
+
 A target's `bundle` and a kind's `outputName` are the two ends of one build: the bundle root is what a document is built *from*, in the library, and `outputName` is what it is built *to*, in `<build.dist>/<target>/`.
 Every target's document of one kind has the same `outputName`; keep the defaults, `openapi.yaml` and `asyncapi.yaml`, because the Subscriber looks for exactly those names.
 

package/package.json

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

package/src/aggregate.js

@@ -2,19 +2,40 @@
 
 // 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.
+// A portfolio view used to be a hand-written OpenAPI bundle root: every path body
+// already lives in a $ref'd fragment, so a whole-landscape table of contents cost
+// one file that duplicated no contract text. It can be written that way, but it
+// does not follow that it should be: nothing stopped it silently falling behind
+// the members it was meant to list, the moment a service grew an endpoint and
+// nobody remembered the table of contents was a second place to add it.
 //
-// AsyncAPI cannot be written that way. Its operations use document-root pointers
-// -- `channel: {$ref: '#/channels/auditV1'}` -- and `#` resolves against whatever
+// AsyncAPI never had the choice. 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
+// So both are generated: 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.
+//
+// Generation happens in two passes, because a member's bundle root is read
+// *before* it is bundled -- staging only copies and substitutes placeholders --
+// and at that point almost everything in it is still a $ref pointer, not the
+// content behind it:
+//
+//   Pass 1, here, merges what is visible unresolved: paths and security schemes
+//   are keyed by a map key that is already there in the bundle root, and a
+//   member's own root-level `security` is written inline, never $ref'd. OpenAPI
+//   paths are prefixed with the member's target at this pass, because that is a
+//   plain string rewrite of the key -- it needs nothing resolved.
+//
+//   Pass 2, in pipeline.js, runs on the aggregate's own bundled output, once
+//   every $ref -- the members' and its own -- has been resolved. Only then are an
+//   operation's id, and whether it already sets its own `security`, visible at
+//   all, so that is where operation ids are prefixed, root security is pushed
+//   down onto the operations it reaches, and repeated tags are reconciled by the
+//   name inside them, which a $ref pointer to a tag fragment never shows.
 
 const fs = require("fs");
 const path = require("path");
@@ -22,40 +43,128 @@ const YAML = require("yaml");
 
 class AggregateError extends Error {}
 
+const HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+
 /**
  * Merge one section of a member's document into the aggregate.
  *
+ * Three modes, for three different expectations of what a repeated key means:
+ *
+ * `unique` (the default) treats a repeated key as ambiguous ownership, whatever
+ * it says -- ordinary for a channel, an operation or a path, where one of two
+ * identical definitions silently not appearing in the aggregate is exactly the
+ * kind of mistake this is here to catch.
+ *
  * `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.
+ * `reconcile` is for a section where members are expected to sometimes *disagree*
+ * without either being wrong -- a shared tag two members describe slightly
+ * differently is an inconsistency to fix, not a defect to fail the build over.
+ * An identical repeat merges silently, like `agree`; a differing one merges too,
+ * with the first contributing member's value kept and the disagreement reported,
+ * rather than failing the build.
+ *
+ * @returns {Array<{section: string, key: string, winner: string, loser: string}>}
+ *     one entry per reconciled disagreement, always empty outside `reconcile` mode
  */
-function mergeSection(into, from, section, member, seen, { agree = false } = {}) {
-    if (!from[section]) return;
+function mergeSection(into, from, section, member, seen, { mode = "unique", label = section } = {}) {
+    const reconciled = [];
+    if (!from[section]) return reconciled;
     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.")
-                );
+            if (identical) {
+                if (mode === "unique") {
+                    throw new AggregateError(
+                        `aggregate: '${member}' redefines ${label}.${key}, already contributed by '${previous}'. ` +
+                        "Rename it, or leave it out of the aggregate."
+                    );
+                }
+                continue;
+            }
+            if (mode === "reconcile") {
+                reconciled.push({ section, key, winner: previous, loser: member });
+                continue;
             }
-            continue;
+            throw new AggregateError(
+                `aggregate: '${member}' ${mode === "agree" ? "disagrees about" : "redefines"} ` +
+                `${label}.${key}, already contributed by '${previous}'. ` +
+                (mode === "agree"
+                    ? "Members may share a server, but not define it differently."
+                    : "Rename it, or leave it out of the aggregate.")
+            );
         }
         into[section] = into[section] || {};
         into[section][key] = value;
         seen[section] = seen[section] || {};
         seen[section][key] = member;
     }
+    return reconciled;
+}
+
+/** Merges every sub-map of `components` present in `from`, `mode` for each. */
+function mergeComponents(into, from, member, seen, mode) {
+    if (!from.components) return;
+    into.components = into.components || {};
+    seen.components = seen.components || {};
+    for (const sub of Object.keys(from.components)) {
+        into.components[sub] = into.components[sub] || {};
+        seen.components[sub] = seen.components[sub] || {};
+        mergeSection(into.components, from.components, sub, member, seen.components, { mode, label: `components.${sub}` });
+    }
+}
+
+function requireMember(config, target, kind, member) {
+    if (!config.targets[member] || !config.targets[member][kind]) {
+        throw new AggregateError(`target '${target}': aggregate member '${member}' declares no ${kind} bundle`);
+    }
+    if (config.targets[member][kind].aggregate !== undefined) {
+        throw new AggregateError(
+            `target '${target}': aggregate member '${member}' is itself an aggregate; nesting is not supported`
+        );
+    }
+}
+
+function memberDocument(config, target, kind, member) {
+    requireMember(config, target, kind, member);
+    const file = path.join(config.stagingDir(kind), config.targets[member][kind].bundle);
+    if (!fs.existsSync(file)) {
+        throw new AggregateError(`aggregate member '${member}': bundle root not found at ${file}`);
+    }
+    return YAML.parse(fs.readFileSync(file, "utf8"));
+}
+
+function membersOf(config, target, kind) {
+    const members = config.targets[target][kind].aggregate;
+    if (!Array.isArray(members) || members.length === 0) {
+        throw new AggregateError(`target '${target}': ${kind}.aggregate must list at least one target`);
+    }
+    return members;
+}
+
+/** The aggregate's own identity: its own info, or a generated stand-in naming its members. */
+function aggregateInfo(spec, target, members, forKind) {
+    return spec.info || {
+        title: `${target} (aggregate)`,
+        version: "0.0.0",
+        description: forKind === "asyncapi"
+            ? `Every event contract published across ${members.join(", ")}.`
+            : `Every API published across ${members.join(", ")}.`,
+    };
+}
+
+function writeGenerated(out, members, content) {
+    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(content)
+    );
 }
 
 /**
@@ -65,54 +174,169 @@ function mergeSection(into, from, section, member, seen, { agree = false } = {})
  */
 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 members = membersOf(config, target, "asyncapi");
 
     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"));
+        const doc = memberDocument(config, target, "asyncapi", member);
 
         merged.asyncapi = merged.asyncapi || doc.asyncapi;
-        mergeSection(merged, doc, "servers", member, seen, { agree: true });
+        mergeSection(merged, doc, "servers", member, seen, { mode: "agree" });
         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(", ")}.`,
-    };
+    merged.info = aggregateInfo(spec, target, members, "asyncapi");
 
-    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)
-    );
+    const out = config.aggregatePath(target, "asyncapi");
+    writeGenerated(out, members, merged);
     log(`-- Generated aggregate ${path.basename(out)} from ${members.join(", ")}`);
     return out;
 }
 
+/**
+ * Synthesise an aggregate OpenAPI bundle root into the staged tree.
+ *
+ * Only what a member's bundle root holds unresolved: paths (prefixed, so keys are
+ * unique by construction -- see openapiPushDown for what happens to the
+ * operations behind them once they are resolved), servers, root-level security,
+ * and every `components.*` sub-map. Tags are carried over as whatever the member
+ * declared -- usually a list of $ref pointers -- and reconciled by name in
+ * openapiPushDown, once bundling has resolved them into `{name, ...}` objects a
+ * $ref pointer never shows.
+ *
+ * @returns {string} the path of the generated bundle root
+ */
+function generateOpenApi(config, target, { log = () => {} } = {}) {
+    const spec = config.targets[target].openapi;
+    const members = membersOf(config, target, "openapi");
+    const prefixPaths = config.portfolioPathStrategy() === "target-prefix";
+
+    const merged = { openapi: null, info: null, servers: {}, tags: [], paths: {}, components: {} };
+    const seen = {};
+    // Recorded here, in pass 1, because only here is it still known which member a
+    // path came from: once paths are merged, one document can no longer tell.
+    const owners = {};
+
+    for (const member of members) {
+        const doc = memberDocument(config, target, "openapi", member);
+
+        merged.openapi = merged.openapi || doc.openapi;
+        mergeSection(merged, doc, "servers", member, seen, { mode: "agree" });
+        mergeComponents(merged, doc, member, seen, "agree");
+        if (Array.isArray(doc.tags)) merged.tags.push(...doc.tags);
+
+        const prefixed = {};
+        for (const [rawPath, item] of Object.entries(doc.paths || {})) {
+            prefixed[prefixPaths ? `/${member}${rawPath}` : rawPath] = item;
+        }
+        mergeSection(merged, { paths: prefixed }, "paths", member, seen);
+        for (const finalPath of Object.keys(prefixed)) {
+            owners[finalPath] = { member, security: doc.security };
+        }
+    }
+    if (Object.keys(merged.components).length === 0) delete merged.components;
+    if (merged.tags.length === 0) delete merged.tags;
+
+    merged.info = aggregateInfo(spec, target, members, "openapi");
+
+    const out = config.aggregatePath(target, "openapi");
+    writeGenerated(out, members, merged);
+    log(`-- Generated aggregate ${path.basename(out)} from ${members.join(", ")}`);
+    return { out, owners };
+}
+
+const SECURITY_NOTE =
+    "Each member's own root-level `security` has been moved onto the operations it contributes " +
+    "-- see each operation's own `security`, and `components.securitySchemes` for what each scheme requires.";
+
+/**
+ * Pass 2: what generateOpenApi could not do until its own output was bundled.
+ * Run on `text` -- the aggregate's *bundled* document -- after every $ref, the
+ * members' and its own, has been resolved.
+ *
+ * - Every operation id is prefixed with its path's member, the same way the path
+ *   itself already was, so two members sharing an operation id -- coincidence,
+ *   not intent -- cannot collide in the portfolio.
+ * - Every member's root-level `security` -- explicit `[]` included -- becomes
+ *   every operation it contributes to's own `security`, unless the operation
+ *   already set one; the portfolio itself keeps no root `security`. See the
+ *   Security section of the README for why: union and intersection are both
+ *   unsound merges of a security requirement, and requiring every member to
+ *   agree would make a landscape where they legitimately differ unbuildable.
+ *   Where anything was pushed down, `info.description` and `x-security-note`
+ *   both say so -- a comment would not survive bundling, so neither carries this.
+ * - Two members contributing the same tag name are one tag; an identical body
+ *   merges silently, a differing one is reported and the first contributor's
+ *   body wins, deterministically.
+ *
+ * Edits the document in place -- `YAML.parseDocument`, never a parse and
+ * re-stringify -- so everything this pass does not touch keeps the bundler's own
+ * formatting exactly, the same reason version.js splices rather than re-emits.
+ *
+ * @returns {{text: string, reconciled: Array<{section: string, key: string}>}}
+ */
+function openapiPushDown(text, owners, { operationIdStrategy = "target-prefix" } = {}) {
+    const doc = YAML.parseDocument(text);
+    const plain = doc.toJS();
+    let pushedDown = false;
+
+    for (const [pathKey, item] of Object.entries(plain.paths || {})) {
+        const owner = owners[pathKey];
+        if (!owner || !item || typeof item !== "object") continue;
+        for (const httpMethod of HTTP_METHODS) {
+            const op = item[httpMethod];
+            if (!op || typeof op !== "object") continue;
+            if (op.operationId && operationIdStrategy === "target-prefix") {
+                doc.setIn(["paths", pathKey, httpMethod, "operationId"], `${pascalCase(owner.member)}${op.operationId}`);
+            }
+            if (op.security === undefined && owner.security !== undefined) {
+                doc.setIn(["paths", pathKey, httpMethod, "security"], owner.security);
+                pushedDown = true;
+            }
+        }
+    }
+
+    if (pushedDown) {
+        const description = doc.getIn(["info", "description"]);
+        doc.setIn(["info", "description"], description ? `${description}\n\n${SECURITY_NOTE}` : SECURITY_NOTE);
+        doc.setIn(["x-security-note"], SECURITY_NOTE);
+    }
+
+    const reconciled = [];
+    if (Array.isArray(plain.tags)) {
+        const byName = new Map();
+        const order = [];
+        for (const tag of plain.tags) {
+            const existing = byName.get(tag.name);
+            if (existing === undefined) {
+                byName.set(tag.name, tag);
+                order.push(tag.name);
+                continue;
+            }
+            if (JSON.stringify(existing) !== JSON.stringify(tag)) {
+                reconciled.push({ section: "tags", key: tag.name });
+            }
+            // The first contributor's body wins either way -- identical or not.
+        }
+        doc.setIn(["tags"], order.map((name) => byName.get(name)));
+    }
+
+    return { text: doc.toString(), reconciled };
+}
+
+/** A target name, in PascalCase: user-account -> UserAccount. */
+function pascalCase(target) {
+    return target.split(/[-_]/).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+
 function isAggregate(config, target, kind) {
     const spec = config.targets[target][kind];
     return Boolean(spec && spec.aggregate);
 }
 
-module.exports = { generateAsyncApi, isAggregate, AggregateError };
+module.exports = {
+    generateAsyncApi, generateOpenApi, openapiPushDown, isAggregate, mergeSection, pascalCase, AggregateError,
+};