claudecode-omc 5.6.7 → 5.6.8

package/.local/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/.local/skills/swiftui-expert-skill/scripts/instruments_parser/__init__.py

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

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