claudecode-omc 5.6.6 → 5.6.8

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

@@ -0,0 +1,135 @@
+"""Time Profiler lane parser (schema `time-profile`).
+
+Aggregates CPU samples by leaf symbol, keeps per-sample rows so that other
+lanes can correlate by timestamp window.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from . import xctrace, xml_utils
+
+PREFERRED_SCHEMAS = ("time-profile",)
+FALLBACK_SCHEMAS = ("time-sample",)  # no symbolication; used only if nothing else
+
+
+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": "time-profiler",
+            "available": False,
+            "notes": ["Time Profiler data not present in trace."],
+        }
+
+    xml_bytes = xctrace.export_schema(trace_path, schema, run=run)
+    stream = xml_utils.RowStream(xml_bytes)
+
+    samples: list[dict] = []
+    symbol_weight: dict[str, int] = defaultdict(int)
+    symbol_samples: dict[str, int] = defaultdict(int)
+    symbol_thread: dict[str, str] = {}
+    processes: set[str] = set()
+    total_weight = 0
+    min_time: int | None = None
+    max_time: int | None = None
+
+    for row in stream:
+        time_el = row.get("time")
+        weight_el = row.get("weight")
+        thread_el = row.get("thread")
+        stack_el = row.get("stack")
+        if stack_el is None or time_el is None or thread_el is None:
+            continue
+
+        sample_time_ns = xml_utils.int_text(stream.resolve(time_el))
+        if not xml_utils.in_window(sample_time_ns, window):
+            continue
+        weight_ns = xml_utils.int_text(stream.resolve(weight_el)) or 0
+        frames = xml_utils.extract_backtrace(stack_el, stream, max_frames=20)
+        if not frames:
+            continue
+
+        thread = xml_utils.extract_thread(thread_el, stream)
+        process_name = (thread.get("process") or {}).get("name")
+        if process_name:
+            processes.add(process_name)
+
+        leaf = xml_utils.top_symbol(frames)
+        symbol_weight[leaf] += weight_ns
+        symbol_samples[leaf] += 1
+        symbol_thread.setdefault(
+            leaf, "main" if thread["is_main"] else thread.get("name", "")
+        )
+        total_weight += weight_ns
+
+        if sample_time_ns is not None:
+            min_time = sample_time_ns if min_time is None else min(min_time, sample_time_ns)
+            max_time = sample_time_ns if max_time is None else max(max_time, sample_time_ns)
+
+            samples.append({
+                "time_ns": sample_time_ns,
+                "weight_ns": weight_ns,
+                "thread_name": thread["name"],
+                "is_main": thread["is_main"],
+                "process": process_name,
+                "leaf_symbol": leaf,
+                "frames": frames[:5],
+            })
+
+    samples.sort(key=lambda s: s["time_ns"])
+
+    top = sorted(
+        symbol_weight.items(), key=lambda kv: kv[1], reverse=True
+    )[:top_n]
+    top_offenders = [
+        {
+            "symbol": sym,
+            "weight_ns": w,
+            "weight_ms": round(w / 1_000_000, 2),
+            "samples": symbol_samples[sym],
+            "percent": round(100.0 * w / total_weight, 2) if total_weight else 0.0,
+            "thread": symbol_thread.get(sym, ""),
+        }
+        for sym, w in top
+    ]
+
+    notes: list[str] = []
+    if schema in FALLBACK_SCHEMAS:
+        notes.append(
+            f"Using fallback schema `{schema}`; backtraces may be unsymbolicated."
+        )
+
+    return {
+        "lane": "time-profiler",
+        "available": True,
+        "schema_used": schema,
+        "metrics": {
+            "total_samples": len(samples),
+            "total_weight_ns": total_weight,
+            "total_weight_ms": round(total_weight / 1_000_000, 2),
+            "window_start_ns": min_time,
+            "window_end_ns": max_time,
+            "processes": sorted(processes),
+        },
+        "top_offenders": top_offenders,
+        "notes": notes,
+        # Internal: retained for correlation. Stripped before JSON emission
+        # if --slim is requested by the orchestrator.
+        "_samples": samples,
+    }
+
+
+def _pick_schema(available: frozenset[str]) -> str | None:
+    for s in PREFERRED_SCHEMAS + FALLBACK_SCHEMAS:
+        if s in available:
+            return s
+    return None

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

@@ -0,0 +1,117 @@
+"""Thin wrapper around the `xctrace` CLI."""
+from __future__ import annotations
+
+import subprocess
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class RunInfo:
+    """Per-run metadata and schemas. Instruments traces can hold multiple runs."""
+    number: int
+    template_name: str | None
+    duration_s: float | None
+    start_date: str | None
+    end_date: str | None
+    schemas: frozenset[str]
+
+
+@dataclass(frozen=True)
+class TraceInfo:
+    xctrace_version: str
+    runs: tuple[RunInfo, ...]
+
+    def get_run(self, number: int) -> RunInfo:
+        for r in self.runs:
+            if r.number == number:
+                return r
+        available = ", ".join(str(r.number) for r in self.runs)
+        raise KeyError(f"run {number} not in trace (available: {available})")
+
+
+def version() -> str:
+    out = subprocess.run(
+        ["xctrace", "version"], capture_output=True, text=True, check=True
+    )
+    return out.stdout.strip()
+
+
+def toc(trace_path: Path) -> TraceInfo:
+    """Export the trace's table of contents and return per-run metadata.
+
+    The TOC is small (a few KB) so we load it fully rather than streaming.
+    """
+    xml_bytes = _run_export(trace_path, ["--toc"])
+    root = ET.fromstring(xml_bytes)
+
+    instruments = _find_text(root, ".//instruments-version") or ""
+
+    runs: list[RunInfo] = []
+    for run_el in root.iterfind("./run"):
+        number_attr = run_el.get("number")
+        if not number_attr:
+            continue
+        try:
+            number = int(number_attr)
+        except ValueError:
+            continue
+        if number <= 0:
+            continue
+
+        schemas: set[str] = set()
+        for table in run_el.iterfind("./data/table"):
+            schema = table.get("schema")
+            if schema:
+                schemas.add(schema)
+
+        summary = run_el.find("./info/summary")
+        if summary is not None:
+            template = _find_text(summary, "./template-name")
+            duration = _find_text(summary, "./duration")
+            start = _find_text(summary, "./start-date")
+            end = _find_text(summary, "./end-date")
+        else:
+            template = duration = start = end = None
+
+        runs.append(RunInfo(
+            number=number,
+            template_name=template,
+            duration_s=float(duration) if duration else None,
+            start_date=start,
+            end_date=end,
+            schemas=frozenset(schemas),
+        ))
+
+    runs.sort(key=lambda r: r.number)
+    return TraceInfo(
+        xctrace_version=instruments,
+        runs=tuple(runs),
+    )
+
+
+def export_schema(trace_path: Path, schema: str, run: int = 1) -> bytes:
+    """Export one schema's data as XML bytes from the given run.
+
+    Callers are expected to iterparse the result rather than build a full tree
+    for large schemas (time-profile can be tens of MB).
+    """
+    xpath = f'/trace-toc/run[@number="{run}"]/data/table[@schema="{schema}"]'
+    return _run_export(trace_path, ["--xpath", xpath])
+
+
+def _run_export(trace_path: Path, extra_args: list[str]) -> bytes:
+    cmd = ["xctrace", "export", "--input", str(trace_path), *extra_args]
+    proc = subprocess.run(cmd, capture_output=True, check=False)
+    if proc.returncode != 0:
+        raise RuntimeError(
+            f"xctrace export failed ({proc.returncode}): "
+            f"{proc.stderr.decode(errors='replace').strip()}"
+        )
+    return proc.stdout
+
+
+def _find_text(root: ET.Element, path: str) -> str | None:
+    el = root.find(path)
+    return el.text if el is not None and el.text else None

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

@@ -0,0 +1,224 @@
+"""Streaming XML helpers for xctrace export output.
+
+Instruments XML deduplicates repeated values with `id`/`ref` attributes that
+can span the whole document, so we stream rows with iterparse while keeping
+a global id cache for later ref lookups.
+"""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Column:
+    mnemonic: str          # e.g. "time", "weight", "stack"
+    engineering_type: str  # e.g. "sample-time", "weight", "tagged-backtrace"
+
+
+class RowStream:
+    """Iterate <row> elements of a single <table> schema export.
+
+    Yields `dict[str, Element]` keyed by column mnemonic. Elements inside a
+    yielded row are live ET elements (rooted in the id cache where applicable
+    so ref resolution via `resolve()` remains valid after the row is yielded).
+    """
+
+    def __init__(self, xml_bytes: bytes):
+        self._xml = xml_bytes
+        self.columns: list[Column] = []
+        self._id_cache: dict[str, ET.Element] = {}
+
+    def resolve(self, element: ET.Element) -> ET.Element:
+        """If the element is a ref, return the referenced element; else self."""
+        ref = element.get("ref")
+        if ref is None:
+            return element
+        target = self._id_cache.get(ref)
+        if target is None:
+            return element  # unresolved; return the ref element itself
+        return target
+
+    def __iter__(self) -> Iterator[dict[str, ET.Element]]:
+        # iterparse fires `end` events once an element is fully parsed, so ids
+        # are visible to descendants via the cache. We only need `end` events;
+        # row bodies are reconstructed from the end element itself in _row_dict.
+        #
+        # NOTE: we intentionally don't call `elem.clear()` after yielding a row.
+        # Instruments' XML is a single shared doc where any row can `ref` an
+        # `id` defined earlier (threads, processes, stacks, metadata), and
+        # clearing would break those later lookups. The tradeoff is peak RAM
+        # ≈ document size. That's fine for typical traces up to a few hundred
+        # MB; very large exports may need a smarter pass that first indexes
+        # referenced ids and only retains those.
+        schema_seen = False
+
+        context = ET.iterparse(_bytes_to_file(self._xml), events=("end",))
+        for _event, elem in context:
+            eid = elem.get("id")
+            if eid is not None:
+                self._id_cache[eid] = elem
+
+            if elem.tag == "schema" and not schema_seen:
+                self.columns = _parse_columns(elem)
+                schema_seen = True
+                continue
+
+            if elem.tag == "row":
+                yield _row_dict(elem, self.columns)
+                # Do not clear elem — children referenced via id may still be needed.
+
+
+def _parse_columns(schema_el: ET.Element) -> list[Column]:
+    cols: list[Column] = []
+    for col in schema_el.findall("col"):
+        mnemonic = (col.findtext("mnemonic") or "").strip()
+        etype = (col.findtext("engineering-type") or "").strip()
+        if mnemonic:
+            cols.append(Column(mnemonic=mnemonic, engineering_type=etype))
+    return cols
+
+
+def _row_dict(row_el: ET.Element, cols: list[Column]) -> dict[str, ET.Element]:
+    # Row children map positionally to columns. <sentinel/> marks a missing
+    # optional value for that column.
+    result: dict[str, ET.Element] = {}
+    children = list(row_el)
+    for idx, child in enumerate(children):
+        if idx >= len(cols):
+            break
+        if child.tag == "sentinel":
+            continue
+        result[cols[idx].mnemonic] = child
+    return result
+
+
+def _bytes_to_file(data: bytes):
+    import io
+    return io.BytesIO(data)
+
+
+# --- Extraction helpers ---------------------------------------------------
+
+def int_text(elem: ET.Element | None) -> int | None:
+    if elem is None or elem.text is None:
+        return None
+    try:
+        return int(elem.text)
+    except ValueError:
+        return None
+
+
+def str_text(elem: ET.Element | None) -> str | None:
+    if elem is None or elem.text is None:
+        return None
+    return elem.text
+
+
+def fmt_attr(elem: ET.Element | None) -> str | None:
+    """Return the human-readable `fmt` attribute if present."""
+    if elem is None:
+        return None
+    return elem.get("fmt")
+
+
+def extract_thread(thread_el: ET.Element, stream: RowStream) -> dict:
+    """Parse a <thread> element into name, tid, process dict.
+
+    Handles ref-style threads by resolving through the stream's id cache.
+    """
+    resolved = stream.resolve(thread_el)
+    name = resolved.get("fmt", "")
+    tid_el = resolved.find("tid")
+    process_el = resolved.find("process")
+    process = extract_process(process_el, stream) if process_el is not None else None
+    return {
+        "name": name,
+        "tid": int_text(tid_el),
+        "process": process,
+        "is_main": name.startswith("Main Thread") if name else False,
+    }
+
+
+def extract_process(process_el: ET.Element, stream: RowStream) -> dict:
+    resolved = stream.resolve(process_el)
+    name = resolved.get("fmt", "")
+    pid_el = resolved.find("pid")
+    return {
+        "name": _clean_process_name(name),
+        "pid": int_text(pid_el),
+    }
+
+
+def _clean_process_name(fmt: str) -> str:
+    # "NowPlaying Gigs (28401)" -> "NowPlaying Gigs"
+    if " (" in fmt and fmt.endswith(")"):
+        return fmt.rsplit(" (", 1)[0]
+    return fmt
+
+
+def extract_backtrace(
+    bt_el: ET.Element, stream: RowStream, max_frames: int = 20
+) -> list[dict]:
+    """Return a list of frame dicts from a <tagged-backtrace> or <backtrace>.
+
+    Frames are ordered leaf-first (top of stack first), matching Instruments'
+    display order.
+    """
+    resolved = stream.resolve(bt_el)
+    inner = resolved.find("backtrace")
+    if inner is None:
+        inner = resolved
+    frames: list[dict] = []
+    for frame_el in inner.findall("frame"):
+        f = stream.resolve(frame_el)
+        frames.append({
+            "name": f.get("name") or "",
+            "addr": f.get("addr") or "",
+        })
+        if len(frames) >= max_frames:
+            break
+    return frames
+
+
+def top_symbol(frames: list[dict]) -> str:
+    """Pick the leaf symbol, falling back to addr if unsymbolicated."""
+    if not frames:
+        return "<empty-stack>"
+    first = frames[0]
+    return first.get("name") or first.get("addr") or "<unknown>"
+
+
+def first_present(row: dict, *keys: str) -> ET.Element | None:
+    """Return the first row column whose key exists.
+
+    `row[key] or row[other_key]` is unsafe here: Element is falsy when it has
+    no children (a common case for leaf <event-time>, <start-time>, etc.), so
+    `or` short-circuits past valid leaf elements. This walks keys explicitly.
+    """
+    for key in keys:
+        el = row.get(key)
+        if el is not None:
+            return el
+    return None
+
+
+def in_window(time_ns: int | None, window: tuple[int, int] | None) -> bool:
+    """Return True if time_ns is inside [start, end] (inclusive), or window is None."""
+    if window is None:
+        return True
+    if time_ns is None:
+        return False
+    start, end = window
+    return start <= time_ns <= end
+
+
+def event_overlaps_window(
+    start_ns: int, end_ns: int, window: tuple[int, int] | None
+) -> bool:
+    """Return True if [start, end] overlaps [window.start, window.end]."""
+    if window is None:
+        return True
+    w_start, w_end = window
+    return not (end_ns < w_start or start_ns > w_end)