Centralize codegen path configuration

Add codegen/lib/config.ts with all path-related constants:
- apiRootPath: Metalsmith file key prefix ('api-reference')
- apiUrlPrefix: published URL prefix ('/api')
- baseUrl: docs site base URL
- siteUrlPrefix: URL prefix to strip ('/latest')
- apiReferenceDir, apiSummaryPath: derived disk paths

All codegen files now import from config instead of defining
their own constants. Changing the output directory or URL prefix
only requires editing config.ts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: louis-pre

codegen/lib/config.ts

@@ -0,0 +1,17 @@
+import { join } from 'node:path'
+
+// The Metalsmith file key prefix and disk directory name for generated API docs.
+export const apiRootPath = 'api-reference'
+
+// The published URL prefix for the API Reference site section on docs.seam.co.
+export const apiUrlPrefix = '/api'
+
+// The base URL for the published documentation site.
+export const baseUrl = 'https://docs.seam.co/latest/'
+
+// The URL prefix to strip when resolving absolute URLs to file paths.
+export const siteUrlPrefix = '/latest'
+
+// Derived paths
+export const apiReferenceDir = join('docs', apiRootPath)
+export const apiSummaryPath = join(apiReferenceDir, 'SUMMARY.md')

codegen/lib/postprocess.ts

@@ -3,10 +3,12 @@ import { dirname, join, relative, sep } from 'node:path'
 
 import type Metalsmith from 'metalsmith'
 
-const baseUrl = 'https://docs.seam.co/latest/'
-const urlPrefix = '/latest'
-const apiUrlPrefix = '/api'
-const apiReferenceRoot = join('docs', 'api-reference')
+import {
+  apiReferenceDir,
+  apiUrlPrefix,
+  baseUrl,
+  siteUrlPrefix,
+} from './config.js'
 
 export const postprocess = (
   files: Metalsmith.Files,
@@ -18,14 +20,14 @@ export const postprocess = (
       contents.replaceAll(new RegExp(`(${baseUrl}[^)]+)`, 'g'), ($1, $2) => {
         if (typeof $2 !== 'string') return $1
         const url = new URL($2)
-        url.pathname = url.pathname.replace(urlPrefix, '')
+        url.pathname = url.pathname.replace(siteUrlPrefix, '')
 
         // Only relativize links to pages within the api-reference space.
-        // The site section uses /api as its URL prefix.
+        // The site section uses apiUrlPrefix as its URL prefix.
         // Cross-section links (to guides) stay as absolute URLs.
         if (!url.pathname.startsWith(apiUrlPrefix + '/')) return $1
         const apiPath = url.pathname.replace(apiUrlPrefix, '')
-        const targetRoot = join(apiReferenceRoot, apiPath)
+        const targetRoot = join(apiReferenceDir, apiPath)
 
         const target = `${targetRoot}.md`
         if (existsSync(target)) {
@@ -44,7 +46,7 @@ export const postprocess = (
 }
 
 const getRelativeLink = (name: string, target: string, url: URL): string => {
-  const src = join(apiReferenceRoot, name)
+  const src = join(apiReferenceDir, name)
   const relativePath = relative(dirname(src), target)
   const urlPath = relativePath.split(sep).join('/')
   return `${urlPath}${url.hash}`

codegen/lib/reference.ts

@@ -15,6 +15,7 @@ import {
   type ApiSummaryLayoutContext,
   setSummaryLayoutContext,
 } from './layout/summary.js'
+import { apiRootPath } from './config.js'
 import { PathMetadataSchema } from './path-metadata.js'
 
 interface Metadata {
@@ -27,7 +28,7 @@ type File = ApiEndpointLayoutContext &
   ApiNamespaceLayoutContext &
   ApiSummaryLayoutContext & { layout: string }
 
-const rootPath = 'api-reference'
+const rootPath = apiRootPath
 const indexFile = 'README.md'
 
 export const reference = (

codegen/lib/report.ts

@@ -12,6 +12,8 @@ import type {
 import { openapi } from '@seamapi/types/connect'
 import type Metalsmith from 'metalsmith'
 
+import { apiRootPath } from './config.js'
+
 const defaultDeprecatedMessage = 'No deprecated message provided'
 const defaultDraftMessage = 'No draft message provided'
 const defaultUndocumentedMessage = 'No undocumented message provided'
@@ -75,13 +77,13 @@ export const report = (
 
   const reportData = generateReport(metadata)
 
-  files['api-reference/_report.md'] = {
+  files[`${apiRootPath}/_report.md`] = {
     contents: Buffer.from('\n'),
     layout: 'report.hbs',
     ...reportData,
   }
 
-  files['api-reference/_blueprint.json'] = {
+  files[`${apiRootPath}/_blueprint.json`] = {
     contents: Buffer.from(JSON.stringify(metadata.blueprint, null, 2)),
     layout: 'default.hbs',
   }

codegen/lib/summary.ts

@@ -1,29 +1,28 @@
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
 
 import type Metalsmith from 'metalsmith'
 
-const summaryPath = join('docs', 'api-reference', 'SUMMARY.md')
+import { apiRootPath, apiSummaryPath } from './config.js'
 
 export const summary = async (
   files: Metalsmith.Files,
   _metalsmith: Metalsmith,
 ): Promise<void> => {
-  const apiSummary =
-    files['api-reference/_summary.md']?.contents?.toString('utf-8')
+  const summaryKey = `${apiRootPath}/_summary.md`
+  const apiSummary = files[summaryKey]?.contents?.toString('utf-8')
   if (apiSummary == null) {
-    throw new Error('Missing api-reference/_summary.md')
+    throw new Error(`Missing ${summaryKey}`)
   }
 
-  const k = 'api-reference/SUMMARY.md'
+  const k = `${apiRootPath}/SUMMARY.md`
   const summary = await readSummary()
   const contents = getUpdatedSummary(summary, apiSummary)
   files[k] = { contents: Buffer.from(`${contents}\n`) }
-  delete files['api-reference/_summary.md']
+  delete files[summaryKey]
 }
 
 const readSummary = async (): Promise<string> => {
-  const buf = await readFile(summaryPath)
+  const buf = await readFile(apiSummaryPath)
   return buf.toString('utf-8')
 }
 

codegen/smith.ts

@@ -9,6 +9,7 @@ import * as types from '@seamapi/types/connect'
 import { deleteAsync } from 'del'
 import Metalsmith from 'metalsmith'
 
+import { apiReferenceDir } from './lib/config.js'
 import {
   formatCode,
   helpers,
@@ -22,9 +23,9 @@ const rootDir = dirname(fileURLToPath(import.meta.url))
 
 await Promise.all([
   deleteAsync([
-    './docs/api-reference/**',
-    '!./docs/api-reference/SUMMARY.md',
-    '!./docs/api-reference/.gitbook.yaml',
+    `./${apiReferenceDir}/**`,
+    `!./${apiReferenceDir}/SUMMARY.md`,
+    `!./${apiReferenceDir}/.gitbook.yaml`,
   ]),
 ])