fix(hooks): bundle emitted AsyncAPI document in generate:after hook (#2189)

Co-authored-by: Adi-204 <adiboghawala@gmail.com>
Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com>

Author: Adi-204

.changeset/bundle-emitted-asyncapi.md

@@ -0,0 +1,7 @@
+---
+"@asyncapi/generator-hooks": patch
+---
+
+Fix `createAsyncapiFile` (`generate:after`) copying the source AsyncAPI document verbatim, which left external `$ref`s (e.g. `$ref: './commons/servers.yml#/...'`) unresolved in the generated output and broke runtime consumers such as `@asyncapi/keeper`. The hook now bundles the document via `@asyncapi/bundler` when it was loaded from a file on disk, inlining external `$ref`s into a single self-contained file. If no source file is available, or bundling fails, it falls back to writing the original source unchanged.
+
+Note: refs are resolved relative to the source file's own directory only, so refs pointing outside a path reachable from there (e.g. a `commons/` folder reached only through a symlink) will not bundle and fall back to the verbatim source.

apps/generator/docs/hooks.md

@@ -92,7 +92,9 @@ It is a library of reusable hooks that you can use in your templates. You only h
 This library consists of the following hooks:
 |Hook name|Hook type|Description|
 |---|---|---|
-| `createAsyncapiFile` | `generate:after` | It creates an AsyncAPI file with the content of the spec file passed to the generator. By default, it creates the file in the root of the generation output directory. This hook also supports custom parameters that the user can pass to template generation. The parameter called `asyncapiFileDir` allows the user to specify the location where the spec file should be created. To make your template users use this parameter, you need to add it to the configuration of your template like other parameters |
+| `createAsyncapiFile` | `generate:after` | It creates an AsyncAPI file with the content of the spec file passed to the generator. If the spec was loaded from a file on disk, external `$ref`s (e.g. `$ref: './commons/servers.yml#/...'`) are bundled via [`@asyncapi/bundler`](https://github.com/asyncapi/bundler) into a single self-contained file; otherwise, or if bundling fails, the original spec is written unchanged. By default, it creates the file in the root of the generation output directory. This hook also supports custom parameters that the user can pass to template generation. The parameter called `asyncapiFileDir` allows the user to specify the location where the spec file should be created. To make your template users use this parameter, you need to add it to the configuration of your template like other parameters |
+
+> **Limitation:** refs are only resolved relative to the source file's own directory, so a `$ref` reachable only through another path (e.g. a symlink) won't bundle and falls back to the unresolved source.
 
 1. In your template configuration in `package.json` specify you want to use this library and what hook exactly:
     ```json

apps/hooks/package.json

@@ -29,6 +29,7 @@
   },
   "homepage": "https://github.com/asyncapi/generator/tree/master/apps/hooks#readme",
   "dependencies": {
+    "@asyncapi/bundler": "1.0.1",
     "fs.extra": "^1.3.2"
   },
   "devDependencies": {

apps/hooks/src/index.js

@@ -1,17 +1,21 @@
 const fs = require('fs');
 const path = require('path');
 const xfs = require('fs.extra');
+const bundle = require('@asyncapi/bundler');
 
-function createAsyncapiFile(generator) {
-  const asyncapi = generator.originalAsyncAPI;
+async function createAsyncapiFile(generator) {
+  const sourceFilePath = typeof generator.asyncapi?.meta === 'function'
+    ? generator.asyncapi.meta('asyncapi')?.source
+    : undefined;
+  let asyncapi = generator.originalAsyncAPI;
   const targetDir = generator.targetDir;
   const customDirInTarget = generator.templateParams.asyncapiFileDir;
   const getCustomFileLocation = (target, dir, filename) => {
-    xfs.mkdirpSync(path.resolve(target, dir)); 
-    return path.resolve(target, dir, filename); 
+    xfs.mkdirpSync(path.resolve(target, dir));
+    return path.resolve(target, dir, filename);
   };
   let extension;
-  
+
   try {
     JSON.parse(asyncapi);
     extension = 'json';
@@ -20,11 +24,22 @@ function createAsyncapiFile(generator) {
   }
 
   const outputFileName = `asyncapi.${extension}`;
-
-  const asyncapiOutputLocation = customDirInTarget 
+  
+  const asyncapiOutputLocation = customDirInTarget
     ? getCustomFileLocation(targetDir, customDirInTarget, outputFileName)
     : path.resolve(targetDir, outputFileName);
 
+  if (sourceFilePath && fs.existsSync(sourceFilePath)) {
+    try {
+      const bundled = await bundle([sourceFilePath], {
+        baseDir: path.dirname(sourceFilePath)
+      });
+      asyncapi = extension === 'json' ? bundled.string() : bundled.yml();
+    } catch (err) {
+      console.warn(`[generator-hooks] Failed to bundle AsyncAPI document, writing original source verbatim: ${err.message}`);
+    }
+  }
+
   fs.writeFileSync(asyncapiOutputLocation, asyncapi);
 }
 

apps/hooks/test/__fixtures__/asyncapi-with-broken-ref.yml

@@ -0,0 +1,7 @@
+asyncapi: 3.0.0
+info:
+  title: Broken refs example
+  version: 1.0.0
+channels:
+  echo:
+    $ref: './commons/does-not-exist.yml#/channels/echo'

apps/hooks/test/__fixtures__/asyncapi-with-refs.json

@@ -0,0 +1,28 @@
+{
+  "asyncapi": "3.0.0",
+  "info": {
+    "title": "Refs example",
+    "version": "1.0.0"
+  },
+  "servers": {
+    "echoServer": {
+      "$ref": "./commons/servers.yml#/servers/echoServer"
+    }
+  },
+  "channels": {
+    "echo": {
+      "$ref": "./commons/channels.yml#/channels/echo"
+    }
+  },
+  "operations": {
+    "sendEcho": {
+      "action": "send",
+      "channel": {
+        "$ref": "#/channels/echo"
+      },
+      "messages": [
+        { "$ref": "#/channels/echo/messages/echo" }
+      ]
+    }
+  }
+}

apps/hooks/test/__fixtures__/asyncapi-with-refs.yml

@@ -0,0 +1,17 @@
+asyncapi: 3.0.0
+info:
+  title: Refs example
+  version: 1.0.0
+servers:
+  echoServer:
+    $ref: './commons/servers.yml#/servers/echoServer'
+channels:
+  echo:
+    $ref: './commons/channels.yml#/channels/echo'
+operations:
+  sendEcho:
+    action: send
+    channel:
+      $ref: '#/channels/echo'
+    messages:
+      - $ref: '#/channels/echo/messages/echo'

apps/hooks/test/__fixtures__/commons/channels.yml

@@ -0,0 +1,6 @@
+channels:
+  echo:
+    address: /
+    messages:
+      echo:
+        $ref: './messages.yml#/messages/echo'

apps/hooks/test/__fixtures__/commons/messages.yml

@@ -0,0 +1,4 @@
+messages:
+  echo:
+    payload:
+      type: string

apps/hooks/test/__fixtures__/commons/servers.yml

@@ -0,0 +1,4 @@
+servers:
+  echoServer:
+    host: echo.example.org
+    protocol: ws