Pin the toolchain and stop shipping machine-specific state (review PRs 1 + 2)

.bazelignore

@@ -0,0 +1,8 @@
+# Cargo output directories. Bazel's package loader walks the whole tree, and a
+# plain `cargo build` in any of these subdirectories leaves tens of thousands of
+# files behind for it to crawl.
+corex/target
+server/target
+combos/target
+combos/backend/target
+combos/frontend/target

.bazelrc

@@ -0,0 +1,54 @@
+# Bazel configuration for complex-bazel-setup.
+#
+#   Bazel version      -> .bazelversion
+#   Rust toolchain     -> MODULE.bazel (rust.toolchain) + rust-toolchain.toml
+#   Personal overrides -> .bazelrc.user (gitignored, imported at the bottom)
+
+# ---------- correctness ----------
+# An empty glob is a typo or a moved file, not an empty list. On by default in
+# Bazel 8; pinned here so it survives a version change.
+build --incompatible_disallow_empty_glob
+
+# ---------- build profiles ----------
+# Bazel's default compilation mode (fastbuild) is opt-level 0 with NO debug
+# info, while `cargo build` gives you -C debuginfo=2. Without this, a backtrace
+# out of `bazel run //server:server_bin` has bare addresses and a debugger has
+# nothing to attach to -- one of the ways the two build systems disagreed.
+build --compilation_mode=dbg
+build:release --compilation_mode=opt
+build:release --strip=always
+
+# ---------- rules_rust ----------
+# Verified against all 17 targets with rules_rust 0.63.0 / Bazel 8.7.0.
+build --@rules_rust//rust/settings:pipelined_compilation=True
+
+# ---------- caching ----------
+build --disk_cache=~/.cache/bazel-disk
+build --repository_cache=~/.cache/bazel-repo
+
+# ---------- tests ----------
+test --test_output=errors
+test --build_tests_only
+
+# ---------- coverage ----------
+# rules_rust ships llvm-tools with every toolchain >= 1.45.0 (repositories.bzl),
+# so `bazel coverage //...` needs nothing beyond the pinned toolchain.
+coverage --combined_report=lcov
+coverage --instrumentation_filter=^//corex[:/],^//server[:/],^//combos[:/]
+
+# ---------- CI ----------
+build:ci --announce_rc --verbose_failures --keep_going
+build:ci --disk_cache=/tmp/bazel-disk
+test:ci --flaky_test_attempts=1
+# Surfaces targets whose declared size does not match how long they actually
+# run. Every test in this repo is currently MODERATE and finishes in ~0.1s;
+# they want size = "small". CI-only so local runs stay quiet.
+test:ci --test_verbose_timeout_warnings
+# Fail on a stale MODULE.bazel.lock instead of silently re-resolving.
+# PREREQUISITE: MODULE.bazel.lock must be committed first, and it must be
+# generated on a machine that can reach the real bcr.bazel.build -- a lock
+# produced against a local file:// registry has an empty registryFileHashes and
+# will be treated as out of date here.
+common:ci --lockfile_mode=error
+
+try-import %workspace%/.bazelrc.user

.bazelversion

@@ -0,0 +1 @@
+8.7.0

.cargo-runner.json

@@ -3,14 +3,7 @@
     "command": "bazel",
     "extra_args": [],
     "extra_env": {},
-    "extra_test_binary_args": [],
-    "linked_projects": [
-      "/Users/uriah/Code/yoyo/combos/Cargo.toml",
-      "/Users/uriah/Code/yoyo/combos/frontend/Cargo.toml",
-      "/Users/uriah/Code/yoyo/combos/backend/Cargo.toml",
-      "/Users/uriah/Code/yoyo/server/Cargo.toml",
-      "/Users/uriah/Code/yoyo/corex/Cargo.toml"
-    ]
+    "extra_test_binary_args": []
   },
   "overrides": []
-}
+}

.gitignore

@@ -1,10 +1,12 @@
 bazel-*
 .bazelrc.user
 .bazelversion.user
-MODULE.bazel.lock
 .cache/
 .bazel/
 
