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

deploy_guard/cli.py

@@ -0,0 +1,190 @@
+"""``deploy-guard`` command-line interface.
+
+    deploy-guard scan    [path]   analyse a tree, report findings + behavior spec
+    deploy-guard check   [path]   same, but exit non-zero on gate-blocking findings
+    deploy-guard explain          explain a pasted traceback using the analysis
+    deploy-guard version
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from deploy_guard import __version__
+from deploy_guard.analysis.paths import DEFAULT_LIMIT, DEFAULT_UNROLL
+from deploy_guard.config import load_config
+from deploy_guard.engine import scan
+from deploy_guard.explain import explain_traceback, parse_traceback, render_explanation
+from deploy_guard.frontend import lower_python
+from deploy_guard.ingest import discover
+from deploy_guard.report import render_json, render_markdown, render_text
+from deploy_guard.store import write_generated
+
+_FAIL_ON_CHOICES = ("block", "review", "warn", "none")
+_EXIT_OK = 0
+_EXIT_FINDINGS = 1
+_EXIT_USAGE = 2
+
+
+def _add_common(sp: argparse.ArgumentParser) -> None:
+    sp.add_argument("path", nargs="?", default=".", help="directory to scan (default: .)")
+    sp.add_argument("--include-tests", action="store_true", help="analyse test files too")
+    sp.add_argument("--path-limit", type=int, default=DEFAULT_LIMIT,
+                    help=f"max paths per function (default: {DEFAULT_LIMIT})")
+    sp.add_argument("--unroll", type=int, default=DEFAULT_UNROLL,
+                    help=f"max visits to a block on one path (default: {DEFAULT_UNROLL})")
+    sp.add_argument("--format", choices=("text", "markdown", "json"), default="text")
+    sp.add_argument("--behavior", action="store_true",
+                    help="include the per-function behavior spec (text format)")
+    sp.add_argument("--notes", action="store_true",
+                    help="list informational notes (e.g. path-explosion) instead of just counting them")
+    sp.add_argument("--disable", metavar="RULES", default="",
+                    help="comma-separated rule names to suppress, e.g. --disable path-explosion,bare-except")
+    sp.add_argument("--no-collapse", action="store_true",
+                    help="do not fold duplicate findings from copy-pasted functions")
+    sp.add_argument("--write-tests", action="store_true",
+                    help="write generated tests into .deploy-guard/generated/")
+    sp.add_argument("--report", metavar="FILE",
+                    help="also write the report (markdown or json by extension) to FILE")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="deploy-guard", description=__doc__)
+    parser.add_argument("--version", action="version", version=f"deploy-guard {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    p_scan = sub.add_parser("scan", help="analyse and report (never fails the build)")
+    _add_common(p_scan)
+    p_scan.add_argument("--fail-on", choices=_FAIL_ON_CHOICES, default=None)
+
+    p_check = sub.add_parser("check", help="deployment gate - exit non-zero on blockers")
+    _add_common(p_check)
+    p_check.add_argument("--fail-on", choices=_FAIL_ON_CHOICES, default=None)
+
+    p_explain = sub.add_parser(
+        "explain",
+        help="explain a pasted traceback using the project's analysis",
+    )
+    p_explain.add_argument("--project", default=".", help="project root (default: .)")
+    p_explain.add_argument(
+        "--file", metavar="FILE", help="read the traceback from FILE instead of stdin"
+    )
+
+    sub.add_parser("version", help="print version")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command in (None, "version"):
+        if args.command is None:
+            parser.print_help()
+            return _EXIT_USAGE
+        print(f"deploy-guard {__version__}")
+        return _EXIT_OK
+
+    if args.command == "explain":
+        return _run_explain(args)
+
+    root = Path(args.path).resolve()
+    if not root.is_dir():
+        print(f"deploy-guard: not a directory: {root}", file=sys.stderr)
+        return _EXIT_USAGE
+
+    cli_disable = {r.strip() for r in args.disable.split(",") if r.strip()}
+    cfg = load_config(root).merged_with_cli(
+        disable=cli_disable,
+        fail_on=args.fail_on,                       # None unless passed on the CLI
+        include_tests=True if args.include_tests else None,
+    )
+    subcommand_default = "block" if args.command == "check" else "none"
+    effective_fail_on = cfg.fail_on or subcommand_default
+
+    if cfg.source is not None:
+        print(f"(config: {cfg.source})")
+    result = scan(
+        root,
+        include_tests=bool(cfg.include_tests),
+        path_limit=args.path_limit,
+        unroll=args.unroll,
+        disable=cfg.disable,
+        exclude=cfg.exclude,
+    )
+    result.collapse = not args.no_collapse
+
+    if args.format == "json":
+        rendered = render_json(result)
+    elif args.format == "markdown":
+        rendered = render_markdown(result)
+    else:
+        rendered = render_text(
+            result, show_behavior=args.behavior, show_notes=args.notes
+        )
+    print(rendered)
+
+    if args.report:
+        report_path = Path(args.report)
+        text = render_json(result) if report_path.suffix == ".json" else render_markdown(result)
+        report_path.write_text(text, encoding="utf-8")
+        print(f"report written to {report_path}")
+
+    if args.write_tests and result.generated:
+        written = write_generated(root, result.generated)
+        for w in written:
+            print(f"wrote {w}")
+
+    if args.command == "check":
+        print()
+        print("note: check scans the whole tree; diff-scoped gating is on the roadmap.")
+
+    if effective_fail_on != "none":
+        blockers = result.findings_at_or_above(effective_fail_on)
+        if blockers:
+            print(
+                f"\n{len(blockers)} finding(s) at or above '{effective_fail_on}' - "
+                "deployment gate: FAIL",
+                file=sys.stderr,
+            )
+            return _EXIT_FINDINGS
+
+    return _EXIT_OK
+
+
+def _run_explain(args: argparse.Namespace) -> int:
+    project_root = Path(args.project).resolve()
+    if not project_root.is_dir():
+        print(f"deploy-guard: not a directory: {project_root}", file=sys.stderr)
+        return _EXIT_USAGE
+
+    if args.file:
+        text = Path(args.file).read_text(encoding="utf-8", errors="replace")
+    elif not sys.stdin.isatty():
+        text = sys.stdin.read()
+    else:
+        print(
+            "deploy-guard explain: paste a traceback on stdin, or use --file FILE\n"
+            "  e.g.  deploy-guard explain --project . < traceback.txt",
+            file=sys.stderr,
+        )
+        return _EXIT_USAGE
+
+    if not text.strip():
+        print("deploy-guard explain: no traceback text provided", file=sys.stderr)
+        return _EXIT_USAGE
+
+    cfg = load_config(project_root)
+    project = lower_python(
+        discover(project_root, include_tests=bool(cfg.include_tests), extra_exclude=cfg.exclude)
+    )
+    tb = parse_traceback(text)
+    explanation = explain_traceback(tb, project)
+    print(render_explanation(explanation))
+    return _EXIT_OK
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

deploy_guard/config.py

@@ -0,0 +1,72 @@
+"""Load ``[tool.deploy-guard]`` from a scanned project's ``pyproject.toml``.
+
+TOML reading needs the standard-library ``tomllib`` (Python 3.11+). On 3.10
+there is no config file support; CLI flags still work.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+try:  # Python 3.11+
+    import tomllib as _toml
+except ModuleNotFoundError:  # pragma: no cover - 3.10
+    _toml = None
+
+_VALID_FAIL_ON = {"block", "review", "warn", "none"}
+
+
+@dataclass
+class Config:
+    disable: set[str] = field(default_factory=set)
+    exclude: list[str] = field(default_factory=list)
+    fail_on: str | None = None
+    include_tests: bool | None = None
+    source: Path | None = None  # the file it came from, if any
+
+    def merged_with_cli(
+        self,
+        *,
+        disable: set[str] | None = None,
+        fail_on: str | None = None,
+        include_tests: bool | None = None,
+    ) -> Config:
+        """CLI values win over the file."""
+        return Config(
+            disable=self.disable | (disable or set()),
+            exclude=list(self.exclude),
+            fail_on=fail_on or self.fail_on,
+            include_tests=include_tests if include_tests is not None else self.include_tests,
+            source=self.source,
+        )
+
+
+def load_config(project_root: str | Path) -> Config:
+    root = Path(project_root)
+    pyproject = root / "pyproject.toml"
+    if _toml is None or not pyproject.is_file():
+        return Config()
+    try:
+        data = _toml.loads(pyproject.read_text(encoding="utf-8"))
+    except Exception:
+        return Config()
+    table = data.get("tool", {}).get("deploy-guard", {})
+    if not isinstance(table, dict):
+        return Config()
+
+    fail_on = table.get("fail-on")
+    if fail_on not in _VALID_FAIL_ON:
+        fail_on = None
+
+    return Config(
+        disable={str(r) for r in table.get("disable", []) if isinstance(r, str)},
+        exclude=[str(d) for d in table.get("exclude", []) if isinstance(d, str)],
+        fail_on=fail_on,
+        include_tests=_as_bool(table.get("include-tests")),
+        source=pyproject,
+    )
+
+
+def _as_bool(value: object) -> bool | None:
+    return value if isinstance(value, bool) else None

