4.8.4 Large-Scale Refactoring via Aspects

Aspects do not have to be read-only. The same shadow-graph mechanism that drives lint and IDE metadata in 4.8.1 Aspects — Cross-Cutting Graph Traversal can also drive code-rewriting tools across an entire repository — without adding any of those rewriting jobs to the BUILD graph as first-class targets. Airbnb's JVM monorepo team uses this pattern to apply OpenRewrite recipes to a 30+ million LOC codebase in about fifteen minutes by leaning on RBE for parallelism.¹

This article is a use-case study, not a new mechanism. It assumes you already understand aspect propagation and action declaration from 4.8.2 Aspect Implementation Basics. The interesting design questions are what to wrap, how to split the pipeline so it caches well, and why aspects are the right place for it.

The Use Case: Whole-Repo Code Transformation

OpenRewrite is an automated refactoring tool for JVM languages. A small Bazel wrapper calls the tool's API and splits parsing, AST conversion, and reserialization into cacheable actions.² It is the Java-ecosystem equivalent of any whole-repo transformation tool: import rewriters, codemod runners, deprecated-API migrators.

Running such recipes across a large service-platform monorepo exposes the core problem. The naive shape — a standalone driver script that walks the repo target-by-target — is prohibitively slow.² Switching the driver to invoke per-target Bazel actions and let RBE schedule them in parallel cut the same workload to roughly 15 minutes for the entire repository.²

The change is not in the refactoring tool. It is in how the tool is invoked. The aspect is the wrapper.

Why an Aspect Instead of a Macro or Rule

The repository already has thousands of *_library targets that describe the source files and dependency graph the refactoring needs. The job of the aspect is to visit each of those targets, hand its sources and classpath to OpenRewrite, and produce rewritten outputs. Three concrete reasons aspects are the right shape for this:

• No target pollution. A macro-based approach would need to declare a rewrite_<lib> target next to every library, either eagerly in BUILD files or via a generator. Both add ongoing maintenance and BUILD-graph noise. An aspect attaches at request time, runs through --aspects, and disappears when the rewrite is over.³
• Reuses the existing dep graph. Refactoring a library typically needs the same classpath the library compiles against. Propagating along the same deps/exports edges the rule already declares — instead of redefining them inside a new rule — keeps the aspect aligned with what the build already knows.⁴
• Cross-cutting by definition. Rewriting recipes are infrastructure-team concerns layered on top of normal *_library rules. That is precisely the split aspects are designed for, the same split discussed in 4.8.3 Validation Actions vs Aspects for linters: the rule set author owns the build contract, and the platform team owns the cross-cutting tool that observes it.⁵

Aspects are not the only way to wrap an external tool. They become the right way when the work is conceptually orthogonal to the rule that describes the target.

Pipeline Splitting for Cacheable Parallelism

Wrapping OpenRewrite in a single monolithic action would work but throw away most of Bazel's caching and remote-execution benefit. A monolithic action recomputes everything when any input or any tool input changes. Small recipe iterations would invalidate the whole repo.

The fix is to split the work along OpenRewrite's phase boundaries into several smaller actions per target — parsing, AST conversion, and reserialization each become their own Bazel action:²

1. Parsing — turn source files into the tool's initial intermediate representation.
2. AST conversion — produce the Lossless Semantic Tree the recipes operate on.
3. Reserialization — emit transformed source files after the recipes run.

Each phase is a regular Bazel action with explicit declared inputs and outputs. The cache key model from 2.4.3 What Makes a Cache Hit then does the rest: parsing can stay cached across recipe-only changes, and reruns when its declared inputs, tool, command line, or relevant configuration change. AST conversion follows the same action-key rule over its parsing outputs and tool inputs, so previous-phase outputs can be reused across recipe iterations and across targets that share the same upstream artifacts.

The split also unlocks horizontal parallelism on RBE — phases for thousands of targets schedule independently across a worker fleet instead of serializing inside a single per-target action. This is what turns a multi-hour script into a 15-minute job.²

The General Pattern

Strip the JVM specifics and the recipe is reusable for any whole-repo transformation that can be expressed as "for each library target, run a tool that reads sources and produces rewritten outputs":

• API migrations (e.g. moving callers off a deprecated symbol).
• Framework or language-version upgrades that need a mechanical sweep.
• Style or convention enforcement that is too structural for a formatter.
• Bytecode-level transformations driven by source classpath analysis (for example, a separate aspect that validates the maximum bytecode version on the runtime classpath, in the same broader pattern of aspect-driven analysis over the existing graph).⁶

The recipe is always the same shape: define the aspect, propagate along the dep edges the tool needs, declare a small number of cacheable actions per visited target, drive it from the command line with --aspects, and rely on 6.3 Remote Execution Infrastructure for the parallelism. The transformation tool itself stays a normal external program — Bazel's contribution is the work decomposition and the worker fleet, not the rewriting logic.