feat: add jsdoc-example-eslint ESLint rule

etc/eslint/.eslintrc.overrides.js

@@ -16,15 +16,72 @@
 * limitations under the License.
 */
 
+/* eslint-disable vars-on-top, stdlib/empty-line-before-comment */
+
 'use strict';
 
 // MODULES //
 
 // FIXME: remove the next line and uncomment the subsequent line once all remark JSDoc ESLint rules are completed
 var copy = require( './../../lib/node_modules/@stdlib/utils/copy' );
-
 // var copy = require( './utils/copy.js' );
+var objectKeys = require( './../../lib/node_modules/@stdlib/utils/keys' );
 var defaults = require( './.eslintrc.js' );
+var examplesConfig = require( './.eslintrc.examples.js' );
+
+
+// VARIABLES //
+
+/**
+* List of rules to exclude when linting JSDoc code snippets because they are incompatible with code fragments extracted from JSDoc comments.
+*
+* @private
+* @type {Array}
+*/
+var JSDOC_SNIPPET_EXCLUDE = [
+	'no-undef',
+	'no-unused-vars',
+	'strict',
+	'no-var',
+	'eol-last',
+	'indent',
+	'no-restricted-syntax'
+];
+
+
+// FUNCTIONS //
+
+/**
+* Extracts built-in ESLint rules from a configuration object, filtering out plugin rules and rules listed in an exclusion list.
+*
+* @private
+* @param {Object} config - ESLint configuration object
+* @param {Array} exclude - rule names to exclude
+* @returns {Object} filtered rules object
+*/
+function extractSnippetRules( config, exclude ) {
+	var rules;
+	var keys;
+	var key;
+	var i;
+
+	rules = {};
+	keys = objectKeys( config.rules );
+	for ( i = 0; i < keys.length; i++ ) {
+		key = keys[ i ];
+
+		// Skip plugin rules (e.g., "stdlib/foo", "node/bar") since the Linter instance does not have them registered:
+		if ( key.indexOf( '/' ) !== -1 ) {
+			continue;
+		}
+		// Skip rules explicitly excluded as incompatible with code snippets:
+		if ( exclude.indexOf( key ) !== -1 ) {
+			continue;
+		}
+		rules[ key ] = config.rules[ key ];
+	}
+	return rules;
+}
 
 
 // MAIN //
@@ -45,6 +102,13 @@
 */
 eslint.overrides = require( './overrides' );
 
+/**
+* Configure JSDoc example linting using the examples ESLint config, with rules filtered for use on JSDoc code snippets.
+*/
+eslint.rules[ 'stdlib/jsdoc-example-eslint' ] = [ 'warn', {
+	'rules': extractSnippetRules( examplesConfig, JSDOC_SNIPPET_EXCLUDE )
+}];
+
 
 // EXPORTS //
 

etc/eslint/rules/stdlib.js

@@ -867,6 +867,38 @@
 */
 rules[ 'stdlib/jsdoc-empty-line-before-example' ] = 'error';
 
