feat: add no-single-property-require ESLint rule

etc/eslint/.eslintrc.tests.js

@@ -22,10 +22,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' );
 
 
@@ -128,6 +128,13 @@
 */
 eslint.rules[ 'stdlib/jsdoc-doctest' ] = 'off';
 
+/**
+* Allow requiring the package under test as a whole when only a single property is used.
+*
+* @private
+*/
+eslint.rules[ 'stdlib/no-single-property-require' ] = 'off';
+
 /**
 * Do not enforce nested function elevation.
 *

etc/eslint/overrides/index.js

@@ -122,6 +122,7 @@ var overrides = [
 			'require-jsdoc': 'off',
 			'stdlib/jsdoc-private-annotation': 'off',
 			'stdlib/jsdoc-doctest': 'off',
+			'stdlib/no-single-property-require': 'off',
 			'stdlib/no-unnecessary-nested-functions': 'off',
 			'no-undefined': 'off'
 		}
@@ -158,6 +159,7 @@ var overrides = [
 			'require-jsdoc': 'off',
 			'stdlib/jsdoc-private-annotation': 'off',
 			'stdlib/jsdoc-return-annotations-values': 'off',
+			'stdlib/no-single-property-require': 'off',
 			'stdlib/no-unnecessary-nested-functions': 'off',
 			'stdlib/return-annotations-values': 'off',
 			'strict': 'off',

etc/eslint/rules/stdlib.js

@@ -879,7 +879,7 @@
 * // Bad...
 *
 * /**
 * * Fréchet distribution constructor.
 * *
 * * @module @stdlib/stats/base/dists/frechet/ctor
 * *
@@ -895,7 +895,7 @@
 * // Good...
 *
 * /**
 * * Fréchet distribution constructor.
 * *
 * * @module @stdlib/stats/base/dists/frechet/ctor
 * *
@@ -4589,6 +4589,30 @@
 */
 rules[ 'stdlib/no-self-require' ] = 'error';
 
+/**
+* Enforce that a property is required directly when only a single property of a required module is used. Requiring a property directly reduces bundle sizes during ESM tree-shaking via named imports.
+*
+* @name no-single-property-require
+* @memberof rules
+* @type {string}
+* @default 'warn'
+*
+* @example
+* // Bad...
+* var dcopy = require( '@stdlib/blas/base/dcopy' );
+*
+* dcopy.ndarray( x.length, x, 1, 0, y, 1, 0 );
+* dcopy.ndarray( y.length, y, 1, 0, z, 1, 0 );
+*
+* @example
+* // Good...
+* var dcopy = require( '@stdlib/blas/base/dcopy' ).ndarray;
+*
+* dcopy( x.length, x, 1, 0, y, 1, 0 );
+* dcopy( y.length, y, 1, 0, z, 1, 0 );
+*/
+rules[ 'stdlib/no-single-property-require' ] = 'warn';
+
 /**
 * Never allow unassigned `require()` calls.
 *

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

@@ -999,6 +999,15 @@ setReadOnly( rules, 'no-require-index', require( '@stdlib/_tools/eslint/rules/no
 */
 setReadOnly( rules, 'no-self-require', require( '@stdlib/_tools/eslint/rules/no-self-require' ) );
 
