@arc-e-tect/api-only-publisher 0.7.1 → 0.8.0

package/src/cli.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 "use strict";
 
+const fs = require("fs");
 const path = require("path");
+const YAML = require("yaml");
 
 const { loadFrom, ConfigError } = require("./config");
 const { build, prepare, BuildError } = require("./pipeline");
 const { init, scaffold, plan } = require("./init");
 const { resolveValues } = require("./init-questions");
+const { resolvePortfolioValues, writePortfolioSection } = require("./config-command");
 const { PlaceholderError } = require("./placeholders");
 const { VersionError } = require("./version");
 const { forTargets, ClosureError } = require("./closure");
@@ -26,6 +29,8 @@ Usage:
                           [--contact-name <text>] [--contact-url <url>]
                           [--license <spdx-id>] [--license-url <url>]
                           [--server-url <url>] [--broker-host <host[:port]>]
+  api-only-publisher config [section] [--yes] [--portfolio-paths <target-prefix|none>]
+                            [--portfolio-location <dir>]
   api-only-publisher build [--target <name>]... [--pre-release <ids>] [--openapi|--asyncapi]
   api-only-publisher lint  [--target <name>]...
   api-only-publisher targets
@@ -44,14 +49,16 @@ Options:
   --asyncapi        Only build AsyncAPI documents.
   --force           init only: overwrite files that differ from the scaffold;
                     at a terminal, after listing them and asking once.
-  -y, --yes         init only: ask nothing, even at a terminal; take the defaults
-                    for every value no flag gives. Without a terminal, init never asks.
+  -y, --yes         init/config only: ask nothing, even at a terminal; take the
+                    current or default value for anything no flag gives.
   --openapi, --asyncapi
                     init: the kinds of document the library holds; both flags for both.
   --target <name>   init: the target's name, in lowercase kebab-case.
   --title, --contract-version, --contact-name, --contact-url, --license,
   --license-url, --server-url, --broker-host
                     init only: the value of that question; a flag always wins.
+  --portfolio-paths <target-prefix|none>, --portfolio-location <dir>
+                    config only: the value of that question; a flag always wins.
   --since <ref>     changed only: the git ref to compare the working tree against.
   --out <dir>       pack/publish/split: where to write.
   --channel <name>  publish only: repeat for several. Default: every configured channel.
