GO — Healthy across the board

• Last commit today
• 21+ active contributors
• Distributed ownership (top contributor 35% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard}

Ruff is an extremely fast Python linter and formatter written in Rust that replaces Flake8, Black, isort, and 900+ linting rules in a single unified tool. It achieves 10-100x performance improvements over traditional Python linters by leveraging Rust's speed and implements native re-implementations of popular Flake8 plugins like flake8-bugbear. The core linting engine lives in crates/ruff_linter/, the formatter in crates/ruff_python_formatter/, and the Python parser in crates/ruff_python_parser/. Workspace monorepo with crates/ containing 20+ specialized packages: ruff_linter/ (core linting engine), ruff_python_formatter/ (formatting rules), ruff_python_parser/ (AST parsing), ruff_python_semantic/ (semantic analysis), ruff_db/ (caching layer), and ruff_options_metadata/ (configuration). The CLI entry point wraps these modules via crates/ruff/. Configuration cascades through pyproject.toml discovery per .github/ty-ecosystem.toml patterns.

Python developers and teams who need blazingly fast linting and formatting in CI/CD pipelines, large monorepos, and development workflows. Contributors include Astral maintainers and open-source Python community members who need better alternatives to slow existing tools like Flake8 and Black.

Production-ready and actively maintained. The project is well-established (v0.15.20 at time of snapshot), has comprehensive CI workflows (11+ GitHub Actions workflows in .github/workflows/), uses advanced testing infrastructure (nextest config in .config/nextest.toml), ships pre-built binaries, publishes to PyPI, and has hierarchical configuration support. Last signals show active development with Docker builds, WASM compilation, and ecosystem testing.

Low risk for adoption but high maintenance surface area due to broad scope: it replaces 5+ tools (Flake8, Black, isort, pydocstyle, pyupgrade, autoflake), so breaking changes in any rule implementation could affect users. The dual-language nature (Rust + Python) increases onboarding friction, and the monorepo structure with 20+ interdependent crates (ruff_db, ruff_formatter, ruff_linter, etc.) means changes require careful coordination. However, the active CI/CD setup and stable versioning (0.15.x indicates maturity) mitigate risk.

Active ecosystem integration and stability work: .github/workflows/notify-dependents.yml and ecosystem testing (.github/ty-ecosystem.toml) suggest testing against dependent Python packages. Daily fuzz testing (daily_fuzz.yaml), memory profiling (memory_report.yaml), and platform-specific binary builds (Darwin, Linux, Windows) indicate focus on correctness and performance. The .agents/skills/ directory with 'adding-ty-diagnostics', 'minimizing-ty-ecosystem-changes', and 'summarise-ecosystem-results' suggests AI-assisted development and systematic impact analysis on the Python ecosystem.

git clone https://github.com/astral-sh/ruff.git
cd ruff
cargo build --release  # builds all crates in workspace
cargo run --bin ruff -- --help  # test the CLI

For development setup, the .devcontainer/ and .claude/hooks/ suggest VS Code devcontainer support (devcontainer.json) and custom session hooks available.

Daily commands:

cargo build  # compile all crates
cargo test  # run test suite (uses nextest from .config/nextest.toml)
cargo run --bin ruff -- check .  # lint current directory
cargo run --bin ruff -- format .  # format files

For specific crate testing: cargo test -p ruff_linter or cargo test -p ruff_python_formatter. The project uses cargo exclusively; no Node/npm or Python setuptools required for core development.

• Cargo.toml — Workspace root configuration defining all member crates, dependencies, and Rust edition (2024); essential for understanding project structure and build setup.
• crates/ruff/src — Core linter and formatter implementation; the primary entry point for understanding how Ruff analyzes and transforms Python code.
• .github/workflows/ci.yaml — Main CI/CD pipeline defining test, lint, and build processes that all contributors must pass before merge.
• CONTRIBUTING.md — Contribution guidelines, code style, and development workflow expectations for all contributors.
• crates/ruff_diagnostics — Diagnostic and error reporting framework shared across all linting rules; fundamental to rule implementation.
• README.md — Project overview, feature summary, and links to documentation; essential context for understanding scope and use cases.
• .claude/settings.json — AI assistant configuration and context settings for Claude agents working within the codebase.

