@tsdoctor/pages 0.1.0

package/Nav.js

@@ -0,0 +1,148 @@
+import { Schema } from "effect";
+
+//#region src/Nav.ts
+/**
+* The per-API navigation tree — category groups of pages plus the index —
+* as data, so a sidebar that is files in one framework and config in another
+* is a pure rendering of the same value.
+*
+* @remarks
+* The ordering is the one the RSPress adapter's `writeMetadata` produced when
+* it wrote `_meta.json` files directly: groups in category insertion order,
+* kept only when at least one page landed in them; pages within a group by
+* `label.localeCompare`; the index page always present. `buildNav` is
+* characterized against that behaviour, and the RSPress rendering of this
+* tree is covered by the golden gate.
+*
+* @packageDocumentation
+*/
+/**
+* A page's place in the navigation tree, carried on the page itself.
+*
+* @public
+*/
+var NavEntry = class extends Schema.Class("NavEntry")({
+	/** The category key the page was categorized under. */
+	categoryKey: Schema.String,
+	/** The sidebar label — the display name, qualified for a namespace member. */
+	label: Schema.String,
+	/** The file basename without extension (`foo` for `class/foo.mdx`). */
+	name: Schema.String,
+	/** The page route. */
+	route: Schema.String
+}) {};
+/**
+* The per-category presentation facts a tree carries for its groups.
+*
+* @public
+*/
+var NavCategory = class extends Schema.Class("NavCategory")({
+	/** The group label. */
+	displayName: Schema.String,
+	/** The folder the category's pages live in. */
+	folderName: Schema.String,
+	/** Whether the group can be collapsed; absent means the renderer's default. */
+	collapsible: Schema.optionalKey(Schema.Boolean),
+	/** Whether the group starts collapsed; absent means the renderer's default. */
+	collapsed: Schema.optionalKey(Schema.Boolean),
+	/** Heading depths surfaced in an overview; absent means the renderer's default. */
+	overviewHeaders: Schema.optionalKey(Schema.Array(Schema.Number))
+}) {};
+/**
+* One page in a group.
+*
+* @public
+*/
+var NavPage = class extends Schema.Class("NavPage")({
+	/** The sidebar label. */
+	label: Schema.String,
+	/** The file basename without extension. */
+	name: Schema.String,
+	/** The page route. */
+	route: Schema.String
+}) {};
+/**
+* One category group with its pages, already sorted.
+*
+* @public
+*/
+var NavGroup = class extends Schema.Class("NavGroup")({
+	/** The category key. */
+	key: Schema.String,
+	/** The category presentation facts. */
+	category: NavCategory,
+	/** The group's pages, sorted by label. */
+	pages: Schema.Array(NavPage)
+}) {};
+/**
+* The navigation tree for one API.
+*
+* @public
+*/
+var NavTree = class extends Schema.Class("NavTree")({
+	/** The API's base route; the index page lives at its root. */
+	baseRoute: Schema.String,
+	/** The index page. */
+	index: NavPage,
+	/** The category groups that received at least one page, in category order. */
+	groups: Schema.Array(NavGroup)
+}) {};
+/**
+* The label of the index page every tree carries.
+*
+* @public
+*/
+const NAV_INDEX_LABEL = "API Reference";
+/**
+* Sort pages the way the sidebar lists them: alphabetically by label.
+*
+* @public
+*/
+function sortNavPages(pages) {
+	return [...pages].sort((a, b) => a.label.localeCompare(b.label));
+}
+/**
+* Build the navigation tree for one API from its categories and its pages.
+*
+* @remarks
+* Groups follow `categories`' insertion order and a category with no page
+* is dropped rather than rendered empty. An entry whose category key names
+* no configured category is dropped too — it could not have been generated
+* into a folder — so the tree only ever describes pages that exist.
+*
+* @public
+*/
+function buildNav(input) {
+	const byCategory = /* @__PURE__ */ new Map();
+	for (const entry of input.entries) {
+		const pages = byCategory.get(entry.categoryKey) ?? [];
+		pages.push(NavPage.make({
+			label: entry.label,
+			name: entry.name,
+			route: entry.route
+		}));
+		byCategory.set(entry.categoryKey, pages);
+	}
+	const groups = [];
+	for (const [key, category] of Object.entries(input.categories)) {
+		const pages = byCategory.get(key);
+		if (!pages || pages.length === 0) continue;
+		groups.push(NavGroup.make({
+			key,
+			category,
+			pages: sortNavPages(pages)
+		}));
+	}
+	return NavTree.make({
+		baseRoute: input.baseRoute,
+		index: NavPage.make({
+			label: NAV_INDEX_LABEL,
+			name: "index",
+			route: `${input.baseRoute}/index`
+		}),
+		groups
+	});
+}
+
+//#endregion
+export { NAV_INDEX_LABEL, NavCategory, NavEntry, NavGroup, NavPage, NavTree, buildNav, sortNavPages };

