Skip to content
TypeScript
20.6 KB
Raw Blame
/**
 * Coordinates source parsing, validation, example checking, and Markdown generation.
 *
 * @since 0.6.0
 */

import * as NodePath from "@effect/platform-node/NodePath"
import chalk from "chalk"
import * as Array from "effect/Array"
import * as Effect from "effect/Effect"
import * as Fiber from "effect/Fiber"
import * as FileSystem from "effect/FileSystem"
import { pipe } from "effect/Function"
import * as Path from "effect/Path"
import * as ChildProcess from "effect/process/ChildProcess"
import * as CommandLine from "effect/process/CommandLine"
import * as Result from "effect/Result"
import * as Stream from "effect/Stream"
import * as String from "effect/String"
import * as Glob from "glob"
import * as Checker from "./Checker.ts"
import * as Configuration from "./Configuration.ts"
import * as Domain from "./Domain.ts"
import * as Parser from "./Parser.ts"
import * as Printer from "./Printer.ts"
/**
 * Find all files matching the specified `glob` pattern, optionally excluding
 * files matching the provided `exclude` patterns.
 */
const glob = (pattern: string, exclude: ReadonlyArray<string> = []) =>
  Effect.tryPromise(() =>
    Glob.glob(pattern, {
      ignore: exclude.slice(),
      withFileTypes: false
    })
  ).pipe(
    Effect.mapError(() =>
      new Domain.DocgenError({
        message: `[Core.glob] Unable to execute glob pattern '${pattern}' ` +
          `excluding files matching '${exclude}'`
      })
    ),
    Effect.orDie
  )

/** @internal */
export const runCommand = Effect.fnUntraced(function*(
  executable: string,
  args: ReadonlyArray<string>,
  shell: boolean
) {
  // Windows runs `.cmd` shims only through a shell, which takes one script.
  const handle = yield* (shell
    ? ChildProcess.make(Result.getOrThrow(CommandLine.join([executable, ...args], { format: "windows" })), {
      shell
    })
    : ChildProcess.make(executable, args))
  const [stdout, stderr, exitCode] = yield* Effect.all([
    Stream.mkString(Stream.decodeText(handle.stdout)),
    Stream.mkString(Stream.decodeText(handle.stderr)),
    handle.exitCode
  ], { concurrency: "unbounded" })
  return { stdout, stderr, exitCode } as const
})

/**
 * Reads all TypeScript files in the source directory and returns an array of file objects.
 * Each file object contains the file path and its content.
 */
const readSourceFiles = Effect.gen(function*() {
  const config = yield* Configuration.Configuration
  const fs = yield* FileSystem.FileSystem
  const path = yield* Path.Path.pipe(Effect.provide(NodePath.layerPosix))
  const pattern = path.normalize(path.join(config.srcDir, "**", "*.ts"))
  const paths = yield* glob(pattern, config.exclude)
  yield* Effect.logInfo(chalk.bold(`${paths.length} module(s) found`))
  return yield* Effect.forEach(paths, (path) =>
    Effect.map(
      fs.readFileString(path),
      (content) => new Domain.File(path, content, false)
    ), { concurrency: "unbounded" })
})

/**
 * Writes a file to the `config.outDir` directory, taking into account the configuration and existing files.
 */
const writeFileToOutDir = Effect.fnUntraced(function*(file: Domain.File) {
  const config = yield* Configuration.Configuration
  const fs = yield* FileSystem.FileSystem
  const path = yield* Path.Path
  const process = yield* Domain.Process
  const cwd = yield* process.cwd
  const fileName = path.relative(path.join(cwd, config.outDir), file.path)

  const exists = yield* fs.exists(file.path)
  if (exists) {
    if (file.isOverwriteable) {
      yield* Effect.logDebug(`Overwriting file ${chalk.black(fileName)}...`)
      yield* fs.makeDirectory(path.dirname(file.path), { recursive: true })
      yield* fs.writeFileString(file.path, file.content)
    } else {
      yield* Effect.logDebug(
        `File ${chalk.black(fileName)} already exists, skipping creation.`
      )
    }
  } else {
    yield* fs.makeDirectory(path.dirname(file.path), { recursive: true })
    yield* fs.writeFileString(file.path, file.content)
  }
})

const writeFilesToOutDir = (
  files: ReadonlyArray<Domain.File>
) => Effect.forEach(files, writeFileToOutDir, { discard: true })

