#!/usr/bin/env node

import fs from "node:fs";

import path from "node:path";

import { execFileSync } from "node:child_process";

import { fileURLToPath } from "node:url";

import ts from "typescript";

const REPO_URL = "https://github.com/solidjs/solid.git";

const DEFAULT_SOURCE = "/tmp/solid-v2-source";

const DEFAULT_OUT = "src/routes/v2/reference";

const DEFAULT_REF = "next";

const SPARSE_PATHS = [

"packages/solid",

"packages/solid-web",

"packages/solid-signals",

"documentation/solid-2.0",

];

const ENTRYPOINTS = [

{

packageName: "solid-js",

path: "packages/solid/src/index.ts",

},

{

packageName: "@solidjs/web",

path: "packages/solid-web/src/index.ts",

},

{

packageName: "@solidjs/signals",

path: "packages/solid-signals/src/index.ts",

},

];

const GENERATED_MARKER =

"Generated by scripts/extract-solid-ref.mjs. Edit the source JSDoc or disposition map, then regenerate.";

const TOP_LEVEL_ROUTE_ORDER = {

reactivity: "(1)reactivity",

stores: "(2)stores",

"lifecycle-actions": "(3)lifecycle-actions",

"components-context": "(4)components-context",

"components-jsx": "(5)components-jsx",

"rendering-ssr": "(6)rendering-ssr",

advanced: "(7)advanced",

types: "(8)types",

};

const ADVANCED_ROUTE_ORDER = {

"owner-introspection": "(1)owner-introspection",

"specialized-reactivity": "(2)specialized-reactivity",

"store-advanced": "(3)store-advanced",

"jsx-component-primitives": "(4)jsx-component-primitives",

"manual-hydration": "(5)manual-hydration",

"interop-async": "(6)interop-async",

"diagnostics-dev-hooks": "(7)diagnostics-dev-hooks",

};

const CANONICAL_ROUTES = {

createEffect: ["reactivity/create-effect.mdx", "Reactivity"],

createMemo: ["reactivity/create-memo.mdx", "Reactivity"],

createOptimistic: ["reactivity/create-optimistic.mdx", "Reactivity"],

createSignal: ["reactivity/create-signal.mdx", "Reactivity"],

flush: ["reactivity/flush.mdx", "Reactivity"],

isPending: ["reactivity/is-pending.mdx", "Reactivity"],

latest: ["reactivity/latest.mdx", "Reactivity"],

untrack: ["reactivity/untrack.mdx", "Reactivity"],

createOptimisticStore: ["stores/create-optimistic-store.mdx", "Stores"],

createProjection: ["stores/create-projection.mdx", "Stores"],

createStore: ["stores/create-store.mdx", "Stores"],

merge: ["stores/merge.mdx", "Stores"],

omit: ["stores/omit.mdx", "Stores"],

reconcile: ["stores/reconcile.mdx", "Stores"],

action: ["lifecycle-actions/action.mdx", "Lifecycle & Actions"],

onSettled: ["lifecycle-actions/on-settled.mdx", "Lifecycle & Actions"],

refresh: ["lifecycle-actions/refresh.mdx", "Lifecycle & Actions"],

children: ["components-context/children.mdx", "Components & Context"],

createContext: [

"components-context/create-context.mdx",

"Components & Context",

],

createUniqueId: [

"components-context/create-unique-id.mdx",

"Components & Context",

],

dynamic: ["components-context/dynamic.mdx", "Components & Context"],

lazy: ["components-context/lazy.mdx", "Components & Context"],

useContext: ["components-context/use-context.mdx", "Components & Context"],

Dynamic: ["components-jsx/dynamic.mdx", "Components (JSX)"],

Errored: ["components-jsx/errored.mdx", "Components (JSX)"],

For: ["components-jsx/for.mdx", "Components (JSX)"],

Loading: ["components-jsx/loading.mdx", "Components (JSX)"],

Match: ["components-jsx/switch-and-match.mdx", "Components (JSX)"],

Portal: ["components-jsx/portal.mdx", "Components (JSX)"],

Repeat: ["components-jsx/repeat.mdx", "Components (JSX)"],

Reveal: ["components-jsx/reveal.mdx", "Components (JSX)"],

Show: ["components-jsx/show.mdx", "Components (JSX)"],

Switch: ["components-jsx/switch-and-match.mdx", "Components (JSX)"],

hydrate: ["rendering-ssr/hydrate.mdx", "Rendering & SSR"],

isDev: ["rendering-ssr/is-dev.mdx", "Rendering & SSR"],

isServer: ["rendering-ssr/is-server.mdx", "Rendering & SSR"],

render: ["rendering-ssr/render.mdx", "Rendering & SSR"],

renderToStream: ["rendering-ssr/render-to-stream.mdx", "Rendering & SSR"],

renderToString: ["rendering-ssr/render-to-string.mdx", "Rendering & SSR"],

renderToStringAsync: [

"rendering-ssr/render-to-string-async.mdx",

"Rendering & SSR",

],

};

