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

/**
 * Data models shared by the docgen parser, checker, and printer.
 *
 * @since 0.6.0
 */

import type * as Array from "effect/Array"
import * as Context from "effect/Context"
import * as Data from "effect/Data"
import * as Effect from "effect/Effect"
import * as Layer from "effect/Layer"
import * as Order from "effect/Order"
import * as Rec from "effect/Record"
import * as String from "effect/String"
import type * as Parser from "./Parser.ts"

/**
 * Base model for a named, documented declaration.
 *
 * @category models
 * @since 0.6.0
 */
export class DocEntry {
  readonly name: string
  readonly doc: Doc
  readonly signature: string
  readonly position: Position
  constructor(
    name: string,
    doc: Doc,
    signature: string,
    position: Position
  ) {
    this.name = name
    this.doc = doc
    this.signature = signature
    this.position = position
  }
}

/**
 * Parsed JSDoc content attached to a declaration or module.
 *
 * @category models
 * @since 0.6.0
 */
export class Doc {
  readonly description: string | undefined
  readonly since: ReadonlyArray<string>
  readonly deprecated: ReadonlyArray<string>
  readonly examples: ReadonlyArray<string>
  readonly category: ReadonlyArray<string>
  readonly throws: ReadonlyArray<string>
  readonly sees: ReadonlyArray<string>
  readonly tags: Record<string, ReadonlyArray<string> | undefined>
  constructor(
    description: string | undefined,
    since: ReadonlyArray<string>,
    deprecated: ReadonlyArray<string>,
    examples: ReadonlyArray<string>,
    category: ReadonlyArray<string>,
    throws: ReadonlyArray<string>,
    sees: ReadonlyArray<string>,
    tags: Record<string, ReadonlyArray<string> | undefined>
  ) {
    this.description = description
    this.since = since
    this.deprecated = deprecated
    this.examples = examples
    this.category = category
    this.throws = throws
    this.sees = sees
    this.tags = tags
  }

  modifyDescription(description: string | undefined): Doc {
    return new Doc(
      description,
      this.since,
      this.deprecated,
      this.examples,
      this.category,
      this.throws,
      this.sees,
      this.tags
    )
  }
}

/**
 * Parsed documentation model for one source module.
 *
 * @category models
 * @since 0.6.0
 */
export class Module {
  readonly source: Parser.SourceShape
  readonly name: string
  readonly doc: Doc
  readonly path: Array.NonEmptyReadonlyArray<string>
  readonly classes: ReadonlyArray<Class>
  readonly interfaces: ReadonlyArray<Interface>
  readonly functions: ReadonlyArray<Function>
  readonly typeAliases: ReadonlyArray<TypeAlias>
  readonly constants: ReadonlyArray<Constant>
  readonly exports: ReadonlyArray<Export>
  readonly namespaces: ReadonlyArray<Namespace>
  constructor(
    source: Parser.SourceShape,
    name: string,
    doc: Doc,
    path: Array.NonEmptyReadonlyArray<string>,
    classes: ReadonlyArray<Class>,
    interfaces: ReadonlyArray<Interface>,
    functions: ReadonlyArray<Function>,
    typeAliases: ReadonlyArray<TypeAlias>,
    constants: ReadonlyArray<Constant>,
    exports: ReadonlyArray<Export>,
    namespaces: ReadonlyArray<Namespace>
  ) {
    this.source = source
    this.name = name
    this.doc = doc
    this.path = path
    this.classes = classes
    this.interfaces = interfaces
    this.functions = functions
    this.typeAliases = typeAliases
    this.constants = constants
    this.exports = exports
    this.namespaces = namespaces
  }
}

/**
 * Parsed documentation model for a class and its documented members.
 *
 * @category models
 * @since 0.6.0
 */
export class Class extends DocEntry {
  readonly _tag = "Class"
  readonly methods: ReadonlyArray<DocEntry>
  readonly staticMethods: ReadonlyArray<DocEntry>
  readonly properties: ReadonlyArray<DocEntry>
  constructor(
    name: string,
    doc: Doc,
    signature: string,
    position: Position,
    methods: ReadonlyArray<DocEntry>,
    staticMethods: ReadonlyArray<DocEntry>,
    properties: ReadonlyArray<DocEntry>
  ) {
    super(name, doc, signature, position)
    this.methods = methods
    this.staticMethods = staticMethods
    this.properties = properties
  }
}

