refactor: refine types

CountRedClaw · CountRedClaw · commit 40f8436761ee · 2025-04-23T19:31:35.000+05:00
diff --git a/src/apitypes/unknown/unknown.parser.ts b/src/apitypes/unknown/unknown.parser.ts
@@ -17,7 +17,7 @@
 import YAML from 'js-yaml'
 
 import { DOCUMENT_TYPE, FILE_FORMAT, SUPPORTED_FILE_FORMATS } from '../../consts'
-import { BinaryFile, FILE_KIND, TextFile } from '../../types/internal'
+import { BinaryFile, FILE_KIND, FileFormat, TextFile } from '../../types/internal'
 import { getFileExtension } from '../../utils'
 
 export const parseUnknownFile = async (fileId: string, source: Blob): Promise<TextFile | undefined> => {
@@ -47,6 +47,6 @@ export const parseUnknownFile = async (fileId: string, source: Blob): Promise<Te
 
 export const unknownParsedFile = (fileId: string, source: Blob): BinaryFile => {
   const extension = getFileExtension(fileId)
-  const format = SUPPORTED_FILE_FORMATS.includes(extension) ? extension : FILE_FORMAT.UNKNOWN
+  const format = (SUPPORTED_FILE_FORMATS as string[]).includes(extension) ? extension as FileFormat : FILE_FORMAT.UNKNOWN
   return { fileId, type: DOCUMENT_TYPE.UNKNOWN, format: format, source, kind: FILE_KIND.BINARY }
 }
diff --git a/src/builder.ts b/src/builder.ts
@@ -25,10 +25,9 @@ import {
   PackageId,
   ResolvedComparisonSummary,
   ResolvedDeprecatedOperations,
-  ResolvedDocuments,
+  ResolvedGroupDocuments,
   ResolvedOperations,
   ResolvedVersionOperationsHashMap,
-  VALIDATION_RULES_SEVERITY_LEVEL_WARNING,
   VersionId,
   VersionsComparison,
 } from './types'
@@ -172,7 +171,7 @@ export class PackageVersionBuilder implements IPackageVersionBuilder {
       config: this.config,
       configuration: this.params.configuration,
       builderRunOptions: this.builderRunOptions,
-      versionDocumentsResolver: this.versionDocumentsResolver.bind(this),
+      groupDocumentsResolver: this.groupDocumentsResolver.bind(this),
       templateResolver: this.params.resolvers.templateResolver,
       versionLabels: this.config.metadata?.versionLabels as Array<string>,
     }
@@ -336,20 +335,20 @@ export class PackageVersionBuilder implements IPackageVersionBuilder {
     return operations
   }
 
-  async versionDocumentsResolver(
+  async groupDocumentsResolver(
     apiType: OperationsApiType,
     version: VersionId,
     packageId: PackageId,
     filterByOperationGroup: string,
-  ): Promise<ResolvedDocuments | null> {
+  ): Promise<ResolvedGroupDocuments | null> {
     packageId = packageId ?? this.config.packageId
 
-    const { versionDocumentsResolver } = this.params.resolvers
-    if (!versionDocumentsResolver) {
-      throw new Error('No versionDocumentsResolver provided')
+    const { groupDocumentsResolver } = this.params.resolvers
+    if (!groupDocumentsResolver) {
+      throw new Error('No groupDocumentsResolver provided')
     }
 
-    const documents = await versionDocumentsResolver(
+    const documents = await groupDocumentsResolver(
       apiType,
       version,
       packageId,
@@ -542,7 +541,7 @@ export class PackageVersionBuilder implements IPackageVersionBuilder {
       return this.parsedFiles.get(fileId) ?? null
     }
 
-    if (SUPPORTED_FILE_FORMATS.includes(getFileExtension(fileId))) {
+    if ((SUPPORTED_FILE_FORMATS as string[]).includes(getFileExtension(fileId))) {
       for (const { parser } of this.apiBuilders) {
         try {
           // todo check source.type
diff --git a/src/components/document.ts b/src/components/document.ts
@@ -15,7 +15,7 @@
  */
 
 import { BuildConfigFile, BuilderContext, File, FILE_KIND, TextFile, VersionDocument } from '../types'
-import { API_KIND, API_KIND_LABEL, DOCUMENT_TYPE } from '../consts'
+import { API_KIND, API_KIND_LABEL, DOCUMENT_TYPE, FILE_FORMAT_UNKNOWN } from '../consts'
 import { getDocumentTitle, getFileExtension, rawToApiKind } from '../utils'
 import { buildBinaryDocument, unknownApiBuilder } from '../apitypes'
 
@@ -24,7 +24,7 @@ export const buildErrorDocument = (file: BuildConfigFile, parsedFile?: TextFile)
   return {
     fileId: fileId,
     type: DOCUMENT_TYPE.UNKNOWN,
-    format: getFileExtension(fileId),
+    format: FILE_FORMAT_UNKNOWN,
     data: '',
     slug,
     publish,
diff --git a/src/consts.ts b/src/consts.ts
@@ -114,6 +114,7 @@ export const FILE_FORMAT_UNKNOWN = 'unknown'
 export const FILE_FORMAT_GRAPHQL = 'graphql'
 export const FILE_FORMAT_GQL = 'gql'
 export const FILE_FORMAT_MD = 'md'
+export const FILE_FORMAT_PROTO = 'proto'
 
 export const FILE_FORMAT = {
   JSON: FILE_FORMAT_JSON,
@@ -123,7 +124,8 @@ export const FILE_FORMAT = {
   GRAPHQL: FILE_FORMAT_GRAPHQL,
   GQL: FILE_FORMAT_GQL,
   MD: FILE_FORMAT_MD,
-}
+  PROTO: FILE_FORMAT_PROTO,
+} as const
 
 export const SUPPORTED_FILE_FORMATS = Object.values(FILE_FORMAT)
 
diff --git a/src/strategies/document-group.strategy.ts b/src/strategies/document-group.strategy.ts
@@ -21,7 +21,7 @@ import {
   BuildTypeContexts,
   FileFormat,
   JSON_EXPORT_GROUP_FORMAT,
-  ResolvedDocument,
+  ResolvedGroupDocument,
   ResolvedReferenceMap,
   VersionDocument,
 } from '../types'
@@ -41,7 +41,7 @@ import { INLINE_REFS_FLAG, NORMALIZE_OPTIONS } from '../consts'
 import { normalize } from '@netcracker/qubership-apihub-api-unifier'
 import { calculateSpecRefs, extractCommonPathItemProperties } from '../apitypes/rest/rest.operation'
 
-async function getTransformedDocument(document: ResolvedDocument, format: FileFormat, packages: ResolvedReferenceMap): Promise<VersionRestDocument> {
+async function getTransformedDocument(document: ResolvedGroupDocument, format: FileFormat, packages: ResolvedReferenceMap): Promise<VersionRestDocument> {
   const versionDocument = toVersionDocument(document, format)
 
   const source = extractDocumentData(versionDocument)
@@ -88,7 +88,7 @@ export class DocumentGroupStrategy implements BuilderStrategy {
 
     const builderContextObject = builderContext(config)
 
-    const { documents, packages } = await builderContextObject.versionDocumentsResolver(
+    const { documents, packages } = await builderContextObject.groupDocumentsResolver(
       REST_API_TYPE,
       version,
       packageId,
diff --git a/src/strategies/merged-document-group.strategy.ts b/src/strategies/merged-document-group.strategy.ts
@@ -76,6 +76,8 @@ export class MergedDocumentGroupStrategy extends DocumentGroupStrategy {
     buildResult.merged = {
       fileId: info.title,
       type: firstDocument.type,
+      // todo html will be handled in api-processor
+      // @ts-ignore
       format: format,
       data: mergeOpenapiDocuments(specs, info, templateDocument),
       slug: info.title,
diff --git a/src/types/external/documents.ts b/src/types/external/documents.ts
@@ -16,29 +16,57 @@
 
 import { OperationsApiType, PackageId, VersionId } from './types'
 import { ResolvedReferenceMap } from './references'
+import { FileFormat } from '../internal'
 
 export type VersionDocumentsResolver = (
   apiType: OperationsApiType,
   version: VersionId,
   packageId: PackageId,
   filterByOperationGroup: string,
-) => Promise<ResolvedDocuments | null>
+) => Promise<ResolvedVersionDocuments | null>
 
-export type ResolvedDocuments = {
-  documents: ReadonlyArray<ResolvedDocument>
+export type ResolvedVersionDocuments = {
+  documents: ReadonlyArray<ResolvedVersionDocument>
   packages: ResolvedReferenceMap
 }
 
-export type ResolvedDocument = {
+export type ResolvedVersionDocument = {
   fileId: string
   filename: string
   slug: string
   type: string
-  format: string
+  format: FileFormat
   title: string
   version?: string
-  labels: string[]
+  labels?: Labels
+  packageRef?: string
+}
+
+export type Labels = string[]
+
+export type GroupDocumentsResolver = (
+  apiType: OperationsApiType,
+  version: VersionId,
+  packageId: PackageId,
+  filterByOperationGroup: string,
+) => Promise<ResolvedGroupDocuments | null>
+
+export type ResolvedGroupDocuments = {
+  documents: ReadonlyArray<ResolvedGroupDocument>
+  packages: ResolvedReferenceMap
+}
+
+export type ResolvedGroupDocument = {
+  fileId: string
+  filename: string
+  slug: string
+  type: string
+  format: FileFormat
+  title: string
+  version?: string
+  labels?: Labels
   includedOperationIds?: string[]
   data?: string
   packageRef?: string
+  description: string
 }
diff --git a/src/types/external/resolvers.ts b/src/types/external/resolvers.ts
@@ -16,7 +16,7 @@
 
 import { VersionComparisonResolver } from './comparison'
 import { VersionDeprecatedResolver } from './deprecated'
-import { VersionDocumentsResolver } from './documents'
+import { GroupDocumentsResolver, VersionDocumentsResolver } from './documents'
 import { VersionOperationsResolver } from './operations'
 import { VersionReferencesResolver } from './references'
 import { VersionResolver } from './version'
@@ -32,6 +32,7 @@ export interface BuilderResolvers {
   versionReferencesResolver?: VersionReferencesResolver
   versionDeprecatedResolver?: VersionDeprecatedResolver
   versionComparisonResolver?: VersionComparisonResolver
+  groupDocumentsResolver?: GroupDocumentsResolver
   versionDocumentsResolver?: VersionDocumentsResolver
   templateResolver?: TemplateResolver
 }
diff --git a/src/types/internal/apiBuilder.ts b/src/types/internal/apiBuilder.ts
@@ -23,7 +23,7 @@ import {
   PackageId,
   ResolvedOperation,
   VersionDeprecatedResolver,
-  VersionDocumentsResolver,
+  GroupDocumentsResolver,
   VersionId,
 } from '../external'
 import { CompareContext, OperationChanges } from './compare'
@@ -54,7 +54,7 @@ export interface BuilderContext<T = any> {
   config: BuildConfig
   builderRunOptions: BuilderRunOptions
   configuration?: BuilderConfiguration
-  versionDocumentsResolver: VersionDocumentsResolver
+  groupDocumentsResolver: GroupDocumentsResolver
   templateResolver?: TemplateResolver
   versionLabels?: Array<string>
 }
diff --git a/src/types/internal/documents.ts b/src/types/internal/documents.ts
@@ -24,7 +24,7 @@ export interface VersionDocuments {
 export interface VersionDocument<T = any> {
   fileId: FileId
   type: string
-  format: string
+  format: FileFormat
   data: T
   slug: string
   title: string
diff --git a/src/types/internal/internal.ts b/src/types/internal/internal.ts
@@ -17,7 +17,7 @@
 import { PackageId, VersionId } from '../external'
 import { ErrorObject } from 'ajv'
 
-import { VersionDocument } from './documents'
+import { FileFormat, VersionDocument } from './documents'
 
 export const FILE_KIND = {
   BINARY: 'binary',
@@ -27,7 +27,7 @@ export const FILE_KIND = {
 interface FileBase {
   fileId: string
   type: string
-  format: string
+  format: FileFormat
   source: Blob
 }
 
diff --git a/src/types/package/config.ts b/src/types/package/config.ts
@@ -16,6 +16,9 @@
 
 import { BuildConfigRef, BuildType, PackageId, VersionId } from '../external'
 
+
+//todo this is info.json, add format and other missing fields
+// https://apihub.netcracker.com/portal/packages/NC.CP.AH.RS/2025.1/operations/rest/api-v3-packages-packageid-publish-publishid-status-post?mode=raw#/
 export interface PackageConfig {
   packageId: PackageId
   version: VersionId
diff --git a/src/utils/document.ts b/src/utils/document.ts
@@ -27,7 +27,7 @@ import {
   JSON_EXPORT_GROUP_FORMAT,
   OperationsGroupExportFormat,
   PackageDocument,
-  ResolvedDocument,
+  ResolvedGroupDocument,
   VALIDATION_RULES_SEVERITY_LEVEL_ERROR,
   VALIDATION_RULES_SEVERITY_LEVEL_WARNING,
   VersionDocument,
@@ -43,7 +43,7 @@ export const EXPORT_FORMAT_TO_FILE_FORMAT = new Map<OperationsGroupExportFormat,
   [HTML_EXPORT_GROUP_FORMAT, FILE_FORMAT_JSON],
 ])
 
-export function toVersionDocument(document: ResolvedDocument, fileFormat: FileFormat): VersionDocument {
+export function toVersionDocument(document: ResolvedGroupDocument, fileFormat: FileFormat): VersionDocument {
   return {
     data: document.data,
     version: document.version,
diff --git a/test/helpers/registry/apihub.ts b/test/helpers/registry/apihub.ts
@@ -29,7 +29,7 @@ import {
   PackageVersionBuilder,
   ResolvedComparisonSummary,
   ResolvedDeprecatedOperations,
-  ResolvedDocuments,
+  ResolvedGroupDocuments,
   ResolvedOperations,
   ResolvedReferences,
   ResolvedVersion,
@@ -138,7 +138,8 @@ export class ApihubRegistry implements IRegistry {
       versionReferencesResolver: this.versionReferencesResolver.bind(this),
       versionComparisonResolver: this.versionComparisonResolver.bind(this),
       versionDeprecatedResolver: this.versionDeprecatedResolver.bind(this),
-      versionDocumentsResolver: this.versionDocumentsResolver.bind(this),
+      // todo versionDocumentsResolver: this.versionDocumentsResolver.bind(this),
+      groupDocumentsResolver: this.groupDocumentsResolver.bind(this),
     }
   }
 
@@ -231,15 +232,15 @@ export class ApihubRegistry implements IRegistry {
     return data ?? null
   }
 
-  async versionDocumentsResolver(
+  async groupDocumentsResolver(
     apiType: OperationsApiType,
     version: VersionId,
     packageId: PackageId,
     filterByOperationGroup: string,
-  ): Promise<ResolvedDocuments | null> {
+  ): Promise<ResolvedGroupDocuments | null> {
     const encodedPackageKey = encodeURIComponent(packageId)
     const encodedVersionKey = encodeURIComponent(version)
-    const response: ResolvedDocuments = { documents: [], packages: {} }
+    const response: ResolvedGroupDocuments = { documents: [], packages: {} }
 
     const LIMIT = 100
     let page = 0
diff --git a/test/helpers/registry/local.ts b/test/helpers/registry/local.ts
@@ -40,8 +40,8 @@ import {
   ResolvedComparisonSummary,
   ResolvedDeprecatedOperation,
   ResolvedDeprecatedOperations,
-  ResolvedDocument,
-  ResolvedDocuments,
+  ResolvedGroupDocument,
+  ResolvedGroupDocuments,
   ResolvedOperation,
   ResolvedOperations,
   ResolvedReferenceMap,
@@ -97,7 +97,7 @@ export class LocalRegistry implements IRegistry {
       versionReferencesResolver: this.versionReferencesResolver.bind(this),
       versionComparisonResolver: this.versionComparisonResolver.bind(this),
       versionDeprecatedResolver: this.versionDeprecatedResolver.bind(this),
-      versionDocumentsResolver: this.versionDocumentsResolver.bind(this),
+      groupDocumentsResolver: this.groupDocumentsResolver.bind(this),
     }
   }
 
@@ -190,12 +190,12 @@ export class LocalRegistry implements IRegistry {
     return { operations: versionOperations }
   }
 
-  async versionDocumentsResolver(
+  async groupDocumentsResolver(
     apiType: OperationsApiType,
     version: string,
     packageId: string,
     filterByOperationGroup: string,
-  ): Promise<ResolvedDocuments | null> {
+  ): Promise<ResolvedGroupDocuments | null> {
     const { config: { refs = [] } = {}, documents } = await this.getVersion(packageId || this.packageId, version) ?? {}
 
     const documentsFromVersion = Array.from(documents?.values() ?? [])
@@ -231,7 +231,7 @@ export class LocalRegistry implements IRegistry {
     return (id: string): boolean => this.groupToOperationIdsMap[filterByOperationGroup]?.includes(id)
   }
 
-  private resolveDocuments(documents: VersionDocument[], filterOperationIdsByGroup: (id: string) => boolean, refId?: string): ResolvedDocument[] {
+  private resolveDocuments(documents: VersionDocument[], filterOperationIdsByGroup: (id: string) => boolean, refId?: string): ResolvedGroupDocument[] {
     return documents
       .filter(versionDocument => versionDocument.operationIds.some(filterOperationIdsByGroup))
       .map(document => ({
@@ -244,6 +244,7 @@ export class LocalRegistry implements IRegistry {
         labels: [],
         title: document.title,
         includedOperationIds: document.operationIds.filter(filterOperationIdsByGroup),
+        description: document.description,
         data: toBase64(JSON.stringify(document.data)),
         ...takeIfDefined({ packageRef: refId }),
       }))
diff --git a/test/helpers/registry/types.ts b/test/helpers/registry/types.ts
