@tsdoctor/model 0.1.0 → 0.2.0

package/Tsdoc.js

@@ -0,0 +1,250 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { ApiDocumentedItem, ApiReleaseTagMixin, ReleaseTag } from "@microsoft/api-extractor-model";
+import { Code, InlineCode, Link, Paragraph, Text } from "@effected/markdown";
+
+//#region src/Tsdoc.ts
+var Tsdoc_exports = /* @__PURE__ */ __exportAll({
+	deprecation: () => deprecation,
+	examples: () => examples,
+	hasModifier: () => hasModifier,
+	params: () => params,
+	plainText: () => plainText,
+	releaseTag: () => releaseTag,
+	returns: () => returns,
+	seeReferences: () => seeReferences,
+	summary: () => summary,
+	toMarkdown: () => toMarkdown
+});
+/**
+* Recursively flatten a TSDoc DocNode tree to plain text (code spans →
+* backticks, `{@link}` → display text, code fences dropped).
+*
+* @public
+*/
+function plainText(node) {
+	const nodeAny = node;
+	if (node.kind === "PlainText") return nodeAny.text || "";
+	if (node.kind === "SoftBreak") return " ";
+	if (node.kind === "CodeSpan") return `\`${nodeAny.code || ""}\``;
+	if (node.kind === "LinkTag") {
+		if (nodeAny.linkText) return plainText(nodeAny.linkText);
+		return (nodeAny.codeDestination?.memberReferences?.[0]?.memberIdentifier)?.identifier || "";
+	}
+	const parts = [];
+	if (typeof nodeAny.getChildNodes === "function") for (const child of nodeAny.getChildNodes()) {
+		const childText = plainText(child);
+		if (childText) parts.push(childText);
+	}
+	return parts.join("");
+}
+/**
+* Convert a TSDoc DocNode tree to markdown nodes, preserving structure the
+* plain-text flattener drops: code spans become {@link InlineCode}, url
+* `{@link}` tags become {@link Link} nodes, fenced code becomes {@link Code}
+* blocks. Code-destination `{@link}` tags (declaration references) flatten to
+* their display text — resolving them to URLs is the caller's cross-linking
+* concern, not this layer's.
+*
+* @public
+*/
+function toMarkdown(node) {
+	const nodeAny = node;
+	switch (node.kind) {
+		case "Paragraph": {
+			const children = inlineNodes(node);
+			return children.length > 0 ? [new Paragraph({ children })] : [];
+		}
+		case "FencedCode": return [new Code({
+			value: String(nodeAny.code ?? "").replace(/\n$/, ""),
+			lang: nodeAny.language || "typescript"
+		})];
+		case "PlainText":
+		case "SoftBreak":
+		case "CodeSpan":
+		case "LinkTag": return inlineNodes(node);
+		default: {
+			const out = [];
+			if (typeof nodeAny.getChildNodes === "function") for (const child of nodeAny.getChildNodes()) out.push(...toMarkdown(child));
+			return out;
+		}
+	}
+}
+/** Map a TSDoc inline node (or container of inline nodes) to phrasing content. */
+function inlineNodes(node) {
+	const nodeAny = node;
+	if (node.kind === "PlainText") {
+		const text = nodeAny.text || "";
+		return text ? [new Text({ value: text })] : [];
+	}
+	if (node.kind === "SoftBreak") return [new Text({ value: " " })];
+	if (node.kind === "CodeSpan") {
+		const code = nodeAny.code || "";
+		return code ? [new InlineCode({ value: code })] : [];
+	}
+	if (node.kind === "LinkTag") {
+		const linkText = nodeAny.linkText ?? "";
+		if (nodeAny.urlDestination) {
+			const url = nodeAny.urlDestination;
+			return [new Link({
+				url,
+				children: [new Text({ value: linkText || url })]
+			})];
+		}
+		const ref = nodeAny.codeDestination?.memberReferences?.[0]?.memberIdentifier;
+		const display = linkText || ref?.identifier || "";
+		return display ? [new Text({ value: display })] : [];
+	}
+	const out = [];
+	if (typeof nodeAny.getChildNodes === "function") for (const child of nodeAny.getChildNodes()) out.push(...inlineNodes(child));
+	return out;
+}
+/**
+* The TSDoc summary section as a single cleaned line.
+*
+* @public
+*/
+function summary(item) {
+	if (item instanceof ApiDocumentedItem) {
+		const tsdoc = item.tsdocComment;
+		if (tsdoc?.summarySection) return plainText(tsdoc.summarySection).replace(/\s+/g, " ").trim();
+	}
+	return "";
+}
+/**
+* `@param` blocks merged with parameter types from the declaration excerpt.
+*
+* @public
+*/
+function params(item) {
+	const out = [];
+	const paramTypes = /* @__PURE__ */ new Map();
+	const parameters = item.parameters;
+	if (Array.isArray(parameters)) for (const param of parameters) {
+		const excerpt = param.parameterTypeExcerpt;
+		const name = param.name || "";
+		if (excerpt?.text) paramTypes.set(name, String(excerpt.text).trim());
+	}
+	if (item instanceof ApiDocumentedItem) {
+		const tsdoc = item.tsdocComment;
+		if (tsdoc?.params) {
+			for (const block of tsdoc.params.blocks) {
+				const blockAny = block;
+				const name = blockAny.parameterName || "";
+				const description = plainText(blockAny.content).replace(/\s+/g, " ").trim();
+				const type = paramTypes.get(name);
+				out.push({
+					name,
+					...type != null ? { type } : {},
+					description
+				});
+			}
+			return out;
+		}
+	}
+	for (const [name, type] of paramTypes.entries()) out.push({
+		name,
+		type,
+		description: ""
+	});
+	return out;
+}
+/**
+* The `@returns` block description, if present.
+*
+* @public
+*/
+function returns(item) {
+	if (item instanceof ApiDocumentedItem) {
+		const tsdoc = item.tsdocComment;
+		if (tsdoc?.returnsBlock) {
+			const description = plainText(tsdoc.returnsBlock.content).replace(/\s+/g, " ").trim();
+			return description.length > 0 ? { description } : null;
+		}
+	}
+	return null;
+}
+/**
+* All `@example` fenced-code blocks (falls back to plain text).
+*
+* @public
+*/
+function examples(item) {
+	const out = [];
+	if (!(item instanceof ApiDocumentedItem)) return out;
+	const tsdoc = item.tsdocComment;
+	for (const block of tsdoc?.customBlocks || []) {
+		if (block.blockTag?.tagNameWithUpperCase !== "@EXAMPLE") continue;
+		const content = block.content;
+		let found = false;
+		for (const node of content?.nodes || []) if (node.kind === "FencedCode") {
+			out.push({
+				language: node.language || "typescript",
+				code: node.code || ""
+			});
+			found = true;
+		}
+		if (!found) {
+			const text = plainText(content).trim();
+			if (text) out.push({
+				language: "typescript",
+				code: text
+			});
+		}
+	}
+	return out;
+}
+/**
+* The deprecation-block message, if one is present.
+*
+* @public
+*/
+function deprecation(item) {
+	if (item instanceof ApiDocumentedItem) {
+		const tsdoc = item.tsdocComment;
+		if (tsdoc?.deprecatedBlock) return { message: plainText(tsdoc.deprecatedBlock.content).replace(/\s+/g, " ").trim() };
+	}
+	return null;
+}
+/**
+* The release tag (Public/Beta/Alpha/Internal), `"Public"` when absent.
+*
+* @public
+*/
+function releaseTag(item) {
+	if (ApiReleaseTagMixin.isBaseClassOf(item)) switch (item.releaseTag) {
+		case ReleaseTag.Beta: return "Beta";
+		case ReleaseTag.Alpha: return "Alpha";
+		case ReleaseTag.Internal: return "Internal";
+		default: return "Public";
+	}
+	return "Public";
+}
+/**
+* True when the item carries the given TSDoc modifier tag (without the `@`).
+*
+* @public
+*/
+function hasModifier(item, tagName) {
+	if (item instanceof ApiDocumentedItem) return ((item.tsdocComment?.modifierTagSet)?.nodes || []).some((t) => t.tagName === `@${tagName}`);
+	return false;
+}
+/**
+* `@see` block contents, flattened to prose (whitespace-normalized).
+*
+* @public
+*/
+function seeReferences(item) {
+	if (item instanceof ApiDocumentedItem) {
+		const tsdoc = item.tsdocComment;
+		const references = [];
+		for (const seeBlock of tsdoc?.seeBlocks || []) {
+			const text = plainText(seeBlock.content);
+			if (text.trim()) references.push({ text: text.replace(/\s+/g, " ").trim() });
+		}
+		return references;
+	}
+	return [];
+}
+
+//#endregion
+export { Tsdoc_exports, deprecation, examples, hasModifier, params, plainText, releaseTag, returns, seeReferences, summary, toMarkdown };

package/_virtual/_rolldown/runtime.js

@@ -0,0 +1,18 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll };