deploy-guard-engine 0.1.2__tar.gz → 0.1.4__tar.gz

deploy_guard_engine-0.1.4/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: deploy-guard-engine
+Version: 0.1.4
+Summary: Static root-cause analysis for a Python stack trace - offline, no account. Plus a deployment-gate scanner.
+Author: sai55387
+License: MIT
+Project-URL: Homepage, https://github.com/Dineshsai7/deploy-guard-engine
+Project-URL: Issues, https://github.com/Dineshsai7/deploy-guard-engine/issues
+Project-URL: Changelog, https://github.com/Dineshsai7/deploy-guard-engine/blob/main/CHANGELOG.md
+Keywords: traceback,stacktrace,root-cause,debugging,static-analysis,control-flow,nullability,deployment,ci,incident
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# 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:  project_folder/file_name.py:231 — create_json
+
+231 | if _df.empty or _df is None:
+
+Why:
+
+_df can be None because the default value passed to .get() is None.
+
+It reaches this line when processing report_dict.
+
+Although the condition checks _df is None, Python evaluates the or expression from left to right.
+
+Therefore, _df.empty is evaluated first. If _df is None, this raises an AttributeError before the None check is reached.
+
+Call chain (from the traceback):
+
+project_file:164 function_name
+└─ file_locator.py:231 create_json <- exception raised
+
+Scan finding:
+none-dereference (block) at file_locator.py:231
+
+Fix:
+Reorder the condition so _df is None is checked first:
+
+if _df is None or _df.empty:
+
+This ensures _df.empty is only accessed when _df is not None.
+```
+
+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
+```

deploy_guard_engine-0.1.4/README.md

@@ -0,0 +1,135 @@
+# 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:  project_folder/file_name.py:231 — create_json
+
+231 | if _df.empty or _df is None:
+
+Why:
+
+_df can be None because the default value passed to .get() is None.
+
+It reaches this line when processing report_dict.
+
+Although the condition checks _df is None, Python evaluates the or expression from left to right.
+
+Therefore, _df.empty is evaluated first. If _df is None, this raises an AttributeError before the None check is reached.
+
+Call chain (from the traceback):
+
+project_file:164 function_name
+└─ file_locator.py:231 create_json <- exception raised
+
+Scan finding:
+none-dereference (block) at file_locator.py:231
+
+Fix:
+Reorder the condition so _df is None is checked first:
+
+if _df is None or _df.empty:
+
+This ensures _df.empty is only accessed when _df is not None.
+```
+
+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
+```

