Add TypeScript static analysis for core JavaScript files

[westonruter]

For #64661, a ​PR is proposed which adds TypeScript checking for the scripts related to the CodeMirror code editor integrations. With that in place, core should start expanding the scope of which JS files are checked to ensure code quality and fix subtle bugs. The same is being done for PHP with PHPStan in #61175.

Note that TypeScript is already being used in Gutenberg. See ​https://make.wordpress.org/core/2021/03/18/proposal-native-typescript-support-in-gutenberg/

To do:

1. Commit ​https://github.com/WordPress/wordpress-develop/pull/10900
2. Add typecheck:js to the precommit Grunt task.
3. Add GHA workflow which runs typecheck:js

[westonruter]

PHPStan static analysis (exposed via npm run typecheck:php and composer phpstan) has landed in r61699.

[westonruter]

In 61800:

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 ​https://github.com/WordPress/wordpress-develop/pull/10900

Follow up to r61611, r61539.

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

This introduces a new GitHub Action workflow for JavaScript type checking, mirroring the implementation for PHPStan. It also adds a typecheck:js Grunt task and includes it in the precommit:js task list.

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

## Use of AI Tools

Initial commit authored by Gemini CLI with prompt:

Take a look at https://core.trac.wordpress.org/ticket/64662 and implement. You can see that typecheck:js npm script was added in b6c1bb776b360ef64a00468e6df72792511866d3. Similarly, you can see in 8a82e67cf65766fcb8a11e3fe5c6e2f48083fcdb how typecheck:php was introduced for PHPStan and a GitHub action was added to automatically run. What was done for PHPStan, implement similarly for TypeScript.

Difference between reusable-phpstan-static-analysis.yml and reusable-javascript-type-checking.yml:

.github/workflows/

@@ -1 +1 @@
 ##
-# A reusable workflow that runs PHP Static Analysis tests.
+# A reusable workflow that runs .
 ##
-name: PHP Static Analysis
+name: 
 
 on:
   workflow_call:
-    inputs:
-      php-version:
-        description: 'The PHP version to use.'
-        required: false
-        type: 'string'
-        default: 'latest'
 
 # Disable permissions for all available scopes by default.
 # Any needed permissions should be configured at the job level.
 permissions: {}
 
 jobs:
-  # Runs PHP static analysis tests.
+  # Runs .
   #
   # Violations are reported inline with annotations.
   #
   # Performs the following steps:
   # - Checks out the repository.
-  # - Sets up PHP.
+  # - Sets up .
   # - Logs debug information.
-  # - Installs Composer dependencies.
-  # - Configures caching for PHP static analysis scans.
-  # - Make Composer packages available globally.
-  # - Runs PHPStan static analysis (with Pull Request annotations).
-  # - Saves the PHPStan result cache.
+  # - Installs npm dependencies.
+  # - Configures caching for TypeScript build info.
+  # - Runs JavaScript type checking.
+  # - Saves the TypeScript build info.
   # - Ensures version-controlled files are not modified or deleted.
-  phpstan:
-    name: Run PHP static analysis
+  :
+    name: Run 
     runs-on: ubuntu-24.04
     permissions:
       contents: read
@@ -51 +44 @@
           node-version-file: '.nvmrc'
           cache: npm
 
-      - name: Set up PHP
-        uses: shivammathur/setup-php@20529878ed81ef8e78ddf08b480401e6101a850f # v2.35.3
-        with:
-          php-version: ${{ inputs.php-version }}
-          coverage: none
-          tools: cs2pr
-
-      # This date is used to ensure that the Composer cache is cleared at least once every week.
-      # http://man7.org/linux/man-pages/man1/date.1.html
-      - name: "Get last Monday's date"
-        id: get-date
-        run: echo "date=$(/bin/date -u --date='last Mon' "+%F")" >> "$GITHUB_OUTPUT"
-
-      - name: General debug information
+      - name: Log debug information
         run: |
           npm --version
           node --version
-          composer --version
 
-      # Since Composer dependencies are installed using `composer update` and no lock file is in version control,
-      # passing a custom cache suffix ensures that the cache is flushed at least once per week.
-      - name: Install Composer dependencies
-        uses: ramsey/composer-install@3cf229dc2919194e9e36783941438d17239e8520 # v3.1.1
-        with:
-          custom-cache-suffix: ${{ steps.get-date.outputs.date }}
-
-      - name: Make Composer packages available globally
-        run: echo "${PWD}/vendor/bin" >> "$GITHUB_PATH"
-
       - name: Install npm dependencies
         run: npm ci --ignore-scripts
 
-      - name: Build WordPress
-        run: npm run build:dev
-
-      - name: Cache PHP Static Analysis scan cache
+      - name: Cache TypeScript build info
         uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
-          path: .cache # This is defined in the base.neon file.
-          key: "phpstan-result-cache-${{ github.run_id }}"
+          path: |
+            *.tsbuildinfo
+          key: "ts-build-info-${{ github.run_id }}"
           restore-keys: |
-            phpstan-result-cache-
+            -
 
-      - name: Run PHP static analysis tests
-        id: phpstan
-        run: composer run phpstan -- -vvv --error-format=checkstyle | cs2pr --errors-as-warnings --graceful-warnings
+      - name: Run JavaScript type checking
+        run: npm run typecheck:js
 
       - name: "Save result cache"
         uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         if: ${{ !cancelled() }}
         with:
