envgap 0.1.0__py3-none-any.whl

envgap/model/env_source.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class EnvVar:
+    key: str
+    value: str
+    path: Path
+    line: int
+    raw: str
+
+
+@dataclass
+class EnvFile:
+    path: Path
+    vars: list[EnvVar] = field(default_factory=list)
+    duplicates: dict[str, list[EnvVar]] = field(default_factory=dict)
+    parse_warnings: list[str] = field(default_factory=list)
+
+    @property
+    def values(self) -> dict[str, EnvVar]:
+        return {var.key: var for var in self.vars}
+
+    def contains(self, key: str) -> bool:
+        return key in self.values
+

envgap/model/expected_var.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CodeUsage:
+    key: str
+    path: Path
+    line: int
+    required: bool
+    source: str
+
+
+@dataclass
+class ExpectedVar:
+    key: str
+    documented_in: Path | None = None
+    code_usages: list[CodeUsage] = field(default_factory=list)
+
+    @property
+    def required(self) -> bool:
+        return any(usage.required for usage in self.code_usages)
+

envgap/model/finding.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class Severity(str, Enum):
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+@dataclass(frozen=True)
+class Finding:
+    code: str
+    severity: Severity
+    title: str
+    message: str
+    key: str | None = None
+    path: Path | None = None
+    line: int | None = None
+    suggestion: str | None = None
+    details: list[str] = field(default_factory=list)
+

envgap/reporters/__init__.py

@@ -0,0 +1,2 @@
+"""Render envgap check results."""
+

envgap/reporters/json.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from envgap.checker import CheckResult
+from envgap.model import Finding, Severity
+
+
+def render_json(result: CheckResult) -> str:
+    payload = {
+        "root": str(result.root),
+        "files": {
+            "env": _file_info(result.env_path),
+            "example": _file_info(result.example_path),
+        },
+        "shell": {
+            "checked": result.include_shell,
+            "expected_keys_found": sorted(key for key in result.expected_keys if key in result.shell_env),
+            "expected_keys_missing": sorted(key for key in result.expected_keys if key not in result.shell_env),
+        },
+        "summary": {
+            "findings": len(result.findings),
+            "errors": sum(1 for finding in result.findings if finding.severity == Severity.ERROR),
+            "warnings": sum(1 for finding in result.findings if finding.severity == Severity.WARNING),
+            "expected_keys": len(result.expected_keys),
+            "code_usages": len(result.code_usages),
+        },
+        "findings": [_finding_to_dict(finding, result.root) for finding in result.findings],
+        "code_usages": [
+            {
+                "key": usage.key,
+                "path": _relative(usage.path, result.root),
+                "line": usage.line,
+                "required": usage.required,
+                "source": usage.source,
+            }
+            for usage in result.code_usages
+        ],
+    }
+    return json.dumps(payload, indent=2, sort_keys=True)
+
+
+def _finding_to_dict(finding: Finding, root: Path) -> dict[str, Any]:
+    return {
+        "code": finding.code,
+        "severity": finding.severity.value,
+        "title": finding.title,
+        "message": finding.message,
+        "key": finding.key,
+        "path": _relative(finding.path, root) if finding.path else None,
+        "line": finding.line,
+        "suggestion": finding.suggestion,
+        "details": finding.details,
+    }
+
+
+def _file_info(path: Path) -> dict[str, Any]:
+    return {"path": str(path), "exists": path.exists()}
+
+
+def _relative(path: Path, root: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)

