CodeMirror: Esprima to Espree for JavaScript validation

[westonruter]

This is a sub-PR off of:

• Upgrade CodeMirror to latest v5 WordPress/wordpress-develop#10778

See Gemini summary below: #4 (comment)

Squashed commits WordPress#10778

git log 1535b0c0ac775457ade8da3b16c5181f76b5638b...3048f370efd62fbf873583939b8126f02a15c2d4 --reverse --no-merges --not trunk

1. ee2b6bd Editor: Switch from Esprima to Espree for JavaScript validation.

   Replaces the outdated esprima parser with espree to provide support for modern JavaScript (ES6+) validation in the code editor. A new espree script handle is registered, and the fakejshint wrapper is updated to use it while maintaining the esprima handle for backward compatibility.

   • Adds espree to package.json.
   • Creates tools/vendors/espree-entry.js and adds a new Webpack entry point to bundle espree.
   • Updates fakejshint.js to utilize window.espree.parse with ES6+ support.
   • Registers espree in script-loader.php and updates jshint handle dependencies.
   • Updates PHPUnit test data provider to include espree.

   Co-authored-by: Gemini

2. 744f1c3 Omit CodeMirror license banner from Espree script

   Co-authored-by: Copilot

3. cf742fa Build Tools: Target specific usebanner tasks in build processes.

   Updates build:css to specifically invoke usebanner:files and build:codemirror to invoke usebanner:codemirror. This prevents the generic usebanner task from attempting to process files that have not yet been generated during the general CSS build phase.

   Co-authored-by: Gemini, Copilot

4. 7db8792 Fix formatting of codemirror.config.js

   Co-authored-by: Copilot

5. 3d58f09 Use core version for jshint (fakejshint.js) since not an external dependency.

   Co-authored-by: Copilot

6. 6bc559f Remove duplicate extractComments key

   Unprops Copilot for 7db8792

   Co-authored-by: Copilot

7. ee0d1ec Add line break at EOF

8. 676b088 Remove esprima-specific tolerant error collection (which espree does not support)

9. d3d5a56 Modernize fakejshint

   Remove extraneous new to fix JSHint: Weird construction. Is 'new' necessary? (W057)

10. 1b15d2c Add typing and encapsulate in IIFE

11. a88a606 Refactor fake-JSHint to pass esversion and better support Espree options

12. 2263035 Improve jsdoc

13. b48e38a Fix options handling in fakejshint.js.

    Updates the fakejshint.js vendor shim to correctly store the provided options in currentOptions during parsing. Previously, fakeJSHINT.data().options would always return the initial empty object, failing to reflect the actual configuration used.

    This commit also:

    • Simplifies control flow in getEcmaVersion() by removing unnecessary else blocks.
    • Corrects a spelling error in the file header.
    • Updates JSDoc to correctly mark the options parameter as optional.

    Co-authored-by: Gemini

14. 90551e7 Add link to JSHint API docs

15. 09e7731 Add use strict

16. fc23471 Eliminate needless enumeration of numbers in esversion

17. 534b297 Add missing boolean return for JSHINT for whether valid

    Co-authored-by: Gemini

18. 3048f37 Ensure generic Espree error results in warning logged to console

[gemini-code-assist]

Code Review

This pull request successfully migrates the JavaScript validation from Esprima to Espree, which is a significant improvement for supporting modern JavaScript (ES6+). The changes are well-structured, including updates to package.json, a complete rewrite of fakejshint.js to use Espree's API, and necessary adjustments to Webpack configuration and script loading. The introduction of JSDoc comments and the use of modern JavaScript practices in fakejshint.js enhance code readability and maintainability. The updated JSHint options in general-template.php correctly reflect the new Espree capabilities and include essential global variables for modern environments.

[westonruter]

• Open new PR to upstream via WordPress/wordpress-develop@trunk...westonruter:wordpress-develop:trac-48456-codemirror-v5-upgrade-espree
• Use ES Module instead of script for Espree.

[westonruter]

/gemini summary

[gemini-code-assist]

Summary of Changes

