build: add ESLint rule to enforce empty lines between requires and code

etc/eslint/rules/stdlib.js

@@ -1,3 +1,5 @@
+/* eslint-disable stdlib/jsdoc-doctest-marker, stdlib/jsdoc-doctest, stdlib/jsdoc-example-require-spacing, stdlib/jsdoc-no-tabs */
+
 /**
 * @license Apache-2.0
 *
@@ -16,8 +18,6 @@
 * limitations under the License.
 */
 
-/* eslint-disable stdlib/jsdoc-doctest-marker, stdlib/jsdoc-doctest */
-
 'use strict';
 
 /**
@@ -838,6 +838,49 @@
 */
 rules[ 'stdlib/jsdoc-empty-line-before-example' ] = 'error';
 
+/**
+* Enforce empty lines between requires and code in JSDoc examples.
+*
+* @name jsdoc-example-require-spacing
+* @memberof rules
+* @type {string}
+* @default 'error'
+*
+* @example
+* // Bad...
+*
+* /**
+* * Fréchet distribution constructor.
+* *
+* * @module @stdlib/stats/base/dists/frechet/ctor
+* *
+* * @example
+* * var Frechet = require( '@stdlib/stats/base/dists/frechet/ctor' );
+* * var frechet = new Frechet( 1.0, 1.0, 0.5 );
+* *
+* * var y = frechet.cdf( 0.8 );
+* * // returns ~0.036
+* *\/
+*
+* @example
+* // Good...
+*
+* /**
+* * Fréchet distribution constructor.
+* *
+* * @module @stdlib/stats/base/dists/frechet/ctor
+* *
+* * @example
+* * var Frechet = require( '@stdlib/stats/base/dists/frechet/ctor' );
+* *
+* * var frechet = new Frechet( 1.0, 1.0, 0.5 );
+* *
+* * var y = frechet.cdf( 0.8 );
+* * // returns ~0.036
+* *\/
+*/
+rules[ 'stdlib/jsdoc-example-require-spacing' ] = 'error';
+
 /**
 * Require `\`` be used as the fenced code marker.
 *

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

@@ -0,0 +1,159 @@
+<!--
+
+@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.
+
+-->
+
+# jsdoc-example-require-spacing
+
+> [ESLint rule][eslint-rules] to enforce empty lines between `require` statements and code in JSDoc examples.
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing' );
+```
+
+#### rule
+
+[ESLint rule][eslint-rules] to enforce empty lines between `require` statements and code in JSDoc examples.
+
+**Bad**:
+
+<!-- eslint stdlib/jsdoc-example-require-spacing: "off", @cspell/spellchecker: "off" -->
+
+```javascript
+/**
+* Fréchet distribution constructor.
+*
+* @module @stdlib/stats/base/dists/frechet/ctor
+*
+* @example
+* var Frechet = require( '@stdlib/stats/base/dists/frechet/ctor' );
+* var frechet = new Frechet( 1.0, 1.0, 0.5 );
+*
+* var y = frechet.cdf( 0.8 );
+* // returns ~0.036
+*/
+```
+
+**Good**:
+
+<!-- eslint @cspell/spellchecker: "off" -->
+
+```javascript
+/**
+* Fréchet distribution constructor.
+*
+* @module @stdlib/stats/base/dists/frechet/ctor
+*
+* @example
+* var Frechet = require( '@stdlib/stats/base/dists/frechet/ctor' );
+*
+* var frechet = new Frechet( 1.0, 1.0, 0.5 );
+*
+* var y = frechet.cdf( 0.8 );
+* // returns ~0.036
+*/
+```
+
+</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-require-spacing' );
+
+var linter = new Linter();
+var result;
+var code;
+
+code = [
+    '/**',
+    '* Fréchet distribution constructor.',
+    '*',
+    '* @module @stdlib/stats/base/dists/frechet/ctor',
+    '*',
+    '* @example',
+    '* var Frechet = require( \'@stdlib/stats/base/dists/frechet/ctor\' );',
+    '* var frechet = new Frechet( 1.0, 1.0, 0.5 );',
+    '*',
+    '* var y = frechet.cdf( 0.8 );',
+    '* // returns ~0.036',
+    '*/',
+    'function Frechet() {}'
+].join( '\n' );
+
+linter.defineRule( 'jsdoc-example-require-spacing', rule );
+
+result = linter.verify( code, {
+    'rules': {
+        'jsdoc-example-require-spacing': 'error'
+    }
+});
+/* returns
+    [
+        {
+            'ruleId': 'jsdoc-example-require-spacing',
+            'severity': 2,
+            'message': 'Missing empty line between require statement and code',
+            'line': 13,
+            'column': 1,
+            'nodeType': 'FunctionDeclaration',
+            'endLine': 13,
+            'endColumn': 21
+        }
+    ]
+*/
+```
+
+</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-require-spacing/examples/index.js

@@ -0,0 +1,75 @@
+/**
+* @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 rule = require( './../lib' );
+
+var linter = new Linter();
+
+// Valid example with empty line after require:
+var valid = [
+	'/**',
+	'* Fréchet distribution constructor.',
+	'*',
+	'* @example',
+	'* var Frechet = require( \'@stdlib/stats/base/dists/frechet/ctor\' );',
+	'*',
+	'* var frechet = new Frechet( 1.0, 1.0, 0.5 );',
+	'*',
+	'* var y = frechet.cdf( 0.8 );',
+	'* // returns ~0.036',
+	'*/',
+	'function Frechet() {}'
+].join( '\n' );
+
+// Invalid example without empty line after require:
+var invalid = [
+	'/**',
+	'* Fréchet distribution constructor.',
+	'*',
+	'* @example',
+	'* var Frechet = require( \'@stdlib/stats/base/dists/frechet/ctor\' );',
+	'* var frechet = new Frechet( 1.0, 1.0, 0.5 );',
+	'*',
+	'* var y = frechet.cdf( 0.8 );',
+	'* // returns ~0.036',
+	'*/',
+	'function Frechet() {}'
+].join( '\n' );
+
+// Register the rule:
+linter.defineRule( 'jsdoc-example-require-spacing', rule );
+
+// Lint the valid example:
+var validResult = linter.verify( valid, {
+	'rules': {
+		'jsdoc-example-require-spacing': 'error'
+	}
+});
+console.log( 'Valid example - Number of errors: %d', validResult.length );
+
+// Lint the invalid example:
+var invalidResult = linter.verify( invalid, {
+	'rules': {
+		'jsdoc-example-require-spacing': 'error'
+	}
+});
+console.log( 'Invalid example - Number of errors: %d', invalidResult.length );
+console.log( 'Error message: %s', invalidResult[ 0 ].message );

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

@@ -0,0 +1,45 @@
+/**
+* @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';
+
+// MODULES //
+
+var rule = require( './main.js' );
+
+
+// MAIN //
+
+/**
+* ESLint rule to enforce empty lines between `require` statements and code in JSDoc examples.
+*
+* @module @stdlib/_tools/eslint/rules/jsdoc-example-require-spacing
+*
+* @example
+* var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing' );
+*
+* var config = {
+*     'rules': {
+*         'stdlib/jsdoc-example-require-spacing': 'error'
+*     }
+* };
+*/
+
+// EXPORTS //
+
+module.exports = rule;