envgap/reporters/terminal.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from collections import Counter
+from pathlib import Path
+
+from envgap.checker import CheckResult
+from envgap.model import Finding, Severity
+
+ICONS = {
+    Severity.ERROR: "!",
+    Severity.WARNING: "~",
+    Severity.INFO: "i",
+}
+
+SEVERITY_ORDER = {
+    Severity.ERROR: 0,
+    Severity.WARNING: 1,
+    Severity.INFO: 2,
+}
+
+DIAGNOSIS_LABELS = {
+    "code_missing_from_example": "Code/documentation drift",
+    "duplicate_key": "Duplicate key",
+    "empty_value": "Empty value",
+    "missing_env_file": "Missing source",
+    "missing_example_file": "Missing source",
+    "missing_key": "Missing value",
+    "parse_warning": "Parse warning",
+    "placeholder_value": "Placeholder value",
+    "possible_typo": "Possible typo",
+    "undocumented_key": "Undocumented key",
+}
+
+
+def render_terminal(result: CheckResult, strict: bool = False) -> str:
+    lines: list[str] = []
+    counts = Counter(finding.severity for finding in result.findings)
+
+    lines.append("envgap check")
+    lines.append("=" * 15)
+    lines.append("")
+    lines.append(f"Project: {result.root}")
+    lines.append("Checked:")
+    lines.append(f"  shell environment: {_shell_summary(result)}")
+    lines.append(f"  .env: {_dotenv_summary(result.env_path, len(result.env_file.vars))}")
+    lines.append(f"  .env.example: {_dotenv_summary(result.example_path, len(result.example_file.vars))}")
+    lines.append(f"  Python code: {len(result.code_usages)} env usage(s)")
+    lines.append("")
+
+    if not result.findings:
+        lines.append("OK  No environment config issues found.")
+        lines.append(_exit_code_line(strict))
+        return "\n".join(lines)
+
+    lines.append(
+        "Summary: "
+        f"{counts[Severity.ERROR]} error(s), "
+        f"{counts[Severity.WARNING]} warning(s), "
+        f"{counts[Severity.INFO]} info"
+    )
+    lines.append("")
+    lines.append("Diagnosis:")
+
+    for group, findings in _group_findings(result.findings).items():
+        lines.append(f"  {group}")
+        for finding in sorted(findings, key=_finding_sort_key):
+            lines.extend(_format_finding(finding, result))
+        lines.append("")
+
+    lines.append(_exit_code_line(strict))
+    return "\n".join(lines).rstrip()
+
+
+def _format_finding(finding: Finding, result: CheckResult) -> list[str]:
+    icon = ICONS[finding.severity]
+    location = _location(finding, result.root)
+    label = DIAGNOSIS_LABELS.get(finding.code, finding.code.replace("_", " ").title())
+    lines = [f"    {icon} {label}: {finding.title}{location}", f"      {finding.message}"]
+    checked = [detail for detail in finding.details if _is_checked_detail(detail)]
+    usages = [detail for detail in finding.details if not _is_checked_detail(detail)]
+    if checked:
+        lines.append("      Checked:")
+        for detail in checked:
+            lines.append(f"        {detail}")
+    elif finding.key:
+        lines.extend(_checked_lines(finding.key, result))
+    for detail in usages:
+        lines.append(f"      Used at: {_relative_detail(detail, result.root)}")
+    if finding.suggestion:
+        lines.append(f"      Suggested fix: {finding.suggestion}")
+    return lines
+
+
+def _group_findings(findings: list[Finding]) -> dict[str, list[Finding]]:
+    groups: dict[str, list[Finding]] = defaultdict(list)
+    for finding in findings:
+        groups[finding.key or "Project setup"].append(finding)
+    return {
+        key: groups[key]
+        for key in sorted(groups, key=lambda value: (value != "Project setup", value))
+    }
+
+
+def _finding_sort_key(finding: Finding) -> tuple[int, str, int]:
+    return (SEVERITY_ORDER[finding.severity], finding.code, finding.line or 0)
+
+
+def _checked_lines(key: str, result: CheckResult) -> list[str]:
+    return [
+        "      Checked:",
+        f"        shell environment: {_shell_key_status(key, result)}",
+        f"        .env: {_env_file_status(key, result.env_path, result.env_file.values)}",
+        f"        .env.example: {_env_file_status(key, result.example_path, result.example_file.values)}",
+        f"        Python code: {_code_status(key, result)}",
+    ]
+
+
+def _is_checked_detail(detail: str) -> bool:
+    return detail.startswith(("shell environment:", ".env:", ".env.example:", "Python code:"))
+
+
+def _dotenv_summary(path: Path, count: int) -> str:
+    if not path.exists():
+        return "not found"
+    return f"found ({count} key(s))"
+
+
+def _shell_summary(result: CheckResult) -> str:
+    if not result.include_shell:
+        return "ignored (--no-shell)"
+    if not result.expected_keys:
+        return f"available ({len(result.shell_env)} variable(s))"
+    found = sum(1 for key in result.expected_keys if key in result.shell_env)
+    return f"available ({found}/{len(result.expected_keys)} expected key(s) found)"
+
+
+def _env_file_status(key: str, path: Path, values: dict) -> str:
+    if not path.exists():
+        return "file not found"
+    return "found" if key in values else "not found"
+
+
+def _shell_key_status(key: str, result: CheckResult) -> str:
+    if not result.include_shell:
+        return "ignored"
+    return "found" if key in result.shell_env else "not found"
+
+
+def _code_status(key: str, result: CheckResult) -> str:
+    usages = [usage for usage in result.code_usages if usage.key == key]
+    if not usages:
+        return "not found"
+    if any(usage.required for usage in usages):
+        return "required"
+    return "optional"
+
+
+def _exit_code_line(strict: bool) -> str:
+    if strict:
+        return "Exit code: 1 when errors or warnings are present (--strict/--ci), otherwise 0."
+    return "Exit code: 1 when errors are present, otherwise 0. Warnings do not fail unless --strict or --ci is used."
+
+
+def _location(finding: Finding, root: Path) -> str:
+    if not finding.path:
+        return ""
+    path = _relative(finding.path, root)
+    if finding.line:
+        return f" ({path}:{finding.line})"
+    return f" ({path})"
+
+
+def _relative(path: Path, root: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)
+
+
+def _relative_detail(detail: str, root: Path) -> str:
+    root_text = str(root)
+    return detail.replace(root_text + "/", "")

