envsleuth 0.1.0__py3-none-any.whl

envsleuth/__init__.py

@@ -0,0 +1,3 @@
+"""envsleuth — static analyzer for environment variables in Python projects."""
+
+__version__ = "0.1.0"

envsleuth/checker.py

@@ -0,0 +1,160 @@
+"""Compare scanned env vars against an actual .env file."""
+
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from dotenv import dotenv_values
+
+from envsleuth.scanner import EnvUsage, ScanResult
+
+
+DEFAULT_ENV_FILE = ".env"
+DEFAULT_ENVIGNORE_FILE = ".envignore"
+
+
+@dataclass
+class VarReport:
+    """Per-variable status after comparing scan results with .env."""
+
+    name: str
+    present_in_env: bool
+    has_default_in_code: bool
+    usages: List[EnvUsage] = field(default_factory=list)
+    ignored: bool = False
+
+    @property
+    def status(self) -> str:
+        """One of: 'present', 'missing', 'default', 'ignored'."""
+        if self.ignored:
+            return "ignored"
+        if self.present_in_env:
+            return "present"
+        if self.has_default_in_code:
+            return "default"
+        return "missing"
+
+
+@dataclass
+class CheckReport:
+    """Full comparison report."""
+
+    variables: List[VarReport] = field(default_factory=list)
+    dynamic_usages: List[EnvUsage] = field(default_factory=list)
+    env_file: Optional[Path] = None
+    env_file_exists: bool = False
+    extra_in_env: List[str] = field(default_factory=list)
+    ignore_patterns: List[str] = field(default_factory=list)
+    errors: List[Tuple[Path, str]] = field(default_factory=list)
+
+    @property
+    def missing(self) -> List[VarReport]:
+        return [v for v in self.variables if v.status == "missing"]
+
+    @property
+    def present(self) -> List[VarReport]:
+        return [v for v in self.variables if v.status == "present"]
+
+    @property
+    def with_default(self) -> List[VarReport]:
+        return [v for v in self.variables if v.status == "default"]
+
+    @property
+    def ignored(self) -> List[VarReport]:
+        return [v for v in self.variables if v.status == "ignored"]
+
+    @property
+    def has_issues(self) -> bool:
+        """True if anything requires user attention (missing vars or scan errors)."""
+        return bool(self.missing) or bool(self.errors)
+
+
+# --------------------------------------------------------------------- helpers
+
+
+def load_env_file(path: Path) -> Dict[str, Optional[str]]:
+    if not path.exists():
+        return {}
+    return dict(dotenv_values(path))
+
+
+def load_ignore_patterns(path: Path) -> List[str]:
+    """Read .envignore — one glob pattern per line. Blank lines and '#' are ignored."""
+    if not path.exists():
+        return []
+    patterns: List[str] = []
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        patterns.append(line)
+    return patterns
+
+
+def _matches_any(name: str, patterns: List[str]) -> bool:
+    return any(fnmatch.fnmatchcase(name, p) for p in patterns)
+
+
+# -------------------------------------------------------------------- main api
+
+
+def check(
+    scan: ScanResult,
+    env_path: Path,
+    ignore_patterns: Optional[List[str]] = None,
+) -> CheckReport:
+    """Compare scan results against the given .env file and return a report."""
+    patterns = ignore_patterns or []
+    env_values = load_env_file(env_path)
+    env_keys = set(env_values.keys())
+
+    by_name: Dict[str, List[EnvUsage]] = {}
+    for u in scan.usages:
+        if u.name is None:
+            continue
+        by_name.setdefault(u.name, []).append(u)
+
+    variables: List[VarReport] = []
+    for name in sorted(by_name):
+        usages = by_name[name]
+        has_default = any(u.has_default for u in usages)
+        ignored = _matches_any(name, patterns)
+        variables.append(
+            VarReport(
+                name=name,
+                present_in_env=name in env_keys,
+                has_default_in_code=has_default,
+                usages=usages,
+                ignored=ignored,
+            )
+        )
+
+    code_names = set(by_name.keys())
+    extra_in_env = sorted(env_keys - code_names)
+
+    return CheckReport(
+        variables=variables,
+        dynamic_usages=scan.dynamic_usages,
+        env_file=env_path,
+        env_file_exists=env_path.exists(),
+        extra_in_env=extra_in_env,
+        ignore_patterns=patterns,
+        errors=list(scan.errors),
+    )
+
+
+def find_nearby_env_files(root: Path) -> List[Path]:
+    """Look for .env.* files in `root` to help the user when .env is missing."""
+    if not root.is_dir():
+        return []
+    candidates: List[Path] = []
+    for p in sorted(root.iterdir()):
+        if not p.is_file():
+            continue
+        name = p.name
+        if name == ".env" or name.startswith(".env."):
+            candidates.append(p)
+    return candidates

envsleuth/cli.py