package/Page.js

@@ -0,0 +1,80 @@
+import { Block } from "./Blocks.js";
+import { NavEntry } from "./Nav.js";
+import { Schema } from "effect";
+
+//#region src/Page.ts
+/**
+* The neutral head tag, as a schema — the same shape as `@tsdoctor/seo`'s
+* `HeadTag` interface, so a value from `headTags` is accepted unchanged.
+*
+* @public
+*/
+const HeadTag = Schema.Struct({
+	/** The element name. */
+	tag: Schema.Literals([
+		"meta",
+		"link",
+		"script"
+	]),
+	/** The element attributes. */
+	attrs: Schema.Record(Schema.String, Schema.String),
+	/** Element content; only meaningful for `script`. */
+	body: Schema.optionalKey(Schema.String)
+});
+/**
+* The kind of symbol a page documents — which builder produced it, and
+* which component imports and block layout an emitter chooses.
+*
+* @public
+*/
+const PageKind = Schema.Literals([
+	"class",
+	"interface",
+	"function",
+	"type-alias",
+	"enum",
+	"variable",
+	"namespace"
+]);
+/**
+* One generated API page.
+*
+* @public
+*/
+var Page = class extends Schema.Class("Page")({
+	/** The kind of symbol the page documents. */
+	kind: PageKind,
+	/** The documented item's display name — the first title part. */
+	entityName: Schema.String,
+	/** The category's singular name (`Class`, `Function`) — the second title part. */
+	singularName: Schema.String,
+	/** The API's display name — the last title part, when the site names one. */
+	apiName: Schema.optionalKey(Schema.String),
+	/** The page description: the item's summary, or the fallback the generators used. */
+	description: Schema.String,
+	/** The page route. */
+	route: Schema.String,
+	/** Every `<head>` tag the page carries, from `@tsdoctor/seo`. */
+	headTags: Schema.Array(HeadTag),
+	/** The page body, in order. */
+	blocks: Schema.Array(Block),
+	/** The page's place in the navigation tree. */
+	nav: NavEntry
+}) {
+	/**
+	* The structured page title: `{entityName} | {singularName} | API | {apiName}`,
+	* the last part omitted when the site names no API.
+	*/
+	get title() {
+		const parts = [
+			this.entityName,
+			this.singularName,
+			"API"
+		];
+		if (this.apiName !== void 0) parts.push(this.apiName);
+		return parts.join(" | ");
+	}
+};
+
+//#endregion
+export { HeadTag, Page, PageKind };

package/README.md

