dotguard-cli 0.2.0__py3-none-any.whl

dotguard/__init__.py

@@ -0,0 +1,22 @@
+"""dotguard: validate .env files against a documented .env.example."""
+
+from dotguard.checker import check
+from dotguard.differ import diff
+from dotguard.models import Entry, EnvFile, Issue, Severity
+from dotguard.parser import parse, parse_file
+from dotguard.secrets import scan
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Entry",
+    "EnvFile",
+    "Issue",
+    "Severity",
+    "check",
+    "diff",
+    "parse",
+    "parse_file",
+    "scan",
+    "__version__",
+]

dotguard/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from dotguard.cli import main
+
+sys.exit(main())

dotguard/checker.py

@@ -0,0 +1,203 @@
+"""Compare a .env file with the .env.example that documents it."""
+
+from __future__ import annotations
+
+import re
+
+from dotguard.models import Entry, EnvFile, Issue, Severity
+from dotguard.types import NUMERIC_TYPES, VALIDATORS
+
+KNOWN_ANNOTATIONS = {
+    "type",
+    "required",
+    "optional",
+    "pattern",
+    "values",
+    "min",
+    "max",
+    "secret",
+    "deprecated",
+}
+
+
+def check(env: EnvFile, example: EnvFile, strict: bool = False) -> list[Issue]:
+    """Return every issue found in ``env`` according to ``example``.
+
+    ``strict`` turns keys that exist only in ``env`` into errors instead of
+    warnings.
+    """
+    issues: list[Issue] = []
+
+    for spec in example.entries:
+        issues.extend(_check_annotations(spec, example.path))
+        entry = env.get(spec.key)
+
+        if entry is None:
+            if "optional" not in spec.annotations:
+                issues.append(
+                    Issue(
+                        "DG001",
+                        f"{spec.key} is missing (documented in {example.path}:{spec.line})",
+                        Severity.ERROR,
+                        env.path,
+                        key=spec.key,
+                    )
+                )
+            continue
+
+        if "deprecated" in spec.annotations:
+            reason = spec.annotations["deprecated"] or "it is deprecated"
+            issues.append(
+                Issue(
+                    "DG008",
+                    f"{spec.key} is deprecated: {reason}",
+                    Severity.WARNING,
+                    env.path,
+                    entry.line,
+                    spec.key,
+                )
+            )
+
+        issues.extend(_check_value(entry, spec, env.path))
+
+    documented = set(example.keys())
+    for entry in env.entries:
+        for name in entry.unresolved:
+            issues.append(
+                Issue(
+                    "DG011",
+                    f"{entry.key} references ${{{name}}}, which is not defined above it",
+                    Severity.WARNING,
+                    env.path,
+                    entry.line,
+                    entry.key,
+                )
+            )
+        if entry.key not in documented:
+            issues.append(
+                Issue(
+                    "DG002",
+                    f"{entry.key} is not documented in {example.path}",
+                    Severity.ERROR if strict else Severity.WARNING,
+                    env.path,
+                    entry.line,
+                    entry.key,
+                )
+            )
+
+    return issues
+
+
+def _check_annotations(spec: Entry, path: str) -> list[Issue]:
+    issues = []
+    for name in spec.annotations:
+        if name not in KNOWN_ANNOTATIONS:
+            issues.append(
+                Issue(
+                    "DG009",
+                    f"unknown annotation @{name} on {spec.key}",
+                    Severity.WARNING,
+                    path,
+                    spec.line,
+                    spec.key,
+                )
+            )
+
+    type_name = spec.annotations.get("type")
+    if type_name is not None and type_name not in VALIDATORS:
+        issues.append(
+            Issue(
+                "DG010",
+                f"unknown @type {type_name!r} on {spec.key}; "
+                f"choose one of: {', '.join(sorted(VALIDATORS))}",
+                Severity.ERROR,
+                path,
+                spec.line,
+                spec.key,
+            )
+        )
+
+    pattern = spec.annotations.get("pattern")
+    if pattern is not None:
+        try:
+            re.compile(pattern)
+        except re.error as exc:
+            issues.append(
+                Issue(
+                    "DG010",
+                    f"invalid @pattern on {spec.key}: {exc}",
+                    Severity.ERROR,
+                    path,
+                    spec.line,
+                    spec.key,
+                )
+            )
+    return issues
+
+
+def _check_value(entry: Entry, spec: Entry, path: str) -> list[Issue]:
+    rules = spec.annotations
+    value = entry.value
+
+    def issue(code: str, message: str) -> Issue:
+        return Issue(code, message, Severity.ERROR, path, entry.line, entry.key)
+
+    if value == "":
+        if "required" in rules:
+            return [issue("DG003", f"{entry.key} is required but empty")]
+        # An empty optional value has nothing else to validate.
+        return []
+
+    type_name = rules.get("type", "string")
+    validator = VALIDATORS.get(type_name)
+    if validator is not None:
+        reason = validator(value)
+        if reason:
+            return [issue("DG004", f"{entry.key}={_preview(value, rules)}: {reason}")]
+
+    issues = []
+
+    pattern = rules.get("pattern")
+    if pattern is not None:
+        try:
+            if not re.fullmatch(pattern, value):
+                issues.append(
+                    issue("DG005", f"{entry.key} does not match pattern {pattern!r}")
+                )
+        except re.error:
+            pass  # Already reported by _check_annotations.
+
+    allowed = rules.get("values")
+    if allowed:
+        choices = [choice.strip() for choice in allowed.split(",") if choice.strip()]
+        if value not in choices:
+            issues.append(
+                issue(
+                    "DG007",
+                    f"{entry.key}={_preview(value, rules)} is not one of: {', '.join(choices)}",
+                )
+            )
+
+    if type_name in NUMERIC_TYPES:
+        number = float(value)
+        for bound, compare, word in (("min", float.__lt__, "below"), ("max", float.__gt__, "above")):
+            limit = rules.get(bound)
+            if limit is None:
+                continue
+            try:
+                limit_value = float(limit)
+            except ValueError:
+                continue
+            if compare(number, limit_value):
+                issues.append(
+                    issue("DG006", f"{entry.key}={value} is {word} the @{bound} of {limit}")
+                )
+
+    return issues
+
+
+def _preview(value: str, rules: dict) -> str:
+    """Never echo a secret back to the terminal or a CI log."""
+    if "secret" in rules:
+        return "****"
+    return value if len(value) <= 40 else value[:37] + "..."

