build: add lint rule to enforce functions are moved to outermost scopes

etc/eslint/overrides/index.js

@@ -91,7 +91,8 @@ var overrides = [
 			'no-restricted-syntax': restrictedSyntaxConfig,
 			'require-jsdoc': 'off',
 			'stdlib/jsdoc-private-annotation': 'off',
-			'stdlib/jsdoc-doctest': 'off'
+			'stdlib/jsdoc-doctest': 'off',
+			'stdlib/no-unnecessary-nested-functions': 'off'
 		}
 	},
 	{
@@ -103,6 +104,7 @@ var overrides = [
 			'require-jsdoc': 'off',
 			'stdlib/jsdoc-private-annotation': 'off',
 			'stdlib/jsdoc-doctest': 'off',
+			'stdlib/no-unnecessary-nested-functions': 'off',
 			'stdlib/vars-order': 'off'
 		}
 	},
@@ -120,6 +122,7 @@ var overrides = [
 			'require-jsdoc': 'off',
 			'stdlib/jsdoc-private-annotation': 'off',
 			'stdlib/jsdoc-doctest': 'off',
+			'stdlib/no-unnecessary-nested-functions': 'off',
 			'no-undefined': 'off'
 		}
 	},
@@ -155,6 +158,7 @@ var overrides = [
 			'require-jsdoc': 'off',
 			'stdlib/jsdoc-private-annotation': 'off',
 			'stdlib/jsdoc-return-annotations-values': 'off',
+			'stdlib/no-unnecessary-nested-functions': 'off',
 			'stdlib/return-annotations-values': 'off',
 			'strict': 'off',
 			'vars-on-top': 'off',

etc/eslint/rules/stdlib.js

@@ -850,7 +850,7 @@
 * // Bad...
 *
 * /**
 * * Fréchet distribution constructor.
 * *
 * * @module @stdlib/stats/base/dists/frechet/ctor
 * *
@@ -866,7 +866,7 @@
 * // Good...
 *
 * /**
 * * Fréchet distribution constructor.
 * *
 * * @module @stdlib/stats/base/dists/frechet/ctor
 * *
@@ -4334,6 +4334,45 @@
 */
 rules[ 'stdlib/no-nested-require' ] = 'error';
 
+/**
+* Enforce moving inner function declarations to the highest possible scope.
+*
+* @name no-unnecessary-nested-functions
+* @memberof rules
+* @type {string}
+* @default 'error'
+*
+* @example
+* // Bad...
+* function outer() {
+*     function inner() {
+*         return 42;
+*     }
+*     return inner();
+* }
+*
+* @example
+* // Good...
+* function inner() {
+*     return 42;
+* }
+*
+* function outer() {
+*     return inner();
+* }
+*
+* @example
+* // Good (uses outer scope variable)...
+* function outer( x ) {
+*     var multiplier = 2;
+*     function inner() {
+*         return x * multiplier;
+*     }
+*     return inner();
+* }
+*/
+rules[ 'stdlib/no-unnecessary-nested-functions' ] = 'error';
+
 /**
 * Disallow the use of the `new Array()` constructor.
 *

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

@@ -972,6 +972,15 @@ setReadOnly( rules, 'no-self-require', require( '@stdlib/_tools/eslint/rules/no-
 */
 setReadOnly( rules, 'no-unassigned-require', require( '@stdlib/_tools/eslint/rules/no-unassigned-require' ) );
 
+/**
+* @name no-unnecessary-nested-functions
+* @memberof rules
+* @readonly
+* @type {Function}
+* @see {@link module:@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions}
+*/
+setReadOnly( rules, 'no-unnecessary-nested-functions', require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' ) );
+
 /**
 * @name repl-namespace-order
 * @memberof rules

lib/node_modules/@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions/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.
+
+-->
+
+# no-unnecessary-nested-functions
+
+> [ESLint rule][eslint-rules] to prevent unnecessary function nesting when inner functions don't depend on outer scope variables.
+
+<section class="intro">
+
+This rule enforces a convention in stdlib to only have functions defined inside of other functions if they need access to variables defined in the outer function scope. Otherwise, functions should always be elevated to the highest level (ideally module scope) to avoid redefining the functions per invocation.
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var rule = require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' );
+```
+
+#### rule
+
+[ESLint rule][eslint-rules] to prevent unnecessary function nesting when inner functions don't depend on outer scope variables.
+
+**Bad**:
+
+<!-- eslint-disable stdlib/no-unnecessary-nested-functions -->
+
+```javascript
+var PI = require( '@stdlib/constants/float64/pi' );
+
+function outer( x ) {
+    var result;
+
+    function helper() {
+        return PI; // doesn't use any variables from outer scope...
+    }
+
+    result = x * helper();
+    return result;
+}
+```
+
+**Good**:
+
+```javascript
+var PI = require( '@stdlib/constants/float64/pi' );
+
+// Helper moved to module scope...
+function helper() {
+    return PI;
+}
+
+function outer( x ) {
+    var result;
+    result = x * helper();
+    return result;
+}
+```
+
+**Good** (function uses outer scope variables):
+
+```javascript
+function outer( x ) {
+    var multiplier = 2;
+
+    function helper() {
+        return x * multiplier; // uses 'multiplier' from outer scope...
+    }
+
+    return helper();
+}
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   The rule only checks function **declarations**, not function expressions or arrow functions.
+-   Functions already at module or global scope are ignored.
+-   Functions that reference variables from outer scopes are not flagged (closures are preserved).
+-   Functions inside IIFEs (Immediately Invoked Function Expressions) are not flagged, as IIFEs are intentionally used for scope isolation.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var Linter = require( 'eslint' ).Linter;
+var rule = require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' );
+
+var linter = new Linter();
+
+// Generate source code containing nested function without dependencies:
+var code = [
+    'function outer() {',
+    '  function inner() {',
+    '    return 42;',
+    '  }',
+    '  return inner();',
+    '}'
+].join( '\n' );
+
+// Define the ESLint configuration:
+var config = {
+    'rules': {
+        'no-unnecessary-nested-functions': 'error'
+    }
+};
+
+// Register the rule:
+linter.defineRule( 'no-unnecessary-nested-functions', rule );
+
+// Lint the code:
+var out = linter.verify( code, config );
+console.log( out );
+/* =>
+    [
+        {
+            'ruleId': 'no-unnecessary-nested-functions',
+            'severity': 2,
+            'message': 'Function \'inner\' should be moved to module scope.',
+            'line': 2,
+            'column': 3,
+            'nodeType': 'FunctionDeclaration',
+            'endLine': 4,
+            'endColumn': 4
+        }
+    ]
+*/
+```
+
+</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-unnecessary-nested-functions/examples/index.js

@@ -0,0 +1,61 @@
+/**
+* @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();
+
+// Generate source code containing nested function without dependencies:
+var code = [
+	'function outer() {',
+	'  function inner() {',
+	'    return 42;',
+	'  }',
+	'  return inner();',
+	'}'
+].join( '\n' );
+
+// Define the ESLint configuration:
+var config = {
+	'rules': {
+		'no-unnecessary-nested-functions': 'error'
+	}
+};
+
+// Register the rule:
+linter.defineRule( 'no-unnecessary-nested-functions', rule );
+
+// Lint the code:
+var out = linter.verify( code, config );
+console.log( out );
+/* =>
+	[
+		{
+			'ruleId': 'no-unnecessary-nested-functions',
+			'severity': 2,
+			'message': 'Function declaration \'inner\' does not use outer scope variables and should be moved to module scope.',
+			'line': 2,
+			'column': 3,
+			'nodeType': 'FunctionDeclaration',
+			...
+		}
+	]
+*/

lib/node_modules/@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions/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 prevent unnecessary function nesting when inner functions don't depend on outer scope variables.
+*
+* @module @stdlib/_tools/eslint/rules/no-unnecessary-nested-functions
+*
+* @example
+* var rule = require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' );
+*
+* console.log( rule );
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;