@tsdoctor/model 0.1.0 → 0.2.0

package/Render.js

@@ -0,0 +1,182 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { deprecation, examples, params, returns, summary } from "./Tsdoc.js";
+import { CrossLinker } from "./CrossLinker.js";
+import { phrasingFromMarkdown } from "./internal/prose.js";
+import { format } from "./Signature.js";
+import { ApiItemContainerMixin } from "@microsoft/api-extractor-model";
+import { Blockquote, Code, Heading, InlineCode, List, ListItem, Markdown, Paragraph, Root, Strong, Text } from "@effected/markdown";
+import { Result } from "effect";
+
+//#region src/Render.ts
+var Render_exports = /* @__PURE__ */ __exportAll({
+	docs: () => docs,
+	isEmittable: () => isEmittable,
+	item: () => item,
+	tree: () => tree
+});
+const KIND_SLUG = {
+	Class: "class",
+	Interface: "interface",
+	Function: "function",
+	TypeAlias: "type",
+	Variable: "variable",
+	Enum: "enum",
+	Namespace: "namespace"
+};
+/**
+* The default emit rule for {@link docs}: 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 signatureOf = (item) => {
+	const declared = item;
+	return declared.excerpt?.text ? format(declared.excerpt).trim() : "";
+};
+/**
+* Render one API item's markdown body as flow nodes — the pre-serialization
+* form of {@link item}.
+*
+* @alpha
+*/
+function tree(apiItem, opts) {
+	const link = (text) => opts.crossLinker ? opts.crossLinker.link(text) : text;
+	const prose = (text) => phrasingFromMarkdown(link(text));
+	const nodes = [new Heading({
+		depth: 1,
+		children: [new Text({ value: apiItem.displayName })]
+	})];
+	const deprecation$1 = deprecation(apiItem);
+	if (deprecation$1) nodes.push(new Blockquote({ children: [new Paragraph({ children: [
+		new Strong({ children: [new Text({ value: "Deprecated:" })] }),
+		new Text({ value: " " }),
+		...prose(deprecation$1.message)
+	] })] }));
+	const summary$1 = summary(apiItem);
+	if (summary$1) nodes.push(new Paragraph({ children: [...prose(summary$1)] }));
+	const signature = signatureOf(apiItem);
+	if (signature) nodes.push(new Code({
+		value: signature,
+		lang: "ts"
+	}));
+	const params$1 = params(apiItem);
+	if (params$1.length > 0) {
+		nodes.push(new Heading({
+			depth: 2,
+			children: [new Text({ value: "Parameters" })]
+		}));
+		nodes.push(new List({
+			ordered: false,
+			spread: false,
+			children: params$1.map((p) => {
+				const children = [new InlineCode({ value: p.name })];
+				if (p.type) children.push(new Text({ value: " " }), new InlineCode({ value: p.type }));
+				if (p.description) children.push(new Text({ value: " — " }), ...prose(p.description));
+				return new ListItem({
+					spread: false,
+					children: [new Paragraph({ children })]
+				});
+			})
+		}));
+	}
+	const returns$1 = returns(apiItem);
+	if (returns$1) {
+		nodes.push(new Heading({
+			depth: 2,
+			children: [new Text({ value: "Returns" })]
+		}));
+		nodes.push(new Paragraph({ children: [...prose(returns$1.description)] }));
+	}
+	const members = apiItem.members;
+	if (Array.isArray(members) && members.length > 0 && ApiItemContainerMixin.isBaseClassOf(apiItem)) {
+		nodes.push(new Heading({
+			depth: 2,
+			children: [new Text({ value: "Members" })]
+		}));
+		for (const m of members) {
+			nodes.push(new Heading({
+				depth: 3,
+				children: [new Text({ value: m.displayName })]
+			}));
+			const sig = signatureOf(m);
+			if (sig) nodes.push(new Code({
+				value: sig,
+				lang: "ts"
+			}));
+			const mSummary = summary(m);
+			if (mSummary) nodes.push(new Paragraph({ children: [...prose(mSummary)] }));
+		}
+	}
+	const examples$1 = examples(apiItem);
+	if (examples$1.length > 0) {
+		nodes.push(new Heading({
+			depth: 2,
+			children: [new Text({ value: "Examples" })]
+		}));
+		for (const ex of examples$1) nodes.push(new Code({
+			value: ex.code.replace(/\n$/, ""),
+			lang: ex.language
+		}));
+	}
+	return nodes;
+}
+/**
+* Render one API item to a markdown body string (no frontmatter).
+*
+* @public
+*/
+function item(apiItem, opts) {
+	const root = new Root({ children: [...tree(apiItem, opts)] });
+	const trimmed = Result.getOrThrow(Markdown.stringifyResult(root)).trim();
+	return trimmed ? `${trimmed}\n` : "\n";
+}
+/**
+* Walk a package's first entry point and assemble one RenderedDoc per
+* top-level member.
+*
+* @public
+*/
+function docs(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 ? CrossLinker.fromRefs(pairs.map((p) => p.ref), opts.routeFor) : void 0;
+	return pairs.map(({ item: member, ref }) => {
+		const body = item(member, {
+			packageName: opts.packageName,
+			...crossLinker ? { crossLinker } : {}
+		});
+		const meta = {
+			...ref,
+			summary: summary(member),
+			packageName: opts.packageName
+		};
+		const frontmatter = opts.frontmatter ? opts.frontmatter(meta) : "";
+		return {
+			...meta,
+			markdown: frontmatter + body
+		};
+	});
+}
+
+//#endregion
+export { Render_exports, docs, isEmittable, item, tree };

