How adrienverge/yamllint works
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”).