opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/swiftui-expert-skill/scripts/instruments_parser/summary.py

@@ -0,0 +1,243 @@
+"""Markdown summary renderer for the combined trace analysis."""
+from __future__ import annotations
+
+
+def render(result: dict) -> str:
+    lines: list[str] = []
+    trace = result.get("trace", "?")
+    header = result.get("xctrace_version") or ""
+    template = result.get("template") or ""
+    duration_s = result.get("duration_s")
+    lines.append(f"# Instruments Trace Analysis")
+    meta = [p for p in [f"Trace: `{trace}`", header, template] if p]
+    lines.append("  •  ".join(meta))
+    if duration_s is not None:
+        lines.append(f"Recording duration: {duration_s:.2f}s")
+    lines.append("")
+
+    lanes_by_name = {lane["lane"]: lane for lane in result.get("lanes", [])}
+
+    _render_time_profiler(lines, lanes_by_name.get("time-profiler"))
+    _render_hangs(lines, lanes_by_name.get("hangs"))
+    _render_hitches(lines, lanes_by_name.get("hitches"))
+    _render_swiftui(lines, lanes_by_name.get("swiftui"))
+    _render_causes(lines, lanes_by_name.get("swiftui-causes"))
+    _render_correlations(lines, result.get("correlations", []))
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _skipped_block(title: str, lane: dict | None) -> list[str]:
+    if lane is None:
+        return [f"## {title} — skipped (lane module not run)", ""]
+    notes = lane.get("notes") or []
+    note_text = f" — {notes[0]}" if notes else ""
+    return [f"## {title} — skipped{note_text}", ""]
+
+
+def _render_time_profiler(lines: list[str], lane: dict | None) -> None:
+    if not lane or not lane.get("available"):
+        lines.extend(_skipped_block("Time Profiler", lane))
+        return
+    m = lane["metrics"]
+    lines.append(
+        f"## Time Profiler — {m['total_samples']:,} samples, "
+        f"{m['total_weight_ms']:.0f}ms CPU time"
+    )
+    if m.get("processes"):
+        lines.append(f"Processes: {', '.join(m['processes'])}")
+    lines.append("")
+    if lane["top_offenders"]:
+        lines.append("Top offenders:")
+        for i, o in enumerate(lane["top_offenders"], 1):
+            lines.append(
+                f"{i}. `{_truncate(o['symbol'], 90)}` — "
+                f"{o['percent']:.1f}% ({o['weight_ms']:.0f}ms, "
+                f"{o['samples']} samples, {_short_thread(o['thread'])})"
+            )
+    for note in lane.get("notes") or []:
+        lines.append(f"> {note}")
+    lines.append("")
+
+
+def _render_hangs(lines: list[str], lane: dict | None) -> None:
+    if not lane or not lane.get("available"):
+        lines.extend(_skipped_block("Hangs", lane))
+        return
+    m = lane["metrics"]
+    buckets = m["severity_buckets"]
+    lines.append(
+        f"## Hangs — {m['count']} hangs, {m['total_duration_ms']:.0f}ms total, "
+        f"worst {m['worst_duration_ms']:.0f}ms"
+    )
+    lines.append(
+        f"Severity: <250ms={buckets['lt_250ms']}, "
+        f"250ms–1s={buckets['250ms_1s']}, >1s={buckets['gt_1s']}"
+    )
+    lines.append("")
+    for i, h in enumerate(lane["top_offenders"], 1):
+        lines.append(
+            f"{i}. {h['duration_ms']:.0f}ms {h['hang_type']} at "
+            f"{h['start_ms']:.2f}ms on {_short_thread(h['thread'])}"
+        )
+    lines.append("")
+
+
+def _render_hitches(lines: list[str], lane: dict | None) -> None:
+    if not lane or not lane.get("available"):
+        lines.extend(_skipped_block("Animation Hitches", lane))
+        return
+    m = lane["metrics"]
+    lines.append(
+        f"## Animation Hitches — {m['count']} hitches, "
+        f"{m['total_hitch_ms']:.0f}ms total, worst {m['worst_hitch_ms']:.0f}ms"
+    )
+    if m.get("per_process"):
+        pp = ", ".join(f"{k}={v}" for k, v in m["per_process"].items())
+        lines.append(f"By process: {pp}")
+    lines.append("")
+    if m.get("narrative_breakdown"):
+        nb = ", ".join(f"{k}={v}" for k, v in m["narrative_breakdown"].items() if k)
+        if nb:
+            lines.append(f"Apple attribution: {nb}")
+    if m.get("system_hitches") is not None:
+        lines.append(
+            f"System vs app: system={m['system_hitches']}, app={m['app_hitches']}"
+        )
+    lines.append("")
+    for i, h in enumerate(lane["top_offenders"], 1):
+        narrative = f" — {h['narrative']}" if h.get("narrative") else ""
+        src = " [system]" if h.get("is_system") else ""
+        proc = f" ({h['process']})" if h.get("process") else ""
+        lines.append(
+            f"{i}. {h['hitch_duration_ms']:.0f}ms at {h['start_ms']:.2f}ms"
+            f"{proc}{src}{narrative}"
+        )
+    lines.append("")
+
+
+def _render_swiftui(lines: list[str], lane: dict | None) -> None:
+    if not lane or not lane.get("available"):
+        lines.extend(_skipped_block("SwiftUI", lane))
+        return
+    m = lane["metrics"]
+    lines.append(
+        f"## SwiftUI — {m['total_events']:,} updates across "
+        f"{m['unique_views']} views, {m['total_duration_ms']:.0f}ms total"
+    )
+    if m.get("severity_breakdown"):
+        sb = ", ".join(f"{k}={v}" for k, v in m["severity_breakdown"].items())
+        lines.append(f"Severity: {sb}")
+    if m.get("update_type_breakdown"):
+        ub = ", ".join(f"{k}={v}" for k, v in m["update_type_breakdown"].items())
+        lines.append(f"Update types: {ub}")
+    lines.append("")
+    if lane["top_offenders"]:
+        lines.append("Heaviest views (by total body time):")
+        for i, v in enumerate(lane["top_offenders"], 1):
+            lines.append(
+                f"{i}. `{_truncate(v['view'], 80)}` — {v['total_ms']:.0f}ms total, "
+                f"{v['count']} updates (avg {v['avg_ms']:.2f}ms)"
+            )
+    if lane.get("high_severity_events"):
+        lines.append("")
+        lines.append("High-severity updates:")
+        for i, e in enumerate(lane["high_severity_events"][:5], 1):
+            cat = f" [{e['category']}]" if e.get("category") else ""
+            lines.append(
+                f"{i}. `{_truncate(e['view'], 60)}` — "
+                f"{e['severity']} ({e['duration_ms']:.2f}ms at {e['start_ms']:.2f}ms){cat}"
+            )
+    lines.append("")
+
+
+def _render_causes(lines: list[str], lane: dict | None) -> None:
+    if not lane or not lane.get("available"):
+        lines.extend(_skipped_block("SwiftUI Cause Graph", lane))
+        return
+    m = lane["metrics"]
+    lines.append(
+        f"## SwiftUI Cause Graph — {m['total_edges']:,} edges, "
+        f"{m['unique_sources']} sources → {m['unique_destinations']} destinations"
+    )
+    lines.append("")
+    if lane.get("top_sources"):
+        lines.append("Top sources (who's driving the most updates):")
+        for i, s in enumerate(lane["top_sources"][:5], 1):
+            lines.append(f"{i}. `{_truncate(s['source'], 80)}` — {s['edges']:,} edges")
+            for d in s["top_destinations"][:3]:
+                lines.append(
+                    f"    → `{_truncate(d['destination'], 70)}` {d['edges']:,}"
+                )
+    if lane.get("top_destinations"):
+        lines.append("")
+        lines.append("Top destinations (who's being invalidated most):")
+        for i, d in enumerate(lane["top_destinations"][:5], 1):
+            lines.append(f"{i}. `{_truncate(d['destination'], 80)}` — {d['edges']:,} edges")
+            for s in d["top_sources"][:3]:
+                lines.append(
+                    f"    ← `{_truncate(s['source'], 70)}` {s['edges']:,}"
+                )
+    lines.append("")
+
+
+def _render_correlations(lines: list[str], correlations: list[dict]) -> None:
+    if not correlations:
+        return
+    lines.append("## Correlations")
+    lines.append("")
+    for c in correlations:
+        t = c["trigger"]
+        head = (
+            f"- **{t['lane']}** at {t['start_ms']:.2f}ms "
+            f"({t['duration_ms']:.0f}ms)"
+        )
+        if t.get("hang_type"):
+            head += f" — {t['hang_type']}"
+        lines.append(head)
+
+        tp = c.get("time_profiler_main_thread")
+        if tp is not None:
+            cov = tp["main_running_coverage_pct"]
+            lines.append(
+                f"  - Main thread: {tp['samples_on_main']} running samples "
+                f"({cov:.0f}% coverage — "
+                f"{'blocked' if cov < 25 else 'mostly running'})"
+            )
+            for s in tp["hot_symbols"][:3]:
+                lines.append(
+                    f"    · `{_truncate(s['symbol'], 80)}` "
+                    f"{s['percent_of_main']:.0f}% ({s['samples']} samples)"
+                )
+            if not tp["hot_symbols"]:
+                lines.append("    · no main-thread samples in window")
+
+        sui = c.get("swiftui_overlapping_updates")
+        if sui:
+            for s in sui[:3]:
+                lines.append(
+                    f"  - SwiftUI: `{s['view']}` {s['duration_ms']:.2f}ms "
+                    f"(at {s['start_ms']:.2f}ms)"
+                )
+    lines.append("")
+
+
+def _short_thread(name: str) -> str:
+    if not name:
+        return ""
+    if name.startswith("Main Thread") or name == "main":
+        return "main"
+    # "NowPlaying Gigs (0x251990d) (NowPlaying Gigs, pid: 28401)" -> "tid 0x251990d"
+    tid_start = name.find("(0x")
+    if tid_start != -1:
+        start = tid_start + 1
+        end = name.find(")", start)
+        if end != -1:
+            return f"tid {name[start:end]}"
+    return name[:40]
+
+
+def _truncate(s: str, n: int) -> str:
+    if len(s) <= n:
+        return s
+    return s[: n - 1] + "…"

