mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/verify/fixtures.py

@@ -0,0 +1,305 @@
+"""Fixtures (.mobster/fixtures/<name>.yaml): what changes a device's state is for simulators, refused on a phone."""
+
+import os
+import re
+import shutil
+import subprocess
+from contextlib import nullcontext
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+
+from . import dialogs as dialog_policy
+from .assertions import CheckError
+
+FOLDER = "fixtures"
+SUFFIXES = (".yaml", ".yml")
+NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,59}")
+KEYS = ("extends", "reset", "launch", "files", "keychain", "pasteboard", "steps", "dialogs")
+DEPTH = 6
+FILES_LIMIT = 50
+BYTES_LIMIT = 20 * 1024 * 1024
+PASTEBOARD_LIMIT = 10_000
+PHONE_REFUSAL = "{what} changes the state of a phone, and fixtures do that on simulators only (from {name})."
+PHONE_FIX = "Run the check on a simulator, or use a fixture with only launch args, env and steps on the phone."
+
+
+class FixtureError(Exception):
+    """A fixture can't be read, found or applied: one sentence that says what to do."""
+
+
+@dataclass(frozen=True)
+class Effective:
+    """A fixture and what it extends, flattened."""
+    names: tuple = ()
+    reset: str = "none"
+    args: tuple = ()
+    env: dict = field(default_factory=dict)
+    steps: tuple = ()
+    files: tuple = ()            # of (absolute source, destination relative to the container)
+    keychain: bool = False
+    pasteboard: str = ""
+    dialogs: dict = field(default_factory=dict)   # how a run answers iOS's own dialogs (dialogs.py)
+
+    @property
+    def changes_state(self):
+        """What a real iPhone must not get: a reset, files, a keychain reset or a clipboard."""
+        return [word for word, held in (("a reset", self.reset != "none"), ("seed files", bool(self.files)),
+                                        ("a keychain reset", self.keychain), ("a pasteboard", bool(self.pasteboard)))
+                if held]
+
+    def public(self):
+        return {"names": list(self.names), "reset": self.reset, "args": list(self.args), "env": dict(self.env),
+                "steps": list(self.steps), "files": [{"from": str(src), "to": dest} for src, dest in self.files],
+                "keychain": self.keychain, "pasteboard": bool(self.pasteboard), "dialogs": dict(self.dialogs),
+                "destructive": bool(self.changes_state)}
+
+
+def folder(root):
+    return Path(root) / ".mobster" / FOLDER
+
+
+def path_of(root, name):
+    for suffix in SUFFIXES:
+        path = folder(root) / f"{name}{suffix}"
+        if path.is_file():
+            return path
+    return None
+
+
+def names(root):
+    """Every fixture's name in the project, sorted."""
+    base = folder(root)
+    if not base.is_dir():
+        return []
+    return sorted({path.stem for path in base.iterdir() if path.suffix in SUFFIXES and NAME.fullmatch(path.stem)})
+
+
+def _load(root, name):
+    """One fixture file as a dict of validated parts (not yet flattened)."""
+    from . import checks
+    path = path_of(root, name)
+    if path is None:
+        have = ", ".join(names(root)[:8])
+        raise FixtureError(f"There's no fixture called {name}." + (f" You have: {have}." if have else
+                           " Add .mobster/fixtures/NAME.yaml."))
+    import yaml
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError):
+        raise FixtureError(f"{path.name} can't be read. Check that it is a text file.") from None
+    except yaml.YAMLError:
+        raise FixtureError(f"{path.name} isn't valid YAML.") from None
+    if data is None:
+        data = {}
+    if not isinstance(data, dict) or set(data) - set(KEYS):
+        bad = sorted(set(data) - set(KEYS))[0] if isinstance(data, dict) else None
+        raise FixtureError(f"{path.name}: " + (f"`{str(bad)[:40]}` isn't a fixture key. Use {', '.join(KEYS)}."
+                                              if bad is not None else "a fixture is a mapping of keys."))
+    where = path.name
+    try:
+        extends = data.get("extends") or []
+        extends = [extends] if isinstance(extends, str) else extends
+        if not isinstance(extends, list) or not all(isinstance(item, str) and NAME.fullmatch(item) for item in extends):
+            raise CheckError("extends is a fixture name or a list of them")
+        reset = data.get("reset")
+        if reset is not None and reset not in checks.RESETS:
+            raise CheckError(f"reset is one of {', '.join(checks.RESETS)}, not {reset!r}")
+        launch = data.get("launch") or {}
+        if not isinstance(launch, dict) or set(launch) - {"args", "env"}:
+            raise CheckError("launch holds args and env")
+        args = checks._strings(launch.get("args"), "launch.args", checks.LIMITS["args"])
+        env = checks._env(launch.get("env"), "launch.env")
+        steps = checks._steps(data.get("steps"))
+        keychain = data.get("keychain")
+        if keychain not in (None, "reset", False):
+            raise CheckError("keychain is reset")
+        pasteboard = data.get("pasteboard") or ""
+        if not isinstance(pasteboard, str) or len(pasteboard) > PASTEBOARD_LIMIT:
+            raise CheckError(f"pasteboard is text of at most {PASTEBOARD_LIMIT:,} characters")
+        files = _files(data.get("files"), folder(root))
+        answers = dialog_policy.parse(data.get("dialogs"))
+    except CheckError as error:
+        raise FixtureError(f"{where}: {error}") from None
+    return {"extends": extends, "reset": reset, "args": args, "env": env, "steps": steps, "files": files,
+            "keychain": keychain == "reset", "pasteboard": pasteboard, "dialogs": answers}
+
+
+def _files(value, base):
+    if value is None:
+        return ()
+    if not isinstance(value, list) or len(value) > FILES_LIMIT:
+        raise CheckError(f"files is a list of at most {FILES_LIMIT} entries with from and to")
+    out = []
+    for index, item in enumerate(value, 1):
+        if (not isinstance(item, dict) or set(item) != {"from", "to"}
+                or not all(isinstance(v, str) for v in item.values())):
+            raise CheckError(f"files[{index}] needs from and to, both text")
+        source = (Path(base) / item["from"])
+        real = Path(os.path.realpath(source))
+        if Path(item["from"]).is_absolute() or ".." in Path(item["from"]).parts or not real.exists() or \
+                not (real == Path(os.path.realpath(base)) or Path(os.path.realpath(base)) in real.parents):
+            raise CheckError(f"files[{index}].from {item['from']!r} must be a file or folder inside .mobster/{FOLDER}/")
+        dest = Path(item["to"])
+        if not item["to"].strip() or dest.is_absolute() or ".." in dest.parts or str(dest) in (".", ""):
+            raise CheckError(f"files[{index}].to {item['to']!r} must be a path inside the app's container, such as "
+                             "Documents/cart.json")
+        out.append((real, dest.as_posix()))
+    return tuple(out)
+
+
+def resolve(root, wanted):
+    """The flattened Effective of the fixture names in ``wanted``, in order."""
+    state = {"names": [], "reset": "none", "args": [], "env": {}, "steps": [], "files": {}, "keychain": False,
+             "pasteboard": "", "dialogs": {}}
+    done = []
+
+    def add(name, chain):
+        if name in chain:
+            raise FixtureError(f"Fixtures extend each other in a circle: {' → '.join([*chain, name])}.")
+        if len(chain) >= DEPTH:
+            raise FixtureError(f"Fixtures extend more than {DEPTH} deep, ending at {name}.")
+        if name in done:
+            return
+        part = _load(root, name)
+        for parent in part["extends"]:
+            add(parent, (*chain, name))
+        done.append(name)
+        state["names"].append(name)
+        if part["reset"] is not None:
+            state["reset"] = part["reset"]
+        state["args"] += part["args"]
+        state["env"].update(part["env"])
+        state["steps"] += part["steps"]
+        for source, dest in part["files"]:
+            state["files"][dest] = source
+        state["keychain"] = state["keychain"] or part["keychain"]
+        state["pasteboard"] = part["pasteboard"] or state["pasteboard"]
+        state["dialogs"] = dialog_policy.merge(state["dialogs"], part["dialogs"])
+
+    for name in wanted:
+        if not isinstance(name, str) or not NAME.fullmatch(name):
+            raise FixtureError(
+                "A fixture name is 1 to 60 lowercase letters, digits or hyphens, starting with a letter or digit.")
+        add(name, ())
+    return Effective(names=tuple(state["names"]), reset=state["reset"], args=tuple(state["args"]),
+                     env=dict(state["env"]), steps=tuple(state["steps"]),
+                     files=tuple((source, dest) for dest, source in state["files"].items()),
+                     keychain=state["keychain"], pasteboard=state["pasteboard"], dialogs=dict(state["dialogs"]))
+
+
+def with_fixtures(check, root):
+    if not check.fixture or check.fixture_origin is not None:
+        return check
+    effective = resolve(root, check.fixture)
+    return replace(check, fixture_origin=check,
+                   reset=effective.reset if check.reset == "auto" and effective.reset != "none" else check.reset,
+                   launch_args=effective.args + check.launch_args,
+                   launch_env={**effective.env, **check.launch_env}, steps=effective.steps + check.steps,
+                   dialogs=dialog_policy.merge(effective.dialogs, check.dialogs),
+                   seed=Seed(effective.files, effective.keychain, effective.pasteboard, tuple(effective.changes_state)))
+
+
+def for_run(check, runs_dir):
+    """The check with its fixtures flattened in. The project is the folder that holds ``.mobster/`` beside the runs,
+    else the folder the check was read from; a check that names a fixture with no project to take it from is refused
+    before any simulator is touched."""
+    if not check.fixture or check.fixture_origin is not None:
+        return check
+    from .checks import project_root
+    runs_dir = Path(runs_dir)
+    root = runs_dir.parent.parent if runs_dir.parent.name == ".mobster" else None
+    if root is None and check.source:
+        root = project_root(check.source)
+    if root is None:
+        raise FixtureError(f"This check uses the fixture {', '.join(check.fixture)}, which comes from a project's "
+                           ".mobster/fixtures/. Run it from a project folder that has .mobster/, with --out left at "
+                           "its default.")
+    return with_fixtures(check, root)
+
+
+@dataclass(frozen=True)
+class Seed:
+    files: tuple = ()
+    keychain: bool = False
+    pasteboard: str = ""
+    risky: tuple = ()            # what the fixtures change that a real iPhone must not get (Effective.changes_state)
+
+    def __bool__(self):
+        return bool(self.files or self.keychain or self.pasteboard)
+
+
+def refuse_on_phone(check):
+    """FixtureError when the check's fixtures would change a real iPhone's state."""
+    if check.seed.risky:
+        raise FixtureError(PHONE_REFUSAL.format(what=check.seed.risky[0], name=", ".join(check.fixture))
+                           + " " + PHONE_FIX)
+
+
+def seed_simulator(seed, *, udid, bundle, run, pbcopy=None, actions=None):
+    """Put the seed on simulator ``udid``: the keychain emptied, the files copied into ``bundle``'s data container and
+    the pasteboard set."""
+    did = []
+    if seed.keychain:
+        with actions.action("FIXTURE_KEYCHAIN") if actions is not None else nullcontext():
+            code, out = run(["keychain", udid, "reset"])
+            if code != 0:
+                raise FixtureError(f"The simulator's keychain wouldn't reset ({out[:120] or code}).")
+        did.append("keychain reset")
+    if seed.files:
+        code, container = run(["get_app_container", udid, bundle, "data"])
+        if code != 0 or not container.strip() or container.strip() == "(null)":
+            raise FixtureError(f"{bundle} isn't installed on the simulator, so there is no container to put files in.")
+        count = _copy(seed.files, container.strip(), udid, actions=actions)
+        did.append(f"{count} file{'' if count == 1 else 's'} copied")
+    if seed.pasteboard:
+        with actions.action("FIXTURE_PASTEBOARD") if actions is not None else nullcontext():
+            (pbcopy or _pbcopy)(udid, seed.pasteboard)
+        did.append("pasteboard set")
+    return did
+
+
+def _pbcopy(udid, text):
+    try:
+        done = subprocess.run(["xcrun", "simctl", "pbcopy", udid], input=text, text=True, capture_output=True,
+                              timeout=30)
+    except (OSError, subprocess.TimeoutExpired):
+        raise FixtureError("The simulator's pasteboard wouldn't set.") from None
+    if done.returncode != 0:
+        raise FixtureError("The simulator's pasteboard wouldn't set.")
+
+
+def _copy(files, container, udid, *, actions=None):
+    from ..sim import apps
+    from ..sim.api import SimError
+    try:
+        root = apps.guard_container(container, udid)
+    except SimError as error:
+        raise FixtureError(str(error)) from None
+    total = count = 0
+    plan = []
+    for source, dest in files:
+        target = (root / dest)
+        for path in ([source] if source.is_file() else sorted(p for p in source.rglob("*"))):
+            if path.is_symlink():
+                raise FixtureError(f"{path.name} is a symbolic link, so Mobster didn't copy it.")
+            if path.is_file():
+                total += path.stat().st_size
+                count += 1
+                plan.append((path, target if source.is_file() else target / path.relative_to(source)))
+    if count > FILES_LIMIT * 4 or total > BYTES_LIMIT:
+        raise FixtureError(f"The seed files are {count} files and {total // 1024} KB; the limit is "
+                           f"{FILES_LIMIT * 4} files and {BYTES_LIMIT // 1024 // 1024} MB.")
+    for _, target in plan:
+        for parent in [target, *target.parents]:
+            if parent == root:
+                break
+            if parent.is_symlink():
+                raise FixtureError(f"{target.relative_to(root)} goes through a symbolic link in the container, so "
+                                   "Mobster didn't copy it.")
+        if root not in Path(os.path.realpath(target)).parents:
+            raise FixtureError(f"{target.relative_to(root)} leaves the app's container, so Mobster didn't copy it.")
+    for path, target in plan:
+        with actions.action("FIXTURE_FILE") if actions is not None else nullcontext():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(path, target)
+    return count

