Give it something worth asking about

Chapter two's workspace has two flat targets. There is nothing interesting to ask about two things, so start by giving each language a shared library — the shape every real project has within a week.

On the Go side, a package the binary will call:

package greeting

import "fmt"

// Greet builds the message the server prints.
func Greet(name string) string {
	return fmt.Sprintf("Hello %s", name)
}

load("@rules_go//go:def.bzl", "go_library")

go_library(
    name = "greeting",
    srcs = ["greeting.go"],
    importpath = "example.com/greet/server/greeting",
    visibility = ["//server:__subpackages__"],
)

The binary now depends on it by label:

load("@rules_go//go:def.bzl", "go_binary", "go_library")

go_library(
    name = "server_lib",
    srcs = ["main.go"],
    importpath = "example.com/greet/server",
    deps = ["//server/greeting"],
)

go_binary(
    name = "server",
    embed = [":server_lib"],
)

The TypeScript side gets the same treatment:

export function greet(name: string): string {
  return `Hello ${name}`;
}

load("@aspect_rules_ts//ts:defs.bzl", "ts_project")

ts_project(
    name = "greeting",
    srcs = ["greeting.ts"],
    declaration = True,
    transpiler = "tsc",
    tsconfig = "//web:tsconfig",
    visibility = ["//web:__subpackages__"],
)

Three levels now, in both languages: a binary, a library it depends on, and the sources underneath. Build it to be sure everything still works, then start asking questions.

What does this depend on?

$ bazel query 'deps(//server, 2)'
//server:main.go
//server:server
//server:server_lib
//server/greeting:greeting

This is the direction you already know. Your compiler knows it too — follow the imports and you get the same answer. Useful, but not new.

What depends on this?

Now run it backwards:

$ bazel query 'rdeps(//..., //server/greeting)'
//server:server
//server:server_lib
//server/greeting:greeting

Stop here for a second, because this is the chapter.

You just asked what breaks if I change this file and got an exact answer. Not a guess, not a grep, not a mental model somebody maintains — a complete list, derived from declarations the build system already had to have in order to work at all.

On three targets the answer is obvious. On three thousand it is the difference between a refactor you can reason about and one you do by feel. This is also the question every continuous-integration system wants answered, which is why chapter thirteen can build only what changed rather than everything.

What kind of thing is each node?

The graph is not only targets and sources. Ask what each direct dependency of the TypeScript project actually is:

$ bazel query 'deps(//web:web, 1)' --output=label_kind
source file //web:greet.ts
ts_config rule //web:tsconfig
ts_project rule //web:web
ts_project rule //web/greeting:greeting
alias rule @@aspect_bazel_lib+//lib:coreutils_toolchain_type
options rule @aspect_rules_ts//ts:options
config_setting rule @npm_typescript//:is_typescript_5_or_greater
js_binary rule @npm_typescript//:tsc
js_binary rule @npm_typescript//:tsc_worker
js_binary rule @npm_typescript//:validator

There it is: @npm_typescript//:tsc, sitting in the dependency list next to your source file.

The TypeScript compiler is a dependency of your code. Not an ambient tool the machine happens to have, not a thing you install before building — a node in the graph, at a pinned version, with an edge pointing at the target that uses it.

This is the idea chapter two mentioned in passing and part three builds on properly. It matters because of what follows from it: if the compiler is an input, then changing the compiler changes the output, so the build knows to redo the work. And if the build knows exactly which compiler produced an artifact, two machines with different compilers installed cannot silently disagree.

You can also see validator in that list, which is the target that produced the tsconfig mismatch warning mentioned earlier. Nothing in this system is hidden machinery; it is all targets, and you can look at any of it.

A cycle your compiler will happily ship

The graph is not only a thing to query. It is a thing with rules, and here is one your own tools do not enforce.

Two TypeScript modules that need each other:

import { punctuate } from '../format/format.js';

export function greet(name: string): string {
  return `${prefix()}${punctuate(name)}`;
}

export function prefix(): string {
  return 'Hello ';
}

import { prefix } from '../greeting/greeting.js';

export function punctuate(name: string): string {
  return prefix().length > 3 ? `${name}!` : name;
}

Type-check it:

$ tsc --noEmit --strict greeting.ts
$ echo $?
0

Nothing wrong was found because, by the compiler's standards, nothing is wrong. Whether this program works depends on which module the runtime happens to evaluate first — and if it picks badly, you get a binding that is declared, typed, visible in your editor, and undefined.

Now declare the same two modules as targets and build:

$ bazel build //web/...
ERROR: in ts_project rule //web/format:format: cycle in dependency graph:
    //web/format:format
.-> //web/format:format
|   //web/greeting:greeting
`-- //web/format:format
ERROR: Analysis of target '//web/format:format' failed; build aborted

Go, for what it is worth, rejects import cycles too — this is one of the places its designers made the stricter choice. TypeScript did not, and the result is a class of bug that type-checks, ships, and surfaces as a mysterious undefined in production.

The graph is not a diagram

It is tempting to treat this as documentation — a nice picture of the project. It is stronger than that. The graph is not a description of the build, it is the build: the same structure that decides what to rebuild, in what order, and what may run in parallel.

That is why the answers are exact rather than approximate. A wiki page about your architecture can be wrong. This cannot be wrong without the build also being wrong, and the build being wrong is loud.

Try this in your own repository

Draw your own dependency graph, then check it. Sketch what you think depends on your most-changed shared module — from memory, before looking. Then find out for real, however your tooling allows. The gap between the sketch and the answer is the part of your architecture that currently exists only as folklore.

Go looking for a cycle. Most large TypeScript codebases have at least one. Write the check if you do not have it — walking imports is an afternoon, and counting only value imports is the part that makes it usable. If the first run finds nothing, that is worth knowing too.

What you can now do

Ask your project what depends on any file in it and get a complete answer, and explain why the compiler appearing in a dependency list is a feature rather than a leak. The next chapter takes the graph's promises and starts enforcing them — with a build that fails on a file that is sitting right there on disk.