Describe toolchain provider and macro contracts

.github/workflows/sty.yaml

@@ -0,0 +1,108 @@
+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
+      - uses: tamird/sty@95e2b424a7f52fa0b0946da98eb2cc328e9b4107
+        with:
+          audit-loads: true
+          bazel-version: '9.3.0'
+          advisory-pathspecs: '*.bzl'
+          advisory-bazel-load-context: '@cross_repo_test//toolchain_include_dirs:toolchain_config'
+          advisory-require-bazel-load-context: tests/builtins_bzl/cc/cc_shared_library/test2/toolchain_include_dirs/cc_toolchain_config.bzl
+          files: |
+            @bazel_skylib//:bzl_library.bzl
+            @bazel_skylib//lib:paths.bzl
+            @bazel_skylib//rules:common_settings.bzl
+            @bazel_skylib//rules/directory:providers.bzl
+            cc/BUILD
+            cc/action_names.bzl
+            cc/cc_import.bzl
+            cc/cc_postmark.bzl
+            cc/cc_rules_extension_support.bzl
+            cc/cc_shared_library.bzl
+            cc/common/BUILD
+            cc/common/cc_shared_library_info.bzl
+            cc/common/debug_package_info.bzl
+            cc/common/feature_names.bzl
+            cc/common/objc_info.bzl
+            cc/extensions.bzl
+            cc/private/cc_shared_library_hint_info.bzl
+            cc/private/cc_shared_library_info.bzl
+            cc/private/debug_package_info.bzl
+            cc/private/graph_node_info.bzl
+            cc/private/paths.bzl
+            cc/private/rules_impl/failing_cc_proto_library.bzl
+            cc/private/rules_impl/fdo/fdo_prefetch_hints.bzl
+            cc/private/rules_impl/fdo/fdo_profile.bzl
+            cc/private/rules_impl/fdo/memprof_profile.bzl
+            cc/private/rules_impl/fdo/propeller_optimize.bzl
+            cc/private/rules_impl/native_cc_common.bzl
+            cc/private/rules_impl/objc_compilation_context_info.bzl
+            cc/private/toolchain/cc_configure.bzl
+            cc/private/toolchain/unix_cc_configure.bzl
+            cc/repositories.bzl
+            cc/starlark_doc_extract_helper.bzl
+            cc/system_library.bzl
+            cc/toolchains/actions.bzl
+            cc/toolchains/actions/BUILD
+            cc/toolchains/args/BUILD
+            cc/toolchains/args/libraries_to_link/private/library_link_args.bzl
+            cc/toolchains/args_list.bzl
+            cc/toolchains/artifacts.bzl
+            cc/toolchains/capabilities/BUILD
+            cc/toolchains/cc_toolchain.bzl
+            cc/toolchains/cc_toolchain_alias.bzl
+            cc/toolchains/cc_toolchain_config_info.bzl
+            cc/toolchains/directory_tool.bzl
+            cc/toolchains/fdo_prefetch_hints.bzl
+            cc/toolchains/fdo_profile.bzl
+            cc/toolchains/feature.bzl
+            cc/toolchains/feature_constraint.bzl
+            cc/toolchains/feature_injection.bzl
+            cc/toolchains/feature_set.bzl
+            cc/toolchains/features/BUILD
+            cc/toolchains/features/legacy/BUILD
+            cc/toolchains/impl/cc_artifact_category.bzl
+            cc/toolchains/impl/external_feature.bzl
+            cc/toolchains/impl/label_utils.bzl
+            cc/toolchains/impl/libc_version.bzl
+            cc/toolchains/impl/markdown_helpers.bzl
+            cc/toolchains/legacy_file_group.bzl
+            cc/toolchains/legacy_tool.bzl
+            cc/toolchains/make_variable.bzl
+            cc/toolchains/memprof_profile.bzl
+            cc/toolchains/mutually_exclusive_category.bzl
+            cc/toolchains/nested_args.bzl
+            cc/toolchains/propeller_optimize.bzl
+            cc/toolchains/providers.bzl
+            cc/toolchains/tool.bzl
+            cc/toolchains/tool_capability.bzl
+            cc/toolchains/variables/BUILD
+            cc/use_cc_toolchain.bzl
+            local_bazel.bzl
+            tests/cc/testutil/toolchains/additional_toolchains.bzl
+            tests/cc/testutil/toolchains/features.bzl
+            tests/load_from_macro/tags.bzl
+            tests/rule_based_toolchain/action_type_sets
+            tests/rule_based_toolchain/args/make_var_provider.bzl
+            tests/rule_based_toolchain/helpers.bzl
+            tests/rule_based_toolchain/legacy_features_as_args/goldens
+            tests/rule_based_toolchain/tool/execution_requirements.bzl

