From 73ce33ac6e2d514b61b891c1c1fc03e4c37eaf04 Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Sun, 16 Aug 2026 20:48:51 +0000 Subject: [PATCH] agents(starlark): document depset element immutability and provider conventions Depset elements and nested provider fields must be immutable upon depset construction in Bazel, and using providers rather than structs enables key sharing to minimize memory overhead. Documenting these invariants helps agents adhere to Bazel best practices and avoid runtime errors or buildifier lint warnings when working with custom providers in depsets. Update Starlark agent rules to require providers for depset elements, enforce tuple or depset types for nested fields instead of mutable lists, and document the buildifier suppression convention for non-Info providers. --- .agents/rules/starlark.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/.agents/rules/starlark.md b/.agents/rules/starlark.md index 2eccba7eab..74bf1bdbb9 100644 --- a/.agents/rules/starlark.md +++ b/.agents/rules/starlark.md @@ -40,9 +40,20 @@ globs: "*.bzl,BUILD,BUILD.bazel,*.bazel" * **Iterable `for` Loops Only (No `while` Loops)**: Starlark does not support `while` loops; iterate over fixed-size ranges or explicit collections. +## Depset Element Invariants & Optimizations +* **Providers over Structs for Depset Elements**: Use `provider()` (without + `-Info` suffix, e.g. `*Fileset`) instead of `struct()` for composite objects + in depsets; providers perform key sharing and reduce memory overhead. +* **Depset Element Immutability**: All depset elements and nested provider + fields must be immutable when `depset()` is called (eager check before rule + freeze). Use `tuple[T]` or `depset[T]` in providers placed into depsets; do + not use mutable `list[T]`. + ## Code Style & Conventions * **Dict union (`|`)**: Use `|` instead of `dicts.add(...)` from `@bazel_skylib//lib:dicts.bzl` when merging dictionaries. +* **Non-Info Provider Naming**: Add `# buildifier: disable=name-conventions` + above `provider()` declarations that do not end in `Info` (e.g. `*Fileset`). * **Docstring Formatting Invariants**: Use triple-quoted strings for multi-line docstrings without trailing backslashes (`\`) for line continuation. * **No Bazel Copyright Headers**: Do not add Bazel copyright headers to new or