/**
 * Parsed documentation model for an interface.
 *
 * @category models
 * @since 0.6.0
 */
export class Interface extends DocEntry {
  readonly _tag = "Interface"
}

/**
 * One-based source position used in diagnostics.
 *
 * @category models
 * @since 0.6.0
 */
export interface Position {
  readonly line: number
  readonly column: number
}

/**
 * Parsed documentation model for a function.
 *
 * @category models
 * @since 0.6.0
 */
export class Function extends DocEntry {
  readonly _tag = "Function"
}

/**
 * Parsed documentation model for a type alias.
 *
 * @category models
 * @since 0.6.0
 */
export class TypeAlias extends DocEntry {
  readonly _tag = "TypeAlias"
}

/**
 * Parsed documentation model for a constant.
 *
 * @category models
 * @since 0.6.0
 */
export class Constant extends DocEntry {
  readonly _tag = "Constant"
}

/**
 * Parsed documentation model for an explicit named or namespace export.
 *
 * @category models
 * @since 0.6.0
 */
export class Export extends DocEntry {
  readonly _tag = "Export"
  readonly isNamespaceExport: boolean
  constructor(
    name: string,
    doc: Doc,
    signature: string,
    position: Position,
    isNamespaceExport: boolean
  ) {
    super(name, doc, signature, position)
    this.isNamespaceExport = isNamespaceExport
  }
}

/**
 * Parsed documentation model for a namespace and its nested declarations.
 *
 * @category models
 * @since 0.6.0
 */
export class Namespace {
  readonly _tag = "Namespace"
  readonly name: string
  readonly doc: Doc
  readonly position: Position
  readonly interfaces: ReadonlyArray<Interface>
  readonly typeAliases: ReadonlyArray<TypeAlias>
  readonly namespaces: ReadonlyArray<Namespace>
  constructor(
    name: string,
    doc: Doc,
    position: Position,
    interfaces: ReadonlyArray<Interface>,
    typeAliases: ReadonlyArray<TypeAlias>,
    namespaces: ReadonlyArray<Namespace>
  ) {
    this.name = name
    this.doc = doc
    this.position = position
    this.interfaces = interfaces
    this.typeAliases = typeAliases
    this.namespaces = namespaces
  }
}

/**
 * A comparator function for sorting `Module` objects by their file path, represented as a string.
 * The file path is converted to lowercase before comparison.
 *
 * @category sorting
 * @since 0.6.0
 */
export const ByPath: Order.Order<Module> = Order.mapInput(
  String.Order,
  (module: Module) => module.path.join("/").toLowerCase()
)

/**
 * Represents a file which can be optionally overwriteable.
 *
 * @category models
 * @since 0.6.0
 */
export class File {
  readonly path: string
  readonly content: string
  readonly isOverwriteable: boolean
  constructor(
    path: string,
    content: string,
    isOverwriteable: boolean = false
  ) {
    this.path = path
    this.content = content
    this.isOverwriteable = isOverwriteable
  }
}

/**
 * Type ID for `DocgenError`.
 *
 * @category symbols
 * @since 0.6.0
 */
export const DocgenErrorTypeId = Symbol.for("@effect/docgen/DocgenError")

/**
 * Type-level representation of `DocgenErrorTypeId`.
 *
 * @category symbols
 * @since 0.6.0
 */
export type DocgenErrorTypeId = typeof DocgenErrorTypeId

/**
 * Error reported when documentation generation cannot continue.
 *
 * @category errors
 * @since 0.6.0
 */
export class DocgenError extends Data.TaggedError("DocgenError")<{
  readonly message: string
}> {}

/**
 * Represents a handle to the currently executing process.
 *
 * @category services
 * @since 0.6.0
 */
export class Process extends Context.Service<Process, {
  readonly cwd: Effect.Effect<string>
  readonly platform: Effect.Effect<NodeJS.Platform>
  readonly argv: Effect.Effect<Array<string>>
  readonly env: Effect.Effect<Record<string, string>>
}>()("@effect/docgen/Process") {
  static readonly layer = Layer.succeed(Process, {
    cwd: Effect.sync(() => process.cwd()),
    platform: Effect.sync(() => process.platform),
    argv: Effect.sync(() => process.argv),
    env: Effect.sync(() => {
      const env: Record<string, string> = {}
      for (const [key, value] of Object.entries(process.env)) {
        if (value !== undefined) Rec.assignProperty(env, key, value)
      }
      return env
    })
  })
}