fix: use packageName instead of packageId in html

Author: CountRedClaw

src/builder.ts

@@ -77,6 +77,7 @@ import { asyncDebugPerformance } from './utils/logs'
 import { ExportVersionStrategy } from './strategies/export-version.strategy'
 import { ExportRestDocumentStrategy } from './strategies/export-rest-document.strategy'
 import { ExportRestOperationsGroupStrategy } from './strategies/export-rest-operations-group.strategy'
+import { ResolvedPackage } from './types/external/package'
 
 export const DEFAULT_RUN_OPTIONS: BuilderRunOptions = {
   cleanCache: false,
@@ -181,6 +182,7 @@ export class PackageVersionBuilder implements IPackageVersionBuilder {
       apiBuilders: this.apiBuilders,
       // todo only used in build strategy, move to the dedicated BuilderContext subtype
       basePath: basePath,
+      packageResolver: this.packageResolver.bind(this),
       versionDeprecatedResolver: this.versionDeprecatedResolver.bind(this),
       templateResolver: this.templateResolver.bind(this),
       parsedFileResolver: this.parsedFileResolver.bind(this),
@@ -427,6 +429,22 @@ export class PackageVersionBuilder implements IPackageVersionBuilder {
     return documents
   }
 
+  async packageResolver(
+    packageId: string,
+  ): Promise<ResolvedPackage> {
+    const { packageResolver } = this.params.resolvers
+    if (!packageResolver) {
+      throw new Error('No packageResolver provided')
+    }
+
+    const resolvedPackage = await packageResolver(packageId)
+    if (!resolvedPackage) {
+      throw new Error(`No such package: packageId: ${packageId}`)
+    }
+
+    return resolvedPackage
+  }
+
   async versionDocumentsResolver(
     version: VersionId,
     packageId: PackageId,

src/strategies/export-rest-document.strategy.ts

@@ -38,7 +38,7 @@ import {
 async function createTransformedDocument(
   file: File,
   format: OperationsGroupExportFormat,
-  packageId: string,
+  packageName: string,
   version: string,
   templateResolver: _TemplateResolver,
   allowedOasExtensions?: OpenApiExtensionKey[],
@@ -48,7 +48,7 @@ async function createTransformedDocument(
   if (format === HTML_EXPORT_GROUP_FORMAT) {
     return createExportDocument(
       `${getDocumentTitle(file.name)}.${HTML_EXPORT_GROUP_FORMAT}`,
-      await generateHtmlPage(JSON.stringify(data, undefined, 2), getDocumentTitle(file.name), packageId, version, templateResolver),
+      await generateHtmlPage(JSON.stringify(data, undefined, 2), getDocumentTitle(file.name), packageName, version, templateResolver),
     )
   }
 
@@ -66,19 +66,20 @@ async function createTransformedDocument(
 export class ExportRestDocumentStrategy implements BuilderStrategy {
   async execute(config: ExportRestDocumentBuildConfig, buildResult: BuildResult, contexts: BuildTypeContexts): Promise<BuildResult> {
     const { builderContext } = contexts
-    const { rawDocumentResolver, templateResolver } = builderContext(config)
+    const { rawDocumentResolver, templateResolver, packageResolver } = builderContext(config)
     const { packageId, version, documentId, format, allowedOasExtensions } = config
 
     const file = await rawDocumentResolver(
       version,
       packageId,
       documentId, //document.slug,
     )
+    const { name: packageName } = await packageResolver(packageId)
 
-    buildResult.exportDocuments.push(await createTransformedDocument(file, format, packageId, version, templateResolver, allowedOasExtensions))
+    buildResult.exportDocuments.push(await createTransformedDocument(file, format, packageName, version, templateResolver, allowedOasExtensions))
 
     if (format === HTML_EXPORT_GROUP_FORMAT) {
-      buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageId, version, templateResolver, buildResult.exportDocuments[0].fileId))
+      buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, buildResult.exportDocuments[0].fileId))
       buildResult.exportFileName = createSingleFileExportName(packageId, version, getDocumentTitle(file.name), 'zip')
       return buildResult
     }

src/strategies/export-rest-operations-group.strategy.ts

@@ -58,7 +58,8 @@ export class ExportRestOperationsGroupStrategy implements BuilderStrategy {
 
 async function exportMergedDocument(config: ExportRestOperationsGroupBuildConfig, buildResult: BuildResult, contexts: BuildTypeContexts): Promise<BuildResult> {
   const { packageId, version, groupName, format = JSON_EXPORT_GROUP_FORMAT, allowedOasExtensions } = config
-  const { templateResolver } = contexts.builderContext(config)
+  const { templateResolver, packageResolver } = contexts.builderContext(config)
+  const { name: packageName } = await packageResolver(packageId)
 
   await new MergedDocumentGroupStrategy().execute({
     ...config,
@@ -73,10 +74,10 @@ async function exportMergedDocument(config: ExportRestOperationsGroupBuildConfig
   if (format === HTML_EXPORT_GROUP_FORMAT) {
     const htmlExportDocument = createExportDocument(
       `${getDocumentTitle(buildResult.merged.filename)}.${HTML_EXPORT_GROUP_FORMAT}`,
-      await generateHtmlPage(JSON.stringify(removeOasExtensions(buildResult.merged?.data, allowedOasExtensions), undefined, 2), getDocumentTitle(buildResult.merged.filename), packageId, version, templateResolver, false),
+      await generateHtmlPage(JSON.stringify(removeOasExtensions(buildResult.merged?.data, allowedOasExtensions), undefined, 2), getDocumentTitle(buildResult.merged.filename), packageName, version, templateResolver, false),
     )
     buildResult.exportDocuments.push(htmlExportDocument)
-    buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageId, version, templateResolver, htmlExportDocument.filename))
+    buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, htmlExportDocument.filename))
     buildResult.exportFileName = `${packageId}_${version}_${groupName}.zip`
     return buildResult
   }
@@ -96,7 +97,8 @@ async function exportMergedDocument(config: ExportRestOperationsGroupBuildConfig
 
 async function exportReducedDocuments(config: ExportRestOperationsGroupBuildConfig, buildResult: BuildResult, contexts: BuildTypeContexts): Promise<BuildResult> {
   const { packageId, version, groupName, format = JSON_EXPORT_GROUP_FORMAT, allowedOasExtensions } = config
-  const { templateResolver } = contexts.builderContext(config)
+  const { templateResolver, packageResolver } = contexts.builderContext(config)
+  const { name: packageName } = await packageResolver(packageId)
 
   await new DocumentGroupStrategy().execute({
     ...config,
@@ -106,14 +108,14 @@ async function exportReducedDocuments(config: ExportRestOperationsGroupBuildConf
 
   const generatedHtmlExportDocuments: ZippableDocument[] = []
   const transformedDocuments = await Promise.all([...buildResult.documents.values()].map(async document => {
-    return await createTransformedDocument(document, format, packageId, version, generatedHtmlExportDocuments, templateResolver, allowedOasExtensions)
+    return await createTransformedDocument(document, format, packageName, version, generatedHtmlExportDocuments, templateResolver, allowedOasExtensions)
   }))
 
   buildResult.exportDocuments.push(...transformedDocuments)
 
   if (format === HTML_EXPORT_GROUP_FORMAT) {
-    buildResult.exportDocuments.push(createExportDocument('index.html', await generateIndexHtmlPage(packageId, version, generatedHtmlExportDocuments, templateResolver)))
-    buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageId, version, templateResolver))
+    buildResult.exportDocuments.push(createExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver)))
+    buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver))
   }
 
   if (buildResult.exportDocuments.length > 1) {
@@ -128,7 +130,7 @@ async function exportReducedDocuments(config: ExportRestOperationsGroupBuildConf
 async function createTransformedDocument(
   document: VersionDocument,
   format: OperationsGroupExportFormat,
-  packageId: string,
+  packageName: string,
   version: string,
   generatedHtmlExportDocuments: ZippableDocument[],
   templateResolver: _TemplateResolver,
@@ -139,7 +141,7 @@ async function createTransformedDocument(
   if (isRestDocument(document) && format === HTML_EXPORT_GROUP_FORMAT) {
     const htmlExportDocument = createExportDocument(
       `${getDocumentTitle(document.filename)}.${HTML_EXPORT_GROUP_FORMAT}`,
-      await generateHtmlPage(JSON.stringify(removeOasExtensions(document.data, allowedOasExtensions), undefined, 2), getDocumentTitle(document.filename), packageId, version, templateResolver, true),
+      await generateHtmlPage(JSON.stringify(removeOasExtensions(document.data, allowedOasExtensions), undefined, 2), getDocumentTitle(document.filename), packageName, version, templateResolver, true),
     )
     generatedHtmlExportDocuments.push(htmlExportDocument)
     return htmlExportDocument

src/strategies/export-version.strategy.ts

@@ -60,7 +60,7 @@ async function createTransformedDocument(
   document: ResolvedVersionDocument,
   file: File,
   format: OperationsGroupExportFormat,
-  packageId: string,
+  packageName: string,
   version: string,
   generatedHtmlExportDocuments: ZippableDocument[],
   templateResolver: _TemplateResolver,
@@ -73,7 +73,7 @@ async function createTransformedDocument(
   if (isRestDocument(document) && format === HTML_EXPORT_GROUP_FORMAT) {
     const htmlExportDocument = createExportDocument(
       `${getDocumentTitle(file.name)}.${HTML_EXPORT_GROUP_FORMAT}`,
-      await generateHtmlPage(JSON.stringify(removeOasExtensions(JSON.parse(data), allowedOasExtensions), undefined, 2), getDocumentTitle(file.name), packageId, version, templateResolver, true),
+      await generateHtmlPage(JSON.stringify(removeOasExtensions(JSON.parse(data), allowedOasExtensions), undefined, 2), getDocumentTitle(file.name), packageName, version, templateResolver, true),
     )
     generatedHtmlExportDocuments.push(htmlExportDocument)
     return htmlExportDocument
@@ -93,8 +93,9 @@ async function createTransformedDocument(
 export class ExportVersionStrategy implements BuilderStrategy {
   async execute(config: ExportVersionBuildConfig, buildResult: BuildResult, contexts: BuildTypeContexts): Promise<BuildResult> {
     const { builderContext } = contexts
-    const { versionDocumentsResolver, rawDocumentResolver, templateResolver } = builderContext(config)
+    const { versionDocumentsResolver, rawDocumentResolver, templateResolver, packageResolver } = builderContext(config)
     const { packageId, version, format = JSON_EXPORT_GROUP_FORMAT, allowedOasExtensions } = config
+    const { name: packageName } = await packageResolver(packageId)
 
     const { documents } = await versionDocumentsResolver(
       version,
@@ -104,18 +105,18 @@ export class ExportVersionStrategy implements BuilderStrategy {
     const generatedHtmlExportDocuments: ZippableDocument[] = []
     const transformedDocuments = await Promise.all(documents.map(async document => {
       const file = await rawDocumentResolver(version, packageId, document.slug)
-      return await createTransformedDocument(document, file, format, packageId, version, generatedHtmlExportDocuments, templateResolver, allowedOasExtensions)
+      return await createTransformedDocument(document, file, format, packageName, version, generatedHtmlExportDocuments, templateResolver, allowedOasExtensions)
     }))
 
     buildResult.exportDocuments.push(...transformedDocuments)
 
     const restDocuments = documents.filter(isRestDocument)
     if (format === HTML_EXPORT_GROUP_FORMAT && restDocuments.length > 0) {
-      buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageId, version, templateResolver))
+      buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver))
       const readme = buildResult.exportDocuments.find(({ fileId }) => fileId.toLowerCase() === 'readme.md')?.description
 
       if (restDocuments.length > 1 || readme) {
-        buildResult.exportDocuments.push(createExportDocument('index.html', await generateIndexHtmlPage(packageId, version, generatedHtmlExportDocuments, templateResolver, readme)))
+        buildResult.exportDocuments.push(createExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver, readme)))
       }
     }
 

src/types/external/package.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright 2024-2025 NetCracker Technology Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { PackageId } from './types'
+
+export type PackageResolver = (
+  packageId: PackageId,
+) => Promise<ResolvedPackage | null>
+
+export type ResolvedPackage = {
+  packageId: string
+  name: string
+
+  // other params (not used in builder logic)
+  [key: string]: unknown
+}

src/types/external/resolvers.ts

@@ -27,9 +27,11 @@ import { VersionOperationsResolver } from './operations'
 import { VersionReferencesResolver } from './references'
 import { VersionResolver } from './version'
 import { GroupExportTemplateResolver } from '../internal'
+import { PackageResolver } from './package'
 
 export interface BuilderResolvers {
   fileResolver: FileResolver
+  packageResolver?: PackageResolver
   versionResolver?: VersionResolver
   versionOperationsResolver?: VersionOperationsResolver
   versionReferencesResolver?: VersionReferencesResolver

src/types/internal/apiBuilder.ts

@@ -41,6 +41,7 @@ import { SourceFile, TextFile } from './internal'
 import { ApiOperation } from './operation'
 import { Diff } from '@netcracker/qubership-apihub-api-diff'
 import { DebugPerformanceContext } from '../../utils/logs'
+import { ResolvedPackage } from '../external/package'
 
 export type BuilderType =
   | typeof REST_API_TYPE
@@ -55,6 +56,7 @@ export interface BuilderContext<T = any> {
   basePath: string
   parsedFileResolver: _ParsedFileResolver
   templateResolver: _TemplateResolver
+  packageResolver: _PackageResolver
   notifications: NotificationMessage[]
   config: BuildConfig
   builderRunOptions: BuilderRunOptions
@@ -116,6 +118,7 @@ export interface ApiBuilder<T = any, O = any, M = any> {
 }
 
 // internal
+export type _PackageResolver = (packageId: PackageId) => Promise<ResolvedPackage>
 export type _VersionResolver = (packageId: PackageId, version: VersionId) => Promise<VersionCache | null>
 export type _VersionReferencesResolver = (packageId: PackageId, version: VersionId) => Promise<BuildConfigRef[]>
 

src/utils/export.ts

@@ -17,9 +17,9 @@ import { _TemplateResolver, ZippableDocument } from '../types'
 import { UNKNOWN_API_TYPE } from '../apitypes'
 import { getDocumentTitle } from './document'
 
-export async function createCommonStaticExportDocuments(packageId: string, version: string, templateResolver: _TemplateResolver, backLinkFilename: string = 'index.html'): Promise<ZippableDocument[]> {
+export async function createCommonStaticExportDocuments(packageName: string, version: string, templateResolver: _TemplateResolver, backLinkFilename: string = 'index.html'): Promise<ZippableDocument[]> {
   return [
-    createExportDocument('ls.html', await generateLegalStatementPage(packageId, version, await templateResolver('ls.html'), backLinkFilename)),
+    createExportDocument('ls.html', await generateLegalStatementPage(packageName, version, await templateResolver('ls.html'), backLinkFilename)),
     createExportDocument('resources/corporatelogo.svg', await templateResolver('resources/corporatelogo.svg')),
     createExportDocument('resources/styles.css', await templateResolver('resources/styles.css')),
   ]
@@ -37,31 +37,25 @@ export function createExportDocument(fileId: string, source: Blob): ZippableDocu
   }
 }
 
-export async function generateLegalStatementPage(packageId: string, version: string, legalStatement: Blob, backLinkFilename: string): Promise<Blob> {
+export async function generateLegalStatementPage(packageName: string, version: string, legalStatement: Blob, backLinkFilename: string): Promise<Blob> {
   const filled = (await legalStatement.text())
-    // todo use packageName instead of packageId
-    .replace('{{packageName}}', packageId)
-    .replace('{{version}}', version)
+    .replaceAll('{{packageName}}', packageName)
+    .replaceAll('{{version}}', version)
     .replace('{{backLinkFilename}}', backLinkFilename)
-    // todo use packageName instead of packageId
-    .replace('{{packageNameAndVersion}}', `${packageId} ${version}`)
   return new Blob([filled])
 }
 
-export async function generateHtmlPage(document: string, fileTitle: string, packageId: string, version: string, templateResolver: _TemplateResolver, addBackLink: boolean = false): Promise<Blob> {
+export async function generateHtmlPage(document: string, fileTitle: string, packageName: string, version: string, templateResolver: _TemplateResolver, addBackLink: boolean = false): Promise<Blob> {
   const template = await (await templateResolver('page.html')).text()
   const apispecViewScript = await (await templateResolver('scripts/apispec-view.js')).text()
   const breadcrumbs = addBackLink ? `<div class="breadcrumbs"><a href="index.html">Table of contents</a> > <span>${fileTitle}</span></div>` : ''
   const filled = template
     .replace('{{fileTitle}}', fileTitle)
     .replace('{{apispecViewScript}}', () => apispecViewScript)
-    // todo use packageName instead of packageId
-    .replace('{{packageName}}', packageId)
-    .replace('{{version}}', version)
+    .replaceAll('{{packageName}}', packageName)
+    .replaceAll('{{version}}', version)
     .replace('{{breadcrumbs}}', breadcrumbs)
     .replace('{{spec}}', escapeHTML(document))
-    // todo use packageName instead of packageId
-    .replace('{{packageNameAndVersion}}', `${packageId} ${version}`)
   return new Blob([filled])
 }
 
@@ -83,7 +77,7 @@ async function generateReadmeParts(templateResolver: _TemplateResolver, readme?:
   return [readmeHtml, `<script>${markdownIt}</script>`]
 }
 
-export async function generateIndexHtmlPage(packageId: string, version: string, generatedHtmlExportDocuments: ZippableDocument[], templateResolver: _TemplateResolver, readme?: string): Promise<Blob> {
+export async function generateIndexHtmlPage(packageName: string, version: string, generatedHtmlExportDocuments: ZippableDocument[], templateResolver: _TemplateResolver, readme?: string): Promise<Blob> {
   const template = await (await templateResolver('index.html')).text()
   const htmlList = generatedHtmlExportDocuments.reduce(
     (acc, { filename }) => acc.concat(`        <li><a href="${filename}">${getDocumentTitle(filename)}</a></li>\n`),
@@ -93,14 +87,11 @@ export async function generateIndexHtmlPage(packageId: string, version: string,
   const [readmeHtml, markdownItScript] = await generateReadmeParts(templateResolver, readme)
 
   const filled = template
-    // todo use packageName instead of packageId
-    .replaceAll('{{packageName}}', packageId)
+    .replaceAll('{{packageName}}', packageName)
+    .replaceAll('{{version}}', version)
     .replace('{{markdownItScript}}', markdownItScript)
-    .replace('{{version}}', version)
     .replace('{{readmeHtml}}', readmeHtml)
     .replace('{{htmlList}}', htmlList)
-    // todo use packageName instead of packageId
-    .replace('{{packageNameAndVersion}}', `${packageId} ${version}`)
   return new Blob([filled])
 }
 

templates/index.html

@@ -27,7 +27,7 @@ <h4>Version: {{version}}</h4>
         <a href="ls.html">Legal statement</a>
       </span>
       <span class="footer__legal">
-        {{packageNameAndVersion}}<br><br>
+        {{packageName}} {{version}}<br><br>
         qubership-apihub
       </span>
     </div>

templates/ls.html

@@ -41,7 +41,7 @@ <h4>Version: {{version}}</h4>
   </div>
   <div class="footer">
     <span class="footer__legal">
-        {{packageNameAndVersion}}<br><br>
+        {{packageName}} {{version}}<br><br>
         qubership-apihub
       </span>
   </div>