test new generate-docs??

Author: abrulic

scripts/generate-docs.ts

@@ -1,10 +1,11 @@
 import { type ExecSyncOptions, execSync } from "node:child_process"
 import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
 import os from "node:os"
-import { join, relative, resolve } from "node:path"
+import path, { join, resolve, posix as pathPosix } from "node:path"
 import { parseArgs } from "node:util"
 import chalk from "chalk"
 import semver from "semver"
+import { getServerEnv } from "~/env.server"
 
 type RunOpts = { cwd?: string; inherit?: boolean }
 function run(cmd: string, opts: RunOpts = {}) {
@@ -31,32 +32,19 @@ const resetDir = (p: string) => {
 }
 
 const contentDir = "content"
-const workspaceRoot = process.cwd()
-const outputDir = resolve(workspaceRoot, "generated-docs")
-
-// If this script is executed from a subdirectory of the repository (for example
-// the `docs/` package inside a monorepo), we need the path of that subdir
-// relative to the repository root so worktrees point at the right package.
-let repoRoot = workspaceRoot
-let workspaceRelativePath = ""
+const outputDir = "generated-docs"
+const APP_ENV = getServerEnv().APP_ENV as "development" | "production"
+const currentDocsWorkspace = process.cwd()
+
+let docsRelative = ""
 try {
-	// This will return the repository top-level directory.
-	repoRoot = run("git rev-parse --show-toplevel")
-	// Compute the path from repo root to the current working dir. If empty,
-	// we are at repo root and no adjustment is needed.
-	// Use posix-style join/resolve via path utilities already imported.
-	workspaceRelativePath = repoRoot === workspaceRoot ? "" : relative(repoRoot, workspaceRoot)
+	docsRelative = run("git rev-parse --show-prefix", { cwd: currentDocsWorkspace }).replace(/\/?$/, "")
 } catch {
-	// If git is not available or the command fails, fall back to assuming the
-	// current working directory is the repository root.
-	repoRoot = workspaceRoot
-	workspaceRelativePath = ""
+	docsRelative = ""
 }
 
-// biome-ignore lint/suspicious/noConsole: TODO remove this
-console.log(chalk.cyan(`Docs workspace root: ${workspaceRoot}`))
-// biome-ignore lint/suspicious/noConsole: TODO remove this
-console.log("outputDir:", outputDir)
+const repoPath = (...segs: string[]) => path.normalize(path.join(...segs.filter(Boolean)))
+
 const allTags = () => run("git tag --list").split("\n").filter(Boolean)
 
 function resolveTagsFromSpec(spec: string) {
@@ -71,6 +59,16 @@ function resolveTagsFromSpec(spec: string) {
 	return matched.sort(semver.rcompare)
 }
 
+function detectDefaultBranch() {
+	try {
+		const ref = run("git symbolic-ref refs/remotes/origin/HEAD")
+		const parts = ref.split("/")
+		return parts[parts.length - 1]
+	} catch {
+		throw new Error("Cannot detect default branch from origin/HEAD")
+	}
+}
+
 function hasLocalRef(ref: string) {
 	try {
 		run(`git show-ref --verify --quiet ${ref}`)
@@ -80,51 +78,37 @@ function hasLocalRef(ref: string) {
 	}
 }
 
-function buildDocs(sourceDir: string, outDir: string) {
-	if (!existsSync(sourceDir)) {
-		throw new Error(
-			`❌ Documentation workspace not found at: ${sourceDir}
-   Cannot build documentation without a valid workspace directory.`
-		)
+const REPO_ROOT = run("git rev-parse --show-toplevel", { cwd: currentDocsWorkspace })
+
+function refHasPath(ref: string, pathFromRepoRoot: string): boolean {
+	const p = pathFromRepoRoot.replace(/^\/+/, "").replace(/\/+$/, "")
+	try {
+		run(`git -C "${REPO_ROOT}" rev-parse --verify --quiet "${ref}:${p}"`)
+		return true
+	} catch {
+		return false
 	}
+}
+
+function buildDocs(sourceDir: string, outDir: string) {
+	if (!existsSync(sourceDir)) throw new Error(`Docs workspace not found: ${sourceDir}`)
 
-	// biome-ignore lint/suspicious/noConsole: TODO remove this
-	console.log(chalk.cyan(`Building docs from: ${sourceDir} → ${outDir}`))
 	const docsContentDir = resolve(sourceDir, contentDir)
 	if (!existsSync(docsContentDir)) {
-		throw new Error(
-			`❌ Content directory "${contentDir}" not found at: ${docsContentDir}
-   Cannot build documentation without content files.
-   Please ensure you have a "${contentDir}/" directory with your documentation content.`
-		)
-	}
-
-	const packageJsonPath = resolve(sourceDir, "package.json")
-	if (!existsSync(packageJsonPath)) {
-		throw new Error(
-			`❌ package.json not found at: ${packageJsonPath}
-   Cannot build documentation without package.json.
-   Please ensure your workspace has a valid package.json file.`
-		)
+		throw new Error(`Docs content directory "${contentDir}" not found at ${docsContentDir}`)
 	}
 
 	resetDir(outDir)
 	run("pnpm run content-collections:build", { cwd: sourceDir, inherit: true })
 
 	const ccSrc = resolve(sourceDir, ".content-collections")
 	const ccDest = join(outDir, ".content-collections")
-	if (!existsSync(ccSrc)) {
-		throw new Error(
-			`❌ Build output missing at: ${ccSrc}
-   Content collections build failed or did not produce output.
-   Please check the build logs above for errors.`
-		)
-	}
+	if (!existsSync(ccSrc)) throw new Error(`Build output missing at ${ccSrc}`)
 
 	resetDir(ccDest)
 	cpSync(ccSrc, ccDest, { recursive: true })
 
-	// biome-ignore lint/suspicious/noConsole: keep for debugging
+	// biome-ignore lint/suspicious/noConsole: <explanation>
 	console.log(chalk.green(`✔ Built docs → ${ccDest}`))
 }
 
@@ -134,12 +118,13 @@ function buildRef(ref: string, labelForOutDir: string) {
 	const worktreePath = resolve(tmpBase, safeLabel)
 
 	run(`git worktree add --detach "${worktreePath}" "${ref}"`, {
-		cwd: workspaceRoot,
+		cwd: currentDocsWorkspace,
 		inherit: true,
 	})
 
 	try {
-		// Install dependencies at root if package.json exists
+		const docsWorkspace = docsRelative ? resolve(worktreePath, docsRelative) : worktreePath
+
 		const rootPkg = existsSync(resolve(worktreePath, "package.json"))
 		const rootLock = existsSync(resolve(worktreePath, "pnpm-lock.yaml"))
 		if (rootPkg) {
@@ -149,15 +134,17 @@ function buildRef(ref: string, labelForOutDir: string) {
 			})
 		}
 
-		// If this script was run from a subdirectory (for example `docs/` inside
-		// a monorepo), adjust the sourceDir inside the created worktree so we
-		// build the correct package.
-		const sourceDir = workspaceRelativePath ? resolve(worktreePath, workspaceRelativePath) : worktreePath
+		const docsPkg = existsSync(resolve(docsWorkspace, "package.json"))
+		const docsLock = existsSync(resolve(docsWorkspace, "pnpm-lock.yaml"))
+		if (docsPkg && docsLock) {
+			run("pnpm install --frozen-lockfile", { cwd: docsWorkspace, inherit: true })
+		}
+
 		const outDir = resolve(outputDir, labelForOutDir)
-		buildDocs(sourceDir, outDir)
+		buildDocs(docsWorkspace, outDir)
 	} finally {
 		run(`git worktree remove "${worktreePath}" --force`, {
-			cwd: workspaceRoot,
+			cwd: currentDocsWorkspace,
 			inherit: true,
 		})
 		rmSync(tmpBase, { recursive: true, force: true })
@@ -166,7 +153,7 @@ function buildRef(ref: string, labelForOutDir: string) {
 
 function buildBranch(branch: string, labelForOutDir: string) {
 	run(`git fetch --tags --prune origin ${branch}`, {
-		cwd: workspaceRoot,
+		cwd: currentDocsWorkspace,
 		inherit: true,
 	})
 	const localRef = `refs/heads/${branch}`
@@ -178,99 +165,88 @@ function buildTag(tag: string) {
 	return buildRef(`refs/tags/${tag}`, tag)
 }
 
-function getCurrentBranch(): string {
-	try {
-		return run("git rev-parse --abbrev-ref HEAD")
-	} catch {
-		throw new Error("Failed to get current branch")
-	}
+function isPullRequestCI() {
+	return process.env.GITHUB_EVENT_NAME === "pull_request" || !!process.env.GITHUB_HEAD_REF
 }
 
-function isOnDefaultBranch(defaultBranch: string): boolean {
-	const currentBranch = getCurrentBranch()
-	return currentBranch === defaultBranch
-}
 ;(async () => {
 	const { values } = parseArgs({
 		args: process.argv.slice(2),
 		options: {
-			versions: { type: "string" }, // optional: comma/space list of semver ranges or exact tags
-			branch: { type: "string" }, // required: specify default branch name (e.g., main, master, develop)
+			versions: { type: "string" }, // optional: comma/space list of semver ranges or exact tags (e.g. "v1.0.0, v1.1.x")
+			branch: { type: "string" }, // optional: default branch override (e.g. main)
 		},
 	})
 
-	// Get default branch from --branch flag (required)
-	const defaultBranch = (values.branch as string | undefined)?.trim()
-	if (!defaultBranch) {
-		throw new Error(
-			`❌ Missing required --branch flag.
-   Please specify the default branch name (e.g., --branch main)
-   Example: pnpm run generate:docs --branch main`
-		)
-	}
+	const defaultBranch =
+		(values.branch as string | undefined)?.trim() || detectDefaultBranch()
 
 	const rawVersions = (values.versions as string | undefined)?.trim() ?? ""
 	const hasVersionsArg = rawVersions.length > 0
 
 	let builtVersions: string[] = []
 
-	// Determine which branch to build as "current"
-	const onDefaultBranch = isOnDefaultBranch(defaultBranch)
-	const currentBranchToBuild = onDefaultBranch ? defaultBranch : getCurrentBranch()
-
-	// biome-ignore lint/suspicious/noConsole: keep for logging
-	console.log(chalk.cyan(`Building from branch: ${currentBranchToBuild}`))
-
-	if (hasVersionsArg) {
-		// Build specified version tags + current branch
-		const tags = resolveTagsFromSpec(rawVersions)
-		if (!tags.length) throw new Error(`No tags matched spec "${rawVersions}".`)
-
-		// biome-ignore lint/suspicious/noConsole: keep for logging
-		console.log(chalk.cyan(`Building tags: ${tags.join(", ")}`))
-		for (const t of tags) buildTag(t)
-
-		// Build current branch
-		if (onDefaultBranch) {
-			// biome-ignore lint/suspicious/noConsole: keep for logging
-			console.log(chalk.cyan(`Building default branch '${defaultBranch}' → current`))
-			buildBranch(defaultBranch, "current")
+	if (APP_ENV === "development") {
+		// Local dev: always build the current workspace → current
+		console.log(chalk.cyan(`(dev) Building docs from current workspace: ${currentDocsWorkspace} → current`))
+		buildDocs(currentDocsWorkspace, join(outputDir, "current"))
+		builtVersions = ["current"]
+	} else if (isPullRequestCI()) {
+		// PR builds
+		if (hasVersionsArg) {
+			// Build PR content as "current" + requested tags
+			console.log(chalk.cyan(`(pr) Building PR docs → current`))
+			buildDocs(currentDocsWorkspace, join(outputDir, "current"))
+
+			const tags = resolveTagsFromSpec(rawVersions)
+			if (!tags.length) throw new Error(`No tags matched spec "${rawVersions}".`)
+			console.log(chalk.cyan(`(pr) Also building tags: ${tags.join(", ")}`))
+			for (const t of tags) buildTag(t)
+
+			builtVersions = ["current", ...tags]
 		} else {
-			// biome-ignore lint/suspicious/noConsole: keep for logging
-			console.log(chalk.cyan("Building current workspace → current"))
-			buildDocs(workspaceRoot, join(outputDir, "current"))
+			// Only PR content as "current"
+			console.log(chalk.cyan(`(pr) Building PR docs → current`))
+			buildDocs(currentDocsWorkspace, join(outputDir, "current"))
+			builtVersions = ["current"]
 		}
-
-		builtVersions = ["current", ...tags]
 	} else {
-		// Build only current branch
-		if (onDefaultBranch) {
-			// biome-ignore lint/suspicious/noConsole: keep for logging
-			console.log(chalk.cyan(`Building default branch '${defaultBranch}' → current`))
-			buildBranch(defaultBranch, "current")
+		// Non-PR (e.g., release)
+		if (hasVersionsArg) {
+			// Build exactly the versions provided (this keeps older docs available if you list them)
+			const tags = resolveTagsFromSpec(rawVersions)
+			if (!tags.length) throw new Error(`No tags matched spec "${rawVersions}".`)
+			console.log(chalk.cyan(`(ci) Building tags: ${tags.join(", ")}`))
+			for (const t of tags) buildTag(t)
+			builtVersions = [...tags]
 		} else {
-			// biome-ignore lint/suspicious/noConsole: keep for logging
-			console.log(chalk.cyan("Building current workspace → current"))
-			buildDocs(workspaceRoot, join(outputDir, "current"))
+			// Fallback: build default branch (useful if you want a "main" channel)
+			const checkPath = repoPath(docsRelative, contentDir) // "docs/content"
+			run(`git fetch --prune origin ${defaultBranch}`, { cwd: currentDocsWorkspace, inherit: true })
+
+			const hasOnDefault = refHasPath(`origin/${defaultBranch}`, checkPath)
+			if (!hasOnDefault) {
+				throw new Error(
+					`Default branch 'origin/${defaultBranch}' has no '${checkPath}'. Pass --versions to build tags.`
+				)
+			}
+			console.log(chalk.cyan(`(ci) Building docs from '${defaultBranch}' → ${defaultBranch}`))
+			buildBranch(defaultBranch, defaultBranch)
+			builtVersions = [defaultBranch]
 		}
-
-		builtVersions = ["current"]
 	}
 
 	// Write versions file for the app
-	const versionsFile = resolve(workspaceRoot, "app/utils/versions.ts")
+	const versionsFile = resolve("app/utils/versions.ts")
 	writeFileSync(
 		versionsFile,
 		`// Auto-generated file. Do not edit manually.
 export const versions = ${JSON.stringify(builtVersions, null, 2)} as const
 `
 	)
-	// biome-ignore lint/suspicious/noConsole: keep for logging
 	console.log(chalk.green(`✔ Wrote versions.ts → ${versionsFile}`))
-	// biome-ignore lint/suspicious/noConsole: keep for logging
 	console.log(chalk.green("✅ Done"))
 })().catch((e) => {
-	// biome-ignore lint/suspicious/noConsole: keep for logging
 	console.error(chalk.red("❌ Build failed:"), e)
 	process.exit(1)
 })