# rust-lang/rust-clippy architecture

> Architecture diagram of the GitHub repository rust-lang/rust-clippy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rust-lang/rust-clippy
- Repository: https://github.com/rust-lang/rust-clippy

## Overview

##### Project type and purpose
- This is **Clippy**, a Rust-based **linter tool** implemented as a collection of crates. It serves both as a Cargo subcommand (`cargo clippy`) and as a standalone driver (`clippy-driver`). Its purpose is to analyze Rust code (AST/HIR) for patterns matching one of 750+ lints and emit suggestions or errors.

##### File structure
- **Top-level crates** (in the workspace):
- `src/` – minimal driver that wires up clippy to Rust’s compiler API.
- `clippy_lints/` – definitions of the bulk of lint rules (each lint implemented in its own module).
- `clippy_utils/` – shared utilities (AST/HIR helpers, suggestion builders, diagnostics, MSRV support).
- `clippy_lints_internal/` – internal tooling to generate or validate lint registrations.
- `clippy_config/` – config file parser (`clippy.toml`, `.clippy.toml` support) and config-driven options.
- `clippy_dev/` – developer tooling: a server, release scripts, “new lint” scaffolding, dogfooding.
- `clippy_dummy/` – example crate/template for PUBLISH or lint bundles.
- `lintcheck/` – separate CLI to run Clippy across multiple crates/versions in CI.
- `rustc_tools_util/` – shared utilities for rustc tools (used by Clippy and rustfmt).
- `book/` – documentation site source.
- **Build & CI**: `.github/workflows/`, `util/` scripts, `Cargo.toml` (workspace manifest), `rust-toolchain.toml`, `clippy.toml`, `askama.toml` for template rendering.

##### README insights
- Clippy integrates deeply with Rust’s compiler as a **Rustc plugin/driver**.
- It loads lint-level categories, configuration files, supports MSRV enforcement, auto-fix (`--fix`), and CI integration.
- There is no external network dependency; it runs entirely in-process with the compiler’s APIs.

