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) }