/**
* Parses TypeScript declarations and JSDoc into docgen models.
*
* @since 0.6.0
*/
import * as doctrine from "doctrine"
import * as Array from "effect/Array"
import * as Context from "effect/Context"
import * as Effect from "effect/Effect"
import { pipe } from "effect/Function"
import * as Option from "effect/Option"
import * as Path from "effect/Path"
import * as Record from "effect/Record"
import * as String from "effect/String"
import * as ast from "ts-morph"
import * as Configuration from "./Configuration.ts"
import * as Domain from "./Domain.ts"
/**
* Source file and path currently being parsed.
*
* @category services
* @since 0.6.0
*/
export interface SourceShape {
readonly path: Array.NonEmptyReadonlyArray<string>
readonly sourceFile: ast.SourceFile
}
/** @internal */
export class Source extends Context.Service<Source, SourceShape>()("@effect/docgen/Source") {}
const sortModulesByPath: <A extends Domain.Module>(self: Iterable<A>) => Array<A> = Array
.sort(Domain.ByPath)
const getJSDocText: (jsdocs: ReadonlyArray<ast.JSDoc>) => string = Array.matchRight({
onEmpty: () => "",
onNonEmpty: (_, last) => last.getText()
})
const getDocComment = (ranges: ReadonlyArray<ast.CommentRange>): Option.Option<ast.CommentRange> =>
pipe(
ranges,
Array.filter((range) => range.getText().startsWith("/**")),
Array.last
)
class Comment {
readonly description: string | undefined
readonly tags: Record<string, ReadonlyArray<string> | undefined>
constructor(
description: string | undefined,
tags: Record<string, ReadonlyArray<string> | undefined>
) {
this.description = description
this.tags = tags
}
}
/**
* @internal
*/
export const parseComment = (text: string): Comment => {
const annotation: doctrine.Annotation = doctrine.parse(text, {
unwrap: true
})
const description = pipe(
Option.fromNullishOr(annotation.description),
Option.map((s) => s.trim()),
Option.filter(String.isNonEmpty),
Option.getOrUndefined
)
const tags = pipe(
annotation.tags,
Array.groupBy((tag) => tag.title),
Record.map((values) =>
Array.map(values, (tag) =>
pipe(
Option.fromNullishOr(tag.description),
Option.map(String.trim),
Option.getOrElse(() => "")
))
)
)
return { description, tags }
}
const isVariableDeclarationList = (
u: ast.VariableDeclarationList | ast.CatchClause
): u is ast.VariableDeclarationList => u.getKind() === ast.ts.SyntaxKind.VariableDeclarationList
const isVariableStatement = (
u:
| ast.VariableStatement
| ast.ForStatement
| ast.ForOfStatement
| ast.ForInStatement
): u is ast.VariableStatement => u.getKind() === ast.ts.SyntaxKind.VariableStatement
const parseDoc = (text: string) => {
const comment = parseComment(text)
return new Domain.Doc(
comment.description,
comment.tags["since"] ?? [],
comment.tags["deprecated"] ?? [],
comment.tags["example"] ?? [],
comment.tags["category"] ?? [],
comment.tags["throws"] ?? [],
comment.tags["see"] ?? [],
comment.tags
)
}
const shouldIgnore = (doc: Domain.Doc): boolean => {
return Record.has(doc.tags, "internal") || Record.has(doc.tags, "ignore")
}
const parseInterfaceDeclaration = Effect.fnUntraced(function*(id: ast.InterfaceDeclaration) {
const doc = parseDoc(getJSDocText(id.getJsDocs()))
if (shouldIgnore(doc)) {
return []
}
const name = id.getName()
const signature = id.getText()
const position = yield* parsePosition(id)
return [
new Domain.Interface(
name,
doc,
signature,
position
)
]
})
const parseInterfaceDeclarations = (interfaces: ReadonlyArray<ast.InterfaceDeclaration>) => {
const exportedInterfaces = Array.filter(
interfaces,
(id) => id.isExported()
)
return Effect.forEach(exportedInterfaces, parseInterfaceDeclaration).pipe(Effect.map(Array.flatten))
}
/**
* Parses exported interfaces from the current source file.
*
* @category parsing
* @since 0.6.0
*/
export const parseInterfaces = Effect.flatMap(
Source,
(source) => parseInterfaceDeclarations(source.sourceFile.getInterfaces())
)
const getTypeText = (node: ast.Node) =>
node.getType().getText(
node,
ast.ts.TypeFormatFlags.NoTruncation
| ast.ts.TypeFormatFlags.WriteArrayAsGenericType
| ast.ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope
| ast.ts.TypeFormatFlags.NoTypeReduction
| ast.ts.TypeFormatFlags.AllowUniqueESSymbolType
| ast.ts.TypeFormatFlags.WriteArrowStyleSignature
)
const parseType = (node: ast.Node) => {
let text = getTypeText(node)
for (const property of node.getDescendantsOfKind(ast.ts.SyntaxKind.PropertySignature)) {
if (!shouldIgnore(parseDoc(getJSDocText(property.getJsDocs())))) continue
const readonly = property.getFirstModifierByKind(ast.ts.SyntaxKind.ReadonlyKeyword) ? "readonly " : ""
const optional = property.hasQuestionToken() ? "?" : ""
const type = property.getTypeNode()?.getText() ?? getTypeText(property)
const signature = `${readonly}${property.getName()}${optional}: ${type}`
text = text
.replaceAll(`; ${signature}`, "")
.replaceAll(`${signature}; `, "")
.replaceAll(signature, "")
}
return text
}
const getFunctionDeclarationJSDocs = (fd: ast.FunctionDeclaration): Array<ast.JSDoc> =>
Array.matchLeft(fd.getOverloads(), {
onEmpty: () => fd.getJsDocs(),
onNonEmpty: (firstOverload) => firstOverload.getJsDocs()
})
const parsePosition = (node: ast.Node): Effect.Effect<Domain.Position, never, Source> => {
return Effect.gen(function*() {
const source = yield* Source
const startPos = node.getStart()
const position = source.sourceFile.getLineAndColumnAtPos(startPos)
return position
})
}
const parseFunctionDeclaration = Effect.fnUntraced(function*(fd: ast.FunctionDeclaration) {
const doc = parseDoc(getJSDocText(getFunctionDeclarationJSDocs(fd)))
if (shouldIgnore(doc)) {
return []
}
const name = fd.getName()
const type = parseType(fd)
const signature = `declare const ${name}: ${type}`
const position = yield* parsePosition(fd)
return [
new Domain.Function(
name ?? "",
doc,
signature,
position
)
]
})
const parseFunctionVariableDeclaration = Effect.fnUntraced(function*(vd: ast.VariableDeclaration) {
const vs: any = vd.getParent().getParent()
const doc = parseDoc(getJSDocText(vs.getJsDocs()))
if (shouldIgnore(doc)) {
return []
}
const name = vd.getName()
const type = parseType(vd)
const signature = `declare const ${name}: ${type}`
const startPos = vd.getStart()
const source = yield* Source
const position = source.sourceFile.getLineAndColumnAtPos(startPos)
return [
new Domain.Function(
name ?? "",
doc,
signature,
position
)
]
})
const getFunctionDeclarations = Effect.gen(function*() {
const source = yield* Source
const functions = Array.filter(
source.sourceFile.getFunctions(),
(fd) => fd.isExported()
)
const arrows = pipe(
Array.filter(
source.sourceFile.getVariableDeclarations(),
(vd) => {
if (isVariableDeclarationList(vd.getParent())) {
const vs: any = vd.getParent().getParent()
if (isVariableStatement(vs)) {
return vs.isExported() &&
Option.fromNullishOr(vd.getInitializer()).pipe(
Option.filter((expr) => ast.Node.isFunctionLikeDeclaration(expr)),
Option.isSome
)
}
}
return false
}
)
)
return { functions, arrows }
})
/**
* Parses exported function declarations and function-valued variables.
*
* @category parsing
* @since 0.6.0
*/
export const parseFunctions = Effect.gen(function*() {
const { arrows, functions } = yield* getFunctionDeclarations
const functionDeclarations = yield* Effect.forEach(functions, parseFunctionDeclaration).pipe(
Effect.map(Array.flatten)
)
const functionVariableDeclarations = yield* Effect.forEach(arrows, parseFunctionVariableDeclaration).pipe(
Effect.map(Array.flatten)
)
return [...functionDeclarations, ...functionVariableDeclarations]
})
const parseTypeAliasDeclaration = Effect.fnUntraced(function*(ta: ast.TypeAliasDeclaration) {
const doc = parseDoc(getJSDocText(ta.getJsDocs()))
if (shouldIgnore(doc)) {
return []
}
const name = ta.getName()
const typeParameters = ta.getTypeParameters().map((parameter) => parameter.getText()).join(", ")
const definition = ta.getTypeNode()?.getText()
const signature = `type ${name}${typeParameters.length > 0 ? `<${typeParameters}>` : ""} = ${definition}`
const position = yield* parsePosition(ta)
return [
new Domain.TypeAlias(
name,
doc,
signature,
position
)
]
})
const parseTypeAliasDeclarations = (typeAliases: ReadonlyArray<ast.TypeAliasDeclaration>) => {
const exportedTypeAliases = Array.filter(
typeAliases,
(tad) => tad.isExported()
)
return Effect.forEach(exportedTypeAliases, parseTypeAliasDeclaration).pipe(Effect.map(Array.flatten))
}
/**
* Parses exported type aliases from the current source file.
*
* @category parsing
* @since 0.6.0
*/
export const parseTypeAliases = Effect.flatMap(
Source,
(source) => parseTypeAliasDeclarations(source.sourceFile.getTypeAliases())
)
const parseConstantVariableDeclaration = Effect.fnUntraced(function*(vd: ast.VariableDeclaration) {
const vs: any = vd.getParent().getParent()
const doc = parseDoc(getJSDocText(vs.getJsDocs()))
if (shouldIgnore(doc)) {
return []
}
const name = vd.getName()
const type = parseType(vd)
const signature = `declare const ${name}: ${type}`
const position = yield* parsePosition(vd)
return [
new Domain.Constant(
name,
doc,
signature,
position
)
]
})
/**
* Parses exported non-function constants from the current source file.
*
* @category parsing
* @since 0.6.0
*/
export const parseConstants = Effect.gen(function*() {
const source = yield* Source
const variableDeclarations = pipe(
Array.filter(
source.sourceFile.getVariableDeclarations(),
(vd) => {
if (isVariableDeclarationList(vd.getParent())) {
const vs: any = vd.getParent().getParent()
if (isVariableStatement(vs)) {
return vs.isExported() &&
Option.fromNullishOr(vd.getInitializer()).pipe(
Option.filter((expr) => !ast.Node.isFunctionLikeDeclaration(expr)),
Option.isSome
)
}
}
return false
}
)
)
return yield* Effect.forEach(variableDeclarations, parseConstantVariableDeclaration).pipe(
Effect.map(Array.flatten)
)
})
const parseExportSpecifier = Effect.fnUntraced(function*(es: ast.ExportSpecifier) {
const name = es.compilerNode.name.text
const type = parseType(es)
const oDocComment = getDocComment(es.getLeadingCommentRanges())
const doc = Option.isSome(oDocComment) ? parseDoc(oDocComment.value.getText()) : parseDoc("")
const signature = `declare const ${name}: ${type}`
const position = yield* parsePosition(es)
return new Domain.Export(
name,
doc,
signature,
position,
false
)
})
const parseExportStar = Effect.fnUntraced(function*(ed: ast.ExportDeclaration) {
const es = ed.getModuleSpecifier()!
const name = es.getText()
const namespace = ed.getNamespaceExport()?.getName()
const signature = `export *${namespace === undefined ? "" : ` as ${namespace}`} from ${name}`
const oDocComment = getDocComment(ed.getLeadingCommentRanges())
const doc = Option.isSome(oDocComment) ? parseDoc(oDocComment.value.getText()) : parseDoc("")
const position = yield* parsePosition(ed)
return new Domain.Export(
namespace ?? name,
doc.modifyDescription(
`Re-exports all named exports from the ${name} module${namespace === undefined ? "" : ` as \`${namespace}\``}.`
),
signature,
position,
true
)
})
const parseNamedExports = (ed: ast.ExportDeclaration) => {
const namedExports = ed.getNamedExports()
if (namedExports.length === 0) {
if (ed.getModuleSpecifier() !== undefined) {
return parseExportStar(ed).pipe(Effect.map(Array.of))
}
return Effect.succeed([])
}
return Effect.forEach(namedExports, parseExportSpecifier)
}
/**
* Parses explicit export declarations from the current source file.
*
* @category parsing
* @since 0.6.0
*/
export const parseExports = pipe(
Effect.map(Source, (source) => source.sourceFile.getExportDeclarations()),
Effect.flatMap((exportDeclarations) => Effect.forEach(exportDeclarations, parseNamedExports)),
Effect.map(Array.flatten)
)
const parseModuleDeclaration = (
ed: ast.ModuleDeclaration
): Effect.Effect<Array<Domain.Namespace>, never, Source | Configuration.Configuration> => {
const doc = parseDoc(getJSDocText(ed.getJsDocs()))
if (shouldIgnore(doc)) {
return Effect.succeed([])
}
const name = ed.getName()
const getInterfaces = parseInterfaceDeclarations(ed.getInterfaces())
const getTypeAliases = parseTypeAliasDeclarations(ed.getTypeAliases())
const getNamespaces = parseModuleDeclarations(ed.getModules())
return Effect.gen(function*() {
const interfaces = yield* getInterfaces
const typeAliases = yield* getTypeAliases
const namespaces = yield* getNamespaces
const position = yield* parsePosition(ed)
return [
new Domain.Namespace(
name,
doc,
position,
interfaces,
typeAliases,
namespaces
)
]
})
}
const parseModuleDeclarations = (namespaces: ReadonlyArray<ast.ModuleDeclaration>) => {
return Effect.forEach(
namespaces.filter((md) => md.isExported()),
parseModuleDeclaration
).pipe(Effect.map(Array.flatten))
}
/**
* Parses exported namespaces from the current source file.
*
* @category parsing
* @since 0.6.0
*/
export const parseNamespaces = Effect.gen(function*() {
const source = yield* Source
return yield* parseModuleDeclarations(source.sourceFile.getModules())
})
const getTypeParameters = (tps: ReadonlyArray<ast.TypeParameterDeclaration>): string =>
tps.length === 0 ? "" : `<${tps.map((p) => p.getName()).join(", ")}>`
const parseMethod = Effect.fnUntraced(function*(md: ast.MethodDeclaration) {
const name = md.getName()
const jsdocs = Array.matchLeft(md.getOverloads(), {
onEmpty: () => md.getJsDocs(),
onNonEmpty: (head) => head.getJsDocs()
})
const doc = parseDoc(getJSDocText(jsdocs))
if (shouldIgnore(doc)) {
return Option.none()
}
const type = parseType(md)
const signature = `declare const ${name}: ${type}`
const position = yield* parsePosition(md)
return Option.some(
new Domain.DocEntry(
name,
doc,
signature,
position
)
)
})
const parseProperty = Effect.fnUntraced(function*(pd: ast.PropertyDeclaration) {
const doc = parseDoc(getJSDocText(pd.getJsDocs()))
if (shouldIgnore(doc)) {
return []
}
const name = pd.getName()
const type = parseType(pd)
const readonly = pipe(
Option.fromNullishOr(pd.getFirstModifierByKind(ast.ts.SyntaxKind.ReadonlyKeyword)),
Option.match({
onNone: () => "",
onSome: () => "readonly "
})
)
const signature = `${readonly}${name}: ${type}`
const position = yield* parsePosition(pd)
return [
new Domain.DocEntry(
name,
doc,
signature,
position
)
]
})
const parseProperties = (c: ast.ClassDeclaration) => {
const properties = Array.filter(
c.getProperties(),
(pd) =>
!pd.isStatic() && pipe(
pd.getFirstModifierByKind(ast.ts.SyntaxKind.PrivateKeyword),
Option.fromNullishOr,
Option.isNone
)
)
return Effect.forEach(properties, parseProperty).pipe(Effect.map(Array.flatten))
}
/**
* @internal
*/
export const getConstructorDeclarationSignature = (
c: ast.ConstructorDeclaration
): string =>
pipe(
Option.fromNullishOr(c.compilerNode.body),
Option.match({
onNone: () => c.getText(),
onSome: (body) => {
const end = body.getStart() - c.getStart() - 1
return c.getText().substring(0, end)
}
})
)
const getClassDeclarationSignature = (c: ast.ClassDeclaration) => {
const name = c.getName() ?? ""
return pipe(
Effect.succeed(getTypeParameters(c.getTypeParameters())),
Effect.map((typeParameters) =>
pipe(
c.getConstructors(),
Array.matchLeft({
onEmpty: () => `declare class ${name}${typeParameters}`,
onNonEmpty: (head) =>
`declare class ${name}${typeParameters} { ${
getConstructorDeclarationSignature(
head
)
} }`
})
)
)
)
}
const parseClass = Effect.fnUntraced(function*(c: ast.ClassDeclaration) {
const doc = parseDoc(getJSDocText(c.getJsDocs()))
if (shouldIgnore(doc)) {
return []
}
const name = c.getName() ?? ""
const signature = yield* getClassDeclarationSignature(c)
const methods = yield* pipe(
c.getInstanceMethods(),
Effect.forEach(parseMethod),
Effect.map(Array.getSomes)
)
const staticMethods = yield* pipe(
c.getStaticMethods(),
Effect.forEach(parseMethod),
Effect.map(Array.getSomes)
)
const properties = yield* parseProperties(c)
const position = yield* parsePosition(c)
return [
new Domain.Class(
name,
doc,
signature,
position,
methods,
staticMethods,
properties
)
]
})
/**
* Parses exported classes and their documented members from the current source file.
*
* @category parsing
* @since 0.6.0
*/
export const parseClasses = Effect.gen(function*() {
const source = yield* Source
const exportedClasses = source.sourceFile.getClasses().filter((cd) => cd.isExported())
return yield* Effect.forEach(exportedClasses, parseClass).pipe(Effect.map(Array.flatten))
})
/**
* @internal
*/
export const parseModuleDocumentation = Effect.gen(function*() {
const source = yield* Source
const statements = source.sourceFile.getStatements()
const ofirstStatement = Array.head(statements)
if (Option.isSome(ofirstStatement)) {
const oDocComment = getDocComment(ofirstStatement.value.getLeadingCommentRanges())
if (Option.isSome(oDocComment)) {
return parseDoc(oDocComment.value.getText())
}
}
return parseDoc("")
})
/**
* Parses the current source file into a module documentation model.
*
* @category parsing
* @since 0.6.0
*/
export const parseModule = Effect.gen(function*() {
const source = yield* Source
const doc = yield* parseModuleDocumentation
const interfaces = yield* parseInterfaces
const functions = yield* parseFunctions
const typeAliases = yield* parseTypeAliases
const classes = yield* parseClasses
const constants = yield* parseConstants
const exports = yield* parseExports
const namespaces = yield* parseNamespaces
const name = source.sourceFile.getBaseName()
return new Domain.Module(
source,
name,
doc,
source.path,
classes,
interfaces,
functions,
typeAliases,
constants,
exports,
namespaces
)
})
/**
* @internal
*/
export const parseFile =
(project: ast.Project) =>
(file: Domain.File): Effect.Effect<Domain.Module, Array<string>, Configuration.Configuration | Path.Path> => {
return Effect.gen(function*() {
const path = yield* Path.Path
const sourceFile = project.getSourceFile(file.path)
const filePath = file.path.split(path.sep)
if (sourceFile !== undefined && Array.isArrayNonEmpty(filePath)) {
return yield* Effect.provideService(parseModule, Source, { sourceFile, path: filePath })
}
return yield* Effect.fail([`Unable to locate file: ${file.path}`])
})
}
const createProject = Effect.fnUntraced(function*(files: ReadonlyArray<Domain.File>) {
const config = yield* Configuration.Configuration
const process = yield* Domain.Process
const cwd = yield* process.cwd
// Convert the raw config into a format that TS/TS-Morph expects
const parsed = ast.ts.parseJsonConfigFileContent(
{
compilerOptions: {
strict: true,
moduleResolution: "node",
...config.parseCompilerOptions
}
},
ast.ts.sys,
cwd
)
const options: ast.ProjectOptions = {
compilerOptions: parsed.options
}
const project = new ast.Project(options)
for (const file of files) {
project.addSourceFileAtPath(file.path)
}
return project
})
/**
* Parses source files into module documentation models sorted by path.
*
* @category parsing
* @since 0.6.0
*/
export const parseFiles = (files: ReadonlyArray<Domain.File>) =>
createProject(files).pipe(
Effect.flatMap((project) =>
pipe(
files,
Effect.validate(parseFile(project)),
Effect.map(sortModulesByPath)
)
)
)