nativescript 8.7.0-rc.0 → 8.7.0-rc.2

package/lib/common/mobile/mobile-core/devices-service.js

@@ -72,6 +72,7 @@ class DevicesService extends events_1.EventEmitter {
                 const device = yield this.getDevice(options.deviceId);
                 return device;
             }
+            // Now let's take data for each device:
             const availableDevicesAndEmulators = this.getDeviceInstances().filter((d) => d.deviceInfo.status === constants_2.CONNECTED_STATUS &&
                 (!this.platform ||
                     d.deviceInfo.platform.toLowerCase() === this.platform.toLowerCase()));
@@ -94,6 +95,8 @@ class DevicesService extends events_1.EventEmitter {
                     const devices = sortedInstances.filter((d) => !d.isEmulator);
                     let selectedInstance;
                     if (options.onlyEmulators || options.onlyDevices) {
+                        // When --emulator or --forDevice is passed, the instances are already filtered
+                        // So we are sure we have exactly the type we need and we can safely return the last one (highest OS version).
                         selectedInstance = _.last(sortedInstances);
                     }
                     else {
@@ -156,6 +159,7 @@ class DevicesService extends events_1.EventEmitter {
                     ...additionalErrors,
                 ];
             }
+            // emulator is already running
             if (emulator.status === constants.RUNNING_EMULATOR_STATUS) {
                 return null;
             }
@@ -188,9 +192,11 @@ class DevicesService extends events_1.EventEmitter {
         return !!(this.$mobileHelper.isiOSPlatform(device.deviceInfo.platform) &&
             device.isEmulator);
     }
+    /* tslint:disable:no-unused-variable */
     setLogLevel(logLevel, deviceIdentifier) {
         this.$deviceLogProvider.setLogLevel(logLevel, deviceIdentifier);
     }
+    /* tslint:enable:no-unused-variable */
     isAppInstalledOnDevices(deviceIdentifiers, appId, projectName, projectDir) {
         this.$logger.trace(`Called isInstalledOnDevices for identifiers ${deviceIdentifiers}. AppIdentifier is ${appId}.`);
         return _.map(deviceIdentifiers, (deviceIdentifier) => this.isApplicationInstalledOnDevice(deviceIdentifier, {
@@ -264,6 +270,9 @@ class DevicesService extends events_1.EventEmitter {
         delete this._availableEmulators[emulator.imageIdentifier];
         this.emit(constants.EmulatorDiscoveryNames.EMULATOR_IMAGE_LOST, emulator);
     }
+    /**
+     * Starts looking for devices. Any found devices are pushed to "_devices" variable.
+     */
     detectCurrentlyAttachedDevices(deviceInitOpts) {
         return __awaiter(this, void 0, void 0, function* () {
             const options = this.getDeviceLookingOptions(deviceInitOpts);
@@ -336,9 +345,14 @@ class DevicesService extends events_1.EventEmitter {
             clearInterval(this.emulatorDetectionInterval);
         }
     }
+    /**
+     * Returns device that matches an identifier.
+     * The identifier is expected to be the same as the running device declares it (emulator-5554 for android or GUID for ios).
+     * @param identifier running emulator or device identifier
+     */
     getDeviceByIdentifier(identifier) {
         const searchedDevice = _.find(this.getDeviceInstances(), (device) => {
-            if (this.$mobileHelper.isApplePlatfrom(device.deviceInfo.platform) &&
+            if (this.$mobileHelper.isApplePlatform(device.deviceInfo.platform) &&
                 device.isEmulator) {
                 return (device.deviceInfo.identifier === identifier ||
                     device.deviceInfo.displayName === identifier);
@@ -351,6 +365,9 @@ class DevicesService extends events_1.EventEmitter {
         }
         return searchedDevice;
     }
+    /**
+     * Starts looking for running devices. All found devices are pushed to _devices variable.
+     */
     startLookingForDevices(deviceInitOpts) {
         return __awaiter(this, void 0, void 0, function* () {
             this.$logger.trace("startLookingForDevices; platform is %s", this._platform);
@@ -362,10 +379,20 @@ class DevicesService extends events_1.EventEmitter {
             yield this.startDeviceDetectionInterval(deviceInitOpts);
         });
     }
+    /**
+     * Returns device depending on the passed index.
+     * The index refers to assigned number to listed devices by tns device command.
+     * @param index assigned device number
+     */
     getDeviceByIndex(index) {
         this.validateIndex(index - 1);
         return this.getDeviceInstances()[index - 1];
     }
+    /**
+     * Returns running device for specified --device <DeviceId>.
+     * Method expects running devices.
+     * @param deviceOption parameter passed by the user to --device flag. Can be name, identifier or imageIdentifier.
+     */
     getDevice(deviceOption) {
         return __awaiter(this, void 0, void 0, function* () {
             let device = null;
@@ -387,6 +414,11 @@ class DevicesService extends events_1.EventEmitter {
             return device;
         });
     }
+    /**
+     * Method runs action for a --device (value), specified by the user.
+     * @param action action to be executed if canExecute returns true
+     * @param canExecute predicate to decide whether the command can be ran
+     */
     executeOnDevice(action, canExecute) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!canExecute || canExecute(this._device)) {
@@ -397,6 +429,11 @@ class DevicesService extends events_1.EventEmitter {
             }
         });
     }
+    /**
+     * Executes passed action for each found device.
+     * @param action action to be executed if canExecute returns true
+     * @param canExecute predicate to decide whether the command can be ran
+     */
     executeOnAllConnectedDevices(action, canExecute) {
         return __awaiter(this, void 0, void 0, function* () {
             const devices = this.filterDevicesByPlatform();
@@ -450,6 +487,12 @@ class DevicesService extends events_1.EventEmitter {
             });
         }));
     }
+    /**
+     * Runs the passed action if the predicate "canExecute" returns true
+     * @param action action to be executed if canExecute returns true.
+     * @param canExecute predicate to decide whether the command can be ran
+     * @param options all possible options that can be passed to the command.
+     */
     execute(action, canExecute, options) {
         return __awaiter(this, void 0, void 0, function* () {
             assert.ok(this._isInitialized, "Devices services not initialized!");
@@ -459,6 +502,7 @@ class DevicesService extends events_1.EventEmitter {
                     this.$mobileHelper.isiOSPlatform(this._platform) &&
                     this.$options.emulator &&
                     !this.isOnlyiOSSimultorRunning()) {
+                    // Executes the command only on iOS simulator
                     const originalCanExecute = canExecute;
                     canExecute = (dev) => this.isiOSSimulator(dev) &&
                         (!originalCanExecute || !!originalCanExecute(dev));
@@ -483,6 +527,11 @@ class DevicesService extends events_1.EventEmitter {
             }
         });
     }
+    /**
+     * Starts emulator or simulator if necessary depending on --device or --emulator flags.
+     * If no options are passed runs default emulator/simulator if no devices are connected.
+     * @param deviceInitOpts mainly contains information about --emulator and --deviceId flags.
+     */
     startEmulatorIfNecessary(deviceInitOpts) {
         return __awaiter(this, void 0, void 0, function* () {
             if (deviceInitOpts && deviceInitOpts.deviceId && deviceInitOpts.emulator) {
@@ -492,6 +541,7 @@ class DevicesService extends events_1.EventEmitter {
             if (deviceInitOpts &&
                 deviceInitOpts.platform &&
                 !deviceInitOpts.skipEmulatorStart) {
+                // are there any running devices
                 this._platform = deviceInitOpts.platform;
                 try {
                     yield this.startLookingForDevices(deviceInitOpts);
@@ -502,7 +552,7 @@ class DevicesService extends events_1.EventEmitter {
                 const deviceInstances = this.getDeviceInstances();
                 if (!deviceInitOpts.deviceId && _.isEmpty(deviceInstances)) {
                     if (!this.$hostInfo.isDarwin &&
-                        this.$mobileHelper.isApplePlatfrom(deviceInitOpts.platform)) {
+                        this.$mobileHelper.isApplePlatform(deviceInitOpts.platform)) {
                         this.$errors.fail(constants.ERROR_NO_DEVICES_CANT_USE_IOS_SIMULATOR);
                     }
                 }
@@ -519,9 +569,11 @@ class DevicesService extends events_1.EventEmitter {
     _startEmulatorIfNecessary(data) {
         return __awaiter(this, void 0, void 0, function* () {
             const deviceInstances = this.getDeviceInstances();
+            //if no --device is passed and no devices are found, the default emulator is started
             if (!data.deviceId && _.isEmpty(deviceInstances)) {
                 return this.startEmulatorCore(data);
             }
+            //check if --device(value) is running, if it's not or it's not the same as is specified, start with name from --device(value)
             if (data.deviceId) {
                 if (!helpers.isNumberWithoutExponent(data.deviceId)) {
                     const activeDeviceInstance = _.find(deviceInstances, (device) => device.deviceInfo.identifier === data.deviceId);
@@ -530,6 +582,7 @@ class DevicesService extends events_1.EventEmitter {
                     }
                 }
             }
+            // make sure if the target platform is visionOS we don't try to run it on an already running iOS simulator...
             if (data.platform === this.$devicePlatformsConstants.visionOS &&
                 deviceInstances.length) {
                 const runningDeviceInstance = deviceInstances.find((device) => device.deviceInfo.platform === this.$devicePlatformsConstants.visionOS);
@@ -537,6 +590,7 @@ class DevicesService extends events_1.EventEmitter {
                     return this.startEmulatorCore(data);
                 }
             }
+            // if only emulator flag is passed and no other emulators are running, start default emulator
             if (data.emulator && deviceInstances.length) {
                 const runningDeviceInstance = _.some(deviceInstances, (value) => value.isEmulator);
                 if (!runningDeviceInstance) {
@@ -545,6 +599,12 @@ class DevicesService extends events_1.EventEmitter {
             }
         });
     }
+    /**
+     * Takes care of gathering information about all running devices.
+     * Sets "_isInitialized" to true after infomation is present.
+     * Method expects running devices.
+     * @param data mainly contains information about --emulator and --deviceId flags.
+     */
     initialize(data) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this._deviceInitializePromise) {
@@ -554,6 +614,7 @@ class DevicesService extends events_1.EventEmitter {
                 yield this._deviceInitializePromise;
             }
             catch (err) {
+                // In case the initalization fails, we want to allow calling `initlialize` again with other arguments for example, so remove the cached promise value.
                 this.$logger.trace(`Error while initializing devicesService: ${err}`);
                 this._deviceInitializePromise = null;
                 throw err;
@@ -579,6 +640,7 @@ class DevicesService extends events_1.EventEmitter {
             deviceInitOpts = deviceInitOpts || {};
             this._data = deviceInitOpts;
             if (!deviceInitOpts.skipEmulatorStart) {
+                // TODO: Remove from here as it calls startLookingForDevices, so we double the calls to specific device detection services
                 yield this.startEmulatorIfNecessary(deviceInitOpts);
             }
             const platform = deviceInitOpts.platform;
@@ -609,6 +671,7 @@ class DevicesService extends events_1.EventEmitter {
                 yield this.startLookingForDevices(deviceLookingOptions);
             }
             else {
+                // platform and deviceId are not specified
                 if (deviceInitOpts.skipInferPlatform) {
                     if (deviceInitOpts.skipDeviceDetectionInterval) {
                         yield this.detectCurrentlyAttachedDevices(deviceLookingOptions);
@@ -715,7 +778,7 @@ class DevicesService extends events_1.EventEmitter {
     }
     resolveEmulatorServices(platform) {
         platform = platform || this._platform;
-        if (this.$mobileHelper.isApplePlatfrom(platform)) {
+        if (this.$mobileHelper.isApplePlatform(platform)) {
             return this.$injector.resolve("iOSEmulatorServices");
         }
         else if (this.$mobileHelper.isAndroidPlatform(platform)) {
@@ -723,6 +786,11 @@ class DevicesService extends events_1.EventEmitter {
         }
         return null;
     }
+    /**
+     * Starts emulator for platform and makes sure started devices/emulators/simulators are in _devices array before finishing.
+     * @param platform (optional) platform to start emulator/simulator for
+     * @param emulatorIdOrName (optional) emulator/simulator image identifier or name
+     */
     startEmulatorCore(deviceInitOpts = {}) {
         return __awaiter(this, void 0, void 0, function* () {
             const { deviceId } = deviceInitOpts;
@@ -852,3 +920,4 @@ __decorate([
 ], DevicesService.prototype, "getDebuggableViews", null);
 exports.DevicesService = DevicesService;
 yok_1.injector.register("devicesService", DevicesService);
+//# sourceMappingURL=devices-service.js.map

package/lib/common/mobile/mobile-core/ios-device-discovery.js

@@ -27,11 +27,12 @@ class IOSDeviceDiscovery extends device_discovery_1.DeviceDiscovery {
             this.$logger.trace("Options for ios-device-discovery", options);
             if (options &&
                 options.platform &&
-                (!this.$mobileHelper.isApplePlatfrom(options.platform) ||
+                (!this.$mobileHelper.isApplePlatform(options.platform) ||
                     options.emulator)) {
                 return;
             }
             if (this.$mobileHelper.isvisionOSPlatform(options.platform)) {
+                // look for ios devices - same logic.
                 options.platform = this.$devicePlatformsConstants.iOS;
             }
             yield this.$iosDeviceOperations.startLookingForDevices((deviceInfo) => {
@@ -61,3 +62,4 @@ class IOSDeviceDiscovery extends device_discovery_1.DeviceDiscovery {
 }
 exports.IOSDeviceDiscovery = IOSDeviceDiscovery;
 yok_1.injector.register("iOSDeviceDiscovery", IOSDeviceDiscovery);
+//# sourceMappingURL=ios-device-discovery.js.map

package/lib/common/mobile/mobile-core/ios-simulator-discovery.js

@@ -40,12 +40,14 @@ class IOSSimulatorDiscovery extends device_discovery_1.DeviceDiscovery {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.$hostInfo.isDarwin) {
                 const currentSimulators = yield this.$iOSSimResolver.iOSSim.getRunningSimulators();
+                // Remove old simulators
                 _(this.cachedSimulators)
                     .reject((s) => _.some(currentSimulators, (simulator) => simulator &&
                     s &&
                     simulator.id === s.id &&
                     simulator.state === s.state))
                     .each((s) => this.deleteAndRemoveDevice(s));
+                // Add new simulators
                 _(currentSimulators)
                     .reject((s) => _.some(this.cachedSimulators, (simulator) => simulator &&
                     s &&
@@ -107,3 +109,4 @@ class IOSSimulatorDiscovery extends device_discovery_1.DeviceDiscovery {
 }
 exports.IOSSimulatorDiscovery = IOSSimulatorDiscovery;
 yok_1.injector.register("iOSSimulatorDiscovery", IOSSimulatorDiscovery);
+//# sourceMappingURL=ios-simulator-discovery.js.map

package/lib/common/mobile/mobile-helper.js

@@ -43,7 +43,7 @@ class MobileHelper {
             this.$devicePlatformsConstants.visionOS.toLowerCase() ===
                 platform.toLowerCase());
     }
-    isApplePlatfrom(platform) {
+    isApplePlatform(platform) {
         return this.isiOSPlatform(platform) || this.isvisionOSPlatform(platform);
     }
     normalizePlatformName(platform) {
@@ -100,3 +100,4 @@ class MobileHelper {
 MobileHelper.DEVICE_PATH_SEPARATOR = "/";
 exports.MobileHelper = MobileHelper;
 yok_1.injector.register("mobileHelper", MobileHelper);
+//# sourceMappingURL=mobile-helper.js.map

package/lib/common/mobile/wp8/wp8-emulator-services.js

@@ -80,3 +80,4 @@ class Wp8EmulatorServices {
 Wp8EmulatorServices.WP8_LAUNCHER = "XapDeployCmd.exe";
 Wp8EmulatorServices.WP8_LAUNCHER_PATH = "Microsoft SDKs\\Windows Phone\\v8.0\\Tools\\XAP Deployment";
 yok_1.injector.register("wp8EmulatorServices", Wp8EmulatorServices);
+//# sourceMappingURL=wp8-emulator-services.js.map

package/lib/common/opener.js

@@ -14,3 +14,4 @@ class Opener {
 }
 exports.Opener = Opener;
 yok_1.injector.register("opener", Opener);
+//# sourceMappingURL=opener.js.map

package/lib/common/os-info.js

@@ -19,3 +19,4 @@ class OsInfo {
 }
 exports.OsInfo = OsInfo;
 yok_1.injector.register("osInfo", OsInfo);
+//# sourceMappingURL=os-info.js.map

package/lib/common/plist-parser.js

@@ -22,3 +22,4 @@ class PlistParser {
 }
 exports.PlistParser = PlistParser;
 yok_1.injector.register("plistParser", PlistParser);
+//# sourceMappingURL=plist-parser.js.map

package/lib/common/project-helper.js

@@ -68,3 +68,4 @@ class ProjectHelper {
 }
 exports.ProjectHelper = ProjectHelper;
 yok_1.injector.register("projectHelper", ProjectHelper);
+//# sourceMappingURL=project-helper.js.map

package/lib/common/prompter.js

@@ -36,6 +36,7 @@ class Prompter {
                     else {
                         const result = {};
                         _.each(questions, (s) => {
+                            // Curly brackets needed because s.default() may return false and break the loop
                             result[s.name] = s.default();
                         });
                         return result;
@@ -137,7 +138,9 @@ class Prompter {
     }
     muteStdout() {
         if (helpers.isInteractive()) {
-            process.stdin.setRawMode(true);
+            process.stdin.setRawMode(true); // After setting rawMode to true, Ctrl+C doesn't work for non node.js events loop i.e device log command
+            // We need to create mute-stream and to pass it as output to ctrlcReader
+            // This will prevent the prompter to show the user's text twice on the console
             this.muteStreamInstance = new MuteStream();
             this.muteStreamInstance.pipe(process.stdout);
             this.muteStreamInstance.mute();
@@ -146,6 +149,7 @@ class Prompter {
                 output: this.muteStreamInstance,
             });
             this.ctrlcReader.on("SIGINT", () => {
+                // enable terminal cursor
                 process.stdout.write("\x1B[?25h");
                 process.exit();
             });
@@ -155,6 +159,7 @@ class Prompter {
         if (helpers.isInteractive()) {
             process.stdin.setRawMode(false);
             if (this.muteStreamInstance) {
+                // We need to clean the event listeners from the process.stdout because the MuteStream.pipe function calls the pipe function of the Node js Stream which adds event listeners and this can cause memory leak if we display more than ~10 prompts.
                 this.cleanEventListeners(process.stdout);
                 this.muteStreamInstance.unmute();
                 this.muteStreamInstance = null;
@@ -163,6 +168,8 @@ class Prompter {
         }
     }
     cleanEventListeners(stream) {
+        // The events names and listeners names can be found here https://github.com/nodejs/node/blob/master/lib/stream.js
+        // Which event cause memory leak can be tested with stream.listeners("event-name") and if the listeners count keeps increasing with each prompt we need to remove the listener.
         const memoryLeakEvents = [
             {
                 eventName: "close",
@@ -189,3 +196,4 @@ class Prompter {
 }
 exports.Prompter = Prompter;
 yok_1.injector.register("prompter", Prompter);
+//# sourceMappingURL=prompter.js.map

package/lib/common/queue.js

@@ -35,3 +35,4 @@ class Queue {
     }
 }
 exports.Queue = Queue;
+//# sourceMappingURL=queue.js.map

package/lib/common/resource-loader.js

@@ -23,3 +23,4 @@ class ResourceLoader {
 }
 exports.ResourceLoader = ResourceLoader;
 yok_1.injector.register("resources", ResourceLoader);
+//# sourceMappingURL=resource-loader.js.map

package/lib/common/services/auto-completion-service.js

@@ -36,12 +36,15 @@ class AutoCompletionService {
     get shellProfiles() {
         return [
             this.getHomePath(".bashrc"),
-            this.getHomePath(".zshrc"),
+            this.getHomePath(".zshrc"), // zsh - http://www.acm.uiuc.edu/workshops/zsh/startup_files.html
         ];
     }
     get cliRunCommandsFile() {
         let cliRunCommandsFile = this.getHomePath(util.format(".%src", this.$staticConfig.CLIENT_NAME.toLowerCase()));
         if (this.$hostInfo.isWindows) {
+            // on Windows bash, file is incorrectly written as C:\Users\<username>, which leads to errors when trying to execute the script:
+            // $ source ~/.bashrc
+            // sh.exe": C:Usersusername.appbuilderrc: No such file or directory
             cliRunCommandsFile = cliRunCommandsFile.replace(/\\/g, "/");
         }
         return cliRunCommandsFile;
@@ -53,7 +56,9 @@ class AutoCompletionService {
         return tabTabRegex;
     }
     removeObsoleteAutoCompletion() {
+        // In previous releases we were writing directly in .bash_profile, .bashrc, .zshrc and .profile - remove this old code
         const shellProfilesToBeCleared = this.shellProfiles;
+        // Add .profile only here as we do not want new autocompletion in this file, but we have to remove our old code from it.
         shellProfilesToBeCleared.push(this.getHomePath(".profile"));
         shellProfilesToBeCleared.forEach((file) => {
             try {
@@ -87,6 +92,7 @@ class AutoCompletionService {
                 this.isNewAutoCompletionEnabledInFile(filePath) ||
                     this.isObsoleteAutoCompletionEnabledInFile(filePath);
             if (!result) {
+                // break each
                 return false;
             }
         });
@@ -114,6 +120,7 @@ class AutoCompletionService {
         _.each(this.shellProfiles, (shellProfile) => {
             result = this.isObsoleteAutoCompletionEnabledInFile(shellProfile);
             if (!result) {
+                // break each
                 return false;
             }
         });
@@ -152,6 +159,8 @@ class AutoCompletionService {
         }
         catch (err) {
             this.$logger.info("Unable to update %s. Command-line completion might not work.", fileName);
+            // When npm is installed with sudo, in some cases the installation cannot write to shell profiles
+            // Advise the user how to enable autocompletion after the installation is completed.
             if ((err.code === "EPERM" || err.code === "EACCES") &&
                 !this.$hostInfo.isWindows &&
                 process.env.SUDO_USER) {
@@ -172,6 +181,7 @@ class AutoCompletionService {
             }
         }
         catch (err) {
+            // If file does not exist, autocompletion was not working for it, so ignore this error.
             if (err.code !== "ENOENT") {
                 this.$logger.info("Failed to update %s. Auto-completion may still work or work incorrectly. ", fileName);
                 this.$logger.info(err);
@@ -230,3 +240,4 @@ __decorate([
 ], AutoCompletionService.prototype, "completionShellScriptContent", null);
 exports.AutoCompletionService = AutoCompletionService;
 yok_1.injector.register("autoCompletionService", AutoCompletionService);
+//# sourceMappingURL=auto-completion-service.js.map

package/lib/common/services/cancellation.js

@@ -38,7 +38,7 @@ class CancellationService {
                 .watch(triggerFile, { ignoreInitial: true })
                 .on("unlink", (filePath) => {
                 this.$logger.info(`Exiting process as the file ${filePath} has been deleted. Probably reinstalling CLI while there's a working instance.`);
-                process.exit(132);
+                process.exit(132 /* ErrorCodes.DELETED_KILL_FILE */);
             });
             if (watcher) {
                 this.watches[name] = watcher;
@@ -65,3 +65,4 @@ class CancellationService {
     }
 }
 yok_1.injector.register("cancellation", CancellationService);
+//# sourceMappingURL=cancellation.js.map

package/lib/common/services/commands-service.js

@@ -48,11 +48,11 @@ class CommandsService {
                 if (!this.$staticConfig.disableAnalytics &&
                     !command.disableAnalytics &&
                     !this.$options.disableAnalytics) {
-                    const analyticsService = this.$injector.resolve("analyticsService");
+                    const analyticsService = this.$injector.resolve("analyticsService"); // This should be resolved here due to cyclic dependency
                     yield analyticsService.checkConsent();
                     const beautifiedCommandName = this.beautifyCommandName(commandName).replace(/\|/g, " ");
                     const googleAnalyticsPageData = {
-                        googleAnalyticsDataType: "pageview",
+                        googleAnalyticsDataType: "pageview" /* GoogleAnalyticsDataType.Page */,
                         path: beautifiedCommandName,
                         title: beautifiedCommandName,
                     };
@@ -62,10 +62,11 @@ class CommandsService {
                 const shouldExecuteHooks = !this.$staticConfig.disableCommandHooks &&
                     (command.enableHooks === undefined || command.enableHooks === true);
                 if (shouldExecuteHooks) {
+                    // Handle correctly hierarchical commands
                     const hierarchicalCommandName = this.$injector.buildHierarchicalCommand(commandName, commandArguments);
                     if (hierarchicalCommandName) {
-                        commandName = helpers.stringReplaceAll(hierarchicalCommandName.commandName, "|*", "-");
-                        commandName = helpers.stringReplaceAll(commandName, "|", "-");
+                        commandName = helpers.stringReplaceAll(hierarchicalCommandName.commandName, "|*" /* CommandsDelimiters.DefaultHierarchicalCommand */, "-" /* CommandsDelimiters.HooksCommand */);
+                        commandName = helpers.stringReplaceAll(commandName, "|" /* CommandsDelimiters.HierarchicalCommand */, "-" /* CommandsDelimiters.HooksCommand */);
                     }
                     yield this.$hooksService.executeBeforeHooks(commandName);
                 }
@@ -116,6 +117,7 @@ class CommandsService {
                 yield this.executeCommandAction(commandName, commandArguments, this.executeCommandUnchecked);
             }
             else {
+                // If canExecuteCommand returns false, the command cannot be executed or there's no such command at all.
                 const command = this.$injector.resolveCommand(commandName);
                 if (command) {
                     let commandWithArgs = commandName;
@@ -133,12 +135,15 @@ class CommandsService {
             const command = this.$injector.resolveCommand(commandName);
             const beautifiedName = helpers.stringReplaceAll(commandName, "|", " ");
             if (command) {
+                // Verify command is enabled
                 if (command.isDisabled) {
                     this.$errors.fail("This command is not applicable to your environment.");
                 }
+                // If command wants to handle canExecute logic on its own.
                 if (command.canExecute) {
                     return yield command.canExecute(commandArguments);
                 }
+                // First part of hierarchical commands should be validated in specific way.
                 if (yield this.$injector.isValidHierarchicalCommand(commandName, commandArguments)) {
                     return true;
                 }
@@ -150,8 +155,8 @@ class CommandsService {
             }
             const commandInfo = {
                 inputStrings: [commandName, ...commandArguments],
-                commandDelimiter: "|",
-                defaultCommandDelimiter: "|*",
+                commandDelimiter: "|" /* CommandsDelimiters.HierarchicalCommand */,
+                defaultCommandDelimiter: "|*" /* CommandsDelimiters.DefaultHierarchicalCommand */,
             };
             const extensionData = yield this.$extensibilityService.getExtensionNameWhereCommandIsRegistered(commandInfo);
             if (extensionData) {
@@ -169,11 +174,13 @@ class CommandsService {
         return __awaiter(this, void 0, void 0, function* () {
             const commandArgsHelper = new CommandArgumentsValidationHelper(true, commandArguments);
             if (mandatoryParams.length > 0) {
+                // If command has more mandatory params than the passed ones, we shouldn't execute it
                 if (mandatoryParams.length > commandArguments.length) {
                     const customErrorMessages = _.map(mandatoryParams, (mp) => mp.errorMessage);
                     customErrorMessages.splice(0, 0, "You need to provide all the required parameters.");
                     this.$errors.failWithHelp(customErrorMessages.join(os_1.EOL));
                 }
+                // If we reach here, the commandArguments are at least as much as mandatoryParams. Now we should verify that we have each of them.
                 for (let mandatoryParamIndex = 0; mandatoryParamIndex < mandatoryParams.length; ++mandatoryParamIndex) {
                     const mandatoryParam = mandatoryParams[mandatoryParamIndex];
                     let argument = null;
@@ -202,12 +209,14 @@ class CommandsService {
             if (!commandArgsHelper.isValid) {
                 return false;
             }
+            // Command doesn't have any allowedParameters
             if (!command.allowedParameters || command.allowedParameters.length === 0) {
                 if (commandArguments.length > 0) {
                     this.$errors.failWithHelp("This command doesn't accept parameters.");
                 }
             }
             else {
+                // Exclude mandatory params, we've already checked them
                 const unverifiedAllowedParams = command.allowedParameters.filter((param) => !param.mandatory);
                 for (let remainingArgsIndex = 0; remainingArgsIndex < commandArgsHelper.remainingArguments.length; ++remainingArgsIndex) {
                     const argument = commandArgsHelper.remainingArguments[remainingArgsIndex];
@@ -221,6 +230,7 @@ class CommandsService {
                     }
                     if (parameter) {
                         const index = unverifiedAllowedParams.indexOf(parameter);
+                        // Remove the matched parameter from unverifiedAllowedParams collection, so it will not be used to verify another argument.
                         unverifiedAllowedParams.splice(index, 1);
                     }
                     else {
@@ -266,3 +276,4 @@ class CommandsService {
 }
 exports.CommandsService = CommandsService;
 yok_1.injector.register("commandsService", CommandsService);
+//# sourceMappingURL=commands-service.js.map

package/lib/common/services/help-service.js

@@ -52,6 +52,7 @@ class HelpService {
             this.$logger.trace("Opening help for command '%s'. FileName is '%s'.", commandName, htmlPage);
             this.$fs.ensureDirectoryExists(this.pathToHtmlPages);
             if (!this.tryOpeningSelectedPage(htmlPage)) {
+                // HTML pages may have been skipped on post-install, lets generate them.
                 this.$logger.trace("Required HTML file '%s' is missing. Let's try generating HTML files and see if we'll find it.", htmlPage);
                 yield this.generateHtmlPages();
                 if (!this.tryOpeningSelectedPage(htmlPage)) {
@@ -113,6 +114,11 @@ class HelpService {
             this.$logger.printMarkdown(help);
         });
     }
+    /**
+     * Gets the help content for a specific command that should be shown on the terminal.
+     * @param {string} commandName Name of the command for which to read the help.
+     * @returns {Promise<string>} Help content of the command parsed with all terminal rules applied (stripped content that should be shown only for html help).
+     */
     getCommandLineHelpForCommand(commandData) {
         return __awaiter(this, void 0, void 0, function* () {
             const helpText = yield this.readMdFileForCommand(commandData);
@@ -126,6 +132,7 @@ class HelpService {
             return commandLineHelp;
         });
     }
+    // This method should return Promise in order to generate all html pages simultaneously.
     createHtmlPage(htmlPageGenerationData) {
         return __awaiter(this, void 0, void 0, function* () {
             const { basicHtmlPage, pathToMdFile, pathToMdPages, pathToHtmlPages, extensionName, } = htmlPageGenerationData;
@@ -177,8 +184,8 @@ class HelpService {
             const commandName = commandData.commandName;
             const commandInfo = {
                 inputStrings: [commandName, ...commandData.commandArguments],
-                commandDelimiter: "|",
-                defaultCommandDelimiter: "|*",
+                commandDelimiter: "|" /* CommandsDelimiters.HierarchicalCommand */,
+                defaultCommandDelimiter: "|*" /* CommandsDelimiters.DefaultHierarchicalCommand */,
             };
             const extensionData = yield this.$extensibilityService.getExtensionNameWhereCommandIsRegistered(commandInfo);
             if (extensionData) {
@@ -247,6 +254,7 @@ HelpService.RELATIVE_PATH_TO_INDEX_REGEX = /@RELATIVE_PATH_TO_INDEX@/g;
 HelpService.EXTENSION_NAME_REGEX = /@EXTENSION_NAME@/g;
 HelpService.MARKDOWN_LINK_REGEX = /\[([\w \-\`\<\>\*\:\\]+?)\]\([\s\S]+?\)/g;
 HelpService.SPAN_REGEX = /([\s\S]*?)(?:\r?\n)?<span.*?>([\s\S]*?)<\/span>(?:\r?\n)*/g;
-HelpService.NEW_LINE_REGEX = /<\/?\s*?br\s*?\/?>/g;
+HelpService.NEW_LINE_REGEX = /<\/?\s*?br\s*?\/?>/g; // <br>, <br > <br/> <br />
 exports.HelpService = HelpService;
 yok_1.injector.register("helpService", HelpService);
+//# sourceMappingURL=help-service.js.map