RFC: (Dev-time .env file linter)

[yamcodes]

Note: This discussion was converted from issue #481. For the v1 core, we are keeping our API surface laser-focused on runtime validation (arkenv check) rather than building custom AST parsers for file formatting. Leaving this architectural specification here for future consideration or if the community wants to explore a standalone CLI linter or tool.

---

Summary

arkenv lint was conceived as a dev-time linter for .env* files on disk. It is complementary to arkenv check, not a second name for the same command.

• check (#962, shipped in #1632): would this process boot? Subject is the resolved environment (process.env plus optional --env-file overlays) vs the schema. Key-level findings. CI / hooks.
• lint (this RFC): are these dotenv files well-authored? Subject is files on disk: syntax, duplicates, unquoted spaces, git-tracked secrets, example placeholders, and schema issues pinned to file:line:col. Editor problem matchers and pre-commit on .env*.
• sync (#1234): writes files from the schema. Third sibling, same schema loader.

---

Architecture Blueprint

One pipeline, two subjects:

schema load (CLI schema loader)
        ↓
env record  ──►  validate()  ──►  EnvIssue[]
        ↑
   dotenv parse

lint was designed to reuse check’s schema loader and validate() — not fork a second validation path. It would grow the dotenv parser so a parse yields both an env record and a coordinate map, run static rules that only make sense on files, then remap EnvIssue[] onto those coordinates.

---

Desired Behavior Spec

Command

arkenv lint [--schema <path>] [--env <name>]

Parser & Coordinate Mapping

Coordinate-aware line scanner: each defined key maps to file, line, and col. Malformed lines are diagnostics, not silent skips.

Lint Rules

• Rule 1 (Schema validation): values vs the imported schema (types, missing keys, bounds, patterns), mapped to coordinates.
• Rule 2 (Syntax): malformed lines (e.g. missing =).
• Rule 3 (Unquoted spaces): warn on unquoted values that contain spaces.
• Rule 4 (Git): warn if sensitive .env files are tracked instead of ignored.
• Rule 5 (Duplicates): error if a key is defined more than once in the same file.
• Rule 6 (Example placeholders): .env.example must not contain real secrets.

Output & Exit Codes

• Default: Unix problem-matcher format path/to/file.env:line:col: message
• --json / --agent: settlement envelope; diagnostics include where: { path, line, column } pointing at dotenv files
• Non-zero on any lint or validation finding