@textmode/tooling-scripts 0.1.0

package/src/scripts/lib/jsdoc-comments.mjs

@@ -0,0 +1,78 @@
+export function getLineStartOffsets(text) {
+	const offsets = [0];
+	for (let index = 0; index < text.length; index += 1) {
+		if (text[index] === '\n') {
+			offsets.push(index + 1);
+		}
+	}
+	return offsets;
+}
+
+export function findJsdocBeforeLine(text, lineStarts, line) {
+	const declarationOffset = lineStarts[line - 1] ?? text.length;
+	const searchText = text.slice(0, declarationOffset);
+	const start = searchText.lastIndexOf('/**');
+	const end = searchText.lastIndexOf('*/');
+
+	if (start === -1 || end === -1 || start > end) {
+		return undefined;
+	}
+
+	return { start, end };
+}
+
+function replaceHostedApiSeeLines(commentText, seeLine, apiBaseUrl) {
+	const lines = commentText.split('\n');
+	let replaced = false;
+	const nextLines = [];
+
+	for (const line of lines) {
+		if (line.includes('@see') && line.includes(apiBaseUrl)) {
+			if (!replaced) {
+				nextLines.push(line.replace(/^(\s*\*\s*).*$/, `$1${seeLine}`));
+				replaced = true;
+			}
+			continue;
+		}
+
+		nextLines.push(line);
+	}
+
+	return replaced ? nextLines.join('\n') : undefined;
+}
+
+export function upsertSeeLine(text, comment, seeLine, apiBaseUrl) {
+	const commentText = text.slice(comment.start, comment.end + 2);
+	const replacedComment = replaceHostedApiSeeLines(commentText, seeLine, apiBaseUrl);
+	if (replacedComment !== undefined) {
+		return `${text.slice(0, comment.start)}${replacedComment}${text.slice(comment.end + 2)}`;
+	}
+
+	if (!commentText.includes('\n')) {
+		const lineStart = text.lastIndexOf('\n', comment.start) + 1;
+		const indent = text.slice(lineStart, comment.start);
+		const summary = commentText
+			.replace(/^\/\*\*\s?/, '')
+			.replace(/\s?\*\/$/, '')
+			.trim();
+		const replacement = [
+			`${indent}/**`,
+			summary ? `${indent} * ${summary}` : undefined,
+			`${indent} *`,
+			`${indent} * ${seeLine}`,
+			`${indent} */`,
+		]
+			.filter(Boolean)
+			.join('\n');
+
+		return `${text.slice(0, lineStart)}${replacement}${text.slice(comment.end + 2)}`;
+	}
+
+	const lineStart = text.lastIndexOf('\n', comment.end) + 1;
+	const closingLine = text.slice(lineStart, comment.end + 2);
+	const prefixMatch = closingLine.match(/^(\s*)\*\//);
+	const indent = prefixMatch?.[1] ?? '';
+	const insertion = `${indent}*\n${indent}* ${seeLine}\n`;
+
+	return `${text.slice(0, lineStart)}${insertion}${text.slice(lineStart)}`;
+}

package/src/scripts/lib/reflection-policy.mjs

@@ -0,0 +1,106 @@
+import path from 'node:path';
+
+import { ReflectionKind } from 'typedoc';
+
+export function isIncludedReflection(reflection, targetKinds) {
+	if (!reflection.kindOf(targetKinds)) {
+		return false;
+	}
+
+	if (reflection.flags.isPrivate || reflection.flags.isProtected || reflection.flags.isInherited) {
+		return false;
+	}
+
+	for (let current = reflection; current && !current.isProject(); current = current.parent) {
+		if (current.name.startsWith('_')) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+export function getIncludedReflections(project, targetKinds) {
+	return project
+		.getReflectionsByKind(targetKinds)
+		.filter((reflection) => isIncludedReflection(reflection, targetKinds));
+}
+
+export function shouldProcessEntryPointReflection(entryPoint, reflection) {
+	return !entryPoint.namespaceExportsOnly || reflection.kind === ReflectionKind.Namespace;
+}
+
+export function getRelevantComments(reflection) {
+	const comments = [];
+
+	if (reflection.comment) {
+		comments.push({ comment: reflection.comment, source: reflection.sources?.[0] });
+	}
+
+	if (!reflection.isDeclaration()) {
+		return comments;
+	}
+
+	for (const signature of reflection.signatures ?? []) {
+		if (signature.comment) {
+			comments.push({ comment: signature.comment, source: signature.sources?.[0] ?? reflection.sources?.[0] });
+		}
+	}
+
+	if (reflection.getSignature?.comment) {
+		comments.push({
+			comment: reflection.getSignature.comment,
+			source: reflection.getSignature.sources?.[0] ?? reflection.sources?.[0],
+		});
+	}
+
+	if (reflection.setSignature?.comment) {
+		comments.push({
+			comment: reflection.setSignature.comment,
+			source: reflection.setSignature.sources?.[0] ?? reflection.sources?.[0],
+		});
+	}
+
+	return comments;
+}
+
+export function getSourceCandidates(reflection) {
+	if (!reflection.isDeclaration()) {
+		return [];
+	}
+
+	return [
+		...(reflection.sources ?? []),
+		...(reflection.signatures ?? []).flatMap((signature) => signature.sources ?? []),
+		...(reflection.getSignature?.sources ?? []),
+		...(reflection.setSignature?.sources ?? []),
+	];
+}
+
+export function getPrimaryLocation(reflection) {
+	const [source] = getSourceCandidates(reflection);
+
+	if (!source) {
+		return {
+			file: path.resolve('<unknown>'),
+			line: 1,
+			column: 1,
+			printable: '<unknown>:1:1',
+		};
+	}
+
+	const file = source.fullFileName || path.resolve(source.fileName);
+	const line = source.line || 1;
+	const column = (source.character ?? 0) + 1;
+
+	return {
+		file,
+		line,
+		column,
+		printable: `${file}:${line}:${column}`,
+	};
+}
+
+export function sourceIsInRoots(source, sourceRoots) {
+	return Boolean(source?.fullFileName) && sourceRoots.some((root) => source.fullFileName.startsWith(root));
+}

package/src/scripts/lib/reporting.mjs

@@ -0,0 +1,23 @@
+export function renderIssueSection(title, issues, stream = console.log) {
+	if (issues.length === 0) {
+		return;
+	}
+
+	stream('');
+	stream(`${title}: ${issues.length}`);
+
+	for (const issue of issues) {
+		stream(`- ${issue.name}`);
+		stream(`  ${issue.location}`);
+		if (issue.detail) {
+			stream(`  ${issue.detail}`);
+		}
+	}
+}
+
+export function renderList(title, items, stream = console.error) {
+	stream(title);
+	for (const item of items) {
+		stream(`  * ${item}`);
+	}
+}

package/src/scripts/lib/typedoc-project.mjs

@@ -0,0 +1,25 @@
+import { Application, PackageJsonReader, TSConfigReader } from 'typedoc';
+
+export async function loadTypeDocProject({ entryPoint, tsconfig = 'tsconfig.json', errorMessage }) {
+	const app = await Application.bootstrap(
+		{
+			entryPoints: [entryPoint],
+			entryPointStrategy: 'resolve',
+			tsconfig,
+			excludeInternal: true,
+			excludePrivate: true,
+			excludeProtected: true,
+			readme: 'none',
+			emit: 'none',
+			logLevel: 'Error',
+		},
+		[new PackageJsonReader(), new TSConfigReader()]
+	);
+
+	const project = await app.convert();
+	if (!project || app.logger.hasErrors()) {
+		throw new Error(errorMessage ?? `TypeDoc failed to resolve ${entryPoint}.`);
+	}
+
+	return project;
+}

package/src/typedoc-plugins/accessor-docs-normalizer/README.md

@@ -0,0 +1,45 @@
+# Accessor Docs Normalizer
+
+## Purpose
+
+TypeDoc stores comments for TypeScript accessors on the getter and setter signatures. `typedoc-plugin-markdown`
+overview tables read descriptions from the accessor reflection itself. When the reflection has no direct comment,
+the generated table falls back to `-` even though the getter or setter is documented in source.
+
+This plugin normalizes that shape for the textmode.js API docs:
+
+- Copies the first getter or setter signature comment onto an accessor reflection when the accessor has no comment.
+- Tracks copied comments so the accessor page does not render the same summary twice.
+- Replaces the markdown accessor partial so getter documentation appears before setter documentation.
+- Keeps getter return sections, setter parameter sections, inheritance sections, and `disableSources` behavior intact.
+
+The plugin does not change runtime library behavior, the public TypeScript API, source JSDoc ownership, or TypeDoc
+reflection conversion. It only adjusts markdown rendering after TypeDoc has built the reflection model.
+
+This exists to avoid source-level documentation stubs or declaration-merging boilerplate for accessor descriptions.
+Accessor docs should stay in the source declarations that own the getter and setter behavior.
+
+## Preserved Output Contract
+
+- Accessor overview tables show the first available getter or setter summary.
+- Accessor pages do not render copied comments twice.
+- Getter content renders before setter content.
+- Getter return sections, setter parameter sections, inheritance sections, and `disableSources` behavior match
+  `typedoc-plugin-markdown`.
+
+## Contributor Notes
+
+- Safe to edit: helper names, tests, README wording, and the local comment-normalization traversal.
+- Be careful with: `theme-patch.js`, because it monkey-patches `MarkdownTheme.prototype.getRenderContext`.
+- Do not casually change: accessor partial output order, copied-comment tracking, or source-display conditions.
+
+## Maintenance
+
+This plugin depends on `typedoc-plugin-markdown` theme internals, especially `MarkdownTheme.getRenderContext` and the
+`partials.accessor` contract. Re-check this plugin after upgrading `typedoc-plugin-markdown`.
+
+Upgrade checklist:
+
+- Compare `render-accessor.js` against the current upstream accessor partial.
+- Confirm `MarkdownTheme.getRenderContext` still exists and returns a mutable partials object.
+- Run `npm run test:tooling` and inspect generated accessor pages for duplicate summaries.

package/src/typedoc-plugins/accessor-docs-normalizer/accessor-comments.js

@@ -0,0 +1,53 @@
+// @ts-check
+
+import { ReflectionKind } from 'typedoc';
+
+const syntheticAccessorComments = new WeakSet();
+
+/**
+ * Get the first signature-level comment available for an accessor reflection.
+ * TypeDoc currently keeps getter/setter comments on their signatures, while
+ * overview tables read from the accessor declaration itself.
+ *
+ * @param {import('typedoc').DeclarationReflection} accessor
+ * @returns {import('typedoc').Comment | undefined}
+ */
+function getAccessorSignatureComment(accessor) {
+	return accessor.getSignature?.comment ?? accessor.setSignature?.comment;
+}
+
+/**
+ * Copy signature comments onto accessor declarations when needed so markdown
+ * overview tables can render descriptions instead of falling back to "-".
+ *
+ * @param {import('typedoc').Reflection | undefined} model
+ * @returns {void}
+ */
+export function normalizeAccessorComments(model) {
+	if (!model) {
+		return;
+	}
+
+	if (model.kind === ReflectionKind.Accessor && 'comment' in model && !model.comment) {
+		const signatureComment = getAccessorSignatureComment(model);
+		if (signatureComment) {
+			model.comment = signatureComment;
+			syntheticAccessorComments.add(model);
+		}
+	}
+
+	model.traverse?.((child) => {
+		normalizeAccessorComments(child);
+		return true;
+	});
+}
+
+/**
+ * Check whether a comment was copied onto an accessor by this plugin.
+ *
+ * @param {import('typedoc').DeclarationReflection} accessor
+ * @returns {boolean}
+ */
+export function hasSyntheticAccessorComment(accessor) {
+	return syntheticAccessorComments.has(accessor);
+}

package/src/typedoc-plugins/accessor-docs-normalizer/index.js

@@ -0,0 +1,32 @@
+// @ts-check
+
+import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';
+
+import { normalizeAccessorComments } from './accessor-comments.js';
+import { renderAccessorDocs } from './render-accessor.js';
+import { patchMarkdownThemeRenderContext } from './theme-patch.js';
+
+class AccessorDocsMarkdownThemeContext extends MarkdownThemeContext {
+	/**
+	 * @param {MarkdownTheme} theme
+	 * @param {import('typedoc-plugin-markdown').MarkdownPageEvent<import('typedoc').Reflection>} page
+	 * @param {import('typedoc').Options} options
+	 */
+	constructor(theme, page, options) {
+		super(theme, page, options);
+		normalizeAccessorComments(page.model);
+		this.partials.accessor = (accessor, partialOptions) => renderAccessorDocs(this, accessor, partialOptions);
+	}
+}
+
+/**
+ * @param {import('typedoc').Application} app
+ * @returns {void}
+ */
+export function load(app) {
+	patchMarkdownThemeRenderContext(
+		(theme, page) => new AccessorDocsMarkdownThemeContext(theme, page, theme.application.options)
+	);
+
+	app.logger.verbose('[typedoc] Registered accessor docs normalizer');
+}

package/src/typedoc-plugins/accessor-docs-normalizer/render-accessor.js

@@ -0,0 +1,144 @@
+// @ts-check
+
+import { i18n, ReflectionKind } from 'typedoc';
+
+import { hasSyntheticAccessorComment } from './accessor-comments.js';
+
+/**
+ * @param {number} level
+ * @param {string} text
+ * @returns {string}
+ */
+function heading(level, text) {
+	return `${'#'.repeat(level)} ${text}`;
+}
+
+/**
+ * Render one getter or setter signature.
+ *
+ * @param {import('typedoc-plugin-markdown').MarkdownThemeContext} context
+ * @param {import('typedoc').SignatureReflection} signature
+ * @param {{
+ *   accessor: 'get' | 'set';
+ *   headingLevel: number;
+ *   includeParameters: boolean;
+ *   showSources: boolean;
+ *   title: string;
+ * }} options
+ * @returns {string}
+ */
+function renderAccessorSignature(context, signature, options) {
+	const md = [];
+
+	md.push(heading(options.headingLevel, options.title));
+	md.push(
+		context.partials.signatureTitle(signature, {
+			accessor: options.accessor,
+		})
+	);
+
+	if (options.showSources && !context.options.getValue('disableSources') && signature.sources) {
+		md.push(context.partials.sources(signature));
+	}
+
+	if (signature.comment) {
+		md.push(
+			context.partials.comment(signature.comment, {
+				headingLevel: options.headingLevel + 1,
+				showTags: false,
+				showSummary: true,
+			})
+		);
+	}
+
+	if (options.includeParameters && signature.parameters?.length) {
+		md.push(heading(options.headingLevel + 1, ReflectionKind.pluralString(ReflectionKind.Parameter)));
+		if (context.helpers.useTableFormat('parameters')) {
+			md.push(context.partials.parametersTable(signature.parameters));
+		} else {
+			md.push(
+				context.partials.parametersList(signature.parameters, {
+					headingLevel: options.headingLevel + 1,
+				})
+			);
+		}
+	}
+
+	if (signature.type) {
+		md.push(
+			context.partials.signatureReturns(signature, {
+				headingLevel: options.headingLevel + 1,
+			})
+		);
+	}
+
+	if (signature.comment) {
+		md.push(
+			context.partials.comment(signature.comment, {
+				headingLevel: options.headingLevel + 1,
+				showTags: true,
+				showSummary: false,
+			})
+		);
+	}
+
+	return md.filter(Boolean).join('\n\n');
+}
+
+/**
+ * Render accessor documentation with getter content before setter content.
+ *
+ * @param {import('typedoc-plugin-markdown').MarkdownThemeContext} context
+ * @param {import('typedoc').DeclarationReflection} accessor
+ * @param {{ headingLevel: number }} options
+ * @returns {string}
+ */
+export function renderAccessorDocs(context, accessor, options) {
+	const md = [];
+	const showSources = accessor.parent?.kind !== ReflectionKind.TypeLiteral;
+
+	if (accessor.getSignature) {
+		md.push(
+			renderAccessorSignature(context, accessor.getSignature, {
+				accessor: 'get',
+				headingLevel: options.headingLevel,
+				includeParameters: false,
+				showSources,
+				title: i18n.kind_get_signature(),
+			})
+		);
+	}
+
+	if (accessor.setSignature) {
+		md.push(
+			renderAccessorSignature(context, accessor.setSignature, {
+				accessor: 'set',
+				headingLevel: options.headingLevel,
+				includeParameters: true,
+				showSources,
+				title: i18n.kind_set_signature(),
+			})
+		);
+	}
+
+	if (
+		showSources &&
+		!context.options.getValue('disableSources') &&
+		!accessor.getSignature &&
+		!accessor.setSignature
+	) {
+		md.push(context.partials.sources(accessor));
+	}
+
+	if (accessor.comment && !hasSyntheticAccessorComment(accessor)) {
+		md.push(
+			context.partials.comment(accessor.comment, {
+				headingLevel: options.headingLevel,
+			})
+		);
+	}
+
+	md.push(context.partials.inheritance(accessor, { headingLevel: options.headingLevel }));
+
+	return md.filter(Boolean).join('\n\n');
+}

package/src/typedoc-plugins/accessor-docs-normalizer/theme-patch.js

@@ -0,0 +1,28 @@
+// @ts-check
+
+import { MarkdownTheme } from 'typedoc-plugin-markdown';
+
+let isPatched = false;
+
+/**
+ * Patch typedoc-plugin-markdown's theme render-context factory once.
+ *
+ * This is the only place this plugin reaches into markdown theme internals.
+ * Keep the patch idempotent because TypeDoc can load plugins repeatedly in
+ * watch mode and tests can import the plugin more than once.
+ *
+ * @param {(theme: MarkdownTheme, page: import('typedoc-plugin-markdown').MarkdownPageEvent<import('typedoc').Reflection>) => import('typedoc-plugin-markdown').MarkdownThemeContext} createContext
+ * @returns {boolean} True when this call installed the patch.
+ */
+export function patchMarkdownThemeRenderContext(createContext) {
+	if (isPatched) {
+		return false;
+	}
+
+	MarkdownTheme.prototype.getRenderContext = function (page) {
+		return createContext(this, page);
+	};
+	isPatched = true;
+
+	return true;
+}

package/src/typedoc-plugins/all-member-pages-router/README.md

@@ -0,0 +1,57 @@
+# All Member Pages Router
+
+## Purpose
+
+This TypeDoc router makes direct public methods render as focused Markdown pages when an owner page would otherwise
+render too many Sandpack examples.
+
+`typedoc-plugin-markdown` can render top-level API structures as pages, but textmode.js also needs compact class and
+interface overview pages that link to individual methods once their inline examples would make the page heavy. This
+router keeps those owner pages small and gives each direct method a stable page.
+
+## Member Pages
+
+The router creates pages for direct class/interface methods when rendering the owner page inline would exceed three
+Sandpack examples:
+
+- methods
+
+Nested type-literal fields intentionally remain inline or anchor-based so structural types do not explode into many
+small pages.
+
+## Paths
+
+Examples:
+
+- `classes/Textmodifier/methods/background.md`
+- `namespaces/layering/classes/TextmodeLayer/methods/draw.md`
+
+## Preserved Output Contract
+
+- The router name remains `all-member-pages`.
+- Direct methods get pages only when their class/interface owner would otherwise exceed three Sandpack examples.
+- Properties, accessors, constructors, variables, type aliases, functions, and nested type-literal members do not get
+  extra pages from this router.
+- Existing `MemberRouter` behavior for modules, namespaces, documents, and configured `membersWithOwnFile` kinds is
+  preserved.
+- Project-root namespaces use the flattened textmode.js path shape, for example `namespaces/color/classes/TextmodeColor.md`.
+- Sidebar entries include generated member pages under their owners.
+
+## Contributor Notes
+
+- Safe to edit: constants, helper names, tests, and README wording.
+- Be careful with: `child-pages.js`, which intentionally mirrors upstream `MemberRouter` traversal.
+- Do not casually change: path segment names, namespace path flattening, example-count thresholds, or direct-method page
+  eligibility.
+
+## Maintenance
+
+This plugin extends `typedoc-plugin-markdown`'s `MemberRouter` and copies its child-page traversal policy so direct
+members can participate in TypeDoc's `hasOwnDocument` behavior. Re-check this router after upgrading TypeDoc or
+`typedoc-plugin-markdown`, especially around router APIs, `membersWithOwnFile`, and namespace path handling.
+
+Upgrade checklist:
+
+- Compare `child-pages.js` against the current upstream `MemberRouter.buildChildPages`.
+- Confirm `PageKind.Reflection`, `Slugger`, `fullUrls`, and `sluggers` are still the correct router APIs.
+- Run `npm run build:docs` and verify generated method links still resolve.

package/src/typedoc-plugins/all-member-pages-router/child-pages.js

@@ -0,0 +1,65 @@
+// @ts-check
+
+import { Reflection, Slugger } from 'typedoc';
+
+import { isDirectMemberPageReflection, shouldRenderOwnPage } from './member-reflections.js';
+
+/**
+ * @typedef {{
+ *   extension: string;
+ *   fullUrls: Map<import('typedoc').Reflection, string>;
+ *   sluggerConfiguration: unknown;
+ *   sluggers: Map<import('typedoc').Reflection, Slugger>;
+ *   getFileName(idealName: string): string;
+ *   getIdealBaseName(reflection: import('typedoc').Reflection): string;
+ *   getPageKind(reflection: import('typedoc').Reflection): import('typedoc').PageKind | undefined;
+ *   shouldWritePage(reflection: import('typedoc').Reflection): boolean;
+ *   buildAnchors(reflection: import('typedoc').Reflection, parent?: import('typedoc').Reflection): void;
+ *   membersWithOwnFile: string[];
+ *   kindsToString: Map<import('typedoc').ReflectionKind, string>;
+ * }} ChildPageRouter
+ */
+
+/**
+ * Build child pages using typedoc-plugin-markdown's MemberRouter traversal
+ * shape, while delegating textmode.js' expanded own-page policy to local
+ * helpers. This mirrors upstream traversal intentionally; when upgrading
+ * typedoc-plugin-markdown, compare this function against MemberRouter.
+ *
+ * @param {ChildPageRouter} router
+ * @param {import('typedoc').Reflection} reflection
+ * @param {import('typedoc').PageDefinition[]} outPages
+ * @returns {void}
+ */
+export function buildMemberRouterChildPages(router, reflection, outPages) {
+	const kind = router.getPageKind(reflection);
+	if (!kind) {
+		router.buildAnchors(reflection, reflection.parent);
+		return;
+	}
+
+	const shouldWritePage = isDirectMemberPageReflection(reflection) || router.shouldWritePage(reflection);
+	const idealName = router.getIdealBaseName(reflection);
+	const actualName = shouldWritePage ? router.getFileName(idealName) : `${idealName}${router.extension}`;
+	router.fullUrls.set(reflection, actualName);
+
+	if (shouldRenderOwnPage(reflection, router)) {
+		if (shouldWritePage) {
+			router.sluggers.set(reflection, new Slugger(router.sluggerConfiguration));
+			outPages.push({
+				kind,
+				model: reflection,
+				url: actualName,
+			});
+		}
+	} else {
+		router.buildAnchors(reflection, reflection.parent);
+	}
+
+	if (reflection instanceof Reflection) {
+		reflection.traverse((child) => {
+			buildMemberRouterChildPages(router, child, outPages);
+			return true;
+		});
+	}
+}