const ADVANCED_ROUTES = {

createRoot: [

"advanced/owner-introspection/create-root.mdx",

"Advanced / Owner & Introspection",

],

getObserver: [

"advanced/owner-introspection/get-observer.mdx",

"Advanced / Owner & Introspection",

],

getOwner: [

"advanced/owner-introspection/get-owner.mdx",

"Advanced / Owner & Introspection",

],

isDisposed: [

"advanced/owner-introspection/is-disposed.mdx",

"Advanced / Owner & Introspection",

],

runWithOwner: [

"advanced/owner-introspection/run-with-owner.mdx",

"Advanced / Owner & Introspection",

],

createReaction: [

"advanced/specialized-reactivity/create-reaction.mdx",

"Advanced / Specialized Reactivity & Tracking",

],

createRenderEffect: [

"advanced/specialized-reactivity/create-render-effect.mdx",

"Advanced / Specialized Reactivity & Tracking",

],

createTrackedEffect: [

"advanced/specialized-reactivity/create-tracked-effect.mdx",

"Advanced / Specialized Reactivity & Tracking",

],

isRefreshing: [

"advanced/specialized-reactivity/is-refreshing.mdx",

"Advanced / Specialized Reactivity & Tracking",

],

onCleanup: [

"advanced/specialized-reactivity/on-cleanup.mdx",

"Advanced / Specialized Reactivity & Tracking",

],

deep: ["advanced/store-advanced/deep.mdx", "Advanced / Store Advanced"],

isWrappable: [

"advanced/store-advanced/is-wrappable.mdx",

"Advanced / Store Advanced",

],

snapshot: [

"advanced/store-advanced/snapshot.mdx",

"Advanced / Store Advanced",

],

storePath: [

"advanced/store-advanced/store-path.mdx",

"Advanced / Store Advanced",

],

createErrorBoundary: [

"advanced/jsx-component-primitives/create-error-boundary.mdx",

"Advanced / JSX Component Primitives",

],

createLoadingBoundary: [

"advanced/jsx-component-primitives/create-loading-boundary.mdx",

"Advanced / JSX Component Primitives",

],

createRevealOrder: [

"advanced/jsx-component-primitives/create-reveal-order.mdx",

"Advanced / JSX Component Primitives",

],

mapArray: [

"advanced/jsx-component-primitives/map-array.mdx",

"Advanced / JSX Component Primitives",

],

repeat: [

"advanced/jsx-component-primitives/repeat.mdx",

"Advanced / JSX Component Primitives",

],

Hydration: [

"advanced/manual-hydration/hydration.mdx",

"Advanced / Manual Hydration",

],

NoHydration: [

"advanced/manual-hydration/no-hydration.mdx",

"Advanced / Manual Hydration",

],

enableExternalSource: [

"advanced/interop-async/enable-external-source.mdx",

"Advanced / Interop & Async",

],

flatten: ["advanced/interop-async/flatten.mdx", "Advanced / Interop & Async"],

NotReadyError: [

"advanced/interop-async/not-ready-error.mdx",

"Advanced / Interop & Async",

],

resolve: ["advanced/interop-async/resolve.mdx", "Advanced / Interop & Async"],

DEV: [

"advanced/diagnostics-dev-hooks/dev.mdx",

"Advanced / Diagnostics & Dev Hooks",

],

};