This pull request significantly upgrades the JavaScript validation capabilities within the CodeMirror editor by transitioning from the legacy esprima parser to the more modern espree. This change ensures that the editor can accurately lint and validate contemporary JavaScript syntax, greatly enhancing the development experience. The update involves a comprehensive overhaul of the JavaScript linting integration, including new build configurations, updated dependency management, and refined error reporting, all while maintaining a degree of backward compatibility where necessary.

Highlights

• Core Parser Migration: Replaced the legacy esprima parser with espree for JavaScript validation within the CodeMirror editor, enabling support for modern ECMAScript (ES6+) syntax.
• fakejshint.js Modernization: The fakejshint.js shim was extensively refactored to integrate espree, correctly handle JSHint options, convert Espree errors into CodeMirror's linting format, and improve code quality with JSDoc, typing, and modern JavaScript practices.
• Build System Integration: espree was added as a new dependency in package.json, configured in Webpack to be bundled as a separate ES module (espree.min.js), and registered in script-loader.php and script-modules.php for proper loading via import maps.
• JSHint Configuration Updates: The default JSHint configuration in general-template.php was updated to specify esversion: 10 and include additional global variables, while acknowledging that many traditional JSHint options are not directly supported by Espree.
• CodeMirror Linting Adaptation: A new javascript-lint.js file was introduced to provide a CodeMirror linting helper that dynamically imports espree and processes its parsing errors into a format consumable by CodeMirror's linting addon.
• Dependency Management Refinement: esprima and the original jshint (which relied on esprima) are now marked as deprecated in script-loader.php, and jshint is no longer unconditionally enqueued for PHP or JSON/TypeScript files. PHPUnit tests for script dependencies were also updated to reflect the new JSHint options.

Changelog

• package.json
  • Added espree version 9.6.1 as a new dependency.
• src/js/_enqueues/vendor/codemirror/javascript-lint.js
  • New file: Implements a CodeMirror linting helper that uses espree for JavaScript parsing and error reporting.
  • Dynamically imports espree to perform syntax validation.
  • Converts espree parsing errors into CodeMirror's linting format, including line, column, and message.
  • Includes logic to map JSHint-style options (esversion, es5, es3, module, strict) to espree's ecmaVersion and sourceType.
• src/wp-includes/general-template.php
  • Enqueued wp-codemirror script module to ensure espree is available via import map.
  • Removed unconditional jshint enqueue for text/x-php and application/ld+json, text/typescript, application/typescript modes.
  • Updated default jshint options: changed es3 to esversion: 10 and added several new global variables (export, module, require, WorkerGlobalScope, self, OffscreenCanvas, Promise).
  • Removed onevar and trailing options from default JSHint configuration, noting that many options are not supported by Espree.
• src/wp-includes/script-loader.php
  • Added comments marking esprima and jshint as deprecated, suggesting the use of the espree script module.
• src/wp-includes/script-modules.php
  • Registered espree as a new script module, pointing to espree.min.js.
  • Registered wp-codemirror as a script module with espree as a dynamic import dependency, facilitating its loading via import maps.
• tests/phpunit/tests/dependencies/scripts.php
  • Updated test data providers for wp_enqueue_code_editor to reflect changes in JSHint options: es3 replaced with esversion, onevar and trailing removed.
  • Added espree to the list of excluded packages in get_package_json_dependencies to prevent it from being incorrectly registered as a classic script.
• tools/vendors/codemirror-entry.js
  • Modified the import path for javascript-lint to point to the new custom implementation (../../src/js/_enqueues/vendor/codemirror/javascript-lint).
• tools/vendors/espree-entry.js
  • New file: Simple entry point to export all from espree for Webpack bundling.
• tools/webpack/codemirror.config.js
  • Refactored Webpack configuration to support multiple entry points and outputs.
  • Configured codemirror.min.js as one output and introduced espree.min.js as a separate ES module output.
  • Removed jshint from externals as it's no longer directly used by the CodeMirror linting addon.
  • Adjusted optimization.minimize to !true (effectively false) for both codemirrorConfig and espreeConfig.

Activity

• The gemini-code-assist[bot] provided an initial summary of the changes in the pull request.
• The author, westonruter, listed two follow-up action items: opening a new PR upstream and ensuring Espree is used as an ES Module.
• The author, westonruter, requested another summary from the bot.

[westonruter]

Closing in favor of WordPress#10806