mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/verify/crashes.py

@@ -0,0 +1,321 @@
+import json
+import re
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from .. import secret_filter
+
+DIAGNOSTIC_REPORTS = Path.home() / "Library" / "Logs" / "DiagnosticReports"
+CRASH_BUG_TYPE = "309"
+TOP_FRAMES = 8
+MAX_REPORT_BYTES = 8 * 1024 * 1024
+MAX_DSYMS = 24
+TOOL_TIMEOUT = 15
+MESSAGE_LIMIT = 400
+TIME_FORMATS = ("%Y-%m-%d %H:%M:%S.%f %z", "%Y-%m-%d %H:%M:%S %z")
+ATOS_LINE = re.compile(r"^(?P<symbol>.+?) \(in (?P<image>[^)]+)\)(?: \((?P<file>[^():]+):(?P<line>\d+)\))?\s*$")
+SYSTEM_PREFIXES = ("/System/", "/usr/lib/", "/Library/Developer/CoreSimulator/Volumes/", "/Applications/Xcode")
+
+
+@dataclass
+class Report:
+    path: Path
+    header: dict
+    body: dict
+
+    @property
+    def bundle_id(self):
+        return self.header.get("bundleID") or (self.body.get("bundleInfo") or {}).get("CFBundleIdentifier")
+
+    @property
+    def process(self):
+        return self.body.get("procName") or self.header.get("name") or self.header.get("app_name")
+
+    @property
+    def pid(self):
+        pid = self.body.get("pid")
+        return pid if isinstance(pid, int) and not isinstance(pid, bool) else None
+
+    @property
+    def wall(self):
+        """The crash time as seconds since the epoch: the body's captureTime, else the header's timestamp."""
+        return parse_time(self.body.get("captureTime")) or parse_time(self.header.get("timestamp"))
+
+
+def parse_time(text):
+    if not isinstance(text, str):
+        return None
+    for form in TIME_FORMATS:
+        try:
+            return datetime.strptime(text.strip(), form).timestamp()
+        except ValueError:
+            continue
+    return None
+
+
+def read(path):
+    """The crash report at ``path``, or None when it isn't one an app crash wrote (or can't be read)."""
+    path = Path(path)
+    try:
+        if path.stat().st_size > MAX_REPORT_BYTES:
+            return None
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    first, _, rest = text.partition("\n")
+    try:
+        header, body = json.loads(first), json.loads(rest)
+    except ValueError:
+        return None
+    if not isinstance(header, dict) or not isinstance(body, dict):
+        return None
+    if str(header.get("bug_type")
+           or body.get("bug_type")) != CRASH_BUG_TYPE or not isinstance(body.get("threads"), list):
+        return None
+    return Report(path, header, body)
+
+
+def candidates(folder, executable, since):
+    """The .ips files in ``folder`` (and its Retired folder) named for ``executable`` and changed since ``since`` (epoch
+    seconds), newest first."""
+    out = []
+    for directory in (Path(folder), Path(folder) / "Retired"):
+        try:
+            entries = list(directory.iterdir())
+        except OSError:
+            continue
+        for path in entries:
+            if not path.name.startswith(f"{executable}-") or not path.name.endswith(".ips"):
+                continue
+            try:
+                changed = path.stat().st_mtime
+            except OSError:
+                continue
+            if changed >= since:
+                out.append((changed, path))
+    return [path for _, path in sorted(out, reverse=True)]
+
+
+def belongs(report, *, bundle_id, executable, since, until=None, pids=(), udid=None):
+    # Two simulators running the same app never take each other's crash, nor a second crash on the same one.
+    named = report.bundle_id == bundle_id if report.bundle_id else (executable and report.process == executable)
+    if not named:
+        return False
+    wall = report.wall
+    if wall is None or wall < since or (until is not None and wall > until):
+        return False
+    if pids:
+        return report.pid is not None and report.pid in set(pids)
+    if udid:
+        where = f"{report.body.get('procPath') or ''} {report.body.get('coalitionName') or ''}"
+        return udid in where
+    return True
+
+
+def _thread(body):
+    threads = body.get("threads") or []
+    index = body.get("faultingThread")
+    if isinstance(index, int) and 0 <= index < len(threads) and isinstance(threads[index], dict):
+        return threads[index]
+    return next((thread for thread in threads if isinstance(thread, dict) and thread.get("triggered")), None)
+
+
+def message(body):
+    asi = body.get("asi")
+    if isinstance(asi, dict):
+        for lines in asi.values():
+            for line in lines if isinstance(lines, list) else [lines]:
+                if isinstance(line, str) and line.strip():
+                    return _clean(line)
+    termination = body.get("termination") or {}
+    for key in ("details", "reasons"):
+        value = termination.get(key)
+        if isinstance(value, list) and value and isinstance(value[0], str):
+            return _clean(value[0])
+    return None
+
+
+def _clean(text):
+    text = " ".join(str(text).split())
+    return text[:MESSAGE_LIMIT]
+
+
+def frames(report, top=TOP_FRAMES, executable=None):
+    body = report.body
+    thread = _thread(body) or {}
+    images = body.get("usedImages") or []
+    out = []
+    for index, frame in enumerate((thread.get("frames") or [])[:top]):
+        if not isinstance(frame, dict):
+            continue
+        image_index = frame.get("imageIndex")
+        image = images[image_index] if isinstance(image_index, int) and 0 <= image_index < len(images) else {}
+        base, offset = image.get("base"), frame.get("imageOffset")
+        out.append({"index": index, "image": image.get("name") or "???", "own": _own_image(image, executable),
+                    "symbol": frame.get("symbol"),
+                    "offset": frame.get("symbolLocation"), "file": frame.get("sourceFile"),
+                    "line": frame.get("sourceLine"), "imageIndex": image_index,
+                    "address": base + offset if isinstance(base, int) and isinstance(offset, int) else None})
+    return out
+
+
+def summary(report, *, executable=None, dsyms=(), run=subprocess.run, top=TOP_FRAMES):
+    """{type, signal, subtype, message, thread, frames, symbolicated}: what a person needs to see first."""
+    body = report.body
+    exception = body.get("exception") or {}
+    thread = _thread(body) or {}
+    stack = frames(report, top, executable or report.process)
+    symbolicated = symbolicate(stack, body.get("usedImages") or [], dsyms, executable=executable, run=run)
+    demangle(stack, run=run)
+    for frame in stack:
+        frame.pop("imageIndex", None)
+        frame.pop("address", None)
+    return {"type": exception.get("type"), "signal": exception.get("signal"), "subtype": exception.get("subtype"),
+            "message": message(body), "thread": thread.get("queue") or thread.get("name"),
+            "process": report.process, "pid": report.pid, "frames": stack, "symbolicated": symbolicated}
+
+
+def headline(summary_, app_name):
+    """One sentence for the verdict: what crashed, how, and where in the app's own code."""
+    what = summary_.get("message") or " ".join(filter(None, [summary_.get("type"), f"({summary_['signal']})"
+                                                              if summary_.get("type") and summary_.get("signal")
+                                                              else summary_.get("signal")]))
+    where = first_own_frame(summary_)
+    text = f"{app_name} crashed" + (f": {what}" if what else "")
+    if where:
+        text += f", in {where}"
+    return text.rstrip(".") + "."
+
+
+def first_own_frame(summary_):
+    """'CrashTrigger.crashNow() (ContentView.swift:23)': the first frame in the app's own image, else None."""
+    for frame in summary_.get("frames") or ():
+        if frame.get("own") and frame.get("symbol"):
+            return frame_text(frame, image=False)
+    return None
+
+
+def frame_text(frame, image=True):
+    symbol = frame.get("symbol") or (f"0x{frame['address']:x}" if frame.get("address") else "???")
+    where = f" ({frame['file']}:{frame['line']})" if frame.get("file") and frame.get("line") else ""
+    return (f"{frame.get('image')}  " if image else "") + symbol + where
+
+
+def find_dsyms(app_path=None, root=None):
+    found = []
+    if app_path:
+        app = Path(app_path)
+        found.append(app.parent / f"{app.name}.dSYM")
+    if root:
+        products = Path(root) / ".mobster" / "build" / "Build" / "Products"
+        try:
+            for config in sorted(products.iterdir()):
+                found.extend(sorted(config.glob("*.dSYM")) if config.is_dir() else [])
+        except OSError:
+            pass
+    unique = []
+    for path in found:
+        if path.is_dir() and path not in unique:
+            unique.append(path)
+    return unique[:MAX_DSYMS]
+
+
+def _uuid(text):
+    return re.sub(r"[^0-9A-F]", "", str(text or "").upper())
+
+
+def dsym_uuids(dsym, run=subprocess.run):
+    """{UUID (hex, upper case, no dashes): the DWARF file inside the dSYM} from ``dwarfdump --uuid``."""
+    try:
+        done = run(["/usr/bin/xcrun", "dwarfdump", "--uuid", str(dsym)], capture_output=True, text=True,
+                   timeout=TOOL_TIMEOUT, stdin=subprocess.DEVNULL)
+    except (OSError, subprocess.SubprocessError):
+        return {}
+    out = {}
+    for line in (done.stdout or "").splitlines():
+        match = re.match(r"UUID: ([0-9A-Fa-f-]+) \(\S+\) (.+)$", line.strip())
+        if match:
+            out[_uuid(match.group(1))] = match.group(2)
+    return out
+
+
+def _own_image(image, executable):
+    path = str(image.get("path") or "")
+    if executable and image.get("name") == executable:
+        return True
+    return ".app/" in path and not path.startswith(SYSTEM_PREFIXES)
+
+
+def symbolicate(stack, images, dsyms, *, executable=None, run=subprocess.run):
+    """Name the app's own frames with ``atos`` and a dSYM whose UUID matches their image."""
+    wanted = {}
+    for frame in stack:
+        index = frame.get("imageIndex")
+        if not isinstance(index, int) or not 0 <= index < len(images) or frame.get("address") is None:
+            continue
+        if frame.get("own") and not (frame.get("symbol") and frame.get("file")):
+            wanted.setdefault(index, []).append(frame)
+    if not wanted or not dsyms:
+        return False
+    files = {}
+    for dsym in dsyms:
+        files.update(dsym_uuids(dsym, run=run))
+    named = False
+    for index, todo in wanted.items():
+        image = images[index]
+        dwarf = files.get(_uuid(image.get("uuid")))
+        base = image.get("base")
+        if not dwarf or not isinstance(base, int):
+            continue
+        argv = ["/usr/bin/xcrun", "atos", "-arch", str(image.get("arch") or "arm64"), "-o", dwarf, "-l", hex(base)]
+        argv += [hex(frame["address"]) for frame in todo]
+        try:
+            done = run(argv, capture_output=True, text=True, timeout=TOOL_TIMEOUT, stdin=subprocess.DEVNULL)
+        except (OSError, subprocess.SubprocessError):
+            continue
+        for frame, line in zip(todo, (done.stdout or "").splitlines()):
+            match = ATOS_LINE.match(line.strip())
+            if not match:
+                continue
+            frame["symbol"] = match.group("symbol")
+            if match.group("file"):
+                frame["file"], frame["line"] = match.group("file"), int(match.group("line"))
+            frame["offset"] = None
+            named = True
+    return named
+
+
+def demangle(stack, run=subprocess.run):
+    """Swift's mangled names ($s…) made readable with ``swift-demangle``, in place; the rest stay."""
+    mangled = [frame for frame in stack if str(frame.get("symbol") or "").lstrip("_").startswith("$s")]
+    if not mangled:
+        return
+    try:
+        done = run(["/usr/bin/xcrun", "swift-demangle", "--compact", "--simplified"],
+                   input="\n".join(frame["symbol"] for frame in mangled), capture_output=True, text=True,
+                   timeout=TOOL_TIMEOUT)
+    except (OSError, subprocess.SubprocessError):
+        return
+    lines = (done.stdout or "").splitlines()
+    if len(lines) == len(mangled):
+        for frame, line in zip(mangled, lines):
+            if line.strip():
+                frame["symbol"] = line.strip()
+
+
+def write_copy(report, folder):
+    # Every string goes through the secret filter; numbers, such as frame offsets, are kept as they are.
+    folder = Path(folder)
+    folder.mkdir(parents=True, exist_ok=True)
+    target = folder / report.path.name
+    header = secret_filter.redact_deep(report.header)
+    body = secret_filter.redact_deep(report.body)
+    target.write_text(json.dumps(header, ensure_ascii=False) + "\n" + json.dumps(body, indent=2, ensure_ascii=False)
+                      + "\n", encoding="utf-8")
+    return target
+
+
+__all__ = ["Report", "read", "candidates", "belongs", "summary", "headline", "frame_text", "find_dsyms",
+           "symbolicate", "write_copy", "DIAGNOSTIC_REPORTS"]

