feat: concrete fix suggestions for each finding

Author: thelastbackspace

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - **`traceperf run`:** starts an app with `traceperf/auto`, sends concurrent traffic (`--path`, `-c`, `-d`/`-n`, `--method`; warm-up requests first), then prints statistics and explanations. Without `--path`, use the app yourself and press Ctrl-C. Works with a script (`traceperf run server.js`) or any command (`traceperf run -- npm start`). `--html`, `--output`, `--json`.
+- **Fix suggestions:** findings now say what to change (`fix` in `explain()` / `--json`, a `fix:` line in text, under each finding in HTML): `Promise.all` for sequential awaits, `WHERE id IN (...)` / DataLoader for N+1, the async API for `pbkdf2Sync`, `readFileSync` and Sync zlib, a worker thread or chunking for hot loops, `EXPLAIN ANALYZE` for a dominant query.
 - **Evidence links in the HTML report:** the report now opens with the findings ("Why it was slow"); click one to highlight its time range on the flame chart (no scripts, works from disk). Each finding carries `evidence: { start, end, labels }` in `explain()` and `--json` output.
 - **Known-slow example apps** (`examples/slow-apps/`): one planted cause each; a test checks that `explain` names it.
 - **Blocking code is named even when untracked:** `traceperf run` (and `TRACEPERF_PROFILE_BLOCKING=1` with `traceperf/auto`) samples the CPU during the synchronous part of blocking calls, and `explain` names the function and line (`CPU time: buildReport (server.js:10) 100%`). Native work is named by the calling app function (`hashPassword → pbkdf2Sync`), code V8 inlined into its caller is credited to the inlined function, and garbage-collection pauses are reported as such.

src/__tests__/explain-auto-profile.test.ts

@@ -58,6 +58,22 @@ describe('explain()', () => {
     expect(explain([n1]).find(f => f.kind === 'repeated')!.evidence).toEqual({ start: 5, end: 59, labels: ['q'] });
   });
 