const parseModules = (files: ReadonlyArray<Domain.File>) =>
  Parser.parseFiles(files).pipe(
    Effect.mapError((errors) =>
      new Domain.DocgenError({
        message: "[Core.parseModules] The following error(s) occurred while " +
          `parsing the TypeScript source files:\n${errors.map((errors) => errors.join("\n")).join("\n")}`
      })
    )
  )

/**
 * Runs the example files for the given modules, type-checking them before execution.
 */
const typeCheckAndRunExamples = Effect.fnUntraced(function*(modules: ReadonlyArray<Domain.Module>) {
  const config = yield* Configuration.Configuration
  yield* cleanupExamples
  const files = yield* getExampleFiles(modules)
  const len = files.length
  if (len > 0) {
    yield* Effect.logInfo(`${len} example(s) found`)
    yield* writeExamplesToOutDir(files)
    yield* createExamplesTsConfigJson
    yield* Effect.logInfo("Typechecking examples...")
    yield* runTscOnExamples
    if (config.runExamples) {
      yield* Effect.logInfo("Running examples...")
      yield* runTsxOnExamples
    } else {
      yield* Effect.logInfo(chalk.gray("Skipping running examples"))
    }
  } else {
    yield* Effect.logInfo("No examples found.")
  }
  yield* cleanupExamples
})

/**
 * Joins an array of strings with a "-" after dropping all empty strings.
 */
const filterJoin = (self: Array<string>) =>
  pipe(
    self,
    Array.filter(String.isNonEmpty),
    Array.join("-")
  )

/**
 * Extracts deeply nested namespaces with their corresponding namespace prefix
 * from a given namespace.
 */
const extractPrefixedNestedNamespaces = (
  doc: Domain.Namespace,
  prefix: string
): ReadonlyArray<[string, Domain.Namespace]> => {
  const newPrefix = String.isEmpty(prefix) ? doc.name : `${prefix}-${doc.name}`
  const namespaces = Array.flatMap(
    doc.namespaces,
    (namespace) => extractPrefixedNestedNamespaces(namespace, newPrefix)
  )
  return Array.prepend(namespaces, [prefix, doc])
}

/**
 * Fence metadata that excludes an example from docgen type checking.
 *
 * @category constants
 * @since 0.6.0
 */
export const SKIP_TYPE_CHECKING_FENCE_METADATA = "skip-type-checking"

/**
 * Extracts all fenced code blocks from markdown content.
 * Handles both ``` and ~~~ fences, including any metadata like language, title, and other attributes.
 *
 * @internal
 */
export const extractFencedCode = (content: string): [examples: Array<string>, warnings: Array<string>] => {
  // The regex now captures the closing fence (group 3) if present.
  // If there's no closing fence, group 3 will be undefined.
  const fenceRegex = /(?:```|~~~)(.*?)\n([\s\S]*?)(?:(```|~~~)|$)/g
  const matches = Array.fromIterable(content.matchAll(fenceRegex))

  const warnings: Array<string> = []

  // Log a warning if a code fence is not properly closed.
  for (const match of matches) {
    if (match[3] === undefined) {
      warnings.push(`Code block does not have a matching closing fence:\n${content}`)
    }
  }

  return [
    matches
      .filter((match) => {
        const meta = match[1].toLocaleLowerCase()
        const isTypeScript = meta.startsWith("ts") || meta.startsWith("typescript")
        const isSkipTypeChecking = meta.includes(SKIP_TYPE_CHECKING_FENCE_METADATA)
        return isTypeScript && !isSkipTypeChecking
      })
      .map((match) => match[2].trim()),
    warnings
  ]
}

/**
 * Generates example files for the given modules.
 */
