sailfork / t3code-github / .repos/ effect/ packages/ tools/ jsdocs/ src/ Jsdocs.ts
/*
AI prompt for writing Effect public API JSDoc:
This package owns Effect public API JSDoc parsing, extraction, and model generation.
*/
import * as Effect from "effect/Effect"
import { globSync } from "glob"
import * as crypto from "node:crypto"
import * as fs from "node:fs"
import * as path from "node:path"
import * as ts from "typescript"
type ExportBucket = "value" | "type"
type DocScope = "module" | "declaration" | "namespace" | "namespace-declaration" | "member"
type Result<A, E> =
| { readonly _tag: "Success"; readonly value: A }
| { readonly _tag: "Failure"; readonly error: E }
interface SourceFileWithParseDiagnostics extends ts.SourceFile {
readonly parseDiagnostics: ReadonlyArray<ts.Diagnostic>
}
/**
* Result type returned by the JSDoc parser helpers.
*
* @category utility types
* @since 4.0.0
*/
export type JSDocResult<A, E> = Result<A, E>
/**
* Diagnostic emitted when a JSDoc block does not follow the standard shape.
*
* @category models
* @since 4.0.0
*/
export interface JSDocDiagnostic {
readonly code: string
readonly message: string
}
/**
* Parse error containing all diagnostics collected for a JSDoc block or file.
*
* @category models
* @since 4.0.0
*/
export interface JSDocParseError {
readonly diagnostics: ReadonlyArray<JSDocDiagnostic>
}
/**
* Parsed `@see` tag text and any inline links it contains.
*
* @category models
* @since 4.0.0
*/
export interface ParsedSeeTag {
readonly text: string
readonly links: ReadonlyArray<ParsedInlineLink>
}
/**
* TypeScript symbol target resolved for a parsed inline JSDoc link.
*
* @category models
* @since 4.0.0
*/
export interface ParsedInlineLinkSymbol {
readonly file: string
readonly range: readonly [number, number]
}
/**
* Parsed inline JSDoc link target and optional display text.
*
* @category models
* @since 4.0.0
*/
export interface ParsedInlineLink {
readonly raw: string
readonly target: string
readonly text: string | null
readonly range?: readonly [number, number]
readonly symbol?: ParsedInlineLinkSymbol
}
/**
* Parsed JSDoc description sections.
*
* @category models
* @since 4.0.0
*/
export interface ParsedDescription {
readonly short: string
readonly whenToUse: string | null
readonly details: string | null
readonly gotchas: string | null
}
/**
* Parsed example section from a JSDoc block.
*
* @category models
* @since 4.0.0
*/
export interface ParsedExample {
readonly title: string
readonly body: string | null
readonly code: string
}
/**
* Raw module-level JSDoc block collected from the top of a checked file.
*
* @category models
* @since 4.0.0
*/
export interface ParsedModuleJSDoc {
readonly raw: string
readonly range: readonly [number, number]
}
/**
* Stability of a documented public API. Untagged APIs are stable.
*
* @category models
* @since 4.0.0
*/
export type JSDocStability = "stable" | "unstable" | "experimental"
interface ParsedModuleTags {
readonly since: string
readonly stability: JSDocStability
readonly deprecated: string | null
readonly see: ReadonlyArray<ParsedSeeTag>
}
/**
* Parsed tags required for a root public declaration.
*
* @category models
* @since 4.0.0
*/
export interface ParsedDeclarationTags {
readonly category: string
readonly since: string
readonly stability: JSDocStability
readonly deprecated: string | null
readonly see: ReadonlyArray<ParsedSeeTag>
}
/**
* Parsed tags allowed for namespace JSDoc.
*
* @category models
* @since 4.0.0
*/
export interface ParsedNamespaceTags {
readonly category: string | null
readonly since: string
readonly stability: JSDocStability
readonly deprecated: string | null
readonly see: ReadonlyArray<ParsedSeeTag>
}
/**
* Parsed tags allowed for documented members.
*
* @category models
* @since 4.0.0
*/
export interface ParsedMemberTags {
readonly since: string | null
readonly stability: JSDocStability
readonly default: string | null
readonly deprecated: string | null
readonly see: ReadonlyArray<ParsedSeeTag>
}
/**
* Parsed documented member within a declaration or another member.
*
* @category models
* @since 4.0.0
*/
export interface ParsedMember {
readonly name: string
readonly signature: string | null
readonly range: readonly [number, number]
readonly description: ParsedDescription
readonly examples: ReadonlyArray<ParsedExample>
readonly tags: ParsedMemberTags
readonly members: ReadonlyArray<ParsedMember>
}
/**
* Parsed root declaration exported from a checked file.
*
* @category models
* @since 4.0.0
*/
export interface ParsedRootDeclaration {
readonly name: string
readonly bucket: ExportBucket
readonly signature: string | null
readonly range: readonly [number, number]
readonly description: ParsedDescription
readonly examples: ReadonlyArray<ParsedExample>
readonly tags: ParsedDeclarationTags
readonly members: ReadonlyArray<ParsedMember>
}
/**
* Parsed type declaration exported from inside a namespace.
*
* @category models
* @since 4.0.0
*/
export interface ParsedNamespaceDeclaration {
readonly name: string
readonly signature: string | null
readonly range: readonly [number, number]
readonly description: ParsedDescription
readonly examples: ReadonlyArray<ParsedExample>
readonly tags: ParsedNamespaceTags
readonly members: ReadonlyArray<ParsedMember>
}
/**
* Parsed namespace and its documented exported type declarations.
*
* @category models
* @since 4.0.0
*/
export interface ParsedNamespace {
readonly name: string
readonly signature: string | null
readonly range: readonly [number, number]
readonly description: ParsedDescription
readonly examples: ReadonlyArray<ParsedExample>
readonly tags: ParsedNamespaceTags
readonly declarations: ReadonlyArray<ParsedNamespaceDeclaration>
readonly namespaces: ReadonlyArray<ParsedNamespace>
}
/**
* Parsed public JSDoc data collected from one checked file.
*
* @category models
* @since 4.0.0
*/
export interface ParsedJSDocFile {
readonly moduleJSDoc?: ParsedModuleJSDoc
readonly declarations: ReadonlyArray<ParsedRootDeclaration>
readonly namespaces: ReadonlyArray<ParsedNamespace>
}
/**
* Barrel import metadata for a public module included in the JSDoc dump.
*
* @category models
* @since 4.0.0
*/
export type ParsedJSDocBarrelImport =
| {
readonly type: "namespace"
readonly module: string
readonly name: string
}
| {
readonly type: "flat"
readonly module: string
}
/**
* Import specifiers for a public module included in the JSDoc dump.
*
* @category models
* @since 4.0.0
*/
export interface ParsedJSDocImports {
readonly module: string
readonly barrel: ParsedJSDocBarrelImport | null
readonly flatNames: ReadonlyArray<string>
}
/**
* Kinds of public API records represented in a JSDoc model.
*
* @category models
* @since 4.0.0
*/
export type JSDocApiKind = "root-declaration" | "namespace" | "namespace-declaration" | "member"
/**
* Recommended import declaration and usage for an importable API.
*
* @category models
* @since 4.0.0
*/
export type JSDocApiImportGuidance =
| {
readonly style: "namespace-barrel"
readonly importDeclaration: string
readonly usage: string
}
| {
readonly style: "named-barrel"
readonly importDeclaration: string
readonly usage: string
}
| {
readonly style: "named-module"
readonly importDeclaration: string
readonly usage: string
}
/**
* Resolution result for a link in an API's `@see` tags.
*
* @category models
* @since 4.0.0
*/
export type JSDocApiSeeLinkResolution =
| {
readonly _tag: "Resolved"
readonly apiId: string
readonly apiFqn: string
}
| {
readonly _tag: "Unresolved"
readonly reason: "not-found" | "ambiguous"
readonly candidates: ReadonlyArray<string>
}
/**
* Parsed `@see` link paired with its public API resolution.
*
* @category models
* @since 4.0.0
*/
export interface JSDocApiSeeLink extends ParsedInlineLink {
readonly resolution: JSDocApiSeeLinkResolution
}
/**
* Parsed `@see` tag and its resolved links.
*
* @category models
* @since 4.0.0
*/
export interface JSDocApiSeeTag {
readonly text: string
readonly links: ReadonlyArray<JSDocApiSeeLink>
}
/**
* Standard tags attached to a public API record.
*
* @category models
* @since 4.0.0
*/
export interface JSDocApiTags {
readonly category: string | null
readonly since: string | null
readonly stability: JSDocStability
readonly deprecated: string | null
readonly default: string | null
}
/**
* One public API record in an extracted JSDoc model.
*
* @category models
* @since 4.0.0
*/
export interface JSDocApi {
readonly id: string
readonly kind: JSDocApiKind
readonly moduleName: string
readonly apiName: string
readonly localName: string
readonly signature: string | null
readonly parentApiName: string | null
readonly apiFqn: string
readonly hasFqnCollision: boolean
readonly bucket: ExportBucket | null
readonly importable: boolean
readonly namespacePath: ReadonlyArray<string>
readonly memberPath: ReadonlyArray<string>
readonly source: {
readonly file: string
readonly path: ReadonlyArray<string | number>
readonly range: readonly [number, number]
}
readonly description: ParsedDescription
readonly examples: ReadonlyArray<ParsedExample>
readonly tags: JSDocApiTags
readonly see: ReadonlyArray<JSDocApiSeeTag>
readonly importGuidance: JSDocApiImportGuidance | null
}
interface ParsedBarrelExports {
readonly namespace: ReadonlyMap<string, string>
readonly flat: ReadonlySet<string>
readonly named: ReadonlyMap<string, ReadonlySet<string>>
}
/**
* Parsed public JSDoc data paired with the normalized source file path.
*
* @category models
* @since 4.0.0
*/
export interface ParsedJSDocFileDumpEntry extends ParsedJSDocFile {
readonly file: string
readonly imports: ParsedJSDocImports
}
interface AstNode {
readonly type: string
readonly range: [number, number]
readonly [key: string]: any
}
interface JSDocTag {
readonly name: string
value: string
readonly line: number
}
interface JSDocBlock {
readonly range: [number, number]
readonly raw: string
readonly lines: Array<string>
readonly tags: Array<JSDocTag>
readonly parsed?: ParsedCoreJSDoc
readonly diagnostics: Array<JSDocDiagnostic>
readonly internal: boolean
}
interface ParsedCoreJSDoc {
readonly description: ParsedDescription
readonly examples: ReadonlyArray<ParsedExample>
readonly tags: ReadonlyArray<JSDocTag>
}
interface ProgramCacheEntry {
readonly program?: ts.Program
readonly error?: string
reported: boolean
}
interface PackageMetadata {
readonly root: string
readonly sourceRoot: string
readonly name: string
readonly exports: unknown
}
interface PackageExportMatch {
readonly key: string
readonly value: unknown
readonly star: string | null
readonly specificity: number
readonly prefixLength: number
}
interface ParsedConfigResult {
readonly parsed?: ts.ParsedCommandLine
readonly error?: string
}
const programCache = new Map<string, ProgramCacheEntry>()
const packageMetadataCache = new Map<string, Result<PackageMetadata, string>>()
const barrelExportCache = new Map<string, Result<ParsedBarrelExports, string>>()
const tagOrder = new Map([
["deprecated", 0],
["default", 1],
["see", 2],
["stability", 3],
["category", 4],
["since", 5]
])
const signatureTypeFormatFlags = ts.TypeFormatFlags.NoTruncation |
ts.TypeFormatFlags.UseSingleQuotesForStringLiteralType
const stableSemverRegex = /^\d+\.\d+\.\d+$/
const urlRegex = /^https?:\/\//
function diagnostic(code: string, message: string): JSDocDiagnostic {
return { code, message }
}
function normalizePathName(filePath: string): string {
return filePath.replaceAll(path.sep, "/")
}
function normalizePackagePath(filePath: string): string {
return normalizePathName(filePath).replace(/^\.\//, "./")
}
function escapeRegExp(value: string): string {
return value.replace(/[|\\{}()[\]^$+?.]/g, "\\Loading Sailfork
amp;")
}
function globToRegExp(glob: string): RegExp {
let source = "^"
for (let index = 0; index < glob.length; index++) {
const char = glob[index]
const next = glob[index + 1]
if (char === "*") {
if (next === "*") {
source += ".*"
index++
} else {
source += "[^/]*"
}
} else if (char === "?") {
source += "[^/]"
} else {
source += escapeRegExp(char)
}
}
return new RegExp(`${source}
.repos/effect/packages/tools/jsdocs/src/Jsdocs.ts at main · sailfork/t3code-github · Sailfork
)
}
/**
* Creates a predicate that checks whether a filename is included by the configured JSDoc globs.
*
* @category constructors
* @since 4.0.0
*/
export function createJSDocFileMatcher(options: {
readonly cwd: string
readonly include?: ReadonlyArray<string>
readonly exclude?: ReadonlyArray<string>
}): (filename: string) => boolean {
const include = options.include?.map(globToRegExp)
const exclude = options.exclude?.map(globToRegExp)
return (filename) => {
const normalizedFilename = normalizePathName(filename)
const relativeFilename = normalizePathName(path.relative(options.cwd, filename))
const matches = (regexp: RegExp) => regexp.test(normalizedFilename) || regexp.test(relativeFilename)
if (include !== undefined && !include.some(matches)) {
return false
}
if (exclude !== undefined && exclude.some(matches)) {
return false
}
return true
}
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value)
}
function findPackageRoot(filename: string): string | undefined {
let directory = path.dirname(path.resolve(filename))
while (true) {
const packageJsonPath = path.join(directory, "package.json")
if (fs.existsSync(packageJsonPath)) {
return directory
}
const parent = path.dirname(directory)
if (parent === directory) {
return undefined
}
directory = parent
}
}
function readPackageMetadata(root: string): Result<PackageMetadata, string> {
const normalizedRoot = path.resolve(root)
const cached = packageMetadataCache.get(normalizedRoot)
if (cached !== undefined) {
return cached
}
const packageJsonPath = path.join(normalizedRoot, "package.json")
let parsed: unknown
try {
parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"))
} catch (error) {
const result = {
_tag: "Failure",
error: `unable to read package.json at ${packageJsonPath}: ${String(error)}`
} as const
packageMetadataCache.set(normalizedRoot, result)
return result
}
if (!isRecord(parsed)) {
const result = { _tag: "Failure", error: `package.json at ${packageJsonPath} must be an object` } as const
packageMetadataCache.set(normalizedRoot, result)
return result
}
if (typeof parsed.name !== "string" || parsed.name.length === 0) {
const result = {
_tag: "Failure",
error: `package.json at ${packageJsonPath} must include a non-empty name`
} as const
packageMetadataCache.set(normalizedRoot, result)
return result
}
if (parsed.exports === undefined) {
const result = { _tag: "Failure", error: `package.json at ${packageJsonPath} must include exports` } as const
packageMetadataCache.set(normalizedRoot, result)
return result
}
const result = {
_tag: "Success",
value: {
root: normalizedRoot,
sourceRoot: path.join(normalizedRoot, "src"),
name: parsed.name,
exports: parsed.exports
}
} as const
packageMetadataCache.set(normalizedRoot, result)
return result
}
function parseBarrelExports(indexPath: string): Result<ParsedBarrelExports, string> {
const normalizedIndexPath = path.resolve(indexPath)
const cached = barrelExportCache.get(normalizedIndexPath)
if (cached !== undefined) {
return cached
}
let source: string
try {
source = fs.readFileSync(normalizedIndexPath, "utf8")
} catch (error) {
const result = {
_tag: "Failure",
error: `unable to read barrel file ${normalizedIndexPath}: ${String(error)}`
} as const
barrelExportCache.set(normalizedIndexPath, result)
return result
}
const sourceFile = ts.createSourceFile(normalizedIndexPath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
const namespace = new Map<string, string>()
const flat = new Set<string>()
const named = new Map<string, Set<string>>()
for (const statement of sourceFile.statements) {
if (
ts.isExportDeclaration(statement) &&
statement.moduleSpecifier !== undefined &&
ts.isStringLiteralLike(statement.moduleSpecifier)
) {
const moduleSpecifier = normalizePathName(statement.moduleSpecifier.text)
if (statement.exportClause === undefined) {
flat.add(moduleSpecifier)
} else if (ts.isNamespaceExport(statement.exportClause)) {
namespace.set(moduleSpecifier, statement.exportClause.name.text)
} else if (ts.isNamedExports(statement.exportClause)) {
const names = named.get(moduleSpecifier) ?? new Set<string>()
for (const specifier of statement.exportClause.elements) {
names.add(specifier.name.text)
}
named.set(moduleSpecifier, names)
}
}
}
const result = { _tag: "Success", value: { namespace, flat, named } } as const
barrelExportCache.set(normalizedIndexPath, result)
return result
}
function getPackageExportMatch(exports: unknown, subpath: string): PackageExportMatch | undefined {
if (!isRecord(exports)) {
return subpath === "." ? { key: ".", value: exports, star: null, specificity: 1, prefixLength: 1 } : undefined
}
if (Object.hasOwn(exports, subpath)) {
return {
key: subpath,
value: exports[subpath],
star: null,
specificity: Number.MAX_SAFE_INTEGER,
prefixLength: subpath.length
}
}
const matches: Array<PackageExportMatch> = []
for (const [key, value] of Object.entries(exports)) {
const starIndex = key.indexOf("*")
if (!key.startsWith(".") || starIndex === -1) {
continue
}
const prefix = key.slice(0, starIndex)
const suffix = key.slice(starIndex + 1)
if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) {
continue
}
matches.push({
key,
value,
star: subpath.slice(prefix.length, subpath.length - suffix.length),
specificity: prefix.length + suffix.length,
prefixLength: prefix.length
})
}
return matches.sort((a, b) =>
b.specificity - a.specificity || b.prefixLength - a.prefixLength || b.key.length - a.key.length
)[0]
}
function packageExportTargetMatches(value: unknown, star: string | null, expectedTarget: string): boolean {
if (typeof value === "string") {
const target = normalizePackagePath(star === null ? value : value.replaceAll("*", star))
return target === expectedTarget
}
if (value === null || value === undefined) {
return false
}
if (Array.isArray(value)) {
return value.some((item) => packageExportTargetMatches(item, star, expectedTarget))
}
if (isRecord(value)) {
return Object.values(value).some((item) => packageExportTargetMatches(item, star, expectedTarget))
}
return false
}
function isPackageSubpathExported(
packageExports: unknown,
subpath: string,
expectedTarget: string
): boolean {
const match = getPackageExportMatch(packageExports, subpath)
return match !== undefined && packageExportTargetMatches(match.value, match.star, expectedTarget)
}
function isPathInside(parent: string, child: string): boolean {
const relative = path.relative(parent, child)
return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))
}
function packageSpecifier(packageName: string, subpath: string): string {
return subpath === "" ? packageName : `${packageName}/${subpath}`
}
function resolveBarrelImport(
metadata: PackageMetadata,
filename: string
): Result<{ readonly barrel: ParsedJSDocBarrelImport | null; readonly flatNames: ReadonlyArray<string> }, string> {
let directory = path.dirname(filename)
while (isPathInside(metadata.sourceRoot, directory)) {
const indexPath = path.join(directory, "index.ts")
if (indexPath !== filename && fs.existsSync(indexPath)) {
const expectedExport = `./${normalizePathName(path.relative(directory, filename))}`
const parsed = parseBarrelExports(indexPath)
if (parsed._tag === "Failure") {
return parsed
}
const barrelSubpath = normalizePathName(path.relative(metadata.sourceRoot, directory))
const exportSubpath = barrelSubpath === "" ? "." : `./${barrelSubpath}`
const exportTarget = barrelSubpath === "" ? "./src/index.ts" : `./src/${barrelSubpath}/index.ts`
if (isPackageSubpathExported(metadata.exports, exportSubpath, exportTarget)) {
const moduleSpecifier = packageSpecifier(metadata.name, barrelSubpath)
const flatNames = Array.from(parsed.value.named.get(expectedExport) ?? [])
const namespace = parsed.value.namespace.get(expectedExport)
if (namespace !== undefined) {
return {
_tag: "Success",
value: { barrel: { type: "namespace", module: moduleSpecifier, name: namespace }, flatNames }
}
}
if (parsed.value.flat.has(expectedExport)) {
return {
_tag: "Success",
value: { barrel: { type: "flat", module: moduleSpecifier }, flatNames }
}
}
if (flatNames.length > 0) {
return {
_tag: "Success",
value: { barrel: { type: "flat", module: moduleSpecifier }, flatNames }
}
}
}
}
if (directory === metadata.sourceRoot) {
break
}
directory = path.dirname(directory)
}
return { _tag: "Success", value: { barrel: null, flatNames: [] } }
}
function resolveJSDocImports(
cwd: string,
filename: string,
sourceFile: ts.SourceFile,
checker: ts.TypeChecker
): Result<ParsedJSDocImports, string> {
const absoluteFilename = path.resolve(filename)
const packageRoot = findPackageRoot(absoluteFilename)
const relativeFilename = normalizePathName(path.relative(cwd, absoluteFilename))
if (packageRoot === undefined) {
return { _tag: "Failure", error: `no package.json found for ${relativeFilename}` }
}
const metadata = readPackageMetadata(packageRoot)
if (metadata._tag === "Failure") {
return metadata
}
const relativeToSourceRoot = normalizePathName(path.relative(metadata.value.sourceRoot, absoluteFilename))
if (!isPathInside(metadata.value.sourceRoot, absoluteFilename)) {
return {
_tag: "Failure",
error: `${relativeFilename} is not under ${normalizePathName(path.relative(cwd, metadata.value.sourceRoot))}`
}
}
if (path.extname(absoluteFilename) !== ".ts" || absoluteFilename.endsWith(".d.ts")) {
return {
_tag: "Failure",
error: `${relativeFilename} is not a TypeScript source module`
}
}
const isIndex = path.basename(absoluteFilename) === "index.ts"
const moduleSubpath = isIndex
? relativeToSourceRoot.slice(0, -"index.ts".length).replace(/\/$/, "")
: relativeToSourceRoot.slice(0, -".ts".length)
const moduleExportSubpath = moduleSubpath === "" ? "." : `./${moduleSubpath}`
const moduleExportTarget = `./src/${relativeToSourceRoot}`
if (!isPackageSubpathExported(metadata.value.exports, moduleExportSubpath, moduleExportTarget)) {
return {
_tag: "Failure",
error: `package.json exports do not expose ${
packageSpecifier(metadata.value.name, moduleSubpath)
} for ${relativeFilename}`
}
}
const symbol = checker.getSymbolAtLocation(sourceFile)
const barrel = isIndex
? {
_tag: "Success",
value: {
barrel: null,
flatNames: symbol === undefined ? [] : checker.getExportsOfModule(symbol).map((item) => item.name)
}
} as const
: resolveBarrelImport(metadata.value, absoluteFilename)
if (barrel._tag === "Failure") {
return barrel
}
return {
_tag: "Success",
value: {
module: packageSpecifier(metadata.value.name, moduleSubpath),
barrel: barrel.value.barrel,
flatNames: barrel.value.flatNames
}
}
}
/**
* Reads source text from an Oxlint-compatible rule context.
*
* @category getters
* @since 4.0.0
*/
export function getSourceText(context: {
readonly sourceCode: { readonly text?: string; getText(node?: unknown): string }
}): string {
return context.sourceCode.text ?? context.sourceCode.getText()
}
/**
* Resolves the working directory from an Oxlint-compatible rule context.
*
* @category getters
* @since 4.0.0
*/
export function getCwd(context: { readonly cwd?: string; getCwd?: () => string }): string {
return context.cwd ?? context.getCwd?.() ?? process.cwd()
}
function skipWhitespace(source: string, end: number): number {
while (end > 0 && /\s/.test(source[end - 1])) {
end--
}
return end
}
function isSkippableDirectiveComment(line: string): boolean {
const trimmed = line.trim()
return trimmed.startsWith("// @ts-expect-error") ||
trimmed.startsWith("// @ts-ignore") ||
trimmed.startsWith("// @effect-diagnostics") ||
trimmed.startsWith("// eslint-disable-next-line") ||
trimmed.startsWith("// oxlint-disable-next-line")
}
function skipDirectiveComments(source: string, end: number): number {
while (end > 0) {
const lineStart = source.lastIndexOf("\n", end - 1) + 1
if (!isSkippableDirectiveComment(source.slice(lineStart, end))) {
return end
}
end = skipWhitespace(source, lineStart)
}
return end
}
/**
* Finds the JSDoc block immediately preceding an AST node.
*
* @category parsing
* @since 4.0.0
*/
export function findLeadingJSDoc(
source: string,
node: AstNode,
ignoredRange?: [number, number]
): JSDocBlock | undefined {
const end = skipDirectiveComments(source, skipWhitespace(source, node.range[0]))
if (!source.slice(0, end).endsWith("*/")) {
return undefined
}
const start = source.lastIndexOf("/*", end)
if (start === -1 || source[start + 2] !== "*") {
return undefined
}
const range: [number, number] = [start, end]
if (ignoredRange !== undefined && range[0] === ignoredRange[0] && range[1] === ignoredRange[1]) {
return undefined
}
return parseJSDocBlock(source.slice(start, end), range)
}
/**
* Parses one raw JSDoc block into the standard description, example, and tag structure.
*
* **Details**
*
* The block must have one short description paragraph, optional `When to use`, `Details`, and `Gotchas` sections in that order, then any example sections before tags. Example titles must be unique after trimming and lowercasing, each example must contain exactly one non-empty TypeScript code fence, and boundaries between sections, examples, and tags must use exactly one blank line.
*
* **Example** (Parsing a block)
*
* ```ts import.meta.vitest
* import { parseJSDoc } from "@effect/jsdocs"
*
* const rawBlock = [
* "/" + "**",
* " * A value.",
* " *",
* " * @category models",
* " * @since 4.0.0",
* " *" + "/"
* ].join("\n")
* const result = parseJSDoc(rawBlock)
*
* result._tag // => "Success"
* ```
*
* @category parsing
* @since 4.0.0
*/
export function parseJSDoc(raw: string): Result<ParsedCoreJSDoc, JSDocParseError> {
const block = parseJSDocBlock(raw, [0, raw.length])
if (block.internal) {
return { _tag: "Failure", error: { diagnostics: [diagnostic("internal", "Internal JSDoc blocks are ignored")] } }
}
if (block.diagnostics.length > 0 || block.parsed === undefined) {
return { _tag: "Failure", error: { diagnostics: block.diagnostics } }
}
return { _tag: "Success", value: block.parsed }
}
function parseLooseJSDocBlock(raw: string, range: [number, number]): JSDocBlock {
const body = raw.replace(/^\/\*\*/, "").replace(/\*\/$/, "")
const rawLines = body.split(/\r\n|\r|\n/)
const lines = rawLines.map((line) => line.replace(/^\s*\* ?/, "").trimEnd())
const normalized = trimStructuralBlankLines(lines)
const tags = parseTags(normalized)
const internal = tags.some((tag) => tag.name === "internal")
return { range, raw, lines: normalized, tags, diagnostics: [], internal }
}
function parseJSDocBlock(raw: string, range: [number, number]): JSDocBlock {
const base = parseLooseJSDocBlock(raw, range)
const { lines: normalized, tags, internal } = base
if (internal) {
return base
}
const result = parseCoreJSDoc(normalized, tags)
const block: JSDocBlock = {
...base,
range,
raw,
lines: normalized,
tags,
diagnostics: result._tag === "Failure" ? Array.from(result.error.diagnostics) : [],
internal
}
return result._tag === "Success" ? { ...block, parsed: result.value } : block
}
function trimStructuralBlankLines(lines: Array<string>): Array<string> {
let start = 0
let end = lines.length
if (lines[start]?.trim() === "") {
start++
}
if (end > start && lines[end - 1]?.trim() === "") {
end--
}
return lines.slice(start, end)
}
function parseTags(lines: Array<string>): Array<JSDocTag> {
const tags: Array<JSDocTag> = []
let current: JSDocTag | undefined
let inFence = false
for (let index = 0; index < lines.length; index++) {
const trimmed = lines[index].trim()
if (trimmed.startsWith("```")) {
inFence = !inFence
current = undefined
continue
}
if (inFence) {
continue
}
const match = /^@([A-Za-z][\w-]*)(?:\s+(.*))?$/.exec(trimmed)
if (match) {
current = { name: match[1], value: match[2]?.trim() ?? "", line: index }
tags.push(current)
continue
}
if (current !== undefined && trimmed !== "") {
current.value = current.value === "" ? trimmed : `${current.value}\n${trimmed}`
} else if (trimmed === "") {
current = undefined
}
}
return tags
}
function parseCoreJSDoc(lines: Array<string>, tags: Array<JSDocTag>): Result<ParsedCoreJSDoc, JSDocParseError> {
const diagnostics: Array<JSDocDiagnostic> = []
const firstTagLine = tags[0]?.line ?? lines.length
const content = lines.slice(0, firstTagLine)
if (lines.length === 0) {
diagnostics.push(diagnostic("missing-description", "JSDoc must include a short description"))
}
if (content.at(-1)?.trim() === "" && tags.length > 0) {
// exactly one blank before tags is validated by ensuring the last content line is blank and the previous is not blank
if (content.length < 2 || content[content.length - 2]?.trim() === "") {
diagnostics.push(
diagnostic("invalid-spacing", "JSDoc tags must be separated from description content by exactly one blank line")
)
}
} else if (tags.length > 0 && content.length > 0) {
diagnostics.push(
diagnostic("invalid-spacing", "JSDoc tags must be separated from description content by exactly one blank line")
)
}
if (content[0]?.trim() === "") {
diagnostics.push(diagnostic("leading-blank", "JSDoc must not start with a blank line"))
}
const contentWithoutTagBlank = tags.length > 0 && content.at(-1)?.trim() === "" ? content.slice(0, -1) : content
if (contentWithoutTagBlank.at(-1)?.trim() === "") {
diagnostics.push(diagnostic("trailing-blank", "JSDoc description must not end with a blank line"))
}
const parsedContent = parseDescriptionContent(contentWithoutTagBlank)
diagnostics.push(...parsedContent.diagnostics)
if (diagnostics.length > 0 || parsedContent.value === undefined) {
return { _tag: "Failure", error: { diagnostics: uniqueDiagnostics(diagnostics) } }
}
return {
_tag: "Success",
value: {
description: parsedContent.value.description,
examples: parsedContent.value.examples,
tags
}
}
}
function uniqueDiagnostics(
diagnostics: ReadonlyArray<JSDocDiagnostic>
): ReadonlyArray<JSDocDiagnostic> {
const seen = new Set<string>()
return diagnostics.filter((item) => {
const key = `${item.code}:${item.message}`
if (seen.has(key)) {
return false
}
seen.add(key)
return true
})
}
const standardHeadings = ["**When to use**", "**Details**", "**Gotchas**"] as const
type StandardHeading = typeof standardHeadings[number]
const whenToUsePrefixes = ["Use to", "Use when", "Use as", "Use with"] as const
interface ParsedContentResult {
readonly value?: {
readonly description: ParsedDescription
readonly examples: ReadonlyArray<ParsedExample>
}
readonly diagnostics: ReadonlyArray<JSDocDiagnostic>
}
function parseDescriptionContent(lines: Array<string>): ParsedContentResult {
const diagnostics: Array<JSDocDiagnostic> = []
const sections: Record<StandardHeading, string | null> = {
"**When to use**": null,
"**Details**": null,
"**Gotchas**": null
}
const examples: Array<ParsedExample> = []
const exampleTitles = new Set<string>()
let index = 0
let currentSectionOrder = -1
let examplesStarted = false
while (index < lines.length && lines[index].trim() !== "" && !isHeadingLine(lines[index])) {
if (isForbiddenMarkdownHeading(lines[index], false)) {
diagnostics.push(diagnostic("invalid-heading", "Markdown headings are not allowed in JSDoc descriptions"))
}
index++
}
const shortLines = lines.slice(0, index)
if (shortLines.length === 0 || joinBody(shortLines).trim() === "") {
diagnostics.push(diagnostic("missing-description", "JSDoc must include a short description"))
}
if (index < lines.length && lines[index].trim() === "") {
const next = lines[index + 1]
if (next !== undefined && !isHeadingLine(next)) {
diagnostics.push(diagnostic("multiple-description-paragraphs", "JSDoc short description must be one paragraph"))
}
}
while (index < lines.length) {
if (lines[index].trim() !== "") {
diagnostics.push(diagnostic("invalid-spacing", "JSDoc sections must be separated by exactly one blank line"))
break
}
if (lines[index + 1]?.trim() === "") {
diagnostics.push(diagnostic("invalid-spacing", "JSDoc sections must be separated by exactly one blank line"))
while (lines[index + 1]?.trim() === "") index++
}
index++
if (index >= lines.length) {
break
}
const line = lines[index].trim()
if (line.startsWith("**Example**")) {
examplesStarted = true
const parsed = parseExample(lines, index)
diagnostics.push(...parsed.diagnostics)
if (parsed.example !== undefined) {
const key = parsed.example.title.trim().toLowerCase()
if (exampleTitles.has(key)) {
diagnostics.push(diagnostic("duplicate-example", `Duplicate example title: ${parsed.example.title.trim()}`))
}
exampleTitles.add(key)
examples.push(parsed.example)
}
index = parsed.nextIndex
continue
}
const heading = standardHeadings.find((candidate) => candidate === line)
if (heading !== undefined) {
if (examplesStarted) {
diagnostics.push(diagnostic("section-after-example", `${heading} must appear before examples`))
}
const order = standardHeadings.indexOf(heading)
if (order <= currentSectionOrder) {
diagnostics.push(diagnostic("section-out-of-order", `${heading} is out of order or duplicated`))
}
currentSectionOrder = Math.max(currentSectionOrder, order)
if (sections[heading] !== null) {
diagnostics.push(diagnostic("duplicate-section", `${heading} may appear at most once`))
}
const parsed = parseSection(lines, index)
diagnostics.push(...parsed.diagnostics)
sections[heading] = parsed.body
index = parsed.nextIndex
continue
}
if (isNearMissHeading(line)) {
diagnostics.push(diagnostic("invalid-heading", `Invalid JSDoc section heading: ${line}`))
index++
continue
}
if (isBoldOnlyLine(line)) {
diagnostics.push(diagnostic("unknown-heading", `Unknown JSDoc section heading: ${line}`))
index++
continue
}
if (isForbiddenMarkdownHeading(line, false)) {
diagnostics.push(diagnostic("invalid-heading", "Markdown headings are not allowed in JSDoc descriptions"))
index++
continue
}
diagnostics.push(
diagnostic("invalid-description", "JSDoc description content must appear under a standard section heading")
)
index++
}
const whenToUse = sections["**When to use**"]
if (whenToUse !== null && !hasWhenToUsePrefix(whenToUse)) {
diagnostics.push(
diagnostic(
"when-to-use-format",
`**When to use** must start with one of: ${whenToUsePrefixes.map((prefix) => `\`${prefix}\``).join(", ")}`
)
)
}
if (diagnostics.length > 0) {
return { diagnostics }
}
return {
value: {
description: {
short: joinBody(shortLines),
whenToUse: sections["**When to use**"],
details: sections["**Details**"],
gotchas: sections["**Gotchas**"]
},
examples
},
diagnostics
}
}
function hasWhenToUsePrefix(text: string): boolean {
const trimmed = text.trimStart()
return whenToUsePrefixes.some((prefix) => trimmed === prefix || trimmed.startsWith(`${prefix} `))
}
function parseSection(lines: Array<string>, headingIndex: number): {
readonly body: string | null
readonly nextIndex: number
readonly diagnostics: ReadonlyArray<JSDocDiagnostic>
} {
const diagnostics: Array<JSDocDiagnostic> = []
if (lines[headingIndex + 1]?.trim() !== "") {
diagnostics.push(
diagnostic("invalid-spacing", `${lines[headingIndex].trim()} must be followed by exactly one blank line`)
)
}
let index = headingIndex + 2
const bodyStart = index
let inFence = false
while (index < lines.length) {
const trimmed = lines[index].trim()
if (trimmed.startsWith("```")) {
if (isTypeScriptFence(trimmed)) {
diagnostics.push(diagnostic("loose-ts-fence", "TypeScript examples must use **Example** (Title) sections"))
}
inFence = !inFence
}
if (!inFence && trimmed === "" && isHeadingLine(lines[index + 1])) {
break
}
if (!inFence && trimmed !== "" && isForbiddenMarkdownHeading(trimmed, false)) {
diagnostics.push(diagnostic("invalid-heading", "Markdown headings are not allowed in JSDoc descriptions"))
}
if (
!inFence && isBoldOnlyLine(trimmed) && !standardHeadings.includes(trimmed as StandardHeading) &&
!trimmed.startsWith("**Example**")
) {
diagnostics.push(diagnostic("unknown-heading", `Unknown JSDoc section heading: ${trimmed}`))
}
index++
}
const bodyLines = lines.slice(bodyStart, index)
if (joinBody(bodyLines).trim() === "") {
diagnostics.push(diagnostic("empty-section", `${lines[headingIndex].trim()} must have a non-empty body`))
}
if (bodyLines.at(-1)?.trim() === "") {
diagnostics.push(diagnostic("invalid-spacing", "Section bodies must not end with extra blank lines"))
}
return { body: joinBody(bodyLines), nextIndex: index, diagnostics }
}
const isTypeScriptFence = (line: string): boolean => /^```ts(?:\s.*)?$/.test(line)
function parseExample(lines: Array<string>, headingIndex: number): {
readonly example?: ParsedExample
readonly nextIndex: number
readonly diagnostics: ReadonlyArray<JSDocDiagnostic>
} {
const diagnostics: Array<JSDocDiagnostic> = []
const heading = lines[headingIndex].trim()
const match = /^\*\*Example\*\* \((.+)\)$/.exec(heading)
if (!match || match[1].trim() === "") {
diagnostics.push(diagnostic("malformed-example", "TypeScript examples must use **Example** (Title)"))
}
if (lines[headingIndex + 1]?.trim() !== "") {
diagnostics.push(diagnostic("invalid-spacing", "Example headings must be followed by exactly one blank line"))
}
let index = headingIndex + 2
const bodyStart = index
let fenceIndex = -1
while (index < lines.length) {
const trimmed = lines[index].trim()
if (isTypeScriptFence(trimmed)) {
fenceIndex = index
break
}
if (trimmed.startsWith("```")) {
diagnostics.push(diagnostic("malformed-example", "Examples may only contain one TypeScript code fence"))
}
if (trimmed === "" && isHeadingLine(lines[index + 1])) {
break
}
if (trimmed.startsWith("@")) {
break
}
index++
}
if (fenceIndex === -1) {
diagnostics.push(diagnostic("malformed-example", "Examples must include a non-empty ```ts fence"))
return { nextIndex: index, diagnostics }
}
const bodyLines = lines.slice(bodyStart, fenceIndex)
const nonEmptyBody = joinBody(bodyLines).trim() !== ""
if (nonEmptyBody && bodyLines.at(-1)?.trim() !== "") {
diagnostics.push(
diagnostic("invalid-spacing", "Example prose must be separated from code by exactly one blank line")
)
}
const prose = nonEmptyBody ? joinBody(bodyLines.slice(0, bodyLines.at(-1)?.trim() === "" ? -1 : undefined)) : null
index = fenceIndex + 1
const codeStart = index
while (index < lines.length && lines[index].trim() !== "```") {
if (isTypeScriptFence(lines[index].trim())) {
diagnostics.push(diagnostic("malformed-example", "Examples must contain exactly one TypeScript code fence"))
}
index++
}
const codeLines = lines.slice(codeStart, index)
if (index >= lines.length) {
diagnostics.push(diagnostic("malformed-example", "Examples must close the TypeScript code fence"))
}
if (joinBody(codeLines).trim() === "") {
diagnostics.push(diagnostic("malformed-example", "Examples must include non-empty TypeScript code"))
}
index++
if (index < lines.length && lines[index].trim() !== "" && !lines[index].trim().startsWith("@")) {
diagnostics.push(
diagnostic("invalid-spacing", "Examples must be separated from following content by exactly one blank line")
)
}
const result = { nextIndex: index, diagnostics }
return match
? { ...result, example: { title: match[1].trim(), body: prose, code: joinBody(codeLines) } }
: result
}
function parseModuleExamples(block: JSDocBlock): {
readonly examples: ReadonlyArray<ParsedExample>
readonly diagnostics: ReadonlyArray<JSDocDiagnostic>
} {
const diagnostics: Array<JSDocDiagnostic> = []
const examples: Array<ParsedExample> = []
const exampleTitles = new Set<string>()
const firstTagLine = block.tags[0]?.line ?? block.lines.length
const lines = block.lines.slice(0, firstTagLine)
let index = 0
while (index < lines.length) {
const trimmed = lines[index].trim()
if (trimmed.startsWith("**Example**")) {
const parsed = parseExample(lines, index)
diagnostics.push(...parsed.diagnostics)
if (parsed.example !== undefined) {
const key = parsed.example.title.trim().toLowerCase()
if (exampleTitles.has(key)) {
diagnostics.push(diagnostic("duplicate-example", `Duplicate example title: ${parsed.example.title.trim()}`))
}
exampleTitles.add(key)
examples.push(parsed.example)
}
index = Math.max(parsed.nextIndex, index + 1)
continue
}
if (trimmed.startsWith("```")) {
diagnostics.push(
diagnostic("loose-ts-fence", "Code fences in module JSDoc must use **Example** (Title) sections")
)
index++
while (index < lines.length && !lines[index].trim().startsWith("```")) index++
if (index < lines.length) index++
continue
}
index++
}
return { examples, diagnostics }
}
function joinBody(lines: ReadonlyArray<string>): string {
let start = 0
let end = lines.length
while (start < end && lines[start]?.trim() === "") start++
while (end > start && lines[end - 1]?.trim() === "") end--
return lines.slice(start, end).join("\n")
}
function isHeadingLine(line: string | undefined): boolean {
if (line === undefined) return false
const trimmed = line.trim()
return standardHeadings.includes(trimmed as StandardHeading) || trimmed.startsWith("**Example**") ||
isNearMissHeading(trimmed) || isBoldOnlyLine(trimmed) || isForbiddenMarkdownHeading(trimmed, false)
}
function isNearMissHeading(line: string): boolean {
return /^\*\*(When to use|When To Use|Details|Gotchas).*\*\*/.test(line) &&
!standardHeadings.includes(line as StandardHeading)
}
function isBoldOnlyLine(line: string): boolean {
return /^\*\*[^*]+\*\*(?:\s*)$/.test(line)
}
function isForbiddenMarkdownHeading(line: string, inFence: boolean): boolean {
return !inFence && /^#{1,6}\s+/.test(line.trim())
}
function parseSeeTag(value: string): ParsedSeeTag {
return { text: value, links: extractParsedInlineLinks(value) }
}
function extractParsedInlineLinks(source: string): ReadonlyArray<ParsedInlineLink> {
const links: Array<ParsedInlineLink> = []
let index = source.indexOf("{@link")
while (index !== -1) {
if (!isInlineLinkStart(source, index)) {
index = source.indexOf("{@link", index + 1)
continue
}
const end = source.indexOf("}", index + "{@link".length)
if (end === -1) {
break
}
const raw = source.slice(index, end + 1)
const content = raw.slice("{@link".length, -1).trim()
const pipeIndex = content.indexOf("|")
const beforeLabel = pipeIndex === -1 ? content : content.slice(0, pipeIndex).trim()
const target = beforeLabel.split(/\s+/)[0] ?? ""
const text = pipeIndex === -1
? beforeLabel.slice(target.length).trim() || null
: content.slice(pipeIndex + 1).trim() || null
links.push({ raw, target, text })
index = source.indexOf("{@link", end + 1)
}
return links
}
function buildTags(
scope: DocScope,
tags: ReadonlyArray<JSDocTag>,
requireStability = false
): Result<ParsedModuleTags | ParsedDeclarationTags | ParsedNamespaceTags | ParsedMemberTags, JSDocParseError> {
const diagnostics: Array<JSDocDiagnostic> = []
const allowed = scope === "declaration"
? new Set(["deprecated", "see", "stability", "category", "since"])
: scope === "member"
? new Set(["deprecated", "default", "see", "stability", "since"])
: scope === "module"
? new Set(["deprecated", "see", "stability", "since"])
: new Set(["deprecated", "see", "stability", "category", "since"])
let previousOrder = -1
const values = new Map<string, Array<string>>()
for (const tag of tags) {
if (tag.name === "internal") {
continue
}
if (tag.name === "example") {
diagnostics.push(
diagnostic("forbidden-tag", "@example is not allowed; use a canonical **Example** (Title) section")
)
continue
}
if (!allowed.has(tag.name)) {
diagnostics.push(
diagnostic(
"forbidden-tag",
`@${tag.name} is not allowed in ${scope === "namespace-declaration" ? "namespace" : scope} JSDoc`
)
)
continue
}
const order = tagOrder.get(tag.name) ?? previousOrder
if (order < previousOrder) {
diagnostics.push(diagnostic("tag-out-of-order", `@${tag.name} is out of order in JSDoc`))
}
previousOrder = Math.max(previousOrder, order)
values.set(tag.name, [...values.get(tag.name) ?? [], tag.value.trim()])
}
const singletonTags = scope === "member"
? ["deprecated", "default", "stability", "since"]
: ["deprecated", "stability", "category", "since"]
for (const tag of singletonTags) {
if ((values.get(tag)?.length ?? 0) > 1) {
diagnostics.push(diagnostic("duplicate-tag", `JSDoc blocks may contain at most one @${tag} tag`))
}
}
const see = values.get("see") ?? []
for (const value of see) {
if (value === "") {
diagnostics.push(diagnostic("empty-tag", "@see must include a value"))
}
}
const deprecated = values.get("deprecated")?.[0] ?? null
const stability = values.get("stability")?.[0]
if (stability !== undefined && stability !== "stable" && stability !== "unstable" && stability !== "experimental") {
diagnostics.push(
diagnostic("invalid-stability", "@stability must have the value stable, unstable, or experimental")
)
}
if (requireStability && stability === undefined) {
diagnostics.push(
diagnostic(
"missing-tag",
scope === "module" ? "Module JSDoc must include @stability" : "Public JSDoc must include @stability"
)
)
}
const resolvedStability: JSDocStability = stability === "unstable" || stability === "experimental"
? stability
: "stable"
if (deprecated === "") diagnostics.push(diagnostic("empty-tag", "@deprecated must include a message"))
const since = values.get("since")?.[0] ?? null
if ((scope === "declaration" || scope === "namespace" || scope === "namespace-declaration") && since === null) {
diagnostics.push(
diagnostic(
"missing-tag",
scope === "declaration" ? "Public JSDoc must include @since" : "Namespace JSDoc must include @since"
)
)
}
if (scope === "module" && since === null) {
diagnostics.push(diagnostic("missing-tag", "Module JSDoc must include @since"))
}
if (since !== null && !stableSemverRegex.test(since)) {
diagnostics.push(diagnostic("invalid-since", "@since must be a stable semver version like 1.2.3"))
}
if (scope === "declaration") {
const category = values.get("category")?.[0] ?? null
if (category === null) diagnostics.push(diagnostic("missing-tag", "Public JSDoc must include @category"))
if (category === "") diagnostics.push(diagnostic("empty-tag", "@category must include a value"))
if (diagnostics.length > 0 || category === null || since === null) {
return { _tag: "Failure", error: { diagnostics } }
}
return {
_tag: "Success",
value: { category, since, stability: resolvedStability, deprecated, see: see.map(parseSeeTag) }
}
}
if (scope === "member") {
const defaultValue = values.get("default")?.[0] ?? null
if (defaultValue === "") diagnostics.push(diagnostic("empty-tag", "@default must include a value"))
if (diagnostics.length > 0) return { _tag: "Failure", error: { diagnostics } }
return {
_tag: "Success",
value: { since, stability: resolvedStability, default: defaultValue, deprecated, see: see.map(parseSeeTag) }
}
}
if (scope === "module") {
if (diagnostics.length > 0 || since === null) return { _tag: "Failure", error: { diagnostics } }
return { _tag: "Success", value: { since, stability: resolvedStability, deprecated, see: see.map(parseSeeTag) } }
}
const category = values.get("category")?.[0] ?? null
if (category === "") diagnostics.push(diagnostic("empty-tag", "@category must include a value"))
if (diagnostics.length > 0 || since === null) return { _tag: "Failure", error: { diagnostics } }
return {
_tag: "Success",
value: { category, since, stability: resolvedStability, deprecated, see: see.map(parseSeeTag) }
}
}
function formatDiagnostic(diagnostic: ts.Diagnostic): string {
return ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")
}
function parseTsConfig(tsconfigPath: string): ParsedConfigResult {
const config = ts.readConfigFile(tsconfigPath, ts.sys.readFile)
if (config.error !== undefined) {
return { error: `Unable to read TypeScript config ${tsconfigPath}: ${formatDiagnostic(config.error)}` }
}
const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, path.dirname(tsconfigPath))
if (parsed.errors.length > 0) {
return {
error: `Unable to parse TypeScript config ${tsconfigPath}: ${parsed.errors.map(formatDiagnostic).join("; ")}`
}
}
return { parsed }
}
function collectTsConfigFiles(tsconfigPath: string, seen: Set<string>, fileNames: Set<string>): ParsedConfigResult {
if (seen.has(tsconfigPath)) return {}
seen.add(tsconfigPath)
const result = parseTsConfig(tsconfigPath)
if (result.error !== undefined || result.parsed === undefined) return result
for (const fileName of result.parsed.fileNames) fileNames.add(fileName)
for (const reference of result.parsed.projectReferences ?? []) {
const referenceResult = collectTsConfigFiles(ts.resolveProjectReferencePath(reference), seen, fileNames)
if (referenceResult.error !== undefined) return referenceResult
}
return result
}
/**
* Loads and caches the TypeScript program for a project configuration.
*
* @category constructors
* @since 4.0.0
*/
export function getProgram(tsconfigPath: string): ProgramCacheEntry {
const cached = programCache.get(tsconfigPath)
if (cached !== undefined) return cached
const fileNames = new Set<string>()
const result = collectTsConfigFiles(tsconfigPath, new Set(), fileNames)
if (result.error !== undefined || result.parsed === undefined) {
const entry = { error: result.error ?? `Unable to parse TypeScript config ${tsconfigPath}`, reported: false }
programCache.set(tsconfigPath, entry)
return entry
}
const program = ts.createProgram(Array.from(fileNames), result.parsed.options)
const entry = { program, reported: false }
programCache.set(tsconfigPath, entry)
return entry
}
function resolveJSDocLinkSymbol(
link: ts.JSDocLink,
checker: ts.TypeChecker
): ts.Symbol | undefined {
return link.name === undefined ? undefined : checker.getSymbolAtLocation(link.name)
}
function isInlineLinkStart(source: string, index: number): boolean {
if (!source.startsWith("{@link", index)) return false
const next = source[index + "{@link".length]
return next === undefined || /\s|}/.test(next)
}
function hasInlineLink(block: JSDocBlock): boolean {
return block.lines.some((line) => {
let index = line.indexOf("{@link")
while (index !== -1) {
if (isInlineLinkStart(line, index)) return true
index = line.indexOf("{@link", index + 1)
}
return false
})
}
function extractInlineLinkTarget(linkText: string): string {
const content = linkText.slice("{@link".length, linkText.endsWith("}") ? -1 : undefined).trim()
const pipeIndex = content.indexOf("|")
const beforeLabel = pipeIndex === -1 ? content : content.slice(0, pipeIndex).trim()
return beforeLabel.split(/\s+/)[0] ?? ""
}
function malformedInlineLinks(block: JSDocBlock): Array<string> {
const source = block.lines.join("\n")
const malformed: Array<string> = []
let index = source.indexOf("{@link")
while (index !== -1) {
if (!isInlineLinkStart(source, index)) {
index = source.indexOf("{@link", index + 1)
continue
}
const end = source.indexOf("}", index + "{@link".length)
const text = end === -1 ? source.slice(index).split(/\r?\n/, 1)[0] : source.slice(index, end + 1)
if (end === -1 || extractInlineLinkTarget(text) === "") malformed.push(text)
index = source.indexOf("{@link", end === -1 ? index + 1 : end + 1)
}
return malformed
}
function collectJSDocLinks(sourceFile: ts.SourceFile, block: JSDocBlock): Array<ts.JSDocLink> {
const links: Array<ts.JSDocLink> = []
function inspectJSDoc(node: ts.Node) {
for (const jsdoc of (node as { readonly jsDoc?: ReadonlyArray<ts.JSDoc> }).jsDoc ?? []) {
if (jsdoc.pos !== block.range[0] || jsdoc.end !== block.range[1]) continue
ts.forEachChild(jsdoc, function visit(child) {
if (ts.isJSDocLink(child)) links.push(child)
ts.forEachChild(child, visit)
})
}
}
function visit(node: ts.Node) {
inspectJSDoc(node)
ts.forEachChild(node, visit)
}
visit(sourceFile)
return links
}
function collectJSDocSeeLinks(sourceFile: ts.SourceFile, block: JSDocBlock): Array<ts.JSDocLink> {
const links: Array<ts.JSDocLink> = []
function inspectJSDoc(node: ts.Node) {
for (const jsdoc of (node as { readonly jsDoc?: ReadonlyArray<ts.JSDoc> }).jsDoc ?? []) {
if (jsdoc.pos !== block.range[0] || jsdoc.end !== block.range[1]) continue
ts.forEachChild(jsdoc, function visit(child) {
if (ts.isJSDocSeeTag(child)) {
ts.forEachChild(child, function visitSeeTag(seeTagChild) {
if (ts.isJSDocLink(seeTagChild)) links.push(seeTagChild)
ts.forEachChild(seeTagChild, visitSeeTag)
})
return
}
ts.forEachChild(child, visit)
})
}
}
function visit(node: ts.Node) {
inspectJSDoc(node)
ts.forEachChild(node, visit)
}
visit(sourceFile)
return links
}
function resolvedSymbolTarget(symbol: ts.Symbol, checker: ts.TypeChecker): ts.Symbol {
return (symbol.flags & ts.SymbolFlags.Alias) === 0 ? symbol : checker.getAliasedSymbol(symbol)
}
function isLocalSourceFile(cwd: string, sourceFile: ts.SourceFile): boolean {
if (sourceFile.isDeclarationFile) return false
const relative = path.relative(cwd, sourceFile.fileName)
return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))
}
function symbolDeclarations(symbol: ts.Symbol, checker: ts.TypeChecker): ReadonlyArray<ts.Declaration> {
const target = resolvedSymbolTarget(symbol, checker)
const declarations = new Set<ts.Declaration>()
if (target.valueDeclaration !== undefined) declarations.add(target.valueDeclaration)
for (const declaration of target.declarations ?? []) declarations.add(declaration)
return Array.from(declarations)
}
function symbolHasPublicJSDoc(symbol: ts.Symbol, checker: ts.TypeChecker): boolean {
return symbolDeclarations(symbol, checker).some((declaration) => {
const block = getNodeJSDoc(declaration)
return block !== undefined && !block.internal && block.parsed !== undefined
})
}
function isMemberDeclaration(declaration: ts.Declaration): boolean {
return ts.isPropertySignature(declaration) || ts.isMethodSignature(declaration) ||
ts.isPropertyDeclaration(declaration) || ts.isMethodDeclaration(declaration) ||
ts.isGetAccessorDeclaration(declaration) || ts.isSetAccessorDeclaration(declaration)
}
function undocumentedSeeLinkTarget(
symbol: ts.Symbol,
checker: ts.TypeChecker,
cwd: string
): ts.Declaration | undefined {
const localDeclarations = symbolDeclarations(symbol, checker).filter((declaration) =>
isMemberDeclaration(declaration) && isLocalSourceFile(cwd, declaration.getSourceFile())
)
if (localDeclarations.length === 0 || symbolHasPublicJSDoc(symbol, checker)) return undefined
return localDeclarations[0]
}
function inlineLinkSymbol(
symbol: ts.Symbol,
cwd: string,
checker: ts.TypeChecker
): ParsedInlineLinkSymbol | undefined {
const target = resolvedSymbolTarget(symbol, checker)
const declaration = target.valueDeclaration ?? target.declarations?.[0]
if (declaration === undefined) return undefined
return {
file: normalizeFile(cwd, declaration.getSourceFile().fileName),
range: nodeRange(declaration)
}
}
function attachSeeLinkSymbolsFromSourceFile<
T extends ParsedModuleTags | ParsedDeclarationTags | ParsedNamespaceTags | ParsedMemberTags
>(
tags: T,
sourceFile: ts.SourceFile,
block: JSDocBlock,
linkContext: { readonly checker: ts.TypeChecker; readonly entry: ProgramCacheEntry; readonly cwd: string }
): T {
const resolved = new Map<
string,
Array<{ readonly range: readonly [number, number]; readonly symbol?: ParsedInlineLinkSymbol }>
>()
for (const link of collectJSDocLinks(sourceFile, block)) {
const text = link.getText(sourceFile)
const target = extractInlineLinkTarget(text)
if (target === "" || urlRegex.test(target)) continue
const symbol = resolveJSDocLinkSymbol(link, linkContext.checker)
const info = symbol === undefined ? undefined : inlineLinkSymbol(symbol, linkContext.cwd, linkContext.checker)
const items = resolved.get(text) ?? []
items.push(info === undefined ? { range: [link.pos, link.end] } : { range: [link.pos, link.end], symbol: info })
resolved.set(text, items)
}
return {
...tags,
see: tags.see.map((tag) => ({
...tag,
links: tag.links.map((link) => {
const items = resolved.get(link.raw)
const info = items?.shift()
if (info === undefined) return link
return info.symbol === undefined
? { ...link, range: info.range }
: { ...link, range: info.range, symbol: info.symbol }
})
}))
}
}
function attachSeeLinkSymbols<T extends ParsedDeclarationTags | ParsedNamespaceTags | ParsedMemberTags>(
tags: T,
node: ts.Node,
block: JSDocBlock,
linkContext: { readonly checker: ts.TypeChecker; readonly entry: ProgramCacheEntry; readonly cwd: string }
): T {
return attachSeeLinkSymbolsFromSourceFile(tags, node.getSourceFile(), block, linkContext)
}
/**
* JSDoc diagnostic paired with its source range.
*
* @category models
* @since 4.0.0
*/
export interface JSDocModelDiagnostic extends JSDocDiagnostic {
readonly range: readonly [number, number]
}
/**
* Parsed JSDoc and diagnostics for one source file in a model.
*
* @category models
* @since 4.0.0
*/
export interface JSDocModelFile extends ParsedJSDocFile {
readonly file: string
readonly hash: string
readonly diagnostics: ReadonlyArray<JSDocModelDiagnostic>
readonly imports?: ParsedJSDocImports
}
/**
* Versioned output of a repository JSDoc extraction.
*
* @category models
* @since 4.0.0
*/
export interface JSDocModel {
readonly version: 3
readonly generatedBy: "@effect/jsdocs"
readonly generatedAt: string
readonly inputHash?: string
readonly files: ReadonlyArray<JSDocModelFile>
readonly apis: ReadonlyArray<JSDocApi>
}
/**
* File selection and output configuration for JSDoc extraction.
*
* @category configuration
* @since 4.0.0
*/
export interface JSDocConfig {
readonly tsconfig: string
readonly include: ReadonlyArray<string>
readonly exclude?: ReadonlyArray<string>
readonly output: string
}
/**
* JSDoc extraction configuration with an optional working directory.
*
* @category configuration
* @since 4.0.0
*/
export interface ExtractJSDocsOptions extends JSDocConfig {
readonly cwd?: string
}
function addInputFile(files: Set<string>, filename: string) {
const normalized = path.resolve(filename)
if (fs.existsSync(normalized) && fs.statSync(normalized).isFile()) {
files.add(normalized)
}
}
/**
* Computes the cache key for the configured JSDoc extraction inputs.
*
* @category hashing
* @since 4.0.0
*/
export function computeJSDocInputHash(options: ExtractJSDocsOptions): string {
const cwd = path.resolve(options.cwd ?? process.cwd())
const hash = crypto.createHash("sha256")
const files = new Set<string>()
hash.update(JSON.stringify({
tsconfig: options.tsconfig,
include: options.include,
exclude: options.exclude ?? [],
output: options.output
}))
addInputFile(files, path.join(cwd, "jsdocs.config.json"))
addInputFile(files, path.resolve(cwd, options.tsconfig))
for (
const filename of globSync([...options.include], {
cwd,
absolute: true,
nodir: true,
ignore: ["**/node_modules/**"]
})
) {
addInputFile(files, filename)
}
for (
const filename of globSync([
"package.json",
"packages/**/package.json",
"tsconfig*.json",
"packages/**/tsconfig*.json"
], {
cwd,
absolute: true,
nodir: true,
ignore: ["**/node_modules/**"]
})
) {
addInputFile(files, filename)
}
for (const filename of Array.from(files).sort()) {
hash.update("\0")
hash.update(normalizeFile(cwd, filename))
hash.update("\0")
hash.update(hashSource(fs.readFileSync(filename, "utf8")))
}
return hash.digest("hex")
}
function isIdentifierName(value: string): boolean {
return /^[$A-Z_a-z][$\w]*$/.test(value)
}
function renderInlineLinks(text: string): string {
return text.replace(/\{@link\s+([^}]+)\}/g, (_match, content: string) => {
const pipeIndex = content.indexOf("|")
const beforeLabel = pipeIndex === -1 ? content.trim() : content.slice(0, pipeIndex).trim()
const target = beforeLabel.split(/\s+/)[0] ?? ""
const label = pipeIndex === -1
? beforeLabel.slice(target.length).trim() || target
: content.slice(pipeIndex + 1).trim() || target
return `\`${label.replace(/:var$/, "")}\``
})
}
function renderDescription(description: ParsedDescription): ParsedDescription {
return {
short: renderInlineLinks(description.short),
whenToUse: description.whenToUse === null ? null : renderInlineLinks(description.whenToUse),
details: description.details === null ? null : renderInlineLinks(description.details),
gotchas: description.gotchas === null ? null : renderInlineLinks(description.gotchas)
}
}
function renderExamples(examples: ReadonlyArray<ParsedExample>): ReadonlyArray<ParsedExample> {
return examples.map((example) => ({
...example,
body: example.body === null ? null : renderInlineLinks(example.body)
}))
}
function apiTags(
tags: ParsedDeclarationTags | ParsedNamespaceTags | ParsedMemberTags
): JSDocApiTags {
return {
category: "category" in tags ? tags.category : null,
since: tags.since,
stability: tags.stability,
deprecated: tags.deprecated,
default: "default" in tags ? tags.default : null
}
}
function unresolvedSeeTag(tag: ParsedSeeTag): JSDocApiSeeTag {
return {
text: renderInlineLinks(tag.text),
links: tag.links.map((link) => ({
...link,
resolution: { _tag: "Unresolved", reason: "not-found", candidates: [] }
}))
}
}
function unresolvedSee(tags: ReadonlyArray<ParsedSeeTag>): ReadonlyArray<JSDocApiSeeTag> {
return tags.map(unresolvedSeeTag)
}