bazel - SKILL.md Agent Skill

name: bazel description: Vantle Bazel conventions for BUILD.bazel files. Apply when creating or modifying build targets, adding dependencies, or scaffolding new modules. user-invocable: false

Bazel Conventions

File Structure

Every BUILD.bazel follows this section order:

##### Import
##### Internal
load("@vantle//component/generation/starlark:defs.bzl", ...)
##### External
load("@rules_rust//rust:defs.bzl", "rust_library")

##### Visibility
package(default_visibility = ["//visibility:public"])

##### Module
# ... targets ...

Add ##### Documentation before document generation targets when present.

Target Naming

Target name equals crate name. Use crate_name only for:

Case	Example
Root module	`name = "module"`, `crate_name = "vantle"`
Reserved keyword	`name = "returns"` when directory is `returns/`
Template libraries	Auto-generated by `rust_autotest_template`

Single-word targets matching their directory: //system/generation/runtime:runtime.

Dependencies

Type	Format
Internal absolute	`//system/generation/runtime:runtime`
Internal relative	`:error` (same package only)
External crate	`@crates//:miette`
Proc macros	`proc_macro_deps = ["//system/observation:macro"]`

Rules

Rule	Source	Purpose
`rust_library`	`@rules_rust//rust:defs.bzl`	Library targets
`rust_binary`	`@rules_rust//rust:defs.bzl`	Binary targets
`rust_autotest_template`	`@vantle//component/generation/starlark:defs.bzl`	Test template + validation library
`rust_autotest`	`@vantle//component/generation/starlark:defs.bzl`	Generate tests from template + cases.json
`document`	`//component/web/starlark:defs.bzl`	Document generation
`folder`	`//component/web/starlark:defs.bzl`	Aggregate pages
`distribute`	`//component/web/starlark:defs.bzl`	Dev server

Autotest Pattern

Test resources live in test/resource/ mirroring source structure.

Template resource (test/resource/system/<module>/):

filegroup(name = "cases", srcs = ["cases.json"])

rust_autotest_template(
    name = "template",
    src = "test.template.rs",
)

Test target (test/system/<module>/):

rust_autotest(
    name = "simple",
    size = "small",
    cases = "//test/resource/system/generation/simple:cases",
    template = "//test/resource/system/generation/simple:template",
)

Standard deps are auto-included by the macro: miette, serde, serde_json, clap, //:module, //system:command, //system:concurrent, //system:diagnostic, //system:observation, //system/generation/runtime:runtime. Proc macro deps (proc_macro_deps) are also injected automatically.

Banned Patterns

Pattern	Alternative
`exports_files()`	Use `filegroup(name = "...", srcs = ["..."])`

Visibility

Scope	Pattern
Public (default)	`["//visibility:public"]`
Test resources	`["//test:__pkg__", "//test:__subpackages__"]`
Component-internal	`["//component/generation:__pkg__"]`

Module Aggregation

Aggregator targets re-export child modules. The rust_library lists all children as deps, and the .rs source contains pub use child; for each.