Build Scoping & Affected Detection

## The scaling problem a monorepo creates A monorepo's core selling point — everything in one place, atomic cross-project commits, shared tooling — comes with a scaling problem single-project repos never face: **the codebase keeps growing even though any individual change stays small**. If CI naively rebuilds and retests every project on every push, pipeline duration becomes a function of total repository size, not of the diff. - In a repo with **fifty projects** that might be tolerable. - In one with **two thousand** it turns a one-line fix in a shared utility library into an hours-long, machine-hungry run, and every engineer pays that tax on every commit regardless of what they touched. ## How affected detection works Affected detection (also called 'scoped builds' or 'impacted project detection') solves this by treating the codebase as a **dependency graph** — nodes are projects/packages/targets, edges are 'depends on' relationships derived from imports, build-file declarations, or module manifests. Given a set of changed files (usually from a git diff against a base commit), the tool then: 1. maps each file to the project that owns it; 2. does a **reverse-dependency (upward) traversal** of the graph to find every project that transitively depends on an owning project. That traversal result is the **affected set** — everything whose behavior could plausibly change because of this diff. Build, lint, and test tasks then run only for that set. ## The payoff The payoff is that CI latency and cost scale with change size instead of repo size. - A change confined to a leaf package with no internal consumers might affect only itself. - A change to a widely-shared core library might affect dozens of downstream projects, which is exactly the correct, conservative behavior — you want the CI cost to reflect real blast radius. This is what makes monorepos with tens of thousands of projects (Google's Piper/Blaze ecosystem, or open-source tools like Nx and Bazel used at that scale) operationally viable at all; without scoping, the CI queue time alone would make the monorepo model unusable past a few hundred projects. ## The trade-off The trade-off is that affected detection trades exhaustiveness for speed, and its correctness is entirely bounded by how complete and accurate the dependency graph is. Static analysis of import statements and build manifests captures most dependencies, but it can miss dynamic ones: - reflection-based dependency injection; - string-based dynamic imports; - config files that reference another project by name at runtime; - shared runtime infrastructure (a database schema, a message topic contract) that isn't expressed as a code-level import at all. When the graph misses an edge, affected detection produces a **false negative** — a project that would actually break ships through CI green because the tool never knew it depended on the changed code. This is the central risk teams accept when adopting affected-only CI, and it's why most organizations pair it with a periodic full-suite safety net (nightly or pre-release) rather than trusting affected detection as the sole gate forever. ## What the tools actually do A concrete illustration: Nx computes the affected set by diffing against a base ref (commonly the last common ancestor with main, or the previous successful run on trunk), mapping changed files to their owning `project.json` targets via its project graph, then running `nx affected -- test`/`build`/`lint` only for the reverse-dependency closure. Bazel does the analogous thing with `bazel query 'rdeps(//..., set(changed_targets))'` built from its own build-graph rules. Both systems make the same implicit bet: that the declared graph is a faithful superset of real runtime dependencies. Where that bet breaks down — most commonly with polyglot repos mixing statically-analyzable code with loosely-coupled services communicating over the network — affected detection needs supplementary signals to stay trustworthy: - explicit `implicitDependencies` declarations, - tags marking 'always run', - or manual dependency pinning. Getting this wrong doesn't fail loudly; it fails as a production incident weeks later that nobody's CI run ever caught.