@memlab/core 1.0.0

package/dist/lib/FileManager.js

@@ -0,0 +1,309 @@
+"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 });
+exports.FileManager = void 0;
+const minimist_1 = __importDefault(require("minimist"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const Console_1 = __importDefault(require("./Console"));
+const Constant_1 = __importDefault(require("./Constant"));
+const Utils_1 = __importDefault(require("./Utils"));
+function joinAndProcessDir(options, ...args) {
+    const filepath = path_1.default.join(...args);
+    if (!fs_extra_1.default.existsSync(filepath)) {
+        try {
+            fs_extra_1.default.mkdirSync(filepath);
+        }
+        catch (ex) {
+            const err = Utils_1.default.getError(ex);
+            if (!err.message.includes('already exists')) {
+                Utils_1.default.haltOrThrow(err);
+            }
+        }
+    }
+    return filepath;
+}
+class FileManager {
+    getDefaultWorkDir() {
+        return path_1.default.join(this.getTmpDir(), 'memlab');
+    }
+    generateTmpHeapDir() {
+        const dirPath = path_1.default.join(this.getTmpDir(), Utils_1.default.getUniqueID());
+        fs_extra_1.default.mkdirSync(dirPath);
+        return dirPath;
+    }
+    getWorkDir(options = {}) {
+        // workDir options supercedes all the other options
+        if (options.workDir) {
+            return path_1.default.resolve(options.workDir);
+        }
+        // transcient options supercedes other the CLI options
+        if (options.transcient) {
+            const idx = ++FileManager.transcientInstanceIdx;
+            const instanceId = `${process.pid}-${Date.now()}-${idx}`;
+            const workDir = path_1.default.join(this.getTmpDir(), `memlab-${instanceId}`);
+            return path_1.default.resolve(workDir);
+        }
+        // workDir from the CLI options
+        const argv = (0, minimist_1.default)(process.argv.slice(2));
+        const workDir = argv['work-dir'] || this.getDefaultWorkDir();
+        return path_1.default.resolve(workDir);
+    }
+    getChromeBinaryZipFile() {
+        return path_1.default.join(this.getDefaultWorkDir(), 'chrome.tar.gz');
+    }
+    getChromeBinaryTimeStampFile() {
+        return path_1.default.join(this.getChromeBinaryDir(), 'memlab-success');
+    }
+    getChromeBinaryDir() {
+        return path_1.default.join(this.getDefaultWorkDir(), 'chrome');
+    }
+    clearUserDataDir(options) {
+        const userDataDir = this.getUserDataDir(options);
+        this.rmDir(userDataDir);
+    }
+    getDataBaseDir(options) {
+        return path_1.default.join(this.getWorkDir(options), 'data');
+    }
+    getCodeDataDir() {
+        return path_1.default.join(this.getCoreProjectBaseDir(), 'static');
+    }
+    getClusterSampleDataDir() {
+        return path_1.default.join(this.getCodeDataDir(), 'cluster');
+    }
+    getUserDataDir(options) {
+        return path_1.default.join(this.getDataBaseDir(options), 'profile');
+    }
+    getCurDataDir(options) {
+        return path_1.default.join(this.getDataBaseDir(options), 'cur');
+    }
+    getPersistDataDir(options) {
+        return path_1.default.join(this.getDataBaseDir(options), 'persist');
+    }
+    getLoggerOutDir(options = {}) {
+        return path_1.default.join(this.getDataBaseDir(options), 'logger');
+    }
+    // all trace clusters generated from the current run
+    getTraceClustersDir(options = {}) {
+        return path_1.default.join(this.getLoggerOutDir(options), 'trace-clusters');
+    }
+    // stores JSON file (with heap object and reference details for visualization)
+    // of all trace clusters (each cluster has a representative trace)
+    getTraceJSONDir(options = {}) {
+        return path_1.default.join(this.getLoggerOutDir(options), 'trace-jsons');
+    }
+    getUnclassifiedTraceClusterDir(options = {}) {
+        return path_1.default.join(this.getLoggerOutDir(options), 'unclassified-clusters');
+    }
+    getUniqueTraceClusterDir(options = {}) {
+        return path_1.default.join(this.getLoggerOutDir(options), 'unique-trace-clusters');
+    }
+    getNewUniqueTraceClusterDir(options = {}) {
+        return path_1.default.join(this.getUniqueTraceClusterDir(options), 'add');
+    }
+    getStaleUniqueTraceClusterDir(options = {}) {
+        return path_1.default.join(this.getUniqueTraceClusterDir(options), 'delete');
+    }
+    getAllClusterSummaryFile(options = {}) {
+        return path_1.default.join(this.getUniqueTraceClusterDir(options), 'unique-clusters-summary.txt');
+    }
+    getExistingUniqueTraceClusterDir(options = {}) {
+        return path_1.default.join(this.getUniqueTraceClusterDir(options), 'existing');
+    }
+    getAllFilesInDir(dir) {
+        const files = fs_extra_1.default.readdirSync(dir);
+        return files.map((file) => path_1.default.join(dir, file));
+    }
+    getDataOutDir(options = {}) {
+        return path_1.default.join(this.getDataBaseDir(options), 'out');
+    }
+    getCoreProjectBaseDir() {
+        return path_1.default.join(__dirname, '..', '..');
+    }
+    getReportOutDir(options = {}) {
+        return path_1.default.join(this.getPersistDataDir(options), 'reports');
+    }
+    getPreviewReportDir(options = {}) {
+        return path_1.default.join(this.getPersistDataDir(options), 'report-preview');
+    }
+    getLeakSummaryFile(options = {}) {
+        return path_1.default.join(this.getDataOutDir(options), 'leaks.txt');
+    }
+    getInputDataDir() {
+        return path_1.default.join(this.getDefaultWorkDir(), 'input');
+    }
+    getAllFilesInSubDirs(dir) {
+        let ret = [];
+        if (!fs_extra_1.default.existsSync(dir)) {
+            return ret;
+        }
+        const files = fs_extra_1.default.readdirSync(dir);
+        for (const file of files) {
+            const p = path_1.default.join(dir, file);
+            if (fs_extra_1.default.lstatSync(p).isDirectory()) {
+                ret = ret.concat(this.getAllFilesInSubDirs(p));
+            }
+            else {
+                ret.push(p);
+            }
+        }
+        return ret;
+    }
+    getTmpDir() {
+        return os_1.default.tmpdir();
+    }
+    rmDir(dir) {
+        if (fs_extra_1.default.existsSync(dir)) {
+            fs_extra_1.default.removeSync(dir);
+        }
+    }
+    getExperimentsDir() {
+        return path_1.default.join(this.getTmpDir(), 'memlab-experiments');
+    }
+    initExperimentDir(experimentId) {
+        const expsDir = joinAndProcessDir({}, this.getExperimentsDir());
+        const expDir = joinAndProcessDir({}, expsDir, `exp-${experimentId}`);
+        const controlWorkDir = joinAndProcessDir({}, expDir, 'control');
+        const testWorkDir = joinAndProcessDir({}, expDir, 'test');
+        return { controlWorkDir, testWorkDir };
+    }
+    getAndInitTSCompileIntermediateDir() {
+        const dir = path_1.default.join(this.getTmpDir(), 'memlab-code');
+        this.rmDir(dir);
+        fs_extra_1.default.mkdirSync(dir);
+        return dir;
+    }
+    clearDataDirs(options = {}) {
+        const curDataDir = this.getCurDataDir(options);
+        if (!fs_extra_1.default.existsSync(curDataDir)) {
+            return;
+        }
+        const dataSuffix = ['.heapsnapshot', '.json', '.png'];
+        const files = fs_extra_1.default.readdirSync(curDataDir);
+        for (const file of files) {
+            inner: for (const suffix of dataSuffix) {
+                if (file.endsWith(suffix)) {
+                    const filepath = path_1.default.join(curDataDir, file);
+                    fs_extra_1.default.unlinkSync(filepath);
+                    break inner;
+                }
+            }
+        }
+    }
+    emptyDirIfExists(dir) {
+        if (this.isDirectory(dir)) {
+            fs_extra_1.default.emptyDirSync(dir);
+        }
+    }
+    emptyTraceLogDataDir(options = {}) {
+        // all leak trace clusters
+        this.emptyDirIfExists(this.getTraceClustersDir(options));
+        // all JSON files for trace visualization
+        this.emptyDirIfExists(this.getTraceJSONDir(options));
+        // all unclassified clusters
+        this.emptyDirIfExists(this.getUnclassifiedTraceClusterDir(options));
+        // all unique cluster info
+        this.emptyDirIfExists(this.getUniqueTraceClusterDir(options));
+    }
+    resetBrowserDir() {
+        try {
+            const browserDir = this.getChromeBinaryDir();
+            const browserBinary = this.getChromeBinaryZipFile();
+            if (fs_extra_1.default.existsSync(browserBinary)) {
+                fs_extra_1.default.unlinkSync(browserBinary);
+            }
+            this.rmDir(browserDir);
+            joinAndProcessDir({}, browserDir);
+        }
+        catch (e) {
+            Console_1.default.error(Utils_1.default.getError(e).message);
+        }
+    }
+    isDirectory(file) {
+        const stats = fs_extra_1.default.statSync(file);
+        return stats.isDirectory();
+    }
+    iterateAllFiles(dir, callback) {
+        if (!this.isDirectory(dir)) {
+            callback(dir);
+            return;
+        }
+        const files = fs_extra_1.default.readdirSync(dir);
+        files.forEach((file) => {
+            const filepath = path_1.default.join(dir, file);
+            this.iterateAllFiles(filepath, callback);
+        });
+    }
+    rmWorkDir(options = {}) {
+        try {
+            this.rmDir(this.getWorkDir(options));
+        }
+        catch (e) {
+            Console_1.default.error(Utils_1.default.getError(e).message);
+        }
+    }
+    isWithinInternalDirectory(filePath) {
+        const sep = path_1.default.sep;
+        const internalDir = Constant_1.default.internalDir;
+        return filePath.includes(`${sep}${internalDir}${sep}`);
+    }
+    initDirs(config, options = {}) {
+        config.monoRepoDir = Constant_1.default.monoRepoDir;
+        // make sure getWorkDir is called first before
+        // any other get file or get dir calls
+        const workDir = this.getWorkDir(options);
+        joinAndProcessDir(options, workDir);
+        options = Object.assign(Object.assign({}, options), { workDir });
+        config.dataBaseDir = joinAndProcessDir(options, this.getDataBaseDir(options));
+        config.browserDir = joinAndProcessDir(options, this.getChromeBinaryDir());
+        config.userDataDir = joinAndProcessDir(options, this.getUserDataDir(options));
+        const outDir = joinAndProcessDir(options, this.getDataOutDir(options));
+        config.curDataDir = joinAndProcessDir(options, this.getCurDataDir(options));
+        config.dataBuilderDataDir = joinAndProcessDir(options, config.dataBaseDir, 'dataBuilder');
+        config.persistentDataDir = joinAndProcessDir(options, this.getPersistDataDir(options));
+        config.consoleLogFile = path_1.default.join(config.curDataDir, 'console-log.txt');
+        config.runMetaFile = path_1.default.join(config.curDataDir, 'run-meta.json');
+        config.snapshotSequenceFile = path_1.default.join(config.curDataDir, 'snap-seq.json');
+        config.browserInfoSummary = path_1.default.join(config.curDataDir, 'browser-info.txt');
+        config.exploreResultFile = this.getLeakSummaryFile(options);
+        config.singleReportSummary = path_1.default.join(outDir, 'report.txt');
+        config.unboundObjectCSV = path_1.default.join(outDir, 'unbound-object.csv');
+        config.inputDataDir = joinAndProcessDir(options, this.getInputDataDir());
+        config.reportOutDir = joinAndProcessDir(options, this.getReportOutDir(options));
+        config.previewReportDir = joinAndProcessDir(options, this.getPreviewReportDir(options));
+        config.viewJsonFile = path_1.default.join(config.reportOutDir, 'js', 'gc-path.js');
+        config.cookieSettingFile = path_1.default.join(config.persistentDataDir, 'cookie-setting.json');
+        config.traceClusterFile = path_1.default.join(config.persistentDataDir, 'trace-cluster.json');
+        const loggerOutDir = joinAndProcessDir(options, this.getLoggerOutDir(options));
+        // trace cluster meta info
+        config.traceClusterOutDir = joinAndProcessDir(options, this.getTraceClustersDir(options));
+        // detailed trace json files for visualization
+        config.traceJsonOutDir = joinAndProcessDir(options, this.getTraceJSONDir(options));
+        config.metricsOutDir = joinAndProcessDir(options, loggerOutDir, 'metrics');
+        config.reportScreenshotFile = path_1.default.join(outDir, 'report.png');
+        const codeDataDir = this.getCodeDataDir();
+        config.externalRunMetaFile = path_1.default.join(codeDataDir, 'run-meta.json');
+        config.externalSnapshotVisitOrderFile = path_1.default.join(codeDataDir, 'visit-order.json');
+        joinAndProcessDir(options, this.getUniqueTraceClusterDir(options));
+        config.newUniqueClusterDir = joinAndProcessDir(options, this.getNewUniqueTraceClusterDir(options));
+        config.staleUniqueClusterDir = joinAndProcessDir(options, this.getStaleUniqueTraceClusterDir(options));
+        config.currentUniqueClusterDir = joinAndProcessDir(options, this.getExistingUniqueTraceClusterDir(options));
+        config.unclassifiedClusterDir = joinAndProcessDir(options, this.getUnclassifiedTraceClusterDir(options));
+        config.allClusterSummaryFile = this.getAllClusterSummaryFile(options);
+    }
+}
+exports.FileManager = FileManager;
+FileManager.transcientInstanceIdx = 0;
+exports.default = new FileManager();

package/dist/lib/HeapAnalyzer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 { E2EStepInfo, HeapNodeIdSet, IHeapNode, IHeapSnapshot, IMemoryAnalystOptions, IMemoryAnalystSnapshotDiff, LeakTracePathItem, Optional, IOveralLeakInfo, TraceCluster } from './Types';
+import TraceFinder from '../paths/TraceFinder';
+declare class MemoryAnalyst {
+    checkLeak(): Promise<void>;
+    checkUnbound(options?: IMemoryAnalystOptions): Promise<void>;
+    breakDownMemoryByShapes(options?: {
+        file?: string;
+    }): Promise<void>;
+    detectUnboundGrowth(options?: IMemoryAnalystOptions): Promise<void>;
+    detectMemoryLeaks(): Promise<void>;
+    visualizeMemoryUsage(options?: IMemoryAnalystOptions): void;
+    focus(options?: {
+        file?: string;
+    }): Promise<void>;
+    shouldLoadCompleteSnapshot(tabsOrder: E2EStepInfo[], tab: E2EStepInfo): boolean;
+    diffSnapshots(loadAll?: boolean): Promise<IMemoryAnalystSnapshotDiff>;
+    private calculateRetainedSizes;
+    preparePathFinder(snapshot: IHeapSnapshot): TraceFinder;
+    private dumpPageInteractionSummary;
+    private dumpLeakSummaryToConsole;
+    private checkDetachedFiberNode;
+    private isTrivialNode;
+    private filterLeakedObjects;
+    aggregateDominatorMetrics(ids: HeapNodeIdSet, snapshot: IHeapSnapshot, checkNodeCb: (node: IHeapNode) => boolean, nodeMetricsCb: (node: IHeapNode) => number): number;
+    private getOverallHeapInfo;
+    getRetainedSize(node: IHeapNode): number;
+    getOverallLeakInfo(leakedNodeIds: HeapNodeIdSet, snapshot: IHeapSnapshot): Optional<IOveralLeakInfo>;
+    private printHeapInfo;
+    private breakDownSnapshotByShapes;
+    private isTrivialEdgeForBreakDown;
+    private breakDownByReferrers;
+    searchLeakedTraces(leakedNodeIds: HeapNodeIdSet, snapshot: IHeapSnapshot): Promise<{
+        paths: LeakTracePathItem[];
+    }>;
+    serializeClusterUpdate(clusters: TraceCluster[], options?: {
+        reclusterOnly?: boolean;
+    }): Promise<void>;
+    dumpPathByNodeId(leakedIdSet: HeapNodeIdSet, snapshot: IHeapSnapshot, nodeIdsInSnapshots: Array<HeapNodeIdSet>, id: number, pathLoaderFile: string, summaryFile: string): void;
+}
+declare const _default: MemoryAnalyst;
+export default _default;
+//# sourceMappingURL=HeapAnalyzer.d.ts.map

package/dist/lib/HeapAnalyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeapAnalyzer.d.ts","sourceRoot":"","sources":["../../src/lib/HeapAnalyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EAEb,SAAS,EACT,aAAa,EAGb,qBAAqB,EACrB,0BAA0B,EAE1B,iBAAiB,EAEjB,QAAQ,EACR,eAAe,EACf,YAAY,EACb,MAAM,SAAS,CAAC;AAOjB,OAAO,WAAW,MAAM,sBAAsB,CAAC;AAO/C,cAAM,aAAa;IACX,SAAS;IAMT,YAAY,CAAC,OAAO,GAAE,qBAA0B;IAMhD,uBAAuB,CAAC,OAAO,GAAE;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAM;IAgBrD,mBAAmB,CAAC,OAAO,GAAE,qBAA0B;IA8IvD,iBAAiB;IAgBvB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B;IAqDlD,KAAK,CAAC,OAAO,GAAE;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAM;IA0BzC,0BAA0B,CACxB,SAAS,EAAE,WAAW,EAAE,EACxB,GAAG,EAAE,WAAW,GACf,OAAO;IAUJ,aAAa,CAAC,OAAO,UAAQ,GAAG,OAAO,CAAC,0BAA0B,CAAC;IA8FzE,OAAO,CAAC,sBAAsB;IAO9B,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,WAAW;IAavD,OAAO,CAAC,0BAA0B;IAOlC,OAAO,CAAC,wBAAwB;IA6ChC,OAAO,CAAC,sBAAsB;IAW9B,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,mBAAmB;IA8C3B,yBAAyB,CACvB,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,aAAa,EACvB,WAAW,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,EACzC,aAAa,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM;IAc5C,OAAO,CAAC,kBAAkB;IA4C1B,eAAe,CAAC,IAAI,EAAE,SAAS;IAI/B,kBAAkB,CAChB,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,aAAa,GACtB,QAAQ,CAAC,eAAe,CAAC;IA4B5B,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,yBAAyB;IAoEjC,OAAO,CAAC,yBAAyB;IAWjC,OAAO,CAAC,oBAAoB;IAoDtB,kBAAkB,CACtB,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,aAAa;;;IA4FnB,sBAAsB,CAC1B,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,GAAE;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAM;IAqBzC,gBAAgB,CACd,WAAW,EAAE,aAAa,EAC1B,QAAQ,EAAE,aAAa,EACvB,kBAAkB,EAAE,KAAK,CAAC,aAAa,CAAC,EACxC,EAAE,EAAE,MAAM,EACV,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM;CAsCtB;;AAED,wBAAmC"}