+/**
+* Lint JavaScript code in JSDoc example blocks using ESLint.
+*
+* @name jsdoc-example-eslint
+* @memberof rules
+* @type {string}
+* @default 'warn'
+*
+* @example
+* // Bad...
+*
+* /**
+* * Squares a number.
+* *
+* * @example
+* * var y = square( 3.0 )
+* *\/
+* function square( x ) {}
+*
+* @example
+* // Good...
+*
+* /**
+* * Squares a number.
+* *
+* * @example
+* * var y = square( 3.0 );
+* *\/
+* function square( x ) {}
+*/
+rules[ 'stdlib/jsdoc-example-eslint' ] = 'off';
+
 /**
 * Enforce empty lines between requires and code in JSDoc examples.
 *
@@ -879,7 +911,7 @@
 * // Bad...
 *
 * /**
 * * Fréchet distribution constructor.
 * *
 * * @module @stdlib/stats/base/dists/frechet/ctor
 * *
@@ -895,7 +927,7 @@
 * // Good...
 *
 * /**
 * * Fréchet distribution constructor.
 * *
 * * @module @stdlib/stats/base/dists/frechet/ctor
 * *

lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-eslint/README.md

@@ -0,0 +1,149 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2026 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.
+
+-->
+
+# jsdoc-example-eslint
+
+> [ESLint rule][eslint-rules] to lint JavaScript code in JSDoc example blocks.
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-example-eslint' );
+```
+
+#### rule
+
+[ESLint rule][eslint-rules] to lint JavaScript code in JSDoc example blocks. The rule extracts code from `@example` tags in JSDoc comments, lints it using a provided set of ESLint rules, and reports violations mapped back to the original source lines.
+
+The rule accepts an options object with a `rules` property specifying which ESLint rules to apply to the extracted example code.
+
+**Bad** (missing semicolon):
+
+<!-- eslint stdlib/jsdoc-example-eslint: "off", stdlib/jsdoc-doctest-marker: "off", valid-jsdoc: "off" -->
+
+```javascript
+/**
+* Squares a number.
+*
+* @example
+* var y = square( 3.0 )
+*/
+function square( x ) {
+    return x * x;
+}
+```
+
+**Good**:
+
+<!-- eslint valid-jsdoc: "off" -->
+
+```javascript
+/**
+* Squares a number.
+*
+* @example
+* var y = square( 3.0 );
+*/
+function square( x ) {
+    return x * x;
+}
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var Linter = require( 'eslint' ).Linter;
+var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-example-eslint' );
+
+var linter = new Linter();
+var code = [
+    '/**',
+    '* Squares a number.',
+    '*',
+    '* @example',
+    '* var y = square( 3.0 )',
+    '* // returns 9.0',
+    '*/',
+    'function square( x ) {',
+    '\treturn x * x;',
+    '}'
+].join( '\n' );
+
+linter.defineRule( 'jsdoc-example-eslint', rule );
+
+var result = linter.verify( code, {
+    'rules': {
+        'jsdoc-example-eslint': [ 'error', {
+            'rules': {
+                'semi': 'error'
+            }
+        }]
+    }
+});
+console.log( result );
+/* =>
+    [
+        {
+            'ruleId': 'jsdoc-example-eslint',
+            'severity': 2,
+            'message': 'Missing semicolon. (semi)',
+            ...
+        }
+    ]
+*/
+```
+
+</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/jsdoc-example-eslint/examples/index.js

@@ -0,0 +1,59 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 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 rule = require( './../lib' );
+
+var linter = new Linter();
+var code = [
+	'/**',
+	'* Squares a number.',
+	'*',
+	'* @example',
+	'* var y = square( 3.0 )',
+	'* // returns 9.0',
+	'*/',
+	'function square( x ) {',
+	'\treturn x * x;',
+	'}'
+].join( '\n' );
+
+linter.defineRule( 'jsdoc-example-eslint', rule );
+
+var result = linter.verify( code, {
+	'rules': {
+		'jsdoc-example-eslint': [ 'error', {
+			'rules': {
+				'semi': 'error'
+			}
+		}]
+	}
+});
+console.log( result );
+/* =>
+	[
+		{
+			'ruleId': 'jsdoc-example-eslint',
+			'severity': 2,
+			'message': 'Missing semicolon. (semi)',
+			...
+		}
+	]
+*/

lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-eslint/lib/index.js

@@ -0,0 +1,39 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 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';
+
+/**
+* ESLint rule to lint JavaScript code in JSDoc example blocks.
+*
+* @module @stdlib/_tools/eslint/rules/jsdoc-example-eslint
+*
+* @example
+* var main = require( '@stdlib/_tools/eslint/rules/jsdoc-example-eslint' );
+*
+* console.log( main );
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;