feat: fail invalid ref publication

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)
+  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 } 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,6 +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.`]),
       },
     ) 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)
+      } = 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 {
@@ -50,7 +51,14 @@ import {
 import type { NotificationMessage, PackageConfig } from './types/package'
 import { graphqlApiBuilder, REST_API_TYPE, restApiBuilder, textApiBuilder, unknownApiBuilder } from './apitypes'
 import { filesDiff, findSharedPath, getCompositeKey, getFileExtension, getOperationsList } from './utils'
-import { BUILD_TYPE, DEFAULT_BATCH_SIZE, MESSAGE_SEVERITY, SUPPORTED_FILE_FORMATS, VERSION_STATUS } from './consts'
+import {
+  BUILD_TYPE,
+  DEFAULT_BATCH_SIZE,
+  DEFAULT_VALIDATION_RULES_SEVERITY_CONFIG,
+  MESSAGE_SEVERITY,
+  SUPPORTED_FILE_FORMATS,
+  VERSION_STATUS,
+} from './consts'
 import { unknownParsedFile } from './apitypes/unknown/unknown.parser'
 import { createVersionPackage } from './components/package'
 import { compareVersions } from './components/compare'
@@ -90,7 +98,15 @@ export class PackageVersionBuilder implements IPackageVersionBuilder {
 
   constructor(config: BuildConfig, public params: BuilderParams, fileSources?: FileSourceMap) {
     this.apiBuilders.push(restApiBuilder, graphqlApiBuilder, textApiBuilder, unknownApiBuilder)
-    this.config = { previousVersion: '', previousVersionPackageId: '', ...config }
+    this.config = {
+      previousVersion: '',
+      previousVersionPackageId: '',
+      ...config,
+      validationRulesSeverity: {
+        ...DEFAULT_VALIDATION_RULES_SEVERITY_CONFIG,
+        ...config.validationRulesSeverity,
+      },
+    }
 
     this.params.configuration = {
       batchSize: DEFAULT_BATCH_SIZE,
@@ -232,11 +248,6 @@ export class PackageVersionBuilder implements IPackageVersionBuilder {
 
     const source = await this.params.resolvers.fileResolver(fileId)
     if (!source) {
-      this.notifications.push({
-        severity: MESSAGE_SEVERITY.Error,
-        message: 'Cannot resolve file',
-        fileId: fileId,
-      })
       return null
     }
 

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/components/operations.ts

@@ -24,7 +24,7 @@ export const buildOperations = async (document: VersionDocument, ctx: BuilderCon
     try {
       return await builder.buildOperations?.(document, ctx, debugCtx) ?? []
     } catch (error) {
-      throw new Error(`Cannot build document "${document.slug}" operations. ${error instanceof Error ? error.message : 'Unknown error'}`)
+      throw new Error(`Cannot process the "${document.fileId}" document. ${error instanceof Error ? error.message : 'Unknown error'}`)
     }
   }
 

src/consts.ts

@@ -23,10 +23,16 @@ import {
   NON_BREAKING_CHANGE_TYPE,
   SEMI_BREAKING_CHANGE_TYPE,
   UNCLASSIFIED_CHANGE_TYPE,
+  VALIDATION_RULES_SEVERITY_LEVEL_WARNING,
+  ValidationRulesSeverity,
 } from './types'
 
 export const DEFAULT_BATCH_SIZE = 32
 
+export const DEFAULT_VALIDATION_RULES_SEVERITY_CONFIG: ValidationRulesSeverity = {
+  brokenRefs: VALIDATION_RULES_SEVERITY_LEVEL_WARNING,
+}
+
 export const REVISION_DELIMITER = '@'
 
 export const VERSION_DIFFERENCE_ACTION = {

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
@@ -48,6 +59,8 @@ export interface BuildConfig {
 
   metadata?: Record<string, unknown>
   format?: OperationsGroupExportFormat
+
+  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,11 +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 { 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],
@@ -117,21 +121,43 @@ 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 const getBundledFileDataWithDependencies = async (
   fileId: FileId,
   parsedFileResolver: _ParsedFileResolver,
+  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 {}
     }
 
     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) {
@@ -143,6 +169,10 @@ export const getBundledFileDataWithDependencies = async (
 
   const bundledFileData = await bundle(fileId, resolver)
 
+  if (isNotEmpty(errorMessages)) {
+    onError(errorMessages)
+  }
+
   return { data: bundledFileData, dependencies: dependencies }
 }
 

test/helpers/matchers.ts

@@ -15,10 +15,13 @@
  */
 
 import {
+  BuildResult,
   ChangeMessage,
   ChangeSummary,
   DeprecateItem,
   EMPTY_CHANGE_SUMMARY,
+  MESSAGE_SEVERITY,
+  NotificationMessage,
   OperationChanges,
   type OperationsApiType,
   OperationType,
@@ -32,6 +35,8 @@ import { ArrayContaining, ObjectContaining, RecursiveMatcher } from '../../.jest
 export type ApihubComparisonMatcher = ObjectContaining<VersionsComparison> & VersionsComparison
 export type ApihubOperationChangesMatcher = ObjectContaining<OperationChanges> & OperationChanges
 export type ApihubChangesSummaryMatcher = ObjectContaining<ChangeSummary> & ChangeSummary
+export type ApihubNotificationsMatcher = ObjectContaining<BuildResult> & BuildResult
+export type ApihubErrorNotificationMatcher = ObjectContaining<NotificationMessage> & NotificationMessage
 export type ApihubChangeMessagesMatcher = ArrayContaining<ChangeMessage> & ChangeMessage[]
 
 export function apihubComparisonMatcher(
@@ -130,3 +135,21 @@ export function deprecatedItemDescriptionMatcher(
 }
 
 type Matcher = ObjectContaining<DeprecateItem>
+
+export function notificationsMatcher(
+  expected: Array<RecursiveMatcher<NotificationMessage>>,
+): ApihubNotificationsMatcher {
+  return expect.objectContaining({
+      notifications: expect.toIncludeSameMembers(expected),
+    },
+  )
+}
+
+export function errorNotificationMatcher(
+  message: string | RegExp,
+): ApihubErrorNotificationMatcher {
+  return expect.objectContaining({
+    message: expect.stringMatching(message),
+    severity: MESSAGE_SEVERITY.Error,
+  })
+}