sailfork / t3code-github / .repos/ effect/ packages/ tools/ docgen/ src/ Printer.ts

/**
 * Renders parsed documentation models as Markdown.
 *
 * @since 0.6.0
 */
import * as Array from "effect/Array"
import * as Effect from "effect/Effect"
import { pipe } from "effect/Function"
import * as Order from "effect/Order"
import * as Record from "effect/Record"
import * as String from "effect/String"
import * as Prettier from "prettier"
import * as Configuration from "./Configuration.ts"
import type * as Domain from "./Domain.ts"
import * as Parser from "./Parser.ts"

/** @internal */
export type Printable =
  | Domain.Class
  | Domain.Constant
  | Domain.Export
  | Domain.Function
  | Domain.Interface
  | Domain.TypeAlias
  | Domain.Namespace

const Markdown = {
  bold: (content: string) => `**${content}**`,
  fence: (content: string) => `\`\`\`ts\n${content}\n\`\`\`\n\n`,
  strikethrough: (content: string) => `~~${content}~~`
}

/**
 * Replaces the link from a JSDoc link tag with a simple text.
 *
 * Given "This is a description containing two links to {@link foo} and {@link bar baz}."
 * returns "This is a description containing two links to `foo` and `baz`."
 */
function replaceJSDocLinks(text: string): string {
  return text.replace(/\{@link\s+([^\s}]+)(?:\s+([^}]+))?\}/g, (_, link, label) => {
    // Use the label if provided; otherwise, use the link target
    return `\`${(label || link).trim()}\``
  })
}

/**
 * Removes all extra metadata from fenced code blocks in a Markdown string.
 * For each code fence, only the first token (the language identifier) is preserved.
 */
