1"""Cross-lane correlation: for each hang and top-N worst hitches, aggregate
2Time Profiler samples and SwiftUI updates whose timestamps fall inside the
3event window [start, start+duration]. Uses bisect so lookups stay O(log N)
4per event.
5"""
6from __future__ import annotations
7 
8from bisect import bisect_left, bisect_right
9from collections import defaultdict
10from typing import Any
11 
12 
13def build(lanes: dict[str, dict], top_hitches: int = 5, top_symbols: int = 5) -> list[dict]:
14    """Produce a list of correlation entries.
15 
16    `lanes` is a dict keyed by lane name (time-profiler, hangs, hitches,
17    swiftui) of their analyzer outputs.
18    """
19    tp = lanes.get("time-profiler")
20    hangs = lanes.get("hangs")
21    hitches = lanes.get("hitches")
22    swiftui = lanes.get("swiftui")
23 
24    tp_index = _build_time_profile_index(tp)
25    sui_events = (swiftui or {}).get("_events") if swiftui and swiftui.get("available") else None
26 
27    correlations: list[dict] = []
28 
29    if hangs and hangs.get("available"):
30        for h in hangs.get("_events", []):
31            correlations.append(
32                _correlate_event(
33                    trigger_lane="hangs",
34                    start_ns=h["start_ns"],
35                    end_ns=h["end_ns"],
36                    extra={"hang_type": h["hang_type"]},
37                    tp_index=tp_index,
38                    sui_events=sui_events,
39                    top_symbols=top_symbols,
40                )
41            )
42 
43    if hitches and hitches.get("available"):
44        worst_hitches = hitches.get("_events", [])[:top_hitches]
45        for hi in worst_hitches:
46            correlations.append(
47                _correlate_event(
48                    trigger_lane="hitches",
49                    start_ns=hi["start_ns"],
50                    end_ns=hi["end_ns"],
51                    extra={
52                        "frame_duration_ms": hi["frame_duration_ms"],
53                        "hitch_duration_ms": hi["hitch_duration_ms"],
54                    },
55                    tp_index=tp_index,
56                    sui_events=sui_events,
57                    top_symbols=top_symbols,
58                )
59            )
60 
61    return correlations
62 
63 
64# --- Internal -------------------------------------------------------------
65 
66def _build_time_profile_index(tp: dict | None):
67    if not tp or not tp.get("available"):
68        return None
69    samples = tp.get("_samples") or []
70    if not samples:
71        return None
72    # Samples are already sorted by time in time_profiler.analyze.
73    times = [s["time_ns"] for s in samples]
74    return {"times": times, "samples": samples}
75 
76 
77def _correlate_event(
78    trigger_lane: str,
79    start_ns: int,
80    end_ns: int,
81    extra: dict,
82    tp_index: dict | None,
83    sui_events: list[dict] | None,
84    top_symbols: int,
85) -> dict[str, Any]:
86    entry: dict[str, Any] = {
87        "trigger": {
88            "lane": trigger_lane,
89            "start_ms": round(start_ns / 1_000_000, 2),
90            "end_ms": round(end_ns / 1_000_000, 2),
91            "duration_ms": round((end_ns - start_ns) / 1_000_000, 2),
92            **extra,
93        },
94    }
95 
96    if tp_index is not None:
97        tp = _time_profile_hot_symbols(
98            tp_index, start_ns, end_ns, top_symbols
99        )
100        duration_ns = end_ns - start_ns
101        # Sample rate is 1ms/sample on standard Time Profiler. If the window
102        # is N ms long we'd expect ~N main-thread samples if main was fully
103        # running; fewer means main was blocked (I/O, lock, etc.).
104        expected_if_running = max(1, duration_ns // 1_000_000)
105        coverage_pct = min(100.0, 100.0 * tp["samples_main"] / expected_if_running)
106        entry["time_profiler_main_thread"] = {
107            "samples_in_window": tp["samples_total"],
108            "samples_on_main": tp["samples_main"],
109            "main_running_coverage_pct": round(coverage_pct, 1),
110            "hot_symbols": tp["hot_symbols"],
111        }
112 
113    if sui_events is not None:
114        sui_overlap = _swiftui_overlaps(sui_events, start_ns, end_ns)
115        entry["swiftui_overlapping_updates"] = sui_overlap
116 
117    return entry
118 
119 
120def _time_profile_hot_symbols(
121    tp_index: dict, start_ns: int, end_ns: int, top_n: int
122) -> dict:
123    """Return main-thread hot symbols in the given window.
124 
125    Hang/hitch/SwiftUI correlations are all main-thread responsiveness
126    problems, so worker-thread symbols are noise. We also return a coverage
127    metric — when main was blocked on I/O or a lock, the window will have
128    far fewer samples than its duration would predict, and that signal is
129    what tells the agent "this was blocked, not CPU-bound".
130    """
131    times = tp_index["times"]
132    samples = tp_index["samples"]
133    lo = bisect_left(times, start_ns)
134    hi = bisect_right(times, end_ns)
135    window = samples[lo:hi]
136    if not window:
137        return {"samples_total": 0, "samples_main": 0, "hot_symbols": []}
138 
139    main_samples = [s for s in window if s["is_main"]]
140    weight_by_symbol: dict[str, int] = defaultdict(int)
141    count_by_symbol: dict[str, int] = defaultdict(int)
142    for s in main_samples:
143        weight_by_symbol[s["leaf_symbol"]] += s["weight_ns"]
144        count_by_symbol[s["leaf_symbol"]] += 1
145    total_weight = sum(weight_by_symbol.values()) or 1
146 
147    ranked = sorted(weight_by_symbol.items(), key=lambda kv: kv[1], reverse=True)
148    hot = []
149    for symbol, weight in ranked[:top_n]:
150        hot.append({
151            "symbol": symbol,
152            "samples": count_by_symbol[symbol],
153            "weight_ms": round(weight / 1_000_000, 2),
154            "percent_of_main": round(100.0 * weight / total_weight, 2),
155        })
156    return {
157        "samples_total": len(window),
158        "samples_main": len(main_samples),
159        "hot_symbols": hot,
160    }
161 
162 
163def _swiftui_overlaps(
164    events: list[dict], start_ns: int, end_ns: int
165) -> list[dict]:
166    # Events aren't guaranteed sorted by start_ns here (we sort by duration in
167    # swiftui.analyze). Linear scan; SwiftUI event counts are typically small.
168    out: list[dict] = []
169    for e in events:
170        if e["end_ns"] < start_ns or e["start_ns"] > end_ns:
171            continue
172        out.append({
173            "view": e["view"],
174            "duration_ms": e["duration_ms"],
175            "start_ms": e["start_ms"],
176        })
177    # Worst first.
178    out.sort(key=lambda x: x["duration_ms"], reverse=True)
179    return out[:10]
180