@textmode/tooling-scripts 0.1.0

package/src/typedoc-plugins/api-frontmatter/library-context.js

@@ -0,0 +1,62 @@
+// @ts-check
+
+import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+import { TEXTMODE_ECOSYSTEM_NAME, TEXTMODE_PACKAGE_PREFIX, UNKNOWN_LIBRARY_NAME } from './constants.js';
+
+/**
+ * Library context extracted from package.json and the TypeDoc project.
+ *
+ * @typedef {Object} LibraryContext
+ * @property {string} name
+ * @property {string} description
+ * @property {string} ecosystem
+ */
+
+/**
+ * Read and parse package.json from the project root.
+ *
+ * @returns {{ name?: string; description?: string } | null}
+ */
+export function readPackageJson() {
+	try {
+		const directory = dirname(fileURLToPath(import.meta.url));
+		const packagePath = resolve(directory, '..', '..', 'package.json');
+		const content = readFileSync(packagePath, 'utf-8');
+		return JSON.parse(content);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Get the ecosystem name for a package.
+ *
+ * @param {string} packageName
+ * @returns {string}
+ */
+export function getEcosystemName(packageName) {
+	return packageName.startsWith(TEXTMODE_PACKAGE_PREFIX) ? TEXTMODE_ECOSYSTEM_NAME : packageName;
+}
+
+/**
+ * Extract library context from TypeDoc project metadata and package.json.
+ *
+ * @param {import('typedoc').ProjectReflection} project
+ * @returns {LibraryContext}
+ */
+export function extractLibraryContext(project) {
+	const name = project.packageName ?? project.name ?? UNKNOWN_LIBRARY_NAME;
+
+	let description = `API reference for ${name}`;
+	const packageJson = readPackageJson();
+	if (packageJson?.description) {
+		description = packageJson.description;
+	}
+
+	const ecosystem = getEcosystemName(name);
+
+	return { name, description, ecosystem };
+}

package/src/typedoc-plugins/api-frontmatter/reflection-metadata.js

@@ -0,0 +1,95 @@
+// @ts-check
+
+import { ReflectionKind } from 'typedoc';
+
+import { API_REFERENCE_CATEGORY, CATEGORY_BY_KIND } from './constants.js';
+
+/**
+ * Get the frontmatter category for a reflection kind.
+ *
+ * @param {import('typedoc').ReflectionKind} kind
+ * @returns {string}
+ */
+export function getCategoryForKind(kind) {
+	return CATEGORY_BY_KIND.get(kind) ?? API_REFERENCE_CATEGORY;
+}
+
+/**
+ * Check if a reflection belongs to a namespace.
+ *
+ * @param {import('typedoc').Reflection} model
+ * @returns {boolean}
+ */
+export function isInNamespace(model) {
+	let parent = model.parent;
+	while (parent) {
+		if (parent.kind === ReflectionKind.Namespace) {
+			return true;
+		}
+		parent = parent.parent;
+	}
+	return false;
+}
+
+/**
+ * Get the full namespace path for a reflection.
+ *
+ * @param {import('typedoc').Reflection} model
+ * @returns {string | undefined}
+ */
+export function getNamespacePath(model) {
+	/** @type {string[]} */
+	const parts = [];
+	let parent = model.parent;
+
+	while (parent) {
+		if (parent.kind === ReflectionKind.Namespace) {
+			parts.unshift(parent.name);
+		}
+		parent = parent.parent;
+	}
+
+	return parts.length > 0 ? parts.join('.') : undefined;
+}
+
+/**
+ * Get the owning class or interface name for member reflections.
+ *
+ * @param {import('typedoc').Reflection} model
+ * @returns {string | undefined}
+ */
+export function getOwnerName(model) {
+	let parent = model.parent;
+	while (parent) {
+		if (parent.kind === ReflectionKind.Class || parent.kind === ReflectionKind.Interface) {
+			return parent.name;
+		}
+		parent = parent.parent;
+	}
+
+	return undefined;
+}
+
+/**
+ * Check if a class reflection has a constructor child.
+ *
+ * @param {import('typedoc').Reflection} model
+ * @returns {boolean | undefined}
+ */
+export function getHasConstructor(model) {
+	if (model.kind !== ReflectionKind.Class || !('children' in model)) {
+		return undefined;
+	}
+
+	return model.children?.some((child) => child.kind === ReflectionKind.Constructor);
+}
+
+/**
+ * Check if a reflection is an interface.
+ *
+ * @param {import('typedoc').Reflection} model
+ * @returns {true | undefined}
+ */
+export function getIsInterface(model) {
+	return model.kind === ReflectionKind.Interface ? true : undefined;
+}

package/src/typedoc-plugins/include-code-examples/README.md

@@ -0,0 +1,40 @@
+# Include Code Examples
+
+## Purpose
+
+This TypeDoc plugin cleans up example sketches included in API docs with `{@includeCode ...}`.
+
+Example sketches keep leading gallery metadata such as `@title` and `@author` so the examples gallery and validation
+scripts can read it. API reference pages should show only the runnable sketch code, so this plugin removes a leading
+JSDoc metadata block from supported fenced code blocks after TypeDoc has rendered markdown.
+
+The plugin also normalizes transformed `js` fences to `javascript` for VitePress syntax highlighting. That normalization
+is intentionally gated by metadata stripping: a plain `js` fence without a leading metadata block is left unchanged.
+
+This is a post-render markdown transform. It does not edit source examples, change TypeDoc reflections, or add new
+TypeDoc options.
+
+## Preserved Output Contract
+
+- Only fenced `js`, `jsx`, `ts`, `tsx`, `javascript`, and `typescript` blocks are considered.
+- Only a leading JSDoc metadata block is stripped.
+- Plain code fences without stripped metadata are left byte-for-byte unchanged.
+- `js` fences are normalized to `javascript` only when metadata was stripped.
+- Unsupported and language-less fences are left unchanged.
+
+## Contributor Notes
+
+- Safe to edit: helper names, supported-language tests, and comments.
+- Be careful with: `EXAMPLE_CODE_FENCE_PATTERN`, because it intentionally operates after TypeDoc renders markdown.
+- Do not casually change: supported language gating, `js` normalization timing, or the “leading docblock only” rule.
+
+## Maintenance
+
+This plugin depends on TypeDoc rendering `{@includeCode ...}` examples as fenced code blocks before
+`MarkdownPageEvent.END`. Re-check the transform after upgrading TypeDoc or `typedoc-plugin-markdown`.
+
+Upgrade checklist:
+
+- Confirm included examples still arrive in `page.contents` as fenced markdown.
+- Run `npm run test:tooling`.
+- Inspect a generated API example and verify gallery metadata such as `@title` is absent.

package/src/typedoc-plugins/include-code-examples/code-fences.js

@@ -0,0 +1,55 @@
+// @ts-check
+
+export const EXAMPLE_CODE_FENCE_PATTERN = /```([^\n]*)\n([\s\S]*?)```/g;
+
+export const SUPPORTED_INCLUDED_EXAMPLE_LANGUAGES = new Set(['js', 'jsx', 'ts', 'tsx', 'javascript', 'typescript']);
+
+/**
+ * Get the language token from a fenced code block info string.
+ *
+ * @param {string} infoString
+ * @returns {string}
+ */
+export function getFenceLanguage(infoString) {
+	return infoString.trim().split(/\s+/, 1)[0]?.toLowerCase() ?? '';
+}
+
+/**
+ * Check whether the language can contain an included sketch.
+ *
+ * @param {string} language
+ * @returns {boolean}
+ */
+export function isSupportedExampleLanguage(language) {
+	return SUPPORTED_INCLUDED_EXAMPLE_LANGUAGES.has(language);
+}
+
+/**
+ * Normalize the fence language for transformed included examples.
+ *
+ * @param {string} infoString
+ * @returns {string}
+ */
+export function normalizeIncludedExampleFenceInfo(infoString) {
+	const trimmedInfoString = infoString.trim();
+	if (!trimmedInfoString) {
+		return infoString;
+	}
+
+	const parts = trimmedInfoString.split(/\s+/);
+	if (parts[0].toLowerCase() === 'js') {
+		parts[0] = 'javascript';
+	}
+
+	return parts.join(' ');
+}
+
+/**
+ * Ensure transformed code ends with one newline before the closing fence.
+ *
+ * @param {string} code
+ * @returns {string}
+ */
+export function ensureTrailingNewline(code) {
+	return code.endsWith('\n') ? code : `${code}\n`;
+}

package/src/typedoc-plugins/include-code-examples/example-metadata.js

@@ -0,0 +1,41 @@
+// @ts-check
+
+const LEADING_EXAMPLE_METADATA_PATTERN = /^\s*\/\*\*([\s\S]*?)\*\/\s*\n?/;
+
+/**
+ * Strip the leading gallery metadata docblock from an included example.
+ *
+ * @param {string} source
+ * @returns {string}
+ */
+export function stripLeadingExampleMetadataDocblock(source) {
+	const match = source.match(LEADING_EXAMPLE_METADATA_PATTERN);
+	if (!match) {
+		return source;
+	}
+
+	return source.slice(match[0].length).replace(/^\n+/, '');
+}
+
+/**
+ * Backwards-compatible helper name retained for copied add-on plugin stacks.
+ *
+ * @param {string} source
+ * @returns {string}
+ */
+export function stripLeadingExampleMetadata(source) {
+	return stripLeadingExampleMetadataDocblock(source);
+}
+
+/**
+ * Preserve the old helper shape while keeping metadata parsing intentionally minimal.
+ *
+ * @param {string} source
+ * @returns {{ metadata: null; code: string }}
+ */
+export function extractExampleMetadata(source) {
+	return {
+		metadata: null,
+		code: stripLeadingExampleMetadataDocblock(source),
+	};
+}

package/src/typedoc-plugins/include-code-examples/index.js

@@ -0,0 +1,23 @@
+// @ts-check
+
+import { MarkdownPageEvent } from 'typedoc-plugin-markdown';
+
+import { transformExampleCodeBlocks } from './transform-markdown.js';
+
+/**
+ * TypeDoc plugin load function.
+ *
+ * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
+ * @returns {void}
+ */
+export function load(app) {
+	app.renderer.on(MarkdownPageEvent.END, (page) => {
+		if (!page.contents) {
+			return;
+		}
+
+		page.contents = transformExampleCodeBlocks(page.contents);
+	});
+
+	app.logger.verbose('[typedoc] Registered includeCode example normalizer');
+}

package/src/typedoc-plugins/include-code-examples/transform-markdown.js

@@ -0,0 +1,33 @@
+// @ts-check
+
+import {
+	ensureTrailingNewline,
+	EXAMPLE_CODE_FENCE_PATTERN,
+	getFenceLanguage,
+	isSupportedExampleLanguage,
+	normalizeIncludedExampleFenceInfo,
+} from './code-fences.js';
+import { stripLeadingExampleMetadataDocblock } from './example-metadata.js';
+
+/**
+ * Remove gallery metadata from included example code blocks.
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+export function transformExampleCodeBlocks(markdown) {
+	return markdown.replace(EXAMPLE_CODE_FENCE_PATTERN, (fullMatch, infoString, code) => {
+		const language = getFenceLanguage(infoString);
+		if (!isSupportedExampleLanguage(language)) {
+			return fullMatch;
+		}
+
+		const strippedCode = stripLeadingExampleMetadataDocblock(code);
+		if (strippedCode === code) {
+			return fullMatch;
+		}
+
+		const normalizedInfoString = normalizeIncludedExampleFenceInfo(infoString);
+		return `\`\`\`${normalizedInfoString}\n${ensureTrailingNewline(strippedCode)}\`\`\``;
+	});
+}

package/src/typedoc-plugins/strip-api-self-links/index.js

@@ -0,0 +1,126 @@
+// @ts-check
+
+import { Converter, ParameterType, ReflectionKind } from 'typedoc';
+import { MarkdownPageEvent } from 'typedoc-plugin-markdown';
+
+let apiBaseUrl = 'https://code.textmode.art/api/textmode.js';
+let stripMode = 'full';
+
+/**
+ * Check whether a comment display part links to the hosted textmode.js API.
+ *
+ * @param {import('typedoc').CommentDisplayPart} part
+ * @returns {boolean}
+ */
+function isHostedApiLink(part) {
+	return part.kind === 'inline-tag' && part.tag === '@link' && String(part.target ?? '').startsWith(apiBaseUrl);
+}
+
+/**
+ * Remove `@see` tags that point back to the generated API site itself.
+ *
+ * These links are useful in emitted declaration hover docs, but they are redundant
+ * inside the TypeDoc API pages hosted at the same URLs.
+ *
+ * @param {import('typedoc').Comment | undefined} comment
+ * @returns {void}
+ */
+function stripHostedApiSeeTags(comment) {
+	if (!comment) {
+		return;
+	}
+
+	comment.blockTags = comment.blockTags.filter(
+		(tag) => tag.tag !== '@see' || !tag.content.some((part) => isHostedApiLink(part))
+	);
+}
+
+/**
+ * @param {import('typedoc').Reflection} reflection
+ * @returns {void}
+ */
+function stripReflectionHostedApiSeeTags(reflection) {
+	stripHostedApiSeeTags(reflection.comment);
+
+	if (!reflection.isDeclaration()) {
+		return;
+	}
+
+	for (const signature of reflection.signatures ?? []) {
+		stripHostedApiSeeTags(signature.comment);
+	}
+
+	stripHostedApiSeeTags(reflection.getSignature?.comment);
+	stripHostedApiSeeTags(reflection.setSignature?.comment);
+}
+
+/**
+ * Remove generated Markdown links back to the same hosted API reference.
+ *
+ * @param {string} contents
+ * @returns {string}
+ */
+function stripHostedApiMarkdownLinks(contents) {
+	const escapedBaseUrl = apiBaseUrl.replaceAll('.', '\\.');
+	const hostedApiLinkPattern = `\\[[^\\]]+ API reference\\]\\(${escapedBaseUrl}[^)]*\\)`;
+	const standaloneSeeSection = new RegExp(`\\n#{2,6} See\\n\\n${hostedApiLinkPattern}\\n`, 'g');
+	const inlineSeeLink = new RegExp(`\\s*\\*\\*See\\*\\*\\s*${hostedApiLinkPattern}`, 'g');
+	const standaloneLinkLine =
+		stripMode === 'minimal'
+			? new RegExp(`^${hostedApiLinkPattern}\\n`, 'gm')
+			: new RegExp(`^\\s*${hostedApiLinkPattern}\\n?`, 'gm');
+
+	let nextContents = contents.replace(standaloneSeeSection, '\n').replace(inlineSeeLink, '').replace(standaloneLinkLine, '');
+
+	if (stripMode === 'full') {
+		const listItemLinkLine = new RegExp(`^\\s*-\\s*${hostedApiLinkPattern}\\n?`, 'gm');
+		const emptySeeSection = /\n#{2,6} See\n(?:\s*\n)+(?=#{1,6}\s|\n*$)/g;
+		nextContents = nextContents.replace(listItemLinkLine, '').replace(emptySeeSection, '\n');
+	}
+
+	return nextContents;
+}
+
+/**
+ * TypeDoc plugin load function.
+ *
+ * @param {import('typedoc').Application} app
+ * @returns {void}
+ */
+export function load(app) {
+	app.options.addDeclaration({
+		name: 'textmodeApiBaseUrl',
+		help: 'Base URL of the hosted textmode API for self-link stripping.',
+		type: ParameterType.String,
+		defaultValue: apiBaseUrl,
+	});
+	app.options.addDeclaration({
+		name: 'textmodeStripApiSelfLinksMode',
+		help: 'Hosted API self-link Markdown stripping mode.',
+		type: ParameterType.String,
+		defaultValue: stripMode,
+	});
+
+	app.converter.on(Converter.EVENT_BEGIN, () => {
+		apiBaseUrl = app.options.getValue('textmodeApiBaseUrl');
+		stripMode = app.options.getValue('textmodeStripApiSelfLinksMode');
+	});
+
+	app.converter.on(Converter.EVENT_RESOLVE_END, (context) => {
+		const reflections = context.project.getReflectionsByKind(ReflectionKind.All);
+
+		for (const reflection of reflections) {
+			stripReflectionHostedApiSeeTags(reflection);
+		}
+	});
+
+	app.renderer.on(MarkdownPageEvent.END, (page) => {
+		if (!page.contents) {
+			return;
+		}
+
+		page.contents = stripHostedApiMarkdownLinks(page.contents);
+	});
+
+	app.logger.verbose('[typedoc] Registered hosted API self-link stripper');
+}