claudecode-omc 5.6.6 → 5.6.8

package/.local/skills/swiftui-expert-skill/scripts/instruments_parser/correlate.py

@@ -0,0 +1,179 @@
+"""Cross-lane correlation: for each hang and top-N worst hitches, aggregate
+Time Profiler samples and SwiftUI updates whose timestamps fall inside the
+event window [start, start+duration]. Uses bisect so lookups stay O(log N)
+per event.
+"""
+from __future__ import annotations
+
+from bisect import bisect_left, bisect_right
+from collections import defaultdict
+from typing import Any
+
+
+def build(lanes: dict[str, dict], top_hitches: int = 5, top_symbols: int = 5) -> list[dict]:
+    """Produce a list of correlation entries.
+
+    `lanes` is a dict keyed by lane name (time-profiler, hangs, hitches,
+    swiftui) of their analyzer outputs.
+    """
+    tp = lanes.get("time-profiler")
+    hangs = lanes.get("hangs")
+    hitches = lanes.get("hitches")
+    swiftui = lanes.get("swiftui")
+
+    tp_index = _build_time_profile_index(tp)
+    sui_events = (swiftui or {}).get("_events") if swiftui and swiftui.get("available") else None
+
+    correlations: list[dict] = []
+
+    if hangs and hangs.get("available"):
+        for h in hangs.get("_events", []):
+            correlations.append(
+                _correlate_event(
+                    trigger_lane="hangs",
+                    start_ns=h["start_ns"],
+                    end_ns=h["end_ns"],
+                    extra={"hang_type": h["hang_type"]},
+                    tp_index=tp_index,
+                    sui_events=sui_events,
+                    top_symbols=top_symbols,
+                )
+            )
+
+    if hitches and hitches.get("available"):
+        worst_hitches = hitches.get("_events", [])[:top_hitches]
+        for hi in worst_hitches:
+            correlations.append(
+                _correlate_event(
+                    trigger_lane="hitches",
+                    start_ns=hi["start_ns"],
+                    end_ns=hi["end_ns"],
+                    extra={
+                        "frame_duration_ms": hi["frame_duration_ms"],
+                        "hitch_duration_ms": hi["hitch_duration_ms"],
+                    },
+                    tp_index=tp_index,
+                    sui_events=sui_events,
+                    top_symbols=top_symbols,
+                )
+            )
+
+    return correlations
+
+
+# --- Internal -------------------------------------------------------------
+
+def _build_time_profile_index(tp: dict | None):
+    if not tp or not tp.get("available"):
+        return None
+    samples = tp.get("_samples") or []
+    if not samples:
+        return None
+    # Samples are already sorted by time in time_profiler.analyze.
+    times = [s["time_ns"] for s in samples]
+    return {"times": times, "samples": samples}
+
+
+def _correlate_event(
+    trigger_lane: str,
+    start_ns: int,
+    end_ns: int,
+    extra: dict,
+    tp_index: dict | None,
+    sui_events: list[dict] | None,
+    top_symbols: int,
+) -> dict[str, Any]:
+    entry: dict[str, Any] = {
+        "trigger": {
+            "lane": trigger_lane,
+            "start_ms": round(start_ns / 1_000_000, 2),
+            "end_ms": round(end_ns / 1_000_000, 2),
+            "duration_ms": round((end_ns - start_ns) / 1_000_000, 2),
+            **extra,
+        },
+    }
+
+    if tp_index is not None:
+        tp = _time_profile_hot_symbols(
+            tp_index, start_ns, end_ns, top_symbols
+        )
+        duration_ns = end_ns - start_ns
+        # Sample rate is 1ms/sample on standard Time Profiler. If the window
+        # is N ms long we'd expect ~N main-thread samples if main was fully
+        # running; fewer means main was blocked (I/O, lock, etc.).
+        expected_if_running = max(1, duration_ns // 1_000_000)
+        coverage_pct = min(100.0, 100.0 * tp["samples_main"] / expected_if_running)
+        entry["time_profiler_main_thread"] = {
+            "samples_in_window": tp["samples_total"],
+            "samples_on_main": tp["samples_main"],
+            "main_running_coverage_pct": round(coverage_pct, 1),
+            "hot_symbols": tp["hot_symbols"],
+        }
+
+    if sui_events is not None:
+        sui_overlap = _swiftui_overlaps(sui_events, start_ns, end_ns)
+        entry["swiftui_overlapping_updates"] = sui_overlap
+
+    return entry
+
+
+def _time_profile_hot_symbols(
+    tp_index: dict, start_ns: int, end_ns: int, top_n: int
+) -> dict:
+    """Return main-thread hot symbols in the given window.
+
+    Hang/hitch/SwiftUI correlations are all main-thread responsiveness
+    problems, so worker-thread symbols are noise. We also return a coverage
+    metric — when main was blocked on I/O or a lock, the window will have
+    far fewer samples than its duration would predict, and that signal is
+    what tells the agent "this was blocked, not CPU-bound".
+    """
+    times = tp_index["times"]
+    samples = tp_index["samples"]
+    lo = bisect_left(times, start_ns)
+    hi = bisect_right(times, end_ns)
+    window = samples[lo:hi]
+    if not window:
+        return {"samples_total": 0, "samples_main": 0, "hot_symbols": []}
+
+    main_samples = [s for s in window if s["is_main"]]
+    weight_by_symbol: dict[str, int] = defaultdict(int)
+    count_by_symbol: dict[str, int] = defaultdict(int)
+    for s in main_samples:
+        weight_by_symbol[s["leaf_symbol"]] += s["weight_ns"]
+        count_by_symbol[s["leaf_symbol"]] += 1
+    total_weight = sum(weight_by_symbol.values()) or 1
+
+    ranked = sorted(weight_by_symbol.items(), key=lambda kv: kv[1], reverse=True)
+    hot = []
+    for symbol, weight in ranked[:top_n]:
+        hot.append({
+            "symbol": symbol,
+            "samples": count_by_symbol[symbol],
+            "weight_ms": round(weight / 1_000_000, 2),
+            "percent_of_main": round(100.0 * weight / total_weight, 2),
+        })
+    return {
+        "samples_total": len(window),
+        "samples_main": len(main_samples),
+        "hot_symbols": hot,
+    }
+
+
+def _swiftui_overlaps(
+    events: list[dict], start_ns: int, end_ns: int
+) -> list[dict]:
+    # Events aren't guaranteed sorted by start_ns here (we sort by duration in
+    # swiftui.analyze). Linear scan; SwiftUI event counts are typically small.
+    out: list[dict] = []
+    for e in events:
+        if e["end_ns"] < start_ns or e["start_ns"] > end_ns:
+            continue
+        out.append({
+            "view": e["view"],
+            "duration_ms": e["duration_ms"],
+            "start_ms": e["start_ms"],
+        })
+    # Worst first.
+    out.sort(key=lambda x: x["duration_ms"], reverse=True)
+    return out[:10]

package/.local/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/.local/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