Merge branch 'release'

Author: b41ex

.github/super-linter.env

@@ -36,3 +36,6 @@ VALIDATE_TSX=false
 VALIDATE_TYPESCRIPT_ES=false
 VALIDATE_TYPESCRIPT_PRETTIER=false
 VALIDATE_TYPESCRIPT_STANDARD=false
+
+# Skip OPENAPI check for this repo as soon as it contains OAS 3.1 which is not supported by super-linter and contains invalid OAS 3.0 specs for testing purposes
+VALIDATE_OPENAPI=false

.qubership/grand-report.json

@@ -0,0 +1,15 @@
+{
+  "exclusions" : [ {
+    "t-hash" : "d0c92c764c5647d43d7166efc3e7d350751de063c1388bd2e113fab4865529d3",
+    "f-hash" : "3780d8d44a0ffb112a67bef412882b39ed01c95e09ad51e0567d45cbf43dc639"
+  }, {
+    "t-hash" : "d0c92c764c5647d43d7166efc3e7d350751de063c1388bd2e113fab4865529d3",
+    "f-hash" : "c084bbbd31296a950bb007771c0a53b3d8830ae129c7a5fe2333cdf043532c75"
+  }, {
+    "t-hash" : "d0c92c764c5647d43d7166efc3e7d350751de063c1388bd2e113fab4865529d3",
+    "f-hash" : "e04d08ed8d22eff358a8e65fded2a4ef6cc954fc3070acf96f5795ec99e742c1"
+  }, {
+    "t-hash" : "d0c92c764c5647d43d7166efc3e7d350751de063c1388bd2e113fab4865529d3",
+    "f-hash" : "e0d1bbde9173b4d91a89fb10ddf9ec131de758861a826c8ca0d1fc2d12681035"
+  } ]
+}

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@netcracker/qubership-apihub-api-unifier",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Tools for JsonSchema/Openapi/GraphQL spec for unified processing",
   "module": "./dist/index.es.js",
   "main": "./dist/index.cjs.js",

package.json

@@ -22,7 +22,7 @@ import {
   ResolveOptions,
   RichReference,
 } from './types'
-import { resolveSpec, SPEC_TYPE_GRAPH_API, SPEC_TYPE_OPEN_API_31 } from './spec-type'
+import { resolveSpec } from './spec-type'
 import { ErrorMessage } from './errors'
 import { createCycledJsoHandlerHook } from './cycle-jso'
 import { JSON_SCHEMA_PROPERTY_ALL_OF, JSON_SCHEMA_PROPERTY_REF } from './rules/jsonschema.const'