@@ -69,13 +76,14 @@ function parseArgs(argv) {
     const options = {
         targets: [], kinds: null, preRelease: null, quiet: false, force: false,
         dir: process.cwd(), since: null, out: null, channels: null, by: "kind",
-        yes: false, init: {},
+        yes: false, init: {}, config: {},
     };
     const INIT_VALUES = {
         "--title": "title", "--contract-version": "contractVersion", "--contact-name": "contactName",
         "--contact-url": "contactUrl", "--license": "license", "--license-url": "licenseUrl",
         "--server-url": "serverUrl", "--broker-host": "brokerHost",
     };
+    const CONFIG_VALUES = { "--portfolio-paths": "paths", "--portfolio-location": "location" };
     const positional = [];
 
     for (let i = 0; i < argv.length; i++) {
@@ -109,6 +117,10 @@ function parseArgs(argv) {
                     options.init[INIT_VALUES[arg]] = next();
                     break;
                 }
+                if (CONFIG_VALUES[arg]) {
+                    options.config[CONFIG_VALUES[arg]] = next();
+                    break;
+                }
                 if (arg.startsWith("-")) throw new ConfigError(`unrecognized option '${arg}'`);
                 positional.push(arg);
         }
@@ -136,6 +148,28 @@ function initKinds(kinds) {
     return kinds ? ["openapi", "asyncapi"].filter((kind) => kinds.includes(kind)) : undefined;
 }
 
+/**
+ * Whether init should ask about the portfolio section this run: "ask", once the
+ * library is about to have more than one target -- there is nothing to aggregate
+ * with just one -- and it does not have a portfolio section yet; "present" the
+ * same way, but the section is already there, which init never changes, and
+ * reports rather than silently doing nothing about; "not-yet" while there is
+ * still only one target, which is not worth mentioning at all.
+ *
+ * @returns {"ask"|"present"|"not-yet"}
+ */
+function portfolioStatus(dir, target) {
+    const file = path.join(dir, "apionly.yaml");
+    if (!fs.existsSync(file)) return "not-yet";
+    const doc = YAML.parseDocument(fs.readFileSync(file, "utf8"));
+    if (doc.errors.length > 0) return "not-yet";
+    const targets = doc.get("targets", true);
+    const names = YAML.isMap(targets) ? new Set(targets.items.map((pair) => String(pair.key))) : new Set();
+    names.add(target);
+    if (names.size <= 1) return "not-yet";
+    return doc.hasIn(["portfolio"]) ? "present" : "ask";
+}
+
 /**
  * Scaffolds a library. At a terminal, and without --yes, it asks for every value no
  * flag gives; anywhere else it takes the defaults, as it always has.
@@ -163,19 +197,36 @@ async function runInit(options, positional, io, log) {
             ask: terminal && ((question) => terminal.question(question)),
             tell: (message) => output.write(`${message}\n`),
         });
+
+        // Asked, or defaulted, the same way a kind's own questions are -- but only
+        // once there is something to aggregate. A section already there is never
+        // asked about or changed, and reported as present rather than passed over
+        // in silence.
+        const portfolioStatusThisRun = portfolioStatus(dir, values.target);
+        let portfolio = null;
+        if (portfolioStatusThisRun === "ask") {
+            portfolio = await resolvePortfolioValues({
+                given: options.config,
+                current: { paths: "target-prefix", location: "portfolios" },
+                ask: terminal && ((question) => terminal.question(question)),
+                tell: (message) => output.write(`${message}\n`),
+            });
+        }
+
         log(`Scaffolding a specification library in ${dir}`);
         let force = options.force;
         if (terminal && force) {
             // Asked, --force means "after showing me": it overwrites what differs only
             // once the list has been seen and agreed to.
-            const differing = plan(dir, scaffold(values), values).filter((entry) => entry.status === "differs");
+            const differing = plan(dir, scaffold(values), values, portfolio).filter((entry) => entry.status === "differs");
             if (differing.length > 0) {
                 output.write(`These files differ from the scaffold:\n${differing.map((d) => `  ${d.rel}\n`).join("")}`);
                 const answer = await terminal.question(`Overwrite these ${differing.length} file(s)? [y/N] `);
                 force = /^y(es)?$/i.test(answer.trim());
             }
         }
-        init(dir, { values, force, log });
+        init(dir, { values, force, log, portfolio });
+        if (portfolioStatusThisRun === "present") log("  present    portfolio (already configured; init never changes it)");
         log(`\nNext: api-only-publisher build -C ${dir}`);
     } finally {
         if (terminal) terminal.close();
@@ -183,6 +234,50 @@ async function runInit(options, positional, io, log) {
     return 0;
 }
 
+const CONFIGURABLE_SECTIONS = ["portfolio"];
+
+/**
+ * Reconfigures a section of apionly.yaml. Unlike init, this always asks -- at a
+ * terminal, each question shows what is already configured, or the documented
+ * default when there is nothing yet, and Enter keeps it -- and always rewrites
+ * the keys it asked about, whatever else the section or the file holds.
+ */
+async function runConfig(options, positional, io, log) {
+    const section = positional[1];
+    if (section !== undefined && !CONFIGURABLE_SECTIONS.includes(section)) {
+        throw new ConfigError(
+            `'${section}' is not a configurable section; there is: ${CONFIGURABLE_SECTIONS.join(", ")}`
+        );
+    }
+    const config = loadFrom(options.dir);
+    const input = io.input || process.stdin;
+    const output = io.output || process.stdout;
+    const interactive = io.interactive !== undefined ? io.interactive : Boolean(input.isTTY && output.isTTY);
+    const terminal = interactive && !options.yes
+        ? require("node:readline/promises").createInterface({ input, output })
+        : null;
+    try {
+        for (const name of section ? [section] : CONFIGURABLE_SECTIONS) {
+            // The only configurable section today; a second one gets its own current
+            // values, its own given-flags and its own writer, called the same way.
+            const current = { paths: config.portfolioPathStrategy(), location: config.portfolioLocation() };
+            const given = { ...options.config };
+            for (const key of Object.keys(given)) if (given[key] === undefined) delete given[key];
+
+            const values = await resolvePortfolioValues({
+                given, current,
+                ask: terminal && ((question) => terminal.question(question)),
+                tell: (message) => output.write(`${message}\n`),
+            });
+            fs.writeFileSync(config.path, writePortfolioSection(fs.readFileSync(config.path, "utf8"), values));
+            log(`Configured ${name}: paths=${values.paths}, location=${values.location}`);
+        }
+    } finally {
+        if (terminal) terminal.close();
+    }
+    return 0;
+}
+
 async function main(argv, io = {}) {
     const { options, positional } = parseArgs(argv);
     const command = positional[0];
@@ -195,6 +290,7 @@ async function main(argv, io = {}) {
     const log = options.quiet ? () => {} : (message) => console.log(message);
 
     if (command === "init") return runInit(options, positional, io, log);
+    if (command === "config") return runConfig(options, positional, io, log);
 
     const config = loadFrom(options.dir);
     const targets = options.targets.length > 0 ? options.targets : null;
@@ -236,7 +332,6 @@ async function main(argv, io = {}) {
             // Lint without rebuilding, for fast local feedback on what is already
             // 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;

package/src/closure.js

@@ -104,7 +104,7 @@ function forTargets(config, kinds = ["openapi", "asyncapi"], only = null) {
     for (const kind of kinds) {
         for (const target of config.targetsFor(kind)) {
             if (only && !only.includes(target)) continue;
-            const entry = config.bundlePath(target, kind);
+            const entry = config.bundleRootPath(target, kind);
             if (!fs.existsSync(entry)) {
                 throw new ClosureError(
                     `target '${target}': ${kind} bundle root not found at ${entry}; stage the tree first`

package/src/config-command.js

@@ -0,0 +1,100 @@
+"use strict";
+
+// The `config` command's one section so far: `portfolio`.
+//
+// `init` only ever adds this section when it is missing (init-config.js);
+// reconfiguring what is already there is this file's job instead, and it works
+// the opposite way on purpose -- it always asks, offering what is already
+// configured as each default, and always rewrites the keys it asked about.
+//
+// A second configurable section extends this the same way a second kind
+// extended init-config.js's slots: its own question list, its own current()
+// reader and its own writer, called from the same `config` command. Nothing here
+// is written as a registry ahead of that need -- there is exactly one section
+// today, and one small module reads more easily than an abstraction for a
+// second case that does not exist yet.
+
+const YAML = require("yaml");
+const { ConfigError } = require("./config");
+
+const PATH_STRATEGIES = ["target-prefix", "none"];
+
+/** The portfolio section's questions, in the order they are asked. */
+const QUESTIONS = [
+    {
+        key: "paths", flag: "--portfolio-paths",
+        text: "Path prefix strategy for a portfolio: target-prefix or none",
+        check: (v) => (PATH_STRATEGIES.includes(v) ? null : `use ${PATH_STRATEGIES.join(" or ")}`),
+    },
+    {
+        key: "location", flag: "--portfolio-location",
+        text: "Where a portfolio's generated bundle root lands, as a directory beside bundles/",
+        check: (v) => (v.trim() ? null : "it may not be empty"),
+    },
+];
+
+/**
+ * Resolves the portfolio section's values: a flag always wins. At a terminal,
+ * each question shows `current`'s value for it in brackets -- the section's own,
+ * if it has one, or the documented default when it does not -- and Enter keeps
+ * it; without a terminal, that same value is taken as given, exactly as if it
+ * had been typed.
+ *
+ * @param {object} options
+ * @param {object} [options.given] values given as flags, by key; never asked
+ * @param {object} options.current the value each question defaults to
+ * @param {function(string): Promise<string>} [options.ask] shows a question, resolves to the answer
+ * @param {function(string): void} [options.tell] shows why an answer was refused
+ * @returns {Promise<object>} the resolved values, one per question
+ * @throws {ConfigError} when a flag's value is invalid
+ */
+async function resolvePortfolioValues({ given = {}, current, ask = null, tell = () => {} } = {}) {
+    const values = {};
+    for (const question of QUESTIONS) {
+        const flagged = given[question.key];
+        if (flagged !== undefined) {
+            const problem = question.check(flagged);
+            if (problem) throw new ConfigError(`${question.flag} ${problem}`);
+            values[question.key] = flagged;
+            continue;
+        }
+        const fallback = current[question.key];
+        if (!ask) {
+            values[question.key] = fallback;
+            continue;
+        }
+        const prompt = `${question.text} [${fallback}]: `;
+        for (;;) {
+            const text = (await ask(prompt)).trim();
+            if (!text) {
+                values[question.key] = fallback;
+                break;
+            }
+            const problem = question.check(text);
+            if (!problem) {
+                values[question.key] = text;
+                break;
+            }
+            tell(problem);
+        }
+    }
+    return values;
+}
+
+/**
+ * Writes `values` into apionly.yaml's portfolio section, wholesale for the keys
+ * asked about and untouched everywhere else: a hand-set portfolio.openapi.tags,
+ * for one, is not something `config portfolio` asked about, so it survives.
+ * YAML.parseDocument, never a parse and restringify -- the file's comments, and
+ * every value this did not ask about, are not this command's to change.
+ *
+ * @returns {string} the edited text
+ */
+function writePortfolioSection(text, values) {
+    const doc = YAML.parseDocument(text);
+    doc.setIn(["portfolio", "openapi", "paths"], values.paths);
+    doc.setIn(["portfolio", "location"], values.location);
+    return doc.toString();
+}
+
+module.exports = { resolvePortfolioValues, writePortfolioSection, QUESTIONS };

package/src/config.js

@@ -12,8 +12,52 @@ const YAML = require("yaml");
 const CONFIG_NAME = "apionly.yaml";
 const SUPPORTED_SCHEMA_VERSION = 1;
 
+// The keys allowed at the levels of apionly.yaml that have a fixed shape. `channels`
+// and `toolchain` are deliberately absent: 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. Everywhere else, a key nothing reads is far more
+// often a typo or a bad indent than a value nobody has used yet -- see checkKeys.
+const ROOT_KEYS = [
+    "schemaVersion", "sources", "defaults", "build", "reports", "lint",
+    "distribution", "channels", "targets", "toolchain", "portfolio",
+];
+const SOURCES_KEYS = ["root", "openapi", "asyncapi"];
+const DEFAULTS_KEYS = ["openapi", "asyncapi", "placeholders"];
+const DEFAULTS_KIND_KEYS = { openapi: ["lint", "outputName", "fragmentPaths"], asyncapi: ["lint", "outputName", "fragmentPaths"] };
+const PLACEHOLDERS_KEYS = ["strict"];
+const BUILD_KEYS = ["staging", "dist"];
+const REPORTS_KEYS = ["lint"];
+const LINT_KEYS = ["unreferenced"];
+const DISTRIBUTION_KEYS = ["root", "layout"];
+const TARGET_KEYS = ["openapi", "asyncapi", "publish", "versionFile"];
+const TARGET_KIND_KEYS = ["bundle", "aggregate", "info"];
+const PORTFOLIO_KEYS = ["openapi", "security", "location"];
+const PORTFOLIO_OPENAPI_KEYS = ["paths", "operationIds", "tags"];
+
+// What every portfolio setting is when apionly.yaml says nothing: safe for the
+// ordinary case (a gateway routing /<target>/** to each service), and named rather
+// than boolean, so a third strategy can be added later without breaking the schema.
+// Because a portfolio is regenerated on every build, none of this needs a migration
+// when it changes -- the next build simply produces a different portfolio.
+const PORTFOLIO_DEFAULTS = Object.freeze({
+    openapi: Object.freeze({ paths: "target-prefix", operationIds: "target-prefix", tags: "reconcile" }),
+    security: "push-down",
+    location: "portfolios",
+});
+const PATH_STRATEGIES = ["target-prefix", "none"];
+
 class ConfigError extends Error {}
 
+/** Refuses a key `obj` has that is not in `allowed`, naming the key and where it is. */
+function checkKeys(obj, allowed, where) {
+    if (!obj || typeof obj !== "object") return;
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key)) {
+            throw new ConfigError(`unknown key '${key}' in ${where}`);
+        }
+    }
+}
+
 // Walk up from `startDir` looking for apionly.yaml, so the CLI can be run from
 // anywhere inside the specification repository.
 function locate(startDir) {
@@ -57,10 +101,38 @@ function load(configPath) {
         );
     }
 
+    checkKeys(parsed, ROOT_KEYS, CONFIG_NAME);
+
     const root = path.dirname(configPath);
     const sources = parsed.sources || {};
+    checkKeys(sources, SOURCES_KEYS, "sources");
     requireString(sources.root, "sources.root");
 
+    const defaults = parsed.defaults || {};
+    checkKeys(defaults, DEFAULTS_KEYS, "defaults");
+    for (const kind of ["openapi", "asyncapi"]) {
+        if (defaults[kind]) checkKeys(defaults[kind], DEFAULTS_KIND_KEYS[kind], `defaults.${kind}`);
+    }
+    if (defaults.placeholders) checkKeys(defaults.placeholders, PLACEHOLDERS_KEYS, "defaults.placeholders");
+
+    const build = parsed.build || {};
+    checkKeys(build, BUILD_KEYS, "build");
+    const reports = parsed.reports || {};
+    checkKeys(reports, REPORTS_KEYS, "reports");
+    const lint = parsed.lint || {};
+    checkKeys(lint, LINT_KEYS, "lint");
+    if (parsed.distribution) checkKeys(parsed.distribution, DISTRIBUTION_KEYS, "distribution");
+
+    const portfolio = parsed.portfolio || {};
+    checkKeys(portfolio, PORTFOLIO_KEYS, "portfolio");
+    if (portfolio.openapi) checkKeys(portfolio.openapi, PORTFOLIO_OPENAPI_KEYS, "portfolio.openapi");
+    const pathStrategy = portfolio.openapi && portfolio.openapi.paths;
+    if (pathStrategy !== undefined && !PATH_STRATEGIES.includes(pathStrategy)) {
+        throw new ConfigError(
+            `portfolio.openapi.paths must be ${PATH_STRATEGIES.join(" or ")}, not ${JSON.stringify(pathStrategy)}`
+        );
+    }
+
     const targets = parsed.targets;
     if (!targets || typeof targets !== "object" || Object.keys(targets).length === 0) {
         throw new ConfigError(`${configPath} declares no targets`);
@@ -72,14 +144,84 @@ function load(configPath) {
         if (!target || typeof target !== "object") {
             throw new ConfigError(`target '${name}' is not a mapping`);
         }
+        checkKeys(target, TARGET_KEYS, `targets.${name}`);
         const kinds = ["openapi", "asyncapi"].filter((k) => target[k]);
         if (kinds.length === 0) {
             throw new ConfigError(
                 `target '${name}' declares neither an openapi nor an asyncapi bundle`
             );
         }
+
+        // A portfolio is a catalogue, never a contract of its own: declaring an
+        // aggregate for one kind means the target IS a portfolio, so it must
+        // aggregate every kind it declares, and it is never published.
+        const aggregateKinds = kinds.filter((k) => target[k].aggregate !== undefined);
+        if (aggregateKinds.length > 0 && aggregateKinds.length !== kinds.length) {
+            const bundled = kinds.find((k) => target[k].aggregate === undefined);
+            throw new ConfigError(
+                `target '${name}' aggregates ${aggregateKinds[0]} but has a hand-written bundle for ${bundled}; ` +
+                "a target may not mix an aggregate with a hand-written bundle across kinds -- a hand-written " +
+                "AsyncAPI portfolio is an ordinary bundle, not an aggregate that happens to look like one"
+            );
+        }
+        if (aggregateKinds.length > 0 && target.publish === true) {
+            throw new ConfigError(
+                `target '${name}' declares an aggregate; it is never published, whatever publish says. ` +
+                "Prefixed operation ids match no member's, transcribed classes would not match a member's " +
+                "either, 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 -- author one instead."
+            );
+        }
+
         for (const kind of kinds) {
-            requireString(target[kind].bundle, `targets.${name}.${kind}.bundle`);
+            checkKeys(target[kind], TARGET_KIND_KEYS, `targets.${name}.${kind}`);
+            if (target[kind].aggregate !== undefined) {
+                if (target[kind].bundle !== undefined) {
+                    throw new ConfigError(
+                        `target '${name}' declares both aggregate and bundle for ${kind}; an aggregate is ` +
+                        "generated whole, so it needs no hand-written bundle root"
+                    );
+                }
+                const members = target[kind].aggregate;
+                if (!Array.isArray(members) || members.length === 0) {
+                    throw new ConfigError(`targets.${name}.${kind}.aggregate must list at least one target`);
+                }
+                if (members.includes(name)) {
+                    throw new ConfigError(`target '${name}' aggregates itself`);
+                }
+            } else {
+                requireString(target[kind].bundle, `targets.${name}.${kind}.bundle`);
+                if (target[kind].info !== undefined) {
+                    throw new ConfigError(`targets.${name}.${kind}.info only applies to an aggregate`);
+                }
+            }
+        }
+    }
+
+    // Every member an aggregate lists is checked by name, and a member that is
+    // itself an aggregate is refused outright: it has no hand-written bundle for
+    // the generator to read, and reading its *generated* one would mean generating
+    // aggregates in dependency order, which nothing here attempts. Because an
+    // aggregate can only ever reach a hand-written bundle this way, refusing that
+    // one step also catches every transitive self-reference, not only the direct
+    // one the loop above already refused.
+    for (const [name, target] of Object.entries(targets)) {
+        for (const kind of ["openapi", "asyncapi"].filter((k) => target[k] && target[k].aggregate !== undefined)) {
+            for (const member of target[kind].aggregate) {
+                const memberTarget = targets[member];
+                if (!memberTarget || memberTarget[kind] === undefined) {
+                    throw new ConfigError(
+                        `target '${name}': aggregate member '${member}' declares no ${kind} bundle`
+                    );
+                }
+                if (memberTarget[kind].aggregate !== undefined) {
+                    throw new ConfigError(
+                        `target '${name}' aggregates '${member}', which is itself an aggregate; ` +
+                        "nesting is not supported"
+                    );
+                }
+            }
         }
     }
 
@@ -88,13 +230,14 @@ function load(configPath) {
         root,
         schemaVersion: parsed.schemaVersion,
         sources,
-        defaults: parsed.defaults || {},
+        defaults,
         toolchain: parsed.toolchain || {},
-        build: parsed.build || {},
-        reports: parsed.reports || {},
-        lint: parsed.lint || {},
+        build,
+        reports,
+        lint,
         distribution: parsed.distribution || null,
         channels: parsed.channels || {},
+        portfolio,
         targets,
 
         // --- derived accessors, so callers never re-derive a path themselves ---
@@ -148,19 +291,79 @@ function load(configPath) {
         targetsFor(kind) {
             return Object.keys(this.targets).filter((t) => this.targets[t][kind]);
         },
+        // Whether this target is itself an aggregate, for any kind it declares.
+        // load() already refuses a target that aggregates one kind and hand-writes
+        // another, so any one kind answers for the whole target.
+        isAggregate(target) {
+            return ["openapi", "asyncapi"].some((k) => this.targets[target][k] && this.targets[target][k].aggregate !== undefined);
+        },
         // A target with `publish: false` is a documentation view rather than a
         // contract any one project implements: built and linted, never shipped.
+        // An aggregate is never published either, whether or not it says so --
+        // load() already refuses the one case that would contradict this, `publish:
+        // true` alongside an aggregate, so nothing here needs to re-check that.
         isPublished(target) {
-            return this.targets[target].publish !== false;
+            return this.targets[target].publish !== false && !this.isAggregate(target);
         },
         // A target's bundle root in a staged tree: the build's own, unless another
-        // staged copy is named.
+        // staged copy is named. Only a hand-written bundle has one; an aggregate's
+        // generated root is aggregatePath(), below.
         bundlePath(target, kind, stagingRoot = this.stagingRoot(kind)) {
             return path.join(
                 stagingRoot,
                 requireString(this.sources[kind], `sources.${kind}`),
                 this.targets[target][kind].bundle);
         },
+        // Where an aggregate's generated bundle root lands in a staged tree: outside
+        // bundles/, at the same depth, so every $ref a member contributes -- carried
+        // over verbatim -- still resolves. The path is the tool's to decide, not the
+        // author's: an aggregate declares its members and its info, never where its
+        // generated root lands.
+        aggregatePath(target, kind, stagingRoot = this.stagingRoot(kind)) {
+            return path.join(
+                stagingRoot,
+                requireString(this.sources[kind], `sources.${kind}`),
+                this.portfolioLocation(),
+                `${target}_${kind}_structure.yaml`);
+        },
+        // Where a target's document root sits in a staged tree, hand-written or
+        // generated -- whichever this target is.
+        bundleRootPath(target, kind, stagingRoot = this.stagingRoot(kind)) {
+            return this.isAggregate(target)
+                ? this.aggregatePath(target, kind, stagingRoot)
+                : this.bundlePath(target, kind, stagingRoot);
+        },
+        // The path prefix strategy an OpenAPI portfolio merges its members' paths
+        // and operation ids with: `target-prefix` (the default) for a gateway
+        // routing /<target>/** to each service, `none` where routing is by host and
+        // a prefixed path would exist nowhere.
+        portfolioPathStrategy() {
+            return (this.portfolio.openapi && this.portfolio.openapi.paths) || PORTFOLIO_DEFAULTS.openapi.paths;
+        },
+        // How a portfolio's operation ids are told apart: currently always prefixed
+        // with the target, the same way paths are -- named, like every portfolio
+        // setting, so a second strategy can be added later without a breaking change.
+        portfolioOperationIdStrategy() {
+            return (this.portfolio.openapi && this.portfolio.openapi.operationIds) || PORTFOLIO_DEFAULTS.openapi.operationIds;
+        },
+        // How two members contributing the same tag name are merged: `reconcile`,
+        // today the only mode -- an identical body merges silently, a differing one
+        // merges too, reported, with the first contributing member's body winning.
+        portfolioTagStrategy() {
+            return (this.portfolio.openapi && this.portfolio.openapi.tags) || PORTFOLIO_DEFAULTS.openapi.tags;
+        },
+        // How a portfolio merges root-level `security`: `push-down`, today the only
+        // mode -- each member's root security becomes each of its own contributed
+        // operations' security, so the portfolio never has to say something false
+        // about any one of them. See the Security section of the README.
+        portfolioSecurityStrategy() {
+            return this.portfolio.security || PORTFOLIO_DEFAULTS.security;
+        },
+        // The directory an aggregate's generated bundle root lands in, sibling to
+        // bundles/, at the same depth under each kind's own source tree.
+        portfolioLocation() {
+            return this.portfolio.location || PORTFOLIO_DEFAULTS.location;
+        },
         // Whether built documents of this kind carry x-fragment-path: on each
         // component of an OpenAPI document, on each fragment of an AsyncAPI one.
         // On unless turned off, for both kinds.

package/src/init-config.js

@@ -84,22 +84,33 @@ function place(doc, parentPath, key, value, before) {
  * already there survives unchanged; a slot already present, however it reads, is
  * never touched, and neither is anything inside it.
  *
+ * `portfolio`, unlike a kind, is never added on its own account: whether a
+ * library is about to have more than one target, and so whether the question is
+ * even asked, is the caller's decision, made once, before this runs -- give the
+ * strategies it resolved here to have the section written with them, or leave
+ * this out entirely to leave the section alone, present or not.
+ *
  * @param {string} text apionly.yaml, as it is on disk
  * @param {object} v the values scaffold(values) was given, resolved: every value
  *     DEFAULTS has, `values`' own where it gives one -- the shape scaffold() itself
  *     works from, so a caller that already has that object need not rebuild it
+ * @param {{paths: string, location: string}} [portfolio] the portfolio section to
+ *     add, with every strategy resolved, when it is missing; omitted, the section
+ *     is never considered at all, whether or not the file already has one
  * @returns {{text: string, added: string[]}} the edited text, and the slots added, in
- *     the order scaffold() declares them; `added` is empty, and `text` is `text`
- *     itself, when nothing was missing.
+ *     the order scaffold() declares them, portfolio last; `added` is empty, and
+ *     `text` is `text` itself, when nothing was missing.
  */
-function addMissingConfig(text, v) {
+function addMissingConfig(text, v, portfolio) {
     const doc = YAML.parseDocument(text);
     const added = [];
 
-    // Not every file that differs is a library with a kind missing -- one that does not
-    // even declare sources.root is not an apionly.yaml this can complete, whatever it
-    // holds instead; force, or a person, is what that file needs.
-    if (!doc.hasIn(["sources", "root"])) return { text, added };
+    // Not every file that differs is a library with a kind missing. One with a YAML
+    // error cannot be edited at all -- parseDocument does not throw on one, it just
+    // records it, and a document with errors refuses to be stringified back. One that
+    // does not even declare sources.root, whatever it parses to, is not an apionly.yaml
+    // this can complete either way; force, or a person, is what either file needs.
+    if (doc.errors.length > 0 || !doc.hasIn(["sources", "root"])) return { text, added };
 
     for (const kind of ["openapi", "asyncapi"].filter((k) => v.kinds.includes(k))) {
         for (const slot of slotsFor(kind, v)) {
@@ -109,6 +120,15 @@ function addMissingConfig(text, v) {
         }
     }
 
+    if (portfolio && !doc.hasIn(["portfolio"])) {
+        doc.setIn(["portfolio"], {
+            openapi: { paths: portfolio.paths, operationIds: "target-prefix", tags: "reconcile" },
+            security: "push-down",
+            location: portfolio.location,
+        });
+        added.push("portfolio");
+    }
+
     return added.length === 0 ? { text, added } : { text: doc.toString(), added };
 }