fix(API): refactor API data compilation to be done at build time (#183)

* fix(API): refactor API data compilation to be done at build time

* fix cloudflare excluding api routes from worker bundle

* fix unit tests for api routes

* move tests outside of pages dir so that astro doesn't try to render them

* lint

* limit memory usage for build

Author: wise-king-sullyman

.gitignore

@@ -28,5 +28,9 @@ pnpm-debug.log*
 
 .eslintcache
 
-## Ignore content.ts
-src/content.ts
+## Ignore generated files
+src/content.ts
+src/apiIndex.json
+textContent/*.mdx
+
+coverage/

astro.config.mjs

@@ -19,6 +19,5 @@ export default defineConfig({
       }
     }
   },
-
   adapter: cloudflare()
 });

cli/__tests__/convertToMDX.test.ts

@@ -5,13 +5,16 @@ import { convertToMDX } from '../convertToMDX.ts'
 jest.mock('fs/promises', () => ({
   readFile: jest.fn(),
   writeFile: jest.fn(),
-  access: jest.fn().mockResolvedValue(undefined), // Mock access to always resolve (file exists)
 }))
 
 jest.mock('glob', () => ({
   glob: jest.fn(),
 }))
 
+jest.mock('../fileExists', () => ({
+  fileExists: jest.fn().mockResolvedValue(true), // Mock fileExists to always return true (file exists)
+}))
+
 beforeEach(() => {
   jest.clearAllMocks()
 })

cli/__tests__/createCollectionContent.test.ts

@@ -64,7 +64,7 @@ it('should call writeFile with the expected file location and content without th
   await createCollectionContent('/foo/', '/config/dir/pf-docs.config.mjs', false)
 
   const expectedContent = [
-    { name: 'test', base: '/config/dir/src/docs', pattern: '**/*.md' }
+    { name: 'test', base: '/config/dir/src/docs', pattern: '**/*.md', version: 'v6' }
   ]
 
   expect(writeFile).toHaveBeenCalledWith(
@@ -208,11 +208,12 @@ it('should handle content with packageName by finding package in node_modules',
   await createCollectionContent('/foo/', '/config/dir/pf-docs.config.mjs', false)
 
   const expectedContent = [
-    { 
+    {
       base: '/config/dir/node_modules/@patternfly/react-core',
-      name: 'test', 
-      packageName: '@patternfly/react-core', 
-      pattern: '**/*.md'
+      name: 'test',
+      packageName: '@patternfly/react-core',
+      pattern: '**/*.md',
+      version: 'v6'
     }
   ]
 
@@ -242,11 +243,12 @@ it('should handle content with packageName when package is not found locally but
   await createCollectionContent('/foo/', '/config/dir/pf-docs.config.mjs', false)
 
   const expectedContent = [
-    { 
+    {
       base: '/config/node_modules/@patternfly/react-core',
-      name: 'test', 
-      packageName: '@patternfly/react-core', 
-      pattern: '**/*.md'
+      name: 'test',
+      packageName: '@patternfly/react-core',
+      pattern: '**/*.md',
+      version: 'v6'
     }
   ]
 
@@ -274,11 +276,12 @@ it('should handle content with packageName when package is not found anywhere',
   await createCollectionContent('/foo/', '/config/dir/pf-docs.config.mjs', false)
 
   const expectedContent = [
-    { 
+    {
       base: null,
-      name: 'test', 
-      packageName: '@patternfly/react-core', 
-      pattern: '**/*.md'
+      name: 'test',
+      packageName: '@patternfly/react-core',
+      pattern: '**/*.md',
+      version: 'v6'
     }
   ]
 
@@ -307,12 +310,13 @@ it('should handle mixed content with both base and packageName entries', async (
   await createCollectionContent('/foo/', '/config/dir/pf-docs.config.mjs', false)
 
   const expectedContent = [
-    { name: 'docs', base: '/config/dir/src/docs', pattern: '**/*.md' },
-    { 
+    { name: 'docs', base: '/config/dir/src/docs', pattern: '**/*.md', version: 'v6' },
+    {
       base: '/config/dir/node_modules/@patternfly/react-core',
-      name: 'components', 
-      packageName: '@patternfly/react-core', 
-      pattern: '**/*.md'
+      name: 'components',
+      packageName: '@patternfly/react-core',
+      pattern: '**/*.md',
+      version: 'v6'
     }
   ]
 

cli/__tests__/fileExists.test.ts

@@ -0,0 +1,35 @@
+import { access } from 'fs/promises'
+import { fileExists } from '../fileExists'
+
+jest.mock('fs/promises', () => ({
+  access: jest.fn(),
+}))
+
+it('returns true when file exists', async () => {
+  ;(access as jest.Mock).mockResolvedValue(undefined)
+
+  const result = await fileExists('/path/to/existing/file.txt')
+
+  expect(result).toBe(true)
+  expect(access).toHaveBeenCalledWith('/path/to/existing/file.txt')
+})
+
+it('returns false when file does not exist', async () => {
+  ;(access as jest.Mock).mockRejectedValue(
+    new Error('ENOENT: no such file or directory'),
+  )
+
+  const result = await fileExists('/path/to/nonexistent/file.txt')
+
+  expect(result).toBe(false)
+  expect(access).toHaveBeenCalledWith('/path/to/nonexistent/file.txt')
+})
+
+it('returns false when access throws any error', async () => {
+  ;(access as jest.Mock).mockRejectedValue(new Error('Permission denied'))
+
+  const result = await fileExists('/path/to/file.txt')
+
+  expect(result).toBe(false)
+  expect(access).toHaveBeenCalledWith('/path/to/file.txt')
+})

cli/cli.ts

@@ -12,7 +12,8 @@ import { symLinkConfig } from './symLinkConfig.js'
 import { buildPropsData } from './buildPropsData.js'
 import { hasFile } from './hasFile.js'
 import { convertToMDX } from './convertToMDX.js'
-import { mkdir } from 'fs/promises'
+import { mkdir, copyFile } from 'fs/promises'
+import { fileExists } from './fileExists.js'
 
 const currentDir = process.cwd()
 const config = await getConfig(`${currentDir}/pf-docs.config.mjs`)
@@ -86,6 +87,26 @@ async function transformMDContentToMDX() {
   }
 }
 
+async function initializeApiIndex() {
+  const templateIndexPath = join(astroRoot, 'cli', 'templates', 'apiIndex.json')
+  const targetIndexPath = join(astroRoot, 'src', 'apiIndex.json')
+
+  const indexExists = await fileExists(targetIndexPath)
+
+  // early return if the file exists from a previous build
+  if (indexExists) {
+    console.log('apiIndex.json already exists, skipping initialization')
+    return
+  }
+
+  try {
+    await copyFile(templateIndexPath, targetIndexPath)
+    console.log('Initialized apiIndex.json')
+  } catch (e: any) {
+    console.error('Error copying apiIndex.json template:', e)
+  }
+}
+
 async function buildProject(): Promise<DocsConfig | undefined> {
   await updateContent(program)
   await generateProps(program, true)
@@ -103,6 +124,7 @@ async function buildProject(): Promise<DocsConfig | undefined> {
     return config
   }
 
+  await initializeApiIndex()
   await transformMDContentToMDX()
 
   build({
@@ -172,6 +194,7 @@ program.command('init').action(async () => {
 
 program.command('start').action(async () => {
   await updateContent(program)
+  await initializeApiIndex()
 
   // if a props file hasn't been generated yet, but the consumer has propsData, it will cause a runtime error so to
   // prevent that we're just creating a props file regardless of what they say if one doesn't exist yet

cli/convertToMDX.ts

@@ -1,6 +1,7 @@
-import { readFile, writeFile, access } from 'fs/promises'
+import { readFile, writeFile } from 'fs/promises'
 import { glob } from 'glob'
 import path from 'path'
+import { fileExists } from './fileExists.js'
 
 function handleTsExamples(content: string): string {
   //regex link: https://regexr.com/8f0bu
@@ -57,10 +58,6 @@ function convertCommentsToMDX(content: string): string {
   )
 }
 
-async function fileExists(file: string): Promise<boolean> {
-  return access(file).then(() => true).catch(() => false)
-}
-
 async function processFile(file: string): Promise<void> {
   const exists = await fileExists(file)
 

cli/createCollectionContent.ts

@@ -80,6 +80,8 @@ export async function createCollectionContent(
   verboseModeLog('repoRootDir: ', repoRootDir, '\n')
 
   const contentWithAbsolutePaths = content.map((contentEntry) => {
+    const version = contentEntry.version || 'v6'
+
     if (contentEntry.base) {
       const absoluteBase = resolve(configDir, contentEntry.base)
 
@@ -89,6 +91,7 @@ export async function createCollectionContent(
       return {
         ...contentEntry,
         base: absoluteBase,
+        version
       }
     }
 
@@ -103,6 +106,7 @@ export async function createCollectionContent(
       return {
         ...contentEntry,
         base: null,
+        version
       }
     }
 
@@ -116,6 +120,7 @@ export async function createCollectionContent(
     return {
       base: packagePath,
       ...contentEntry,
+      version
     }
   })
 

cli/fileExists.ts

@@ -0,0 +1,7 @@
+import { access } from 'fs/promises'
+
+export async function fileExists(file: string): Promise<boolean> {
+  return access(file)
+    .then(() => true)
+    .catch(() => false)
+}

cli/getConfig.ts

@@ -2,6 +2,7 @@
 export interface CollectionDefinition {
   base?: string
   packageName?: string
+  version?: string
   pattern: string
   name: string
 }