`.env` linter

[yamcodes]

Summary

This RFC proposes a linter for .env files that validates entries against an ArkEnv schema during development, without running the app or performing a build. The linter should work in IDEs and via a CLI script, providing early, actionable feedback on environment configuration.

The aim is to bring environment validation into devtime, similar to how tsc provides early type safety, with lint-like errors surfaced directly on .env files.

Motivation

Developers often define environment variables ahead of time in files like .env.development and .env.production. In many projects, the set of variables, their types, and expected shapes are known early, yet validation is deferred to runtime or build.

A devtime linter aligns with how teams expect configuration to behave:

• catch mistakes early
• surface issues in-editor
• avoid wasted time starting dev servers or CI jobs

Rather than building a new infrastructure from scratch, we can leverage existing linting ecosystems and optionally provide a lightweight CLI for projects that prefer scripts over IDE integrations.

Proposal

Introduce a dotenv linter that reads an ArkEnv schema and validates .env files at devtime. The linter should:

• map ArkEnv schema definitions to rules that check presence, type, allowed values, and coercion expectations
• produce lint-like diagnostics on .env files, including per-line messages and quick fixes where possible
• run in IDEs without launching the app, and as a CLI for CI or pre-commit workflows

Integration paths:

• IDE integration via existing lint frameworks or a VS Code extension
• CLI command, for example arkenv lint, that scans .env* files and exits with non-zero status on violations
• potential plugins for existing tools like dotenv-linter, Biome, or Oxc if feasible

Goals

• Provide early feedback when .env entries do not match the ArkEnv schema
• Validate presence, type, and value constraints for variables
• Offer both IDE diagnostics and CLI scripting for CI and pre-commit
• Minimize maintenance by reusing existing lint frameworks where possible

Non-Goals

• Replace runtime validation or parsing logic
• Manage secrets or deployment workflows
• Build a full linter framework from scratch if existing ecosystems can be extended

Open Questions

• Should this ship as a standalone arkenv subcommand like arkenv lint, or as plugins for existing linters, or both?
• How should multiple environments be resolved and prioritized, for example .env.development, .env.production, .env.local?
• What is the best way to expose ArkEnv schema context to the linter, for example codegen, config files, or direct imports?
• How should coercion and transforms be represented in diagnostics, for example string to number or boolean hints?
• What is the minimal set of IDE features needed, for example highlights, quick fixes, code actions?

Related Work

• Prior discussion in RFC: CLI tool for devtime environment variable validation
• Existing dotenv-linter and general-purpose lint engines like Biome and Oxc may be candidates for plugin integration
• Potentially duplicated by CLI tool for dev-time environment variable validation #642