Skip to content

Commit 7e048ae

Browse files
authored
Merge pull request #1 from SemTiOne/fix/env-auditor-audit
fix: PASS/FAIL exit-code divergence, Docker false positives, coverage gate, mypy clean
2 parents 25aa98d + b9976df commit 7e048ae

12 files changed

Lines changed: 581 additions & 80 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,4 +60,3 @@ jobs:
6060

6161
- name: Type-check with mypy
6262
run: mypy src/env_auditor --ignore-missing-imports --strict
63-
continue-on-error: true # advisory for now; flip to false when clean

‎CHANGELOG.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,56 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [Unreleased]
9+
10+
> Note: versions 0.1.1–0.1.4 shipped (see pyproject.toml) without corresponding
11+
> entries here. Those changes (project rename to env-auditor, CRLF injection
12+
> fix in `sanitize_raw`, `output_format` validation, `.gitattributes`) are not
13+
> reconstructed retroactively to avoid documenting them inaccurately. This gap
14+
> is disclosed rather than backfilled with guessed details.
15+
16+
### Fixed
17+
- `[tool.env-auditor]` in `pyproject.toml` was silently ignored on Python 3.10
18+
without `tomli` installed. The fallback TOML parser flattened all
19+
`[section]` tables into one shared namespace, so the section could never be
20+
found. The fallback parser is now section-aware.
21+
- `--config FILE` read the *parent directory* of the given file and
22+
auto-discovered `.env-auditorrc`/`env-auditor.toml`/`pyproject.toml` there,
23+
ignoring the actual file passed. It now reads exactly the file given.
24+
- `required_keys` was parsed from config but never enforced anywhere, missing
25+
required keys now correctly cause exit code 1 and appear in both text and
26+
JSON output.
27+
- Docker `ENV KEY1=a KEY2=b KEY3=c` (recommended single-line multi-assignment
28+
style) only detected `KEY1`. Now detects all keys on the line. Scoped
29+
strictly to `ENV`/`ARG` lines so it does not also match shell-local
30+
`KEY=value` assignments on `RUN`/`LABEL`/`CMD` lines.
31+
- `--exclude some/path/foo` also silently excluded every other directory
32+
named `foo` anywhere in the tree (matched by basename, not full path).
33+
- List-typed config values given the wrong type (e.g. `ignore_keys = true`)
34+
were silently ignored instead of warning.
35+
- The human-readable and JSON reports could display `Result: PASS` /
36+
`"result": "pass"` while the process exited with code 1, whenever the only
37+
failure was stale variables under `--strict` — the renderers computed their
38+
own incomplete pass/fail flag that never accounted for `--strict`. Pass/fail
39+
is now computed once and shared between the exit code and both output
40+
formats.
41+
- `--strict` combined with `--ignore-stale` could exit 1 with no visible
42+
explanation at all (the stale section causing the failure was hidden by
43+
`--ignore-stale`, and nothing else in the report indicated why). Both
44+
output formats now include a note when this happens.
45+
- `mypy --strict` (as run in CI) now passes with zero errors, down from 14.
46+
47+
### Changed
48+
- CI's mypy step is no longer `continue-on-error: true` now that it's clean.
49+
- `load_config` and `load_config_from_file` shared ~40 lines of duplicated
50+
size-check/parse/error-handling logic; extracted into `_read_config_raw`.
51+
52+
### Removed
53+
- `EnvCheckConfig` alias (leftover from the env-check → env-auditor rename).
54+
Unused anywhere in the codebase; the rename it bridged is long complete.
55+
If you were importing it directly from a pinned old version, use
56+
`EnvAuditorConfig` instead.
57+
858
## [0.1.0] - 2026-04-21
959

1060
### Added

‎src/env_auditor/cli.py‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -308,12 +308,28 @@ def _run_audit(
308308
required_missing=required_missing,
309309
)
310310

311+
# Single source of truth for pass/fail, computed once and shared by both
312+
# the exit code and the rendered output, previously the renderers
313+
# recomputed their own (incomplete) "passed" flag that ignored --strict
314+
# entirely, so a stale-only failure under --strict would print
315+
# "Result: PASS" while the process still exited 1.
316+
effective_undoc = diff.undocumented - ignore_keys
317+
effective_stale = diff.stale - ignore_keys
318+
if effective_undoc or diff.required_missing:
319+
exit_code = 1
320+
elif cfg.strict and effective_stale:
321+
exit_code = 1
322+
else:
323+
exit_code = 0
324+
passed = exit_code == 0
325+
311326
fmt = cfg.output_format or "text"
312327

