@arc-e-tect/api-only-publisher 0.13.0 → 0.14.0

package/README.adoc

@@ -6,7 +6,15 @@
 :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.13.0
+:api-only-publisher-version: 0.14.0
+
+[NOTE]
+.About this documentation
+====
+This documentation was partially authored by Claude, an AI assistant.
+Documentation is part of the product, and is held to the same standard as the code it describes.
+If something here seems wrong, please file a bug report: link:https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/issues/new[open an issue in this repository ↗].
+====
 
 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]
@@ -1021,11 +1029,19 @@ AsyncAPI operation '<operationId>': message '<messageKey>' (<fragment, or where
 ----
 
 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:
+The message never claims the bundle cannot be used, and says only what is true for the part.
+For a request body, the TranscriberJ's contract cases send the example the media type names, or values from the schemas' own examples (link:../api-only-transcriberj/README.adoc#example-data[Example data in the TranscriberJ's README →]); without one they send values it generates:
+
+[source,text]
+----
+OpenAPI operation '<operationId>': request body (<fragment, or where in the bundle>) carries no example, so the TranscriberJ's contract cases send generated values rather than ones the contract chose, and the generated documentation is harder to read.
+----
+
+Nothing downstream reads a response's example, so for a response only the 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.
+OpenAPI operation '<operationId>': 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.
@@ -1589,6 +1605,8 @@ docker/smoke-test.sh api-only-publisher:local 0.0.0-local
 It runs every step with no network, a read-only root and your own user: the version, the help, the toolchain labels against what is installed and against `init`'s pins, a library with two targets built, linted and packaged to every local channel in one run, ownership, byte-identical packaging twice, the hand-off, a foreign toolchain pin failing at once, the shell mode, and a build as an arbitrary UID.
 
 link:../.github/workflows/api-only-publisher-image-e2e.yml[`api-only-publisher-image-e2e.yml` →] runs the GitHub Actions reference pipeline for real, by hand only.
+link:test/docker.test.js[`test/docker.test.js` →] holds it to what the link:pipelines/[reference pipelines →] do, the same actions, commands, inputs and environment, but not to the versions they pin.
+The reference pipelines are examples, maintained on their own, and the end-to-end workflow is maintained with this repository's other workflows, so a new version of an action in one never fails the Publisher's build while the other has not moved.
 Give it an image by digest; it publishes version `0.<run>.<attempt>` of two scratch targets, `apionly-e2e-alpha` and `apionly-e2e-beta`, to npm, Maven and NuGet on GitHub Packages and to a scratch release, publishes again to prove a re-run is safe, resolves each package with its own client and with the Subscriber, and removes what it published.
 The image workflow, dispatched by hand, is the release's dry run: its defaults are the scratch names `ghcr.io/arc-e-tect/api-only-publisher-scratch` and `arcetect/api-only-publisher-scratch`, and it builds from the branch's source.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Builds, packs and publishes API description documents from a library of reusable fragments.",
   "license": "MIT",
   "author": "Arc-E-Tect",
@@ -46,7 +46,7 @@
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^11.0.1",
-    "@semantic-release/github": "^12.0.9",
+    "@semantic-release/github": "^12.0.10",
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",
     "semantic-release": "^25.0.9"

package/src/examples.js

@@ -16,10 +16,12 @@
 // 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.
+// OpenAPI: the TranscriberJ sends a request body's named example, or values from
+// the schemas' own examples, in the contract cases it generates; without them it
+// generates values from the constraints, and processes the bundle perfectly well.
+// A response's example is read by nothing downstream. So the OpenAPI message
+// claims only what is true for its part -- generated values for a request body,
+// weaker documentation for both -- never that the bundle cannot be used.
 
 const KEY = "x-fragment-path";
 
@@ -160,8 +162,12 @@ function asyncapiMessage(finding) {
  */
 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.";
+    const prefix = `OpenAPI operation '${finding.operationId}': ${finding.part} (${where}) carries no example, `;
+    if (finding.part === "request body") {
+        return prefix + "so the TranscriberJ's contract cases send generated values rather than ones the " +
+            "contract chose, and the generated documentation is harder to read.";
+    }
+    return prefix + "which makes the generated documentation harder to read.";
 }
 
 module.exports = {