opencode-skills-collection 3.1.12 → 3.1.13

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

@@ -0,0 +1,291 @@
+"""Discovery helpers for os_log messages and os_signpost intervals.
+
+These let an agent locate a focus window (e.g. "after the log saying X",
+"during signpost Y") before running the main lane analysis.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import xctrace, xml_utils
+
+OS_LOG_SCHEMA = "os-log"
+OS_SIGNPOST_SCHEMA = "os-signpost"
+OS_SIGNPOST_INTERVAL_SCHEMA = "os-signpost-interval"
+
+
+def list_logs(
+    trace_path: Path,
+    toc_schemas: frozenset[str],
+    subsystem: str | None = None,
+    category: str | None = None,
+    message_contains: str | None = None,
+    message_type: str | None = None,
+    limit: int | None = None,
+    window_ns: tuple[int, int] | None = None,
+    run: int = 1,
+) -> list[dict[str, Any]]:
+    """Return os_log entries, optionally filtered. Case-insensitive contains.
+
+    `limit` counts *post-filter* matches — including the window filter — so
+    the caller gets N matching logs inside the window rather than the first
+    N matching logs that might all fall outside it.
+    """
+    if OS_LOG_SCHEMA not in toc_schemas:
+        return []
+    xml_bytes = xctrace.export_schema(trace_path, OS_LOG_SCHEMA, run=run)
+    stream = xml_utils.RowStream(xml_bytes)
+    needle = message_contains.lower() if message_contains else None
+
+    out: list[dict[str, Any]] = []
+    for row in stream:
+        time_el = row.get("time")
+        if time_el is None:
+            continue
+        time_ns = xml_utils.int_text(stream.resolve(time_el))
+        if time_ns is None:
+            continue
+        if not xml_utils.in_window(time_ns, window_ns):
+            continue
+
+        sub = _str_of(row, stream, "subsystem")
+        cat = _str_of(row, stream, "category")
+        typ = _str_of(row, stream, "message-type")
+        fmt = _str_of(row, stream, "format-string")
+        msg = _str_of(row, stream, "message") or fmt
+
+        if subsystem and (sub or "") != subsystem:
+            continue
+        if category and (cat or "") != category:
+            continue
+        if message_type and (typ or "") != message_type:
+            continue
+        if needle and needle not in (msg or "").lower() and needle not in (fmt or "").lower():
+            continue
+
+        process_el = row.get("process")
+        process = (
+            xml_utils.extract_process(process_el, stream).get("name")
+            if process_el is not None else None
+        )
+
+        out.append({
+            "time_ns": time_ns,
+            "time_ms": round(time_ns / 1_000_000, 3),
+            "type": typ,
+            "subsystem": sub,
+            "category": cat,
+            "process": process,
+            "message": msg,
+            "format_string": fmt,
+        })
+        if limit is not None and len(out) >= limit:
+            break
+
+    out.sort(key=lambda e: e["time_ns"])
+    return out
+
+
+def list_signposts(
+    trace_path: Path,
+    toc_schemas: frozenset[str],
+    name_contains: str | None = None,
+    subsystem: str | None = None,
+    category: str | None = None,
+    window_ns: tuple[int, int] | None = None,
+    run: int = 1,
+) -> dict[str, list[dict[str, Any]]]:
+    """Return signpost intervals (paired begin/end) plus single-point events.
+
+    Shape: { "intervals": [...], "events": [...] }. Intervals have
+    start_ms/end_ms/duration_ms; events have a single time_ms.
+
+    Reads two complementary schemas:
+      * `os-signpost-interval`: already-paired intervals (this is where
+        user-emitted signposts like com.example.MyApp typically land).
+      * `os-signpost`: raw begin/end/event rows; we pair begins with ends
+        ourselves and fall back to point events for unpaired rows. Most
+        Apple-framework signposts (CloudKit, AppKit, …) live here.
+
+    Filters are AND-combined. `name_contains` is a case-insensitive substring
+    match. `window_ns` keeps intervals that overlap the window (not strict
+    containment) and point events whose timestamp falls inside it.
+    """
+    # The two signpost schemas overlap: every paired begin/end in `os-signpost`
+    # also shows up as a row in `os-signpost-interval`. To avoid duplicates we
+    # prefer the pre-paired schema for intervals and only mine `os-signpost`
+    # for point events (and for begin/end pairing as a fallback when the
+    # interval schema is missing — older traces).
+    intervals: list[dict[str, Any]] = []
+    events: list[dict[str, Any]] = []
+
+    has_intervals = OS_SIGNPOST_INTERVAL_SCHEMA in toc_schemas
+    if has_intervals:
+        intervals.extend(_read_interval_schema(trace_path, run=run))
+
+    if OS_SIGNPOST_SCHEMA in toc_schemas:
+        more_intervals, more_events = _read_event_schema(trace_path, run=run)
+        if not has_intervals:
+            intervals.extend(more_intervals)
+        events.extend(more_events)
+
+    intervals.sort(key=lambda i: i["start_ns"])
+    events.sort(key=lambda e: e["time_ns"])
+
+    needle = name_contains.lower() if name_contains else None
+
+    def _matches(entry: dict) -> bool:
+        if subsystem and (entry.get("subsystem") or "") != subsystem:
+            return False
+        if category and (entry.get("category") or "") != category:
+            return False
+        if needle and needle not in (entry.get("name") or "").lower():
+            return False
+        return True
+
+    if subsystem or category or needle:
+        intervals = [i for i in intervals if _matches(i)]
+        events = [e for e in events if _matches(e)]
+
+    if window_ns is not None:
+        s, e = window_ns
+        intervals = [
+            i for i in intervals
+            if not (i["end_ns"] < s or i["start_ns"] > e)
+        ]
+        events = [ev for ev in events if s <= ev["time_ns"] <= e]
+
+    return {"intervals": intervals, "events": events}
+
+
+def _read_interval_schema(trace_path: Path, run: int = 1) -> list[dict[str, Any]]:
+    """Read the os-signpost-interval schema (pre-paired intervals)."""
+    xml_bytes = xctrace.export_schema(trace_path, OS_SIGNPOST_INTERVAL_SCHEMA, run=run)
+    stream = xml_utils.RowStream(xml_bytes)
+
+    out: list[dict[str, Any]] = []
+    for row in stream:
+        start_el = xml_utils.first_present(row, "start", "time")
+        dur_el = row.get("duration")
+        if start_el is None or dur_el is None:
+            continue
+        start_ns = xml_utils.int_text(stream.resolve(start_el))
+        dur_ns = xml_utils.int_text(stream.resolve(dur_el))
+        if start_ns is None or dur_ns is None:
+            continue
+        end_ns = start_ns + dur_ns
+
+        name = _str_of(row, stream, "name")
+        sub = _str_of(row, stream, "subsystem")
+        cat = _str_of(row, stream, "category")
+        signpost_id = _str_of(row, stream, "identifier") or _str_of(row, stream, "signpost-id")
+        process_el = row.get("process")
+        process = (
+            xml_utils.extract_process(process_el, stream).get("name")
+            if process_el is not None else None
+        )
+
+        out.append({
+            "start_ns": start_ns,
+            "end_ns": end_ns,
+            "duration_ns": dur_ns,
+            "start_ms": round(start_ns / 1_000_000, 3),
+            "end_ms": round(end_ns / 1_000_000, 3),
+            "duration_ms": round(dur_ns / 1_000_000, 3),
+            "name": name,
+            "subsystem": sub,
+            "category": cat,
+            "process": process,
+            "signpost_id": signpost_id,
+        })
+    return out
+
+
+def _read_event_schema(
+    trace_path: Path,
+    run: int = 1,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Read the os-signpost schema and pair begin/end rows into intervals."""
+    xml_bytes = xctrace.export_schema(trace_path, OS_SIGNPOST_SCHEMA, run=run)
+    stream = xml_utils.RowStream(xml_bytes)
+
+    pending: dict[tuple, dict] = {}
+    intervals: list[dict[str, Any]] = []
+    events: list[dict[str, Any]] = []
+
+    for row in stream:
+        time_el = xml_utils.first_present(row, "time", "start")
+        if time_el is None:
+            continue
+        time_ns = xml_utils.int_text(stream.resolve(time_el))
+        if time_ns is None:
+            continue
+
+        name = _str_of(row, stream, "name")
+        sub = _str_of(row, stream, "subsystem")
+        cat = _str_of(row, stream, "category")
+        event_type = _str_of(row, stream, "event-type") or _str_of(row, stream, "message-type")
+        signpost_id = _str_of(row, stream, "signpost-id") or _str_of(row, stream, "identifier")
+        process_el = row.get("process")
+        process = (
+            xml_utils.extract_process(process_el, stream).get("name")
+            if process_el is not None else None
+        )
+
+        key = (process, sub, cat, name, signpost_id)
+        etype = (event_type or "").lower()
+
+        if etype in ("begin", "interval begin", "start"):
+            pending[key] = {"start_ns": time_ns, "name": name,
+                            "subsystem": sub, "category": cat,
+                            "process": process, "signpost_id": signpost_id}
+        elif etype in ("end", "interval end", "stop"):
+            start = pending.pop(key, None)
+            if start is not None:
+                dur_ns = time_ns - start["start_ns"]
+                intervals.append({
+                    **start,
+                    "end_ns": time_ns,
+                    "duration_ns": dur_ns,
+                    "start_ms": round(start["start_ns"] / 1_000_000, 3),
+                    "end_ms": round(time_ns / 1_000_000, 3),
+                    "duration_ms": round(dur_ns / 1_000_000, 3),
+                })
+            else:
+                events.append(_point_event(time_ns, name, sub, cat,
+                                            process, signpost_id, event_type))
+        else:
+            events.append(_point_event(time_ns, name, sub, cat,
+                                        process, signpost_id, event_type))
+
+    # Unclosed begins are surfaced as point events so nothing is silently dropped.
+    for info in pending.values():
+        events.append(_point_event(info["start_ns"], info["name"],
+                                    info["subsystem"], info["category"],
+                                    info["process"], info["signpost_id"],
+                                    "Begin (unclosed)"))
+
+    return intervals, events
+
+
+def _point_event(time_ns, name, subsystem, category, process, signpost_id, event_type):
+    return {
+        "time_ns": time_ns,
+        "time_ms": round(time_ns / 1_000_000, 3),
+        "name": name,
+        "subsystem": subsystem,
+        "category": category,
+        "process": process,
+        "signpost_id": signpost_id,
+        "event_type": event_type,
+    }
+
+
+def _str_of(row, stream, key):
+    el = row.get(key)
+    if el is None:
+        return None
+    resolved = stream.resolve(el)
+    txt = xml_utils.str_text(resolved) or resolved.get("fmt")
+    return txt

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

