feat: align with new requirements

Author: CountRedClaw

src/apitypes/rest/rest.document.ts

@@ -20,10 +20,9 @@ import { convertObj } from 'swagger2openapi'
 import { REST_DOCUMENT_TYPE, REST_KIND_KEY } from './rest.consts'
 import type { RestDocumentInfo } from './rest.types'
 
-import type { DocumentBuilder, DocumentDumper } from '../../types'
-import { YAML_EXPORT_GROUP_FORMAT } from '../../types'
+import { DocumentBuilder, DocumentDumper, YAML_EXPORT_GROUP_FORMAT } from '../../types'
 import { FILE_FORMAT } from '../../consts'
-import { getBundledFileDataWithDependencies, getDocumentTitle } from '../../utils'
+import { createBundlingErrorHandler, getBundledFileDataWithDependencies, getDocumentTitle } from '../../utils'
 import YAML from 'js-yaml'
 
 const openApiDocumentMeta = (data: OpenAPIV3.Document): RestDocumentInfo => {
@@ -53,7 +52,10 @@ const openApiDocumentMeta = (data: OpenAPIV3.Document): RestDocumentInfo => {
 export const buildRestDocument: DocumentBuilder<OpenAPIV3.Document> = async (parsedFile, file, ctx) => {
   const { fileId, slug = '', publish = true, apiKind, ...fileMetadata } = file
 
-  const { data, dependencies } = await getBundledFileDataWithDependencies(fileId, ctx.parsedFileResolver, !!ctx.config.strictValidation)
+  const {
+    data,
+    dependencies,
+  } = await getBundledFileDataWithDependencies(fileId, ctx.parsedFileResolver, createBundlingErrorHandler(ctx, fileId))
 
   let bundledFileData = data
 

src/apitypes/rest/rest.operations.ts

@@ -17,8 +17,8 @@
 import { OpenAPIV3 } from 'openapi-types'
 
 import { buildRestOperation } from './rest.operation'
-import type { OperationsBuilder } from '../../types'
-import { removeComponents, removeFirstSlash, slugify, takeIf } from '../../utils'
+import { OperationsBuilder } from '../../types'
+import { createBundlingErrorHandler, removeComponents, removeFirstSlash, slugify } from '../../utils'
 import { getOperationBasePath } from './rest.utils'
 import type * as TYPE from './rest.types'
 import { HASH_FLAG, INLINE_REFS_FLAG, MESSAGE_SEVERITY, NORMALIZE_OPTIONS, ORIGINS_SYMBOL } from '../../consts'
@@ -28,6 +28,7 @@ import { normalize } from '@netcracker/qubership-apihub-api-unifier'
 
 export const buildRestOperations: OperationsBuilder<OpenAPIV3.Document> = async (document, ctx, debugCtx) => {
   const documentWithoutComponents = removeComponents(document.data)
+  const bundlingErrorHandler = createBundlingErrorHandler(ctx, document.fileId)
 
   const { effectiveDocument, refsOnlyDocument } = syncDebugPerformance('[NormalizeDocument]', () => {
     const effectiveDocument = normalize(
@@ -37,18 +38,8 @@ export const buildRestOperations: OperationsBuilder<OpenAPIV3.Document> = async
         originsFlag: ORIGINS_SYMBOL,
         hashFlag: HASH_FLAG,
         source: document.data,
-        ...takeIf({
-          onRefResolveError: (message: string, path: PropertyKey[], ref: string) => {
-            // console.debug([
-            //   '[Ref Resolve Error]',
-            //   `Message: ${message}`,
-            //   `JSON path: ${path}`,
-            //   `Ref: ${ref}`,
-            // ].join('\n'))
-            // todo is this message enough? (ErrorMessage.refNotFound)
-            throw new Error(message)
-          },
-        }, !!ctx.config.strictValidation),
+        onRefResolveError: (_: string, __: PropertyKey[], ref: string) =>
+          bundlingErrorHandler([`The $ref "${ref}" references an invalid location in the document.`]),
       },
     ) as OpenAPIV3.Document
     const refsOnlyDocument = normalize(

src/apitypes/unknown/unknown.document.ts

@@ -15,7 +15,7 @@
  */
 
 import { BuildConfigFile, DocumentBuilder, DocumentDumper, File, VersionDocument } from '../../types'
-import { getBundledFileDataWithDependencies, getDocumentTitle } from '../../utils'
+import { createBundlingErrorHandler, getBundledFileDataWithDependencies, getDocumentTitle } from '../../utils'
 import { FILE_FORMAT } from '../../consts'
 
 export const buildUnknownDocument: DocumentBuilder<string> = async (parsedFile, file, ctx) => {
@@ -33,7 +33,7 @@ export const buildUnknownDocument: DocumentBuilder<string> = async (parsedFile,
       const {
         data,
         dependencies: fileDependencies,
-      } = await getBundledFileDataWithDependencies(fileId, ctx.parsedFileResolver, !!ctx.config.strictValidation)
+      } = await getBundledFileDataWithDependencies(fileId, ctx.parsedFileResolver, createBundlingErrorHandler(ctx, fileId))
       bundledFileData = data
       dependencies = fileDependencies
     }

src/builder.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import type {
+import {
   BuildConfig,
   BuildConfigFile,
   BuildConfigRef,
@@ -28,6 +28,7 @@ import type {
   ResolvedDocuments,
   ResolvedOperations,
   ResolvedVersionOperationsHashMap,
+  VALIDATION_RULES_SEVERITY_LEVEL_WARNING,
   VersionId,
 } from './types'
 import {
@@ -90,7 +91,12 @@ export class PackageVersionBuilder implements IPackageVersionBuilder {
 
   constructor(config: BuildConfig, public params: BuilderParams, fileSources?: FileSourceMap) {
     this.apiBuilders.push(restApiBuilder, graphqlApiBuilder, textApiBuilder, unknownApiBuilder)
-    this.config = { previousVersion: '', previousVersionPackageId: '', strictValidation: true, ...config }
+    this.config = {
+      previousVersion: '',
+      previousVersionPackageId: '',
+      validationRulesSeverity: { brokenRefs: VALIDATION_RULES_SEVERITY_LEVEL_WARNING },
+      ...config,
+    }
 
     this.params.configuration = {
       batchSize: DEFAULT_BATCH_SIZE,

src/components/document.ts

@@ -55,7 +55,7 @@ export const buildDocument = async (parsedFile: File, file: BuildConfigFile, ctx
 
     return await apiBuilder.buildDocument(parsedFile, file, ctx)
   } catch (error) {
-    throw new Error(`Cannot build file ${file.fileId}. ${error instanceof Error ? error.message : 'Unknown error'}`)
+    throw new Error(`Cannot process the "${file.fileId}" document. ${error instanceof Error ? error.message : 'Unknown error'}`)
   }
 }
 

src/types/external/config.ts

@@ -29,6 +29,17 @@ export type OperationsGroupExportFormat =
   | typeof JSON_EXPORT_GROUP_FORMAT
   | typeof HTML_EXPORT_GROUP_FORMAT
 
+export const VALIDATION_RULES_SEVERITY_LEVEL_ERROR = 'error'
+export const VALIDATION_RULES_SEVERITY_LEVEL_WARNING = 'warning'
+
+export type ValidationRulesSeverityLevel =
+  | typeof VALIDATION_RULES_SEVERITY_LEVEL_ERROR
+  | typeof VALIDATION_RULES_SEVERITY_LEVEL_WARNING
+
+export interface ValidationRulesSeverity {
+  brokenRefs: ValidationRulesSeverityLevel
+}
+
 export interface BuildConfig {
   packageId: PackageId
   version: VersionId // @revision for rebuild
@@ -49,7 +60,7 @@ export interface BuildConfig {
   metadata?: Record<string, unknown>
   format?: OperationsGroupExportFormat
 
-  strictValidation?: boolean
+  validationRulesSeverity?: ValidationRulesSeverity
 }
 
 export interface BuildConfigFile {

src/utils/document.ts

@@ -18,6 +18,7 @@ import createSlug from 'slug'
 import {
   _ParsedFileResolver,
   ApiOperation,
+  BuilderContext,
   BuildResult,
   FILE_KIND,
   FileFormat,
@@ -27,12 +28,14 @@ import {
   OperationsGroupExportFormat,
   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 } from '../consts'
-import { takeIf } from './objects'
+import { FILE_FORMAT_JSON, FILE_FORMAT_YAML, MESSAGE_SEVERITY } from '../consts'
+import { isNotEmpty } from './arrays'
 
 export const EXPORT_FORMAT_TO_FILE_FORMAT = new Map<OperationsGroupExportFormat, FileFormat>([
   [YAML_EXPORT_GROUP_FORMAT, FILE_FORMAT_YAML],
@@ -118,24 +121,42 @@ 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:
+      for (const message of messages) {
+        ctx.notifications.push({
+          severity: MESSAGE_SEVERITY.Error,
+          message: message,
+          fileId: fileId,
+        })
+      }
+  }
+}
+
 export const getBundledFileDataWithDependencies = async (
   fileId: FileId,
   parsedFileResolver: _ParsedFileResolver,
-  throwOnBadRef: boolean,
+  onError: (messages: string[]) => void,
 ): Promise<{ data: any; dependencies: string[] }> => {
   const dependencies: string[] = []
+  const errorMessages: string[] = []
 
   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.`)
       return {}
     }
 
-    // todo: this error has no effect because it is suppressed here: https://github.com/udamir/api-ref-bundler/blob/master/src/resolver.ts#L33
-    // move this throw to bundler hooks or you'll see just "Cannot resolve: filename" message in case of wrong file kind
     if (data.kind !== FILE_KIND.TEXT) {
-      throw new Error(`Dependency with path ${filepath} is not a text file`)
+      // 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.`)
+      return {}
     }
 
     if (filepath !== fileId) {
@@ -145,14 +166,11 @@ export const getBundledFileDataWithDependencies = async (
     return data.data
   }
 
-  const bundledFileData = await bundle(fileId, resolver, {
-    hooks: {
-      ...takeIf(
-        { onError: (message: string) => { throw new Error(message) } },
-        throwOnBadRef,
-      ),
-    },
-  })
+  const bundledFileData = await bundle(fileId, resolver)
+
+  if (isNotEmpty(errorMessages)) {
+    onError(errorMessages)
+  }
 
   return { data: bundledFileData, dependencies: dependencies }
 }

test/projects/reference-bundling/case6/Test.png

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

test/projects/reference-bundling/case6/config.json

@@ -0,0 +1,16 @@
+openapi: 3.0.1
+info:
+  title: API
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      responses:
+        '200':
+          description: description
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: './Test.png'