errpath 0.1.0__py3-none-any.whl

errpath/review.py

@@ -0,0 +1,517 @@
+"""Compare error railways between two git refs."""
+
+from __future__ import annotations
+
+import difflib
+import subprocess
+import tarfile
+import tempfile
+from collections import Counter
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Literal
+
+from errpath.analyse import analyse_path
+from errpath.diagram import render_function
+from errpath.ir import (
+    SCHEMA_VERSION,
+    Branch,
+    Coverage,
+    Fail,
+    Finding,
+    Function,
+    Jump,
+    Loop,
+    Node,
+    Panic,
+    Recover,
+    Report,
+    Step,
+    Succeed,
+    Swallow,
+    Unanalysed,
+    to_dict,
+)
+
+MARKER = "<!-- errpath-review -->"
+MAX_FUNCTIONS = 20
+MAX_DIAGRAMS = 5
+
+
+class Risk(StrEnum):
+    LOW = "low"
+    MODERATE = "moderate"
+    HIGH = "high"
+
+
+class Status(StrEnum):
+    CHANGED = "changed"
+    ADDED = "added"
+    REMOVED = "removed"
+
+
+class ItemKind(StrEnum):
+    STEP = "step"
+    FAIL = "fail"
+    PANIC = "panic"
+    SWALLOW = "swallow"
+    RECOVER = "recover"
+    RETURN = "return"
+    JUMP = "jump"
+    FORK = "fork"
+
+
+@dataclass
+class Item:
+    kind: ItemKind
+    label: str
+    line: int
+    error: str | None = None
+    context: str = ""
+    key: str = ""
+
+
+@dataclass
+class FnChange:
+    id: str
+    status: Status
+    file: str
+    line: int
+    added: list[Item] = field(default_factory=list)
+    removed: list[Item] = field(default_factory=list)
+    diagram: str | None = None
+
+
+@dataclass
+class NewFinding:
+    severity: str
+    finding: Finding
+
+
+@dataclass
+class Review:
+    schema_version: int = SCHEMA_VERSION
+    changed: bool = False
+    risk: Risk = Risk.LOW
+    markdown: str = ""
+    new_findings: list[NewFinding] = field(default_factory=list)
+    new_allows: list[Finding] = field(default_factory=list)
+    functions: list[FnChange] = field(default_factory=list)
+    moved: int = 0
+    new_functions: int = 0
+    removed_functions: int = 0
+    notes: list[str] = field(default_factory=list)
+    coverage: Coverage = field(default_factory=Coverage)
+    unparsed_files: int = 0
+    support_files_skipped: int = 0
+    # gaps new in this change, plus existing ones in changed functions
+    unanalysed: list[Unanalysed] = field(default_factory=list)
+    new_unanalysed: list[Unanalysed] = field(default_factory=list)
+    summary: str = ""
+
+
+def _nested(context: str, part: str) -> str:
+    return part if not context else f"{context} / {part}"
+
+
+def _routing(n: Step | Panic, tries: list[str]) -> str:
+    """Which handler catches which exception type, e.g. ``ValueError -> except ValueError``.
+
+    Part of the comparison key, so moving a call out of a try's protection is a change.
+    ``tries`` are the enclosing try tags, innermost last; a handler of an outer try is
+    marked with how many tries out it is, so same-named nested handlers stay distinct.
+    """
+    parts = []
+    for k, c in n.caught_by.items():
+        tag = c.handler.split("#")[0]
+        up = len(tries) - 1 - tries.index(tag) if tag in tries else -1
+        parts.append(
+            f"{k} -> {c.how}" + (f" ({up} {'try' if up == 1 else 'tries'} out)" if up else "")
+        )
+    return ", ".join(sorted(parts))
+
+
+def _with_routing(label: str, routing: str) -> str:
+    return f"{label} (caught: {routing})" if routing else label
+
+
+def flatten(nodes: list[Node], context: str = "", tries: list[str] | None = None) -> list[Item]:
+    tries = tries or []
+    items: list[Item] = []
+    for n in nodes:
+        if isinstance(n, Step):
+            routing = _routing(n, tries)
+            items.append(
+                Item(
+                    kind=ItemKind.STEP,
+                    label=_with_routing(n.name, routing),
+                    error=n.error,
+                    line=n.line,
+                    context=context,
+                    key=f"step:{context}:{n.name}:{n.error or ''}:{routing}",
+                )
+            )
+        elif isinstance(n, Fail):
+            items.append(
+                Item(
+                    kind=ItemKind.FAIL,
+                    label=n.error,
+                    error=n.error,
+                    line=n.line,
+                    context=context,
+                    key=f"fail:{context}:{n.error}",
+                )
+            )
+        elif isinstance(n, Succeed):
+            items.append(
+                Item(
+                    kind=ItemKind.RETURN,
+                    label="Ok",
+                    line=0,
+                    context=context,
+                    key=f"return:{context}:Ok",
+                )
+            )
+        elif isinstance(n, Panic):
+            routing = _routing(n, tries)
+            items.append(
+                Item(
+                    kind=ItemKind.PANIC,
+                    label=_with_routing(n.name, routing),
+                    line=n.line,
+                    context=context,
+                    key=f"panic:{context}:{n.name}:{routing}",
+                )
+            )
+        elif isinstance(n, Swallow):
+            items.append(
+                Item(
+                    kind=ItemKind.SWALLOW,
+                    label=n.name,
+                    line=n.line,
+                    context=context,
+                    key=f"swallow:{context}:{n.name}:{n.how}",
+                )
+            )
+        elif isinstance(n, Recover):
+            items.append(
+                Item(
+                    kind=ItemKind.RECOVER,
+                    label=n.name,
+                    line=n.line,
+                    context=context,
+                    key=f"recover:{context}:{n.name}:{n.how}",
+                )
+            )
+        elif isinstance(n, Jump):
+            items.append(
+                Item(
+                    kind=ItemKind.JUMP,
+                    label=n.name,
+                    line=n.line,
+                    context=context,
+                    key=f"jump:{context}:{n.name}",
+                )
+            )
+        elif isinstance(n, Branch):
+            items.append(
+                Item(
+                    kind=ItemKind.FORK,
+                    label=n.label,
+                    line=0,
+                    context=context,
+                    key=f"fork:{context}:{n.label}",
+                )
+            )
+            inner = [*tries, n.tag] if n.tag else tries
+            for arm in n.arms:
+                items.extend(flatten(arm.body, _nested(context, arm.label), inner))
+        elif isinstance(n, Loop):
+            items.extend(flatten(n.head, _nested(context, n.label), tries))
+            items.extend(flatten(n.body, _nested(context, n.label), tries))
+    return items
+
+
+def _diff(old: list[Item], new: list[Item]) -> tuple[list[Item], list[Item]]:
+    """(added, removed) by sequence, so repeats and reordering both count as changes."""
+    matcher = difflib.SequenceMatcher(
+        a=[i.key for i in old], b=[i.key for i in new], autojunk=False
+    )
+    added: list[Item] = []
+    removed: list[Item] = []
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        if tag != "equal":
+            removed.extend(old[i1:i2])
+            added.extend(new[j1:j2])
+    return added, removed
+
+
+def _fn_map(report: Report) -> dict[str, Function]:
+    return {fn.id: fn for fn in report.functions}
+
+
+def _finding_key(f: Finding) -> str:
+    # No line number: code moving up or down must not make an old finding look new.
+    return f"{f.rule}:{f.file}:{f.function}:{f.message}"
+
+
+def compare(
+    base: Report, head: Report, *, diagrams: Literal["open", "collapsed"] = "collapsed"
+) -> Review:
+    review = Review(
+        coverage=head.coverage,
+        unparsed_files=len(head.parse_failures),
+        support_files_skipped=head.support_files_skipped,
+    )
+    base_fns = _fn_map(base)
+    head_fns = _fn_map(head)
+
+    base_ids = set(base_fns)
+    head_ids = set(head_fns)
+
+    review.new_functions = len(head_ids - base_ids)
+    review.removed_functions = len(base_ids - head_ids)
+
+    for fid in sorted(base_ids | head_ids):
+        b, h = base_fns.get(fid), head_fns.get(fid)
+        b_items = flatten(b.nodes) if b else []
+        h_items = flatten(h.nodes) if h else []
+        added, removed = _diff(b_items, h_items)
+        if not added and not removed:
+            continue
+        shown = h or b
+        assert shown is not None
+        review.functions.append(
+            FnChange(
+                id=fid,
+                status=Status.CHANGED if b and h else Status.ADDED if h else Status.REMOVED,
+                file=shown.file,
+                line=shown.line,
+                added=added,
+                removed=removed,
+                diagram=render_function(h) if h else None,
+            )
+        )
+
+    # Counted, so a second identical unwrap in the same function is still new.
+    base_fkeys = Counter(_finding_key(f) for f in base.findings)
+    for finding in head.findings:
+        key = _finding_key(finding)
+        if base_fkeys[key] > 0:
+            base_fkeys[key] -= 1
+            continue
+        severity = "error" if finding.rule == "no-panic" else "warning"
+        review.new_findings.append(NewFinding(severity=severity, finding=finding))
+
+    # A new gap is a change too: the review can no longer vouch for that code.
+    # Counted, and keyed without the line, like findings.
+    base_gaps = Counter(_gap_key(u) for u in base.unanalysed)
+    for gap in head.unanalysed:
+        key = _gap_key(gap)
+        if base_gaps[key] > 0:
+            base_gaps[key] -= 1
+        else:
+            review.new_unanalysed.append(gap)
+    changed_ids = {c.id for c in review.functions}
+    review.unanalysed = [
+        u
+        for u in head.unanalysed
+        if u.function in changed_ids or any(u is new for new in review.new_unanalysed)
+    ]
+    review.changed = bool(review.functions or review.new_findings or review.new_unanalysed)
+    review.risk = _risk(review)
+    review.summary = _summary(review)
+    review.markdown = _markdown(review, diagrams=diagrams) if review.changed else ""
+    return review
+
+
+def _gap_key(u: Unanalysed) -> str:
+    return f"{u.file}:{u.function}:{u.code}:{u.reason}"
+
+
+def _risk(review: Review) -> Risk:
+    if any(nf.finding.rule == "no-panic" for nf in review.new_findings):
+        return Risk.HIGH
+    if any(nf.finding.rule == "no-swallow" for nf in review.new_findings):
+        return Risk.HIGH
+    if review.functions or review.new_unanalysed:
+        return Risk.MODERATE
+    return Risk.LOW
+
+
+def _summary(review: Review) -> str:
+    if not review.changed:
+        return "No error-path changes."
+    parts = [
+        f"{len(review.functions)} function(s) changed",
+        f"{len(review.new_findings)} new finding(s)",
+    ]
+    if review.new_unanalysed:
+        parts.append(f"{len(review.new_unanalysed)} new spot(s) errpath can't follow")
+    parts.append(f"risk={review.risk.value}")
+    return ", ".join(parts)
+
+
+def _markdown(review: Review, *, diagrams: Literal["open", "collapsed"]) -> str:
+    lines = [
+        MARKER,
+        "",
+        f"## Error path review: {review.risk.value} risk",
+        "",
+        review.summary,
+        "",
+    ]
+    if review.new_findings:
+        lines.append("### New findings")
+        lines.append("")
+        for nf in review.new_findings:
+            f = nf.finding
+            lines.append(f"- `{f.rule}` {f.message} at `{f.file}:{f.line}`")
+        lines.append("")
+
+    for i, change in enumerate(review.functions[:MAX_FUNCTIONS]):
+        status = "" if change.status == Status.CHANGED else f" ({change.status.value})"
+        lines.append(f"### `{change.id}`{status}")
+        lines.append("")
+        for item in change.added:
+            lines.append(f"- added {item.kind.value} `{item.label}`")
+        for item in change.removed:
+            lines.append(f"- removed {item.kind.value} `{item.label}`")
+        if change.diagram and i < MAX_DIAGRAMS:
+            open_attr = " open" if diagrams == "open" else ""
+            lines.append("")
+            lines.append(f"<details{open_attr}>")
+            lines.append("<summary>Diagram</summary>")
+            lines.append("")
+            lines.append("```mermaid")
+            lines.append(change.diagram)
+            lines.append("```")
+            lines.append("")
+            lines.append("</details>")
+        lines.append("")
+
+    if review.unanalysed:
+        lines.append("### Not analysed")
+        lines.append("")
+        lines.append("errpath couldn't follow these, so this review may miss error paths there:")
+        lines.append("")
+        for u in review.unanalysed:
+            new = " (new)" if any(u is n for n in review.new_unanalysed) else ""
+            lines.append(f"- `{u.file}:{u.line}` `{u.code}`{new}: {u.reason}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def review_to_dict(review: Review) -> dict[str, Any]:
+    def item_dict(item: Item) -> dict[str, Any]:
+        return {
+            "kind": item.kind.value,
+            "label": item.label,
+            "error": item.error,
+            "line": item.line,
+            "context": item.context,
+        }
+
+    return {
+        "schema_version": review.schema_version,
+        "changed": review.changed,
+        "risk": review.risk.value,
+        "markdown": review.markdown,
+        "newFindings": [
+            {
+                "severity": nf.severity,
+                **to_dict(nf.finding),
+            }
+            for nf in review.new_findings
+        ],
+        "new_allows": [to_dict(f) for f in review.new_allows],
+        "functions": [
+            {
+                "id": c.id,
+                "status": c.status.value,
+                "file": c.file,
+                "line": c.line,
+                "added": [item_dict(i) for i in c.added],
+                "removed": [item_dict(i) for i in c.removed],
+            }
+            for c in review.functions
+        ],
+        "moved": review.moved,
+        "new_functions": review.new_functions,
+        "removed_functions": review.removed_functions,
+        "notes": review.notes,
+        "coverage": to_dict(review.coverage),
+        "unparsed_files": review.unparsed_files,
+        "support_files_skipped": review.support_files_skipped,
+        "unanalysed": [
+            {**to_dict(u), "new": any(u is n for n in review.new_unanalysed)}
+            for u in review.unanalysed
+        ],
+        "summary": review.summary,
+    }
+
+
+def _git_export(repo: Path, ref: str, paths: list[str], dest: Path) -> Path:
+    """Write ``ref``'s .py files (limited to ``paths`` if given) under ``dest``.
+
+    One ``git archive`` stream instead of one ``git show`` per file.
+    """
+    prefixes = [p.rstrip("/") for p in paths]
+
+    def wanted(name: str) -> bool:
+        if not name.endswith(".py"):
+            return False
+        return not prefixes or any(name == p or name.startswith(p + "/") for p in prefixes)
+
+    dest.mkdir(parents=True, exist_ok=True)
+    root = dest.resolve()
+    # `with` closes both pipes and waits for git, on every path out.
+    with subprocess.Popen(
+        ["git", "-C", str(repo), "archive", "--format=tar", ref],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    ) as proc:
+        assert proc.stdout is not None and proc.stderr is not None
+        try:
+            with tarfile.open(fileobj=proc.stdout, mode="r|") as tar:
+                for member in tar:
+                    if not member.isfile() or not wanted(member.name):
+                        continue
+                    target = (dest / member.name).resolve()
+                    if not target.is_relative_to(root):
+                        continue  # never write outside dest
+                    fileobj = tar.extractfile(member)
+                    if fileobj is None:
+                        continue
+                    target.parent.mkdir(parents=True, exist_ok=True)
+                    target.write_bytes(fileobj.read())
+        except tarfile.ReadError:
+            if proc.wait() == 0:
+                raise  # git succeeded but the stream is broken
+            # else: git failed (bad ref); raised with its message below
+        stderr = proc.stderr.read()
+        if proc.wait() != 0:
+            raise subprocess.CalledProcessError(proc.returncode, proc.args, stderr=stderr)
+    return dest
+
+
+def run(
+    *,
+    repo: Path,
+    base: str,
+    head: str = "HEAD",
+    paths: list[str] | None = None,
+    diagrams: Literal["open", "collapsed"] = "collapsed",
+) -> Review:
+    paths = paths or []
+    with tempfile.TemporaryDirectory(prefix="errpath-") as tmp:
+        base_dir = _git_export(repo, base, paths, Path(tmp) / "base")
+        head_dir = _git_export(repo, head, paths, Path(tmp) / "head")
+        # Both trees share the repo layout, so file paths in the reports are repo-relative.
+        return compare(analyse_path(base_dir), analyse_path(head_dir), diagrams=diagrams)
+
+
+def compare_paths(base_path: Path, head_path: Path, **kwargs: Any) -> Review:
+    """Compare two directories or files without git (handy for tests)."""
+    return compare(analyse_path(base_path), analyse_path(head_path), **kwargs)

errpath/safe.py

@@ -0,0 +1,129 @@
+"""Decorators that wrap function returns in Result."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+from collections.abc import Awaitable, Callable
+from typing import Any, ParamSpec, TypeVar, overload
+
+from errpath.result import Err, Ok, Result
+
+P = ParamSpec("P")
+R = TypeVar("R")
+E1 = TypeVar("E1", bound=BaseException)
+E2 = TypeVar("E2", bound=BaseException)
+E3 = TypeVar("E3", bound=BaseException)
+
+
+def safe(func: Callable[P, R]) -> Callable[P, Result[R, Exception]]:
+    """Catch any Exception and return ``Result[R, Exception]``."""
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> Result[R, Exception]:
+        try:
+            return Ok(func(*args, **kwargs))
+        except Exception as e:
+            return Err(e)
+
+    return wrapper
+
+
+# Overloads keep the exact error types for up to three (e.g. Err[ValueError | KeyError]);
+# with more, the error is typed as BaseException.
+@overload
+def safe_with(e1: type[E1], /) -> Callable[[Callable[P, R]], Callable[P, Result[R, E1]]]: ...
+@overload
+def safe_with(
+    e1: type[E1], e2: type[E2], /
+) -> Callable[[Callable[P, R]], Callable[P, Result[R, E1 | E2]]]: ...
+@overload
+def safe_with(
+    e1: type[E1], e2: type[E2], e3: type[E3], /
+) -> Callable[[Callable[P, R]], Callable[P, Result[R, E1 | E2 | E3]]]: ...
+@overload
+def safe_with(
+    *exc_types: type[BaseException],
+) -> Callable[[Callable[P, R]], Callable[P, Result[R, BaseException]]]: ...
+
+
+def safe_with(
+    *exc_types: type[BaseException],
+) -> Callable[[Callable[P, R]], Callable[P, Result[R, Any]]]:
+    """Catch only the given exception types; others propagate."""
+    if not exc_types:
+        raise TypeError("safe_with requires at least one exception type")
+
+    def decorator(func: Callable[P, R]) -> Callable[P, Result[R, BaseException]]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> Result[R, BaseException]:
+            try:
+                return Ok(func(*args, **kwargs))
+            except exc_types as e:
+                return Err(e)
+
+        return wrapper
+
+    return decorator
+
+
+def safe_async(
+    func: Callable[P, Awaitable[R]],
+) -> Callable[P, Awaitable[Result[R, Exception]]]:
+    """Async variant of ``@safe``. Never catches ``CancelledError``."""
+
+    @functools.wraps(func)
+    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> Result[R, Exception]:
+        try:
+            return Ok(await func(*args, **kwargs))
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            return Err(e)
+
+    return wrapper
+
+
+@overload
+def safe_async_with(
+    e1: type[E1], /
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[Result[R, E1]]]]: ...
+@overload
+def safe_async_with(
+    e1: type[E1], e2: type[E2], /
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[Result[R, E1 | E2]]]]: ...
+@overload
+def safe_async_with(
+    e1: type[E1], e2: type[E2], e3: type[E3], /
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[Result[R, E1 | E2 | E3]]]]: ...
+@overload
+def safe_async_with(
+    *exc_types: type[BaseException],
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[Result[R, BaseException]]]]: ...
+
+
+def safe_async_with(
+    *exc_types: type[BaseException],
+) -> Callable[
+    [Callable[P, Awaitable[R]]],
+    Callable[P, Awaitable[Result[R, Any]]],
+]:
+    """Async variant of ``@safe_with``. Never catches ``CancelledError``."""
+    if not exc_types:
+        raise TypeError("safe_async_with requires at least one exception type")
+
+    def decorator(
+        func: Callable[P, Awaitable[R]],
+    ) -> Callable[P, Awaitable[Result[R, BaseException]]]:
+        @functools.wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> Result[R, BaseException]:
+            try:
+                return Ok(await func(*args, **kwargs))
+            except asyncio.CancelledError:
+                raise
+            except exc_types as e:
+                return Err(e)
+
+        return wrapper
+
+    return decorator