Make WordPress Core

Opened 5 weeks ago

Last modified 36 hours ago

#65997 new task (blessed)

TypeScript code quality improvements for 7.2

Reported by: westonruter Owned by:
Priority: normal Milestone: 7.2
Component: General Version:
Severity: normal Keywords: has-patch
Cc: Focuses: javascript, docs

Description (last modified by westonruter)

This is the JavaScript analog to the PHP in #65817, but using TypeScript instead of PHPStan. Adding TypeScript checking will likely identify bugs that need to be fixed along the way and it will greatly improve the resilience of the codebase against defects being introduced in the future, either by humans or by agents.

This follows the introduction of the TypeScript in the core codebase in #64662. The initial files being checked with TypeScript are those used by the Code Editor, the tooltip logic, and some build tooling, as is listed in ​tsconfig.json:

"src/js/_enqueues/lib/codemirror/htmlhint-kses.js",
"src/js/_enqueues/lib/codemirror/javascript-lint.js",
"src/js/_enqueues/wp/code-editor.js",
"src/js/_enqueues/wp/wp-tooltip.js",
"tools/gutenberg/copy.js",
"tools/gutenberg/download.js",
"tools/gutenberg/utils.js"

This list needs to expand so that TypeScript checking can eventually cover the entire JS codebase.

TypeScript can be invoked via npm run typecheck:js. Note also the related command do check JSDoc: npm run lint:jsdoc.

Note that while PHPStan has the concept of ​the baseline which allows adopting static analysis for an existing codebase with errors, this is not available for TypeScript. So this means we'll need to either go file-by-file adding TypeScript checking with the existing config, or make the existing config (or separate configs) much looser and then stricter over time.

This will naturally be closely related to improvements to JS documentation across the codebase:

  • #65951 (Fix all the JSDocs)
  • #65860 (General docblock improvements for 7.2)
  • #40831 (Customize: Further improve JS inline documentation)

Change History (2)

#1 @westonruter
5 weeks ago

  • Description modified (diff)

This ticket was mentioned in ​PR #14041 on ​WordPress/wordpress-develop by ​@rahultank.


36 hours ago
#2

  • Keywords has-patch added

Adds src/js/_enqueues/lib/accordion.js to the files checked by tsc (npm run typecheck:js).

With the file included, tsc reported 3 errors, all from one cause: the el parameter of accordionSwitch() was documented as {Object}, so el.closest() and el.attr() were reported as missing (TS2339). el is always a jQuery object (accordionSwitch( $( this ) )), so the JSDoc type is changed to {JQuery}. This matches the existing use of jQuery types in core JSDoc, such as {JQueryStatic} in color-picker.js and nav-menu.js.

Only a JSDoc comment changes in the script, so there is no runtime change.

Testing instructions

  1. Check out this branch and run npm run typecheck:js. It completes with no errors.
  2. Optional: revert only the JSDoc change in accordion.js and run it again. tsc reports the 3 TS2339 errors on lines 58 and 91.

Use of AI Tools

AI assistance: Yes
Used for: Initial draft of the change and this description; the change and the verification runs were reviewed and confirmed by me in a local environment.

Note: See TracTickets for help on using tickets.