@tsdoctor/pages 0.1.0

package/Build.js

@@ -0,0 +1,525 @@
+import { AvailableFrom, BaseClass, CodeText, EnumMemberRow, EnumMemberTable, Example, ExampleGroup, Member, MemberGroup, MemberIndex, MemberIndexEntry, ParameterRow, ParameterTable, ProseBlock, SeeAlso, Signature as Signature$1, SourceLink, Title } from "./Blocks.js";
+import { codeText, formatExampleCode, prepareExampleCode, prependHiddenImports } from "./Examples.js";
+import { NavEntry } from "./Nav.js";
+import { Page } from "./Page.js";
+import { Markdown, Paragraph, Text } from "@effected/markdown";
+import { Effect, Option, Result, Schema } from "effect";
+import { ApiItemKind } from "@microsoft/api-extractor-model";
+import { ApiItems, Routes, Signature, Tsdoc, TypeReferenceExtractor } from "@tsdoctor/model";
+
+//#region src/Build.ts
+/**
+* The description a page carries when its item has no summary.
+*
+* @public
+*/
+const NO_DESCRIPTION = "No description available.";
+/**
+* The API landing page: frontmatter facts only, no blocks.
+*
+* @public
+*/
+var IndexPage = class extends Schema.Class("IndexPage")({
+	/** The page route (`{baseRoute}/index`). */
+	route: Schema.String,
+	/** The page title. */
+	title: Schema.String,
+	/** The page description. */
+	description: Schema.String
+}) {};
+/**
+* The label of the index page.
+*
+* @public
+*/
+const INDEX_PAGE_TITLE = "API Reference";
+/**
+* Build the API landing page.
+*
+* @public
+*/
+function buildIndexPage(input) {
+	return IndexPage.make({
+		route: `${input.baseRoute}/index`,
+		title: INDEX_PAGE_TITLE,
+		description: `Auto-generated API documentation for ${input.packageName}`
+	});
+}
+const PARSE_OPTIONS = { dialect: "commonmark" };
+/**
+* Parse a one-line prose string as phrasing content. Total: a parse failure
+* (a hardening-guard trip on a pathological string) degrades to the raw
+* text.
+*/
+function phrasing(text) {
+	const parsed = Markdown.parsePhrasingResult(text, PARSE_OPTIONS);
+	return Result.isSuccess(parsed) ? parsed.success : [Text.make({ value: text })];
+}
+/** Cross-link a prose string, then parse it as phrasing content. */
+function linked(linker, text) {
+	return phrasing(linker.link(text));
+}
+/** Parse a prose string as flow content. Total, on the same terms as {@link phrasing}. */
+function flow(text) {
+	const parsed = Markdown.parseResult(text, PARSE_OPTIONS);
+	if (Result.isSuccess(parsed)) {
+		const nodes = parsed.success.children.filter((node) => node.type !== "frontmatter" && node.type !== "mdxjsEsm");
+		if (nodes.length > 0) return nodes;
+	}
+	return [Paragraph.make({ children: [Text.make({ value: text })] })];
+}
+/** The formatted declaration excerpt, or `""` when the item has none. */
+function excerptOf(item) {
+	const declared = item;
+	return declared.excerpt?.text ? Signature.format(declared.excerpt).trim() : "";
+}
+/**
+* Prepend the hidden `import type` lines a code block needs for the external
+* types `scope` references, resolved against `owner`'s package.
+*/
+function withHiddenImports(code, owner, scope, packageName) {
+	const apiPackage = owner.getAssociatedPackage?.();
+	if (!apiPackage) return code;
+	const imports = new TypeReferenceExtractor(apiPackage, packageName).extractImportsForApiItem(scope);
+	return prependHiddenImports(code, imports);
+}
+/** The `class X extends … implements … {` / `interface X<T> extends … {` opening line. */
+function containerDeclaration(item) {
+	const inheritance = ApiItems.inheritance(item);
+	let declaration = item.kind === ApiItemKind.Class ? `class ${item.displayName}` : `interface ${item.displayName}`;
+	if (item.kind === ApiItemKind.Interface) {
+		const typeParameters = item.typeParameters;
+		if (typeParameters && typeParameters.length > 0) declaration += `<${typeParameters.map((parameter) => parameter.name).join(", ")}>`;
+	}
+	if (inheritance.extends && inheritance.extends.length > 0) declaration += ` extends ${inheritance.extends.join(", ")}`;
+	if (item.kind === ApiItemKind.Class && inheritance.implements && inheritance.implements.length > 0) declaration += ` implements ${inheritance.implements.join(", ")}`;
+	return `${declaration} {`;
+}
+/** The full skeleton: the opening line, one indented line per member, the closing brace. */
+function containerSkeleton(item, members) {
+	const lines = [containerDeclaration(item)];
+	for (const member of members) {
+		const signature = excerptOf(member);
+		if (signature) lines.push(`    ${signature}`);
+	}
+	lines.push("}");
+	return lines.join("\n");
+}
+/** The three-line member context the hide-cut transformer trims: opening, member, closing. */
+function memberContext(item, member, packageName) {
+	return withHiddenImports(`${containerDeclaration(item)}\n${excerptOf(member)}\n}`, item, member, packageName);
+}
+const isStatic = (member) => member.isStatic === true;
+const isAccessorName = (member) => member.displayName.startsWith("get ") || member.displayName.startsWith("set ");
+/** Group a class's members the way the class page lists and skeletons them. */
+function classMembers(apiClass) {
+	const properties = apiClass.members.filter((m) => m.kind === "Property" || m.kind === "PropertySignature");
+	const methods = apiClass.members.filter((m) => m.kind === "Method" || m.kind === "MethodSignature");
+	return {
+		constructors: apiClass.members.filter((m) => m.kind === "Constructor"),
+		staticProperties: properties.filter(isStatic),
+		staticMethods: methods.filter((m) => !(m.kind === "Method" && isAccessorName(m)) && isStatic(m)),
+		instanceProperties: properties.filter((m) => !isStatic(m) && !isAccessorName(m)),
+		getters: methods.filter((m) => m.kind === "Method" && isAccessorName(m)),
+		instanceMethods: methods.filter((m) => !(m.kind === "Method" && isAccessorName(m)) && !isStatic(m))
+	};
+}
+/** The anchor a member's page element carries — data from the work item, or the model's own algorithm. */
+function anchorOf(ctx, member) {
+	return ctx.anchors.get(member.canonicalReference?.toString() ?? member.displayName) ?? Routes.memberAnchor(member.displayName);
+}
+function parameterRows(linker, item) {
+	return Tsdoc.params(item).map((parameter) => ParameterRow.make({
+		name: parameter.name,
+		...parameter.type !== void 0 ? { type: parameter.type } : {},
+		description: linked(linker, parameter.description)
+	}));
+}
+/**
+* One member block, or none when the member has no declaration excerpt —
+* the generators rendered nothing for such a member.
+*/
+function buildMember(ctx, member, role, name, anchor, options) {
+	const signature = excerptOf(member);
+	if (!signature) return Option.none();
+	const summary = Tsdoc.summary(member);
+	const parameters = options.parameters ? parameterRows(ctx.linker, member) : [];
+	const returns = options.returns ? Tsdoc.returns(member) : null;
+	return Option.some(Member.make({
+		role,
+		name,
+		anchor,
+		code: CodeText.make({
+			display: signature,
+			source: memberContext(ctx.owner, member, ctx.packageName)
+		}),
+		...summary ? { summary: linked(ctx.linker, summary) } : {},
+		...parameters.length > 0 ? { parameters } : {},
+		...returns ? { returns: linked(ctx.linker, returns.description) } : {}
+	}));
+}
+const fixedMember = (name, anchorName) => ({
+	name,
+	anchor: Routes.memberAnchor(anchorName)
+});
+/** A heading group, or none when no member of the list renders. */
+function memberGroup(ctx, title, members, role, options, fixed) {
+	if (members.length === 0) return Option.none();
+	const built = [];
+	for (const member of members) {
+		const anchor = fixed ? fixed.anchor : anchorOf(ctx, member);
+		const result = buildMember(ctx, member, role, fixed ? fixed.name : member.displayName, anchor, options);
+		if (Option.isSome(result)) built.push(result.value);
+	}
+	return Option.some(MemberGroup.make({
+		title,
+		members: built
+	}));
+}
+function titleBlock(item, linker) {
+	const deprecation = Tsdoc.deprecation(item);
+	return Title.make({
+		name: item.displayName,
+		releaseTag: Tsdoc.releaseTag(item),
+		...deprecation ? { deprecation: linked(linker, deprecation.message) } : {}
+	});
+}
+function headBlocks(input, summary) {
+	const blocks = [titleBlock(input.item, input.linker), ProseBlock.make({
+		role: "summary",
+		content: flow(summary)
+	})];
+	if (input.availableFrom && input.availableFrom.length > 1) blocks.push(AvailableFrom.make({
+		packageName: input.packageName,
+		entryPoints: input.availableFrom
+	}));
+	const href = ApiItems.sourceLink(input.item, input.source);
+	if (href) blocks.push(SourceLink.make({ href }));
+	return blocks;
+}
+const buildExampleWithFallback = (input, example) => Effect.gen(function* () {
+	const prepared = prepareExampleCode(example, input.item.displayName, input.packageName, input.suppressExampleErrors);
+	const formatted = yield* formatExampleCode(prepared.code, prepared.language).pipe(Effect.catchTag("ExampleFormatError", (error) => (input.onExampleFormatError ? input.onExampleFormatError(error) : Effect.void).pipe(Effect.as(prepared.code))));
+	return Example.make({
+		language: prepared.language,
+		code: prepared.isTypeScript ? codeText(formatted) : CodeText.make({
+			display: formatted,
+			source: formatted
+		}),
+		typeChecked: prepared.isTypeScript
+	});
+});
+const tailBlocks = (input) => Effect.gen(function* () {
+	const blocks = [];
+	const examples = Tsdoc.examples(input.item);
+	if (examples.length > 0) {
+		const items = yield* Effect.forEach(examples, (example) => buildExampleWithFallback(input, example));
+		blocks.push(ExampleGroup.make({ items }));
+	}
+	const references = Tsdoc.seeReferences(input.item);
+	if (references.length > 0) blocks.push(SeeAlso.make({ references: references.map((reference) => linked(input.linker, reference.text)) }));
+	return blocks;
+});
+function classBody(input, apiClass) {
+	const { packageName, linker } = input;
+	const members = classMembers(apiClass);
+	const ctx = {
+		owner: apiClass,
+		packageName,
+		linker,
+		anchors: input.memberAnchors ?? ApiItems.memberAnchors(apiClass)
+	};
+	const blocks = [];
+	const skeleton = containerSkeleton(apiClass, [
+		...members.constructors,
+		...members.staticProperties,
+		...members.staticMethods,
+		...members.instanceProperties,
+		...members.getters,
+		...members.instanceMethods
+	]);
+	blocks.push(Signature$1.make({ code: codeText(withHiddenImports(skeleton, apiClass, apiClass, packageName)) }));
+	const base = input.syntheticBase;
+	if (base?.excerpt?.text) {
+		const signature = Signature.format(base.excerpt).trim();
+		blocks.push(BaseClass.make({
+			className: apiClass.displayName,
+			baseName: base.displayName,
+			packageName,
+			code: codeText(withHiddenImports(signature, apiClass, base, packageName))
+		}));
+	}
+	const withParameters = {
+		parameters: true,
+		returns: false
+	};
+	const methodOptions = {
+		parameters: true,
+		returns: true
+	};
+	const propertyOptions = {
+		parameters: false,
+		returns: false
+	};
+	const groups = [
+		memberGroup(ctx, "Constructors", members.constructors, "constructor", withParameters, fixedMember("constructor", "constructor")),
+		memberGroup(ctx, "Static Properties", members.staticProperties, "property", propertyOptions),
+		memberGroup(ctx, "Static Methods", members.staticMethods, "method", methodOptions),
+		memberGroup(ctx, "Properties", members.instanceProperties, "property", propertyOptions),
+		memberGroup(ctx, "Getters & Setters", members.getters, "getter", methodOptions),
+		memberGroup(ctx, "Methods", members.instanceMethods, "method", methodOptions)
+	];
+	for (const group of groups) if (Option.isSome(group)) blocks.push(group.value);
+	return blocks;
+}
+function interfaceBody(input, apiInterface) {
+	const { packageName, linker } = input;
+	const ctx = {
+		owner: apiInterface,
+		packageName,
+		linker,
+		anchors: input.memberAnchors ?? ApiItems.memberAnchors(apiInterface)
+	};
+	const ofKind = (kind) => apiInterface.members.filter((m) => m.kind === kind);
+	const callSignatures = ofKind("CallSignature");
+	const constructSignatures = ofKind("ConstructSignature");
+	const indexSignatures = ofKind("IndexSignature");
+	const properties = ofKind("PropertySignature");
+	const methods = ofKind("MethodSignature");
+	const blocks = [];
+	const skeleton = containerSkeleton(apiInterface, [
+		...callSignatures,
+		...constructSignatures,
+		...indexSignatures,
+		...properties,
+		...methods
+	]);
+	blocks.push(Signature$1.make({ code: codeText(withHiddenImports(skeleton, apiInterface, apiInterface, packageName)) }));
+	const plain = {
+		parameters: false,
+		returns: false
+	};
+	const groups = [
+		memberGroup(ctx, "Call Signatures", callSignatures, "call-signature", plain, fixedMember("Call Signature", "call-signature")),
+		memberGroup(ctx, "Construct Signatures", constructSignatures, "construct-signature", plain, fixedMember("Construct Signature", "construct-signature")),
+		memberGroup(ctx, "Index Signature", indexSignatures, "index-signature", plain, fixedMember("Index Signature", "index-signature")),
+		memberGroup(ctx, "Properties", properties, "property", plain),
+		memberGroup(ctx, "Methods", methods, "method", {
+			parameters: true,
+			returns: true
+		})
+	];
+	for (const group of groups) if (Option.isSome(group)) blocks.push(group.value);
+	return blocks;
+}
+function functionBody(input) {
+	const { item, packageName, linker } = input;
+	const blocks = [];
+	const rows = parameterRows(linker, item);
+	const signature = excerptOf(item);
+	if (signature) blocks.push(Signature$1.make({
+		code: codeText(withHiddenImports(signature, item, item, packageName)),
+		hasParameters: rows.length > 0
+	}));
+	if (rows.length > 0) blocks.push(ParameterTable.make({ rows }));
+	const returns = Tsdoc.returns(item);
+	if (returns) blocks.push(ProseBlock.make({
+		role: "returns",
+		content: [Paragraph.make({ children: [...linked(linker, returns.description)] })]
+	}));
+	return blocks;
+}
+function declarationBody(input) {
+	const { item, packageName } = input;
+	const signature = excerptOf(item);
+	if (!signature) return [];
+	return [Signature$1.make({ code: codeText(withHiddenImports(signature, item, item, packageName)) })];
+}
+/** The initializer after `=` in an enum member's excerpt, without a trailing comma. */
+function enumMemberValue(member) {
+	const text = member.excerpt?.text?.trim();
+	if (!text) return void 0;
+	const equals = text.indexOf("=");
+	if (equals === -1) return void 0;
+	return text.substring(equals + 1).trim().replace(/,\s*$/, "");
+}
+function enumBody(input, apiEnum) {
+	const { linker } = input;
+	const members = apiEnum.members;
+	const lines = [`enum ${apiEnum.displayName} {`];
+	members.forEach((member, index) => {
+		const value = enumMemberValue(member);
+		const line = `    ${member.displayName}${value !== void 0 ? ` = ${value}` : ""}`;
+		lines.push(index < members.length - 1 ? `${line},` : line);
+	});
+	lines.push("}");
+	const hasMembers = members.length > 0;
+	const blocks = [Signature$1.make({
+		code: codeText(lines.join("\n")),
+		hasMembers
+	})];
+	if (hasMembers) blocks.push(EnumMemberTable.make({ rows: members.map((member) => {
+		const value = enumMemberValue(member);
+		return EnumMemberRow.make({
+			name: member.displayName,
+			...value !== void 0 ? { value } : {},
+			description: linked(linker, Tsdoc.summary(member) || "")
+		});
+	}) }));
+	return blocks;
+}
+/** The namespace member index sections, in the order the namespace page lists them. */
+const NAMESPACE_SECTIONS = [
+	[
+		"Classes",
+		ApiItemKind.Class,
+		"class"
+	],
+	[
+		"Interfaces",
+		ApiItemKind.Interface,
+		"interface"
+	],
+	[
+		"Functions",
+		ApiItemKind.Function,
+		"function"
+	],
+	[
+		"Variables",
+		ApiItemKind.Variable,
+		"variable"
+	],
+	[
+		"Types",
+		ApiItemKind.TypeAlias,
+		"type"
+	],
+	[
+		"Enums",
+		ApiItemKind.Enum,
+		"enum"
+	],
+	[
+		"Namespaces",
+		ApiItemKind.Namespace,
+		"namespace"
+	]
+];
+/** A declaration abbreviated to its header — everything before the opening brace. */
+function abbreviate(signature) {
+	const brace = signature.indexOf("{");
+	return brace === -1 ? signature : signature.substring(0, brace).trim();
+}
+function namespaceBody(input, apiNamespace) {
+	const { packageName, linker, baseRoute } = input;
+	const name = apiNamespace.displayName;
+	const lines = [`namespace ${name} {`];
+	const bodied = /* @__PURE__ */ new Set([
+		ApiItemKind.Class,
+		ApiItemKind.Interface,
+		ApiItemKind.Enum,
+		ApiItemKind.Namespace
+	]);
+	for (const [, kind] of NAMESPACE_SECTIONS) for (const member of apiNamespace.members) {
+		if (member.kind !== kind) continue;
+		const signature = excerptOf(member);
+		if (!signature) continue;
+		lines.push(bodied.has(kind) ? `    ${abbreviate(signature)} { }` : `    ${signature}`);
+	}
+	lines.push("}");
+	const blocks = [Signature$1.make({ code: codeText(withHiddenImports(lines.join("\n"), apiNamespace, apiNamespace, packageName)) })];
+	for (const [title, kind, folder] of NAMESPACE_SECTIONS) {
+		const members = apiNamespace.members.filter((member) => member.kind === kind);
+		if (members.length === 0) continue;
+		blocks.push(MemberIndex.make({
+			title,
+			entries: members.map((member) => {
+				const summary = Tsdoc.summary(member);
+				return MemberIndexEntry.make({
+					name: member.displayName,
+					route: `${baseRoute}/${folder}/${`${name}.${member.displayName}`.toLowerCase()}`,
+					...summary ? { summary: linked(linker, summary) } : {}
+				});
+			})
+		}));
+	}
+	return blocks;
+}
+/** The page kind for a supported item kind, or none for anything else. */
+function pageKindOf(kind) {
+	switch (kind) {
+		case ApiItemKind.Class: return Option.some("class");
+		case ApiItemKind.Interface: return Option.some("interface");
+		case ApiItemKind.Function: return Option.some("function");
+		case ApiItemKind.TypeAlias: return Option.some("type-alias");
+		case ApiItemKind.Enum: return Option.some("enum");
+		case ApiItemKind.Variable: return Option.some("variable");
+		case ApiItemKind.Namespace: return Option.some("namespace");
+		default: return Option.none();
+	}
+}
+/**
+* Whether {@link buildPage} produces a page for an item of this kind.
+*
+* @public
+*/
+function isPageKind(kind) {
+	return Option.isSome(pageKindOf(kind));
+}
+function bodyFor(input, kind) {
+	switch (kind) {
+		case "class": return classBody(input, input.item);
+		case "interface": return interfaceBody(input, input.item);
+		case "function": return functionBody(input);
+		case "enum": return enumBody(input, input.item);
+		case "namespace": return namespaceBody(input, input.item);
+		case "type-alias":
+		case "variable": return declarationBody(input);
+	}
+}
+/**
+* Build the page for one item, or none for an item kind that gets no page.
+*
+* @remarks
+* The route is `{baseRoute}/{folderName}/{name}` with the name lowercased;
+* a namespace member's last segment is its lowercased qualified name, which
+* is also its sidebar label. Only Prettier can fail here, and that failure
+* degrades through {@link BuildPageInput.onExampleFormatError}, so the
+* error channel is `never`.
+*
+* @public
+*/
+const buildPage = Effect.fn("Build.buildPage")(function* (input) {
+	const kind = pageKindOf(input.item.kind);
+	if (Option.isNone(kind)) return Option.none();
+	const { item } = input;
+	const summary = Tsdoc.summary(item) || "No description available.";
+	const label = input.namespaceMember ? input.namespaceMember.qualifiedName : item.displayName;
+	const name = label.toLowerCase();
+	const route = `${input.baseRoute}/${input.folderName}/${name}`;
+	const blocks = [
+		...headBlocks(input, summary),
+		...bodyFor(input, kind.value),
+		...yield* tailBlocks(input)
+	];
+	return Option.some(Page.make({
+		kind: kind.value,
+		entityName: item.displayName,
+		singularName: input.singularName,
+		...input.apiName !== void 0 ? { apiName: input.apiName } : {},
+		description: summary,
+		route,
+		headTags: input.headTags ?? [],
+		blocks,
+		nav: NavEntry.make({
+			categoryKey: input.categoryKey,
+			label,
+			name,
+			route
+		})
+	}));
+});
+
+//#endregion
+export { INDEX_PAGE_TITLE, IndexPage, NO_DESCRIPTION, buildIndexPage, buildPage, isPageKind };