Switch type checking from mypy to Pyrefly (#1399)

Replace mypy with Pyrefly via check/typecheck, migrate config, fix a few annotations, and update CI, deps, and docs. Keep check/mypy as a deprecated wrapper.

Author: rosspeili

.github/problem-matchers/README.md

@@ -20,15 +20,19 @@ license. The version of the files at the time they were copied was 2025.1.2.
 -   [`pylint.json`](https://github.com/home-assistant/core/blob/dev/.github/workflows/matchers/pylint.json)
 -   [`yamllint.json`](https://github.com/home-assistant/core/blob/dev/.github/workflows/matchers/yamllint.json)
 
-The Mypy and Pytest problem matchers files originally came from the
+The Pytest problem matcher file originally came from the
 [gh-problem-matcher-wrap](https://github.com/liskin/gh-problem-matcher-wrap/tree/master/problem-matchers)
-repository (copied 2025-03-04, version 3.0.0), and were subsequently modified by
-Michael Hucka. The original JSON files are Copyright © 2020 Tomáš Janoušek and
+repository (copied 2025-03-04, version 3.0.0), and was subsequently modified by
+Michael Hucka. The original JSON file is Copyright © 2020 Tomáš Janoušek and
 made available under the terms of the MIT license.
 
--   [`mypy.json`](https://github.com/liskin/gh-problem-matcher-wrap/blob/master/problem-matchers/mypy.json)
 -   [`pytest.json`](https://github.com/liskin/gh-problem-matcher-wrap/blob/master/problem-matchers/pytest.json)
 
+The typecheck problem matcher matches Pyrefly's text and GitHub Actions output
+formats used by `check/typecheck`.
+
+-   [`typecheck.json`](./typecheck.json)
+
 The actionlint problem matcher JSON file came from the
 [actionlint](https://github.com/rhysd/actionlint/blob/v1.7.7/docs/usage.md)
 documentation (copied on 2025-02-12, version 1.7.7). Actionlint is made

.github/problem-matchers/mypy.json

@@ -0,0 +1,18 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "typecheck",
+      "severity": "error",
+      "pattern": [
+        {
+          "regexp": "^(?:ERROR|WARN(?:ING)?)\\s+([^:]+):(\\d+):(\\d+)(?:-\\d+)?:\\s+(.*?)(?:\\s+\\[(\\S+)\\])?$",
+          "file": 1,
+          "line": 2,
+          "column": 3,
+          "message": 4,
+          "code": 5
+        }
+      ]
+    }
+  ]
+}

.github/problem-matchers/typecheck.json

@@ -46,7 +46,7 @@ env:
   # This is used by setup-python to check whether its cache needs updating.
   python-dep-files: >-
     dev_tools/requirements/envs/format.env.txt
-    dev_tools/requirements/envs/mypy.env.txt
+    dev_tools/requirements/envs/typecheck.env.txt
     dev_tools/requirements/envs/pylint.env.txt
     dev_tools/requirements/envs/pytest-extra.env.txt
     dev_tools/requirements/envs/pytest.env.txt
@@ -83,7 +83,7 @@ jobs:
         run: |
           pip install -r dev_tools/requirements/envs/format.env.txt
           pip install -r dev_tools/requirements/envs/pylint.env.txt
-          pip install -r dev_tools/requirements/envs/mypy.env.txt
+          pip install -r dev_tools/requirements/envs/typecheck.env.txt
 
       - name: Check format
         run: |
@@ -97,8 +97,8 @@ jobs:
 
       - name: Check type declarations
         run: |
-          echo '::add-matcher::.github/problem-matchers/mypy.json'
-          check/mypy
+          echo '::add-matcher::.github/problem-matchers/typecheck.json'
+          check/typecheck --output-format github
 
   pytest:
     name: Unit tests

.github/workflows/ci.yaml

@@ -170,6 +170,14 @@ repos:
         files: \.(cc|h|cu|py)$
         stages: [pre-push]
 
+      - id: typecheck
+        name: 'check/typecheck runs without errors'
+        entry: check/typecheck
+        language: script
+        pass_filenames: false
+        types: [python]
+        stages: [pre-push]
+
   - repo: https://github.com/Pierre-Sassoulas/copyright_notice_precommit
     rev: 'd9215b6b2a028d1614c92cf43a9fcff3b1dd889e'  # frozen: 0.1.2
     hooks:

.pre-commit-config.yaml

@@ -234,13 +234,15 @@ for information about how to set up a local copy of the software for development
 ### Type annotation conventions
 
 Code should have [type annotations](https://www.python.org/dev/peps/pep-0484/). We use
-[mypy](http://mypy-lang.org/) to check that type annotations are correct, and the following script
-to run it:
+[Pyrefly](https://pyrefly.org/) to check that type annotations are correct, and the following
+script to run it:
 
 ```shell
-check/mypy
+check/typecheck
 ```
 
+(`check/mypy` remains as a deprecated wrapper that forwards to `check/typecheck`.)
+
 ### Linting and formatting
 
 Code should meet common style standards for Python and be free of error-prone constructs. We use

CONTRIBUTING.md

@@ -100,7 +100,7 @@ done
 declare -a errors=()
 declare -a pylint_j=()
 declare -a pytest_n=()
-declare -a mypy_n=()
+declare -a typecheck_j=()
 
 function run() {
     echo "~~~~ Running $* ~~~~"
@@ -112,11 +112,11 @@ function run() {
 cpus=$(python3 -c 'import psutil; print(psutil.cpu_count(logical=False))')
 
 if [[ -z "${no_parallel}" ]]; then
-    # Pylint & pytest can auto-detect the number of CPUs, but not mypy. To be
-    # consistent, this uses the same explicit number for all of them.
+    # Pylint & pytest can auto-detect the number of CPUs; pyrefly uses -j.
+    # To be consistent, this uses the same explicit number for all of them.
     pylint_j=("-j" "${cpus}")
     pytest_n=("-n" "${cpus}")
-    mypy_n=("-n" "${cpus}")
+    typecheck_j=("-j" "${cpus}")
 fi
 
 if [[ -n "${only_changed}" ]]; then
@@ -126,7 +126,7 @@ else
     run check/format-incremental "${rev[@]}" "${apply_arg[@]}" --all
     run check/pylint "${pylint_j[@]}" "${rev[@]}"
 fi
-run check/mypy "${mypy_n[@]}"
+run check/typecheck "${typecheck_j[@]}"
 run check/pytest-and-incremental-coverage "${pytest_n[@]}" "${rev[@]}"
 run check/shellcheck
 run check/nbformat

check/all

@@ -14,19 +14,18 @@
 # limitations under the License.
 
 ################################################################################
-# Runs mypy on the repository starting from the root.
+# Deprecated wrapper that forwards to check/typecheck (Pyrefly).
 #
 # Usage:
 #     check/mypy [--flags]
 ################################################################################
 
+echo "Warning: 'check/mypy' is deprecated." \
+  "Please use 'check/typecheck' instead." >&2
+echo >&2
+
 # Get the working directory to the repo root.
 cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" || exit 1
 cd "$(git rev-parse --show-toplevel)" || exit 1
 
-echo -e -n "\033[31m"
-mypy "$@" .
-result=$?
-echo -e -n "\033[0m"
-
-exit ${result}
+exec check/typecheck "$@"

check/mypy

@@ -62,6 +62,7 @@ required_shell_scripts=(
     check/pylint-changed-files
     check/pytest
     check/pytest-and-incremental-coverage
+    check/typecheck
 )
 
 scripts_not_found=$(comm -13 \

check/shellcheck

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+################################################################################
+# Runs type checking on the repository using Pyrefly.
+#
+# Usage:
+#     check/typecheck [--flags]
+################################################################################
+
+# Get the working directory to the repo root.
+cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" || exit 1
+cd "$(git rev-parse --show-toplevel)" || exit 1
+
+echo -e -n "\033[31m"
+pyrefly check "$@"
+result=$?
+echo -e -n "\033[0m"
+
+exit ${result}