@@ -0,0 +1,108 @@
+"""Hangs lane parser (schema `potential-hangs`).
+
+The schema lacks inline backtraces — stacks come from Time Profiler samples
+that overlap each hang's window. Correlation is done later in correlate.py.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import xctrace, xml_utils
+
+PREFERRED_SCHEMAS = ("potential-hangs",)
+FALLBACK_SCHEMAS = ("main-thread-hang", "hang", "hangs")
+
+
+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": "hangs",
+            "available": False,
+            "notes": ["Hangs data not present in trace."],
+        }
+
+    xml_bytes = xctrace.export_schema(trace_path, schema, run=run)
+    stream = xml_utils.RowStream(xml_bytes)
+
+    hangs: list[dict] = []
+    for row in stream:
+        start_el = row.get("start")
+        dur_el = row.get("duration")
+        type_el = row.get("hang-type")
+        thread_el = row.get("thread")
+        if start_el is None or dur_el is None:
+            continue
+        start_ns = xml_utils.int_text(stream.resolve(start_el))
+        duration_ns = xml_utils.int_text(stream.resolve(dur_el))
+        if start_ns is None or duration_ns is None:
+            continue
+        if not xml_utils.event_overlaps_window(start_ns, start_ns + duration_ns, window):
+            continue
+        hang_type = xml_utils.str_text(stream.resolve(type_el)) if type_el is not None else None
+        thread = xml_utils.extract_thread(thread_el, stream) if thread_el is not None else None
+
+        hangs.append({
+            "start_ns": start_ns,
+            "duration_ns": duration_ns,
+            "end_ns": start_ns + duration_ns,
+            "duration_ms": round(duration_ns / 1_000_000, 2),
+            "start_ms": round(start_ns / 1_000_000, 2),
+            "hang_type": hang_type or "Hang",
+            "thread": thread,
+        })
+
+    hangs.sort(key=lambda h: h["duration_ns"], reverse=True)
+
+    total_ms = sum(h["duration_ms"] for h in hangs)
+    worst = hangs[0] if hangs else None
+
+    # Severity buckets per Apple docs (Microhang: 250ms–500ms, Hang: ≥500ms).
+    # We bucket by raw duration so the agent can reason about it.
+    buckets = {"lt_250ms": 0, "250ms_1s": 0, "gt_1s": 0}
+    for h in hangs:
+        if h["duration_ms"] < 250:
+            buckets["lt_250ms"] += 1
+        elif h["duration_ms"] < 1000:
+            buckets["250ms_1s"] += 1
+        else:
+            buckets["gt_1s"] += 1
+
+    top_offenders = [
+        {
+            "start_ms": h["start_ms"],
+            "duration_ms": h["duration_ms"],
+            "hang_type": h["hang_type"],
+            "thread": (h["thread"] or {}).get("name", ""),
+        }
+        for h in hangs[:top_n]
+    ]
+
+    return {
+        "lane": "hangs",
+        "available": True,
+        "schema_used": schema,
+        "metrics": {
+            "count": len(hangs),
+            "total_duration_ms": round(total_ms, 2),
+            "worst_duration_ms": worst["duration_ms"] if worst else 0,
+            "severity_buckets": buckets,
+        },
+        "top_offenders": top_offenders,
+        "notes": [],
+        "_events": hangs,  # retained for correlation
+    }
+
+
+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/hitches.py

@@ -0,0 +1,145 @@
+"""Animation hitches lane parser.
+
+Xcode 26 schema `hitches` columns: start, duration (hitch time), process,
+is-system, swap-id, label, display, narrative-description. The
+narrative-description field carries Apple's own attribution (e.g.
+"Potentially expensive app update(s)") which is the highest-signal column.
+"""
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from . import xctrace, xml_utils
+
+CANDIDATE_SCHEMAS = ("hitches", "animation-hitch", "hitch")
+
+START_KEYS = ("start", "time", "sample-time")
+DURATION_KEYS = ("duration", "hitch-duration", "frame-duration")
+
+
+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": "hitches",
+            "available": False,
+            "notes": ["Animation hitches not present in trace."],
+        }
+
+    xml_bytes = xctrace.export_schema(trace_path, schema, run=run)
+    stream = xml_utils.RowStream(xml_bytes)
+
+    events: list[dict] = []
+    narrative_counts: Counter[str] = Counter()
+    system_count = 0
+
+    for row in stream:
+        start_ns = _first_int(row, stream, START_KEYS)
+        duration_ns = _first_int(row, stream, DURATION_KEYS)
+        if start_ns is None or duration_ns is None:
+            continue
+        if not xml_utils.event_overlaps_window(start_ns, start_ns + duration_ns, window):
+            continue
+
+        process_el = row.get("process")
+        process = (
+            xml_utils.extract_process(process_el, stream)
+            if process_el is not None else None
+        )
+
+        narrative_el = row.get("narrative-description")
+        narrative = xml_utils.str_text(stream.resolve(narrative_el)) if narrative_el is not None else None
+        if narrative:
+            narrative_counts[narrative] += 1
+
+        is_system_el = row.get("is-system")
+        is_system = _bool_text(stream.resolve(is_system_el)) if is_system_el is not None else None
+        if is_system:
+            system_count += 1
+
+        events.append({
+            "start_ns": start_ns,
+            "end_ns": start_ns + duration_ns,
+            "duration_ns": duration_ns,
+            "hitch_duration_ns": duration_ns,  # Xcode 26 `duration` == hitch time
+            "frame_duration_ns": None,
+            "hitch_duration_ms": round(duration_ns / 1_000_000, 2),
+            "frame_duration_ms": None,
+            "start_ms": round(start_ns / 1_000_000, 2),
+            "process": (process or {}).get("name"),
+            "narrative": narrative,
+            "is_system": bool(is_system) if is_system is not None else None,
+        })
+
+    events.sort(key=lambda e: e["duration_ns"], reverse=True)
+
+    total_hitch_ms = sum(e["hitch_duration_ms"] for e in events)
+    worst = events[0] if events else None
+
+    per_process: dict[str, int] = {}
+    for e in events:
+        key = e["process"] or "unknown"
+        per_process[key] = per_process.get(key, 0) + 1
+
+    top_offenders = [
+        {
+            "start_ms": e["start_ms"],
+            "hitch_duration_ms": e["hitch_duration_ms"],
+            "frame_duration_ms": e["frame_duration_ms"],
+            "process": e["process"],
+            "narrative": e["narrative"],
+            "is_system": e["is_system"],
+        }
+        for e in events[:top_n]
+    ]
+
+    return {
+        "lane": "hitches",
+        "available": True,
+        "schema_used": schema,
+        "metrics": {
+            "count": len(events),
+            "total_hitch_ms": round(total_hitch_ms, 2),
+            "worst_hitch_ms": worst["hitch_duration_ms"] if worst else 0,
+            "per_process": per_process,
+            "system_hitches": system_count,
+            "app_hitches": len(events) - system_count,
+            "narrative_breakdown": dict(narrative_counts.most_common()),
+        },
+        "top_offenders": top_offenders,
+        "notes": [],
+        "_events": events,
+    }
+
+
+def _pick_schema(available: frozenset[str]) -> str | None:
+    for s in CANDIDATE_SCHEMAS:
+        if s in available:
+            return s
+    return None
+
+
+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 _bool_text(elem) -> bool | None:
+    txt = xml_utils.str_text(elem)
+    if txt is None:
+        return None
+    return txt.strip() in ("1", "true", "True", "YES", "Yes")