const STANDALONE_TYPE_ROUTES = {

Accessor: ["types/reactive-types.mdx", "Types"],

SourceAccessor: ["types/reactive-types.mdx", "Types"],

Setter: ["types/reactive-types.mdx", "Types"],

Signal: ["types/reactive-types.mdx", "Types"],

Component: ["types/component-types.mdx", "Types"],

ParentComponent: ["types/component-types.mdx", "Types"],

VoidComponent: ["types/component-types.mdx", "Types"],

FlowComponent: ["types/component-types.mdx", "Types"],

ParentProps: ["types/component-types.mdx", "Types"],

VoidProps: ["types/component-types.mdx", "Types"],

FlowProps: ["types/component-types.mdx", "Types"],

ValidComponent: ["types/component-types.mdx", "Types"],

ComponentProps: ["types/component-types.mdx", "Types"],

Ref: ["types/component-types.mdx", "Types"],

Context: ["types/context-types.mdx", "Types"],

ContextProviderComponent: ["types/context-types.mdx", "Types"],

Store: ["types/store-types.mdx", "Types"],

StoreNode: ["types/store-types.mdx", "Types"],

SolidStore: ["types/store-types.mdx", "Types"],

Owner: ["types/owner.mdx", "Types"],

JSX: ["types/jsx-types.mdx", "Types"],

JSXElement: ["types/jsx-types.mdx", "Types"],

};

const FOLD_INTO = {

ArrayFilterFn: "storePath",

ChildrenReturn: "children",

ComputeFunction: "createEffect",

ContextNotFoundError: "useContext",

ContextRecord: "createContext",

CustomPartial: "storePath",

ArrayElement: "JSXElement",

Dev: "DEV",

DevHooks: "DEV",

DiagnosticCapture: "DEV",

DiagnosticCode: "DEV",

DiagnosticEvent: "DEV",

DiagnosticKind: "DEV",

Diagnostics: "DEV",

DiagnosticSeverity: "DEV",

DynamicProps: "Dynamic",

EffectBundle: "createEffect",

EffectFunction: "createEffect",

EffectOptions: "createEffect",

ExternalSource: "enableExternalSource",

ExternalSourceConfig: "enableExternalSource",

ExternalSourceFactory: "enableExternalSource",

HydrationProjectionOptions: "createProjection",

IntrinsicElement: "JSXElement",

KeyedMatchProps: "Switch",

AnyMatchProps: "Switch",

Maybe: "mapArray",

Merge: "merge",

MemoOptions: ["createMemo", "createSignal"],

NoOwnerError: "getOwner",

NoInfer: "createSignal",

NotWrappable: "isWrappable",

Omit: "omit",

Part: "storePath",

PathSetter: "storePath",

ProjectionOptions: ["createProjection", "createStore"],

PatchOp: "createStore",

Refreshable: ["createOptimisticStore", "createProjection", "createStore"],

RevealOrder: "Reveal",

RevealProps: "Reveal",

ResolvedChildren: "children",

ResolvedElement: "JSXElement",

ResolvedJSXElement: "children",

Element: "JSXElement",

MatchProps: "Switch",

SignalOptions: ["createSignal", "createMemo"],

StoreOptions: "createStore",

StorePathRange: "storePath",

StoreReturn: "createStore",

StoreSetter: "createStore",

ProjectionStoreReturn: ["createProjection", "createStore"],

isEqual: ["createSignal", "createMemo"],

};

