Tooling

The day-to-day toolbelt this repo expects you to use.

Cargo workspace

Everything is a single Cargo workspace at the repo root. Common entry points:

cargo build                       # debug build of all crates
cargo run -p ruff -- ...          # run the ruff CLI
cargo run --bin ty -- ...         # run the ty CLI
cargo test -p <crate>             # tests for one crate
cargo nextest run                 # tests for all crates (faster, recommended)
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo doc --no-deps --open

Profiles are tuned for development:

• dev (default) — fast incremental builds.
• The AGENTS.md env-var preset (CARGO_PROFILE_DEV_OPT_LEVEL=1, CARGO_PROFILE_DEV_DEBUG="line-tables-only") gives a much faster test run while keeping debug info.
• release — for benchmarking and releases. Enables full optimization.

Toolchain is pinned in rust-toolchain.toml; rustup will install the right version on first use.

cargo dev (the project CLI)

cargo dev is an alias for cargo run -p ruff_dev --. Subcommands:

Command	Purpose
cargo dev generate-all	Regenerate ruff.schema.json, ty.schema.json, the rules table in docs, the CLI reference. Run after changing rules, options, env vars, or CLI args.
cargo dev print-ast <file>	Pretty-print the AST for a Python file.
cargo dev print-cst <file>	Print the CST (with trivia).
cargo dev print-tokens <file>	Print the lexer's token stream.
cargo dev print-noqa <file>	Show the parsed noqa directives.
cargo dev round-trip <file>	Parse → unparse → reparse and check equivalence.
cargo dev format-dev	Format-stability tests against an internal corpus.

Source: crates/ruff_dev/.

prek (pre-commit replacement)

prek runs the project's hooks the way CI does. It's a faster Rust-based pre-commit alternative.

uv tool install prek
prek install              # install git hooks
prek run -a               # run all hooks against all files
prek run -a <hook-id>     # run a specific hook

The hook config is .pre-commit-config.yaml at the repo root. Hooks include:

• Rust formatting (rustfmt) and Clippy
• TOML/YAML linting
• Markdown linting (markdownlint-cli2)
• Spelling (typos, configured via _typos.toml)
• The pyproject schema sanity check

Run uvx prek run -a at the end of a task, after every rebase, and before pushing.

uv and uvx

uv is Astral's Python package manager and is required to run Python utility scripts in this repo:

uvx ruff check ...                    # run the released Ruff CLI in an isolated env
uv run scripts/setup_primer_project.py  # ty ecosystem reproductions
uv run --with-requirements docs/requirements.txt mkdocs serve -f mkdocs.template.yml

The repo's pyproject.toml lists Python dev dependencies; uv sync will install them.

Codegen targets

Several files are checked-in but generated. CI will fail if they drift:

File	Generated by
ruff.schema.json	RUFF_UPDATE_SCHEMA=1 cargo test or cargo dev generate-all
ty.schema.json	cargo dev generate-all
docs/rules/*.md rule reference	cargo dev generate-all
Some snapshots in crates/*/snapshots/	cargo nextest run with INSTA_UPDATE=always

Benchmarks

cargo bench -p ruff_benchmark           # criterion benchmarks for the linter
cargo bench -p ty_completion_bench      # ty completion latency

The CodSpeed integration (codspeed-criterion-compat) wires these benchmarks into the CodSpeed dashboard via CI.

Fuzzing

cd fuzz
cargo +nightly fuzz list
cargo +nightly fuzz run <target>

Fuzz targets cover the parser, the formatter idempotency property, and a few rule-specific oracles.

Documentation site

uv run --with-requirements docs/requirements.txt mkdocs serve -f mkdocs.template.yml

The published site at https://docs.astral.sh/ruff is built from the same template. The site uses mkdocs-material and embeds the rules table generated by cargo dev generate-all.

Playground

cd playground
npm install
npm run dev

The web playground (https://play.ruff.rs) wraps crates/ruff_wasm and crates/ty_wasm. The wasm crates expose check, format, and infer-style entry points consumed by the JS frontend.

CI overview

GitHub Actions workflows live in .github/workflows/:

• ci.yaml — build, test, clippy, prek hooks.
• Format-stability checks (formatter corpus).
• Fuzz smoke runs.
• Docs build.
• Release cut (tag-driven).

Most workflows run on every PR; the heavier corpus and benchmark jobs run on a schedule.