@@ -60,12 +60,14 @@ const IMPOSSIBLE_ORIGIN_PARENT: ChainItem = { parent: undefined, value: 'ERROR!!
 
 export const defineOriginsAndResolveRef = (value: unknown, options?: ResolveOptions) => {
   const spec = resolveSpec(value)
+  const source = options?.source ?? value
+
   const internalOptions = {
     resolveRef: DEFAULT_OPTION_RESOLVE_REF,
     originsAlreadyDefined: !!options?.originsFlag,
     ...options,
     originsFlag: options?.originsAlreadyDefined ? undefined : options?.originsFlag,
-    source: options?.source ?? value,
+    source,
     ignoreSymbols: new Set([
       ...(options?.originsFlag ? [options.originsFlag] : []),
       ...(options?.inlineRefsFlag ? [options.inlineRefsFlag] : []),
@@ -140,7 +142,13 @@ export const deDefineOriginsAndResolvedRefSymbols = (value: unknown, options?: R
 const createDefineOriginsAndResolveRefHook: (rootJso: unknown, options: InternalResolveOptions, cycleJsoHook: SyncCloneHook<DefineOriginsAndResolveRefState>) => DefineOriginsAndResolveRefSyncCloneHook = (rootJso, options, cycleJsoHook) => {
   const cyclingGuard: Set<unknown> = new Set()
   const syntheticTitleCache: Map<string, Record<PropertyKey, unknown>> = new Map()
-  const defineOriginsAndResolveRefHook: DefineOriginsAndResolveRefSyncCloneHook = ({ key, value, state, path, rules, }) => {
+  const defineOriginsAndResolveRefHook: DefineOriginsAndResolveRefSyncCloneHook = ({
+    key,
+    value,
+    state,
+    path,
+    rules,
+  }) => {
     if (state.ignoreTreeUnderSymbols) {
       return { value }
     }
@@ -189,7 +197,7 @@ const createDefineOriginsAndResolveRefHook: (rootJso: unknown, options: Internal
           }
           const reference = parseRef($ref)
 
-          const processWrapRefWithAllOfReference = (resolvedRefWithSibling: ResolvedRefWithSiblings)  => {
+          const processWrapRefWithAllOfReference = (resolvedRefWithSibling: ResolvedRefWithSiblings) => {
             const {
               refValue,
               origin,
@@ -282,9 +290,9 @@ const createDefineOriginsAndResolveRefHook: (rootJso: unknown, options: Internal
             }
           }
 
-          const processResolvedReference = (resolvedRefWithSibling: ResolvedRefWithSiblings) =>  {
+          const processResolvedReference = (resolvedRefWithSibling: ResolvedRefWithSiblings) => {
             if (hasChildrenOrigins(resolvedRefWithSibling)) {
-                return processReferenceWithChildren(resolvedRefWithSibling)
+              return processReferenceWithChildren(resolvedRefWithSibling)
             }
             return processWrapRefWithAllOfReference(resolvedRefWithSibling)
           }

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

@@ -10,7 +10,7 @@ import {
   NormalizeOptions,
 } from './types'
 import { deDefineOriginsAndResolvedRefSymbols, defineOriginsAndResolveRef } from './define-origins-and-resolve-ref'
-import { validate } from './validate'
+import { preValidate, validate } from './validate'
 import { merge } from './merge'
 import { cleanUpSynthetic, deCleanUpSynthetic, deUnify, unify } from './unify'
 import { deHash, hash } from './hash'
@@ -19,7 +19,8 @@ import { removeOasExtensions } from './remove-oas-extensions'
 export const normalize = (value: unknown, options: NormalizeOptions = {}) => {
   const optionsWithDefaults = createOptionsWithDefaults(options)
   let spec = value
-  if (optionsWithDefaults.resolveRef || (!optionsWithDefaults.originsAlreadyDefined && optionsWithDefaults.originsFlag)) { spec = defineOriginsAndResolveRef(spec, optionsWithDefaults) }
+  if (optionsWithDefaults.validate) { preValidate(spec, options) }
+  if (optionsWithDefaults.resolveRef || (!optionsWithDefaults.originsAlreadyDefined && optionsWithDefaults.originsFlag)) {spec = defineOriginsAndResolveRef(spec, optionsWithDefaults)}
   if (optionsWithDefaults.validate) { spec = validate(spec, optionsWithDefaults) }
   if (optionsWithDefaults.mergeAllOf) { spec = merge(spec, optionsWithDefaults) }
   if (optionsWithDefaults.unify) { spec = unify(spec, optionsWithDefaults) }

src/normalize.ts

@@ -438,7 +438,6 @@ export const jsonSchemaRules: (
     hashStrategy: CURRENT_DATA_LEVEL,
   },
   '/properties': {
-
     '/*': () => ({
       ...self(),
       newDataLayer: true,

src/rules/jsonschema.ts

@@ -47,6 +47,7 @@ export const OPEN_API_PROPERTY_SCHEMAS = 'schemas'
 export const OPEN_API_PROPERTY_SCHEMA = 'schema'
 export const OPEN_API_PROPERTY_LINKS = 'links'
 export const OPEN_API_PROPERTY_SECURITY_SCHEMAS = 'securitySchemes'
+export const OPEN_API_PROPERTY_PATH_ITEMS = 'pathItems'
 
 export const OPEN_API_PROPERTY_DESCRIPTION = 'description'
 export const OPEN_API_PROPERTY_SUMMARY = 'summary'

src/rules/openapi.const.ts

@@ -436,7 +436,7 @@ const customFor30JsonSchemaRulesFactory = (): NormalizationRules => {
       ...customFor30JsonSchemaRules,
       merge: resolvers.itemsMergeResolver,
       hashStrategy: CURRENT_DATA_LEVEL,
-      newDataLayer: true
+      newDataLayer: true,
     }),
     '/additionalItems': {
       validate: () => false,
@@ -704,10 +704,7 @@ const openApiPathItemRules = (version: OpenApiSpecVersion): NormalizationRules =
     validate: checkType(TYPE_OBJECT),
   }),
   '/parameters': openApiParametersRules(version),
-  referenceHandler: referenceObjectRuleFunction({
-    version,
-    allowedOverrides: [OPEN_API_PROPERTY_SUMMARY, OPEN_API_PROPERTY_DESCRIPTION],
-  }),
+  referenceHandler: referenceObjectResolver(),
   validate: checkType(TYPE_OBJECT),
   unify: pathItemsUnification,
 })
@@ -822,6 +819,18 @@ export const openApiRules = (version: OpenApiSpecVersion): NormalizationRules =>
         ...openApiExtensionRulesFunction(() => openApiPathItemRules(version)),
       },
     },
+    /**
+     * Note: For OAS 3.0, `components.pathItems` is not a valid property.
+     * We intentionally keep these rules and do not delete this path here
+     * because invalid `components.pathItems` entries are pre-processed and
+     * handled during pre-validation step.
+     * Additionally, the reference resolver contains checks that guard against
+     * misuse in OAS 3.0. See: validate.ts
+     */
+    '/pathItems': ({
+      ...openApiExtensionRulesFunction(openApiPathItemRules(version)),
+      validate: checkType(TYPE_OBJECT),
+    }),
     ...openApiExamplesRules(version),
     ...openApiExtensionRules,
     validate: checkType(TYPE_OBJECT),

src/rules/openapi.ts

@@ -7,10 +7,33 @@ import {
   ValidateSyncCloneHook,
 } from './types'
 import { isArray, isObject, JSON_ROOT_KEY, syncClone } from '@netcracker/qubership-apihub-json-crawl'
-import { resolveSpec } from './spec-type'
+import { resolveSpec, SPEC_TYPE_OPEN_API_30 } from './spec-type'
 import { createCycledJsoHandlerHook } from './cycle-jso'
 import { RULES } from './rules'
 import { cleanSeveralOrigins } from './origins'
+import { OPEN_API_PROPERTY_COMPONENTS, OPEN_API_PROPERTY_PATH_ITEMS } from './rules/openapi.const'
+
+/**
+ * Preprocesses an OpenAPI specification prior to reference resolution/origin definition.
+ *
+ * For OpenAPI 3.0 documents, `components.pathItems` is not a valid field (it was
+ * added in OAS 3.1). Some tools may still emit it. To keep the input compliant,
+ * deterministic, and to avoid misinterpreting invalid nodes as real API paths,
+ * this function removes `components.pathItems` for OAS 3.0 and emits an optional
+ * validation message via `options.onValidateError`.
+ */
+export function preValidate(source: unknown, options?: ValidateOptions & ResolveOptions): void {
+  const spec = resolveSpec(source)
+  if (spec.type !== SPEC_TYPE_OPEN_API_30 || !isObject(source)) {
+    return
+  }
+  if (OPEN_API_PROPERTY_COMPONENTS in source && isObject(source.components)) {
+    const components = source.components as Record<string, unknown>
+    if (Reflect.deleteProperty(components, OPEN_API_PROPERTY_PATH_ITEMS)) {
+      (options as ValidateOptions)?.onValidateError?.(`Invalid property 'components.pathItems' for OpenAPI 3.0. The property has been removed to maintain 3.0 compliance.`, ['components', 'pathItems'], 'pathItems')
+    }
+  }
+}
 
 const createValidationHook: (options: InternalValidationOptions) => ValidateSyncCloneHook = (options) => {
   const validateHook: ValidateSyncCloneHook = ({ key, path, value, rules, state }) => {