const HIDDEN_EXPORTS = new Set([

"$DEVCOMP",

"$PROXY",

"$REFRESH",

"$TRACK",

"SUPPORTS_PROXY",

"Namespaces",

"SVGElements",

"MathMLElements",

"addEventListener",

"clearSnapshots",

"createComponent",

"createDeepProxy",

"createOwner",

"enableHydration",

"enforceLoadingBoundary",

"escape",

"getContext",

"getNextChildId",

"getNextElement",

"HydrationContext",

"insert",

"IQueue",

"markSnapshotScope",

"mergeProps",

"NoHydrateContext",

"peekNextChildId",

"releaseSnapshotScope",

"resolveSSRNode",

"setSnapshotCapture",

"setContext",

"sharedConfig",

"spread",

"SSRTemplateObject",

"ssr",

"ssrAttribute",

"ssrClassList",

"ssrElement",

"ssrHandleError",

"ssrHydrationKey",

"ssrRunInScope",

"ssrStyle",

"template",

]);

const ENTRY_CALLOUTS = {

Dynamic:

"> `<Dynamic>` is the JSX convenience wrapper for `dynamic()`. Prefer `dynamic()` when you need a reusable stable component reference.",

createRoot:

"> `render()` creates the root for normal app code. Reach for `createRoot` in tests, libraries, or non-render entry points that need to host a reactive scope.",

dynamic:

"> `dynamic()` is the canonical API: it returns a stable component identity and composes with `lazy()` and routing. Use `<Dynamic>` when the choice happens at a JSX callsite.",

onCleanup:

"> For component setup and teardown in Solid 2.0, prefer `onSettled` and return a cleanup function. Keep `onCleanup` for advanced owner and custom primitive internals.",

};

const scriptPath = fileURLToPath(import.meta.url);

const repoRoot = path.resolve(path.dirname(scriptPath), "..");

const args = parseArgs(process.argv.slice(2));

const sourceDir = path.resolve(args.source ?? DEFAULT_SOURCE);

const sourceRef = args["source-ref"] ?? DEFAULT_REF;

const outDir = path.resolve(repoRoot, args.out ?? DEFAULT_OUT);

const dryRun = Boolean(args["dry-run"]);

const skipFetch = Boolean(args["skip-fetch"]);

if (args.help) {

printHelp();

process.exit(0);

}

if (!skipFetch) {

ensureSourceCheckout(sourceDir, sourceRef);

}

const sourceSha = git(["-C", sourceDir, "rev-parse", "HEAD"]).trim();

const program = createProgram(sourceDir);

const checker = program.getTypeChecker();

const reference = collectEntries(program, checker, sourceDir);

const files = buildOutputFiles(reference, {

sourceDir,

sourceRef,

sourceSha,

});

if (dryRun) {

printDryRun(files, reference, sourceSha);

} else {

writeFiles(files);

console.log(

`Wrote ${files.length} reference file(s) to ${path.relative(repoRoot, outDir)}`

);

console.log(`Solid source SHA: ${sourceSha}`);

}

function parseArgs(rawArgs) {

const parsed = {};

for (let i = 0; i < rawArgs.length; i++) {

const arg = rawArgs[i];

if (!arg.startsWith("--")) {

throw new Error(`Unexpected argument: ${arg}`);

}

const key = arg.slice(2);

if (["dry-run", "skip-fetch", "help"].includes(key)) {

parsed[key] = true;

continue;

}

const next = rawArgs[++i];

if (!next || next.startsWith("--")) {

throw new Error(`Missing value for --${key}`);

}

parsed[key] = next;

}

return parsed;

}

function printHelp() {

console.log(`Usage:

node scripts/extract-solid-ref.mjs [options]

Options:

--source-ref <ref> Solid source ref to fetch. Defaults to "next".

--source <path> Local solidjs/solid checkout. Defaults to /tmp/solid-v2-source.

--out <path> Output directory. Defaults to src/routes/v2/reference.

--dry-run Print planned files without writing MDX.

--skip-fetch Use the current local checkout as-is.

--help Show this help.

`);

}

