feat!: explicitly provide ref error type (#9)

* feat!: explicitly provide ref error type

* build: add additional branches on push

* feat: provide additional details in richRefObjectNotAllowed error message

Author: b41ex

src/define-origins-and-resolve-ref.ts

@@ -18,6 +18,7 @@ import {
   NormalizationRule,
   OriginCache,
   OriginsMetaRecord,
+  RefErrorTypes,
   ResolveOptions,
   RichReference,
 } from './types'
@@ -164,15 +165,15 @@ const createDefineOriginsAndResolveRefHook: (rootJso: unknown, options: Internal
           value: JSON_SCHEMA_PROPERTY_REF,
         }, state.originCache) //abuse cache. Keys should be a real node value only!!!
         if (typeof $ref !== 'string') {
-          options.onRefResolveError?.(ErrorMessage.refNotValidFormat($ref), path, $ref)
+          options.onRefResolveError?.(ErrorMessage.refNotValidFormat($ref), path, $ref, RefErrorTypes.REF_NOT_VALID_FORMAT)
           const brokenValueClone = { [JSON_SCHEMA_PROPERTY_REF]: $ref }
           state.node[safeKey] = brokenValueClone
           setOrigins(state.node, safeKey, options.originsFlag, [originForObj])
           setOrigins(brokenValueClone, JSON_SCHEMA_PROPERTY_REF, options.originsFlag, [originForRef])
           return { done: true }
         }
         if (!options.richRefAllowed && Reflect.ownKeys(sibling).length !== 0) {
-          options.onRefResolveError?.(ErrorMessage.richRefObjectNotAllowed(), path, $ref)
+          options.onRefResolveError?.(ErrorMessage.richRefObjectNotAllowed($ref), path, $ref, RefErrorTypes.RICH_REF_NOT_ALLOWED)
           sibling = {}
         }
         const reference = parseRef($ref)
@@ -342,7 +343,7 @@ const createDefineOriginsAndResolveRefHook: (rootJso: unknown, options: Internal
             const { refValue, origin } = refInSourceJso
             return wrapRefWithAllOfIfNeed(refValue, sibling, origin)
           }
-          options.onRefResolveError?.(ErrorMessage.refNotFound($ref), path, $ref)
+          options.onRefResolveError?.(ErrorMessage.refNotFound($ref), path, $ref, RefErrorTypes.REF_NOT_FOUND)
           const brokenValueClone = { [JSON_SCHEMA_PROPERTY_REF]: $ref }
           state.node[safeKey] = brokenValueClone
           setOrigins(state.node, safeKey, options.originsFlag, [originForObj])

src/errors.ts

@@ -4,7 +4,7 @@ export const ErrorMessage = {
   mergeError: () => 'Could not merge values, they are probably incompatible',
   mergeWithBrokenRef: () => 'Could not merge values with unresolved ref',
   ruleNotFound: (key: any) => `Merge rule not found for key: ${key}`,
-  richRefObjectNotAllowed: () => `${JSON_SCHEMA_PROPERTY_REF} can't have siblings in this specification version`,
+  richRefObjectNotAllowed: (ref: string) => `${JSON_SCHEMA_PROPERTY_REF} can't have siblings in this specification version: ${ref}`,
   refNotFound: (ref: string) => `${JSON_SCHEMA_PROPERTY_REF} can't be resolved: ${ref}`,
   refNotValidFormat: (ref: string) => `${JSON_SCHEMA_PROPERTY_REF} can't be parsed: ${ref}`,
 } as const

src/types.ts

@@ -7,6 +7,14 @@ export type JsonSchema = Record<PropertyKey, unknown>
 
 export type NormalizationRules = CrawlRules<NormalizationRule>
 