package/Routes.js

@@ -0,0 +1,110 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { Schema } from "effect";
+
+//#region src/Routes.ts
+/**
+* Output-route computation: collision detection over route candidates and the
+* canonical anchor-id sanitizer. Detection is pure; the typed
+* {@link RouteCollisionError} is the artifact a consumer fails its build with.
+*
+* @packageDocumentation
+*/
+var Routes_exports = /* @__PURE__ */ __exportAll({
+	RouteCandidate: () => RouteCandidate,
+	RouteCollisionError: () => RouteCollisionError,
+	detectCollisions: () => detectCollisions,
+	sanitizeId: () => sanitizeId
+});
+/**
+* A candidate output route for collision detection. All-string and
+* serializable — candidates cross the error boundary inside
+* {@link RouteCollisionError} and may be persisted by consumer diagnostics.
+*
+* @public
+*/
+var RouteCandidate = class extends Schema.Class("RouteCandidate")({
+	/** Stable identity (e.g. `"displayName::kind"` or a namespace qualified name). */
+	id: Schema.String,
+	/** Human-readable name for error messages (original, non-lowercased). */
+	displayName: Schema.String,
+	/** Category folder name, e.g. `"variable"`. */
+	folder: Schema.String,
+	/** Lowercased sanitized last path segment, e.g. `"foo"` — the value used in the route. */
+	baseName: Schema.String,
+	/** API item kind string, e.g. `"Variable"`. */
+	kind: Schema.String,
+	/** canonicalReference string, used for deterministic ordering. */
+	canonicalRef: Schema.String
+}) {};
+/**
+* Group candidates by their final route (`${folder}/${baseName}`) and return
+* the groups with more than one distinct item. The route key is the lowercased
+* path the file is written to, so detection matches generation (and what a
+* case-insensitive filesystem would merge). Companion pairs (same name,
+* different folders) land under different keys and are never collisions.
+*
+* Output is deterministic: collisions ordered by route, items within a
+* collision ordered by canonicalReference.
+*
+* @public
+*/
+function detectCollisions(candidates) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) {
+		const key = `${candidate.folder}/${candidate.baseName}`;
+		const group = byKey.get(key) ?? [];
+		group.push(candidate);
+		byKey.set(key, group);
+	}
+	const collisions = [];
+	for (const [route, group] of byKey) if (group.length > 1) {
+		const items = [...group].sort((a, b) => a.canonicalRef < b.canonicalRef ? -1 : a.canonicalRef > b.canonicalRef ? 1 : 0);
+		collisions.push({
+			route,
+			items
+		});
+	}
+	collisions.sort((a, b) => a.route < b.route ? -1 : a.route > b.route ? 1 : 0);
+	return collisions;
+}
+/**
+* Two or more distinct API items resolve to the same documentation route — a
+* naming or category-configuration problem the build must fail on. The
+* `message` names every colliding item with its kind and canonical reference,
+* plus remediation guidance.
+*
+* @public
+*/
+var RouteCollisionError = class extends Schema.TaggedError()("RouteCollisionError", {
+	baseRoute: Schema.String,
+	collisions: Schema.Array(Schema.Struct({
+		route: Schema.String,
+		items: Schema.Array(RouteCandidate)
+	}))
+}) {
+	get message() {
+		const lines = [];
+		for (const collision of this.collisions) {
+			lines.push(`Route collision: ${collision.items.length} API items resolve to the same documentation path "${this.baseRoute}/${collision.route}":`);
+			for (const item of collision.items) lines.push(`  - ${item.displayName} (${item.kind})  [${item.canonicalRef}]`);
+		}
+		lines.push("");
+		lines.push("Item names must be unique per category folder. Paths are lowercased, so names differing only in case collide. Rename one of the items, or configure categories so they map to different folders.");
+		return lines.join("\n");
+	}
+};
+/**
+* Sanitize a display name into a valid HTML anchor id: lowercase,
+* spaces/underscores → hyphens, other specials stripped, optional prefix for
+* disambiguation. The ONE canonical implementation — anchor generation and
+* cross-link routes must agree on it by construction.
+*
+* @public
+*/
+function sanitizeId(displayName, prefix = "") {
+	const sanitized = displayName.toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/^-+|-+$/g, "");
+	return prefix ? `${prefix}-${sanitized}` : sanitized;
+}
+
+//#endregion
+export { RouteCandidate, RouteCollisionError, Routes_exports, detectCollisions, sanitizeId };

