Code Editor: Improve types and options handling

[westonruter]

This is a follow-up to:

• Switch from Esprima to Espree for JavaScript linting in CodeMirror. #10806
• Upgrade CodeMirror to latest v5 #10778

To address:

• Fix TypeScript issues with code-editor.js.
• Address issue where linting runs twice when the editor is initialized. See Switch from Esprima to Espree for JavaScript linting in CodeMirror. #10806 (comment). See dd7579f.

This is closely related to Core-61175 which introduces PHPStan as the PR for this ticket introduces TypeScript, although currently constrained to apply to files related to the code editor. The pull request introduces TypeScript to help guide the refactor to how linting options are gathered so as to avoid the double-linting issue. Instead of initializing with the default options first and then supplying the WordPress options, now it gathers the WordPress options and supplies them into the code editor when it first initializes.

Additionally, the source files were re-organized to remove our CodeMirror extension code from confusingly being located in a vendor directory.

In subsequent PRs:

• Remove jQuery dependency
• Add TypeScript to precommit task and GHA workflow. See Core-64662.

Trac ticket: https://core.trac.wordpress.org/ticket/64661

Gemini Summary

This branch introduces comprehensive TypeScript static analysis for JavaScript files using JSDoc, modernizes several Code Editor components, and refines the build and organizational structure of CodeMirror extensions.

1. TypeScript Static Analysis & Type Safety

• Infrastructure: Introduced tsconfig.json configured for JS checking (checkJs: true) and strict mode (strict: true). Added a typecheck:js script to package.json to facilitate this analysis.
• Global Definitions: Created typings/globals.d.ts to provide type definitions for WordPress globals (wp), jQuery, _ (Underscore), Backbone, and HTMLHint.
• Enhanced Type Definitions:
  • Defined precise JSDoc typedefs in code-editor.js (e.g., CodeEditorInstance, LintingController) to replace generic types.
  • Integrated CodeMirror addon types (lint, show-hint) using triple-slash directives.
  • Eliminated almost all generic any usage in favor of specific intersection types and unions.
• Strict Checking: Resolved numerous strict-mode issues, including mandatory null checks for optional callbacks and properties.

2. Code Modernization & Refactoring

• code-editor.js:
  • Modernized variable declarations using const and let.
  • Updated deprecated APIs: replaced event.keyCode with event.key and substr() with slice().
  • Adopted native DOM APIs where appropriate (classList, Node.contains).
  • Standardized code style with trailing commas in multi-line object literals.
• htmlhint-kses.js:
  • Refactored to modern ES syntax (arrow functions, template literals, and for...of loops).
  • Formatted with Prettier for consistency with modern standards.

3. Organization & Build Process

• Source Reorganization: Moved WordPress-maintained CodeMirror extensions (htmlhint-kses.js, javascript-lint.js) from vendor/ to lib/ to distinguish them from third-party code.
• Deprecation: The fakejshint.js file has been documented as deprecated and moved to src/js/_enqueues/deprecated/.
• Redundancy Cleanup: Removed the redundant esprima.js source file; the build now correctly sources it from the npm package.
• Linter Optimization:
  • Resolved a double-linting bug during initialization by centralizing option construction.
  • Removed obsolete nested options.options for linting, following modern CodeMirror standards.
• ESLint Alignment: Added a local .eslintrc.json in lib/codemirror/ to correctly signal ES module parsing for javascript-lint.js.

4. Dependencies

• Added @types packages for jquery, codemirror, underscore, espree, and htmlhint as devDependencies to support the static analysis effort.

All changes have been verified via npm run typecheck:js and npx grunt jshint:core.

Fixed PhpStorm Inspections

Use of AI Tools

I used Gemini CLI for granular commits, each of which I reviewed.

---

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.

[github-actions]

Test using WordPress Playground

The 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

• The Plugin and Theme Directories cannot be accessed within Playground.
• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[westonruter]

This file should have been deleted previously as part of #10778

[github-actions]

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 props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props westonruter, justlevine, jonsurrell.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[westonruter]

This was not committed yet.

[sirreal]

I've left some feedback mostly around the TypeScript setup. If you'd like, I'm happy to work on adjustments and push changes.

Frankly, I'd like to start using TypeScript syntax directly for these files that are already being compiled/bundled where we're adding a lot of type information. Whether a file is TypeScript or not could also serve as the condition for whether to check types.

[sirreal]

Some suggestions here.

