overlay: keep comments and linewidth when dumping to YAML

examples/valid/asyncapi.v2.overlayed.yml

@@ -0,0 +1,177 @@
+# Some comments in the API definition
+asyncapi: 2.2.0
+info:
+  title: Streetlights API
+  version: 1.0.0
+  description: |
+    Turn lights on or off. And get notified when lights are dimmed or switched.
+  license:
+    name: Apache 2.0
+    url: 'https://www.apache.org/licenses/LICENSE-2.0'
+servers:
+  # This is a Production MQTT server
+  production:
+    url: 'test.mosquitto.org:{port}'
+    protocol: mqtt
+    description: Test broker
+    variables:
+      port:
+        description: Secure connection (TLS) is available through port 8883.
+        default: '1883'
+        enum:
+          - '1883'
+          - '8883'
+    security:
+      - apiKey: []
+      - supportedOauthFlows:
+          - 'streetlights:on'
+          - 'streetlights:off'
+          - 'streetlights:dim'
+      - openIdConnectWellKnown: []
+defaultContentType: application/json
+channels:
+  'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured':
+    description: The topic on which measured values may be produced and consumed.
+    parameters:
+      streetlightId:
+        $ref: 'http://example.org/param-lights.json'
+    publish:
+      summary: Inform about environmental lighting conditions of a particular streetlight.
+      operationId: receiveLightMeasurement
+      traits:
+        - $ref: ./traits/kafka.yml
+      message:
+        $ref: '#/components/messages/lightMeasured'
+  'smartylighting/streetlights/1/0/action/{streetlightId}/turn/on':
+    parameters:
+      streetlightId:
+        $ref: ./params/streetlightId.json
+    subscribe:
+      operationId: turnOn
+      traits:
+        - $ref: ./traits/kafka.yml
+      message:
+        $ref: '#/components/messages/turnOnOff'
+  'smartylighting/streetlights/1/0/action/{streetlightId}/turn/off':
+    parameters:
+      streetlightId:
+        $ref: ./params/streetlightId.json
+  'smartylighting/streetlights/1/0/action/{streetlightId}/dim':
+    parameters:
+      streetlightId:
+        $ref: params/streetlightId.json
+    subscribe:
+      operationId: dimLight
+      traits:
+        - $ref: ./traits/kafka.yml
+      message:
+        $ref: '#/components/messages/dimLight'
+components:
+  messages:
+    lightMeasured:
+      name: lightMeasured
+      title: Light measured
+      summary: Inform about environmental lighting conditions of a particular streetlight.
+      contentType: application/json
+      traits:
+        - $ref: '#/components/messageTraits/commonHeaders'
+      payload:
+        $ref: '#/components/schemas/lightMeasuredPayload'
+    turnOnOff:
+      name: turnOnOff
+      title: Turn on/off
+      summary: Command a particular streetlight to turn the lights on or off.
+      traits:
+        - $ref: '#/components/messageTraits/commonHeaders'
+      payload:
+        $ref: '#/components/schemas/turnOnOffPayload'
+    dimLight:
+      name: dimLight
+      title: Dim light
+      summary: Command a particular streetlight to dim the lights.
+      traits:
+        - $ref: '#/components/messageTraits/commonHeaders'
+      payload:
+        $ref: '#/components/schemas/dimLightPayload'
+  schemas:
+    lightMeasuredPayload:
+      type: object
+      properties:
+        lumens:
+          type: integer
+          minimum: 0
+          description: Light intensity measured in lumens.
+        sentAt:
+          $ref: '#/components/schemas/sentAt'
+    turnOnOffPayload:
+      type: object
+      properties:
+        command:
+          type: string
+          enum:
+            - 'on'
+            - 'off'
+          description: Whether to turn on or off the light.
+        sentAt:
+          $ref: '#/components/schemas/sentAt'
+    dimLightPayload:
+      type: object
+      properties:
+        percentage:
+          type: integer
+          description: Percentage to which the light should be dimmed to.
+          minimum: 0
+          maximum: 100
+        sentAt:
+          $ref: '#/components/schemas/sentAt'
+    sentAt:
+      type: string
+      format: date-time
+      description: Date and time when the message was sent.
+  securitySchemes:
+    apiKey:
+      type: apiKey
+      in: user
+      description: Provide your API key as the user and leave the password empty.
+    supportedOauthFlows:
+      type: oauth2
+      description: Flows to support OAuth 2.0
+      flows:
+        implicit:
+          authorizationUrl: 'https://authserver.example/auth'
+          scopes:
+            'streetlights:on': Ability to switch lights on
+            'streetlights:off': Ability to switch lights off
+            'streetlights:dim': Ability to dim the lights
+        password:
+          tokenUrl: 'https://authserver.example/token'
+          scopes:
+            'streetlights:on': Ability to switch lights on
+            'streetlights:off': Ability to switch lights off
+            'streetlights:dim': Ability to dim the lights
+        clientCredentials:
+          tokenUrl: 'https://authserver.example/token'
+          scopes:
+            'streetlights:on': Ability to switch lights on
+            'streetlights:off': Ability to switch lights off
+            'streetlights:dim': Ability to dim the lights
+        authorizationCode:
+          authorizationUrl: 'https://authserver.example/auth'
+          tokenUrl: 'https://authserver.example/token'
+          refreshUrl: 'https://authserver.example/refresh'
+          scopes:
+            'streetlights:on': Ability to switch lights on
+            'streetlights:off': Ability to switch lights off
+            'streetlights:dim': Ability to dim the lights
+    openIdConnectWellKnown:
+      type: openIdConnect
+      openIdConnectUrl: 'https://authserver.example/.well-known'
+  messageTraits:
+    commonHeaders:
+      headers:
+        type: object
+        properties:
+          my-app-header:
+            type: integer
+            minimum: 0
+            maximum: 100

