@memlab/cli 1.0.1 → 1.0.4

package/README.md

@@ -1,6 +1,6 @@
 ## memlab CLI
 
-This is the memlab CLI library. It contains all memlab commands, command-line options, and command-line interfaces. 
+This is the memlab CLI library. It contains all memlab commands, command-line options, and command-line interfaces.
 The library supports adding new commands.
 
 ## Full documentation

package/dist/BaseCommand.d.ts

@@ -30,6 +30,7 @@ export default class BaseCommand extends Command {
     getPrerequisites(): BaseCommand[];
     isInternalCommand(): boolean;
     getOptions(): BaseOption[];
+    getExcludedOptions(): BaseOption[];
     getSubCommands(): BaseCommand[];
     run(_options: CLIOptions): Promise<void>;
 }

package/dist/BaseCommand.js

@@ -55,21 +55,23 @@ class Command {
         const uniqueOptions = new Map();
         const visitedCommands = new Set();
         const queue = [self];
+        const excludedOptions = new Set(self.getExcludedOptions().map(option => option.getOptionName()));
         while (queue.length > 0) {
             const cur = queue.shift();
-            if (cur) {
-                const options = cur.getOptions();
-                for (const option of options) {
-                    const optionName = option.getOptionName();
-                    if (!uniqueOptions.has(optionName)) {
-                        uniqueOptions.set(optionName, option);
-                    }
+            const options = cur.getOptions();
+            for (const option of options) {
+                const optionName = option.getOptionName();
+                if (excludedOptions.has(optionName)) {
+                    continue;
                 }
-                visitedCommands.add(cur.getCommandName());
-                for (const prereq of cur.getPrerequisites()) {
-                    if (!visitedCommands.has(prereq.getCommandName())) {
-                        queue.push(prereq);
-                    }
+                if (!uniqueOptions.has(optionName)) {
+                    uniqueOptions.set(optionName, option);
+                }
+            }
+            visitedCommands.add(cur.getCommandName());
+            for (const prereq of cur.getPrerequisites()) {
+                if (!visitedCommands.has(prereq.getCommandName())) {
+                    queue.push(prereq);
                 }
             }
         }
@@ -112,6 +114,13 @@ class BaseCommand extends Command {
     getOptions() {
         return [];
     }
+    // commands from getPrerequisites may propagate
+    // options that does not make sense for the
+    // current command, this returns the list of
+    // options that should be excluded from helper text
+    getExcludedOptions() {
+        return [];
+    }
     // get subcommands of this command
     // for example command 'A' has two sub-commands 'B' and 'C'
     // CLI supports running in terminal: `memlab A B` or `memlab A C`

package/dist/CommandLoader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 BaseCommand from './BaseCommand';
+export default class CommandLoader {
+    private isLoaded;
+    private OSSModules;
+    private modules;
+    private modulePaths;
+    getModules(): Map<string, BaseCommand>;
+    getModulePaths(): Map<string, string>;
+    registerCommands(): void;
+    private registerCommandsFromDir;
+    private postRegistration;
+}
+//# sourceMappingURL=CommandLoader.d.ts.map

package/dist/CommandLoader.js

@@ -0,0 +1,95 @@
+"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");
+const BaseCommand_1 = __importDefault(require("./BaseCommand"));
+const GenerateCLIDocCommand_1 = __importDefault(require("./commands/helper/GenerateCLIDocCommand"));
+class CommandLoader {
+    constructor() {
+        this.isLoaded = false;
+        this.OSSModules = new Map();
+        this.modules = new Map();
+        this.modulePaths = new Map();
+    }
+    getModules() {
+        if (!this.isLoaded) {
+            this.registerCommands();
+        }
+        return this.modules;
+    }
+    getModulePaths() {
+        if (!this.isLoaded) {
+            this.registerCommands();
+        }
+        return this.modulePaths;
+    }
+    registerCommands() {
+        const modulesDir = path_1.default.resolve(__dirname, 'commands');
+        this.registerCommandsFromDir(modulesDir);
+        this.postRegistration();
+    }
+    registerCommandsFromDir(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.registerCommandsFromDir(modulePath);
+                continue;
+            }
+            // only import modules files ends with with Command.js
+            if (!moduleFile.endsWith('Command.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();
+            if (!(moduleInstance instanceof BaseCommand_1.default)) {
+                core_1.utils.haltOrThrow('loading a command that does not extend BaseCommand');
+            }
+            const commandName = moduleInstance.getCommandName();
+            const loadingOssCommand = !core_1.fileManager.isWithinInternalDirectory(modulePath);
+            // reigster OSS commands
+            if (loadingOssCommand) {
+                this.OSSModules.set(commandName, moduleInstance);
+            }
+            // register all commands
+            if (this.modules.has(commandName)) {
+                // resolve conflict
+                const ossCommandLoaded = !core_1.fileManager.isWithinInternalDirectory(this.modulePaths.get(commandName));
+                if (ossCommandLoaded === loadingOssCommand) {
+                    // when both commands are open source or neither are open source
+                    core_1.info.midLevel(`MemLab command ${commandName} is already registered`);
+                }
+                else if (!ossCommandLoaded && loadingOssCommand) {
+                    // when open source command tries to overwrite non-open source command
+                    continue;
+                }
+            }
+            this.modules.set(commandName, moduleInstance);
+            this.modulePaths.set(commandName, modulePath);
+        }
+    }
+    postRegistration() {
+        const cliDocCommand = new GenerateCLIDocCommand_1.default();
+        const instance = this.modules.get(cliDocCommand.getCommandName());
+        if (instance) {
+            instance.setModulesMap(this.OSSModules);
+        }
+    }
+}
+exports.default = CommandLoader;

package/dist/Dispatcher.d.ts

@@ -8,7 +8,7 @@
  * @format
  */
 import type { ParsedArgs } from 'minimist';
-import { MemLabConfig, AnyRecord } from '@memlab/core';
+import type { AnyRecord, MemLabConfig } from '@memlab/core';
 import BaseCommand from './BaseCommand';
 declare type RunCommandOptions = {
     isPrerequisite?: boolean;
@@ -17,7 +17,6 @@ declare type RunCommandOptions = {
 };
 declare class CommandDispatcher {
     private modules;
-    private modulePaths;
     private executedCommands;
     private executingCommandStack;
     constructor();
@@ -26,9 +25,6 @@ declare class CommandDispatcher {
     private runCommand;
     runSubCommandIfAny(command: BaseCommand, args: ParsedArgs, runCmdOpt: RunCommandOptions): Promise<void>;
     private helper;
-    private registerBuiltInCommands;
-    private registerCommands;
-    private registerCommandsFromDir;
 }
 declare const _default: CommandDispatcher;
 export default _default;

package/dist/Dispatcher.js

@@ -22,40 +22,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@memlab/core");
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-const core_2 = require("@memlab/core");
-const BaseCommand_1 = __importDefault(require("./BaseCommand"));
 const HelperCommand_1 = __importDefault(require("./commands/helper/HelperCommand"));
-const VerboseOption_1 = __importDefault(require("./options/VerboseOption"));
-const SetContinuousTestOption_1 = __importDefault(require("./options/SetContinuousTestOption"));
-const DebugOption_1 = __importDefault(require("./options/DebugOption"));
-const SilentOption_1 = __importDefault(require("./options/SilentOption"));
-const HelperOption_1 = __importDefault(require("./options/HelperOption"));
-const universalOptions = [
-    new HelperOption_1.default(),
-    new VerboseOption_1.default(),
-    new SetContinuousTestOption_1.default(),
-    new DebugOption_1.default(),
-    new SilentOption_1.default(),
-];
+const UniversalOptions_1 = __importDefault(require("./options/lib/UniversalOptions"));
+const CommandLoader_1 = __importDefault(require("./CommandLoader"));
 const helperCommand = new HelperCommand_1.default();
-helperCommand.setUniversalOptions(universalOptions);
 class CommandDispatcher {
     constructor() {
         this.executedCommands = new Set();
         this.executingCommandStack = [];
         // auto load all command modules
-        this.modules = new Map();
-        this.modulePaths = new Map();
-        this.registerBuiltInCommands();
-        this.registerCommands();
+        const commandLoader = new CommandLoader_1.default();
+        this.modules = commandLoader.getModules();
     }
     dispatch(args) {
         return __awaiter(this, void 0, void 0, function* () {
             // triggered by `memlab` (without specific command)
             if (!args._ || !(args._.length >= 1)) {
-                core_2.info.error('\n  command argument missing');
+                core_1.info.error('\n  command argument missing');
                 yield this.helper(args);
                 return;
             }
@@ -83,7 +66,7 @@ class CommandDispatcher {
     }
     parseOptions(command, config, args) {
         return __awaiter(this, void 0, void 0, function* () {
-            const options = [...universalOptions, ...command.getOptions()];
+            const options = [...UniversalOptions_1.default, ...command.getOptions()];
             const configFromOptions = Object.create(null);
             for (const option of options) {
                 const ret = yield option.run(config, args);
@@ -113,7 +96,7 @@ class CommandDispatcher {
                 yield this.runCommand(prereq, args, Object.assign({ isPrerequisite: true }, runCmdOpt));
             }
             // parse command line options
-            const c = yield this.parseOptions(command, core_2.config, args);
+            const c = yield this.parseOptions(command, core_1.config, args);
             Object.assign(runCmdOpt.configFromOptions, c);
             const { configFromOptions } = runCmdOpt;
             // execute command
@@ -142,7 +125,7 @@ class CommandDispatcher {
                     return;
                 }
             }
-            core_2.info.error(`Invalid sub-command \`${args._[subCommandIndex]}\` of \`${command.getCommandName()}\`\n`);
+            core_1.info.error(`Invalid sub-command \`${args._[subCommandIndex]}\` of \`${command.getCommandName()}\`\n`);
             yield this.helper(args, command);
         });
     }
@@ -156,50 +139,5 @@ class CommandDispatcher {
             });
         });
     }
-    registerBuiltInCommands() {
-        // TBA
-    }
-    registerCommands() {
-        const modulesDir = path_1.default.resolve(__dirname, 'commands');
-        this.registerCommandsFromDir(modulesDir);
-    }
-    registerCommandsFromDir(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.registerCommandsFromDir(modulePath);
-                continue;
-            }
-            // only import modules files ends with with Command.js
-            if (!moduleFile.endsWith('Command.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();
-            if (!(moduleInstance instanceof BaseCommand_1.default)) {
-                core_1.utils.haltOrThrow('loading a command that does not extend BaseCommand');
-            }
-            const commandName = moduleInstance.getCommandName();
-            if (this.modules.has(commandName)) {
-                // resolve conflict
-                const ossCommandLoaded = !core_2.fileManager.isWithinInternalDirectory(this.modulePaths.get(commandName));
-                const loadingOssCommand = !core_2.fileManager.isWithinInternalDirectory(modulePath);
-                if (ossCommandLoaded === loadingOssCommand) {
-                    // when both commands are open source or neither are open source
-                    core_2.info.midLevel(`MemLab command ${commandName} is already registered`);
-                }
-                else if (!ossCommandLoaded && loadingOssCommand) {
-                    // when open source command tries to overwrite non-open source command
-                    continue;
-                }
-            }
-            this.modules.set(commandName, moduleInstance);
-            this.modulePaths.set(commandName, modulePath);
-        }
-    }
 }
 exports.default = new CommandDispatcher();

package/dist/commands/MemLabRunCommand.d.ts

@@ -8,13 +8,15 @@
  * @format
  */
 import type { BaseOption, CLIOptions } from '@memlab/core';
-import BaseCommand from '../BaseCommand';
+import BaseCommand, { CommandCategory } from '../BaseCommand';
 export default class MemLabRunCommand extends BaseCommand {
     getCommandName(): string;
     getDescription(): string;
     getExamples(): string[];
     getPrerequisites(): BaseCommand[];
     getOptions(): BaseOption[];
+    getExcludedOptions(): BaseOption[];
+    getCategory(): CommandCategory;
     run(options: CLIOptions): Promise<void>;
 }
 //# sourceMappingURL=MemLabRunCommand.d.ts.map

package/dist/commands/MemLabRunCommand.js

@@ -8,6 +8,29 @@
  * @emails oncall+ws_labs
  * @format
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 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) {
@@ -24,11 +47,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const core_1 = require("@memlab/core");
-const BaseCommand_1 = __importDefault(require("../BaseCommand"));
+const BaseCommand_1 = __importStar(require("../BaseCommand"));
 const CheckLeakCommand_1 = __importDefault(require("./heap/CheckLeakCommand"));
 const InitDirectoryCommand_1 = __importDefault(require("./InitDirectoryCommand"));
 const TakeSnapshotCommand_1 = __importDefault(require("./snapshot/TakeSnapshotCommand"));
 const SetWorkingDirectoryOption_1 = __importDefault(require("../options/SetWorkingDirectoryOption"));
+const AppOption_1 = __importDefault(require("../options/AppOption"));
+const InteractionOption_1 = __importDefault(require("../options/InteractionOption"));
+const SkipSnapshotOption_1 = __importDefault(require("../options/SkipSnapshotOption"));
+const RunningModeOption_1 = __importDefault(require("../options/RunningModeOption"));
+const BaselineFileOption_1 = __importDefault(require("../options/heap/BaselineFileOption"));
+const TargetFileOption_1 = __importDefault(require("../options/heap/TargetFileOption"));
+const FinalFileOption_1 = __importDefault(require("../options/heap/FinalFileOption"));
+const SnapshotDirectoryOption_1 = __importDefault(require("../options/heap/SnapshotDirectoryOption"));
+const JSEngineOption_1 = __importDefault(require("../options/heap/JSEngineOption"));
 class MemLabRunCommand extends BaseCommand_1.default {
     getCommandName() {
         return 'run';
@@ -37,7 +69,11 @@ class MemLabRunCommand extends BaseCommand_1.default {
         return 'find memory leaks in web apps';
     }
     getExamples() {
-        return ['--app=comet --interaction=watch'];
+        return [
+            '--scenario <TEST_SCENARIO_FILE>',
+            '--scenario /tmp/test-scenario.js',
+            '--scenario /tmp/test-scenario.js --work-dir /tmp/test-1/',
+        ];
     }
     getPrerequisites() {
         return [
@@ -49,6 +85,22 @@ class MemLabRunCommand extends BaseCommand_1.default {
     getOptions() {
         return [new SetWorkingDirectoryOption_1.default()];
     }
+    getExcludedOptions() {
+        return [
+            new AppOption_1.default(),
+            new InteractionOption_1.default(),
+            new SkipSnapshotOption_1.default(),
+            new RunningModeOption_1.default(),
+            new BaselineFileOption_1.default(),
+            new TargetFileOption_1.default(),
+            new FinalFileOption_1.default(),
+            new SnapshotDirectoryOption_1.default(),
+            new JSEngineOption_1.default(),
+        ];
+    }
+    getCategory() {
+        return BaseCommand_1.CommandCategory.COMMON;
+    }
     run(options) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {

package/dist/commands/PrintSummaryCommand.js

@@ -45,7 +45,7 @@ class PrintSummaryCommand extends BaseCommand_1.default {
             const workDir = (_a = options.configFromOptions) === null || _a === void 0 ? void 0 : _a.workDir;
             const summaryFile = core_2.fileManager.getLeakSummaryFile({ workDir });
             if (!fs_extra_1.default.existsSync(summaryFile)) {
-                core_1.utils.haltOrThrow('No MemLab leak summary found. Please make sure "memlab explore" runs successfully first.');
+                core_1.utils.haltOrThrow('No MemLab leak summary found. Please make sure "memlab find-leaks" runs successfully first.');
             }
             const content = fs_extra_1.default.readFileSync(summaryFile, 'UTF-8');
             core_2.info.topLevel(content);

package/dist/commands/RunMeasureCommand.d.ts

@@ -14,6 +14,7 @@ export default class RunMeasureCommand extends BaseCommand {
     getCommandName(): string;
     getDescription(): string;
     getPrerequisites(): BaseCommand[];
+    getExamples(): string[];
     getOptions(): BaseOption[];
     run(options: CLIOptions): Promise<void>;
 }

package/dist/commands/RunMeasureCommand.js

@@ -50,6 +50,13 @@ class RunMeasureCommand extends BaseCommand_1.default {
     getPrerequisites() {
         return [new CleanRunDataCommand_1.default(), new InitDirectoryCommand_1.default()];
     }
+    getExamples() {
+        return [
+            '--scenario <TEST_SCENARIO_FILE>',
+            '--scenario /tmp/test-scenario.js',
+            '--scenario /tmp/test-scenario.js --work-dir /tmp/test-1/',
+        ];
+    }
     getOptions() {
         return [
             new NumberOfRunsOption_1.default(),

package/dist/commands/WarmupAppCommand.d.ts

@@ -14,6 +14,7 @@ export default class FBWarmupAppCommand extends BaseCommand {
     getCommandName(): string;
     getDescription(): string;
     getPrerequisites(): BaseCommand[];
+    getExamples(): string[];
     getOptions(): BaseOption[];
     run(_options: CLIOptions): Promise<void>;
 }

package/dist/commands/WarmupAppCommand.js

@@ -43,6 +43,12 @@ class FBWarmupAppCommand extends BaseCommand_1.default {
     getPrerequisites() {
         return [new InitDirectoryCommand_1.default(), new CheckXvfbSupportCommand_1.default()];
     }
+    getExamples() {
+        return [
+            '--scenario <TEST_SCENARIO_FILE>',
+            '--scenario /tmp/test-scenario.js',
+        ];
+    }
     getOptions() {
         return [
             new AppOption_1.default(),

package/dist/commands/heap/CheckLeakCommand.js

@@ -57,9 +57,10 @@ const TraceAllObjectsOption_1 = __importDefault(require("../../options/heap/Trac
 const LogTraceAsClusterOption_1 = __importDefault(require("../../options/heap/LogTraceAsClusterOption"));
 const CleanLoggerDataCommand_1 = __importDefault(require("../CleanLoggerDataCommand"));
 const LeakFilterFileOption_1 = __importDefault(require("../../options/heap/leak-filter/LeakFilterFileOption"));
+const LeakClusterSizeThresholdOption_1 = __importDefault(require("../../options/heap/LeakClusterSizeThresholdOption"));
 class CheckLeakCommand extends BaseCommand_1.default {
     getCommandName() {
-        return 'explore';
+        return 'find-leaks';
     }
     getDescription() {
         return 'find memory leaks in heap snapshots';
@@ -79,6 +80,7 @@ class CheckLeakCommand extends BaseCommand_1.default {
             new JSEngineOption_1.default(),
             new LeakFilterFileOption_1.default(),
             new OversizeThresholdOption_1.default(),
+            new LeakClusterSizeThresholdOption_1.default(),
             new TraceAllObjectsOption_1.default(),
             new LogTraceAsClusterOption_1.default(),
         ];

package/dist/commands/heap/GetRetainerTraceCommand.js

@@ -60,7 +60,7 @@ function calculateRetainerTrace() {
 }
 class GetRetainerTraceCommand extends BaseCommand_1.default {
     getCommandName() {
-        return 'report';
+        return 'trace';
     }
     getDescription() {
         return 'report retainer trace of a specific node, use with --nodeId';
@@ -69,7 +69,11 @@ class GetRetainerTraceCommand extends BaseCommand_1.default {
         return BaseCommand_1.CommandCategory.COMMON;
     }
     getExamples() {
-        return ['--nodeId=@3123123'];
+        return [
+            '--node-id=<HEAP_OBJECT_ID>',
+            '--node-id=@3123123',
+            '--node-id=128127',
+        ];
     }
     getOptions() {
         return [

package/dist/commands/helper/GenerateCLIDocCommand.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 { CLIOptions } from '@memlab/core';
+import BaseCommand from '../../BaseCommand';
+export default class GenerateCLIDocCommand extends BaseCommand {
+    private modules;
+    private generatedCommandInIndex;
+    private universalOptions;
+    getCommandName(): string;
+    getDescription(): string;
+    isInternalCommand(): boolean;
+    setModulesMap(modules: Map<string, BaseCommand>): void;
+    run(options: CLIOptions): Promise<void>;
+    private generateDocs;
+    private writeCommandCategories;
+    private writeCategory;
+    private writeCategoryHeader;
+    private writeCommand;
+    private writeTextWithNewLine;
+    private touchFile;
+    private writeCodeBlock;
+    private writeCommandOptions;
+}
+//# sourceMappingURL=GenerateCLIDocCommand.d.ts.map