@tsdoctor/model 0.1.0 → 0.2.1

package/internal/text.js

@@ -0,0 +1,11 @@
+//#region src/internal/text.ts
+/**
+* Shared private text helpers.
+*
+* @internal
+*/
+/** Escape a literal string for embedding in a RegExp pattern. */
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+//#endregion
+export { escapeRegExp };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tsdoctor/model",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"private": false,
 	"description": "Render Microsoft API Extractor models into LLM-lean markdown. Pure model loading, TSDoc extraction, type-signature formatting, and per-item markdown rendering.",
 	"keywords": [
@@ -41,6 +41,16 @@
 		"@microsoft/api-extractor-model": "^7.33.10",
 		"@microsoft/tsdoc": "^0.16.0"
 	},
+	"peerDependencies": {
+		"@effected/markdown": "^0.7.0",
+		"@effected/package-json": "^0.12.0",
+		"effect": "4.0.0-rc.109"
+	},
+	"peerDependenciesMeta": {
+		"@effected/package-json": {
+			"optional": true
+		}
+	},
 	"engines": {
 		"node": ">=24.11.0"
 	}

package/cross-linker.js

@@ -1,37 +0,0 @@
-//#region src/cross-linker.ts
-const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-/**
-* Links known API item names in prose to their docs, using an injected
-* {@link RouteFormatter} so each consumer supplies its own URL scheme.
-*
-* @public
-*/
-var CrossLinker = class {
-	byName;
-	routeFor;
-	constructor(refs, routeFor) {
-		this.byName = new Map(refs.map((r) => [r.name, r]));
-		this.routeFor = routeFor;
-	}
-	/** Wrap known item names in markdown links, skipping code spans + existing links. */
-	addLinks(text) {
-		let result = text;
-		const names = [...this.byName.keys()].sort((a, b) => b.length - a.length);
-		for (const name of names) {
-			const ref = this.byName.get(name);
-			if (!ref) continue;
-			const route = this.routeFor(ref);
-			const regex = new RegExp(`\\b${escapeRegExp(name)}\\b`, "g");
-			result = result.replace(regex, (match, offset) => {
-				const before = result.slice(0, offset);
-				if (before.endsWith("](") || before.endsWith("[")) return match;
-				if ((before.match(/`/g) || []).length % 2 === 1) return match;
-				return `[${match}](${route})`;
-			});
-		}
-		return result;
-	}
-};
-
-//#endregion
-export { CrossLinker };

package/formatter.js

@@ -1,70 +0,0 @@
-//#region src/formatter.ts
-/**
-* Formats an API Extractor `Excerpt` into a clean, line-wrapped type signature string.
-*
-* @public
-*/
-var TypeSignatureFormatter = class {
-	maxLineLength;
-	indent;
-	constructor(opts = {}) {
-		this.maxLineLength = opts.maxLineLength ?? 80;
-		this.indent = opts.indent ?? "  ";
-	}
-	format(excerpt) {
-		if (!excerpt.spannedTokens || excerpt.spannedTokens.length === 0) return this.stripExportDeclare(excerpt.text);
-		const tokens = excerpt.spannedTokens;
-		let currentLine = "";
-		const lines = [];
-		let bracketDepth = 0;
-		let lastTokenText = "";
-		for (let i = 0; i < tokens.length; i++) {
-			let tokenText = tokens[i].text;
-			if (i === 0) tokenText = this.stripExportDeclare(tokenText);
-			if (tokenText.trim() === "") continue;
-			if (tokenText === "{" || tokenText === "[" || tokenText === "(") bracketDepth++;
-			else if (tokenText === "}" || tokenText === "]" || tokenText === ")") bracketDepth--;
-			const isOperator = tokenText.trim() === "|" || tokenText.trim() === "&";
-			if (lastTokenText && this.needsSpaceBefore(lastTokenText, tokenText)) currentLine += " ";
-			currentLine += tokenText;
-			lastTokenText = tokenText;
-			if (isOperator && bracketDepth === 0 && currentLine.length > this.maxLineLength && i < tokens.length - 1) {
-				lines.push(currentLine.trimEnd());
-				currentLine = this.indent;
-			}
-		}
-		if (currentLine.trim()) lines.push(currentLine.trimEnd());
-		if (lines.length <= 1) return lines.length === 1 ? lines[0].trimStart() : "";
-		return this.stripExportDeclare(lines.join("\n"));
-	}
-	stripExportDeclare(text) {
-		let result = text.trim().replace(/^export\s+declare\s+/i, "").replace(/^export\s+/i, "").replace(/^declare\s+/i, "");
-		result = result.replace(/\bexport\s+declare\s+/gi, "").replace(/\bexport\s+/gi, "").replace(/\bdeclare\s+/gi, "");
-		return result;
-	}
-	needsSpaceBefore(prevText, currentText) {
-		if (/\s$/.test(prevText)) return false;
-		if (/^\s/.test(currentText)) return false;
-		if (currentText.trim().startsWith("<")) return false;
-		if (currentText.trim().match(/^[,;]/)) return false;
-		if (prevText.trim().endsWith(",")) return true;
-		if (currentText.trim() === "=" || currentText.trim().startsWith("=")) return true;
-		if (prevText.trim().endsWith("=")) return true;
-		if (currentText.trim() === "|" || currentText.trim() === "&") return true;
-		if (prevText.trim() === "|" || prevText.trim() === "&") return true;
-		if (prevText.trim() === "{" && currentText.trim() !== "}") return true;
-		if (currentText.trim() === "}" && prevText.trim() !== "{") return true;
-		if (prevText.trim().match(/^[[(]$/)) return false;
-		if (currentText.trim().match(/^[\])]$/)) return false;
-		if (prevText.trim().endsWith(":")) return true;
-		if (prevText.trim().endsWith("?:")) return true;
-		if (currentText.trim().startsWith(":") && !prevText.trim().match(/[,;:?]$/)) return false;
-		if (currentText.trim().startsWith("{") && /[a-zA-Z0-9_>]$/.test(prevText.trim())) return true;
-		const prevEndsAlnum = /[a-zA-Z0-9_>]$/.test(prevText.trim());
-		const currStartsAlnum = /^[a-zA-Z0-9_<]/.test(currentText.trim());
-		return prevEndsAlnum && currStartsAlnum;
-	}
-};
-
-//#endregion
-export { TypeSignatureFormatter };

package/model-loader.js

@@ -1,24 +0,0 @@
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { ApiModel } from "@microsoft/api-extractor-model";
-
-//#region src/model-loader.ts
-/**
-* Load a Microsoft API Extractor `.api.json` model from disk and return its
-* single `ApiPackage`. Ported from rspress-plugin-api-extractor's ApiModelLoader.
-*
-* @packageDocumentation
-*/
-/**
-* Load a `.api.json` model file and return its first (only) package.
-*
-* @public
-*/
-async function loadApiModel(modelPath) {
-	const resolved = resolve(modelPath);
-	if (!existsSync(resolved)) throw new Error(`API model file not found: ${resolved}`);
-	return new ApiModel().loadPackage(resolved);
-}
-
-//#endregion
-export { loadApiModel };

package/render.js

@@ -1,118 +0,0 @@
-import { CrossLinker } from "./cross-linker.js";
-import { TypeSignatureFormatter } from "./formatter.js";
-import { getDeprecation, getExamples, getParams, getReturns, getSummary } from "./tsdoc.js";
-import { ApiItemContainerMixin } from "@microsoft/api-extractor-model";
-
-//#region src/render.ts
-const KIND_SLUG = {
-	Class: "class",
-	Interface: "interface",
-	Function: "function",
-	TypeAlias: "type",
-	Variable: "variable",
-	Enum: "enum",
-	Namespace: "namespace"
-};
-/**
-* The default emit rule for {@link renderPackage}: drop compiler-synthetic
-* forgotten exports — items the model retains only because API Extractor ran with
-* `includeForgottenExports: true` (e.g. the `*_base` classes TypeScript hoists for
-* Effect class mixins). Those carry `isExported === false` on `ApiExportedMixin`.
-* Every other item, including any lacking the flag, is kept.
-*
-* @public
-*/
-const isEmittable = (item) => item.isExported !== false;
-const formatter = new TypeSignatureFormatter();
-const signatureOf = (item) => {
-	const declared = item;
-	return declared.excerpt?.text ? formatter.format(declared.excerpt).trim() : "";
-};
-/**
-* Render one API item to a markdown body (no frontmatter).
-*
-* @public
-*/
-function renderItem(item, opts) {
-	const link = (text) => opts.crossLinker ? opts.crossLinker.addLinks(text) : text;
-	const lines = [`# ${item.displayName}`, ""];
-	const deprecation = getDeprecation(item);
-	if (deprecation) lines.push(`> **Deprecated:** ${link(deprecation.message)}`, "");
-	const summary = getSummary(item);
-	if (summary) lines.push(link(summary), "");
-	const signature = signatureOf(item);
-	if (signature) lines.push("```ts", signature, "```", "");
-	const params = getParams(item);
-	if (params.length > 0) {
-		lines.push("## Parameters", "");
-		for (const p of params) {
-			const type = p.type ? ` \`${p.type}\`` : "";
-			const desc = p.description ? ` — ${link(p.description)}` : "";
-			lines.push(`- \`${p.name}\`${type}${desc}`);
-		}
-		lines.push("");
-	}
-	const returns = getReturns(item);
-	if (returns) lines.push("## Returns", "", link(returns.description), "");
-	const members = item.members;
-	if (Array.isArray(members) && members.length > 0 && ApiItemContainerMixin.isBaseClassOf(item)) {
-		lines.push("## Members", "");
-		for (const m of members) {
-			const sig = signatureOf(m);
-			const mSummary = getSummary(m);
-			lines.push(`### ${m.displayName}`, "");
-			if (sig) lines.push("```ts", sig, "```", "");
-			if (mSummary) lines.push(link(mSummary), "");
-		}
-	}
-	const examples = getExamples(item);
-	if (examples.length > 0) {
-		lines.push("## Examples", "");
-		for (const ex of examples) lines.push(`\`\`\`${ex.language}`, ex.code, "```", "");
-	}
-	return `${lines.join("\n").trim()}\n`;
-}
-/**
-* Walk a package's first entry point and assemble one RenderedDoc per top-level member.
-*
-* @public
-*/
-function renderPackage(apiPackage, opts) {
-	const entryPoint = apiPackage.entryPoints[0];
-	if (!entryPoint) return [];
-	const keep = opts.filter ?? isEmittable;
-	const pairs = [];
-	for (const member of entryPoint.members) {
-		const kind = KIND_SLUG[member.kind];
-		if (kind === void 0) continue;
-		if (!keep(member)) continue;
-		pairs.push({
-			item: member,
-			ref: {
-				name: member.displayName,
-				kind,
-				slug: member.displayName.toLowerCase()
-			}
-		});
-	}
-	const crossLinker = opts.routeFor ? new CrossLinker(pairs.map((p) => p.ref), opts.routeFor) : void 0;
-	return pairs.map(({ item, ref }) => {
-		const body = renderItem(item, {
-			packageName: opts.packageName,
-			...crossLinker ? { crossLinker } : {}
-		});
-		const meta = {
-			...ref,
-			summary: getSummary(item),
-			packageName: opts.packageName
-		};
-		const frontmatter = opts.frontmatter ? opts.frontmatter(meta) : "";
-		return {
-			...meta,
-			markdown: frontmatter + body
-		};
-	});
-}
-
-//#endregion
-export { isEmittable, renderItem, renderPackage };

package/tsdoc.js

@@ -1,158 +0,0 @@
-import { ApiDocumentedItem, ApiReleaseTagMixin, ReleaseTag } from "@microsoft/api-extractor-model";
-
-//#region src/tsdoc.ts
-/**
-* Recursively flatten a TSDoc DocNode tree to plain text (code spans → backticks).
-*
-* @public
-*/
-function extractPlainText(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 extractPlainText(nodeAny.linkText);
-		return (nodeAny.codeDestination?.memberReferences?.[0]?.memberIdentifier)?.identifier || "";
-	}
-	const parts = [];
-	if (typeof nodeAny.getChildNodes === "function") for (const child of nodeAny.getChildNodes()) {
-		const childText = extractPlainText(child);
-		if (childText) parts.push(childText);
-	}
-	return parts.join("");
-}
-/**
-* The TSDoc `@summary` section as a single cleaned line.
-*
-* @public
-*/
-function getSummary(item) {
-	if (item instanceof ApiDocumentedItem) {
-		const tsdoc = item.tsdocComment;
-		if (tsdoc?.summarySection) return extractPlainText(tsdoc.summarySection).replace(/\s+/g, " ").trim();
-	}
-	return "";
-}
-/**
-* `@param` blocks merged with parameter types from the declaration excerpt.
-*
-* @public
-*/
-function getParams(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 = extractPlainText(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 getReturns(item) {
-	if (item instanceof ApiDocumentedItem) {
-		const tsdoc = item.tsdocComment;
-		if (tsdoc?.returnsBlock) {
-			const description = extractPlainText(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 getExamples(item) {
-	const examples = [];
-	if (!(item instanceof ApiDocumentedItem)) return examples;
-	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") {
-			examples.push({
-				language: node.language || "typescript",
-				code: node.code || ""
-			});
-			found = true;
-		}
-		if (!found) {
-			const text = extractPlainText(content).trim();
-			if (text) examples.push({
-				language: "typescript",
-				code: text
-			});
-		}
-	}
-	return examples;
-}
-/**
-* Reads the deprecation-block message from an ApiItem, if one is present.
-*
-* @public
-*/
-function getDeprecation(item) {
-	if (item instanceof ApiDocumentedItem) {
-		const tsdoc = item.tsdocComment;
-		if (tsdoc?.deprecatedBlock) return { message: extractPlainText(tsdoc.deprecatedBlock.content).replace(/\s+/g, " ").trim() };
-	}
-	return null;
-}
-/**
-* The release tag (Public/Beta/Alpha/Internal) or "Public" when absent.
-*
-* @public
-*/
-function getReleaseTag(item) {
-	if (ApiReleaseTagMixin.isBaseClassOf(item)) switch (item.releaseTag) {
-		case ReleaseTag.Public: return "Public";
-		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 hasModifierTag(item, tagName) {
-	if (item instanceof ApiDocumentedItem) return ((item.tsdocComment?.modifierTagSet)?.nodes || []).some((t) => t.tagName === `@${tagName}`);
-	return false;
-}
-
-//#endregion
-export { extractPlainText, getDeprecation, getExamples, getParams, getReleaseTag, getReturns, getSummary, hasModifierTag };