@@ -0,0 +1,32 @@
+# @tsdoctor/pages
+
+[![npm](https://img.shields.io/npm/v/@tsdoctor%2Fpages?label=npm&color=cb3837)](https://www.npmjs.com/package/@tsdoctor/pages)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+The framework-neutral documentation page IR for static TypeScript API sites. A page is facts, an ordered list of typed doc blocks and its navigation entry; prose inside a block is `@effected/markdown` mdast, and code-bearing blocks carry a `display` / `source` pair. A framework adapter is an emitter over this IR.
+
+## What you get
+
+- **Blocks** — the block vocabulary (`Title`, `Signature`, `MemberGroup`, `ParameterTable`, `EnumMemberTable`, `ExampleGroup`, …) as Effect `Schema.Class` variants discriminated on `kind`, plus the `Block` union.
+- **`Page`** — the page record: title parts, description, route, `HeadTag[]`, blocks and nav entry.
+- **`buildNav`** — one `NavTree` per API (category groups, pages, index), sorted deterministically.
+- **`buildExample`, `codeText`, `prepareExampleCode`, `stripTwoslashDirectives`, `prependHiddenImports`, `formatExampleCode`** — display/source preparation for code blocks, with Prettier formatting behind a typed `ExampleFormatError`.
+- **`renderMarkdown` / `renderMarkdownResult`** — the neutral plain-markdown emitter over the IR.
+- **`parseLlmsTxtLine`, `filterLlmsTxt`, `generateStructuredLlmsTxt`, …** — pure text transforms over the llms.txt standard.
+- **`apiScopeOf`, `unscopedName`, `normalizeBaseRoute`** — API scope naming helpers shared by every adapter.
+
+## Install
+
+```bash
+npm install @tsdoctor/pages
+# or
+pnpm add @tsdoctor/pages
+```
+
+Requires `effect` and `@effected/markdown` as peers.
+
+## License
+
+MIT

package/Scope.js

@@ -0,0 +1,56 @@
+//#region src/Scope.ts
+/**
+* API scope naming — the helpers that turn a package name and a base route
+* into the identifiers every adapter must agree on.
+*
+* @remarks
+* These sit beside the navigation tree rather than in an adapter because the
+* scope string is load-bearing across frameworks: it keys Twoslash cache
+* generations and names the per-package llms files. Two adapters deriving it
+* differently would silently miss each other's caches. The multiVersion /
+* i18n output-directory layout is NOT here — that is a framework's product
+* policy and stays adapter-side.
+*
+* @packageDocumentation
+*/
+/**
+* Extract the unscoped name from a possibly scoped package name:
+* `@scope/pkg` becomes `pkg`, `pkg` stays `pkg`.
+*
+* @public
+*/
+function unscopedName(packageName) {
+	return packageName.startsWith("@") ? packageName.split("/")[1] ?? packageName : packageName;
+}
+/**
+* Normalize a base route: ensure a leading slash, strip a trailing slash,
+* and keep the root as `/`.
+*
+* @public
+*/
+function normalizeBaseRoute(route) {
+	const withSlash = route.startsWith("/") ? route : `/${route}`;
+	const stripped = withSlash.endsWith("/") ? withSlash.slice(0, -1) : withSlash;
+	return stripped === "" ? "/" : stripped;
+}
+/**
+* The API scope key derived from a base route: its first path segment,
+* falling back to the package name so a single-API site mounted at `/`
+* still gets a non-empty scope.
+*
+* @remarks
+* Load-bearing and previously duplicated. Config resolution registers each
+* API's Twoslash environment under this key and the build program looks it
+* up by the same key; if two derivations disagree, every lookup misses and
+* per-scope type-checking degrades to build-wide with no error and nothing
+* visibly wrong in the output. One definition matters more than the
+* duplication was costing.
+*
+* @public
+*/
+function apiScopeOf(baseRoute, packageName) {
+	return baseRoute.replace(/^\//, "").split("/")[0] || packageName;
+}
+
+//#endregion
+export { apiScopeOf, normalizeBaseRoute, unscopedName };

package/TwoslashDirectives.js

@@ -0,0 +1,63 @@
+//#region src/TwoslashDirectives.ts
+/**
+* Twoslash directive detection — the regexes that decide which lines of a
+* code block are notation rather than code.
+*
+* @remarks
+* These mirror the upstream Twoslash source
+* (`twoslashes/twoslash`, `packages/twoslash/src/regexp.ts`). All patterns
+* allow an optional space after `//`, so both `// @noErrors` and `//@noErrors`
+* are recognized, as Twoslash itself does. They live in the IR package
+* because the display/source split depends on them and both adapters must
+* strip the same lines.
+*
+* @packageDocumentation
+*/
+/**
+* Config directives: boolean flags and key-value pairs.
+*
+* Upstream: `reConfigBoolean` + `reConfigValue` + `reFilenamesMakers` —
+* `// @noErrors`, `//@strict`, `// @errors: 2304`, `// @filename: example.ts`.
+*/
+const RE_CONFIG = /^\/\/\s?@\w+/;
+/**
+* Annotation markers: query, completion, and highlight markers.
+*
+* Upstream: `reAnnonateMarkers` — `/^\s*\/\/\s*\^(\?|\||\^+)( .*)?$/gm`. After
+* `line.trim()` leading whitespace is gone but the spaces between `//` and
+* `^` are preserved, so `//    ^?` still matches.
+*/
+const RE_ANNOTATION = /^\/\/\s*\^[?|^]/;
+/**
+* Cut directives: `// ---cut---`, `//---cut-before---`, `// ---cut-after---`,
+* `// ---cut-start---`, `// ---cut-end---`.
+*/
+const RE_CUT = /^\/\/\s?---cut/;
+/**
+* Test whether a trimmed line is any Twoslash directive — a config flag or
+* value, a filename marker, an annotation marker or a cut directive.
+*
+* @param trimmedLine - The line with leading and trailing whitespace removed
+* @returns `true` if the line is a Twoslash directive
+* @public
+*/
+function isTwoslashDirective(trimmedLine) {
+	return RE_CONFIG.test(trimmedLine) || RE_ANNOTATION.test(trimmedLine) || RE_CUT.test(trimmedLine);
+}
+/**
+* Classify a cut directive line.
+*
+* @param trimmedLine - The line with leading and trailing whitespace removed
+* @returns The cut form, or `null` if the line is not a cut directive
+* @public
+*/
+function classifyCutDirective(trimmedLine) {
+	if (/^\/\/\s?---cut(-before)?---$/.test(trimmedLine)) return "cut-before";
+	if (/^\/\/\s?---cut-after---$/.test(trimmedLine)) return "cut-after";
+	if (/^\/\/\s?---cut-start---$/.test(trimmedLine)) return "cut-start";
+	if (/^\/\/\s?---cut-end---$/.test(trimmedLine)) return "cut-end";
+	return null;
+}
+
+//#endregion
+export { classifyCutDirective, isTwoslashDirective };

package/WorkItems.js

@@ -0,0 +1,162 @@
+import { ApiItems, EntryPoints, Routes, SyntheticBases } from "@tsdoctor/model";
+
+//#region src/WorkItems.ts
+/**
+* Cross-link priority by API item kind (lower = higher priority). When a bare
+* name maps to multiple pages (the const+type companion pattern), the bare
+* cross-link resolves to the higher-priority kind — value declarations win
+* over type-only declarations, so `Foo` links to the importable schema, not
+* the type.
+*/
+const CROSS_LINK_KIND_PRIORITY = {
+	Class: 0,
+	Function: 1,
+	Variable: 2,
+	Enum: 3,
+	Interface: 4,
+	TypeAlias: 5,
+	Namespace: 6
+};
+/**
+* Lower number = higher priority for which page a bare cross-link name
+* resolves to.
+*
+* @public
+*/
+function crossLinkKindPriority(kind) {
+	return CROSS_LINK_KIND_PRIORITY[kind] ?? 100;
+}
+/**
+* Prepare the flat list of work items to build and the cross-link maps.
+*
+* @remarks
+* Resolves entry points into deduplicated items, detects synthetic base
+* declarations (excluded from categorization, collision detection and work
+* items — the owner class page renders them inline), categorizes, detects
+* route collisions on the lowercased `folder/name` route, builds the route
+* map with bare names owned by the highest-priority kind and member routes
+* from the model's anchors, adds namespace member routes (qualified always,
+* unqualified PascalCase when unambiguous), routes synthetic base names to
+* the owner's `#base-class` anchor, and flattens everything into work items.
+*
+* @public
+*/
+function prepareWorkItems(input) {
+	const { apiPackage, categories, baseRoute } = input;
+	const resolvedItems = EntryPoints.resolve(apiPackage);
+	const syntheticBases = SyntheticBases.detect(resolvedItems.map((r) => r.item));
+	const docItems = syntheticBases.bases.size ? resolvedItems.filter((r) => !syntheticBases.bases.has(r.item)) : resolvedItems;
+	const resolvedLookup = /* @__PURE__ */ new Map();
+	for (const resolved of docItems) resolvedLookup.set(`${resolved.item.displayName}::${resolved.item.kind}`, resolved);
+	const { items, uncategorized } = ApiItems.categorize(docItems, categories);
+	const namespaceMembers = ApiItems.namespaceMembers(docItems);
+	const categoryFor = (item) => Object.entries(categories).find(([, config]) => config.itemKinds?.includes(item.kind));
+	const candidates = [];
+	for (const [categoryKey, categoryConfig] of Object.entries(categories)) for (const item of items[categoryKey] || []) candidates.push(new Routes.RouteCandidate({
+		id: `${item.displayName}::${item.kind}`,
+		displayName: item.displayName,
+		folder: categoryConfig.folderName,
+		baseName: item.displayName.toLowerCase(),
+		kind: String(item.kind),
+		canonicalRef: item.canonicalReference?.toString() ?? item.displayName
+	}));
+	for (const nsMember of namespaceMembers) {
+		const nsCategory = categoryFor(nsMember.item);
+		if (!nsCategory) continue;
+		candidates.push(new Routes.RouteCandidate({
+			id: nsMember.qualifiedName,
+			displayName: nsMember.qualifiedName,
+			folder: nsCategory[1].folderName,
+			baseName: nsMember.qualifiedName.toLowerCase(),
+			kind: String(nsMember.item.kind),
+			canonicalRef: nsMember.item.canonicalReference?.toString() ?? nsMember.qualifiedName
+		}));
+	}
+	const collisions = Routes.detectCollisions(candidates);
+	const routes = /* @__PURE__ */ new Map();
+	const kinds = /* @__PURE__ */ new Map();
+	const routeOwnerPriority = /* @__PURE__ */ new Map();
+	for (const [categoryKey, categoryConfig] of Object.entries(categories)) for (const item of items[categoryKey] || []) {
+		const itemRoute = `${baseRoute}/${categoryConfig.folderName}/${item.displayName.toLowerCase()}`;
+		const priority = crossLinkKindPriority(String(item.kind));
+		const existingPriority = routeOwnerPriority.get(item.displayName);
+		if (existingPriority === void 0 || priority < existingPriority) {
+			routes.set(item.displayName, itemRoute);
+			kinds.set(item.displayName, item.kind);
+			routeOwnerPriority.set(item.displayName, priority);
+		}
+		if (item.kind === "Class" || item.kind === "Interface") {
+			const itemWithMembers = item;
+			const anchors = ApiItems.memberAnchors(itemWithMembers);
+			const byCanonicalRef = new Map(itemWithMembers.members.map((member) => [member.canonicalReference?.toString() ?? member.displayName, member]));
+			for (const [routeKey, memberId] of ApiItems.memberRouteKeys(itemWithMembers)) {
+				const member = byCanonicalRef.get(memberId);
+				if (!member) continue;
+				const anchor = anchors.get(memberId) ?? Routes.memberAnchor(member.displayName);
+				routes.set(routeKey, `${itemRoute}#${anchor}`);
+				kinds.set(routeKey, member.kind);
+			}
+		}
+	}
+	const unqualifiedNameCounts = /* @__PURE__ */ new Map();
+	for (const nsMember of namespaceMembers) {
+		const name = nsMember.item.displayName;
+		unqualifiedNameCounts.set(name, (unqualifiedNameCounts.get(name) || 0) + 1);
+	}
+	for (const nsMember of namespaceMembers) {
+		const category = categoryFor(nsMember.item);
+		if (!category) continue;
+		const qualifiedRoute = `${baseRoute}/${category[1].folderName}/${nsMember.qualifiedName.toLowerCase()}`;
+		routes.set(nsMember.qualifiedName, qualifiedRoute);
+		kinds.set(nsMember.qualifiedName, nsMember.item.kind);
+		const displayName = nsMember.item.displayName;
+		if (/^[A-Z]/.test(displayName) && (unqualifiedNameCounts.get(displayName) || 0) <= 1 && !routes.has(displayName)) {
+			routes.set(displayName, qualifiedRoute);
+			kinds.set(displayName, nsMember.item.kind);
+		}
+	}
+	for (const [baseItem, syntheticBase] of syntheticBases.bases) {
+		const baseName = baseItem.displayName;
+		if (routes.has(baseName)) continue;
+		const owner = syntheticBase.ownerClasses[0];
+		const ownerRoute = owner ? routes.get(owner.displayName) : void 0;
+		if (!ownerRoute) continue;
+		routes.set(baseName, `${ownerRoute}#${SyntheticBases.BASE_CLASS_ANCHOR}`);
+		kinds.set(baseName, baseItem.kind);
+	}
+	const workItems = [];
+	for (const [categoryKey, categoryConfig] of Object.entries(categories)) for (const item of items[categoryKey] || []) {
+		const resolved = resolvedLookup.get(`${item.displayName}::${item.kind}`);
+		const syntheticBase = syntheticBases.baseByOwner.get(item);
+		const memberAnchors = item.kind === "Class" || item.kind === "Interface" ? ApiItems.memberAnchors(item) : void 0;
+		workItems.push({
+			item,
+			categoryKey,
+			categoryConfig,
+			...resolved?.availableFrom != null ? { availableFrom: resolved.availableFrom } : {},
+			...syntheticBase != null ? { syntheticBase } : {},
+			...memberAnchors != null ? { memberAnchors } : {}
+		});
+	}
+	for (const nsMember of namespaceMembers) {
+		const category = categoryFor(nsMember.item);
+		if (category) workItems.push({
+			item: nsMember.item,
+			categoryKey: category[0],
+			categoryConfig: category[1],
+			namespaceMember: nsMember
+		});
+	}
+	return {
+		workItems,
+		crossLinkData: {
+			routes,
+			kinds
+		},
+		uncategorized,
+		collisions
+	};
+}
+
+//#endregion
+export { crossLinkKindPriority, prepareWorkItems };