import os
import re
from typing import Dict, List, Tuple

def audit_env_file(env_path: str = '.env') -> Dict:
    """
    Forensic audit of your .env file.
    Returns shame levels, unused vars, and naming violations.
    """
    try:
        with open(env_path, 'r') as f:
            lines = f.readlines()
    except FileNotFoundError:
        return {"error": "No .env file found. (Too clean or too hidden?)"}
    
    # Analysis containers
    variables = {}
    unused_candidates = []
    secret_flags = []
    naming_violations = []
    
    # Pattern matching
    secret_keywords = ['KEY', 'SECRET', 'PASSWORD', 'TOKEN', 'PRIVATE', 'CREDENTIAL']
    shame_patterns = ['TEST_', 'OLD_', 'TEMP_', '_BACKUP', '_DEPRECATED']
    
    for line_num, line in enumerate(lines, 1):
        line = line.strip()
        
        # Skip comments and empties
        if not line or line.startswith('#'):
            continue
            
        # Parse KEY=VALUE
        if '=' in line:
            key, value = line.split('=', 1)
            key = key.strip()
            
            # Record variable
            variables[key] = {
                'line': line_num,
                'value_preview': value[:20] + ('...' if len(value) > 20 else '')
            }
            
            # Check for secrets
            if any(secret in key.upper() for secret in secret_keywords):
                shame = "HIGH" if len(value) > 5 else "MEDIUM"
                secret_flags.append({
                    'key': key,
                    'shame': shame,
                    'line': line_num
                })
            
            # Check for shame patterns
            if any(pattern in key.upper() for pattern in shame_patterns):
                naming_violations.append({
                    'key': key,
                    'pattern': next(p for p in shame_patterns if p in key.upper()),
                    'line': line_num
                })
    
    # Simple unused detection (looks for keys not in project files)
    # In reality, you'd scan your codebase - this is a placeholder
    project_files = ['app.py', 'config.py', 'main.js']  # Extend this list
    for key in variables:
        unused_candidates.append(key)  # Simplified for example
    
    return {
        'total_variables': len(variables),
        'secret_flags': secret_flags,
        'naming_violations': naming_violations,
        'unused_candidates': unused_candidates[:10],  # Top 10
        'shame_score': len(secret_flags) * 3 + len(naming_violations) * 2
    }

# Usage:
# results = audit_env_file()
# print(f"Shame Score: {results['shame_score']}")
# print(f"Secret Flags: {results['secret_flags']}")
# print(f"Cleanup Candidates: {results['unused_candidates']}")

The Digital Junk Drawer We All Pretend Is Fine

Let's be honest: your .env file is where configuration variables go to die. It starts innocently enough—a few database credentials, an API key or two. But then you add DEBUG_MODE=true for that one bug fix in 2019. Then you comment it out but never remove it. Then you add OLD_API_KEY "just in case" you need to roll back. Then you create DATABASE_URL_2 because you couldn't remember if the original was for staging or production. Before you know it, you've got 87 environment variables, and 53 of them are either unused, deprecated, or so cryptically named that they might as well be written in ancient Sumerian.

This isn't just messy—it's actively harmful. That TEST_STRIPE_KEY you forgot about? It's probably still valid. That ADMIN_PASSWORD variable from your intern's project three years ago? It's sitting there like a landmine waiting for the next developer to stumble upon it. And don't get me started on naming conventions. Is it DB_HOST or DATABASE_HOST or POSTGRES_HOSTNAME? Your codebase has all three, and they all point to different things depending on which file you're looking at. It's like playing configuration roulette every time you deploy.

The worst part? We all know this is happening. We see the bloated .env files. We notice the inconsistent naming. We wince when we find an API key that should have been rotated six months ago. But we're too busy putting out production fires to clean up the arsonist's toolkit. So the junk drawer gets fuller, the technical debt grows, and we all collectively agree to pretend this is normal developer behavior.

The Solution: A Confessional for Your Configuration Sins

I built .ENV Confession Booth to solve this exact problem. It's not just another linter or static analysis tool—it's an intervention for your configuration files. The tool scans your entire codebase, looks for references to environment variables, and compares them against what's actually defined in your .env files. Then it presents you with a "confession report" that highlights your sins with the gentle subtlety of a baseball bat to the face.

How does it work? At a high level, it parses your .env files to extract all defined variables. Then it scans your source code (supporting multiple languages) to find where those variables are actually referenced. Any variable defined but not referenced? That's unused. Any variable that looks like a secret (API keys, passwords, tokens) but is named something ridiculous like SUPER_SECRET_DONT_SHARE? That gets flagged with a shame level. The tool even suggests naming conventions based on common patterns it finds in your codebase, all while roasting your current chaos with delightful sarcasm.

But here's the important part: despite the humor, this tool is genuinely useful. It catches security risks before they become breaches. It eliminates debugging time wasted on configuration issues. It helps teams establish consistent naming conventions. And it does all of this with a personality that makes the medicine go down easier. Think of it as that brutally honest friend who tells you when you have spinach in your teeth—embarrassing in the moment, but ultimately helpful.

How to Use It: Your Path to Redemption

Getting started with .ENV Confession Booth is straightforward. First, install it via npm:

npm install -g env-confession-booth

Then navigate to your project directory and run:

env-confess analyze --path ./

The tool will scan your project and generate a confession report. Here's a snippet from the main analysis function that shows how it detects unused variables:

// From the main analyzer
function findUnusedVariables(envVars, codeReferences) {
  const unused = [];
  
  for (const envVar of envVars) {
    const isUsed = codeReferences.some(ref => 
      ref.variableName === envVar.name
    );
    
    if (!isUsed) {
      unused.push({
        name: envVar.name,
        line: envVar.line,
        shameLevel: calculateShame(envVar.value)
      });
    }
  }
  
  return unused;
}

Check out the full source code on GitHub to see all the features in detail. The tool is designed to be extensible—you can add custom rules for your organization's naming conventions, integrate it into your CI/CD pipeline, or even extend it to support additional file types.

Key Features That Actually Help

• Detects unused environment variables by scanning codebase references: Finds those forgotten variables that have been sitting in your .env file since the Obama administration.
• Flags potentially leaked secrets with cheeky shame levels: From "Mild Embarrassment" for questionable naming to "Full Blown Security Incident" for actual API keys in plain sight.
• Suggests naming conventions while roasting your current chaos: "I see you have DB_HOST, databaseUrl, and postgres_hostname. Pick one, you chaotic neutral developer."
• Generates a 'confession report' with absolution suggestions: Not just criticism—actual actionable steps to clean up your mess.

Conclusion: Clean Up Your Digital Closet

Your .env file doesn't have to be a digital junk drawer. With .ENV Confession Booth, you can finally clean up the configuration chaos that's been haunting your projects. The benefits are real: fewer debugging headaches, reduced security risks, and more consistent codebases. Plus, you get to enjoy the sarcastic commentary while you fix your mistakes.

Try it out today: https://github.com/BoopyCode/env-var-confession-booth-1767274677. Your future self—and your teammates—will thank you. And remember: the first step to recovery is admitting you have a problem. The second step is letting a sarcastic tool point out all your problems while suggesting solutions.

Now if you'll excuse me, I need to go check my own .env files. I'm pretty sure there's a variable in there from my first Node.js project that's just the word "password" followed by 1234. We've all been there.