package/bundled-skills/swiftui-expert-skill/scripts/instruments_parser/swiftui.py

@@ -0,0 +1,195 @@
+"""SwiftUI lane parser (Xcode 26+).
+
+Primary schema is `swiftui-updates` with columns: start, duration, id,
+update-type, allocations, description, category, view-hierarchy, module,
+view-name, process, thread, root-causes, severity, cause-graph-node,
+full-cause-graph-node.
+
+We aggregate by view-name across all SwiftUI schemas (future-proofing against
+schema renames) and break severity out separately so the agent can focus on
+the high-severity rows.
+"""
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any
+
+from . import xctrace, xml_utils
+
+START_KEYS = ("start", "time", "sample-time", "timestamp")
+DURATION_KEYS = ("duration", "body-duration", "update-duration")
+VIEW_KEYS = ("view-name", "view", "view-type", "name", "type")
+MODULE_KEYS = ("module",)
+CATEGORY_KEYS = ("category",)
+UPDATE_TYPE_KEYS = ("update-type",)
+SEVERITY_KEYS = ("severity",)
+DESCRIPTION_KEYS = ("description",)
+
+HIGH_SEVERITIES = {"High", "Very High", "Severe", "Critical"}
+
+# Ongoing / unterminated updates carry a sentinel duration (≈ UINT64_MAX-ish).
+# Any duration longer than an hour is almost certainly that sentinel and would
+# break aggregates + the correlation overlap check.
+_SENTINEL_DURATION_NS = 60 * 60 * 1_000_000_000  # 1 hour
+
+
+def analyze(
+    trace_path: Path,
+    toc_schemas: frozenset[str],
+    top_n: int = 10,
+    window: tuple[int, int] | None = None,
+    run: int = 1,
+) -> dict[str, Any]:
+    schemas = sorted(
+        s for s in toc_schemas
+        if s.startswith("swiftui") and not s.endswith("-causes")
+    )
+    if not schemas:
+        return {
+            "lane": "swiftui",
+            "available": False,
+            "notes": ["SwiftUI lane not in trace (Xcode 26+ SwiftUI template required)."],
+        }
+
+    events: list[dict] = []
+    per_view_total_ns: dict[str, int] = defaultdict(int)
+    per_view_count: dict[str, int] = defaultdict(int)
+    severity_counts: Counter[str] = Counter()
+    update_type_counts: Counter[str] = Counter()
+    category_counts: Counter[str] = Counter()
+
+    for schema in schemas:
+        xml_bytes = xctrace.export_schema(trace_path, schema, run=run)
+        stream = xml_utils.RowStream(xml_bytes)
+        for row in stream:
+            start_ns = _first_int(row, stream, START_KEYS)
+            dur_ns = _first_int(row, stream, DURATION_KEYS)
+            if start_ns is None or dur_ns is None:
+                continue
+            if dur_ns < 0 or dur_ns > _SENTINEL_DURATION_NS:
+                # Unterminated / ongoing update; skip so it doesn't poison
+                # totals and the correlation overlap check.
+                continue
+            if not xml_utils.event_overlaps_window(start_ns, start_ns + dur_ns, window):
+                continue
+
+            view = _first_str(row, stream, VIEW_KEYS)
+            module = _first_str(row, stream, MODULE_KEYS)
+            category = _first_str(row, stream, CATEGORY_KEYS)
+            update_type = _first_str(row, stream, UPDATE_TYPE_KEYS)
+            severity = _first_str(row, stream, SEVERITY_KEYS)
+            description = _first_str(row, stream, DESCRIPTION_KEYS)
+            # Fall back through description → category → update-type so the
+            # agent sees "EnvironmentWriter: RootEnvironment" instead of
+            # "<unknown>" when SwiftUI doesn't record a view type.
+            if not view:
+                view = description or category or update_type or "<unknown>"
+
+            per_view_total_ns[view] += dur_ns
+            per_view_count[view] += 1
+            if severity:
+                severity_counts[severity] += 1
+            if update_type:
+                update_type_counts[update_type] += 1
+            if category:
+                category_counts[category] += 1
+
+            events.append({
+                "schema": schema,
+                "start_ns": start_ns,
+                "end_ns": start_ns + dur_ns,
+                "duration_ns": dur_ns,
+                "duration_ms": round(dur_ns / 1_000_000, 2),
+                "start_ms": round(start_ns / 1_000_000, 2),
+                "view": view,
+                "module": module,
+                "category": category,
+                "update_type": update_type,
+                "severity": severity,
+                "description": description,
+            })
+
+    events.sort(key=lambda e: e["duration_ns"], reverse=True)
+
+    top_by_total = sorted(
+        per_view_total_ns.items(), key=lambda kv: kv[1], reverse=True
+    )[:top_n]
+    top_offenders = [
+        {
+            "view": view,
+            "total_ms": round(total_ns / 1_000_000, 2),
+            "count": per_view_count[view],
+            "avg_ms": round(total_ns / per_view_count[view] / 1_000_000, 2),
+        }
+        for view, total_ns in top_by_total
+    ]
+
+    high_severity = [
+        {
+            "view": e["view"],
+            "severity": e["severity"],
+            "duration_ms": e["duration_ms"],
+            "start_ms": e["start_ms"],
+            "category": e["category"],
+            "update_type": e["update_type"],
+            "description": e["description"],
+        }
+        for e in events if e["severity"] in HIGH_SEVERITIES
+    ][:top_n]
+
+    longest = [
+        {
+            "view": e["view"],
+            "duration_ms": e["duration_ms"],
+            "start_ms": e["start_ms"],
+            "category": e["category"],
+            "update_type": e["update_type"],
+            "severity": e["severity"],
+        }
+        for e in events[:top_n]
+    ]
+
+    return {
+        "lane": "swiftui",
+        "available": True,
+        "schemas_used": schemas,
+        "metrics": {
+            "total_events": len(events),
+            "unique_views": len(per_view_total_ns),
+            "total_duration_ms": round(
+                sum(per_view_total_ns.values()) / 1_000_000, 2
+            ),
+            "severity_breakdown": dict(severity_counts.most_common()),
+            "update_type_breakdown": dict(update_type_counts.most_common()),
+            "category_breakdown": dict(category_counts.most_common()),
+        },
+        "top_offenders": top_offenders,
+        "longest_single_events": longest,
+        "high_severity_events": high_severity,
+        "notes": [],
+        "_events": events,
+    }
+
+
+def _first_int(row, stream, keys):
+    for key in keys:
+        el = row.get(key)
+        if el is None:
+            continue
+        val = xml_utils.int_text(stream.resolve(el))
+        if val is not None:
+            return val
+    return None
+
+
+def _first_str(row, stream, keys):
+    for key in keys:
+        el = row.get(key)
+        if el is None:
+            continue
+        resolved = stream.resolve(el)
+        txt = xml_utils.str_text(resolved) or resolved.get("fmt")
+        if txt:
+            return txt
+    return None