{deploy_guard_engine-0.1.2 → deploy_guard_engine-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deploy-guard-engine"
-version = "0.1.2"
+version = "0.1.4"
 description = "Static root-cause analysis for a Python stack trace - offline, no account. Plus a deployment-gate scanner."
 readme = "README.md"
 requires-python = ">=3.10"

deploy_guard_engine-0.1.4/src/deploy_guard/__init__.py

@@ -0,0 +1,10 @@
+"""Deployment Guard Engine.
+
+A local engine that reads a Python or Java codebase, reasons about every
+branch and return path, and blocks a deploy when the logic says production
+would break.
+
+The public entrypoint is the ``deploy_guard`` CLI (see :mod:`deploy_guard.cli`).
+"""
+
+__version__ = "0.1.4"

deploy_guard_engine-0.1.4/src/deploy_guard/__main__.py

@@ -0,0 +1,4 @@
+from deploy_guard.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

deploy_guard_engine-0.1.4/src/deploy_guard/analysis/__init__.py

@@ -0,0 +1,39 @@
+"""Analysis passes over the shared IR / CFG.
+
+* ``paths``        - path enumeration -> behavior spec
+* ``nullability``  - flow-sensitive None analysis (merges at joins)
+* ``callgraph``    - best-effort intra-project call graph
+* ``context``      - whole-project context shared by the per-function passes
+* ``findings``     - the rules, mapped onto the deployment gate
+"""
+
+from deploy_guard.analysis.callgraph import CallGraph, CallSite, build_call_graph
+from deploy_guard.analysis.context import AnalysisContext
+from deploy_guard.analysis.findings import Finding, analyze_function
+from deploy_guard.analysis.nullability import NV, NullabilityAnalysis, NullFinding
+from deploy_guard.analysis.paths import (
+    BehaviorEntry,
+    BehaviorSpec,
+    ExecPath,
+    PathSet,
+    behavior_spec,
+    enumerate_paths,
+)
+
+__all__ = [
+    "Finding",
+    "analyze_function",
+    "NullabilityAnalysis",
+    "NullFinding",
+    "NV",
+    "CallGraph",
+    "CallSite",
+    "build_call_graph",
+    "AnalysisContext",
+    "ExecPath",
+    "PathSet",
+    "BehaviorEntry",
+    "BehaviorSpec",
+    "enumerate_paths",
+    "behavior_spec",
+]

deploy_guard_engine-0.1.4/src/deploy_guard/analysis/callgraph.py

@@ -0,0 +1,149 @@
+"""A best-effort intra-project call graph.
+
+Full import resolution is out of scope; instead every function is indexed by
+its qualified name, its bare name, and its ``Class.method`` suffix, and call
+sites are resolved against those indexes.  A call resolves when exactly one
+project function matches; otherwise it is kept as an unresolved name.
+
+Two things depend on this:
+
+* caller-aware ``inconsistent-return`` - only flag a value/None function when
+  a caller actually uses the result without a guard;
+* ``explain`` - analyse every project frame in a traceback and trace where a
+  ``None`` entered.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+from deploy_guard.ir.model import FunctionDef, Project
+
+
+@dataclass
+class CallSite:
+    caller: str                 # qualname of the enclosing function
+    callee_name: str            # the name as written (bare or dotted tail)
+    callee_qualname: str | None  # resolved project function, or None
+    node: ast.Call
+    lineno: int
+
+
+@dataclass
+class CallGraph:
+    functions: dict[str, FunctionDef] = field(default_factory=dict)
+    _by_bare: dict[str, list[str]] = field(default_factory=dict)
+    _by_method: dict[str, list[str]] = field(default_factory=dict)
+    call_sites: list[CallSite] = field(default_factory=list)
+    _callers: dict[str, list[CallSite]] = field(default_factory=dict)
+    _callees: dict[str, list[CallSite]] = field(default_factory=dict)
+
+    # -- lookups --------------------------------------------------------
+
+    def function(self, qualname: str) -> FunctionDef | None:
+        return self.functions.get(qualname)
+
+    def resolve(self, name: str) -> FunctionDef | None:
+        if name in self.functions:
+            return self.functions[name]
+        bare = name.rsplit(".", 1)[-1]
+        hits = self._by_bare.get(bare) or []
+        if len(hits) == 1:
+            return self.functions[hits[0]]
+        return None
+
+    def callers_of(self, qualname: str) -> list[CallSite]:
+        return list(self._callers.get(qualname, ()))
+
+    def callees_of(self, qualname: str) -> list[CallSite]:
+        return list(self._callees.get(qualname, ()))
+
+
+def build_call_graph(project: Project) -> CallGraph:
+    cg = CallGraph()
+
+    for _module, fn in project.iter_functions():
+        cg.functions[fn.qualname] = fn
+        bare = fn.name
+        cg._by_bare.setdefault(bare, []).append(fn.qualname)
+        if fn.is_method:
+            # Class.method  (drop the module prefix)
+            parts = fn.qualname.split(".")
+            if len(parts) >= 2:
+                cg._by_method.setdefault(".".join(parts[-2:]), []).append(fn.qualname)
+
+    for _module, fn in project.iter_functions():
+        if not isinstance(fn.raw, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        enclosing_class = _enclosing_class(fn.qualname)
+        for call in _iter_calls(fn.raw):
+            name = _callee_name(call.func)
+            if name is None:
+                continue
+            qn = _resolve_call(cg, name, call.func, enclosing_class)
+            site = CallSite(
+                caller=fn.qualname,
+                callee_name=name,
+                callee_qualname=qn,
+                node=call,
+                lineno=getattr(call, "lineno", fn.span.lineno),
+            )
+            cg.call_sites.append(site)
+            if qn is not None:
+                cg._callers.setdefault(qn, []).append(site)
+            cg._callees.setdefault(fn.qualname, []).append(site)
+
+    return cg
+
+
+# --------------------------------------------------------------------------
+
+def _iter_calls(node: ast.AST) -> Iterator[ast.Call]:
+    for sub in ast.walk(node):
+        if isinstance(sub, ast.Call):
+            yield sub
+
+
+def _callee_name(func: ast.AST) -> str | None:
+    if isinstance(func, ast.Name):
+        return func.id
+    if isinstance(func, ast.Attribute):
+        if isinstance(func.value, ast.Name):
+            return f"{func.value.id}.{func.attr}"
+        return func.attr
+    return None
+
+
+def _enclosing_class(qualname: str) -> str | None:
+    parts = qualname.split(".")
+    return parts[-2] if len(parts) >= 3 else None
+
+
+def _resolve_call(
+    cg: CallGraph, name: str, func: ast.AST, enclosing_class: str | None
+) -> str | None:
+    # self.method() / cls.method()
+    if (
+        isinstance(func, ast.Attribute)
+        and isinstance(func.value, ast.Name)
+        and func.value.id in ("self", "cls")
+        and enclosing_class
+    ):
+        key = f"{enclosing_class}.{func.attr}"
+        hits = cg._by_method.get(key) or []
+        if len(hits) == 1:
+            return hits[0]
+
+    # module.func()  or  obj.method()
+    tail = name.rsplit(".", 1)[-1]
+    hits = cg._by_bare.get(tail) or []
+    if len(hits) == 1:
+        return hits[0]
+    if len(hits) > 1 and "." in name:
+        prefix = name.rsplit(".", 1)[0]
+        narrowed = [q for q in hits if f".{prefix}." in f".{q}." or q.startswith(prefix + ".")]
+        if len(narrowed) == 1:
+            return narrowed[0]
+    return None

deploy_guard_engine-0.1.4/src/deploy_guard/analysis/context.py

@@ -0,0 +1,31 @@
+"""Whole-project context shared by the per-function analyses.
+
+Built once per scan, after every function's CFG and behavior spec exist, so
+that a single function's analysis can ask questions about the rest of the
+project (does this callee return None? who calls me and how?).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from deploy_guard.analysis.callgraph import CallGraph
+from deploy_guard.analysis.paths import BehaviorSpec
+
+
+@dataclass
+class AnalysisContext:
+    callgraph: CallGraph
+    specs: dict[str, BehaviorSpec] = field(default_factory=dict)
+    # qualnames of project functions that can return None on some path
+    returns_none: set[str] = field(default_factory=set)
+    # qualnames that return a non-None value on some path
+    returns_value: set[str] = field(default_factory=set)
+
+    def callee_can_be_none(self, name: str) -> str | None:
+        """If ``name`` resolves to a project function that can return None,
+        return that function's qualname; else None."""
+        fn = self.callgraph.resolve(name)
+        if fn is not None and fn.qualname in self.returns_none:
+            return fn.qualname
+        return None