@memlab/heap-analysis 1.0.0

package/README.md

@@ -0,0 +1,11 @@
+# `@memlab/heap-analysis`
+
+> TODO: description
+
+## Usage
+
+```
+const heapAnalysis = require('heap-analysis');
+
+// TODO: DEMONSTRATE API
+```

package/dist/BaseAnalysis.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+import type { AnyValue } from '@memlab/core';
+import type { HeapAnalysisOptions } from './PluginUtils';
+import { BaseOption } from '@memlab/core';
+declare abstract class Analysis {
+    protected process(_options: HeapAnalysisOptions): Promise<AnyValue>;
+    run(options?: HeapAnalysisOptions): Promise<AnyValue>;
+    analyzeSnapshotFromFile(file: string): Promise<AnyValue>;
+    analyzeSnapshotsInDirectory(directory: string): Promise<AnyValue>;
+}
+declare class BaseAnalysis extends Analysis {
+    getCommandName(): string;
+    getDescription(): string;
+    protected process(_options: HeapAnalysisOptions): Promise<AnyValue>;
+    getOptions(): BaseOption[];
+}
+export default BaseAnalysis;
+//# sourceMappingURL=BaseAnalysis.d.ts.map

package/dist/BaseAnalysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseAnalysis.d.ts","sourceRoot":"","sources":["../src/BaseAnalysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,eAAe,CAAC;AAEvD,OAAO,EAAC,UAAU,EAA0B,MAAM,cAAc,CAAC;AAuBjE,uBAAe,QAAQ;cAEL,OAAO,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAM5D,GAAG,CACd,OAAO,GAAE,mBAAqD,GAC7D,OAAO,CAAC,QAAQ,CAAC;IAKP,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAUxD,2BAA2B,CACtC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,CAAC;CASrB;AAED,cAAM,YAAa,SAAQ,QAAQ;IAGjC,cAAc,IAAI,MAAM;IAOxB,cAAc,IAAI,MAAM;cAUR,OAAO,CAErB,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,QAAQ,CAAC;IAMpB,UAAU,IAAI,UAAU,EAAE;CAG3B;AAED,eAAe,YAAY,CAAC"}

package/dist/BaseAnalysis.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@memlab/core");
+const e2e_1 = require("@memlab/e2e");
+const PluginUtils_1 = __importDefault(require("./PluginUtils"));
+// Identify the target scenario and
+// add its setting to Config
+function loadScenarioConfig() {
+    core_1.utils.loadTargetInfoFromRunMeta();
+    if (core_1.config.targetApp === 'external' ||
+        core_1.config.targetTab.startsWith(core_1.constant.namePrefixForScenarioFromFile)) {
+        return;
+    }
+    const synthesizer = e2e_1.defaultTestPlanner.getSynthesizer({ needCookies: false });
+    synthesizer
+        .getNodeNameBlocklist()
+        .forEach(name => core_1.config.nodeNameBlockList.add(name));
+    synthesizer
+        .getEdgeNameBlocklist()
+        .forEach(name => core_1.config.edgeNameBlockList.add(name));
+}
+class Analysis {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    process(_options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const className = this.constructor.name;
+            throw new Error(`${className}.process is not implemented`);
+        });
+    }
+    // DO NOT override this method
+    run(options = PluginUtils_1.default.defaultAnalysisArgs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            loadScenarioConfig();
+            return yield this.process(options);
+        });
+    }
+    analyzeSnapshotFromFile(file) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.process({
+                args: {
+                    _: [],
+                    snapshot: file,
+                    'snapshot-dir': '<MUST_PROVIDE_SNAPSHOT_DIR>',
+                },
+            });
+        });
+    }
+    analyzeSnapshotsInDirectory(directory) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.process({
+                args: {
+                    _: [],
+                    snapshot: '<MUST_PROVIDE_SNAPSHOT_FILE>',
+                    'snapshot-dir': directory,
+                },
+            });
+        });
+    }
+}
+class BaseAnalysis extends Analysis {
+    // The following terminal command will initiate with this analysis
+    // `memlab analyze <command-name>`
+    getCommandName() {
+        const className = this.constructor.name;
+        throw new Error(`${className}.getCommandName is not implemented`);
+    }
+    // The description of this analysis will be printed by
+    // `memlab analyze list`
+    getDescription() {
+        const className = this.constructor.name;
+        throw new Error(`${className}.getDescription is not implemented`);
+    }
+    // Callback for `memlab analyze <command-name>`
+    // Do the memory analysis and print results in this callback
+    // The analysis should support:
+    //  1) printing results on screen
+    //  2) returning results via the return value
+    process(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const className = this.constructor.name;
+            throw new Error(`${className}.process is not implemented`);
+        });
+    }
+    // override this method if you would like CLI to print the option info
+    getOptions() {
+        return [];
+    }
+}
+exports.default = BaseAnalysis;

