@memlab/heap-analysis 1.0.14 → 1.0.16

package/dist/BaseAnalysis.d.ts

@@ -7,9 +7,8 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { AnyValue } from '@memlab/core';
-import type { HeapAnalysisOptions } from './PluginUtils';
-import { BaseOption } from '@memlab/core';
+import type { AnyValue, BaseOption } from '@memlab/core';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions, RunHeapAnalysisOptions } from './PluginUtils';
 declare abstract class Analysis {
     process(_options: HeapAnalysisOptions): Promise<void>;
     /**
@@ -27,33 +26,65 @@ declare abstract class Analysis {
     /**
      * Run heap analysis for a single heap snapshot file
      * @param file the absolute path of a `.heapsnapshot` file.
-     * @returns this API returns void. To get the analysis results,
-     * check out the documentation of the hosting heap analysis class and
-     * call the analysis-specific API to get results after calling this method.
+     * @param options optional configuration for the heap analysis run
+     * @returns this API returns {@link AnalyzeSnapshotResult}, which contains
+     * the logging file of analysis console output. Alternatively, to get more
+     * structured analysis results, check out the documentation of the hosting
+     * heap analysis class and call the analysis-specific API to get results
+     * after calling this method.
      * * **Example**:
      * ```typescript
      * const analysis = new StringAnalysis();
-     * await anaysis.analyzeSnapshotFromFile(snapshotFile);
+     * // analysis console output is saved in result.analysisOutputFile
+     * const result = await analysis.analyzeSnapshotFromFile(snapshotFile);
+     * // query analysis-specific and structured results
      * const stringPatterns = analysis.getTopDuplicatedStringsInCount();
      * ```
+     * Additionally, you can specify a working directory to where
+     * the intermediate, logging, and final output files will be dumped:
+     * ```typescript
+     * const analysis = new StringAnalysis();
+     * // analysis console output is saved in result.analysisOutputFile
+     * // which is inside the specified working directory
+     * const result = await analysis.analyzeSnapshotFromFile(snapshotFile, {
+     *   // if the specified directory doesn't exist, memlab will create it
+     *   workDir: '/tmp/your/work/dir',
+     * });
+     * ```
      */
-    analyzeSnapshotFromFile(file: string): Promise<void>;
+    analyzeSnapshotFromFile(file: string, options?: RunHeapAnalysisOptions): Promise<AnalyzeSnapshotResult>;
     /**
      * Run heap analysis for a series of heap snapshot files
      * @param directory the absolute path of the directory holding a series of
      * `.heapsnapshot` files, all snapshot files will be loaded and analyzed
      * in the alphanumerically ascending order of those snapshot file names.
-     * @returns this API returns void. To get the analysis results,
-     * check out the documentation of the hosting heap analysis class and
-     * call the analysis-specific API to get results after calling this method.
+     * @param options optional configuration for the heap analysis run
+     * @returns this API returns {@link AnalyzeSnapshotResult}, which contains
+     * the logging file of analysis console output. Alternatively, to get more
+     * structured analysis results, check out the documentation of the hosting
+     * heap analysis class and call the analysis-specific API to get results
+     * after calling this method.
      * * **Example**:
      * ```typescript
      * const analysis = new ShapeUnboundGrowthAnalysis();
-     * await anaysis.analyzeSnapshotsInDirectory(snapshotDirectory);
+     * // analysis console output is saved in result.analysisOutputFile
+     * const result = await analysis.analyzeSnapshotsInDirectory(snapshotDirectory);
+     * // query analysis-specific and structured results
      * const shapes = analysis.getShapesWithUnboundGrowth();
      * ```
+     * * Additionally, you can specify a working directory to where
+     * the intermediate, logging, and final output files will be dumped:
+     * ```typescript
+     * const analysis = new ShapeUnboundGrowthAnalysis();
+     * // analysis console output is saved in result.analysisOutputFile
+     * // which is inside the specified working directory
+     * const result = await analysis.analyzeSnapshotsInDirectory(snapshotDirectory, {
+     *   // if the specified directory doesn't exist, memlab will create it
+     *   workDir: '/tmp/your/work/dir',
+     * });
+     * ```
      */
-    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
+    analyzeSnapshotsInDirectory(directory: string, options?: RunHeapAnalysisOptions): Promise<AnalyzeSnapshotResult>;
 }
 /**
  *

package/dist/BaseAnalysis.js

@@ -68,25 +68,49 @@ class Analysis {
     /**
      * Run heap analysis for a single heap snapshot file
      * @param file the absolute path of a `.heapsnapshot` file.
-     * @returns this API returns void. To get the analysis results,
-     * check out the documentation of the hosting heap analysis class and
-     * call the analysis-specific API to get results after calling this method.
+     * @param options optional configuration for the heap analysis run
+     * @returns this API returns {@link AnalyzeSnapshotResult}, which contains
+     * the logging file of analysis console output. Alternatively, to get more
+     * structured analysis results, check out the documentation of the hosting
+     * heap analysis class and call the analysis-specific API to get results
+     * after calling this method.
      * * **Example**:
      * ```typescript
      * const analysis = new StringAnalysis();
-     * await anaysis.analyzeSnapshotFromFile(snapshotFile);
+     * // analysis console output is saved in result.analysisOutputFile
+     * const result = await analysis.analyzeSnapshotFromFile(snapshotFile);
+     * // query analysis-specific and structured results
      * const stringPatterns = analysis.getTopDuplicatedStringsInCount();
      * ```
+     * Additionally, you can specify a working directory to where
+     * the intermediate, logging, and final output files will be dumped:
+     * ```typescript
+     * const analysis = new StringAnalysis();
+     * // analysis console output is saved in result.analysisOutputFile
+     * // which is inside the specified working directory
+     * const result = await analysis.analyzeSnapshotFromFile(snapshotFile, {
+     *   // if the specified directory doesn't exist, memlab will create it
+     *   workDir: '/tmp/your/work/dir',
+     * });
+     * ```
      */