function ensureSourceCheckout(dir, ref) {

if (!fs.existsSync(dir)) {

git(["clone", "--filter=blob:none", "--sparse", REPO_URL, dir]);

} else if (!fs.existsSync(path.join(dir, ".git"))) {

throw new Error(`${dir} exists but is not a git checkout`);

}

git(["-C", dir, "sparse-checkout", "set", ...SPARSE_PATHS]);

git(["-C", dir, "fetch", "origin", ref, "--depth=1"]);

git(["-C", dir, "checkout", "--detach", "FETCH_HEAD"]);

}

function git(args) {

return execFileSync("git", args, {

encoding: "utf8",

stdio: ["ignore", "pipe", "inherit"],

});

}

function createProgram(root) {

const options = {

allowJs: false,

allowSyntheticDefaultImports: true,

esModuleInterop: true,

jsx: ts.JsxEmit.Preserve,

module: ts.ModuleKind.NodeNext,

moduleResolution: ts.ModuleResolutionKind.NodeNext,

noEmit: true,

skipLibCheck: true,

target: ts.ScriptTarget.ES2022,

baseUrl: root,

paths: {

"solid-js": ["packages/solid/src/index.ts"],

"@solidjs/signals": ["packages/solid-signals/src/index.ts"],

"@solidjs/web": ["packages/solid-web/src/index.ts"],

},

};

const rootNames = [

...ENTRYPOINTS.map((entry) => path.join(root, entry.path)),

...collectTsFiles(path.join(root, "packages/solid/src")),

...collectTsFiles(path.join(root, "packages/solid-web/src")),

...collectTsFiles(path.join(root, "packages/solid-signals/src")),

];

const host = ts.createCompilerHost(options);

const originalResolve = ts.resolveModuleName;

host.resolveModuleNames = (moduleNames, containingFile) =>

moduleNames.map((moduleName) => {

const alias = resolveAlias(root, moduleName);

if (alias) {

return {

resolvedFileName: alias,

extension: ts.Extension.Ts,

};

}

if (moduleName.startsWith(".")) {

const local = resolveLocalModule(containingFile, moduleName);

if (local) {

return {

resolvedFileName: local,

extension: ts.Extension.Ts,

};

}

}

return originalResolve(moduleName, containingFile, options, host)

.resolvedModule;

});

return ts.createProgram([...new Set(rootNames)], options, host);

}

function resolveAlias(root, moduleName) {

const aliases = {

"solid-js": "packages/solid/src/index.ts",

"@solidjs/signals": "packages/solid-signals/src/index.ts",

"@solidjs/web": "packages/solid-web/src/index.ts",

};

return aliases[moduleName] ? path.join(root, aliases[moduleName]) : undefined;

}

function resolveLocalModule(containingFile, moduleName) {

const base = path.resolve(path.dirname(containingFile), moduleName);

const candidates = [

base,

base.replace(/\.js$/, ".ts"),

`${base}.ts`,

path.join(base, "index.ts"),

];

return candidates.find((candidate) => fs.existsSync(candidate));

}

function collectTsFiles(dir) {

if (!fs.existsSync(dir)) return [];

const files = [];

for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {

const fullPath = path.join(dir, entry.name);

if (entry.isDirectory()) {

files.push(...collectTsFiles(fullPath));

} else if (

entry.isFile() &&

fullPath.endsWith(".ts") &&

!fullPath.endsWith(".d.ts")

) {

files.push(fullPath);

}

}

return files;

}

