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

#!/usr/bin/env node

/**
 * Command-line interface for generating Effect API documentation.
 *
 * @since 0.6.0
 */
import * as Array from "effect/Array"
import * as CliError from "effect/cli/CliError"
import * as Command from "effect/cli/Command"
import * as Flag from "effect/cli/Flag"
import * as Config from "effect/Config"
import * as Effect from "effect/Effect"
import * as Option from "effect/Option"
import * as Schema from "effect/Schema"
import PackageJson from "../package.json" with { type: "json" }
import * as Configuration from "./Configuration.ts"
import * as Core from "./Core.ts"
import * as Domain from "./Domain.ts"

const projectHomepage = Flag.String("homepage").pipe(
  Flag.withFallbackConfig(Config.String("projectHomepage")),
  Flag.withDescription(
    "The link to the project homepage (will be shown in the Auxiliary Links of the generated documentation)"
  ),
  Flag.optional
)

const srcLink = Flag.String("srcLink").pipe(
  Flag.withFallbackConfig(Config.String("srcLink")),
  Flag.withDescription("The link to the project source code"),
  Flag.optional
)

const srcDir = Flag.Directory("src", { mustExist: true }).pipe(
  Flag.withFallbackConfig(Config.String("src").pipe(Config.withDefault("src"))),
  Flag.withDescription("The directory in which docgen will search for TypeScript files to parse")
)

const outDir = Flag.Directory("out").pipe(
  Flag.withFallbackConfig(Config.String("out").pipe(Config.withDefault("docs"))),
  Flag.withDescription("The directory to which docgen will generate its output markdown documents")
)

const theme = Flag.String("theme").pipe(
  Flag.withFallbackConfig(Config.String("theme").pipe(Config.withDefault(Configuration.DEFAULT_THEME))),
  Flag.withDescription("The Jekyll theme that should be used for the generated documentation")
)

const disableSearch = Flag.Boolean("disable-search").pipe(
  Flag.withDescription("Whether or not search should be enabled in the generated documentation"),
  Flag.optional
)

const enableSearchAlias = Flag.Boolean("enable-search").pipe(
  Flag.withDescription("Whether or not search should be enabled in the generated documentation"),
  Flag.optional
)

const enforceDescriptions = Flag.Boolean("enforce-descriptions").pipe(
  Flag.withDescription("Whether or not a description for each module export should be required"),
  Flag.optional
)

const enforceExamples = Flag.Boolean("enforce-examples").pipe(
  Flag.withDescription(
    "Whether or not @example tags for each module export should be required " +
      "(Note: examples will not be enforced in module documentation)"
  ),
  Flag.optional
)

const noEnforceVersion = Flag.Boolean("no-enforce-version").pipe(
  Flag.withDescription("Whether or not @since tags for each module export should be required"),
  Flag.optional
)

const enforceVersionAlias = Flag.Boolean("enforce-version").pipe(
  Flag.withDescription("Whether or not @since tags for each module export should be required"),
  Flag.optional
)

const runExamples = Flag.Boolean("run-examples").pipe(
  Flag.withDescription("Whether or not to execute examples discovered in the TypeScript source files"),
  Flag.optional
)

const exclude = Flag.String("exclude").pipe(
  Flag.between(0, Infinity),
  Flag.withFallbackConfig(
    Config.Array(Schema.String, "exclude").pipe(
      Config.withDefault(Array.empty<string>())
    )
  ),
  Flag.withDescription(
    "An array of glob patterns specifying files that should be excluded from the generated documentation"
  )
)

const compilerOptionsSchema = Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown))

const parseCompilerOptionsFlag = (name: string, description: string) =>
  Flag.String(name).pipe(
    Flag.withDescription(description),
    Flag.mapEffect((value) =>
      Schema.decodeUnknownEffect(compilerOptionsSchema)(value).pipe(
        Effect.mapError((error) =>
          new CliError.InvalidValue({
            option: name,
            value,
            expected: `a JSON record (${globalThis.String(error)})`,
            kind: "flag"
          })
        )
      )
    )
  )

const parseCompilerOptionsFile = Flag.File("parse-tsconfig-file", { mustExist: true }).pipe(
  Flag.withDescription("The TypeScript TSConfig file to use for parsing source files"),
  Flag.optional
)

const parseCompilerOptionsInline = parseCompilerOptionsFlag(
  "parse-compiler-options",
  "The TypeScript compiler options to use for parsing source files"
).pipe(Flag.optional)

