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,183 @@
+<!--
+
+@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`). 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 automatically resolving the corresponding implementation via the nearest `package.json` file.
+
+**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;
+
+export = add;
+```
+
+**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;
+
+export = add;
+```
+
+</section>
+
+<!-- /.usage -->
+
+<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 class="notes">
+
+## Notes
+
+-   The rule automatically resolves the implementation path by traversing up the directory tree to find the nearest `package.json` file 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` extension.
+
+</section>
+
+<!-- /.notes -->
+
+<!-- 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
+		}
+	]
+*/