function removeFenceMetadata(markdown: string): string {
  return markdown.replace(/^(`{3,})([^\n]*)/gm, (_match, fence, info) => {
    // Trim the info string and split by whitespace into tokens.
    // The first token (if present) is typically the language identifier.
    const tokens = info.trim().split(/\s+/)
    // Rebuild the fence line with just the language (if it exists)
    return fence + (tokens[0] || "")
  })
}

const printOptionalDescription = Effect.fnUntraced(function*(description: string | undefined) {
  if (description === undefined) {
    return ""
  }
  const config = yield* Configuration.Configuration
  const descriptionWithoutLinks = replaceJSDocLinks(description)
  const out = config.theme === Configuration.DEFAULT_THEME
    ? removeFenceMetadata(descriptionWithoutLinks)
    : descriptionWithoutLinks
  return `\n\n${out}`
})

const printArray = (title: string, ss?: ReadonlyArray<string>): string => {
  if (ss === undefined || ss.length === 0) {
    return ""
  }
  return `\n\n${Markdown.bold(title)}\n\n${ss.join("\n")}`
}

const printFence = (code: string): string => {
  if (code.startsWith("```ts") || code.startsWith("~~~ts")) {
    return code
  }
  return "```ts\n" + code + "\n```"
}

const printOptionalSignature = (signature?: string): string => {
  if (signature === undefined) {
    return ""
  }
  return `\n\n${Markdown.bold("Signature")}\n\n${printFence(signature)}`
}

const printThrowsArray = (throws?: ReadonlyArray<string>): string => printArray("Throws", throws)

const printExamplesArray = (examples: ReadonlyArray<string>): string => {
  if (examples.length === 0) {
    return ""
  }
  return examples.map((ex) => "\n\n**Example**\n\n" + printFence(ex)).join("")
}

const printOptionalSince = (since: ReadonlyArray<string>): string => {
  if (since.length === 0) {
    return ""
  }
  return `\n\nSince v${since.join(", ")}`
}

const printHeaderByIndentation = (indentation: number) => {
  switch (indentation) {
    case 0:
      return "## "
    case 1:
      return "### "
    default:
      return "#### "
  }
}

const printTitle = (s: string, deprecated: ReadonlyArray<string>, postfix?: string): string => {
  const name = s.trim() === "hasOwnProperty" ? `${s} (function)` : s
  const title = deprecated.length > 0 ? Markdown.strikethrough(name) : name
  return postfix === undefined ? title : title + ` ${postfix}`
}

const printSeesArray = (sees?: ReadonlyArray<string>): string => {
  if (sees === undefined || sees.length === 0) {
    return ""
  }
  return `\n\n${Markdown.bold("See")}\n\n${sees.map((see) => `- ${replaceJSDocLinks(see)}`).join("\n")}`
}

const printOptionalSourceLink = Effect.fnUntraced(function*(position?: Domain.Position) {
  if (position === undefined) {
    return ""
  }
  const config = yield* Configuration.Configuration
  const source = yield* Parser.Source
  const name = source.sourceFile.getBaseName()
  return `\n\n[Source](${config.srcLink}${name}#L${position.line})`
})

const printModel = Effect.fnUntraced(function*(name: string, doc: Domain.Doc, options: {
  readonly signature?: string | undefined
  readonly position?: Domain.Position | undefined
  readonly indentation?: number | undefined
  readonly postfix?: string | undefined
}) {
  const sourceLink = yield* printOptionalSourceLink(options.position)
  const description = yield* printOptionalDescription(doc.description)
  return printHeaderByIndentation(options.indentation ?? 0) + printTitle(name, doc.deprecated, options.postfix) +
    description +
    printThrowsArray(doc.throws) +
    printExamplesArray(doc.examples) +
    printSeesArray(doc.sees) +
    printOptionalSignature(options.signature) +
    sourceLink +
    printOptionalSince(doc.since)
})

const printEntry = (model: Domain.DocEntry, options: {
  readonly indentation?: number | undefined
  readonly postfix?: string | undefined
}) => {
  return printModel(model.name, model.doc, {
    signature: model.signature,
    position: model.position,
    indentation: options.indentation,
    postfix: options.postfix
  })
}

const printStaticMethod = (model: Domain.DocEntry) => {
  return printEntry(model, {
    indentation: 1,
    postfix: "(static method)"
  })
}

const printMethod = (model: Domain.DocEntry) => {
  return printEntry(model, {
    indentation: 1,
    postfix: "(method)"
  })
}

const printProperty = (model: Domain.DocEntry) => {
  return printEntry(model, {
    indentation: 1,
    postfix: "(property)"
  })
}

const printClass = Effect.fnUntraced(function*(model: Domain.Class) {
  const header = yield* printEntry(model, {
    postfix: "(class)"
  })
  const staticMethods = yield* Effect.forEach(model.staticMethods, (method) => printStaticMethod(method))
  const methods = yield* Effect.forEach(model.methods, (method) => printMethod(method))
  const properties = yield* Effect.forEach(model.properties, (property) => printProperty(property))
  return header +
    staticMethods.map((s) => "\n\n" + s).join("") +
    methods.map((s) => "\n\n" + s).join("") +
    properties.map((s) => "\n\n" + s).join("")
})

const printConstant = (model: Domain.Constant) => {
  return printEntry(model, {})
}

const printExport = (model: Domain.Export) => {
  return printEntry(model, {
    postfix: model.isNamespaceExport ? "(namespace export)" : undefined
  })
}

const printFunction = (model: Domain.Function) => {
  return printEntry(model, {})
}

const printInterface = (model: Domain.Interface, indentation: number) => {
  return printEntry(model, {
    indentation,
    postfix: "(interface)"
  })
}

const printTypeAlias = (model: Domain.TypeAlias, indentation: number) => {
  return printEntry(model, {
    indentation,
    postfix: "(type alias)"
  })
}

const printNamespace = (
  model: Domain.Namespace,
  indentation: number
): Effect.Effect<string, never, Configuration.Configuration | Parser.Source> => {
  return Effect.gen(function*() {
    const header = yield* printModel(model.name, model.doc, {
      position: model.position,
      indentation,
      postfix: "(namespace)"
    })
    const interfaces = yield* Effect.forEach(model.interfaces, (inter) => printInterface(inter, indentation + 1))
    const typeAliases = yield* Effect.forEach(
      model.typeAliases,
      (typeAlias) => printTypeAlias(typeAlias, indentation + 1)
    )
    const namespaces = yield* Effect.forEach(
      model.namespaces,
      (namespace) => printNamespace(namespace, indentation + 1)
    )
    return header +
      interfaces.map((s) => "\n\n" + s).join("") +
      typeAliases.map((s) => "\n\n" + s).join("") +
      namespaces.map((s) => "\n\n" + s).join("")
  })
}

/** @internal */
export const print = (p: Printable) => {
  switch (p._tag) {
    case "Class":
      return printClass(p)
    case "Constant":
      return printConstant(p)
    case "Export":
      return printExport(p)
    case "Function":
      return printFunction(p)
    case "Interface":
      return printInterface(p, 0)
    case "TypeAlias":
      return printTypeAlias(p, 0)
    case "Namespace":
      return printNamespace(p, 0)
  }
}

const DEFAULT_CATEGORY = "utils"

const byCategory = Order.mapInput(
  String.Order,
  ([category]: [string, ...Array<unknown>]) => category
)

const getPrintables = (module: Domain.Module): ReadonlyArray<Printable> =>
  Array.flatten([
    module.classes,
    module.constants,
    module.exports,
    module.functions,
    module.interfaces,
    module.typeAliases,
    module.namespaces
  ])

const sortByName: <A extends { name: string }>(self: Iterable<A>) => Array<A> = Array.sort(
  pipe(
    String.Order,
    Order.mapInput(({ name }: { name: string }) => name)
  )
)

/**
 * Renders a parsed module as a Markdown documentation page.
 *
 * @category printers
 * @since 0.6.0
 */
export const printModule = (module: Domain.Module) => {
  return Effect.gen(function*() {
    const description = yield* printModel(module.name, module.doc, {
      postfix: "overview"
    })

    const printables = pipe(
      sortByName(getPrintables(module)),
      Array.groupBy((printable) =>
        printable.doc.category.length === 0 ? DEFAULT_CATEGORY : printable.doc.category.join(", ")
      ),
      Record.toEntries,
      Array.sort(byCategory)
    )

    const strings = yield* Effect.forEach(printables, ([category, printables]) =>
      Effect.gen(function*() {
        const out = `\n\n# ${category}`
        const strings = yield* Effect.forEach(sortByName(printables), (printable) => print(printable))
        return out + strings.map((s) => "\n\n" + s).join("")
      }))

    const content = strings.join("")

    return `${description}

<!-- toc -->${content}`
  }).pipe(Effect.provideService(Parser.Source, module.source))
}

const defaultPrettierOptions: Prettier.Options = {
  parser: "markdown",
  semi: false,
  singleQuote: false,
  printWidth: 120,
  trailingComma: "none"
}

/**
 * Renders the front matter for a generated module page.
 *
 * @category printers
 * @since 0.6.0
 */
export const printFrontMatter = (module: Domain.Module, nav_order: number): string => {
  return `---
title: ${module.name}
nav_order: ${nav_order}
parent: Modules
---`
}

/**
 * Formats generated Markdown with the docgen Prettier settings.
 *
 * @category printers
 * @since 0.6.0
 */
export function prettify(s: string) {
  return Effect.tryPromise({
    try: () => Prettier.format(s, defaultPrettierOptions),
    catch: globalThis.String
  }).pipe(Effect.orDie)
}