fix: do not fail publish on description override in OAS 3.0.x

Author: b41ex

src/apitypes/rest/rest.operations.ts

@@ -24,7 +24,7 @@ import type * as TYPE from './rest.types'
 import { HASH_FLAG, INLINE_REFS_FLAG, MESSAGE_SEVERITY, NORMALIZE_OPTIONS, ORIGINS_SYMBOL } from '../../consts'
 import { asyncFunction } from '../../utils/async'
 import { logLongBuild, syncDebugPerformance } from '../../utils/logs'
-import { normalize } from '@netcracker/qubership-apihub-api-unifier'
+import { normalize, RefErrorType } from '@netcracker/qubership-apihub-api-unifier'
 
 export const buildRestOperations: OperationsBuilder<OpenAPIV3.Document> = async (document, ctx, debugCtx) => {
   const documentWithoutComponents = removeComponents(document.data)
@@ -38,8 +38,8 @@ export const buildRestOperations: OperationsBuilder<OpenAPIV3.Document> = async
         originsFlag: ORIGINS_SYMBOL,
         hashFlag: HASH_FLAG,
         source: document.data,
-        onRefResolveError: (_: string, __: PropertyKey[], ref: string) =>
-          bundlingErrorHandler([`The $ref "${ref}" references an invalid location in the document.`]),
+        onRefResolveError: (message: string, _path: PropertyKey[], _ref: string, errorType: RefErrorType) =>
+          bundlingErrorHandler([{ message, errorType }]),
       },
     ) as OpenAPIV3.Document
     const refsOnlyDocument = normalize(

src/utils/document.ts

@@ -29,13 +29,13 @@ import {
   PackageDocument,
   ResolvedDocument,
   VALIDATION_RULES_SEVERITY_LEVEL_ERROR,
-  VALIDATION_RULES_SEVERITY_LEVEL_WARNING,
   VersionDocument,
   YAML_EXPORT_GROUP_FORMAT,
 } from '../types'
 import { bundle, Resolver } from 'api-ref-bundler'
 import { FILE_FORMAT_JSON, FILE_FORMAT_YAML, MESSAGE_SEVERITY } from '../consts'
 import { isNotEmpty } from './arrays'
+import { RefErrorType, RefErrorTypes } from '@netcracker/qubership-apihub-api-unifier'
 
 export const EXPORT_FORMAT_TO_FILE_FORMAT = new Map<OperationsGroupExportFormat, FileFormat>([
   [YAML_EXPORT_GROUP_FORMAT, FILE_FORMAT_YAML],
@@ -121,42 +121,60 @@ export const getDocumentTitle = (fileId: string): string => {
   return fileId.substring(cutDot).split('/').pop()!.replace(/\.[^/.]+$/, '')
 }
 
-export const createBundlingErrorHandler = (ctx: BuilderContext, fileId: FileId) => (messages: string[]): void => {
-  switch (ctx.config.validationRulesSeverity?.brokenRefs) {
-    case VALIDATION_RULES_SEVERITY_LEVEL_ERROR:
-      throw new Error(messages[0])
-    case VALIDATION_RULES_SEVERITY_LEVEL_WARNING:
-    default:
-      for (const message of messages) {
-        ctx.notifications.push({
-          severity: MESSAGE_SEVERITY.Error,
-          message: message,
-          fileId: fileId,
-        })
-      }
+export interface BundlingError {
+  message: string
+  errorType: RefErrorType
+}
+
+export const createBundlingErrorHandler = (ctx: BuilderContext, fileId: FileId) => (errors: BundlingError[]): void => {
+  // Always push all errors to notifications
+  for (const error of errors) {
+    ctx.notifications.push({
+      severity: MESSAGE_SEVERITY.Error,
+      message: error.message,
+      fileId: fileId,
+    })
+  }
+
+  // Only throw if severity is ERROR and there's at least one critical error
+  if (ctx.config.validationRulesSeverity?.brokenRefs === VALIDATION_RULES_SEVERITY_LEVEL_ERROR) {
+    const criticalError = errors.find(error => 
+      error.errorType === RefErrorTypes.REF_NOT_FOUND || 
+      error.errorType === RefErrorTypes.REF_NOT_VALID_FORMAT,
+    )
+    
+    if (criticalError) {
+      throw new Error(criticalError.message)
+    }
   }
 }
 
 export const getBundledFileDataWithDependencies = async (
   fileId: FileId,
   parsedFileResolver: _ParsedFileResolver,
-  onError: (messages: string[]) => void,
+  onError: (errors: BundlingError[]) => void,
 ): Promise<{ data: any; dependencies: string[] }> => {
   const dependencies: string[] = []
-  const errorMessages: string[] = []
+  const errors: BundlingError[] = []
 
   const resolver: Resolver = async (filepath: string) => {
     const data = await parsedFileResolver(filepath)
 
     if (data === null) {
       // can't throw the error here because it will be suppressed: https://github.com/udamir/api-ref-bundler/blob/0.4.0/src/resolver.ts#L33
-      errorMessages.push(`Unable to resolve the file "${filepath}" because it does not exist.`)
+      errors.push({
+        message: `Unable to resolve the file "${filepath}" because it does not exist.`,
+        errorType: RefErrorTypes.REF_NOT_FOUND,
+      })
       return {}
     }
 
     if (data.kind !== FILE_KIND.TEXT) {
       // can't throw the error here because it will be suppressed: https://github.com/udamir/api-ref-bundler/blob/0.4.0/src/resolver.ts#L33
-      errorMessages.push(`Unable to resolve the file "${filepath}" because it is not a valid text file.`)
+      errors.push({
+        message: `Unable to resolve the file "${filepath}" because it is not a valid text file.`,
+        errorType: RefErrorTypes.REF_NOT_VALID_FORMAT,
+      })
       return {}
     }
 
@@ -169,8 +187,8 @@ export const getBundledFileDataWithDependencies = async (
 
   const bundledFileData = await bundle(fileId, resolver)
 
-  if (isNotEmpty(errorMessages)) {
-    onError(errorMessages)
+  if (isNotEmpty(errors)) {
+    onError(errors)
   }
 
   return { data: bundledFileData, dependencies: dependencies }

test/projects/reference-bundling/description-override/config.json

@@ -0,0 +1,13 @@
+{
+  "packageId": "reference-bundling/description-override",
+  "apiType": "rest",
+  "version": "v1",
+  "files": [
+    {
+      "fileId": "openapi.yaml",
+      "publish": true,
+      "labels": [],
+      "commitId": "6c778b1f44200bd19944a6a8eac10a4e5a21a1xd"
+    }
+  ]
+}

test/projects/reference-bundling/description-override/openapi.yaml

@@ -0,0 +1,19 @@
+openapi: 3.0.3
+info:
+  title: test
+  version: 0.1.0
+paths:
+  /path1:
+    get:
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Test'
+                description: Description override
+components:
+  schemas:
+    Test:
+      type: object

test/reference-bundling.test.ts

@@ -22,7 +22,7 @@ describe('Reference bundling test', () => {
     const result = await pkg.publish(pkg.packageId)
 
     expect(result).toEqual(notificationsMatcher([
-      errorNotificationMatcher('references an invalid location'),
+      errorNotificationMatcher('can\'t be resolved'),
       errorNotificationMatcher('does not exist'),
     ]))
     expect(result.operations.size).toBe(1)
@@ -52,7 +52,7 @@ describe('Reference bundling test', () => {
     const result = await pkg.publish(pkg.packageId)
 
     expect(result).toEqual(notificationsMatcher([
-      errorNotificationMatcher('references an invalid location'),
+      errorNotificationMatcher('can\'t be resolved'),
       errorNotificationMatcher('does not exist'),
     ]))
     expect(result.operations.size).toBe(1)
@@ -64,14 +64,14 @@ describe('Reference bundling test', () => {
 
     await expect(
       pkg.publish(pkg.packageId, { validationRulesSeverity: { brokenRefs: VALIDATION_RULES_SEVERITY_LEVEL_ERROR } }),
-    ).rejects.toThrow(/references an invalid location/)
+    ).rejects.toThrow(/can't be resolved/)
   })
 
   test('should collect missing internal reference notification if severity level is not configured', async () => {
     const pkg = LocalRegistry.openPackage('reference-bundling/case5')
     const result = await pkg.publish(pkg.packageId)
 
-    expect(result).toEqual(notificationsMatcher([errorNotificationMatcher('references an invalid location')]))
+    expect(result).toEqual(notificationsMatcher([errorNotificationMatcher('can\'t be resolved')]))
     expect(result.operations.size).toBe(1)
   })
 
@@ -81,4 +81,18 @@ describe('Reference bundling test', () => {
       pkg.publish(pkg.packageId, { validationRulesSeverity: { brokenRefs: VALIDATION_RULES_SEVERITY_LEVEL_ERROR } }),
     ).rejects.toThrow(/not a valid text file/)
   })
+
+  test('should not throw error on publishing specification with incorrect description override', async () => {
+    const pkg = LocalRegistry.openPackage('reference-bundling/description-override')
+    const result = await pkg.publish(pkg.packageId, {
+      validationRulesSeverity: {
+        brokenRefs: VALIDATION_RULES_SEVERITY_LEVEL_ERROR,
+      },
+    })
+
+    expect(result).toEqual(notificationsMatcher([
+      errorNotificationMatcher('can\'t have siblings in this specification version'),      
+    ]))
+    expect(result.operations.size).toBe(1)    
+  })
 })