Describe Apple helper and action contracts

.github/sty/rules_cc.MODULE.bazel

@@ -0,0 +1,7 @@
+# TODO(https://github.com/bazelbuild/rules_cc/pull/940): Remove this override once
+# the selected rules_cc release annotates framework_includes and compilation_context.
+single_version_override(
+    module_name = "rules_cc",
+    patch_strip = 1,
+    patches = ["//:.github/sty/rules_cc.patch"],
+)

.github/sty/rules_cc.patch

@@ -0,0 +1,20 @@
+diff --git a/cc/private/cc_common.bzl b/cc/private/cc_common.bzl
+index 4533f7f..2d005ec 100644
+--- a/cc/private/cc_common.bzl
++++ b/cc/private/cc_common.bzl
+@@ -253,3 +253,5 @@ def _create_compilation_context(
+         quote_includes = None,
+-        framework_includes = None,
++        # TODO(https://github.com/bazelbuild/bazel/issues/32021): make this an
++        # annotation when supported Bazel versions expose element-typed depsets.
++        framework_includes = None,  # type: depset[str] | None
+         defines = None,
+diff --git a/cc/private/cc_info.bzl b/cc/private/cc_info.bzl
+index 76eca95..7d6a599 100644
+--- a/cc/private/cc_info.bzl
++++ b/cc/private/cc_info.bzl
+@@ -322,3 +322,3 @@ def _create_cc_info(
+         *,
+-        compilation_context = None,
++        compilation_context = None,  # type: CcCompilationContextInfo | None
+         linking_context = None,

.github/workflows/sty.yml

@@ -0,0 +1,71 @@
+name: Starlark types
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  sty:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Prepare C++ annotations
+        env:
+          USE_BAZEL_VERSION: '9.3.0'
+        shell: bash
+        run: |
+          expected=rules_cc@0.2.26
+          selected=$(bazelisk mod show_repo rules_cc --output=streamed_jsonproto | jq -r .moduleKey)
+          if [[ "$selected" != "$expected" ]]; then
+            echo "The advisory annotations cover $expected; Bazel selected $selected." >&2
+            exit 1
+          fi
+          cat .github/sty/rules_cc.MODULE.bazel >> MODULE.bazel
+      - uses: tamird/sty@sty-action-v0.2.0
+        with:
+          audit-loads: true
+          advisory-pathspecs: '*.bzl'
+          bazel-version: '9.3.0'
+          files: |
+            @bazel_skylib//lib:shell.bzl
+            configs/platforms.bzl
+            crosstool/osx_cc_configure.bzl
+            crosstool/setup.bzl
+            crosstool/setup_internal.bzl
+            crosstool/universal_exec_tool.bzl
+            lib/missing_platform_fallback_users.bzl
+            lib/private/toolchain_flags.bzl
+            lib/providers.bzl
+            lib/xcode_support.bzl
+            rules/apple_genrule.bzl
+            rules/private/apple_genrule.bzl
+            rules/rules.doc.bzl
+            rules/toolchain_substitution.bzl
+            rules/universal_binary.bzl
+            test/apple_support_test.bzl
+            test/binary_tests.bzl
+            test/rules/apple_verification_test.bzl
+            test/test_data/framework_includes_provider.bzl
+            test/universal_binary_test.bzl
+            toolchain/dynamic_toolchain_info.bzl
+            toolchain/toolchain_env.bzl
+            tools/http_dmg/http_dmg.bzl
+            tools/http_dmg/private/tests/http_dmg_test_deps.bzl
+            tools/http_dmg/private/tests/http_dmg_test_extensions.bzl
+            tools/http_dmg/private/zip7.bzl
+            xcode/available_xcodes.bzl
+            xcode/private/providers.bzl
+            xcode/xcode_configure.bzl
+            xcode/xcode_sdk_variant.bzl
+            xcode/xcode_version.bzl

MODULE.bazel

@@ -32,6 +32,14 @@ bazel_dep(name = "protobuf", version = "33.0", dev_dependency = True)
 
 http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
+http_archive(
+    name = "sty_bazel_tools",
+    dev_dependency = True,
+    integrity = "sha256-FayMMyMk37REW96xvJXMY1fYcWXBban9QgFAZUB+Kr0=",
+    strip_prefix = "sty-2ab74c830937d3ca85165ca0e9a02a42400ad9e5/crates/starpls_bazel/data/bazel_tools",
+    urls = ["https://github.com/tamird/sty/archive/2ab74c830937d3ca85165ca0e9a02a42400ad9e5.tar.gz"],
+)
+
 http_archive(
     name = "swift_linux_toolchain",
     build_file = "//test/linux_toolchain:swift_toolchain.BUILD",

crosstool/osx_cc_configure.bzl

@@ -18,6 +18,7 @@ load("//lib/private:toolchain_flags.bzl", "get_starlark_list", "quote_starlark_s
 load("//xcode:xcode_configure.bzl", "run_xcode_locator", "watch_selected_xcode")
 
 def _get_copts_env_var(repository_ctx, name, default = ""):
+    # type: (repository_ctx, str, str) -> list[str]
     """Get an environment variable and split it on ":" to be used as copts.
 
     Args:
@@ -33,6 +34,7 @@ def _get_copts_env_var(repository_ctx, name, default = ""):
     return _split_escaped(default, ":")
 
 def _split_escaped(string, delimiter):
+    # type: (str, str) -> list[str]
     """Split string on the delimiter unless %-escaped.
 
     Examples:
@@ -63,7 +65,7 @@ def _split_escaped(string, delimiter):
 
     i = 0
     result = []
-    accumulator = []
+    accumulator = []  # type: list[str]
     length = len(string)
     delimiter_length = len(delimiter)
 
@@ -83,7 +85,7 @@ def _split_escaped(string, delimiter):
             i += 1 + delimiter_length
         elif i + delimiter_length <= length and string[i:i + delimiter_length] == delimiter:
             result.append("".join(accumulator))
-            accumulator = []
+            accumulator = []  # type: list[str]
             i += delimiter_length
         else:
             accumulator.append(string[i])
@@ -93,7 +95,14 @@ def _split_escaped(string, delimiter):
     result.append("".join(accumulator))
     return result
 
+# TODO(https://github.com/bazelbuild/bazel/pull/30373): Use a native alias when
+# Bazel 8.8 is the minimum supported version.
+# type _DeveloperDirectory = struct[{"developer_dir": str}, ...]
+
 def _get_xcode_cxx_inc_directories(repository_ctx, xcode_toolchains):
+    # type: (repository_ctx, Collection[_DeveloperDirectory]) -> list[str]
+    # TODO(https://github.com/bazelbuild/bazel/issues/32020): Use a native
+    # signature when supported Bazel versions expose repository_ctx.
     """Compute the list of default C++ include paths on Xcode-enabled darwin.
 
     Args:
@@ -123,6 +132,9 @@ def _get_xcode_cxx_inc_directories(repository_ctx, xcode_toolchains):
     return include_dirs
 
 def _succeeds(repository_ctx, *args):
+    # type: (repository_ctx, *str) -> bool
+    # TODO(https://github.com/bazelbuild/bazel/issues/32020): make this an
+    # annotation when supported Bazel versions expose a repository context type.
     env = repository_ctx.os.environ
     result = repository_ctx.execute([
         "env",
@@ -136,9 +148,13 @@ def _succeeds(repository_ctx, *args):
     return result.return_code == 0
 
 def _copy_file(repository_ctx, src, dest):
+    # type: (repository_ctx, str | Label | path, str | path) -> None
+    # TODO(https://github.com/bazelbuild/bazel/issues/32020): annotate repository_ctx
+    # when supported Bazel versions expose a repository context type.
     repository_ctx.file(dest, content = repository_ctx.read(src))
 
 def configure_osx_toolchain(repository_ctx):
+    # type: (repository_ctx) -> tuple[bool, str | None]
     """Configure C++ toolchain on macOS.
 
     Args:
@@ -156,7 +172,7 @@ def configure_osx_toolchain(repository_ctx):
     cc_toolchain_config = Label("@apple_support//crosstool:cc_toolchain_config.bzl")
     build_template = Label("@apple_support//crosstool:BUILD.tpl")
 
-    xcode_toolchains = []
+    xcode_toolchains = []  # type: Collection[_DeveloperDirectory]
     xcodeloc_err = ""
     allow_non_applications_xcode = "BAZEL_ALLOW_NON_APPLICATIONS_XCODE" in repository_ctx.os.environ and repository_ctx.os.environ["BAZEL_ALLOW_NON_APPLICATIONS_XCODE"] == "1"
     if allow_non_applications_xcode:

crosstool/setup.bzl

@@ -4,6 +4,9 @@ load("@bazel_features//:features.bzl", "bazel_features")
 load(":setup_internal.bzl", "apple_cc_autoconf", "apple_cc_autoconf_toolchains")
 
 def _apple_cc_configure_extension_impl(module_ctx):
+    # type: (module_ctx) -> extension_metadata | None
+    # TODO(https://github.com/bazelbuild/bazel/issues/32020): make this an
+    # annotation when supported Bazel versions expose context and metadata types.
     apple_cc_autoconf_toolchains(name = "local_config_apple_cc_toolchains")
     apple_cc_autoconf(name = "local_config_apple_cc")
     if bazel_features.external_deps.extension_metadata_has_reproducible:

crosstool/setup_internal.bzl

@@ -9,6 +9,9 @@ _OLD_DISABLE_ENV_VAR = "BAZEL_USE_CPP_ONLY_TOOLCHAIN"
 _NEW_TOOLCHAIN_VAR = "APPLE_SUPPORT_RULES_BASED_TOOLCHAIN"
 
 def _apple_cc_autoconf_toolchains_impl(repository_ctx):
+    # type: (...) -> repo_metadata | None
+    # TODO(https://github.com/bazelbuild/bazel/issues/32020): make this an
+    # annotation when supported Bazel versions expose metadata types.
     """Generate BUILD file with 'toolchain' targets for the local host C++ toolchain.
 
     Args:
@@ -55,6 +58,7 @@ apple_cc_autoconf_toolchains = repository_rule(
 )
 
 def _apple_cc_autoconf_impl(repository_ctx):
+    # type: (...) -> repo_metadata | None
     env = repository_ctx.os.environ
     should_disable = _DISABLE_ENV_VAR in env and env[_DISABLE_ENV_VAR] == "1"
     old_should_disable = _OLD_DISABLE_ENV_VAR in env and env[_OLD_DISABLE_ENV_VAR] == "1"

crosstool/universal_exec_tool.bzl

@@ -3,6 +3,7 @@
 load("//rules:apple_genrule.bzl", "apple_genrule")
 
 def _force_exec_impl(ctx):
+    # type: (...) -> list[DefaultInfo]
     default_into = ctx.attr.target[DefaultInfo]
 
     return [
@@ -24,7 +25,15 @@ force_exec = rule(
     exec_compatible_with = ["@platforms//os:macos"],
 )
 
+# TODO(https://github.com/bazelbuild/bazel/issues/32021): Use native annotations
+# once supported Bazel versions expose depset element types.
+# type _Labels = Collection[Label | str] | depset[Label | str]
+
+# TODO(https://github.com/tamird/sty/blob/sty-action-v0.2.0/docs/type-interfaces.md#selectors):
+# Use a native parameter annotation when Bazel can describe configurable srcs
+# whose selected value can be a list, a depset, or None.
 def universal_exec_tool(*, name, out, srcs):
+    # type: (str, Label | str, _Labels | select[_Labels | None] | None) -> None
     apple_genrule(
         name = name + ".target_config",
         srcs = srcs,

lib/BUILD

@@ -9,6 +9,12 @@ package(
 
 exports_files(glob(["*.bzl"]))
 
+exports_files([
+    "apple_support.bzli",
+    "lipo.bzli",
+    "transitions.bzli",
+])
+
 # This target is mainly for use by rules_apple and rules_swift.
 # When this target is linked into an XCTest binary, and the
 # `BUILD_WORKSPACE_DIRECTORY` environment variable is set, the relative paths of