errpath 0.1.0__py3-none-any.whl

errpath/cli.py

@@ -0,0 +1,141 @@
+"""errpath CLI: ir | machine | diagram | review."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from errpath.analyse import analyse_path
+from errpath.diagram import render_function
+from errpath.ir import Function, to_dict
+from errpath.machine import function_to_machine
+from errpath.review import review_to_dict
+from errpath.review import run as run_review
+
+
+def _find_function(report_functions: list[Function], name: str) -> Function | None:
+    matches = [
+        f for f in report_functions if f.name == name or f.id == name or f.id.endswith("." + name)
+    ]
+    if not matches:
+        return None
+    if len(matches) > 1:
+        # Prefer exact name match in the given file scope
+        exact = [f for f in matches if f.name == name]
+        return exact[0] if exact else matches[0]
+    return matches[0]
+
+
+def _emit(text: str, output: str | None) -> int:
+    if output:
+        Path(output).write_text(text + "\n", encoding="utf-8")
+    else:
+        print(text)
+    return 0
+
+
+def _load_function(args: argparse.Namespace) -> Function | None:
+    report = analyse_path(Path(args.path))
+    fn = _find_function(report.functions, args.function)
+    if fn is None:
+        names = ", ".join(f.name for f in report.functions) or "(none)"
+        print(f"function {args.function!r} not found; have: {names}", file=sys.stderr)
+        return None
+    for u in report.unanalysed:  # say what the output can't show, on stderr
+        if u.function == fn.id:
+            print(f"errpath: note: {u.file}:{u.line}: {u.reason}: {u.code}", file=sys.stderr)
+    return fn
+
+
+def cmd_ir(args: argparse.Namespace) -> int:
+    report = analyse_path(Path(args.path))
+    return _emit(json.dumps(to_dict(report), indent=2), args.output)
+
+
+def cmd_machine(args: argparse.Namespace) -> int:
+    fn = _load_function(args)
+    if fn is None:
+        return 1
+    return _emit(json.dumps(function_to_machine(fn), indent=2), args.output)
+
+
+def cmd_diagram(args: argparse.Namespace) -> int:
+    fn = _load_function(args)
+    if fn is None:
+        return 1
+    return _emit(render_function(fn), args.output)
+
+
+def cmd_review(args: argparse.Namespace) -> int:
+    review = run_review(
+        repo=Path(args.repo or ".").resolve(),
+        base=args.base,
+        head=args.head,
+        paths=args.paths or [],
+        diagrams=args.diagrams,
+    )
+    if args.format == "json":
+        text = json.dumps(review_to_dict(review), indent=2)
+    else:
+        text = review.markdown or review.summary
+    return _emit(text, args.output)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="errpath",
+        description="Result type helpers and error-path analysis for Python",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    ir_p = sub.add_parser("ir", help="Emit versioned IR JSON for a path")
+    ir_p.add_argument("path", nargs="?", default=".", help="File or directory")
+    ir_p.add_argument("-o", "--output", help="Write to file instead of stdout")
+    ir_p.set_defaults(func=cmd_ir)
+
+    machine_p = sub.add_parser("machine", help="Emit XState MachineJSON for a function")
+    machine_p.add_argument("path", help="File or directory")
+    machine_p.add_argument("function", help="Function name")
+    machine_p.add_argument("-o", "--output", help="Write to file instead of stdout")
+    machine_p.set_defaults(func=cmd_machine)
+
+    diagram_p = sub.add_parser("diagram", help="Emit Mermaid flowchart for a function")
+    diagram_p.add_argument("path", help="File or directory")
+    diagram_p.add_argument("function", help="Function name")
+    diagram_p.add_argument("-o", "--output", help="Write to file instead of stdout")
+    diagram_p.set_defaults(func=cmd_diagram)
+
+    review_p = sub.add_parser("review", help="Compare error paths between git refs")
+    review_p.add_argument("paths", nargs="*", help="Optional paths to limit the review")
+    review_p.add_argument("--base", required=True, help="Base git ref")
+    review_p.add_argument("--head", default="HEAD", help="Head git ref (default HEAD)")
+    review_p.add_argument("--repo", default=".", help="Git repository root")
+    review_p.add_argument(
+        "--diagrams",
+        choices=("open", "collapsed"),
+        default="collapsed",
+        help="Mermaid diagrams in markdown",
+    )
+    review_p.add_argument(
+        "--format",
+        choices=("markdown", "json"),
+        default="markdown",
+        help="Output format",
+    )
+    review_p.add_argument("-o", "--output", help="Write to file instead of stdout")
+    review_p.set_defaults(func=cmd_review)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    code = args.func(args)
+    raise SystemExit(code)
+
+
+if __name__ == "__main__":
+    main()

errpath/diagram.py

@@ -0,0 +1,135 @@
+"""Render Mermaid flowchart LR from a function's IR nodes."""
+
+from __future__ import annotations
+
+from errpath.ir import (
+    CATCH_ANY,
+    Branch,
+    Fail,
+    Function,
+    Jump,
+    Loop,
+    Node,
+    Panic,
+    Recover,
+    Step,
+    Succeed,
+    Swallow,
+    escaping,
+)
+
+
+def _text(label: str) -> str:
+    return label.replace('"', "'")
+
+
+def render(fn_name: str, nodes: list[Node]) -> str:
+    """Mermaid flowchart of ``nodes``.
+
+    Built back to front, like the state machine: what follows a fork is drawn once and
+    every arm points at it, and each error type gets one shared box.
+    """
+    lines = ["flowchart LR", f'  Start(["{_text(fn_name)}"])', "  Done((Success))"]
+    counter = {"n": 0}
+    handlers: dict[str, str] = {}  # "<try tag>#<arm index>" -> handler entry node
+    errors: dict[str, str] = {}  # error label -> its box
+
+    def add(prefix: str, shape: str) -> str:
+        counter["n"] += 1
+        node_id = f"{prefix}{counter['n']}"
+        lines.append(f"  {node_id}{shape}")
+        return node_id
+
+    def link(src: str, label: str, dst: str) -> None:
+        if not label:
+            lines.append(f"  {src} --> {dst}")
+        elif label.replace("_", "").replace(" ", "").isalnum():
+            lines.append(f"  {src} -->|{label}| {dst}")
+        else:
+            lines.append(f'  {src} -->|"{_text(label)}"| {dst}')
+
+    def error_box(label: str) -> str:
+        if label not in errors:
+            errors[label] = add("E", f'[/"{_text(label)}"/]')
+        return errors[label]
+
+    def error_edges(src: str, edge: str, node: Step | Panic, escape_label: str | None) -> None:
+        """One edge per caught type to its handler, one for what escapes; through finally first."""
+        for key, catch in node.caught_by.items():
+            label = "any" if key == CATCH_ANY else key
+            link(src, f"{edge} {label}", emit(list(catch.cleanup), handlers[catch.handler]))
+        left = escaping(node.error, node.caught_by)
+        if left is not None:
+            link(src, edge, emit([*node.cleanup, Fail(error=escape_label or left)], "Done"))
+
+    def emit(nodes: list[Node], join: str) -> str:
+        """Draw ``nodes``, falling through to ``join``; return the first node's id."""
+        if not nodes:
+            return join
+        node, after = nodes[0], nodes[1:]
+        if isinstance(node, Succeed):
+            return "Done"
+        if isinstance(node, Fail):
+            return error_box(node.error or "Error")
+        rest = emit(after, join)
+
+        if isinstance(node, Step):
+            sid = add("S", f'["{_text(node.name)}"]')
+            link(sid, "ok", rest)
+            error_edges(sid, "err", node, None)
+            return sid
+
+        if isinstance(node, Panic):
+            pid = add("P", f'["{_text(node.name)}"]')
+            if not node.terminal:
+                link(pid, "ok", rest)
+            label = node.error if node.terminal and node.error else "Panic"  # raise X: X
+            error_edges(pid, "raise" if node.terminal else "panic", node, label)
+            return pid
+
+        if isinstance(node, Swallow):
+            wid = add("W", f'["swallow {_text(node.name)}"]')
+            link(wid, "", rest)
+            return wid
+
+        if isinstance(node, Recover):
+            rid = add("R", f'["recover {_text(node.how)}"]')
+            link(rid, "", rest)
+            return rid
+
+        if isinstance(node, Jump):
+            jid = add("J", f'["{_text(node.name)}"]')
+            link(jid, "", rest)
+            return jid
+
+        if isinstance(node, Branch):
+            did = add("D", f'{{"{_text(node.label)}"}}')
+            targets: dict[int, str] = {}
+            # try: draw handlers first so steps in the body can point their errors at them
+            order = [*range(1, len(node.arms)), 0] if node.tag else range(len(node.arms))
+            for i in order:
+                targets[i] = emit(list(node.arms[i].body), rest)
+                if node.tag and i > 0:
+                    handlers[f"{node.tag}#{i}"] = targets[i]
+            for i, arm in enumerate(node.arms):
+                link(did, arm.label, targets[i])
+            return did
+
+        if isinstance(node, Loop):
+            lid = add("L", f'["{_text(node.label)}"]')
+            if node.body:
+                link(lid, "next", emit(list(node.body), lid))  # the body loops back
+            link(lid, "done", rest)
+            return lid
+
+        return rest
+
+    link("Start", "", emit(nodes, "Done"))
+    if errors:
+        lines.append("  classDef error fill:#fdecea,stroke:#d93025,color:#a50e0e")
+        lines.append(f"  class {','.join(errors.values())} error")
+    return "\n".join(lines)
+
+
+def render_function(fn: Function) -> str:
+    return render(fn.name, fn.nodes)

