#!/usr/bin/env python3
# YAML Whisperer - Whitespace Validator
# Save as yaml_check.py and run: python3 yaml_check.py yourfile.yaml

import sys
import yaml

def check_yaml_whitespace(filepath):
    """
    Validates YAML file for common whitespace and indentation issues.
    Returns detailed error messages for troubleshooting.
    """
    
    try:
        with open(filepath, 'r') as f:
            content = f.read()
            
        # Check for tabs (YAML's mortal enemy)
        for i, line in enumerate(content.split('\n'), 1):
            if '\t' in line:
                print(f"🚨 Line {i}: Tab character found! YAML requires spaces, not tabs.")
                print(f"   Content: {repr(line)}\n")
        
        # Try to parse the YAML
        parsed = yaml.safe_load(content)
        
        if parsed is None:
            print("⚠️  File parsed successfully but appears to be empty.")
        else:
            print("✅ YAML file is valid and properly formatted!")
            print(f"   Parsed structure type: {type(parsed).__name__}")
            
    except yaml.YAMLError as e:
        print(f"❌ YAML Parsing Error:")
        print(f"   {str(e)}")
        
        # Provide helpful hints for common issues
        if "mapping values" in str(e):
            print("\n💡 Tip: Check for missing colons or incorrect indentation after colons.")
        elif "expected " in str(e):
            print("\n💡 Tip: This is usually an indentation issue. Check that lists and nested items align properly.")
        
    except FileNotFoundError:
        print(f"❌ File not found: {filepath}")
    except Exception as e:
        print(f"❌ Unexpected error: {str(e)}")

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python3 yaml_check.py ")
        sys.exit(1)
    
    check_yaml_whitespace(sys.argv[1])

The Problem: When Whitespace Becomes a Weapon of Mass Destruction

YAML stands for "YAML Ain't Markup Language," which should have been our first clue that something was deeply wrong. It's the configuration format that promised to be "human-friendly" and "intuitive," then proceeded to create more developer trauma than a merge conflict on Friday at 5 PM.

Here's the absurdity: we're using a format where indentation—the thing your IDE automatically messes up when you paste code—determines whether your entire Kubernetes cluster decides to take a nap or your CI/CD pipeline throws a tantrum. It's like building a skyscraper where the structural integrity depends entirely on whether the construction workers remembered to put exactly two spaces after their coffee break.

I've seen grown developers cry over YAML. I've watched teams spend entire sprints debugging what turned out to be a tab character that snuck in when someone copied code from Stack Overflow. The worst part? These errors are often silent. Your YAML parser just shrugs and says "sure, this looks fine" while secretly plotting your production outage. It's the digital equivalent of your car starting normally, driving to the grocery store, then suddenly deciding to park itself in the frozen food aisle.

The Solution: Introducing YAML Whisperer

After one too many 2 AM debugging sessions that turned out to be indentation issues, I decided enough was enough. I built YAML Whisperer to solve this exact problem. It's not another YAML linter—it's a YAML therapist that helps your files work through their whitespace trauma before they take it out on your production environment.

YAML Whisperer works by analyzing your YAML files for indentation inconsistencies before runtime. It doesn't just tell you "something's wrong"—it points directly at the offending lines, suggests specific fixes, and even generates a "YAML purity score" with feedback that ranges from encouraging to brutally honest.

The best part? It catches problems before they become problems. Instead of discovering your indentation error when your Kubernetes pod refuses to start at 3 AM, you catch it during development. It's like having a friend who tells you you have spinach in your teeth before you go on stage, rather than after your TED Talk.

How to Use It (Without Losing Your Mind)

Installation is simple because, unlike YAML itself, we believe in being actually human-friendly:

npm install -g yaml-whisperer
# or
pip install yaml-whisperer
# or use the Docker image if you really want to

Basic usage is even simpler:

# Check a single file
yaml-whisperer check my-manifest.yaml

# Check a whole directory
yaml-whisperer check ./k8s/

# Enable strict mode (tab detection with screaming)
yaml-whisperer check --strict deployment.yaml

Here's what you'll see when it finds something:

❌ YAML Purity Score: 42/100 - "Are you typing with mittens?"

Line 17: Inconsistent indentation (expected 4 spaces, found 3)
   Suggestion: Add one more space before 'image:'

Line 23: Tab character detected (HERESY!)
   Suggestion: Replace with 2 spaces and reconsider your life choices

Check out the full source code on GitHub to see how it works under the hood. The core detection logic is surprisingly simple—which makes you wonder why we've been suffering for so long.

Key Features That Actually Help

• Detects and highlights indentation inconsistencies before runtime: Catches mixed spaces, inconsistent levels, and other whitespace crimes before they ruin your deployment.
• Suggests specific fixes with line numbers: No more "something's wrong somewhere"—get exact line numbers and specific corrections.
• Generates a 'YAML purity score' with snarky feedback: From "Flawless! Did a robot write this?" to "This looks like it was formatted during an earthquake."
• Optional 'strict mode' that screams when tabs are detected: Because tabs in YAML should be treated with the same seriousness as pineapple on pizza debates.
• CI/CD integration: Add it to your pipeline to catch errors before they reach production.
• Multiple output formats: Human-readable, JSON for automation, or "panic mode" for when you need extra motivation.

Conclusion: Stop Debugging, Start Developing

YAML Whisperer won't fix all your problems (you still have to write the actual logic), but it will eliminate one of the most frustrating categories of bugs in modern development. It turns hours of debugging into seconds of validation. It replaces production outages with quick fixes during code review. It gives you back the time you'd spend staring at spaces and tabs wondering if you need glasses.

The tool is free, open source, and available right now. Try it out: https://github.com/BoopyCode/yaml-whisperer. Add it to your pre-commit hooks, your CI pipeline, or just run it when you're feeling paranoid. Your future self—the one not debugging at 2 AM—will thank you.

Remember: in the battle against YAML indentation errors, you're not fighting spaces and tabs. You're fighting wasted time, frustration, and unnecessary complexity. And with YAML Whisperer, you finally have a weapon that actually works. Now if only we could get it to make coffee too.