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

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,53 @@ 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", "examples"];
+const LINT_EXAMPLES_KEYS = ["openapi", "asyncapi"];
+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 +102,39 @@ 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 (lint.examples) checkKeys(lint.examples, LINT_EXAMPLES_KEYS, "lint.examples");
+    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 +146,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 +232,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 ---
@@ -141,6 +286,20 @@ function load(configPath) {
             }
             return mode;
         },
+        // What the build does about an operation whose example this kind's
+        // toolchain could use, and does not have: `warn`, the default, reports it;
+        // `error` fails the build; `off` does not look. Examples are never
+        // mandatory to the specification, so the default suits a library that has
+        // not adopted Microcks; a library that has wants `error` for asyncapi.
+        lintExamples(kind) {
+            const configured = (this.lint.examples || {})[kind];
+            const mode = configured === undefined ? "warn" : configured;
+            if (!["error", "warn", "off"].includes(mode)) {
+                throw new ConfigError(
+                    `lint.examples.${kind} must be error, warn or off, not ${JSON.stringify(configured)}`);
+            }
+            return mode;
+        },
         tool(name) {
             return requireString(this.toolchain[name], `toolchain.${name}`);
         },
@@ -148,19 +307,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/examples.js

@@ -0,0 +1,172 @@
+"use strict";
+
+// Whether a bundled document's operations carry examples the rest of the API-Only
+// toolchain can do something with.
+//
+// Both OpenAPI and AsyncAPI make examples optional, and the specification linters
+// are right to accept their absence: a contract without one is a valid contract.
+// This is a toolchain-compatibility check instead -- can Microcks, or the
+// TranscriberJ, do anything useful with what is about to be published -- and the
+// answer, and so the message, differs per kind. Neither runs from a Redocly plugin
+// or a Spectral ruleset: one implementation, one message shape, aware of why it
+// cares, reported apart from either linter's own findings.
+//
+// AsyncAPI: Microcks builds its async mocks and its conformance tests from a
+// message's own `examples` -- an array of {name, summary, payload} on the Message
+// Object itself. A message with none cannot be used for Microcks-based conformance
+// testing at all, so the message says exactly that.
+//
+// OpenAPI: nothing downstream currently reads an example. The TranscriberJ
+// processes a bundle without one perfectly well -- bodies take arguments,
+// constraints become constants. So the OpenAPI message claims only what is true:
+// weaker documentation, never that the bundle cannot be used.
+
+const KEY = "x-fragment-path";
+
+/** The value at a local JSON pointer (`#/a/b/0`) within `document`, or undefined. */
+function pointer(document, ref) {
+    if (typeof ref !== "string" || !ref.startsWith("#/")) return undefined;
+    let node = document;
+    for (const raw of ref.slice(2).split("/")) {
+        if (node === null || typeof node !== "object") return undefined;
+        const segment = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+        node = node[segment];
+    }
+    return node;
+}
+
+/** `node`, or what it points to when it is a `{ $ref }`. */
+function resolve(document, node) {
+    if (node && typeof node === "object" && typeof node.$ref === "string") {
+        return pointer(document, node.$ref);
+    }
+    return node;
+}
+
+/**
+ * Every AsyncAPI operation whose message carries no example, in operation order.
+ *
+ * An operation naming no message explicitly acts on every message of its channel,
+ * so each of those is checked in its place. A message this document cannot resolve
+ * -- a dangling `$ref`, which lint would already have refused -- is skipped rather
+ * than reported here.
+ *
+ * @returns {Array<{operationId: string, messageKey: string, fragmentPath: string|null, at: string}>}
+ */
+function asyncapiOperationsWithoutExamples(document) {
+    const findings = [];
+    const operations = document.operations || {};
+    for (const [operationId, operation] of Object.entries(operations)) {
+        if (!operation || typeof operation !== "object") continue;
+        const channel = resolve(document, operation.channel);
+        const named = Array.isArray(operation.messages) ? operation.messages : [];
+        const entries = named.length > 0
+            ? named.map((ref) => [
+                typeof ref.$ref === "string" ? ref.$ref.split("/").pop() : null,
+                resolve(document, ref),
+            ])
+            : Object.entries((channel && channel.messages) || {});
+
+        for (const [messageKey, message] of entries) {
+            if (!message || typeof message !== "object" || messageKey === null) continue;
+            const examples = message.examples;
+            if (Array.isArray(examples) && examples.length > 0) continue;
+            findings.push({
+                operationId,
+                messageKey,
+                fragmentPath: message[KEY] || null,
+                at: `/operations/${operationId}`,
+            });
+        }
+    }
+    return findings;
+}
+
+/** Whether any media type of a request body or response object has an example. */
+function hasExample(document, bodyOrResponse) {
+    const content = bodyOrResponse.content;
+    if (!content || typeof content !== "object") return true; // nothing to exemplify
+    return Object.values(content).some((mediaType) => {
+        if (!mediaType || typeof mediaType !== "object") return false;
+        if (mediaType.example !== undefined) return true;
+        if (mediaType.examples && Object.keys(mediaType.examples).length > 0) return true;
+        const schema = resolve(document, mediaType.schema);
+        return !!(schema && Array.isArray(schema.examples) && schema.examples.length > 0);
+    });
+}
+
+const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+
+/**
+ * Every OpenAPI operation whose request body or a response carries no example, in
+ * path-and-method order.
+ *
+ * An entity counts as having one when a media type declares `example` or
+ * `examples` directly, or when the schema that media type's `schema` resolves to
+ * -- not a property inside it -- carries its own top-level `examples`. A body or
+ * response with no `content` at all, such as a 204, has nothing to exemplify and
+ * is not reported.
+ *
+ * @returns {Array<{operationId: string, part: string, fragmentPath: string|null, at: string}>}
+ */
+function openapiOperationsWithoutExamples(document) {
+    const findings = [];
+    const paths = document.paths || {};
+    for (const [route, pathItem] of Object.entries(paths)) {
+        if (!pathItem || typeof pathItem !== "object") continue;
+        for (const method of METHODS) {
+            const operation = pathItem[method];
+            if (!operation || typeof operation !== "object") continue;
+            const operationId = operation.operationId || `${method.toUpperCase()} ${route}`;
+            const at = `/paths/${route.replace(/~/g, "~0").replace(/\//g, "~1")}/${method}`;
+
+            if (operation.requestBody) {
+                const body = resolve(document, operation.requestBody);
+                if (body && !hasExample(document, body)) {
+                    findings.push({ operationId, part: "request body", fragmentPath: body[KEY] || null, at });
+                }
+            }
+
+            for (const [status, raw] of Object.entries(operation.responses || {})) {
+                const response = resolve(document, raw);
+                if (response && !hasExample(document, response)) {
+                    findings.push({
+                        operationId, part: `response ${status}`, fragmentPath: response[KEY] || null, at,
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+
+/**
+ * The warning text for one AsyncAPI finding.
+ *
+ * @param {{operationId: string, messageKey: string, fragmentPath: string|null}} finding
+ * @returns {string}
+ */
+function asyncapiMessage(finding) {
+    const where = finding.fragmentPath || `at ${finding.at}`;
+    return `AsyncAPI operation '${finding.operationId}': message '${finding.messageKey}' (${where}) ` +
+        "carries no example, so this bundle cannot be used for Microcks-based conformance testing.";
+}
+
+/**
+ * The warning text for one OpenAPI finding.
+ *
+ * @param {{operationId: string, part: string, fragmentPath: string|null}} finding
+ * @returns {string}
+ */
+function openapiMessage(finding) {
+    const where = finding.fragmentPath || `at ${finding.at}`;
+    return `OpenAPI operation '${finding.operationId}': ${finding.part} (${where}) ` +
+        "carries no example, which makes the generated documentation harder to read.";
+}
+
+module.exports = {
+    asyncapiOperationsWithoutExamples,
+    openapiOperationsWithoutExamples,
+    asyncapiMessage,
+    openapiMessage,
+};

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 };
 }