diff --git a/etc/eslint/rules/stdlib.js b/etc/eslint/rules/stdlib.js index 09d3f9d7e717..ceacbd72d966 100644 --- a/etc/eslint/rules/stdlib.js +++ b/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-emphasis-marker' ] = [ 'error', '_' ]; */ 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. * diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/README.md b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/README.md new file mode 100644 index 000000000000..3d9d99a0bed7 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/README.md @@ -0,0 +1,159 @@ + + +# jsdoc-example-require-spacing + +> [ESLint rule][eslint-rules] to enforce empty lines between `require` statements and code in JSDoc examples. + +
+ +
+ + + +
+ +## 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**: + + + +```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**: + + + +```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 +*/ +``` + +
+ + + +
+ +## Examples + + + +```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 + } + ] +*/ +``` + +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/examples/index.js b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/examples/index.js new file mode 100644 index 000000000000..7761ac91946a --- /dev/null +++ b/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 ); diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/lib/index.js b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/lib/index.js new file mode 100644 index 000000000000..c65d6877d487 --- /dev/null +++ b/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; diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/lib/main.js b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/lib/main.js new file mode 100644 index 000000000000..d371e73643a5 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/lib/main.js @@ -0,0 +1,175 @@ +/** +* @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 parseJSDoc = require( 'doctrine' ).parse; +var trim = require( '@stdlib/string/base/trim' ); +var reEOL = require( '@stdlib/regexp/eol' ); +var isObject = require( '@stdlib/assert/is-object' ); +var isEmptyArray = require( '@stdlib/assert/is-empty-array' ); +var findJSDoc = require( '@stdlib/_tools/eslint/utils/find-jsdoc' ); + + +// VARIABLES // + +var DOPTS = { + 'sloppy': true, + 'unwrap': true, + 'tags': [ 'example' ] +}; +var rule; + + +// FUNCTIONS // + +/** +* Checks if a line contains a require statement. +* +* @private +* @param {string} line - line to check +* @returns {boolean} boolean indicating if line contains a require statement +*/ +function hasRequire( line ) { + return trim( line ).indexOf( 'require(' ) !== -1; +} + +/** +* Checks if a line is empty. +* +* @private +* @param {string} line - line to check +* @returns {boolean} boolean indicating if line is empty +*/ +function isEmpty( line ) { + return trim( line ) === ''; +} + + +// MAIN // + +/** +* Rule to enforce empty lines between `require` statements and code in JSDoc examples. +* +* @param {Object} context - ESLint context +* @returns {Object} rule object +*/ +function main( context ) { + var source = context.getSourceCode(); + + /** + * Reports the error message. + * + * @private + * @param {Object} node - node to report + */ + function report( node ) { + context.report({ + 'node': node, + 'message': 'Missing empty line between require statement and code in JSDoc example' + }); + } + + /** + * Processes an example tag description. + * + * @private + * @param {string} description - example description + * @param {Object} node - node to report + */ + function processExample( description, node ) { + var nextLine; + var lines; + var i; + + lines = description.split( reEOL.REGEXP ); + for ( i = 0; i < lines.length; i++ ) { + if ( hasRequire( lines[ i ] ) ) { + if ( i + 1 >= lines.length ) { + break; + } + nextLine = lines[ i+1 ]; + if ( isEmpty( nextLine ) ) { + continue; + } + + // If next line is neither empty nor another require, report the error: + if ( !hasRequire( nextLine ) ) { + report( node ); + return; + } + } + } + } + + /** + * Checks if a JSDoc comment contains examples with `require` statements which are not followed by empty lines. + * + * @private + * @param {Object} node - node to examine + */ + function validate( node ) { + var jsdoc; + var tags; + var tag; + var ast; + var j; + + jsdoc = findJSDoc( source, node ); + if ( isObject( jsdoc ) ) { + ast = parseJSDoc( jsdoc.value, DOPTS ); + tags = ast.tags; + if ( isEmptyArray( tags ) ) { + return; + } + for ( j = 0; j < tags.length; j++ ) { + tag = tags[ j ]; + if ( tag.title === 'example' && tag.description ) { + processExample( tag.description, node ); + } + } + } + } + + return { + 'FunctionDeclaration': validate, + 'VariableDeclaration': validate, + 'ExpressionStatement': validate + }; +} + + +// MAIN // + +rule = { + 'meta': { + 'type': 'suggestion', + 'docs': { + 'description': 'enforce empty lines between requires and code in JSDoc examples' + }, + 'schema': [] + }, + 'create': main +}; + + +// EXPORTS // + +module.exports = rule; diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/package.json b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/package.json new file mode 100644 index 000000000000..ee740cdd67d1 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/package.json @@ -0,0 +1,64 @@ +{ + "name": "@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing", + "version": "0.0.0", + "description": "ESLint rule to enforce empty lines between `require` statements and code in JSDoc examples.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "bin": {}, + "main": "./lib", + "directories": { + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "tools", + "tool", + "eslint", + "lint", + "custom", + "rules", + "rule", + "plugin", + "jsdoc", + "example", + "require", + "spacing" + ] +} diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/test/fixtures/invalid.js b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/test/fixtures/invalid.js new file mode 100644 index 000000000000..bc1b8df8cd2b --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/test/fixtures/invalid.js @@ -0,0 +1,90 @@ +/** +* @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 invalid = []; +var test; + +test = { + 'code': [ + '/**', + '* Single require without proper spacing.', + '*', + '* @example', + '* var foo = require( \'foo\' );', + '* var x = foo();', + '*/', + 'function test1() {}' + ].join( '\n' ), + 'errors': [ + { + 'message': 'Missing empty line between require statement and code in JSDoc example', + 'type': 'FunctionDeclaration' + } + ] +}; +invalid.push( test ); + +test = { + 'code': [ + '/**', + '* Multiple requires without proper spacing.', + '*', + '* @example', + '* var foo = require( \'foo\' );', + '* var bar = require( \'bar\' );', + '* var x = foo( bar() );', + '*/', + 'function test2() {}' + ].join( '\n' ), + 'errors': [ + { + 'message': 'Missing empty line between require statement and code in JSDoc example', + 'type': 'FunctionDeclaration' + } + ] +}; +invalid.push( test ); + +test = { + 'code': [ + '/**', + '* Mixed spacing - second require without proper spacing.', + '*', + '* @example', + '* var foo = require( \'foo\' );', + '*', + '* var bar = require( \'bar\' );', + '* var x = foo( bar() );', + '*/', + 'function test4() {}' + ].join( '\n' ), + 'errors': [ + { + 'message': 'Missing empty line between require statement and code in JSDoc example', + 'type': 'FunctionDeclaration' + } + ] +}; +invalid.push( test ); + + +// EXPORTS // + +module.exports = invalid; diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/test/fixtures/valid.js b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/test/fixtures/valid.js new file mode 100644 index 000000000000..208284fdc264 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/test/fixtures/valid.js @@ -0,0 +1,90 @@ +/** +* @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 valid = []; +var test; + +test = { + 'code': [ + '/**', + '* Single require with proper spacing.', + '*', + '* @example', + '* var foo = require( \'foo\' );', + '*', + '* var x = foo();', + '*/', + 'function test1() {}' + ].join( '\n' ) +}; +valid.push( test ); + +test = { + 'code': [ + '/**', + '* Multiple requires with proper spacing.', + '*', + '* @example', + '* var foo = require( \'foo\' );', + '*', + '* var bar = require( \'bar\' );', + '*', + '* var x = foo( bar() );', + '*/', + 'function test2() {}' + ].join( '\n' ) +}; +valid.push( test ); + +test = { + 'code': [ + '/**', + '* Example without requires.', + '*', + '* @example', + '* var x = 5;', + '* var y = x * 2;', + '*/', + 'function test3() {}' + ].join( '\n' ) +}; +valid.push( test ); + +test = { + 'code': [ + '/**', + '* Example with requires and comments.', + '*', + '* @example', + '* var foo = require( \'foo\' );', + '*', + '* // This is a comment', + '*', + '* var x = foo();', + '*/', + 'function test4() {}' + ].join( '\n' ) +}; +valid.push( test ); + + +// EXPORTS // + +module.exports = valid; diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/test/test.js b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/test/test.js new file mode 100644 index 000000000000..2fa07c24668f --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/test/test.js @@ -0,0 +1,70 @@ +/** +* @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 tape = require( 'tape' ); +var RuleTester = require( 'eslint' ).RuleTester; +var rule = require( './../lib' ); + + +// FIXTURES // + +var valid = require( './fixtures/valid.js' ); +var invalid = require( './fixtures/invalid.js' ); + + +// TESTS // + +tape( 'main export is an object', function test( t ) { + t.ok( true, __filename ); + t.equal( typeof rule, 'object', 'main export is an object' ); + t.end(); +}); + +tape( 'the function positively validates JSDoc examples with proper spacing after require statements', function test( t ) { + var tester = new RuleTester(); + + try { + tester.run( 'jsdoc-example-require-spacing', rule, { + 'valid': valid, + 'invalid': [] + }); + t.pass( 'passed without errors' ); + } catch ( err ) { + t.fail( 'encountered an error: ' + err.message ); + } + t.end(); +}); + +tape( 'the function negatively validates JSDoc examples without proper spacing after require statements', function test( t ) { + var tester = new RuleTester(); + + try { + tester.run( 'jsdoc-example-require-spacing', rule, { + 'valid': [], + 'invalid': invalid + }); + t.pass( 'passed without errors' ); + } catch ( err ) { + t.fail( 'encountered an error: ' + err.message ); + } + t.end(); +}); diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/lib/index.js b/lib/node_modules/@stdlib/_tools/eslint/rules/lib/index.js index 8b029f004377..e4d567fa12f6 100644 --- a/lib/node_modules/@stdlib/_tools/eslint/rules/lib/index.js +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/lib/index.js @@ -207,6 +207,15 @@ setReadOnly( rules, 'jsdoc-emphasis-marker', require( '@stdlib/_tools/eslint/rul */ setReadOnly( rules, 'jsdoc-empty-line-before-example', require( '@stdlib/_tools/eslint/rules/jsdoc-empty-line-before-example' ) ); +/** +* @name jsdoc-example-require-spacing +* @memberof rules +* @readonly +* @type {Function} +* @see {@link module:@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing} +*/ +setReadOnly( rules, 'jsdoc-example-require-spacing', require( '@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing' ) ); + /** * @name jsdoc-fenced-code-flag * @memberof rules