• ruff (main CLI) (Clap CLI framework, Rayon for parallelism) — Entry point and command-line interface; orchestrates parser, linter, formatter, and output.
  • Failure mode: Invalid CLI arguments, file I/O errors, or panic in downstream components crash the tool.
• Python Parser (rustpython parser or vendored parser) — Converts Python source code into AST representation for analysis; must handle all modern Python syntax.
  • Failure mode: Syntax errors in source files cause parse failure; tool reports file as unparseable.
• Rule Engine (Visitor pattern, ruff_diagnostics framework) — Applies all enabled linting rules to AST nodes via visitor pattern; generates diagnostics.
  • Failure mode: Rule panics or infinite loop during traversal crashes linter; must be caught in tests.
• Cache Layer (ruff_cache, file system or in-memory storage) — Stores parsed AST and diagnostic results to avoid re-analyzing unchanged files across runs.
  • Failure mode: Corrupted cache invalidates incremental results; tool falls back to full re-analysis.
• Formatter (AST reconstruction, ruff_formatter) — Rewrites AST back to Python source code with consistent style and formatting rules applied.
  • Failure mode: Formatting logic error produces syntactically invalid Python output; typically caught by round-trip tests.
• Output Renderer (ruff_annotate_snippets, serde for JSON/SARIF serialization) — Formats diagnostics and code output in user-requested format (JSON, SARIF, diff, plain text).
  • Failure mode: Serialization error or malformed output; typically non-fatal but confuses downstream tooling.

• User CLI → Python Parser — File paths and configuration passed; source code read from disk.
• Python Parser → Cache Layer — AST and metadata stored for future runs; file hash/mtime used as cache key.
• Cache Layer → Rule Engine — AST retrieved from cache or freshly parsed; fed to linting rules.
• Rule Engine → Output Renderer — Diagnostics (violations) collected with line, column, rule code, and message.
• Output Renderer → User CLI — Formatted diagnostics and optional formatted code written to stdout/file.

Add a New Linting Rule

1. Create a new rule module in the appropriate rule set under crates/ruff/src/rules/ (crates/ruff/src/rules)
2. Implement the rule checker struct with diagnostic generation logic (crates/ruff/src/rules/{RULE_SET}/{rule_name}.rs)
3. Register the rule in the rule set's mod.rs and include in the visitor (crates/ruff/src/rules/{RULE_SET}/mod.rs)
4. Add test cases with expected diagnostics in the test module (crates/ruff/src/rules/{RULE_SET}/tests/)
5. Update documentation in docs/ directory with rule code, description, and examples (docs/rules/{RULE_SET}.md)

Add a New Formatting Style Option

1. Define the new configuration option in crates/ruff_formatter configuration structures (crates/ruff_formatter/src/config.rs)
2. Implement formatting logic in the appropriate formatter module using the configuration (crates/ruff_formatter/src/format/)
3. Add test case validating the formatting output with the new option enabled (crates/ruff_formatter/src/format/tests/)
4. Update pyproject.toml schema and CLI help text with the new option (crates/ruff/src/cli/mod.rs)

Optimize Performance for a Specific Check

1. Profile the rule using Rust benchmarks in benches/ or by measuring time with real codebases (crates/ruff/benches/)
2. Identify optimization opportunities: AST traversal patterns, redundant allocations, or unnecessary clones (crates/ruff/src/rules/{RULE_SET}/{rule_name}.rs)
3. Implement caching or early-exit logic using ruff_cache or incremental analysis patterns (crates/ruff_cache/src/lib.rs)
4. Verify improvement with before/after benchmarks and add regression test (crates/ruff/benches/)