##### Main components & interactions
a. **Frontend / Entrypoint**
- **User CLI**: `cargo clippy` or `clippy-driver`.
- **Driver Module** (`src/driver.rs`, `src/main.rs`) initializes the plugin, reads flags, invokes the compiler.
b. **Configuration Loader**
- **clippy_config** parses `clippy.toml`/.clippy.toml and environment variables (e.g. MSRV).
c. **Lint Engine**
- **clippy_lints**: thousands of individual lint modules registered via `declare_clippy_lint!`.
- **clippy_lints_internal**: generates, validates macro expansions for lint registrations.
d. **Utility Library**
- **clippy_utils**: AST/HIR traversal, suggestions builder, diagnostic helpers, MSRV enforcement, type checks.
e. **Developer Tooling**
- **clippy_dev**: web server, formatter scripts, dogfooding utilities, setup helpers for editors.
- **lintcheck**: separate command-line tool to run lints across crates in CI contexts.
- **rustc_tools_util**: shared tools used by Clippy and related rustc-toolchain utilities.
f. **Documentation Site**
- **book/** uses Askama templates (`askama.toml`) to build HTML documentation.
g. **CI / Workflow**
- **.github/workflows/** automates lint checks, deployments, changelog generation.

Relationships & data flow:
1. User invokes CLI → Driver
2. Driver reads config via clippy_config
3. Driver hooks into Rustc → provides plugin callbacks
4. Rustc parsing produces AST/HIR → clippy_utils helpers → clippy_lints passes visit HIR
5. Lint passes produce Diagnostics → suggestions, fixes
6. Driver collects Diagnostics → prints to stdout, integrates with Cargo test output
7. Optional: `--fix` applies fixes back to source
8. lintcheck & clippy_dev operate separately on the workspace or lints registry
9. Documentation built from book/ and deployed via scripts in util/gh-pages

##### Architectural patterns and principles
- **Modular crate design**: each concern lives in its own crate for clear separation
- **Plugin architecture**: Clippy registers as a custom Rustc driver to inject lint passes
- **Macro-driven registration**: lint declarations & metadata generated via macros (in clippy_lints_internal)
- **Separation of concerns**: config parsing, lint logic, utilities, developer tooling, documentation all distinct

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Runtime Path"
        Driver["Driver"]:::runtime
        ConfigLoader["Config Loader"]:::runtime
        RustcAPI["Rustc API"]:::runtime
        Utils["Utility Library"]:::runtime
        LintInternal["Lint Registration Tooling"]:::runtime
        LintEngine["Lint Engine"]:::runtime
    end

    Driver -->|"reads config"| ConfigLoader
    Driver -->|"registers plugin"| RustcAPI
    RustcAPI -->|"AST/HIR"| Utils
    Utils -->|"assist lint passes"| LintEngine
    LintInternal -->|"generate registrations"| LintEngine
    LintEngine -->|"diagnostics"| Driver

    subgraph "Developer Tooling"
        DevTools["clippy_dev"]:::dev
        LintCheck["lintcheck"]:::dev
        SharedTools["rustc_tools_util"]:::dev
    end

    DevTools -->|uses| LintEngine
    DevTools -->|uses| ConfigLoader
    DevTools -->|uses| Docs
    LintCheck -->|runs lints on crates| LintEngine
    SharedTools -.->|shared utils| Driver

    subgraph "Documentation"
        Docs["Documentation (book)"]:::docs
    end

    subgraph "CI / Workflows"
        CI[".github/workflows"]:::ci
    end

    CI -.->|triggers| Driver
    CI -.->|runs| LintCheck
    CI -.->|deploys| Docs

    %% Click Events
    click Driver "https://github.com/rust-lang/rust-clippy/blob/master/src/main.rs"
    click Driver "https://github.com/rust-lang/rust-clippy/blob/master/src/driver.rs"
    click ConfigLoader "https://github.com/rust-lang/rust-clippy/blob/master/clippy_config/src/conf.rs"
    click ConfigLoader "https://github.com/rust-lang/rust-clippy/blob/master/clippy_config/src/lib.rs"
    click ConfigLoader "https://github.com/rust-lang/rust-clippy/blob/master/clippy_config/src/metadata.rs"
    click ConfigLoader "https://github.com/rust-lang/rust-clippy/blob/master/clippy_config/src/types.rs"
    click LintEngine "https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints/src/lib.rs"
    click LintEngine "https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints/src/declare_clippy_lint.rs"
    click LintInternal "https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints_internal/src/lib.rs"
    click LintInternal "https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints_internal/src/msrv_attr_impl.rs"
    click LintInternal "https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints_internal/src/outer_expn_data_pass.rs"
    click LintInternal "https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints_internal/src/internal_paths.rs"
    click Utils "https://github.com/rust-lang/rust-clippy/blob/master/clippy_utils/src/lib.rs"
    click Utils "https://github.com/rust-lang/rust-clippy/blob/master/clippy_utils/src/ast_utils/mod.rs"
    click Utils "https://github.com/rust-lang/rust-clippy/blob/master/clippy_utils/src/diagnostics.rs"
    click Utils "https://github.com/rust-lang/rust-clippy/blob/master/clippy_utils/src/sugg.rs"
    click Utils "https://github.com/rust-lang/rust-clippy/blob/master/clippy_utils/src/msrvs.rs"
    click Utils "https://github.com/rust-lang/rust-clippy/blob/master/clippy_utils/src/hir_utils.rs"
    click Utils "https://github.com/rust-lang/rust-clippy/blob/master/clippy_utils/src/mir/mod.rs"
    click DevTools "https://github.com/rust-lang/rust-clippy/blob/master/clippy_dev/src/main.rs"
    click DevTools "https://github.com/rust-lang/rust-clippy/blob/master/clippy_dev/src/lib.rs"
    click DevTools "https://github.com/rust-lang/rust-clippy/blob/master/clippy_dev/src/serve.rs"
    click DevTools "https://github.com/rust-lang/rust-clippy/blob/master/clippy_dev/src/new_lint.rs"
    click DevTools "https://github.com/rust-lang/rust-clippy/blob/master/clippy_dev/src/release.rs"
    click DevTools "https://github.com/rust-lang/rust-clippy/blob/master/clippy_dev/src/dogfood.rs"
    click DevTools "https://github.com/rust-lang/rust-clippy/blob/master/clippy_dev/src/fmt.rs"
    click DevTools "https://github.com/rust-lang/rust-clippy/blob/master/clippy_dev/src/setup/mod.rs"
    click LintCheck "https://github.com/rust-lang/rust-clippy/blob/master/lintcheck/src/main.rs"
    click LintCheck "https://github.com/rust-lang/rust-clippy/blob/master/lintcheck/src/driver.rs"
    click LintCheck "https://github.com/rust-lang/rust-clippy/blob/master/lintcheck/src/config.rs"
    click LintCheck "https://github.com/rust-lang/rust-clippy/blob/master/lintcheck/src/output.rs"
    click LintCheck "https://github.com/rust-lang/rust-clippy/blob/master/lintcheck/src/json.rs"
    click SharedTools "https://github.com/rust-lang/rust-clippy/blob/master/rustc_tools_util/src/lib.rs"
    click Docs "https://github.com/rust-lang/rust-clippy/blob/master/book/book.toml"
    click Docs "https://github.com/rust-lang/rust-clippy/blob/master/book/src/SUMMARY.md"
    click Docs "https://github.com/rust-lang/rust-clippy/blob/master/book/src/usage.md"
    click CI "https://github.com/rust-lang/rust-clippy/blob/master/.github/workflows/clippy_pr.yml"
    click CI "https://github.com/rust-lang/rust-clippy/blob/master/.github/workflows/lintcheck.yml"
    click CI "https://github.com/rust-lang/rust-clippy/blob/master/.github/workflows/deploy.yml"

    %% Styles
    classDef runtime fill:#e6ffe6,stroke:#2f6627,stroke-width:1px;
    classDef dev fill:#e6f0ff,stroke:#1e3a8a,stroke-width:1px;
    classDef docs fill:#fff2e6,stroke:#cc5200,stroke-width:1px;
    classDef ci fill:#f2f2f2,stroke:#666666,stroke-width:1px;
```