mobile_agent/verify/flow.py

@@ -0,0 +1,213 @@
+import base64
+import time
+
+from .smart import LEFT_APP, LEFT_APP_FIX, check_approver, check_guard, no_smart_key, smart_request
+from .verdict import CouldntRun
+
+NOTE_LIMIT = 500
+
+
+def _safe(cancelled):
+    try:
+        return bool(cancelled())
+    except Exception:
+        return False
+
+
+def _data_url_bytes(url):
+    if not isinstance(url, str) or not url.startswith("data:") or "," not in url:
+        return None
+    try:
+        return base64.b64decode(url.split(",", 1)[1])
+    except (ValueError, TypeError):
+        return None
+
+
+class Flow:
+    def run_smart(self, cancelled=None):
+        from .. import costs, engines, smart_events
+        from ..model_clients import cost_usd
+        if self.mode != "smart":
+            raise ValueError("run_smart needs mode smart")
+        key = self.key or engines.smart_key()
+        if not key:
+            why, fix = no_smart_key()
+            raise self._fail(CouldntRun("model", f"Smart can't run: {why}.", fix))
+        self.key = key
+        self.state = "running"
+        spent = {"usd": 0.0}
+        started = time.monotonic()
+        deadline = started + float(self.check.max_seconds) + 60  # a backstop past the loop's own time limit
+        names = {self.app.bundle_id: self.app.name}
+
+        def stopping():
+            if self._stop.is_set() or time.monotonic() > deadline:
+                return True
+            try:
+                return bool(cancelled and cancelled())
+            except Exception:
+                return False
+
+        def on_inference(event):
+            if event.get("event") == "inference_finished" and isinstance(event.get("estimated_usd"), (int, float)):
+                spent["usd"] += event["estimated_usd"]
+            self.event(event)
+
+        def on_event(event):
+            kind = event.get("event")
+            if kind == "frontier_prompt":
+                data = _data_url_bytes(event.get("image"))
+                path = self.frame_from_bytes(data, "step") if data else None
+                if not data:
+                    self._observe_screen(None)
+                if path is not None:
+                    self._give_after_frame(path)
+                self.event({"event": kind, "step": event.get("step"), "operations": event.get("operations"),
+                            "out": event.get("out")})
+                return
+            self.event(event)
+            if kind == "frontier_action":
+                op = event.get("operation") or ""
+                label = event.get("target_label") or ""
+                text = smart_events.step_text(op, label, names, text=event.get("text"))
+                typed = event.get("text") if op in smart_events.TYPING else None
+                step = self.record_step(op=op, text=text, target={"id": None, "label": label or None, "role": None},
+                                        typed=typed, changed=event.get("changed"))
+                # Its frame is the screen after it: the image Smart sees next turn, or the verdict frame.
+                self._awaiting_frame.append(step)
+                self.progress(f"  {text}")
+
+        with self.lock:
+            client = engines.build_client(key=key)
+            costs.meter(client, on_inference)
+            guard = check_guard(self.manager, self.app.bundle_id)
+            driver, recording = self.driver, {}
+            if self.replay is not None and self.replay.mode != "off":
+                recorder = self.replay.recorder()  # the path a later run replays, if this one passes
+                driver, recording = recorder.wrap(self.driver), {"step_observer": recorder.observe_step}
+            agent = engines.build_frontier(driver, client, apps=names, emit=on_event,
+                                           max_cost_usd=self.check.max_usd, approve=check_approver(self.manager),
+                                           cancelled=stopping, guard=guard, dialogs=True,
+                                           dialog_policy=self.dialogs, **recording)
+            agent.max_seconds = float(self.check.max_seconds)  # the check's time limit, not the app's 15 minutes
+            from .. import intents
+            if intents.enabled() and getattr(self.target, "udid", None):
+                from ..intents.plan import LinkFirst
+                agent.link_first = LinkFirst.for_device(self.target.udid)
+            request = smart_request(self.app.name, self._live.steps)
+            self.progress(f"Smart: {request}")
+            outcome = agent.run(request)
+        self.timing["flow"] = round(time.monotonic() - started, 2)
+        status = outcome.get("status")
+        if outcome.get("code") == "unknown_outcome":
+            raise self._fail(CouldntRun("unknown_outcome", "A phone action's outcome is unknown.",
+                                        "Inspect the phone before another run; Mobster did not retry the action."))
+        if status == "stopped" and not self._stop.is_set() and not (cancelled and _safe(cancelled)):
+            status = "timeout"  # the backstop, not the user
+        self._smart_status, self._smart_reason = status, str(outcome.get("reason") or "")
+        if guard is not None and guard.left and outcome.get("code") == "blocked_app":
+            self._left_app = guard.left
+        self._model_failed = bool(getattr(client, "model_failed", False))
+        loop_cost = cost_usd(getattr(client, "model", ""), outcome.get("usage") or {}) or 0.0
+        self.cost_usd = round(max(spent["usd"], loop_cost), 5)
+        note = outcome.get("answer") or outcome.get("reason") or ""
+        self.agent = {"status": status, "note": self._scrub(str(note))[:NOTE_LIMIT] or None,
+                      "model": getattr(client, "model", None), "turns": outcome.get("steps"),
+                      **_link_first(outcome)}
+        self.log(f"Smart ended {status} after {outcome.get('steps')} turns, ${self.cost_usd:.4f}")
+        self.state = "ready"
+
+    def run_flow(self, cancelled=None):
+        """The check's steps: replayed from the recorded path when one is cached and replay is on, else Smart."""
+        if (self.replay is not None and not (self.check.throughout or self.check.somewhere)
+                and self.replay.lookup() is not None):
+            return self.run_replay(cancelled)  # a replay shows no screens to sweep, so `throughout` runs Smart
+        if self.replay is not None and self.replay.reason:
+            self.progress(f"Smart runs every step ({self.replay.reason}); a pass records the path to replay")
+        return self.run_smart(cancelled)
+
+    def run_replay(self, cancelled=None):
+        """Replay the recorded path with no model (replay_core); Smart heals a step that changed, for that step only,
+        unless replay is strict."""
+        from .. import engines
+        if self.mode != "smart" or self.replay is None:
+            raise ValueError("run_replay needs mode smart with replay on")
+        self.state = "running"
+        started = time.monotonic()
+        steps = len(self.replay.path["steps"])
+        if (steps and (self._a11y is not None or self._l10n is not None)
+                and not (self.source_observation is not None and self.source_observation.active)):
+            self._incomplete_screen("Replay did not read each intermediate accessibility screen")
+        self.progress(f"Replaying {steps} recorded step{'' if steps == 1 else 's'} (no model)")
+        with self.lock:
+            tune = getattr(self.driver, "tune", None)
+            if callable(tune):
+                try:
+                    tune(rich=True, glide=True)
+                except Exception as error:
+                    self.log(f"tune failed: {type(error).__name__}")
+            result = self.replay.replay(cancelled)
+        self.timing["flow"] = round(time.monotonic() - started, 2)
+        self.cost_usd = round(result.cost_usd, 5)
+        status = {"done": result.model_status or "done", "declined": "approval_denied", "stopped": "stopped",
+                  "drift": "done"}.get(result.status)
+        if result.status == "drift":
+            self._replay_drift = result.reason
+        if result.status == "heal_failed" and result.model_status == "budget":
+            status = "budget"
+        healed = len(result.heals)
+        note = (f"Replayed {result.replayed} step{'' if result.replayed == 1 else 's'} with no model"
+                + (f", healed {healed}" if healed else "") + (f": {result.reason}" if result.reason else ""))
+        self.agent = {"status": status or result.status, "note": self._scrub(note)[:NOTE_LIMIT],
+                      "model": engines.smart_model() if result.cost_usd else None, "turns": None, "replayed": True}
+        self.log(f"replay ended {result.status} after {result.replayed} steps, {healed} healed, "
+                 f"${self.cost_usd:.4f}")
+        self.state = "ready"
+        if self._left_app:
+            raise self._fail(self._smart_failure())
+        if result.status == "dialog":
+            raise self._fail(CouldntRun("system_dialog", f"The replay stopped: {result.reason}",
+                                        "Name an answer in the check's dialogs, or answer it by hand and run the check "
+                                        "again; the recorded steps are kept."))
+        if status is None:
+            if result.model_status == "unknown_outcome":
+                raise self._fail(CouldntRun("unknown_outcome", f"The replay stopped: {result.reason}",
+                                            "Check the app before starting another run; the action may have happened."))
+            raise self._fail(CouldntRun("replay", f"The replay stopped: {result.reason}",
+                                        "Run it again: the next run records the flow afresh (or use --fresh)."))
+        self._smart_status, self._smart_reason = status, result.reason or ""
+
+    def _smart_failure(self):
+        """CouldntRun for a Smart run that ended in error or was stopped (§4 rule 4), else None."""
+        status = self._smart_status
+        if self._left_app:
+            return CouldntRun("usage", LEFT_APP.format(app=self.app.name, other=self._left_app), LEFT_APP_FIX)
+        if status == "stopped":
+            return CouldntRun("stopped", "The run was stopped before the flow finished.")
+        if status != "error":
+            return None
+        from .. import engines
+        reason = self._smart_reason
+        model = (self.agent or {}).get("model") or engines.smart_model()
+        found = engines.PROVIDER_ERROR.search(reason)
+        provider = found.group(1) if found else engines.provider_name(model)
+        ok, why = engines.model_failure(reason, model=model)
+        if ok is False:
+            return CouldntRun("model", why, f"Check your {provider} key and credit, then run again.")
+        if self._model_failed or found or "OpenAI" in reason or "Anthropic" in reason:
+            reach = engines.NO_ANTHROPIC_REACH if provider == "Anthropic" else engines.NO_OPENAI_REACH
+            return CouldntRun("model", engines.plain_error(reason, model_failed=True, model=model) or reach)
+        from ..frontier import CONNECTION_LOST
+        if any(name in reason for name in CONNECTION_LOST + ("TimeoutError", "timed out", "TransportError")):
+            return CouldntRun("wda", "WebDriverAgent stopped answering during the flow and didn't come back.",
+                              "Run `mobster sim doctor --fix`, then try again.")
+        return CouldntRun("internal", "Smart stopped with an unexpected error. run.log has the details.")
+
+
+def _link_first(outcome):
+    """{"linkFirst": {"taken", "landed", "modelCallsSaved"}} when the run opened a link before any model call."""
+    timing = outcome.get("timing") or {}
+    if not timing.get("link_first"):
+        return {}
+    return {"linkFirst": {"taken": timing["link_first"], "landed": timing.get("link_first_landed", 0),
+                          "modelCallsSaved": timing.get("model_calls_saved", 0)}}

