Skip to content

Commit 295d7e2

Browse files
PlaneshifterPlaneshifter
committed
build: add lint rule to enforce functions are moved to outermost possible scope
--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---
1 parent 774b270 commit 295d7e2

File tree

12 files changed

+1491
-1
lines changed

12 files changed

+1491
-1
lines changed

‎etc/eslint/overrides/index.js‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,8 @@ var overrides = [
9191
'no-restricted-syntax': restrictedSyntaxConfig,
9292
'require-jsdoc': 'off',
9393
'stdlib/jsdoc-private-annotation': 'off',
94-
'stdlib/jsdoc-doctest': 'off'
94+
'stdlib/jsdoc-doctest': 'off',
95+
'stdlib/no-unnecessary-nested-functions': 'off'
9596
}
9697
},
9798
{
@@ -103,6 +104,7 @@ var overrides = [
103104
'require-jsdoc': 'off',
104105
'stdlib/jsdoc-private-annotation': 'off',
105106
'stdlib/jsdoc-doctest': 'off',
107+
'stdlib/no-unnecessary-nested-functions': 'off',
106108
'stdlib/vars-order': 'off'
107109
}
108110
},
@@ -120,6 +122,7 @@ var overrides = [
120122
'require-jsdoc': 'off',
121123
'stdlib/jsdoc-private-annotation': 'off',
122124
'stdlib/jsdoc-doctest': 'off',
125+
'stdlib/no-unnecessary-nested-functions': 'off',
123126
'no-undefined': 'off'
124127
}
125128
},
@@ -155,6 +158,7 @@ var overrides = [
155158
'require-jsdoc': 'off',
156159
'stdlib/jsdoc-private-annotation': 'off',
157160
'stdlib/jsdoc-return-annotations-values': 'off',
161+
'stdlib/no-unnecessary-nested-functions': 'off',
158162
'stdlib/return-annotations-values': 'off',
159163
'strict': 'off',
160164
'vars-on-top': 'off',

‎etc/eslint/rules/stdlib.js‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4334,6 +4334,45 @@ rules[ 'stdlib/no-dynamic-exports' ] = 'error';
43344334
*/
43354335
rules[ 'stdlib/no-nested-require' ] = 'error';
43364336

4337+
/**
4338+
* Enforce moving inner function declarations to the highest possible scope.
4339+
*
4340+
* @name no-unnecessary-nested-functions
4341+
* @memberof rules
4342+
* @type {string}
4343+
* @default 'error'
4344+
*
4345+
* @example
4346+
* // Bad...
4347+
* function outer() {
4348+
* function inner() {
4349+
* return 42;
4350+
* }
4351+
* return inner();
4352+
* }
4353+
*
4354+
* @example
4355+
* // Good...
4356+
* function inner() {
4357+
* return 42;
4358+
* }
4359+
*
4360+
* function outer() {
4361+
* return inner();
4362+
* }
4363+
*
4364+
* @example
4365+
* // Good (uses outer scope variable)...
4366+
* function outer( x ) {
4367+
* var multiplier = 2;
4368+
* function inner() {
4369+
* return x * multiplier;
4370+
* }
4371+
* return inner();
4372+
* }
4373+
*/
4374+
rules[ 'stdlib/no-unnecessary-nested-functions' ] = 'error';
4375+
43374376
/**
43384377
* Disallow the use of the `new Array()` constructor.
43394378
*

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -972,6 +972,15 @@ setReadOnly( rules, 'no-self-require', require( '@stdlib/_tools/eslint/rules/no-
972972
*/
973973
setReadOnly( rules, 'no-unassigned-require', require( '@stdlib/_tools/eslint/rules/no-unassigned-require' ) );
974974

975+
/**
976+
* @name no-unnecessary-nested-functions
977+
* @memberof rules
978+
* @readonly
979+
* @type {Function}
980+
* @see {@link module:@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions}
981+
*/
982+
setReadOnly( rules, 'no-unnecessary-nested-functions', require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' ) );
983+
975984
/**
976985
* @name repl-namespace-order
977986
* @memberof rules

‎lib/node_modules/@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions/README.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# no-unnecessary-nested-functions
22+
23+
> [ESLint rule][eslint-rules] to prevent unnecessary function nesting when inner functions don't depend on outer scope variables.
24+
25+
<section class="intro">
26+
27+
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.
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<section class="usage">
34+
35+
## Usage
36+
37+
```javascript
38+
var rule = require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' );
39+
```
40+
41+
#### rule
42+
43+
[ESLint rule][eslint-rules] to prevent unnecessary function nesting when inner functions don't depend on outer scope variables.
44+
45+
**Bad**:
46+
47+
<!-- eslint-disable stdlib/no-unnecessary-nested-functions -->
48+
49+
```javascript
50+
var PI = require( '@stdlib/constants/float64/pi' );
51+
52+
function outer( x ) {
53+
var result;
54+
55+
function helper() {
56+
return PI; // doesn't use any variables from outer scope...
57+
}
58+
59+
result = x * helper();
60+
return result;
61+
}
62+
```
63+
64+
**Good**:
65+
66+
```javascript
67+
var PI = require( '@stdlib/constants/float64/pi' );
68+
69+
// Helper moved to module scope...
70+
function helper() {
71+
return PI;
72+
}
73+
74+
function outer( x ) {
75+
var result;
76+
result = x * helper();
77+
return result;
78+
}
79+
```
80+
81+
**Good** (function uses outer scope variables):
82+
83+
```javascript
84+
function outer( x ) {
85+
var multiplier = 2;
86+
87+
function helper() {
88+
return x * multiplier; // uses 'multiplier' from outer scope...
89+
}
90+
91+
return helper();
92+
}
93+
```
94+
95+
</section>
96+
97+
<!-- /.usage -->
98+
99+
<section class="notes">
100+
101+
## Notes
102+
103+
- The rule only checks function **declarations**, not function expressions or arrow functions.
104+
- Functions already at module or global scope are ignored.
105+
- Functions that reference variables from outer scopes are not flagged (closures are preserved).
106+
- Functions that use `this` context from outer scope are not flagged.
107+
- Functions that use `arguments` from outer scope are not flagged.
108+
- Functions inside IIFEs (Immediately Invoked Function Expressions) are not flagged, as IIFEs are intentionally used for scope isolation.
109+
110+
</section>
111+
112+
<!-- /.notes -->
113+
114+
<section class="examples">
115+
116+
## Examples
117+
118+
<!-- eslint no-undef: "error" -->
119+
120+
```javascript
121+
var Linter = require( 'eslint' ).Linter;
122+
var rule = require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' );
123+
124+
var linter = new Linter();
125+
var code;
126+
var config;
127+
var out;
128+
129+
// Generate source code containing nested function without dependencies:
130+
code = [
131+
'function outer() {',
132+
' function inner() {',
133+
' return 42;',
134+
' }',
135+
' return inner();',
136+
'}'
137+
].join( '\n' );
138+
139+
// Define the ESLint configuration:
140+
config = {
141+
'rules': {
142+
'no-unnecessary-nested-functions': 'error'
143+
}
144+
};
145+
146+
// Register the rule:
147+
linter.defineRule( 'no-unnecessary-nested-functions', rule );
148+
149+
// Lint the code:
150+
out = linter.verify( code, config );
151+
console.log( out );
152+
/* =>
153+
[
154+
{
155+
'ruleId': 'no-unnecessary-nested-functions',
156+
'severity': 2,
157+
'message': 'Function declaration \'inner\' does not use outer scope variables and should be moved to module scope.',
158+
'line': 2,
159+
'column': 3,
160+
'nodeType': 'FunctionDeclaration',
161+
'endLine': 4,
162+
'endColumn': 4
163+
}
164+
]
165+
*/
166+
```
167+
168+
</section>
169+
170+
<!-- /.examples -->
171+
172+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
173+
174+
<section class="related">
175+
176+
</section>
177+
178+
<!-- /.related -->
179+
180+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
181+
182+
<section class="links">
183+
184+
[eslint-rules]: https://eslint.org/docs/developer-guide/working-with-rules
185+
186+
</section>
187+
188+
<!-- /.links -->

‎lib/node_modules/@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions/examples/index.js‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
var Linter = require( 'eslint' ).Linter;
22+
var rule = require( './../lib' );
23+
24+
var linter = new Linter();
25+
var code;
26+
var config;
27+
var out;
28+
29+
// Generate source code containing nested function without dependencies:
30+
code = [
31+
'function outer() {',
32+
' function inner() {',
33+
' return 42;',
34+
' }',
35+
' return inner();',
36+
'}'
37+
].join( '\n' );
38+
39+
// Define the ESLint configuration:
40+
config = {
41+
'rules': {
42+
'no-unnecessary-nested-functions': 'error'
43+
}
44+
};
45+
46+
// Register the rule:
47+
linter.defineRule( 'no-unnecessary-nested-functions', rule );
48+
49+
// Lint the code:
50+
out = linter.verify( code, config );
51+
console.log( out );
52+
/* =>
53+
[
54+
{
55+
'ruleId': 'no-unnecessary-nested-functions',
56+
'severity': 2,
57+
'message': 'Function declaration \'inner\' does not use outer scope variables and should be moved to module scope.',
58+
'line': 2,
59+
'column': 3,
60+
'nodeType': 'FunctionDeclaration',
61+
...
62+
}
63+
]
64+
*/

‎lib/node_modules/@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions/lib/index.js‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
/**
22+
* ESLint rule to prevent unnecessary function nesting when inner functions don't depend on outer scope variables.
23+
*
24+
* @module @stdlib/_tools/eslint/rules/no-unnecessary-nested-functions
25+
*
26+
* @example
27+
* var rule = require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' );
28+
*
29+
* console.log( rule );
30+
*/
31+
32+
// MODULES //
33+
34+
var main = require( './main.js' );
35+
36+
37+
// EXPORTS //
38+
39+
module.exports = main;

0 commit comments

Comments
 (0)