-    analyzeSnapshotFromFile(file) {
+    analyzeSnapshotFromFile(file, options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.process({
+            if (options.workDir) {
+                // set and init the new work dir
+                core_1.config.defaultFileManagerOption = options;
+            }
+            const analysisOutputFile = core_1.fileManager.initNewHeapAnalysisLogFile();
+            core_1.info.registerLogFile(analysisOutputFile);
+            yield this.process({
                 args: {
                     _: [],
                     snapshot: file,
                     'snapshot-dir': '<MUST_PROVIDE_SNAPSHOT_DIR>',
                 },
             });
+            core_1.info.unregisterLogFile(analysisOutputFile);
+            return { analysisOutputFile };
         });
     }
     /**
@@ -94,25 +118,49 @@ class Analysis {
      * @param directory the absolute path of the directory holding a series of
      * `.heapsnapshot` files, all snapshot files will be loaded and analyzed
      * in the alphanumerically ascending order of those snapshot file names.
-     * @returns this API returns void. To get the analysis results,
-     * check out the documentation of the hosting heap analysis class and
-     * call the analysis-specific API to get results after calling this method.
+     * @param options optional configuration for the heap analysis run
+     * @returns this API returns {@link AnalyzeSnapshotResult}, which contains
+     * the logging file of analysis console output. Alternatively, to get more
+     * structured analysis results, check out the documentation of the hosting
+     * heap analysis class and call the analysis-specific API to get results
+     * after calling this method.
      * * **Example**:
      * ```typescript
      * const analysis = new ShapeUnboundGrowthAnalysis();
-     * await anaysis.analyzeSnapshotsInDirectory(snapshotDirectory);
+     * // analysis console output is saved in result.analysisOutputFile
+     * const result = await analysis.analyzeSnapshotsInDirectory(snapshotDirectory);
+     * // query analysis-specific and structured results
      * const shapes = analysis.getShapesWithUnboundGrowth();
      * ```
+     * * Additionally, you can specify a working directory to where
+     * the intermediate, logging, and final output files will be dumped:
+     * ```typescript
+     * const analysis = new ShapeUnboundGrowthAnalysis();
+     * // analysis console output is saved in result.analysisOutputFile
+     * // which is inside the specified working directory
+     * const result = await analysis.analyzeSnapshotsInDirectory(snapshotDirectory, {
+     *   // if the specified directory doesn't exist, memlab will create it
+     *   workDir: '/tmp/your/work/dir',
+     * });
+     * ```
      */
-    analyzeSnapshotsInDirectory(directory) {
+    analyzeSnapshotsInDirectory(directory, options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.process({
+            if (options.workDir) {
+                // set and init the new work dir
+                core_1.config.defaultFileManagerOption = options;
+            }
+            const analysisOutputFile = core_1.fileManager.initNewHeapAnalysisLogFile();
+            core_1.info.registerLogFile(analysisOutputFile);
+            yield this.process({
                 args: {
                     _: [],
                     snapshot: '<MUST_PROVIDE_SNAPSHOT_FILE>',
                     'snapshot-dir': directory,
                 },
             });
+            core_1.info.unregisterLogFile(analysisOutputFile);
+            return { analysisOutputFile };
         });
     }
 }

package/dist/PluginUtils.d.ts

@@ -25,6 +25,27 @@ export declare type HeapAnalysisOptions = {
     /** @internal */
     config?: MemLabConfig;
 };
+/**
+ * This is the input option for {@link analyzeSnapshotFromFile}
+ * and {@link analyzeSnapshotsInDirectory}.
+ */
+export declare type RunHeapAnalysisOptions = {
+    /**
+     * specify the working directory to where the intermediate, logging,
+     * and output files should be saved
+     */
+    workDir?: string;
+};
+/**
+ * This is the return type from calling {@link analyzeSnapshotFromFile}
+ * or {@link analyzeSnapshotsInDirectory}.
+ */
+export declare type AnalyzeSnapshotResult = {
+    /**
+     * file path of the console output of the heap analysis call
+     */
+    analysisOutputFile: string;
+};
 declare type PrintNodeOption = {
     indent?: string;
     printReferences?: boolean;

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export declare function registerPackage(): Promise<void>;
 export declare const getDominatorNodes: (ids: Set<number>, snapshot: import("@memlab/core").IHeapSnapshot) => Set<number>, 
 /** @deprecated */
 getHeapFromFile: (file: string) => Promise<import("@memlab/core").IHeapSnapshot>, getFullHeapFromFile: (file: string) => Promise<import("@memlab/core").IHeapSnapshot>, getSnapshotDirForAnalysis: (options: import("./PluginUtils").HeapAnalysisOptions) => import("@memlab/core").Nullable<string>, getSnapshotFileForAnalysis: (options: import("./PluginUtils").HeapAnalysisOptions) => string, loadHeapSnapshot: (options: import("./PluginUtils").HeapAnalysisOptions) => Promise<import("@memlab/core").IHeapSnapshot>, snapshotMapReduce: <T1, T2>(mapCallback: (snapshot: import("@memlab/core").IHeapSnapshot, i: number, file: string) => T1, reduceCallback: (results: T1[]) => T2, options: import("./PluginUtils").HeapAnalysisOptions) => Promise<T2>, takeNodeFullHeap: () => Promise<import("@memlab/core").IHeapSnapshot>;
-export type { HeapAnalysisOptions } from './PluginUtils';
+export type { AnalyzeSnapshotResult, HeapAnalysisOptions, RunHeapAnalysisOptions, } from './PluginUtils';
 export { default as BaseAnalysis } from './BaseAnalysis';
 export { default as DetachedDOMElementAnalysis } from './plugins/DetachedDOMElementAnalysis';
 export { default as GlobalVariableAnalysis } from './plugins/GlobalVariableAnalysis/GlobalVariableAnalysis';

package/dist/plugins/CollectionUnboundGrowthAnalysis.d.ts

@@ -7,7 +7,7 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
 import type { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../BaseAnalysis';
 declare class CollectionUnboundGrowthAnalysis extends BaseAnalysis {
@@ -17,7 +17,7 @@ declare class CollectionUnboundGrowthAnalysis extends BaseAnalysis {
     /** @internal */
     getOptions(): BaseOption[];
     /** @internal */
-    analyzeSnapshotFromFile(file: string): Promise<void>;
+    analyzeSnapshotFromFile(file: string): Promise<AnalyzeSnapshotResult>;
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;
     private checkUnboundCollection;

package/dist/plugins/CollectionsHoldingStaleAnalysis.d.ts

@@ -7,7 +7,7 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
 import { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../BaseAnalysis';
 export default class CollectionsHoldingStaleAnalysis extends BaseAnalysis {
@@ -17,7 +17,7 @@ export default class CollectionsHoldingStaleAnalysis extends BaseAnalysis {
     /** @internal */
     getOptions(): BaseOption[];
     /** @internal */
-    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
+    analyzeSnapshotsInDirectory(directory: string): Promise<AnalyzeSnapshotResult>;
     private staleCollectionMapper;
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;

package/dist/plugins/DetachedDOMElementAnalysis.d.ts

@@ -7,7 +7,7 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
 import type { IHeapNode } from '@memlab/core';
 import { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../BaseAnalysis';
@@ -18,7 +18,7 @@ export default class DetachedDOMElementAnalysis extends BaseAnalysis {
     /** @internal */
     getOptions(): BaseOption[];
     /** @internal */
-    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
+    analyzeSnapshotsInDirectory(directory: string): Promise<AnalyzeSnapshotResult>;
     private detachedElements;
     getDetachedElements(): IHeapNode[];
     /** @internal */

package/dist/plugins/GlobalVariableAnalysis/GlobalVariableAnalysis.d.ts

@@ -7,7 +7,7 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../../PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../../PluginUtils';
 import { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../../BaseAnalysis';
 declare class GlobalVariableAnalysis extends BaseAnalysis {
@@ -19,7 +19,7 @@ declare class GlobalVariableAnalysis extends BaseAnalysis {
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;
     /** @internal */
-    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
+    analyzeSnapshotsInDirectory(directory: string): Promise<AnalyzeSnapshotResult>;
     private shouldFilterOutEdge;
     /** @internal */
     private getGlobalVariables;

package/dist/plugins/ObjectContentAnalysis.d.ts

@@ -7,7 +7,7 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
 import { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../BaseAnalysis';
 declare class GlobalVariableAnalysis extends BaseAnalysis {
@@ -19,7 +19,7 @@ declare class GlobalVariableAnalysis extends BaseAnalysis {
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;
     /** @internal */
-    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
+    analyzeSnapshotsInDirectory(directory: string): Promise<AnalyzeSnapshotResult>;
     /** @internal */
     private getObjectProperties;
     /** @internal */

package/dist/plugins/ObjectFanoutAnalysis.d.ts

@@ -7,7 +7,7 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
 import { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../BaseAnalysis';
 declare class ObjectFanoutAnalysis extends BaseAnalysis {
@@ -17,7 +17,7 @@ declare class ObjectFanoutAnalysis extends BaseAnalysis {
     /** @internal */
     getOptions(): BaseOption[];
     /** @internal */
-    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
+    analyzeSnapshotsInDirectory(directory: string): Promise<AnalyzeSnapshotResult>;
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;
     private getObjectsWithHighFanout;

package/dist/plugins/ObjectShallowAnalysis.d.ts

@@ -7,7 +7,7 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
 import { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../BaseAnalysis';
 /**
@@ -44,7 +44,7 @@ declare class ObjectShallowAnalysis extends BaseAnalysis {
     /** @internal */
     getOptions(): BaseOption[];
     /** @internal */
-    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
+    analyzeSnapshotsInDirectory(directory: string): Promise<AnalyzeSnapshotResult>;
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;
     /**

package/dist/plugins/ObjectShapeAnalysis.d.ts

@@ -7,8 +7,8 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
-import { BaseOption } from '@memlab/core';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
+import type { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../BaseAnalysis';
 declare class ObjectShapeAnalysis extends BaseAnalysis {
     getCommandName(): string;
@@ -17,9 +17,19 @@ declare class ObjectShapeAnalysis extends BaseAnalysis {
     /** @internal */
     getOptions(): BaseOption[];
     /** @internal */
-    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
+    analyzeSnapshotsInDirectory(directory: string): Promise<AnalyzeSnapshotResult>;
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;
+    /** @internal */
+    breakDownMemoryByShapes(options?: {
+        file?: string;
+    }): Promise<void>;
+    /** @internal */
+    private breakDownSnapshotByShapes;
+    /** @internal */
+    private breakDownByReferrers;
+    /** @internal */
+    private isTrivialEdgeForBreakDown;
 }
 export default ObjectShapeAnalysis;
 //# sourceMappingURL=ObjectShapeAnalysis.d.ts.map

package/dist/plugins/ObjectShapeAnalysis.js

@@ -21,6 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const chalk_1 = __importDefault(require("chalk"));
 const core_1 = require("@memlab/core");
 const BaseAnalysis_1 = __importDefault(require("../BaseAnalysis"));
 const PluginUtils_1 = __importDefault(require("../PluginUtils"));
@@ -49,8 +50,132 @@ class ObjectShapeAnalysis extends BaseAnalysis_1.default {
     process(options) {
         return __awaiter(this, void 0, void 0, function* () {
             const snapshotPath = PluginUtils_1.default.getSnapshotFileForAnalysis(options);
-            yield core_1.analysis.breakDownMemoryByShapes({ file: snapshotPath });
+            yield this.breakDownMemoryByShapes({ file: snapshotPath });
         });
     }
+    /** @internal */
+    breakDownMemoryByShapes(options = {}) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const opt = { buildNodeIdIndex: true, verbose: true };
+            const file = options.file ||
+                core_1.utils.getSnapshotFilePathWithTabType(/.*/) ||
+                '<EMPTY_FILE_PATH>';
+            const snapshot = yield core_1.utils.getSnapshotFromFile(file, opt);
+            core_1.analysis.preparePathFinder(snapshot);
+            const heapInfo = core_1.analysis.getOverallHeapInfo(snapshot, { force: true });
+            if (heapInfo) {
+                core_1.analysis.printHeapInfo(heapInfo);
+            }
+            this.breakDownSnapshotByShapes(snapshot);
+        });
+    }
+    /** @internal */
+    breakDownSnapshotByShapes(snapshot) {
+        core_1.info.overwrite('Breaking down memory by shapes...');
+        const breakdown = Object.create(null);
+        const population = Object.create(null);
+        // group objects based on their shapes
+        snapshot.nodes.forEach((node) => {
+            if ((node.type !== 'object' && !core_1.utils.isStringNode(node)) ||
+                core_1.config.nodeIgnoreSetInShape.has(node.name)) {
+                return;
+            }
+            const key = core_1.serializer.summarizeNodeShape(node);
+            breakdown[key] = breakdown[key] || new Set();
+            breakdown[key].add(node.id);
+            if (population[key] === undefined) {
+                population[key] = { examples: [], n: 0 };
+            }
+            ++population[key].n;
+            // retain the top 5 examples
+            const examples = population[key].examples;
+            examples.push(node);
+            examples.sort((n1, n2) => n2.retainedSize - n1.retainedSize);
+            if (examples.length > 5) {
+                examples.pop();
+            }
+        });
+        // calculate and sort based on retained sizes
+        const ret = [];
+        for (const key in breakdown) {
+            const size = core_1.utils.aggregateDominatorMetrics(breakdown[key], snapshot, () => true, core_1.utils.getRetainedSize);
+            ret.push({ key, retainedSize: size });
+        }
+        ret.sort((o1, o2) => o2.retainedSize - o1.retainedSize);
+        core_1.info.topLevel('Object shapes with top retained sizes:');
+        core_1.info.lowLevel(' (Use `memlab trace --node-id=@ID` to get trace)\n');
+        const topList = ret.slice(0, 40);
+        // print settings
+        const opt = { color: true, compact: true };
+        const dot = chalk_1.default.grey('· ');
+        const colon = chalk_1.default.grey(': ');
+        // print the shapes with the biggest retained size
+        for (const o of topList) {
+            const referrerInfo = this.breakDownByReferrers(breakdown[o.key], snapshot);
+            const { examples, n } = population[o.key];
+            const shapeStr = core_1.serializer.summarizeNodeShape(examples[0], opt);
+            const bytes = core_1.utils.getReadableBytes(o.retainedSize);
+            const examplesStr = examples
+                .map(e => `@${e.id} [${core_1.utils.getReadableBytes(e.retainedSize)}]`)
+                .join(' | ');
+            const meta = chalk_1.default.grey(` (N: ${n}, Examples: ${examplesStr})`);
+            core_1.info.topLevel(`${dot}${shapeStr}${colon}${bytes}${meta}`);
+            core_1.info.lowLevel(referrerInfo + '\n');
+        }
+    }
+    /** @internal */
+    breakDownByReferrers(ids, snapshot) {
+        const edgeNames = Object.create(null);
+        for (const id of ids) {
+            const node = snapshot.getNodeById(id);
+            for (const edge of (node === null || node === void 0 ? void 0 : node.referrers) || []) {
+                const source = edge.fromNode;
+                if (!core_1.utils.isMeaningfulEdge(edge) ||
+                    this.isTrivialEdgeForBreakDown(edge)) {
+                    continue;
+                }
+                const sourceName = core_1.serializer.summarizeNodeName(source, {
+                    color: false,
+                });
+                const edgeName = core_1.serializer.summarizeEdgeName(edge, {
+                    color: false,
+                    abstract: true,
+                });
+                const edgeKey = `[${sourceName}] --${edgeName}--> `;
+                edgeNames[edgeKey] = edgeNames[edgeKey] || {
+                    numberOfEdgesToNode: 0,
+                    source,
+                    edge,
+                };
+                ++edgeNames[edgeKey].numberOfEdgesToNode;
+            }
+        }
+        const referrerInfo = Object.entries(edgeNames)
+            .sort((i1, i2) => i2[1].numberOfEdgesToNode - i1[1].numberOfEdgesToNode)
+            .slice(0, 4)
+            .map(i => {
+            const meta = i[1];
+            const source = core_1.serializer.summarizeNodeName(meta.source, {
+                color: true,
+            });
+            const edgeName = core_1.serializer.summarizeEdgeName(meta.edge, {
+                color: true,
+                abstract: true,
+            });
+            const edgeSummary = `${source} --${edgeName}-->`;
+            return `  · ${edgeSummary}: ${meta.numberOfEdgesToNode}`;
+        })
+            .join('\n');
+        return referrerInfo;
+    }
+    /** @internal */
+    isTrivialEdgeForBreakDown(edge) {
+        const source = edge.fromNode;
+        return (source.type === 'array' ||
+            source.name === '(object elements)' ||
+            source.name === 'system' ||
+            edge.name_or_index === '__proto__' ||
+            edge.name_or_index === 'prototype');
+    }
 }
 exports.default = ObjectShapeAnalysis;

package/dist/plugins/ObjectSizeAnalysis.d.ts

@@ -7,7 +7,7 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
 import { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../BaseAnalysis';
 declare class ObjectSizeRankAnalysis extends BaseAnalysis {
@@ -17,7 +17,7 @@ declare class ObjectSizeRankAnalysis extends BaseAnalysis {
     /** @internal */
     getOptions(): BaseOption[];
     /** @internal */
-    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
+    analyzeSnapshotsInDirectory(directory: string): Promise<AnalyzeSnapshotResult>;
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;
 }

package/dist/plugins/ObjectUnboundGrowthAnalysis.d.ts

@@ -7,8 +7,8 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
-import { BaseOption } from '@memlab/core';
+import type { BaseOption } from '@memlab/core';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
 import BaseAnalysis from '../BaseAnalysis';
 declare class ObjectUnboundGrowthAnalysis extends BaseAnalysis {
     getCommandName(): string;
@@ -17,9 +17,12 @@ declare class ObjectUnboundGrowthAnalysis extends BaseAnalysis {
     /** @internal */
     getOptions(): BaseOption[];
     /** @internal */
-    analyzeSnapshotFromFile(file: string): Promise<void>;
+    analyzeSnapshotFromFile(file: string): Promise<AnalyzeSnapshotResult>;
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;
+    private checkUnbound;
+    private detectUnboundGrowth;
+    private calculateRetainedSizes;
 }
 export default ObjectUnboundGrowthAnalysis;
 //# sourceMappingURL=ObjectUnboundGrowthAnalysis.d.ts.map

package/dist/plugins/ObjectUnboundGrowthAnalysis.js

@@ -21,6 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
 const core_1 = require("@memlab/core");
 const BaseAnalysis_1 = __importDefault(require("../BaseAnalysis"));
 const HeapAnalysisSnapshotDirectoryOption_1 = __importDefault(require("../options/HeapAnalysisSnapshotDirectoryOption"));
@@ -52,8 +53,148 @@ class ObjectUnboundGrowthAnalysis extends BaseAnalysis_1.default {
             const snapshotDir = PluginUtils_1.default.getSnapshotDirForAnalysis(options);
             const opt = snapshotDir ? { minSnapshots: 2, snapshotDir } : {};
             core_1.config.chaseWeakMapEdge = false;
-            yield core_1.analysis.checkUnbound(opt);
+            yield this.checkUnbound(opt);
         });
     }
+    checkUnbound(options = {}) {
+        return __awaiter(this, void 0, void 0, function* () {
+            core_1.analysis.visualizeMemoryUsage(options);
+            core_1.utils.checkSnapshots(options);
+            yield this.detectUnboundGrowth(options);
+        });
+    }
+    // find any objects that keeps growing
+    detectUnboundGrowth(options = {}) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const nodeInfo = Object.create(null);
+            let hasCheckedFirstSnapshot = false;
+            let snapshot = null;
+            const isValidNode = (node) => node.type === 'object' ||
+                node.type === 'closure' ||
+                node.type === 'regexp';
+            const initNodeInfo = (node) => {
+                if (!isValidNode(node)) {
+                    return;
+                }
+                const n = node.retainedSize;
+                nodeInfo[node.id] = {
+                    type: node.type,
+                    name: node.name,
+                    min: n,
+                    max: n,
+                    history: [n],
+                    node,
+                };
+            };
+            const updateNodeInfo = (node) => {
+                const item = nodeInfo[node.id];
+                if (!item) {
+                    return;
+                }
+                if (node.name !== item.name || node.type !== item.type) {
+                    nodeInfo[node.id] = null;
+                    return;
+                }
+                const n = node.retainedSize;
+                // only monotonic increase?
+                if (core_1.config.monotonicUnboundGrowthOnly && n < item.max) {
+                    nodeInfo[node.id] = null;
+                    return;
+                }
+                item.history.push(n);
+                item.max = Math.max(item.max, n);
+                item.min = Math.min(item.min, n);
+            };
+            // summarize the heap objects info in current heap snapshot
+            // this is mainly used for better understanding of the % of
+            // objects released and allocated over time
+            const maybeSummarizeNodeInfo = () => {
+                if (!core_1.config.verbose) {
+                    return;
+                }
+                let n = 0;
+                for (const k in nodeInfo) {
+                    if (nodeInfo[k]) {
+                        ++n;
+                    }
+                }
+                core_1.info.lowLevel(`Objects tracked: ${n}`);
+            };
+            core_1.info.overwrite('Checking unbounded objects...');
+            const snapshotFiles = options.snapshotDir
+                ? // load snapshots from a directory
+                    core_1.utils.getSnapshotFilesInDir(options.snapshotDir)
+                : // load snapshots based on the visit sequence meta data
+                    core_1.utils.getSnapshotFilesFromTabsOrder();
+            for (const file of snapshotFiles) {
+                // force GC before loading each snapshot
+                if (global.gc) {
+                    global.gc();
+                }
+                // load and preprocess heap snapshot
+                const opt = { buildNodeIdIndex: true, verbose: true };
+                snapshot = yield core_1.utils.getSnapshotFromFile(file, opt);
+                this.calculateRetainedSizes(snapshot);
+                // keep track of heap objects
+                if (!hasCheckedFirstSnapshot) {
+                    // record Ids in the snapshot
+                    snapshot.nodes.forEach(initNodeInfo);
+                    hasCheckedFirstSnapshot = true;
+                }
+                else {
+                    snapshot.nodes.forEach(updateNodeInfo);
+                    maybeSummarizeNodeInfo();
+                }
+            }
+            // exit if no heap snapshot found
+            if (!hasCheckedFirstSnapshot) {
+                return;
+            }
+            // post process and print the unbounded objects
+            const idsInLastSnapshot = new Set();
+            snapshot === null || snapshot === void 0 ? void 0 : snapshot.nodes.forEach(node => {
+                idsInLastSnapshot.add(node.id);
+            });
+            let ids = [];
+            for (const key in nodeInfo) {
+                const id = parseInt(key, 10);
+                const item = nodeInfo[id];
+                if (!item) {
+                    continue;
+                }
+                if (!idsInLastSnapshot.has(id)) {
+                    continue;
+                }
+                if (item.min === item.max) {
+                    continue;
+                }
+                // filter out non-significant leaks
+                if (item.history[item.history.length - 1] < core_1.config.unboundSizeThreshold) {
+                    continue;
+                }
+                ids.push(Object.assign({ id }, item));
+            }
+            if (ids.length === 0) {
+                core_1.info.midLevel('No increasing objects found.');
+                return;
+            }
+            ids = ids
+                .sort((o1, o2) => o2.history[o2.history.length - 1] - o1.history[o1.history.length - 1])
+                .slice(0, 20);
+            // print on terminal
+            const str = core_1.serializer.summarizeUnboundedObjects(ids, { color: true });
+            core_1.info.topLevel('Top growing objects in sizes:');
+            core_1.info.lowLevel(' (Use `memlab trace --node-id=@ID` to get trace)');
+            core_1.info.topLevel('\n' + str);
+            // save results to file
+            const csv = core_1.serializer.summarizeUnboundedObjectsToCSV(ids);
+            fs_1.default.writeFileSync(core_1.config.unboundObjectCSV, csv, 'UTF-8');
+        });
+    }
+    calculateRetainedSizes(snapshot) {
+        const finder = new core_1.TraceFinder();
+        // dominator and retained size
+        finder.calculateAllNodesRetainedSizes(snapshot);
+    }
 }
 exports.default = ObjectUnboundGrowthAnalysis;

package/dist/plugins/ShapeUnboundGrowthAnalysis.d.ts

@@ -7,7 +7,7 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
 import { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../BaseAnalysis';
 declare type ShapeSummary = {
@@ -25,7 +25,7 @@ export default class ShapeUnboundGrowthAnalysis extends BaseAnalysis {
     /** @internal */
     getOptions(): BaseOption[];
     /** @internal */
-    analyzeSnapshotFromFile(file: string): Promise<void>;
+    analyzeSnapshotFromFile(file: string): Promise<AnalyzeSnapshotResult>;
     getShapesWithUnboundGrowth(): ShapeSummary[];
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;

package/dist/plugins/StringAnalysis.d.ts

@@ -7,7 +7,7 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
 import { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../BaseAnalysis';
 /**
@@ -58,7 +58,7 @@ export default class StringAnalysis extends BaseAnalysis {
     /** @internal */
     getOptions(): BaseOption[];
     /** @internal */
-    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
+    analyzeSnapshotsInDirectory(directory: string): Promise<AnalyzeSnapshotResult>;
     private static shouldIgnoreNode;
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;

package/dist/plugins/UnmountedReactFiberNodesAnalysis.d.ts

@@ -7,7 +7,7 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HeapAnalysisOptions } from '../PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from '../PluginUtils';
 import { BaseOption } from '@memlab/core';
 import BaseAnalysis from '../BaseAnalysis';
 export default class UnmountedFiberNodeAnalysis extends BaseAnalysis {
@@ -17,7 +17,7 @@ export default class UnmountedFiberNodeAnalysis extends BaseAnalysis {
     /** @internal */
     getOptions(): BaseOption[];
     /** @internal */
-    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
+    analyzeSnapshotsInDirectory(directory: string): Promise<AnalyzeSnapshotResult>;
     /** @internal */
     process(options: HeapAnalysisOptions): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/heap-analysis",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "license": "MIT",
   "description": "heap analysis plugins for memlab",
   "author": "Liang Gong <lgong@fb.com>",
@@ -50,7 +50,7 @@
   "scripts": {
     "build-pkg": "tsc",
     "test-pkg": "jest .",
-    "publish-patch": "npm version patch --force && npm publish",
+    "publish-patch": "npm publish",
     "clean-pkg": "rm -rf ./dist && rm -rf ./node_modules && rm -f ./tsconfig.tsbuildinfo"
   },
   "bugs": {