feat(core): expand --trace dump with per-case spans, heap counter, and metadata

Why: phase summary already conveys macro-level timings, but Perfetto UI is
underused at the file level — every test file shows up as 8 phase blocks
with no visibility into which case or hook dominates `tests`. Add detail
that surfaces in Perfetto without touching `runner.ts`.

- Emit per-case and per-suite `ph: 'X'` slices (cats `case` / `suite`)
  via the runner's existing `RunnerHooks` lifecycle callbacks; `runner.ts`
  is untouched. `TestCaseInfo.startTime` provides the case start time,
  suite start is captured at hook firing.
- Sample `process.memoryUsage()` as `ph: 'C'` counter events at every
  phase boundary so heap pressure shows up as Perfetto tracks
  (heapUsedMB / heapTotalMB / rssMB).
- Add `process_sort_index` and `thread_name` metadata per pid so the UI
  lists test files in execution order under a "worker" label.
- Delete previous-session trace JSON on each finalize so watch mode
  doesn't accumulate multi-MB files under `.rstest/`.

Refactor: collapse `types/trace.ts`, `utils/traceController.ts`, and
`utils/traceServer.ts` into a single `utils/trace.ts`. The split was
incidental, the call sites all consume the same surface, and a single
file makes the public-vs-internal boundary obvious.

When `--trace` is off, the new methods early-return on a single
`if (!this.trace)` check; the no-trace path stays allocation-free aside
from the existing `PhaseTimings` totals object used by phase summary.

Author: fi3ework

packages/core/src/pool/index.ts

