deploy-guard-engine 0.1.0__py3-none-any.whl

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.0"

deploy_guard/__main__.py

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

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

deploy_guard/analysis/findings.py

@@ -0,0 +1,333 @@
+"""First-pass flow findings, derived from the CFG and the behavior spec.
+
+Every finding names a rule, a severity that maps onto the deployment gate
+(``block`` / ``review`` / ``warn``), and a source location.  M2 adds the
+data-flow findings (null deref, escaping exception) with concrete repros.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+from deploy_guard.analysis.nullability import NullabilityAnalysis
+from deploy_guard.analysis.paths import BehaviorSpec
+from deploy_guard.ir.cfg import CFG, Terminator
+from deploy_guard.ir.model import FunctionDef
+
+# block/review/warn feed the deployment gate; note is informational only and
+# is never a gate input - it is shown in a separate, quiet section.
+SEVERITIES = ("block", "review", "warn", "note")
+
+
+@dataclass
+class Finding:
+    rule: str
+    severity: str
+    message: str
+    qualname: str
+    file: str
+    lineno: int
+    detail: str = ""
+    # Identifies findings that are "the same finding in a copy-pasted function"
+    # so the report can collapse them. Set by the engine.
+    group_key: str = ""
+
+    def __post_init__(self) -> None:
+        if self.severity not in SEVERITIES:
+            raise ValueError(f"bad severity {self.severity!r}")
+
+    @property
+    def location(self) -> str:
+        return f"{self.file}:{self.lineno}"
+
+
+_MUTABLE_DEFAULT_CALLS = {"list", "dict", "set", "bytearray"}
+
+
+def _return_shape(cfg: CFG) -> tuple[bool, bool, set[int]]:
+    """(has explicit `return <non-None>`, has a None-valued exit, exit line nos).
+
+    Computed over reachable blocks only, straight from block terminators - no
+    path enumeration, so it is unaffected by the path-explosion cap.
+    """
+    reachable = cfg.reachable_ids()
+    has_value_return = False
+    has_none_exit = False
+    none_exit_lines: set[int] = set()
+    for bid in reachable:
+        block = cfg.blocks[bid]
+        if block.terminator == Terminator.RETURN:
+            value = getattr(block.term_node, "value", None)
+            is_none = value is None or (
+                isinstance(value, ast.Constant) and value.value is None
+            )
+            if is_none:
+                has_none_exit = True
+                none_exit_lines.add(getattr(block.term_node, "lineno", 0) or 0)
+            else:
+                has_value_return = True
+        elif block.terminator == Terminator.IMPLICIT_RETURN:
+            has_none_exit = True
+            line = block.first_line or 0
+            if line:
+                none_exit_lines.add(line)
+    return has_value_return, has_none_exit, {ln for ln in none_exit_lines if ln}
+
+
+def _inconsistent_return_severity(fn, ctx) -> tuple[str | None, str]:
+    """Decide how loud an inconsistent-return should be, using callers.
+
+    review  - at least one in-project caller uses the result without a guard
+    note    - every caller discards or guards it, or nothing calls it
+    None    - suppress (should not happen here)
+    """
+    if ctx is None:
+        return "review", ""
+
+    callers = ctx.callgraph.callers_of(fn.qualname)
+    if not callers:
+        return (
+            "note",
+            "  [no in-project caller uses this result - dead, or called dynamically]",
+        )
+
+    unguarded: list[str] = []
+    for site in callers:
+        caller_fn = ctx.callgraph.function(site.caller)
+        if caller_fn is None:
+            continue
+        usage = _classify_call_usage(caller_fn, site.node)
+        if usage in ("deref", "return"):
+            unguarded.append(f"{site.caller.rsplit('.', 1)[-1]}:{site.lineno}")
+
+    if unguarded:
+        shown = ", ".join(sorted(set(unguarded))[:5])
+        return "review", f"  [used without a guard by: {shown}]"
+    return (
+        "note",
+        "  [every caller checks the result or discards it - likely intentional]",
+    )
+
+
+def _classify_call_usage(caller_fn, call_node: ast.Call) -> str:
+    root = caller_fn.raw
+    if not isinstance(root, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return "unknown"
+    parent = None
+    for node in ast.walk(root):
+        for child in ast.iter_child_nodes(node):
+            if child is call_node:
+                parent = node
+                break
+        if parent is not None:
+            break
+    if parent is None:
+        return "unknown"
+
+    if isinstance(parent, (ast.Attribute, ast.Subscript)) and parent.value is call_node:
+        return "deref"
+    if isinstance(parent, ast.Return):
+        return "return"
+    if isinstance(parent, ast.Expr):
+        return "discard"
+    if isinstance(parent, ast.BoolOp):
+        return "guard"  # `call() or default`, `call() and ...`
+    if isinstance(parent, ast.Assign):
+        targets = [t.id for t in parent.targets if isinstance(t, ast.Name)]
+        if not targets:
+            return "assign"
+        name = targets[0]
+        src = ast.unparse(root)
+        deref = f"{name}." in src or f"{name}[" in src
+        guarded = (
+            f"if {name}" in src
+            or f"{name} is None" in src
+            or f"{name} is not None" in src
+            or f"not {name}" in src
+        )
+        if deref and not guarded:
+            return "deref"
+        if guarded:
+            return "guard"
+        return "assign"
+    return "unknown"
+
+
+def _declares_optional(returns: str | None) -> bool:
+    """True when the return annotation admits None on purpose."""
+    if not returns:
+        return False
+    text = returns.replace(" ", "")
+    return (
+        "Optional[" in text
+        or "|None" in text
+        or "None|" in text
+        or text == "None"
+        or "Union[" in text and "None" in text
+    )
+
+
+def analyze_function(
+    fn: FunctionDef, cfg: CFG, spec: BehaviorSpec, ctx=None
+) -> list[Finding]:
+    file = str(fn.span.file)
+    findings: list[Finding] = []
+
+    def add(rule: str, severity: str, message: str, lineno: int, detail: str = "") -> None:
+        findings.append(
+            Finding(
+                rule=rule,
+                severity=severity,
+                message=message,
+                qualname=fn.qualname,
+                file=file,
+                lineno=lineno,
+                detail=detail,
+            )
+        )
+
+    # 1. inconsistent return (computed from the CFG, so it scales past the
+    #    path-enumeration cap). A declared Optional/None-union return means
+    #    None is intended - skip those.
+    if not _declares_optional(fn.returns):
+        value_return, none_exit, none_exit_lines = _return_shape(cfg)
+        if value_return and none_exit:
+            where = (
+                f"None-returning path(s) end near line(s) {sorted(none_exit_lines)}"
+                if none_exit_lines
+                else "one path falls off the end of the function"
+            )
+            severity, caller_note = _inconsistent_return_severity(fn, ctx)
+            if severity is not None:
+                add(
+                    "inconsistent-return",
+                    severity,
+                    "returns a value on some paths but None on others - callers "
+                    "that use the result hit AttributeError/TypeError on the None path",
+                    fn.span.lineno,
+                    detail=(where + caller_note),
+                )
+
+    # 1b. None-dereference (flow-sensitive nullability) ------------------
+    for nf in NullabilityAnalysis(fn, cfg, ctx).find_none_derefs():
+        when = (
+            "reached when " + " and ".join(nf.witness)
+            if nf.witness
+            else "on the straight-line path - no branch guards this access"
+        )
+        if nf.definite:
+            add(
+                "none-dereference",
+                "block",
+                f"`{nf.var}` is None here - this access raises "
+                "AttributeError/TypeError when the line runs",
+                nf.lineno,
+                detail=when,
+            )
+        else:
+            add(
+                "none-dereference",
+                "review",
+                f"`{nf.var}` can be None here ({nf.reason}) and is dereferenced "
+                "without a guard",
+                nf.lineno,
+                detail=when,
+            )
+
+    # 2. unreachable code -------------------------------------------------
+    for block in cfg.unreachable_blocks():
+        line = block.first_line or fn.span.lineno
+        add(
+            "unreachable-code",
+            "warn",
+            "statements here can never execute - a preceding branch always "
+            "returns, raises, breaks or continues",
+            line,
+        )
+
+    # 3. path explosion (informational note, not a finding) --------------
+    if spec.truncated:
+        add(
+            "path-explosion",
+            "note",
+            "very branchy function - the per-path behavior table is capped "
+            "(bug detection is unaffected); consider splitting it up",
+            fn.span.lineno,
+        )
+
+    # 4/5. exception-handler smells + 6. mutable defaults ----------------
+    node = fn.raw
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        _handler_findings(node, add)
+        _mutable_default_findings(node, add)
+
+    return findings
+
+
+def _handler_findings(node: ast.AST, add) -> None:
+    for handler in ast.walk(node):
+        if not isinstance(handler, ast.ExceptHandler):
+            continue
+        body = [s for s in handler.body if not _is_docstring(s)]
+        only_pass = len(body) == 1 and isinstance(body[0], ast.Pass)
+        only_ellipsis = (
+            len(body) == 1
+            and isinstance(body[0], ast.Expr)
+            and isinstance(body[0].value, ast.Constant)
+            and body[0].value.value is Ellipsis
+        )
+        has_reraise = any(
+            isinstance(s, ast.Raise) for s in ast.walk(handler)
+        )
+
+        if handler.type is None:
+            add(
+                "bare-except",
+                "warn",
+                "bare `except:` also swallows KeyboardInterrupt and SystemExit; "
+                "catch a specific exception type",
+                handler.lineno,
+            )
+
+        if (only_pass or only_ellipsis) and not has_reraise:
+            caught = ast.unparse(handler.type) if handler.type is not None else "everything"
+            add(
+                "swallowed-exception",
+                "review",
+                f"exception ({caught}) is caught and silently discarded - a real "
+                "failure here becomes invisible in production",
+                handler.lineno,
+            )
+
+
+def _mutable_default_findings(node: ast.FunctionDef | ast.AsyncFunctionDef, add) -> None:
+    args = node.args
+    defaults = list(args.defaults) + [d for d in args.kw_defaults if d is not None]
+    for default in defaults:
+        label = _mutable_default_label(default)
+        if label is not None:
+            add(
+                "mutable-default-arg",
+                "warn",
+                f"default argument {label} is created once and shared across every "
+                "call - mutating it leaks state between calls",
+                getattr(default, "lineno", node.lineno),
+            )
+
+
+def _mutable_default_label(node: ast.expr) -> str | None:
+    if isinstance(node, (ast.List, ast.Dict, ast.Set)):
+        return {ast.List: "[]", ast.Dict: "{}", ast.Set: "set literal"}[type(node)]
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+        if node.func.id in _MUTABLE_DEFAULT_CALLS and not node.args and not node.keywords:
+            return f"{node.func.id}()"
+    return None
+
+
+def _is_docstring(stmt: ast.stmt) -> bool:
+    return (
+        isinstance(stmt, ast.Expr)
+        and isinstance(stmt.value, ast.Constant)
+        and isinstance(stmt.value.value, str)
+    )