package/Signature.js

@@ -0,0 +1,100 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { escapeRegExp } from "./internal/text.js";
+
+//#region src/Signature.ts
+var Signature_exports = /* @__PURE__ */ __exportAll({
+	format: () => format,
+	linkReferences: () => linkReferences,
+	stripExportDeclare: () => stripExportDeclare
+});
+/**
+* Strip `export` / `declare` modifiers from a declaration text.
+*
+* @public
+*/
+function 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;
+}
+function 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;
+}
+/**
+* Format an API Extractor `Excerpt` into a clean type signature string,
+* wrapping long top-level unions/intersections.
+*
+* @public
+*/
+function format(excerpt, options) {
+	const maxLineLength = options?.maxLineLength ?? 80;
+	const indent = options?.indent ?? "  ";
+	if (!excerpt.spannedTokens || excerpt.spannedTokens.length === 0) return 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 = 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 && needsSpaceBefore(lastTokenText, tokenText)) currentLine += " ";
+		currentLine += tokenText;
+		lastTokenText = tokenText;
+		if (isOperator && bracketDepth === 0 && currentLine.length > maxLineLength && i < tokens.length - 1) {
+			lines.push(currentLine.trimEnd());
+			currentLine = indent;
+		}
+	}
+	if (currentLine.trim()) lines.push(currentLine.trimEnd());
+	if (lines.length <= 1) return lines.length === 1 ? lines[0].trimStart() : "";
+	return stripExportDeclare(lines.join("\n"));
+}
+/**
+* Inject markdown cross-links into already-formatted signature text. Reference
+* tokens in the excerpt whose canonical reference appears in
+* `routesByCanonicalRef` have their display text wrapped in a markdown link.
+*
+* @public
+*/
+function linkReferences(text, excerpt, routesByCanonicalRef) {
+	if (!excerpt.spannedTokens || routesByCanonicalRef.size === 0) return text;
+	const typeReferences = /* @__PURE__ */ new Map();
+	for (const token of excerpt.spannedTokens) if (token.kind === "Reference" && token.canonicalReference) {
+		const canonicalRef = token.canonicalReference.toString();
+		const route = routesByCanonicalRef.get(canonicalRef);
+		if (route && token.text) typeReferences.set(token.text.trim(), route);
+	}
+	let result = text;
+	for (const [typeName, route] of typeReferences.entries()) {
+		const regex = new RegExp(`\\b${escapeRegExp(typeName)}\\b`, "g");
+		result = result.replace(regex, `[${typeName}](${route})`);
+	}
+	return result;
+}
+
+//#endregion
+export { Signature_exports, format, linkReferences, stripExportDeclare };