package/dist/HeapAnalysisLoader.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+import type BaseAnalysis from './BaseAnalysis';
+declare class HeapAnalysisLoader {
+    private modules;
+    loadAllAnalysis(): Map<string, BaseAnalysis>;
+    private registerAnalyses;
+    private registerAnalysesFromDir;
+}
+declare const _default: HeapAnalysisLoader;
+export default _default;
+//# sourceMappingURL=HeapAnalysisLoader.d.ts.map

package/dist/HeapAnalysisLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeapAnalysisLoader.d.ts","sourceRoot":"","sources":["../src/HeapAnalysisLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAE/C,cAAM,kBAAkB;IACtB,OAAO,CAAC,OAAO,CAAwC;IAEhD,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC;IASnD,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,uBAAuB;CA4BhC;;AAED,wBAAwC"}

package/dist/HeapAnalysisLoader.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+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 path_1 = __importDefault(require("path"));
+const core_1 = require("@memlab/core");
+class HeapAnalysisLoader {
+    constructor() {
+        this.modules = new Map();
+    }
+    loadAllAnalysis() {
+        if (this.modules.size === 0) {
+            // auto load all analysis modules
+            this.modules = new Map();
+            this.registerAnalyses();
+        }
+        return this.modules;
+    }
+    registerAnalyses() {
+        const modulesDir = path_1.default.resolve(__dirname, 'plugins');
+        this.registerAnalysesFromDir(modulesDir);
+    }
+    registerAnalysesFromDir(modulesDir) {
+        const moduleFiles = fs_1.default.readdirSync(modulesDir);
+        for (const moduleFile of moduleFiles) {
+            const modulePath = path_1.default.join(modulesDir, moduleFile);
+            // recursively import modules from subdirectories
+            if (fs_1.default.lstatSync(modulePath).isDirectory()) {
+                this.registerAnalysesFromDir(modulePath);
+                continue;
+            }
+            // only import modules files ends with with Analysis.js
+            if (!moduleFile.endsWith('Analysis.js')) {
+                continue;
+            }
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const module = require(modulePath);
+            const moduleConstructor = typeof module.default === 'function' ? module.default : module;
+            const moduleInstance = new moduleConstructor();
+            const commandName = moduleInstance.getCommandName();
+            if (this.modules.has(commandName)) {
+                core_1.utils.haltOrThrow(`heap command ${commandName} is already registered`);
+            }
+            this.modules.set(commandName, moduleInstance);
+        }
+    }
+}
+exports.default = new HeapAnalysisLoader();

