sailfork / t3code-github / .repos/ effect/ packages/ tools/ doctest/ src/ Transform.ts

/**
 * @since 4.0.0
 */

import { RolldownMagicString } from "rolldown"
import { type ESTree, parseSync } from "rolldown/utils"

const markerPattern = /^ => (.+)$/
const helper = "__effect_doctest_assert_"
const statementTypes = new Set([
  "ClassDeclaration",
  "ExportAllDeclaration",
  "ExportDefaultDeclaration",
  "ExportNamedDeclaration",
  "FunctionDeclaration",
  "ImportDeclaration",
  "TSDeclareFunction",
  "TSEnumDeclaration",
  "TSExportAssignment",
  "TSImportEqualsDeclaration",
  "TSInterfaceDeclaration",
  "TSModuleDeclaration",
  "TSNamespaceExportDeclaration",
  "TSTypeAliasDeclaration",
  "VariableDeclaration"
])

interface Node {
  readonly type: string
  readonly start: number
  readonly end: number
  readonly [key: string]: unknown
}

interface Candidate {
  readonly node: Node
  readonly parent: Node | undefined
  readonly depth: number
}

const isNode = (value: unknown): value is Node =>
  typeof value === "object" && value !== null &&
  "type" in value && typeof value.type === "string" &&
  "start" in value && typeof value.start === "number" &&
  "end" in value && typeof value.end === "number"

const isStatement = (node: Node): boolean => node.type.endsWith("Statement") || statementTypes.has(node.type)

const collect = (program: ESTree.Program): { readonly candidates: Array<Candidate>; readonly names: Set<string> } => {
  const candidates: Array<Candidate> = []
  const names = new Set<string>()

  const visit = (node: Node, parent: Node | undefined, depth: number): void => {
    if (isStatement(node)) candidates.push({ node, parent, depth })
    if (node.type === "Identifier" && typeof node.name === "string") names.add(node.name)

    for (const value of Object.values(node)) {
      if (isNode(value)) {
        visit(value, node, depth + 1)
      } else if (Array.isArray(value)) {
        for (const child of value) {
          if (isNode(child)) visit(child, node, depth + 1)
        }
      }
    }
  }

  visit(program as unknown as Node, undefined, 0)
  return { candidates, names }
}

const location = (source: string, offset: number, file: string, line: number): string => {
  let localLine = 1
  let column = 1
  for (let index = 0; index < offset; index++) {
    if (source.charCodeAt(index) === 10) {
      localLine++
      column = 1
    } else {
      column++
    }
  }
  return `${file}:${line + localLine}:${column}`
}

const fail = (source: string, offset: number, file: string, line: number, message: string): never => {
  throw new Error(`${location(source, offset, file, line)} ${message}`)
}

const isUnbracedControlFlow = (parent: Node | undefined): boolean =>
  parent !== undefined && new Set([
    "DoWhileStatement",
    "ForInStatement",
    "ForOfStatement",
    "ForStatement",
    "IfStatement",
    "LabeledStatement",
    "WhileStatement",
    "WithStatement"
  ]).has(parent.type)

const assertionTarget = (
  source: string,
  candidates: ReadonlyArray<Candidate>,
  comment: { readonly start: number },
  file: string,
  line: number
): Candidate => {
  const target = candidates
    .filter(({ node }) => node.end <= comment.start && /^[ \t]*$/.test(source.slice(node.end, comment.start)))
    .sort((left, right) => right.node.end - left.node.end || right.depth - left.depth)[0]

  if (target === undefined) {
    return fail(source, comment.start, file, line, "doctest assertion must trail a complete statement on the same line")
  }
  if (isUnbracedControlFlow(target.parent)) {
    return fail(source, comment.start, file, line, "doctest assertions in control flow require an explicit block")
  }
  return target
}

const parseExpected = (expected: string, source: string, offset: number, file: string, line: number): void => {
  const parsed = parseSync(`${file}?doctest-expected`, `const __expected = (${expected})`, { lang: "ts" })
  const error = parsed.errors[0]
  if (error !== undefined) {
    fail(source, offset, file, line, `invalid doctest expected expression: ${error.message}`)
  }
}

/**
 * Transforms trailing doctest assertion comments into executable assertions.
 *
 * **Details**
 *
 * An assertion may trail an expression statement or a single initialized
 * `const` identifier. Expected values are TypeScript expressions evaluated in
 * the same lexical scope.
 *
 * @category testing
 * @since 4.0.0
 */
export const transform = (source: string, file: string, line: number): string => {
  if (!source.includes("// =>")) return source

  const parsed = parseSync(file, source, { lang: "ts" })
  const parseError = parsed.errors[0]
  if (parseError !== undefined) {
    fail(source, parseError.labels[0]?.start ?? 0, file, line, `invalid doctest source: ${parseError.message}`)
  }

  const markers = parsed.comments.flatMap((comment) => {
    if (comment.type !== "Line") return []
    const match = markerPattern.exec(comment.value)
    return match === null ? [] : [{ comment, expected: match[1].trim() }]
  })
  if (markers.length === 0) return source

  const { candidates, names } = collect(parsed.program)
  let index = 0
  while (names.has(`${helper}${index}`)) index++
  const alias = `${helper}${index}`
  const output = new RolldownMagicString(source)

  for (const { comment, expected } of markers) {
    parseExpected(expected, source, comment.start, file, line)
    const { node, parent } = assertionTarget(source, candidates, comment, file, line)

    if (node.type === "ExpressionStatement") {
      if (node.directive !== null) {
        fail(source, comment.start, file, line, "doctest assertions cannot target directives")
      }
      const expression = isNode(node.expression)
        ? node.expression
        : fail(source, comment.start, file, line, "doctest assertion has no expression")
      output.overwrite(
        expression.start,
        comment.end,
        `${alias}(${source.slice(expression.start, expression.end)}, ${expected});`
      )
      continue
    }

    if (node.type === "VariableDeclaration" && parent?.type !== "ExportNamedDeclaration") {
      const declarations = node.declarations
      const declaration = Array.isArray(declarations) && declarations.length === 1 ? declarations[0] : undefined
      const id = isNode(declaration) && isNode(declaration.id) ? declaration.id : undefined
      if (
        node.kind === "const" && node.declare === false && isNode(declaration?.init) &&
        id?.type === "Identifier" && typeof id.name === "string"
      ) {
        const indentation = source.slice(source.lastIndexOf("\n", node.start - 1) + 1, node.start)
        output.overwrite(node.end, comment.end, `\n${indentation}${alias}(${id.name}, ${expected});`)
        continue
      }
    }

    fail(
      source,
      comment.start,
      file,
      line,
      "doctest assertions can only target expression statements or a single initialized const identifier"
    )
  }

  output.append(`\n\nimport { assertEquals as ${alias} } from "@effect/doctest/Runtime"`)
  return output.toString()
}