build(pyrefly): enable Pyrefly static type checking across Python targets

.agents/rules/python.md

@@ -13,6 +13,16 @@
 * **External Objects**: When defining a `TypedDict` for an external object,
   link to its definition in the docstring.
 
+## Type Checking & Annotations
+* **In-file disables vs target skipping**: Prefer `# pyrefly: ignore[<error-code>]`
+  (e.g. `[missing-import]`) over `tags = ["no-pyrefly"]`.
+* **No blanket ignores**: NEVER use bare `# type: ignore` or literal
+  `# type: ignore[...]`. Use error-specific ignores instead.
+* **Type assertions**: When adding assertions for type narrowing, add an
+  end-of-line comment: `assert foo is not None  # type assert`.
+* **Consent for `Any`**: Require user consent before changing type annotations
+  to `Any`.
+
 ## Delegating Functions
 * Module-level functions delegating to class methods should have a docstring
   referring to the class method (e.g. `"""Refer to \`Class.method\`."""`).

.agents/skills/analyze-ci-failure/scripts/analyze_ci_failure.py

@@ -8,7 +8,29 @@
 import urllib.request
 
 
-def fetch_log(build_id, job_id, output_path):
+def fetch_log(job_name, build_id, job_id, output_path):
+    if (
+        "readthedocs" in job_name.lower()
+        or "readthedocs" in build_id.lower()
+        or "readthedocs" in job_id.lower()
+    ):
+        rtd_match = re.search(r"(\d+)", build_id) or re.search(r"(\d+)", job_id)
+        if rtd_match:
+            rtd_id = rtd_match.group(1)
+            rtd_url = f"https://app.readthedocs.org/api/v2/build/{rtd_id}.txt"
+            print(f"📥 Downloading ReadTheDocs failure log from {rtd_url}...")
+            req = urllib.request.Request(rtd_url, headers={"User-Agent": "ci-analyzer"})
+            try:
+                with urllib.request.urlopen(req) as resp:
+                    content = resp.read()
+                    with open(output_path, "wb") as f:
+                        f.write(content)
+                return True
+            except Exception as e:
+                print(
+                    f"⚠️ Failed to download RTD log from {rtd_url}: {e}", file=sys.stderr
+                )
+
     if build_id.startswith("http"):
         log_url = build_id
     elif job_id.startswith("http"):
@@ -17,9 +39,10 @@ def fetch_log(build_id, job_id, output_path):
         log_url = f"https://buildkite.com/organizations/bazel/pipelines/rules-python-python/builds/{build_id}/jobs/{job_id}/download.txt"
 
     # Check if this is a GitHub Actions job
-    gh_match = re.search(r"github\.com/.*/job/(\d+)", log_url) or re.search(
-        r"^(\d+)$", job_id
-    )
+    gh_match = re.search(r"github\.com/.*/job/(\d+)", log_url)
+    if not gh_match and "github" in job_name.lower() and re.match(r"^\d+$", job_id):
+        gh_match = re.match(r"^(\d+)$", job_id)
+
     if gh_match:
         gh_job_id = gh_match.group(1)
         print(f"📥 Fetching GitHub Action log for job {gh_job_id} using gh CLI...")
@@ -53,6 +76,9 @@ def fetch_log(build_id, job_id, output_path):
         return False
 
 
+ANSI_ESCAPE = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+
+
 def parse_log(log_path):
     if not os.path.exists(log_path):
         return [f"Log file not found at {log_path}"]
@@ -62,28 +88,36 @@ def parse_log(log_path):
 
     errors = []
     for line in lines:
+        clean_line = ANSI_ESCAPE.sub("", line).strip()
+        # Clean buildkite timestamp prefix: _bk;t=...
+        clean_line = re.sub(r"^_bk;t=\d+\s*", "", clean_line)
         if any(
-            keyword in line
+            keyword.lower() in clean_line.lower()
             for keyword in [
-                "ERROR:",
-                "FAILED:",
-                "Critical Path",
-                "Traceback",
-                "Exception",
-                "FileNotFoundError",
+                "error:",
+                "failed:",
+                "critical path",
+                "traceback",
+                "exception",
+                "filenotfounderror",
                 "no such package",
                 "no such target",
                 "exit code",
                 "exit-code",
+                "status 125",
                 "fatal:",
                 "fatal",
                 "##[error]",
-                "Would reformat:",
+                "would reformat:",
                 "would be reformatted",
                 "error]",
+                "error waiting for container",
+                "error during connect:",
+                "user command error:",
             ]
         ):