dotguard/cli.py

@@ -0,0 +1,182 @@
+"""Command-line interface: ``dotguard check | scan | diff | init``."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from dotguard import __version__
+from dotguard.checker import check
+from dotguard.differ import diff
+from dotguard.models import EnvFile, Issue, Severity
+from dotguard.parser import ParseError, parse_file
+from dotguard.report import FORMATS, render
+from dotguard.secrets import SENSITIVE_NAME, scan
+from dotguard.types import VALIDATORS
+
+EXIT_OK = 0
+EXIT_PROBLEMS = 1
+EXIT_USAGE = 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dotguard",
+        description="Validate .env files against a documented .env.example.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    sub.required = True
+
+    def add_output_options(p: argparse.ArgumentParser) -> None:
+        p.add_argument("--format", choices=FORMATS, default="text", help="output format (default: text)")
+        p.add_argument(
+            "--fail-on-warning",
+            action="store_true",
+            help="exit with status 1 on warnings too, not only on errors",
+        )
+
+    p_check = sub.add_parser("check", help="check a .env file against .env.example")
+    p_check.add_argument("--env", default=".env", help="file to check (default: .env)")
+    p_check.add_argument(
+        "--example", default=".env.example", help="documented reference file (default: .env.example)"
+    )
+    p_check.add_argument(
+        "--strict", action="store_true", help="treat keys missing from the example as errors"
+    )
+    add_output_options(p_check)
+
+    p_scan = sub.add_parser("scan", help="look for real secrets in files you commit")
+    p_scan.add_argument(
+        "files", nargs="*", default=[".env.example"], help="files to scan (default: .env.example)"
+    )
+    add_output_options(p_scan)
+
+    p_diff = sub.add_parser("diff", help="compare the keys of two env files, e.g. staging and production")
+    p_diff.add_argument("left", help="first file, e.g. .env.staging")
+    p_diff.add_argument("right", help="second file, e.g. .env.production")
+    p_diff.add_argument(
+        "--values",
+        action="store_true",
+        help="also report keys whose values differ (values themselves are never printed)",
+    )
+    add_output_options(p_diff)
+
+    p_init = sub.add_parser("init", help="create .env.example from an existing .env")
+    p_init.add_argument("--env", default=".env", help="source file (default: .env)")
+    p_init.add_argument("--output", default=".env.example", help="file to write (default: .env.example)")
+    p_init.add_argument(
+        "--keep-values",
+        action="store_true",
+        help="keep non-sensitive values as defaults instead of blanking every value",
+    )
+    p_init.add_argument("--force", action="store_true", help="overwrite the output file if it exists")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "check":
+            return _cmd_check(args)
+        if args.command == "scan":
+            return _cmd_scan(args)
+        if args.command == "diff":
+            return _cmd_diff(args)
+        return _cmd_init(args)
+    except ParseError as exc:
+        print(f"dotguard: parse error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    except FileNotFoundError as exc:
+        print(f"dotguard: file not found: {exc.filename}", file=sys.stderr)
+        return EXIT_USAGE
+
+
+def _exit_code(issues: list[Issue], fail_on_warning: bool) -> int:
+    if any(i.severity is Severity.ERROR for i in issues):
+        return EXIT_PROBLEMS
+    if fail_on_warning and issues:
+        return EXIT_PROBLEMS
+    return EXIT_OK
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    issues = check(parse_file(args.env), parse_file(args.example), strict=args.strict)
+    render(issues, args.format)
+    return _exit_code(issues, args.fail_on_warning)
+
+
+def _cmd_scan(args: argparse.Namespace) -> int:
+    issues: list[Issue] = []
+    for path in args.files:
+        issues.extend(scan(parse_file(path)))
+    render(issues, args.format)
+    return _exit_code(issues, args.fail_on_warning)
+
+
+def _cmd_diff(args: argparse.Namespace) -> int:
+    issues = diff(parse_file(args.left), parse_file(args.right), compare_values=args.values)
+    render(issues, args.format)
+    return _exit_code(issues, args.fail_on_warning)
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    if os.path.exists(args.output) and not args.force:
+        print(f"dotguard: {args.output} already exists (use --force to overwrite)", file=sys.stderr)
+        return EXIT_USAGE
+
+    source = parse_file(args.env)
+    with open(args.output, "w", encoding="utf-8") as handle:
+        handle.write(render_example(source, keep_values=args.keep_values))
+    print(f"wrote {args.output} with {len(source.entries)} key(s) from {args.env}")
+    return EXIT_OK
+
+
+def render_example(source: EnvFile, keep_values: bool = False) -> str:
+    """Turn a real .env into a shareable, annotated .env.example."""
+    lines = [
+        "# Generated by dotguard. Document each key, then commit this file.",
+        "# Annotations: @type @required @optional @pattern @values @min @max @secret @deprecated",
+        "",
+    ]
+    for entry in source.entries:
+        lines.extend(f"# {text}" for text in entry.doc)
+        for name, value in entry.annotations.items():
+            lines.append(f"# @{name} {value}".rstrip())
+
+        sensitive = bool(SENSITIVE_NAME.search(entry.key)) or "secret" in entry.annotations
+        if sensitive and "secret" not in entry.annotations:
+            lines.append("# @secret")
+        if "type" not in entry.annotations and entry.value:
+            guessed = _guess_type(entry.value)
+            if guessed != "string":
+                lines.append(f"# @type {guessed}")
+
+        value = entry.value if keep_values and not sensitive else ""
+        lines.append(f"{entry.key}={_quote(value)}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _guess_type(value: str) -> str:
+    if value.lower() in {"true", "false", "yes", "no", "on", "off"}:
+        return "bool"
+    for name in ("port", "int", "float", "url", "email"):
+        if VALIDATORS[name](value) is None:
+            return name
+    return "string"
+
+
+def _quote(value: str) -> str:
+    if value == "" or all(c.isalnum() or c in "-_./:@,+" for c in value):
+        return value
+    escaped = (
+        value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n").replace("$", "\\$")
+    )
+    return f'"{escaped}"'
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dotguard/differ.py

@@ -0,0 +1,59 @@
+"""Compare the keys of two environment files, e.g. staging and production."""
+
+from __future__ import annotations
+
+from dotguard.models import EnvFile, Issue, Severity
+
+
+def diff(left: EnvFile, right: EnvFile, compare_values: bool = False) -> list[Issue]:
+    """Report keys that exist in only one file.
+
+    With ``compare_values``, also report keys whose values differ. Values are
+    never included in the messages, so the output is safe to share.
+    """
+    issues: list[Issue] = []
+    right_keys = set(right.keys())
+    left_keys = set(left.keys())
+
+    for entry in left.entries:
+        if entry.key not in right_keys:
+            issues.append(
+                Issue(
+                    "DD001",
+                    f"{entry.key} is set in {left.path} but missing from {right.path}",
+                    Severity.ERROR,
+                    left.path,
+                    entry.line,
+                    entry.key,
+                )
+            )
+
+    for entry in right.entries:
+        if entry.key not in left_keys:
+            issues.append(
+                Issue(
+                    "DD002",
+                    f"{entry.key} is set in {right.path} but missing from {left.path}",
+                    Severity.ERROR,
+                    right.path,
+                    entry.line,
+                    entry.key,
+                )
+            )
+
+    if compare_values:
+        for entry in left.entries:
+            other = right.get(entry.key)
+            if other is not None and other.value != entry.value:
+                issues.append(
+                    Issue(
+                        "DD003",
+                        f"{entry.key} has a different value in {right.path}:{other.line}",
+                        Severity.WARNING,
+                        left.path,
+                        entry.line,
+                        entry.key,
+                    )
+                )
+
+    return issues

dotguard/models.py

@@ -0,0 +1,63 @@
+"""Data types shared across dotguard."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+
+
+class Severity(str, enum.Enum):
+    ERROR = "error"
+    WARNING = "warning"
+
+
+@dataclass
+class Entry:
+    """A single KEY=value assignment in a .env file."""
+
+    key: str
+    value: str
+    line: int
+    # Annotations come from "# @name value" comments directly above the key.
+    annotations: dict[str, str] = field(default_factory=dict)
+    # Plain comment lines above the key, used as human documentation.
+    doc: list[str] = field(default_factory=list)
+    # Names referenced as $NAME / ${NAME} that were not defined earlier.
+    unresolved: list[str] = field(default_factory=list)
+
+
+@dataclass
+class EnvFile:
+    path: str
+    entries: list[Entry] = field(default_factory=list)
+
+    def get(self, key: str) -> Entry | None:
+        for entry in self.entries:
+            if entry.key == key:
+                return entry
+        return None
+
+    def keys(self) -> list[str]:
+        return [entry.key for entry in self.entries]
+
+
+@dataclass
+class Issue:
+    """A problem found while checking or scanning a file."""
+
+    code: str
+    message: str
+    severity: Severity
+    path: str
+    line: int | None = None
+    key: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "severity": self.severity.value,
+            "path": self.path,
+            "line": self.line,
+            "key": self.key,
+        }