@sayoriqwq/effect-harness 0.0.1

package/repos/effect/packages/tools/jsdocs/src/Jsdocs.ts

@@ -0,0 +1,3303 @@
+/*
+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 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 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(),
+    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)
+}