opencode-skills-collection 3.1.12 → 3.1.14

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

@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+"""Analyze an Xcode Instruments .trace file and emit JSON + markdown.
+
+Primary modes:
+  (default)           Full four-lane analysis + cross-lane correlations.
+  --list-logs         Dump os_log entries (optionally filtered) as JSON so an
+                      agent can locate a focus window by log content.
+  --list-signposts    Dump os_signpost intervals + point events as JSON.
+
+Windowing:
+  --window START_MS:END_MS restricts every lane to that slice of the trace.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from instruments_parser import (
+    causes,
+    correlate,
+    events,
+    hangs,
+    hitches,
+    summary,
+    swiftui,
+    time_profiler,
+    xctrace,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Analyze an Instruments .trace file.",
+    )
+    parser.add_argument("--trace", required=True, type=Path)
+    parser.add_argument(
+        "--output",
+        type=Path,
+        help="Base path; writes <output>.json and <output>.md",
+    )
+    parser.add_argument("--top", type=int, default=10, help="Top-N per lane")
+    parser.add_argument(
+        "--top-hitches",
+        type=int,
+        default=5,
+        help="Correlate only the N worst hitches (avoid flooding output).",
+    )
+    parser.add_argument(
+        "--window",
+        type=str,
+        default=None,
+        help="Restrict analysis to a time slice, e.g. --window 10400:11700 (ms).",
+    )
+    parser.add_argument(
+        "--run",
+        type=int,
+        default=None,
+        help="Which run to analyze (1-based). Required for traces with >1 run.",
+    )
+    parser.add_argument(
+        "--list-runs", action="store_true",
+        help="Emit per-run metadata as JSON (use this to discover available runs).",
+    )
+
+    # Mode flags (mutually exclusive with full analysis)
+    mode_group = parser.add_argument_group("Discovery modes")
+    mode_group.add_argument(
+        "--list-logs", action="store_true",
+        help="Emit os_log entries as JSON (use filter flags below).",
+    )
+    mode_group.add_argument(
+        "--list-signposts", action="store_true",
+        help="Emit os_signpost intervals + events as JSON.",
+    )
+    mode_group.add_argument("--log-subsystem", type=str, default=None)
+    mode_group.add_argument("--log-category", type=str, default=None)
+    mode_group.add_argument(
+        "--log-type", type=str, default=None,
+        help="e.g. Fault, Error, Default, Info, Debug",
+    )
+    mode_group.add_argument(
+        "--log-message-contains", type=str, default=None,
+        help="Case-insensitive substring match on the message / format string.",
+    )
+    mode_group.add_argument(
+        "--log-limit", type=int, default=None,
+        help="Cap number of log entries returned (applied after all filters).",
+    )
+    mode_group.add_argument(
+        "--signpost-name-contains", type=str, default=None,
+        help="Case-insensitive substring match on signpost name.",
+    )
+    mode_group.add_argument("--signpost-subsystem", type=str, default=None)
+    mode_group.add_argument("--signpost-category", type=str, default=None)
+    mode_group.add_argument(
+        "--fanin-for", type=str, default=None,
+        help="Emit incoming cause-graph sources for destinations whose fmt "
+             "contains this substring. Case-insensitive.",
+    )
+
+    fmt_group = parser.add_mutually_exclusive_group()
+    fmt_group.add_argument("--json-only", action="store_true")
+    fmt_group.add_argument("--markdown-only", action="store_true")
+
+    args = parser.parse_args(argv)
+
+    # The discovery modes aren't in a mutually_exclusive_group because they
+    # live alongside their sub-filters in the same argparse group; enforce the
+    # constraint by hand so an agent gets a clear error instead of silent
+    # precedence.
+    active_modes = sum([
+        args.list_runs,
+        args.list_logs,
+        args.list_signposts,
+        bool(args.fanin_for),
+    ])
+    if active_modes > 1:
+        parser.error(
+            "--list-runs, --list-logs, --list-signposts, and --fanin-for are "
+            "mutually exclusive; pick one per invocation."
+        )
+
+    trace = args.trace
+    if not trace.exists():
+        print(f"error: trace not found: {trace}", file=sys.stderr)
+        return 2
+
+    info = xctrace.toc(trace)
+    window_ns = _parse_window(args.window)
+
+    if args.list_runs:
+        sys.stdout.write(json.dumps({
+            "xctrace_version": info.xctrace_version,
+            "runs": [
+                {
+                    "number": r.number,
+                    "template": r.template_name,
+                    "duration_s": r.duration_s,
+                    "start_date": r.start_date,
+                    "end_date": r.end_date,
+                    "schemas": sorted(r.schemas),
+                }
+                for r in info.runs
+            ],
+        }, indent=2))
+        sys.stdout.write("\n")
+        return 0
+
+    run_info = _resolve_run(info, args.run)
+    if run_info is None:
+        return 2
+    run_number = run_info.number
+
+    if args.list_logs:
+        out = events.list_logs(
+            trace, run_info.schemas,
+            subsystem=args.log_subsystem,
+            category=args.log_category,
+            message_contains=args.log_message_contains,
+            message_type=args.log_type,
+            limit=args.log_limit,
+            window_ns=window_ns,
+            run=run_number,
+        )
+        sys.stdout.write(json.dumps({"logs": out, "count": len(out)}, indent=2))
+        sys.stdout.write("\n")
+        return 0
+
+    if args.list_signposts:
+        sp = events.list_signposts(
+            trace, run_info.schemas,
+            name_contains=args.signpost_name_contains,
+            subsystem=args.signpost_subsystem,
+            category=args.signpost_category,
+            window_ns=window_ns,
+            run=run_number,
+        )
+        sys.stdout.write(json.dumps(sp, indent=2))
+        sys.stdout.write("\n")
+        return 0
+
+    if args.fanin_for:
+        fanin = causes.fanin_for(
+            trace, run_info.schemas,
+            destination_contains=args.fanin_for,
+            top_k=args.top,
+            window=window_ns,
+            run=run_number,
+        )
+        sys.stdout.write(json.dumps(fanin, indent=2))
+        sys.stdout.write("\n")
+        return 0
+
+    # Full five-lane analysis
+    schemas = run_info.schemas
+    lanes_out = {
+        "time-profiler":  time_profiler.analyze(trace, schemas, top_n=args.top, window=window_ns, run=run_number),
+        "hangs":          hangs.analyze(trace, schemas, top_n=args.top, window=window_ns, run=run_number),
+        "hitches":        hitches.analyze(trace, schemas, top_n=args.top, window=window_ns, run=run_number),
+        "swiftui":        swiftui.analyze(trace, schemas, top_n=args.top, window=window_ns, run=run_number),
+        "swiftui-causes": causes.analyze(trace, schemas, top_n=args.top, window=window_ns, run=run_number),
+    }
+    correlations = correlate.build(
+        lanes_out, top_hitches=args.top_hitches, top_symbols=5
+    )
+    public_lanes = [_strip_internal(l) for l in lanes_out.values()]
+
+    result: dict = {
+        "trace": str(trace),
+        "xctrace_version": info.xctrace_version,
+        "run": run_number,
+        "runs_available": [r.number for r in info.runs],
+        "template": run_info.template_name,
+        "duration_s": run_info.duration_s,
+        "start_date": run_info.start_date,
+        "end_date": run_info.end_date,
+        "schemas_available": sorted(run_info.schemas),
+        "lanes": public_lanes,
+        "correlations": correlations,
+    }
+    if window_ns is not None:
+        result["window_ms"] = {
+            "start": window_ns[0] / 1_000_000,
+            "end": window_ns[1] / 1_000_000,
+        }
+
+    md = summary.render(result)
+
+    if args.output:
+        json_path = args.output.with_suffix(".json")
+        md_path = args.output.with_suffix(".md")
+        json_path.write_text(json.dumps(result, indent=2))
+        md_path.write_text(md)
+        print(f"wrote {json_path}")
+        print(f"wrote {md_path}")
+        return 0
+
+    if args.markdown_only:
+        sys.stdout.write(md)
+    elif args.json_only:
+        sys.stdout.write(json.dumps(result, indent=2))
+        sys.stdout.write("\n")
+    else:
+        sys.stdout.write(json.dumps(result, indent=2))
+        sys.stdout.write("\n---\n")
+        sys.stdout.write(md)
+    return 0
+
+
+def _resolve_run(info, requested: int | None):
+    """Pick a run from the trace.
+
+    If `requested` is given, return that run or None on miss (with a friendly
+    error). If unset and the trace has exactly one run, default to it. If
+    unset and there are multiple runs, error out so the agent picks
+    explicitly — silently picking run 1 lost data for the user.
+    """
+    if not info.runs:
+        print("error: trace has no runs", file=sys.stderr)
+        return None
+    if requested is not None:
+        try:
+            return info.get_run(requested)
+        except KeyError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return None
+    if len(info.runs) == 1:
+        return info.runs[0]
+    available = ", ".join(str(r.number) for r in info.runs)
+    print(
+        f"error: trace has {len(info.runs)} runs ({available}); pass --run N. "
+        f"Use --list-runs to see per-run metadata.",
+        file=sys.stderr,
+    )
+    return None
+
+
+def _parse_window(spec: str | None) -> tuple[int, int] | None:
+    if not spec:
+        return None
+    if ":" not in spec:
+        raise SystemExit(f"--window expects START_MS:END_MS, got {spec!r}")
+    start_s, end_s = spec.split(":", 1)
+    try:
+        start_ms = float(start_s)
+        end_ms = float(end_s)
+    except ValueError as e:
+        raise SystemExit(f"--window: {e}")
+    if end_ms < start_ms:
+        raise SystemExit("--window: end_ms must be >= start_ms")
+    return (int(start_ms * 1_000_000), int(end_ms * 1_000_000))
+
+
+def _strip_internal(lane: dict) -> dict:
+    return {k: v for k, v in lane.items() if not k.startswith("_")}
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1 @@
+"""Parsers for Xcode Instruments .trace files via xctrace export."""

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

@@ -0,0 +1,187 @@
+"""SwiftUI cause-graph lane (`swiftui-causes` schema).
+
+Instruments emits one row per edge in SwiftUI's dependency graph: every time
+a source node (a state change, user defaults observer, system event, etc.)
+propagates to a destination node (a body evaluation, layout, creation), a
+row is written with both endpoints as metadata values.
+
+This lane aggregates those edges two ways:
+
+- **By source node** — which attribute graph nodes are driving the most
+  updates overall. The canonical "why is my app thrashing?" view; a
+  `UserDefaultObserver.send()` showing up with 11k outgoing edges is a
+  feedback storm.
+- **By destination node** — which views/modifiers receive the most
+  invalidations, and from whom. Use this to trace a hot view back to the
+  source that keeps poking it.
+
+The analyzer's main lane (`swiftui`) tells you *what* updates are
+expensive; this lane tells you *why* they keep happening.
+"""
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any
+
+from . import xctrace, xml_utils
+
+SCHEMA = "swiftui-causes"
+
+# Metadata nodes render as space-separated field dumps ("A gray icon n/a n/a").
+# We aggregate on the full fmt string so callers can spot specific edges like
+# "@AppStorage TextStyleModifier.fontOption", but also expose the short head
+# ("@AppStorage", "Creation of App", ...) for coarser grouping.
+
+
+def analyze(
+    trace_path: Path,
+    toc_schemas: frozenset[str],
+    top_n: int = 10,
+    top_k_per_node: int = 5,
+    window: tuple[int, int] | None = None,
+    run: int = 1,
+) -> dict[str, Any]:
+    if SCHEMA not in toc_schemas:
+        return {
+            "lane": "swiftui-causes",
+            "available": False,
+            "notes": [
+                "SwiftUI causes data not present (requires SwiftUI template on a real device).",
+            ],
+        }
+
+    xml_bytes = xctrace.export_schema(trace_path, SCHEMA, run=run)
+    stream = xml_utils.RowStream(xml_bytes)
+
+    source_edges: Counter[str] = Counter()
+    destination_edges: Counter[str] = Counter()
+    fanout: dict[str, Counter[str]] = defaultdict(Counter)
+    fanin: dict[str, Counter[str]] = defaultdict(Counter)
+    label_counts: Counter[str] = Counter()
+    total_edges = 0
+
+    for row in stream:
+        time_el = xml_utils.first_present(row, "timestamp", "time")
+        if time_el is not None:
+            t_ns = xml_utils.int_text(stream.resolve(time_el))
+            if t_ns is not None and not xml_utils.in_window(t_ns, window):
+                continue
+
+        src = _fmt(row, stream, "source-node")
+        dst = _fmt(row, stream, "destination-node")
+        if not src or not dst:
+            continue
+
+        source_edges[src] += 1
+        destination_edges[dst] += 1
+        fanout[src][dst] += 1
+        fanin[dst][src] += 1
+
+        label = _fmt(row, stream, "label")
+        if label:
+            label_counts[label] += 1
+
+        total_edges += 1
+
+    top_sources = [
+        {
+            "source": src,
+            "edges": count,
+            "top_destinations": [
+                {"destination": d, "edges": c}
+                for d, c in fanout[src].most_common(top_k_per_node)
+            ],
+        }
+        for src, count in source_edges.most_common(top_n)
+    ]
+
+    top_destinations = [
+        {
+            "destination": dst,
+            "edges": count,
+            "top_sources": [
+                {"source": s, "edges": c}
+                for s, c in fanin[dst].most_common(top_k_per_node)
+            ],
+        }
+        for dst, count in destination_edges.most_common(top_n)
+    ]
+
+    return {
+        "lane": "swiftui-causes",
+        "available": True,
+        "schema_used": SCHEMA,
+        "metrics": {
+            "total_edges": total_edges,
+            "unique_sources": len(source_edges),
+            "unique_destinations": len(destination_edges),
+            "top_labels": dict(label_counts.most_common(top_n)),
+        },
+        "top_sources": top_sources,
+        "top_destinations": top_destinations,
+        "notes": [],
+    }
+
+
+def fanin_for(
+    trace_path: Path,
+    toc_schemas: frozenset[str],
+    destination_contains: str,
+    top_k: int = 10,
+    window: tuple[int, int] | None = None,
+    run: int = 1,
+) -> dict[str, Any]:
+    """Return the top source nodes feeding any destination whose fmt string
+    contains `destination_contains` (case-insensitive substring).
+
+    Used when the agent has a suspect view from the `swiftui` lane and wants
+    to know *who keeps invalidating it*. Does a full pass over the causes
+    schema each time — cheap enough at typical trace sizes.
+    """
+    if SCHEMA not in toc_schemas:
+        return {"available": False, "matches": []}
+
+    needle = destination_contains.lower()
+    xml_bytes = xctrace.export_schema(trace_path, SCHEMA, run=run)
+    stream = xml_utils.RowStream(xml_bytes)
+
+    matches: dict[str, Counter[str]] = defaultdict(Counter)
+    totals: Counter[str] = Counter()
+
+    for row in stream:
+        time_el = xml_utils.first_present(row, "timestamp", "time")
+        if time_el is not None:
+            t_ns = xml_utils.int_text(stream.resolve(time_el))
+            if t_ns is not None and not xml_utils.in_window(t_ns, window):
+                continue
+
+        dst = _fmt(row, stream, "destination-node")
+        if not dst or needle not in dst.lower():
+            continue
+        src = _fmt(row, stream, "source-node")
+        if not src:
+            continue
+
+        matches[dst][src] += 1
+        totals[dst] += 1
+
+    out = []
+    for dst, count in totals.most_common(top_k):
+        out.append({
+            "destination": dst,
+            "total_incoming_edges": count,
+            "top_sources": [
+                {"source": s, "edges": c}
+                for s, c in matches[dst].most_common(top_k)
+            ],
+        })
+    return {"available": True, "matches": out}
+
+
+def _fmt(row, stream, key: str) -> str | None:
+    el = row.get(key)
+    if el is None:
+        return None
+    resolved = stream.resolve(el)
+    return resolved.get("fmt") or xml_utils.str_text(resolved)

package/bundled-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]