@arc-e-tect/api-only-publisher 0.8.0 → 0.9.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.8.0
+:api-only-publisher-version: 0.9.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]
@@ -687,6 +687,9 @@ reports:
   lint: build/reports/lint
 lint:
   unreferenced: error  # a fragment no target reaches: error, warn or off
+  examples:
+    asyncapi: warn      # a message with no example: error, warn (the default) or off
+    openapi: warn       # a request body or response with no example: error, warn (the default) or off
 
 toolchain:
   redocly: "@redocly/cli@2.52.0"
@@ -781,6 +784,32 @@ Any other YAML file under the source root counts.
 
 `lint` lints every document even when one of them fails, and names every failure at the end, so a single run reports all of them.
 
+[#examples-check]
+=== An operation with no example is reported apart from lint
+
+`build` also checks, after linting, whether each operation's example is one the rest of the API-Only toolchain could use -- and reports that separately from lint's own findings, since "your contract is wrong" and "your contract limits what you can do with it downstream" are different claims.
+Neither specification requires an example, and this is not a specification-validity rule: it is never run as a Redocly plugin or a Spectral ruleset.
+
+For AsyncAPI, it is whether a message's own `examples` array is non-empty -- what Microcks reads to build its async mocks and its conformance tests:
+
+[source,text]
+----
+AsyncAPI operation '<operationId>': message '<messageKey>' (<fragment, or where in the bundle>) carries no example, so this bundle cannot be used for Microcks-based conformance testing.
+----
+
+For OpenAPI, it is whether a request body's or response's media type declares `example`/`examples`, or the schema it references carries its own top-level `examples`.
+Nothing downstream currently reads an OpenAPI example, so the message never claims the bundle cannot be used -- only that the generated documentation is weaker without one:
+
+[source,text]
+----
+OpenAPI operation '<operationId>': <request body, or response <status>> (<fragment, or where in the bundle>) carries no example, which makes the generated documentation harder to read.
+----
+
+A body or response with no `content` at all, such as a `204`, has nothing to exemplify and is never reported.
+
+`lint.examples.asyncapi` and `lint.examples.openapi` each default to `warn`; `error` fails the build, `off` does not look.
+A library that has adopted the Microcks-based conformance emitter will usually want `lint.examples.asyncapi: error`: publishing a bundle its own toolchain cannot use is a real defect there, not merely a gap (link:../docs/reference/authoring-a-specification-library.adoc#give-every-operation-an-example[Give every operation an example →]).
+
 [#version-stamping]
 === Version stamping edits one scalar
 

package/package.json

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

package/src/config.js

@@ -27,7 +27,8 @@ const DEFAULTS_KIND_KEYS = { openapi: ["lint", "outputName", "fragmentPaths"], a
 const PLACEHOLDERS_KEYS = ["strict"];
 const BUILD_KEYS = ["staging", "dist"];
 const REPORTS_KEYS = ["lint"];
-const LINT_KEYS = ["unreferenced"];
+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"];
@@ -121,6 +122,7 @@ function load(configPath) {
     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 || {};
@@ -284,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}`);
         },

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/pipeline.js

@@ -11,6 +11,9 @@ const { substituteFile } = require("./placeholders");
 const { stampFile } = require("./version");
 const { generateAsyncApi, generateOpenApi, openapiPushDown, isAggregate } = require("./aggregate");
 const { stampFiles, componentPaths, strayPaths, fragmentStamps, unresolvedStamps, FragmentPathError, KEY } = require("./fragment-paths");
+const {
+    asyncapiOperationsWithoutExamples, openapiOperationsWithoutExamples, asyncapiMessage, openapiMessage,
+} = require("./examples");
 
 class BuildError extends Error {}
 
@@ -205,6 +208,33 @@ function lint(config, kind, file, log, { report = false, reportFile = null } = {
     if (report && output.trim()) log(output.trimEnd());
 }
 
+/**
+ * Reports operations of a built document whose example this kind's toolchain
+ * could use, and does not have -- separately from lint's own findings, since
+ * "your contract is wrong" and "your contract limits what you can do with it
+ * downstream" are different claims and read worse conflated.
+ *
+ * Governed by `lint.examples.<kind>`: `warn`, the default, logs each finding and
+ * continues; `error` logs them and fails the build; `off` does not look.
+ */
+function checkExamples(config, kind, file, log) {
+    const mode = config.lintExamples(kind);
+    if (mode === "off") return;
+
+    const document = YAML.parse(fs.readFileSync(file, "utf8"));
+    const findings = kind === "asyncapi"
+        ? asyncapiOperationsWithoutExamples(document).map(asyncapiMessage)
+        : openapiOperationsWithoutExamples(document).map(openapiMessage);
+    if (findings.length === 0) return;
+
+    for (const message of findings) log(`-- ${message}`);
+    if (mode === "error") {
+        throw new BuildError(
+            `${findings.length} operation(s) in ${path.basename(file)} have no example ` +
+            "(lint.examples." + kind + " is error):\n" + findings.map((m) => `  ${m}`).join("\n"));
+    }
+}
+
 /**
  * Copy a built document to the project that implements the target.
  *
@@ -304,6 +334,7 @@ function build(config, { targets, versionOf = () => null, kinds = ["openapi", "a
                 stampFile(outFile, version);
             }
             lint(config, kind, outFile, log);
+            checkExamples(config, kind, outFile, log);
 
             let distributed = null;
             if (config.isPublished(target)) {
@@ -317,4 +348,6 @@ function build(config, { targets, versionOf = () => null, kinds = ["openapi", "a
     return results;
 }
 
-module.exports = { build, prepare, stage, substituteTree, bundle, bundleWithFragmentPaths, lint, distribute, BuildError };
+module.exports = {
+    build, prepare, stage, substituteTree, bundle, bundleWithFragmentPaths, lint, checkExamples, distribute, BuildError,
+};