envgap-0.1.0.dist-info/METADATA

@@ -0,0 +1,319 @@
+Metadata-Version: 2.4
+Name: envgap
+Version: 0.1.0
+Summary: Find the gaps in your Python environment config.
+Project-URL: Homepage, https://github.com/Pinak-Datta/envgap
+Project-URL: Repository, https://github.com/Pinak-Datta/envgap
+Project-URL: Issues, https://github.com/Pinak-Datta/envgap/issues
+Project-URL: Changelog, https://github.com/Pinak-Datta/envgap/blob/main/CHANGELOG.md
+Author: envgap contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,configuration,diagnostics,dotenv,environment
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# envgap
+
+Find the gaps in your Python environment config.
+
+`envgap` is a diagnostic CLI for Python projects that use `.env` files, `.env.example`, shell variables, and `os.environ` / `os.getenv` in code. It does not load your config. It shows the gaps between what your app expects, what your project documents, and what your environment actually provides.
+
+![envgap terminal diagnosis screenshot](docs/assets/envgap-terminal.svg)
+
+## 30-Second Demo
+
+Given a project with:
+
+```dotenv
+# .env
+DB_URL=postgres://localhost/app
+OPENAI_API_KEY=changeme
+```
+
+```python
+# app.py
+import os
+
+DATABASE_URL = os.environ["DATABASE_URL"]
+```
+
+Run:
+
+```console
+$ DATABASE_URL=postgres://shell/app envgap check examples/basic
+
+envgap check
+===============
+
+Checked:
+  shell environment: available (1/4 expected key(s) found)
+  .env: found (3 key(s))
+  .env.example: found (3 key(s))
+  Python code: 3 env usage(s)
+
+Diagnosis:
+  DATABASE_URL
+    ! Missing value: DATABASE_URL is missing from .env (app.py:3)
+      It is present in your shell environment, so local commands may work while CI or Docker still fails.
+      Suggested fix: Add DATABASE_URL=... to .env or document how CI/Docker should provide it.
+
+  DB_URL
+    ~ Possible typo: DB_URL may be a typo for DATABASE_URL (.env:1)
+      Suggested fix: Rename DB_URL to DATABASE_URL if they represent the same setting.
+```
+
+## Why
+
+Environment config bugs are boring until they eat an afternoon.
+
+Common examples:
+
+- The app expects `DATABASE_URL`, but `.env` contains `DB_URL`.
+- `.env.example` says a key exists, but local `.env` never got it.
+- A secret is still set to `changeme`.
+- A variable works locally only because it is exported in your shell.
+- CI, Docker, or another developer's machine fails because the real required variables are not documented.
+
+`envgap` is for that moment when you want the project to explain itself.
+
+## Install
+
+```console
+pip install envgap
+```
+
+From a local checkout:
+
+```console
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+Run a check in the current project:
+
+```console
+envgap check
+```
+
+Try the included broken example:
+
+```console
+envgap check examples/basic
+```
+
+Show machine-readable output:
+
+```console
+envgap check --json
+```
+
+Ignore shell variables for deterministic CI checks:
+
+```console
+envgap check --no-shell
+```
+
+Fail on warnings as well as errors:
+
+```console
+envgap check --strict
+```
+
+`--ci` is supported as a CI-friendly alias for `--strict`:
+
+```console
+envgap check --ci
+```
+
+Use custom dotenv filenames:
+
+```console
+envgap check --env-file .env.local --example-file .env.example
+```
+
+## What It Checks Today
+
+`envgap check` currently inspects:
+
+- current shell environment
+- `.env`
+- `.env.example`
+- Python files using common environment variable APIs
+
+It detects:
+
+- missing keys
+- undocumented extra keys
+- duplicate keys
+- empty values
+- placeholder values like `your-key-here`, `changeme`, `todo`, and `replace-me`
+- likely typo pairs like `DB_URL` vs `DATABASE_URL`
+- required env vars used in Python code but missing from `.env.example`
+- missing `.env`
+- missing `.env.example`
+
+It scans Python code for:
+
+```python
+os.environ["DATABASE_URL"]
+os.getenv("DATABASE_URL")
+os.getenv("DATABASE_URL", "sqlite:///local.db")
+os.environ.get("DATABASE_URL", "sqlite:///local.db")
+```
+
+Required vs optional behavior:
+
+- `os.environ["KEY"]` is required
+- `os.getenv("KEY")` is required
+- `os.getenv("KEY", default)` is optional
+- `os.environ.get("KEY", default)` is optional
+
+## Exit Codes
+
+| Command | Exit code behavior |
+| --- | --- |
+| `envgap check` | exits `1` when errors are present |
+| `envgap check --strict` | exits `1` when errors or warnings are present |
+| `envgap check --ci` | same as `--strict` |
+| `envgap check --json` | same pass/fail behavior, JSON output |
+| `envgap check --no-shell` | ignores current shell variables when diagnosing missing keys |
+
+Warnings do not fail a normal check unless `--strict` or `--ci` is used.
+
+## CI
+
+```yaml
+name: envgap
+
+on: [push, pull_request]
+
+jobs:
+  envgap:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install envgap
+      - run: envgap check --ci
+```
+
+## Example Diagnosis
+
+Given:
+
+```dotenv
+# .env
+DB_URL=postgres://localhost/app
+OPENAI_API_KEY=changeme
+```
+
+```dotenv
+# .env.example
+DATABASE_URL=
+OPENAI_API_KEY=your-key-here
+```
+
+```python
+# app.py
+import os
+
+DATABASE_URL = os.environ["DATABASE_URL"]
+DEBUG = os.getenv("DEBUG", "false")
+```
+
+`envgap` can report:
+
+- `DATABASE_URL` is required in code but missing from `.env`
+- `DB_URL` may be a typo for `DATABASE_URL`
+- `OPENAI_API_KEY` still looks like a placeholder
+- `DEBUG` is optional because it has a default
+
+## Why Not Just python-dotenv?
+
+`python-dotenv` loads environment variables.
+
+`envgap` explains whether the environment variables your app expects match the variables your project defines and documents.
+
+The useful question is not only:
+
+> Did `.env` load?
+
+It is:
+
+> What does my app expect, where should it come from, and why is it missing or wrong here?
+
+## Current Scope
+
+This is intentionally a small diagnostic tool, not a config framework.
+
+In scope now:
+
+- `.env`
+- `.env.example`
+- shell environment
+- Python `os.environ` / `os.getenv` scanning
+- terminal and JSON reports
+- CI-friendly exit codes
+
+Not in scope yet:
+
+- loading or mutating your environment
+- validating every framework-specific settings pattern
+- Docker Compose parsing
+- GitHub Actions secrets parsing
+- Pydantic `BaseSettings` extraction
+
+## Roadmap
+
+- Pydantic `BaseSettings` support
+- Django settings helper detection
+- Docker Compose env detection
+- GitHub Actions env/secrets detection
+- precedence explanations for shell vs `.env` vs framework defaults
+- GitHub Actions annotations
+- richer JSON schema for editor and CI integrations
+
+## Development
+
+```console
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Run the example locally:
+
+```console
+envgap check examples/basic
+```
+
+Run the shell-aware example:
+
+```console
+DATABASE_URL=postgres://shell/app envgap check examples/basic
+```
+
+## License
+
+MIT

