From 4599b9f81de3ed3a7f5c8a7e8b9b451ba11dbb0b Mon Sep 17 00:00:00 2001 From: Philipp Burckhardt Date: Wed, 19 Feb 2025 10:03:39 -0500 Subject: [PATCH 1/2] build: refactor rule to disallow tabs in entire JSDoc comment --- 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: passed - 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: passed - 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 --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na --- --- .../eslint/rules/jsdoc-no-tabs/README.md | 4 +- .../eslint/rules/jsdoc-no-tabs/lib/main.js | 21 ++----- .../jsdoc-no-tabs/test/fixtures/invalid.js | 60 +++++++++++++++++++ 3 files changed, 68 insertions(+), 17 deletions(-) diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/README.md b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/README.md index 7c89fdb131b2..71478982d4d7 100644 --- a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/README.md +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/README.md @@ -20,7 +20,7 @@ limitations under the License. # No Tabs -> [ESLint rule][eslint-rules] forbidding the use of tabs in JSDoc descriptions. +> [ESLint rule][eslint-rules] forbidding the use of tabs in JSDoc comments.
@@ -38,7 +38,7 @@ var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-no-tabs' ); #### rule -[ESLint rule][eslint-rules] forbidding the use of tabs in JSDoc descriptions. +[ESLint rule][eslint-rules] forbidding the use of tabs in JSDoc comments. **Bad**: diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/lib/main.js b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/lib/main.js index 1d2e00862283..ab912107f28c 100644 --- a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/lib/main.js +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/lib/main.js @@ -20,7 +20,6 @@ // MODULES // -var parseJSDoc = require( 'doctrine' ).parse; var remark = require( 'remark' ); var remarkLint = require( 'remark-lint' ); var remarkPlugin = require( 'remark-lint-no-tabs' ); @@ -30,17 +29,13 @@ var findJSDoc = require( '@stdlib/_tools/eslint/utils/find-jsdoc' ); // VARIABLES // -var DOPTS = { - 'sloppy': true, - 'unwrap': true -}; var rule; // FUNCTIONS // /** -* Rule forbidding the use of tabs in JSDoc descriptions. +* Rule forbidding the use of tabs in JSDoc comments. * * @param {Object} context - ESLint context * @returns {Object} validators @@ -67,7 +62,7 @@ function main( context ) { }; /** - * Lints JSDoc descriptions. + * Lints entire JSDoc comments for tabs. * * @private * @param {ASTNode} node - AST node @@ -75,16 +70,12 @@ function main( context ) { function validate( node ) { var jsdoc; var vfile; - var ast; jsdoc = findJSDoc( source, node ); if ( isObject( jsdoc ) ) { - ast = parseJSDoc( jsdoc.value, DOPTS ); - if ( ast.description ) { - vfile = lint( ast.description ); - if ( vfile.messages.length ) { - reportErrors( vfile.messages, jsdoc.loc ); - } + vfile = lint( jsdoc.value ); + if ( vfile.messages.length ) { + reportErrors( vfile.messages, jsdoc.loc ); } } } @@ -154,7 +145,7 @@ function main( context ) { rule = { 'meta': { 'docs': { - 'description': 'forbid the use of tabs in JSDoc descriptions' + 'description': 'forbid the use of tabs in JSDoc comments' }, 'schema': [] }, diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/test/fixtures/invalid.js b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/test/fixtures/invalid.js index 2ff2633fa4d9..2fdca32e36ec 100644 --- a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/test/fixtures/invalid.js +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/test/fixtures/invalid.js @@ -70,6 +70,66 @@ test = { }; invalid.push( test ); +test = { + 'code': [ + '/**', + '* Beep boop.', + '*', + '* [foo]: http://foo.bar/baz', + '*', + '* @param {string} str - input value', + '* @returns {string} output value', + '*', + '* @example', + '* var out = beep( "boop" );', + '* // returns "beepboop"', + '*/', + 'function beep( str ) {', + ' return "beep" + str;', + '}' + ].join( '\n' ), + 'errors': [ + { + 'message': 'Use spaces instead of tabs', + 'type': null + }, + { + 'message': 'Use spaces instead of tabs', + 'type': null + } + ] +}; +invalid.push( test ); + +test = { + 'code': [ + '/**', + '* Beep boop.', + '*', + '* @param {string} str - input value', + '* @returns {string} output value', + '*', + '* @example', + '* var out = beep( "boop" );', + '* // returns "beepboop"', + '*/', + 'function beep( str ) {', + ' return "beep" + str;', + '}' + ].join( '\n' ), + 'errors': [ + { + 'message': 'Use spaces instead of tabs', + 'type': null + }, + { + 'message': 'Use spaces instead of tabs', + 'type': null + } + ] +}; +invalid.push( test ); + // EXPORTS // From 54c64ddfcafb8b7df76c13c933b8cd8ee1bd790b Mon Sep 17 00:00:00 2001 From: Philipp Burckhardt Date: Wed, 19 Feb 2025 20:42:37 -0500 Subject: [PATCH 2/2] fix: handle nested function case --- 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: passed - 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 --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na --- --- .../eslint/rules/jsdoc-no-tabs/lib/main.js | 7 +- .../jsdoc-no-tabs/test/fixtures/valid.js | 66 +++++++++++++++++++ 2 files changed, 72 insertions(+), 1 deletion(-) diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/lib/main.js b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/lib/main.js index ab912107f28c..cf4ed164d42e 100644 --- a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/lib/main.js +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/lib/main.js @@ -23,12 +23,14 @@ var remark = require( 'remark' ); var remarkLint = require( 'remark-lint' ); var remarkPlugin = require( 'remark-lint-no-tabs' ); +var replace = require( '@stdlib/string/replace' ); var isObject = require( '@stdlib/assert/is-object' ); var findJSDoc = require( '@stdlib/_tools/eslint/utils/find-jsdoc' ); // VARIABLES // +var RE_LEADING_TABS = /^\t+(\*|$)/gm; var rule; @@ -70,10 +72,13 @@ function main( context ) { function validate( node ) { var jsdoc; var vfile; + var text; jsdoc = findJSDoc( source, node ); if ( isObject( jsdoc ) ) { - vfile = lint( jsdoc.value ); + text = jsdoc.value; + text = replace( text, RE_LEADING_TABS, '*' ); + vfile = lint( text ); if ( vfile.messages.length ) { reportErrors( vfile.messages, jsdoc.loc ); } diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/test/fixtures/valid.js b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/test/fixtures/valid.js index 9ef02be53d01..8ce68df3b71a 100644 --- a/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/test/fixtures/valid.js +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-no-tabs/test/fixtures/valid.js @@ -48,6 +48,72 @@ test = { }; valid.push( test ); +test = { + 'code': [ + '/**', + '* @license Apache-2.0', + '*', + '* Copyright (c) 2018 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.', + '*/', + '', + '/**', + '* Squares a number.', + '* ', + '* @param {number} x - input number', + '* @returns {number} x squared', + '*', + '* @example', + '* var y = square( 2.0 );', + '* // returns 4.0', + '*/', + 'function square( x ) {', + ' return x*x;', + '}' + ].join( '\n' ) +}; +valid.push( test ); + +test = { + 'code': [ + '/**', + '* Creates a function to calculate powers.', + '*', + '* @param {number} base - base number', + '* @returns {Function} function to calculate powers', + '*', + '* @example', + '* var powerFn = createPowerFn( 2 );', + '* var result = powerFn( 3 );', + '* // returns 8', + '*/', + 'function createPowerFn( base ) {', + ' /**', + ' * Calculates power of base number.', + ' *', + ' * @private', + ' * @param {number} exponent - power to raise base to', + ' * @returns {number} result of base raised to exponent', + ' */', + ' return function power( exponent ) {', + ' return Math.pow( base, exponent );', + ' };', + '}' + ].join( '\n' ) +}; +valid.push( test ); + test = { 'code': [ '/**',