@@ -18,7 +18,6 @@ import type {
   TestInfo,
   TestResult,
   TestSuiteInfo,
-  TraceEvent,
   UserConsoleLog,
 } from '../types';
 import {
@@ -27,6 +26,7 @@ import {
   isDeno,
   needFlagExperimentalDetectModule,
 } from '../utils';
+import type { TraceEvent } from '../utils/trace';
 import { isMemorySufficient } from '../utils/memory';
 import { Pool } from './pool';
 

packages/core/src/runtime/worker/phaseTracker.ts

@@ -1,5 +1,10 @@
 import type { PhaseTimings } from '../../types/reporter';
-import type { TraceEvent } from '../../types/trace';
+import type {
+  TestCaseInfo,
+  TestResult,
+  TestSuiteInfo,
+} from '../../types/testSuite';
+import type { TraceEvent } from '../../utils/trace';
 import { emptyPhaseTimings } from '../../utils/phaseTimings';
 import { getRealNow } from '../util';
 
@@ -16,28 +21,48 @@ export type PhaseTrackerOptions = {
 type TraceState = {
   events: TraceEvent[];
   meta: NonNullable<PhaseTrackerOptions['trace']>;
+  /** Start timestamps (ms, wall-clock) keyed by testId. */
+  suiteStarts: Map<string, number>;
+  caseStarts: Map<string, number>;
 };
 
+type SliceCat = 'phase' | 'suite' | 'case';
+
 /**
  * Accumulates non-overlapping per-phase totals (ms) for a single test file.
  *
  * `transition(name)` ends the active phase and starts the next. A phase
  * may be re-entered (e.g. `prepare` resumes after `envSetup`); each entry
  * adds to the matching `PhaseTimings` field.
  *
- * When `trace` is enabled, each completed span is also recorded as a
- * Perfetto-compatible `ph: 'X'` event with `pid = process.pid`. The host
- * later writes these into a single trace JSON file.
+ * When `trace` is enabled, the tracker also emits Perfetto-compatible events:
+ * - per-phase `ph: 'X'` spans (`cat: 'phase'`)
+ * - per-suite / per-case `ph: 'X'` spans (`cat: 'suite' | 'case'`), recorded
+ *   via the runner's existing lifecycle hooks (zero intrusion into runner.ts)
+ * - heap-usage counter samples (`ph: 'C'`, `cat: 'memory'`) at each phase
+ *   boundary, so memory pressure shows up as a track in Perfetto UI
+ *
+ * All events use `pid = process.pid`. The host later merges these into a
+ * single trace JSON file.
  */
 export class PhaseTracker {
   private currentPhase: PhaseName | null = null;
   private currentStart = 0;
   private hasData = false;
   private readonly totals: PhaseTimings = emptyPhaseTimings();
   private readonly trace: TraceState | null;
+  /** Workers are single-threaded; pid doubles as tid for Perfetto tracks. */
+  private readonly pid = process.pid;
 
   constructor(options: PhaseTrackerOptions = {}) {
-    this.trace = options.trace ? { events: [], meta: options.trace } : null;
+    this.trace = options.trace
+      ? {
+          events: [],
+          meta: options.trace,
+          suiteStarts: new Map(),
+          caseStarts: new Map(),
+        }
+      : null;
   }
 
   transition(phase: PhaseName): void {
@@ -46,8 +71,9 @@ export class PhaseTracker {
       const dur = now - this.currentStart;
       this.totals[this.currentPhase] += dur;
       this.hasData = true;
-      this.recordTraceSpan(this.currentPhase, this.currentStart, dur);
+      this.pushSlice(this.currentPhase, 'phase', this.currentStart, dur);
     }
+    this.sampleHeap(now);
     this.currentPhase = phase;
     this.currentStart = now;
   }
@@ -58,11 +84,49 @@ export class PhaseTracker {
       const dur = now - this.currentStart;
       this.totals[this.currentPhase] += dur;
       this.hasData = true;
-      this.recordTraceSpan(this.currentPhase, this.currentStart, dur);
+      this.pushSlice(this.currentPhase, 'phase', this.currentStart, dur);
+      this.sampleHeap(now);
       this.currentPhase = null;
     }
   }
 
+  recordSuiteStart(info: TestSuiteInfo): void {
+    if (!this.trace) return;
+    this.trace.suiteStarts.set(info.testId, getRealNow());
+  }
+
+  recordSuiteResult(result: TestResult): void {
+    if (!this.trace) return;
+    const start = this.trace.suiteStarts.get(result.testId);
+    this.trace.suiteStarts.delete(result.testId);
+    if (start === undefined || typeof result.duration !== 'number') return;
+    this.pushSlice(result.name || '<suite>', 'suite', start, result.duration, {
+      testId: result.testId,
+      status: result.status,
+    });
+  }
+
+  recordCaseStart(info: TestCaseInfo): void {
+    if (!this.trace) return;
+    // Prefer the runner's authoritative start time when present so the slice
+    // aligns exactly with the case's reported duration.
+    const start =
+      typeof info.startTime === 'number' ? info.startTime : getRealNow();
+    this.trace.caseStarts.set(info.testId, start);
+  }
+
+  recordCaseResult(result: TestResult): void {
+    if (!this.trace) return;
+    const start = this.trace.caseStarts.get(result.testId);
+    this.trace.caseStarts.delete(result.testId);
+    if (start === undefined || typeof result.duration !== 'number') return;
+    this.pushSlice(result.name, 'case', start, result.duration, {
+      testId: result.testId,
+      status: result.status,
+      retryCount: result.retryCount,
+    });
+  }
+
   getTotals(): PhaseTimings | undefined {
     return this.hasData ? this.totals : undefined;
   }
@@ -73,24 +137,47 @@ export class PhaseTracker {
       : undefined;
   }
 
-  private recordTraceSpan(
-    phase: PhaseName,
+  private pushSlice(
+    name: string,
+    cat: SliceCat,
     startMs: number,
     durMs: number,
+    extraArgs?: Record<string, string | number | boolean | undefined>,
   ): void {
     if (!this.trace) return;
     this.trace.events.push({
-      name: phase,
-      cat: 'phase',
+      name,
+      cat,
       ph: 'X',
       ts: startMs * 1000,
       dur: durMs * 1000,
-      pid: process.pid,
-      tid: process.pid,
+      pid: this.pid,
+      tid: this.pid,
       args: {
         testPath: this.trace.meta.testPath,
         project: this.trace.meta.project,
+        ...extraArgs,
+      },
+    });
+  }
+
+  private sampleHeap(nowMs: number): void {
+    if (!this.trace) return;
+    const mem = process.memoryUsage();
+    this.trace.events.push({
+      name: 'heap',
+      cat: 'memory',
+      ph: 'C',
+      ts: nowMs * 1000,
+      pid: this.pid,
+      tid: this.pid,
+      args: {
+        heapUsedMB: round2(mem.heapUsed / 1024 / 1024),
+        heapTotalMB: round2(mem.heapTotal / 1024 / 1024),
+        rssMB: round2(mem.rss / 1024 / 1024),
       },
     });
   }
 }
+
+const round2 = (n: number): number => Math.round(n * 100) / 100;

packages/core/src/runtime/worker/runInPool.ts

@@ -555,9 +555,11 @@ export const runInPool = async (
           await rpc.onTestFileReady(test);
         },
         onTestSuiteStart: async (test) => {
+          tracker.recordSuiteStart(test);
           await rpc.onTestSuiteStart(test);
         },
         onTestSuiteResult: async (result) => {
+          tracker.recordSuiteResult(result);
           silentConsoleController.flushBufferedLogsForTask({
             taskId: result.testId,
             status: result.status,
@@ -568,9 +570,11 @@ export const runInPool = async (
           await rpc.onTestSuiteResult(result);
         },
         onTestCaseStart: async (test) => {
+          tracker.recordCaseStart(test);
           await rpc.onTestCaseStart(test);
         },
         onTestCaseResult: async (result) => {
+          tracker.recordCaseResult(result);
           silentConsoleController.flushBufferedLogsForTask({
             taskId: result.testId,
             status: result.status,

packages/core/src/types/index.ts

@@ -9,6 +9,5 @@ export type * from './mock';
 export type * from './reporter';
 export type * from './runner';
 export type * from './testSuite';
-export type * from './trace';
 export type * from './utils';
 export type * from './worker';

packages/core/src/types/testSuite.ts

@@ -175,7 +175,7 @@ export type TestFileResult = TestResult & {
    *
    * @internal
    */
-  traceEvents?: import('./trace').TraceEvent[];
+  traceEvents?: import('../utils/trace').TraceEvent[];
 };
 
 export interface UserConsoleLog {

packages/core/src/types/trace.ts

@@ -7,5 +7,3 @@ export * from './process';
 export * from './shard';
 export * from './testFiles';
 export * from './trace';
-export * from './traceController';
-export * from './traceServer';