• Rust — Compiled, memory-safe language enabling extreme performance and fast execution required for a developer tool processing large codebases on every save.
• AST-based analysis — Full syntax tree traversal allows accurate semantic analysis that regex or token-based approaches cannot provide, reducing false positives.
• Incremental caching (ruff_cache) — Avoids re-analyzing unchanged files, critical for IDE integration and developer iteration speed on large projects.
• Single-pass rule engine — Processes entire codebase in one traversal rather than multiple passes, minimizing I/O and memory overhead.

• Monolithic Rust codebase over plugin architecture

  • Why: Simplifies compilation, ensures consistent performance, and avoids FFI overhead of plugin boundaries.
  • Consequence: Adding rules requires Rust expertise and recompilation; cannot dynamically load custom rules at runtime.

• Strict Python compatibility over linting flexibility

  • Why: Ensures rules behave identically across all environments and Python versions.
  • Consequence: Cannot support all legacy Python versions simultaneously; requires explicit version targeting in configuration.

• Integrated linter and formatter in one tool

  • Why: Shared AST parsing and caching reduces redundant work when both operations are needed.
  • Consequence: Users cannot update linting and formatting independently; both use same release cycle.

• Does not provide real-time in-editor linting without IDE plugin integration
• Does not support user-defined custom rules via plugins or scripting
• Does not handle Python runtime behavior analysis or type checking at interpretation time
• Does not guarantee compatibility with all historical Python 2.x codebases

• Avg cyclomatic complexity: ~7 — Rust codebase with complex trait hierarchies (Visitor pattern, diagnostic builders), AST traversal logic, and performance-critical path. High cyclomatic complexity in rule implementations due to many edge cases.
• Largest file: crates/ruff/src/rules (50,000 lines)
• Estimated quality issues: ~12 — Some rules have high cyclomatic complexity; occasional unwrap() calls without proper bounds checking; cache invalidation logic is subtle and error-prone. Mitigated by comprehensive test suite and CI validation.

• Unbounded rule complexity (High) — crates/ruff/src/rules/{RULE_SET}/{rule_name}.rs: Rules that traverse entire AST multiple times or perform O(n²) comparisons can dominate total linting time; should use incremental checks and early exits.
• Cache invalidation mismatches (Medium) — crates/ruff_cache/src/lib.rs: Cache key based on file mtime alone can miss edits if system clock skew occurs; should use content hash.
• Diagnostic allocation per violation (Medium) — crates/ruff_diagnostics/src/lib.rs: Allocating large diagnostic structs for every violation in a file with thousands of issues wastes memory; should batch or stream.
• Panic on malformed input (High) — crates/ruff/src/rules: Rules that unwrap() without bounds checks can panic on edge-case Python syntax; should gracefully skip nodes or return None.

• Python Parser (rustpython or vendored) (I/O and CPU bound) — Parsing large files (>1MB) can consume significant CPU and memory; incremental re-parsing not supported.
• ruff_cache serialization/deserialization (CPU bound) — Serde operations on large ASTs can add 10–20% overhead; consider binary format or streaming.
• Rule Engine visitor with many rules (CPU bound) — Each rule walks same AST nodes; parallelism per-file helps but single-threaded per-rule is inherent.
• Output rendering (SARIF, JSON) for many diagnostics (Memory and CPU bound) — Serializing thousands of diagnostics with full context (code snippets, source spans) can be slow; consider lazy rendering.

Rust edition 2024: Very recent (check local rustc --version compatibility; rust-version in Cargo.toml is 1.94, a nightly-adjacent version). Parser complexity: The Python parser in ruff_python_parser/ is a hand-written recursive descent parser, not a generated one—understanding its token management is non-obvious. Cache serialization: ruff_cache/ uses bincode serialization; changing AST structures can invalidate caches silently (no auto-migration). PyPI packaging: The Python package is generated from Rust via maturin (not visible in file list but implied by multi-language setup); building wheels locally requires additional tooling. Configuration discovery: pyproject.toml lookup is hierarchical and cascading; tests may behave differently depending on ancestor config files in the filesystem. Notebook support: ruff_notebook/ handles Jupyter cells; rules may need separate logic for in-notebook parsing.

