fix: index.html file is missing during export if package contains just single document (#32)

Author: iurii-golovinskii

src/apitypes/rest/rest.document.ts

@@ -125,7 +125,6 @@ export async function createRestExportDocument(
   templateResolver: _TemplateResolver,
   allowedOasExtensions?: OpenApiExtensionKey[],
   generatedHtmlExportDocuments?: ExportDocument[],
-  addBackLink?: boolean,
 ): Promise<ExportDocument> {
   const exportFilename = `${getDocumentTitle(filename)}.${format}`
   const [[document], blobProperties] = dump(removeOasExtensions(JSON.parse(data), allowedOasExtensions), EXPORT_FORMAT_TO_FILE_FORMAT.get(format)!)
@@ -138,7 +137,6 @@ export async function createRestExportDocument(
         packageName,
         version,
         templateResolver,
-        addBackLink,
       ),
       filename: exportFilename,
     }

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

@@ -14,9 +14,20 @@
  * limitations under the License.
  */
 
-import { BuilderStrategy, BuildResult, BuildTypeContexts, ExportRestDocumentBuildConfig } from '../types'
+import {
+  BuilderStrategy,
+  BuildResult,
+  BuildTypeContexts,
+  ExportDocument,
+  ExportRestDocumentBuildConfig,
+} from '../types'
 import { getDocumentTitle, getSplittedVersionKey } from '../utils'
-import { createCommonStaticExportDocuments, createSingleFileExportName } from '../utils/export'
+import {
+  createCommonStaticExportDocuments,
+  createSingleFileExportName,
+  createUnknownExportDocument,
+  generateIndexHtmlPage,
+} from '../utils/export'
 import { createRestExportDocument } from '../apitypes/rest/rest.document'
 import { FILE_FORMAT_HTML } from '../consts'
 
@@ -26,17 +37,17 @@ export class ExportRestDocumentStrategy implements BuilderStrategy {
     const { rawDocumentResolver, templateResolver, packageResolver } = builderContext(config)
     const { packageId, version: versionWithRevision, documentId, format, allowedOasExtensions } = config
     const [version] = getSplittedVersionKey(versionWithRevision)
-
+    const generatedHtmlExportDocuments: ExportDocument[] = []
     const file = await rawDocumentResolver(
       versionWithRevision,
       packageId,
       documentId,
     )
     const { name: packageName } = await packageResolver(packageId)
-    buildResult.exportDocuments.push(await createRestExportDocument(file.name, await file.text(), format, packageName, version, templateResolver, allowedOasExtensions))
-
+    buildResult.exportDocuments.push(await createRestExportDocument(file.name, await file.text(), format, packageName, version, templateResolver, allowedOasExtensions, generatedHtmlExportDocuments))
     if (format === FILE_FORMAT_HTML) {
-      buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, buildResult.exportDocuments[0].filename))
+      buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver))
+      buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver)))
       buildResult.exportFileName = createSingleFileExportName(packageId, version, getDocumentTitle(file.name), 'zip')
       return buildResult
     }

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

@@ -78,7 +78,7 @@ async function exportMergedDocument(config: ExportRestOperationsGroupBuildConfig
   buildResult.exportDocuments.push(await createRestExportDocument(buildResult.merged.filename, JSON.stringify(buildResult.merged?.data), format, packageName, version, templateResolver, allowedOasExtensions))
 
   if (format === FILE_FORMAT_HTML) {
-    buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, buildResult.exportDocuments[0].filename))
+    buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver))
   }
 }
 
@@ -100,19 +100,15 @@ async function exportReducedDocuments(config: ExportRestOperationsGroupBuildConf
   }, buildResult, contexts)
 
   const generatedHtmlExportDocuments: ExportDocument[] = []
-  const restDocuments = [...buildResult.documents.values()].filter(isRestDocument)
   const transformedDocuments = await Promise.all([...buildResult.documents.values()].map(async document => {
-    return createRestExportDocument?.(document.filename, JSON.stringify(document.data), format, packageName, version, templateResolver, allowedOasExtensions, generatedHtmlExportDocuments, restDocuments.length > 1)
+    return createRestExportDocument?.(document.filename, JSON.stringify(document.data), format, packageName, version, templateResolver, allowedOasExtensions, generatedHtmlExportDocuments)
   }))
 
   buildResult.exportDocuments.push(...transformedDocuments)
 
   if (format === FILE_FORMAT_HTML) {
-    const shouldAddIndexPage = generatedHtmlExportDocuments.length > 1
-    buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, shouldAddIndexPage ? 'index.html' : buildResult.exportDocuments[0].filename))
+    buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver))
 
-    if (shouldAddIndexPage) {
-      buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver)))
-    }
+    buildResult.exportDocuments.push(createUnknownExportDocument('index.html', await generateIndexHtmlPage(packageName, version, generatedHtmlExportDocuments, templateResolver)))
   }
 }

src/strategies/export-version.strategy.ts

