Code Editor: Improve types and options handling

Gruntfile.js

@@ -340,7 +340,7 @@ module.exports = function(grunt) {
 					},
 					{
 						expand: true,
-						cwd: SOURCE_DIR + 'js/_enqueues/vendor/codemirror/',
+						cwd: SOURCE_DIR + 'js/_enqueues/lib/codemirror/',
 						src: [
 							'fakejshint.js',
 							'htmlhint-kses.js',

package.json

@@ -31,6 +31,10 @@
 		"@playwright/test": "1.56.1",
 		"@pmmmwh/react-refresh-webpack-plugin": "0.6.1",
 		"@types/codemirror": "5.60.17",
+		"@types/espree": "10.1.0",
+		"@types/htmlhint": "1.1.5",
+		"@types/jquery": "3.5.33",
+		"@types/underscore": "1.11.15",
 		"@wordpress/e2e-test-utils-playwright": "1.33.2",
 		"@wordpress/prettier-config": "4.33.1",
 		"@wordpress/scripts": "30.26.2",
@@ -69,6 +73,7 @@
 		"sinon-test": "~3.1.6",
 		"source-map-loader": "5.0.0",
 		"terser-webpack-plugin": "5.3.14",
+		"typescript": "5.9.3",
 		"uuid": "13.0.0",
 		"wait-on": "9.0.3",
 		"webpack": "5.98.0"
@@ -115,6 +120,7 @@
 		"grunt": "grunt",
 		"lint:jsdoc": "wp-scripts lint-js",
 		"lint:jsdoc:fix": "wp-scripts lint-js --fix",
+		"static-analysis:js": "tsc",
 		"env:start": "node ./tools/local-env/scripts/start.js && node ./tools/local-env/scripts/docker.js run -T --rm php composer update -W",
 		"env:stop": "node ./tools/local-env/scripts/docker.js down",
 		"env:restart": "npm run env:stop && npm run env:start",

src/js/_enqueues/lib/codemirror/.eslintrc.json

@@ -0,0 +1,17 @@
+{
+	"overrides": [
+		{
+			"files": [ "javascript-lint.js" ],
+			"parserOptions": {
+				"sourceType": "module",
+				"ecmaVersion": 2020
+			}
+		},
+		{
+			"files": [ "htmlhint-kses.js" ],
+			"parserOptions": {
+				"ecmaVersion": 2020
+			}
+		}
+	]
+}

src/js/_enqueues/lib/codemirror/htmlhint-kses.js

@@ -0,0 +1,47 @@
+/* global HTMLHint */
+/* eslint no-magic-numbers: ["error", { "ignore": [1] }] */
+HTMLHint.addRule( {
+	id: 'kses',
+	description: 'Element or attribute cannot be used.',
+
+	/**
+	 * 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';
+
+		parser.addListener( 'tagstart', ( event ) => {
+			const tagName = event.tagName.toLowerCase();
+			if ( ! options[ tagName ] ) {
+				reporter.error(
+					`Tag <${ event.tagName }> is not allowed.`,
+					event.line,
+					event.col,
+					this,
+					event.raw
+				);
+				return;
+			}
+
+			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
+					);
+				}
+			}
+		} );
+	},
+} );

src/js/_enqueues/vendor/codemirror/javascript-lint.js → src/js/_enqueues/lib/codemirror/javascript-lint.js

@@ -25,7 +25,7 @@ import CodeMirror from 'codemirror';
  * @see https://www.npmjs.com/package/espree#options
  *
  * @typedef {Object} SupportedJSHintOptions
- * @property {number} [esversion] - "This option is used to specify the ECMAScript version to which the code must adhere."
+ * @property {import('espree').Options['ecmaVersion']} [esversion] - "This option is used to specify the ECMAScript version to which the code must adhere."
  * @property {boolean} [es5] - "This option enables syntax first defined in the ECMAScript 5.1 specification. This includes allowing reserved keywords as object properties."
  * @property {boolean} [es3] - "This option tells JSHint that your code needs to adhere to ECMAScript 3 specification. Use this option if you need your program to be executable in older browsers—such as Internet Explorer 6/7/8/9—and other legacy JavaScript environments."
  * @property {boolean} [module] - "This option informs JSHint that the input code describes an ECMAScript 6 module. All module code is interpreted as strict mode code."
@@ -50,19 +50,20 @@ async function validator( text, options ) {
 			loc: true,
 		} );
 	} catch ( error ) {
+		const enhancedError = /** @type {Error & { lineNumber?: number, column?: number }} */ ( error );
 		if (
 			// This is an `EnhancedSyntaxError` in Espree: <https://github.com/brettz9/espree/blob/3c1120280b24f4a5e4c3125305b072fa0dfca22b/packages/espree/lib/espree.js#L48-L54>.
 			error instanceof SyntaxError &&
-			typeof error.lineNumber === 'number' &&
-			typeof error.column === 'number'
+			typeof enhancedError.lineNumber === 'number' &&
+			typeof enhancedError.column === 'number'
 		) {
-			const line = error.lineNumber - 1;
-			errors.push( {
+			const line = enhancedError.lineNumber - 1;
+			errors.push( /** @type {CodeMirrorLintError} */ ( {
 				message: error.message,
 				severity: 'error',
-				from: CodeMirror.Pos( line, error.column - 1 ),
-				to: CodeMirror.Pos( line, error.column ),
-			} );
+				from: CodeMirror.Pos( line, enhancedError.column - 1 ),
+				to: CodeMirror.Pos( line, enhancedError.column ),
+			} ) );
 		} else {
 			console.warn( '[CodeMirror] Unable to lint JavaScript:', error ); // jshint ignore:line
 		}
@@ -80,13 +81,15 @@ CodeMirror.registerHelper( 'lint', 'javascript', validator );
  *
  * @param {SupportedJSHintOptions} options - Linting options for JSHint.
  * @return {{
- *     ecmaVersion?: number|'latest',
+ *     ecmaVersion?: import('espree').Options['ecmaVersion'],
+ *     sourceType?: 'module'|'script',
  *     ecmaFeatures?: {
  *         impliedStrict?: true
  *     }
  * }}
  */
 function getEspreeOptions( options ) {
+	/** @type {{ impliedStrict?: true }} */
 	const ecmaFeatures = {};
 	if ( options.strict === 'implied' ) {
 		ecmaFeatures.impliedStrict = true;
@@ -105,10 +108,10 @@ function getEspreeOptions( options ) {
  * @since 7.0.0
  *
  * @param {SupportedJSHintOptions} options - Options.
- * @return {number|'latest'} ECMAScript version.
+ * @return {import('espree').Options['ecmaVersion']} ECMAScript version.
  */
 function getEcmaVersion( options ) {
-	if ( typeof options.esversion === 'number' ) {
+	if ( options.esversion ) {
 		return options.esversion;
 	}
 	if ( options.es5 ) {