diff --git a/.agents/rules/bazelci.md b/.agents/rules/bazelci.md new file mode 100644 index 0000000000..c3bf7d6eb2 --- /dev/null +++ b/.agents/rules/bazelci.md @@ -0,0 +1,28 @@ +--- +trigger: glob +description: BazelCI presubmit.yml flag conventions +globs: ".bazelci/**" +--- + +# BazelCI Presubmit Config Rule + +* Write `build_flags` and `test_flags` as YAML mappings with `? "--flag"` + keys, not as lists. Don't put matrix placeholders (`${{ }}`) in those keys; + bazelci.py doesn't expand them in mapping keys. +* To give a task the shared flags plus its own, merge the anchor instead of + copying flags: `<<: *reusable_config_build_flags` or + `<<: *reusable_config_test_flags`, then add the task's keys. A task's own + `build_flags` or `test_flags` replaces the inherited mapping entirely. +* To change a merged flag, such as a tag filter, list it again: Bazel uses + the last value. +* Pass build-configuration flags, such as `--config=ci`, to both build and + test, so `bazel test` reuses the build's analysis cache. +* Only the root `.bazelrc` defines `--config=ci`. Tasks with a + `working_directory` can't use it. +* When a task has several `<<:` keys, later anchors win for the same key; + e.g. the workspace anchors replace `reusable_config`'s flags. In the list + form, `<<: [*a, *b]`, the first anchor wins. +* After editing, run + `bazel test --config=fast-tests //tests/bazelci:presubmit_test`. To + review how each task's flags changed, run + `bazel run //dev/bazelci:diff_presubmit_flags`. diff --git a/.bazelci/BUILD.bazel b/.bazelci/BUILD.bazel new file mode 100644 index 0000000000..2910c2a51c --- /dev/null +++ b/.bazelci/BUILD.bazel @@ -0,0 +1,5 @@ +filegroup( + name = "presubmit_yml", + srcs = ["presubmit.yml"], + visibility = ["//:__subpackages__"], +) diff --git a/dev/bazelci/BUILD.bazel b/dev/bazelci/BUILD.bazel new file mode 100644 index 0000000000..d90eba8b3f --- /dev/null +++ b/dev/bazelci/BUILD.bazel @@ -0,0 +1,18 @@ +load("//python:py_binary.bzl", "py_binary") +load("//python:py_library.bzl", "py_library") + +package(default_visibility = ["//:__subpackages__"]) + +py_library( + name = "presubmit_flags", + srcs = ["presubmit_flags.py"], + imports = ["../.."], + deps = ["@pypi//pyyaml"], +) + +py_binary( + name = "diff_presubmit_flags", + srcs = ["diff_presubmit_flags.py"], + imports = ["../.."], + deps = [":presubmit_flags"], +) diff --git a/dev/bazelci/diff_presubmit_flags.py b/dev/bazelci/diff_presubmit_flags.py new file mode 100644 index 0000000000..ea89b4a971 --- /dev/null +++ b/dev/bazelci/diff_presubmit_flags.py @@ -0,0 +1,82 @@ +"""Shows how a presubmit.yml change alters each BazelCI task's flags. + +Usage: + bazel run //dev/bazelci:diff_presubmit_flags + bazel run //dev/bazelci:diff_presubmit_flags -- --base=HEAD~1 + bazel run //dev/bazelci:diff_presubmit_flags -- --flag=--config=ci + +It reads `.bazelci/presubmit.yml` from the workspace and, through `git show`, +from the `--base` ref. For each task, it prints the `build_flags` and +`test_flags` that were added or removed, as BazelCI passes them to Bazel after +resolving YAML merges. With `--flag`, it instead lists the tasks in the +workspace's presubmit.yml that pass that flag. +""" + +from __future__ import annotations + +import argparse +import os +import subprocess +import sys +from pathlib import Path + +from dev.bazelci import presubmit_flags + + +def _git_show(workspace: Path, spec: str) -> str: + try: + result = subprocess.run( + ["git", "show", spec], + cwd=workspace, + capture_output=True, + text=True, + check=True, + ) + except subprocess.CalledProcessError as e: + e.add_note( + "==================== STDOUT BEGIN ====================\n" + f"{e.stdout}" + "==================== STDOUT END ====================\n" + "==================== STDERR BEGIN ====================\n" + f"{e.stderr}" + "==================== STDERR END ====================" + ) + raise + return result.stdout + + +def main(argv: list[str]) -> int: + parser = argparse.ArgumentParser( + description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + mode = parser.add_mutually_exclusive_group() + mode.add_argument( + "--base", + default="upstream/main", + help="Git ref whose presubmit.yml to compare with (default: %(default)s).", + ) + mode.add_argument( + "--flag", + help="List the tasks that pass this flag, e.g. --flag=--config=ci.", + ) + args = parser.parse_args(argv) + + workspace = Path(os.environ["BUILD_WORKSPACE_DIRECTORY"]) + presubmit = workspace / presubmit_flags.PRESUBMIT_PATH + workspace_tasks = presubmit_flags.load_tasks(presubmit.read_text(encoding="utf-8")) + + if args.flag: + lines = presubmit_flags.tasks_with_flag(workspace_tasks, args.flag) + print("\n".join(lines) if lines else f"No task passes {args.flag}.") + return 0 + + base_text = _git_show(workspace, f"{args.base}:{presubmit_flags.PRESUBMIT_PATH}") + base_tasks = presubmit_flags.load_tasks(base_text) + lines = presubmit_flags.diff_tasks(base_tasks, workspace_tasks) + print("\n".join(lines) if lines else f"No task's flags differ from {args.base}.") + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/dev/bazelci/presubmit_flags.py b/dev/bazelci/presubmit_flags.py new file mode 100644 index 0000000000..14ea85f21a --- /dev/null +++ b/dev/bazelci/presubmit_flags.py @@ -0,0 +1,101 @@ +"""Reads the build and test flags of BazelCI presubmit tasks. + +BazelCI's bazelci.py loads `.bazelci/presubmit.yml` with `yaml.safe_load`, so +YAML merge keys (`<<:`) resolve the way PyYAML resolves them. It then flattens +each task's `build_flags` and `test_flags` with `flatten()`, which yields a +mapping's keys. This module mirrors that, except that it doesn't expand the +task matrix: matrix values only fill `${{ }}` placeholders, so a task stands +for all of its matrix jobs. + +See https://github.com/bazelbuild/continuous-integration/blob/master/buildkite/bazelci.py +""" + +from __future__ import annotations + +from collections.abc import Iterable, Mapping + +import yaml + +PRESUBMIT_PATH = ".bazelci/presubmit.yml" +FLAG_ATTRS = ( + # keep-sorted start + "build_flags", + "test_flags", + # keep-sorted end +) + + +def load_tasks(text: str) -> dict[str, dict[str, object]]: + """Returns the tasks of a presubmit.yml, with YAML merges resolved.""" + return yaml.safe_load(text)["tasks"] + + +def diff_tasks( + old_tasks: Mapping[str, Mapping[str, object]], + new_tasks: Mapping[str, Mapping[str, object]], +) -> list[str]: + """Describes how each task's flags changed between two presubmit.yml files. + + Args: + old_tasks: The tasks before the change, from `load_tasks`. + new_tasks: The tasks after the change, from `load_tasks`. + + Returns: + One line per added task, removed task, or changed flags attribute, + sorted by task. A changed attribute lists removed flags with `-` and + added flags with `+`, then the new order if the kept flags changed + order, since Bazel uses a repeated flag's last value. + """ + lines = [] + for name in sorted(old_tasks.keys() | new_tasks.keys()): + if name not in new_tasks: + lines.append(f"{name}: removed") + continue + if name not in old_tasks: + parts = [] + for attr in FLAG_ATTRS: + flags = " ".join(_task_flags(new_tasks[name], attr)) or "(none)" + parts.append(f"{attr}: {flags}") + lines.append(f"{name}: added; {'; '.join(parts)}") + continue + for attr in FLAG_ATTRS: + old_flags = _task_flags(old_tasks[name], attr) + new_flags = _task_flags(new_tasks[name], attr) + if old_flags == new_flags: + continue + changes = [f"-{flag}" for flag in old_flags if flag not in new_flags] + changes += [f"+{flag}" for flag in new_flags if flag not in old_flags] + kept_old = [flag for flag in old_flags if flag in new_flags] + kept_new = [flag for flag in new_flags if flag in old_flags] + if kept_old != kept_new: + changes += ["reordered:", *new_flags] + lines.append(f"{name}: {attr}: {' '.join(changes)}") + return lines + + +def tasks_with_flag(tasks: Mapping[str, Mapping[str, object]], flag: str) -> list[str]: + """Lists the tasks that pass `flag`, and in which flags attributes.""" + lines = [] + for name in sorted(tasks): + attrs = [attr for attr in FLAG_ATTRS if flag in _task_flags(tasks[name], attr)] + if attrs: + lines.append(f"{name}: {', '.join(attrs)}") + return lines + + +def _flatten(value: Iterable[object]) -> list[str]: + # Like bazelci.py's `flatten()`: keeps strings, expands one level of + # nested lists, and drops anything else. + flags = [] + for item in value: + if isinstance(item, str): + flags.append(item) + elif isinstance(item, list): + flags.extend(item) + return flags + + +def _task_flags(task: Mapping[str, object], attr: str) -> list[str]: + value = task.get(attr, {}) + assert isinstance(value, (dict, list)) # type assert + return _flatten(value) diff --git a/tests/bazelci/BUILD.bazel b/tests/bazelci/BUILD.bazel new file mode 100644 index 0000000000..b035cad336 --- /dev/null +++ b/tests/bazelci/BUILD.bazel @@ -0,0 +1,11 @@ +load("//python:pytest_test.bzl", "pytest_test") + +pytest_test( + name = "presubmit_test", + srcs = ["presubmit_test.py"], + data = ["//.bazelci:presubmit_yml"], + deps = [ + "//dev/bazelci:presubmit_flags", + "//python/runfiles", + ], +) diff --git a/tests/bazelci/presubmit_test.py b/tests/bazelci/presubmit_test.py new file mode 100644 index 0000000000..db702dcea3 --- /dev/null +++ b/tests/bazelci/presubmit_test.py @@ -0,0 +1,32 @@ +"""Checks that .bazelci/presubmit.yml writes flags as mappings of `?` keys.""" + +from __future__ import annotations + +from collections.abc import Mapping + +from dev.bazelci import presubmit_flags +from python.runfiles import runfiles + + +def _find_problems(tasks: Mapping[str, Mapping[str, object]]) -> list[str]: + problems = [] + for name, task in tasks.items(): + for attr in presubmit_flags.FLAG_ATTRS: + value = task.get(attr, {}) + if not isinstance(value, dict): + problems.append(f'{name}: {attr} isn\'t a mapping of `? "--flag"` keys') + elif any(v is not None for v in value.values()): + problems.append(f"{name}: {attr} has `?` keys with values") + return sorted(problems) + + +def test_presubmit_has_no_flag_problems(): + rf = runfiles.CreateOrRaise() + presubmit = rf.root() / "rules_python" / presubmit_flags.PRESUBMIT_PATH + tasks = presubmit_flags.load_tasks(presubmit.read_text(encoding="utf-8")) + + problems = _find_problems(tasks) + + assert not problems, ( + f"Fix these tasks in {presubmit_flags.PRESUBMIT_PATH}:\n" + "\n".join(problems) + )