@@ -63,8 +63,7 @@ async function exportToHTML(config: ExportVersionBuildConfig, buildResult: Build
 
   const generatedHtmlExportDocuments: ExportDocument[] = []
   const restDocuments = documents.filter(isRestDocument)
-  const hasReadme = !!documents.find(({ filename }) => filename.toLowerCase() === 'readme.md')
-  const shouldAddIndexPage = hasReadme && restDocuments.length > 0 || restDocuments.length > 1
+  const shouldAddIndexPage = restDocuments.length > 0
   const transformedDocuments = await Promise.all(documents.map(async document => {
     const { createExportDocument } = apiBuilders.find(({ types }) => types.includes(document.type)) || unknownApiBuilder
     const file = await rawDocumentResolver(versionWithRevision, packageId, document.slug)
@@ -74,7 +73,7 @@ async function exportToHTML(config: ExportVersionBuildConfig, buildResult: Build
   buildResult.exportDocuments.push(...transformedDocuments)
 
   if (generatedHtmlExportDocuments.length > 0) {
-    buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver, shouldAddIndexPage ? 'index.html' : buildResult.exportDocuments[0].filename))
+    buildResult.exportDocuments.push(...await createCommonStaticExportDocuments(packageName, version, templateResolver))
   }
   if (shouldAddIndexPage) {
     const readme = await buildResult.exportDocuments.find(({ filename }) => filename.toLowerCase() === 'readme.md')?.data.text()

src/utils/export.ts

@@ -16,9 +16,9 @@
 import { _TemplateResolver, ExportDocument } from '../types'
 import { getDocumentTitle } from './document'
 
-export async function createCommonStaticExportDocuments(packageName: string, version: string, templateResolver: _TemplateResolver, backLinkFilename: string): Promise<ExportDocument[]> {
+export async function createCommonStaticExportDocuments(packageName: string, version: string, templateResolver: _TemplateResolver): Promise<ExportDocument[]> {
   return [
-    createUnknownExportDocument('ls.html', await generateLegalStatementPage(packageName, version, await templateResolver('ls.html'), backLinkFilename)),
+    createUnknownExportDocument('ls.html', await generateLegalStatementPage(packageName, version, await templateResolver('ls.html'), 'index.html')),
     createUnknownExportDocument('resources/corporatelogo.png', await templateResolver('resources/corporatelogo.png')),
     createUnknownExportDocument('resources/styles.css', await templateResolver('resources/styles.css')),
   ]
@@ -39,10 +39,10 @@ export async function generateLegalStatementPage(packageName: string, version: s
   return new Blob([filled])
 }
 
-export async function generateHtmlPage(document: string, fileTitle: string, packageName: string, version: string, templateResolver: _TemplateResolver, addBackLink: boolean = false): Promise<Blob> {
+export async function generateHtmlPage(document: string, fileTitle: string, packageName: string, version: string, templateResolver: _TemplateResolver): 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 breadcrumbs = `<div class="breadcrumbs"><a href="index.html">Table of contents</a> > <span>${fileTitle}</span></div>`
   const filled = template
     .replace('{{fileTitle}}', fileTitle)
     // arrow function disables replacement patterns like $&

test/export.test.ts

@@ -117,6 +117,7 @@ describe('Export test', () => {
     expect(result).toEqual(exportDocumentsMatcher([
       exportDocumentMatcher('1.html'),
       exportDocumentMatcher('ls.html'),
+      exportDocumentMatcher('index.html'),
       exportDocumentMatcher('resources/corporatelogo.png'),
       exportDocumentMatcher('resources/styles.css'),
     ]))
@@ -211,7 +212,7 @@ describe('Export test', () => {
     expect(result.exportFileName).toEqual('export_single-document-version.zip')
     expect(result).toEqual(exportDocumentsMatcher([
       exportDocumentMatcher('1.html'),
-
+      exportDocumentMatcher('index.html'),
       exportDocumentMatcher('ls.html'),
       exportDocumentMatcher('resources/corporatelogo.png'),
       exportDocumentMatcher('resources/styles.css'),
@@ -253,7 +254,7 @@ describe('Export test', () => {
       exportDocumentMatcher('1.html'),
       exportDocumentMatcher('README.md'),
 
-      exportDocumentMatcher('index.html'), // contains index.html due to the presence of README
+      exportDocumentMatcher('index.html'),
       exportDocumentMatcher('ls.html'),
       exportDocumentMatcher('resources/corporatelogo.png'),
       exportDocumentMatcher('resources/styles.css'),
@@ -300,7 +301,7 @@ describe('Export test', () => {
     expect(result.exportFileName).toEqual('export_regular-version_GROUP_WITH_OPERATIONS_FROM_ONE_DOCUMENT_ONLY.zip')
     expect(result).toEqual(exportDocumentsMatcher([
       exportDocumentMatcher('2.html'),
-
+      exportDocumentMatcher('index.html'),
       exportDocumentMatcher('ls.html'),
       exportDocumentMatcher('resources/corporatelogo.png'),
       exportDocumentMatcher('resources/styles.css'),