@textmode/tooling-scripts 0.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@textmode/tooling-scripts",
+	"version": "0.1.0",
+	"type": "module",
+	"exports": {
+		"./config": "./src/config/create-config.mjs",
+		"./typedoc-plugins/accessor-docs-normalizer/index.js": "./src/typedoc-plugins/accessor-docs-normalizer/index.js",
+		"./typedoc-plugins/all-member-pages-router/index.js": "./src/typedoc-plugins/all-member-pages-router/index.js",
+		"./typedoc-plugins/api-frontmatter/index.js": "./src/typedoc-plugins/api-frontmatter/index.js",
+		"./typedoc-plugins/include-code-examples/index.js": "./src/typedoc-plugins/include-code-examples/index.js",
+		"./typedoc-plugins/strip-api-self-links/index.js": "./src/typedoc-plugins/strip-api-self-links/index.js"
+	},
+	"bin": {
+		"install-husky": "src/cli/install-husky.mjs",
+		"check-deps": "src/cli/check-deps.mjs",
+		"textmode-add-api-links": "src/scripts/add-api-doc-links.mjs",
+		"textmode-check-api-docs": "src/scripts/check-public-api-docs.mjs",
+		"textmode-check-examples": "src/scripts/check-examples.mjs"
+	},
+	"files": [
+		"src",
+		"policy.json"
+	],
+	"peerDependencies": {
+		"husky": ">=9",
+		"typedoc": ">=0.28",
+		"typedoc-plugin-markdown": ">=4.11",
+		"typescript": ">=5.9"
+	},
+	"devDependencies": {
+		"typedoc": "^0.28.19",
+		"typedoc-plugin-markdown": "^4.11.0",
+		"typescript": "^5.9.2"
+	},
+	"scripts": {
+		"check": "node --check src/cli/check-deps.mjs && node --check src/scripts/check-examples.mjs",
+		"lint": "node --check src/cli/check-deps.mjs",
+		"test": "vitest run"
+	}
+}

package/policy.json

@@ -0,0 +1,29 @@
+{
+	"dependencies": {
+		"@semantic-release/commit-analyzer": "^13.0.1",
+		"@semantic-release/exec": "^7.1.0",
+		"@semantic-release/git": "^10.0.1",
+		"@semantic-release/github": "^12.0.6",
+		"@semantic-release/npm": "^13.1.5",
+		"@semantic-release/release-notes-generator": "^14.1.0",
+		"@vitest/coverage-v8": "^3.2.4",
+		"@vitest/ui": "^3.1.2",
+		"eslint": "^9.39.2",
+		"eslint-plugin-jsdoc": "^62.9.0",
+		"globals": "^17.5.0",
+		"jsdom": "^27.4.0",
+		"prettier": "^3.8.3",
+		"semantic-release": "^25.0.3",
+		"typedoc": "^0.28.19",
+		"typedoc-plugin-frontmatter": "^1.3.1",
+		"typedoc-plugin-markdown": "^4.11.0",
+		"typedoc-vitepress-theme": "^1.1.2",
+		"typescript": "^5.9.2",
+		"typescript-eslint": "^8.59.0",
+		"vite": "^6.3.4",
+		"vitest": "^3.1.2"
+	},
+	"peerDependencies": {
+		"textmode.js": ">=0.16.0"
+	}
+}