mobile_agent/verify/device_audit.py

@@ -0,0 +1,246 @@
+"""Apple's own accessibility audit, run on the iPhone (`audit: ax-device`, experimental).
+
+The phone's accessibility audit daemon (``com.apple.accessibility.axAuditDaemon.remoteserver``) checks contrast, hit
+regions, element descriptions, clipped text and Dynamic Type on the screen that is up, with no model and no pixels sent
+anywhere. Mobster asks for it through ``pymobiledevice3 developer accessibility``, a separate program you install
+yourself (``pipx install pymobiledevice3``), over the tunnel macOS keeps to an iPhone paired for development
+(``--native``, iOS 17 or later). Mobster never imports pymobiledevice3: it reads the JSON the program prints. A
+simulator has no such service, so on a simulator the check reports one note and the tree audit (a11y.py) is what covers
+the screen.
+"""
+
+import json
+import os
+import re
+import subprocess
+
+from ..phone_io import tunnel
+
+__all__ = ["NAME", "SETTING", "enabled", "findings_from_issues", "Collector"]
+
+NAME = "ax-device"
+SETTING = "MOBSTER_EXPERIMENTAL_AUDIT"
+TIMEOUT = 45.0  # seconds for one command: each opens macOS's tunnel to the phone again (about 7 s, phone_io/tunnel.py)
+LIMIT = 30  # screens per run: an audit takes seconds on the phone
+UDID = re.compile(r"[0-9A-Fa-f-]{24,40}")
+AUDIT_TYPE = re.compile(r"[A-Za-z0-9_]{1,64}")
+NO_TOOL = (
+    "The on-device audit runs pymobiledevice3, which isn't on this Mac. Install it with "
+    "`pipx install pymobiledevice3`, then run again."
+)
+# issue_classification (pymobiledevice3 names the classification it knows) -> (rule id, guideline, what to do)
+RULES = {
+    "testTypeContrast": (
+        "device-contrast",
+        "WCAG 1.4.3",
+        "its text contrast is too low. Darken the text or lighten the background.",
+    ),
+    "testTypeHitRegion": (
+        "device-hit-region",
+        "HIG 44 pt",
+        "its tap area is too small. Make the control or its tappable area at least 44 pt.",
+    ),
+    "testTypeSufficientElementDescription": (
+        "device-description",
+        "WCAG 4.1.2",
+        "VoiceOver has no good description for it. Give it an accessibility label.",
+    ),
+    "testTypeElementDetection": (
+        "device-element-detection",
+        "WCAG 4.1.2",
+        "it looks like a control the app doesn't expose. Make it an accessibility element.",
+    ),
+    "testTypeTextClipped": (
+        "device-text-clipped",
+        "WCAG 1.4.4",
+        "its text is clipped. Let the text wrap or the container grow.",
+    ),
+    "testTypeDynamicText": (
+        "device-dynamic-text",
+        "WCAG 1.4.4",
+        "its text doesn't follow the Dynamic Type size. Use a text style or scaled font.",
+    ),
+}
+RECT = re.compile(r"-?\d+(?:\.\d+)?")
+
+
+def enabled():
+    return os.environ.get(SETTING, "").strip().lower() in ("1", "on", "true", "yes")
+
+
+def _rect(value):
+    numbers = [float(n) for n in RECT.findall(value)] if isinstance(value, str) else []
+    return numbers if len(numbers) == 4 else [0.0, 0.0, 0.0, 0.0]
+
+
+def _note(rule, message, evidence, frame):
+    return {
+        "id": rule,
+        "audit": NAME,
+        "guideline": None,
+        "level": "review",
+        "frame": frame,
+        "message": message,
+        "evidence": evidence,
+        "element": None,
+    }
+
+
+def findings_from_issues(issues, frame=None):
+    """Run findings from the audit's issues, as ``run-audit`` prints them. An issue of a kind this table doesn't know is
+    kept, as a review."""
+    out = []
+    for issue in issues:
+        kind = str(issue.get("issue_classification"))
+        rule, guideline, advice = RULES.get(kind, (f"device-{kind}", None, "Apple's audit flagged it. Check it."))
+        rect = _rect(issue.get("element_rect_value"))
+        where = f"at {rect[0]:g}, {rect[1]:g}, {rect[2]:g} x {rect[3]:g} pt"
+        detail = issue.get("ml_generated_description") or issue.get("long_description_extra_info")
+        name = f" ({detail})" if isinstance(detail, str) and detail.strip() else ""
+        out.append(
+            {
+                "id": rule,
+                "audit": NAME,
+                "guideline": guideline,
+                "level": "review",
+                "frame": frame,
+                "message": f"The element{name} {where}: {advice}",
+                "evidence": f"{kind} {where}",
+                "element": {"role": "", "label": "", "identifier": "", "path": "", "rect": rect},
+            }
+        )
+    return out
+
+
+class ToolMissing(RuntimeError):
+    """pymobiledevice3 isn't on this Mac."""
+
+
+class Unavailable(RuntimeError):
+    """The audit gave no answer Mobster can read. The message names the reason only, never the phone's or the app's
+    text."""
+
+
+def run_tool(argv, timeout):
+    """(exit code, standard output) of one pymobiledevice3 command, run as a separate program for at most ``timeout``
+    seconds. Its standard error is dropped: a finding never carries the program's own text."""
+    from ..native_helpers import require_devices
+
+    require_devices()
+    env = dict(os.environ, NO_COLOR="1", TERM="dumb", COLUMNS="200")
+    try:
+        done = subprocess.run(argv, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, stdin=subprocess.DEVNULL,
+                              text=True, errors="replace", timeout=timeout, env=env)
+    except subprocess.TimeoutExpired:
+        raise Unavailable(f"pymobiledevice3 didn't finish in {timeout:g} seconds") from None
+    except OSError as error:
+        raise Unavailable(f"pymobiledevice3 couldn't start ({type(error).__name__})") from None
+    return done.returncode, done.stdout
+
+
+def command(program, udid, *args):
+    """``pymobiledevice3 developer accessibility <args>`` for the iPhone ``udid``, over macOS's own tunnel."""
+    if not isinstance(udid, str) or not UDID.fullmatch(udid):
+        raise Unavailable("the run's device has no iPhone identifier")
+    return [program, "developer", "accessibility", *args, "--native", "--udid", udid]
+
+
+def audit_types(value):
+    """The audit types the phone supports, as ``supported-audit-types`` prints them: JSON strings only. None is no
+    answer, never "audit nothing": an empty list, or numbers ``run-audit`` would get as text, could pass every screen
+    unchecked."""
+    types = value if isinstance(value, list) else []
+    if not types or not all(isinstance(item, str) and AUDIT_TYPE.fullmatch(item) for item in types):
+        raise Unavailable("pymobiledevice3 listed no audit types")
+    return types
+
+
+def audit_issues(value):
+    """The issues ``run-audit`` printed: a list of objects, or no answer."""
+    if not isinstance(value, list) or not all(isinstance(item, dict) for item in value):
+        raise Unavailable("pymobiledevice3 printed no list of issues")
+    return value
+
+
+class Collector:
+    """The audit's findings for a run; ``add`` audits the screen that is up on the phone, once per distinct screen."""
+
+    def __init__(self, udid_of, *, program=tunnel.tool, run=run_tool):
+        self._udid_of = udid_of  # () -> the real iPhone's UDID, or None on a simulator
+        self._program, self._run = program, run  # () -> pymobiledevice3's path or None; (argv, timeout) -> (code, out)
+        self._types = None  # the phone's audit types, read once a run
+        self._seen, self._found, self._noted = set(), [], False
+
+    def _note_once(self, rule, message, evidence):
+        if not self._noted:
+            self._noted = True
+            self._found.append(_note(rule, message, evidence, None))
+
+    def _read(self, argv):
+        code, output = self._run(argv, TIMEOUT)
+        if code != 0:
+            raise Unavailable(f"pymobiledevice3 exited {code}")
+        try:
+            return json.loads(output)
+        except ValueError:
+            raise Unavailable("pymobiledevice3 printed no JSON") from None
+
+    def _audit(self, udid):
+        program = self._program()
+        if not program:
+            raise ToolMissing()
+        if self._types is None:
+            self._types = audit_types(self._read(command(program, udid, "supported-audit-types")))
+        return audit_issues(self._read(command(program, udid, "run-audit", *self._types)))
+
+    def add(self, tree, frame=None):
+        if not enabled():
+            return self._note_once(
+                "device-audit-off",
+                f"The on-device audit is experimental. Set {SETTING}=1 to run it.",
+                f"{SETTING} is not set",
+            )
+        udid = self._udid_of()
+        if udid is None:
+            return self._note_once(
+                "device-audit-simulator",
+                "The on-device audit needs a real iPhone: a simulator "
+                "has no audit service. The accessibility tree audit (`audit: a11y`) covers "
+                "this screen.",
+                "the run's device is a simulator",
+            )
+        fingerprint = tree.fingerprint()
+        if fingerprint in self._seen or len(self._seen) >= LIMIT:
+            return None
+        self._seen.add(fingerprint)
+        try:
+            issues = self._audit(udid)
+        except ToolMissing:
+            return self._note_once("device-audit-no-tool", NO_TOOL, "pymobiledevice3 is not installed")
+        except Exception as error:
+            reason = str(error) if isinstance(error, Unavailable) else type(error).__name__
+            return self._note_once(
+                "device-audit-unavailable",
+                f"The iPhone's audit service didn't answer ({reason}). It needs iOS 17 or later, paired with this Mac "
+                "for development, unlocked, in Developer Mode and with the developer disk image mounted. Fix what's "
+                "missing, then run again.",
+                f"{reason} from the audit",
+            )
+        self._found.extend(findings_from_issues(issues, frame))
+        return None
+
+    @property
+    def screens(self):
+        return len(self._seen)
+
+    def findings(self):
+        return list(self._found)
+
+
+def for_run(run, audit):
+    """The collector for ``run`` when its check audits ``ax_device``, else None. It asks for the iPhone's UDID when it
+    reads: None on a simulator or before a device is held."""
+    from .smart import is_real_device
+    if NAME not in audit:
+        return None
+    return Collector(lambda: getattr(run.target, "udid", None) if is_real_device(run._manager()) else None)