diff --git a/.agents/rules/code-style.md b/.agents/rules/code-style.md index 2028a4da6f..e2c0aa8f06 100644 --- a/.agents/rules/code-style.md +++ b/.agents/rules/code-style.md @@ -15,6 +15,19 @@ Order definitions within a file as: 5. Main ## Control Flow & API Design +* Trace existing call graphs and check what inputs downstream functions and + rules already accept before adding new rules, wrapper macros, format + converters, or attributes. Wire new inputs into the existing pipeline at the + narrowest seam. +* Do not modify existing code or behavior unless strictly required; justify + every modified line in existing files. +* Keep parameter, return, and collection element types uniform across all + callers (e.g., always `list[str]`, never `str | list[str]`; always a + `struct`, never `str | struct`). Do not add runtime type branches to accept + inconsistent caller or test inputs; fix callers and test fixtures to pass the + uniform type instead. +* Keep functions small and focused on a single step; decompose multi-stage + functions into named helpers with documented `Args:` and `Returns:`. * Use early-return guard clauses over deeply nested conditionals. * When branching on validation modes, make the fall-off `else` the error case (fail-closed). diff --git a/.agents/rules/rules_python.md b/.agents/rules/rules_python.md index 701a9c38c7..eb58f7016c 100644 --- a/.agents/rules/rules_python.md +++ b/.agents/rules/rules_python.md @@ -33,9 +33,28 @@ description: rules_python-specific Bzlmod, PyPI, and rule usage invariants `bzl_library` `deps` for files loading `@bazel_tools//...`. ## WORKSPACE & Bzlmod Parity -* Match Bzlmod extension defaults, tag schemas (e.g., `configure` list of - dicts), and single-hub multi-version structure in `WORKSPACE` macros. Share - configuration and hub logic in common private `.bzl` helpers. +* **Extend Existing Rules Over Adding Parallel Rules**: When bringing a Bzlmod + tag attribute (such as `pip.parse(uv_lock = ...)`) to an existing `WORKSPACE` + rule or macro (`pip_parse` / `pip_repository`), add the attribute to the + existing rule and reuse its pipeline (`parse_requirements` -> + `requirements.bzl.tmpl.workspace` -> `whl_library`) instead of creating a + separate rule or duplicating Bzlmod's hub/spoke repo graph. +* **Extract Shared Pure Helpers from Bzlmod Extensions**: When `WORKSPACE` code + needs pure functions or data defined in a Bzlmod extension file (such as + `default_platforms()` in `extension.bzl`), move them into a standalone + Bzlmod-agnostic `.bzl` file instead of duplicating definitions. +* **Preserve Vendored `requirements.bzl` Portability in `WORKSPACE`**: + `pip_repository` outputs (`requirements.bzl`) may be vendored and evaluated + on any host platform. Only emit direct Bazel downloader attributes (`urls`, + `integrity`, `filename`) into `requirements.bzl` when a package resolves to + the same distribution across all target platforms + (`len({src.url: None for src in whl.srcs}) == 1`); otherwise append + `--hash=` flags to the requirement line so `pip` selects the host + wheel while enforcing lockfile hashes. +* For new `WORKSPACE` macros without an existing rule counterpart, match Bzlmod + extension defaults, tag schemas (e.g., `configure` list of dicts), and + single-hub multi-version structure, sharing configuration and hub logic in + common private `.bzl` helpers. * When `WORKSPACE` repos depend on downloaded manifests, split setup into a manifest repo rule (writes unfiltered `DIST_MANIFESTS` and a bound registration macro to `dist_manifest.bzl`) and a registration macro (filters diff --git a/.agents/rules/starlark.md b/.agents/rules/starlark.md index f9bdcda759..4b2239e8c4 100644 --- a/.agents/rules/starlark.md +++ b/.agents/rules/starlark.md @@ -129,7 +129,10 @@ globs: "*.bzl,BUILD,BUILD.bazel,*.bazel" `@bazel_skylib//lib:dicts.bzl` when merging dictionaries. * **Type Checks (`@bazel_skylib//lib:types.bzl`)**: Prefer `types.is_*` helpers (e.g., `types.is_dict(x)`, `types.is_list(x)`, `types.is_string(x)`) from - `@bazel_skylib//lib:types.bzl` instead of `type(x)` comparisons. + `@bazel_skylib//lib:types.bzl` instead of `type(x)` comparisons. Do not use + runtime type checks to support union parameter or field types (`str` vs. + `struct`, `str` vs. `list[str]`); enforce a single canonical type across all + callers and test fixtures. * **Non-Info Provider Naming**: Add `# buildifier: disable=name-conventions` above `provider()` declarations that do not end in `Info` (e.g. `*Fileset`). * **`config_setting` Naming**: Prefix `config_setting` names with `is_` (e.g.