examples/valid/asyncapi.v2.yml

@@ -1,3 +1,4 @@
+# Some comments in the API definition
 asyncapi: '2.2.0'
 info:
   title: Streetlights API
@@ -9,6 +10,7 @@ info:
     url: https://www.apache.org/licenses/LICENSE-2.0
 
 servers:
+  # This is a Production MQTT server
   production:
     url: test.mosquitto.org:{port}
     protocol: mqtt
@@ -60,6 +62,7 @@ channels:
       streetlightId:
         $ref: './params/streetlightId.json'
     subscribe:
+      x-beta: true
       operationId: turnOff
       traits:
         - $ref: './traits/kafka.yml'

examples/valid/overlay-async.yaml

@@ -0,0 +1,13 @@
+overlay: 1.0.0
+info:
+  title: Overlay to customise API for Streetlights
+  version: 0.0.1
+actions:
+  - target: '$.info.description'
+    description: Provide a better introduction for our end users than this techno babble.
+    update: |
+      Turn lights on or off. And get notified when lights are dimmed or switched.
+
+  - target: '$..[?(@["x-beta"]==true)]'
+    description: Remove all beta operations
+    remove: true

src/definition.ts

@@ -1,7 +1,7 @@
 import {default as $RefParser, getJsonSchemaRefParserDefaultOptions} from '@apidevtools/json-schema-ref-parser'
 import asyncapi from '@asyncapi/specs'
 import {CLIError} from '@oclif/core/errors'
-import {safeStringify} from '@stoplight/yaml'
+import {parseWithPointers, safeStringify} from '@stoplight/yaml'
 import debug from 'debug'
 import {
   JSONSchema4,
@@ -277,9 +277,11 @@ class API {
 
   serializeDefinition(outputPath?: string): string {
     if (this.overlayedDefinition) {
+      const {comments} = parseWithPointers(this.rawDefinition, {attachComments: true})
+      const dumpOptions = {comments, lineWidth: Number.POSITIVE_INFINITY}
       return this.guessFormat(outputPath) === 'json'
         ? JSON.stringify(this.overlayedDefinition)
-        : safeStringify(this.overlayedDefinition)
+        : safeStringify(this.overlayedDefinition, dumpOptions)
     }
 
     return this.rawDefinition

test/unit/definition.test.ts

@@ -1,6 +1,7 @@
 import * as YAML from '@stoplight/yaml'
 import {expect} from 'chai'
 import nock from 'nock'
+import * as fs from 'node:fs'
 import path from 'node:path'
 
 import {API, APIDefinition} from '../../src/definition'
@@ -136,7 +137,20 @@ describe('API class', () => {
 
         expect(api.serializeDefinition()).to.equal(JSON.stringify(api.overlayedDefinition))
 
-        expect(api.serializeDefinition('destination/file.yaml')).to.equal(YAML.safeStringify(api.overlayedDefinition))
+        expect(api.serializeDefinition('destination/file.yaml')).to.equal(
+          YAML.safeStringify(api.overlayedDefinition, {lineWidth: Number.POSITIVE_INFINITY}),
+        )
+      })
+
+      it('preserves line width and YAML comments', async () => {
+        nock('http://example.org').get('/param-lights.json').reply(200, {})
+
+        const api = await API.load('examples/valid/asyncapi.v2.yml')
+        await api.applyOverlay('examples/valid/overlay-async.yaml')
+
+        expect(api.serializeDefinition()).to.equal(
+          fs.readFileSync('examples/valid/asyncapi.v2.overlayed.yml', 'utf8').replaceAll('\r', ''),
+        )
       })
     })
   })