rerender-lens 0.4.0 → 0.5.0

package/dist/cli.js

@@ -4,50 +4,206 @@ import { createServer } from 'http';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
-// src/report.ts
-function storeAdvice(custom) {
-  const chain = custom ?? [];
-  if (chain.some((n) => /^useSelector$/.test(n)))
-    return "the Redux selector returns a new object on every call: return a stored slice, pass shallowEqual as the equality function, or memoize it with createSelector";
-  if (chain.some((n) => /^useAppSelector$/.test(n)))
-    return "the selector returns a new object on every call: return a stored slice, pass shallowEqual, or memoize it with createSelector";
-  if (chain.some((n) => /^use[A-Z]\w*Store$/.test(n) || n === "useStore" || n === "useBoundStore"))
-    return "the store selector returns a new object on every call: select a primitive, or wrap the selector with useShallow (Zustand) / an equality function";
-  return "getSnapshot returns a new reference with the same contents: cache the snapshot in the store and return the same object while the data is unchanged";
+// src/diff.ts
+var AVOIDABLE_KINDS = /* @__PURE__ */ new Set(["deep-equal", "function", "element"]);
+
+// src/causes.ts
+var isAncestorReport = (anc, r) => anc.path.length < r.path.length && r.path[anc.path.length] === anc.component && anc.path.every((p, i) => r.path[i] === p);
+var bump = (m, key, n = 1) => void m.set(key, (m.get(key) || 0) + n);
+function indexByComponent(reports) {
+  const index = /* @__PURE__ */ new Map();
+  for (const r of reports) {
+    const list = index.get(r.component);
+    if (list) list.push(r);
+    else index.set(r.component, [r]);
+  }
+  return index;
+}
+function rootCauseOf(r, commitReports, index = indexByComponent(commitReports)) {
+  let cur = r;
+  const seen = /* @__PURE__ */ new Set([r]);
+  while (cur.trigger === "parent" && cur.parent) {
+    const parent = cur.parent;
+    const candidates = index.get(parent.name);
+    const p = candidates && candidates.find((x) => isAncestorReport(x, cur));
+    if (!p || seen.has(p)) return { name: parent.name, trigger: parent.trigger, report: null };
+    seen.add(p);
+    cur = p;
+  }
+  return cur === r ? null : { name: cur.component, trigger: cur.trigger, report: cur };
+}
+function rootCausesOf(reports) {
+  const roots = /* @__PURE__ */ new Map();
+  const rootByReport = /* @__PURE__ */ new Map();
+  const index = indexByComponent(reports);
+  let avoidable = 0;
+  let wasted = 0;
+  for (const r of reports) {
+    if (!r.avoidable) continue;
+    avoidable++;
+    if (typeof r.selfDuration === "number") wasted += r.selfDuration;
+    const root = rootCauseOf(r, reports, index);
+    const name = root ? root.name : r.parent && r.parent.name || "(unknown)";
+    const trigger = root ? root.trigger : r.parent && r.parent.trigger || "parent";
+    rootByReport.set(r, name);
+    let agg = roots.get(name);
+    if (!agg) {
+      agg = { name, trigger, count: 0, components: /* @__PURE__ */ new Map() };
+      roots.set(name, agg);
+    }
+    agg.count++;
+    bump(agg.components, r.component);
+  }
+  return { roots: [...roots.values()].sort((a, b) => b.count - a.count), rootByReport, avoidable, wasted };
+}
+function groupByCommit(reports) {
+  const out = /* @__PURE__ */ new Map();
+  for (const r of reports) {
+    if (typeof r.commitId !== "number" || r.commitId <= 0) continue;
+    const list = out.get(r.commitId);
+    if (list) list.push(r);
+    else out.set(r.commitId, [r]);
+  }
+  return out;
+}
+function rankRootCauses(reports) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const commit of groupByCommit(reports).values()) {
+    for (const root of rootCausesOf(commit).roots) {
+      let agg = byName.get(root.name);
+      if (!agg) {
+        agg = { name: root.name, trigger: root.trigger, commits: 0, count: 0, components: /* @__PURE__ */ new Map() };
+        byName.set(root.name, agg);
+      }
+      agg.commits++;
+      agg.count += root.count;
+      for (const [c, n] of root.components) bump(agg.components, c, n);
+    }
+  }
+  return [...byName.values()].sort((a, b) => b.count - a.count || b.commits - a.commits || a.name.localeCompare(b.name));
+}
+var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+function formatRootCauses(reports, limit = 5) {
+  const ranked = rankRootCauses(reports);
+  const lines = ranked.slice(0, limit).map((root, i) => `${String(i + 1).padStart(2)}. <${root.name}> (${root.trigger}) started ${plural(root.commits, "commit")}, ${plural(root.count, "avoidable re-render")}  (${[...root.components].map(([c, n]) => `<${c}>${n > 1 ? " x" + n : ""}`).join(", ")})`);
+  if (ranked.length > limit) lines.push(`    \u2026 ${ranked.length - limit} more`);
+  return lines.join("\n");
 }
 
 // src/fixes.ts
