feat(whl_install): enable path mapping for remote cache deduplication (#906)

## Summary

Adds `supports-path-mapping: "1"` to the `WhlInstall` action, allowing
remote build systems to deduplicate wheel installation actions across
configurations that differ only in their config segment (e.g. different
`--compilation_mode` values that don't affect installed wheel content).

Path mapping requires that file arguments are passed as `File` objects
to `ctx.actions.args` rather than `.path` strings — Bazel cannot rewrite
string literals when computing the remote cache key. This PR switches
all file arguments accordingly:

- `install_dir` and `archive` passed as `File` objects via `args.add()`
- Patch files switched from `for f in patch_files: args.add("--patch",
f.path)` to `args.add_all(patch_files, before_each = "--patch")`
- `exec_runtime.interpreter` was already passed as a `File` object

Also adds `mnemonic = "WhlInstall"` for clearer identification in build
output and remote cache tooling.

## Compatibility

`supports-path-mapping` is a no-op unless the user opts in with
`--experimental_output_paths=strip`, so this is safe for all existing
users.

The known Bazel tree-artifact + path-mapping bug
(bazelbuild/bazel#23681) was specific to C++ header discovery and was
fixed in Bazel 7.4.0. There are no known issues with `declare_directory`
outputs in Starlark actions.

One edge case to be aware of: Bazel silently produces wrong results when
a path-mapped action runs under a local/unsandboxed execution strategy
(bazelbuild/bazel#28910). Users who override
`--strategy=WhlInstall=local` should not use
`--experimental_output_paths=strip`.

## Test plan

- [x] Existing e2e suite passes (patching, compile_pyc, crossbuild
tests)

Author: gregmagolan

e2e/.bazelrc

@@ -8,3 +8,8 @@ common --repo_env=BAZEL_NO_APPLE_CPP_TOOLCHAIN=1
 
 # Configure a default venv
 # common --@pypi//venv=say
+
+# Enable path mapping so WhlInstall actions are exercised with
+# supports-path-mapping. Actions that declare the execution requirement get
+# configuration-stripped cache keys; those that don't still work normally.
+build --experimental_output_paths=strip

uv/private/whl_install/rule.bzl

@@ -11,28 +11,32 @@ def _whl_install(ctx):
         "install",
     )
 
-    archive = ctx.attr.src[DefaultInfo].files.to_list()[0]
+    archive = ctx.file.src
 
     arguments = ctx.actions.args()
-    arguments.add_all([
-        "--into",
-        install_dir.path,
-        "--wheel",
-        archive.path,
-        "--python-version-major",
-        py_toolchain.interpreter_version_info.major,
-        "--python-version-minor",
-        py_toolchain.interpreter_version_info.minor,
-    ])
+
+    # Pass File objects (not .path strings) so Bazel can rewrite paths for
+    # remote-cache deduplication when supports-path-mapping is set.
+    #
+    # Both install_dir and archive may be tree artifacts (install_dir is always
+    # a declare_directory; archive is a tree when src is a directory containing
+    # a single wheel). Args#add rejects directories
+    # outright; Args#add_all with expand_directories=False passes the directory
+    # path itself without enumerating its contents.
+    # https://bazel.build/versions/7.1.0/rules/lib/builtins/Args#add
+    # https://bazel.build/versions/7.1.0/rules/lib/builtins/Args#add_all
+    arguments.add_all([install_dir], expand_directories = False, before_each = "--into")
+    arguments.add_all([archive], expand_directories = False, before_each = "--wheel")
+    arguments.add("--python-version-major", py_toolchain.interpreter_version_info.major)
+    arguments.add("--python-version-minor", py_toolchain.interpreter_version_info.minor)
 
     transitive_inputs = [depset([archive])]
 
     # Patch application (happens before pyc compilation).
     patch_files = [f for t in ctx.attr.patches for f in t[DefaultInfo].files.to_list()]
     if patch_files:
         arguments.add("--patch-strip", str(ctx.attr.patch_strip))
-        for f in patch_files:
-            arguments.add("--patch", f.path)
+        arguments.add_all(patch_files, before_each = "--patch")
         transitive_inputs.append(depset(patch_files))
 
     # Optional .pyc pre-compilation (runs after patching).
@@ -52,13 +56,17 @@ def _whl_install(ctx):
     # to use unpack in crossbuild scenarios.
     unpack = ctx.attr._unpack[platform_common.ToolchainInfo].bin.bin
     ctx.actions.run(
+        mnemonic = "WhlInstall",
         executable = unpack,
         arguments = [arguments],
         inputs = depset(transitive = transitive_inputs),
         outputs = [
             install_dir,
         ],
         use_default_shell_env = bool(patch_files),
+        execution_requirements = {
+            "supports-path-mapping": "1",
+        },
     )
 
     return [
@@ -100,7 +108,10 @@ to bypass some of the platform checks that UV does to enable crossbuilds, and is
 lighter weight since the toolchain's files aren't inputs.
 """,
     attrs = {
-        "src": attr.label(doc = "The wheel to install, or a tree artifact containing exactly one wheel at its root."),
+        "src": attr.label(
+            allow_single_file = True,
+            doc = "The wheel to install, or a tree artifact containing exactly one wheel at its root.",
+        ),
         "patches": attr.label_list(
             default = [],
             allow_files = [".patch", ".diff"],