package/dist/PluginUtils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+import type { ParsedArgs } from 'minimist';
+import { IHeapSnapshot, IHeapNode, AnyOptions, IHeapEdge, Nullable, MemLabConfig } from '@memlab/core';
+export declare type HeapAnalysisOptions = {
+    args: ParsedArgs;
+    config?: MemLabConfig;
+};
+declare function isNodeWorthInspecting(node: IHeapNode): boolean;
+declare type PrintNodeOption = {
+    indent?: string;
+    printReferences?: boolean;
+};
+declare function printNodeListInTerminal(nodeList: IHeapNode[], options?: AnyOptions & PrintNodeOption): void;
+declare function printReferencesInTerminal(edgeList: IHeapEdge[], options?: AnyOptions & PrintNodeOption): void;
+declare function getObjectOutgoingEdgeCount(node: IHeapNode): number;
+declare function getSnapshotFileForAnalysis(options: HeapAnalysisOptions): string;
+declare function getSnapshotDirForAnalysis(options: HeapAnalysisOptions): Nullable<string>;
+declare function loadHeapSnapshot(options: HeapAnalysisOptions): Promise<IHeapSnapshot>;
+declare function snapshotMapReduce<T1, T2>(mapCallback: (snapshot: IHeapSnapshot, i: number, file: string) => T1, reduceCallback: (results: T1[]) => T2, options: HeapAnalysisOptions): Promise<T2>;
+declare function aggregateDominatorMetrics(ids: Set<number>, snapshot: IHeapSnapshot, checkNodeCb: (node: IHeapNode) => boolean, nodeMetricsCb: (node: IHeapNode) => number): number;
+declare function filterOutLargestObjects(snapshot: IHeapSnapshot, objectFilter: (node: IHeapNode) => boolean, listSize?: number): IHeapNode[];
+declare const _default: {
+    aggregateDominatorMetrics: typeof aggregateDominatorMetrics;
+    defaultAnalysisArgs: {
+        args: {
+            _: never[];
+        };
+    };
+    filterOutLargestObjects: typeof filterOutLargestObjects;
+    getObjectOutgoingEdgeCount: typeof getObjectOutgoingEdgeCount;
+    getSnapshotDirForAnalysis: typeof getSnapshotDirForAnalysis;
+    getSnapshotFileForAnalysis: typeof getSnapshotFileForAnalysis;
+    isNodeWorthInspecting: typeof isNodeWorthInspecting;
+    loadHeapSnapshot: typeof loadHeapSnapshot;
+    printNodeListInTerminal: typeof printNodeListInTerminal;
+    printReferencesInTerminal: typeof printReferencesInTerminal;
+    snapshotMapReduce: typeof snapshotMapReduce;
+};
+export default _default;
+//# sourceMappingURL=PluginUtils.d.ts.map

package/dist/PluginUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginUtils.d.ts","sourceRoot":"","sources":["../src/PluginUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,UAAU,CAAC;AACzC,OAAO,EACL,aAAa,EACb,SAAS,EACT,UAAU,EACV,SAAS,EACT,QAAQ,EAER,YAAY,EAEb,MAAM,cAAc,CAAC;AAKtB,oBAAY,mBAAmB,GAAG;IAChC,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB,CAAC;AAmBF,iBAAS,qBAAqB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAYvD;AAiDD,aAAK,eAAe,GAAG;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AACF,iBAAS,uBAAuB,CAC9B,QAAQ,EAAE,SAAS,EAAE,EACrB,OAAO,GAAE,UAAU,GAAG,eAAoB,GACzC,IAAI,CAgBN;AA4ED,iBAAS,yBAAyB,CAChC,QAAQ,EAAE,SAAS,EAAE,EACrB,OAAO,GAAE,UAAU,GAAG,eAAoB,GACzC,IAAI,CAON;AAED,iBAAS,0BAA0B,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAS3D;AAED,iBAAS,0BAA0B,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAWxE;AAED,iBAAS,yBAAyB,CAChC,OAAO,EAAE,mBAAmB,GAC3B,QAAQ,CAAC,MAAM,CAAC,CASlB;AAED,iBAAe,gBAAgB,CAC7B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAGxB;AAYD,iBAAe,iBAAiB,CAAC,EAAE,EAAE,EAAE,EACrC,WAAW,EAAE,CAAC,QAAQ,EAAE,aAAa,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,EAAE,EACrE,cAAc,EAAE,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EACrC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,EAAE,CAAC,CAqBb;AAED,iBAAS,yBAAyB,CAChC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,EAChB,QAAQ,EAAE,aAAa,EACvB,WAAW,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,EACzC,aAAa,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,GACzC,MAAM,CAWR;AAED,iBAAS,uBAAuB,CAC9B,QAAQ,EAAE,aAAa,EACvB,YAAY,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,EAC1C,QAAQ,SAAK,GACZ,SAAS,EAAE,CAoBb;;;;;;;;;;;;;;;;;;AAED,wBAYE"}