313328
if fmt == "json":
314329
output = render_json(
315330
diff,
316331
scan_result,
332+
passed=passed,
317333
ignore_stale=cfg.ignore_stale,
318334
ignore_missing=cfg.ignore_missing,
319335
ignore_keys=ignore_keys,
@@ -322,20 +338,14 @@ def _run_audit(
322338
output = render_text(
323339
diff,
324340
scan_result,
341+
passed=passed,
325342
use_color=use_color,
326343
ignore_stale=cfg.ignore_stale,
327344
ignore_missing=cfg.ignore_missing,
328345
ignore_keys=ignore_keys,
329346
)
330347

331-
effective_undoc = diff.undocumented - ignore_keys
332-
effective_stale = diff.stale - ignore_keys
333-
334-
if effective_undoc or diff.required_missing:
335-
return 1, output
336-
if cfg.strict and effective_stale:
337-
return 1, output
338-
return 0, output
348+
return exit_code, output
339349

340350

341351
# ──────────────────────────────────────────────────────────────────────────────
@@ -360,4 +370,4 @@ def main(argv: Optional[list[str]] = None) -> None:
360370

361371
exit_code, output = _run_audit(scan_root, cfg, use_color)
362372
print(output)
363-
sys.exit(exit_code)
373+
sys.exit(exit_code)

‎src/env_auditor/config.py‎

Lines changed: 54 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
import sys
55
from dataclasses import dataclass, field, replace as dataclass_replace
66
from pathlib import Path
7-
from typing import Optional
7+
from typing import Any, Optional, cast
88

99
# Config file is searched in this order within the scan root.
1010
CONFIG_FILENAMES = (".env-auditorrc", "env-auditor.toml", "pyproject.toml")
@@ -48,10 +48,6 @@ class EnvAuditorConfig:
4848
"""Keys that MUST be documented; always flagged if missing."""
4949

5050

51-
# Keep old name as alias so existing imports don't break during transition
52-
EnvCheckConfig = EnvAuditorConfig
53-
54-
5551
def load_config(scan_root: Path) -> EnvAuditorConfig:
5652
"""Search for and parse a config file within *scan_root*.
5753
@@ -70,30 +66,15 @@ def load_config(scan_root: Path) -> EnvAuditorConfig:
7066
if not candidate.is_file():
7167
continue
7268

73-
# Guard: size limit — prevents memory exhaustion
74-
try:
75-
size = candidate.stat().st_size
76-
except OSError:
77-
continue
78-
79-
if size > CONFIG_FILE_SIZE_LIMIT:
80-
print(
81-
f"env-auditor: warning: config file {candidate} exceeds "
82-
f"{CONFIG_FILE_SIZE_LIMIT // 1024} KB size limit, skipping",
83-
file=sys.stderr,
84-
)
85-
continue
86-
87-
try:
88-
raw = _parse_toml_file(candidate, filename == "pyproject.toml")
89-
except (OSError, ValueError, KeyError, TypeError) as exc:
90-
print(
91-
f"env-auditor: warning: could not parse config {candidate}: {exc}",
92-
file=sys.stderr,
93-
)
69+
raw, hard_error = _read_config_raw(candidate)
70+
if hard_error:
71+
# A candidate that exists but is broken (unreadable, unparseable)
72+
# stops the search here rather than silently falling through to
73+
# a different config file the user may not know exists.
9474
return EnvAuditorConfig()
95-
9675
if raw is None:
76+
# File parsed fine but has no env-auditor section for us (e.g. a
77+
# pyproject.toml without [tool.env-auditor]), keep looking.
9778
continue
9879

9980
return _dict_to_config(raw, candidate)
@@ -105,7 +86,7 @@ def load_config_from_file(path: Path) -> EnvAuditorConfig:
10586
"""Load config from an explicitly specified file path.
10687
10788
Unlike :func:`load_config`, which auto-discovers config files by name
108-
within a directory, this function reads *exactly* the file given —
89+
within a directory, this function reads exactly the file given,
10990
regardless of its name. Used by the ``--config FILE`` CLI flag.
11091
11192
Args:
@@ -114,22 +95,53 @@ def load_config_from_file(path: Path) -> EnvAuditorConfig:
11495
Returns:
11596
Populated EnvAuditorConfig (defaults if the file cannot be parsed).
11697
"""
98+
raw, _hard_error = _read_config_raw(path)
99+
if raw is None:
100+
print(
101+
f"env-auditor: warning: no [tool.env-auditor] section found in "
102+
f"{path}, using defaults",
103+
file=sys.stderr,
104+
)
105+
return EnvAuditorConfig()
106+
107+
return _dict_to_config(raw, path)
108+
109+
110+
def _read_config_raw(path: Path) -> tuple[Optional[dict[str, Any]], bool]:
111+
"""Validate size, parse path as TOML, and return its env-auditor section.
112+
113+
Shared by :func:`load_config` (auto-discovery) and
114+
:func:`load_config_from_file` (explicit ``--config``) to avoid duplicating
115+
the size-limit check and parse-error handling in both places.
116+
117+
Args:
118+
path: Path to a config file that is known to exist.
119+
120+
Returns:
121+
``(raw, hard_error)`` where:
122+
- ``raw`` is the parsed env-auditor section dict, or ``None`` if the
123+
file parsed cleanly but has no such section (e.g. pyproject.toml
124+
without ``[tool.env-auditor]``).
125+
- ``hard_error`` is ``True`` if the file could not be stat'd, exceeded
126+
the size limit, or failed to parse. Callers should not treat a
127+
hard error the same as "no section found".
128+
"""
117129
try:
118130
size = path.stat().st_size
119131
except OSError as exc:
120132
print(
121133
f"env-auditor: warning: cannot stat config file {path}: {exc}",
122134
file=sys.stderr,
123135
)
124-
return EnvAuditorConfig()
136+
return None, True
125137

126138
if size > CONFIG_FILE_SIZE_LIMIT:
127139
print(
128140
f"env-auditor: warning: config file {path} exceeds "
129141
f"{CONFIG_FILE_SIZE_LIMIT // 1024} KB size limit, using defaults",
130142
file=sys.stderr,
131143
)
132-
return EnvAuditorConfig()
144+
return None, True
133145

134146
try:
135147
raw = _parse_toml_file(path, is_pyproject=(path.name == "pyproject.toml"))
@@ -138,20 +150,12 @@ def load_config_from_file(path: Path) -> EnvAuditorConfig:
138150
f"env-auditor: warning: could not parse config {path}: {exc}",
139151
file=sys.stderr,
140152
)
141-
return EnvAuditorConfig()
153+
return None, True
142154

143-
if raw is None:
144-
print(
145-
f"env-auditor: warning: no [tool.env-auditor] section found in "
146-
f"{path}, using defaults",
147-
file=sys.stderr,
148-
)
149-
return EnvAuditorConfig()
150-
151-
return _dict_to_config(raw, path)
155+
return raw, False
152156

153157

154-
def _parse_toml_file(path: Path, is_pyproject: bool) -> Optional[dict]:
158+
def _parse_toml_file(path: Path, is_pyproject: bool) -> Optional[dict[str, Any]]:
155159
"""Parse *path* as TOML and return the env-auditor section, or None.
156160
157161
Uses stdlib ``tomllib`` (Python 3.11+) with ``tomli`` fallback,
@@ -179,11 +183,11 @@ def _parse_toml_file(path: Path, is_pyproject: bool) -> Optional[dict]:
179183

180184
if is_pyproject:
181185
tool = data.get("tool", {})
182-
return tool.get("env-auditor") # None if not present
186+
return cast(Optional[dict[str, Any]], tool.get("env-auditor")) # None if not present
183187
return data or None
184188

185189

186-
def _minimal_toml_parse(path: Path) -> dict:
190+
def _minimal_toml_parse(path: Path) -> dict[str, Any]:
187191
"""Hand-rolled TOML subset parser for .env-auditorrc on Python 3.10.
188192
189193
Handles: string, bool, list of strings, comments, blank lines, and
@@ -200,8 +204,8 @@ def _minimal_toml_parse(path: Path) -> dict:
200204
Returns:
201205
Nested dict of parsed key/value pairs.
202206
"""
203-
result: dict = {}
204-
current_node: dict = result # pointer into result at the current section
207+
result: dict[str, Any] = {}
208+
current_node: dict[str, Any] = result # pointer into result at the current section
205209
text = path.read_text(encoding="utf-8", errors="replace")
206210

207211
for raw_line in text.splitlines():
@@ -244,7 +248,7 @@ def _minimal_toml_parse(path: Path) -> dict:
244248
return result
245249

246250

247-
def _dict_to_config(raw: dict, source: Path) -> EnvAuditorConfig:
251+
def _dict_to_config(raw: dict[str, Any], source: Path) -> EnvAuditorConfig:
248252
"""Convert a raw dict from TOML into an EnvAuditorConfig.
249253
250254
Unknown keys are warned about but ignored. Type coercion is strict —
@@ -262,7 +266,7 @@ def _dict_to_config(raw: dict, source: Path) -> EnvAuditorConfig:
262266
raw = dict(raw)
263267
raw["output_format"] = raw.pop("format")
264268

265-
known_keys = set(EnvAuditorConfig.__dataclass_fields__.keys()) # type: ignore[attr-defined]
269+
known_keys = set(EnvAuditorConfig.__dataclass_fields__.keys())
266270
cfg = EnvAuditorConfig()
267271

268272
for key, value in raw.items():
@@ -274,7 +278,7 @@ def _dict_to_config(raw: dict, source: Path) -> EnvAuditorConfig:
274278
continue
275279

276280
field_type = str(
277-
EnvAuditorConfig.__dataclass_fields__[key].type # type: ignore[attr-defined]
281+
EnvAuditorConfig.__dataclass_fields__[key].type
278282
)
279283

280284
try:
@@ -339,7 +343,7 @@ def merge_cli_into_config(
339343
Returns:
340344
New EnvAuditorConfig with CLI overrides applied.
341345
"""
342-
overrides: dict = {}
346+
overrides: dict[str, Any] = {}
343347
if env_files is not None:
344348
overrides["env_files"] = env_files
345349
if exclude_dirs is not None:
@@ -361,4 +365,4 @@ def merge_cli_into_config(
361365
output_format = "text"
362366
overrides["output_format"] = output_format
363367

364-
return dataclass_replace(cfg, **overrides)
368+
return dataclass_replace(cfg, **overrides)

‎src/env_auditor/patterns.py‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
import re
44
from dataclasses import dataclass, field
5-
from typing import Sequence
5+
from typing import Optional, Sequence
66

77
# Env var name: uppercase, starts with letter, underscores/digits allowed
88
ENV_VAR_NAME = r"([A-Z][A-Z0-9_]*)"
@@ -20,6 +20,14 @@ class LanguagePattern:
2020
extensions: Sequence[str]
2121
static_patterns: Sequence[re.Pattern[str]]
2222
dynamic_patterns: Sequence[re.Pattern[str]] = field(default_factory=list)
23+
line_filter: Optional[re.Pattern[str]] = None
24+
"""If set, static_patterns/dynamic_patterns are only applied to lines that
25+
match this filter first. Used by Docker: the KEY= continuation pattern
26+
(which has no anchor of its own) must not fire on RUN/LABEL/CMD lines that
27+
happen to contain shell-local KEY=value assignments, e.g.
28+
``RUN DEBIAN_FRONTEND=noninteractive apt-get install -y curl``, that is
29+
a build-time shell variable, not a container ENV declaration, and must
30+
not be reported as an (un)documented application variable."""
2331

2432

2533
LANGUAGE_PATTERNS: list[LanguagePattern] = [
@@ -77,13 +85,27 @@ class LanguagePattern:
7785
),
7886
LanguagePattern(
7987
name="Docker",
80-
extensions=[""], # matched by filename, not extension
88+
extensions=[], # matched by filename in scanner._get_patterns, not
89+
# extension. Do not add "" here: EXTENSION_MAP registers every
90+
# entry in `extensions` verbatim, so extensions=[""] previously
91+
# made *every* extensionless file (Makefile, LICENSE, README, ...)
92+
# fall through to Docker's ENV/ARG patterns via the generic
93+
# EXTENSION_MAP[""] lookup, not just genuine Dockerfiles.
8194
static_patterns=[
95+
# ENV KEY=val (new style, single) or ENV KEY value (deprecated style)
8296
re.compile(r"^\s*ENV\s+" + ENV_VAR_NAME),
97+
# ENV KEY1=val1 KEY2=val2 KEY3=val3 — additional vars after the first
98+
# (Docker's recommended single-line multi-assignment style, used to
99+
# reduce image layer count). Scoped to ENV/ARG lines only via
100+
# line_filter below. This pattern has no anchor of its own and
101+
# would otherwise match KEY=value tokens on RUN/LABEL/CMD lines too
102+
# (e.g. RUN DEBIAN_FRONTEND=noninteractive apt-get install ...).
83103
re.compile(r"(?<=\s)" + ENV_VAR_NAME + r"="),
104+
# ARG KEY or ARG KEY=default
84105
re.compile(r"^\s*ARG\s+" + ENV_VAR_NAME),
85106
],
86107
dynamic_patterns=[],
108+
line_filter=re.compile(r"^\s*(?:ENV|ARG)\s"),
87109
),
88110
LanguagePattern(
89111
name="Ruby",
@@ -119,4 +141,4 @@ class LanguagePattern:
119141
"LANG", "LC_ALL", "IFS", "PS1", "PS2", "OLDPWD",
120142
"SHLVL", "LOGNAME", "MAIL", "HOSTNAME",
121143
}
122-
)
144+
)

0 commit comments

Comments
 (0)