BUILD

@@ -4,7 +4,10 @@ package(default_visibility = ["//visibility:public"])
 
 licenses(["notice"])
 
-exports_files(["LICENSE"])
+exports_files([
+    "LICENSE",
+    "stubs.toml",
+])
 
 exports_files(["copy.bara.sky"])
 
@@ -51,6 +54,7 @@ filegroup(
     srcs = [
         "BUILD",
         "MODULE.bazel",
+        "stubs.toml",
         "//cc:srcs",
     ],
     visibility = ["//:__subpackages__"],

cc/BUILD

@@ -30,6 +30,8 @@ filegroup(
 )
 
 exports_files([
+    "cc_postmark_initializers.bzli",
+    "cc_toolchain_config_lib.bzli",
     "defs.bzl",
     "action_names.bzl",
     "system_library.bzl",
@@ -74,6 +76,7 @@ filegroup(
     testonly = 1,
     srcs = glob([
         "**/*.bzl",
+        "**/*.bzli",
         "**/BUILD",
     ]) + [
         "//cc/common:srcs",

cc/cc_import.bzl

@@ -15,5 +15,8 @@
 
 load("@cc_compatibility_proxy//:proxy.bzl", _cc_import = "cc_import")
 
+# TODO(https://github.com/bazelbuild/bazel/issues/32343): Annotate **kwargs
+# when Bazel can derive them from the wrapped cc_import rule.
 def cc_import(**kwargs):
+    # type: (**Unpack[KeywordArgs[_cc_import]]) -> None
     _cc_import(**kwargs)

cc/cc_postmark.bzl

@@ -14,20 +14,21 @@
 
 """PostMark is not implemented in Bazel."""
 
-def _get_postmark_attrs():
-    return {}
-
-def _postmark_initializer(**kwargs):
-    return kwargs
+load("//cc:cc_postmark_initializers.bzl", _get_postmark_attrs = "get_postmark_attrs", _postmark_initializer = "postmark_initializer")
 
 def _add_postmark_action(
         ctx,  # @unused
         cc_toolchain,  # @unused
         binary,  # @unused
         output_binary_for_linking):  # @unused
+    # type: (object, object, object, object) -> None
     pass
 
+# The public toolchain never enables PostMark. A broader bool makes the
+# cc_binary branch that passes internal-only action keywords reachable.
+# TODO: Use bool when the public implementation supports that action.
 def _get_use_postmark(ctx):  # @unused
+    # type: (object) -> Literal[False]
     return False
 
 postmark = struct(

cc/cc_postmark_initializers.bzli

@@ -0,0 +1,7 @@
+"""Contracts for the PostMark initializer compatibility layer."""
+
+# TODO(https://github.com/bazelbuild/starlark/pull/362): Move the initializers into source when supported Bazel versions can bind
+# K and V on the function. A signature comment cannot bind these type parameters.
+
+def _get_postmark_attrs[K, V]() -> dict[K, V]: ...
+def _postmark_initializer[T](**kwargs: T) -> dict[str, T]: ...

cc/cc_shared_library.bzl

@@ -15,5 +15,8 @@
 
 load("@cc_compatibility_proxy//:proxy.bzl", _cc_shared_library = "cc_shared_library")
 
+# TODO(https://github.com/bazelbuild/bazel/issues/32343): Annotate **kwargs
+# when Bazel can derive them from the wrapped cc_shared_library rule.
 def cc_shared_library(**kwargs):
+    # type: (**Unpack[KeywordArgs[_cc_shared_library]]) -> None
     _cc_shared_library(**kwargs)