function collectEntries(program, checker, root) {

const entries = [];

const foldedEntries = [];

const byName = new Map();

const foldedByName = new Map();

for (const entrypoint of ENTRYPOINTS) {

const sourceFile = program.getSourceFile(path.join(root, entrypoint.path));

if (!sourceFile) {

throw new Error(`Entrypoint not found: ${entrypoint.path}`);

}

const moduleSymbol = checker.getSymbolAtLocation(sourceFile);

if (!moduleSymbol) continue;

for (const exportedSymbol of checker.getExportsOfModule(moduleSymbol)) {

const name = exportedSymbol.getName();

if (shouldSkipName(name)) continue;

const symbol = resolveSymbol(checker, exportedSymbol);

const declarations = declarationList(symbol).filter((declaration) =>

isSourceDeclaration(root, declaration)

);

if (!declarations.length) continue;

const docs = getDocs(declarations);

const disposition = getDisposition(name, docs);

if (disposition.type === "hidden") {

continue;

}

if (disposition.type === "missing") {

throw new Error(

`Missing reference disposition for exported symbol "${name}". Add it to CANONICAL_ROUTES, ADVANCED_ROUTES, STANDALONE_TYPE_ROUTES, FOLD_INTO, HIDDEN_EXPORTS, or mark it @internal upstream.`

);

}

const primary = selectPrimaryDeclaration(declarations);

const entry = createEntry({

name,

entrypoint,

primary,

root,

declarations,

docs,

checker,

exportedSymbol,

symbol,

disposition,

});

if (disposition.type === "fold") {

const existing = foldedByName.get(name);

if (existing) {

mergeDuplicateEntry(existing, entry);

} else {

foldedByName.set(name, entry);

foldedEntries.push(entry);

}

continue;

}

const existing = byName.get(name);

if (existing) {

mergeDuplicateEntry(existing, entry);

} else {

byName.set(name, entry);

entries.push(entry);

}

}

}

return {

pages: entries.sort(

(a, b) =>

a.route.outputPath.localeCompare(b.route.outputPath) ||

a.name.localeCompare(b.name)

),

folds: foldedEntries.sort((a, b) => a.name.localeCompare(b.name)),

};

}

function createEntry({

name,

entrypoint,

primary,

root,

declarations,

docs,

checker,

exportedSymbol,

symbol,

disposition,

}) {

const sourceFilePath = primary.getSourceFile().fileName;

const sourcePath = relativePath(root, sourceFilePath);

const line =

primary.getSourceFile().getLineAndCharacterOfPosition(primary.getStart())

.line + 1;

return {

name,

packageName: entrypoint.packageName,

kind: getKind(primary),

sourcePath,

line,

docs,

signature: getSignature(name, declarations, checker),

memberDocs: getMemberDocs(declarations),

route: disposition.route,

foldTargets: disposition.targets ?? [],

aliases: getExportAliases(name, exportedSymbol, symbol),

};

}

function mergeDuplicateEntry(existing, incoming) {

if (!existing.docs.summary && incoming.docs.summary) {

existing.kind = incoming.kind;

existing.sourcePath = incoming.sourcePath;

existing.line = incoming.line;

existing.docs = incoming.docs;

existing.signature = incoming.signature;

existing.aliases = incoming.aliases;

}

}

function shouldSkipName(name) {

return false;

}

function resolveSymbol(checker, symbol) {

if ((symbol.flags & ts.SymbolFlags.Alias) !== 0) {

try {

return checker.getAliasedSymbol(symbol);

} catch {

return symbol;

}

}

return symbol;

}

function declarationList(symbol) {

return symbol.declarations ?? [];

}

function isSourceDeclaration(root, declaration) {

const fileName = declaration.getSourceFile().fileName;

return fileName.startsWith(path.join(root, "packages"));

}

function selectPrimaryDeclaration(declarations) {

const withDocs = declarations.find(

(declaration) => getDocs([declaration]).summary

);

return withDocs ?? declarations[0];

}

function getKind(declaration) {

if (

ts.isInterfaceDeclaration(declaration) ||

ts.isTypeAliasDeclaration(declaration) ||

ts.isTypeParameterDeclaration(declaration)

) {

return "type";

}

if (ts.isModuleDeclaration(declaration)) {

return "namespace";

}

return "value";

}

