feat: Review

Author: makeev-pavel

src/apitypes/graphql/graphql.operation.ts

@@ -19,13 +19,12 @@ import {
   getKeyValue,
   getSplittedVersionKey,
   isOperationDeprecated,
-  rawToApiKind,
   removeComponents,
   setValueByPath,
   takeIf,
   takeIfDefined,
 } from '../../utils'
-import { APIHUB_API_COMPATIBILITY_KIND, INLINE_REFS_FLAG, ORIGINS_SYMBOL, VERSION_STATUS } from '../../consts'
+import { APIHUB_API_BWC_KIND, INLINE_REFS_FLAG, ORIGINS_SYMBOL, VERSION_STATUS } from '../../consts'
 import { GraphQLSchemaType, VersionGraphQLDocument, VersionGraphQLOperation } from './graphql.types'
 import { GRAPHQL_API_TYPE, GRAPHQL_TYPE } from './graphql.consts'
 import { GraphApiSchema } from '@netcracker/qubership-apihub-graphapi'
@@ -89,7 +88,7 @@ export const buildGraphQLOperation = (
     operationId,
     documentId: documentSlug,
     apiType: GRAPHQL_API_TYPE,
-    apiKind: rawToApiKind(documentApiKind, APIHUB_API_COMPATIBILITY_KIND.BWC),
+    apiKind: documentApiKind || APIHUB_API_BWC_KIND,
     deprecated: !!singleOperationEffectiveSpec[type]?.[method]?.directives?.deprecated,
     title: toTitleCase(method),
     metadata: {

src/apitypes/rest/rest.changes.ts

@@ -83,7 +83,7 @@ import {
   OperationsMap,
 } from '../../components'
 import { createApiKindChecker } from '../../components/compare/bwc.validation'
-import { calculateApiKindFromLabels, getApiKind } from '../../components/document'
+import { calculateApiKindFromLabels, getApiKindProperty } from '../../components/document'
 
 export const compareDocuments: DocumentsCompare = async (
   operationsMap: OperationsMap,
@@ -125,8 +125,8 @@ export const compareDocuments: DocumentsCompare = async (
     currDocData = createCopyWithEmptyPathItems(prevDocData)
   }
 
-  const prevApiKind = prevDoc?.apiKind || getApiKind(prevDocData?.info) || calculateApiKindFromLabels(prevDoc?.labels, previousVersionLabels)
-  const currApiKind = currDoc?.apiKind || getApiKind(currDocData?.info) || calculateApiKindFromLabels(currDoc?.labels, currentVersionLabels)
+  const prevDocumentApiKind = prevDoc?.apiKind || getApiKindProperty(prevDocData?.info) || calculateApiKindFromLabels(prevDoc?.labels, previousVersionLabels)
+  const currDocumentApiKind = currDoc?.apiKind || getApiKindProperty(currDocData?.info) || calculateApiKindFromLabels(currDoc?.labels, currentVersionLabels)
 
   const { merged, diffs } = apiDiff(
     prevDocData,
@@ -139,7 +139,7 @@ export const compareDocuments: DocumentsCompare = async (
       normalizedResult: false,
       afterValueNormalizedProperty: AFTER_VALUE_NORMALIZED_PROPERTY,
       beforeValueNormalizedProperty: BEFORE_VALUE_NORMALIZED_PROPERTY,
-      apiCompatibilityScopeFunction: createApiKindChecker(prevApiKind, currApiKind),
+      apiCompatibilityScopeFunction: createApiKindChecker(prevDocumentApiKind, currDocumentApiKind),
     },
   ) as { merged: OpenAPIV3.Document; diffs: Diff[] }
 

src/apitypes/rest/rest.document.ts

@@ -40,7 +40,7 @@ import { dump } from './rest.utils'
 import { generateHtmlPage } from '../../utils/export'
 import { removeOasExtensions } from '../../utils/removeOasExtensions'
 import { OpenApiExtensionKey } from '@netcracker/qubership-apihub-api-unifier'
-import { getApiKind } from '../../components/document'
+import { getApiKindProperty } from '../../components/document'
 
 const openApiDocumentMeta = (data: OpenAPIV3.Document): RestDocumentInfo => {
   if (typeof data !== 'object' || !data) {
@@ -76,7 +76,7 @@ export const buildRestDocument: DocumentBuilder<OpenAPIV3.Document> = async (par
 
   let bundledFileData = data
 
-  const documentApiKind = getApiKind(bundledFileData?.info) || apiKind
+  const documentApiKind = getApiKindProperty(bundledFileData?.info) || apiKind
 
   if (parsedFile.type === REST_DOCUMENT_TYPE.SWAGGER) {
     try {

src/apitypes/rest/rest.operation.ts

@@ -16,7 +16,7 @@
 
 import { JsonPath, syncCrawl } from '@netcracker/qubership-apihub-json-crawl'
 import { OpenAPIV3 } from 'openapi-types'
-import { REST_API_TYPE, REST_KIND_KEY } from './rest.consts'
+import { REST_API_TYPE } from './rest.consts'
 import { operationRules } from './rest.rules'
 import type * as TYPE from './rest.types'
 import { RestOperationData } from './rest.types'
@@ -30,9 +30,9 @@ import {
   SearchScopes,
 } from '../../types'
 import {
+  _calculateRestOperationIdV1,
   buildSearchScope,
   calculateRestOperationId,
-  _calculateRestOperationIdV1,
   capitalize,
   extractSymbolProperty,
   getKeyValue,
@@ -42,12 +42,11 @@ import {
   isOperationDeprecated,
   isValidHttpMethod,
   normalizePath,
-  rawToApiKind,
   setValueByPath,
   takeIf,
   takeIfDefined,
 } from '../../utils'
-import { APIHUB_API_COMPATIBILITY_KIND, INLINE_REFS_FLAG, ORIGINS_SYMBOL, VERSION_STATUS } from '../../consts'
+import { APIHUB_API_BWC_KIND, INLINE_REFS_FLAG, ORIGINS_SYMBOL, VERSION_STATUS } from '../../consts'
 import { extractSecuritySchemesNames, getCustomTags, resolveApiAudience } from './rest.utils'
 import { DebugPerformanceContext, syncDebugPerformance } from '../../utils/logs'
 import {
@@ -68,6 +67,7 @@ import { extractOperationBasePath } from '@netcracker/qubership-apihub-api-diff'
 import { calculateHash, ObjectHashCache } from '../../utils/hashes'
 import { calculateTolerantHash } from '../../components/deprecated'
 import { getValueByPath } from '../../utils/path'
+import { getApiKindProperty } from '../../components/document'
 
 export const buildRestOperation = (
   operationId: string,
@@ -142,7 +142,7 @@ export const buildRestOperation = (
   }, debugCtx)
 
   const models: Record<string, string> = {}
-  const apiKind = effectiveOperationObject[REST_KIND_KEY] || documentApiKind || APIHUB_API_COMPATIBILITY_KIND.BWC
+  const operationApiKind = getApiKindProperty(effectiveOperationObject) || documentApiKind || APIHUB_API_BWC_KIND
   const [specWithSingleOperation] = syncDebugPerformance('[ModelsAndOperationHashing]', () => {
     const operationSecurity = effectiveOperationObject.security
     const specWithSingleOperation = createSingleOperationSpec(
@@ -171,7 +171,7 @@ export const buildRestOperation = (
     operationId,
     documentId: documentSlug,
     apiType: REST_API_TYPE,
-    apiKind: rawToApiKind(apiKind, APIHUB_API_COMPATIBILITY_KIND.BWC),
+    apiKind: operationApiKind,
     deprecated: !!effectiveOperationObject.deprecated,
     title: effectiveOperationObject.summary || operationId.split('-').map(str => capitalize(str)).join(' '),
     metadata: {

src/components/compare/bwc.validation.ts

@@ -14,67 +14,53 @@
  * limitations under the License.
  */
 
-import { APIHUB_API_COMPATIBILITY_KIND } from '../../consts'
+import { APIHUB_API_BWC_KIND, APIHUB_API_NO_BWC_KIND, ApihubApiCompatibilityKind } from '../../consts'
 import { isObject, isValidHttpMethod } from '../../utils'
 import { JsonPath } from '@netcracker/qubership-apihub-json-crawl'
 import {
-  ApiCompatibilityKind,
   ApiCompatibilityScope,
   ApiCompatibilityScopeFunction,
+  BACKWARD_COMPATIBLE,
+  NOT_BACKWARD_COMPATIBLE,
 } from '@netcracker/qubership-apihub-api-diff'
-import { ApihubApiCompatibilityKind } from '../../types'
-import { getApiKind } from '../document'
-
-const convertApihubToApiCompatibilityKind = (apihubApiKind: ApihubApiCompatibilityKind): ApiCompatibilityKind => {
-  switch (apihubApiKind) {
-    case APIHUB_API_COMPATIBILITY_KIND.BWC:
-      return ApiCompatibilityKind.BACKWARD_COMPATIBLE
-    case APIHUB_API_COMPATIBILITY_KIND.NO_BWC:
-      return ApiCompatibilityKind.NOT_BACKWARD_COMPATIBLE
-    default:
-      return ApiCompatibilityKind.BACKWARD_COMPATIBLE
-  }
-}
-
-export const getApiCompatibilityKind = (
-  beforeJson: unknown,
-  afterJson: unknown,
-  beforeParentApiKind: ApihubApiCompatibilityKind,
-  afterParentApiKind: ApihubApiCompatibilityKind,
-): ApiCompatibilityKind | undefined => {
-  const beforeKind = getApiKind(beforeJson) ?? beforeParentApiKind
-  const afterKind = getApiKind(afterJson) ?? afterParentApiKind
-
-  if (beforeKind === APIHUB_API_COMPATIBILITY_KIND.NO_BWC || afterKind === APIHUB_API_COMPATIBILITY_KIND.NO_BWC) {
-    return convertApihubToApiCompatibilityKind(APIHUB_API_COMPATIBILITY_KIND.NO_BWC)
+import { getApiKindProperty } from '../document'
+import { OpenAPIV3 } from 'openapi-types'
+
+export const calculateOperationApiCompatibilityKind = (
+  beforeOperationObject: OpenAPIV3.OperationObject | undefined,
+  afterOperationObject: OpenAPIV3.OperationObject | undefined,
+  beforeDefaultApiKind: ApihubApiCompatibilityKind,
+  afterDefaultApiKind: ApihubApiCompatibilityKind,
+): ApiCompatibilityScope | undefined => {
+  const beforeKind = getApiKindProperty(beforeOperationObject, beforeDefaultApiKind)
+  const afterKind = getApiKindProperty(afterOperationObject, afterDefaultApiKind)
+
+  if (beforeKind === APIHUB_API_NO_BWC_KIND || afterKind === APIHUB_API_NO_BWC_KIND) {
+    return NOT_BACKWARD_COMPATIBLE
   }
 
-  if (beforeKind === APIHUB_API_COMPATIBILITY_KIND.BWC && afterKind === APIHUB_API_COMPATIBILITY_KIND.BWC) {
-    return convertApihubToApiCompatibilityKind(APIHUB_API_COMPATIBILITY_KIND.BWC)
+  if (beforeKind === APIHUB_API_BWC_KIND && afterKind === APIHUB_API_BWC_KIND) {
+    return BACKWARD_COMPATIBLE
   }
-
-  return undefined
 }
 
-export const getMethodsApiCompatibilityKind = (obj: unknown): ApiCompatibilityKind | undefined => {
-  if (checkAllMethodsHaveSameApiKind(obj, APIHUB_API_COMPATIBILITY_KIND.NO_BWC)) {
-    return convertApihubToApiCompatibilityKind(APIHUB_API_COMPATIBILITY_KIND.NO_BWC)
+export const getMethodsApiCompatibilityKind = (pathItemObject: OpenAPIV3.PathItemObject): ApiCompatibilityScope | undefined => {
+  if (checkAllMethodsHaveSameApiKind(pathItemObject, APIHUB_API_NO_BWC_KIND)) {
+    return NOT_BACKWARD_COMPATIBLE
   }
 
-  if (checkAllMethodsHaveSameApiKind(obj, APIHUB_API_COMPATIBILITY_KIND.BWC)) {
-    return convertApihubToApiCompatibilityKind(APIHUB_API_COMPATIBILITY_KIND.BWC)
+  if (checkAllMethodsHaveSameApiKind(pathItemObject, APIHUB_API_BWC_KIND)) {
+    return BACKWARD_COMPATIBLE
   }
-
-  return undefined
 }
 
-const hasApiKind = (obj: unknown, apiKind: string): boolean => {
-  return getApiKind(obj) === apiKind
+const hasApiKind = (obj: OpenAPIV3.OperationObject, apiKind: ApihubApiCompatibilityKind): boolean => {
+  return getApiKindProperty(obj) === apiKind
 }
 
 // If a path object is removed/added, we must ensure every HTTP method under it
 // is explicitly marked NO_BWC before treating the change as risky.
-const checkAllMethodsHaveSameApiKind = (obj: unknown, apiKind: string): boolean => {
+const checkAllMethodsHaveSameApiKind = (obj: OpenAPIV3.PathItemObject, apiKind: ApihubApiCompatibilityKind): boolean => {
   if (!isObject(obj)) {
     return false
   }
@@ -93,12 +79,12 @@ const PATH_ITEM_PATH_LENGTH = 2
 const OPERATION_OBJECT_PATH_LENGTH = 3
 
 export const createApiKindChecker = (
-  prevApiKind: ApihubApiCompatibilityKind = APIHUB_API_COMPATIBILITY_KIND.BWC,
-  currApiKind: ApihubApiCompatibilityKind = APIHUB_API_COMPATIBILITY_KIND.BWC,
+  prevDocumentApiKind: ApihubApiCompatibilityKind = APIHUB_API_BWC_KIND,
+  currDocumentApiKind: ApihubApiCompatibilityKind = APIHUB_API_BWC_KIND,
 ): ApiCompatibilityScopeFunction => {
-  const defaultApiCompatibilityKind = (prevApiKind === APIHUB_API_COMPATIBILITY_KIND.NO_BWC || currApiKind === APIHUB_API_COMPATIBILITY_KIND.NO_BWC)
-    ? ApiCompatibilityKind.NOT_BACKWARD_COMPATIBLE
-    : ApiCompatibilityKind.BACKWARD_COMPATIBLE
+  const defaultApiCompatibilityKind = (prevDocumentApiKind === APIHUB_API_NO_BWC_KIND || currDocumentApiKind === APIHUB_API_NO_BWC_KIND)
+    ? NOT_BACKWARD_COMPATIBLE
+    : BACKWARD_COMPATIBLE
 
   return (
     path?: JsonPath,
@@ -147,7 +133,10 @@ export const createApiKindChecker = (
     }
 
     if (pathLength === OPERATION_OBJECT_PATH_LENGTH) {
-      return getApiCompatibilityKind(beforeJson, afterJson, prevApiKind, currApiKind)
+      const beforeOperationObject = beforeJson as OpenAPIV3.OperationObject | undefined
+      const afterOperationObject = afterJson as OpenAPIV3.OperationObject | undefined
+
+      return calculateOperationApiCompatibilityKind(beforeOperationObject, afterOperationObject, prevDocumentApiKind, currDocumentApiKind)
     }
 
     return undefined

src/components/document.ts

@@ -14,8 +14,14 @@
  * limitations under the License.
  */
 
-import { ApihubApiCompatibilityKind, BuildConfigFile, BuilderContext, FILE_KIND, SourceFile, TextFile, VersionDocument } from '../types'
-import { APIHUB_API_COMPATIBILITY_KIND, API_KIND_LABEL, DOCUMENT_TYPE, FILE_FORMAT_UNKNOWN } from '../consts'
+import { BuildConfigFile, BuilderContext, FILE_KIND, SourceFile, TextFile, VersionDocument } from '../types'
+import {
+  API_KIND_LABEL,
+  APIHUB_API_BWC_KIND,
+  ApihubApiCompatibilityKind,
+  DOCUMENT_TYPE,
+  FILE_FORMAT_UNKNOWN,
+} from '../consts'
 import {
   createVersionInternalDocument,
   getDocumentTitle,
@@ -65,7 +71,7 @@ export const buildDocument = async (parsedFile: SourceFile, file: BuildConfigFil
 
 export const calculateApiKindFromLabels = (fileLabels: unknown, versionLabels: unknown): ApihubApiCompatibilityKind => {
   if (!Array.isArray(fileLabels) && !Array.isArray(versionLabels)) {
-    return APIHUB_API_COMPATIBILITY_KIND.BWC
+    return APIHUB_API_BWC_KIND
   }
 
   const labels = [
@@ -80,13 +86,13 @@ export const calculateApiKindFromLabels = (fileLabels: unknown, versionLabels: u
 
     const match = new RegExp(`${API_KIND_LABEL}:`).exec(label)
     if (match) {
-      return rawToApiKind(label.slice(match[0].length).trim(), APIHUB_API_COMPATIBILITY_KIND.BWC)
+      return rawToApiKind(label.slice(match[0].length).trim(), APIHUB_API_BWC_KIND)
     }
   }
-  return APIHUB_API_COMPATIBILITY_KIND.BWC
+  return APIHUB_API_BWC_KIND
 }
 
-export const getApiKind = (obj: unknown, defaultApiKind?: ApihubApiCompatibilityKind): ApihubApiCompatibilityKind | undefined => {
+export const getApiKindProperty = (obj: unknown, defaultApiKind?: ApihubApiCompatibilityKind): ApihubApiCompatibilityKind | undefined => {
   if (isObject(obj)) {
     const apiKindLike = obj?.[REST_KIND_KEY]
     if (isString(apiKindLike)) {

src/consts.ts

@@ -108,11 +108,13 @@ export const VERSION_STATUS = {
   NONE: '', // non-existent status for changelog builds
 } as const
 
-export const APIHUB_API_COMPATIBILITY_KIND = {
-  BWC: 'bwc',
-  NO_BWC: 'no-bwc',
-  EXPERIMENTAL: 'experimental',
-} as const
+export const APIHUB_API_BWC_KIND = 'bwc'
+export const APIHUB_API_NO_BWC_KIND = 'no-bwc'
+export const APIHUB_API_EXPERIMENTAL_KIND = 'experimental'
+
+export type ApihubApiCompatibilityKind = typeof APIHUB_API_BWC_KIND
+  | typeof APIHUB_API_NO_BWC_KIND
+  | typeof APIHUB_API_EXPERIMENTAL_KIND
 
 export const API_KIND_LABEL = 'apihub/x-api-kind'
 

src/types/external/config.ts

@@ -15,9 +15,15 @@
  */
 
 import { FileId, KeyOfConstType, OperationsApiType, PackageId, VersionId } from './types'
-import { BUILD_TYPE, FILE_FORMAT_HTML, FILE_FORMAT_JSON, FILE_FORMAT_YAML, VERSION_STATUS } from '../../consts'
+import {
+  ApihubApiCompatibilityKind,
+  BUILD_TYPE,
+  FILE_FORMAT_HTML,
+  FILE_FORMAT_JSON,
+  FILE_FORMAT_YAML,
+  VERSION_STATUS,
+} from '../../consts'
 import { OpenApiExtensionKey } from '@netcracker/qubership-apihub-api-unifier'
-import { ApihubApiCompatibilityKind } from './operations'
 
 export type BuildType = KeyOfConstType<typeof BUILD_TYPE>
 export type VersionStatus = KeyOfConstType<typeof VERSION_STATUS>

src/types/external/documents.ts

@@ -17,7 +17,7 @@
 import { FileId, OperationsApiType, PackageId, TemplatePath, VersionId } from './types'
 import { ResolvedReferenceMap } from './references'
 import { FileFormat } from '../internal'
-import { ApihubApiCompatibilityKind } from './operations'
+import { ApihubApiCompatibilityKind } from '../../consts'
 
 export type ResolvedDocument = {
   fileId: string

src/types/external/operations.ts

@@ -14,12 +14,10 @@
  * limitations under the License.
  */
 
-import { KeyOfConstType, OperationId, OperationsApiType, PackageId, VersionId } from './types'
+import { OperationId, OperationsApiType, PackageId, VersionId } from './types'
 import { DeprecateItem } from './deprecated'
-import { APIHUB_API_COMPATIBILITY_KIND } from '../../consts'
 import { ApiAudience } from '../package'
-
-export type ApihubApiCompatibilityKind = KeyOfConstType<typeof APIHUB_API_COMPATIBILITY_KIND>
+import { ApihubApiCompatibilityKind } from '../../consts'
 
 export type VersionOperationsResolver = (
   apiType: OperationsApiType,