missing-env

Jemand fügt process.env.STRIPE_SECRET_KEY hinzu, setzt den Wert auf seinem Rechner und vergisst, ihn aufzuschreiben. Zwei Wochen später klont ein neuer Kollege das Repository, die Anwendung startet ohne Fehler, und der Wert taucht als undefined mitten in einem Zahlungsvorgang wieder auf. Das ist kein exotischer Fall, das passiert in jedem Team.

Es gibt Werkzeuge, die .env-Dateien prüfen. Die haben alle dasselbe Problem: Sie kennen nur die Datei, nicht das Programm. missing-env geht den umgekehrten Weg. Es liest den Quellcode, sammelt jeden Lesezugriff auf eine Umgebungsvariable und vergleicht diese Liste gegen .env und .env.example. Fehlt eine Pflichtvariable, ist der Exit-Code 1 — damit taugt der Aufruf als Gate in der CI, nicht nur als Bericht für Menschen.

Der Grund, warum das kein grep ist, steht in einer einzigen Datei: dem Lexer. Ein auskommentierter Zugriff ist keiner, ein Vorkommen in einem String-Literal ist keiner, der Code in einem Template-Loch dagegen schon. Kommentare werden dabei mit Leerzeichen überschrieben statt gelöscht, damit Byte-Offsets und Zeilennummern exakt bleiben — eine Fundstelle, die auf die falsche Zeile zeigt, ist schlimmer als keine. Dieselbe Schicht kennt Python-Docstrings, verschachtelte Rust-Blockkommentare und den Unterschied zwischen '…' und "…" in Shell-Skripten, wo in doppelten Anführungszeichen ${VAR} weiterhin Code ist.

Die zentrale Entscheidung ist, was überhaupt Pflicht ist. Dafür gibt es genau eine Regel: Ein Lesezugriff ist optional, wenn die Aufrufstelle einen Ersatzwert liefert. process.env.DATABASE_URL ist Pflicht, process.env.LOG_LEVEL ?? 'info' nicht. Zwei Ausnahmen gelten auch ohne Default als optional, weil die API den Aufrufer zwingt, das Fehlen zu behandeln: Gos os.LookupEnv und Rusts option_env!. Diese Einheitlichkeit war Absicht — eine Regel, die sich in einer Zeile README erklären lässt, wird auch geglaubt.

Erkannt wird das in elf Sprachfamilien: JavaScript samt TypeScript, Python, Go, Ruby, PHP, Java samt Kotlin und Scala, C#, Rust, Shell-Skripte, YAML inklusive docker-compose und Dockerfiles. Das Ganze sind 1.774 Zeilen Quellcode gegen 748 Zeilen Tests, null Laufzeit-Abhängigkeiten und als Entwicklungsabhängigkeiten nur TypeScript, Prettier und die Node-Typen. Das Paket liegt unter MIT auf npm, eine GitHub Action verpackt denselben Aufruf für Pipelines, und die CI prüft Node 20, 22 und 24.

Den peinlichsten Fehler fand das Werkzeug an sich selbst: Eigene ignore-Angaben ersetzten die Standard-Ausschlüsse, statt sie zu ergänzen — womit plötzlich node_modules mitgescannt wurde. Ein Linter, den man auf sein eigenes Repository loslässt, ist die ehrlichste Testmethode, die es für so ein Werkzeug gibt.