envgap-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+envgap/__init__.py,sha256=pGzI4Jg8YQnLWnSukTFYR0bAehgUoJ3ZqIjAEIcqMMI,77
+envgap/checker.py,sha256=gaKZuG4r8jMObbVfsu2XW7SuZQ0zDgivluP-vc_e2z8,14489
+envgap/cli.py,sha256=KmG7F3CWt5MFIbChOIWXEITJfJRVDp9rPakD5wGedm0,2592
+envgap/extractors/__init__.py,sha256=nACaqCNkydmDvzoE6-JVgRtnWrY3Zkch-8Mk2vET6ZI,77
+envgap/extractors/dotenv.py,sha256=5CEJA2X3NGkZCQ4mpU0I3_U20XLrOwZ9wsxF94IVJ9s,2132
+envgap/extractors/python_ast.py,sha256=utf8UOOpe8bQCd2LRFKrgpRDOCB8RBVXKXQHzjqgZi8,3381
+envgap/model/__init__.py,sha256=XR_3UlT31a1Q4Y2IdlIxew5xc_-2U4yOxMB9XhLpVBs,276
+envgap/model/env_source.py,sha256=B8JvXQteTjO0ij319BdBUIejxVC77qiunZAtWXufHw4,625
+envgap/model/expected_var.py,sha256=PnBdvCg06U6PhJtfc4ILbGVL92hggqPfwvM0jaY7L-I,481
+envgap/model/finding.py,sha256=vW3i5L7dnJs8DkDvUQCo06uN9H1zewnRojKHUOj6oL8,497
+envgap/reporters/__init__.py,sha256=my7j9pg8jRzUEUX8o7LOoqmGCPoANyMlhRufIoGG8HU,36
+envgap/reporters/json.py,sha256=4sl5YwrkheBCI9mjF5NooAmuXdBbaanJeEF8FM7kND4,2265
+envgap/reporters/terminal.py,sha256=2AhId3bAyS7R4WHwswo-U3M5DVjRjQY_sRtGcGGo0Kg,6220
+envgap-0.1.0.dist-info/METADATA,sha256=QUqKJz4Umd1R7gIX2RLYfMHeL8AJPyBR5ZrB58RMry8,7472
+envgap-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+envgap-0.1.0.dist-info/entry_points.txt,sha256=n3ti1tfkj0SoYffpqS6Yl1QjhUh8iEtnWalN7JAN0U4,43
+envgap-0.1.0.dist-info/licenses/LICENSE,sha256=czunO6Ct_QtfNBeUU5BNSUvz8lNkni5wzoWcJavSusM,1077
+envgap-0.1.0.dist-info/RECORD,,

envgap-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

envgap-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+envgap = envgap.cli:main