feat(core): emit agent-readable timing summary for --trace (#1355)

Author: fi3ework

packages/core/src/cli/commands.ts

@@ -98,7 +98,10 @@ const runtimeOptionDefinitions: OptionDefinition[] = [
   ['--disableConsoleIntercept', 'Disable console intercept'],
   ['--logHeapUsage', 'Log heap usage after each test'],
   ['--detectAsyncLeaks', 'Detect async resources that leak after tests finish'],
-  ['--trace', 'Dump a Perfetto-compatible performance trace JSON file'],
+  [
+    '--trace',
+    'Dump a Perfetto-compatible performance trace JSON file, plus a ranked markdown timing summary printed to the terminal and written next to it',
+  ],
   [
     '--slowTestThreshold <value>',
     'The number of milliseconds after which a test or suite is considered slow',

packages/core/src/utils/helper.ts

@@ -1,4 +1,12 @@
-import { isAbsolute, join, normalize, parse, sep } from 'pathe';
+import {
+  isAbsolute,
+  join,
+  normalize,
+  parse,
+  relative,
+  resolve,
+  sep,
+} from 'pathe';
 import type { RuntimeConfig, TestResult } from '../types';
 import { TEST_DELIMITER } from './constants';
 import { color } from './logger';
@@ -41,6 +49,17 @@ export function getAbsolutePath(base: string, filepath: string): string {
   return isAbsolute(filepath) ? filepath : join(base, filepath);
 }
 
+/**
+ * Render a path relative to `rootPath` when it lives inside the root, otherwise
+ * fall back to the original path. Used for trace labels and summary tables so
+ * in-repo files show as short relative paths while external/sentinel paths
+ * (e.g. `<host>`) pass through unchanged.
+ */
+export const displayPath = (filePath: string, rootPath: string): string => {
+  const rel = relative(rootPath, resolve(rootPath, filePath));
+  return rel && !rel.startsWith('..') ? rel : filePath;
+};
+
 export const parsePosix = (filePath: string): { dir: string; base: string } => {
   const { dir, base } = parse(filePath);
 

packages/core/src/utils/trace.ts

@@ -1,8 +1,9 @@
 import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
-import { dirname, relative, resolve } from 'pathe';
-import { isTTY } from './helper';
+import { dirname, resolve } from 'pathe';
+import { displayPath, isTTY } from './helper';
 import { color, logger } from './logger';
+import { formatTraceSummary, summarizeTrace } from './traceSummary';
 
 // ---------------------------------------------------------------------------
 // Public event type
@@ -46,12 +47,17 @@ export const noopTraceSpan: TraceSpan = async (_name, _cat, fn) => fn();
 // ---------------------------------------------------------------------------
 
 /**
- * Build the absolute path for a Perfetto trace dump. The filename embeds an
- * ISO-like timestamp so repeated runs do not overwrite each other.
+ * Build the absolute paths for a run's artifacts: the Perfetto trace dump and
+ * its markdown summary sidecar. Both share one timestamped stem so the pair is
+ * named from a single source (no fragile extension rewriting), and the stamp
+ * keeps repeated runs from overwriting each other.
  */
-const getTraceOutputPath = (rootPath: string): string => {
+const getTraceOutputPaths = (
+  rootPath: string,
+): { tracePath: string; summaryPath: string } => {
   const stamp = new Date().toISOString().replace(/[:.]/g, '-').replace('Z', '');
-  return resolve(rootPath, '.rstest', `trace-${stamp}.json`);
+  const stem = resolve(rootPath, '.rstest', `trace-${stamp}`);
+  return { tracePath: `${stem}.json`, summaryPath: `${stem}.summary.md` };
 };
 
 /**
@@ -100,11 +106,6 @@ const buildTraceFile = (
     threadIds.add(ev.tid);
   }
 
-  const displayPath = (testPath: string): string => {
-    const rel = relative(rootPath, testPath);
-    return rel && !rel.startsWith('..') ? rel : testPath;
-  };
-
   const seenPid = new Set<number>();
   const seenThread = new Set<string>();
   const metadata: TraceEvent[] = [];
@@ -119,7 +120,9 @@ const buildTraceFile = (
       const sharedWorker = (threadIdsByPid.get(ev.pid)?.size ?? 0) > 1;
       metadata.push(
         meta('process_name', ev.pid, ev.tid, {
-          name: sharedWorker ? `worker ${ev.pid}` : displayPath(testPath),
+          name: sharedWorker
+            ? `worker ${ev.pid}`
+            : displayPath(testPath, rootPath),
         }),
         meta('process_sort_index', ev.pid, ev.tid, {
           sort_index: sortIndex++,
@@ -131,7 +134,9 @@ const buildTraceFile = (
     if (!seenThread.has(threadKey)) {
       seenThread.add(threadKey);
       metadata.push(
-        meta('thread_name', ev.pid, ev.tid, { name: displayPath(testPath) }),
+        meta('thread_name', ev.pid, ev.tid, {
+          name: displayPath(testPath, rootPath),
+        }),
       );
     }
   }
@@ -300,6 +305,9 @@ export const createTraceController = (options: {
   // In watch mode we replace it on each rerun so .rstest/ does not accumulate
   // multi-MB JSONs; files from earlier sessions are left alone.
   let lastTracePath: string | undefined;
+  // Sidecar `.summary.md` produced alongside the trace; replaced on rerun in
+  // watch mode for the same reason as `lastTracePath`.
+  let lastSummaryPath: string | undefined;
 
   const beginRun = (): TraceRun => {
     if (!enabled) {
@@ -343,7 +351,7 @@ export const createTraceController = (options: {
       span: pushHostSlice,
       finalize: async () => {
         if (!events.length) return;
-        const tracePath = getTraceOutputPath(rootPath);
+        const { tracePath, summaryPath } = getTraceOutputPaths(rootPath);
         await mkdir(dirname(tracePath), { recursive: true });
         await writeFile(
           tracePath,
@@ -354,10 +362,29 @@ export const createTraceController = (options: {
           unlink(lastTracePath).catch(() => {});
         }
         lastTracePath = tracePath;
+
+        // Agent/CI-friendly text summary: the Perfetto JSON is a raw event
+        // dump meant for the visual UI, so always emit a ranked markdown
+        // digest (printed to stdout and written next to the trace) that
+        // answers "where did time go" without opening a flame graph.
+        const summaryMarkdown = formatTraceSummary(
+          summarizeTrace(events, rootPath),
+        );
+        await writeFile(summaryPath, `${summaryMarkdown}\n`);
+        if (lastSummaryPath && lastSummaryPath !== summaryPath) {
+          unlink(lastSummaryPath).catch(() => {});
+        }
+        lastSummaryPath = summaryPath;
+
+        logger.log(`\n${summaryMarkdown}\n`);
         logger.log(
           color.gray('  Perfetto trace file: '),
           color.cyan(tracePath),
         );
+        logger.log(
+          color.gray('  Trace summary file: '),
+          color.cyan(summaryPath),
+        );
         // The helper server keeps the event loop alive until SIGINT, which
         // would hang `rstest run` in CI. Only start it in an interactive TTY,
         // otherwise leave the file for the user to download from the CI