-var AVOIDABLE = /* @__PURE__ */ new Set(["deep-equal", "function", "element"]);
+var MAX_FIX_REPORTS = 50;
 var rootOf = (path) => path.split(/[.[]/)[0] || path;
+var identifier = (name) => /^[A-Za-z_$][\w$]*$/.test(name) ? name : "value";
+function shortValue(v, max = 60) {
+  let s;
+  try {
+    s = JSON.stringify(v);
+  } catch {
+    s = String(v);
+  }
+  if (s === void 0) s = String(v);
+  return s.length > max ? s.slice(0, max - 3) + "..." : s;
+}
 function fixesFor(r) {
   const out = [];
-  const owner = r.owner || r.parent && r.parent.name || "?";
-  const changes = [...r.propChanges, ...r.stateChanges, ...r.hookChanges];
+  const ownerName = r.owner || r.parent && r.parent.name || null;
+  const propChanges = r.propChanges || [];
+  const changes = [...propChanges, ...r.stateChanges || [], ...r.hookChanges || []];
   if (r.avoidable && (changes.length === 0 || r.memoized === false)) {
+    const identical = changes.length === 0;
     out.push({
       kind: "memo",
       owner: r.component,
       target: r.component,
       prop: null,
       label: `Wrap <${r.component}> in React.memo`,
-      detail: changes.length === 0 ? `<${r.component}> re-rendered with identical props because <${r.parent && r.parent.name || "its parent"}> re-rendered.` : `<${r.component}> is not memoized: fixing its props alone will not stop the re-render.`
+      detail: identical ? `<${r.component}> re-rendered with identical props because <${r.parent && r.parent.name || "its parent"}> re-rendered.` : `<${r.component}> is not memoized: fixing its props alone will not stop the re-render.`,
+      snippet: `// ${r.component}
+import { memo } from 'react';
+
+export const ${r.component} = memo(function ${r.component}(props) {
+  // ...
+});
+// class components: extend PureComponent instead`
     });
   }
-  for (const c of r.propChanges) {
-    if (!AVOIDABLE.has(c.kind)) continue;
+  for (const c of propChanges) {
+    if (!AVOIDABLE_KINDS.has(c.kind)) continue;
+    const owner = ownerName || "?";
     const root = rootOf(c.path);
+    const id = identifier(root);
     if (root === "children" && (c.kind === "element" || c.kind === "deep-equal")) {
-      out.push({ kind: "children", owner, target: r.component, prop: "children", label: `memoize children of <${r.component}> in <${owner}>`, detail: `<${owner}> re-creates the children of <${r.component}> on every render.` });
+      out.push({
+        kind: "children",
+        owner,
+        target: r.component,
+        prop: "children",
+        label: `memoize children of <${r.component}> in <${owner}>`,
+        detail: `<${owner}> re-creates the children of <${r.component}> on every render; they have the same types and props each time.`,
+        snippet: `// ${owner}
+import { useMemo } from 'react';
+
+const children = useMemo(() => (
+  <>{/* the same elements */}</>
+), [/* deps */]);
+
+<${r.component}>{children}</${r.component}>
+
+// static children: hoist them to module scope
+const STATIC = <em>hi</em>;`
+      });
     } else if (c.kind === "function") {
-      out.push({ kind: "useCallback", owner, target: r.component, prop: root, label: `useCallback(${root}) in <${owner}>`, detail: `prop "${c.path}" of <${r.component}> is a new function on every render of <${owner}>.` });
+      out.push({
+        kind: "useCallback",
+        owner,
+        target: r.component,
+        prop: root,
+        label: `useCallback(${root}) in <${owner}>`,
+        detail: `prop "${c.path}" of <${r.component}> is a new function on every render of <${owner}>.`,
+        snippet: `// ${owner}
+import { useCallback } from 'react';
+
+const ${id} = useCallback((/* args */) => {
+  // ...
+}, [/* deps */]);
+
+<${r.component} ${root}={${id}} />`
+      });
     } else if (c.kind === "element") {
-      out.push({ kind: "useMemoElement", owner, target: r.component, prop: root, label: `memoize element prop ${root} in <${owner}>`, detail: `prop "${c.path}" of <${r.component}> is a new element with the same type and props on every render of <${owner}>.` });
+      out.push({
+        kind: "useMemoElement",
+        owner,
+        target: r.component,
+        prop: root,
+        label: `memoize element prop ${root} in <${owner}>`,
+        detail: `prop "${c.path}" of <${r.component}> is a new element with the same type and props on every render of <${owner}>.`,
+        snippet: `// ${owner}
+import { useMemo } from 'react';
+
+const ${id} = useMemo(() => ${shortValue(c.next, 40)}, [/* deps */]);
+// or pass it as children from a component that does not re-render`
+      });
     } else {
-      out.push({ kind: "useMemo", owner, target: r.component, prop: root, label: `useMemo(${root}) in <${owner}>`, detail: `prop "${c.path}" of <${r.component}> is a new ${Array.isArray(c.next) ? "array" : "object"} with the same contents on every render of <${owner}>.` });
+      const isArray = Array.isArray(c.next);
+      out.push({
+        kind: "useMemo",
+        owner,
+        target: r.component,
+        prop: root,
+        label: `useMemo(${root}) in <${owner}>`,
+        detail: `prop "${c.path}" of <${r.component}> is a new ${isArray ? "array" : "object"} with the same contents on every render of <${owner}>.`,
+        snippet: `// ${owner}
+import { useMemo } from 'react';
+
+const ${id} = useMemo(() => (${shortValue(c.next, 80)}), [/* deps */]);
+
+// or, when it never changes, hoist it to module scope:
+const ${id.toUpperCase()} = ${shortValue(c.next, 80)};`
+      });
     }
   }
-  for (const c of [...r.stateChanges, ...r.hookChanges]) {
-    const isContext = c.hook === "useContext";
+  for (const c of [...r.stateChanges || [], ...r.hookChanges || []]) {
+    const isContext = c.hook === "useContext" || /^useContext/.test(c.path);
     const ctxName = isContext ? (/useContext\((.*)\)/.exec(c.path) || [])[1] || "Context" : "";
     const providerOwner = isContext && c.provider && c.provider.component ? c.provider.component : null;
     if (isContext && c.kind === "different" && c.changedKeys && typeof c.totalKeys === "number" && c.changedKeys.length > 0 && c.changedKeys.length < c.totalKeys) {
@@ -57,20 +213,63 @@ function fixesFor(r) {
         target: r.component,
         prop: ctxName,
         label: `split ${ctxName}${providerOwner ? ` in <${providerOwner}>` : ""}: only ${c.changedKeys.join(", ")} changed`,
-        detail: `${c.changedKeys.length} of ${c.totalKeys} keys changed in ${ctxName}, yet every consumer re-rendered.`
+        detail: `${c.changedKeys.map((k) => `"${k}"`).join(", ")} of ${c.totalKeys} keys changed in ${ctxName}, yet every consumer (like <${r.component}>) re-rendered. Consumers that read the other keys re-render for nothing.`,
+        snippet: `// ${providerOwner || "Provider"}
+// one context per independently-changing slice
+const ${identifier(ctxName)}Static = createContext(...);
+const ${identifier(ctxName)}${c.changedKeys.map((k) => k[0].toUpperCase() + k.slice(1)).join("")} = createContext(...);
+
+// or keep one context and let consumers select a slice:
+const ${c.changedKeys[0]} = useContextSelector(${ctxName}, (v) => v.${c.changedKeys[0]});`
       });
       continue;
     }
-    if (!AVOIDABLE.has(c.kind)) continue;
+    if (!AVOIDABLE_KINDS.has(c.kind)) continue;
     if (isContext) {
-      out.push({ kind: "contextValue", owner: providerOwner || `${ctxName}.Provider`, target: r.component, prop: ctxName, label: `memoize the ${ctxName} provider value${providerOwner ? ` in <${providerOwner}>` : ""}`, detail: `${ctxName} produced a new value that is deep-equal to the previous one.` });
+      out.push({
+        kind: "contextValue",
+        owner: providerOwner || `${ctxName}.Provider`,
+        target: r.component,
+        prop: ctxName,
+        label: `memoize the ${ctxName} provider value${providerOwner ? ` in <${providerOwner}>` : ""}`,
+        detail: `<${r.component}> re-rendered because ${ctxName} produced a new value that is deep-equal to the previous one${providerOwner ? ` (Provider rendered by <${providerOwner}>)` : ""}.`,
+        snippet: `// ${providerOwner || `where <${ctxName}.Provider> is rendered`}
+const value = useMemo(() => ({ /* ... */ }), [/* deps */]);
+<${ctxName}.Provider value={value}>`
+      });
     } else if (c.hook === "useSyncExternalStore") {
       const chain = c.custom || [];
       const redux = chain.some((n) => /^use(App)?Selector$/.test(n));
       const zustand = !redux && chain.some((n) => /^use[A-Z]\w*Store$/.test(n) || n === "useStore" || n === "useBoundStore");
-      out.push({ kind: "storeSnapshot", owner: r.component, target: r.component, prop: c.path, label: redux ? `memoize the selector in <${r.component}>` : zustand ? `useShallow in <${r.component}>` : `stable getSnapshot in <${r.component}>`, detail: storeAdvice(c.custom) });
+      const via = chain.length ? ` via ${chain.join(" \u203A ")}` : "";
+      out.push({
+        kind: "storeSnapshot",
+        owner: r.component,
+        target: r.component,
+        prop: c.path,
+        label: redux ? `memoize the selector in <${r.component}>` : zustand ? `useShallow in <${r.component}>` : `stable getSnapshot in <${r.component}>`,
+        detail: redux ? `the selector${via} returns a new object on every call, so the component re-renders on every store change.` : zustand ? `the store selector${via} returns a new object on every call, so the component re-renders on every store change.` : `${c.path}${via} returned a new reference with the same contents; getSnapshot must return a cached value.`,
+        snippet: redux ? `// ${r.component}
+import { shallowEqual } from 'react-redux';
+const slice = useSelector(selectSlice, shallowEqual);
+// or memoize: const selectSlice = createSelector([selectA, selectB], (a, b) => ({ a, b }));` : zustand ? `// ${r.component}
+import { useShallow } from 'zustand/react/shallow';
+const { a, b } = useStore(useShallow((s) => ({ a: s.a, b: s.b })));
+// or select a primitive: const a = useStore((s) => s.a);` : `// ${r.component}
+// getSnapshot must return the same reference while the data is unchanged
+const snapshot = useSyncExternalStore(subscribe, store.getSnapshot /* cached */);`
+      });
     } else {
-      out.push({ kind: "bailout", owner: r.component, target: r.component, prop: c.path, label: `bail out before setting ${c.path} in <${r.component}>`, detail: `${c.path} was set to a value deep-equal to the current one (new reference).` });
+      out.push({
+        kind: "bailout",
+        owner: r.component,
+        target: r.component,
+        prop: c.path,
+        label: `bail out before setting ${c.path} in <${r.component}>`,
+        detail: `${c.path} was set to a value deep-equal to the current one (new reference).`,
+        snippet: `// ${r.component}
+setState((prev) => (deepEqual(prev, next) ? prev : next));`
+      });
     }
   }
   return out;
@@ -84,11 +283,12 @@ function rankFixes(reports) {
       const key = fixKey(f);
       let agg = byKey.get(key);
       if (!agg) {
-        agg = { ...f, key, count: 0, components: {} };
+        agg = { ...f, key, count: 0, components: {}, reports: [] };
         byKey.set(key, agg);
       }
       agg.count++;
       agg.components[r.component] = (agg.components[r.component] || 0) + 1;
+      if (agg.reports.length < MAX_FIX_REPORTS) agg.reports.push(r);
     }
   }
   return [...byKey.values()].sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
@@ -98,6 +298,8 @@ function formatFixes(reports, limit = 10) {
   if (!ranked.length) return "No avoidable re-renders.";
   const lines = ranked.slice(0, limit).map((f, i) => `${String(i + 1).padStart(2)}. ${f.label}  (removes ${f.count}: ${Object.entries(f.components).map(([c, n]) => `<${c}>${n > 1 ? " x" + n : ""}`).join(", ")})`);
   if (ranked.length > limit) lines.push(`    \u2026 ${ranked.length - limit} more`);
+  const roots = formatRootCauses(reports, 5);
+  if (roots) lines.push("", "Root causes:", roots);
   return lines.join("\n");
 }
 
@@ -287,12 +489,20 @@ function createRelayServer(options = {}) {
         clearInterval(ping);
         role.delete(res);
       });
+      const count = () => ({ __rerenderLens: true, version: 2, type: "relay", payload: { apps: apps.size } });
       if (role === apps) {
-        send(panels, { __rerenderLens: true, version: 2, type: "relay", payload: { apps: apps.size } });
-        req.on("close", () => send(panels, { __rerenderLens: true, version: 2, type: "relay", payload: { apps: apps.size } }));
+        send(panels, count());
+        req.on("close", () => send(panels, count()));
+      } else {
+        send(/* @__PURE__ */ new Set([res]), count());
       }
       return;
     }
