The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 03:37 UTC
| 1 | // Generates the provider API reference under website/src/content/docs/providers |
| 2 | // (plus the providers sidebar and reference redirects) from source JSDoc. |
| 3 | // |
| 4 | // Usage: node scripts/generate-api-reference.ts [--copy-markers] |
| 5 | // --copy-markers (or API_REFERENCE_COPY_MARKERS=1) emits the website's |
| 6 | // dev-time copy-editor markers. |
| 7 | import * as NodeRuntime from "@effect/platform-node/NodeRuntime"; |
| 8 | import * as NodeServices from "@effect/platform-node/NodeServices"; |
| 9 | import { Command, Flag } from "effect/cli"; |
| 10 | import * as Config from "effect/Config"; |
| 11 | import * as Console from "effect/Console"; |
| 12 | import * as Data from "effect/Data"; |
| 13 | import * as Effect from "effect/Effect"; |
| 14 | import * as FileSystem from "effect/FileSystem"; |
| 15 | import * as Path from "effect/Path"; |
| 16 | import type * as PlatformError from "effect/PlatformError"; |
| 17 | import * as ts from "tsrs/unstable/ast"; |
| 18 | import type { Node, SourceFile } from "tsrs/unstable/ast"; |
| 19 | import { |
| 20 | docCommentLines, |
| 21 | jsdocCopyId, |
| 22 | LINK_TAG_RE, |
| 23 | markDocLines, |
| 24 | normalizeLinkTarget, |
| 25 | parseLinkTag, |
| 26 | } from "./jsdoc-blocks.ts"; |
| 27 | import { createSyntaxProject } from "./typescript-source.ts"; |
| 28 | |
| 29 | interface SourceRoot { |
| 30 | /** Directory scanned for documented source files (repo-relative). */ |
| 31 | srcRoot: string; |
| 32 | /** |
| 33 | * Synthetic provider name for flat single-provider packages (their files |
| 34 | * sit directly at `srcRoot`); empty for the alchemy package, whose |
| 35 | * top-level directories ARE the providers. |
| 36 | */ |
| 37 | providerPrefix: string; |
| 38 | /** Display prefix for the page's `Source:` line. */ |
| 39 | sourceDisplayPrefix: string; |
| 40 | } |
| 41 | |
| 42 | /** Source roots, relative to the repo root (resolved in `main`). */ |
| 43 | const sourceRoots: SourceRoot[] = [ |
| 44 | { srcRoot: "packages/alchemy/src", providerPrefix: "", sourceDisplayPrefix: "src" }, |
| 45 | { |
| 46 | srcRoot: "packages/better-auth/src", |
| 47 | providerPrefix: "BetterAuth", |
| 48 | sourceDisplayPrefix: "packages/better-auth/src", |
| 49 | }, |
| 50 | { srcRoot: "packages/git/src", providerPrefix: "Git", sourceDisplayPrefix: "packages/git/src" }, |
| 51 | { |
| 52 | srcRoot: "packages/drizzle/src", |
| 53 | providerPrefix: "Drizzle", |
| 54 | sourceDisplayPrefix: "packages/drizzle/src", |
| 55 | }, |
| 56 | { |
| 57 | srcRoot: "packages/acme/src", |
| 58 | providerPrefix: "ACME", |
| 59 | sourceDisplayPrefix: "packages/acme/src", |
| 60 | }, |
| 61 | { |
| 62 | srcRoot: "packages/axiom/src", |
| 63 | providerPrefix: "Axiom", |
| 64 | sourceDisplayPrefix: "packages/axiom/src", |
| 65 | }, |
| 66 | { |
| 67 | srcRoot: "packages/doppler/src", |
| 68 | providerPrefix: "Doppler", |
| 69 | sourceDisplayPrefix: "packages/doppler/src", |
| 70 | }, |
| 71 | { |
| 72 | srcRoot: "packages/infisical/src", |
| 73 | providerPrefix: "Infisical", |
| 74 | sourceDisplayPrefix: "packages/infisical/src", |
| 75 | }, |
| 76 | { |
| 77 | srcRoot: "packages/turso/src", |
| 78 | providerPrefix: "Turso", |
| 79 | sourceDisplayPrefix: "packages/turso/src", |
| 80 | }, |
| 81 | { |
| 82 | srcRoot: "packages/planetscale/src", |
| 83 | providerPrefix: "Planetscale", |
| 84 | sourceDisplayPrefix: "packages/planetscale/src", |
| 85 | }, |
| 86 | { |
| 87 | srcRoot: "packages/neon/src", |
| 88 | providerPrefix: "Neon", |
| 89 | sourceDisplayPrefix: "packages/neon/src", |
| 90 | }, |
| 91 | { |
| 92 | srcRoot: "packages/prisma/src", |
| 93 | providerPrefix: "Prisma", |
| 94 | sourceDisplayPrefix: "packages/prisma/src", |
| 95 | }, |
| 96 | { |
| 97 | srcRoot: "packages/hetzner/src", |
| 98 | providerPrefix: "Hetzner", |
| 99 | sourceDisplayPrefix: "packages/hetzner/src", |
| 100 | }, |
| 101 | { |
| 102 | srcRoot: "packages/railway/src", |
| 103 | providerPrefix: "Railway", |
| 104 | sourceDisplayPrefix: "packages/railway/src", |
| 105 | }, |
| 106 | { srcRoot: "packages/fly/src", providerPrefix: "Fly", sourceDisplayPrefix: "packages/fly/src" }, |
| 107 | { |
| 108 | srcRoot: "packages/github/src", |
| 109 | providerPrefix: "GitHub", |
| 110 | sourceDisplayPrefix: "packages/github/src", |
| 111 | }, |
| 112 | { |
| 113 | srcRoot: "packages/stripe/src", |
| 114 | providerPrefix: "Stripe", |
| 115 | sourceDisplayPrefix: "packages/stripe/src", |
| 116 | }, |
| 117 | { |
| 118 | srcRoot: "packages/cloudflare/src", |
| 119 | providerPrefix: "Cloudflare", |
| 120 | sourceDisplayPrefix: "packages/cloudflare/src", |
| 121 | }, |
| 122 | { srcRoot: "packages/gcp/src", providerPrefix: "GCP", sourceDisplayPrefix: "packages/gcp/src" }, |
| 123 | { srcRoot: "packages/aws/src", providerPrefix: "AWS", sourceDisplayPrefix: "packages/aws/src" }, |
| 124 | { |
| 125 | srcRoot: "packages/domain/src", |
| 126 | providerPrefix: "Domain", |
| 127 | sourceDisplayPrefix: "packages/domain/src", |
| 128 | }, |
| 129 | { |
| 130 | srcRoot: "packages/kubernetes/src", |
| 131 | providerPrefix: "Kubernetes", |
| 132 | sourceDisplayPrefix: "packages/kubernetes/src", |
| 133 | }, |
| 134 | { |
| 135 | srcRoot: "packages/docker/src", |
| 136 | providerPrefix: "Docker", |
| 137 | sourceDisplayPrefix: "packages/docker/src", |
| 138 | }, |
| 139 | { srcRoot: "packages/sql/src", providerPrefix: "SQL", sourceDisplayPrefix: "packages/sql/src" }, |
| 140 | ]; |
| 141 | |
| 142 | interface FileEntry { |
| 143 | /** Output-relative path (provider-prefixed for flat packages). */ |
| 144 | relativePath: string; |
| 145 | absolutePath: string; |
| 146 | /** Display path for the page's `Source:` blockquote. */ |
| 147 | sourceDisplay: string; |
| 148 | } |
| 149 | |
| 150 | interface ExampleBlock { |
| 151 | title: string; |
| 152 | body: string; |
| 153 | } |
| 154 | |
| 155 | interface ExampleSection { |
| 156 | title: string; |
| 157 | description: string; |
| 158 | examples: ExampleBlock[]; |
| 159 | } |
| 160 | |
| 161 | interface PageDoc { |
| 162 | title: string; |
| 163 | /** Display path for the `Source:` blockquote. */ |
| 164 | sourceDisplay: string; |
| 165 | summary: string; |
| 166 | sections: ExampleSection[]; |
| 167 | /** True for `@layer` pages — renders the Layer metadata line. */ |
| 168 | isLayer: boolean; |
| 169 | /** Service tags the Layer provides (`@provides`). */ |
| 170 | provides: string[]; |
| 171 | /** Optional peer dependencies (`@peer`). */ |
| 172 | peers: string[]; |
| 173 | } |
| 174 | |
| 175 | // Paths are POSIX on every platform we run on; also fold Windows separators. |
| 176 | const normalizeSlashes = (value: string) => value.replaceAll("\\", "/"); |
| 177 | |
| 178 | const isSourceFile = (baseName: string) => |
| 179 | (baseName.endsWith(".ts") || baseName.endsWith(".tsx")) && |
| 180 | !baseName.endsWith(".d.ts") && |
| 181 | baseName !== "index.ts"; |
| 182 | |
| 183 | const discoverFiles = Effect.fn(function* (repoRoot: string, root: SourceRoot) { |
| 184 | const fs = yield* FileSystem.FileSystem; |
| 185 | const path = yield* Path.Path; |
| 186 | const srcRoot = path.join(repoRoot, root.srcRoot); |
| 187 | const entries: FileEntry[] = []; |
| 188 | |
| 189 | // Flat single-provider packages: every file under srcRoot belongs to the |
| 190 | // synthetic provider directory. |
| 191 | if (root.providerPrefix) { |
| 192 | const files = yield* fs.readDirectory(srcRoot, { recursive: true }); |
| 193 | for (const file of files) { |
| 194 | if (!isSourceFile(path.basename(file))) continue; |
| 195 | entries.push({ |
| 196 | relativePath: path.join(root.providerPrefix, file), |
| 197 | absolutePath: path.join(srcRoot, file), |
| 198 | sourceDisplay: `${root.sourceDisplayPrefix}/${normalizeSlashes(file)}`, |
| 199 | }); |
| 200 | } |
| 201 | entries.sort((a, b) => a.relativePath.localeCompare(b.relativePath)); |
| 202 | return entries; |
| 203 | } |
| 204 | |
| 205 | for (const dir of yield* fs.readDirectory(srcRoot)) { |
| 206 | const dirPath = path.join(srcRoot, dir); |
| 207 | const info = yield* fs.stat(dirPath); |
| 208 | if (info.type !== "Directory") continue; |
| 209 | const files = yield* fs |
| 210 | .readDirectory(dirPath, { recursive: true }) |
| 211 | .pipe(Effect.orElseSucceed((): string[] => [])); |
| 212 | |
| 213 | for (const file of files) { |
| 214 | if (!isSourceFile(path.basename(file))) continue; |
| 215 | |
| 216 | const relativePath = path.join(dir, file); |
| 217 | entries.push({ |
| 218 | relativePath, |
| 219 | absolutePath: path.join(srcRoot, relativePath), |
| 220 | sourceDisplay: `${root.sourceDisplayPrefix}/${normalizeSlashes(relativePath)}`, |
| 221 | }); |
| 222 | } |
| 223 | } |
| 224 | |
| 225 | entries.sort((a, b) => a.relativePath.localeCompare(b.relativePath)); |
| 226 | return entries; |
| 227 | }); |
| 228 | |
| 229 | function getJsDocText(node: Node): string { |
| 230 | return node.jsDoc?.map((doc) => doc.getText()).join("\n") ?? ""; |
| 231 | } |
| 232 | |
| 233 | function cleanDocComment(raw: string): string { |
| 234 | return raw |
| 235 | .replace(/^\/\*\*?/, "") |
| 236 | .replace(/\*\/$/, "") |
| 237 | .split("\n") |
| 238 | .map((line) => line.replace(/^\s*\*\s?/, "")) |
| 239 | .join("\n"); |
| 240 | } |
| 241 | |
| 242 | interface ParsedJSDoc { |
| 243 | summary: string; |
| 244 | sections: ExampleSection[]; |
| 245 | hasResourceTag: boolean; |
| 246 | hasBindingTag: boolean; |
| 247 | /** `@layer` — a Layer factory providing a Context service. */ |
| 248 | hasLayerTag: boolean; |
| 249 | /** |
| 250 | * `@primitive` — a building block exported as a module's `make` (e.g. |
| 251 | * `Domain.Event`). Its page is named after the file, not the export. |
| 252 | */ |
| 253 | hasPrimitiveTag: boolean; |
| 254 | /** `@provides <Service.Tag>` — service tags the Layer satisfies. */ |
| 255 | provides: string[]; |
| 256 | /** `@peer <package>` — optional peer dependencies the Layer needs. */ |
| 257 | peers: string[]; |
| 258 | category: string; |
| 259 | product: string; |
| 260 | /** `@title <Heading>` — overrides the section heading (the export name). */ |
| 261 | title: string; |
| 262 | } |
| 263 | |
| 264 | /** Where a declaration's JSDoc lives, for copy markers. */ |
| 265 | interface MarkerContext { |
| 266 | /** Repo-relative path of the source file. */ |
| 267 | file: string; |
| 268 | /** Full source text (JSDoc offsets index into it). */ |
| 269 | text: string; |
| 270 | } |
| 271 | |
| 272 | function docLines(node: Node, raw: string, markers?: MarkerContext): string[] { |
| 273 | const docs = node.jsDoc ?? []; |
| 274 | // Markers need one comment per declaration to map blocks to source. |
| 275 | const start = docs[0]?.getStart(); |
| 276 | // `getStart()` can land on leading `//` trivia; only map clean comments. |
| 277 | if ( |
| 278 | markers && |
| 279 | docs.length === 1 && |
| 280 | start !== undefined && |
| 281 | markers.text.startsWith("/**", start) |
| 282 | ) { |
| 283 | return markDocLines(docCommentLines(markers.text, start), (block) => |
| 284 | jsdocCopyId(markers.file, start, block), |
| 285 | ); |
| 286 | } |
| 287 | return cleanDocComment(raw).split("\n"); |
| 288 | } |
| 289 | |
| 290 | function parseJSDoc(node: Node, markers?: MarkerContext): ParsedJSDoc { |
| 291 | const raw = getJsDocText(node); |
| 292 | if (!raw) { |
| 293 | return { |
| 294 | summary: "", |
| 295 | sections: [], |
| 296 | hasResourceTag: false, |
| 297 | hasBindingTag: false, |
| 298 | hasLayerTag: false, |
| 299 | hasPrimitiveTag: false, |
| 300 | provides: [], |
| 301 | peers: [], |
| 302 | category: "", |
| 303 | product: "", |
| 304 | title: "", |
| 305 | }; |
| 306 | } |
| 307 | |
| 308 | const lines = docLines(node, raw, markers); |
| 309 | |
| 310 | const summaryLines: string[] = []; |
| 311 | const sections: ExampleSection[] = []; |
| 312 | const provides: string[] = []; |
| 313 | const peers: string[] = []; |
| 314 | let hasResourceTag = false; |
| 315 | let hasBindingTag = false; |
| 316 | let hasLayerTag = false; |
| 317 | let hasPrimitiveTag = false; |
| 318 | let category = ""; |
| 319 | let product = ""; |
| 320 | let title = ""; |
| 321 | let sawTag = false; |
| 322 | let currentSection: ExampleSection | undefined; |
| 323 | let currentExample: ExampleBlock | undefined; |
| 324 | |
| 325 | let sectionDescLines: string[] = []; |
| 326 | let collectingSectionDesc = false; |
| 327 | let insideFence = false; |
| 328 | |
| 329 | const flushExample = () => { |
| 330 | if (!currentExample) return; |
| 331 | currentExample.body = currentExample.body.trim(); |
| 332 | if (!currentSection) { |
| 333 | currentSection = { title: "Examples", description: "", examples: [] }; |
| 334 | sections.push(currentSection); |
| 335 | } |
| 336 | currentSection.examples.push(currentExample); |
| 337 | currentExample = undefined; |
| 338 | }; |
| 339 | |
| 340 | const flushSectionDesc = () => { |
| 341 | if (currentSection && sectionDescLines.length > 0) { |
| 342 | currentSection.description = sectionDescLines.join("\n").trim(); |
| 343 | } |
| 344 | sectionDescLines = []; |
| 345 | collectingSectionDesc = false; |
| 346 | }; |
| 347 | |
| 348 | for (const line of lines) { |
| 349 | // Track fenced code blocks so an `@`-prefixed line inside an example |
| 350 | // (e.g. a decorator) is never mistaken for a JSDoc tag. |
| 351 | if (line.trim().startsWith("```")) { |
| 352 | insideFence = !insideFence; |
| 353 | } |
| 354 | |
| 355 | const proseHeading = insideFence |
| 356 | ? null |
| 357 | : line.trim().match(/^###\s+(.+?)\s+<!-- api-prose -->$/); |
| 358 | if (proseHeading) { |
| 359 | if (!sawTag) summaryLines.push(`### ${proseHeading[1]!.trim()}`); |
| 360 | continue; |
| 361 | } |
| 362 | |
| 363 | const section = insideFence ? null : line.trim().match(/^###\s+(.+)$/); |
| 364 | if (section) { |
| 365 | sawTag = true; |
| 366 | flushExample(); |
| 367 | flushSectionDesc(); |
| 368 | currentSection = { title: section[1]!.trim(), description: "", examples: [] }; |
| 369 | sections.push(currentSection); |
| 370 | collectingSectionDesc = true; |
| 371 | continue; |
| 372 | } |
| 373 | |
| 374 | const example = insideFence ? null : line.trim().match(/^\*\*Example:\*\*\s*(.*)$/); |
| 375 | if (example) { |
| 376 | sawTag = true; |
| 377 | flushSectionDesc(); |
| 378 | flushExample(); |
| 379 | currentExample = { title: example[1]!.trim() || "Example", body: "" }; |
| 380 | continue; |
| 381 | } |
| 382 | |
| 383 | const tag = insideFence ? null : line.trim().match(/^@(\w+)\s*(.*)$/); |
| 384 | if (tag) { |
| 385 | sawTag = true; |
| 386 | const [, name, rest] = tag; |
| 387 | const value = (rest ?? "").trim(); |
| 388 | switch (name) { |
| 389 | case "resource": |
| 390 | hasResourceTag = true; |
| 391 | break; |
| 392 | case "binding": |
| 393 | hasBindingTag = true; |
| 394 | break; |
| 395 | case "layer": |
| 396 | hasLayerTag = true; |
| 397 | break; |
| 398 | case "primitive": |
| 399 | hasPrimitiveTag = true; |
| 400 | break; |
| 401 | case "provides": |
| 402 | if (value) provides.push(value); |
| 403 | break; |
| 404 | case "peer": |
| 405 | if (value) peers.push(value); |
| 406 | break; |
| 407 | case "category": |
| 408 | case "group": |
| 409 | if (value) category = value; |
| 410 | break; |
| 411 | case "product": |
| 412 | case "label": |
| 413 | if (value) product = value; |
| 414 | break; |
| 415 | case "title": |
| 416 | if (value) title = value; |
| 417 | break; |
| 418 | case "section": |
| 419 | flushExample(); |
| 420 | flushSectionDesc(); |
| 421 | currentSection = { title: value || "Examples", description: "", examples: [] }; |
| 422 | sections.push(currentSection); |
| 423 | collectingSectionDesc = true; |
| 424 | break; |
| 425 | case "example": |
| 426 | flushSectionDesc(); |
| 427 | flushExample(); |
| 428 | currentExample = { title: value || "Example", body: "" }; |
| 429 | break; |
| 430 | } |
| 431 | continue; |
| 432 | } |
| 433 | |
| 434 | if (!sawTag) { |
| 435 | summaryLines.push(line); |
| 436 | continue; |
| 437 | } |
| 438 | |
| 439 | if (currentExample) { |
| 440 | currentExample.body += `${line}\n`; |
| 441 | } else if (collectingSectionDesc) { |
| 442 | sectionDescLines.push(line); |
| 443 | } |
| 444 | } |
| 445 | |
| 446 | flushSectionDesc(); |
| 447 | flushExample(); |
| 448 | |
| 449 | return { |
| 450 | summary: summaryLines.join("\n").trim(), |
| 451 | sections, |
| 452 | hasResourceTag, |
| 453 | hasBindingTag, |
| 454 | hasLayerTag, |
| 455 | hasPrimitiveTag, |
| 456 | provides, |
| 457 | peers, |
| 458 | category, |
| 459 | product, |
| 460 | title, |
| 461 | }; |
| 462 | } |
| 463 | |
| 464 | function declName(node: Node): string { |
| 465 | if (ts.isVariableStatement(node)) { |
| 466 | return node.declarationList.declarations[0]?.name.getText() ?? ""; |
| 467 | } |
| 468 | if ( |
| 469 | ts.isClassDeclaration(node) || |
| 470 | ts.isFunctionDeclaration(node) || |
| 471 | ts.isInterfaceDeclaration(node) || |
| 472 | ts.isTypeAliasDeclaration(node) |
| 473 | ) { |
| 474 | return node.name?.getText() ?? ""; |
| 475 | } |
| 476 | return ""; |
| 477 | } |
| 478 | |
| 479 | interface Primary { |
| 480 | name: string; |
| 481 | doc: ParsedJSDoc; |
| 482 | category: string; |
| 483 | product: string; |
| 484 | } |
| 485 | |
| 486 | const hasContent = (doc: ParsedJSDoc) => Boolean(doc.summary) || doc.sections.length > 0; |
| 487 | |
| 488 | /** |
| 489 | * Map a public export name back to its local declaration name when a file |
| 490 | * re-exports under an alias, e.g. `export { VpcLinkResource as VpcLink }` |
| 491 | * lets us find the documented `VpcLinkResource` const from the tagged |
| 492 | * `VpcLink` interface. |
| 493 | */ |
| 494 | export function exportedNames(sourceFile: SourceFile): string[] { |
| 495 | const names = new Set<string>(); |
| 496 | const addBinding = (name: ts.BindingName): void => { |
| 497 | if (ts.isIdentifier(name)) names.add(name.text); |
| 498 | else |
| 499 | for (const element of name.elements) { |
| 500 | if (ts.isBindingElement(element) && element.name) addBinding(element.name); |
| 501 | } |
| 502 | }; |
| 503 | for (const statement of sourceFile.statements) { |
| 504 | if (ts.isExportDeclaration(statement)) { |
| 505 | if (statement.exportClause && ts.isNamedExports(statement.exportClause)) { |
| 506 | for (const spec of statement.exportClause.elements) names.add(spec.name.text); |
| 507 | } else if (statement.exportClause && ts.isNamespaceExport(statement.exportClause)) { |
| 508 | names.add(statement.exportClause.name.text); |
| 509 | } |
| 510 | } else if (ts.isExportAssignment(statement)) { |
| 511 | if (!statement.isExportEquals) names.add("default"); |
| 512 | } else if ( |
| 513 | (ts.isVariableStatement(statement) || |
| 514 | ts.isClassDeclaration(statement) || |
| 515 | ts.isFunctionDeclaration(statement) || |
| 516 | ts.isInterfaceDeclaration(statement) || |
| 517 | ts.isTypeAliasDeclaration(statement) || |
| 518 | ts.isEnumDeclaration(statement) || |
| 519 | ts.isModuleDeclaration(statement) || |
| 520 | ts.isImportEqualsDeclaration(statement)) && |
| 521 | statement.modifierFlags & ts.ModifierFlags.Export |
| 522 | ) { |
| 523 | if (statement.modifierFlags & ts.ModifierFlags.Default) names.add("default"); |
| 524 | else if (ts.isVariableStatement(statement)) { |
| 525 | for (const declaration of statement.declarationList.declarations) |
| 526 | addBinding(declaration.name); |
| 527 | } else if ( |
| 528 | ts.isClassDeclaration(statement) || |
| 529 | ts.isFunctionDeclaration(statement) || |
| 530 | ts.isInterfaceDeclaration(statement) || |
| 531 | ts.isTypeAliasDeclaration(statement) || |
| 532 | ts.isEnumDeclaration(statement) || |
| 533 | ts.isModuleDeclaration(statement) || |
| 534 | ts.isImportEqualsDeclaration(statement) |
| 535 | ) { |
| 536 | if (statement.name) names.add(statement.name.text); |
| 537 | } |
| 538 | } |
| 539 | } |
| 540 | return [...names]; |
| 541 | } |
| 542 | |
| 543 | function localNameForExport(sourceFile: SourceFile, publicName: string): string | undefined { |
| 544 | for (const ed of sourceFile.statements.filter(ts.isExportDeclaration)) { |
| 545 | if (ed.moduleSpecifier) continue; |
| 546 | for (const spec of ed.exportClause && ts.isNamedExports(ed.exportClause) |
| 547 | ? ed.exportClause.elements |
| 548 | : []) { |
| 549 | if (spec.name.text === publicName) { |
| 550 | return (spec.propertyName ?? spec.name).text; |
| 551 | } |
| 552 | } |
| 553 | } |
| 554 | return undefined; |
| 555 | } |
| 556 | |
| 557 | /** |
| 558 | * The page for a file is owned by the single exported declaration tagged |
| 559 | * `@resource` or `@binding`, and named after it. Authors sometimes write the |
| 560 | * docs (summary/@section/@example) on a sibling declaration of the same name |
| 561 | * (an `interface X` paired with `const X`) or on an internal const that is |
| 562 | * re-exported under the tagged name (the ApiGateway `XResource as X` pattern). |
| 563 | * When the tagged declaration itself has no content, pull it from that related |
| 564 | * declaration so the page isn't dropped as empty. |
| 565 | */ |
| 566 | export function findTaggedPrimary( |
| 567 | sourceFile: SourceFile, |
| 568 | markers?: MarkerContext, |
| 569 | ): Primary | undefined { |
| 570 | const candidates: Node[] = [ |
| 571 | ...sourceFile.statements |
| 572 | .filter(ts.isVariableStatement) |
| 573 | .filter((s) => Boolean(s.modifierFlags & ts.ModifierFlags.Export)), |
| 574 | ...sourceFile.statements |
| 575 | .filter(ts.isClassDeclaration) |
| 576 | .filter((c) => Boolean(c.modifierFlags & ts.ModifierFlags.Export)), |
| 577 | ...sourceFile.statements |
| 578 | .filter(ts.isInterfaceDeclaration) |
| 579 | .filter((i) => Boolean(i.modifierFlags & ts.ModifierFlags.Export)), |
| 580 | // An overloaded function carries its JSDoc on the first signature. |
| 581 | ...sourceFile.statements |
| 582 | .filter(ts.isFunctionDeclaration) |
| 583 | .filter((f) => Boolean(f.modifierFlags & ts.ModifierFlags.Export)), |
| 584 | ]; |
| 585 | |
| 586 | for (const node of candidates) { |
| 587 | const doc = parseJSDoc(node, markers); |
| 588 | if (!doc.hasResourceTag && !doc.hasBindingTag && !doc.hasLayerTag && !doc.hasPrimitiveTag) { |
| 589 | continue; |
| 590 | } |
| 591 | // A primitive is its module's `make`; the page is named after the module. |
| 592 | const exportName = doc.hasPrimitiveTag |
| 593 | ? normalizeSlashes(sourceFile.fileName) |
| 594 | .split("/") |
| 595 | .pop()! |
| 596 | .replace(/\.tsx?$/, "") |
| 597 | : declName(node); |
| 598 | if (!exportName) continue; |
| 599 | const name = doc.title || exportName; |
| 600 | const category = doc.category; |
| 601 | const product = doc.product; |
| 602 | if (hasContent(doc)) return { name, doc, category, product }; |
| 603 | |
| 604 | // Tagged declaration has no prose — look for the related declaration that |
| 605 | // carries the docs (same name, or re-exported under this name). |
| 606 | const localName = localNameForExport(sourceFile, exportName); |
| 607 | const related: Node[] = [ |
| 608 | ...sourceFile.statements.filter(ts.isVariableStatement), |
| 609 | ...sourceFile.statements.filter(ts.isClassDeclaration), |
| 610 | ...sourceFile.statements.filter(ts.isInterfaceDeclaration), |
| 611 | ...sourceFile.statements.filter(ts.isTypeAliasDeclaration), |
| 612 | ].filter((d) => { |
| 613 | if (d === node) return false; |
| 614 | const dn = declName(d); |
| 615 | return dn === exportName || (localName !== undefined && dn === localName); |
| 616 | }); |
| 617 | |
| 618 | let best: ParsedJSDoc | undefined; |
| 619 | for (const d of related) { |
| 620 | const pd = parseJSDoc(d, markers); |
| 621 | if (pd.sections.length > 0) { |
| 622 | best = pd; |
| 623 | break; |
| 624 | } |
| 625 | if (!best && pd.summary) best = pd; |
| 626 | } |
| 627 | // Borrowed prose keeps the TAGGED declaration's kind + metadata. |
| 628 | const merged: ParsedJSDoc = { |
| 629 | ...(best ?? doc), |
| 630 | hasResourceTag: doc.hasResourceTag, |
| 631 | hasBindingTag: doc.hasBindingTag, |
| 632 | hasLayerTag: doc.hasLayerTag, |
| 633 | hasPrimitiveTag: doc.hasPrimitiveTag, |
| 634 | provides: doc.provides, |
| 635 | peers: doc.peers, |
| 636 | }; |
| 637 | return { name, doc: merged, category, product }; |
| 638 | } |
| 639 | return undefined; |
| 640 | } |
| 641 | |
| 642 | /** Resolves a `{@link}` symbol target to a generated page URL, if any. */ |
| 643 | type LinkResolver = (target: string) => string | undefined; |
| 644 | |
| 645 | /** |
| 646 | * Build a per-page resolver factory. A symbol resolves to another generated |
| 647 | * page preferring (in order): a same-directory page named after it, a |
| 648 | * same-directory page whose source file exports it (an access-level service |
| 649 | * like `ReadNamespace` documented on its `ReadWriteNamespace` page), a unique |
| 650 | * name match within the same provider, a unique exporter within the same |
| 651 | * provider, then a unique global name match. Member suffixes |
| 652 | * (`Cluster#capacityProviders`), provider-qualified names (`Cloudflare.Worker`) |
| 653 | * and `FooProps` interfaces resolve to the base resource's page. |
| 654 | */ |
| 655 | function makeLinkResolverFactory(pages: PageEntry[]): (fromDir: string) => LinkResolver { |
| 656 | const byName = new Map<string, PageEntry[]>(); |
| 657 | const byExport = new Map<string, PageEntry[]>(); |
| 658 | for (const p of pages) { |
| 659 | if (!byName.has(p.resource)) byName.set(p.resource, []); |
| 660 | byName.get(p.resource)!.push(p); |
| 661 | for (const name of p.exports) { |
| 662 | if (!byExport.has(name)) byExport.set(name, []); |
| 663 | byExport.get(name)!.push(p); |
| 664 | } |
| 665 | } |
| 666 | const providers = new Set(pages.map((p) => p.provider)); |
| 667 | |
| 668 | return (fromDir: string) => { |
| 669 | const fromProvider = fromDir.split("/")[0] ?? ""; |
| 670 | |
| 671 | const lookup = (name: string, provider?: string): PageEntry | undefined => { |
| 672 | const scope = (list: PageEntry[] | undefined) => |
| 673 | (list ?? []).filter((c) => !provider || c.provider === provider); |
| 674 | const named = scope(byName.get(name)); |
| 675 | const exporting = scope(byExport.get(name)); |
| 676 | |
| 677 | const sameDirNamed = named.filter((c) => c.dir === fromDir); |
| 678 | if (sameDirNamed.length === 1) return sameDirNamed[0]; |
| 679 | const sameDirExporting = exporting.filter((c) => c.dir === fromDir); |
| 680 | if (sameDirExporting.length === 1) return sameDirExporting[0]; |
| 681 | const providerNamed = named.filter((c) => c.provider === fromProvider); |
| 682 | if (providerNamed.length === 1) return providerNamed[0]; |
| 683 | const providerExporting = exporting.filter((c) => c.provider === fromProvider); |
| 684 | if (providerExporting.length === 1) return providerExporting[0]; |
| 685 | if (named.length === 1) return named[0]; |
| 686 | return undefined; |
| 687 | }; |
| 688 | |
| 689 | return (target: string) => { |
| 690 | // Strip a `#member` suffix — the link lands on the owning resource page. |
| 691 | const base = target.split("#")[0]; |
| 692 | |
| 693 | const attempts: { name: string; provider?: string }[] = [{ name: base }]; |
| 694 | if (base.includes(".")) { |
| 695 | const segments = base.split("."); |
| 696 | const first = segments[0]; |
| 697 | const last = segments[segments.length - 1]; |
| 698 | if (providers.has(first)) { |
| 699 | // Provider-qualified: `Cloudflare.Worker`, `Cloudflare.KV.Namespace`. |
| 700 | attempts.push({ name: last, provider: first }); |
| 701 | } else { |
| 702 | // Member access on a symbol: `KeyPairProps.publicKeyMaterial`. |
| 703 | attempts.push({ name: first }); |
| 704 | if (first.endsWith("Props")) { |
| 705 | attempts.push({ name: first.slice(0, -"Props".length) }); |
| 706 | } |
| 707 | } |
| 708 | } else if (base.endsWith("Props")) { |
| 709 | attempts.push({ name: base.slice(0, -"Props".length) }); |
| 710 | } |
| 711 | |
| 712 | for (const attempt of attempts) { |
| 713 | const found = lookup(attempt.name, attempt.provider); |
| 714 | if (found) return found.link; |
| 715 | } |
| 716 | return undefined; |
| 717 | }; |
| 718 | }; |
| 719 | } |
| 720 | |
| 721 | const isUrl = (target: string) => /^https?:\/\//.test(target); |
| 722 | |
| 723 | /** |
| 724 | * Replace `{@link ...}` tags with markdown links, skipping fenced code |
| 725 | * blocks. Symbols that don't resolve to a generated page render as inline |
| 726 | * code (or their label) instead of leaking the raw tag. |
| 727 | */ |
| 728 | /** Symbol targets that didn't resolve to a page, for the end-of-run summary. */ |
| 729 | const unresolvedLinkTargets = new Map<string, number>(); |
| 730 | |
| 731 | function linkifyMarkdown(markdown: string, resolve: LinkResolver): string { |
| 732 | const replaceTags = (chunk: string) => |
| 733 | chunk.replace(LINK_TAG_RE, (_, inner: string) => { |
| 734 | // A tag wrapped across source lines carries the line break in its |
| 735 | // label — collapse it so the markdown link stays intact. |
| 736 | const parsed = parseLinkTag(inner.replace(/\s+/g, " ")); |
| 737 | const label = parsed.label; |
| 738 | if (isUrl(parsed.target)) { |
| 739 | return `[${label ?? parsed.target}](${parsed.target})`; |
| 740 | } |
| 741 | const target = normalizeLinkTarget(parsed.target); |
| 742 | const url = resolve(target); |
| 743 | if (!url) { |
| 744 | unresolvedLinkTargets.set(target, (unresolvedLinkTargets.get(target) ?? 0) + 1); |
| 745 | } |
| 746 | const text = label ?? `\`${target}\``; |
| 747 | return url ? `[${text}](${url})` : text; |
| 748 | }); |
| 749 | |
| 750 | // Apply across contiguous non-fence chunks (a `{@link}` may span lines); |
| 751 | // leave fenced code blocks untouched. |
| 752 | const out: string[] = []; |
| 753 | let chunk: string[] = []; |
| 754 | let insideFence = false; |
| 755 | const flushChunk = () => { |
| 756 | if (chunk.length > 0) { |
| 757 | out.push(replaceTags(chunk.join("\n"))); |
| 758 | chunk = []; |
| 759 | } |
| 760 | }; |
| 761 | for (const line of markdown.split("\n")) { |
| 762 | if (line.trim().startsWith("```")) { |
| 763 | if (!insideFence) flushChunk(); |
| 764 | insideFence = !insideFence; |
| 765 | out.push(line); |
| 766 | continue; |
| 767 | } |
| 768 | if (insideFence) { |
| 769 | out.push(line); |
| 770 | } else { |
| 771 | chunk.push(line); |
| 772 | } |
| 773 | } |
| 774 | flushChunk(); |
| 775 | return out.join("\n"); |
| 776 | } |
| 777 | |
| 778 | function yamlString(value: string): string { |
| 779 | if (/[\n:"{}[\],&*?|>!%@`#]/.test(value) || value.trim() !== value) { |
| 780 | return JSON.stringify(value); |
| 781 | } |
| 782 | return value; |
| 783 | } |
| 784 | |
| 785 | function renderPageBody(doc: PageDoc): string { |
| 786 | const parts: string[] = []; |
| 787 | |
| 788 | if (doc.summary) { |
| 789 | parts.push(doc.summary); |
| 790 | } |
| 791 | |
| 792 | for (const section of doc.sections) { |
| 793 | const secParts = [`## ${section.title}`]; |
| 794 | if (section.description) { |
| 795 | secParts.push(section.description); |
| 796 | } |
| 797 | for (const example of section.examples) { |
| 798 | if (section.examples.length > 1) { |
| 799 | secParts.push(`**${example.title}**`); |
| 800 | } |
| 801 | secParts.push(example.body); |
| 802 | } |
| 803 | parts.push(secParts.join("\n\n")); |
| 804 | } |
| 805 | |
| 806 | return parts.join("\n\n"); |
| 807 | } |
| 808 | |
| 809 | function renderReferenceFrontmatter(title: string): string { |
| 810 | return [ |
| 811 | "---", |
| 812 | `title: ${yamlString(`${title} reference`)}`, |
| 813 | `description: ${yamlString(`Resources and capabilities for ${title}.`)}`, |
| 814 | // Keep the existing search-engine indexing policy during this experiment. |
| 815 | "head:", |
| 816 | " - tag: meta", |
| 817 | " attrs:", |
| 818 | " name: robots", |
| 819 | ' content: "noindex, follow"', |
| 820 | "prev: false", |
| 821 | "next: false", |
| 822 | "tableOfContents:", |
| 823 | " minHeadingLevel: 2", |
| 824 | " maxHeadingLevel: 2", |
| 825 | "---", |
| 826 | ].join("\n"); |
| 827 | } |
| 828 | |
| 829 | function renderResource(doc: PageDoc, resolve: LinkResolver): string { |
| 830 | const headerLines = [`> **Source:** \`${doc.sourceDisplay}\``]; |
| 831 | if (doc.isLayer) { |
| 832 | const meta = ["**Kind:** Layer"]; |
| 833 | if (doc.provides.length > 0) { |
| 834 | meta.push(`**Provides:** ${doc.provides.map((tag) => `\`${tag}\``).join(", ")}`); |
| 835 | } |
| 836 | if (doc.peers.length > 0) { |
| 837 | meta.push(`**Peer dependencies:** ${doc.peers.map((peer) => `\`${peer}\``).join(", ")}`); |
| 838 | } |
| 839 | headerLines.push(`> ${meta.join(" · ")}`); |
| 840 | } |
| 841 | const sourceBlock = headerLines.join("\n"); |
| 842 | const body = linkifyMarkdown(renderPageBody(doc).trim(), resolve); |
| 843 | |
| 844 | if (body) { |
| 845 | return `${sourceBlock}\n\n${body}\n`; |
| 846 | } |
| 847 | return `${sourceBlock}\n`; |
| 848 | } |
| 849 | |
| 850 | /** Change this grouping to experiment with larger or smaller reference pages. */ |
| 851 | function referenceLocation(outputRelative: string, product: string) { |
| 852 | const parts = normalizeSlashes(outputRelative).replace(/\.md$/, "").split("/"); |
| 853 | // Flat providers declare service-sized pages with @product instead of |
| 854 | // folders; a resource without one gets its own page. |
| 855 | const group = |
| 856 | parts.length > 2 |
| 857 | ? parts.slice(0, 2) |
| 858 | : product |
| 859 | ? [ |
| 860 | parts[0], |
| 861 | "reference", |
| 862 | product |
| 863 | .toLowerCase() |
| 864 | .replace(/[^a-z0-9]+/g, "-") |
| 865 | .replace(/^-|-$/g, ""), |
| 866 | ] |
| 867 | : parts; |
| 868 | const title = parts.slice(parts.length > 2 ? 2 : 1).join("-"); |
| 869 | return { |
| 870 | outputRelative: `${group.join("/")}.md`, |
| 871 | title: |
| 872 | parts.length > 2 ? group.join(".") : product ? `${parts[0]}.${product}` : parts.join("."), |
| 873 | resourceTitle: title, |
| 874 | link: `/providers/${group.join("/").toLowerCase()}#${title.toLowerCase()}`, |
| 875 | }; |
| 876 | } |
| 877 | |
| 878 | /** Keep example headings below their resource, with resource-scoped slugs. */ |
| 879 | function nestResourceHeadings(markdown: string, resource: string): string { |
| 880 | let fence: string | undefined; |
| 881 | return markdown |
| 882 | .split("\n") |
| 883 | .map((line) => { |
| 884 | const marker = line.match(/^\s{0,3}(`{3,}|~{3,})/); |
| 885 | if (marker) { |
| 886 | if (!fence) fence = marker[1]; |
| 887 | else if (marker[1][0] === fence[0] && marker[1].length >= fence.length) fence = undefined; |
| 888 | return line; |
| 889 | } |
| 890 | if (fence) return line; |
| 891 | return line.replace( |
| 892 | /^(#{1,6})\s+(.+)$/, |
| 893 | (_, hashes: string, title: string) => |
| 894 | `${"#".repeat(Math.min(6, Math.max(3, hashes.length + 1)))} ${resource}: ${title}`, |
| 895 | ); |
| 896 | }) |
| 897 | .join("\n"); |
| 898 | } |
| 899 | |
| 900 | /** Providers shown first in the sidebar; the rest follow alphabetically. */ |
| 901 | const PROVIDER_ORDER = ["AWS", "Cloudflare"]; |
| 902 | |
| 903 | interface SidebarLeaf { |
| 904 | label: string; |
| 905 | link: string; |
| 906 | } |
| 907 | interface SidebarGroup { |
| 908 | label: string; |
| 909 | collapsed: true; |
| 910 | items: SidebarItem[]; |
| 911 | } |
| 912 | type SidebarItem = SidebarLeaf | SidebarGroup; |
| 913 | |
| 914 | interface PageEntry { |
| 915 | provider: string; |
| 916 | service: string; |
| 917 | resource: string; |
| 918 | category: string; |
| 919 | product: string; |
| 920 | link: string; |
| 921 | /** Source directory relative to srcRoot (slash-normalized), e.g. `Cloudflare/KV`. */ |
| 922 | dir: string; |
| 923 | /** All names the page's source file exports — `{@link}` targets documented on this page. */ |
| 924 | exports: string[]; |
| 925 | } |
| 926 | |
| 927 | const byLabel = (a: { label: string }, b: { label: string }) => a.label.localeCompare(b.label); |
| 928 | |
| 929 | function orderedKeys(keys: string[], order: string[]): string[] { |
| 930 | const ranked = keys.filter((k) => order.includes(k)); |
| 931 | ranked.sort((a, b) => order.indexOf(a) - order.indexOf(b)); |
| 932 | const rest = keys.filter((k) => !order.includes(k)).sort(); |
| 933 | return [...ranked, ...rest]; |
| 934 | } |
| 935 | |
| 936 | /** The sidebar lists documents; resource anchors live in the page's TOC. */ |
| 937 | function buildServiceItems(pages: PageEntry[]): SidebarItem[] { |
| 938 | return pages |
| 939 | .map((page) => ({ label: page.product || page.service || page.resource, link: page.link })) |
| 940 | .sort(byLabel); |
| 941 | } |
| 942 | |
| 943 | function buildProvidersSidebar(entries: PageEntry[]): SidebarItem[] { |
| 944 | const byProvider = new Map<string, PageEntry[]>(); |
| 945 | for (const e of entries) { |
| 946 | if (!byProvider.has(e.provider)) byProvider.set(e.provider, []); |
| 947 | byProvider.get(e.provider)!.push(e); |
| 948 | } |
| 949 | |
| 950 | const providers: SidebarGroup[] = []; |
| 951 | for (const provider of orderedKeys([...byProvider.keys()], PROVIDER_ORDER)) { |
| 952 | const byPage = new Map<string, PageEntry[]>(); |
| 953 | for (const entry of byProvider.get(provider)!) { |
| 954 | const link = entry.link.split("#")[0]; |
| 955 | if (!byPage.has(link)) byPage.set(link, []); |
| 956 | byPage.get(link)!.push(entry); |
| 957 | } |
| 958 | const pages = [...byPage].map(([link, resources]) => ({ |
| 959 | ...resources[0], |
| 960 | link, |
| 961 | product: resources.every((resource) => resource.product === resources[0].product) |
| 962 | ? resources[0].product |
| 963 | : "", |
| 964 | })); |
| 965 | |
| 966 | const items = buildServiceItems(pages); |
| 967 | |
| 968 | providers.push({ label: provider, collapsed: true, items }); |
| 969 | } |
| 970 | |
| 971 | assertNoDuplicateSiblings(providers, []); |
| 972 | return providers; |
| 973 | } |
| 974 | |
| 975 | /** |
| 976 | * Duplicate sibling labels are always a tagging bug (e.g. two products |
| 977 | * resolving to the same name in one category) and render as confusing |
| 978 | * twin sections — fail the generation instead of shipping them. |
| 979 | */ |
| 980 | function assertNoDuplicateSiblings(items: SidebarItem[], path: string[]) { |
| 981 | const seen = new Map<string, number>(); |
| 982 | for (const item of items) { |
| 983 | seen.set(item.label, (seen.get(item.label) ?? 0) + 1); |
| 984 | } |
| 985 | const dups = [...seen.entries()].filter(([, n]) => n > 1); |
| 986 | if (dups.length > 0) { |
| 987 | throw new Error( |
| 988 | `Duplicate sidebar sibling label(s) under "${path.join(" > ") || "(root)"}": ${dups |
| 989 | .map(([label, n]) => `"${label}" ×${n}`) |
| 990 | .join(", ")} — fix the @product/@category tags on the offending files.`, |
| 991 | ); |
| 992 | } |
| 993 | for (const item of items) { |
| 994 | if ("items" in item) { |
| 995 | assertNoDuplicateSiblings(item.items, [...path, item.label]); |
| 996 | } |
| 997 | } |
| 998 | } |
| 999 | |
| 1000 | /** |
| 1001 | * Writes `content` only when it differs from what's on disk, so a dev server |
| 1002 | * watching the output reloads just the pages that changed. |
| 1003 | */ |
| 1004 | const writeIfChanged = Effect.fn(function* (file: string, content: string) { |
| 1005 | const fs = yield* FileSystem.FileSystem; |
| 1006 | const path = yield* Path.Path; |
| 1007 | const current = yield* fs |
| 1008 | .readFileString(file) |
| 1009 | .pipe(Effect.orElseSucceed((): string | undefined => undefined)); |
| 1010 | if (current === content) return false; |
| 1011 | yield* fs.makeDirectory(path.dirname(file), { recursive: true }); |
| 1012 | yield* fs.writeFileString(file, content); |
| 1013 | return true; |
| 1014 | }); |
| 1015 | |
| 1016 | /** Deletes files under `dir` not in `keep`, then any directories left empty. */ |
| 1017 | const pruneOutput = ( |
| 1018 | dir: string, |
| 1019 | keep: Set<string>, |
| 1020 | ): Effect.Effect<void, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path> => |
| 1021 | Effect.gen(function* () { |
| 1022 | const fs = yield* FileSystem.FileSystem; |
| 1023 | const path = yield* Path.Path; |
| 1024 | const entries = yield* fs.readDirectory(dir).pipe(Effect.orElseSucceed((): string[] => [])); |
| 1025 | for (const name of entries) { |
| 1026 | const full = path.join(dir, name); |
| 1027 | const info = yield* fs.stat(full); |
| 1028 | if (info.type === "Directory") { |
| 1029 | yield* pruneOutput(full, keep); |
| 1030 | const left = yield* fs.readDirectory(full).pipe(Effect.orElseSucceed((): string[] => [])); |
| 1031 | if (left.length === 0) yield* fs.remove(full, { recursive: true }).pipe(Effect.ignore); |
| 1032 | } else if (!keep.has(full)) { |
| 1033 | yield* fs.remove(full, { force: true }); |
| 1034 | } |
| 1035 | } |
| 1036 | }); |
| 1037 | |
| 1038 | class DuplicateReferenceAnchor extends Data.TaggedError("DuplicateReferenceAnchor")<{ |
| 1039 | readonly message: string; |
| 1040 | }> {} |
| 1041 | |
| 1042 | const command = Command.make( |
| 1043 | "generate-api-reference", |
| 1044 | { |
| 1045 | copyMarkers: Flag.Boolean("copy-markers").pipe( |
| 1046 | Flag.withDefault(false), |
| 1047 | Flag.withDescription( |
| 1048 | "Emit copy-editor markers for the website's dev server (also API_REFERENCE_COPY_MARKERS=1)", |
| 1049 | ), |
| 1050 | ), |
| 1051 | }, |
| 1052 | Effect.fn(function* (flags) { |
| 1053 | const path = yield* Path.Path; |
| 1054 | const fs = yield* FileSystem.FileSystem; |
| 1055 | const repoRoot = path.resolve(import.meta.dirname, ".."); |
| 1056 | const websiteRoot = path.join(repoRoot, "website"); |
| 1057 | const envCopyMarkers = yield* Config.String("API_REFERENCE_COPY_MARKERS").pipe( |
| 1058 | Config.withDefault(""), |
| 1059 | ); |
| 1060 | const config = { |
| 1061 | outRoot: path.join(websiteRoot, "src/content/docs/providers"), |
| 1062 | /** |
| 1063 | * Emit `<!--copy:jsdoc:...-->` markers after each prose block so the |
| 1064 | * website's dev-time copy editor can map rendered text back to the JSDoc |
| 1065 | * it came from. Dev only — production builds never set this. |
| 1066 | */ |
| 1067 | copyMarkers: envCopyMarkers === "1" || flags.copyMarkers, |
| 1068 | }; |
| 1069 | |
| 1070 | yield* fs.makeDirectory(config.outRoot, { recursive: true }); |
| 1071 | const outputs = new Set<string>(); |
| 1072 | |
| 1073 | const seen = new Map<string, string>(); |
| 1074 | const pageEntries: PageEntry[] = []; |
| 1075 | const pending: { outputRelative: string; product: string; doc: PageDoc }[] = []; |
| 1076 | let written = 0; |
| 1077 | const redirects: Record<string, string> = {}; |
| 1078 | const anchors = new Set<string>(); |
| 1079 | let skipped = 0; |
| 1080 | |
| 1081 | for (const root of sourceRoots) { |
| 1082 | const entries = yield* discoverFiles(repoRoot, root); |
| 1083 | yield* Console.log(`Discovered ${entries.length} source files in ${root.srcRoot}.`); |
| 1084 | |
| 1085 | yield* Effect.scoped( |
| 1086 | Effect.gen(function* () { |
| 1087 | const syntax = yield* createSyntaxProject(entries.map((entry) => entry.absolutePath)); |
| 1088 | |
| 1089 | for (const entry of entries) { |
| 1090 | const sourceFile = yield* syntax.getSourceFile(entry.absolutePath); |
| 1091 | |
| 1092 | const primary = findTaggedPrimary( |
| 1093 | sourceFile, |
| 1094 | config.copyMarkers |
| 1095 | ? { |
| 1096 | file: normalizeSlashes(path.relative(repoRoot, entry.absolutePath)), |
| 1097 | text: sourceFile.text, |
| 1098 | } |
| 1099 | : undefined, |
| 1100 | ); |
| 1101 | if (!primary) { |
| 1102 | skipped++; |
| 1103 | continue; |
| 1104 | } |
| 1105 | |
| 1106 | // Only emit a page when there's actual documented content; a bare |
| 1107 | // frontmatter + source link stub is noise. |
| 1108 | if (!primary.doc.summary && primary.doc.sections.length === 0) { |
| 1109 | skipped++; |
| 1110 | continue; |
| 1111 | } |
| 1112 | |
| 1113 | // Mirror the source directory structure; name the page after the |
| 1114 | // tagged declaration (e.g. Cloudflare.AI.Search/AiSearchInstance.md). |
| 1115 | const relDir = path.dirname(entry.relativePath); |
| 1116 | const outputRelative = path.join(relDir, `${primary.name}.md`); |
| 1117 | |
| 1118 | const existing = seen.get(outputRelative); |
| 1119 | if (existing) { |
| 1120 | yield* Console.warn( |
| 1121 | ` collision: ${outputRelative} from ${entry.relativePath} (already from ${existing})`, |
| 1122 | ); |
| 1123 | } |
| 1124 | seen.set(outputRelative, entry.relativePath); |
| 1125 | |
| 1126 | const doc: PageDoc = { |
| 1127 | title: primary.name, |
| 1128 | sourceDisplay: entry.sourceDisplay, |
| 1129 | summary: primary.doc.summary, |
| 1130 | sections: primary.doc.sections, |
| 1131 | isLayer: primary.doc.hasLayerTag, |
| 1132 | provides: primary.doc.provides, |
| 1133 | peers: primary.doc.peers, |
| 1134 | }; |
| 1135 | pending.push({ outputRelative, product: primary.product, doc }); |
| 1136 | |
| 1137 | const exportNames = exportedNames(sourceFile); |
| 1138 | |
| 1139 | const segments = normalizeSlashes(outputRelative).split("/"); |
| 1140 | const location = referenceLocation(outputRelative, primary.product); |
| 1141 | const oldLink = `/providers/${normalizeSlashes(outputRelative).replace(/\.md$/, "").toLowerCase()}`; |
| 1142 | if (anchors.has(location.link)) { |
| 1143 | return yield* new DuplicateReferenceAnchor({ |
| 1144 | message: `Duplicate reference anchor: ${location.link}`, |
| 1145 | }); |
| 1146 | } |
| 1147 | anchors.add(location.link); |
| 1148 | // A resource whose page kept its old URL needs no redirect. |
| 1149 | if (oldLink !== location.link.split("#")[0]) redirects[oldLink] = location.link; |
| 1150 | pageEntries.push({ |
| 1151 | provider: segments[0] ?? "", |
| 1152 | service: segments.length > 2 ? segments[1] : "", |
| 1153 | resource: primary.name, |
| 1154 | category: primary.category, |
| 1155 | product: primary.product, |
| 1156 | link: location.link, |
| 1157 | dir: normalizeSlashes(relDir), |
| 1158 | exports: exportNames, |
| 1159 | }); |
| 1160 | } |
| 1161 | }), |
| 1162 | ); |
| 1163 | } |
| 1164 | |
| 1165 | // Second pass: render with `{@link}` resolution — the full page set must be |
| 1166 | // known before symbol targets can resolve to their pages. |
| 1167 | const resolverFor = makeLinkResolverFactory(pageEntries); |
| 1168 | const groups = new Map<string, { title: string; sections: string[] }>(); |
| 1169 | for (const page of pending) { |
| 1170 | const location = referenceLocation(page.outputRelative, page.product); |
| 1171 | const resolve = resolverFor(normalizeSlashes(path.dirname(page.outputRelative))); |
| 1172 | const group = groups.get(location.outputRelative) ?? { title: location.title, sections: [] }; |
| 1173 | group.sections.push( |
| 1174 | `## ${location.resourceTitle}\n\n${nestResourceHeadings(renderResource(page.doc, resolve), location.resourceTitle)}`, |
| 1175 | ); |
| 1176 | groups.set(location.outputRelative, group); |
| 1177 | } |
| 1178 | for (const [relative, group] of groups) { |
| 1179 | const outputPath = path.join(config.outRoot, relative); |
| 1180 | outputs.add(outputPath); |
| 1181 | if ( |
| 1182 | yield* writeIfChanged( |
| 1183 | outputPath, |
| 1184 | `${renderReferenceFrontmatter(group.title)}\n\n${group.sections.join("\n\n")}\n`, |
| 1185 | ) |
| 1186 | ) { |
| 1187 | written++; |
| 1188 | } |
| 1189 | } |
| 1190 | |
| 1191 | const sidebar = buildProvidersSidebar(pageEntries); |
| 1192 | |
| 1193 | // Landing page for the Reference tab (/providers): a provider directory. |
| 1194 | // Each provider's reference belongs to its docs hub — the directory just |
| 1195 | // routes there (or into the tree, for providers without a hub). The |
| 1196 | // ProviderDirectory component reads the generated sidebar for counts. |
| 1197 | // Regenerated with the rest of the tree on every run. |
| 1198 | const referenceIndex = [ |
| 1199 | "---", |
| 1200 | "title: API Reference", |
| 1201 | "description: Every provider alchemy can manage — pick a provider to open its docs hub and resource reference.", |
| 1202 | "---", |
| 1203 | "", |
| 1204 | 'import ProviderDirectory from "../../../components/ProviderDirectory.astro";', |
| 1205 | "", |
| 1206 | "Every resource alchemy can manage, documented from the source JSDoc and", |
| 1207 | "organized by provider. A provider's reference lives in its docs hub —", |
| 1208 | "pick one below, or search with `⌘K`.", |
| 1209 | "", |
| 1210 | "<ProviderDirectory />", |
| 1211 | "", |
| 1212 | ].join("\n"); |
| 1213 | const indexPath = path.join(config.outRoot, "index.mdx"); |
| 1214 | outputs.add(indexPath); |
| 1215 | yield* writeIfChanged(indexPath, referenceIndex); |
| 1216 | yield* pruneOutput(config.outRoot, outputs); |
| 1217 | |
| 1218 | const sidebarPath = path.join(websiteRoot, "src/generated/providers-sidebar.json"); |
| 1219 | yield* writeIfChanged( |
| 1220 | path.join(websiteRoot, "src/generated/reference-redirects.json"), |
| 1221 | `${JSON.stringify(redirects, null, 2)}\n`, |
| 1222 | ); |
| 1223 | // astro.config imports the sidebar, so rewriting it restarts a dev server. |
| 1224 | yield* writeIfChanged(sidebarPath, `${JSON.stringify(sidebar, null, 2)}\n`); |
| 1225 | |
| 1226 | yield* Console.log( |
| 1227 | `Done. Wrote ${written} changed reference pages containing ${pending.length} resources (skipped ${skipped} untagged${ |
| 1228 | config.copyMarkers ? ", with copy markers" : "" |
| 1229 | }) to ${normalizeSlashes(path.relative(repoRoot, config.outRoot))}.`, |
| 1230 | ); |
| 1231 | if (unresolvedLinkTargets.size > 0) { |
| 1232 | const list = [...unresolvedLinkTargets.entries()] |
| 1233 | .sort((a, b) => b[1] - a[1]) |
| 1234 | .map(([target, n]) => (n > 1 ? `${target} ×${n}` : target)) |
| 1235 | .join(", "); |
| 1236 | yield* Console.log(`{@link} targets without a page (rendered as inline code): ${list}`); |
| 1237 | } |
| 1238 | yield* Console.log( |
| 1239 | `Wrote provider sidebar to ${normalizeSlashes(path.relative(repoRoot, sidebarPath))}.`, |
| 1240 | ); |
| 1241 | }), |
| 1242 | ).pipe(Command.withDescription("Generate the provider API reference from source JSDoc")); |
| 1243 | |
| 1244 | Command.run(command, { version: "0.0.0" }).pipe( |
| 1245 | Effect.provide(NodeServices.layer), |
| 1246 | NodeRuntime.runMain, |
| 1247 | ); |