astral-sh/ruff

Ruff's clap `Command` enum is the product surface: lint, format, an LSP server, rule and config help, cache cleaning, shell completions, and an import graph. The linter reimplements a large set of Flake8-family plugins as native rules under `ruff_linter::rules`, selected by code or category. ty exposes check (with fix and ignore insertion), a language server, and `explain rule`. Both tools have WASM playgrounds; Ruff also formats notebooks and can watch the filesystem.

• `ruff check` (`CheckCommand`) accepts paths or `-` for stdin, `--fix` / `--fix-only` / `--diff` / `--unsafe-fixes`, `--watch`, `--ignore-noqa`, `--add-noqa` and `--add-ignore`, `--select` / rule selectors, `--target-version`, `--preview`, and `--output-format` from `RUFF_OUTPUT_FORMAT` plus `--output-file` from `RUFF_OUTPUT_FILE`. `--show-settings` and `--show-files` short-circuit before linting.
  crates/ruff/src/args.rs#L133-L186crates/ruff/src/args.rs#L231-L279crates/ruff/src/lib.rs#L237-L277
• Default fix behavior generates fixes but does not write them. `--diff` selects `FixMode::Diff`; `--fix` or `--fix-only` selects `FixMode::Apply`; otherwise `FixMode::Generate`. Applicability stays automatic unless `--unsafe-fixes` is set. `--add-noqa` / `--add-ignore` refuse newlines in the reason and are incompatible with `--fix`.
  crates/ruff/src/lib.rs#L279-L364
• `ruff format` (`FormatCommand`) writes files by default. `--diff` selects `FormatMode::Diff` and `--check` selects `FormatMode::Check`. `--range` is rejected when the resolved path set contains more than one file. Stdin is handled by `commands::format_stdin::format_stdin` instead of `commands::format::format`.
  crates/ruff/src/lib.rs#L214-L221crates/ruff/src/commands/format.rs#L48-L92
• Formatting itself is `format_module_source`: parse with `ParseOptions` from the source type, build `TriviaRanges`, `format_module_ast`, then `print`. Parse, format, and print failures become `FormatModuleError` and map to `DiagnosticId::InternalError`.
  crates/ruff_python_formatter/src/lib.rs#L99-L155
• `ruff server` is the editor integration. Request handlers registered in `ruff_server` are code action, code-action resolve, document diagnostic, execute command, format, format range, hover, and shutdown. Notifications include didOpen/didChange/didClose for text documents and notebooks, configuration, watched files, and workspace changes. Code-action kinds include `source.fixAll.ruff` and `source.organizeImports.ruff` (plus notebook variants).
  crates/ruff_server/src/lib.rs#L24-L33crates/ruff_server/src/server/api/requests.rs#L1-L24crates/ruff_server/src/server/api/notifications.rs#L1-L23crates/ruff_server/src/server/api/diagnostics.rs#L8-L39
• Other Ruff subcommands: `rule` (one rule or `--all`), `config` (one option or the catalog), `linter` (upstream linter list), `clean`, hidden `generate-shell-completion`, `version`, and `analyze graph` (`AnalyzeGraphCommand`: direction, string-import detection, `--python` venv, type-checking imports, preview, target version).
  crates/ruff/src/args.rs#L133-L228crates/ruff/src/lib.rs#L170-L210
• Native lint plugins are the `Linter` enum in `registry.rs` (prefixes such as AIR, E/W via pycodestyle, F, S, B, I, UP, PL, RUF) and matching modules under `crates/ruff_linter/src/rules/` (`airflow` through `tryceratops`, including `pyflakes`, `pylint`, `pyupgrade`, `isort`, `flake8_bugbear`, `ruff`). `code_to_rule` is the `#[ruff_macros::map_codes]` table that maps `(Linter, code)` to a rule struct.
  crates/ruff_linter/src/registry.rs#L34-L150crates/ruff_linter/src/rules/mod.rs#L1-L59crates/ruff_linter/src/codes.rs#L237-L249
• `ty` subcommands are `check`, `server`, `version`, hidden `generate-shell-completion`, and `explain rule`. `ty check` takes paths, `--project`, `--config-file`, `--fix`, `--add-ignore`, `--watch`, `--exit-zero`, color, verbosity, and progress flags. Fix mode is `FixMode::ApplyFixes` or `FixMode::AddIgnore`; plain runs are `MainLoopMode::Check`.
  crates/ty/src/args.rs#L33-L73crates/ty/src/lib.rs#L54-L77crates/ty/src/lib.rs#L133-L139
• ty diagnostics come from `ty_python_semantic::check_file`: I/O errors, parse errors, unsupported-syntax errors (with an inferred-version hint), then `check_types`. Lints are `LintMetadata` values created with `declare_lint!` (kebab-case name, summary, docs, default `Level` of ignore/warn/error, status) and stored in `default_lint_registry`.
  crates/ty_python_semantic/src/lib.rs#L79-L97crates/ty_python_semantic/src/lib.rs#L204-L244crates/ty_python_semantic/src/lint.rs#L10-L55crates/ty_python_semantic/src/lint.rs#L256-L281
• The Ruff WASM API exposes `Workspace` with `version`, a constructor from JS `Options`, and `defaultSettings`. The playground README describes two SPAs (Ruff at play.ruff.rs and a ty playground) using Monaco, Vite, and localStorage, plus a Worker KV share store.
  crates/ruff_wasm/src/lib.rs#L268-L318playground/README.md#L1-L34playground/package.json#L9-L21
• Notebooks are first-class inputs: watch mode treats `.py`, `.pyi`, `.pyw`, and `.ipynb` as source and `.toml` as configuration, and `lint_path` lints `pyproject.toml` / `ruff.toml` when a TOML rule is enabled via `lint_fix_toml` / `lint_toml`.
  crates/ruff/src/lib.rs#L63-L92crates/ruff/src/diagnostics.rs#L215-L270
• `cargo dev` (`crates/ruff_dev`) is the maintainer CLI: `generate-all`, JSON schemas, rules tables, options docs, ty CLI/env/schema docs, `print-ast` / `print-cst` / `print-tokens`, formatter stability (`format-dev`), and `repeat` for profiling `ruff check`.
  crates/ruff_dev/src/main.rs#L1-L90