• AST (Abstract Syntax Tree) — Ruff's entire linting and formatting pipeline is built on AST analysis via ruff_python_ast and ruff_python_parser; understanding how Python code is represented as a tree is foundational to modifying rules
• Semantic Analysis / Scope Tracking — The ruff_python_semantic crate implements scope binding and reference tracking; this powers context-aware rules like unused import detection and is critical for writing sophisticated linting rules
• Incremental Caching — Ruff's speed advantage relies on ruff_cache and ruff_db for avoiding re-analysis of unchanged files; understanding cache invalidation is key to the performance promise
• Hierarchical Configuration Discovery — Ruff cascades configuration from parent pyproject.toml files up the directory tree; this pattern affects how rules apply differently in monorepos and requires careful testing
• Code Formatter Design Patterns (Line Breaking, Precedence) — The ruff_python_formatter implements Black's algorithm for line-length-aware formatting with precedence-aware breaks; useful for understanding how formatter rules interact
• Diagnostic Reporting and Annotation — The ruff_diagnostics and ruff_annotate_snippets crates format linting output with code snippets and suggestions; modifying how diagnostics appear requires understanding this pipeline
• Workspace-based Monorepo Architecture — The 20+ crates in crates/ are interdependent and versioned together via Cargo.toml workspace; changes to shared types (e.g., ruff_python_ast) cascade to all consumers, requiring careful testing

• psf/black — Ruff's formatter aims for drop-in parity with Black; understanding Black's algorithm is useful for formatting rule modifications
• PyCQA/flake8 — Ruff re-implements Flake8's rule set natively; reference implementation for understanding linting behavior
• PyCQA/isort — Ruff includes isort-compatible import sorting; relevant for understanding sort order logic in the formatter
• astral-sh/ruff-vscode — Official VS Code extension providing LSP integration; shows how to consume Ruff's outputs in an editor plugin
• astral-sh/uv — Sibling Astral project (fast Python package manager in Rust); shares architecture patterns and dependency management philosophy

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for ruff_db crate with integration tests

The ruff_db crate (database/indexing layer) is a critical dependency across the monorepo but lacks visible integration tests in the file structure. Given Ruff's focus on performance and correctness, adding a test suite that validates database operations, caching behavior, and concurrent access patterns would prevent regressions and establish benchmarks for the indexing system.

• [ ] Create crates/ruff_db/tests/ directory with integration test module
• [ ] Add tests for database initialization, querying, and persistence across crates/ruff_db/src/
• [ ] Add benchmarks in crates/ruff_db/benches/ for common database operations
• [ ] Update .config/nextest.toml if needed to include new test groups
• [ ] Document test patterns in CONTRIBUTING.md for future DB contributors

Implement missing GitHub Action for ecosystem regression detection

The repo has .github/workflows/ty-ecosystem-analyzer.yaml and ty-ecosystem-report.yaml, but lacks a workflow that automatically runs on PRs to detect breaking changes against popular Python packages. This would catch regressions early and complement the existing skill in .agents/skills/minimizing-ty-ecosystem-changes/.

• [ ] Create .github/workflows/pr-ecosystem-check.yml that runs ty-ecosystem tests on modified rule files
• [ ] Reference .github/ty-ecosystem.toml configuration in the new workflow
• [ ] Add step to comment on PRs with ecosystem impact summary using the report template from .agents/skills/summarise-ecosystem-results/assets/report-template.md
• [ ] Update CONTRIBUTING.md to document the ecosystem check requirement for rule changes
• [ ] Ensure workflow respects the minimize-changes strategy from .agents/skills/minimizing-ty-ecosystem-changes/

Add missing documentation for agent skills system in AGENTS.md