+export const RefErrorTypes = {
+  RICH_REF_NOT_ALLOWED: 'richRefObjectNotAllowed' as const,
+  REF_NOT_FOUND: 'refNotFound' as const,
+  REF_NOT_VALID_FORMAT: 'refNotValidFormat' as const,
+} as const
+
+export type RefErrorType = typeof RefErrorTypes[keyof typeof RefErrorTypes]
+
 //todo ugly API. Some Flag activate transformation (like syntheticTitleFlag) some flags just mark result for transfomration
 export interface ResolveOptions {
   resolveRef?: boolean            // execute resolve ref phase (inline usages that can produce cycled JSO)
@@ -17,7 +25,7 @@ export interface ResolveOptions {
   originsFlag?: symbol            // used in JSO as anchor to chained declaration path (contains link to parent in declarationPath)
   originsAlreadyDefined?: boolean // are there already origins in the spec
   ignoreSymbols?: symbol[],       // symbols to ignore scan
-  onRefResolveError?: (message: string, path: JsonPath, ref: string) => void
+  onRefResolveError?: (message: string, path: JsonPath, ref: string, errorType: RefErrorType) => void
 }
 
 export interface MergeOptions {

test/oas/merge.errors.test.ts

@@ -1,12 +1,13 @@
 import { JsonPath } from '@netcracker/qubership-apihub-json-crawl'
-import { normalize } from '../../src'
+import { normalize, RefErrorType, RefErrorTypes } from '../../src'
 
 describe("merge errors handling", function () {
   it('should trigger onRefResolveError when merging broken $ref', (done) => {
 
-    const onRefResolveError = (message: string, path: JsonPath, ref: string) => {
+    const onRefResolveError = (message: string, path: JsonPath, ref: string, errorType: RefErrorType) => {
 
-      expect(ref).toBe ("#/foo")
+      expect(ref).toBe("#/foo")
+      expect(errorType).toBe(RefErrorTypes.REF_NOT_FOUND)
       done()
     }
 

test/oas/merge.openapi.test.ts

@@ -1,4 +1,4 @@
-import { normalize } from '../../src'
+import { normalize, RefErrorType, RefErrorTypes } from '../../src'
 import source31x from '../resources/openapi31x.json'
 import source30x from '../resources/openapi30x.json'
 import { JsonPath } from '@netcracker/qubership-apihub-json-crawl'
@@ -7,7 +7,8 @@ import { ErrorMessage } from '../../src/errors'
 interface Error {
   readonly message: string,
   readonly path: JsonPath,
-  readonly ref: unknown
+  readonly ref: unknown,
+  readonly errorType: RefErrorType
 }
 
 describe('merge allof in openapi schema', function () {
@@ -128,7 +129,7 @@ describe('merge allof in openapi schema', function () {
     const errors: Error[] = []
     const result = normalize({ ...documentFragment, openapi: '3.0.0' }, {
       source: documentSource,
-      onRefResolveError: (message, path, ref) => errors.push({ message, path, ref: ref }),
+      onRefResolveError: (message, path, ref, errorType) => errors.push({ message, path, ref: ref, errorType }),
     })
     const expected = {
       openapi: '3.0.0',
@@ -170,19 +171,22 @@ describe('merge allof in openapi schema', function () {
     expect(result).toEqual(expected)
     expect(errors).toEqual([
       {
-        message: ErrorMessage.richRefObjectNotAllowed(),
+        message: ErrorMessage.richRefObjectNotAllowed('#/components/schemas/Human'),
         path: ['paths', 'humans', 'get', 'responses', '200', 'content', 'application/json', 'schema', 'items'],
         ref: '#/components/schemas/Human',
+        errorType: RefErrorTypes.RICH_REF_NOT_ALLOWED
       },
       {
-        message: ErrorMessage.richRefObjectNotAllowed(),
+        message: ErrorMessage.richRefObjectNotAllowed('#/components/schemas/Location'),
         path: ['paths', 'humans', 'get', 'responses', '200', 'content', 'application/json', 'schema', 'items', 'properties', 'location'],
         ref: '#/components/schemas/Location',
+        errorType: RefErrorTypes.RICH_REF_NOT_ALLOWED
       },
       {
-        message: ErrorMessage.richRefObjectNotAllowed(),
+        message: ErrorMessage.richRefObjectNotAllowed('#/components/schemas/Human'),
         path: ['paths', 'humans', 'get', 'responses', '200', 'content', 'application/json', 'schema', 'items', 'properties', 'location', 'allOf', 0, 'properties', 'ownedBy'],
         ref: '#/components/schemas/Human',
+        errorType: RefErrorTypes.RICH_REF_NOT_ALLOWED
       },
     ] as Error[])
   })