yaml-lint-rs

A fast YAML linter written in Rust, inspired by yamllint.

Built with Claude Code and Cursor.

Why yaml-lint-rs?

• ⚡ 20-60x faster than Python yamllint (see benchmarks)
• 📦 Single binary - no runtime dependencies required
• 🔧 Drop-in replacement - compatible with yamllint config format
• 🦀 Memory safe - written in Rust

Features

• ✅ Fast and efficient YAML linting
• ✅ Multiple output formats (standard, colored, parsable)
• ✅ Configurable rules with preset configurations
• ✅ Support for .yamllint configuration files
• ✅ Directory traversal for batch linting
• ✅ Exit codes for CI/CD integration

Performance

yaml-lint-rs is significantly faster than Python yamllint:

Benchmarks run on Apple M1, macOS. Results may vary. See benchmarks/ for reproduction.

Installation

Homebrew (macOS/Linux)

brew tap hiromaily/tap
brew install yaml-lint

From Source

Requires Rust 1.85+ (install from rustup.rs):

# Clone or navigate to the project directory
cd yaml-lint-rs

# Build the project
cargo build --release

# The binary will be at ./target/release/yaml-lint

Install globally via Cargo

cargo install --path cli

Usage

Basic usage

# Lint a single file
yaml-lint file.yaml

# Lint multiple files
yaml-lint file1.yaml file2.yaml

# Lint all YAML files in a directory
yaml-lint src/

# Lint with specific config file
yaml-lint -c .yamllint file.yaml

Output formats

# Standard human-readable output (default)
yaml-lint file.yaml

# Colored output (coming soon)
yaml-lint -f colored file.yaml

# Machine-parsable output (coming soon)
yaml-lint -f parsable file.yaml

Presets

# Use default preset (strict)
yaml-lint -d default file.yaml

# Use relaxed preset
yaml-lint -d relaxed file.yaml

Options

# Treat warnings as errors
yaml-lint --strict file.yaml

# List files that would be linted
yaml-lint --list-files src/

Configuration

Create a .yamllint or .yamllint.yml file in your project root:

# Extend a preset
extends: default

# Configure individual rules
rules:
  trailing-spaces: error
  line-length:
    max: 120
  document-start: disable
  indentation:
    spaces: 2

# Ignore patterns
ignore: |
  /vendor/
  *.generated.yaml

Available Presets

default (strict)

• All rules enabled as errors
• Suitable for production code

relaxed

• Most rules as warnings
• More permissive for development

Implemented Rules

✅ Phase 1 (Current)

1. trailing-spaces - Detects whitespace at line endings
   • Level: Error
   • No configuration

🚧 Phase 1 (In Progress)

2. line-length - Enforces maximum line length

   • Level: Error
   • Options: max (default: 80)

3. document-start - Requires or forbids --- at document start

   • Level: Disable (by default)
   • Options: present (true/false)

4. colons - Validates spacing around colons in mappings

   • Level: Error
   • Options: max-spaces-before (0), max-spaces-after (1)

5. key-duplicates - Prevents duplicate keys in mappings

   • Level: Error
   • Critical for YAML correctness

6. indentation - Validates consistent indentation

   • Level: Error
   • Options: spaces (2/4/consistent), indent-sequences

📋 Future Rules

Additional 17 rules planned for full yamllint compatibility:

• truthy, hyphens, comments, new-line-at-end-of-file
• braces, brackets, commas, empty-lines, new-lines
• comments-indentation, document-end, empty-values
• float-values, octal-values, quoted-strings, key-ordering

Exit Codes

• 0: Success (no errors, or only warnings without --strict)
• 1: Errors detected
• 2: Warnings detected with --strict flag

Examples

Example 1: Trailing spaces

# Bad
key: value

# Good
key: value

Example 2: Line length

# Bad (> 80 characters)
key: this is a very long value that exceeds the maximum line length of eighty characters

# Good
key: shorter value
# or use multiline
key: |
  this is a very long value
  split across multiple lines

Roadmap

• Phase 1: Core infrastructure + 6 priority rules
• Phase 2: Additional output formats, directives, more rules
• Phase 3: Full yamllint parity (23 rules)
• Phase 4: Performance optimizations, parallel linting
• Phase 5: Editor integration (LSP?)

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT

Acknowledgments

Inspired by yamllint by Adrien Vergé.