package/dist/PluginUtils.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@memlab/core");
+const chalk_1 = __importDefault(require("chalk"));
+const core_2 = require("@memlab/core");
+const nodeNameBlockList = new Set([
+    '(Startup object cache)',
+    '(Global handles)',
+    '(External strings)',
+    '(Builtins)',
+]);
+const nodeTypeBlockList = new Set([
+    'array',
+    'native',
+    'code',
+    'synthetic',
+    'hidden',
+]);
+const defaultAnalysisArgs = { args: { _: [] } };
+function isNodeWorthInspecting(node) {
+    // exclude meta objects like GC roots etc.
+    if (node.id <= 3) {
+        return false;
+    }
+    if (nodeTypeBlockList.has(node.type)) {
+        return false;
+    }
+    if (nodeNameBlockList.has(node.name)) {
+        return false;
+    }
+    return true;
+}
+// filter out dominators that have a similar size
+// for example if input is [A, B] and A is the dominator of B
+// then this function throw away A if the size of A is close to the size of B
+function filterOutDominators(nodeList) {
+    const candidateIdSet = new Set(nodeList.map(node => node.id));
+    const childrenSizeInList = new Map();
+    for (const node of nodeList) {
+        const visitedIds = new Set();
+        let curNode = node;
+        inner: while (!visitedIds.has(curNode.id)) {
+            curNode = node.dominatorNode;
+            if (!curNode || curNode.id === node.id) {
+                break inner;
+            }
+            // record the size of the children node in the candidate list
+            // and associate the children size with its dominator in the candidate list
+            if (candidateIdSet.has(curNode.id)) {
+                let childrenSize = node.retainedSize;
+                if (childrenSizeInList.has(curNode.id)) {
+                    childrenSize += childrenSizeInList.get(curNode.id)[1];
+                }
+                childrenSizeInList.set(curNode.id, [
+                    curNode.retainedSize,
+                    childrenSize,
+                ]);
+                break inner;
+            }
+            visitedIds.add(curNode.id);
+        }
+    }
+    // remove the dominator node from the candidate set
+    // if the dominator node's size is similar to the child node
+    for (const [dominatorId, [dominatorSize, childrenSize],] of childrenSizeInList) {
+        if (dominatorSize - childrenSize < 500000) {
+            candidateIdSet.delete(dominatorId);
+        }
+    }
+    return nodeList.filter(node => candidateIdSet.has(node.id));
+}
+function printNodeListInTerminal(nodeList, options = {}) {
+    const dot = chalk_1.default.grey('· ');
+    const indent = options.indent || '';
+    const printRef = !!options.printReferences;
+    if (!options.printAll) {
+        nodeList = filterOutDominators(nodeList);
+    }
+    for (const node of nodeList) {
+        const nodeInfo = getHeapObjectString(node);
+        core_2.info.topLevel(`${indent}${dot}${nodeInfo}`);
+        if (printRef) {
+            printReferencesInTerminal(node.references, { indent: indent + '  ' });
+        }
+    }
+}
+function isNumeric(v) {
+    if (typeof v === 'number') {
+        return true;
+    }
+    if (parseInt(v, 10) + '' === v + '') {
+        return true;
+    }
+    if (parseFloat(v) + '' === v + '') {
+        return true;
+    }
+    return false;
+}
+function getObjectReferenceNames(node) {
+    const referrers = node.referrers;
+    const names = new Set();
+    const visited = new Set();
+    for (const edge of referrers) {
+        const name = edge.name_or_index;
+        // in case infinite loop
+        if (visited.has(edge.edgeIndex)) {
+            continue;
+        }
+        visited.add(edge.edgeIndex);
+        // numeric index is not informative
+        if (isNumeric(name) || name === '') {
+            continue;
+        }
+        // context and previous references are not informative
+        if ((name === 'previous' || name === 'context') &&
+            edge.type === 'internal') {
+            for (const ref of edge.fromNode.referrers) {
+                referrers.push(ref);
+            }
+            continue;
+        }
+        names.add(name);
+    }
+    const refs = Array.from(names).slice(0, 10).join(chalk_1.default.grey(', '));
+    return 'refs: ' + chalk_1.default.grey('[') + refs + chalk_1.default.grey(']');
+}
+function getHeapObjectString(node) {
+    const colon = chalk_1.default.grey(':');
+    const comma = chalk_1.default.grey(',');
+    const serializeOpt = { color: true, compact: true };
+    const shapeStr = core_2.serializer.summarizeNodeShape(node, serializeOpt);
+    const edgeCount = getObjectOutgoingEdgeCount(node);
+    const fanout = `${edgeCount} edges`;
+    const bytes = core_2.utils.getReadableBytes(node.retainedSize);
+    const nodeId = chalk_1.default.grey(`@${node.id}`);
+    const type = node.type === 'object' ? '' : ` ${node.type}`;
+    const refs = getObjectReferenceNames(node);
+    return (`${nodeId}${type} ${shapeStr}${colon} ` +
+        `${fanout}${comma} ${bytes}${comma} ${refs}`);
+}
+function getReferenceString(edge) {
+    const edgeName = chalk_1.default.green(edge.name_or_index);
+    const objectInfo = getHeapObjectString(edge.toNode);
+    return ` --${edgeName}--> ${objectInfo}`;
+}
+function printReferencesInTerminal(edgeList, options = {}) {
+    const dot = chalk_1.default.grey('· ');
+    const indent = options.indent || '';
+    for (const edge of edgeList) {
+        const refStr = getReferenceString(edge);
+        core_2.info.topLevel(`${indent}${dot}${refStr}`);
+    }
+}
+function getObjectOutgoingEdgeCount(node) {
+    if (node.name === 'Set' || node.name === 'Map') {
+        const edge = core_2.utils.getEdgeByNameAndType(node, 'table');
+        if (!edge) {
+            return node.edge_count;
+        }
+        return edge.toNode.edge_count;
+    }
+    return node.edge_count;
+}
+function getSnapshotFileForAnalysis(options) {
+    const args = options.args;
+    if (args.snapshot) {
+        return args.snapshot;
+    }
+    if (core_1.config.externalSnapshotFilePaths.length > 0) {
+        return core_1.config.externalSnapshotFilePaths[core_1.config.externalSnapshotFilePaths.length - 1];
+    }
+    return core_2.utils.getSingleSnapshotFileForAnalysis();
+}
+function getSnapshotDirForAnalysis(options) {
+    const args = options.args;
+    if (args['snapshot-dir']) {
+        return args['snapshot-dir'];
+    }
+    if (core_1.config.externalSnapshotDir) {
+        return core_1.config.externalSnapshotDir;
+    }
+    return null;
+}
+function loadHeapSnapshot(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const file = getSnapshotFileForAnalysis(options);
+        return loadProcessedSnapshot({ file });
+    });
+}
+function loadProcessedSnapshot(options = {}) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const opt = { buildNodeIdIndex: true, verbose: true };
+        const file = options.file || core_2.utils.getSnapshotFilePathWithTabType(/.*/);
+        const snapshot = yield core_2.utils.getSnapshotFromFile(file, opt);
+        core_2.analysis.preparePathFinder(snapshot);
+        return snapshot;
+    });
+}
+function snapshotMapReduce(mapCallback, reduceCallback, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const snapshotDir = getSnapshotDirForAnalysis(options);
+        core_2.utils.checkSnapshots({ snapshotDir });
+        const snapshotFiles = snapshotDir
+            ? // load snapshots from a directory
+                core_2.utils.getSnapshotFilesInDir(snapshotDir)
+            : // load snapshots based on the visit sequence meta data
+                core_2.utils.getSnapshotFilesFromTabsOrder();
+        const intermediateResults = [];
+        for (let i = 0; i < snapshotFiles.length; ++i) {
+            const file = snapshotFiles[i];
+            // force GC before loading each snapshot
+            if (global.gc) {
+                global.gc();
+            }
+            const snapshot = yield loadProcessedSnapshot({ file });
+            intermediateResults.push(mapCallback(snapshot, i, file));
+        }
+        return reduceCallback(intermediateResults);
+    });
+}
+function aggregateDominatorMetrics(ids, snapshot, checkNodeCb, nodeMetricsCb) {
+    let ret = 0;
+    const dominators = core_2.utils.getConditionalDominatorIds(ids, snapshot, checkNodeCb);
+    core_2.utils.applyToNodes(dominators, snapshot, node => {
+        ret += nodeMetricsCb(node);
+    });
+    return ret;
+}
+function filterOutLargestObjects(snapshot, objectFilter, listSize = 50) {
+    let largeObjects = [];
+    snapshot.nodes.forEach(node => {
+        if (!objectFilter(node)) {
+            return;
+        }
+        const size = node.retainedSize;
+        let i;
+        for (i = largeObjects.length - 1; i >= 0; --i) {
+            if (largeObjects[i].retainedSize >= size) {
+                largeObjects.splice(i + 1, 0, node);
+                break;
+            }
+        }
+        if (i < 0) {
+            largeObjects.unshift(node);
+        }
+        largeObjects = largeObjects.slice(0, listSize);
+    });
+    return largeObjects;
+}
+exports.default = {
+    aggregateDominatorMetrics,
+    defaultAnalysisArgs,
+    filterOutLargestObjects,
+    getObjectOutgoingEdgeCount,
+    getSnapshotDirForAnalysis,
+    getSnapshotFileForAnalysis,
+    isNodeWorthInspecting,
+    loadHeapSnapshot,
+    printNodeListInTerminal,
+    printReferencesInTerminal,
+    snapshotMapReduce,
+};

