@joystack/cli 0.0.0-stage → 0.1.43

package/lib/replay-profile.mjs

@@ -0,0 +1,467 @@
+// `joystack replay profile` — which functions a stretch of a recorded session
+// spends its time in, written down as a table.
+//
+// The performance track says what a stretch cost on the device that played it
+// and how that split between simulating, presenting and drawing. It cannot say
+// which functions inside the simulation spent the time: no per-frame counter
+// can carry that, and no phone can be asked for it twice. The replay can: it
+// runs the same simulation on the same inputs, so re-running the ticks under a
+// sampling profiler names the functions.
+//
+// What a profile here can NOT say is what any of it cost on the device. This
+// machine has a different CPU, a different JIT state and no thermal throttle,
+// so the table holds shares of this machine's samples, never the device's
+// milliseconds. It covers the simulation only — the room and the traits it
+// ticks — because a replay draws nothing.
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadOpenReplay, rowSinkFor } from './replay-export.mjs';
+import { streamDir } from './replay-store.mjs';
+import { sourcePath } from './source-path.mjs';
+import { STATE_DIR_NAMES } from './legacy-names.mjs';
+
+// The sampling interval, in microseconds. A second of simulation on a
+// developer machine runs in tens of milliseconds, and V8's default of 1 ms
+// would give it a few dozen samples — too few for one sample to be less than
+// several percent.
+export const PROFILE_SAMPLE_US = 100;
+
+// How many ticks one profile covers before it is stopped, reduced to the
+// functions that ran, and started again. A profile holds every sample until it
+// is stopped, and a range is as long as the session a recording claims, so a
+// whole long session in one profile is one very large object.
+const PROFILE_PIECE_TICKS = 600;
+
+/**
+ * `--ticks 1195-1228` (or one tick) as `{ from, to }`. Throws, naming the flag,
+ * on anything else.
+ */
+export function parseTickRange(text) {
+  const m = /^\s*(\d+)\s*(?:[-–]\s*(\d+))?\s*$/.exec(String(text ?? ''));
+  const from = m ? Number(m[1]) : NaN;
+  const to = m ? Number(m[2] ?? m[1]) : NaN;
+  if (!m || !Number.isSafeInteger(from) || !Number.isSafeInteger(to) || to < from) {
+    throw new Error(`--ticks takes a tick or a range of ticks, like 1195-1228, and ${JSON.stringify(String(text ?? ''))} is not one`);
+  }
+  return { from, to };
+}
+
+// Samples that are the profiler or the process rather than the game: stopping
+// a profile posts through the inspector, and `(idle)` is the process waiting.
+// Counting either would rank the measurement among the things it measures.
+const notTheGame = (frame) => String(frame?.url ?? '').startsWith('node:inspector') || frame?.functionName === '(idle)';
+
+// ── which tick or channel handler a sample ran under ─────────────────────────
+//
+// A function's name and file say what ran, not why: the same query helper runs
+// under every trait that reads a query, and a trait's tick is usually an
+// anonymous arrow. So while the profiler runs, each kind's ticks and channel
+// handlers are swapped for stand-ins with names of their own —
+// `joystack_run_<n>`, numbered into a list of what each one is — and a sample is
+// credited to the nearest stand-in above it in the call stack. A stand-in is a
+// function built with `new Function`, because V8 names a profile's frames by
+// the function's source, and closures made by one source text share one name.
+// Samples under no stand-in are the engine's own work around the traits:
+// draining inputs, the sync phase, reading the world back.
+const RUN_PREFIX = 'joystack_run_';
+
+/**
+ * Swap every tick and channel handler of a replayer's runtime for a named
+ * stand-in. Returns what each stand-in is, and a function that puts the
+ * originals back. A channel handler's trait comes from the lowered game's
+ * `channelOrigins`, since the runtime's handler table is keyed by channel name
+ * alone.
+ */
+function instrumentRuns(runtime, channelOrigins) {
+  const runs = [];
+  const undo = [];
+  const code = runtime?.code;
+  if (!code || typeof code !== 'object') return { runs, restore: () => {} };
+  const name = (v) => (typeof v === 'string' ? v : null);
+  const standIn = (inner, n) => new Function('inner', `return function ${RUN_PREFIX}${n}(a, b, c) { return inner(a, b, c); };`)(inner);
+  for (const [kind, impl] of Object.entries(code)) {
+    const ticks = Array.isArray(impl?.ticks) ? impl.ticks : [];
+    ticks.forEach((t, position) => {
+      if (typeof t?.fn !== 'function') return;
+      const original = t.fn;
+      // A tick's place in the list is its place in the kind's run order.
+      runs.push({ kind, trait: name(t.trait), instance: name(t.instance), tick_index: position, channel: null });
+      t.fn = standIn(original, runs.length - 1);
+      undo.push(() => { t.fn = original; });
+    });
+    const handlers = impl?.handlers;
+    if (handlers && typeof handlers === 'object') {
+      for (const [channel, original] of Object.entries(handlers)) {
+        if (typeof original !== 'function') continue;
+        const origin = channelOrigins?.[kind] && Object.hasOwn(channelOrigins[kind], channel) ? channelOrigins[kind][channel] : null;
+        runs.push({ kind, trait: name(origin?.trait), instance: name(origin?.instance), tick_index: null, channel });
+        handlers[channel] = standIn(original, runs.length - 1);
+        undo.push(() => { handlers[channel] = original; });
+      }
+    }
+  }
+  return { runs, restore: () => { for (const u of undo) u(); } };
+}
+
+/**
+ * Where a frame's code lives, as a person would look for it: relative to the
+ * game folder, or inside the engine's package, with a one-based line.
+ */
+export function sourceLabel(frame, { dir = null, sharedDir = null } = {}) {
+  const url = frame?.url ?? '';
+  if (!url) return '(native)';
+  // V8 line numbers are zero-based; every editor and stack trace is not.
+  const line = (frame.lineNumber ?? -1) + 1;
+  let where = url;
+  if (url.startsWith('file:')) {
+    let path;
+    try { path = fileURLToPath(url); } catch { path = null; }
+    where = sourcePath(path, { dir, sharedDir }) ?? url;
+  }
+  return `${where}:${line}`;
+}
+
+// A frame's file, as a path, when it is a file on disk.
+function framePath(frame) {
+  const url = frame?.url ?? '';
+  if (!url.startsWith('file:')) return null;
+  try { return fileURLToPath(url); } catch { return null; }
+}
+
+// Whether a frame is the game's own code: a file inside the game folder that
+// is not installed there — the engine, this CLI and every other package live
+// under `node_modules/` — and not the tooling's own `.joystack/` folder.
+const gameFrameTest = ({ dir, sharedDir }) => {
+  const memo = new Map();
+  return (frame) => {
+    const url = frame?.url ?? '';
+    if (!dir || !url) return false;
+    if (!memo.has(url)) {
+      const at = sourcePath(framePath(frame), { dir, sharedDir });
+      const first = at?.split('/')[0];
+      memo.set(url, at !== null && !at.startsWith('@joystack/engine/') && first !== 'node_modules' && !STATE_DIR_NAMES.includes(first));
+    }
+    return memo.get(url);
+  };
+};
+
+// Every sampled node of one profile, with the stand-in it ran under (or null),
+// and the innermost frame of the game's own code at or above it (or null).
+function* sampledNodes(profile, runs, isGame = () => false) {
+  const nodes = profile?.nodes ?? [];
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const parent = new Map();
+  for (const n of nodes) for (const c of n.children ?? []) parent.set(c, n.id);
+  // Both walk up the call tree from a node; memoised, so each node is visited
+  // once however many samples sit below it.
+  const upward = (test) => {
+    const memo = new Map();
+    const find = (id) => {
+      if (memo.has(id)) return memo.get(id);
+      const n = byId.get(id);
+      let found = test(n);
+      if (found === undefined) found = parent.has(id) ? find(parent.get(id)) : null;
+      memo.set(id, found);
+      return found;
+    };
+    return find;
+  };
+  const runOf = upward((n) => {
+    const name = n?.callFrame?.functionName ?? '';
+    return name.startsWith(RUN_PREFIX) ? (runs[Number(name.slice(RUN_PREFIX.length))] ?? null) : undefined;
+  });
+  const gameOf = upward((n) => (n && isGame(n.callFrame) ? n.callFrame : undefined));
+  for (const n of nodes) {
+    const hits = n.hitCount ?? 0;
+    if (!hits || notTheGame(n.callFrame)) continue;
+    yield { node: n, hits, run: n.id != null ? runOf(n.id) : null, game: n.id != null ? gameOf(n.id) : null };
+  }
+}
+
+const EMPTY_RUN = { kind: null, trait: null, instance: null, tick_index: null, channel: null };
+
+// Which of a tick handler, a channel handler, or the engine around them a run is.
+const whatOf = (r) => (r.channel ? 'channel' : r.kind ? 'tick' : 'engine');
+
+/**
+ * V8 CPU profiles, reduced to the functions that spent the time, most first,
+ * each credited to the tick or channel handler it ran under, and to the
+ * innermost function of the game's own code it ran under (`game_fn`,
+ * `game_source`) — itself, when it is the game's. Engine code a game function
+ * called is that game function's doing; summing by `game_source` says so.
+ *
+ * Self time, from `hitCount`: a sample lands on the function actually running.
+ * One function under two different ticks, or two different game functions, is
+ * two rows; reached by two callers under the same ones, one. Several profiles
+ * sum as one.
+ *
+ * @param {object|object[]} profiles - Profiler.stop()'s profile, or several
+ * @param {{ runs?: object[], dir?: string, sharedDir?: string }} [opts]
+ * @returns {{ fn: string, source: string, game_fn: string|null, game_source: string|null,
+ *   kind: string|null, trait: string|null, instance: string|null,
+ *   tick_index: number|null, channel: string|null, samples: number, share: number }[]}
+ */
+export function tallyProfiles(profiles, { runs = [], dir = null, sharedDir = null } = {}) {
+  const byFn = new Map();
+  const isGame = gameFrameTest({ dir, sharedDir });
+  let total = 0;
+  for (const profile of Array.isArray(profiles) ? profiles : [profiles]) {
+    for (const { node, hits, run, game } of sampledNodes(profile, runs, isGame)) {
+      const frame = node.callFrame ?? {};
+      const fn = frame.functionName || '(anonymous)';
+      const source = sourceLabel(frame, { dir, sharedDir });
+      const game_fn = game ? (game.functionName || '(anonymous)') : null;
+      const game_source = game ? sourceLabel(game, { dir, sharedDir }) : null;
+      const r = run ?? EMPTY_RUN;
+      const key = [fn, source, game_fn, game_source, r.kind, r.instance, r.tick_index, r.channel].join('\x1f');
+      const cur = byFn.get(key) ?? { fn, source, game_fn, game_source, ...r, samples: 0 };
+      cur.samples += hits;
+      byFn.set(key, cur);
+      total += hits;
+    }
+  }
+  return [...byFn.values()]
+    .map((r) => ({ ...r, share: r.samples / total }))
+    .sort((a, b) => b.samples - a.samples);
+}
+
+/**
+ * The lines samples landed on, from V8's per-line counts of each function:
+ * one row per line per tick or channel handler, most first. `source` is the
+ * line itself, not the line the function starts on. Shares are of every
+ * sample, as the function rows' are; a function V8 kept no line counts for
+ * has no line rows.
+ *
+ * @returns {{ fn: string, source: string, kind: string|null, trait: string|null, instance: string|null,
+ *   tick_index: number|null, channel: string|null, samples: number, share: number }[]}
+ */
+export function tallyLines(profiles, { runs = [], dir = null, sharedDir = null } = {}) {
+  const byLine = new Map();
+  // One label per file and line: naming a source resolves real paths.
+  const labels = new Map();
+  const label = (url, line) => {
+    const key = `${line}\x1f${url}`;
+    if (!labels.has(key)) labels.set(key, sourceLabel({ url, lineNumber: line - 1 }, { dir, sharedDir }));
+    return labels.get(key);
+  };
+  let total = 0;
+  for (const profile of Array.isArray(profiles) ? profiles : [profiles]) {
+    for (const { node, hits, run } of sampledNodes(profile, runs)) {
+      total += hits;
+      const frame = node.callFrame ?? {};
+      if (!frame.url || !Array.isArray(node.positionTicks)) continue;
+      const fn = frame.functionName || '(anonymous)';
+      const r = run ?? EMPTY_RUN;
+      for (const { line, ticks } of node.positionTicks) {
+        if (!Number.isSafeInteger(line) || !(ticks > 0)) continue;
+        // `positionTicks` lines are one-based already; sourceLabel adds one.
+        const source = label(frame.url, line);
+        const key = [fn, source, r.kind, r.instance, r.tick_index, r.channel].join('\x1f');
+        const cur = byLine.get(key) ?? { fn, source, ...r, samples: 0 };
+        cur.samples += ticks;
+        byLine.set(key, cur);
+      }
+    }
+  }
+  return [...byLine.values()]
+    .map((r) => ({ ...r, share: r.samples / total }))
+    .sort((a, b) => b.samples - a.samples);
+}
+
+/**
+ * The samples each tick and channel handler ran, and the engine's own work
+ * around them, as shares of all the samples.
+ *
+ * @returns {{ what: 'tick'|'channel'|'engine', kind: string|null, trait: string|null,
+ *   instance: string|null, tick_index: number|null, channel: string|null, samples: number, share: number }[]}
+ */
+export function tallyRuns(profiles, { runs = [] } = {}) {
+  // Keyed by what a run IS, not by its object: `--repeat` wraps every handler
+  // again on each run, and the same handler must add up to one row.
+  const byRun = new Map();
+  let total = 0;
+  for (const profile of Array.isArray(profiles) ? profiles : [profiles]) {
+    for (const { hits, run } of sampledNodes(profile, runs)) {
+      const r = run ?? EMPTY_RUN;
+      const key = [r.kind, r.instance, r.tick_index, r.channel].join('\x1f');
+      const cur = byRun.get(key) ?? { what: whatOf(r), ...r, samples: 0 };
+      cur.samples += hits;
+      byRun.set(key, cur);
+      total += hits;
+    }
+  }
+  return [...byRun.values()]
+    .map((r) => ({ ...r, share: r.samples / total }))
+    .sort((a, b) => b.samples - a.samples);
+}
+
+// A V8 profiler over this process, or null where one cannot be opened (an old
+// runtime, an environment with the inspector disabled).
+async function nodeProfiler() {
+  try {
+    const { Session } = await import('node:inspector/promises');
+    const session = new Session();
+    session.connect();
+    await session.post('Profiler.enable');
+    await session.post('Profiler.setSamplingInterval', { interval: PROFILE_SAMPLE_US });
+    return {
+      start: () => session.post('Profiler.start'),
+      stop: async () => (await session.post('Profiler.stop'))?.profile ?? null,
+      dispose: async () => {
+        try { await session.post('Profiler.disable'); } finally { session.disconnect(); }
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+// `row` is `function` (one per function, credited to the tick or channel
+// handler it ran under and to the innermost game function above it), `line`
+// (one per line samples landed on, per handler) or `trait` (one per tick and
+// channel handler, plus one `engine` row for the work around them). `what`
+// says which of tick, channel or engine a row's run is. `tick_index` is which
+// of its kind's ticks a tick handler is, counted from 0 in the order the kind
+// runs them; it is not a sim tick, which `tick_from` and `tick_to` are.
+const PROFILE_COLUMNS = [
+  { name: 'row', type: 'STRING' },
+  { name: 'tick_from', type: 'DOUBLE' },
+  { name: 'tick_to', type: 'DOUBLE' },
+  { name: 'fn', type: 'STRING' },
+  { name: 'source', type: 'STRING' },
+  { name: 'game_fn', type: 'STRING' },
+  { name: 'game_source', type: 'STRING' },
+  { name: 'what', type: 'STRING' },
+  { name: 'kind', type: 'STRING' },
+  { name: 'trait', type: 'STRING' },
+  { name: 'instance', type: 'STRING' },
+  { name: 'tick_index', type: 'DOUBLE' },
+  { name: 'channel', type: 'STRING' },
+  { name: 'samples', type: 'DOUBLE' },
+  { name: 'share', type: 'DOUBLE' },
+];
+
+/**
+ * Re-run ticks `from`–`to` of a recorded session under a sampling profiler and
+ * write one row per function, line and handler that ran, with its share of the
+ * samples.
+ *
+ * @param {object} opts
+ * @param {string} opts.dir - the game folder
+ * @param {string} [opts.stream] - which recording; defaults to the most recent
+ * @param {{ from: number, to: number }} opts.ticks
+ * @param {string} opts.outDir
+ * @param {string} [opts.sharedDir] - the resolved engine bundle's shared/ tree
+ * @param {number} [opts.repeat] - how many times to run the ticks, each from a
+ *   fresh replay; the samples of every run sum
+ * @param {Function} [opts.openReplayImpl] - seam for tests
+ * @param {Function} [opts.profilerImpl] - seam for tests
+ * @param {(msg: string) => void} [opts.log]
+ * @returns {Promise<{ stream: string|null, file: string, fromTick: number, toTick: number, samples: number,
+ *   rows: number, repeat: number }>}
+ */
+export async function profileSession({
+  dir, stream, ticks, outDir, sharedDir, repeat = 1, openReplayImpl, profilerImpl, log = () => {},
+}) {
+  if (!ticks) {
+    throw new Error('profile needs --ticks: the ticks to re-run under the profiler, like 1195-1228. '
+      + 'Find them in the exported perf table.');
+  }
+  if (!Number.isSafeInteger(repeat) || repeat < 1) throw new Error(`--repeat takes a whole number of runs, and ${repeat} is not one`);
+  const openReplay = openReplayImpl ?? await loadOpenReplay(sharedDir, 'profile');
+  // Every run opens the recording afresh, and opening one says what it found
+  // — an engine or build that changed since, a drift. Said once, not per run.
+  const said = new Set();
+  const logOnce = (msg) => {
+    if (said.has(msg)) return;
+    said.add(msg);
+    log(msg);
+  };
+  const pieces = [];
+  const runsAll = [];
+  let first = null;
+  for (let i = 0; i < repeat; i++) {
+    const got = await profileOnce({ dir, stream, ticks, openReplay, profilerImpl, log: logOnce, runsOffset: runsAll.length });
+    // Every run numbers its stand-ins from where the last left off, so the
+    // pieces of all of them read against one list.
+    runsAll.push(...got.runs);
+    pieces.push(...got.pieces);
+    first ??= got;
+  }
+  const { chosen, fromTick, toTick } = first;
+  const fns = tallyProfiles(pieces, { runs: runsAll, dir, sharedDir });
+  const lines = tallyLines(pieces, { runs: runsAll, dir, sharedDir });
+  const traits = tallyRuns(pieces, { runs: runsAll });
+  const samples = fns.reduce((n, f) => n + f.samples, 0);
+
+  mkdirSync(outDir, { recursive: true });
+  const file = join(outDir, `${chosen ?? 'session'}.profile.${fromTick}-${toTick}.parquet`);
+  const sink = rowSinkFor(file, PROFILE_COLUMNS);
+  let rows;
+  try {
+    for (const f of fns) sink.push({ row: 'function', tick_from: fromTick, tick_to: toTick, what: whatOf(f), ...f });
+    for (const l of lines) sink.push({ row: 'line', tick_from: fromTick, tick_to: toTick, what: whatOf(l), ...l });
+    for (const t of traits) sink.push({ row: 'trait', tick_from: fromTick, tick_to: toTick, ...t });
+    rows = sink.finish();
+  } catch (e) {
+    sink.abandon();
+    throw e;
+  }
+  return { stream: chosen, file, fromTick, toTick, samples, rows, repeat };
+}
+
+// One run of the ticks from a freshly opened replay, profiled in pieces.
+async function profileOnce({ dir, stream, ticks, openReplay, profilerImpl, log, runsOffset }) {
+  const opened = await openReplay({ dir, stream, log });
+  const { replayer } = opened;
+  const chosen = opened.stream ?? stream ?? null;
+  // Both become part of a file name: the session's name when none was given
+  // is a directory listing's, and playback's position is the recording's
+  // keyframe tick. Neither is first-party, so each is checked, not trusted.
+  if (chosen !== null) streamDir(dir, chosen);
+  const position = () => {
+    const t = replayer.tick;
+    if (!Number.isSafeInteger(t)) throw new Error(`this recording's playback is at tick ${JSON.stringify(t)}, which is not a tick`);
+    return t;
+  };
+  const endTick = replayer.endTick;
+  if (ticks.from > endTick) {
+    throw new Error(`this session ends at tick ${endTick}, so there is no tick ${ticks.from} to profile`);
+  }
+  // Stepping to a tick runs it, so playback stops one short of the first tick
+  // the profile holds. A session entered at a keyframe past `from` has already
+  // run those ticks, and the profile starts where playback does.
+  while (position() < ticks.from - 1 && !replayer.atEnd) replayer.step();
+  const fromTick = position() + 1;
+  if (fromTick > ticks.to) {
+    throw new Error(`playback of this session starts at tick ${fromTick}, after the ticks asked for`);
+  }
+
+  const profiler = await (profilerImpl ?? nodeProfiler)();
+  if (!profiler) throw new Error('this Node cannot open its own profiler (node:inspector), so there is nothing to profile with');
+  const { runs, restore } = instrumentRuns(replayer.runtime, opened.bundle?.channelOrigins);
+  // Stand-ins are numbered from zero in each run; renumbered here into the
+  // list every run shares.
+  const renumber = (name) => (name?.startsWith(RUN_PREFIX) ? `${RUN_PREFIX}${Number(name.slice(RUN_PREFIX.length)) + runsOffset}` : name);
+  // Each piece keeps only what the tally reads: the call tree's shape and the
+  // sampled frames. The timeline goes.
+  const pieces = [];
+  try {
+    while (position() < ticks.to && !replayer.atEnd) {
+      const pieceEnd = Math.min(ticks.to, position() + PROFILE_PIECE_TICKS);
+      await profiler.start();
+      while (position() < pieceEnd && !replayer.atEnd) replayer.step();
+      const raw = await profiler.stop();
+      pieces.push({
+        nodes: (raw?.nodes ?? []).map(({ id, children, hitCount, positionTicks, callFrame }) => ({
+          id, children, hitCount, positionTicks, callFrame: { ...callFrame, functionName: renumber(callFrame?.functionName) },
+        })),
+      });
+    }
+  } finally {
+    restore();
+    await profiler.dispose();
+  }
+  return { chosen, fromTick, toTick: position(), runs, pieces };
+}