+  test('findings carry a concrete fix that matches the cause', () => {
+    const seq = node('page', 0, 30, { children: [node('loadUser', 0, 10), node('loadOrders', 10, 10)] });
+    expect(explain([seq]).find(f => f.kind === 'sequential')!.fix).toBe("if they don't depend on each other, start them together: await Promise.all([loadUser(), loadOrders()])");
+    const n1 = node('list', 0, 60, { children: Array.from({ length: 6 }, (_, i) => node('pg SELECT items', 5 + i * 9, 9)) });
+    expect(explain([n1]).find(f => f.kind === 'repeated')!.fix).toMatch(/IN \(\.\.\.\)/);
+    const rest = node('list', 0, 60, { children: Array.from({ length: 6 }, (_, i) => node('fetchUser', 5 + i * 9, 9)) });
+    expect(explain([rest]).find(f => f.kind === 'repeated')!.fix).toMatch(/DataLoader/);
+    const hash = node('login', 0, 30, { async: false, syncDuration: 30 });
+    const hotspots = { login: [{ functionName: 'hashPassword → pbkdf2Sync', location: 'a.js:3', ms: 28 }, { functionName: '(garbage collection)', location: '', ms: 2 }] };
+    const blocking = explain([hash], { hotspots }).find(f => f.kind === 'blocking')!;
+    expect(blocking.fix).toMatch(/^hashPassword: use the async version/);
+    expect(formatFindings([blocking])).toMatch(/\n {3}fix: hashPassword/);
+    expect(explain([hash]).find(f => f.kind === 'blocking')!.fix).toMatch(/worker_threads/);
+    expect(explain([node('boom', 0, 10, { error: new Error('x') })])[0].fix).toBeUndefined();
+  });
+
   test('blocking is attributed to the deepest call that did it', () => {
     const inner = node('parseJson', 0, 40, { async: false, syncDuration: 40 });
     const outer = node('handler', 0, 42, { async: false, syncDuration: 42, children: [inner] });

src/core/explain.ts

@@ -35,6 +35,8 @@ export interface Finding {
   ms: number;
   /** For blocking / blocked: the call whose synchronous code blocked */
   call?: string;
+  /** What to change, when the cause suggests a concrete fix */
+  fix?: string;
   /** Where to look: the time range (same clock as the input) and the calls involved */
   evidence?: FindingEvidence;
 }
@@ -336,6 +338,8 @@ export function explain(roots: ExplainNode[], options: ExplainOptions = {}): Fin
     .map(({ times, roots: seenIn, group, ...f }) => {
       const where = [...seenIn];
       const label = where.length > 3 ? `${where.slice(0, 3).join(', ')} and ${where.length - 3} more` : where.join(', ');
+      const fix = suggestFix(f, options.hotspots);
+      if (fix) f = { ...f, fix };
       if (f.kind === 'blocking') {
         const self = where.length === 1 && where[0] === f.message.split(' ran ')[0];
         const count = times > where.length ? `${times} times` : '';
@@ -346,12 +350,62 @@ export function explain(roots: ExplainNode[], options: ExplainOptions = {}): Fin
     });
 }
 
+const SYNC_FIX: Array<[RegExp, string]> = [
+  [/pbkdf2Sync|scryptSync/, 'use the async version (crypto.pbkdf2 / crypto.scrypt with a callback or util.promisify): it runs on the thread pool'],
+  [/(randomBytes|generateKeyPairSync|hashSync|compareSync)/, 'use the async version of $1 so the work leaves the event loop'],
+  [/readFileSync|writeFileSync|readdirSync|statSync|existsSync/, 'use fs.promises instead of the Sync call, or read it once at startup and cache it'],
+  [/zlib|gzipSync|inflateSync|deflateSync|brotli/i, 'use the async / streaming zlib API instead of the Sync call'],
+  [/JSON\.(stringify|parse)/, 'the payload is large: paginate it, send fewer fields, or stream it (e.g. a streaming JSON encoder)'],
+  [/garbage collection/, 'it allocates a lot: reuse objects/buffers and avoid building large temporary arrays or strings'],
+];
+const SQL = /\b(select|insert|update|delete|pg|mysql|postgres|sql|query|prisma|knex|sequelize|typeorm|drizzle)\b/i;
+
+/** A concrete change for a finding, from its kind, labels and CPU hotspots */
+function suggestFix(f: Finding, hotspots?: Record<string, BlockingHotspot[]>): string | undefined {
+  const labels = f.evidence?.labels || [];
+  switch (f.kind) {
+    case 'blocked':
+    case 'blocking': {
+      const spots = (f.call && hotspots?.[f.call]) || [];
+      // Only the top culprit decides: a 10% GC share is not the fix for a hot loop
+      for (const h of spots.slice(0, 1)) {
+        const name = `${h.functionName} ${h.location}`;
+        for (const [re, fix] of SYNC_FIX) {
+          const m = name.match(re);
+          if (m) return `${h.functionName.split(' → ')[0]}: ${fix.replace('$1', m[1] || '')}`;
+        }
+      }
+      const at = spots[0] ? `${spots[0].functionName.split(' → ')[0]}${spots[0].location ? ` (${spots[0].location})` : ''}` : f.call;
+      return `move the CPU work in ${at} off the request path: a worker_threads Worker (e.g. a pool like piscina), split it into chunks with setImmediate, or cache its result`;
+    }
+    case 'sequential': {
+      const names = labels.slice(0, 3);
+      if (!names.every(n => /^[\w.$]+$/.test(n))) return `if they don't depend on each other, start them together with Promise.all instead of awaiting each in turn`;
+      return `if they don't depend on each other, start them together: await Promise.all([${names.map(n => `${n}()`).join(', ')}${labels.length > 3 ? ', ...' : ''}])`;
+    }
+    case 'repeated': {
+      const label = labels[0] || '';
+      return SQL.test(label)
+        ? `load them in one query: WHERE id IN (...) (or = ANY($1) in Postgres), or your ORM's include/join; then match results in memory`
+        : `make one batched call instead of one per item (a bulk API, or DataLoader to collect the calls of one tick)`;
+    }
+    case 'dominant':
+      // Outside tracked code: the message says what to do; waited: the blocking finding has the fix
+      if (f.message.includes('outside any tracked call') || f.message.includes('waiting for blocking code')) return undefined;
+      return SQL.test(labels[0] || '')
+        ? `check this query's plan (EXPLAIN ANALYZE) and indexes, or cache its result`
+        : `that is where the time goes: track or profile inside ${labels[0] || 'it'} next`;
+    default:
+      return undefined;
+  }
+}
+
 const ICON: Record<FindingKind, string> = {
   error: '✖', blocked: '⏳', blocking: '🔥', repeated: '🔁', sequential: '⇉', dominant: '●',
 };
 
-/** Render findings as text, one per line */
+/** Render findings as text, one per line (and the fix, if any, below it) */
 export function formatFindings(findings: Finding[]): string {
   if (findings.length === 0) return 'No issues found: nothing blocked, repeated, or ran sequentially in a way worth changing.';
-  return findings.map(f => `${ICON[f.kind]} ${f.message}`).join('\n');
+  return findings.map(f => `${ICON[f.kind] || '•'} ${f.message}${f.fix ? `\n   fix: ${f.fix}` : ''}`).join('\n');
 }

src/report-html.ts

@@ -70,9 +70,10 @@ export function renderHtmlReport(calls: Call[], stats: Record<string, LabelStats
   });
   const findingItems = findings.map((f, i) => {
     const text = `${ICON[f.kind] || '•'} ${esc(f.message)}`;
+    const fix = f.fix ? `<div class="fix">fix: ${esc(f.fix)}</div>` : '';
     return bands[i]
-      ? `<li><a href="#ev-${i}">${text}</a> <span class="at">at ${esc(ms(f.evidence!.start - start))}, ${esc(f.evidence!.labels.slice(0, 3).join(', '))}</span></li>`
-      : `<li>${text}</li>`;
+      ? `<li><a href="#ev-${i}">${text}</a> <span class="at">at ${esc(ms(f.evidence!.start - start))}, ${esc(f.evidence!.labels.slice(0, 3).join(', '))}</span>${fix}</li>`
+      : `<li>${text}${fix}</li>`;
   }).join('\n');
   const findingsSection = findings.length
     ? `<h2>Why it was slow</h2>\n<ol class="findings">\n${findingItems}\n</ol>\n<p class="meta">Click a finding to highlight its time range on the flame chart.</p>`
@@ -116,7 +117,7 @@ export function renderHtmlReport(calls: Call[], stats: Record<string, LabelStats
   .slow td:first-child { width: 1%; } .slow td:last-child, .slow th:last-child { text-align: left; white-space: normal; width: auto; } .err { color: #d73a49; }
   .wrap { overflow-x: auto; }
   ol.findings { padding-left: 20px; margin: 0; } ol.findings li { margin: 4px 0; } ol.findings a { color: inherit; }
-  .at { color: var(--muted); font-size: 12px; }
+  .fix { color: var(--muted); font-size: 13px; } .at { color: var(--muted); font-size: 12px; }
   rect.ev { fill: #f0b400; fill-opacity: 0; stroke: none; pointer-events: none; }
   rect.ev:target { fill-opacity: 0.22; stroke: #f0b400; stroke-width: 2; }
 </style>