claudecode-omc 5.6.7 → 5.9.1

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

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