3365 lines
118 KiB
TypeScript
3365 lines
118 KiB
TypeScript
/*
|
|
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]
|
|
}
|
|
|
|
interface ParsedModuleTags {
|
|
readonly since: string
|
|
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 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 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 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>
|
|
}
|
|
|
|
export type JSDocApiKind = "root-declaration" | "namespace" | "namespace-declaration" | "member"
|
|
|
|
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
|
|
}
|
|
|
|
export type JSDocApiSeeLinkResolution =
|
|
| {
|
|
readonly _tag: "Resolved"
|
|
readonly apiId: string
|
|
readonly apiFqn: string
|
|
}
|
|
| {
|
|
readonly _tag: "Unresolved"
|
|
readonly reason: "not-found" | "ambiguous"
|
|
readonly candidates: ReadonlyArray<string>
|
|
}
|
|
|
|
export interface JSDocApiSeeLink extends ParsedInlineLink {
|
|
readonly resolution: JSDocApiSeeLinkResolution
|
|
}
|
|
|
|
export interface JSDocApiSeeTag {
|
|
readonly text: string
|
|
readonly links: ReadonlyArray<JSDocApiSeeLink>
|
|
}
|
|
|
|
export interface JSDocApiTags {
|
|
readonly category: string | null
|
|
readonly since: string | null
|
|
readonly deprecated: string | null
|
|
readonly default: string | null
|
|
}
|
|
|
|
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],
|
|
["category", 3],
|
|
["since", 4]
|
|
])
|
|
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, "\\$&")
|
|
}
|
|
|
|
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}$`)
|
|
}
|
|
|
|
/**
|
|
* 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
|
|
): 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.basename(absoluteFilename) === "index.ts") {
|
|
return {
|
|
_tag: "Failure",
|
|
error: `${relativeFilename} is a barrel file; exclude it from jsdocs`
|
|
}
|
|
}
|
|
if (path.extname(absoluteFilename) !== ".ts" || absoluteFilename.endsWith(".d.ts")) {
|
|
return {
|
|
_tag: "Failure",
|
|
error: `${relativeFilename} is not a TypeScript source module`
|
|
}
|
|
}
|
|
const moduleSubpath = relativeToSourceRoot.slice(0, -".ts".length)
|
|
const moduleExportSubpath = `./${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 barrel = 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
|
|
}
|
|
}
|
|
}
|
|
|
|
export function getSourceText(context: {
|
|
readonly sourceCode: { readonly text?: string; getText(node?: unknown): string }
|
|
}): string {
|
|
return context.sourceCode.text ?? context.sourceCode.getText()
|
|
}
|
|
|
|
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
|
|
}
|
|
|
|
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
|
|
* const rawBlock = [
|
|
* "/" + "**",
|
|
* " * A value.",
|
|
* " *",
|
|
* " * @category models",
|
|
* " * @since 4.0.0",
|
|
* " *" + "/"
|
|
* ].join("\n")
|
|
* const result = parseJSDoc(rawBlock)
|
|
* ```
|
|
*
|
|
* @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 (trimmed === "```ts") {
|
|
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 }
|
|
}
|
|
|
|
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 (trimmed === "```ts") {
|
|
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 (lines[index].trim() === "```ts") {
|
|
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>
|
|
): Result<ParsedModuleTags | ParsedDeclarationTags | ParsedNamespaceTags | ParsedMemberTags, JSDocParseError> {
|
|
const diagnostics: Array<JSDocDiagnostic> = []
|
|
const allowed = scope === "declaration"
|
|
? new Set(["deprecated", "see", "category", "since"])
|
|
: scope === "member"
|
|
? new Set(["deprecated", "default", "see", "since"])
|
|
: scope === "module"
|
|
? new Set(["deprecated", "see", "since"])
|
|
: new Set(["deprecated", "see", "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", "since"] : ["deprecated", "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
|
|
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, 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, 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, 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, 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
|
|
}
|
|
|
|
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)
|
|
}
|
|
|
|
export interface JSDocModelDiagnostic extends JSDocDiagnostic {
|
|
readonly range: readonly [number, number]
|
|
}
|
|
|
|
export interface JSDocModelFile extends ParsedJSDocFile {
|
|
readonly file: string
|
|
readonly hash: string
|
|
readonly diagnostics: ReadonlyArray<JSDocModelDiagnostic>
|
|
readonly imports?: ParsedJSDocImports
|
|
}
|
|
|
|
export interface JSDocModel {
|
|
readonly version: 2
|
|
readonly generatedBy: "@effect/jsdocs"
|
|
readonly generatedAt: string
|
|
readonly inputHash?: string
|
|
readonly files: ReadonlyArray<JSDocModelFile>
|
|
readonly apis: ReadonlyArray<JSDocApi>
|
|
}
|
|
|
|
export interface JSDocConfig {
|
|
readonly tsconfig: string
|
|
readonly include: ReadonlyArray<string>
|
|
readonly exclude?: ReadonlyArray<string>
|
|
readonly output: string
|
|
}
|
|
|
|
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)
|
|
}
|
|
}
|
|
|
|
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,
|
|
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)
|
|
}
|
|
|
|
function apiId(kind: JSDocApiKind, bucket: ExportBucket | null, apiFqn: string): string {
|
|
return `${kind}:${bucket ?? "none"}:${apiFqn}`
|
|
}
|
|
|
|
function importGuidance(
|
|
imports: ParsedJSDocImports,
|
|
kind: JSDocApiKind,
|
|
bucket: ExportBucket | null,
|
|
apiName: string
|
|
): JSDocApiImportGuidance | null {
|
|
if (kind !== "root-declaration" || bucket !== "value" || !isIdentifierName(apiName)) {
|
|
return null
|
|
}
|
|
if (imports.flatNames.includes(apiName) && imports.barrel !== null) {
|
|
return {
|
|
style: "named-barrel",
|
|
importDeclaration: `import { ${apiName} } from "${imports.barrel.module}"`,
|
|
usage: apiName
|
|
}
|
|
}
|
|
if (imports.barrel?.type === "namespace") {
|
|
if (!isIdentifierName(imports.barrel.name)) return null
|
|
return {
|
|
style: "namespace-barrel",
|
|
importDeclaration: `import { ${imports.barrel.name} } from "${imports.barrel.module}"`,
|
|
usage: `${imports.barrel.name}.${apiName}`
|
|
}
|
|
}
|
|
if (imports.barrel?.type === "flat") {
|
|
return {
|
|
style: "named-barrel",
|
|
importDeclaration: `import { ${apiName} } from "${imports.barrel.module}"`,
|
|
usage: apiName
|
|
}
|
|
}
|
|
return {
|
|
style: "named-module",
|
|
importDeclaration: `import { ${apiName} } from "${imports.module}"`,
|
|
usage: apiName
|
|
}
|
|
}
|
|
|
|
function makeApi(input: {
|
|
readonly file: JSDocModelFile
|
|
readonly imports: ParsedJSDocImports
|
|
readonly kind: JSDocApiKind
|
|
readonly bucket: ExportBucket | null
|
|
readonly apiName: string
|
|
readonly localName: string
|
|
readonly signature: string | null
|
|
readonly parentApiName: string | null
|
|
readonly namespacePath: ReadonlyArray<string>
|
|
readonly memberPath: ReadonlyArray<string>
|
|
readonly sourcePath: ReadonlyArray<string | number>
|
|
readonly sourceRange: readonly [number, number]
|
|
readonly description: ParsedDescription
|
|
readonly examples: ReadonlyArray<ParsedExample>
|
|
readonly tags: ParsedDeclarationTags | ParsedNamespaceTags | ParsedMemberTags
|
|
}): JSDocApi {
|
|
const apiFqn = `${input.imports.module}.${input.apiName}`
|
|
return {
|
|
id: apiId(input.kind, input.bucket, apiFqn),
|
|
kind: input.kind,
|
|
moduleName: input.imports.module,
|
|
apiName: input.apiName,
|
|
localName: input.localName,
|
|
signature: input.signature,
|
|
parentApiName: input.parentApiName,
|
|
apiFqn,
|
|
hasFqnCollision: false,
|
|
bucket: input.bucket,
|
|
importable: input.kind === "root-declaration",
|
|
namespacePath: input.namespacePath,
|
|
memberPath: input.memberPath,
|
|
source: {
|
|
file: input.file.file,
|
|
path: input.sourcePath,
|
|
range: input.sourceRange
|
|
},
|
|
description: renderDescription(input.description),
|
|
examples: renderExamples(input.examples),
|
|
tags: apiTags(input.tags),
|
|
see: unresolvedSee(input.tags.see),
|
|
importGuidance: importGuidance(input.imports, input.kind, input.bucket, input.apiName)
|
|
}
|
|
}
|
|
|
|
function buildJSDocApis(files: ReadonlyArray<JSDocModelFile>): ReadonlyArray<JSDocApi> {
|
|
const apis: Array<JSDocApi> = []
|
|
const addMembers = (
|
|
file: JSDocModelFile,
|
|
imports: ParsedJSDocImports,
|
|
members: ReadonlyArray<ParsedMember>,
|
|
parentApiName: string,
|
|
namespacePath: ReadonlyArray<string>,
|
|
memberPath: ReadonlyArray<string>,
|
|
sourcePath: ReadonlyArray<string | number>
|
|
) => {
|
|
members.forEach((member, index) => {
|
|
const nextMemberPath = [...memberPath, member.name]
|
|
const apiName = `${parentApiName}.${nextMemberPath.join(".")}`
|
|
apis.push(makeApi({
|
|
file,
|
|
imports,
|
|
kind: "member",
|
|
bucket: null,
|
|
apiName,
|
|
localName: member.name,
|
|
signature: member.signature,
|
|
parentApiName,
|
|
namespacePath,
|
|
memberPath: nextMemberPath,
|
|
sourcePath: [...sourcePath, "members", index],
|
|
sourceRange: member.range,
|
|
description: member.description,
|
|
examples: member.examples,
|
|
tags: member.tags
|
|
}))
|
|
addMembers(file, imports, member.members, parentApiName, namespacePath, nextMemberPath, [
|
|
...sourcePath,
|
|
"members",
|
|
index
|
|
])
|
|
})
|
|
}
|
|
const addNamespaces = (
|
|
file: JSDocModelFile,
|
|
imports: ParsedJSDocImports,
|
|
namespaces: ReadonlyArray<ParsedNamespace>,
|
|
namespacePath: ReadonlyArray<string>,
|
|
sourcePath: ReadonlyArray<string | number>
|
|
) => {
|
|
namespaces.forEach((namespace, index) => {
|
|
const nextNamespacePath = [...namespacePath, namespace.name]
|
|
const namespaceApiName = nextNamespacePath.join(".")
|
|
apis.push(makeApi({
|
|
file,
|
|
imports,
|
|
kind: "namespace",
|
|
bucket: null,
|
|
apiName: namespaceApiName,
|
|
localName: namespace.name,
|
|
signature: namespace.signature,
|
|
parentApiName: namespacePath.length === 0 ? null : namespacePath.join("."),
|
|
namespacePath: nextNamespacePath,
|
|
memberPath: [],
|
|
sourcePath: [...sourcePath, index],
|
|
sourceRange: namespace.range,
|
|
description: namespace.description,
|
|
examples: namespace.examples,
|
|
tags: namespace.tags
|
|
}))
|
|
namespace.declarations.forEach((declaration, declarationIndex) => {
|
|
const apiName = `${namespaceApiName}.${declaration.name}`
|
|
apis.push(makeApi({
|
|
file,
|
|
imports,
|
|
kind: "namespace-declaration",
|
|
bucket: "type",
|
|
apiName,
|
|
localName: declaration.name,
|
|
signature: declaration.signature,
|
|
parentApiName: namespaceApiName,
|
|
namespacePath: nextNamespacePath,
|
|
memberPath: [],
|
|
sourcePath: [...sourcePath, index, "declarations", declarationIndex],
|
|
sourceRange: declaration.range,
|
|
description: declaration.description,
|
|
examples: declaration.examples,
|
|
tags: declaration.tags
|
|
}))
|
|
addMembers(file, imports, declaration.members, apiName, nextNamespacePath, [], [
|
|
...sourcePath,
|
|
index,
|
|
"declarations",
|
|
declarationIndex
|
|
])
|
|
})
|
|
addNamespaces(file, imports, namespace.namespaces, nextNamespacePath, [...sourcePath, index, "namespaces"])
|
|
})
|
|
}
|
|
for (const file of files) {
|
|
if (file.imports === undefined) continue
|
|
const imports = file.imports
|
|
file.declarations.forEach((declaration, index) => {
|
|
apis.push(makeApi({
|
|
file,
|
|
imports,
|
|
kind: "root-declaration",
|
|
bucket: declaration.bucket,
|
|
apiName: declaration.name,
|
|
localName: declaration.name,
|
|
signature: declaration.signature,
|
|
parentApiName: null,
|
|
namespacePath: [],
|
|
memberPath: [],
|
|
sourcePath: ["declarations", index],
|
|
sourceRange: declaration.range,
|
|
description: declaration.description,
|
|
examples: declaration.examples,
|
|
tags: declaration.tags
|
|
}))
|
|
addMembers(file, imports, declaration.members, declaration.name, [], [], ["declarations", index])
|
|
})
|
|
addNamespaces(file, imports, file.namespaces, [], ["namespaces"])
|
|
}
|
|
return resolveJSDocApiSeeLinks(markFqnCollisions(apis))
|
|
}
|
|
|
|
function markFqnCollisions(apis: ReadonlyArray<JSDocApi>): ReadonlyArray<JSDocApi> {
|
|
const counts = new Map<string, number>()
|
|
for (const api of apis) counts.set(api.apiFqn, (counts.get(api.apiFqn) ?? 0) + 1)
|
|
return apis.map((api) => ({ ...api, hasFqnCollision: (counts.get(api.apiFqn) ?? 0) > 1 }))
|
|
}
|
|
|
|
function normalizeSeeTarget(target: string): ReadonlyArray<string> {
|
|
const withoutKind = target.replace(/:[A-Za-z]+$/, "")
|
|
const out = [withoutKind]
|
|
if (withoutKind.endsWith("_")) out.push(withoutKind.slice(0, -1))
|
|
return Array.from(new Set(out.filter((item) => item.length > 0)))
|
|
}
|
|
|
|
function sourceRangeKey(file: string, range: readonly [number, number]): string {
|
|
return `${file}:${range[0]}:${range[1]}`
|
|
}
|
|
|
|
function rangeContains(outer: readonly [number, number], inner: readonly [number, number]): boolean {
|
|
return outer[0] <= inner[0] && inner[1] <= outer[1]
|
|
}
|
|
|
|
function rangeOverlaps(self: readonly [number, number], that: readonly [number, number]): boolean {
|
|
return self[0] <= that[1] && that[0] <= self[1]
|
|
}
|
|
|
|
function rangeWidth(range: readonly [number, number]): number {
|
|
return range[1] - range[0]
|
|
}
|
|
|
|
function seeTargetNames(link: ParsedInlineLink): ReadonlySet<string> {
|
|
const names = new Set<string>()
|
|
const add = (target: string) => {
|
|
for (const normalized of normalizeSeeTarget(target)) {
|
|
const parts = normalized.split(".").filter((part) => part.length > 0)
|
|
for (const part of parts) names.add(part)
|
|
if (parts.length > 0) names.add(parts.join("."))
|
|
}
|
|
}
|
|
add(link.target)
|
|
if (link.text !== null) add(link.text)
|
|
return names
|
|
}
|
|
|
|
function apiMatchesSeeTarget(api: JSDocApi, names: ReadonlySet<string>): boolean {
|
|
if (names.size === 0) return true
|
|
if (names.has(api.localName) || names.has(api.apiName)) return true
|
|
for (const name of names) {
|
|
if (api.apiName.endsWith(`.${name}`)) return true
|
|
}
|
|
return false
|
|
}
|
|
|
|
function createJSDocApiSeeLinkResolver(apis: ReadonlyArray<JSDocApi>) {
|
|
const byModuleAndName = new Map<string, JSDocApi>()
|
|
const byLocalName = new Map<string, Array<JSDocApi>>()
|
|
const bySourceRange = new Map<string, JSDocApi>()
|
|
const bySourceFile = new Map<string, Array<JSDocApi>>()
|
|
for (const api of apis) {
|
|
byModuleAndName.set(`${api.moduleName}:${api.apiName}`, api)
|
|
bySourceRange.set(sourceRangeKey(api.source.file, api.source.range), api)
|
|
const sourceApis = bySourceFile.get(api.source.file) ?? []
|
|
sourceApis.push(api)
|
|
bySourceFile.set(api.source.file, sourceApis)
|
|
for (const name of new Set([api.apiName, api.localName])) {
|
|
const existing = byLocalName.get(name) ?? []
|
|
existing.push(api)
|
|
byLocalName.set(name, existing)
|
|
}
|
|
}
|
|
const resolveSymbol = (link: ParsedInlineLink): JSDocApiSeeLinkResolution | undefined => {
|
|
if (link.symbol === undefined) return undefined
|
|
const symbol = link.symbol
|
|
const exact = bySourceRange.get(sourceRangeKey(symbol.file, symbol.range))
|
|
if (exact !== undefined) return { _tag: "Resolved", apiId: exact.id, apiFqn: exact.apiFqn }
|
|
const names = seeTargetNames(link)
|
|
const candidates = (bySourceFile.get(symbol.file) ?? []).filter((api) =>
|
|
apiMatchesSeeTarget(api, names) &&
|
|
(rangeContains(symbol.range, api.source.range) ||
|
|
rangeContains(api.source.range, symbol.range) ||
|
|
rangeOverlaps(symbol.range, api.source.range))
|
|
).sort((self, that) => rangeWidth(self.source.range) - rangeWidth(that.source.range))
|
|
const unique = Array.from(new Map(candidates.map((candidate) => [candidate.id, candidate])).values())
|
|
if (unique.length === 1) return { _tag: "Resolved", apiId: unique[0].id, apiFqn: unique[0].apiFqn }
|
|
if (unique.length > 1) {
|
|
return { _tag: "Unresolved", reason: "ambiguous", candidates: unique.map((candidate) => candidate.id) }
|
|
}
|
|
const sameFileByName = (bySourceFile.get(symbol.file) ?? []).filter((api) => apiMatchesSeeTarget(api, names))
|
|
const uniqueByName = Array.from(new Map(sameFileByName.map((candidate) => [candidate.id, candidate])).values())
|
|
if (uniqueByName.length === 1) {
|
|
return { _tag: "Resolved", apiId: uniqueByName[0].id, apiFqn: uniqueByName[0].apiFqn }
|
|
}
|
|
if (uniqueByName.length > 1) {
|
|
return { _tag: "Unresolved", reason: "ambiguous", candidates: uniqueByName.map((candidate) => candidate.id) }
|
|
}
|
|
return undefined
|
|
}
|
|
return (
|
|
context: { readonly moduleName: string; readonly namespacePath: ReadonlyArray<string> },
|
|
link: ParsedInlineLink
|
|
): JSDocApiSeeLinkResolution => {
|
|
const symbolResolution = resolveSymbol(link)
|
|
if (symbolResolution !== undefined) return symbolResolution
|
|
const targets = new Set<string>()
|
|
for (const target of normalizeSeeTarget(link.target)) targets.add(target)
|
|
if (link.text !== null) {
|
|
for (const target of normalizeSeeTarget(link.text)) targets.add(target)
|
|
}
|
|
for (const target of targets) {
|
|
const sameModule = byModuleAndName.get(`${context.moduleName}:${target}`)
|
|
if (sameModule !== undefined) return { _tag: "Resolved", apiId: sameModule.id, apiFqn: sameModule.apiFqn }
|
|
if (!target.includes(".") && context.namespacePath.length > 0) {
|
|
const sameNamespace = byModuleAndName.get(
|
|
`${context.moduleName}:${[...context.namespacePath, target].join(".")}`
|
|
)
|
|
if (sameNamespace !== undefined) {
|
|
return { _tag: "Resolved", apiId: sameNamespace.id, apiFqn: sameNamespace.apiFqn }
|
|
}
|
|
}
|
|
}
|
|
const candidates = Array.from(targets).flatMap((target) => byLocalName.get(target) ?? [])
|
|
const unique = Array.from(new Map(candidates.map((candidate) => [candidate.id, candidate])).values())
|
|
if (unique.length === 1) return { _tag: "Resolved", apiId: unique[0].id, apiFqn: unique[0].apiFqn }
|
|
if (unique.length > 1) {
|
|
return { _tag: "Unresolved", reason: "ambiguous", candidates: unique.map((candidate) => candidate.id) }
|
|
}
|
|
return { _tag: "Unresolved", reason: "not-found", candidates: [] }
|
|
}
|
|
}
|
|
|
|
function resolveJSDocApiSeeLinks(apis: ReadonlyArray<JSDocApi>): ReadonlyArray<JSDocApi> {
|
|
const resolve = createJSDocApiSeeLinkResolver(apis)
|
|
return apis.map((api) => ({
|
|
...api,
|
|
see: api.see.map((tag) => ({
|
|
...tag,
|
|
links: tag.links.map((link) => ({ ...link, resolution: resolve(api, link) }))
|
|
}))
|
|
}))
|
|
}
|
|
|
|
function sameDiagnostic(self: JSDocModelDiagnostic, that: JSDocModelDiagnostic): boolean {
|
|
return self.code === that.code && self.message === that.message &&
|
|
self.range[0] === that.range[0] && self.range[1] === that.range[1]
|
|
}
|
|
|
|
function unresolvedPublicSeeDiagnostic(link: JSDocApiSeeLink): JSDocModelDiagnostic | undefined {
|
|
if (link.resolution._tag === "Resolved" || link.range === undefined) return undefined
|
|
const message = link.resolution.reason === "ambiguous"
|
|
? `@see link ${link.raw} is ambiguous; it must resolve to exactly one public JSDoc API. Candidates: ${
|
|
link.resolution.candidates.join(", ")
|
|
}`
|
|
: `@see link ${link.raw} does not resolve to a public JSDoc API. Check that the target is exported and has valid public JSDoc.`
|
|
return { ...diagnostic("public-see-target", message), range: link.range }
|
|
}
|
|
|
|
function appendPublicSeeDiagnostics(
|
|
files: ReadonlyArray<JSDocModelFile>,
|
|
apis: ReadonlyArray<JSDocApi>
|
|
): { readonly files: ReadonlyArray<JSDocModelFile>; readonly added: boolean } {
|
|
const diagnosticsByFile = new Map(files.map((file) => [file.file, [...file.diagnostics]]))
|
|
let added = false
|
|
for (const api of apis) {
|
|
const diagnostics = diagnosticsByFile.get(api.source.file)
|
|
if (diagnostics === undefined) continue
|
|
for (const tag of api.see) {
|
|
for (const link of tag.links) {
|
|
const item = unresolvedPublicSeeDiagnostic(link)
|
|
if (item === undefined || diagnostics.some((diagnostic) => sameDiagnostic(diagnostic, item))) continue
|
|
diagnostics.push(item)
|
|
added = true
|
|
}
|
|
}
|
|
}
|
|
if (!added) return { files, added }
|
|
return {
|
|
added,
|
|
files: files.map((file) => ({
|
|
...file,
|
|
diagnostics: diagnosticsByFile.get(file.file) ?? file.diagnostics
|
|
}))
|
|
}
|
|
}
|
|
|
|
function moduleSeeTags(
|
|
file: JSDocModelFile,
|
|
sourceFile: ts.SourceFile,
|
|
linkContext: { readonly checker: ts.TypeChecker; readonly entry: ProgramCacheEntry; readonly cwd: string }
|
|
): ReadonlyArray<JSDocApiSeeTag> {
|
|
if (file.moduleJSDoc === undefined) return []
|
|
const block = parseLooseJSDocBlock(file.moduleJSDoc.raw, [file.moduleJSDoc.range[0], file.moduleJSDoc.range[1]])
|
|
if (block.internal) return []
|
|
const tags = buildTags("module", block.tags)
|
|
const moduleTags: ParsedModuleTags = tags._tag === "Success"
|
|
? tags.value as ParsedModuleTags
|
|
: {
|
|
since: "0.0.0",
|
|
deprecated: null,
|
|
see: block.tags.filter((tag) => tag.name === "see" && tag.value.trim() !== "").map((tag) =>
|
|
parseSeeTag(tag.value.trim())
|
|
)
|
|
}
|
|
const withSymbols = attachSeeLinkSymbolsFromSourceFile(moduleTags, sourceFile, block, linkContext)
|
|
return unresolvedSee(withSymbols.see)
|
|
}
|
|
|
|
function appendModulePublicSeeDiagnostics(
|
|
files: ReadonlyArray<JSDocModelFile>,
|
|
apis: ReadonlyArray<JSDocApi>,
|
|
context: {
|
|
readonly sourceFilesByFile: ReadonlyMap<string, ts.SourceFile>
|
|
readonly checker: ts.TypeChecker
|
|
readonly entry: ProgramCacheEntry
|
|
readonly cwd: string
|
|
}
|
|
): { readonly files: ReadonlyArray<JSDocModelFile>; readonly added: boolean } {
|
|
const diagnosticsByFile = new Map(files.map((file) => [file.file, [...file.diagnostics]]))
|
|
const resolve = createJSDocApiSeeLinkResolver(apis)
|
|
let added = false
|
|
for (const file of files) {
|
|
if (file.imports === undefined || file.moduleJSDoc === undefined) continue
|
|
const sourceFile = context.sourceFilesByFile.get(file.file)
|
|
const diagnostics = diagnosticsByFile.get(file.file)
|
|
if (sourceFile === undefined || diagnostics === undefined) continue
|
|
for (const tag of moduleSeeTags(file, sourceFile, context)) {
|
|
for (const link of tag.links) {
|
|
const item = unresolvedPublicSeeDiagnostic({
|
|
...link,
|
|
resolution: resolve({ moduleName: file.imports.module, namespacePath: [] }, link)
|
|
})
|
|
if (item === undefined || diagnostics.some((diagnostic) => sameDiagnostic(diagnostic, item))) continue
|
|
diagnostics.push(item)
|
|
added = true
|
|
}
|
|
}
|
|
}
|
|
if (!added) return { files, added }
|
|
return {
|
|
added,
|
|
files: files.map((file) => ({
|
|
...file,
|
|
diagnostics: diagnosticsByFile.get(file.file) ?? file.diagnostics
|
|
}))
|
|
}
|
|
}
|
|
|
|
function buildJSDocApisWithPublicSeeDiagnostics(
|
|
files: ReadonlyArray<JSDocModelFile>,
|
|
context?: {
|
|
readonly sourceFilesByFile: ReadonlyMap<string, ts.SourceFile>
|
|
readonly checker: ts.TypeChecker
|
|
readonly entry: ProgramCacheEntry
|
|
readonly cwd: string
|
|
}
|
|
): {
|
|
readonly files: ReadonlyArray<JSDocModelFile>
|
|
readonly apis: ReadonlyArray<JSDocApi>
|
|
} {
|
|
let current = files
|
|
for (let index = 0; index < 5; index++) {
|
|
const apis = buildJSDocApis(current)
|
|
const publicSee = appendPublicSeeDiagnostics(current, apis)
|
|
const moduleSee = context === undefined
|
|
? { files: publicSee.files, added: false }
|
|
: appendModulePublicSeeDiagnostics(publicSee.files, apis, context)
|
|
const next = { files: moduleSee.files, added: publicSee.added || moduleSee.added }
|
|
if (!next.added) return { files: current, apis }
|
|
current = next.files
|
|
}
|
|
return { files: current, apis: buildJSDocApis(current) }
|
|
}
|
|
|
|
interface ExampleImportPolicy {
|
|
readonly allowedNamedBySource: ReadonlyMap<string, ReadonlySet<string>>
|
|
readonly namespaceModuleBySource: ReadonlyMap<string, { readonly barrelModule: string; readonly name: string }>
|
|
readonly flatModuleBySource: ReadonlyMap<
|
|
string,
|
|
{ readonly barrelModule: string; readonly names: ReadonlySet<string> }
|
|
>
|
|
readonly namedModuleBySource: ReadonlyMap<string, ReadonlySet<string>>
|
|
}
|
|
|
|
function createExampleImportPolicy(files: ReadonlyArray<JSDocModelFile>): ExampleImportPolicy {
|
|
const allowedNamed = new Map<string, Set<string>>()
|
|
const namespaceModuleBySource = new Map<string, { readonly barrelModule: string; readonly name: string }>()
|
|
const flatModuleBySource = new Map<string, { readonly barrelModule: string; readonly names: ReadonlySet<string> }>()
|
|
const namedModuleBySource = new Map<string, ReadonlySet<string>>()
|
|
const addAllowed = (source: string, name: string) => {
|
|
const names = allowedNamed.get(source) ?? new Set<string>()
|
|
names.add(name)
|
|
allowedNamed.set(source, names)
|
|
}
|
|
for (const file of files) {
|
|
if (file.imports === undefined) continue
|
|
const rootValues = file.declarations.filter((declaration) =>
|
|
declaration.bucket === "value" && isIdentifierName(declaration.name)
|
|
).map((declaration) => declaration.name)
|
|
if (file.imports.barrel?.type === "namespace") {
|
|
addAllowed(file.imports.barrel.module, file.imports.barrel.name)
|
|
for (const name of file.imports.flatNames) addAllowed(file.imports.barrel.module, name)
|
|
namespaceModuleBySource.set(file.imports.module, {
|
|
barrelModule: file.imports.barrel.module,
|
|
name: file.imports.barrel.name
|
|
})
|
|
continue
|
|
}
|
|
if (file.imports.barrel?.type === "flat") {
|
|
for (const name of new Set([...rootValues, ...file.imports.flatNames])) {
|
|
addAllowed(file.imports.barrel.module, name)
|
|
}
|
|
flatModuleBySource.set(file.imports.module, {
|
|
barrelModule: file.imports.barrel.module,
|
|
names: new Set([...rootValues, ...file.imports.flatNames])
|
|
})
|
|
continue
|
|
}
|
|
for (const name of rootValues) addAllowed(file.imports.module, name)
|
|
namedModuleBySource.set(file.imports.module, new Set(rootValues))
|
|
}
|
|
return { allowedNamedBySource: allowedNamed, namespaceModuleBySource, flatModuleBySource, namedModuleBySource }
|
|
}
|
|
|
|
function importSpecifierName(specifier: ts.ImportSpecifier): string {
|
|
return specifier.propertyName?.text ?? specifier.name.text
|
|
}
|
|
|
|
function validateExampleImports(
|
|
code: string,
|
|
policy: ExampleImportPolicy
|
|
): ReadonlyArray<JSDocDiagnostic> {
|
|
const diagnostics: Array<JSDocDiagnostic> = []
|
|
const sourceFile = ts.createSourceFile("example.ts", code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
|
|
for (const statement of sourceFile.statements) {
|
|
if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier)) continue
|
|
if (statement.importClause?.isTypeOnly) continue
|
|
const source = statement.moduleSpecifier.text
|
|
const namedAllowed = policy.allowedNamedBySource.get(source)
|
|
const namespaceModule = policy.namespaceModuleBySource.get(source)
|
|
const flatModule = policy.flatModuleBySource.get(source)
|
|
const namedModule = policy.namedModuleBySource.get(source)
|
|
const clause = statement.importClause
|
|
if (clause === undefined) continue
|
|
if (namespaceModule !== undefined) {
|
|
diagnostics.push(diagnostic(
|
|
"example-import-style",
|
|
`JSDoc examples should use \`import { ${namespaceModule.name} } from "${namespaceModule.barrelModule}"\` instead of importing from "${source}"`
|
|
))
|
|
continue
|
|
}
|
|
if (flatModule !== undefined) {
|
|
diagnostics.push(diagnostic(
|
|
"example-import-style",
|
|
`JSDoc examples should import ${
|
|
Array.from(flatModule.names).map((name) => `\`${name}\``).join(", ")
|
|
} from "${flatModule.barrelModule}" instead of "${source}"`
|
|
))
|
|
continue
|
|
}
|
|
if (clause.namedBindings !== undefined && ts.isNamespaceImport(clause.namedBindings)) {
|
|
if (namedAllowed !== undefined || namedModule !== undefined) {
|
|
diagnostics.push(diagnostic("example-import-style", `JSDoc examples should use named imports from "${source}"`))
|
|
}
|
|
continue
|
|
}
|
|
if (clause.name !== undefined && (namedAllowed !== undefined || namedModule !== undefined)) {
|
|
diagnostics.push(
|
|
diagnostic("example-import-style", `JSDoc examples should not use default imports from "${source}"`)
|
|
)
|
|
}
|
|
if (clause.namedBindings !== undefined && ts.isNamedImports(clause.namedBindings) && namedAllowed !== undefined) {
|
|
for (const specifier of clause.namedBindings.elements) {
|
|
if (specifier.isTypeOnly) continue
|
|
const imported = importSpecifierName(specifier)
|
|
if (!namedAllowed.has(imported)) {
|
|
diagnostics.push(diagnostic(
|
|
"example-import-style",
|
|
`JSDoc example import \`${imported}\` from "${source}" is not a canonical public API import`
|
|
))
|
|
}
|
|
}
|
|
}
|
|
}
|
|
return diagnostics
|
|
}
|
|
|
|
function appendExampleImportDiagnostics(files: ReadonlyArray<JSDocModelFile>): ReadonlyArray<JSDocModelFile> {
|
|
const policy = createExampleImportPolicy(files)
|
|
const checkExamples = (
|
|
examples: ReadonlyArray<ParsedExample>,
|
|
range: readonly [number, number] = [0, 0] as const
|
|
): ReadonlyArray<JSDocModelDiagnostic> =>
|
|
examples.flatMap((example) => validateExampleImports(example.code, policy).map((item) => ({ ...item, range })))
|
|
const checkModuleExamples = (moduleJSDoc: ParsedModuleJSDoc | undefined): ReadonlyArray<JSDocModelDiagnostic> => {
|
|
if (moduleJSDoc === undefined) return []
|
|
const block = parseLooseJSDocBlock(moduleJSDoc.raw, [moduleJSDoc.range[0], moduleJSDoc.range[1]])
|
|
if (block.internal) return []
|
|
return checkExamples(parseModuleExamples(block).examples, moduleJSDoc.range)
|
|
}
|
|
const checkMembers = (members: ReadonlyArray<ParsedMember>): ReadonlyArray<JSDocModelDiagnostic> =>
|
|
members.flatMap((member) => [
|
|
...checkExamples(member.examples),
|
|
...checkMembers(member.members)
|
|
])
|
|
const checkNamespaces = (namespaces: ReadonlyArray<ParsedNamespace>): ReadonlyArray<JSDocModelDiagnostic> =>
|
|
namespaces.flatMap((namespace) => [
|
|
...checkExamples(namespace.examples),
|
|
...namespace.declarations.flatMap((declaration) => [
|
|
...checkExamples(declaration.examples),
|
|
...checkMembers(declaration.members)
|
|
]),
|
|
...checkNamespaces(namespace.namespaces)
|
|
])
|
|
return files.map((file) => {
|
|
const diagnostics = [
|
|
...file.diagnostics,
|
|
...checkModuleExamples(file.moduleJSDoc),
|
|
...file.declarations.flatMap((declaration) => [
|
|
...checkExamples(declaration.examples),
|
|
...checkMembers(declaration.members)
|
|
]),
|
|
...checkNamespaces(file.namespaces)
|
|
]
|
|
return diagnostics.length === file.diagnostics.length
|
|
? file
|
|
: { ...file, diagnostics: uniqueModelDiagnostics(diagnostics) }
|
|
})
|
|
}
|
|
|
|
function uniqueModelDiagnostics(
|
|
diagnostics: ReadonlyArray<JSDocModelDiagnostic>
|
|
): ReadonlyArray<JSDocModelDiagnostic> {
|
|
const seen = new Set<string>()
|
|
return diagnostics.filter((item) => {
|
|
const key = `${item.code}:${item.message}:${item.range[0]}:${item.range[1]}`
|
|
if (seen.has(key)) return false
|
|
seen.add(key)
|
|
return true
|
|
})
|
|
}
|
|
|
|
function nodeRange(node: ts.Node): [number, number] {
|
|
return [node.getStart(), node.getEnd()]
|
|
}
|
|
|
|
function normalizeFile(cwd: string, filename: string): string {
|
|
return normalizePathName(path.relative(cwd, filename))
|
|
}
|
|
|
|
function hashSource(source: string): string {
|
|
return crypto.createHash("sha256").update(source).digest("hex")
|
|
}
|
|
|
|
function getNodeJSDoc(node: ts.Node): JSDocBlock | undefined {
|
|
const jsDocs = (node as { readonly jsDoc?: ReadonlyArray<ts.JSDoc> }).jsDoc
|
|
const jsDoc = jsDocs?.[jsDocs.length - 1]
|
|
if (jsDoc === undefined) return undefined
|
|
const source = node.getSourceFile().text
|
|
return parseJSDocBlock(source.slice(jsDoc.pos, jsDoc.end), [jsDoc.pos, jsDoc.end])
|
|
}
|
|
|
|
function addModelDiagnostics(
|
|
out: Array<JSDocModelDiagnostic>,
|
|
range: [number, number],
|
|
diagnostics: ReadonlyArray<JSDocDiagnostic>
|
|
) {
|
|
for (const item of diagnostics) out.push({ ...item, range })
|
|
}
|
|
|
|
function addJSDocLinkDiagnostics(
|
|
sourceFile: ts.SourceFile,
|
|
block: JSDocBlock,
|
|
diagnostics: Array<JSDocModelDiagnostic>,
|
|
linkContext: { readonly checker: ts.TypeChecker; readonly entry: ProgramCacheEntry; readonly cwd: string }
|
|
) {
|
|
if (!hasInlineLink(block)) return
|
|
for (const link of malformedInlineLinks(block)) {
|
|
diagnostics.push({ ...diagnostic("malformed-link", `Malformed JSDoc inline link: ${link}`), range: block.range })
|
|
}
|
|
for (const link of collectJSDocLinks(sourceFile, block)) {
|
|
const text = link.getText(sourceFile)
|
|
const target = extractInlineLinkTarget(text)
|
|
if (target === "") continue
|
|
if (urlRegex.test(target)) {
|
|
diagnostics.push({
|
|
...diagnostic("url-link", `JSDoc inline link must target a TypeScript symbol: ${text}`),
|
|
range: [link.pos, link.end]
|
|
})
|
|
} else if (resolveJSDocLinkSymbol(link, linkContext.checker) === undefined) {
|
|
diagnostics.push({
|
|
...diagnostic("unresolved-link", `Unresolved JSDoc inline link: ${text}`),
|
|
range: [link.pos, link.end]
|
|
})
|
|
}
|
|
}
|
|
for (const link of collectJSDocSeeLinks(sourceFile, block)) {
|
|
const text = link.getText(sourceFile)
|
|
const target = extractInlineLinkTarget(text)
|
|
if (target === "" || urlRegex.test(target)) continue
|
|
const symbol = resolveJSDocLinkSymbol(link, linkContext.checker)
|
|
if (symbol === undefined) continue
|
|
if (undocumentedSeeLinkTarget(symbol, linkContext.checker, linkContext.cwd) !== undefined) {
|
|
diagnostics.push({
|
|
...diagnostic("undocumented-see-target", `@see link target must have public JSDoc: ${text}`),
|
|
range: [link.pos, link.end]
|
|
})
|
|
}
|
|
}
|
|
}
|
|
|
|
function parseDocumentedTs(
|
|
node: ts.Node,
|
|
scope: DocScope,
|
|
diagnostics: Array<JSDocModelDiagnostic>,
|
|
required = true,
|
|
linkContext?: { readonly checker: ts.TypeChecker; readonly entry: ProgramCacheEntry; readonly cwd: string }
|
|
) {
|
|
const block = getNodeJSDoc(node)
|
|
if (block?.internal) return undefined
|
|
if (block === undefined) {
|
|
if (required) {
|
|
diagnostics.push({
|
|
...diagnostic("missing-jsdoc", scope === "member" ? "Member JSDoc is required" : "Public JSDoc is required"),
|
|
range: nodeRange(node)
|
|
})
|
|
}
|
|
return undefined
|
|
}
|
|
addModelDiagnostics(diagnostics, block.range, block.diagnostics)
|
|
if (block.parsed === undefined) return undefined
|
|
const tags = buildTags(scope, block.parsed.tags)
|
|
if (tags._tag === "Failure") {
|
|
addModelDiagnostics(diagnostics, block.range, tags.error.diagnostics)
|
|
return undefined
|
|
}
|
|
const parsedTags = tags.value as ParsedDeclarationTags | ParsedNamespaceTags | ParsedMemberTags
|
|
if (linkContext !== undefined) addJSDocLinkDiagnostics(node.getSourceFile(), block, diagnostics, linkContext)
|
|
return {
|
|
core: block.parsed,
|
|
tags: linkContext === undefined ? parsedTags : attachSeeLinkSymbols(parsedTags, node, block, linkContext)
|
|
}
|
|
}
|
|
|
|
function hasExportModifier(node: ts.Node): boolean {
|
|
return ts.canHaveModifiers(node) &&
|
|
(ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false)
|
|
}
|
|
|
|
function hasDefaultModifier(node: ts.Node): boolean {
|
|
return ts.canHaveModifiers(node) &&
|
|
(ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword) ?? false)
|
|
}
|
|
|
|
function declarationName(node: ts.Node): string | undefined {
|
|
if (
|
|
(ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isClassDeclaration(node) ||
|
|
ts.isFunctionDeclaration(node) || ts.isModuleDeclaration(node)) && node.name !== undefined
|
|
) return node.name.text
|
|
if (ts.isVariableStatement(node)) {
|
|
return node.declarationList.declarations.map((declaration) => {
|
|
if (ts.isIdentifier(declaration.name)) return declaration.name.text
|
|
if (ts.isObjectBindingPattern(declaration.name)) {
|
|
return declaration.name.elements.map((element) =>
|
|
element.propertyName?.getText(element.getSourceFile()) ?? element.name.getText(element.getSourceFile())
|
|
).join(", ")
|
|
}
|
|
return ""
|
|
}).filter(Boolean).join(", ")
|
|
}
|
|
return undefined
|
|
}
|
|
|
|
function publicDeclarationRange(node: ts.Node, name: string): readonly [number, number] {
|
|
if (ts.isVariableStatement(node)) {
|
|
const declaration = node.declarationList.declarations.find((item) =>
|
|
ts.isIdentifier(item.name) && item.name.text === name
|
|
)
|
|
if (declaration !== undefined) return nodeRange(declaration)
|
|
}
|
|
return nodeRange(node)
|
|
}
|
|
|
|
function bucketOfTs(node: ts.Node): ExportBucket | undefined {
|
|
if (ts.isVariableStatement(node) || ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) return "value"
|
|
if (ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node)) return "type"
|
|
return undefined
|
|
}
|
|
|
|
function normalizeSignature(cwd: string, text: string): string | null {
|
|
const normalizedCwd = normalizePathName(cwd)
|
|
const signature = text.replaceAll(normalizedCwd, ".").replaceAll(cwd, ".").replace(/\r\n?/g, "\n").replace(
|
|
/[ \t]+$/gm,
|
|
""
|
|
).trim()
|
|
return signature === "" ? null : signature
|
|
}
|
|
|
|
function displaySignature(text: string): string {
|
|
return text.replace(/import\((?:"[^"]+"|'[^']+')\)\.([A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*)/g, "$1")
|
|
}
|
|
|
|
function parseableSignature(cwd: string, text: string): string | null {
|
|
const signature = normalizeSignature(cwd, displaySignature(text))
|
|
if (signature === null) return null
|
|
const source = ts.createSourceFile(
|
|
"signature.ts",
|
|
signature,
|
|
ts.ScriptTarget.Latest,
|
|
true,
|
|
ts.ScriptKind.TS
|
|
) as SourceFileWithParseDiagnostics
|
|
return source.parseDiagnostics.length === 0 ? signature : null
|
|
}
|
|
|
|
function signatureLocalName(name: string): string {
|
|
const sanitized = name.replace(/[^A-Za-z0-9_$]/g, "_")
|
|
return `_${sanitized === "" ? "api" : sanitized}`
|
|
}
|
|
|
|
function signatureExportName(name: string): string {
|
|
return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name)
|
|
}
|
|
|
|
function signatureAlias(name: string, text: string): string {
|
|
const localName = signatureLocalName(name)
|
|
return `declare const ${localName}: ${text}
|
|
export { ${localName} as ${signatureExportName(name)} }`
|
|
}
|
|
|
|
function signatureParameterDeclaration(parameter: ts.Symbol): ts.ParameterDeclaration | undefined {
|
|
const declaration = parameter.valueDeclaration ?? parameter.declarations?.[0]
|
|
return declaration !== undefined && ts.isParameter(declaration) ? declaration : undefined
|
|
}
|
|
|
|
function signatureParameterName(parameter: ts.Symbol): string {
|
|
const declaration = signatureParameterDeclaration(parameter)
|
|
if (declaration !== undefined && ts.isIdentifier(declaration.name)) return declaration.name.text
|
|
return parameter.getName()
|
|
}
|
|
|
|
function signatureFunctionThisKind(type: ts.Type, checker: ts.TypeChecker, location: ts.Node): string {
|
|
const thisParameter = checker.getSignaturesOfType(type, ts.SignatureKind.Call)[0]?.thisParameter
|
|
if (thisParameter === undefined) return "none"
|
|
const thisType = checker.typeToString(
|
|
checker.getTypeOfSymbolAtLocation(thisParameter, location),
|
|
location,
|
|
signatureTypeFormatFlags
|
|
)
|
|
return thisType === "unassigned" ? "unassigned" : "self"
|
|
}
|
|
|
|
function isSignatureFunctionKind(kind: string): boolean {
|
|
return kind.startsWith("body:") || kind.startsWith("function:")
|
|
}
|
|
|
|
function signatureTransformCountKind(count: number): string {
|
|
if (count <= 3) return String(count)
|
|
if (count <= 7) return "4"
|
|
if (count <= 15) return "8"
|
|
return "16"
|
|
}
|
|
|
|
function signatureParameterKind(
|
|
parameter: ts.Symbol | undefined,
|
|
checker: ts.TypeChecker,
|
|
location: ts.Node
|
|
): string {
|
|
if (parameter === undefined) return "none"
|
|
const declaration = signatureParameterDeclaration(parameter)
|
|
if (declaration?.dotDotDotToken !== undefined) return "rest"
|
|
const name = signatureParameterName(parameter).replace(/_$/, "").toLowerCase()
|
|
const type = checker.getTypeOfSymbolAtLocation(parameter, declaration ?? location)
|
|
if (name === "self" || name === "that") return "self"
|
|
if (name === "body") return `body:${signatureFunctionThisKind(type, checker, location)}`
|
|
if (name === "name" || name === "spanname") return "name"
|
|
if (name.includes("refinement")) return "refinement"
|
|
if (name.includes("predicate")) return "predicate"
|
|
if (name === "options" || name === "option" || name === "opts" || name === "config" || name === "args") {
|
|
return "options"
|
|
}
|
|
if (name === "f" || name === "fn" || name === "callback") {
|
|
return `function:${signatureFunctionThisKind(type, checker, location)}`
|
|
}
|
|
if (checker.getSignaturesOfType(type, ts.SignatureKind.Call).length > 0) {
|
|
return `function:${signatureFunctionThisKind(type, checker, location)}`
|
|
}
|
|
if ((type.flags & ts.TypeFlags.StringLike) !== 0) return "primitive:string"
|
|
if ((type.flags & ts.TypeFlags.NumberLike) !== 0) return "primitive:number"
|
|
if ((type.flags & ts.TypeFlags.BooleanLike) !== 0) return "primitive:boolean"
|
|
if ((type.flags & ts.TypeFlags.BigIntLike) !== 0) return "primitive:bigint"
|
|
if ((type.flags & ts.TypeFlags.ESSymbolLike) !== 0) return "primitive:symbol"
|
|
if ((type.flags & ts.TypeFlags.Object) !== 0 || checker.getPropertiesOfType(type).length > 0) return "object"
|
|
return "other"
|
|
}
|
|
|
|
function signatureTailKind(signature: ts.Signature, checker: ts.TypeChecker, location: ts.Node): string {
|
|
if (signature.parameters.length <= 1) return "none"
|
|
const firstKind = signatureParameterKind(signature.parameters[0], checker, location)
|
|
const tailKinds = signature.parameters.slice(1).map((parameter) =>
|
|
signatureParameterKind(parameter, checker, location)
|
|
)
|
|
if (firstKind === "options") {
|
|
const hasTransformTail = tailKinds.length > 1 && tailKinds.slice(1).every(isSignatureFunctionKind)
|
|
return `${tailKinds[0]}:${hasTransformTail ? "transform" : "none"}`
|
|
}
|
|
if (tailKinds.every(isSignatureFunctionKind)) {
|
|
return firstKind.startsWith("body:")
|
|
? "transform"
|
|
: `transform:${signatureTransformCountKind(tailKinds.length)}`
|
|
}
|
|
return tailKinds[0]
|
|
}
|
|
|
|
function signatureShapeKey(signature: ts.Signature, checker: ts.TypeChecker, location: ts.Node): string {
|
|
const hasRest = signature.parameters.some((parameter) =>
|
|
signatureParameterDeclaration(parameter)?.dotDotDotToken !== undefined
|
|
)
|
|
const returnType = checker.getReturnTypeOfSignature(signature)
|
|
const returnMode = checker.getSignaturesOfType(returnType, ts.SignatureKind.Call).length > 0 ? "curried" : "direct"
|
|
return [
|
|
hasRest ? "rest" : "fixed",
|
|
signatureParameterKind(signature.parameters[0], checker, location),
|
|
signatureTailKind(signature, checker, location),
|
|
returnMode
|
|
].join(":")
|
|
}
|
|
|
|
function representativeSignatures(
|
|
signatures: ReadonlyArray<ts.Signature>,
|
|
checker: ts.TypeChecker,
|
|
location: ts.Node
|
|
): ReadonlyArray<ts.Signature> {
|
|
const seen = new Set<string>()
|
|
const out: Array<ts.Signature> = []
|
|
for (const signature of signatures) {
|
|
const key = signatureShapeKey(signature, checker, location)
|
|
if (seen.has(key)) continue
|
|
seen.add(key)
|
|
out.push(signature)
|
|
}
|
|
return out
|
|
}
|
|
|
|
function functionSignature(
|
|
name: string,
|
|
symbol: ts.Symbol,
|
|
location: ts.Node,
|
|
checker: ts.TypeChecker,
|
|
cwd: string
|
|
): string | null {
|
|
const target = resolvedSymbolTarget(symbol, checker)
|
|
const type = checker.getTypeOfSymbolAtLocation(target, location)
|
|
const signatures = checker.getSignaturesOfType(type, ts.SignatureKind.Call)
|
|
if (signatures.length === 0) return null
|
|
const callSignatures: Array<string> = []
|
|
for (const signature of representativeSignatures(signatures, checker, location)) {
|
|
const text = normalizeSignature(
|
|
cwd,
|
|
checker.signatureToString(signature, location, signatureTypeFormatFlags, ts.SignatureKind.Call)
|
|
)
|
|
if (text === null) return null
|
|
callSignatures.push(text)
|
|
}
|
|
const declaration = parseableSignature(
|
|
cwd,
|
|
callSignatures.map((text) => `declare function ${name}${text}`).join("\n")
|
|
)
|
|
if (declaration !== null) return declaration
|
|
const callSignatureAlias = parseableSignature(
|
|
cwd,
|
|
signatureAlias(
|
|
name,
|
|
`{
|
|
${callSignatures.map((text) => ` ${text};`).join("\n")}
|
|
}`
|
|
)
|
|
)
|
|
if (callSignatureAlias !== null) return callSignatureAlias
|
|
const typeText = normalizeSignature(cwd, checker.typeToString(type, location, signatureTypeFormatFlags))
|
|
if (typeText === null) return null
|
|
return parseableSignature(cwd, `declare const ${name}: ${typeText}`) ??
|
|
parseableSignature(cwd, signatureAlias(name, typeText))
|
|
}
|
|
|
|
function symbolSignature(
|
|
name: string,
|
|
bucket: ExportBucket,
|
|
symbol: ts.Symbol,
|
|
location: ts.Node,
|
|
checker: ts.TypeChecker,
|
|
cwd: string
|
|
): string | null {
|
|
if (bucket !== "value") return null
|
|
const target = resolvedSymbolTarget(symbol, checker)
|
|
const type = checker.getTypeOfSymbolAtLocation(target, location)
|
|
if (checker.getSignaturesOfType(type, ts.SignatureKind.Call).length === 0) return null
|
|
return functionSignature(name, symbol, location, checker, cwd)
|
|
}
|
|
|
|
function declarationSignature(
|
|
name: string,
|
|
bucket: ExportBucket,
|
|
node: ts.Node,
|
|
checker: ts.TypeChecker,
|
|
cwd: string
|
|
): string | null {
|
|
if (ts.isVariableStatement(node)) {
|
|
const declaration = node.declarationList.declarations.find((item) =>
|
|
ts.isIdentifier(item.name) && item.name.text === name
|
|
)
|
|
if (declaration === undefined) return null
|
|
const symbol = checker.getSymbolAtLocation(declaration.name)
|
|
return symbol === undefined ? null : symbolSignature(name, bucket, symbol, declaration.name, checker, cwd)
|
|
}
|
|
const nameNode = ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node) ||
|
|
ts.isTypeAliasDeclaration(node)
|
|
? node.name
|
|
: undefined
|
|
if (nameNode === undefined) return null
|
|
const symbol = checker.getSymbolAtLocation(nameNode)
|
|
return symbol === undefined ? null : symbolSignature(name, bucket, symbol, nameNode, checker, cwd)
|
|
}
|
|
|
|
function exportSpecifierSignature(
|
|
name: string,
|
|
bucket: ExportBucket,
|
|
specifier: ts.ExportSpecifier,
|
|
checker: ts.TypeChecker,
|
|
cwd: string
|
|
): string | null {
|
|
const symbol = checker.getSymbolAtLocation(specifier.name) ??
|
|
(specifier.propertyName === undefined ? undefined : checker.getSymbolAtLocation(specifier.propertyName))
|
|
return symbol === undefined ? null : symbolSignature(name, bucket, symbol, specifier.name, checker, cwd)
|
|
}
|
|
|
|
function parseMembersFromTsType(
|
|
type: ts.TypeNode | undefined,
|
|
diagnostics: Array<JSDocModelDiagnostic>,
|
|
linkContext: { readonly checker: ts.TypeChecker; readonly entry: ProgramCacheEntry; readonly cwd: string }
|
|
): Array<ParsedMember> {
|
|
if (!type) return []
|
|
if (ts.isTypeLiteralNode(type)) return parseTsMembers(type.members, diagnostics, linkContext)
|
|
if (ts.isUnionTypeNode(type) || ts.isIntersectionTypeNode(type)) {
|
|
return type.types.flatMap((item) => parseMembersFromTsType(item, diagnostics, linkContext))
|
|
}
|
|
if (ts.isParenthesizedTypeNode(type) || ts.isTypeOperatorNode(type)) {
|
|
return parseMembersFromTsType(type.type, diagnostics, linkContext)
|
|
}
|
|
if (ts.isArrayTypeNode(type)) return parseMembersFromTsType(type.elementType, diagnostics, linkContext)
|
|
if (ts.isConditionalTypeNode(type)) {
|
|
return [
|
|
...parseMembersFromTsType(type.checkType, diagnostics, linkContext),
|
|
...parseMembersFromTsType(type.extendsType, diagnostics, linkContext),
|
|
...parseMembersFromTsType(type.trueType, diagnostics, linkContext),
|
|
...parseMembersFromTsType(type.falseType, diagnostics, linkContext)
|
|
]
|
|
}
|
|
if (ts.isTypeReferenceNode(type)) {
|
|
return type.typeArguments?.flatMap((item) => parseMembersFromTsType(item, diagnostics, linkContext)) ?? []
|
|
}
|
|
if (ts.isMappedTypeNode(type)) return parseMembersFromTsType(type.type, diagnostics, linkContext)
|
|
if (ts.isIndexedAccessTypeNode(type)) {
|
|
return [
|
|
...parseMembersFromTsType(type.objectType, diagnostics, linkContext),
|
|
...parseMembersFromTsType(type.indexType, diagnostics, linkContext)
|
|
]
|
|
}
|
|
if (ts.isFunctionTypeNode(type) || ts.isConstructorTypeNode(type)) {
|
|
return parseMembersFromTsType(type.type, diagnostics, linkContext)
|
|
}
|
|
return []
|
|
}
|
|
|
|
function memberName(member: ts.TypeElement | ts.ClassElement): string {
|
|
if (
|
|
ts.isPropertySignature(member) || ts.isMethodSignature(member) || ts.isPropertyDeclaration(member) ||
|
|
ts.isMethodDeclaration(member) || ts.isGetAccessorDeclaration(member) || ts.isSetAccessorDeclaration(member)
|
|
) {
|
|
const name = member.name
|
|
if (ts.isComputedPropertyName(name)) return name.expression.getText(member.getSourceFile())
|
|
return name.getText(member.getSourceFile()).replace(/^[']|[']$/g, "")
|
|
}
|
|
return ""
|
|
}
|
|
|
|
function memberType(member: ts.TypeElement | ts.ClassElement): ts.TypeNode | undefined {
|
|
if (
|
|
ts.isPropertySignature(member) || ts.isMethodSignature(member) || ts.isPropertyDeclaration(member) ||
|
|
ts.isMethodDeclaration(member) || ts.isGetAccessorDeclaration(member) || ts.isSetAccessorDeclaration(member)
|
|
) return member.type
|
|
return undefined
|
|
}
|
|
|
|
function parseTsMembers(
|
|
members: ts.NodeArray<ts.TypeElement | ts.ClassElement>,
|
|
diagnostics: Array<JSDocModelDiagnostic>,
|
|
linkContext: { readonly checker: ts.TypeChecker; readonly entry: ProgramCacheEntry; readonly cwd: string }
|
|
): Array<ParsedMember> {
|
|
const out: Array<ParsedMember> = []
|
|
for (const member of members) {
|
|
if (
|
|
ts.isCallSignatureDeclaration(member) || ts.isConstructSignatureDeclaration(member) ||
|
|
ts.isIndexSignatureDeclaration(member) || member.kind === ts.SyntaxKind.Constructor
|
|
) continue
|
|
const documented = parseDocumentedTs(member, "member", diagnostics, false, linkContext)
|
|
if (documented === undefined) continue
|
|
const name = memberName(member)
|
|
if (name === "") continue
|
|
const nested = parseMembersFromTsType(memberType(member), diagnostics, linkContext)
|
|
out.push({
|
|
name,
|
|
signature: null,
|
|
range: nodeRange(member),
|
|
description: documented.core.description,
|
|
examples: documented.core.examples,
|
|
tags: documented.tags as ParsedMemberTags,
|
|
members: nested
|
|
})
|
|
}
|
|
return out
|
|
}
|
|
|
|
function parseDeclarationMembersTs(
|
|
node: ts.Node,
|
|
diagnostics: Array<JSDocModelDiagnostic>,
|
|
linkContext: { readonly checker: ts.TypeChecker; readonly entry: ProgramCacheEntry; readonly cwd: string }
|
|
): Array<ParsedMember> {
|
|
if (ts.isInterfaceDeclaration(node)) return parseTsMembers(node.members, diagnostics, linkContext)
|
|
if (ts.isClassDeclaration(node)) return parseTsMembers(node.members, diagnostics, linkContext)
|
|
if (ts.isTypeAliasDeclaration(node)) return parseMembersFromTsType(node.type, diagnostics, linkContext)
|
|
if (ts.isVariableStatement(node)) {
|
|
return node.declarationList.declarations.flatMap((d) => parseMembersFromTsType(d.type, diagnostics, linkContext))
|
|
}
|
|
if (ts.isFunctionDeclaration(node)) return parseMembersFromTsType(node.type, diagnostics, linkContext)
|
|
return []
|
|
}
|
|
|
|
function hasDeclareModifier(node: ts.Node): boolean {
|
|
return ts.canHaveModifiers(node) &&
|
|
(ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.DeclareKeyword) ?? false)
|
|
}
|
|
|
|
function parseNamespaceTs(
|
|
node: ts.ModuleDeclaration,
|
|
diagnostics: Array<JSDocModelDiagnostic>,
|
|
linkContext: { readonly checker: ts.TypeChecker; readonly entry: ProgramCacheEntry; readonly cwd: string },
|
|
isInsideDeclare = false
|
|
): ParsedNamespace | undefined {
|
|
if (!ts.isIdentifier(node.name)) return undefined
|
|
if (!isInsideDeclare && !hasDeclareModifier(node)) {
|
|
diagnostics.push({
|
|
...diagnostic("namespace-declare", "Namespaces must be declared with declare namespace"),
|
|
range: nodeRange(node)
|
|
})
|
|
return undefined
|
|
}
|
|
const documented = parseDocumentedTs(node, "namespace", diagnostics, true, linkContext)
|
|
if (documented === undefined) return undefined
|
|
const declarations: Array<ParsedNamespaceDeclaration> = []
|
|
const namespaces: Array<ParsedNamespace> = []
|
|
if (node.body !== undefined && ts.isModuleBlock(node.body)) {
|
|
for (const statement of node.body.statements) {
|
|
if (!hasExportModifier(statement)) continue
|
|
if (ts.isModuleDeclaration(statement)) {
|
|
const nested = parseNamespaceTs(statement, diagnostics, linkContext, true)
|
|
if (nested !== undefined) namespaces.push(nested)
|
|
continue
|
|
}
|
|
if (ts.isEnumDeclaration(statement)) {
|
|
diagnostics.push({ ...diagnostic("enum", "Enums are not allowed"), range: nodeRange(statement) })
|
|
continue
|
|
}
|
|
const bucket = bucketOfTs(statement)
|
|
if (bucket !== "type") {
|
|
diagnostics.push({
|
|
...diagnostic("namespace-value", "Namespace exports must be type declarations"),
|
|
range: nodeRange(statement)
|
|
})
|
|
continue
|
|
}
|
|
const nestedDocumented = parseDocumentedTs(statement, "namespace-declaration", diagnostics, true, linkContext)
|
|
if (nestedDocumented === undefined) continue
|
|
const name = declarationName(statement)
|
|
if (name === undefined || name.length === 0) {
|
|
diagnostics.push({
|
|
...diagnostic("missing-name", "Namespace declaration name could not be determined"),
|
|
range: nodeRange(statement)
|
|
})
|
|
continue
|
|
}
|
|
declarations.push({
|
|
name,
|
|
signature: null,
|
|
range: publicDeclarationRange(statement, name),
|
|
description: nestedDocumented.core.description,
|
|
examples: nestedDocumented.core.examples,
|
|
tags: nestedDocumented.tags as ParsedNamespaceTags,
|
|
members: parseDeclarationMembersTs(statement, diagnostics, linkContext)
|
|
})
|
|
}
|
|
}
|
|
return {
|
|
name: node.name.text,
|
|
signature: null,
|
|
range: nodeRange(node),
|
|
description: documented.core.description,
|
|
examples: documented.core.examples,
|
|
tags: documented.tags as ParsedNamespaceTags,
|
|
declarations,
|
|
namespaces
|
|
}
|
|
}
|
|
|
|
function skipLeadingIgnoredTrivia(source: string): number {
|
|
let index = source.charCodeAt(0) === 0xfeff ? 1 : 0
|
|
while (index < source.length) {
|
|
while (index < source.length && /\s/.test(source[index])) index++
|
|
if (!source.startsWith("//", index)) return index
|
|
const lineEnd = source.indexOf("\n", index)
|
|
const end = lineEnd === -1 ? source.length : lineEnd + 1
|
|
if (!isSkippableDirectiveComment(source.slice(index, end))) return index
|
|
index = end
|
|
}
|
|
return index
|
|
}
|
|
|
|
function sourceFileTopLevelJSDoc(sourceFile: ts.SourceFile): ParsedModuleJSDoc | undefined {
|
|
const source = sourceFile.text
|
|
const start = skipLeadingIgnoredTrivia(source)
|
|
if (!source.startsWith("/**", start)) return undefined
|
|
const end = source.indexOf("*/", start + 3)
|
|
if (end === -1) return undefined
|
|
const range = [start, end + 2] as const
|
|
const firstStatement = sourceFile.statements[0]
|
|
if (firstStatement !== undefined) {
|
|
const jsDocs = (firstStatement as { readonly jsDoc?: ReadonlyArray<ts.JSDoc> }).jsDoc ?? []
|
|
if (
|
|
jsDocs.some((jsDoc) => jsDoc.pos === range[0] && jsDoc.end === range[1]) &&
|
|
!ts.isImportDeclaration(firstStatement) &&
|
|
!ts.isImportEqualsDeclaration(firstStatement)
|
|
) return undefined
|
|
}
|
|
return { raw: source.slice(range[0], range[1]), range }
|
|
}
|
|
|
|
function parseModuleJSDocTs(
|
|
sourceFile: ts.SourceFile,
|
|
moduleJSDoc: ParsedModuleJSDoc,
|
|
diagnostics: Array<JSDocModelDiagnostic>,
|
|
linkContext: { readonly checker: ts.TypeChecker; readonly entry: ProgramCacheEntry; readonly cwd: string }
|
|
): ParsedModuleJSDoc | undefined {
|
|
const block = parseLooseJSDocBlock(moduleJSDoc.raw, [moduleJSDoc.range[0], moduleJSDoc.range[1]])
|
|
if (block.internal) return undefined
|
|
const tags = buildTags("module", block.tags)
|
|
if (tags._tag === "Failure") addModelDiagnostics(diagnostics, block.range, tags.error.diagnostics)
|
|
const examples = parseModuleExamples(block)
|
|
addModelDiagnostics(diagnostics, block.range, examples.diagnostics)
|
|
addJSDocLinkDiagnostics(sourceFile, block, diagnostics, linkContext)
|
|
return moduleJSDoc
|
|
}
|
|
|
|
function parseSourceFileDocs(
|
|
cwd: string,
|
|
sourceFile: ts.SourceFile,
|
|
checker: ts.TypeChecker,
|
|
entry: ProgramCacheEntry
|
|
): { readonly parsed: ParsedJSDocFile; readonly diagnostics: ReadonlyArray<JSDocModelDiagnostic> } {
|
|
const diagnostics: Array<JSDocModelDiagnostic> = []
|
|
const declarations: Array<ParsedRootDeclaration> = []
|
|
const namespaces: Array<ParsedNamespace> = []
|
|
const linkContext = { checker, entry, cwd }
|
|
const checkedFunctionOverloads = new Set<string>()
|
|
const moduleJSDoc = sourceFileTopLevelJSDoc(sourceFile)
|
|
const parsedModuleJSDoc = moduleJSDoc === undefined
|
|
? undefined
|
|
: parseModuleJSDocTs(sourceFile, moduleJSDoc, diagnostics, linkContext)
|
|
|
|
for (const statement of sourceFile.statements) {
|
|
if (ts.isExportAssignment(statement)) continue
|
|
if (ts.isExportDeclaration(statement)) {
|
|
if (statement.exportClause === undefined) continue
|
|
if (ts.isNamedExports(statement.exportClause) && statement.exportClause.elements.length === 0) {
|
|
diagnostics.push({
|
|
...diagnostic("empty-export", "Empty export declarations are not allowed"),
|
|
range: nodeRange(statement)
|
|
})
|
|
}
|
|
if (ts.isNamedExports(statement.exportClause)) {
|
|
for (const specifier of statement.exportClause.elements) {
|
|
const documented = parseDocumentedTs(specifier, "declaration", diagnostics, true, linkContext)
|
|
if (documented === undefined) continue
|
|
declarations.push({
|
|
name: specifier.name.text,
|
|
bucket: statement.isTypeOnly || specifier.isTypeOnly ? "type" : "value",
|
|
signature: exportSpecifierSignature(
|
|
specifier.name.text,
|
|
statement.isTypeOnly || specifier.isTypeOnly ? "type" : "value",
|
|
specifier,
|
|
checker,
|
|
cwd
|
|
),
|
|
range: nodeRange(specifier),
|
|
description: documented.core.description,
|
|
examples: documented.core.examples,
|
|
tags: documented.tags as ParsedDeclarationTags,
|
|
members: []
|
|
})
|
|
}
|
|
}
|
|
continue
|
|
}
|
|
if (!hasExportModifier(statement) || hasDefaultModifier(statement)) continue
|
|
if (ts.isModuleDeclaration(statement)) {
|
|
const namespace = parseNamespaceTs(statement, diagnostics, linkContext)
|
|
if (namespace !== undefined) namespaces.push(namespace)
|
|
continue
|
|
}
|
|
if (ts.isEnumDeclaration(statement)) {
|
|
diagnostics.push({ ...diagnostic("enum", "Enums are not allowed"), range: nodeRange(statement) })
|
|
continue
|
|
}
|
|
const bucket = bucketOfTs(statement)
|
|
if (bucket === undefined) continue
|
|
if (ts.isFunctionDeclaration(statement) && statement.name !== undefined) {
|
|
const name = statement.name.text
|
|
if (statement.body === undefined) {
|
|
if (checkedFunctionOverloads.has(name)) continue
|
|
checkedFunctionOverloads.add(name)
|
|
} else if (checkedFunctionOverloads.has(name)) {
|
|
continue
|
|
}
|
|
}
|
|
const documented = parseDocumentedTs(statement, "declaration", diagnostics, true, linkContext)
|
|
if (documented === undefined) continue
|
|
const name = declarationName(statement)
|
|
if (name === undefined || name.length === 0) {
|
|
diagnostics.push({
|
|
...diagnostic("missing-name", "Root declaration name could not be determined"),
|
|
range: nodeRange(statement)
|
|
})
|
|
continue
|
|
}
|
|
declarations.push({
|
|
name,
|
|
bucket,
|
|
signature: declarationSignature(name, bucket, statement, checker, cwd),
|
|
range: publicDeclarationRange(statement, name),
|
|
description: documented.core.description,
|
|
examples: documented.core.examples,
|
|
tags: documented.tags as ParsedDeclarationTags,
|
|
members: parseDeclarationMembersTs(statement, diagnostics, linkContext)
|
|
})
|
|
}
|
|
return {
|
|
parsed: {
|
|
...(parsedModuleJSDoc === undefined ? {} : { moduleJSDoc: parsedModuleJSDoc }),
|
|
declarations,
|
|
namespaces
|
|
},
|
|
diagnostics: uniqueDiagnostics(diagnostics) as Array<JSDocModelDiagnostic>
|
|
}
|
|
}
|
|
|
|
export function loadJSDocConfig(cwd = process.cwd(), configPath = "jsdocs.config.json"): JSDocConfig {
|
|
const absolute = path.resolve(cwd, configPath)
|
|
const parsed = JSON.parse(fs.readFileSync(absolute, "utf8")) as JSDocConfig
|
|
return parsed
|
|
}
|
|
|
|
export function extractJSDocsSync(options: ExtractJSDocsOptions): JSDocModel {
|
|
const cwd = path.resolve(options.cwd ?? process.cwd())
|
|
const tsconfigPath = path.resolve(cwd, options.tsconfig)
|
|
const entry = getProgram(tsconfigPath)
|
|
if (entry.error !== undefined || entry.program === undefined) {
|
|
throw new Error(entry.error ?? `Unable to read ${tsconfigPath}`)
|
|
}
|
|
const program = entry.program
|
|
const checker = program.getTypeChecker()
|
|
const sourceByPath = new Map(program.getSourceFiles().map((file) => [path.resolve(file.fileName), file]))
|
|
const sourceFilesByFile = new Map(program.getSourceFiles().map((file) => [normalizeFile(cwd, file.fileName), file]))
|
|
const files = globSync([...options.include], {
|
|
cwd,
|
|
absolute: true,
|
|
nodir: true,
|
|
ignore: [...options.exclude ?? []]
|
|
}).sort()
|
|
const modelFiles: Array<JSDocModelFile> = []
|
|
for (const filename of files) {
|
|
const source = fs.readFileSync(filename, "utf8")
|
|
const file = normalizeFile(cwd, filename)
|
|
const hash = hashSource(source)
|
|
const sourceFile = sourceByPath.get(path.resolve(filename))
|
|
if (sourceFile === undefined) {
|
|
modelFiles.push({
|
|
file,
|
|
hash,
|
|
diagnostics: [{ ...diagnostic("tsconfig", `${file} is not included in ${options.tsconfig}`), range: [0, 0] }],
|
|
declarations: [],
|
|
namespaces: []
|
|
})
|
|
continue
|
|
}
|
|
const result = parseSourceFileDocs(cwd, sourceFile, checker, entry)
|
|
if (
|
|
result.diagnostics.length === 0 && result.parsed.declarations.length === 0 &&
|
|
result.parsed.namespaces.length === 0 && result.parsed.moduleJSDoc === undefined
|
|
) continue
|
|
const fileDiagnostics = [...result.diagnostics]
|
|
let importsValue: ParsedJSDocImports | undefined
|
|
if (
|
|
result.parsed.declarations.length > 0 || result.parsed.namespaces.length > 0 ||
|
|
result.parsed.moduleJSDoc !== undefined
|
|
) {
|
|
const imports = resolveJSDocImports(cwd, filename)
|
|
if (imports._tag === "Success") importsValue = imports.value
|
|
else {
|
|
fileDiagnostics.push({
|
|
...diagnostic(
|
|
"imports",
|
|
`Unable to resolve jsdocs imports: ${imports.error}. Add the missing barrel/package export or exclude this file from jsdocs.`
|
|
),
|
|
range: [0, 0]
|
|
})
|
|
}
|
|
}
|
|
modelFiles.push({
|
|
file,
|
|
hash,
|
|
diagnostics: fileDiagnostics,
|
|
...(importsValue === undefined ? {} : { imports: importsValue }),
|
|
...result.parsed
|
|
})
|
|
}
|
|
const filesWithExampleDiagnostics = appendExampleImportDiagnostics(modelFiles)
|
|
const withPublicSeeDiagnostics = buildJSDocApisWithPublicSeeDiagnostics(filesWithExampleDiagnostics, {
|
|
sourceFilesByFile,
|
|
checker,
|
|
entry,
|
|
cwd
|
|
})
|
|
return {
|
|
version: 2,
|
|
generatedBy: "@effect/jsdocs",
|
|
generatedAt: new Date().toISOString(),
|
|
inputHash: computeJSDocInputHash(options),
|
|
files: withPublicSeeDiagnostics.files,
|
|
apis: withPublicSeeDiagnostics.apis
|
|
}
|
|
}
|
|
|
|
export const extractJSDocs = (options: ExtractJSDocsOptions): Effect.Effect<JSDocModel> =>
|
|
Effect.sync(() => extractJSDocsSync(options))
|
|
|
|
export function writeJSDocModel(cwd: string, output: string, model: JSDocModel) {
|
|
const filename = path.resolve(cwd, output)
|
|
fs.mkdirSync(path.dirname(filename), { recursive: true })
|
|
fs.writeFileSync(filename, `${JSON.stringify(model, null, 2)}\n`)
|
|
}
|
|
|
|
export function readJSDocModel(filename: string): Result<JSDocModel, string> {
|
|
if (!fs.existsSync(filename)) return { _tag: "Failure", error: "missing" }
|
|
try {
|
|
const parsed = JSON.parse(fs.readFileSync(filename, "utf8")) as JSDocModel
|
|
if (parsed.version !== 2) return { _tag: "Failure", error: "Unsupported jsdocs model version" }
|
|
if (!Array.isArray(parsed.files)) return { _tag: "Failure", error: "Invalid jsdocs model: files must be an array" }
|
|
if (!Array.isArray(parsed.apis)) return { _tag: "Failure", error: "Invalid jsdocs model: apis must be an array" }
|
|
return { _tag: "Success", value: parsed }
|
|
} catch (error) {
|
|
return { _tag: "Failure", error: `Invalid jsdocs model: ${error instanceof Error ? error.message : String(error)}` }
|
|
}
|
|
}
|
|
|
|
export function sourceHash(source: string): string {
|
|
return hashSource(source)
|
|
}
|