envgap 0.1.0__tar.gz

envgap-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,43 @@
+name: Bug report
+description: Report a bug in envgap.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for helping make envgap sharper.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Tell us what envgap did and what you expected instead.
+      placeholder: envgap reported X, but I expected Y.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction
+      description: Include the smallest `.env`, `.env.example`, and Python snippet that reproduces it.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: envgap output
+      description: Paste the relevant output. Please redact real secrets.
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: envgap version
+      placeholder: envgap --version
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: python --version
+

envgap-0.1.0/.github/ISSUE_TEMPLATE/false_positive.yml

@@ -0,0 +1,32 @@
+name: Config false positive
+description: Report a case where envgap warns incorrectly.
+title: "[False positive]: "
+labels: ["false-positive"]
+body:
+  - type: markdown
+    attributes:
+      value: False positives are especially useful for keeping envgap practical.
+  - type: textarea
+    id: finding
+    attributes:
+      label: Finding
+      description: Which envgap finding seems wrong?
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Why is it valid in your project?
+      description: Explain the framework pattern, default, alias, or deployment behavior envgap missed.
+    validations:
+      required: true
+  - type: textarea
+    id: minimal-example
+    attributes:
+      label: Minimal example
+      description: Include redacted config/code that reproduces the false positive.
+      render: shell
+    validations:
+      required: true
+

envgap-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: Feature request
+description: Suggest a new envgap capability.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What repeated config pain would this solve?
+      placeholder: I often hit this when...
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed behavior
+      description: What should envgap report or detect?
+    validations:
+      required: true
+  - type: textarea
+    id: example
+    attributes:
+      label: Example project shape
+      description: Include sample `.env`, code, Docker, CI, or framework config if relevant.
+      render: shell
+

envgap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest
+

envgap-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.coverage
+

envgap-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Initial MVP with `envgap check`.
+- Dotenv and `.env.example` parsing.
+- Python AST scanning for common `os.environ` and `os.getenv` usage.
+- Missing, duplicate, placeholder, undocumented, and possible-typo findings.
+- Terminal and JSON reporters.
+

envgap-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Thanks for helping improve envgap.
+
+envgap is intentionally a practical diagnostic tool, not a configuration framework. Good contributions make broken environment config easier to understand without adding surprising runtime behavior.
+
+## Setup
+
+```console
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Run Tests
+
+```console
+pytest
+```
+
+You can also run the sample broken project:
+
+```console
+envgap check examples/basic
+```
+
+## Good Issues
+
+The most useful reports include:
+
+- a small `.env`
+- a small `.env.example`
+- the Python code that reads environment variables
+- the envgap output
+- what you expected instead
+
+Please redact real API keys, tokens, passwords, and connection strings.
+
+## Scope
+
+In scope:
+
+- clearer diagnostics
+- fewer false positives
+- Python env usage detection
+- `.env` / `.env.example` drift detection
+- CI-friendly output
+- common framework support when it can be explained clearly
+
+Out of scope:
+
+- loading environment variables for the app
+- mutating your shell environment
+- becoming a general secrets manager
+- replacing framework settings systems
+
+## Pull Requests
+
+Before opening a PR:
+
+```console
+pytest
+```
+
+For user-facing behavior changes, add or update tests and include a short README or changelog update when useful.
+

envgap-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 envgap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

envgap-0.1.0/PKG-INFO

@@ -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