+    if (u.pathname === "/favicon.ico") {
+      res.statusCode = 204;
+      res.end();
+      return;
+    }
     if (u.pathname === "/message" && req.method === "POST") {
       try {
         const parsed = JSON.parse(await readBody(req) || "null");
@@ -393,6 +603,13 @@ function main(argv) {
         console.log(formatFixes(reports, Number(flag("--limit") || 20)));
         return 0;
       }
+      case "causes": {
+        const file = positional[0];
+        if (!file) throw new Error("usage: rerender-lens causes <export.json> [--limit N]");
+        const { reports } = parseExport(read(file));
+        console.log(formatRootCauses(reports, Number(flag("--limit") || 10)) || "No root causes: no avoidable re-renders, or the reports carry no commit ids.");
+        return 0;
+      }
       case "summary": {
         const file = positional[0];
         if (!file) throw new Error("usage: rerender-lens summary <export.json> [--out summary.json]");
@@ -436,7 +653,7 @@ ${cmp.regressions.length} component${cmp.regressions.length === 1 ? "" : "s"} re
         return 1;
       }
       default:
-        console.error("usage: rerender-lens <panel|fixes|summary|compare|budget> ...");
+        console.error("usage: rerender-lens <panel|fixes|causes|summary|compare|budget> ...");
         return cmd ? 1 : 0;
     }
   } catch (e) {