deploy_guard/engine.py

@@ -0,0 +1,270 @@
+"""The scan pipeline: directory in, analysis + generated tests out.
+
+    discover  ->  lower (Python)  ->  per function: CFG -> behavior spec -> findings
+                                  ->  generators (import smoke)
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+
+from deploy_guard.analysis import findings as _findings_mod
+from deploy_guard.analysis.callgraph import build_call_graph
+from deploy_guard.analysis.context import AnalysisContext
+from deploy_guard.analysis.findings import Finding, analyze_function
+from deploy_guard.analysis.paths import (
+    DEFAULT_LIMIT,
+    DEFAULT_UNROLL,
+    BehaviorSpec,
+    behavior_spec,
+)
+from deploy_guard.frontend import build_cfg, lower_python
+from deploy_guard.generators import GeneratedFile, generate_import_smoke
+from deploy_guard.ingest import discover
+from deploy_guard.ir.model import FunctionDef, Module, Project
+
+_SEVERITY_ORDER = {"block": 0, "review": 1, "warn": 2, "note": 3}
+# Severities that count as gate findings; "note" is informational only.
+GATE_SEVERITIES = ("block", "review", "warn")
+
+
+@dataclass
+class FunctionReport:
+    module: Module
+    fn: FunctionDef
+    spec: BehaviorSpec
+    findings: list[Finding] = field(default_factory=list)
+    cfg_block_count: int = 0
+    cfg_notes: list[str] = field(default_factory=list)
+    error: str | None = None
+
+
+@dataclass
+class ScanResult:
+    project: Project
+    functions: list[FunctionReport] = field(default_factory=list)
+    generated: list[GeneratedFile] = field(default_factory=list)
+    parse_errors: list[tuple[str, str]] = field(default_factory=list)
+    disabled_rules: frozenset[str] = frozenset()
+    extra_findings: list[Finding] = field(default_factory=list)
+    context: AnalysisContext | None = None
+    collapse: bool = True
+
+    @property
+    def _all(self) -> list[Finding]:
+        flat = [f for fr in self.functions for f in fr.findings] + list(self.extra_findings)
+        flat.sort(key=lambda f: (_SEVERITY_ORDER.get(f.severity, 9), f.file, f.lineno))
+        return flat
+
+    @property
+    def findings(self) -> list[Finding]:
+        """Gate findings (block/review/warn), copy-paste duplicates collapsed."""
+        gate = [f for f in self._all if f.severity in GATE_SEVERITIES]
+        return _collapse_duplicates(gate, self.project.root) if self.collapse else gate
+
+    @property
+    def raw_findings(self) -> list[Finding]:
+        """Every gate finding, nothing collapsed."""
+        return [f for f in self._all if f.severity in GATE_SEVERITIES]
+
+    @property
+    def notes(self) -> list[Finding]:
+        return [f for f in self._all if f.severity == "note"]
+
+    def findings_at_or_above(self, threshold: str) -> list[Finding]:
+        cap = _SEVERITY_ORDER.get(threshold, -1)
+        return [f for f in self.findings if _SEVERITY_ORDER.get(f.severity, 9) <= cap]
+
+    def counts_by_severity(self) -> dict[str, int]:
+        out = {s: 0 for s in _SEVERITY_ORDER}
+        for f in [*self.findings, *self.notes]:
+            out[f.severity] = out.get(f.severity, 0) + 1
+        return out
+
+    @property
+    def collapsed_count(self) -> int:
+        """How many duplicate findings were folded away."""
+        return len(self.raw_findings) - len(self.findings)
+
+
+def scan(
+    root: str | Path,
+    *,
+    include_tests: bool = False,
+    path_limit: int = DEFAULT_LIMIT,
+    unroll: int = DEFAULT_UNROLL,
+    disable: frozenset[str] | set[str] | None = None,
+    exclude: list[str] | None = None,
+) -> ScanResult:
+    disabled = frozenset(disable or ())
+    project = lower_python(
+        discover(root, include_tests=include_tests, extra_exclude=exclude)
+    )
+    result = ScanResult(project=project, disabled_rules=disabled)
+
+    ctx = build_context(project, path_limit=path_limit, unroll=unroll)
+    result.context = ctx
+
+    for module in project.modules:
+        if module.parse_error:
+            result.parse_errors.append(
+                (module.dotted_name or str(module.path), module.parse_error)
+            )
+            continue
+        result.extra_findings.extend(_syntax_warning_findings(module))
+        for fn in module.iter_functions():
+            fr = _analyze_one(module, fn, ctx=ctx, path_limit=path_limit, unroll=unroll)
+            if disabled:
+                fr.findings = [f for f in fr.findings if f.rule not in disabled]
+            result.functions.append(fr)
+
+    if disabled:
+        result.extra_findings = [
+            f for f in result.extra_findings if f.rule not in disabled
+        ]
+
+    if project.modules:
+        result.generated.append(generate_import_smoke(project))
+
+    return result
+
+
+def build_context(
+    project: Project, *, path_limit: int = DEFAULT_LIMIT, unroll: int = DEFAULT_UNROLL
+) -> AnalysisContext:
+    """First pass: call graph + every function's return shape, so the second
+    pass can reason across function boundaries."""
+    cg = build_call_graph(project)
+    ctx = AnalysisContext(callgraph=cg)
+    for _module, fn in project.iter_functions():
+        try:
+            cfg = build_cfg(fn)
+        except Exception:
+            continue
+        value_return, none_exit, _ = _findings_mod._return_shape(cfg)
+        if none_exit and not _findings_mod._declares_optional(fn.returns):
+            ctx.returns_none.add(fn.qualname)
+        if value_return:
+            ctx.returns_value.add(fn.qualname)
+        ctx.specs[fn.qualname] = behavior_spec(fn, cfg, limit=path_limit, unroll=unroll)
+    return ctx
+
+
+def _syntax_warning_findings(module: Module) -> list[Finding]:
+    out: list[Finding] = []
+    for lineno, message in module.syntax_warnings:
+        is_escape = "escape sequence" in message
+        rule = "invalid-escape" if is_escape else "syntax-warning"
+        # Works today, breaks in a future Python -> informational note, not a gate finding.
+        severity = "note" if is_escape else "warn"
+        msg = (
+            "invalid escape sequence in a non-raw string - works today but is "
+            "deprecated and will become a SyntaxError in a future Python; use a "
+            "raw string r\"...\""
+            if is_escape
+            else f"Python SyntaxWarning: {message}"
+        )
+        out.append(
+            Finding(
+                rule=rule,
+                severity=severity,
+                message=msg,
+                qualname=module.dotted_name,
+                file=str(module.path),
+                lineno=lineno,
+                detail=message,
+            )
+        )
+    return out
+
+
+def _collapse_duplicates(findings: list[Finding], root: Path) -> list[Finding]:
+    """Fold findings that are the same finding in a copy-pasted function into
+    one, listing the other locations in its detail."""
+    groups: dict[tuple[str, str], list[Finding]] = {}
+    order: list[tuple[str, str]] = []
+    passthrough: list[Finding] = []
+    for f in findings:
+        if not f.group_key:
+            passthrough.append(f)
+            continue
+        key = (f.rule, f.group_key)
+        if key not in groups:
+            groups[key] = []
+            order.append(key)
+        groups[key].append(f)
+
+    collapsed: list[Finding] = list(passthrough)
+    for key in order:
+        members = groups[key]
+        head = members[0]
+        if len(members) > 1:
+            others = sorted({_rel(root, m.file) for m in members if m is not head})
+            shown = ", ".join(others[:6]) + ("…" if len(others) > 6 else "")
+            extra = (
+                f"this function is copy-pasted; same finding in {len(members)} "
+                f"places total (also: {shown})"
+            )
+            new_detail = f"{head.detail}  [{extra}]" if head.detail else f"[{extra}]"
+            head = replace(head, detail=new_detail)  # never mutate the original
+        collapsed.append(head)
+
+    collapsed.sort(key=lambda f: (_SEVERITY_ORDER.get(f.severity, 9), f.file, f.lineno))
+    return collapsed
+
+
+def _rel(root: Path, path: str) -> str:
+    try:
+        return str(Path(path).resolve().relative_to(Path(root).resolve()))
+    except ValueError:
+        return path
+
+
+def _analyze_one(
+    module: Module,
+    fn: FunctionDef,
+    *,
+    ctx: AnalysisContext | None = None,
+    path_limit: int,
+    unroll: int,
+) -> FunctionReport:
+    try:
+        cfg = build_cfg(fn)
+        spec = behavior_spec(fn, cfg, limit=path_limit, unroll=unroll)
+        findings = analyze_function(fn, cfg, spec, ctx)
+        body_hash = _body_hash(fn)
+        for f in findings:
+            f.group_key = f"{body_hash}:{f.rule}:{f.lineno - fn.span.lineno}"
+        return FunctionReport(
+            module=module,
+            fn=fn,
+            spec=spec,
+            findings=findings,
+            cfg_block_count=len(cfg.blocks),
+            cfg_notes=cfg.notes,
+        )
+    except Exception as exc:  # analysis must never crash the whole scan
+        return FunctionReport(
+            module=module,
+            fn=fn,
+            spec=BehaviorSpec(qualname=fn.qualname),
+            error=f"{type(exc).__name__}: {exc}",
+        )
+
+
+def _body_hash(fn: FunctionDef) -> str:
+    """Structural hash of the function body, ignoring names/lines, so that
+    copy-pasted helpers hash identically."""
+    node = fn.raw
+    if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return ""
+    try:
+        dump = ast.dump(
+            ast.Module(body=list(node.body), type_ignores=[]), include_attributes=False
+        )
+    except Exception:
+        return ""
+    return hashlib.blake2b(dump.encode(), digest_size=8).hexdigest()

deploy_guard/explain/__init__.py

@@ -0,0 +1,16 @@
+"""Reverse mode: take a production traceback and explain why it happened,
+using the same CFG / nullability / behavior-spec analysis the scanner uses.
+"""
+
+from deploy_guard.explain.explainer import Explanation, explain_traceback
+from deploy_guard.explain.render import render_explanation
+from deploy_guard.explain.traceback_parse import Frame, ParsedTraceback, parse_traceback
+
+__all__ = [
+    "parse_traceback",
+    "ParsedTraceback",
+    "Frame",
+    "explain_traceback",
+    "Explanation",
+    "render_explanation",
+]