const getExampleFiles = Effect.fnUntraced(function*(modules: ReadonlyArray<Domain.Module>) {
  const config = yield* Configuration.Configuration
  const path = yield* Path.Path
  let warnings: Array<string> = []
  // Flattened module paths can collide, so give every emitted example a unique prefix.
  let fileIndex = 0
  const files = Array.flatMap(modules, (module) => {
    const prefix = module.path.join("-")

    const getFiles =
      (exampleId: string) =>
      (namedDoc: { readonly name: string; readonly doc: Domain.Doc }): ReadonlyArray<Domain.File> => {
        let descriptionExamples: Array<string> = []
        if (namedDoc.doc.description !== undefined) {
          const [es, ws] = extractFencedCode(namedDoc.doc.description)
          warnings = warnings.concat(ws)
          descriptionExamples = es
        }
        let exampleTagExamples: Array<string> = []
        for (const example of namedDoc.doc.examples) {
          const [es, ws] = extractFencedCode(example)
          warnings = warnings.concat(ws)
          exampleTagExamples = exampleTagExamples.concat(es)
        }
        const examples = descriptionExamples.concat(exampleTagExamples)
        return Array.map(
          examples,
          (example, i) => {
            return new Domain.File(
              path.join(
                config.outDir,
                "examples",
                `${fileIndex++}-${prefix}-${exampleId}-${namedDoc.name}-${i}.ts`
              ),
              example,
              true // make the file overwritable
            )
          }
        )
      }

    const allPrefixedNamespaces = Array.flatMap(
      module.namespaces,
      (namespace) => extractPrefixedNestedNamespaces(namespace, "")
    )

    const moduleExamples = getFiles("module")(module)
    const classExamples = Array.flatMap(module.classes, (c) =>
      Array.flatten([
        getFiles("class")(c),
        Array.flatMap(c.properties, getFiles(`${c.name}-property`)),
        Array.flatMap(
          c.methods,
          getFiles(`${c.name}-method`)
        ),
        Array.flatMap(
          c.staticMethods,
          getFiles(`${c.name}-staticmethod`)
        )
      ]))
    const allPrefixedInterfaces = [
      ...module.interfaces.map((iface) => ["" as string, iface] as const),
      ...Array.flatMap(
        allPrefixedNamespaces,
        ([prefix, namespace]) =>
          namespace.interfaces.map((iface) => [filterJoin([prefix, namespace.name]), iface] as const)
      )
    ]
    const interfacesExamples = Array.flatMap(
      allPrefixedInterfaces,
      ([ns, doc]) => getFiles(filterJoin(["interface", ns]))(doc)
    )
    const allPrefixedTypeAliases = [
      ...module.typeAliases.map((typeAlias) => ["" as string, typeAlias] as const),
      ...Array.flatMap(
        allPrefixedNamespaces,
        ([prefix, namespace]) =>
          namespace.typeAliases.map((typeAlias) => [filterJoin([prefix, namespace.name]), typeAlias] as const)
      )
    ]
    const typeAliasesExamples = Array.flatMap(
      allPrefixedTypeAliases,
      ([ns, doc]) => getFiles(filterJoin(["typealias", ns]))(doc)
    )
    const constantsExamples = Array.flatMap(
      module.constants,
      getFiles("constant")
    )
    const functionsExamples = Array.flatMap(
      module.functions,
      getFiles("function")
    )
    const exportsExamples = Array.flatMap(
      module.exports,
      getFiles("export")
    )
    const namespacesExamples = Array.flatMap(
      allPrefixedNamespaces,
      ([ns, doc]) => getFiles(filterJoin(["namespace", ns]))(doc)
    )

    return Array.flatten([
      moduleExamples,
      classExamples,
      interfacesExamples,
      typeAliasesExamples,
      constantsExamples,
      functionsExamples,
      namespacesExamples,
      exportsExamples
    ])
  })

  if (warnings.length > 0) {
    yield* Effect.logWarning(warnings.join("\n"))
  }

  return files
})

/**
 * Generates an entry point file for the given examples.
 */
const getExamplesEntryPoint = Effect.fnUntraced(function*(examples: ReadonlyArray<Domain.File>) {
  const config = yield* Configuration.Configuration
  const path = yield* Path.Path
  const content = examples.map((example) => `import './${path.basename(example.path, ".ts")}'`)
    .join("\n")
  return new Domain.File(
    path.normalize(path.join(config.outDir, "examples", "index.ts")),
    `${content}\n`,
    true // make the file overwritable
  )
})

/**
 * Removes the "examples" directory from the output directory specified in the configuration.
 */
const cleanupExamples = Effect.gen(function*() {
  const fs = yield* FileSystem.FileSystem
  const config = yield* Configuration.Configuration
  const path = yield* Path.Path
  const examplesDir = path.join(config.outDir, "examples")
  const exists = yield* Effect.orDie(fs.exists(examplesDir))
  if (exists) {
    yield* fs.remove(examplesDir, { recursive: true })
  }
})

/**
 * Runs tsc on the examples directory.
 */
