deploy-guard-engine 0.1.0__tar.gz

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

@@ -0,0 +1,37 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check src
+      - run: pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

deploy_guard_engine-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: publish
+
+# Publishes to PyPI on a tagged release using Trusted Publishing (OIDC) -
+# no API token needed. Configure the publisher at
+# https://pypi.org/manage/project/deploy-guard/settings/publishing/
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

deploy_guard_engine-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+deploy_guard_env/
+deployguard_env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.idea/
+.vscode/
+.deploy-guard/cache/
+.deploy-guard/*.log

deploy_guard_engine-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - 2026-09-01
+
+First public release. Reworked from an internal prototype ("deployguard").
+
+### Added
+- **Interprocedural call graph** (`deploy_guard.analysis.callgraph`) - best-effort
+  resolution of intra-project calls by qualified name, bare name, and
+  `Class.method` suffix.
+- **Caller-aware `inconsistent-return`** - a value/None function is only `review`
+  when an in-project caller dereferences or returns the result without a guard;
+  otherwise it drops to a `note`. Kills the copy-pasted-helper false-positive
+  flood.
+- **Interprocedural nullability** - a call that resolves to a project function
+  which can return `None` now makes the result nullable, so
+  `x = compute(); x.attr` is flagged when `compute()` is a local function.
+- **`explain` walks the whole call chain** - every project frame in the
+  traceback is analysed, not just the deepest.
+- **Configuration file** - `[tool.deploy-guard]` in the scanned project's
+  `pyproject.toml` (Python 3.11+ for TOML reading). CLI flags override.
+- Packaging: `LICENSE` (MIT), trove classifiers, `dg` short alias, this
+  changelog, a standalone single-file build.
+
+### Changed
+- Renamed distribution to **`deploy-guard`** (import package `deploy_guard`);
+  `deployguard` was already taken on PyPI.
+- README leads with `explain`; `scan` is positioned as a supporting gate, with
+  a pointer to ruff + mypy for general linting.
+
+### Carried over from the prototype
+- Python frontend, CFG builder (`if`/`while`/`for`/`with`/`try`/`match` + async),
+  path enumeration -> behavior spec.
+- Flow-sensitive nullability with `is None` / truthiness / `isinstance` guards,
+  early-return guards, short-circuit narrowing in `and`/`or`/ternary, `.get()`
+  and `re.match/search` sources, `Optional[...]` params.
+- Findings: `none-dereference`, `swallowed-exception`, `unreachable-code`,
+  `bare-except`, `mutable-default-arg`, `invalid-escape`, `path-explosion`.
+- Import-smoke test generator.
+- `explain` traceback parser with dedicated handlers for AttributeError,
+  TypeError, KeyError, IndexError, ZeroDivisionError, UnboundLocalError,
+  NameError, ValueError; the "checks in the wrong order" special case.
+- Text / Markdown / JSON output, duplicate-finding collapse, `--disable`.
+
+### Known limitations
+- Python only (a Java frontend would reuse the analysis unchanged).
+- Call resolution is name-based, not full import resolution - ambiguous names
+  stay unresolved.
+- No Z3-backed concrete repro inputs yet.

deploy_guard_engine-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sai55387
+
+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.

deploy_guard_engine-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: deploy-guard-engine
+Version: 0.1.0
+Summary: Static root-cause analysis for a Python stack trace - offline, no account. Plus a deployment-gate scanner.
+Project-URL: Homepage, https://github.com/sai55387/deploy-guard
+Project-URL: Issues, https://github.com/sai55387/deploy-guard/issues
+Project-URL: Changelog, https://github.com/sai55387/deploy-guard/blob/main/CHANGELOG.md
+Author: sai55387
+License: MIT
+License-File: LICENSE
+Keywords: ci,control-flow,debugging,deployment,incident,nullability,root-cause,stacktrace,static-analysis,traceback
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Debuggers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# deploy-guard
+
+**Static root-cause analysis for a Python stack trace.** Paste a traceback,
+point it at the repo, and get: which variable is `None` and *why*, the branch
+path that reached the crash, where the bad value entered across the call
+chain, and a concrete fix. Fully local — no server, no account, no
+network. Zero dependencies. Python 3.10+.
+
+It also ships a deployment-gate scanner (`scan` / `check`), but for
+general-purpose linting you should run **[ruff](https://docs.astral.sh/ruff/)
++ [mypy](https://mypy-lang.org/)** — they are faster and deeper. What
+deploy-guard does that they don't is turn *a traceback you already have* into
+an explanation grounded in your code.
+
+## Install
+
+```bash
+pip install deploy-guard-engine   # or: pipx install deploy-guard-engine
+```
+
+Or run it with no install at all — a single ~120 KB file:
+
+```bash
+./scripts/build-standalone.sh     # -> dist/deploy-guard.pyz
+python deploy-guard.pyz explain --project ./service < traceback.txt
+```
+
+## Explain a traceback
+
+```bash
+deploy-guard explain --project ./service --file traceback.txt
+# or pipe it
+deploy-guard explain --project ./service < traceback.txt
+```
+
+```
+Explaining:  AttributeError: 'NoneType' object has no attribute 'empty'
+
+Crash site:  dg_financial_profile/financial_main.py:231  create_json
+             231 | if profile_df.empty or profile_df is None:
+
+Why:
+  - `profile_df` can be None here - the default passed to .get() is None.
+  - It reaches this line when: overall_financial_dict
+  - This line does check `profile_df is None`, but only after dereferencing it -
+    and/or evaluate left to right, so the attribute access raises first.
+
+Call chain (from the traceback):
+  multiprocessing_script:164  lambda_handler
+    └─ financial_main:231      create_json   <- raised
+
+Matches scan finding:  none-dereference (block) at financial_main.py:231
+
+Fix:  reorder the check so `profile_df is None` comes first.
+```
+
+Dedicated explanations for `AttributeError` / `TypeError` (None), `KeyError`,
+`IndexError`, `ZeroDivisionError`, `UnboundLocalError`, `NameError`, and
+`int()` / `float()` `ValueError`. Anything else falls back to the call chain
++ the branch conditions that reach the line. The call chain is analysed
+*interprocedurally* &mdash; each project frame is checked, and a `None` that
+originates in an argument is traced back to the caller that passed it.
+
+## Scan a project
+
+```bash
+deploy-guard scan  ./service                 # report, never fails
+deploy-guard scan  ./service --behavior      # + the when-X-returns-Y table
+deploy-guard check ./service --fail-on review  # gate: exit 1 on findings
+deploy-guard scan  ./service --report report.json
+```
+
+| Rule | Severity | Catches |
+|---|---|---|
+| `none-dereference` | block / review | attr/subscript on a possibly-`None` value (interprocedural: a call to a project function that can return `None` counts) |
+| `inconsistent-return` | review / note | returns a value on some paths, `None` on others &mdash; **review only when an in-project caller uses the result without a guard**, otherwise a note |
+| `swallowed-exception` | review | `except …: pass` |
+| `unreachable-code` | warn | code after an always-diverting branch |
+| `bare-except` | warn | `except:` with no type |
+| `mutable-default-arg` | warn | `def f(x=[])` |
+| `invalid-escape` | note | `"\d"` in a non-raw string |
+| `path-explosion` | note | too-branchy function (detection still complete) |
+
+Notes are collapsed to a one-line count; `--notes` lists them. Identical
+findings from copy-pasted functions fold into one; `--no-collapse` expands.
+
+## Configuration
+
+A `[tool.deploy-guard]` table in the **scanned project's** `pyproject.toml`
+(Python 3.11+ for TOML reading):
+
+```toml
+[tool.deploy-guard]
+disable = ["bare-except"]
+exclude = ["vendor", "migrations"]
+fail-on = "review"
+include-tests = false
+```
+
+CLI flags override the file.
+
+## How it works
+
+```
+discover -> lower to IR -> CFG per function -> call graph
+   -> behavior spec (path conditions -> returns/raises)
+   -> nullability data-flow (merges None facts at every branch join; interprocedural)
+   -> findings   |   explain (traceback -> the above, focused on one failure)
+```
+
+The nullability pass is a forward fixpoint over the CFG &mdash; it merges
+facts at branch joins, so it covers 100% of a function regardless of how
+branchy it is, in roughly linear time.
+
+`scan` and `explain` only **read** your code &mdash; never import or run it.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src
+```
+
+## What changed from the prototype
+
+See [CHANGELOG.md](CHANGELOG.md). Headline: an interprocedural call graph, so
+`explain` traces a `None` across frames and `inconsistent-return` no longer
+fires on copy-pasted helpers whose callers all guard the result; plus real
+packaging and a config file.

deploy_guard_engine-0.1.0/README.md

@@ -0,0 +1,130 @@
+# deploy-guard
+
+**Static root-cause analysis for a Python stack trace.** Paste a traceback,
+point it at the repo, and get: which variable is `None` and *why*, the branch
+path that reached the crash, where the bad value entered across the call
+chain, and a concrete fix. Fully local — no server, no account, no
+network. Zero dependencies. Python 3.10+.
+
+It also ships a deployment-gate scanner (`scan` / `check`), but for
+general-purpose linting you should run **[ruff](https://docs.astral.sh/ruff/)
++ [mypy](https://mypy-lang.org/)** — they are faster and deeper. What
+deploy-guard does that they don't is turn *a traceback you already have* into
+an explanation grounded in your code.
+
+## Install
+
+```bash
+pip install deploy-guard-engine   # or: pipx install deploy-guard-engine
+```
+
+Or run it with no install at all — a single ~120 KB file:
+
+```bash
+./scripts/build-standalone.sh     # -> dist/deploy-guard.pyz
+python deploy-guard.pyz explain --project ./service < traceback.txt
+```
+
+## Explain a traceback
+
+```bash
+deploy-guard explain --project ./service --file traceback.txt
+# or pipe it
+deploy-guard explain --project ./service < traceback.txt
+```
+
+```
+Explaining:  AttributeError: 'NoneType' object has no attribute 'empty'
+
+Crash site:  dg_financial_profile/financial_main.py:231  create_json
+             231 | if profile_df.empty or profile_df is None:
+
+Why:
+  - `profile_df` can be None here - the default passed to .get() is None.
+  - It reaches this line when: overall_financial_dict
+  - This line does check `profile_df is None`, but only after dereferencing it -
+    and/or evaluate left to right, so the attribute access raises first.
+
+Call chain (from the traceback):
+  multiprocessing_script:164  lambda_handler
+    └─ financial_main:231      create_json   <- raised
+
+Matches scan finding:  none-dereference (block) at financial_main.py:231
+
+Fix:  reorder the check so `profile_df is None` comes first.
+```
+
+Dedicated explanations for `AttributeError` / `TypeError` (None), `KeyError`,
+`IndexError`, `ZeroDivisionError`, `UnboundLocalError`, `NameError`, and
+`int()` / `float()` `ValueError`. Anything else falls back to the call chain
++ the branch conditions that reach the line. The call chain is analysed
+*interprocedurally* &mdash; each project frame is checked, and a `None` that
+originates in an argument is traced back to the caller that passed it.
+
+## Scan a project
+
+```bash
+deploy-guard scan  ./service                 # report, never fails
+deploy-guard scan  ./service --behavior      # + the when-X-returns-Y table
+deploy-guard check ./service --fail-on review  # gate: exit 1 on findings
+deploy-guard scan  ./service --report report.json
+```
+
+| Rule | Severity | Catches |
+|---|---|---|
+| `none-dereference` | block / review | attr/subscript on a possibly-`None` value (interprocedural: a call to a project function that can return `None` counts) |
+| `inconsistent-return` | review / note | returns a value on some paths, `None` on others &mdash; **review only when an in-project caller uses the result without a guard**, otherwise a note |
+| `swallowed-exception` | review | `except …: pass` |
+| `unreachable-code` | warn | code after an always-diverting branch |
+| `bare-except` | warn | `except:` with no type |
+| `mutable-default-arg` | warn | `def f(x=[])` |
+| `invalid-escape` | note | `"\d"` in a non-raw string |
+| `path-explosion` | note | too-branchy function (detection still complete) |
+
+Notes are collapsed to a one-line count; `--notes` lists them. Identical
+findings from copy-pasted functions fold into one; `--no-collapse` expands.
+
+## Configuration
+
+A `[tool.deploy-guard]` table in the **scanned project's** `pyproject.toml`
+(Python 3.11+ for TOML reading):
+
+```toml
+[tool.deploy-guard]
+disable = ["bare-except"]
+exclude = ["vendor", "migrations"]
+fail-on = "review"
+include-tests = false
+```
+
+CLI flags override the file.
+
+## How it works
+
+```
+discover -> lower to IR -> CFG per function -> call graph
+   -> behavior spec (path conditions -> returns/raises)
+   -> nullability data-flow (merges None facts at every branch join; interprocedural)
+   -> findings   |   explain (traceback -> the above, focused on one failure)
+```
+
+The nullability pass is a forward fixpoint over the CFG &mdash; it merges
+facts at branch joins, so it covers 100% of a function regardless of how
+branchy it is, in roughly linear time.
+
+`scan` and `explain` only **read** your code &mdash; never import or run it.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src
+```
+
+## What changed from the prototype
+
+See [CHANGELOG.md](CHANGELOG.md). Headline: an interprocedural call graph, so
+`explain` traces a `None` across frames and `inconsistent-return` no longer
+fires on copy-pasted helpers whose callers all guard the result; plus real
+packaging and a config file.