+# NOTE: MODULE.bazel.lock is deliberately NOT ignored. It is what makes a bzlmod
+# build reproducible and what --lockfile_mode=error checks against in CI.
+
 # Rust
 target/
 **/*.rs.bk
@@ -16,14 +18,22 @@ target/
 # Cargo.lock
 
 # Bazel + Rust specific
-# Generated by cargo-bazel
-cargo-bazel-lock.json
+# NOTE: cargo-bazel-lock.json is the crate_universe `lockfile` artifact. It must
+# be COMMITTED -- it is what makes crate resolution deterministic and lets CI
+# detect a Cargo.lock bump that was never repinned. Do not ignore it.
 .cargo-bazel/
 
 # IDE
 .idea/
 *.iml
-.vscode/
+# Generated by ./build-ra.sh. Machine-specific: it embeds absolute output-base
+# paths and the host target triple, and committing it makes rust-analyzer skip
+# its (working) Cargo fallback on every other machine.
+rust-project.json
+.vscode/*
+!.vscode/extensions.json
+!.vscode/launch.json
+!.vscode/tasks.json
 *.swp
 *.swo
 *~
@@ -73,7 +83,3 @@ coverage/
 # Temporary files
 tmp/
 temp/
-
-*.md
-!BAZEL_RUST_GUIDE.md
-!README.md

MODULE.bazel

@@ -2,6 +2,67 @@
 # Bring in Rust rules
 bazel_dep(name = "rules_rust", version = "0.63.0")  # check for latest release
 
+###############################################################################
+## Rust toolchain
+###############################################################################
+#
+# Without this block, `toolchains = root.tags.toolchain or rules_rust.tags.toolchain`
+# (rules_rust rust/extensions.bzl:93) falls back to rules_rust's OWN toolchain
+# tag, which is `rust.toolchain(edition = "2021")` at rules_rust MODULE.bazel:48
+# and DEFAULT_RUST_VERSION = "1.86.0" at rust/private/common.bzl:34. Every target
+# in this repo was being compiled as edition 2021 by rustc 1.86.0 while every
+# Cargo.toml said edition 2024 and contributors ran whatever rustup gave them.
+#
+# `versions` MUST stay in sync with rust-toolchain.toml -- that file is the
+# cargo half of the same pin. If they drift, the two build systems are back to
+# using different compilers on the same source.
+
+rust = use_extension("@rules_rust//rust:extensions.bzl", "rust")
+rust.toolchain(
+    edition = "2024",
+    versions = ["1.94.1"],
+    # rules_rust 0.63.0 predates 1.94.1, so rust/known_shas.bzl has no entry for
+    # it. Without these, load_arbitrary_tool falls back to sha256 = "" and
+    # downloads the toolchain unverified (repository_utils.bzl:516-521).
+    # Regenerate on a version bump: python3 tools/pin_rust_toolchain.py <version>
+    sha256s = {
+        "cargo-1.94.1-aarch64-apple-darwin.tar.xz": "57f4e445695decbdff1e10abdebd6af2b129b9baac531e691862a2861b222d87",
+        "cargo-1.94.1-aarch64-unknown-linux-gnu.tar.xz": "69a99d7f0af6d9a86c89c1f991953e924d9910eb06847524e3833063338e3923",
+        "cargo-1.94.1-x86_64-apple-darwin.tar.xz": "f8278da462908960eee660d7a20f34649b95805e2b741a5c09cd94cdddd82687",
+        "cargo-1.94.1-x86_64-unknown-linux-gnu.tar.xz": "03595624775204f80ff3a67986f69c8918e4cd311877ced635108888013a1e39",
+        "clippy-1.94.1-aarch64-apple-darwin.tar.xz": "79e34e43a0a2a4dd8849a1424d0bc1e0e7a7fdfc1052e8c4ea05d5d05d5986ce",
+        "clippy-1.94.1-aarch64-unknown-linux-gnu.tar.xz": "d35ce7705052d5bf43203012d8dceafcf13ca01ab9727f24c079b2ad9da45428",
+        "clippy-1.94.1-x86_64-apple-darwin.tar.xz": "ff91e9a2e3bac8eee40d52fa6b8c0f6ad93ee868d6d29a9d2e39802bc5e839a9",
+        "clippy-1.94.1-x86_64-unknown-linux-gnu.tar.xz": "883a8116360741aca335e12cc02c201e027473861c807027df19bb82583a8603",
+        "llvm-tools-1.94.1-aarch64-apple-darwin.tar.xz": "91430b90398a15d9285c88459105765e2c9575e50f7aba4a144c5bd25fdbc211",
+        "llvm-tools-1.94.1-aarch64-unknown-linux-gnu.tar.xz": "a3620d27ddee0c1a51d113f9703030a1b7964dd56c1b6eb4708665b738b3cc9f",
+        "llvm-tools-1.94.1-x86_64-apple-darwin.tar.xz": "d7dfb07b18a823bd135254b5bef90d5310cec881860a29d5851ffdb0edb9ed7e",
+        "llvm-tools-1.94.1-x86_64-unknown-linux-gnu.tar.xz": "058274dede890491d156aa9fe7da397e56c88f9b564bc15455f540f420d2ef9e",
+        "rust-src-1.94.1.tar.xz": "cb3756156fe6d2d6cedad327c94ad3721b612c4cd20dfb226d7543250788b66c",
+        "rust-std-1.94.1-aarch64-apple-darwin.tar.xz": "36574c7d66ea7978224aa4b672b61e6fd9bef55083b1d0caea06201e6dcfa3e1",
+        "rust-std-1.94.1-aarch64-unknown-linux-gnu.tar.xz": "2be613d5525a4ce8b7e2a1a55beeb64198314507be0d2da5aea4fd166cdde21f",
+        "rust-std-1.94.1-wasm32-unknown-unknown.tar.xz": "26b8953083b942aeaf870de742962e4ba17c0da2095725fbf4ab5ab85a4d5fd5",
+        "rust-std-1.94.1-wasm32-wasip1.tar.xz": "3d5073709bca32de85852e52c24e85e93574af59ddcc7fc7c56132de6c07a3cf",
+        "rust-std-1.94.1-x86_64-apple-darwin.tar.xz": "15fea4fdba0496abdd5c0d14fcd5a964ad42c7783163429e798967248c0a2419",
+        "rust-std-1.94.1-x86_64-unknown-linux-gnu.tar.xz": "74109ee2c19098f1d7122087dd338a8f643203b3ce678c9d58169db733e17a03",
+        "rustc-1.94.1-aarch64-apple-darwin.tar.xz": "3ae26df6f8c83a13e4190469d124de49970432b6f4517a0762d9bfffdff5b89b",
+        "rustc-1.94.1-aarch64-unknown-linux-gnu.tar.xz": "fb4ff31b71d7a2b6a793fb88fac18429befe807ddab3472bf87cbf92b6e5fbf6",
+        "rustc-1.94.1-x86_64-apple-darwin.tar.xz": "813dcb7968ec0c851baa77e5f605f215c0ab975a7bd608c614749263a3c66a61",
+        "rustc-1.94.1-x86_64-unknown-linux-gnu.tar.xz": "0a6b16ca476461c6238f48efcb74a7aa08a3983e61adf587f208ba48504d87e1",
+        "rustfmt-1.94.1-aarch64-apple-darwin.tar.xz": "41f004a12cb8fb0aa8c6e479cc8735e1303a2f8a57b887c5f9de7fd22afa9173",
+        "rustfmt-1.94.1-aarch64-unknown-linux-gnu.tar.xz": "05faec7ab676e867efe613e59c686b1e33d906256f0cc37bb16658e4e31b0f07",
+        "rustfmt-1.94.1-x86_64-apple-darwin.tar.xz": "e6c27213c98c9a4a5a8b9d46097a9bbc334fd1bb43a11c3c4cb4b28c8d3ad04e",
+        "rustfmt-1.94.1-x86_64-unknown-linux-gnu.tar.xz": "eaff8c808a1b82261e235002fc86ad217cba194525364cfd8d3a4de21c179d0f",
+    },
+)
+use_repo(rust, "rust_toolchains")
+
+register_toolchains("@rust_toolchains//:all")
+
+###############################################################################
+## Third-party crates
+###############################################################################
+
 # Use crate_universe extension
 crate = use_extension(
     "@rules_rust//crate_universe:extensions.bzl",

README.md

@@ -86,20 +86,23 @@ CARGO_BAZEL_REPIN=1 bazel sync --only=crates --enable_workspace
 ### 3. IDE Integration
 
 **rust-analyzer Setup**
-```bash
-# Generate rust-project.json
-bazel run @rules_rust//tools/rust_analyzer:gen_rust_project -- //...
 
-# VS Code settings.json
-{
-    "rust-analyzer.linkedProjects": ["rust-project.json"]
-}
+No editor configuration is required. rust-analyzer discovers `corex/`, `server/`
+and `combos/` as three separate Cargo projects on its own.
+
+For Bazel-accurate metadata — the Bazel-only edges such as `//corex:corex_lib`,
+and the exact flags Bazel passes to rustc — generate a `rust-project.json`:
+
+```bash
+./build-ra.sh
+# wraps: bazel run @rules_rust//tools/rust_analyzer:gen_rust_project -- //...
 ```
 
-**Automation Options**
-- VS Code tasks (see `.vscode/tasks.json`)
-- Keyboard shortcuts: `Cmd+R Cmd+R` to regenerate
-- Shell script: `./refresh-rust-analyzer.sh`
+That file is gitignored on purpose: it embeds absolute output-base paths and the
+host target triple, so it is only valid on the machine that produced it. Re-run
+`./build-ra.sh` after adding or renaming a Bazel target — a stale file points
+rust-analyzer at labels that no longer exist, and its mere presence stops
+rust-analyzer from falling back to Cargo.
 
 ### 4. Common Issues & Solutions
 

build-ra.sh

@@ -1,3 +1,18 @@
-#!/bin/bash
-# Regenerate rust-project.json for rust-analyzer
-bazel run @rules_rust//tools/rust_analyzer:gen_rust_project -- //...
+#!/usr/bin/env bash
+# Regenerate rust-project.json for rust-analyzer.
+#
+# The generated file is machine-specific -- it embeds absolute output-base paths
+# and the host target triple -- so it is gitignored. Run this after changing any
+# BUILD.bazel, or skip it entirely: rust-analyzer also discovers corex/, server/
+# and combos/ through plain Cargo.
+set -euo pipefail
+
+cd "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+BAZEL="${BAZEL:-$(command -v bazelisk || command -v bazel || true)}"
+if [[ -z "$BAZEL" ]]; then
+    echo "error: neither bazelisk nor bazel found on PATH" >&2
+    exit 1
+fi
+
+exec "$BAZEL" run @rules_rust//tools/rust_analyzer:gen_rust_project -- "${@:-//...}"