const runTscOnExamples = Effect.gen(function*() {
  const config = yield* Configuration.Configuration
  const process = yield* Domain.Process
  const cwd = yield* process.cwd
  const path = yield* Path.Path
  const platform = yield* process.platform

  const tsconfig = path.normalize(path.join(cwd, config.outDir, "examples", "tsconfig.json"))
  const options = ["--noEmit", "--project", tsconfig]
  yield* Effect.logDebug("Running tsc on examples...")
  const result = yield* runCommand(
    platform === "win32" ? `${config.tscExecutable}.cmd` : config.tscExecutable,
    options,
    platform === "win32"
  ).pipe(Effect.mapError((error) =>
    new Domain.DocgenError({
      message: `Something went wrong while running tsc on examples:\n\n${globalThis.String(error)}`
    })
  ))
  if (result.exitCode !== 0) {
    return yield* new Domain.DocgenError({
      message: `Something went wrong while running tsc on examples:\n\n${result.stdout}`
    })
  }
})

/**
 * Runs tsc on the examples directory.
 */
const runTsxOnExamples = Effect.gen(function*() {
  const config = yield* Configuration.Configuration
  const path = yield* Path.Path
  const process = yield* Domain.Process
  const cwd = yield* process.cwd
  const platform = yield* process.platform

  const examples = path.normalize(path.join(cwd, config.outDir, "examples"))
  const tsconfig = path.join(examples, "tsconfig.json")
  const index = path.join(examples, "index.ts")
  const options = ["--tsconfig", tsconfig, index]
  yield* Effect.logDebug("Running tsx on examples...")
  const result = yield* runCommand(
    platform === "win32" ? "tsx.cmd" : "tsx",
    options,
    platform === "win32"
  ).pipe(Effect.mapError((error) =>
    new Domain.DocgenError({
      message: `Something went wrong while running tsx on examples:\n\n${globalThis.String(error)}`
    })
  ))
  if (result.exitCode !== 0) {
    return yield* new Domain.DocgenError({
      message: `Something went wrong while running tsx on examples:\n\n${result.stderr}`
    })
  }
})

const writeExamplesToOutDir = Effect.fnUntraced(function*(examples: ReadonlyArray<Domain.File>) {
  yield* Effect.logDebug("Writing examples...")
  const entryPoint = yield* getExamplesEntryPoint(examples)
  const files = [entryPoint, ...examples]
  yield* writeFilesToOutDir(files)
})

const createExamplesTsConfigJson = Effect.gen(function*() {
  yield* Effect.logDebug("Writing examples tsconfig...")
  const config = yield* Configuration.Configuration
  const process = yield* Domain.Process
  const cwd = yield* process.cwd
  const path = yield* Path.Path
  yield* writeFileToOutDir(
    new Domain.File(
      path.join(cwd, config.outDir, "examples", "tsconfig.json"),
      JSON.stringify({ compilerOptions: config.examplesCompilerOptions }, null, 2),
      true // make the file overwritable
    )
  )
})

const getMarkdown = Effect.fnUntraced(function*(modules: ReadonlyArray<Domain.Module>) {
  const homepage = yield* getMarkdownHomepage
  const index = yield* getMarkdownIndex
  const yml = yield* getMarkdownConfigYML
  const moduleFiles = yield* getModuleMarkdownFiles(modules)
  return [homepage, index, yml, ...moduleFiles]
})

const getMarkdownHomepage = Effect.gen(function*() {
  const config = yield* Configuration.Configuration
  const process = yield* Domain.Process
  const cwd = yield* process.cwd
  const path = yield* Path.Path
  return new Domain.File(
    path.join(cwd, config.outDir, "index.md"),
    String.stripMargin(
      `|---
       |title: Home
       |nav_order: 1
       |---
       |`
    ),
    false
  )
})

const getMarkdownIndex = Effect.gen(function*() {
  const config = yield* Configuration.Configuration
  const process = yield* Domain.Process
  const cwd = yield* process.cwd
  const path = yield* Path.Path
  return new Domain.File(
    path.join(cwd, config.outDir, "modules", "index.md"),
    String.stripMargin(
      `|---
       |title: Modules
       |has_children: true
       |permalink: /docs/modules
       |nav_order: 2
       |---
       |`
    ),
    false
  )
})

const resolveConfigYML = Effect.fnUntraced(function*(content: string) {
  const config = yield* Configuration.Configuration
  return content
    .replace(/^remote_theme:.*$/m, `remote_theme: ${config.theme}`)
    .replace(
      /^search_enabled:.*$/m,
      `search_enabled: ${config.enableSearch}`
    ).replace(
      /^ {2}'\S* on GitHub':\n {4}- '.*'/m,
      `  '${config.projectName} on GitHub':\n    - '${config.projectHomepage}'`
    )
})