mobile_agent/verify/l10n.py

@@ -0,0 +1,141 @@
+"""The locale audit: what `mobster test --locale de,ja,ar` reads in the trees of a check run in a language."""
+
+import re
+
+from .a11y import EDGE, TEXT, _clipped, _describe
+from .tree import SCROLL_CONTAINERS
+
+NAME = "l10n"
+RTL = frozenset({"ar", "he", "fa", "ur", "ps", "sd", "ug", "yi", "dv"})
+# Languages whose own script isn't Latin: an ASCII sentence in one of them was not translated.
+NON_LATIN = RTL | frozenset({"ja", "ko", "zh", "ru", "uk", "bg", "sr", "mk", "be", "el", "th", "hi", "bn", "ta", "te",
+                             "ml", "kn", "gu", "pa", "mr", "ne", "si", "my", "km", "lo", "ka", "hy", "am", "mn"})
+GUIDELINES = {"text-truncated": "Localisation: long strings",
+              "untranslated-string": "Localisation: missing translation",
+              "rtl-not-mirrored": "Localisation: right-to-left layout"}
+ELLIPSIS = re.compile(r".*(…|\.\.\.)\s*$", re.S)
+ASCII_WORDS = re.compile(r"[A-Za-z]{2,}(?:[ '\-][A-Za-z]{2,})+|[A-Za-z]{5,}")
+RTL_SCRIPT = re.compile(r"[֐-ࣿיִ-﷿ﹰ-]")
+WIDE = 0.6      # a container at least this share of the screen's width counts as a full-width row
+NARROW = 0.7    # text narrower than this share of its row can show which edge it is flush to
+
+
+def language(locale):
+    return (locale or "").replace("-", "_").split("_")[0].lower()
+
+
+def is_rtl(locale):
+    return language(locale) in RTL
+
+
+def _finding(rule, node, message, frame):
+    name, where = _describe(node)
+    x, y, w, h = node.rect
+    return {"id": rule, "audit": NAME, "guideline": GUIDELINES[rule], "level": "warn", "frame": frame,
+            "message": f"{name} {where}: {message}", "evidence": f"{name} {where}", "baseline": False,
+            "element": {"role": node.role, "label": node.label, "identifier": node.identifier, "path": node.path,
+                        "rect": [x, y, w, h]}}
+
+
+def _ancestors(path):
+    while "/" in path.strip("/"):
+        path = path.rsplit("/", 1)[0]
+        yield path
+
+
+def audit_tree(tree, locale, *, frame=None):
+    """The findings of one screen's tree in ``locale``."""
+    shown = tree.shown()
+    by_path = {node.path: node for node in tree.nodes}
+    width = tree.size[0]
+    lang = language(locale)
+    out = []
+    for node in shown:
+        label = node.label.strip()
+        x, y, w, h = node.rect
+        if node.role in TEXT and label and w > 0 and h > 0:
+            if ELLIPSIS.fullmatch(label):
+                out.append(_finding("text-truncated", node,
+                                    "the text ends in an ellipsis, so it was cut short. Let it wrap or give it room "
+                                    "(SwiftUI: remove .lineLimit; UIKit: numberOfLines = 0).", frame))
+            else:
+                clipped = _clipped(node, by_path, width)
+                if clipped:
+                    out.append(_finding("text-truncated", node,
+                                        f"in {locale} it is {clipped}. Let the text wrap or the container grow.",
+                                        frame))
+        if lang in NON_LATIN and node.role in TEXT and label and _ascii_sentence(label):
+            out.append(_finding("untranslated-string", node,
+                                f"the text is plain English in {locale}. Translate it, or ignore this if it is a "
+                                "brand name.", frame))
+    if is_rtl(locale):
+        out.extend(_not_mirrored(shown, by_path, width, frame))
+    return out
+
+
+def _ascii_sentence(label):
+    letters = re.sub(r"[^A-Za-z]", "", label)
+    return bool(ASCII_WORDS.fullmatch(" ".join(label.split()))) and len(letters) >= 5 \
+        and len(re.sub(r"[A-Za-z '\-]", "", label)) == 0
+
+
+def _not_mirrored(shown, by_path, width, frame):
+    out = []
+    for bar in (node for node in shown if node.role == "NavigationBar"):
+        bx, _, bw, _ = bar.rect
+        buttons = [node for node in shown if node.role == "Button" and node.path.startswith(bar.path + "/")
+                   and node.rect[2] > 0]
+        if buttons and all(node.rect[0] + node.rect[2] / 2 < bx + bw / 2 for node in buttons) and bw >= width * WIDE:
+            out.append(_finding("rtl-not-mirrored", bar,
+                                "every button sits in the left half, so the back button didn't move to the right. "
+                                "Use leading and trailing edges, not left and right.", frame))
+    for node in shown:
+        label = node.label.strip()
+        x, y, w, h = node.rect
+        if node.role != "StaticText" or not label or not RTL_SCRIPT.search(label) or w <= 0 or h <= 0:
+            continue
+        row = next((by_path[path] for path in _ancestors(node.path) if path in by_path
+                    and by_path[path].rect[2] >= width * WIDE and by_path[path].role not in SCROLL_CONTAINERS), None)
+        if row is None or w > row.rect[2] * NARROW:
+            continue
+        left, right = x - row.rect[0], (row.rect[0] + row.rect[2]) - (x + w)
+        if left + EDGE < right and left < row.rect[2] * 0.1:
+            out.append(_finding("rtl-not-mirrored", node,
+                                "right-to-left text is flush to the left edge of its row. Align it to the leading "
+                                "edge (SwiftUI: .multilineTextAlignment(.leading); UIKit: .natural).", frame))
+    return out
+
+
+class Collector:
+    """A run's screens, audited once each (``add(tree, frame)``), like a11y.Collector."""
+
+    LIMIT = 60
+
+    def __init__(self, locale):
+        self.locale = locale
+        self._seen, self._found, self._keys = {}, [], set()
+
+    def add(self, tree, frame=None):
+        fingerprint = tree.audit_fingerprint()
+        if fingerprint in self._seen:
+            if frame is not None:
+                start, end = self._seen[fingerprint]
+                for finding in self._found[start:end]:
+                    if finding["frame"] is None:
+                        finding["frame"] = frame
+            return True
+        if len(self._seen) >= self.LIMIT:
+            return False
+        start = len(self._found)
+        for finding in audit_tree(tree, self.locale, frame=frame):
+            element = finding["element"]
+            key = (finding["id"], element["role"], element["label"], element["identifier"],
+                   tuple(round(n) for n in element["rect"]))
+            if key not in self._keys:
+                self._keys.add(key)
+                self._found.append(finding)
+        self._seen[fingerprint] = (start, len(self._found))
+        return True
+
+    def findings(self):
+        return list(self._found)