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

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/

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__/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
 }

cli/templates/apiIndex.json

@@ -0,0 +1,6 @@
+{
+  "versions": [],
+  "sections": {},
+  "pages": {},
+  "tabs": {}
+}

src/pages/api/[version].ts

@@ -0,0 +1,25 @@
+import type { APIRoute } from 'astro'
+import { createJsonResponse, createIndexKey } from '../../utils/apiHelpers'
+import { sections as sectionsData } from '../../apiIndex.json'
+
+export const prerender = false
+
+export const GET: APIRoute = async ({ params }) => {
+  const { version } = params
+
+  if (!version) {
+    return createJsonResponse(
+      { error: 'Version parameter is required' },
+      400,
+    )
+  }
+
+  const key = createIndexKey(version)
+  const sections = sectionsData[key as keyof typeof sectionsData]
+
+  if (!sections) {
+    return createJsonResponse({ error: `Version '${version}' not found` }, 404)
+  }
+
+  return createJsonResponse(sections)
+}