package/StructuredData.js

@@ -0,0 +1,18 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+
+//#region src/StructuredData.ts
+var StructuredData_exports = /* @__PURE__ */ __exportAll({ derive: () => derive });
+/**
+* Derive schema.org structured data for a documented package.
+*
+* @remarks
+* Not implemented yet — this is the phase-4 seam. Calling it throws.
+*
+* @alpha
+*/
+function derive(_apiPackage, _manifest) {
+	throw new Error("@tsdoctor/model: StructuredData.derive is a phase-4 seam and is not implemented yet");
+}
+
+//#endregion
+export { StructuredData_exports, derive };

package/SyntheticBases.js

@@ -0,0 +1,83 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { ApiExportedMixin, ApiItemKind, ExcerptTokenKind } from "@microsoft/api-extractor-model";
+
+//#region src/SyntheticBases.ts
+var SyntheticBases_exports = /* @__PURE__ */ __exportAll({
+	BASE_CLASS_ANCHOR: () => BASE_CLASS_ANCHOR,
+	detect: () => detect
+});
+/**
+* Anchor id of the inline "Base Class" section rendered on the owner class
+* page. Must match the slug RSPress derives from the `## Base Class` heading
+* emitted by the owner-class page.
+*
+* @public
+*/
+const BASE_CLASS_ANCHOR = "base-class";
+const EMPTY_DETECTION = {
+	bases: /* @__PURE__ */ new Map(),
+	baseByOwner: /* @__PURE__ */ new Map()
+};
+/**
+* Strip the trailing meaning (`:class`, `:var`, `:function(1)`, ...) from a
+* canonical reference string so the reference token in an extends clause
+* (`example!~Person_base`) matches the declaration's canonical reference
+* (`example!~Person_base:var`).
+*/
+function stripMeaning(canonicalRef) {
+	return canonicalRef.replace(/:[a-z]+(\(\d+\))?$/i, "");
+}
+/** True when the item carries ApiExportedMixin and is NOT exported from its entry point. */
+function isUnexported(item) {
+	return ApiExportedMixin.isBaseClassOf(item) && !item.isExported;
+}
+/**
+* Detect synthetic base declarations among top-level API items.
+*
+* An item qualifies when it is unexported (hoisted into the model only because
+* something references it) AND at least one class's extends clause references
+* its canonical symbol. Unexported items with no class referencing them
+* (genuine forgotten exports) are left alone, as are extends references whose
+* target is absent from the model.
+*
+* @public
+*/
+function detect(items) {
+	const unexportedByRef = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		if (!isUnexported(item)) continue;
+		const ref = item.canonicalReference?.toString();
+		if (ref) unexportedByRef.set(stripMeaning(ref), item);
+	}
+	if (unexportedByRef.size === 0) return EMPTY_DETECTION;
+	const owners = /* @__PURE__ */ new Map();
+	const baseByOwner = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		if (item.kind !== ApiItemKind.Class) continue;
+		const apiClass = item;
+		const extendsType = apiClass.extendsType;
+		if (!extendsType) continue;
+		for (const token of extendsType.excerpt.spannedTokens) {
+			if (token.kind !== ExcerptTokenKind.Reference || !token.canonicalReference) continue;
+			const base = unexportedByRef.get(stripMeaning(token.canonicalReference.toString()));
+			if (!base || base === item || baseByOwner.has(item)) continue;
+			baseByOwner.set(item, base);
+			const ownerList = owners.get(base);
+			if (ownerList) ownerList.push(apiClass);
+			else owners.set(base, [apiClass]);
+		}
+	}
+	if (owners.size === 0) return EMPTY_DETECTION;
+	const bases = /* @__PURE__ */ new Map();
+	for (const [baseItem, ownerClasses] of owners) bases.set(baseItem, {
+		baseItem,
+		ownerClasses
+	});
+	return {
+		bases,
+		baseByOwner
+	};
+}
+
+//#endregion
+export { BASE_CLASS_ANCHOR, SyntheticBases_exports, detect };