Code Editor: Improve types and fix options handling to avoid double-linting at initialization.

* Refactor how CodeMirror is initialized so that the full settings are provided up-front. This avoids the linting from being applied twice at initialization, the first time with an incorrect configuration.
* Add initial TypeScript configuration for core with `npm run typecheck:js`.
* Add comprehensive types for code editor files: `code-editor.js`, `javascript-lint.js`, and `htmlhint-kses.js`.
* Move code editor scripts from `src/js/_enqueues/vendor/codemirror/` to `src/js/_enqueues/lib/codemirror/`. The CodeMirror library is sourced from the npm package as of r61539.
* Remove (deprecated) `esprima.js` from being committed to SVN since in r61539 it was switched to using the npm package as its source.
* Move `fakejshint.js` to `src/js/_enqueues/deprecated`.

Developed in WordPress#10900

Follow up to r61611, r61539.

Props westonruter, jonsurrell, justlevine.
See #64662, #48456.
Fixes #64661.


git-svn-id: https://develop.svn.wordpress.org/trunk@61800 602fd350-edb4-49c9-b593-d223f7449a82

Author: westonruter

.gitignore

@@ -24,6 +24,7 @@ wp-tests-config.php
 /tests/phpunit/build
 /wp-cli.local.yml
 /phpstan.neon
+/*.tsbuildinfo
 /jsdoc
 /composer.lock
 /vendor

Gruntfile.js

@@ -339,12 +339,19 @@ 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',
 						],
 						dest: WORKING_DIR + 'wp-includes/js/codemirror/'
+					},
+					{
+						expand: true,
+						cwd: SOURCE_DIR + 'js/_enqueues/deprecated/',
+						src: [
+							'fakejshint.js',
+						],
+						dest: WORKING_DIR + 'wp-includes/js/codemirror/'
 					}
 				]
 			},

package-lock.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",
+		"typecheck:js": "tsc --build",
 		"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",

package.json

@@ -1,6 +1,16 @@
-// JSHINT has some GPL Compatability issues, so we are faking it out and using esprima for validation
-// Based on https://github.com/jquery/esprima/blob/gh-pages/demo/validate.js which is MIT licensed
+/**
+ * JSHINT has some GPL Compatability issues, so we are faking it out and using esprima for validation
+ * Based on https://github.com/jquery/esprima/blob/gh-pages/demo/validate.js which is MIT licensed.
+ * This is now deprecated in favor of Espree.
+ *
+ * @since 4.9.3
+ * @deprecated 7.0.0
+ * @output wp-includes/js/codemirror/fakejshint.js
+ * @see https://core.trac.wordpress.org/ticket/42850
+ * @see https://core.trac.wordpress.org/ticket/64558
+ */
 
+/* jshint -W057, -W058 */
 var fakeJSHINT = new function() {
 	var syntax, errors;
 	var that = this;

…enqueues/vendor/codemirror/fakejshint.js src/js/_enqueues/deprecated/fakejshint.jssrc/js/_enqueues/vendor/codemirror/fakejshint.js renamed to src/js/_enqueues/deprecated/fakejshint.js src/js/_enqueues/vendor/codemirror/fakejshint.js renamed to src/js/_enqueues/deprecated/fakejshint.js

@@ -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/.eslintrc.json

@@ -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/lib/codemirror/htmlhint-kses.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 ) {