yamllint

Yamllint Tool Analysis

Overview

Yamllint is a linter for YAML files that checks for syntax errors, formatting issues, and other YAML best practices. This analysis compares Lintro’s wrapper implementation with the core Yamllint tool.

Core Tool Capabilities

Yamllint provides comprehensive YAML analysis including:

  • Syntax validation: Detects YAML syntax errors and parsing issues
  • Style checking: Enforces consistent formatting and indentation
  • Document structure: Validates document structure and key ordering
  • Configuration options: --format, --config-file, --config-data, --strict
  • Output formats: parsable, standard, colored, github, auto
  • Rule customization: Extensive rule configuration via config files
  • Error codes: Specific codes for different violation types

Lintro Implementation Analysis

✅ Preserved Features

Core Functionality:

  • ✅ Syntax validation: Full preservation of YAML syntax checking
  • ✅ Style enforcement: Supports all Yamllint style rules
  • ✅ Configuration files: Respects .yamllint, setup.cfg, pyproject.toml
  • ✅ Error categorization: Preserves Yamllint’s error code system
  • ✅ File targeting: Supports YAML file patterns (*.yml, *.yaml)
  • ✅ Error detection: Captures syntax and style violations

Command Execution:

# From tool_yamllint.py
cmd = ["yamllint"] + self.files
result = subprocess.run(cmd, capture_output=True, text=True)

Configuration Options:

  • ✅ Output format: format parameter (parsable, standard, colored, github, auto)
  • ✅ Config file: config_file parameter for custom configuration
  • ✅ Inline config: config_data parameter for YAML configuration string
  • ✅ Strict mode: strict parameter for treating warnings as errors
  • ✅ Relaxed mode: relaxed parameter for relaxed configuration
  • ✅ No warnings: no_warnings parameter to show only errors

⚠️ Limited/Missing Features

Advanced Configuration:

  • ❌ Runtime rule customization: Cannot modify individual rules at runtime
  • ❌ Per-file configuration: No support for file-specific rule overrides
  • ❌ Custom rule definitions: No support for custom rule creation
  • ❌ Rule severity control: Limited control over rule severity levels

Output Customization:

  • ❌ Detailed error context: Limited access to detailed error explanations
  • ❌ Custom formatters: Cannot use custom output formatters
  • ❌ Progress reporting: No access to progress indicators for large files

Advanced Features:

  • ❌ Document validation: Limited schema validation capabilities
  • ❌ Key ordering: No runtime control over key ordering rules
  • ❌ Comment handling: Limited control over comment-related rules

Performance Options:

  • ❌ Parallel processing: No access to parallel file processing
  • ❌ Caching: No access to incremental checking features

🚀 Enhancements

Unified Interface:

  • ✅ Consistent API: Same interface as other linting tools (check(), set_options())
  • ✅ Structured output: Issues formatted as standardized Issue objects
  • ✅ Python integration: Native Python object handling vs CLI parsing
  • ✅ Pipeline integration: Seamless integration with other tools

Enhanced Error Processing:

  • ✅ Issue normalization: Converts Yamllint output to standard Issue format:

    Issue(
    file_path=match.group(1),
    line_number=int(match.group(2)),
    column_number=int(match.group(3)) if match.group(3) else None,
    error_code=match.group(4),
    message=match.group(5).strip(),
    severity="error"
)

Error Parsing:

  • ✅ Regex-based parsing: Robust parsing of Yamllint’s output format
  • ✅ Multi-line support: Handles complex error messages
  • ✅ Position tracking: Accurate line and column number extraction

File Management:

🔧 Proposed runtime pass-throughs

  • --tool-options yamllint:format=standard (switch output style)

  • --tool-options yamllint:config_file=.yamllint (explicit config path)

  • --tool-options yamllint:no_warnings=True (errors only)

  • ✅ Extension filtering: Automatic YAML file detection

  • ✅ Batch processing: Efficient handling of multiple files

  • ✅ Error aggregation: Collects all issues across files

Usage Comparison

Core Yamllint

# Basic checking
yamllint config.yml

# With custom format
yamllint --format parsable config.yml

# With custom config
yamllint --config-file .yamllint-custom config.yml

# Strict mode
yamllint --strict config.yml

# Multiple files
yamllint *.yml *.yaml

Lintro Wrapper

# Basic checking
yamllint_tool = YamllintTool()
yamllint_tool.set_files(["config.yml"])
issues = yamllint_tool.check()

# With options
yamllint_tool.set_options(
    format="parsable",
    strict=True,
    no_warnings=True
)

Configuration Strategy

Core Tool Configuration

Yamllint uses configuration files:

  • .yamllint
  • setup.cfg [yamllint] section
  • pyproject.toml [tool.yamllint] section

Lintro Approach

The wrapper supports both configuration files and runtime options:

  • Configuration files: Primary configuration method
  • Runtime options: Override specific settings via set_options()
  • Combined approach: Configuration files provide defaults, runtime options override

Error Code Mapping

Lintro preserves all Yamllint error codes:

CategoryCodesDescription
Syntax Errorssyntax-errorYAML syntax violations
Document Structuredocument-start, document-endDocument structure issues
IndentationindentationIndentation and spacing issues
Line Lengthline-lengthLine length violations
CommentscommentsComment formatting and placement
Key Orderingkey-orderingKey ordering in mappings
Trailing Spacestrailing-spacesTrailing whitespace issues
Truthy ValuestruthyBoolean value formatting

Recommendations

When to Use Core Yamllint

  • Need runtime configuration changes
  • Require specific output formats for tooling integration
  • Want detailed error explanations
  • Need custom rule definitions
  • Require schema validation capabilities

When to Use Lintro Wrapper

  • Part of multi-tool linting pipeline
  • Need consistent issue reporting across tools
  • Want Python object integration
  • Require aggregated results across multiple tools
  • Need standardized error handling

Limitations and Workarounds

Missing Runtime Configuration

Problem: Cannot modify individual rules at runtime Workaround: Use configuration files (.yamllint, setup.cfg, pyproject.toml)

Limited Schema Validation

Problem: No built-in schema validation Workaround: Use external tools like jsonschema for schema validation

No Auto-fixing

Problem: Yamllint cannot automatically fix issues Workaround: Use external formatters like Prettier for YAML formatting

Future Enhancement Opportunities

  1. Configuration Pass-through: Allow runtime rule customization via set_options()
  2. Schema Integration: Built-in schema validation capabilities
  3. Auto-fixing: Integration with YAML formatters for automatic fixes
  4. Advanced Filtering: Post-processing filters for issue selection
  5. Performance: Parallel processing for large YAML files
  6. Custom Rules: Plugin system for custom rule definitions