The best way to control Claude Code, Codex and more from any computer or phone

main
ts 625 lines 20.6 KB
Raw
1 /**
2 * Coordinates source parsing, validation, example checking, and Markdown generation.
3 *
4 * @since 0.6.0
5 */
6
7 import * as NodePath from "@effect/platform-node/NodePath"
8 import chalk from "chalk"
9 import * as Array from "effect/Array"
10 import * as Effect from "effect/Effect"
11 import * as Fiber from "effect/Fiber"
12 import * as FileSystem from "effect/FileSystem"
13 import { pipe } from "effect/Function"
14 import * as Path from "effect/Path"
15 import * as ChildProcess from "effect/process/ChildProcess"
16 import * as CommandLine from "effect/process/CommandLine"
17 import * as Result from "effect/Result"
18 import * as Stream from "effect/Stream"
19 import * as String from "effect/String"
20 import * as Glob from "glob"
21 import * as Checker from "./Checker.ts"
22 import * as Configuration from "./Configuration.ts"
23 import * as Domain from "./Domain.ts"
24 import * as Parser from "./Parser.ts"
25 import * as Printer from "./Printer.ts"
26 /**
27 * Find all files matching the specified `glob` pattern, optionally excluding
28 * files matching the provided `exclude` patterns.
29 */
30 const glob = (pattern: string, exclude: ReadonlyArray<string> = []) =>
31 Effect.tryPromise(() =>
32 Glob.glob(pattern, {
33 ignore: exclude.slice(),
34 withFileTypes: false
35 })
36 ).pipe(
37 Effect.mapError(() =>
38 new Domain.DocgenError({
39 message: `[Core.glob] Unable to execute glob pattern '${pattern}' ` +
40 `excluding files matching '${exclude}'`
41 })
42 ),
43 Effect.orDie
44 )
45
46 /** @internal */
47 export const runCommand = Effect.fnUntraced(function*(
48 executable: string,
49 args: ReadonlyArray<string>,
50 shell: boolean
51 ) {
52 // Windows runs `.cmd` shims only through a shell, which takes one script.
53 const handle = yield* (shell
54 ? ChildProcess.make(Result.getOrThrow(CommandLine.join([executable, ...args], { format: "windows" })), {
55 shell
56 })
57 : ChildProcess.make(executable, args))
58 const [stdout, stderr, exitCode] = yield* Effect.all([
59 Stream.mkString(Stream.decodeText(handle.stdout)),
60 Stream.mkString(Stream.decodeText(handle.stderr)),
61 handle.exitCode
62 ], { concurrency: "unbounded" })
63 return { stdout, stderr, exitCode } as const
64 })
65
66 /**
67 * Reads all TypeScript files in the source directory and returns an array of file objects.
68 * Each file object contains the file path and its content.
69 */
70 const readSourceFiles = Effect.gen(function*() {
71 const config = yield* Configuration.Configuration
72 const fs = yield* FileSystem.FileSystem
73 const path = yield* Path.Path.pipe(Effect.provide(NodePath.layerPosix))
74 const pattern = path.normalize(path.join(config.srcDir, "**", "*.ts"))
75 const paths = yield* glob(pattern, config.exclude)
76 yield* Effect.logInfo(chalk.bold(`${paths.length} module(s) found`))
77 return yield* Effect.forEach(paths, (path) =>
78 Effect.map(
79 fs.readFileString(path),
80 (content) => new Domain.File(path, content, false)
81 ), { concurrency: "unbounded" })
82 })
83
84 /**
85 * Writes a file to the `config.outDir` directory, taking into account the configuration and existing files.
86 */
87 const writeFileToOutDir = Effect.fnUntraced(function*(file: Domain.File) {
88 const config = yield* Configuration.Configuration
89 const fs = yield* FileSystem.FileSystem
90 const path = yield* Path.Path
91 const process = yield* Domain.Process
92 const cwd = yield* process.cwd
93 const fileName = path.relative(path.join(cwd, config.outDir), file.path)
94
95 const exists = yield* fs.exists(file.path)
96 if (exists) {
97 if (file.isOverwriteable) {
98 yield* Effect.logDebug(`Overwriting file ${chalk.black(fileName)}...`)
99 yield* fs.makeDirectory(path.dirname(file.path), { recursive: true })
100 yield* fs.writeFileString(file.path, file.content)
101 } else {
102 yield* Effect.logDebug(
103 `File ${chalk.black(fileName)} already exists, skipping creation.`
104 )
105 }
106 } else {
107 yield* fs.makeDirectory(path.dirname(file.path), { recursive: true })
108 yield* fs.writeFileString(file.path, file.content)
109 }
110 })
111
112 const writeFilesToOutDir = (
113 files: ReadonlyArray<Domain.File>
114 ) => Effect.forEach(files, writeFileToOutDir, { discard: true })
115
116 const parseModules = (files: ReadonlyArray<Domain.File>) =>
117 Parser.parseFiles(files).pipe(
118 Effect.mapError((errors) =>
119 new Domain.DocgenError({
120 message: "[Core.parseModules] The following error(s) occurred while " +
121 `parsing the TypeScript source files:\n${errors.map((errors) => errors.join("\n")).join("\n")}`
122 })
123 )
124 )
125
126 /**
127 * Runs the example files for the given modules, type-checking them before execution.
128 */
129 const typeCheckAndRunExamples = Effect.fnUntraced(function*(modules: ReadonlyArray<Domain.Module>) {
130 const config = yield* Configuration.Configuration
131 yield* cleanupExamples
132 const files = yield* getExampleFiles(modules)
133 const len = files.length
134 if (len > 0) {
135 yield* Effect.logInfo(`${len} example(s) found`)
136 yield* writeExamplesToOutDir(files)
137 yield* createExamplesTsConfigJson
138 yield* Effect.logInfo("Typechecking examples...")
139 yield* runTscOnExamples
140 if (config.runExamples) {
141 yield* Effect.logInfo("Running examples...")
142 yield* runTsxOnExamples
143 } else {
144 yield* Effect.logInfo(chalk.gray("Skipping running examples"))
145 }
146 } else {
147 yield* Effect.logInfo("No examples found.")
148 }
149 yield* cleanupExamples
150 })
151
152 /**
153 * Joins an array of strings with a "-" after dropping all empty strings.
154 */
155 const filterJoin = (self: Array<string>) =>
156 pipe(
157 self,
158 Array.filter(String.isNonEmpty),
159 Array.join("-")
160 )
161
162 /**
163 * Extracts deeply nested namespaces with their corresponding namespace prefix
164 * from a given namespace.
165 */
166 const extractPrefixedNestedNamespaces = (
167 doc: Domain.Namespace,
168 prefix: string
169 ): ReadonlyArray<[string, Domain.Namespace]> => {
170 const newPrefix = String.isEmpty(prefix) ? doc.name : `${prefix}-${doc.name}`
171 const namespaces = Array.flatMap(
172 doc.namespaces,
173 (namespace) => extractPrefixedNestedNamespaces(namespace, newPrefix)
174 )
175 return Array.prepend(namespaces, [prefix, doc])
176 }
177
178 /**
179 * Fence metadata that excludes an example from docgen type checking.
180 *
181 * @category constants
182 * @since 0.6.0
183 */
184 export const SKIP_TYPE_CHECKING_FENCE_METADATA = "skip-type-checking"
185
186 /**
187 * Extracts all fenced code blocks from markdown content.
188 * Handles both ``` and ~~~ fences, including any metadata like language, title, and other attributes.
189 *
190 * @internal
191 */
192 export const extractFencedCode = (content: string): [examples: Array<string>, warnings: Array<string>] => {
193 // The regex now captures the closing fence (group 3) if present.
194 // If there's no closing fence, group 3 will be undefined.
195 const fenceRegex = /(?:```|~~~)(.*?)\n([\s\S]*?)(?:(```|~~~)|$)/g
196 const matches = Array.fromIterable(content.matchAll(fenceRegex))
197
198 const warnings: Array<string> = []
199
200 // Log a warning if a code fence is not properly closed.
201 for (const match of matches) {
202 if (match[3] === undefined) {
203 warnings.push(`Code block does not have a matching closing fence:\n${content}`)
204 }
205 }
206
207 return [
208 matches
209 .filter((match) => {
210 const meta = match[1].toLocaleLowerCase()
211 const isTypeScript = meta.startsWith("ts") || meta.startsWith("typescript")
212 const isSkipTypeChecking = meta.includes(SKIP_TYPE_CHECKING_FENCE_METADATA)
213 return isTypeScript && !isSkipTypeChecking
214 })
215 .map((match) => match[2].trim()),
216 warnings
217 ]
218 }
219
220 /**
221 * Generates example files for the given modules.
222 */
223 const getExampleFiles = Effect.fnUntraced(function*(modules: ReadonlyArray<Domain.Module>) {
224 const config = yield* Configuration.Configuration
225 const path = yield* Path.Path
226 let warnings: Array<string> = []
227 // Flattened module paths can collide, so give every emitted example a unique prefix.
228 let fileIndex = 0
229 const files = Array.flatMap(modules, (module) => {
230 const prefix = module.path.join("-")
231
232 const getFiles =
233 (exampleId: string) =>
234 (namedDoc: { readonly name: string; readonly doc: Domain.Doc }): ReadonlyArray<Domain.File> => {
235 let descriptionExamples: Array<string> = []
236 if (namedDoc.doc.description !== undefined) {
237 const [es, ws] = extractFencedCode(namedDoc.doc.description)
238 warnings = warnings.concat(ws)
239 descriptionExamples = es
240 }
241 let exampleTagExamples: Array<string> = []
242 for (const example of namedDoc.doc.examples) {
243 const [es, ws] = extractFencedCode(example)
244 warnings = warnings.concat(ws)
245 exampleTagExamples = exampleTagExamples.concat(es)
246 }
247 const examples = descriptionExamples.concat(exampleTagExamples)
248 return Array.map(
249 examples,
250 (example, i) => {
251 return new Domain.File(
252 path.join(
253 config.outDir,
254 "examples",
255 `${fileIndex++}-${prefix}-${exampleId}-${namedDoc.name}-${i}.ts`
256 ),
257 example,
258 true // make the file overwritable
259 )
260 }
261 )
262 }
263
264 const allPrefixedNamespaces = Array.flatMap(
265 module.namespaces,
266 (namespace) => extractPrefixedNestedNamespaces(namespace, "")
267 )
268
269 const moduleExamples = getFiles("module")(module)
270 const classExamples = Array.flatMap(module.classes, (c) =>
271 Array.flatten([
272 getFiles("class")(c),
273 Array.flatMap(c.properties, getFiles(`${c.name}-property`)),
274 Array.flatMap(
275 c.methods,
276 getFiles(`${c.name}-method`)
277 ),
278 Array.flatMap(
279 c.staticMethods,
280 getFiles(`${c.name}-staticmethod`)
281 )
282 ]))
283 const allPrefixedInterfaces = [
284 ...module.interfaces.map((iface) => ["" as string, iface] as const),
285 ...Array.flatMap(
286 allPrefixedNamespaces,
287 ([prefix, namespace]) =>
288 namespace.interfaces.map((iface) => [filterJoin([prefix, namespace.name]), iface] as const)
289 )
290 ]
291 const interfacesExamples = Array.flatMap(
292 allPrefixedInterfaces,
293 ([ns, doc]) => getFiles(filterJoin(["interface", ns]))(doc)
294 )
295 const allPrefixedTypeAliases = [
296 ...module.typeAliases.map((typeAlias) => ["" as string, typeAlias] as const),
297 ...Array.flatMap(
298 allPrefixedNamespaces,
299 ([prefix, namespace]) =>
300 namespace.typeAliases.map((typeAlias) => [filterJoin([prefix, namespace.name]), typeAlias] as const)
301 )
302 ]
303 const typeAliasesExamples = Array.flatMap(
304 allPrefixedTypeAliases,
305 ([ns, doc]) => getFiles(filterJoin(["typealias", ns]))(doc)
306 )
307 const constantsExamples = Array.flatMap(
308 module.constants,
309 getFiles("constant")
310 )
311 const functionsExamples = Array.flatMap(
312 module.functions,
313 getFiles("function")
314 )
315 const exportsExamples = Array.flatMap(
316 module.exports,
317 getFiles("export")
318 )
319 const namespacesExamples = Array.flatMap(
320 allPrefixedNamespaces,
321 ([ns, doc]) => getFiles(filterJoin(["namespace", ns]))(doc)
322 )
323
324 return Array.flatten([
325 moduleExamples,
326 classExamples,
327 interfacesExamples,
328 typeAliasesExamples,
329 constantsExamples,
330 functionsExamples,
331 namespacesExamples,
332 exportsExamples
333 ])
334 })
335
336 if (warnings.length > 0) {
337 yield* Effect.logWarning(warnings.join("\n"))
338 }
339
340 return files
341 })
342
343 /**
344 * Generates an entry point file for the given examples.
345 */
346 const getExamplesEntryPoint = Effect.fnUntraced(function*(examples: ReadonlyArray<Domain.File>) {
347 const config = yield* Configuration.Configuration
348 const path = yield* Path.Path
349 const content = examples.map((example) => `import './${path.basename(example.path, ".ts")}'`)
350 .join("\n")
351 return new Domain.File(
352 path.normalize(path.join(config.outDir, "examples", "index.ts")),
353 `${content}\n`,
354 true // make the file overwritable
355 )
356 })
357
358 /**
359 * Removes the "examples" directory from the output directory specified in the configuration.
360 */
361 const cleanupExamples = Effect.gen(function*() {
362 const fs = yield* FileSystem.FileSystem
363 const config = yield* Configuration.Configuration
364 const path = yield* Path.Path
365 const examplesDir = path.join(config.outDir, "examples")
366 const exists = yield* Effect.orDie(fs.exists(examplesDir))
367 if (exists) {
368 yield* fs.remove(examplesDir, { recursive: true })
369 }
370 })
371
372 /**
373 * Runs tsc on the examples directory.
374 */
375 const runTscOnExamples = Effect.gen(function*() {
376 const config = yield* Configuration.Configuration
377 const process = yield* Domain.Process
378 const cwd = yield* process.cwd
379 const path = yield* Path.Path
380 const platform = yield* process.platform
381
382 const tsconfig = path.normalize(path.join(cwd, config.outDir, "examples", "tsconfig.json"))
383 const options = ["--noEmit", "--project", tsconfig]
384 yield* Effect.logDebug("Running tsc on examples...")
385 const result = yield* runCommand(
386 platform === "win32" ? `${config.tscExecutable}.cmd` : config.tscExecutable,
387 options,
388 platform === "win32"
389 ).pipe(Effect.mapError((error) =>
390 new Domain.DocgenError({
391 message: `Something went wrong while running tsc on examples:\n\n${globalThis.String(error)}`
392 })
393 ))
394 if (result.exitCode !== 0) {
395 return yield* new Domain.DocgenError({
396 message: `Something went wrong while running tsc on examples:\n\n${result.stdout}`
397 })
398 }
399 })
400
401 /**
402 * Runs tsc on the examples directory.
403 */
404 const runTsxOnExamples = Effect.gen(function*() {
405 const config = yield* Configuration.Configuration
406 const path = yield* Path.Path
407 const process = yield* Domain.Process
408 const cwd = yield* process.cwd
409 const platform = yield* process.platform
410
411 const examples = path.normalize(path.join(cwd, config.outDir, "examples"))
412 const tsconfig = path.join(examples, "tsconfig.json")
413 const index = path.join(examples, "index.ts")
414 const options = ["--tsconfig", tsconfig, index]
415 yield* Effect.logDebug("Running tsx on examples...")
416 const result = yield* runCommand(
417 platform === "win32" ? "tsx.cmd" : "tsx",
418 options,
419 platform === "win32"
420 ).pipe(Effect.mapError((error) =>
421 new Domain.DocgenError({
422 message: `Something went wrong while running tsx on examples:\n\n${globalThis.String(error)}`
423 })
424 ))
425 if (result.exitCode !== 0) {
426 return yield* new Domain.DocgenError({
427 message: `Something went wrong while running tsx on examples:\n\n${result.stderr}`
428 })
429 }
430 })
431
432 const writeExamplesToOutDir = Effect.fnUntraced(function*(examples: ReadonlyArray<Domain.File>) {
433 yield* Effect.logDebug("Writing examples...")
434 const entryPoint = yield* getExamplesEntryPoint(examples)
435 const files = [entryPoint, ...examples]
436 yield* writeFilesToOutDir(files)
437 })
438
439 const createExamplesTsConfigJson = Effect.gen(function*() {
440 yield* Effect.logDebug("Writing examples tsconfig...")
441 const config = yield* Configuration.Configuration
442 const process = yield* Domain.Process
443 const cwd = yield* process.cwd
444 const path = yield* Path.Path
445 yield* writeFileToOutDir(
446 new Domain.File(
447 path.join(cwd, config.outDir, "examples", "tsconfig.json"),
448 JSON.stringify({ compilerOptions: config.examplesCompilerOptions }, null, 2),
449 true // make the file overwritable
450 )
451 )
452 })
453
454 const getMarkdown = Effect.fnUntraced(function*(modules: ReadonlyArray<Domain.Module>) {
455 const homepage = yield* getMarkdownHomepage
456 const index = yield* getMarkdownIndex
457 const yml = yield* getMarkdownConfigYML
458 const moduleFiles = yield* getModuleMarkdownFiles(modules)
459 return [homepage, index, yml, ...moduleFiles]
460 })
461
462 const getMarkdownHomepage = Effect.gen(function*() {
463 const config = yield* Configuration.Configuration
464 const process = yield* Domain.Process
465 const cwd = yield* process.cwd
466 const path = yield* Path.Path
467 return new Domain.File(
468 path.join(cwd, config.outDir, "index.md"),
469 String.stripMargin(
470 `|---
471 |title: Home
472 |nav_order: 1
473 |---
474 |`
475 ),
476 false
477 )
478 })
479
480 const getMarkdownIndex = Effect.gen(function*() {
481 const config = yield* Configuration.Configuration
482 const process = yield* Domain.Process
483 const cwd = yield* process.cwd
484 const path = yield* Path.Path
485 return new Domain.File(
486 path.join(cwd, config.outDir, "modules", "index.md"),
487 String.stripMargin(
488 `|---
489 |title: Modules
490 |has_children: true
491 |permalink: /docs/modules
492 |nav_order: 2
493 |---
494 |`
495 ),
496 false
497 )
498 })
499
500 const resolveConfigYML = Effect.fnUntraced(function*(content: string) {
501 const config = yield* Configuration.Configuration
502 return content
503 .replace(/^remote_theme:.*$/m, `remote_theme: ${config.theme}`)
504 .replace(
505 /^search_enabled:.*$/m,
506 `search_enabled: ${config.enableSearch}`
507 ).replace(
508 /^ {2}'\S* on GitHub':\n {4}- '.*'/m,
509 ` '${config.projectName} on GitHub':\n - '${config.projectHomepage}'`
510 )
511 })
512
513 const getHomepageNavigationHeader = (config: Configuration.ConfigurationShape): string => {
514 const isGitHub = config.projectHomepage.toLowerCase().includes("github")
515 return isGitHub ? config.projectName + " on GitHub" : "Homepage"
516 }
517
518 const getMarkdownConfigYML = Effect.gen(function*() {
519 const config = yield* Configuration.Configuration
520 const process = yield* Domain.Process
521 const fs = yield* FileSystem.FileSystem
522 const cwd = yield* process.cwd
523 const path = yield* Path.Path
524 const configPath = path.join(cwd, config.outDir, "_config.yml")
525 const exists = yield* fs.exists(configPath)
526 if (exists) {
527 const content = yield* fs.readFileString(configPath)
528 const resolved = yield* resolveConfigYML(content)
529 return new Domain.File(configPath, resolved, true)
530 } else {
531 return new Domain.File(
532 configPath,
533 String.stripMargin(
534 `|remote_theme: ${config.theme}
535 |
536 |# Enable or disable the site search
537 |search_enabled: ${config.enableSearch}
538 |
539 |# Aux links for the upper right navigation
540 |aux_links:
541 |'${getHomepageNavigationHeader(config)}':
542 | - '${config.projectHomepage}'`
543 ),
544 false
545 )
546 }
547 })
548
549 const getModuleMarkdownOutputPath = Effect.fnUntraced(function*(module: Domain.Module) {
550 const config = yield* Configuration.Configuration
551 const path = yield* Path.Path
552 return path.normalize(path.join(
553 config.outDir,
554 "modules",
555 `${path.relative(config.srcDir, module.path.join(path.sep))}.md`
556 ))
557 })
558
559 /** @internal */
560 export const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
561 Effect.forEach(modules, (module, i) =>
562 Effect.gen(function*() {
563 const outputPath = yield* getModuleMarkdownOutputPath(module)
564 const moduleContent = yield* Printer.printModule(module)
565 const tocgen = yield* Effect.promise(() => import("@effect/markdown-toc").then((module) => module.default)).pipe(
566 Effect.orDie
567 )
568 const toc = tocgen(moduleContent, { bullets: "-" }).content
569 const frontMatter = Printer.printFrontMatter(module, i + 1)
570 const content = (frontMatter + "\n\n" + moduleContent).replace(
571 "<!-- toc -->",
572 `---
573 ## Exports Grouped by Category
574 ${toc}
575 ---`
576 )
577
578 const prettified = yield* Printer.prettify(content)
579 return new Domain.File(outputPath, prettified, true)
580 }))
581
582 const writeMarkdown = Effect.fnUntraced(function*(files: ReadonlyArray<Domain.File>) {
583 const config = yield* Configuration.Configuration
584 const fileSystem = yield* FileSystem.FileSystem
585 const path = yield* Path.Path.pipe(Effect.provide(NodePath.layerPosix))
586 const pattern = path.normalize(path.join(config.outDir, "**/*.ts.md"))
587 yield* Effect.logDebug(`Deleting ${chalk.black(pattern)}...`)
588 const paths = yield* glob(pattern)
589 yield* Effect.forEach(paths, (path) => fileSystem.remove(path, { recursive: true }), {
590 concurrency: "unbounded"
591 })
592 return yield* writeFilesToOutDir(files)
593 })
594
595 /** @internal */
596 export const program = Effect.gen(function*() {
597 yield* Effect.logInfo("Reading modules...")
598 const sourceFiles = yield* readSourceFiles
599 yield* Effect.logInfo("Parsing modules...")
600 const modules = yield* parseModules(sourceFiles)
601
602 const checkFiber = yield* Effect.gen(function*() {
603 yield* Effect.logInfo("Checking modules...")
604 const errors = yield* Checker.checkModules(modules)
605 if (errors.length > 0) {
606 return yield* Effect.fail(
607 new Domain.DocgenError({
608 message: `The following errors occurred while checking the modules:\n\n${errors.join("\n\n")}`
609 })
610 )
611 }
612 yield* typeCheckAndRunExamples(modules)
613 }).pipe(Effect.forkChild)
614
615 const markdownFiber = yield* Effect.gen(function*() {
616 yield* Effect.logInfo("Creating markdown files...")
617 const outputFiles = yield* getMarkdown(modules)
618 yield* Effect.logInfo("Writing markdown files...")
619 yield* writeMarkdown(outputFiles)
620 }).pipe(Effect.forkChild)
621
622 yield* Fiber.joinAll([checkFiber, markdownFiber])
623
624 yield* Effect.logInfo(chalk.bold.green("✓ Docs generation succeeded!"))
625 })