-            errors.append(line.strip())
+            if clean_line:
+                errors.append(clean_line)
 
     return errors[:30]
 
@@ -95,8 +129,44 @@ def create_plan(job_name, log_path, errors):
         else "No obvious keyword error lines matched. Please inspect the raw log file."
     )
 
+    is_flake = False
+    flake_reason = ""
+    if any(
+        "fatal: destination path '.' already exists and is not an empty directory." in e
+        for e in errors
+    ):
+        is_flake = True
+        flake_reason = "ReadTheDocs workspace checkout race / dirty container environment where target directory is not empty (`fatal: destination path '.' already exists`). This is an infrastructure flake, not a codebase failure."
+    elif any("exit code 2" in e.lower() for e in errors) and (
+        "docs" in job_name.lower() or "readthedocs" in job_name.lower()
+    ):
+        is_flake = True
+        flake_reason = "Known docs build flake with exit code 2."
+    elif any(
+        "error waiting for container" in e.lower()
+        or "status 125" in e.lower()
+        or "error during connect:" in e.lower()
+        or "docker-buildkite-plugin command hook exited with status 125" in e.lower()
+        for e in errors
+    ):
+        is_flake = True
+        flake_reason = "Buildkite agent / Docker runner infrastructure failure (dockerd disconnection / grpc context canceled / exit status 125). This is an infrastructure flake, not a codebase bug."
+
+    classification = (
+        "⚡ **Classification**: **Infrastructure / Flake Issue** (Not a codebase bug)"
+        if is_flake
+        else "🔍 **Classification**: **Code / Configuration Issue**"
+    )
+    fix_advice = (
+        f"Retry the failed job (`buildkite-retry-job`). {flake_reason}"
+        if is_flake
+        else "Resolve the root cause in the relevant source / build files."
+    )
+
     plan = f"""# 🚨 CI Failure Analysis Report: {job_name}
 
+{classification}
+
 ## 📁 CI Log Path
 `{log_path}`
 
@@ -106,10 +176,9 @@ def create_plan(job_name, log_path, errors):
 ```
 
 ## 🛠️ Suggested Plan to Fix
-1. **Inspect Log**: Review the exact log snippets above or read the full raw log file at `{log_path}`.
-2. **Reproduce Locally**: Run `./replicate_ci "{job_name}"` or the matching `bazel build/test` command locally.
-3. **Apply Fix**: Resolve the root cause in the relevant `BUILD.bazel` or Starlark files.
-4. **Verify & Push**: Run local verification with `--config=fast-tests` and push the updated branch to trigger a clean pipeline.
+1. **Diagnosis**: {flake_reason if is_flake else "Review extracted errors."}
+2. **Action**: {fix_advice}
+3. **Verify**: Check the new build status once re-triggered.
 """
     return plan
 
@@ -131,7 +200,7 @@ def main():
     safe_jname = re.sub(r"[^a-zA-Z0-9]", "_", args.job_name)
     log_path = os.path.join(scratch_dir, f"ci_{safe_jname}_{args.job_id}.log")
 
-    fetch_log(args.build_id, args.job_id, log_path)
+    fetch_log(args.job_name, args.build_id, args.job_id, log_path)
 
     print(f"🚀 Analyzing CI failure log for '{args.job_name}' at '{log_path}'...")
     errors = parse_log(log_path)

.bazelrc

@@ -19,7 +19,9 @@ test --test_output=errors
 # Python targets as required.
 build --incompatible_default_to_explicit_init_py
 build --//python/config_settings:incompatible_default_to_explicit_init_py=True
-build --aspects=//tests/support/pyrefly:pyrefly.bzl%pyrefly_aspect
+build --config=pyrefly
+build:pyrefly --aspects=//tests/support/pyrefly:pyrefly.bzl%pyrefly_aspect
+build:pyrefly --output_groups=+pyrefly
 
 # Ensure ongoing compatibility with this flag.
 common --incompatible_disallow_struct_provider_syntax

docs/howto/debuggers.md