+/**
+* @name no-single-property-require
+* @memberof rules
+* @readonly
+* @type {Function}
+* @see {@link module:@stdlib/_tools/eslint/rules/no-single-property-require}
+*/
+setReadOnly( rules, 'no-single-property-require', require( '@stdlib/_tools/eslint/rules/no-single-property-require' ) );
+
 /**
 * @name no-unassigned-require
 * @memberof rules

lib/node_modules/@stdlib/_tools/eslint/rules/no-single-property-require/README.md

@@ -0,0 +1,182 @@
+<!--
+
+@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.
+
+-->
+
+# no-single-property-require
+
+> [ESLint rule][eslint-rules] disallowing requiring an entire module when only a single property of the module is used.
+
+<section class="intro">
+
+This rule enforces that, when only a single property of a required module is ever used within a module, the property is required directly (e.g., `var dcopy = require( '@stdlib/blas/base/dcopy' ).ndarray;`). Requiring a property directly reduces bundle sizes during ESM tree-shaking via named imports.
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var rule = require( '@stdlib/_tools/eslint/rules/no-single-property-require' );
+```
+
+#### rule
+
+[ESLint rule][eslint-rules] disallowing requiring an entire module when only a single property of the module is used.
+
+**Bad**:
+
+<!-- eslint-disable stdlib/no-single-property-require -->
+
+```javascript
+var dcopy = require( '@stdlib/blas/base/dcopy' );
+
+var x = [ 1.0, 2.0, 3.0 ];
+var y = [ 0.0, 0.0, 0.0 ];
+var z = [ 0.0, 0.0, 0.0 ];
+
+dcopy.ndarray( x.length, x, 1, 0, y, 1, 0 );
+
+// ...
+
+dcopy.ndarray( y.length, y, 1, 0, z, 1, 0 );
+```
+
+**Good**:
+
+```javascript
+var dcopy = require( '@stdlib/blas/base/dcopy' ).ndarray;
+
+var x = [ 1.0, 2.0, 3.0 ];
+var y = [ 0.0, 0.0, 0.0 ];
+var z = [ 0.0, 0.0, 0.0 ];
+
+dcopy( x.length, x, 1, 0, y, 1, 0 );
+
+// ...
+
+dcopy( y.length, y, 1, 0, z, 1, 0 );
+```
+
+**Good** (multiple properties are used):
+
+```javascript
+var dcopy = require( '@stdlib/blas/base/dcopy' );
+
+var x = [ 1.0, 2.0, 3.0 ];
+var y = [ 0.0, 0.0, 0.0 ];
+var z = [ 0.0, 0.0, 0.0 ];
+
+dcopy( x.length, x, 1, y, 1 );
+
+// ...
+
+dcopy.ndarray( y.length, y, 1, 0, z, 1, 0 );
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   The rule only checks module-scope (top-level) variable declarations, as `stdlib` convention is to place `require` statements at the top of a module.
+-   Bindings which are used "bare" anywhere (e.g., called directly, passed as an argument, returned, exported, or interrogated via `typeof`) are not flagged.
+-   Computed property access (e.g., `x[ key ]`) is not flagged, as the accessed property cannot be statically determined.
+-   Bindings which are re-assigned or whose properties are mutated (e.g., assigned, deleted, or updated) are not flagged.
+-   The rule does not resolve whether `require` refers to the global CommonJS function or a shadowing local binding.
+-   When converting a method-style call (e.g., `x.ndarray( ... )`) to a direct call, the `this` context within the called function changes; for `stdlib` packages, exported methods do not rely on `this` binding, and, hence, the transformation is safe.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var Linter = require( 'eslint' ).Linter;
+var rule = require( '@stdlib/_tools/eslint/rules/no-single-property-require' );
+
+var linter = new Linter();
+
+// Generate source code in which only a single property of a required module is used:
+var code = [
+    'var dcopy = require( \'@stdlib/blas/base/dcopy\' );',
+    'dcopy.ndarray( x.length, x, 1, 0, y, 1, 0 );',
+    'dcopy.ndarray( y.length, y, 1, 0, z, 1, 0 );'
+].join( '\n' );
+
+// Define the ESLint configuration:
+var config = {
+    'rules': {
+        'no-single-property-require': 'error'
+    }
+};
+
+// Register the rule:
+linter.defineRule( 'no-single-property-require', rule );
+
+// Lint the code:
+var out = linter.verify( code, config );
+console.log( out );
+/* =>
+    [
+        {
+            'ruleId': 'no-single-property-require',
+            'severity': 2,
+            'message': 'only the `ndarray` property of the required module is used; require the property directly',
+            'line': 1,
+            'column': 5,
+            'nodeType': 'VariableDeclarator',
+            'endLine': 1,
+            'endColumn': 49
+        }
+    ]
+*/
+```
+
+</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/no-single-property-require/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();
+
+// Generate source code in which only a single property of a required module is used:
+var code = [
+	'var dcopy = require( \'@stdlib/blas/base/dcopy\' );',
+	'dcopy.ndarray( x.length, x, 1, 0, y, 1, 0 );',
+	'dcopy.ndarray( y.length, y, 1, 0, z, 1, 0 );'
+].join( '\n' );
+
+// Define the ESLint configuration:
+var config = {
+	'rules': {
+		'no-single-property-require': 'error'
+	}
+};
+
+// Register the rule:
+linter.defineRule( 'no-single-property-require', rule );
+
+// Lint the code:
+var out = linter.verify( code, config );
+console.log( out );
+/* =>
+	[
+		{
+			'ruleId': 'no-single-property-require',
+			'severity': 2,
+			'message': 'only the `ndarray` property of the required module is used; require the property directly',
+			'line': 1,
+			'column': 5,
+			'nodeType': 'VariableDeclarator',
+			'endLine': 1,
+			'endColumn': 49
+		}
+	]
+*/

lib/node_modules/@stdlib/_tools/eslint/rules/no-single-property-require/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 disallowing requiring an entire module when only a single property of the module is used.
+*
+* @module @stdlib/_tools/eslint/rules/no-single-property-require
+*
+* @example
+* var rule = require( '@stdlib/_tools/eslint/rules/no-single-property-require' );
+*
+* console.log( rule );
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;