The .agents/ directory contains a sophisticated skill system (.agents/skills/*) with specific expertise in diagnostics, ecosystem minimization, and reporting, but AGENTS.md appears minimal or incomplete. This documentation would help contributors understand how to extend Ruff's AI-assisted development capabilities and contribute new skills.

• [ ] Expand AGENTS.md with a 'Skills' section documenting each skill in .agents/skills/
• [ ] Add examples for each skill from .agents/skills//SKILL.md and .agents/skills//references/
• [ ] Document the Claude plugin setup in .agents/.claude-plugin/ with marketplace.json and plugin.json
• [ ] Create a 'Contributing Skills' guide explaining the SKILL.md structure and skill.json schema
• [ ] Link to specific use cases like the ty-ecosystem workflow integration

• Add missing test coverage for rule implementations in crates/ruff_linter/src/rules/ that lack snapshot tests; pick an existing rule and create a test.rs file alongside it with edge cases
• Improve error messages for one formatter rule in crates/ruff_python_formatter/src/ by adding concrete examples in the diagnostics (look for TODO or FIXME comments in source)
• Document the Python parser's token stream model by adding doc comments to crates/ruff_python_parser/src/lib.rs; this is the entry point for understanding how the parser works

The Ruff codebase has a generally good security posture as a Rust-based linter. No critical vulnerabilities were identified in the provided configuration files. The primary concerns are Docker/CI/CD configuration practices: unverified script execution during toolchain installation and unpinned package versions in container builds. The codebase itself appears well-maintained by Astral with clear dependency management through Cargo workspaces. No hardcoded secrets, injection vulnerabilities, or exposed credentials were detected in the visible file structure. Recommendations focus on improving supply chain security in the build pipeline.

• Medium · Rust Toolchain Downloaded Over HTTPS Without Checksum Verification — Dockerfile - RUN curl line. The Dockerfile downloads the Rust toolchain installation script from https://sh.rustup.rs and executes it with sh -s without verifying its integrity via checksum or GPG signature. While HTTPS provides transport security, the script should be verified with a known hash before execution. Fix: Verify the downloaded script against a known checksum before execution, or use the official Rust Docker images that pre-include verified toolchains. Example: curl ... | sha256sum -c expected_hash.txt && sh -s --
• Low · Docker Build Uses Latest Package Versions Without Pinning — Dockerfile - FROM and RUN apt install lines. The Dockerfile uses 'apt install -y' without specifying package versions, which could lead to unexpected behavior if dependencies introduce breaking changes or vulnerabilities. Additionally, 'apt update' is called without a base image tag specification. Fix: Pin the Ubuntu base image to a specific version (e.g., ubuntu:22.04 instead of ubuntu), and pin package versions in apt install commands (e.g., build-essential=12.x.x).
• Low · Incomplete Docker Build Configuration — Dockerfile - End of file. The Dockerfile snippet appears incomplete (ends with 'COPY Cargo.toml Car'), making it impossible to fully assess the build security. The build context and final stages are not visible. Fix: Provide the complete Dockerfile configuration for comprehensive security analysis. Ensure multi-stage builds are used to minimize final image size and reduce attack surface.
• Low · Python Virtual Environment Usage in Docker — Dockerfile - venv setup. While using venv inside Docker is not necessarily wrong, it adds complexity. The venv activation is stored in PATH, but this could be simplified with native pip or using Python from the system. Fix: Consider using system Python directly or document why venv is necessary in this container context. Ensure the .venv directory is not included in the final image if using multi-stage builds.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/astral-sh/ruff shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live astral-sh/ruff repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/astral-sh/ruff.

What it runs against: a local clone of astral-sh/ruff — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in astral-sh/ruff | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of astral-sh/ruff. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/astral-sh/ruff.git
#   cd ruff
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of astral-sh/ruff and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "astral-sh/ruff(\\.git)?\\b" \\
  && ok "origin remote is astral-sh/ruff" \\
  || miss "origin remote is not astral-sh/ruff (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "crates/ruff/src" \\
  && ok "crates/ruff/src" \\
  || miss "missing critical file: crates/ruff/src"
test -f ".github/workflows/ci.yaml" \\
  && ok ".github/workflows/ci.yaml" \\
  || miss "missing critical file: .github/workflows/ci.yaml"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"
test -f "crates/ruff_diagnostics" \\
  && ok "crates/ruff_diagnostics" \\
  || miss "missing critical file: crates/ruff_diagnostics"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/astral-sh/ruff"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.