@@ -107,10 +107,10 @@ For the remainder of this document, we assume you are using vscode.
         # Import debugpy, provided by VS Code
         try:
             # debugpy._vendored is needed for force_pydevd to perform path manipulation.
-            import debugpy._vendored  # type: ignore[import-not-found]
+            import debugpy._vendored
 
             # pydev_monkey patches os and subprocess functions to handle new launched processes.
-            from _pydev_bundle import pydev_monkey  # type: ignore[import-not-found]
+            from _pydev_bundle import pydev_monkey
         except ImportError as exc:
             print(f"Error: This script must be run via VS Code's debug adapter. Details: {exc}")
             sys.exit(-1)

examples/wheel/main.py

@@ -12,9 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import examples.wheel.lib.module_with_data as module_with_data
-import examples.wheel.lib.module_with_type_annotations as module_with_type_annotations
-import examples.wheel.lib.simple_module as simple_module
+import examples.wheel.lib.module_with_data as module_with_data  # pyrefly: ignore[missing-import]
+import examples.wheel.lib.module_with_type_annotations as module_with_type_annotations  # pyrefly: ignore[missing-import]
+import examples.wheel.lib.simple_module as simple_module  # pyrefly: ignore[missing-import]
 
 
 def function():

examples/wheel/private/directory_writer.py

@@ -18,10 +18,9 @@
 import argparse
 import json
 from pathlib import Path
-from typing import Tuple
 
 
-def _file_input(value) -> Tuple[Path, str]:
+def _file_input(value) -> tuple[Path, str]:
     path, content = value.split("=", maxsplit=1)
     return (Path(path), json.loads(content))
 

examples/wheel/wheel_test.py

@@ -31,6 +31,7 @@ def setUp(self):
         self.runfiles = runfiles.Create()
 
     def _get_path(self, filename):
+        assert self.runfiles is not None  # type assert
         runfiles_path = os.path.join("rules_python/examples/wheel", filename)
         path = self.runfiles.Rlocation(runfiles_path)
         # The runfiles API can return None if the path doesn't exist or
@@ -110,7 +111,7 @@ def test_py_package_wheel(self):
                 ],
             )
         self.assertFileSha256Equal(
-            filename, "39bec133cf79431e8d057eae550cd91aa9dfbddfedb53d98ebd36e3ade2753d0"
+            filename, "7322902ab63fd702afb9730843496637058b5d7449208c624875d06d191d386e"
         )
 
     def test_customized_wheel(self):
@@ -155,7 +156,7 @@ def test_customized_wheel(self):
 examples/wheel/lib/module_with_type_annotations.py,sha256=2p_0YFT0TBUufbGCAR_u2vtxF1nM0lf3dX4VGeUtYq0,637
 examples/wheel/lib/module_with_type_annotations.pyi,sha256=fja3ql_WRJ1qO8jyZjWWrTTMcg1J7EpOQivOHY_8vI4,630
 examples/wheel/lib/simple_module.py,sha256=z2hwciab_XPNIBNH8B1Q5fYgnJvQTeYf0ZQJpY8yLLY,637
-examples/wheel/main.py,sha256=mFiRfzQEDwCHr-WVNQhOH26M42bw1UMF6IoqvtuDTrw,1047
+examples/wheel/main.py,sha256=THX1qSP_5NUcJrzcFFtpCO7XKFFgPpvanwZo4X_1e-o,1152
 example_customized-0.0.1.dist-info/WHEEL,sha256=sobxWSyDDkdg_rinUth-jxhXHqoNqlmNMJY3aTZn2Us,91
 example_customized-0.0.1.dist-info/METADATA,sha256=QYQcDJFQSIqan8eiXqL67bqsUfgEAwf2hoK_Lgi1S-0,559
 example_customized-0.0.1.dist-info/entry_points.txt,sha256=pqzpbQ8MMorrJ3Jp0ntmpZcuvfByyqzMXXi2UujuXD0,137