-          path: .cache
-          key: "phpstan-result-cache-${{ github.run_id }}"
+          path: |
+            *.tsbuildinfo
+          key: "ts-build-info-${{ github.run_id }}"
 
       - name: Ensure version-controlled files are not modified or deleted
         run: git diff --exit-code

Difference between .github/workflows/phpstan-static-analysis.yml and .github/workflows/javascript-type-checking.yml:

.github/workflows/

@@ -1 @@
-name: PHPStan Static Analysis
+name: 
 
 on:
-  # PHPStan testing was introduced in 7.0.0.
+  # ing was introduced in 7.0.0.
   push:
     branches:
       - trunk
@@ -14 +14 @@
       - trunk
       - '[7-9].[0-9]'
     paths:
-      # This workflow only scans PHP files.
-      - '**.php'
-      # These files configure Composer. Changes could affect the outcome.
-      - 'composer.*'
-      # These files configure PHPStan. Changes could affect the outcome.
-      - 'phpstan.neon.dist'
-      - 'tests/phpstan/base.neon'
-      - 'tests/phpstan/baseline.php'
+      # This workflow only scans JavaScript files.
+      - '**.js'
+      # These files configure npm. Changes could affect the outcome.
+      - 'package*.json'
+      - '.nvmrc'
+      # This file configures TypeScript. Changes could affect the outcome.
+      - 'tsconfig.json'
+      # This directory contains TypeScript definitions. Changes could affect the outcome.
+      - 'typings/**'
       # Confirm any changes to relevant workflow files.
-      - '.github/workflows/phpstan-static-analysis.yml'
-      - '.github/workflows/reusable-phpstan-static-analysis.yml'
+      - '.github/workflows/.yml'
+      - '.github/workflows/reusable-.yml'
   workflow_dispatch:
 
 # Cancels all previous workflow runs for pull requests that have not completed.
@@ -39 +40 @@
 permissions: {}
 
 jobs:
-  # Runs PHPStan Static Analysis.
-  phpstan:
-    name: PHP static analysis
-    uses: ./.github/workflows/reusable-phpstan-static-analysis.yml
+  # Runs .
+  :
+    name: 
+    uses: ./.github/workflows/reusable-.yml
     permissions:
       contents: read
     if: ${{ github.repository == 'WordPress/wordpress-develop' || ( github.event_name == 'pull_request' && github.actor != 'dependabot[bot]' ) }}
@@ -53 +54 @@
     permissions:
       actions: read
       contents: read
-    needs: [ phpstan ]
+    needs: [  ]
     if: ${{ github.repository == 'WordPress/wordpress-develop' && github.event_name != 'pull_request' && always() }}
     with:
       calling_status: ${{ contains( needs.*.result, 'cancelled' ) && 'cancelled' || contains( needs.*.result, 'failure' ) && 'failure' || 'success' }}
@@ -81 +82 @@
 
     steps:
       - name: Dispatch workflow run
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        uses: actions/github-script@
         with:
           retries: 2
           retry-exempt-status-codes: 418

When a TypeScript error occurs (e.g. d2ad278), the ​job fails as expected:

And the errors are annotated in the PR:

This is in contrast with PHPStan's analysis which does _not_ fail its job when there are errors, but instead the errors are annotated as warnings.

I think this is fine given that TypeScript checking is being incrementally added to files on an opt-in basis. (Personally I would have wanted PHPStan errors to also cause jobs to fail with error annotations.)

[westonruter]

​PR is ready for review.

Also, running npx grunt precommit:js with d2ad278 staged:

...

[westonruter]

In 61830:

Build/Test Tools: Integrate TypeScript into the core development workflow.

This introduces a new GitHub Action workflow for JavaScript type checking, mirroring the implementation for PHPStan in #61175. It also adds a typecheck:js Grunt task and includes it in the precommit:js task list. Only files related to the code editor are initially checked with TypeScript, with the expectation that additional files will be added to the files list in tsconfig.json as a part of ongoing maintenance work, for example #64238 and #64226.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11131

Follow up to r61699, r61800, r61539.

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

[desrosj]

Thanks for this, everyone!

I have a few small points of feedback for a follow up commit. Can the reusable workflow file be renamed to include a -v1 suffix? Initially only the PHPUnit reusable workflow contained the -v1 suffix, but all new ones introduced since then have included it.

I know it's inconsistent, but I would like to update all the others eventually. It's just a pain to backport to every single branch calling the file. I do plan to try and tackle that the next time a given workflow requires a new -v2 file.

It just makes it more apparent which one is the most recent. It's reasonable to assume that the file without any suffix is the current or active version and all with a suffix are old.

( github.event_name == 'pull_request' && github.actor != 'dependabot[bot]' )

Can we remove the dependabot check here? The bot was deactivated in [61049] because it stopped working when GitHub switched over to their new runner architecture, and all bot specific checks were removed in [61050].

If we ever decide to try and get that working again, we can re-add this check with the others.

[westonruter]

@desrosj Would this also apply to the new PHPStan reusable workflow .github/workflows/reusable-phpstan-static-analysis.yml added in #61175?

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

• Add -v1 suffix to reusable workflows for JavaScript type checking and PHPStan analysis: This follows the established convention of including a version suffix for reusable workflow files, ensuring consistency with other workflows like PHPUnit.
• Remove Dependabot exclusion from type checking workflows: Since Dependabot was deactivated in b60c06c67e4a5a2b1351cb8bb54ed4cdd2e8e49e and other bot-specific checks were removed in 26230c33261cf559907a90547b4827ea66ff9f30, this exclusion is no longer necessary.

## Use of AI Tools

Feedback from @desrosj fed into Gemini CLI to implement.