@@ -0,0 +1,218 @@
+"""CLI entry point for envsleuth."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional, Set
+
+import click
+
+from envsleuth import __version__
+from envsleuth.checker import (
+    DEFAULT_ENV_FILE,
+    DEFAULT_ENVIGNORE_FILE,
+    check,
+    find_nearby_env_files,
+    load_ignore_patterns,
+)
+from envsleuth.display import (
+    render_env_not_found_error,
+    render_report,
+    render_report_json,
+    should_use_color,
+)
+from envsleuth.generator import write_env_example
+from envsleuth.scanner import scan_project
+
+
+# show flashbar only if the project is big enough that a blink of progress is useful
+PROGRESS_THRESHOLD = 20
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="envsleuth")
+def cli() -> None:
+    """envsleuth — find env vars in your code and check them against .env."""
+    pass
+
+
+# --------------------------------------------------------------------- scan
+
+@cli.command()
+@click.option(
+    "--path", "-p",
+    type=click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path),
+    default=".",
+    help="Directory (or file) to scan. Defaults to current directory.",
+)
+@click.option(
+    "--env", "env_file",
+    type=click.Path(path_type=Path),
+    default=None,
+    help=f"Path to the .env file. Defaults to ./{DEFAULT_ENV_FILE}",
+)
+@click.option(
+    "--envignore",
+    type=click.Path(path_type=Path),
+    default=None,
+    help=f"Path to .envignore. Defaults to ./{DEFAULT_ENVIGNORE_FILE} if present.",
+)
+@click.option(
+    "--strict", is_flag=True,
+    help="Exit with code 1 if any vars are missing (for CI).",
+)
+@click.option(
+    "--json", "as_json", is_flag=True,
+    help="Emit machine-readable JSON instead of the human report.",
+)
+@click.option(
+    "--no-color", is_flag=True,
+    help="Disable ANSI colors. Also set NO_COLOR=1 in your env.",
+)
+@click.option(
+    "--exclude", multiple=True,
+    help="Extra directory name to skip. Can be repeated.",
+)
+@click.option(
+    "--ext", multiple=True,
+    help="Extra file extension to scan (e.g. .pyi). Can be repeated.",
+)
+@click.option(
+    "--verbose", "-v", is_flag=True,
+    help="Show usage locations for every variable, not just missing ones.",
+)
+def scan(
+    path: Path,
+    env_file: Optional[Path],
+    envignore: Optional[Path],
+    strict: bool,
+    as_json: bool,
+    no_color: bool,
+    exclude: tuple,
+    ext: tuple,
+    verbose: bool,
+) -> None:
+    """Scan a project for env var usages and check against .env."""
+
+    # resolve paths up front so error messages look sensible
+    root = path.resolve()
+    if env_file is None:
+        env_file = Path.cwd() / DEFAULT_ENV_FILE
+    env_file = env_file.resolve() if env_file.exists() else env_file
+
+    if envignore is None:
+        candidate = Path.cwd() / DEFAULT_ENVIGNORE_FILE
+        envignore = candidate if candidate.exists() else None
+
+    use_color = should_use_color(force=False if no_color else None)
+    # --json means no color regardless
+    if as_json:
+        use_color = False
+
+    # env file missing — bail out with a helpful message (unless JSON mode where
+    # we still want to emit a report for CI to consume)
+    if not env_file.exists() and not as_json:
+        # look for .env* files in the same directory the user pointed at
+        search_root = env_file.parent if env_file.parent.exists() else Path.cwd()
+        nearby = find_nearby_env_files(search_root)
+        click.echo(render_env_not_found_error(env_file, nearby, use_color=use_color), err=True)
+        sys.exit(2)
+
+    # build the sets for scan_project
+    exts: Optional[Set[str]] = None
+    if ext:
+        # include default .py plus the user-supplied ones, normalise the dot
+        exts = {".py"} | {e if e.startswith(".") else f".{e}" for e in ext}
+    extra_excl: Optional[Set[str]] = set(exclude) if exclude else None
+
+    # flashbar progress, but only if the project is big enough to justify it
+    files_preview = _count_files(root, exts, extra_excl)
+    use_progress = (not as_json) and files_preview >= PROGRESS_THRESHOLD and sys.stdout.isatty()
+
+    if use_progress:
+        from flashbar import Bar  # imported lazily so --json path stays lean
+        bar = Bar(files_preview, label="Scanning", show_eta=True, show_speed=True)
+        def _tick(_f: Path) -> None:
+            bar.update()
+        result = scan_project(root, extensions=exts, extra_excludes=extra_excl, on_file=_tick)
+    else:
+        result = scan_project(root, extensions=exts, extra_excludes=extra_excl)
+
+    # .envignore patterns
+    patterns = load_ignore_patterns(envignore) if envignore else []
+
+    report = check(result, env_file, ignore_patterns=patterns)
+
+    if as_json:
+        click.echo(render_report_json(report))
+    else:
+        click.echo(render_report(report, use_color=use_color, verbose=verbose))
+
+    if strict and report.has_issues:
+        sys.exit(1)
+
+
+def _count_files(root: Path, exts, excludes) -> int:
+    """Pre-count files so flashbar has a real total. Cheap compared to parsing."""
+    # TODO: scan_project already walks twice effectively — merge these eventually
+    from envsleuth.scanner import iter_python_files
+    return len(iter_python_files(root, extensions=exts, extra_excludes=excludes))
+
+
+# ------------------------------------------------------------------- generate
+
+@cli.command()
+@click.option(
+    "--path", "-p",
+    type=click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path),
+    default=".",
+)
+@click.option(
+    "--output", "-o",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Where to write the example file. Defaults to ./.env.example",
+)
+@click.option("--force", "-f", is_flag=True, help="Overwrite if output file exists.")
+@click.option("--no-color", is_flag=True)
+@click.option("--exclude", multiple=True)
+@click.option("--ext", multiple=True)
+def generate(
+    path: Path,
+    output: Optional[Path],
+    force: bool,
+    no_color: bool,
+    exclude: tuple,
+    ext: tuple,
+) -> None:
+    """Generate a .env.example file from scanned code."""
+
+    root = path.resolve()
+    if output is None:
+        output = Path.cwd() / ".env.example"
+
+    use_color = should_use_color(force=False if no_color else None)
+
+    exts: Optional[Set[str]] = None
+    if ext:
+        exts = {".py"} | {e if e.startswith(".") else f".{e}" for e in ext}
+    extra_excl: Optional[Set[str]] = set(exclude) if exclude else None
+
+    result = scan_project(root, extensions=exts, extra_excludes=extra_excl)
+
+    try:
+        write_env_example(result, output, force=force)
+    except FileExistsError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(2)
+
+    n = len(result.static_names)
+    msg = f"Wrote {n} variable{'s' if n != 1 else ''} to {output}"
+    if use_color:
+        msg = f"\033[32m✓\033[0m {msg}"
+    click.echo(msg)
+
+
+if __name__ == "__main__":
+    cli()

envsleuth/display.py

@@ -0,0 +1,269 @@
+"""Terminal output with ANSI colors. No rich dep — just escape codes."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import List, Optional, TextIO
+
+from envsleuth.checker import CheckReport
+
+
+# ANSI escape codes. Keeping these as plain constants — no fancy Color class,
+# it's 5 colors, not a design system.
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+RED = "\033[31m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+BLUE = "\033[34m"
+CYAN = "\033[36m"
+GRAY = "\033[90m"
+
+# unused for now but might use for --verbose later
+MAX_USAGES_SHOWN = 5
+
+
+def should_use_color(stream: Optional[TextIO] = None, force: Optional[bool] = None) -> bool:
+    """Decide whether to emit ANSI codes.
+
+    force=True/False overrides detection. NO_COLOR env var disables colors.
+    See https://no-color.org
+    """
+    if force is not None:
+        return force
+    if os.environ.get("NO_COLOR"):
+        return False
+    s = stream or sys.stdout
+    # not all streams have isatty (e.g. some test runners)
+    try:
+        return s.isatty()
+    except Exception:
+        return False
+
+
+class Styler:
+    """Wraps a bool — either returns text with ANSI codes or untouched."""
+
+    def __init__(self, enabled: bool):
+        self.enabled = enabled
+
+    def _wrap(self, code: str, text: str) -> str:
+        if not self.enabled:
+            return text
+        return f"{code}{text}{RESET}"
+
+    def red(self, t: str) -> str:    return self._wrap(RED, t)
+    def green(self, t: str) -> str:  return self._wrap(GREEN, t)
+    def yellow(self, t: str) -> str: return self._wrap(YELLOW, t)
+    def blue(self, t: str) -> str:   return self._wrap(BLUE, t)
+    def cyan(self, t: str) -> str:   return self._wrap(CYAN, t)
+    def gray(self, t: str) -> str:   return self._wrap(GRAY, t)
+    def bold(self, t: str) -> str:   return self._wrap(BOLD, t)
+    def dim(self, t: str) -> str:    return self._wrap(DIM, t)
+
+
+# ---------------------------------------------------------------- text output
+
+
+def render_report(report: CheckReport, use_color: bool = True, verbose: bool = False) -> str:
+    """Build a human-readable report as a single string."""
+    s = Styler(use_color)
+    lines: List[str] = []
+
+    # header
+    total = len(report.variables)
+    lines.append(s.bold(f"Found {total} variable{'s' if total != 1 else ''} in code"))
+    if report.env_file is not None:
+        env_label = f"checking against {report.env_file}"
+        if not report.env_file_exists:
+            env_label += s.red("  (not found)")
+        lines.append(s.dim(env_label))
+    lines.append("")
+
+    # per-var list
+    for var in report.variables:
+        if var.status == "present":
+            icon = s.green("✅")
+            line = f"{icon} {var.name}"
+            if verbose and var.usages:
+                line += s.dim(f"  ({len(var.usages)} usage{'s' if len(var.usages) != 1 else ''})")
+        elif var.status == "missing":
+            icon = s.red("❌")
+            line = f"{icon} {s.bold(var.name)} {s.dim('— missing from')} {report.env_file}"
+        elif var.status == "default":
+            icon = s.yellow("⚠️ ")
+            line = (
+                f"{icon} {var.name} "
+                f"{s.dim('— not in .env but has default in code (probably ok)')}"
+            )
+        elif var.status == "ignored":
+            icon = s.gray("·")
+            line = s.gray(f"{icon} {var.name}  (ignored by .envignore)")
+        else:
+            # shouldn't happen but don't crash
+            line = f"? {var.name}"
+
+        lines.append(line)
+
+        # show where it's used when verbose, or always for missing (helpful context)
+        if verbose or var.status == "missing":
+            for u in var.usages[:MAX_USAGES_SHOWN]:
+                try:
+                    rel = u.file.relative_to(Path.cwd())
+                except ValueError:
+                    rel = u.file
+                lines.append(s.dim(f"     at {rel}:{u.line}"))
+            if len(var.usages) > MAX_USAGES_SHOWN:
+                extra = len(var.usages) - MAX_USAGES_SHOWN
+                lines.append(s.dim(f"     ... and {extra} more"))
+
+    # dynamic warnings
+    if report.dynamic_usages:
+        lines.append("")
+        lines.append(s.yellow(
+            f"⚠️  {len(report.dynamic_usages)} dynamic usage"
+            f"{'s' if len(report.dynamic_usages) != 1 else ''} "
+            f"(variable name computed at runtime, can't check statically)"
+        ))
+        for u in report.dynamic_usages:
+            try:
+                rel = u.file.relative_to(Path.cwd())
+            except ValueError:
+                rel = u.file
+            expr = u.raw_expr or "?"
+            lines.append(s.dim(f"     {rel}:{u.line}  →  {u.call_type}({expr})"))
+
+    # extras in .env (not fatal, just informational)
+    if report.extra_in_env:
+        lines.append("")
+        lines.append(s.dim(
+            f"ℹ  {len(report.extra_in_env)} variable"
+            f"{'s' if len(report.extra_in_env) != 1 else ''} "
+            f"in .env not referenced in code: {', '.join(report.extra_in_env)}"
+        ))
+
+    # scan errors — these are real problems, surface them at the end
+    if report.errors:
+        lines.append("")
+        lines.append(s.red(f"Scan errors ({len(report.errors)}):"))
+        for path, msg in report.errors:
+            try:
+                rel = path.relative_to(Path.cwd())
+            except ValueError:
+                rel = path
+            lines.append(s.red(f"  {rel}: {msg}"))
+
+    # summary footer
+    lines.append("")
+    summary = _render_summary(report, s)
+    lines.append(summary)
+
+    return "\n".join(lines)
+
+
+def _render_summary(report: CheckReport, s: Styler) -> str:
+    n_missing = len(report.missing)
+    n_present = len(report.present)
+    n_default = len(report.with_default)
+    n_ignored = len(report.ignored)
+
+    parts = []
+    if n_present:
+        parts.append(s.green(f"{n_present} ok"))
+    if n_default:
+        parts.append(s.yellow(f"{n_default} with default"))
+    if n_missing:
+        parts.append(s.red(f"{n_missing} missing"))
+    if n_ignored:
+        parts.append(s.gray(f"{n_ignored} ignored"))
+
+    if not parts:
+        return s.dim("No env vars found in code.")
+    return "  ".join(parts)
+
+
+# -------------------------------------------------------------------- errors
+
+
+def render_env_not_found_error(
+    env_path: Path,
+    nearby: List[Path],
+    use_color: bool = True,
+) -> str:
+    """Nice error message when the user's .env file doesn't exist."""
+    s = Styler(use_color)
+    lines = [
+        s.red(s.bold(f"Error: {env_path} not found.")),
+        "",
+    ]
+
+    # filter out the one we were looking for
+    others = [p for p in nearby if p != env_path]
+
+    if others:
+        lines.append("Found other env-like files in this directory:")
+        for p in others:
+            lines.append(s.cyan(f"  {p.name}"))
+        lines.append("")
+        lines.append(
+            f"Try:  envsleuth scan --env {others[0].name}"
+        )
+    else:
+        lines.append(s.dim("No .env files found in this directory."))
+        lines.append("")
+        lines.append("If your .env lives elsewhere, use:")
+        lines.append(f"  {s.cyan('envsleuth scan --env path/to/.env')}")
+
+    return "\n".join(lines)
+
+
+# ------------------------------------------------------------------- json out
+
+
+def render_report_json(report: CheckReport) -> str:
+    """Machine-readable output for CI pipelines."""
+    def _usage(u) -> dict:
+        return {
+            "file": str(u.file),
+            "line": u.line,
+            "call_type": u.call_type,
+            "has_default": u.has_default,
+        }
+
+    data = {
+        "env_file": str(report.env_file) if report.env_file else None,
+        "env_file_exists": report.env_file_exists,
+        "summary": {
+            "total": len(report.variables),
+            "present": len(report.present),
+            "missing": len(report.missing),
+            "with_default": len(report.with_default),
+            "ignored": len(report.ignored),
+            "dynamic": len(report.dynamic_usages),
+            "errors": len(report.errors),
+        },
+        "variables": [
+            {
+                "name": v.name,
+                "status": v.status,
+                "usages": [_usage(u) for u in v.usages],
+            }
+            for v in report.variables
+        ],
+        "dynamic_usages": [
+            {
+                "file": str(u.file),
+                "line": u.line,
+                "expression": u.raw_expr,
+                "call_type": u.call_type,
+            }
+            for u in report.dynamic_usages
+        ],
+        "extra_in_env": report.extra_in_env,
+        "errors": [{"file": str(p), "error": m} for p, m in report.errors],
+    }
+    return json.dumps(data, indent=2)

envsleuth/generator.py

@@ -0,0 +1,100 @@
+"""Generate .env.example from scan results.
+
+Takes a ScanResult and writes a template file with:
+  - one line per variable
+  - comment pointing to where it's used in code
+  - the default value from code (if any) as the placeholder
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import List, Optional
+
+from envsleuth.scanner import EnvUsage, ScanResult
+
+
+HEADER = """\
+# Generated by envsleuth — edit this file before committing.
+# Each variable below is used somewhere in your code.
+# Replace the empty values with real defaults/examples, but don't commit secrets.
+"""
+
+
+def _first_literal_default(usages: List[EnvUsage]) -> Optional[str]:
+    """Try to recover a literal default value from one of the usage sites.
+
+    We already know which usages have has_default=True; this re-parses the line
+    to pull out the second arg's constant value. It's a bit of a hack but works
+    well enough for the common case.
+    """
+    # TODO: properly thread the default node through from scanner instead of
+    # re-reading the file here. Works for now.
+    for u in usages:
+        if not u.has_default:
+            continue
+        try:
+            source = u.file.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            continue
+
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            if node.lineno != u.line:
+                continue
+            # getenv(name, default) or environ.get(name, default)
+            if len(node.args) >= 2:
+                default = node.args[1]
+                if isinstance(default, ast.Constant):
+                    if default.value is None:
+                        return ""
+                    return str(default.value)
+    return None
+
+
+def build_env_example(scan: ScanResult) -> str:
+    """Produce the text content for a .env.example file."""
+    lines: List[str] = [HEADER]
+
+    # group usages by name
+    grouped: dict = {}
+    for u in scan.usages:
+        if u.name is None:
+            continue
+        grouped.setdefault(u.name, []).append(u)
+
+    if not grouped:
+        lines.append("# No environment variables found in code.")
+        return "\n".join(lines) + "\n"
+
+    for name in sorted(grouped):
+        usages = grouped[name]
+
+        # show up to 3 locations
+        locations = [f"{u.file}:{u.line}" for u in usages[:3]]
+        if len(usages) > 3:
+            locations.append(f"...and {len(usages) - 3} more")
+        lines.append(f"# used at {', '.join(locations)}")
+
+        default = _first_literal_default(usages)
+        if default is not None and default != "":
+            lines.append(f"{name}={default}")
+        else:
+            lines.append(f"{name}=")
+        lines.append("")  # blank between groups, easier to scan
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def write_env_example(scan: ScanResult, path: Path, force: bool = False) -> None:
+    """Write a .env.example to `path`. Raises FileExistsError if it exists and !force."""
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} already exists (use --force to overwrite)")
+    content = build_env_example(scan)
+    path.write_text(content, encoding="utf-8")

envsleuth/scanner.py

@@ -0,0 +1,316 @@
+"""AST-based scanner for environment variable usages in Python code.
+
+Detects three patterns:
+    os.getenv("VAR")              -> static usage
+    os.getenv("VAR", "default")   -> static usage with default
+    os.environ["VAR"]             -> static usage
+    os.environ.get("VAR")         -> static usage
+    os.environ.get("VAR", "def")  -> static usage with default
+    os.getenv(var_name)           -> dynamic usage (can't resolve)
+    os.getenv(f"PREFIX_{x}")      -> dynamic usage (can't resolve)
+
+The scanner also tracks aliased imports:
+    from os import getenv; getenv("X")            -> detected
+    from os import environ; environ["X"]          -> detected
+    import os as operating_system                  -> detected
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, List, Optional, Set, Tuple
+
+
+@dataclass
+class EnvUsage:
+    """A single occurrence of an env var lookup in source code."""
+
+    name: Optional[str]
+    """Variable name if it could be resolved statically, else None."""
+
+    file: Path
+    """File where the usage was found."""
+
+    line: int
+    """1-based line number."""
+
+    has_default: bool = False
+    """True if a default value was provided (e.g. os.getenv('X', 'fallback'))."""
+
+    call_type: str = "getenv"
+    """One of: 'getenv', 'environ_subscript', 'environ_get'."""
+
+    raw_expr: Optional[str] = None
+    """For dynamic usages: text of the unresolved expression (for diagnostics)."""
+
+    @property
+    def is_dynamic(self) -> bool:
+        return self.name is None
+
+
+@dataclass
+class ScanResult:
+    """Aggregated result of scanning one or more files."""
+
+    usages: List[EnvUsage] = field(default_factory=list)
+    scanned_files: List[Path] = field(default_factory=list)
+    errors: List[Tuple[Path, str]] = field(default_factory=list)
+
+    @property
+    def static_names(self) -> Set[str]:
+        """Unique set of statically-resolved variable names."""
+        return {u.name for u in self.usages if u.name is not None}
+
+    @property
+    def dynamic_usages(self) -> List[EnvUsage]:
+        return [u for u in self.usages if u.is_dynamic]
+
+    @property
+    def names_with_defaults(self) -> Set[str]:
+        """Names that have at least one usage with a default value provided."""
+        return {u.name for u in self.usages if u.name is not None and u.has_default}
+
+
+class ScanError(Exception):
+    """Raised when a single file cannot be scanned."""
+
+
+class _EnvVisitor(ast.NodeVisitor):
+    """AST visitor that collects env var usages from a single module."""
+
+    def __init__(self, file_path: Path) -> None:
+        self.file_path = file_path
+        self.usages: List[EnvUsage] = []
+
+        # Track import aliases. We need to recognize calls whether the user wrote
+        # `os.getenv(...)`, `import os as foo; foo.getenv(...)`, or
+        # `from os import getenv; getenv(...)`.
+        self._os_aliases: Set[str] = set()
+        self._getenv_aliases: Set[str] = set()
+        self._environ_aliases: Set[str] = set()
+
+    # ------------------------------------------------------------------ imports
+
+    def visit_Import(self, node: ast.Import) -> None:
+        for alias in node.names:
+            if alias.name == "os":
+                self._os_aliases.add(alias.asname or "os")
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        if node.module == "os":
+            for alias in node.names:
+                bound = alias.asname or alias.name
+                if alias.name == "getenv":
+                    self._getenv_aliases.add(bound)
+                elif alias.name == "environ":
+                    self._environ_aliases.add(bound)
+        self.generic_visit(node)
+
+    # ------------------------------------------------------------------- calls
+
+    def visit_Call(self, node: ast.Call) -> None:
+        # order matters here — environ.get is also a Call so we check getenv first
+        if self._is_getenv_call(node):
+            self._record_call(node, call_type="getenv")
+        elif self._is_environ_get_call(node):
+            self._record_call(node, call_type="environ_get")
+        self.generic_visit(node)
+
+    def visit_Subscript(self, node: ast.Subscript) -> None:
+        if self._is_environ_subscript(node):
+            self._record_subscript(node)
+        self.generic_visit(node)
+
+    # ---------------------------------------------------------------- matchers
+
+    def _is_getenv_call(self, node: ast.Call) -> bool:
+        func = node.func
+        # os.getenv(...)
+        if isinstance(func, ast.Attribute) and func.attr == "getenv":
+            return isinstance(func.value, ast.Name) and func.value.id in self._os_aliases
+        # getenv(...) via `from os import getenv`
+        if isinstance(func, ast.Name):
+            return func.id in self._getenv_aliases
+        return False
+
+    def _is_environ_get_call(self, node: ast.Call) -> bool:
+        func = node.func
+        if not isinstance(func, ast.Attribute) or func.attr != "get":
+            return False
+        inner = func.value
+        # os.environ.get(...)
+        if isinstance(inner, ast.Attribute) and inner.attr == "environ":
+            return isinstance(inner.value, ast.Name) and inner.value.id in self._os_aliases
+        # environ.get(...) via `from os import environ`
+        if isinstance(inner, ast.Name) and inner.id in self._environ_aliases:
+            return True
+        return False
+
+    def _is_environ_subscript(self, node: ast.Subscript) -> bool:
+        value = node.value
+        # os.environ["X"]
+        if isinstance(value, ast.Attribute) and value.attr == "environ":
+            return isinstance(value.value, ast.Name) and value.value.id in self._os_aliases
+        # environ["X"] via `from os import environ`
+        if isinstance(value, ast.Name) and value.id in self._environ_aliases:
+            return True
+        return False
+
+    # ----------------------------------------------------------------- recording
+
+    def _record_call(self, node: ast.Call, call_type: str) -> None:
+        if not node.args:
+            return
+        name_arg = node.args[0]
+        has_default = len(node.args) >= 2 or bool(node.keywords)
+        name = _extract_string(name_arg)
+        self.usages.append(
+            EnvUsage(
+                name=name,
+                file=self.file_path,
+                line=node.lineno,
+                has_default=has_default,
+                call_type=call_type,
+                raw_expr=None if name is not None else _unparse(name_arg),
+            )
+        )
+
+    def _record_subscript(self, node: ast.Subscript) -> None:
+        key_node = _subscript_key(node)
+        name = _extract_string(key_node) if key_node is not None else None
+        raw = None if name is not None else (_unparse(key_node) if key_node is not None else "?")
+        self.usages.append(
+            EnvUsage(
+                name=name,
+                file=self.file_path,
+                line=node.lineno,
+                has_default=False,
+                call_type="environ_subscript",
+                raw_expr=raw,
+            )
+        )
+
+
+# ------------------------------------------------------------------ helpers
+
+
+def _extract_string(node: Optional[ast.AST]) -> Optional[str]:
+    """Return the string value if node is a constant string literal, else None."""
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def _subscript_key(node: ast.Subscript) -> Optional[ast.AST]:
+    """Get the index node from a Subscript, handling py3.8 ast.Index wrapper."""
+    key = node.slice
+    # On Python 3.8, Subscript.slice is an ast.Index wrapping the actual node.
+    Index = getattr(ast, "Index", None)
+    if Index is not None and isinstance(key, Index):
+        return key.value  # type: ignore[attr-defined]
+    return key
+
+
+def _unparse(node: Optional[ast.AST]) -> str:
+    """Best-effort textual representation of an AST node for diagnostics."""
+    if node is None:
+        return "?"
+    unparse = getattr(ast, "unparse", None)
+    if unparse is not None:
+        try:
+            return unparse(node)
+        except Exception:
+            pass
+    return f"<expr at line {getattr(node, 'lineno', '?')}>"
+
+
+# ----------------------------------------------------------------- public api
+
+
+def scan_file(path: Path) -> List[EnvUsage]:
+    try:
+        source = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        raise ScanError(f"could not read {path}: {exc}") from exc
+    try:
+        tree = ast.parse(source, filename=str(path))
+    except SyntaxError as exc:
+        # might break on files with encoding declaratrions in weird places, haven't hit it yet
+        raise ScanError(f"syntax error in {path}: {exc}") from exc
+    visitor = _EnvVisitor(path)
+    visitor.visit(tree)
+    return visitor.usages
+
+
+# Default directories to skip when walking a project tree.
+DEFAULT_EXCLUDES = frozenset({
+    "venv", ".venv", "env",
+    "__pycache__", ".git", ".hg", ".svn",
+    "node_modules",
+    ".tox", ".nox",
+    "build", "dist",
+    ".mypy_cache", ".pytest_cache", ".ruff_cache",
+    ".eggs",
+})
+
+DEFAULT_EXTENSIONS = frozenset({".py"})
+
+# TODO: warn on files above this size, probably not worth scanning test fixtures
+MAX_FILE_SIZE = 2 * 1024 * 1024
+
+
+def iter_python_files(
+    root: Path,
+    extensions: Optional[Set[str]] = None,
+    extra_excludes: Optional[Set[str]] = None,
+) -> List[Path]:
+    """Walk `root` and yield all files matching the given extensions.
+
+    Directories named in DEFAULT_EXCLUDES (plus any in extra_excludes) are skipped.
+    """
+    exts = extensions or DEFAULT_EXTENSIONS
+    excludes = set(DEFAULT_EXCLUDES)
+    if extra_excludes:
+        excludes |= set(extra_excludes)
+
+    files: List[Path] = []
+    if root.is_file():
+        if root.suffix in exts:
+            files.append(root)
+        return files
+
+    for path in root.rglob("*"):
+        if any(part in excludes for part in path.parts):
+            continue
+        if path.is_file() and path.suffix in exts:
+            files.append(path)
+    return sorted(files)
+
+
+def scan_project(
+    root: Path,
+    extensions: Optional[Set[str]] = None,
+    extra_excludes: Optional[Set[str]] = None,
+    on_file: Optional[Callable[[Path], None]] = None,
+) -> ScanResult:
+    """Scan every Python file under `root` and return aggregated results.
+
+    `on_file` is an optional callback invoked after each file is processed
+    (useful for wiring up a progress bar from the CLI layer).
+    """
+    result = ScanResult()
+    files = iter_python_files(root, extensions=extensions, extra_excludes=extra_excludes)
+    result.scanned_files = files
+
+    for f in files:
+        try:
+            result.usages.extend(scan_file(f))
+        except ScanError as exc:
+            result.errors.append((f, str(exc)))
+        if on_file is not None:
+            on_file(f)
+
+    return result

envsleuth-0.1.0.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: envsleuth
+Version: 0.1.0
+Summary: Detective for env vars in Python code. Parses your source with AST, finds every os.getenv/os.environ usage, and tells you what's missing from your .env file.
+Author: k38f
+License: MIT
+Project-URL: Homepage, https://github.com/k38f/envsleuth
+Project-URL: Repository, https://github.com/k38f/envsleuth
+Project-URL: Issues, https://github.com/k38f/envsleuth/issues
+Keywords: env,dotenv,cli,static-analysis,ast,environment-variables
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: flashbar>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# envsleuth
+
+[![tests](https://github.com/k38f/envsleuth/actions/workflows/tests.yml/badge.svg)](https://github.com/k38f/envsleuth/actions/workflows/tests.yml)
+[![pypi](https://img.shields.io/pypi/v/envsleuth.svg)](https://pypi.org/project/envsleuth/)
+[![python](https://img.shields.io/pypi/pyversions/envsleuth.svg)](https://pypi.org/project/envsleuth/)
+[![license](https://img.shields.io/pypi/l/envsleuth.svg)](LICENSE)
+
+> 🕵️  The detective for env vars in Python code. Parses your source with AST, finds every `os.getenv()` / `os.environ[]` / `os.environ.get()`, and tells you what's missing from your `.env` file.
+
+No more shipping to prod and realising you forgot `STRIPE_API_KEY`.
+
+## Install
+
+```bash
+pip install envsleuth
+```
+
+## Usage
+
+```bash
+# scan current directory, check against ./.env
+envsleuth scan
+
+# specific directory, specific env file
+envsleuth scan --path ./src --env .env.production
+
+# CI mode — exits 1 if anything is missing
+envsleuth scan --strict
+
+# generate a .env.example from your code
+envsleuth generate
+
+# machine-readable output
+envsleuth scan --json
+```
+
+### Example output
+
+```
+Found 6 variables in code
+checking against .env
+
+⚠️  AWS_SECRET — not in .env but has default in code (probably ok)
+✅ DATABASE_URL
+✅ DEBUG
+❌ REDIS_URL — missing from .env
+     at src/app.py:7
+✅ SECRET_KEY
+❌ STRIPE_API_KEY — missing from .env
+     at src/app.py:6
+
+⚠️  1 dynamic usage (variable name computed at runtime, can't check statically)
+     src/app.py:12  →  getenv(name)
+
+ℹ  1 variable in .env not referenced in code: UNUSED_VAR
+
+3 ok  1 with default  2 missing
+```
+
+## What it detects
+
+Works with all three common patterns:
+
+```python
+import os
+
+a = os.getenv("A")              # required — must be in .env
+b = os.getenv("B", "fallback")  # has default — warned but not required
+c = os.environ["C"]             # required (would raise KeyError without)
+d = os.environ.get("D")         # required
+```
+
+Also handles aliased imports:
+
+```python
+from os import getenv, environ
+import os as sys_os
+
+a = getenv("A")
+b = environ["B"]
+c = sys_os.getenv("C")
+```
+
+Variables with names computed at runtime (e.g. `os.getenv(f"PREFIX_{x}")`) can't be checked statically — they're reported in a separate warning section so you know they exist.
+
+## `envsleuth generate`
+
+Scans your code and writes a `.env.example` with every variable found, a comment pointing at where it's used, and the default value from code if there is one:
+
+```bash
+$ envsleuth generate
+Wrote 6 variables to .env.example
+
+$ cat .env.example
+# Generated by envsleuth — edit this file before committing.
+# Each variable below is used somewhere in your code.
+
+# used at src/app.py:8
+AWS_SECRET=default-value
+
+# used at src/app.py:3
+DATABASE_URL=
+
+# used at src/app.py:5
+DEBUG=false
+...
+```
+
+Use `--force` to overwrite an existing file, `--output path/to/file` to write elsewhere.
+
+## `.envignore`
+
+Exclude variables from the "missing" check with glob patterns — one per line:
+
+```
+# .envignore
+TEST_*
+LEGACY_*
+DEBUG_TOOL
+```
+
+Great for vars that come from CI, Docker, or your shell rc files rather than the local `.env`.
+
+## CI usage
+
+GitHub Actions:
+
+```yaml
+- name: Check env vars
+  run: |
+    pip install envsleuth
+    envsleuth scan --env .env.example --strict
+```
+
+pre-commit:
+
+```yaml
+# .pre-commit-config.yaml
+- repo: local
+  hooks:
+    - id: envsleuth
+      name: envsleuth
+      entry: envsleuth scan --strict
+      language: system
+      pass_filenames: false
+```
+
+## CLI reference
+
+### `envsleuth scan`
+
+| Flag | Description |
+| --- | --- |
+| `--path`, `-p` | Directory or file to scan. Default: `.` |
+| `--env` | Path to `.env` file. Default: `./.env` |
+| `--envignore` | Path to `.envignore`. Default: `./.envignore` if present |
+| `--strict` | Exit with code 1 if vars are missing |
+| `--json` | JSON output for CI pipelines |
+| `--no-color` | Disable ANSI colors (also honours `NO_COLOR` env var) |
+| `--exclude DIR` | Extra directory name to skip. Can be repeated |
+| `--ext .EXT` | Extra file extension to scan (e.g. `.pyi`). Can be repeated |
+| `--verbose`, `-v` | Show usage locations for every variable |
+
+### `envsleuth generate`
+
+| Flag | Description |
+| --- | --- |
+| `--path`, `-p` | Directory or file to scan. Default: `.` |
+| `--output`, `-o` | Where to write. Default: `./.env.example` |
+| `--force`, `-f` | Overwrite existing output file |
+| `--exclude`, `--ext` | Same as in `scan` |
+
+## How it compares
+
+| | envsleuth | [dotenv-linter](https://github.com/dotenv-linter/dotenv-linter) | [python-decouple](https://github.com/HBNetwork/python-decouple) |
+| --- | --- | --- | --- |
+| Scans your **code** for env var usages | ✅ | ❌ | ❌ |
+| Lints the **.env file itself** | ❌ | ✅ | ❌ |
+| Runtime config reader with casting | ❌ | ❌ | ✅ |
+| Generates `.env.example` from code | ✅ | ❌ | ❌ |
+| Language | Python | Rust | Python |
+
+envsleuth is the only tool here that understands your **source code**. The others either look at your `.env` file in isolation, or read env vars at runtime.
+
+## Dependencies
+
+- [click](https://click.palletsprojects.com/) — CLI
+- [python-dotenv](https://github.com/theskumar/python-dotenv) — `.env` parsing
+- [flashbar](https://github.com/k38f/flashbar) — progress bar (a tiny zero-dep lib I wrote; envsleuth uses it when scanning 20+ files)
+
+The scanner itself uses only the Python standard library (`ast`).
+
+## License
+
+MIT

envsleuth-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+envsleuth/__init__.py,sha256=XE7sPOSampeyt5JAj9PQgoTAiMyL1cgvTu59S81FChY,105
+envsleuth/checker.py,sha256=2Zmibiy8oHw4HZusVYzBz11jVFmoTWxW4E_3nthOcj0,4685
+envsleuth/cli.py,sha256=bUnS0fgUDzvXnEDWKNWjkiIvcSvfyQGP7u1dqmkRdlw,6854
+envsleuth/display.py,sha256=T3L3V8qRp5CtYx5-kjONofEvOQ8dcY6d8q_kIEDgr9M,8810
+envsleuth/generator.py,sha256=dCi5d9Mn8XG0WAKIpjTt2bsPKwzS0LArl9ArUjQKm6E,3321
+envsleuth/scanner.py,sha256=RXWGSD2zs_SR1AcSzq769hkTQgrCXZ27M3D3btiIQew,11014
+envsleuth-0.1.0.dist-info/licenses/LICENSE,sha256=PO0Zof1q5ED5CtdGIxF_vvgGbiwAlAImqcfYi4K9FtE,1061
+envsleuth-0.1.0.dist-info/METADATA,sha256=_XQ7SWxVW8mPCoy34aPvULm_Ao-WXbfsJzcqwhd_RGY,7029
+envsleuth-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+envsleuth-0.1.0.dist-info/entry_points.txt,sha256=fNmL1gFMWfJkfmHiZqUi7aVkExc9u2jM-aFl9N2Jf1E,48
+envsleuth-0.1.0.dist-info/top_level.txt,sha256=vfdfF2IAQUKlrLFQDeTcu4hHHVSi2MOS9l_CzBuvXsg,10
+envsleuth-0.1.0.dist-info/RECORD,,

envsleuth-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

envsleuth-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+envsleuth = envsleuth.cli:cli

envsleuth-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 k38f
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

envsleuth-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+envsleuth