@arc-e-tect/api-only-publisher 0.4.2 → 0.5.0

package/README.adoc

@@ -488,8 +488,8 @@ The path always uses forward slashes, and it names a file in the library.
 Other OpenAPI tooling ignores the key, as it ignores any `x-` extension.
 It is how the API-Only TranscriberJ ties generated code to the fragment it came from, instead of to a component name the bundler picked.
 
-It is on by default, for OpenAPI documents only.
-`defaults.openapi.fragmentPaths: false` turns it off.
+It is on by default, for both specification kinds.
+`defaults.openapi.fragmentPaths: false` and `defaults.asyncapi.fragmentPaths: false` turn it off, each for its own kind.
 
 How it is done::
 The bundler is not told anything; it is shown stamped fragments, in copies of the staged tree under `<build.staging>/fragment-paths/<target>/`.
@@ -504,6 +504,38 @@ A component's fragment that is also inlined somewhere else in the same document,
 
 A component written directly in a bundle root, rather than `$ref`'d from a fragment, has no fragment and carries no path.
 
+[#fragment-paths-asyncapi]
+==== AsyncAPI, where the bundler inlines rather than hoists
+
+An AsyncAPI bundle has no `components` section at all.
+The bundler inlines a message into its channel, the message's payload into the message, and any schema that payload references into the payload.
+So there is nothing to hoist and nothing to select: every fragment is stamped, and the stamp arrives wherever the bundler put that fragment.
+
+[source,yaml]
+----
+channels:
+  auditV1:
+    x-fragment-path: asyncapi/channels/iff/useraccount/AuditV1.yaml
+    address: iff.useraccount.audit.v1
+    messages:
+      registrationInitiatedMessage:
+        x-fragment-path: asyncapi/messages/iff/useraccount/RegistrationInitiatedMessageV1.yaml
+        payload:
+          x-fragment-path: asyncapi/components/iff/useraccount/schemas/RegistrationInitiatedEventV1.yaml
+          properties:
+            username:
+              x-fragment-path: openapi/components/common/schemas/UsernameV1.yaml
+----
+
+The last of those is the point of a shared library: a schema the OpenAPI tree owns keeps its own path when an event payload references it, so a consumer can tell that the `username` in an event and the `username` in a response are one fragment, and generate one class for both.
+
+The bundle root is the document rather than a fragment of one, so it is never stamped.
+One bundler run is enough, because nothing has to be discovered first.
+
+What stops the build::
+A fragment that writes `x-fragment-path` itself, as on the OpenAPI side.
+A stamp in the built document that names no file in the library, which would mean the bundler moved a stamp away from what explains it.
+
 [#fragment-path-versions]
 ==== What a change to `x-fragment-path` means for a contract's version
 
@@ -526,9 +558,11 @@ Semantic versioning describes the contract, so the version follows from what a c
 |Consumers relying on it lose provenance and collision disambiguation, and may stop generating code at all.
 |===
 
-Upgrading to a Publisher that stamps the key changes every OpenAPI document that has components built from fragments.
+The policy is the same for both kinds: an AsyncAPI document gains the key exactly as an OpenAPI one does, and the version follows the table above.
+
+Upgrading to a Publisher that stamps the key changes every OpenAPI document that has components built from fragments, and every AsyncAPI document that has fragments at all.
 `changed` does not see that, because a target's closure hash covers the fragments, not the Publisher.
-Bump each such target's MINOR version in the upgrade's commit, or set `fragmentPaths: false` until you do: publishing a changed document under a version already published is refused by every Subscriber that locked it (see <<versions,Versions §>>).
+Bump each such target's MINOR version in the upgrade's commit, or set `fragmentPaths: false` for the kind until you do: publishing a changed document under a version already published is refused by every Subscriber that locked it (see <<versions,Versions §>>).
 
 [#distribution]
 === `distribution` is transitional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.4.2",
+  "version": "0.5.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

@@ -164,12 +164,12 @@ function load(configPath) {
         // Whether built documents of this kind carry x-fragment-path on each
         // component. On unless turned off; OpenAPI only.
         fragmentPaths(kind) {
-            if (kind !== "openapi") return false;
-            const configured = (this.defaults.openapi || {}).fragmentPaths;
+            if (kind !== "openapi" && kind !== "asyncapi") return false;
+            const configured = (this.defaults[kind] || {}).fragmentPaths;
             if (configured === undefined) return true;
             if (typeof configured !== "boolean") {
                 throw new ConfigError(
-                    `defaults.openapi.fragmentPaths must be true or false, not ${JSON.stringify(configured)}`);
+                    `defaults.${kind}.fragmentPaths must be true or false, not ${JSON.stringify(configured)}`);
             }
             return configured;
         },

package/src/fragment-paths.js

@@ -30,9 +30,11 @@ class FragmentPathError extends Error {}
  * alone; nothing that becomes a component looks like that.
  *
  * @param {Set<string>|null} only the root-relative paths to stamp; all when null
+ * @param {Set<string>} except the root-relative paths to leave alone, such as a
+ *        bundle root, which is the document itself rather than a fragment of one
  * @returns {string[]} the root-relative paths stamped, sorted
  */
-function stampFiles(root, { only = null } = {}) {
+function stampFiles(root, { only = null, except = new Set() } = {}) {
     const stamped = [];
     const walk = (dir) => {
         for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
@@ -44,6 +46,7 @@ function stampFiles(root, { only = null } = {}) {
             if (!/\.ya?ml$/.test(entry.name)) continue;
             const rel = path.relative(root, full).split(path.sep).join("/");
             if (only && !only.has(rel)) continue;
+            if (except.has(rel)) continue;
 
             const doc = YAML.parseDocument(fs.readFileSync(full, "utf8"));
             if (!YAML.isMap(doc.contents)) continue;
@@ -78,22 +81,26 @@ function componentPaths(document) {
 }
 
 /**
- * Every stamp in a parsed document that is not directly on a component, with the
- * JSON pointer of the object carrying it.
+ * Every stamp in a parsed document, with the JSON pointer of the object carrying
+ * it, in document order.
+ *
+ * <p>An OpenAPI bundle hoists fragments into components, so a stamp anywhere else
+ * is a fragment inlined where a component was expected. An AsyncAPI bundle inlines
+ * everything, so every stamp sits where its fragment was used: on a channel, a
+ * message, a payload, or a schema a payload references.
  *
  * @returns {Array<{at: string, path: string}>}
  */
-function strayPaths(document) {
-    const stray = [];
+function fragmentStamps(document, { where = () => true } = {}) {
+    const stamps = [];
     const visit = (node, pointer) => {
         if (Array.isArray(node)) {
             node.forEach((item, i) => visit(item, `${pointer}/${i}`));
             return;
         }
         if (!node || typeof node !== "object") return;
-        const onComponent = /^\/components\/[^/]+\/[^/]+$/.test(pointer);
-        if (Object.hasOwn(node, KEY) && !onComponent) {
-            stray.push({ at: pointer || "/", path: node[KEY] });
+        if (Object.hasOwn(node, KEY) && where(pointer)) {
+            stamps.push({ at: pointer || "/", path: node[KEY] });
         }
         for (const [key, value] of Object.entries(node)) {
             if (key === KEY) continue;
@@ -101,7 +108,30 @@ function strayPaths(document) {
         }
     };
     visit(document, "");
-    return stray;
+    return stamps;
+}
+
+/**
+ * Every stamp in a parsed document that is not directly on a component, with the
+ * JSON pointer of the object carrying it.
+ *
+ * @returns {Array<{at: string, path: string}>}
+ */
+function strayPaths(document) {
+    return fragmentStamps(document, { where: (pointer) => !/^\/components\/[^/]+\/[^/]+$/.test(pointer) });
+}
+
+/**
+ * The stamps of a parsed document that do not name a file under `root`.
+ *
+ * <p>A stamp is written by this tool from a file it walked, so an unresolved one
+ * means the bundler moved a stamp somewhere its fragment no longer explains, and
+ * the document should not be published.
+ *
+ * @returns {Array<{at: string, path: string}>}
+ */
+function unresolvedStamps(document, root) {
+    return fragmentStamps(document).filter((stamp) => !fs.existsSync(path.join(root, stamp.path)));
 }
 
-module.exports = { stampFiles, componentPaths, strayPaths, FragmentPathError, KEY };
+module.exports = { stampFiles, componentPaths, strayPaths, fragmentStamps, unresolvedStamps, FragmentPathError, KEY };

package/src/pipeline.js

@@ -10,7 +10,7 @@ const YAML = require("yaml");
 const { substituteFile } = require("./placeholders");
 const { stampFile } = require("./version");
 const { generateAsyncApi, isAggregate } = require("./aggregate");
-const { stampFiles, componentPaths, strayPaths, FragmentPathError, KEY } = require("./fragment-paths");
+const { stampFiles, componentPaths, strayPaths, fragmentStamps, unresolvedStamps, FragmentPathError, KEY } = require("./fragment-paths");
 
 class BuildError extends Error {}
 
@@ -112,6 +112,7 @@ function bundle(config, target, kind, outFile, log, { stagingRoot } = {}) {
  * rather than publish it.
  */
 function bundleWithFragmentPaths(config, target, kind, outFile, log) {
+    if (kind === "asyncapi") return bundleInlinedWithFragmentPaths(config, target, kind, outFile, log);
     const scratch = config.fragmentPathStaging(target);
     fs.rmSync(scratch, { recursive: true, force: true });
 
@@ -150,6 +151,50 @@ function bundleWithFragmentPaths(config, target, kind, outFile, log) {
     log(`-- Stamped ${KEY} on ${[...components.values()].filter(Boolean).length} component(s)`);
 }
 
+/**
+ * Bundle a target whose bundler inlines rather than hoists, with x-fragment-path on
+ * every fragment it inlines.
+ *
+ * An AsyncAPI bundle has no components section: a message is inlined into its
+ * channel, its payload into the message, and a schema the payload references into
+ * the payload -- including one from the OpenAPI tree, which is how a shared fragment
+ * travels. So there is nothing to discover and nothing to select: every fragment is
+ * stamped, and the stamp arrives wherever the bundler put that fragment.
+ *
+ * The bundle root is the document, not a fragment of one, so it is left alone.
+ */
+function bundleInlinedWithFragmentPaths(config, target, kind, outFile, log) {
+    const scratch = config.fragmentPathStaging(target);
+    fs.rmSync(scratch, { recursive: true, force: true });
+    const root = path.join(scratch, "stamp");
+    fs.cpSync(config.stagingRoot(kind), root, { recursive: true });
+
+    const bundleRoot = path.relative(root, config.bundlePath(target, kind, root)).split(path.sep).join("/");
+    try {
+        stampFiles(root, { except: new Set([bundleRoot]) });
+    } catch (error) {
+        if (error instanceof FragmentPathError) throw new BuildError(`target '${target}': ${error.message}`);
+        throw error;
+    }
+
+    log(`-- Bundling ${path.basename(config.bundlePath(target, kind))} with ${KEY}`);
+    const file = path.join(scratch, "stamp.yaml");
+    bundle(config, target, kind, file, () => {}, { stagingRoot: root });
+    const document = YAML.parse(fs.readFileSync(file, "utf8"));
+
+    const stamps = fragmentStamps(document);
+    const missing = unresolvedStamps(document, root);
+    if (missing.length > 0) {
+        throw new BuildError(
+            `target '${target}': ${KEY} names a fragment that is not in the library: ` +
+            missing.map((stamp) => `${stamp.at} (${stamp.path})`).join(", "));
+    }
+
+    fs.mkdirSync(path.dirname(outFile), { recursive: true });
+    fs.copyFileSync(file, outFile);
+    log(`-- Stamped ${KEY} on ${stamps.length} inlined fragment(s)`);
+}
+
 function lint(config, kind, file, log, { report = false, reportFile = null } = {}) {
     const tool = kind === "openapi" ? config.tool("redocly") : config.tool("asyncapi");
     const args = kind === "openapi"