package/src/cli/check-deps.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const policyPath = path.join(packageDir, 'policy.json');
+
+function readJson(filePath) {
+	return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function getPackageVersion(packageJson, section, dependencyName) {
+	return packageJson[section]?.[dependencyName];
+}
+
+function collectIssues(packageJson, policy) {
+	const issues = [];
+	const dependencySections = ['dependencies', 'devDependencies', 'optionalDependencies'];
+
+	for (const [dependencyName, expectedRange] of Object.entries(policy.dependencies ?? {})) {
+		const actual = dependencySections
+			.map((section) => [section, getPackageVersion(packageJson, section, dependencyName)])
+			.find(([, version]) => version !== undefined);
+
+		if (!actual) {
+			continue;
+		}
+
+		const [section, version] = actual;
+		if (version !== expectedRange) {
+			issues.push(`${section}.${dependencyName} must be ${expectedRange}, found ${version}.`);
+		}
+	}
+
+	for (const [dependencyName, expectedRange] of Object.entries(policy.peerDependencies ?? {})) {
+		const version = getPackageVersion(packageJson, 'peerDependencies', dependencyName);
+		if (version !== undefined && version !== expectedRange) {
+			issues.push(`peerDependencies.${dependencyName} must be ${expectedRange}, found ${version}.`);
+		}
+	}
+
+	return issues;
+}
+
+const packageJsonPath = path.resolve(process.cwd(), 'package.json');
+const packageJson = readJson(packageJsonPath);
+const policy = readJson(policyPath);
+const issues = collectIssues(packageJson, policy);
+
+if (issues.length === 0) {
+	console.log('Dependency policy check passed.');
+} else {
+	console.error('Dependency policy check failed:');
+	for (const issue of issues) {
+		console.error(`- ${issue}`);
+	}
+	process.exitCode = 1;
+}

package/src/cli/install-husky.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const sourceDir = path.join(packageDir, 'src/husky');
+const targetDir = path.resolve(process.cwd(), '.husky');
+
+fs.mkdirSync(targetDir, { recursive: true });
+
+for (const hookName of fs.readdirSync(sourceDir)) {
+	const sourcePath = path.join(sourceDir, hookName);
+	const targetPath = path.join(targetDir, hookName);
+
+	if (!fs.statSync(sourcePath).isFile()) {
+		continue;
+	}
+
+	fs.copyFileSync(sourcePath, targetPath);
+	fs.chmodSync(targetPath, 0o755);
+}

package/src/config/create-config.mjs

@@ -0,0 +1,75 @@
+import path from 'node:path';
+
+const DEFAULT_TARGET_KINDS =
+	128 | // ReflectionKind.Class
+	256 | // ReflectionKind.Interface
+	2097152 | // ReflectionKind.TypeAlias
+	8 | // ReflectionKind.Enum
+	32 | // ReflectionKind.Variable
+	64 | // ReflectionKind.Function
+	2048 | // ReflectionKind.Method
+	262144 | // ReflectionKind.Accessor
+	1024; // ReflectionKind.Property
+
+const DEFAULT_EXAMPLE_TARGET_KINDS = 64 | 2048;
+const DEFAULT_ACCESSOR_TARGET_KIND = 262144;
+
+function sourceRootsForEntryPoints(entryPoints) {
+	return Array.from(
+		new Set(
+			entryPoints.map((entryPoint) => {
+				const firstSegment = entryPoint.path.split(/[\\/]/)[0];
+				return path.resolve(firstSegment);
+			})
+		)
+	);
+}
+
+export function createConfig({
+	apiBaseUrl,
+	apiDocsDir,
+	checkExampleGallerySourceBase = true,
+	checkExampleSketches,
+	docstringTargetKinds,
+	docstringTargetKindsWithAccessors,
+	entryPoints,
+	exampleTargetKinds,
+	exampleTargetKindsWithAccessors,
+	packageName,
+	sourceRoots,
+	targetKinds = DEFAULT_TARGET_KINDS,
+}) {
+	if (!packageName) {
+		throw new Error('textmode tooling config requires packageName.');
+	}
+	if (!apiBaseUrl) {
+		throw new Error('textmode tooling config requires apiBaseUrl.');
+	}
+	if (!Array.isArray(entryPoints) || entryPoints.length === 0) {
+		throw new Error('textmode tooling config requires at least one entry point.');
+	}
+
+	const primaryEntryPoint = entryPoints[0];
+	const resolvedExampleTargetKinds = exampleTargetKinds ?? DEFAULT_EXAMPLE_TARGET_KINDS;
+	const resolvedExampleTargetKindsWithAccessors =
+		exampleTargetKindsWithAccessors ?? (resolvedExampleTargetKinds | DEFAULT_ACCESSOR_TARGET_KIND);
+	const resolvedDocstringTargetKinds = docstringTargetKinds ?? resolvedExampleTargetKinds;
+	const resolvedDocstringTargetKindsWithAccessors =
+		docstringTargetKindsWithAccessors ?? resolvedExampleTargetKindsWithAccessors;
+
+	return {
+		API_BASE_URL: apiBaseUrl,
+		API_DOCS_DIR: path.resolve(apiDocsDir ?? `api/${packageName}`),
+		CHECK_EXAMPLE_GALLERY_SOURCE_BASE: checkExampleGallerySourceBase,
+		CHECK_EXAMPLE_SKETCHES: Boolean(checkExampleSketches),
+		DOCSTRING_TARGET_KINDS: resolvedDocstringTargetKinds,
+		DOCSTRING_TARGET_KINDS_WITH_ACCESSORS: resolvedDocstringTargetKindsWithAccessors,
+		ENTRY_POINT: primaryEntryPoint.path,
+		ENTRY_POINTS: entryPoints,
+		EXAMPLE_TARGET_KINDS: resolvedExampleTargetKinds,
+		EXAMPLE_TARGET_KINDS_WITH_ACCESSORS: resolvedExampleTargetKindsWithAccessors,
+		PACKAGE_LABEL: packageName,
+		SOURCE_ROOTS: sourceRoots ?? sourceRootsForEntryPoints(entryPoints),
+		TARGET_KINDS: targetKinds,
+	};
+}

package/src/husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit "$1"

package/src/husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/src/husky/pre-push

@@ -0,0 +1,6 @@
+branch="$(git rev-parse --abbrev-ref HEAD)"
+
+if [ "$branch" = "dev" ] || [ "$branch" = "beta" ] || [ "$branch" = "main" ]; then
+  echo "Direct pushes to '$branch' are not allowed. Open a pull request to dev, then promote dev -> beta -> main."
+  exit 1
+fi

package/src/scripts/add-api-doc-links.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import process from 'node:process';
+
+import { API_BASE_URL, API_DOCS_DIR, ENTRY_POINTS, SOURCE_ROOTS, TARGET_KINDS } from './lib/api-doc-links-config.mjs';
+import { createApiLinkTargets } from './lib/api-doc-checks.mjs';
+import { readMarkdownRoutes } from './lib/api-doc-routes.mjs';
+import { findJsdocBeforeLine, getLineStartOffsets, upsertSeeLine } from './lib/jsdoc-comments.mjs';
+import {
+	getIncludedReflections,
+	shouldProcessEntryPointReflection,
+	sourceIsInRoots,
+} from './lib/reflection-policy.mjs';
+import { loadTypeDocProject } from './lib/typedoc-project.mjs';
+
+async function collectPendingEdits(routes) {
+	const pendingByFile = new Map();
+
+	for (const entryPoint of ENTRY_POINTS) {
+		const project = await loadTypeDocProject({
+			entryPoint: entryPoint.path,
+			tsconfig: entryPoint.tsconfig,
+		});
+		const reflections = getIncludedReflections(project, TARGET_KINDS);
+
+		for (const reflection of reflections) {
+			if (!shouldProcessEntryPointReflection(entryPoint, reflection)) {
+				continue;
+			}
+
+			for (const target of createApiLinkTargets(reflection, routes, API_BASE_URL)) {
+				if (!target.source?.line || !sourceIsInRoots(target.source, SOURCE_ROOTS)) {
+					continue;
+				}
+
+				const entries = pendingByFile.get(target.source.fullFileName) ?? [];
+				entries.push({ line: target.source.line, seeLine: target.seeLine });
+				pendingByFile.set(target.source.fullFileName, entries);
+			}
+		}
+	}
+
+	return pendingByFile;
+}
+
+function applyPendingEdits(pendingByFile) {
+	let changedFiles = 0;
+	let insertedLinks = 0;
+
+	for (const [fileName, entries] of pendingByFile) {
+		const originalText = fs.readFileSync(fileName, 'utf8');
+		let text = originalText;
+		const uniqueEntries = Array.from(
+			new Map(entries.map((entry) => [`${entry.line}\0${entry.seeLine}`, entry])).values()
+		);
+
+		for (const entry of uniqueEntries.sort((left, right) => right.line - left.line)) {
+			const before = text;
+			const lineStarts = getLineStartOffsets(text);
+			const comment = findJsdocBeforeLine(text, lineStarts, entry.line);
+			if (!comment) {
+				continue;
+			}
+
+			text = upsertSeeLine(text, comment, entry.seeLine, API_BASE_URL);
+			if (text !== before) {
+				insertedLinks += 1;
+			}
+		}
+
+		if (text !== originalText) {
+			fs.writeFileSync(fileName, text);
+			changedFiles += 1;
+		}
+	}
+
+	return { changedFiles, insertedLinks };
+}
+
+async function main() {
+	const routes = readMarkdownRoutes(API_DOCS_DIR);
+	const pendingByFile = await collectPendingEdits(routes);
+	const { changedFiles, insertedLinks } = applyPendingEdits(pendingByFile);
+
+	console.log(`Inserted ${insertedLinks} API reference link(s) in ${changedFiles} file(s).`);
+}
+
+await main().catch((error) => {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+});

package/src/scripts/check-examples.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+
+import { CHECK_EXAMPLE_SKETCHES, PACKAGE_LABEL } from './lib/api-doc-links-config.mjs';
+import {
+	checkSketch,
+	EXAMPLES_MANIFEST,
+	getManifestExamples,
+	readExamplesIndex,
+	readExamplesManifest,
+	validateExamplesGallery,
+	validateExamplesManifest,
+} from './lib/example-checks.mjs';
+import { renderList } from './lib/reporting.mjs';
+
+async function main() {
+	try {
+		console.log(`Checking ${PACKAGE_LABEL} example sketches...`);
+		const indexContent = readExamplesIndex();
+		const manifest = readExamplesManifest();
+		const galleryIssues = validateExamplesGallery(indexContent);
+		const manifestIssues = validateExamplesManifest(manifest);
+		const validationIssues = [...galleryIssues, ...manifestIssues];
+
+		if (validationIssues.length > 0) {
+			renderList('Examples validation failed:', validationIssues);
+			process.exitCode = 1;
+			return;
+		}
+
+		const files = getManifestExamples(manifest).map((example) => example.sourceFile);
+		console.log(`Found ${files.length} manifest examples from ${EXAMPLES_MANIFEST}.`);
+
+		if (!CHECK_EXAMPLE_SKETCHES) {
+			console.log('Sketch convention checks are disabled for this package.');
+			return;
+		}
+
+		let passedCount = 0;
+		let failedCount = 0;
+		let skippedCount = 0;
+		const failures = [];
+
+		for (const file of files) {
+			const { skipped, issues } = checkSketch(file);
+			if (skipped) {
+				skippedCount += 1;
+				continue;
+			}
+
+			if (issues.length === 0) {
+				passedCount += 1;
+			} else {
+				failedCount += 1;
+				failures.push({ file, issues });
+			}
+		}
+
+		console.log(`\nResults: ${passedCount} passed, ${failedCount} failed, ${skippedCount} skipped.\n`);
+
+		if (failures.length > 0) {
+			console.error('Validation failed for the following sketches:');
+			for (const failure of failures) {
+				console.error(`\n- ${failure.file}:`);
+				for (const issue of failure.issues) {
+					console.error(`  * ${issue}`);
+				}
+			}
+			process.exitCode = 1;
+		} else {
+			console.log('All checked sketches meet the requirements successfully.');
+		}
+	} catch (error) {
+		console.error('Error running examples check:');
+		console.error(error instanceof Error ? error.stack : String(error));
+		process.exitCode = 2;
+	}
+}
+
+await main();

package/src/scripts/check-public-api-docs.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+
+import { ReflectionKind } from 'typedoc';
+
+import {
+	API_BASE_URL,
+	API_DOCS_DIR,
+	DOCSTRING_TARGET_KINDS,
+	DOCSTRING_TARGET_KINDS_WITH_ACCESSORS,
+	ENTRY_POINT,
+	EXAMPLE_TARGET_KINDS,
+	EXAMPLE_TARGET_KINDS_WITH_ACCESSORS,
+	TARGET_KINDS,
+} from './lib/api-doc-links-config.mjs';
+import { collectApiDocIssues, countApiDocIssues } from './lib/api-doc-checks.mjs';
+import { readOrGenerateMarkdownRoutes } from './lib/api-doc-routes.mjs';
+import { getIncludedReflections } from './lib/reflection-policy.mjs';
+import { renderIssueSection } from './lib/reporting.mjs';
+import { loadTypeDocProject } from './lib/typedoc-project.mjs';
+
+function parseOptions(argv) {
+	return {
+		help: argv.includes('--help') || argv.includes('-h'),
+		includeAccessors: argv.includes('--include-accessors'),
+	};
+}
+
+function getTargetKinds(options) {
+	if (!options.includeAccessors) {
+		return {
+			docstringTargetKinds: DOCSTRING_TARGET_KINDS,
+			exampleTargetKinds: EXAMPLE_TARGET_KINDS,
+		};
+	}
+
+	return {
+		docstringTargetKinds: DOCSTRING_TARGET_KINDS_WITH_ACCESSORS,
+		exampleTargetKinds: EXAMPLE_TARGET_KINDS_WITH_ACCESSORS,
+	};
+}
+
+function exampleScopeLabel(targetKinds) {
+	return targetKinds & ReflectionKind.Accessor
+		? 'exported functions, methods, and accessors'
+		: 'exported functions and methods';
+}
+
+function printHelp() {
+	console.log('Usage: node ./scripts/check-public-api-docs.mjs [--include-accessors]');
+	console.log('');
+	console.log(`Checks the documented public API reachable from ${ENTRY_POINT}.`);
+	console.log('Skips private/protected/inherited members and any API path segment starting with "_".');
+	console.log('Requires public API JSDoc comments to link to their code.textmode.art API reference.');
+	console.log('Also requires at least one @example tag for configured example target kinds.');
+	console.log('');
+	console.log('Options:');
+	console.log('  --include-accessors  Include accessors/getters when the repository config supports it.');
+}
+
+async function main() {
+	try {
+		const options = parseOptions(process.argv.slice(2));
+
+		if (options.help) {
+			printHelp();
+			return;
+		}
+
+		const routes = await readOrGenerateMarkdownRoutes(API_DOCS_DIR);
+		const { docstringTargetKinds, exampleTargetKinds } = getTargetKinds(options);
+		const project = await loadTypeDocProject({
+			entryPoint: ENTRY_POINT,
+			tsconfig: ENTRY_POINT.startsWith('typedoc-entrypoints/') ? 'tsconfig.typedoc.json' : 'tsconfig.json',
+			errorMessage: 'TypeDoc failed to resolve the public API surface.',
+		});
+		const apiLinkReflections = getIncludedReflections(project, TARGET_KINDS);
+		const docstringReflections = getIncludedReflections(project, docstringTargetKinds);
+		const exampleReflections = getIncludedReflections(project, exampleTargetKinds);
+		const scopeLabel = exampleScopeLabel(exampleTargetKinds);
+		const issues = collectApiDocIssues({
+			apiBaseUrl: API_BASE_URL,
+			apiLinkReflections,
+			docstringReflections,
+			exampleReflections,
+			routes,
+		});
+		const issueCount = countApiDocIssues(issues);
+
+		if (issueCount === 0) {
+			console.log('Public API documentation check passed.');
+			console.log(
+				`Scanned ${docstringReflections.length} documented public API reflections from ${ENTRY_POINT}.`
+			);
+			console.log('Policy: skip private/protected/inherited members and any API path segment starting with "_".');
+			console.log('Every included API item has a JSDoc docstring and a valid code.textmode.art API link.');
+			console.log(`Every included ${scopeLabel} has at least one @example tag.`);
+			if (!options.includeAccessors && EXAMPLE_TARGET_KINDS_WITH_ACCESSORS !== EXAMPLE_TARGET_KINDS) {
+				console.log('Accessors are excluded by default. Re-run with --include-accessors to check them too.');
+			}
+			return;
+		}
+
+		console.error('Public API documentation check failed.');
+		console.error(`Scanned ${docstringReflections.length} documented public API reflections from ${ENTRY_POINT}.`);
+		console.error('Policy: skip private/protected/inherited members and any API path segment starting with "_".');
+		console.error(
+			`Found ${issueCount} issue(s): ${issues.missingDocstrings.length} missing docstring, ${issues.missingExamples.length} missing @example, ${issues.missingApiLinks.length} missing API link, ${issues.invalidApiLinks.length} invalid API link.`
+		);
+		if (!options.includeAccessors && EXAMPLE_TARGET_KINDS_WITH_ACCESSORS !== EXAMPLE_TARGET_KINDS) {
+			console.error('Accessors are excluded by default. Re-run with --include-accessors to check them too.');
+		}
+
+		renderIssueSection('Missing JSDoc docstring', issues.missingDocstrings);
+		renderIssueSection('Missing @example tag', issues.missingExamples);
+		renderIssueSection('Missing code.textmode.art API link', issues.missingApiLinks);
+		renderIssueSection('Invalid code.textmode.art API link', issues.invalidApiLinks);
+
+		process.exitCode = 1;
+	} catch (error) {
+		console.error('Public API documentation check could not complete.');
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 2;
+	}
+}
+
+await main();