errpath/ir.py

@@ -0,0 +1,274 @@
+"""Versioned error-path IR (aligned with Rust errpath schema_version 1)."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import Enum, StrEnum
+from typing import Any, Literal
+
+SCHEMA_VERSION = 1
+NO_PANIC = "no-panic"
+NO_SWALLOW = "no-swallow"
+
+
+class Confidence(StrEnum):
+    CERTAIN = "certain"
+    LIKELY = "likely"
+    POSSIBLE = "possible"
+
+
+class ErrorSource(StrEnum):
+    CALLEE = "callee"
+    ENCLOSING = "enclosing"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class Arm:
+    label: str
+    body: list[Node]
+
+
+@dataclass
+class Catch:
+    """Where one exception type raised by a step goes: an ``except`` arm of an enclosing try."""
+
+    handler: str  # "<try tag>#<arm index>"
+    how: str  # the handler's label, e.g. "except ValueError"
+    cleanup: list[Node] = field(default_factory=list)  # inner finally nodes run before the handler
+
+
+CATCH_ANY = "*"  # caught_by key: an error of unknown type, caught by a catch-all handler
+
+
+def error_members(error: str | None) -> list[str]:
+    """``"ValueError | KeyError"`` -> ``["ValueError", "KeyError"]``; unknown -> ``[]``."""
+    return [m.strip() for m in error.split("|")] if error else []
+
+
+def escaping(error: str | None, caught_by: dict[str, Catch]) -> str | None:
+    """The part of ``error`` that no handler catches, or None when every part is caught."""
+    members = error_members(error)
+    if not members:
+        return None if CATCH_ANY in caught_by else (error or "Error")
+    left = [m for m in members if m not in caught_by]
+    return " | ".join(left) if left else None
+
+
+@dataclass
+class Step:
+    kind: Literal["step"] = "step"
+    name: str = ""
+    error: str | None = None
+    source: ErrorSource = ErrorSource.UNKNOWN
+    conversions: list[str] = field(default_factory=list)
+    line: int = 0
+    cleanup: list[Node] = field(default_factory=list)  # finally nodes run on the error exit
+    raises: bool = False  # error exits by exception (unwrap), so except can catch it
+    # exception type -> handler; for an unknown error, keyed by each handler type it may match
+    caught_by: dict[str, Catch] = field(default_factory=dict)
+
+
+@dataclass
+class Branch:
+    kind: Literal["branch"] = "branch"
+    label: str = ""
+    arms: list[Arm] = field(default_factory=list)
+    tag: str | None = None  # set on try branches; arm 0 is the normal path, the rest are handlers
+
+
+@dataclass
+class Loop:
+    kind: Literal["loop"] = "loop"
+    label: str = ""
+    tag: str | None = None
+    can_skip: bool = True
+    head: list[Node] = field(default_factory=list)
+    body: list[Node] = field(default_factory=list)
+
+
+@dataclass
+class Scope:
+    kind: Literal["scope"] = "scope"
+    label: str = ""
+    body: list[Node] = field(default_factory=list)
+
+
+@dataclass
+class Fail:
+    kind: Literal["fail"] = "fail"
+    error: str = ""
+    line: int = 0
+
+
+@dataclass
+class Succeed:
+    kind: Literal["succeed"] = "succeed"
+
+
+@dataclass
+class Block:
+    kind: Literal["block"] = "block"
+    tag: str = ""
+    body: list[Node] = field(default_factory=list)
+
+
+@dataclass
+class Jump:
+    kind: Literal["jump"] = "jump"
+    name: str = ""
+    line: int = 0
+
+
+@dataclass
+class Convert:
+    kind: Literal["convert"] = "convert"
+    name: str = ""
+    conversions: list[str] = field(default_factory=list)
+    line: int = 0
+
+
+@dataclass
+class Panic:
+    kind: Literal["panic"] = "panic"
+    name: str = ""
+    terminal: bool = False
+    line: int = 0
+    allowed: str | None = None
+    cleanup: list[Node] = field(default_factory=list)  # finally nodes run on the error exit
+    error: str | None = None  # exception type raised, when known
+    caught_by: dict[str, Catch] = field(default_factory=dict)  # as on Step
+
+
+@dataclass
+class Swallow:
+    kind: Literal["swallow"] = "swallow"
+    name: str = ""
+    how: str = ""
+    confidence: Confidence = Confidence.LIKELY
+    line: int = 0
+    allowed: str | None = None
+
+
+@dataclass
+class Recover:
+    kind: Literal["recover"] = "recover"
+    name: str = ""
+    how: str = ""
+    arms: list[str] = field(default_factory=list)
+    line: int = 0
+
+
+Node = (
+    Step
+    | Branch
+    | Loop
+    | Scope
+    | Fail
+    | Succeed
+    | Block
+    | Jump
+    | Convert
+    | Panic
+    | Swallow
+    | Recover
+)
+
+
+@dataclass
+class ReturnsResult:
+    kind: Literal["result"] = "result"
+    error: str = ""
+
+
+@dataclass
+class ReturnsOption:
+    kind: Literal["option"] = "option"
+
+
+@dataclass
+class ReturnsOther:
+    kind: Literal["other"] = "other"
+
+
+Returns = ReturnsResult | ReturnsOption | ReturnsOther
+
+
+@dataclass
+class Function:
+    id: str
+    name: str
+    file: str
+    line: int
+    returns: Returns
+    nodes: list[Node] = field(default_factory=list)
+    macro_try: int = 0
+
+
+@dataclass
+class Finding:
+    rule: str
+    file: str
+    line: int
+    message: str
+    confidence: Confidence = Confidence.CERTAIN
+    function: str | None = None
+    allowed: str | None = None
+
+
+@dataclass
+class Coverage:
+    functions: int = 0
+    steps: int = 0
+    error_from_callee: int = 0
+    error_from_enclosing: int = 0
+    error_unknown: int = 0
+    macro_try: int = 0
+    item_macro_try: int = 0
+    unanalysed: int = 0
+
+
+@dataclass
+class Unanalysed:
+    """Code errpath saw but couldn't follow, so a diagram may miss a path there."""
+
+    file: str
+    line: int
+    function: str
+    code: str
+    reason: str
+
+
+@dataclass
+class ParseFailure:
+    file: str
+    message: str
+
+
+@dataclass
+class Report:
+    schema_version: int = SCHEMA_VERSION
+    coverage: Coverage = field(default_factory=Coverage)
+    functions: list[Function] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+    parse_failures: list[ParseFailure] = field(default_factory=list)
+    unanalysed: list[Unanalysed] = field(default_factory=list)
+    support_files_skipped: int = 0
+
+
+def _enum_to_value(obj: Any) -> Any:
+    if isinstance(obj, Enum):
+        return obj.value
+    if isinstance(obj, list):
+        return [_enum_to_value(x) for x in obj]
+    if isinstance(obj, dict):
+        return {k: _enum_to_value(v) for k, v in obj.items()}
+    return obj
+
+
+def to_dict(obj: Any) -> Any:
+    """Serialize dataclasses (and nested Enums) to JSON-ready dicts."""
+    if hasattr(obj, "__dataclass_fields__"):
+        raw = asdict(obj)
+        return _enum_to_value(raw)
+    return _enum_to_value(obj)