Centralize codegen path configuration

Add codegen/lib/config.ts as single source of truth for all paths:
- apiReferenceRoot: site section root from repo root ('docs/api-reference')
- guidesRoot: guides site section root ('docs/guides')
- apiUrlPrefix: published URL prefix ('/api')
- baseUrl, siteUrlPrefix: docs site URL constants

Change Metalsmith destination from '../docs' to '../' (repo root) so
file keys match the full path from repo root (docs/api-reference/...).
Rename source directory from codegen/docs/ to codegen/source/ to
avoid confusion with the output docs/ directory.

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'
+
+// Site section roots (paths from repo root)
+export const apiReferenceRoot = join('docs', 'api-reference')
+export const guidesRoot = join('docs', 'guides')
+
+// 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 apiSummaryPath = join(apiReferenceRoot, '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 {
+  apiReferenceRoot,
+  apiUrlPrefix,
+  baseUrl,
+  siteUrlPrefix,
+} from './config.js'
 
 export const postprocess = (
   files: Metalsmith.Files,
@@ -18,10 +20,10 @@ 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, '')

codegen/lib/reference.ts

@@ -15,6 +15,7 @@ import {
   type ApiSummaryLayoutContext,
   setSummaryLayoutContext,
 } from './layout/summary.js'
+import { apiReferenceRoot } 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 = apiReferenceRoot
 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 { apiReferenceRoot } 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[`${apiReferenceRoot}/_report.md`] = {
     contents: Buffer.from('\n'),
     layout: 'report.hbs',
     ...reportData,
   }
 
-  files['api-reference/_blueprint.json'] = {
+  files[`${apiReferenceRoot}/_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 { apiReferenceRoot, 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 = `${apiReferenceRoot}/_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 = `${apiReferenceRoot}/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 { apiReferenceRoot } from './lib/config.js'
 import {
   formatCode,
   helpers,
@@ -22,17 +23,17 @@ const rootDir = dirname(fileURLToPath(import.meta.url))
 
 await Promise.all([
   deleteAsync([
-    './docs/api-reference/**',
-    '!./docs/api-reference/SUMMARY.md',
-    '!./docs/api-reference/.gitbook.yaml',
+    `./${apiReferenceRoot}/**`,
+    `!./${apiReferenceRoot}/SUMMARY.md`,
+    `!./${apiReferenceRoot}/.gitbook.yaml`,
   ]),
 ])
 
 const partials = await getHandlebarsPartials(`${rootDir}/layouts/partials`)
 
 Metalsmith(rootDir)
-  .source('./docs')
-  .destination('../docs')
+  .source('./source')
+  .destination('../')
   .clean(false)
   .use(
     metadata({