package/dist/__tests__/HeapAnalysis.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+export {};
+//# sourceMappingURL=HeapAnalysis.test.d.ts.map

package/dist/__tests__/HeapAnalysis.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeapAnalysis.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/HeapAnalysis.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/HeapAnalysis.test.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@memlab/core");
+const HeapAnalysisLoader_1 = __importDefault(require("../HeapAnalysisLoader"));
+beforeEach(() => {
+    core_1.config.isTest = true;
+});
+test('Heap analysis modules can be loaded', () => __awaiter(void 0, void 0, void 0, function* () {
+    const heapAnalysisMap = HeapAnalysisLoader_1.default.loadAllAnalysis();
+    expect(heapAnalysisMap.size).toBeGreaterThan(0);
+}));

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+export { default as heapAnalysisLoader } from './HeapAnalysisLoader';
+export { default as BaseAnalysis } from './BaseAnalysis';
+export { default as DetachedDOMElementAnalysis } from './plugins/DetachedDOMElementAnalysis';
+export { default as GlobalVariableAnalysis } from './plugins/GlobalVariableAnalysis/GlobalVariableAnalysis';
+export { default as CollectionsHoldingStaleAnalysis } from './plugins/CollectionsHoldingStaleAnalysis';
+export { default as ObjectShallowAnalysis } from './plugins/ObjectShallowAnalysis';
+export { default as ObjectSizeAnalysis } from './plugins/ObjectSizeAnalysis';
+export { default as ShapeUnboundGrowthAnalysis } from './plugins/ShapeUnboundGrowthAnalysis';
+export { default as ObjectFanoutAnalysis } from './plugins/ObjectFanoutAnalysis';
+export { default as ObjectShapeAnalysis } from './plugins/ObjectShapeAnalysis';
+export { default as ObjectUnboundGrowthAnalysis } from './plugins/ObjectUnboundGrowthAnalysis';
+export { default as StringAnalysis } from './plugins/StringAnalysis';
+export { default as PluginUtils } from './PluginUtils';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,OAAO,IAAI,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAC,OAAO,IAAI,YAAY,EAAC,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAC,OAAO,IAAI,0BAA0B,EAAC,MAAM,sCAAsC,CAAC;AAC3F,OAAO,EAAC,OAAO,IAAI,sBAAsB,EAAC,MAAM,yDAAyD,CAAC;AAC1G,OAAO,EAAC,OAAO,IAAI,+BAA+B,EAAC,MAAM,2CAA2C,CAAC;AACrG,OAAO,EAAC,OAAO,IAAI,qBAAqB,EAAC,MAAM,iCAAiC,CAAC;AACjF,OAAO,EAAC,OAAO,IAAI,kBAAkB,EAAC,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EAAC,OAAO,IAAI,0BAA0B,EAAC,MAAM,sCAAsC,CAAC;AAC3F,OAAO,EAAC,OAAO,IAAI,oBAAoB,EAAC,MAAM,gCAAgC,CAAC;AAC/E,OAAO,EAAC,OAAO,IAAI,mBAAmB,EAAC,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAC,OAAO,IAAI,2BAA2B,EAAC,MAAM,uCAAuC,CAAC;AAC7F,OAAO,EAAC,OAAO,IAAI,cAAc,EAAC,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAC,OAAO,IAAI,WAAW,EAAC,MAAM,eAAe,CAAC"}