ruff_workspace

Settings model and configuration resolution. Source: crates/ruff_workspace/.

Purpose

Convert user-facing TOML configuration (pyproject.toml [tool.ruff] section, ruff.toml, .ruff.toml, CLI overrides) into the strongly-typed Settings struct that ruff_linter and ruff_python_formatter consume.

Directory layout

crates/ruff_workspace/src/
├── lib.rs
├── configuration.rs   # TOML schema → Configuration
├── options.rs         # Options struct (the big serde target)
├── pyproject.rs       # pyproject.toml-specific loading
├── resolver.rs        # walks up file tree to find config
├── settings.rs        # the resolved Settings struct
└── ...

Key abstractions

Type	Purpose
Options	Mirrors the user's TOML file. Every option is Option<T> so we can layer overrides.
Configuration	An intermediate built from one or more Options.
Settings	Final, fully-resolved configuration consumed downstream.
Resolver	Walks up directories collecting configs; honors extend = ".../base.toml".
PerFileSettings	Allows different settings per file glob.

Resolution order

graph LR
    Defaults[Defaults]
    Workspace["Workspace TOML<br/>pyproject.toml / ruff.toml"]
    Inline[Inline overrides<br/>extend / per-file-ignores]
    CLI[CLI flags<br/>--select / --ignore / --line-length]
    Settings

    Defaults --> Stage1[Configuration]
    Workspace --> Stage1
    Inline --> Stage1
    CLI --> Stage1
    Stage1 --> Settings

Schema generation

Options derives metadata via macros from ruff_macros and ruff_options_metadata. Running cargo dev generate-all (or RUFF_UPDATE_SCHEMA=1 cargo test) walks this metadata to produce:

• ruff.schema.json — the JSON Schema for pyproject.toml / ruff.toml.
• The configuration reference page in docs/.

Adding or changing an option without regenerating these files will fail CI.

Per-file overrides

per-file-ignores and extend-per-file-ignores resolve to PerFileSettings keyed by glob. The linter consults this map when running rules; matched files have a different rule set than the default.

Integration points

• Consumed by ruff CLI (crates/ruff/src/resolve.rs), ruff_server, ruff_wasm.
• The Settings struct is passed to ruff_linter and ruff_python_formatter.

Modifying

• New option: add it to Options, populate it through Configuration and Settings, regenerate the schema.
• New CLI flag: add to crates/ruff/src/args.rs and forward to Options::override_with(...) (or equivalent).
• Always add a documentation comment on the new field — it ends up in the rendered docs.

See reference/configuration for a user-side view of the same options.