build: add ESLint rule to enforce that last require statement in JS examples is a relative path

etc/eslint/.eslintrc.examples.js

@@ -20,10 +20,10 @@
 
 // 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 defaults = require( './.eslintrc.js' );
 
 
@@ -92,6 +92,13 @@
 */
 eslint.rules[ 'stdlib/vars-order' ] = 'off';
 
+/**
+* Enforce that last require is a relative path.
+*
+* @private
+*/
+eslint.rules[ 'stdlib/require-last-path-relative' ] = 'error';
+
 
 // EXPORTS //
 

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

@@ -981,6 +981,15 @@ setReadOnly( rules, 'require-file-extensions', require( '@stdlib/_tools/eslint/r
 */
 setReadOnly( rules, 'require-globals', require( '@stdlib/_tools/eslint/rules/require-globals' ) );
 
+/**
+* @name require-last-path-relative
+* @memberof rules
+* @readonly
+* @type {Function}
+* @see {@link module:@stdlib/_tools/eslint/rules/require-last-path-relative}
+*/
+setReadOnly( rules, 'require-last-path-relative', require( '@stdlib/_tools/eslint/rules/require-last-path-relative' ) );
+
 /**
 * @name require-leading-slash
 * @memberof rules

lib/node_modules/@stdlib/_tools/eslint/rules/require-last-path-relative/README.md

@@ -0,0 +1,126 @@
+<!--
+
+@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.
+
+-->
+
+# require-last-path-relative
+
+> [ESLint rule][eslint-rules] enforcing that the last `require` statement is a relative path.
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var rule = require( '@stdlib/_tools/eslint/rules/require-last-path-relative' );
+```
+
+#### rule
+
+[ESLint rule][eslint-rules] enforcing that the last `require` statement is a relative path.
+
+**Bad**:
+
+```javascript
+var zip = require( '@stdlib/utils/zip' );
+var unzip = require( '@stdlib/utils/unzip' );
+```
+
+**Good**:
+
+<!-- eslint stdlib/require-file-extensions: "off" -->
+
+```javascript
+var zip = require( '@stdlib/utils/zip' );
+var unzip = require( './../lib' );
+```
+
+The rule is mainly for `examples` files to help make explicit that the API being demonstrated belongs to the respective package.
+
+</section>
+
+<!-- /.usage -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var Linter = require( 'eslint' ).Linter;
+var rule = require( '@stdlib/_tools/eslint/rules/require-last-path-relative' );
+
+var linter = new Linter();
+var result;
+
+var code = [
+    'var beep = require( \'@stdlib/boop/beep\' );',
+    'var foo = require( \'@stdlib/bar/foo\' );'
+].join( '\n' );
+
+linter.defineRule( 'require-last-path-relative', rule );
+
+result = linter.verify( code, {
+    'rules': {
+        'require-last-path-relative-relative': 'error'
+    }
+});
+/* returns
+    [
+        {
+            'ruleId': 'require-last-path-relative',
+            'severity': 2,
+            'message': 'Last `require` statement must be a relative path',
+            'line': 2,
+            'column': 11,
+            'nodeType': 'CallExpression',
+            'endLine': 2,
+            'endColumn': 39
+        }
+    ]
+*/
+```
+
+</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/require-last-path-relative/examples/index.js

@@ -0,0 +1,52 @@
+/**
+* @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();
+
+var code = [
+	'var beep = require( \'@stdlib/boop/beep\' );',
+	'var foo = require( \'@stdlib/bar/foo\' );'
+].join( '\n' );
+
+linter.defineRule( 'require-last-path-relative', rule );
+
+var result = linter.verify( code, {
+	'rules': {
+		'require-last-path-relative': 'error'
+	}
+});
+console.log( result );
+/* =>
+	[
+		{
+			'ruleId': 'require-last-path-relative',
+			'severity': 2,
+			'message': 'Last `require` statement must be a relative path',
+			'line': 2,
+			'column': 11,
+			'nodeType': 'CallExpression',
+			'endLine': 2,
+			'endColumn': 39
+		}
+	]
+*/

lib/node_modules/@stdlib/_tools/eslint/rules/require-last-path-relative/lib/index.js

@@ -0,0 +1,39 @@
+/**
+* @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';
+
+/**
+* ESLint rule to enforce that the last `require` statement is a relative path.
+*
+* @module @stdlib/_tools/eslint/rules/require-last-path-relative
+*
+* @example
+* var rule = require( '@stdlib/_tools/eslint/rules/require-last-path-relative' );
+*
+* console.log( rule );
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;

lib/node_modules/@stdlib/_tools/eslint/rules/require-last-path-relative/lib/main.js

@@ -0,0 +1,124 @@
+/**
+* @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 startsWith = require( '@stdlib/string/starts-with' );
+
+
+// FUNCTIONS //
+
+/**
+* Checks if a require path is relative.
+*
+* @private
+* @param {string} path - require path
+* @returns {boolean} boolean indicating if path is relative
+*/
+function isRelativePath( path ) {
+	return (
+		startsWith( path, './' ) ||
+		startsWith( path, '/' ) ||
+		startsWith( path, '../' )
+	);
+}
+
+
+// MAIN //
+
+/**
+* ESLint rule to enforce that the last `require` statement is a relative path.
+*
+* @param {Object} context - ESLint context
+* @returns {Object} validators
+*/
+function main( context ) {
+	var requires = [];
+
+	/**
+	* Validates `require` statements.
+	*
+	* @private
+	* @param {ASTNode} node - node to examine
+	*/
+	function validate( node ) {
+		var requirePath;
+		if (
+			node.callee.name === 'require' &&
+			node.arguments[ 0 ] &&
+			node.arguments[ 0 ].type === 'Literal'
+		) {
+			requirePath = node.arguments[ 0 ].value;
+			requires.push({
+				'node': node,
+				'path': requirePath,
+				'isRelative': isRelativePath( requirePath )
+			});
+		}
+	}
+
+	/**
+	* Reports the error message.
+	*
+	* @private
+	* @param {Object} lastRequire - last require statement
+	*/
+	function report( lastRequire ) {
+		context.report({
+			'node': lastRequire.node,
+			'message': 'Last `require` statement in example files must be a relative path'
+		});
+	}
+
+	/**
+	* Callback invoked upon program exit.
+	*
+	* @private
+	*/
+	function finish() {
+		var lastRequire;
+		if ( requires.length > 0 ) {
+			lastRequire = requires[ requires.length - 1 ];
+			if ( !lastRequire.isRelative ) {
+				report( lastRequire );
+			}
+			requires.length = 0;
+		}
+	}
+
+	return {
+		'CallExpression': validate,
+		'Program:exit': finish
+	};
+}
+
+
+// EXPORTS //
+
+module.exports = {
+	'meta': {
+		'type': 'suggestion',
+		'docs': {
+			'description': 'enforce that the last `require` statement is a relative path'
+		},
+		'schema': []
+	},
+	'create': main
+};