Update the lint:jsdoc configuration to be compatible with ESLint v10 - #13237
Update the lint:jsdoc configuration to be compatible with ESLint v10#13237afercia wants to merge 3 commits into
Conversation
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the Core Committers: Use this line as a base for the props when committing in SVN: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
Note, for history: the |
Test using WordPress PlaygroundThe changes in this pull request can previewed and tested using a WordPress Playground instance. WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser. Some things to be aware of
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
There was a problem hiding this comment.
Thank you for noticing the issue and working on a fix 🙏
I had a quick look and triggered an AI-assisted code review, sharing my findings here.
The current green checks do not exercise the behavior changed here. The JavaScript coding-standards workflow runs npm run grunt jshint, not npm run lint:jsdoc, so CI can stay green if the command hangs, loads the wrong config, accepts legacy-invalid JSDoc, or fixes unrelated directives.
Could we add a small fixture-based check that proves the command completes, selects the flat config, enforces the agreed legacy rules, and leaves non-Javadoc lint directives unchanged? A controlled fixture is preferable to asserting the current repository-wide error count.
Also cc @manzoorwanijk as the author of the related Gutenberg change.
And cc @aduth , too
| // Type validation with exemptTagContexts to allow flexible type formats | ||
| // This avoids enforcing type normalization (Object→object) preferences | ||
| 'jsdoc/check-types': [ 'error', { | ||
| noDefaults: true, | ||
| exemptTagContexts: [ | ||
| { tag: 'param', types: true }, | ||
| { tag: 'return', types: true }, | ||
| { tag: 'returns', types: true }, | ||
| { tag: 'type', types: true }, | ||
| { tag: 'typedef', types: true }, | ||
| { tag: 'property', types: true }, | ||
| { tag: 'arg', types: true }, | ||
| { tag: 'argument', types: true }, | ||
| ], | ||
| } ], | ||
|
|
||
| // NOTE: check-tag-names is DISABLED because eslint-plugin-jsdoc enforces | ||
| // opposite tag preferences (return→returns) than the original valid-jsdoc | ||
| // (which preferred returns→return). Disabling avoids ~1600 false positives. | ||
| 'jsdoc/check-tag-names': 'off', | ||
|
|
||
| // Disable all other jsdoc rules to match minimal original requirements | ||
| 'jsdoc/check-indentation': 'off', | ||
| 'jsdoc/check-line-alignment': 'off', | ||
| 'jsdoc/check-property-names': 'off', | ||
| 'jsdoc/check-syntax': 'off', | ||
| 'jsdoc/check-template-names': 'off', | ||
| 'jsdoc/check-values': 'off', | ||
| 'jsdoc/convert-to-jsdoc-comments': 'off', | ||
| 'jsdoc/empty-tags': 'off', | ||
| 'jsdoc/implements-on-classes': 'off', | ||
| 'jsdoc/match-description': 'off', | ||
| 'jsdoc/multiline-blocks': 'off', | ||
| 'jsdoc/no-bad-blocks': 'off', | ||
| 'jsdoc/no-defaults': 'off', | ||
| 'jsdoc/no-types': 'off', | ||
| 'jsdoc/require-asterisk-prefix': 'off', | ||
| 'jsdoc/require-description': 'off', | ||
| 'jsdoc/require-description-complete-sentence': 'off', | ||
| 'jsdoc/require-example': 'off', | ||
| 'jsdoc/require-file-overview': 'off', | ||
| 'jsdoc/require-hyphen-before-param-description': 'off', | ||
| 'jsdoc/require-jsdoc': 'off', | ||
| 'jsdoc/require-param': 'off', | ||
| 'jsdoc/require-param-description': 'off', | ||
| 'jsdoc/require-param-name': 'off', | ||
| 'jsdoc/require-param-type': 'off', | ||
| 'jsdoc/require-property': 'off', | ||
| 'jsdoc/require-property-description': 'off', | ||
| 'jsdoc/require-property-name': 'off', | ||
| 'jsdoc/require-property-type': 'off', | ||
| 'jsdoc/require-returns': 'off', | ||
| 'jsdoc/require-returns-check': 'off', | ||
| 'jsdoc/require-returns-description': 'off', | ||
| 'jsdoc/require-returns-type': 'off', | ||
| 'jsdoc/require-throws': 'off', | ||
| 'jsdoc/require-yields': 'off', | ||
| 'jsdoc/require-yields-check': 'off', | ||
| 'jsdoc/sort-tags': 'off', | ||
| 'jsdoc/tag-lines': 'off', | ||
| 'jsdoc/text-escaping': 'off', | ||
| 'jsdoc/valid-types': 'off', | ||
| }, |
There was a problem hiding this comment.
This does not preserve the old valid-jsdoc behavior described by the ticket and this config. The new rules exempt the common JSDoc tags from type checks, disable tag-name checks, and disable required parameter/return type and return-description checks.
I ran one fixture against ESLint 8.57.1 with the exact old config, then against ESLint 10 with this PR's config. @arg {int}, @returns {String} without a description, and missing parameter/return types produced six errors before and zero after. Nonconforming docblocks will therefore pass after this migration.
Could we map the old prefer, preferType, required-type, and return-description behavior to eslint-plugin-jsdoc, then add parity fixtures for those cases? The current Gutenberg JSDoc config confirms the supported pattern: use settings.jsdoc.tagNamePreference and preferredTypes with check-tag-names, check-types, and the applicable required-type/description rules.
Verification detail
The old config reported:
- missing return description;
@arginstead of@param;intinstead ofnumber;@returnsinstead of@return;Stringinstead ofstring;- missing type braces.
The PR config exited successfully with no diagnostics for the same source.
| module.exports = [ | ||
| ...jsdocConfig, | ||
| { | ||
| ignores: [ | ||
| 'build/**', | ||
| '**/build/**', | ||
| 'node_modules/**', | ||
| 'tests/**', | ||
| 'vendor/**', | ||
| 'tools/**', | ||
| 'jsdoc/**', | ||
| 'artifacts/**', | ||
| 'coverage/**', | ||
| '.cache/**', | ||
| 'src/wp-includes/blocks/**/*.js', | ||
| 'src/wp-includes/blocks/**/*.js.map', | ||
| 'src/wp-content/themes/**', | ||
| 'src/wp-content/plugins/**', | ||
| 'src/wp-content/mu-plugins/**', | ||
| 'src/wp-content/upgrade/**', | ||
| 'src/wp-content/uploads/**', | ||
| 'src/js/_enqueues/vendor/**', | ||
| 'src/wp-admin/js/**', | ||
| 'src/wp-includes/js/**', | ||
| ], | ||
| }, |
There was a problem hiding this comment.
The dedicated JSDoc commands still process unrelated inline ESLint configuration. At this head, npm run lint:jsdoc reports five eslint-env errors and three unused-disable warnings outside JSDoc. More importantly, --fix-dry-run shows that lint:jsdoc:fix removes existing // eslint-disable-line complexity comments from src/js/_enqueues/wp/code-editor.js because the minimal config does not enable complexity.
That means a JSDoc fixer can change suppressions that belong to another lint pass. Could this config disable unrelated inline-config processing, for example with linterOptions.noInlineConfig: true after confirming that no JSDoc-specific inline suppressions are required? The pinned tree contains no JSDoc-specific ESLint disable comments, and the equivalent --no-inline-config probe removed these unrelated diagnostics.
Verification detail
The exact-head run completed with 40 diagnostics: 37 errors and 3 warnings. Five errors were for unsupported eslint-env comments, and all three warnings were unrelated unused disables. ESLint documents both behaviors in its flat-config migration guide and linter options reference.
2 participants
Trac ticket: https://core.trac.wordpress.org/ticket/65939
Use of AI Tools
npm install && npm run lint:jsdocImportant: compare the new ruleset with the previous one. The Core ruleset is minimal and only checks a very few rules while the one in Gutenberg checks for way more ones. For now, I tried to replicate the 'minimal' configuration that was used in Core.
AI assistance: Yes
Tool(s): GitHub Copilot
Model(s): Claude Haiku 4.5
Used for: Configuration of the rules to match the previous ones. Final implementation was reviewed by me.
This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.