@@ -206,7 +207,7 @@ def test_customized_wheel(self):
 second = second.main:s""",
             )
         self.assertFileSha256Equal(
-            filename, "685f68fc6665f53c9b769fd1ba12cce9937ab7f40ef4e60c82ef2de8653935de"
+            filename, "6d08fbb30864cee89396e7857c910c92bec56b6586d40a64b796b4812af15fbf"
         )
 
     def test_filename_escaping(self):
@@ -278,7 +279,7 @@ def test_custom_package_root_wheel(self):
             for line in record_contents.splitlines():
                 self.assertFalse(line.startswith("/"))
         self.assertFileSha256Equal(
-            filename, "2fbfc3baaf6fccca0f97d02316b8344507fe6c8136991a66ee5f162235adb19f"
+            filename, "0b5a35251ad35fd9e14f3f7e77993f59a7341268f24fb0a255b403cee60d429e"
         )
 
     def test_custom_package_root_multi_prefix_wheel(self):
@@ -312,7 +313,7 @@ def test_custom_package_root_multi_prefix_wheel(self):
             for line in record_contents.splitlines():
                 self.assertFalse(line.startswith("/"))
         self.assertFileSha256Equal(
-            filename, "3e67971ca1e8a9ba36a143df7532e641f5661c56235e41d818309316c955ba58"
+            filename, "437127690584a035dc37542f64c38d1a6d6652655afc81f5a9472706343aae23"
         )
 
     def test_custom_package_root_multi_prefix_reverse_order_wheel(self):
@@ -346,7 +347,7 @@ def test_custom_package_root_multi_prefix_reverse_order_wheel(self):
             for line in record_contents.splitlines():
                 self.assertFalse(line.startswith("/"))
         self.assertFileSha256Equal(
-            filename, "372ef9e11fb79f1952172993718a326b5adda192d94884b54377c34b44394982"
+            filename, "265cc2ba4c99d0b62f1922f357de961f15f416bcee93ff307e4d4f04e4c067a3"
         )
 
     def test_python_requires_wheel(self):
@@ -371,7 +372,7 @@ def test_python_requires_wheel(self):
 """,
             )
         self.assertFileSha256Equal(
-            filename, "10a325ba8f77428b5cfcff6345d508f5eb77c140889eb62490d7382f60d4ebfe"
+            filename, "cb1d0bf64df1cbf23b7d4473a1c113cedbbea0d23209cdb4d2e5fe2edc68ceec"
         )
 
     def test_python_abi3_binary_wheel(self):
@@ -436,7 +437,7 @@ def test_rule_creates_directory_and_is_included_in_wheel(self):
                 ],
             )
         self.assertFileSha256Equal(
-            filename, "85e44c43cc19ccae9fe2e1d629230203aa11791bed1f7f68a069fb58d1c93cd2"
+            filename, "2358a8ee58dd7ed1a89862e368a0eb00e83ec5de28995ecf0f3c38c2524102dc"
         )
 
     def test_rule_expands_workspace_status_keys_in_wheel_metadata(self):

python/bin/repl_stub.py

@@ -57,9 +57,10 @@ def complete(self, text, state):
 
     # TODO(jpwoodbu): Use readline.backend instead of readline.__doc__ once we can depend on having
     # Python >=3.13.
-    if "libedit" in readline.__doc__:  # type: ignore
+    doc = readline.__doc__ or ""
+    if "libedit" in doc:
         readline.parse_and_bind("bind ^I rl_complete")
-    elif "GNU readline" in readline.__doc__:  # type: ignore
+    elif "GNU readline" in doc:
         readline.parse_and_bind("tab: complete")
     else:
         print("Could not enable tab completion: unable to determine readline backend")

python/private/py_console_script_gen.py

@@ -59,7 +59,7 @@
     raise
 
 if __name__ == "__main__":
-    sys.exit({entry_point}())  # type: ignore
+    sys.exit({entry_point}())  # pyrefly: ignore[not-callable]
 """
 
 
@@ -69,10 +69,11 @@ class EntryPointsParser(configparser.ConfigParser):
     See https://packaging.python.org/en/latest/specifications/entry-points/
     """
 
-    optionxform = staticmethod(str)
+    def optionxform(self, optionstr: str) -> str:
+        return str(optionstr)
 
 
-def _guess_entry_point(guess: str, console_scripts: dict[string, string]) -> str | None:  # noqa: F821
+def _guess_entry_point(guess: str, console_scripts: dict[str, str]) -> str | None:
     for key, candidate in console_scripts.items():
         if guess == key:
             return candidate
@@ -82,7 +83,7 @@ def run(
     *,
     entry_points: pathlib.Path,
     out: pathlib.Path,
-    console_script: str,
+    console_script: str | None,
     console_script_guess: str,
     shebang: str,
 ):