const getHomepageNavigationHeader = (config: Configuration.ConfigurationShape): string => {
  const isGitHub = config.projectHomepage.toLowerCase().includes("github")
  return isGitHub ? config.projectName + " on GitHub" : "Homepage"
}

const getMarkdownConfigYML = Effect.gen(function*() {
  const config = yield* Configuration.Configuration
  const process = yield* Domain.Process
  const fs = yield* FileSystem.FileSystem
  const cwd = yield* process.cwd
  const path = yield* Path.Path
  const configPath = path.join(cwd, config.outDir, "_config.yml")
  const exists = yield* fs.exists(configPath)
  if (exists) {
    const content = yield* fs.readFileString(configPath)
    const resolved = yield* resolveConfigYML(content)
    return new Domain.File(configPath, resolved, true)
  } else {
    return new Domain.File(
      configPath,
      String.stripMargin(
        `|remote_theme: ${config.theme}
         |
         |# Enable or disable the site search
         |search_enabled: ${config.enableSearch}
         |
         |# Aux links for the upper right navigation
         |aux_links:
         |'${getHomepageNavigationHeader(config)}':
         |  - '${config.projectHomepage}'`
      ),
      false
    )
  }
})

const getModuleMarkdownOutputPath = Effect.fnUntraced(function*(module: Domain.Module) {
  const config = yield* Configuration.Configuration
  const path = yield* Path.Path
  return path.normalize(path.join(
    config.outDir,
    "modules",
    `${path.relative(config.srcDir, module.path.join(path.sep))}.md`
  ))
})

/** @internal */
export const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
  Effect.forEach(modules, (module, i) =>
    Effect.gen(function*() {
      const outputPath = yield* getModuleMarkdownOutputPath(module)
      const moduleContent = yield* Printer.printModule(module)
      const tocgen = yield* Effect.promise(() => import("@effect/markdown-toc").then((module) => module.default)).pipe(
        Effect.orDie
      )
      const toc = tocgen(moduleContent, { bullets: "-" }).content
      const frontMatter = Printer.printFrontMatter(module, i + 1)
      const content = (frontMatter + "\n\n" + moduleContent).replace(
        "<!-- toc -->",
        `---
## Exports Grouped by Category
${toc}
---`
      )

      const prettified = yield* Printer.prettify(content)
      return new Domain.File(outputPath, prettified, true)
    }))

const writeMarkdown = Effect.fnUntraced(function*(files: ReadonlyArray<Domain.File>) {
  const config = yield* Configuration.Configuration
  const fileSystem = yield* FileSystem.FileSystem
  const path = yield* Path.Path.pipe(Effect.provide(NodePath.layerPosix))
  const pattern = path.normalize(path.join(config.outDir, "**/*.ts.md"))
  yield* Effect.logDebug(`Deleting ${chalk.black(pattern)}...`)
  const paths = yield* glob(pattern)
  yield* Effect.forEach(paths, (path) => fileSystem.remove(path, { recursive: true }), {
    concurrency: "unbounded"
  })
  return yield* writeFilesToOutDir(files)
})

/** @internal */
export const program = Effect.gen(function*() {
  yield* Effect.logInfo("Reading modules...")
  const sourceFiles = yield* readSourceFiles
  yield* Effect.logInfo("Parsing modules...")
  const modules = yield* parseModules(sourceFiles)

  const checkFiber = yield* Effect.gen(function*() {
    yield* Effect.logInfo("Checking modules...")
    const errors = yield* Checker.checkModules(modules)
    if (errors.length > 0) {
      return yield* Effect.fail(
        new Domain.DocgenError({
          message: `The following errors occurred while checking the modules:\n\n${errors.join("\n\n")}`
        })
      )
    }
    yield* typeCheckAndRunExamples(modules)
  }).pipe(Effect.forkChild)

  const markdownFiber = yield* Effect.gen(function*() {
    yield* Effect.logInfo("Creating markdown files...")
    const outputFiles = yield* getMarkdown(modules)
    yield* Effect.logInfo("Writing markdown files...")
    yield* writeMarkdown(outputFiles)
  }).pipe(Effect.forkChild)

  yield* Fiber.joinAll([checkFiber, markdownFiber])

  yield* Effect.logInfo(chalk.bold.green("✓ Docs generation succeeded!"))
})