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

deploy_guard/frontend/python_cfg.py

@@ -0,0 +1,332 @@
+"""Build a control-flow graph from a Python function AST.
+
+Supported structurally: sequential statements, ``if`` / ``elif`` / ``else``,
+``while`` / ``for`` (with ``else``), ``with``, ``try`` / ``except`` / ``else``
+/ ``finally``, ``match`` / ``case``, ``return``, ``raise``, ``break``,
+``continue``.  Exceptions are modelled approximately: a ``try`` body is
+assumed able to raise into any of its handlers at any point.
+
+Anything not recognised is kept as an opaque statement in the current block,
+so flow stays sound even when a construct is not modelled precisely.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from deploy_guard.ir.cfg import CFG, BasicBlock, Edge, EdgeKind, Statement, Terminator
+from deploy_guard.ir.model import FunctionDef
+
+_MAX_SRC = 120
+
+_SIMPLE = (
+    ast.Assign, ast.AugAssign, ast.AnnAssign, ast.Expr, ast.Pass,
+    ast.Import, ast.ImportFrom, ast.Global, ast.Nonlocal, ast.Delete,
+    ast.Assert, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef,
+)
+
+
+def build_cfg(fn: FunctionDef) -> CFG:
+    node = fn.raw
+    if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        raise TypeError(f"{fn.qualname}: no Python AST attached (raw={type(node)!r})")
+    return _Builder(fn.qualname).build(node.body)
+
+
+def _src(node: ast.AST) -> str:
+    try:
+        text = ast.unparse(node)
+    except Exception:  # pragma: no cover
+        return f"<{type(node).__name__}>"
+    text = " ".join(text.split())
+    return text if len(text) <= _MAX_SRC else text[: _MAX_SRC - 1] + "…"
+
+
+class _Builder:
+    def __init__(self, qualname: str) -> None:
+        self.qualname = qualname
+        self.blocks: dict[int, BasicBlock] = {}
+        self._next = 0
+        self.entry_id = self._new("entry").id
+        self.exit_id = self._new("exit").id
+        self.loop_stack: list[tuple[int, int]] = []   # (header_id, exit_id)
+        self.exc_stack: list[list[int]] = []          # handler entry ids
+        self.notes: list[str] = []
+
+    # -- graph construction helpers ------------------------------------------
+
+    def _new(self, label: str = "") -> BasicBlock:
+        b = BasicBlock(id=self._next, label=label)
+        self.blocks[b.id] = b
+        self._next += 1
+        return b
+
+    def _stmt(self, block: BasicBlock, node: ast.AST, *, kind: str = "", src: str = "") -> None:
+        block.statements.append(
+            Statement(
+                node=node,
+                lineno=getattr(node, "lineno", 0) or 0,
+                kind=kind or type(node).__name__,
+                src=src or _src(node),
+            )
+        )
+
+    def _edge(
+        self,
+        src: BasicBlock,
+        target: int,
+        kind: EdgeKind = EdgeKind.SEQ,
+        *,
+        guard: ast.AST | None = None,
+        negated: bool = False,
+    ) -> None:
+        for e in src.succ:
+            if e.target == target and e.kind == kind and e.negated == negated:
+                return
+        src.succ.append(
+            Edge(
+                target=target,
+                kind=kind,
+                guard=guard,
+                guard_src=_src(guard) if guard is not None else None,
+                negated=negated,
+            )
+        )
+
+    # -- public entrypoint -------------------------------------------------
+
+    def build(self, body: list[ast.stmt]) -> CFG:
+        entry = self.blocks[self.entry_id]
+        tail = self._suite(body, entry)
+        if tail is not None:
+            tail.terminator = Terminator.IMPLICIT_RETURN
+            self._edge(tail, self.exit_id)
+        cfg = CFG(
+            func_qualname=self.qualname,
+            entry=self.entry_id,
+            exit=self.exit_id,
+            blocks=self.blocks,
+            notes=self.notes,
+        )
+        return cfg.finalize()
+
+    # -- suite / statement dispatch -------------------------------------------
+
+    def _suite(self, stmts: list[ast.stmt], block: BasicBlock | None) -> BasicBlock | None:
+        for stmt in stmts:
+            if block is None:
+                # Everything from here on is unreachable; keep it in a detached
+                # block so the dead-code detector can point at it.
+                block = self._new("unreachable")
+            block = self._stmt_dispatch(stmt, block)
+        return block
+
+    def _stmt_dispatch(self, stmt: ast.stmt, block: BasicBlock) -> BasicBlock | None:
+        method = getattr(self, f"_do_{type(stmt).__name__}", None)
+        if method is not None:
+            return method(stmt, block)
+        if isinstance(stmt, _SIMPLE):
+            self._stmt(block, stmt)
+            return block
+        # Unknown / unmodelled construct: keep it, stay sound.
+        self._stmt(block, stmt)
+        self.notes.append(f"unmodelled statement {type(stmt).__name__} at line {stmt.lineno}")
+        return block
+
+    # -- terminators -------------------------------------------------------
+
+    def _do_Return(self, stmt: ast.Return, block: BasicBlock) -> None:
+        self._stmt(block, stmt, kind="Return")
+        block.terminator = Terminator.RETURN
+        block.term_node = stmt
+        self._edge(block, self.exit_id)
+        return
+
+    def _do_Raise(self, stmt: ast.Raise, block: BasicBlock) -> None:
+        self._stmt(block, stmt, kind="Raise")
+        block.terminator = Terminator.RAISE
+        block.term_node = stmt
+        for handler_id in self._current_handlers():
+            self._edge(block, handler_id, EdgeKind.EXCEPTION)
+        return
+
+    def _do_Break(self, stmt: ast.Break, block: BasicBlock) -> None:
+        self._stmt(block, stmt, kind="Break")
+        block.terminator = Terminator.BREAK
+        if self.loop_stack:
+            self._edge(block, self.loop_stack[-1][1])
+        return
+
+    def _do_Continue(self, stmt: ast.Continue, block: BasicBlock) -> None:
+        self._stmt(block, stmt, kind="Continue")
+        block.terminator = Terminator.CONTINUE
+        if self.loop_stack:
+            self._edge(block, self.loop_stack[-1][0], EdgeKind.LOOP_BACK)
+        return
+
+    def _current_handlers(self) -> list[int]:
+        return self.exc_stack[-1] if self.exc_stack else []
+
+    # -- branches --------------------------------------------------------
+
+    def _do_If(self, stmt: ast.If, block: BasicBlock) -> BasicBlock | None:
+        self._stmt(block, stmt.test, kind="branch", src=f"if {_src(stmt.test)}")
+        join = self._new("if.join")
+        join_used = False
+
+        then_block = self._new("if.then")
+        self._edge(block, then_block.id, EdgeKind.TRUE, guard=stmt.test)
+        then_tail = self._suite(stmt.body, then_block)
+        if then_tail is not None:
+            self._edge(then_tail, join.id)
+            join_used = True
+
+        if stmt.orelse:
+            else_block = self._new("if.else")
+            self._edge(block, else_block.id, EdgeKind.FALSE, guard=stmt.test, negated=True)
+            else_tail = self._suite(stmt.orelse, else_block)
+            if else_tail is not None:
+                self._edge(else_tail, join.id)
+                join_used = True
+        else:
+            self._edge(block, join.id, EdgeKind.FALSE, guard=stmt.test, negated=True)
+            join_used = True
+
+        return join if join_used else None
+
+    def _do_Match(self, stmt: ast.Match, block: BasicBlock) -> BasicBlock | None:
+        self._stmt(block, stmt.subject, kind="match", src=f"match {_src(stmt.subject)}")
+        join = self._new("match.join")
+        join_used = False
+        has_catch_all = False
+
+        for case in stmt.cases:
+            case_block = self._new("match.case")
+            label = f"case {_src(case.pattern)}"
+            if case.guard is not None:
+                label += f" if {_src(case.guard)}"
+            self._edge(block, case_block.id, EdgeKind.MATCH, guard=case.pattern)
+            self._stmt(case_block, case.pattern, kind="case", src=label)
+            case_tail = self._suite(case.body, case_block)
+            if case_tail is not None:
+                self._edge(case_tail, join.id)
+                join_used = True
+            if (
+                isinstance(case.pattern, ast.MatchAs)
+                and case.pattern.pattern is None
+                and case.guard is None
+            ):
+                has_catch_all = True
+
+        if not has_catch_all:
+            self._edge(block, join.id)
+            join_used = True
+        return join if join_used else None
+
+    # -- loops ---------------------------------------------------------
+
+    def _do_While(self, stmt: ast.While, block: BasicBlock) -> BasicBlock | None:
+        return self._loop(stmt, block, header_src=f"while {_src(stmt.test)}", guard=stmt.test)
+
+    def _do_For(self, stmt: ast.For, block: BasicBlock) -> BasicBlock | None:
+        src = f"for {_src(stmt.target)} in {_src(stmt.iter)}"
+        return self._loop(stmt, block, header_src=src, guard=stmt.iter)
+
+    _do_AsyncFor = _do_For
+
+    def _loop(
+        self,
+        stmt: ast.While | ast.For | ast.AsyncFor,
+        block: BasicBlock,
+        *,
+        header_src: str,
+        guard: ast.AST,
+    ) -> BasicBlock | None:
+        header = self._new("loop.header")
+        self._stmt(header, guard, kind="loop", src=header_src)
+        self._edge(block, header.id)
+
+        exit_block = self._new("loop.exit")
+        body_block = self._new("loop.body")
+        # The loop guard is kept on the header statement for display, but it is
+        # not a per-path branch predicate the way an ``if`` test is, so the
+        # enter/exit edges carry no guard - they must not leak into path
+        # conditions as ``cond and not (cond)``.
+        self._edge(header, body_block.id, EdgeKind.TRUE)
+
+        false_target = exit_block.id
+        else_tail: BasicBlock | None = None
+        if stmt.orelse:
+            else_block = self._new("loop.else")
+            false_target = else_block.id
+            else_tail = self._suite(stmt.orelse, else_block)
+        self._edge(header, false_target, EdgeKind.FALSE)
+        if stmt.orelse and else_tail is not None:
+            self._edge(else_tail, exit_block.id)
+
+        self.loop_stack.append((header.id, exit_block.id))
+        body_tail = self._suite(stmt.body, body_block)
+        self.loop_stack.pop()
+        if body_tail is not None:
+            self._edge(body_tail, header.id, EdgeKind.LOOP_BACK)
+
+        return exit_block
+
+    # -- with / try --------------------------------------------------
+
+    def _do_With(self, stmt: ast.With, block: BasicBlock) -> BasicBlock | None:
+        items = ", ".join(_src(i.context_expr) for i in stmt.items)
+        self._stmt(block, stmt, kind="with", src=f"with {items}")
+        return self._suite(stmt.body, block)
+
+    _do_AsyncWith = _do_With
+
+    def _do_Try(self, stmt: ast.Try, block: BasicBlock) -> BasicBlock | None:
+        self._stmt(block, stmt, kind="try", src="try")
+        try_block = self._new("try.body")
+        self._edge(block, try_block.id)
+
+        handler_blocks = [self._new("try.handler") for _ in stmt.handlers]
+        for hb in handler_blocks:
+            self._edge(try_block, hb.id, EdgeKind.EXCEPTION)
+
+        self.exc_stack.append([hb.id for hb in handler_blocks])
+        try_tail = self._suite(stmt.body, try_block)
+        self.exc_stack.pop()
+
+        # ``else`` runs only when the try body completed without raising.
+        else_tail = try_tail
+        if stmt.orelse and try_tail is not None:
+            else_block = self._new("try.else")
+            self._edge(try_tail, else_block.id)
+            else_tail = self._suite(stmt.orelse, else_block)
+
+        handler_tails: list[BasicBlock | None] = []
+        for handler, hb in zip(stmt.handlers, handler_blocks):
+            type_src = _src(handler.type) if handler.type is not None else ""
+            name = f" as {handler.name}" if handler.name else ""
+            self._stmt(hb, handler, kind="except", src=f"except {type_src}{name}".rstrip())
+            handler_tails.append(self._suite(handler.body, hb))
+
+        sources = [t for t in ([else_tail, *handler_tails]) if t is not None]
+
+        if stmt.finalbody:
+            fin_block = self._new("try.finally")
+            self._stmt(fin_block, stmt, kind="finally", src="finally")
+            for s in sources:
+                self._edge(s, fin_block.id)
+            if not sources:
+                # ``finally`` still runs on the exception-propagation path.
+                self._edge(try_block, fin_block.id, EdgeKind.EXCEPTION)
+            return self._suite(stmt.finalbody, fin_block)
+
+        if not sources:
+            return None
+        if len(sources) == 1:
+            return sources[0]
+        join = self._new("try.join")
+        for s in sources:
+            self._edge(s, join.id)
+        return join
+
+    _do_TryStar = _do_Try

deploy_guard/frontend/python_frontend.py

@@ -0,0 +1,182 @@
+"""Lower Python source into the language-neutral IR.
+
+Captures module-level functions and classes with their methods.  Functions
+nested inside other functions are not lowered in M1 (noted per module); the
+CFG builder still handles them structurally when they appear inside a body.
+"""
+
+from __future__ import annotations
+
+import ast
+import warnings
+from pathlib import Path
+
+from deploy_guard.ir.model import (
+    ClassDef,
+    FunctionDef,
+    Module,
+    Parameter,
+    ParamKind,
+    Project,
+    SourceSpan,
+)
+
+_FUNC_NODES = (ast.FunctionDef, ast.AsyncFunctionDef)
+
+
+def lower_python(project: Project) -> Project:
+    """Fill in functions/classes/imports for every Python module in place."""
+    for module in project.modules:
+        if module.parse_error or module.path.suffix != ".py":
+            continue
+        _lower_module(module)
+    return project
+
+
+def _lower_module(module: Module) -> None:
+    # Parsing quietly captures SyntaxWarnings (invalid escape sequences,
+    # ``is`` with a literal, ...) so they become findings instead of noise on
+    # stderr.
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        try:
+            tree = ast.parse(module.source, filename=str(module.path))
+        except SyntaxError as exc:
+            module.parse_error = f"SyntaxError: {exc.msg} (line {exc.lineno})"
+            return
+    module.syntax_warnings = [
+        (getattr(w.message, "lineno", None) or w.lineno or 0, str(w.message))
+        for w in caught
+        if issubclass(w.category, SyntaxWarning)
+    ]
+
+    for node in tree.body:
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            module.imports.extend(_import_names(node))
+        elif isinstance(node, _FUNC_NODES):
+            module.functions.append(
+                _lower_function(node, module.path, prefix=module.dotted_name)
+            )
+        elif isinstance(node, ast.ClassDef):
+            module.classes.append(_lower_class(node, module.path, module.dotted_name))
+
+
+def _import_names(node: ast.Import | ast.ImportFrom) -> list[str]:
+    if isinstance(node, ast.Import):
+        return [alias.name for alias in node.names]
+    if node.module and node.level == 0:
+        return [node.module]
+    return []
+
+
+def _lower_class(node: ast.ClassDef, file: Path, prefix: str) -> ClassDef:
+    qualname = f"{prefix}.{node.name}" if prefix else node.name
+    cls = ClassDef(
+        name=node.name,
+        qualname=qualname,
+        span=_span(node, file),
+        bases=[_unparse(b) for b in node.bases],
+        decorators=[_unparse(d) for d in node.decorator_list],
+        docstring=ast.get_docstring(node),
+    )
+    for child in node.body:
+        if isinstance(child, _FUNC_NODES):
+            cls.methods.append(
+                _lower_function(child, file, prefix=qualname, is_method=True)
+            )
+    return cls
+
+
+def _lower_function(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+    file: Path,
+    *,
+    prefix: str,
+    is_method: bool = False,
+) -> FunctionDef:
+    qualname = f"{prefix}.{node.name}" if prefix else node.name
+    return FunctionDef(
+        name=node.name,
+        qualname=qualname,
+        span=_span(node, file),
+        params=_params(node.args),
+        returns=_unparse(node.returns) if node.returns is not None else None,
+        decorators=[_unparse(d) for d in node.decorator_list],
+        docstring=ast.get_docstring(node),
+        is_async=isinstance(node, ast.AsyncFunctionDef),
+        is_method=is_method,
+        raw=node,
+    )
+
+
+def _params(args: ast.arguments) -> list[Parameter]:
+    out: list[Parameter] = []
+
+    positional = list(args.posonlyargs) + list(args.args)
+    # ``defaults`` covers the *last* len(defaults) positional params.
+    n_defaults = len(args.defaults)
+    first_with_default = len(positional) - n_defaults
+    posonly_count = len(args.posonlyargs)
+
+    for i, arg in enumerate(positional):
+        kind = (
+            ParamKind.POSITIONAL_ONLY
+            if i < posonly_count
+            else ParamKind.POSITIONAL_OR_KEYWORD
+        )
+        default = None
+        if i >= first_with_default:
+            default = _unparse(args.defaults[i - first_with_default])
+        out.append(Parameter(name=arg.arg, kind=kind, annotation=_ann(arg), default=default))
+
+    if args.vararg:
+        out.append(
+            Parameter(
+                name=args.vararg.arg,
+                kind=ParamKind.VAR_POSITIONAL,
+                annotation=_ann(args.vararg),
+            )
+        )
+
+    for arg, default_node in zip(args.kwonlyargs, args.kw_defaults):
+        out.append(
+            Parameter(
+                name=arg.arg,
+                kind=ParamKind.KEYWORD_ONLY,
+                annotation=_ann(arg),
+                default=_unparse(default_node) if default_node is not None else None,
+            )
+        )
+
+    if args.kwarg:
+        out.append(
+            Parameter(
+                name=args.kwarg.arg,
+                kind=ParamKind.VAR_KEYWORD,
+                annotation=_ann(args.kwarg),
+            )
+        )
+    return out
+
+
+def _ann(arg: ast.arg) -> str | None:
+    return _unparse(arg.annotation) if arg.annotation is not None else None
+
+
+def _span(node: ast.AST, file: Path) -> SourceSpan:
+    return SourceSpan(
+        file=file,
+        lineno=getattr(node, "lineno", 0) or 0,
+        end_lineno=getattr(node, "end_lineno", getattr(node, "lineno", 0)) or 0,
+        col=getattr(node, "col_offset", 0) or 0,
+        end_col=getattr(node, "end_col_offset", 0) or 0,
+    )
+
+
+def _unparse(node: ast.AST | None) -> str:
+    if node is None:
+        return ""
+    try:
+        return ast.unparse(node)
+    except Exception:  # pragma: no cover - unparse is robust on parsed trees
+        return "<expr>"

deploy_guard/generators/__init__.py

@@ -0,0 +1,11 @@
+"""Test generators: turn the analysis into runnable tests.
+
+M1 ships the import-smoke generator - the cheapest, highest-value check for
+"the deployment will not even start".  Characterization, property, endpoint,
+config and contract generators follow in later milestones.
+"""
+
+from deploy_guard.generators.base import GeneratedFile
+from deploy_guard.generators.import_smoke import generate_import_smoke
+
+__all__ = ["GeneratedFile", "generate_import_smoke"]

deploy_guard/generators/base.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class GeneratedFile:
+    """A generated test file, addressed relative to ``.deploy-guard/generated/``."""
+
+    relpath: str
+    content: str
+    kind: str = "test"

deploy_guard/generators/import_smoke.py

@@ -0,0 +1,94 @@
+"""Import-smoke generator.
+
+Emits a single pytest module that imports every discovered product module by
+its dotted name.  A broken import, a missing dependency, a module-level
+exception or a circular import all surface as a failing parametrised case -
+which is exactly the class of bug that takes a deployment down before it
+serves a request.
+
+The generated file is written to ``.deploy-guard/generated/`` and finds the
+project root by walking up to the ``.deploy-guard`` directory, so it stays
+correct no matter where pytest is invoked from or how deep the tree is.
+"""
+
+from __future__ import annotations
+
+import os
+
+from deploy_guard.generators.base import GeneratedFile
+from deploy_guard.ir.model import Project
+
+_TEMPLATE = '''\
+# ---------------------------------------------------------------------------
+# Generated by Deployment Guard Engine - import smoke test.
+# Do not edit by hand; re-run `deploy-guard scan --write-tests` to refresh.
+# ---------------------------------------------------------------------------
+import importlib
+import sys
+from pathlib import Path
+
+import pytest
+
+_HERE = Path(__file__).resolve()
+# .../<root>/.deploy-guard/generated/test_import_smoke.py  ->  <root>
+_PROJECT_ROOT = next(
+    (p.parent for p in _HERE.parents if p.name == ".deploy-guard"),
+    _HERE.parents[2],
+)
+_PACKAGE_ROOTS = {roots!r}
+for _rel in _PACKAGE_ROOTS:
+    _abs = str((_PROJECT_ROOT / _rel).resolve())
+    if _abs not in sys.path:
+        sys.path.insert(0, _abs)
+
+IMPORTABLE_MODULES = {modules!r}
+{broken_block}
+
+@pytest.mark.parametrize(
+    "module_name",
+    IMPORTABLE_MODULES
+    or [pytest.param(None, marks=pytest.mark.skip(reason="no modules discovered"))],
+)
+def test_module_imports_cleanly(module_name):
+    """Importing the module must not raise: no import errors, no crash at import time."""
+    importlib.import_module(module_name)
+'''
+
+_BROKEN_BLOCK = '''\
+UNPARSEABLE_MODULES = {broken!r}
+
+
+@pytest.mark.parametrize("module_name, error", UNPARSEABLE_MODULES)
+def test_module_parses(module_name, error):
+    """A module the engine cannot parse cannot be reasoned about or shipped safely."""
+    pytest.fail(f"{{module_name}}: {{error}}")
+'''
+
+
+def generate_import_smoke(project: Project) -> GeneratedFile:
+    roots = sorted({_rel_root(project, str(p)) for p in project.package_roots}) or ["."]
+
+    modules = sorted(
+        {m.dotted_name for m in project.modules if not m.parse_error and m.dotted_name}
+    )
+    broken = sorted(
+        (m.dotted_name or str(m.path), m.parse_error or "unknown parse error")
+        for m in project.modules
+        if m.parse_error
+    )
+
+    broken_block = _BROKEN_BLOCK.format(broken=broken) if broken else ""
+    content = _TEMPLATE.format(roots=roots, modules=modules, broken_block=broken_block)
+    return GeneratedFile(
+        relpath="test_import_smoke.py", content=content, kind="import-smoke"
+    )
+
+
+def _rel_root(project: Project, path: str) -> str:
+    try:
+        return os.path.relpath(path, project.root)
+    except ValueError:
+        return path
+
+
+__all__ = ["generate_import_smoke"]

deploy_guard/ingest/__init__.py

@@ -0,0 +1,5 @@
+"""Project ingestion: walk a directory and produce a :class:`Project` shell."""
+
+from deploy_guard.ingest.discover import discover
+
+__all__ = ["discover"]