• For including specific files, files rather than include seems more appropriate.
• We can follow some of Gutenberg's established config for things like module: preserve (since TS isn't compiling, just type checking).
• moduleResolution: bundler is likely most appropriate since things are being run processed by bundlers (webpack at the moment).
• Declaration files (*.d.ts aren't source files and typically shouldn't be part of include. Instead, they're included via typeRoots + types.
• I'd like to adopt erasableSyntaxOnly everywhere.

Suggested change

	{
	"compilerOptions": {
	"allowJs": true,
	"checkJs": true,
	"noEmit": true,
	"module": "ESNext",
	"target": "ES2020",
	"moduleResolution": "node",
	"strict": true,
	"noUnusedLocals": true,
	"noUnusedParameters": true,
	"skipLibCheck": true,
	"isolatedModules": true,
	"allowSyntheticDefaultImports": true,
	"lib": [
	"es2020",
	"dom"
	],
	"types": [
	"jquery",
	"codemirror",
	"underscore",
	"htmlhint"
	]
	},
	"include": [
	"src/js/_enqueues/wp/code-editor.js",
	"src/js/_enqueues/lib/codemirror/javascript-lint.js",
	"src/js/_enqueues/lib/codemirror/htmlhint-kses.js",
	"typings/**/*.d.ts"
	]
	}
	{
	"compilerOptions": {
	"allowJs": true,
	"checkJs": true,
	"noEmit": true,
	"module": "preserve",
	"target": "ES2020",
	"moduleResolution": "bundler",
	"strict": true,
	"erasableSyntaxOnly": true,
	"noUnusedLocals": true,
	"noUnusedParameters": true,
	"skipLibCheck": true,
	"isolatedModules": true,
	"allowSyntheticDefaultImports": true,
	"lib": [
	"es2020",
	"dom"
	],
	"typeRoots": [ "./typings", "./node_modules/@types" ],
	"types": [
	"jquery",
	"codemirror",
	"underscore",
	"htmlhint",
	"wp-globals"
	]
	},
	"files": [
	"src/js/_enqueues/wp/code-editor.js",
	"src/js/_enqueues/lib/codemirror/javascript-lint.js",
	"src/js/_enqueues/lib/codemirror/htmlhint-kses.js"
	],
	"include": [],
	}

I think we'll need to move typings/globals.d.ts to typings/wp-globals/index.d.ts for the typeRoots + types change to work correctly.

[sirreal]

I wonder about several things here:

• are the triple-slash directives necessary or can we use type imports instead?
• Do we need to declare both the global vars and the window interface? If things are configured correctly, I think the declared global vars should be available on the global (window) without needing to augment its interface.

See the gutneberg-env types for an example of how this is working.

[westonruter]

You're right! Much better: df54173

[sirreal]

Here's the file diff between fdafcd3
and 5f54c0b. No obvious issues in the diff 👍

diff --git o/src/js/_enqueues/vendor/codemirror/htmlhint-kses.js w/src/js/_enqueues/lib/codemirror/htmlhint-kses.js
index 1aa7ffbd08..e08c4c0f5b 100644
--- o/src/js/_enqueues/vendor/codemirror/htmlhint-kses.js
+++ w/src/js/_enqueues/lib/codemirror/htmlhint-kses.js
@@ -1,30 +1,47 @@
 /* global HTMLHint */
-/* eslint no-magic-numbers: ["error", { "ignore": [0, 1] }] */
-HTMLHint.addRule({
+/* eslint no-magic-numbers: ["error", { "ignore": [1] }] */
+HTMLHint.addRule( {
 	id: 'kses',
 	description: 'Element or attribute cannot be used.',
-	init: function( parser, reporter, options ) {
+
+	/**
+	 * Initialize.
+	 *
+	 * @this {import('htmlhint/types').Rule}
+	 * @param {import('htmlhint').HTMLParser} parser - Parser.
+	 * @param {import('htmlhint').Reporter} reporter - Reporter.
+	 * @param {Record<string, Record<string, boolean>>} options - KSES options.
+	 * @return {void}
+	 */
+	init: function ( parser, reporter, options ) {
 		'use strict';
 
-		var self = this;
-		parser.addListener( 'tagstart', function( event ) {
-			var attr, col, attrName, allowedAttributes, i, len, tagName;
-
-			tagName = event.tagName.toLowerCase();
+		parser.addListener( 'tagstart', ( event ) => {
+			const tagName = event.tagName.toLowerCase();
 			if ( ! options[ tagName ] ) {
-				reporter.error( 'Tag <' + event.tagName + '> is not allowed.', event.line, event.col, self, event.raw );
+				reporter.error(
+					`Tag <${ event.tagName }> is not allowed.`,
+					event.line,
+					event.col,
+					this,
+					event.raw
+				);
 				return;
 			}
 
-			allowedAttributes = options[ tagName ];
-			col = event.col + event.tagName.length + 1;
-			for ( i = 0, len = event.attrs.length; i < len; i++ ) {
-				attr = event.attrs[ i ];
-				attrName = attr.name.toLowerCase();
-				if ( ! allowedAttributes[ attrName ] ) {
-					reporter.error( 'Tag attribute [' + attr.raw + ' ] is not allowed.', event.line, col + attr.index, self, attr.raw );
+			const allowedAttributes = options[ tagName ];
+			const column = event.col + event.tagName.length + 1;
+			for ( const attribute of event.attrs ) {
+				if ( ! allowedAttributes[ attribute.name.toLowerCase() ] ) {
+					reporter.error(
+						`Tag attribute [${ attribute.raw }] is not allowed.`,
+						event.line,
+						column + attribute.index,
+						this,
+						attribute.raw
+					);
 				}
 			}
-		});
-	}
-});
+		} );
+	},
+} );

[westonruter]

@sirreal:

I've left some feedback mostly around the TypeScript setup. If you'd like, I'm happy to work on adjustments and push changes.

Please do! Please amend as you see fit. I'm definitely not a TypeScript expert, so your expertise is much appreciated.

Frankly, I'd like to start using TypeScript syntax directly for these files that are already being compiled/bundled where we're adding a lot of type information.

That sounds good to me. I think in this PR that would mean we could turn src/js/_enqueues/lib/codemirror/javascript-lint.js and tools/vendors/codemirror-entry.js into TypeScript files. The other JS files, namely src/js/_enqueues/lib/codemirror/htmlhint-kses.js and src/js/_enqueues/wp/code-editor.js I think should remain as JS since they should be able to be run directly in the browser. (For example, I symlink them to src/wp-includes to avoid having to run a build when I make changes, although I'm willing to concede if this is just me.)

Whether a file is TypeScript or not could also serve as the condition for whether to check types.

There is a lot of type information added to code-editor.js though, so we should be sure to add that as an allow-list of JS files that we also start type-checking. I really would like to start incrementally adding more and more of the core JS files to beying type-checked as well.