const examplesCompilerOptionsFile = Flag.File("examples-tsconfig-file", { mustExist: true }).pipe(
  Flag.withDescription("The TypeScript TSConfig file to use for examples"),
  Flag.optional
)

const examplesCompilerOptionsInline = parseCompilerOptionsFlag(
  "examples-compiler-options",
  "The TypeScript compiler options to use for examples"
).pipe(Flag.optional)

const options = {
  projectHomepage,
  srcLink,
  srcDir,
  outDir,
  theme,
  disableSearch,
  enableSearchAlias,
  enforceDescriptions,
  enforceExamples,
  noEnforceVersion,
  enforceVersionAlias,
  runExamples,
  exclude,
  parseCompilerOptionsFile,
  parseCompilerOptionsInline,
  examplesCompilerOptionsFile,
  examplesCompilerOptionsInline
}

/** @internal */
export const docgenCommand = Command.make("docgen", options)

/** @internal */
export const loadConfiguration = Effect.fnUntraced(function*(
  args: Command.Command.Config.Infer<typeof options>
) {
  const {
    enableSearchAlias,
    disableSearch,
    enforceDescriptions,
    enforceExamples,
    enforceVersionAlias,
    noEnforceVersion,
    runExamples,
    examplesCompilerOptionsFile,
    examplesCompilerOptionsInline,
    parseCompilerOptionsFile,
    parseCompilerOptionsInline,
    ...config
  } = args
  if (Option.isSome(parseCompilerOptionsFile) && Option.isSome(parseCompilerOptionsInline)) {
    return yield* new CliError.InvalidValue({
      option: "parse-compiler-options",
      value: JSON.stringify(parseCompilerOptionsInline.value),
      expected: "only one of --parse-tsconfig-file or --parse-compiler-options",
      kind: "flag"
    })
  }
  if (Option.isSome(examplesCompilerOptionsFile) && Option.isSome(examplesCompilerOptionsInline)) {
    return yield* new CliError.InvalidValue({
      option: "examples-compiler-options",
      value: JSON.stringify(examplesCompilerOptionsInline.value),
      expected: "only one of --examples-tsconfig-file or --examples-compiler-options",
      kind: "flag"
    })
  }
  const configuredEnableSearch = yield* Config.Boolean("enableSearch").pipe(Effect.orElseSucceed(() => true))
  const configuredEnforceDescriptions = yield* Config.Boolean("enforceDescriptions").pipe(
    Effect.orElseSucceed(() => false)
  )
  const configuredEnforceExamples = yield* Config.Boolean("enforceExamples").pipe(
    Effect.orElseSucceed(() => false)
  )
  const configuredEnforceVersion = yield* Config.Boolean("enforceVersion").pipe(Effect.orElseSucceed(() => true))
  const configuredRunExamples = yield* Config.Boolean("runExamples").pipe(Effect.orElseSucceed(() => false))
  return yield* Configuration.load({
    ...config,
    enableSearch: Option.match(disableSearch, {
      onNone: () => Option.getOrElse(enableSearchAlias, () => configuredEnableSearch),
      onSome: (disabled) => !disabled
    }),
    enforceDescriptions: Option.getOrElse(enforceDescriptions, () => configuredEnforceDescriptions),
    enforceExamples: Option.getOrElse(enforceExamples, () => configuredEnforceExamples),
    enforceVersion: Option.match(noEnforceVersion, {
      onNone: () => Option.getOrElse(enforceVersionAlias, () => configuredEnforceVersion),
      onSome: (disabled) => !disabled
    }),
    runExamples: Option.getOrElse(runExamples, () => configuredRunExamples),
    parseCompilerOptions: Option.orElse(parseCompilerOptionsFile, () => parseCompilerOptionsInline),
    examplesCompilerOptions: Option.orElse(examplesCompilerOptionsFile, () => examplesCompilerOptionsInline)
  })
})

const command = docgenCommand.pipe(
  Command.withHandler(() =>
    Effect.scoped(Core.program).pipe(
      Effect.catchTag("DocgenError", (error) =>
        Effect.gen(function*() {
          const config = yield* Configuration.Configuration
          return yield* new Domain.DocgenError({ message: `[${config.projectName}] ${error.message}` })
        }))
    )
  ),
  Command.provideEffect(Configuration.Configuration, loadConfiguration)
)

/**
 * Runs the docgen command-line program.
 *
 * @category running
 * @since 0.6.0
 */
export const cli = Command.runWith(command, {
  version: PackageJson["version"]
})