Merge pull request #185 from patternfly/fix-text-api-monorepo-issues

fix(API): address issues with text API in monorepos

Author: wise-king-sullyman

.gitignore

@@ -34,3 +34,7 @@ src/apiIndex.json
 textContent/*.mdx
 
 coverage/
+
+.wrangler/
+
+temp

README.mdx

@@ -33,6 +33,7 @@ Any static assets, like images, can be placed in the `public/` directory.
 
 To define the markdown schema this project uses a typescript based schema known as [Zod](https://zod.dev). Details of how this is integratred into Astro can be found in Astros documentation on [content creation using Zod](https://docs.astro.build/en/guides/content-collections/#defining-datatypes-with-zod).
 
+Note: When running in dev mode locally on a clean repository, API endpoints will not be available until you run `npm run build` to generate the API index.
 ### 🧞 Commands
 
 All commands are run from the root of the project, from a terminal:

cli/cli.ts

@@ -34,6 +34,7 @@ try {
     .replace('file://', '')
 } catch (e: any) {
   if (e.code === 'ERR_MODULE_NOT_FOUND') {
+    console.log('@patternfly/patternfly-doc-core not found, using current directory as astroRoot')
     astroRoot = process.cwd()
   } else {
     console.error('Error resolving astroRoot', e)
@@ -87,29 +88,33 @@ async function transformMDContentToMDX() {
   }
 }
 
-async function initializeApiIndex() {
+async function initializeApiIndex(program: Command) {
+  const { verbose } = program.opts()
   const templateIndexPath = join(astroRoot, 'cli', 'templates', 'apiIndex.json')
-  const targetIndexPath = join(astroRoot, 'src', 'apiIndex.json')
-
+  const targetIndexPath = join(absoluteOutputDir, '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')
+    if (verbose) {
+      console.log('apiIndex.json already exists, skipping initialization')
+    }
     return
   }
 
   try {
     await copyFile(templateIndexPath, targetIndexPath)
-    console.log('Initialized apiIndex.json')
+    if (verbose) {
+      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)
+async function buildProject(program: Command): Promise<DocsConfig | undefined> {
+  const { verbose } = program.opts()
+
   if (!config) {
     console.error(
       'No config found, please run the `setup` command or manually create a pf-docs.config.mjs file',
@@ -123,44 +128,57 @@ async function buildProject(): Promise<DocsConfig | undefined> {
     )
     return config
   }
-
-  await initializeApiIndex()
+  await updateContent(program)
+  await generateProps(program, true)
+  await initializeApiIndex(program)
   await transformMDContentToMDX()
 
-  build({
+  const docsOutputDir = join(absoluteOutputDir, 'docs')
+
+  await build({
     root: astroRoot,
-    outDir: join(absoluteOutputDir, 'docs'),
+    outDir: docsOutputDir,
   })
 
+  // copy the apiIndex.json file to the docs directory so it can be served as a static asset
+  try {
+    const apiIndexPath = join(absoluteOutputDir, 'apiIndex.json')
+    const docsApiIndexPath = join(absoluteOutputDir, 'docs', 'apiIndex.json')
+    await copyFile(apiIndexPath, docsApiIndexPath)
+
+    if (verbose) {
+      console.log('Copied apiIndex.json to docs directory')
+    }
+  } catch (error) {
+    console.error('Failed to copy apiIndex.json to docs directory:', error)
+    throw error
+  }
+
   return config
 }
 
-async function deploy() {
-  const { verbose } = program.opts()
+async function deploy(program: Command) {
+  const { verbose, dryRun } = program.opts()
 
   if (verbose) {
     console.log('Starting Cloudflare deployment...')
   }
 
+  if (dryRun) {
+    console.log('Dry run mode enabled, skipping deployment')
+    return
+  }
+
   try {
-    // First build the project
-    const config = await buildProject()
-    if (config) {
-      if (verbose) {
-        console.log('Build complete, deploying to Cloudflare...')
-      }
-
-      // Deploy using Wrangler
-      const { execSync } = await import('child_process')
-      const outputPath = join(absoluteOutputDir, 'docs')
-
-      execSync(`npx wrangler pages deploy ${outputPath}`, {
-        stdio: 'inherit',
-        cwd: currentDir,
-      })
-
-      console.log('Successfully deployed to Cloudflare Pages!')
-    }
+    // Deploy using Wrangler
+    const { execSync } = await import('child_process')
+
+    execSync(`wrangler pages deploy`, {
+      stdio: 'inherit',
+      cwd: currentDir,
+    })
+
+    console.log('Successfully deployed to Cloudflare Pages!')
   } catch (error) {
     console.error('Deployment failed:', error)
     process.exit(1)
@@ -172,6 +190,7 @@ program.name('pf-doc-core')
 
 program.option('--verbose', 'verbose mode', false)
 program.option('--props', 'generate props data', false)
+program.option('--dry-run', 'dry run mode', false)
 
 program.command('setup').action(async () => {
   await Promise.all([
@@ -194,7 +213,7 @@ program.command('init').action(async () => {
 
 program.command('start').action(async () => {
   await updateContent(program)
-  await initializeApiIndex()
+  await initializeApiIndex(program)
 
   // 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
@@ -204,7 +223,7 @@ program.command('start').action(async () => {
 })
 
 program.command('build').action(async () => {
-  await buildProject()
+  await buildProject(program)
 })
 
 program.command('generate-props').action(async () => {
@@ -229,7 +248,7 @@ program
   })
 
 program.command('deploy').action(async () => {
-  await deploy()
+  await deploy(program)
 })
 
 program.parse(process.argv)

jest.config.ts

@@ -17,8 +17,8 @@ const config: Config = {
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
   moduleNameMapper: {
     '\\.(css|less)$': '<rootDir>/src/__mocks__/styleMock.ts',
-    '(.+)\\.js': '$1',
     '^astro:content$': '<rootDir>/src/__mocks__/astro-content.ts',
+    '(.+)\\.js': '$1',
   },
   setupFilesAfterEnv: ['<rootDir>/test.setup.ts'],
   transformIgnorePatterns: [

package-lock.json

@@ -18,14 +18,15 @@
     "build:props": "npm run build:cli && node ./dist/cli/cli.js generate-props",
     "preview": "wrangler pages dev",
     "astro": "astro",
-    "deploy": "wrangler pages deploy",
+    "deploy": "npm run build:cli && node ./dist/cli/cli.js deploy",
     "versions:upload": "wrangler versions upload",
     "prettier": "prettier --write ./src",
     "lint": "eslint . --cache --cache-strategy content",
     "test": "jest",
     "test:watch": "jest --watch",
     "semantic-release": "semantic-release",
-    "cf-typegen": "wrangler types"
+    "cf-typegen": "wrangler types",
+    "clean": "rm -rf dist .astro .wrangler"
   },
   "main": "dist/cli/cli.js",
   "bin": "./dist/cli/cli.js",
@@ -64,7 +65,7 @@
     "@patternfly/quickstarts": "^6.0.0",
     "@types/react": "^18.3.23",
     "@types/react-dom": "^18.3.7",
-    "astro": "5.15.9",
+    "astro": "^5.15.9",
     "change-case": "5.4.4",
     "commander": "^13.1.0",
     "glob": "^11.0.3",

package.json

@@ -1,22 +1,26 @@
 import { GET } from '../../../../pages/api/[version]'
 
-/**
- * Mock apiIndex.json with multiple versions (v5, v6)
- * to test section retrieval for different versions
- */
-jest.mock('../../../../apiIndex.json', () => ({
+const mockApiIndex = {
   versions: ['v5', 'v6'],
   sections: {
     v5: ['getting-started'],
     v6: ['components', 'layouts', 'utilities'],
   },
   pages: {},
   tabs: {},
-}))
+}
 
 it('returns all sections for a valid version', async () => {
+  global.fetch = jest.fn(() =>
+    Promise.resolve({
+      ok: true,
+      json: () => Promise.resolve(mockApiIndex),
+    } as Response)
+  )
+
   const response = await GET({
     params: { version: 'v6' },
+    url: new URL('http://localhost:4321/api/v6'),
   } as any)
   const body = await response.json()
 
@@ -26,67 +30,131 @@ it('returns all sections for a valid version', async () => {
   expect(body).toContain('components')
   expect(body).toContain('layouts')
   expect(body).toContain('utilities')
+
+  jest.restoreAllMocks()
 })
 
 it('returns only sections for the requested version', async () => {
+  global.fetch = jest.fn(() =>
+    Promise.resolve({
+      ok: true,
+      json: () => Promise.resolve(mockApiIndex),
+    } as Response)
+  )
+
   const response = await GET({
     params: { version: 'v5' },
+    url: new URL('http://localhost:4321/api/v5'),
   } as any)
   const body = await response.json()
 
   expect(response.status).toBe(200)
   expect(body).toContain('getting-started')
+
+  jest.restoreAllMocks()
 })
 
 it('sorts sections alphabetically', async () => {
+  global.fetch = jest.fn(() =>
+    Promise.resolve({
+      ok: true,
+      json: () => Promise.resolve(mockApiIndex),
+    } as Response)
+  )
+
   const response = await GET({
     params: { version: 'v6' },
+    url: new URL('http://localhost:4321/api/v6'),
   } as any)
   const body = await response.json()
 
   const sorted = [...body].sort()
   expect(body).toEqual(sorted)
+
+  jest.restoreAllMocks()
 })
 
 it('deduplicates sections from multiple collections', async () => {
+  global.fetch = jest.fn(() =>
+    Promise.resolve({
+      ok: true,
+      json: () => Promise.resolve(mockApiIndex),
+    } as Response)
+  )
+
   const response = await GET({
     params: { version: 'v6' },
+    url: new URL('http://localhost:4321/api/v6'),
   } as any)
   const body = await response.json()
 
   const unique = [...new Set(body)]
   expect(body).toEqual(unique)
+
+  jest.restoreAllMocks()
 })
 
 it('returns 404 error for nonexistent version', async () => {
+  global.fetch = jest.fn(() =>
+    Promise.resolve({
+      ok: true,
+      json: () => Promise.resolve(mockApiIndex),
+    } as Response)
+  )
+
   const response = await GET({
     params: { version: 'v99' },
+    url: new URL('http://localhost:4321/api/v99'),
   } as any)
   const body = await response.json()
 
   expect(response.status).toBe(404)
   expect(body).toHaveProperty('error')
   expect(body.error).toContain('v99')
   expect(body.error).toContain('not found')
+
+  jest.restoreAllMocks()
 })
 
 it('returns 400 error when version parameter is missing', async () => {
+  global.fetch = jest.fn(() =>
+    Promise.resolve({
+      ok: true,
+      json: () => Promise.resolve(mockApiIndex),
+    } as Response)
+  )
+
   const response = await GET({
     params: {},
+    url: new URL('http://localhost:4321/api/'),
   } as any)
   const body = await response.json()
 
   expect(response.status).toBe(400)
   expect(body).toHaveProperty('error')
   expect(body.error).toContain('Version parameter is required')
+
+  jest.restoreAllMocks()
 })
 
-it('excludes content entries that have no section field', async () => {
+it('returns sections array that matches the API index', async () => {
+  global.fetch = jest.fn(() =>
+    Promise.resolve({
+      ok: true,
+      json: () => Promise.resolve(mockApiIndex),
+    } as Response)
+  )
+
   const response = await GET({
     params: { version: 'v6' },
+    url: new URL('http://localhost:4321/api/v6'),
   } as any)
   const body = await response.json()
 
-  // Should only include sections from entries that have data.section
-  expect(body.length).toBeGreaterThan(0)
+  // Verify the returned sections exactly match the indexed sections
+  // The API index generation process filters out entries without section fields
+  expect(body).toEqual(mockApiIndex.sections.v6)
+  expect(body).toEqual(['components', 'layouts', 'utilities'])
+
+  jest.restoreAllMocks()
 })