function getDocs(declarations) {

const result = {

summary: "",

params: [],

returns: "",

examples: [],

see: [],

related: [],

useCases: "",

tags: [],

deprecated: "",

internal: false,

remarks: "",

description: "",

};

for (const declaration of declarations) {

const docs = declaration.jsDoc ?? [];

for (const doc of docs) {

const summary = normalizeMarkdown(renderComment(doc.comment));

if (summary) result.summary = summary;

for (const tag of doc.tags ?? []) {

const tagName = tag.tagName.getText();

const normalizedTagName = normalizeTagName(tagName);

const comment = normalizeMarkdown(renderComment(tag.comment));

if (tagName === "param" && ts.isJSDocParameterTag(tag)) {

result.params.push({

name: tag.name.getText(),

text: comment,

});

} else if (tagName === "returns" || tagName === "return") {

result.returns = comment;

} else if (tagName === "example") {

if (comment) result.examples.push(comment);

} else if (tagName === "see") {

const see = normalizeMarkdown(renderSeeTag(tag));

if (see) result.see.push(see);

} else if (tagName === "deprecated") {

result.deprecated = comment || "Deprecated.";

} else if (tagName === "internal") {

result.internal = true;

} else if (tagName === "remarks") {

result.remarks = comment;

} else if (tagName === "description") {

result.description = comment;

} else if (normalizedTagName === "solidusecases") {

const values = parseCsvTag(comment);

if (values.length) result.useCases = values.join(", ");

} else if (normalizedTagName === "solidtags") {

result.tags.push(...parseCsvTag(comment));

} else if (normalizedTagName === "solidrelated") {

result.related.push(...parseCsvTag(comment));

}

}

}

}

result.see = uniqueStrings(result.see);

result.related = uniqueStrings(result.related);

result.tags = uniqueStrings(result.tags);

return result;

}

function renderComment(comment) {

if (!comment) return "";

if (typeof comment === "string") return comment;

return comment.map((part) => renderCommentPart(part)).join("");

}

function renderCommentPart(part) {

if (

ts.isJSDocLink?.(part) ||

ts.isJSDocLinkCode?.(part) ||

ts.isJSDocLinkPlain?.(part)

) {

return renderDocLink(part);

}

if (typeof part.text === "string") return part.text;

return part.getText?.() ?? "";

}

function renderDocLink(part) {

const name = part.name?.getText?.();

const text = part.text?.trim();

const label = text || name;

if (name) {

const route = getRouteForSymbol(name);

if (route) {

const href = toReferenceHref(route.outputPath);

return `[${escapeLinkLabel(label || name)}](${href})`;

}

}

return label ? `\`${label}\`` : "";

}

function normalizeMarkdown(value) {

const normalized = String(value)

.replace(/\r\n/g, "\n")

.replace(/^\s+\*\s/gm, "")

.replace(/\[([A-Z][A-Z0-9_]{2,})\](?!\()/g, "`$1`")

.trim();

return capitalizeSentences(normalized);

}

function capitalizeSentences(value) {

if (!value) return value;

return splitFencedCode(value)

.map((part) =>

part.fence ? part.text : capitalizeSentencesInPlainText(part.text)

)

.join("");

}

function capitalizeSentencesInPlainText(value) {

return value

.split(/(`[^`]*`)/g)

.map((part) => {

if (part.startsWith("`")) return part;

return part.replace(

/(^|[.!?]\s+|\n{2,}\s*|\n\s*(?:[-*+]\s+|>\s+))([a-z])/g,

(_match, prefix, first) => `${prefix}${first.toUpperCase()}`

);

})

.join("");

}

function normalizeTagName(tagName) {

return String(tagName)

.toLowerCase()

.replace(/[^a-z0-9]/g, "");

}

function parseCsvTag(value) {

if (!value) return [];

return value

.split(/[\n,]/)

.map((item) => item.trim())

.filter(Boolean);

}

function uniqueStrings(values) {

return [...new Set(values.map((value) => value.trim()).filter(Boolean))];

}

function renderSeeTag(tag) {

const comment = renderComment(tag.comment);

if (comment) return comment;

const name = tag.name?.getText?.();

if (name) return name;

const raw = tag.getText?.() ?? "";

return raw.replace(/^@see\s*/, "");

}