package/bundled-skills/swiftui-expert-skill/scripts/instruments_parser/time_profiler.py

@@ -0,0 +1,135 @@
+"""Time Profiler lane parser (schema `time-profile`).
+
+Aggregates CPU samples by leaf symbol, keeps per-sample rows so that other
+lanes can correlate by timestamp window.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from . import xctrace, xml_utils
+
+PREFERRED_SCHEMAS = ("time-profile",)
+FALLBACK_SCHEMAS = ("time-sample",)  # no symbolication; used only if nothing else
+
+
+def analyze(
+    trace_path: Path,
+    toc_schemas: frozenset[str],
+    top_n: int = 10,
+    window: tuple[int, int] | None = None,
+    run: int = 1,
+) -> dict[str, Any]:
+    schema = _pick_schema(toc_schemas)
+    if schema is None:
+        return {
+            "lane": "time-profiler",
+            "available": False,
+            "notes": ["Time Profiler data not present in trace."],
+        }
+
+    xml_bytes = xctrace.export_schema(trace_path, schema, run=run)
+    stream = xml_utils.RowStream(xml_bytes)
+
+    samples: list[dict] = []
+    symbol_weight: dict[str, int] = defaultdict(int)
+    symbol_samples: dict[str, int] = defaultdict(int)
+    symbol_thread: dict[str, str] = {}
+    processes: set[str] = set()
+    total_weight = 0
+    min_time: int | None = None
+    max_time: int | None = None
+
+    for row in stream:
+        time_el = row.get("time")
+        weight_el = row.get("weight")
+        thread_el = row.get("thread")
+        stack_el = row.get("stack")
+        if stack_el is None or time_el is None or thread_el is None:
+            continue
+
+        sample_time_ns = xml_utils.int_text(stream.resolve(time_el))
+        if not xml_utils.in_window(sample_time_ns, window):
+            continue
+        weight_ns = xml_utils.int_text(stream.resolve(weight_el)) or 0
+        frames = xml_utils.extract_backtrace(stack_el, stream, max_frames=20)
+        if not frames:
+            continue
+
+        thread = xml_utils.extract_thread(thread_el, stream)
+        process_name = (thread.get("process") or {}).get("name")
+        if process_name:
+            processes.add(process_name)
+
+        leaf = xml_utils.top_symbol(frames)
+        symbol_weight[leaf] += weight_ns
+        symbol_samples[leaf] += 1
+        symbol_thread.setdefault(
+            leaf, "main" if thread["is_main"] else thread.get("name", "")
+        )
+        total_weight += weight_ns
+
+        if sample_time_ns is not None:
+            min_time = sample_time_ns if min_time is None else min(min_time, sample_time_ns)
+            max_time = sample_time_ns if max_time is None else max(max_time, sample_time_ns)
+
+            samples.append({
+                "time_ns": sample_time_ns,
+                "weight_ns": weight_ns,
+                "thread_name": thread["name"],
+                "is_main": thread["is_main"],
+                "process": process_name,
+                "leaf_symbol": leaf,
+                "frames": frames[:5],
+            })
+
+    samples.sort(key=lambda s: s["time_ns"])
+
+    top = sorted(
+        symbol_weight.items(), key=lambda kv: kv[1], reverse=True
+    )[:top_n]
+    top_offenders = [
+        {
+            "symbol": sym,
+            "weight_ns": w,
+            "weight_ms": round(w / 1_000_000, 2),
+            "samples": symbol_samples[sym],
+            "percent": round(100.0 * w / total_weight, 2) if total_weight else 0.0,
+            "thread": symbol_thread.get(sym, ""),
+        }
+        for sym, w in top
+    ]
+
+    notes: list[str] = []
+    if schema in FALLBACK_SCHEMAS:
+        notes.append(
+            f"Using fallback schema `{schema}`; backtraces may be unsymbolicated."
+        )
+
+    return {
+        "lane": "time-profiler",
+        "available": True,
+        "schema_used": schema,
+        "metrics": {
+            "total_samples": len(samples),
+            "total_weight_ns": total_weight,
+            "total_weight_ms": round(total_weight / 1_000_000, 2),
+            "window_start_ns": min_time,
+            "window_end_ns": max_time,
+            "processes": sorted(processes),
+        },
+        "top_offenders": top_offenders,
+        "notes": notes,
+        # Internal: retained for correlation. Stripped before JSON emission
+        # if --slim is requested by the orchestrator.
+        "_samples": samples,
+    }
+
+
+def _pick_schema(available: frozenset[str]) -> str | None:
+    for s in PREFERRED_SCHEMAS + FALLBACK_SCHEMAS:
+        if s in available:
+            return s
+    return None

package/bundled-skills/swiftui-expert-skill/scripts/instruments_parser/xctrace.py

@@ -0,0 +1,117 @@
+"""Thin wrapper around the `xctrace` CLI."""
+from __future__ import annotations
+
+import subprocess
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class RunInfo:
+    """Per-run metadata and schemas. Instruments traces can hold multiple runs."""
+    number: int
+    template_name: str | None
+    duration_s: float | None
+    start_date: str | None
+    end_date: str | None
+    schemas: frozenset[str]
+
+
+@dataclass(frozen=True)
+class TraceInfo:
+    xctrace_version: str
+    runs: tuple[RunInfo, ...]
+
+    def get_run(self, number: int) -> RunInfo:
+        for r in self.runs:
+            if r.number == number:
+                return r
+        available = ", ".join(str(r.number) for r in self.runs)
+        raise KeyError(f"run {number} not in trace (available: {available})")
+
+
+def version() -> str:
+    out = subprocess.run(
+        ["xctrace", "version"], capture_output=True, text=True, check=True
+    )
+    return out.stdout.strip()
+
+
+def toc(trace_path: Path) -> TraceInfo:
+    """Export the trace's table of contents and return per-run metadata.
+
+    The TOC is small (a few KB) so we load it fully rather than streaming.
+    """
+    xml_bytes = _run_export(trace_path, ["--toc"])
+    root = ET.fromstring(xml_bytes)
+
+    instruments = _find_text(root, ".//instruments-version") or ""
+
+    runs: list[RunInfo] = []
+    for run_el in root.iterfind("./run"):
+        number_attr = run_el.get("number")
+        if not number_attr:
+            continue
+        try:
+            number = int(number_attr)
+        except ValueError:
+            continue
+        if number <= 0:
+            continue
+
+        schemas: set[str] = set()
+        for table in run_el.iterfind("./data/table"):
+            schema = table.get("schema")
+            if schema:
+                schemas.add(schema)
+
+        summary = run_el.find("./info/summary")
+        if summary is not None:
+            template = _find_text(summary, "./template-name")
+            duration = _find_text(summary, "./duration")
+            start = _find_text(summary, "./start-date")
+            end = _find_text(summary, "./end-date")
+        else:
+            template = duration = start = end = None
+
+        runs.append(RunInfo(
+            number=number,
+            template_name=template,
+            duration_s=float(duration) if duration else None,
+            start_date=start,
+            end_date=end,
+            schemas=frozenset(schemas),
+        ))
+
+    runs.sort(key=lambda r: r.number)
+    return TraceInfo(
+        xctrace_version=instruments,
+        runs=tuple(runs),
+    )
+
+
+def export_schema(trace_path: Path, schema: str, run: int = 1) -> bytes:
+    """Export one schema's data as XML bytes from the given run.
+
+    Callers are expected to iterparse the result rather than build a full tree
+    for large schemas (time-profile can be tens of MB).
+    """
+    xpath = f'/trace-toc/run[@number="{run}"]/data/table[@schema="{schema}"]'
+    return _run_export(trace_path, ["--xpath", xpath])
+
+
+def _run_export(trace_path: Path, extra_args: list[str]) -> bytes:
+    cmd = ["xctrace", "export", "--input", str(trace_path), *extra_args]
+    proc = subprocess.run(cmd, capture_output=True, check=False)
+    if proc.returncode != 0:
+        raise RuntimeError(
+            f"xctrace export failed ({proc.returncode}): "
+            f"{proc.stderr.decode(errors='replace').strip()}"
+        )
+    return proc.stdout
+
+
+def _find_text(root: ET.Element, path: str) -> str | None:
+    el = root.find(path)
+    return el.text if el is not None and el.text else None