import os
import sys
from pathlib import Path
from collections import defaultdict

class EnvVarArchaeologist:
    """
    Scans all configuration sources to find environment variable conflicts
    """
    
    def __init__(self):
        self.sources = {
            '.env': 'Project root',
            '.env.local': 'Local overrides',
            '.env.production': 'Production config',
            '.env.development': 'Development config',
            'shell': 'Shell environment',
            'system': 'System environment'
        }
        self.findings = defaultdict(dict)
    
    def scan_all_sources(self):
        """Scan all potential configuration sources"""
        # Check file-based configs
        for env_file in ['.env', '.env.local', '.env.production', '.env.development']:
            if Path(env_file).exists():
                self._parse_env_file(env_file)
        
        # Check shell environment
        self._capture_shell_env()
        
        # Check system environment
        self._capture_system_env()
        
        return self._generate_report()
    
    def _parse_env_file(self, filename):
        """Parse a .env file and record variables"""
        with open(filename, 'r') as f:
            for line in f:
                line = line.strip()
                if line and not line.startswith('#'):
                    if '=' in line:
                        key, value = line.split('=', 1)
                        self.findings[key][filename] = value
    
    def _capture_shell_env(self):
        """Capture shell environment variables"""
        for key, value in os.environ.items():
            self.findings[key]['shell'] = value
    
    def _capture_system_env(self):
        """Capture system environment variables"""
        # This would be platform-specific implementation
        # Simplified for example
        pass
    
    def _generate_report(self):
        """Generate conflict report"""
        report = []
        report.append("=== ENVIRONMENT VARIABLE CONFLICT REPORT ===\n")
        
        for var_name, sources in self.findings.items():
            if len(sources) > 1:
                report.append(f"CONFLICT: {var_name}")
                for source, value in sources.items():
                    report.append(f"  • {source}: {value}")
                report.append("")
        
        return '\n'.join(report)

# Usage example:
if __name__ == "__main__":
    archaeologist = EnvVarArchaeologist()
    report = archaeologist.scan_all_sources()
    print(report)

The Problem: Your Configuration Files Are Having an Identity Crisis

Modern development has become a tragic comedy of configuration sprawl. We started with a simple .env file—one humble text document holding our secrets. Then came .env.local for "just my machine." Then .env.production for when things get serious. Then .env.development for when we're feeling creative. Then shell configs because why not? Then CI/CD variables because the cloud demands tribute. Before you know it, you've got more configuration files than actual code, and your app is having a full-blown existential crisis about who it is and where it lives.

This isn't just annoying—it's a productivity black hole. You know the drill: your app works perfectly locally, but the moment it hits staging, DATABASE_URL suddenly thinks it's 1995 and wants to connect to 'localhost.' Or your API_KEY mysteriously transforms into 'undefined' right when you need it most. You spend hours—sometimes days—playing digital detective, checking file after file, only to discover that .env.production.local was overriding .env.production which was overriding .env which was being ignored by Docker anyway. It's like trying to solve a murder mystery where every suspect is a text file and the murder weapon is a missing semicolon.

The Solution: Stop Digging, Start Solving

I built EnvVar Archaeologist because I got tired of playing configuration whack-a-mole. This tool doesn't just find your environment variables—it understands the entire ecosystem. It knows that .env.local thinks it's special, that shell exports have commitment issues, and that CI/CD variables are the overbearing parents of the configuration world.

Here's how it works: instead of manually checking fifteen different files and hoping you remember the inheritance hierarchy (spoiler: you won't), EnvVar Archaeologist systematically scans every possible source of truth. It reads your .env files, checks your shell environment, examines your CI/CD configuration, and even peeks at your Docker files. Then it presents everything in a clear, visual format that actually makes sense.

The best part? It's not just showing you what's there—it's showing you what's wrong. It highlights conflicts where the same variable has different values in different places. It shows you the inheritance chain so you can see exactly which file is winning the override battle. And my personal favorite feature: it finds "zombie variables"—those environment variables you defined months ago and forgot about, but they're still lurking in your configs, waiting to rise from the dead and haunt your deployment.

How to Use It: From Chaos to Clarity in Minutes

Getting started with EnvVar Archaeologist is easier than explaining to your manager why staging is broken (again). First, install it:

npm install -g env-var-archaeologist
# or
pip install env-var-archaeologist
# or use the Docker image if you really want to

Then run it in your project directory:

eva scan --project ./my-app

Here's a snippet from the core scanning logic that shows how it systematically examines each configuration layer:

def scan_configuration_layers(project_path):
    """Examine every possible source of environment variables"""
    layers = []
    
    # Check standard .env files
    layers.append(scan_dotenv_files(project_path))
    
    # Check shell environment
    layers.append(scan_shell_environment())
    
    # Check CI/CD configuration if present
    if has_ci_config(project_path):
        layers.append(scan_ci_environment(project_path))
    
    # Check Docker and compose files
    layers.append(scan_container_configs(project_path))
    
    return analyze_layer_conflicts(layers)

Check out the full source code on GitHub to see all the clever ways it untangles your configuration mess.

Key Features That Will Save Your Sanity

• Multi-Source Scanning: Examines .env files, shell configs, CI/CD settings, Docker files—everything that could possibly contain environment variables. No more "I forgot to check that one" moments.
• Conflict Visualization: Shows you exactly where variables conflict and which value "wins" in the override hierarchy. Finally understand why DATABASE_URL is 'localhost' in production.
• Inheritance Chain Mapping: Creates a clear visual of which files override what. See the entire family tree of your configuration, complete with all the drama and power struggles.
• Zombie Variable Detection: Finds environment variables that are defined but never actually used by your application. Clean up your configs and eliminate the undead.
• Confession Report: Generates a detailed report showing exactly which file is "guilty" of breaking your app. It's like a detective presenting evidence at the end of a crime show.

Conclusion: Stop Being a Configuration Archaeologist

EnvVar Archaeologist turns what used to be hours of frustrating debugging into minutes of clear insight. Instead of digging through layers of configuration files with a metaphorical trowel and brush, you get a complete excavation report that tells you exactly what's buried where and why it matters.

The tool is free, open source, and available right now. Try it out: https://github.com/BoopyCode/env-variable-archaeologist-1767260279. Your future self—the one who isn't spending Friday night debugging why staging thinks it's development—will thank you.

Remember: in the grand archaeological dig of modern development, you shouldn't need a PhD in Configuration Hierarchies to find out why your app is broken. Sometimes, you just need the right tool to do the digging for you. Now if only someone would build a tool to explain why the CEO's nephew's "simple change" broke everything...