Add lint rule to validate JSDoc codeblocks using TS compiler (#1265)

Author: som-sm

lint-rules/test-utils.js

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import {RuleTester} from 'eslint';
 import tsParser from '@typescript-eslint/parser';
+import dedent from 'dedent';
 
 export const createRuleTester = (overrides = {}) => {
 	const {
@@ -98,3 +99,168 @@ export const createTypeAwareRuleTester = (fixtureFiles, options = {}) => {
 		writeFixture,
 	};
 };
+
+export const dedenter = dedent.withOptions({alignValues: true});
+
+/**
+Returns the specified code in a fenced code block, with an optional language tag.
+
+@example
+```
+fence('type A = string;');
+// Returns:
+// ```
+// type A = string;
+// ```
+
+fence(`import {RemovePrefix} from 'type-fest';
+
+type A = RemovePrefix<'onChange', 'on'>;
+//=> 'Change'`, 'ts');
+// Returns:
+// ```ts
+// import {RemovePrefix} from 'type-fest';
+
+// type A = RemovePrefix<'onChange', 'on'>;
+// //=> 'Change'
+// ```
+```
+*/
+export const fence = (code, lang = '') =>
+	dedenter`
+		\`\`\`${lang}
+		${code}
+		\`\`\`
+	`;
+
+/**
+Returns the specified lines as a JSDoc comment, placing each specified line on a new line.
+
+@example
+```
+jsdoc('Some description.', 'Note: Some note.');
+// Returns:
+// /**
+// Some description.
+// Note: Some note.
+// *​/
+
+jsdoc('@example', '```\ntype A = string;\n```', '@category Test');
+// Returns;
+// /**
+// @example
+// ```
+// type A = string;
+// ```
+// @category Test
+// *​/
+```
+*/
+export const jsdoc = (...lines) =>
+	dedenter`
+		/**
+		${lines.join('\n')}
+		*/
+	`;
+
+/**
+Returns an exported type for each provided prefix, with each prefix placed directly above its corresponding type declaration.
+
+@example
+```
+exportType(
+	'// Some comment',
+	'type Test = string;',
+	'/**\nSome description.\nNote: Some note.\n*​/'
+);
+// Returns:
+// // Some comment
+// export type T0 = string;
+//
+// type Test = string;
+// export type T1 = string;
+//
+// /**
+// Some description.
+// Note: Some note.
+// *​/
+// export type T2 = string;
+*/
+export const exportType = (...prefixes) =>
+	prefixes
+		.map((doc, i) => dedenter`
+			${doc}
+			export type T${i} = string;
+		`)
+		.join('\n\n');
+
+/**
+Returns an exported "Options" object type containing a property for each specified prefix, with each prefix placed directly above its corresponding property declaration.
+
+@example
+```
+exportOption(
+	'// Some comment',
+	'type Test = string;',
+	'/**\nSome description.\nNote: Some note.\n*​/'
+);
+// Returns:
+// export type TOptions = {
+// 	// Some comment
+// 	p0: string;
+
+// 	test: string;
+// 	p1: string;
+
+// 	/**
+// 	Some description.
+// 	Note: Some note.
+// 	*​/
+// 	p2: string;
+// };
+```
+*/
+export const exportOption = (...prefixes) =>
+	dedenter`
+		export type TOptions = {
+			${prefixes
+				.map((doc, i) => dedenter`
+					${doc}
+					p${i}: string;
+				`)
+				.join('\n\n')}
+		};
+	`;
+
+/**
+Returns an exported type for each provided prefix, and an exported "Options" object type containing a property for each specified prefix, with each prefix placed directly above its corresponding declaration.
+
+@example
+```
+exportTypeAndOption('// Some comment', '/**\nSome JSDoc\n*​/');
+// Returns:
+// // Some comment
+// type T0 = string;
+
+// /**
+// Some JSDoc
+// *​/
+// type T1 = string;
+
+// type TOptions = {
+// 	// Some comment
+// 	p0: string;
+
+// 	/**
+// 	Some JSDoc
+// 	*​/
+// 	p1: string;
+// };
+```
+*/
+export const exportTypeAndOption = (...prefixes) =>
+	dedenter`
+		${exportType(...prefixes)}
+
+		${exportOption(...prefixes)}
+	`;

lint-rules/validate-jsdoc-codeblocks.js

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import ts from 'typescript';
+import {createFSBackedSystem, createVirtualTypeScriptEnvironment} from '@typescript/vfs';
+
+const CODEBLOCK_REGEX = /(?<openingFence>```(?:ts|typescript)?\n)(?<code>[\s\S]*?)```/g;
+const FILENAME = 'example-codeblock.ts';
+
+const compilerOptions = {
+	lib: ['lib.es2023.d.ts', 'lib.dom.d.ts', 'lib.dom.iterable.d.ts'],
+	target: ts.ScriptTarget.ESNext,
+	module: ts.ModuleKind.Node20,
+	moduleResolution: ts.ModuleResolutionKind.Node16,
+	strict: true,
+	noImplicitReturns: true,
+	noImplicitOverride: true,
+	noUnusedLocals: false, // This is intentionally disabled
+	noUnusedParameters: true,
+	noFallthroughCasesInSwitch: true,
+	noUncheckedIndexedAccess: true,
+	noPropertyAccessFromIndexSignature: true,
+	noUncheckedSideEffectImports: true,
+	useDefineForClassFields: true,
+	exactOptionalPropertyTypes: true,
+};
+
+const virtualFsMap = new Map();
+virtualFsMap.set(FILENAME, '// Can\'t be empty');
+
+const rootDir = path.join(import.meta.dirname, '..');
+const system = createFSBackedSystem(virtualFsMap, rootDir, ts);
+const env = createVirtualTypeScriptEnvironment(system, [FILENAME], ts, compilerOptions);
+
+export const validateJSDocCodeblocksRule = /** @type {const} */ ({
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Ensures JSDoc example codeblocks don\'t have errors',
+		},
+		messages: {
+			invalidCodeblock: '{{errorMessage}}',
+		},
+		schema: [],
+	},
+	defaultOptions: [],
+	create(context) {
+		const filename = context.filename.replaceAll('\\', '/');
+
+		// Skip internal files
+		if (filename.includes('/internal/')) {
+			return {};
+		}
+
+		return {
+			TSTypeAliasDeclaration(node) {
+				const {parent} = node;
+
+				// Skip if type is not exported or starts with an underscore (private/internal)
+				if (parent.type !== 'ExportNamedDeclaration' || node.id.name.startsWith('_')) {
+					return;
+				}
+
+				const previousNodes = [context.sourceCode.getTokenBefore(parent, {includeComments: true})];
+
+				// Handle JSDoc blocks for options
+				if (node.id.name.endsWith('Options') && node.typeAnnotation.type === 'TSTypeLiteral') {
+					for (const member of node.typeAnnotation.members) {
+						previousNodes.push(context.sourceCode.getTokenBefore(member, {includeComments: true}));
+					}
+				}
+
+				for (const previousNode of previousNodes) {
+					// Skip if previous node is not a JSDoc comment
+					if (!previousNode || previousNode.type !== 'Block' || !previousNode.value.startsWith('*')) {
+						continue;
+					}
+
+					const comment = previousNode.value;
+
+					for (const match of comment.matchAll(CODEBLOCK_REGEX)) {
+						const {code, openingFence} = match.groups ?? {};
+
+						// Skip empty code blocks
+						if (!code || !openingFence) {
+							continue;
+						}
+
+						const matchOffset = match.index + openingFence.length + 2; // Add `2` because `comment` doesn't include the starting `/*`
+						const codeStartIndex = previousNode.range[0] + matchOffset;
+
+						env.updateFile(FILENAME, code);
+						const syntacticDiagnostics = env.languageService.getSyntacticDiagnostics(FILENAME);
+						const semanticDiagnostics = env.languageService.getSemanticDiagnostics(FILENAME);
+						const diagnostics = syntacticDiagnostics.length > 0 ? syntacticDiagnostics : semanticDiagnostics; // Show semantic errors only if there are no syntactic errors
+
+						for (const diagnostic of diagnostics) {
+							// If diagnostic location is not available, report on the entire code block
+							const diagnosticStart = codeStartIndex + (diagnostic.start ?? 0);
+							const diagnosticEnd = diagnosticStart + (diagnostic.length ?? code.length);
+
+							context.report({
+								loc: {
+									start: context.sourceCode.getLocFromIndex(diagnosticStart),
+									end: context.sourceCode.getLocFromIndex(diagnosticEnd),
+								},
+								messageId: 'invalidCodeblock',
+								data: {
+									errorMessage: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'),
+								},
+							});
+						}
+					}
+				}
+			},
+		};
+	},
+});