function getSignature(name, declarations, checker) {

const functionDeclarations = declarations.filter(ts.isFunctionDeclaration);

if (functionDeclarations.length) {

const overloads = functionDeclarations.filter(

(declaration) => !declaration.body

);

const targets = overloads.length ? overloads : functionDeclarations;

return targets

.map((declaration) => cleanSignature(signatureFromNode(declaration)))

.join("\n");

}

const classDeclaration = declarations.find(ts.isClassDeclaration);

if (classDeclaration)

return cleanSignature(signatureFromNode(classDeclaration));

const interfaceDeclaration = declarations.find(ts.isInterfaceDeclaration);

if (interfaceDeclaration)

return cleanSignature(

stripMemberDocs(signatureFromNode(interfaceDeclaration))

);

const typeAlias = declarations.find(ts.isTypeAliasDeclaration);

if (typeAlias)

return cleanSignature(stripMemberDocs(signatureFromNode(typeAlias)));

const variableDeclaration = declarations.find(ts.isVariableDeclaration);

if (variableDeclaration) {

const type = checker.typeToString(

checker.getTypeOfSymbolAtLocation(

checker.getSymbolAtLocation(variableDeclaration.name) ??

checker.getTypeAtLocation(variableDeclaration).symbol,

variableDeclaration

),

variableDeclaration,

ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseFullyQualifiedType

);

return `const ${name}: ${type};`;

}

const enumDeclaration = declarations.find(ts.isEnumDeclaration);

if (enumDeclaration)

return cleanSignature(signatureFromNode(enumDeclaration));

const primary = declarations[0];

return cleanSignature(signatureFromNode(primary));

}

function stripMemberDocs(value) {

return value.replace(/\/\*\*[\s\S]*?\*\/\s*/g, "");

}

function getTypeMembers(declarations) {

for (const declaration of declarations) {

if (ts.isInterfaceDeclaration(declaration)) return declaration.members;

if (

ts.isTypeAliasDeclaration(declaration) &&

declaration.type &&

ts.isTypeLiteralNode(declaration.type)

) {

return declaration.type.members;

}

}

return null;

}

function getMemberDocs(declarations) {

const members = getTypeMembers(declarations);

if (!members) return [];

return members

.map((member) => {

if (!member.name) return null;

const name = member.name.getText();

const type = member.type

? member.type.getText(member.getSourceFile())

: "";

const text = (member.jsDoc ?? [])

.map((doc) => normalizeMarkdown(renderComment(doc.comment)))

.filter(Boolean)

.join("\n\n");

return { name, type, text };

})

.filter(Boolean);

}

function signatureFromNode(node) {

const sourceFile = node.getSourceFile();

if (ts.isFunctionDeclaration(node) && node.body) {

return `${sourceFile.text.slice(node.getStart(sourceFile), node.body.getStart(sourceFile)).trim()};`;

}

const text = node.getText(sourceFile);

const withoutDocs = text.replace(/^\/\*\*[\s\S]*?\*\/\s*/g, "");

return withoutDocs;

}

function cleanSignature(value) {

return value

.replace(/\r\n/g, "\n")

.replace(/^export\s+/gm, "")

.replace(/^declare\s+/gm, "")

.replace(/\n{3,}/g, "\n\n")

.trim()

.replace(/;?$/, ";");

}

function getExportAliases(name, exportedSymbol, resolvedSymbol) {

return exportedSymbol === resolvedSymbol ||

exportedSymbol.getName() === resolvedSymbol.getName()

? []

: [resolvedSymbol.getName()].filter((alias) => alias !== name);

}

function getDisposition(name, docs) {

if (docs.internal || HIDDEN_EXPORTS.has(name) || name.startsWith("$")) {

return { type: "hidden" };

}

if (FOLD_INTO[name]) {

return { type: "fold", targets: normalizeTargets(FOLD_INTO[name]) };

}

const route = getRouteForSymbol(name);

if (route) {

return { type: route.visibility, route };

}

return { type: "missing" };

}

function normalizeTargets(target) {

return Array.isArray(target) ? target : [target];