build: add tsdoc-doctest ESLint rule

etc/eslint/plugins/typescript.js

@@ -30,7 +30,10 @@ var plugins = [
 	'eslint-plugin-jsdoc',
 
 	// Required for TypeScript support:
-	'@typescript-eslint'
+	'@typescript-eslint',
+
+	// Custom stdlib rules:
+	'stdlib'
 ];
 
 

etc/eslint/rules/typescript.js

@@ -2712,6 +2712,17 @@ rules[ 'yoda' ] = 'error';
 */
 rules[ 'expect-type/expect' ] = 'error';
 
+/**
+* Ensures return annotations in TSDoc examples match the actual output.
+*
+* @name stdlib/tsdoc-declarations-doctest
+* @memberof rules
+* @type {string}
+* @default 'error'
+* @see {@link module:@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest}
+*/
+rules[ 'stdlib/tsdoc-declarations-doctest' ] = 'error';
+
 
 // EXPORTS //
 

lib/node_modules/@stdlib/_tools/eslint/rules/lib/index.js

@@ -1071,6 +1071,15 @@ setReadOnly( rules, 'section-headers', require( '@stdlib/_tools/eslint/rules/sec
 */
 setReadOnly( rules, 'ternary-condition-parentheses', require( '@stdlib/_tools/eslint/rules/ternary-condition-parentheses' ) );
 
+/**
+* @name tsdoc-declarations-doctest
+* @memberof rules
+* @readonly
+* @type {Function}
+* @see {@link module:@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest}
+*/
+setReadOnly( rules, 'tsdoc-declarations-doctest', require( '@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest' ) );
+
 /**
 * @name uppercase-required-constants
 * @memberof rules

lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest/README.md

@@ -0,0 +1,180 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2025 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# tsdoc-declarations-doctest
+
+> [ESLint rule][eslint-rules] to ensure that return annotations in TSDoc examples match the actual output in TypeScript declaration files (`*.d.ts`).
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var rule = require( '@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest' );
+```
+
+#### rule
+
+[ESLint rule][eslint-rules] to ensure that return annotations in TSDoc examples match the actual output in TypeScript declaration files (`*.d.ts`).
+
+**Bad**:
+
+<!-- eslint-disable stdlib/tsdoc-declarations-doctest -->
+
+```typescript
+/**
+* Adds two numbers.
+*
+* @param x - first number
+* @param y - second number
+* @returns sum of x and y
+*
+* @example
+* var result = add( 2, 3 );
+* // returns 6
+*/
+declare function add( x: number, y: number ): number;
+```
+
+**Good**:
+
+```typescript
+/**
+* Adds two numbers.
+*
+* @param x - first number
+* @param y - second number
+* @returns sum of x and y
+*
+* @example
+* var result = add( 2, 3 );
+* // returns 5
+*/
+declare function add( x: number, y: number ): number;
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   Return annotations may start with `returns`, `throws`, or `=>`. `returns` follow variable declarations or assignment expressions, whereas `=>` follow expression-only forms including `console.log` calls.
+-   The rule validates `@example` blocks in TSDoc comments within `*.d.ts` files by resolving the corresponding implementation via the nearest `package.json` file in the same or a parent directory and using its `main` field.
+-   The rule skips validation if the `package.json` file cannot be found or if the resolved implementation cannot be loaded.
+-   Examples are executed in a sandboxed VM context with limited globals for security.
+-   This rule is specifically designed for TypeScript declaration files and will only process files with a `*.d.ts` filename extension.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var Linter = require( 'eslint' ).Linter;
+var parser = require( '@typescript-eslint/parser' );
+var rule = require( '@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest' );
+
+var linter = new Linter();
+
+// Register the TypeScript parser and ESLint rule:
+linter.defineParser( '@typescript-eslint/parser', parser );
+linter.defineRule( 'tsdoc-declarations-doctest', rule );
+
+// Generate our source code with incorrect return annotation:
+var code = [
+    '/**',
+    '* Returns the absolute value of a number.',
+    '*',
+    '* @param x - input value',
+    '* @returns absolute value',
+    '*',
+    '* @example',
+    '* var result = abs( -3 );',
+    '* // returns 2',
+    '*/',
+    'declare function abs( x: number ): number;',
+    '',
+    'export = abs;'
+].join( '\n' );
+
+// Lint the code:
+var result = linter.verify( code, {
+    'parser': '@typescript-eslint/parser',
+    'parserOptions': {
+        'ecmaVersion': 2018,
+        'sourceType': 'module'
+    },
+    'rules': {
+        'tsdoc-declarations-doctest': 'error'
+    }
+}, {
+    'filename': '/path/to/project/lib/node_modules/@stdlib/math/base/special/abs/docs/types/index.d.ts'
+});
+/* returns
+    [
+        {
+            'ruleId': 'tsdoc-declarations-doctest',
+            'severity': 2,
+            'message': 'Displayed return value is `2`, but expected `3` instead',
+            'line': 9,
+            'column': 1,
+            'nodeType': null,
+            'endLine': 10,
+            'endColumn': 37
+        }
+    ]
+*/
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[eslint-rules]: https://eslint.org/docs/developer-guide/working-with-rules
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest/examples/index.js

@@ -0,0 +1,76 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+var Linter = require( 'eslint' ).Linter;
+var parser = require( '@typescript-eslint/parser' );
+var rule = require( './../lib' );
+
+var linter = new Linter();
+
+// Register the TypeScript parser and ESLint rule:
+linter.defineParser( '@typescript-eslint/parser', parser );
+linter.defineRule( 'tsdoc-declarations-doctest', rule );
+
+// Generate our source code with incorrect return annotation:
+var code = [
+	'/**',
+	'* Returns the absolute value of a number.',
+	'*',
+	'* @param x - input value',
+	'* @returns absolute value',
+	'*',
+	'* @example',
+	'* var result = abs( -3 );',
+	'* // returns 2',
+	'*/',
+	'declare function abs( x: number ): number;',
+	'',
+	'export = abs;'
+].join( '\n' );
+
+// Lint the code:
+var result = linter.verify( code, {
+	'parser': '@typescript-eslint/parser',
+	'parserOptions': {
+		'ecmaVersion': 2018,
+		'sourceType': 'module'
+	},
+	'rules': {
+		'tsdoc-declarations-doctest': 'error'
+	}
+}, {
+	'filename': 'lib/node_modules/@stdlib/math/base/special/abs/docs/types/index.d.ts'
+});
+
+console.log( result );
+/* =>
+	[
+		{
+			'ruleId': 'tsdoc-declarations-doctest',
+			'severity': 2,
+			'message': 'Displayed return value is `2`, but expected `3` instead',
+			'line': 9,
+			'column': 1,
+			'nodeType': null,
+			'endLine': 10,
+			'endColumn': 37
+		}
+	]
+*/

lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest/lib/add_package_to_scope.js

@@ -0,0 +1,84 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// VARIABLES //
+
+// Regular expression to match function declarations such as "declare function abs( x: number ): number;" (captures function name):
+var RE_DECLARE_FUNCTION = /declare\s+function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*[<(]/;
+
+// Regular expression to match variable declarations such as "declare var someVar: SomeType;" (captures variable name):
+var RE_DECLARE_VAR = /declare\s+var\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/;
+
+// Regular expression to match class declarations such as "declare class Complex64Array {" (captures class name):
+var RE_DECLARE_CLASS = /declare\s+class\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s/;
+
+// Regular expression to match const declarations such as "declare const PI: number;" (captures constant name):
+var RE_DECLARE_CONST = /declare\s+const\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/;
+
+// Regular expression to match variable declarations with interface types such as "declare var ctor: Int32Vector;" (captures variable name and interface name):
+var RE_DECLARE_VAR_INTERFACE = /declare\s+var\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:\s*([A-Z][a-zA-Z0-9_$]*)/;
+
+
+// MAIN //
+
+/**
+* Adds a package export to the scope based on TypeScript declarations.
+*
+* @private
+* @param {Object} scope - VM scope object to add the package export to
+* @param {*} pkg - package export value to be added to scope
+* @param {string} sourceText - TypeScript declaration source text to parse for identifier names
+*/
+function addPackageToScope( scope, pkg, sourceText ) {
+	var interfaceMatch;
+	var namespaceMatch;
+	var pkgType;
+	var match;
+
+	pkgType = typeof pkg;
+	if ( pkgType === 'function' ) {
+		match = sourceText.match( RE_DECLARE_FUNCTION ) || sourceText.match( RE_DECLARE_VAR ) || sourceText.match( RE_DECLARE_CLASS ); // eslint-disable-line max-len
+		if ( match ) {
+			scope[ match[1] ] = pkg;
+		}
+		interfaceMatch = sourceText.match( RE_DECLARE_VAR_INTERFACE );
+		if ( interfaceMatch ) {
+			// Make the function available under both the variable and interface names:
+			scope[ interfaceMatch[1] ] = pkg; // e.g., ctor
+			scope[ interfaceMatch[2] ] = pkg; // e.g., Int32Vector
+		}
+	} else {
+		if ( pkgType === 'object' && pkg !== null ) {
+			namespaceMatch = sourceText.match( RE_DECLARE_VAR_INTERFACE );
+			if ( namespaceMatch ) {
+				scope[ namespaceMatch[1] ] = pkg;
+			}
+		}
+		match = sourceText.match( RE_DECLARE_CONST );
+		if ( match ) {
+			scope[ match[1] ] = pkg;
+		}
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = addPackageToScope;