From 63324124b758f3f2618e17652a20c17d2708c5fa Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Wed, 12 Aug 2026 07:52:07 +0000 Subject: [PATCH] agents(rules): add Starlark dict union and Pyrefly PackagePath conventions Starlark supports the dictionary union operator (|), making skylib's dicts.add redundant. When using importlib.metadata in Python, f.locate() is typed as PathLike and lacks filesystem methods like .exists() and .is_file() under Pyrefly unless wrapped with pathlib.Path. Add rules instructing agents to prefer the dict union operator (|) over dicts.add in Starlark and to wrap f.locate() calls with pathlib.Path() in Python type-annotated code. --- .agents/rules/python.md | 2 ++ .agents/rules/starlark.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/.agents/rules/python.md b/.agents/rules/python.md index 21f6671b93..701397fced 100644 --- a/.agents/rules/python.md +++ b/.agents/rules/python.md @@ -14,6 +14,8 @@ link to its definition in the docstring. ## Type Checking & Annotations +* **`importlib.metadata` `PackagePath`**: `f.locate()` is typed as `PathLike`. + Wrap with `pathlib.Path(f.locate())` to call `.exists()`, `.is_file()`, etc. * **In-file disables vs target skipping**: Prefer `# pyrefly: ignore[]` (e.g. `[missing-import]`) over `tags = ["no-pyrefly"]`. * **No blanket ignores**: NEVER use bare `# type: ignore` or literal diff --git a/.agents/rules/starlark.md b/.agents/rules/starlark.md index 4517b06aec..2eccba7eab 100644 --- a/.agents/rules/starlark.md +++ b/.agents/rules/starlark.md @@ -41,6 +41,8 @@ globs: "*.bzl,BUILD,BUILD.bazel,*.bazel" `while` loops; iterate over fixed-size ranges or explicit collections. ## Code Style & Conventions +* **Dict union (`|`)**: Use `|` instead of `dicts.add(...)` from + `@bazel_skylib//lib:dicts.bzl` when merging dictionaries. * **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