# adrienverge/yamllint architecture

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

- Interactive diagram: https://gitdiagram.com/adrienverge/yamllint
- Repository: https://github.com/adrienverge/yamllint

## Overview

##### Project Type and Purpose
- This is an open-source CLI tool (yamllint) written in Python 3 that performs linting on YAML files.
- It parses YAML documents, applies a suite of built-in rules to detect syntax errors, duplication, style issues, etc., and produces human-readable or machine-parsable reports.

##### High-Level Architecture Components
a. CLI Entrypoint
- yamllint/__main__.py
- yamllint/cli.py
– Parses command-line arguments (files, directories, formats, config path, rule overrides).
– Initializes logging, config, output format, and dispatches files for linting.
b. Configuration Manager
- yamllint/config.py
- yamllint/conf/*.yaml
– Loads default and user-provided configuration (default.yaml, relaxed.yaml).
– Merges CLI overrides and per-file ignore patterns.
– Provides rule-specific settings (severity, parameters, disable/enable).
c. Parser & Decoder
- yamllint/parser.py
- yamllint/decoder.py
– Uses PyYAML under the hood via decoder to produce an in-memory representation or event stream.
– Handles syntax validation, character encoding, and produces a uniform AST or token sequence.
d. Linter Core and Rule Engine
- yamllint/linter.py
- yamllint/rules/*.py
– Linter orchestrates applying each rule module to the parsed document.
– Implements a plugin-style pattern: each rule exposes a check() function or class that registers on certain node types or document events.
– Collects violation objects (line number, rule id, message, severity).
e. Output Formatter
- yamllint/cli.py (report functions)
– Honors CLI output format flags (-f, -q, etc.).
f. File System & I/O
– Scans directories, filters by extension, respects .gitignore-style patterns.
– Reads and writes to stdout and stderr.

##### Component Interactions and Data Flow
- User invokes `yamllint` (CLI) → CLI parses arguments → Configuration Manager loads/merges settings
→ CLI passes each file path to Parser → Decoder converts YAML text to AST/events → Linter applies each rule against AST/events (Rule Engine) → collects violations → CLI calls Output Formatter → prints report to console or file.

- Configuration Manager feeds rule engine with per-rule settings and ignore patterns.
- Rules are modular Python modules under yamllint/rules; new rules can be added without altering core logic.

##### Architectural Patterns and Principles
- Plugin Architecture: rule modules are discovered/imported dynamically.
- Separation of Concerns: CLI, config loading, parsing, linting logic, and output formatting are distinct layers.
- Configuration-Driven Behavior: virtually every aspect (enabled rules, severity, output format) is configurable.
- Test Harness: comprehensive tests under tests/ repeatedly exercise parser, decoder, rules, CLI, config for regression and spec compliance.

##### Final Advice
- Be exhaustive: include every major Python module group (cli, config, parser, decoder, linter, rules).
- Use consistent naming that matches the file tree (e.g., “yamllint/config.py”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & I/O Layer
    subgraph "User & I/O Layer"
        CLI_main["yamllint/__main__.py"]:::cli
        CLI_cli["yamllint/cli.py"]:::cli
        FileSystem["File System & I/O"]:::cli
    end

    %% Configuration Manager
    subgraph "Configuration Manager"
        Config_py["yamllint/config.py"]:::config
        ConfDefault["yamllint/conf/default.yaml"]:::config
        ConfRelaxed["yamllint/conf/relaxed.yaml"]:::config
    end

    %% Parser & Decoder
    subgraph "Parser & Decoder"
        Parser["yamllint/parser.py"]:::core
        Decoder["yamllint/decoder.py"]:::core
    end

    %% Linter Core / Rule Engine
    subgraph "Linter Core / Rule Engine"
        Linter["yamllint/linter.py"]:::core
        subgraph "Rules (Plugins)"
            RInit["yamllint/rules/__init__.py"]:::plugins
            anchors["yamllint/rules/anchors.py"]:::plugins
            braces["yamllint/rules/braces.py"]:::plugins
            brackets["yamllint/rules/brackets.py"]:::plugins
            colons["yamllint/rules/colons.py"]:::plugins
            commas["yamllint/rules/commas.py"]:::plugins
            comments["yamllint/rules/comments.py"]:::plugins
            comments_indentation["yamllint/rules/comments_indentation.py"]:::plugins
            common["yamllint/rules/common.py"]:::plugins
            document_end["yamllint/rules/document_end.py"]:::plugins
            document_start["yamllint/rules/document_start.py"]:::plugins
            empty_lines["yamllint/rules/empty_lines.py"]:::plugins
            empty_values["yamllint/rules/empty_values.py"]:::plugins
            float_values["yamllint/rules/float_values.py"]:::plugins
            hyphens["yamllint/rules/hyphens.py"]:::plugins
            indentation["yamllint/rules/indentation.py"]:::plugins
            key_duplicates["yamllint/rules/key_duplicates.py"]:::plugins
            key_ordering["yamllint/rules/key_ordering.py"]:::plugins
            line_length["yamllint/rules/line_length.py"]:::plugins
            new_line_at_end_of_file["yamllint/rules/new_line_at_end_of_file.py"]:::plugins
            new_lines["yamllint/rules/new_lines.py"]:::plugins
            octal_values["yamllint/rules/octal_values.py"]:::plugins
            quoted_strings["yamllint/rules/quoted_strings.py"]:::plugins
            trailing_spaces["yamllint/rules/trailing_spaces.py"]:::plugins
            truthy["yamllint/rules/truthy.py"]:::plugins
        end
    end

    %% Output Formatter
    subgraph "Output Formatter"
        Formatter["report functions in yamllint/cli.py"]:::cli
    end

    %% External Dependencies
    PyYAML["PyYAML"]:::external

    %% Flow
    CLI_main -->|"invokes"| CLI_cli
    CLI_cli -->|"loads config"| Config_py
    Config_py -->|"reads"| ConfDefault
    Config_py -->|"reads"| ConfRelaxed
    CLI_cli -->|"scans files"| FileSystem
    CLI_cli -->|"parses file"| Parser
    Parser -->|"uses"| PyYAML
    Parser -->|"AST/events"| Decoder
    Decoder -->|"normalized AST"| Linter
    Config_py -->|"rule settings"| Linter
    Linter -->|"loads rules"| RInit
    RInit --> anchors & braces & brackets & colons & commas & comments & comments_indentation & common & document_end & document_start & empty_lines & empty_values & float_values & hyphens & indentation & key_duplicates & key_ordering & line_length & new_line_at_end_of_file & new_lines & octal_values & quoted_strings & trailing_spaces & truthy
    Linter -->|"violations list"| Formatter
    Formatter -->|"outputs report"| FileSystem

    %% Click Events
    click CLI_main "https://github.com/adrienverge/yamllint/blob/master/yamllint/__main__.py"
    click CLI_cli "https://github.com/adrienverge/yamllint/blob/master/yamllint/cli.py"
    click Config_py "https://github.com/adrienverge/yamllint/blob/master/yamllint/config.py"
    click ConfDefault "https://github.com/adrienverge/yamllint/blob/master/yamllint/conf/default.yaml"
    click ConfRelaxed "https://github.com/adrienverge/yamllint/blob/master/yamllint/conf/relaxed.yaml"
    click Parser "https://github.com/adrienverge/yamllint/blob/master/yamllint/parser.py"
    click Decoder "https://github.com/adrienverge/yamllint/blob/master/yamllint/decoder.py"
    click Linter "https://github.com/adrienverge/yamllint/blob/master/yamllint/linter.py"
    click RInit "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/__init__.py"
    click anchors "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/anchors.py"
    click braces "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/braces.py"
    click brackets "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/brackets.py"
    click colons "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/colons.py"
    click commas "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/commas.py"
    click comments "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/comments.py"
    click comments_indentation "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/comments_indentation.py"
    click common "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/common.py"
    click document_end "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/document_end.py"
    click document_start "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/document_start.py"
    click empty_lines "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/empty_lines.py"
    click empty_values "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/empty_values.py"
    click float_values "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/float_values.py"
    click hyphens "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/hyphens.py"
    click indentation "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/indentation.py"
    click key_duplicates "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/key_duplicates.py"
    click key_ordering "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/key_ordering.py"
    click line_length "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/line_length.py"
    click new_line_at_end_of_file "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/new_line_at_end_of_file.py"
    click new_lines "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/new_lines.py"
    click octal_values "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/octal_values.py"
    click quoted_strings "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/quoted_strings.py"
    click trailing_spaces "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/trailing_spaces.py"
    click truthy "https://github.com/adrienverge/yamllint/blob/master/yamllint/rules/truthy.py"

    %% Styles
    classDef cli fill:#FFE082,stroke:#333,stroke-width:1px
    classDef core fill:#90CAF9,stroke:#333,stroke-width:1px
    classDef config fill:#A5D6A7,stroke:#333,stroke-width:1px
    classDef plugins fill:#A5D6A7,stroke:#333,stroke-width:1px
    classDef external fill:#EEEEEE,stroke:#333,stroke-width:1px
```
