Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .agents/rules/code-style.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
25 changes: 22 additions & 3 deletions .agents/rules/rules_python.md
Original file line number Diff line number Diff line change
Expand Up @@ -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=<digest>` 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
Expand Down
5 changes: 4 additions & 1 deletion .agents/rules/starlark.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading