#!/usr/bin/env python3
"""
YAML Roulette - Whitespace Detective
Detects and visualizes problematic whitespace in YAML files
"""

import sys
import re

def analyze_yaml_whitespace(filepath):
    """
    Analyzes YAML file for problematic whitespace patterns
    Returns line numbers and character positions of suspicious whitespace
    """
    issues = []
    
    with open(filepath, 'r') as f:
        lines = f.readlines()
    
    for line_num, line in enumerate(lines, 1):
        # Check for mixed tabs and spaces (common YAML killer)
        if '\t' in line and ' ' in line:
            tab_pos = line.find('\t')
            issues.append({
                'line': line_num,
                'position': tab_pos,
                'type': 'mixed_tabs_spaces',
                'snippet': line.strip()
            })
        
        # Check for trailing spaces (can cause parsing issues)
        if line.rstrip('\n').endswith(' '):
            issues.append({
                'line': line_num,
                'position': len(line.rstrip('\n')) - 1,
                'type': 'trailing_space',
                'snippet': line.strip()
            })
        
        # Check for inconsistent indentation
        if line.strip() and not line.startswith(' ' * 2) and not line.startswith('\t'):
            indent_match = re.match(r'^(\s+)', line)
            if indent_match and len(indent_match.group(1)) % 2 != 0:
                issues.append({
                    'line': line_num,
                    'position': 0,
                    'type': 'odd_indentation',
                    'snippet': line.strip()
                })
    
    return issues

def visualize_issues(issues):
    """
    Creates a visual representation of whitespace issues
    """
    if not issues:
        print("✅ No whitespace issues found!")
        return
    
    print("\n🔍 YAML Whitespace Issues Found:")
    print("=" * 50)
    
    for issue in issues:
        print(f"\nLine {issue['line']}, Position {issue['position']}: {issue['type']}")
        print(f"Snippet: {issue['snippet']}")
        
        # Visual indicator
        indicator = ' ' * issue['position'] + '↑'
        print(f"         {indicator}")

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python yaml_roulette.py ")
        sys.exit(1)
    
    yaml_file = sys.argv[1]
    issues = analyze_yaml_whitespace(yaml_file)
    visualize_issues(issues)

The Problem: When Spaces Become Weapons of Mass Destruction

YAML stands for "YAML Ain't Markup Language," which should have been our first clue that we were dealing with something created by people who enjoy watching others suffer. The entire format is built on a foundation of assumptions: that developers have perfect eyesight, that they never accidentally hit the Tab key when they meant to hit Space, and that they enjoy playing "Find the Invisible Character" as a recreational activity.

The real problem isn't that YAML is sensitive to whitespace—many programming languages are. The problem is that YAML fails with all the helpfulness of a brick wall. You'll get errors like "mapping values are not allowed in this context" or "could not find expected ':'" without any indication of where the problem actually is. It's like your car's check engine light coming on with the additional message "Something's wrong with the car. Good luck figuring out what."

Consider this real-world scenario: Your Docker Compose file works locally. You push to production. It fails. You spend hours comparing files, running diff commands, asking colleagues to look at it. Finally, someone with younger eyes notices that on line 47, there's a tab character instead of two spaces. The entire deployment was held hostage by a character you can't even see without enabling special editor settings. This isn't programming—it's digital archaeology.

The Solution: Making the Invisible Visible (and Mocking It)

I built YAML Roulette because I got tired of explaining to my cat why I was yelling at my screen again. The tool serves two purposes: first, it actually helps you debug YAML files by showing you what's really there (spaces, tabs, invisible characters). Second, it demonstrates just how absurdly fragile YAML is through a feature I call "YAML Russian Roulette."

At its core, YAML Roulette is a visualization tool. It takes your YAML file and shows you exactly what the parser sees: which characters are spaces, which are tabs, where your indentation levels are, and where you've mixed them like a culinary novice combining ketchup with fine wine. It's like putting on those glasses from "They Live" but for code—suddenly you can see the hidden aliens (tabs) living among the humans (spaces).

But the educational part—the part that makes this more than just another linter—is the roulette feature. With one command, YAML Roulette will randomly replace one space in your file with a tab, or vice versa, then show you the catastrophic failure that results. It's like a fire drill for your configuration files: you get to experience the disaster in a controlled environment so you're prepared when it happens for real.

How to Use It: Because Reading Documentation is Harder Than Debugging YAML

Installation is straightforward because if it weren't, we'd be adding to the problem instead of solving it:

npm install -g yaml-roulette
# or
pip install yaml-roulette
# or just clone the repo because we're all adults here

Basic usage is even simpler:

# Visualize whitespace in your file
yaml-roulette inspect my-config.yaml

# Play a round of YAML Russian Roulette
yaml-roulette roulette my-config.yaml

# Fix common whitespace issues
yaml-roulette fix my-config.yaml

The inspect command is where the magic happens. Here's a snippet from the main visualization logic:

def visualize_whitespace(content):
    """Replace invisible characters with visible symbols"""
    # Spaces become middle dots
    content = content.replace(' ', '·')
    # Tabs become right arrows
    content = content.replace('\t', '→')
    # Show indentation guides
    lines = content.split('\n')
    for i, line in enumerate(lines):
        indent_level = len(line) - len(line.lstrip('·→'))
        lines[i] = f"{i+1:3}| {'|  ' * indent_level}{line}"
    return '\n'.join(lines)

Check out the full source code on GitHub to see how we handle edge cases, different YAML flavors, and the sheer existential horror of empty lines with trailing spaces.

Key Features: Because "It Works" Wasn't Specific Enough

• Detects and highlights invisible whitespace characters: Turns spaces into visible dots (·), tabs into arrows (→), and shows trailing whitespace that's lurking at the end of lines like a creepy ex.
• Shows indentation levels with visible guides: Adds vertical lines to show exactly which items are at which nesting level, because counting spaces is what we invented computers to avoid doing.
• Simulates 'YAML Russian Roulette': Randomly corrupts one whitespace character in your file to demonstrate how a single invisible change can cause catastrophic failure. Educational and terrifying—the best combination.
• Batch fixing capabilities: Can automatically convert tabs to spaces (or vice versa if you're a masochist) and normalize indentation across your entire codebase.
• Integration friendly: Works as a standalone tool, a pre-commit hook, or that thing you run at 2 AM when you finally realize why production is down.

Conclusion: Because Every Tragedy Needs a Moral

YAML Roulette won't fix YAML's fundamental design flaws—no tool can do that short of a time machine and a stern talking-to with the original creators. But it will save you hours of debugging, reduce your caffeine consumption, and possibly save your relationships with colleagues who are tired of you asking "does this look like two spaces to you?"

The real value isn't just in fixing files—it's in understanding why they break. By making the invisible visible, YAML Roulette turns a mystical art (YAML debugging) into a science. And by letting you play Russian Roulette with your configs, it teaches you to write more robust files in the first place.

Try it out: https://github.com/BoopyCode/yaml-roulette

Remember: in the game of YAML, you either win or you spend your weekend debugging. Choose wisely.