@stencil/core 2.17.0 → 2.17.1

package/cli/index.js

@@ -1,8 +1,50 @@
 /*!
- Stencil CLI v2.17.0 | MIT Licensed | https://stenciljs.com
+ Stencil CLI v2.17.1 | MIT Licensed | https://stenciljs.com
  */
-const toLowerCase = (str) => str.toLowerCase();
-const dashToPascalCase = (str) => toLowerCase(str)
+/**
+ * This sets the log level hierarchy for our terminal logger, ranging from
+ * most to least verbose.
+ *
+ * Ordering the levels like this lets us easily check whether we should log a
+ * message at a given time. For instance, if the log level is set to `'warn'`,
+ * then anything passed to the logger with level `'warn'` or `'error'` should
+ * be logged, but we should _not_ log anything with level `'info'` or `'debug'`.
+ *
+ * If we have a current log level `currentLevel` and a message with level
+ * `msgLevel` is passed to the logger, we can determine whether or not we should
+ * log it by checking if the log level on the message is further up or at the
+ * same level in the hierarchy than `currentLevel`, like so:
+ *
+ * ```ts
+ * LOG_LEVELS.indexOf(msgLevel) >= LOG_LEVELS.indexOf(currentLevel)
+ * ```
+ *
+ * NOTE: for the reasons described above, do not change the order of the entries
+ * in this array without good reason!
+ */
+const LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
+
+/**
+ * Convert a string from PascalCase to dash-case
+ *
+ * @param str the string to convert
+ * @returns a converted string
+ */
+const toDashCase = (str) => str
+    .replace(/([A-Z0-9])/g, (match) => ` ${match[0]}`)
+    .trim()
+    .split(' ')
+    .join('-')
+    .toLowerCase();
+/**
+ * Convert a string from dash-case / kebab-case to PascalCase (or CamelCase,
+ * or whatever you call it!)
+ *
+ * @param str a string to convert
+ * @returns a converted string
+ */
+const dashToPascalCase = (str) => str
+    .toLowerCase()
     .split('-')
     .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
     .join('');
@@ -275,22 +317,211 @@ const validateComponentTag = (tag) => {
     return undefined;
 };
 
+/**
+ * All the Boolean options supported by the Stencil CLI
+ */
+const BOOLEAN_CLI_ARGS = [
+    'build',
+    'cache',
+    'checkVersion',
+    'ci',
+    'compare',
+    'debug',
+    'dev',
+    'devtools',
+    'docs',
+    'e2e',
+    'es5',
+    'esm',
+    'headless',
+    'help',
+    'log',
+    'open',
+    'prerender',
+    'prerenderExternal',
+    'prod',
+    'profile',
+    'serviceWorker',
+    'screenshot',
+    'serve',
+    'skipNodeCheck',
+    'spec',
+    'ssr',
+    'stats',
+    'updateScreenshot',
+    'verbose',
+    'version',
+    'watch',
+    // JEST CLI OPTIONS
+    'all',
+    'automock',
+    'bail',
+    // 'cache', Stencil already supports this argument
+    'changedFilesWithAncestor',
+    // 'ci', Stencil already supports this argument
+    'clearCache',
+    'clearMocks',
+    'collectCoverage',
+    'color',
+    'colors',
+    'coverage',
+    // 'debug', Stencil already supports this argument
+    'detectLeaks',
+    'detectOpenHandles',
+    'errorOnDeprecated',
+    'expand',
+    'findRelatedTests',
+    'forceExit',
+    'init',
+    'injectGlobals',
+    'json',
+    'lastCommit',
+    'listTests',
+    'logHeapUsage',
+    'noStackTrace',
+    'notify',
+    'onlyChanged',
+    'onlyFailures',
+    'passWithNoTests',
+    'resetMocks',
+    'resetModules',
+    'restoreMocks',
+    'runInBand',
+    'runTestsByPath',
+    'showConfig',
+    'silent',
+    'skipFilter',
+    'testLocationInResults',
+    'updateSnapshot',
+    'useStderr',
+    // 'verbose', Stencil already supports this argument
+    // 'version', Stencil already supports this argument
+    // 'watch', Stencil already supports this argument
+    'watchAll',
+    'watchman',
+];
+/**
+ * All the Number options supported by the Stencil CLI
+ */
+const NUMBER_CLI_ARGS = [
+    'port',
+    // JEST CLI ARGS
+    'maxConcurrency',
+    'testTimeout',
+];
+/**
+ * All the String options supported by the Stencil CLI
+ */
+const STRING_CLI_ARGS = [
+    'address',
+    'config',
+    'docsApi',
+    'docsJson',
+    'emulate',
+    'root',
+    'screenshotConnector',
+    // JEST CLI ARGS
+    'cacheDirectory',
+    'changedSince',
+    'collectCoverageFrom',
+    // 'config', Stencil already supports this argument
+    'coverageDirectory',
+    'coverageThreshold',
+    'env',
+    'filter',
+    'globalSetup',
+    'globalTeardown',
+    'globals',
+    'haste',
+    'moduleNameMapper',
+    'notifyMode',
+    'outputFile',
+    'preset',
+    'prettierPath',
+    'resolver',
+    'rootDir',
+    'runner',
+    'testEnvironment',
+    'testEnvironmentOptions',
+    'testFailureExitCode',
+    'testNamePattern',
+    'testResultsProcessor',
+    'testRunner',
+    'testSequencer',
+    'testURL',
+    'timers',
+    'transform',
+    // ARRAY ARGS
+    'collectCoverageOnlyFrom',
+    'coveragePathIgnorePatterns',
+    'coverageReporters',
+    'moduleDirectories',
+    'moduleFileExtensions',
+    'modulePathIgnorePatterns',
+    'modulePaths',
+    'projects',
+    'reporters',
+    'roots',
+    'selectProjects',
+    'setupFiles',
+    'setupFilesAfterEnv',
+    'snapshotSerializers',
+    'testMatch',
+    'testPathIgnorePatterns',
+    'testPathPattern',
+    'testRegex',
+    'transformIgnorePatterns',
+    'unmockedModulePathPatterns',
+    'watchPathIgnorePatterns',
+];
+/**
+ * All the CLI arguments which may have string or number values
+ *
+ * `maxWorkers` is an argument which is used both by Stencil _and_ by Jest,
+ * which means that we need to support parsing both string and number values.
+ */
+const STRING_NUMBER_CLI_ARGS = ['maxWorkers'];
+/**
+ * All the LogLevel-type options supported by the Stencil CLI
+ *
+ * This is a bit silly since there's only one such argument atm,
+ * but this approach lets us make sure that we're handling all
+ * our arguments in a type-safe way.
+ */
+const LOG_LEVEL_CLI_ARGS = ['logLevel'];
+/**
+ * For a small subset of CLI options we support a short alias e.g. `'h'` for `'help'`
+ */
+const CLI_ARG_ALIASES = {
+    config: 'c',
+    help: 'h',
+    port: 'p',
+    version: 'v',
+};
+
+/**
+ * Parse command line arguments into a structured `ConfigFlags` object
+ *
+ * @param args an array of config flags
+ * @param sys an optional compiler system
+ * @returns a structured ConfigFlags object
+ */
 const parseFlags = (args, sys) => {
     const flags = {
         task: null,
         args: [],
         knownArgs: [],
-        unknownArgs: null,
+        unknownArgs: [],
     };
     // cmd line has more priority over npm scripts cmd
-    flags.args = args.slice();
+    flags.args = Array.isArray(args) ? args.slice() : [];
     if (flags.args.length > 0 && flags.args[0] && !flags.args[0].startsWith('-')) {
         flags.task = flags.args[0];
     }
-    parseArgs(flags, flags.args, flags.knownArgs);
+    parseArgs(flags, flags.args);
     if (sys && sys.name === 'node') {
         const envArgs = getNpmConfigEnvArgs(sys);
-        parseArgs(flags, envArgs, flags.knownArgs);
+        parseArgs(flags, envArgs);
         envArgs.forEach((envArg) => {
             if (!flags.args.includes(envArg)) {
                 flags.args.push(envArg);
@@ -309,185 +540,230 @@ const parseFlags = (args, sys) => {
     return flags;
 };
 /**
- * Parse command line arguments that are whitelisted via the BOOLEAN_ARG_OPTS,
- * STRING_ARG_OPTS, and NUMBER_ARG_OPTS arrays in this file. Handles leading
- * dashes on arguments, aliases that are defined for a small number of argument
- * types, and parsing values for non-boolean arguments (e.g. port number).
+ * Parse command line arguments that are enumerated in the `config-flags`
+ * module. Handles leading dashes on arguments, aliases that are defined for a
+ * small number of arguments, and parsing values for non-boolean arguments
+ * (e.g. port number for the dev server).
  *
- * @param flags     a ConfigFlags object
- * @param args      an array of command-line arguments to parse
- * @param knownArgs an array to which all recognized, legal arguments are added
- */
-const parseArgs = (flags, args, knownArgs) => {
-    BOOLEAN_ARG_OPTS.forEach((booleanName) => {
-        const alias = ARG_OPTS_ALIASES[booleanName];
-        const flagKey = configCase(booleanName);
-        if (typeof flags[flagKey] !== 'boolean') {
-            flags[flagKey] = null;
+ * @param flags a ConfigFlags object to which parsed arguments will be added
+ * @param args  an array of command-line arguments to parse
+ */
+const parseArgs = (flags, args) => {
+    BOOLEAN_CLI_ARGS.forEach((argName) => parseBooleanArg(flags, args, argName));
+    STRING_CLI_ARGS.forEach((argName) => parseStringArg(flags, args, argName));
+    NUMBER_CLI_ARGS.forEach((argName) => parseNumberArg(flags, args, argName));
+    STRING_NUMBER_CLI_ARGS.forEach((argName) => parseStringNumberArg(flags, args, argName));
+    LOG_LEVEL_CLI_ARGS.forEach((argName) => parseLogLevelArg(flags, args, argName));
+};
+/**
+ * Parse a boolean CLI argument. For these, we support the following formats:
+ *
+ * - `--booleanArg`
+ * - `--boolean-arg`
+ * - `--noBooleanArg`
+ * - `--no-boolean-arg`
+ *
+ * The final two variants should be parsed to a value of `false` on the config
+ * object.
+ *
+ * @param flags the config flags object, while we'll modify
+ * @param args our CLI arguments
+ * @param configCaseName the argument we want to look at right now
+ */
+const parseBooleanArg = (flags, args, configCaseName) => {
+    // we support both dash-case and PascalCase versions of the parameter
+    // argName is 'configCase' version which can be found in BOOLEAN_ARG_OPTS
+    const alias = CLI_ARG_ALIASES[configCaseName];
+    const dashCaseName = toDashCase(configCaseName);
+    if (typeof flags[configCaseName] !== 'boolean') {
+        flags[configCaseName] = null;
+    }
+    args.forEach((cmdArg) => {
+        let value;
+        if (cmdArg === `--${configCaseName}` || cmdArg === `--${dashCaseName}`) {
+            value = true;
         }
-        args.forEach((cmdArg) => {
-            if (cmdArg === `--${booleanName}`) {
-                flags[flagKey] = true;
-                knownArgs.push(cmdArg);
-            }
-            else if (cmdArg === `--${flagKey}`) {
-                flags[flagKey] = true;
-                knownArgs.push(cmdArg);
-            }
-            else if (cmdArg === `--no-${booleanName}`) {
-                flags[flagKey] = false;
-                knownArgs.push(cmdArg);
-            }
-            else if (cmdArg === `--no${dashToPascalCase(booleanName)}`) {
-                flags[flagKey] = false;
-                knownArgs.push(cmdArg);
-            }
-            else if (alias && cmdArg === `-${alias}`) {
-                flags[flagKey] = true;
-                knownArgs.push(cmdArg);
-            }
-        });
-    });
-    STRING_ARG_OPTS.forEach((stringName) => {
-        const alias = ARG_OPTS_ALIASES[stringName];
-        const flagKey = configCase(stringName);
-        if (typeof flags[flagKey] !== 'string') {
-            flags[flagKey] = null;
+        else if (cmdArg === `--no-${dashCaseName}` || cmdArg === `--no${dashToPascalCase(dashCaseName)}`) {
+            value = false;
         }
-        for (let i = 0; i < args.length; i++) {
-            const cmdArg = args[i];
-            if (cmdArg.startsWith(`--${stringName}=`)) {
-                const values = cmdArg.split('=');
-                values.shift();
-                flags[flagKey] = values.join('=');
-                knownArgs.push(cmdArg);
-            }
-            else if (cmdArg === `--${stringName}`) {
-                flags[flagKey] = args[i + 1];
-                knownArgs.push(cmdArg);
-                knownArgs.push(args[i + 1]);
-            }
-            else if (cmdArg === `--${flagKey}`) {
-                flags[flagKey] = args[i + 1];
-                knownArgs.push(cmdArg);
-                knownArgs.push(args[i + 1]);
-            }
-            else if (cmdArg.startsWith(`--${flagKey}=`)) {
-                const values = cmdArg.split('=');
-                values.shift();
-                flags[flagKey] = values.join('=');
-                knownArgs.push(cmdArg);
-            }
-            else if (alias) {
-                if (cmdArg.startsWith(`-${alias}=`)) {
-                    const values = cmdArg.split('=');
-                    values.shift();
-                    flags[flagKey] = values.join('=');
-                    knownArgs.push(cmdArg);
-                }
-                else if (cmdArg === `-${alias}`) {
-                    flags[flagKey] = args[i + 1];
-                    knownArgs.push(args[i + 1]);
-                }
-            }
+        else if (alias && cmdArg === `-${alias}`) {
+            value = true;
+        }
+        if (value !== undefined && cmdArg !== undefined) {
+            flags[configCaseName] = value;
+            flags.knownArgs.push(cmdArg);
         }
     });
-    NUMBER_ARG_OPTS.forEach((numberName) => {
-        const alias = ARG_OPTS_ALIASES[numberName];
-        const flagKey = configCase(numberName);
-        if (typeof flags[flagKey] !== 'number') {
-            flags[flagKey] = null;
+};
+/**
+ * Parse a string CLI argument
+ *
+ * @param flags the config flags object, while we'll modify
+ * @param args our CLI arguments
+ * @param configCaseName the argument we want to look at right now
+ */
+const parseStringArg = (flags, args, configCaseName) => {
+    if (typeof flags[configCaseName] !== 'string') {
+        flags[configCaseName] = null;
+    }
+    const { value, matchingArg } = getValue(args, configCaseName);
+    if (value !== undefined && matchingArg !== undefined) {
+        flags[configCaseName] = value;
+        flags.knownArgs.push(matchingArg);
+        flags.knownArgs.push(value);
+    }
+};
+/**
+ * Parse a number CLI argument
+ *
+ * @param flags the config flags object, while we'll modify
+ * @param args our CLI arguments
+ * @param configCaseName the argument we want to look at right now
+ */
+const parseNumberArg = (flags, args, configCaseName) => {
+    if (typeof flags[configCaseName] !== 'number') {
+        flags[configCaseName] = null;
+    }
+    const { value, matchingArg } = getValue(args, configCaseName);
+    if (value !== undefined && matchingArg !== undefined) {
+        flags[configCaseName] = parseInt(value, 10);
+        flags.knownArgs.push(matchingArg);
+        flags.knownArgs.push(value);
+    }
+};
+/**
+ * Parse a CLI argument which may be either a string or a number
+ *
+ * @param flags the config flags object, while we'll modify
+ * @param args our CLI arguments
+ * @param configCaseName the argument we want to look at right now
+ */
+const parseStringNumberArg = (flags, args, configCaseName) => {
+    if (!['number', 'string'].includes(typeof flags[configCaseName])) {
+        flags[configCaseName] = null;
+    }
+    const { value, matchingArg } = getValue(args, configCaseName);
+    if (value !== undefined && matchingArg !== undefined) {
+        if (CLI_ARG_STRING_REGEX.test(value)) {
+            // if it matches the regex we treat it like a string
+            flags[configCaseName] = value;
         }
-        for (let i = 0; i < args.length; i++) {
-            const cmdArg = args[i];
-            if (cmdArg.startsWith(`--${numberName}=`)) {
-                const values = cmdArg.split('=');
-                values.shift();
-                flags[flagKey] = parseInt(values.join(''), 10);
-                knownArgs.push(cmdArg);
-            }
-            else if (cmdArg === `--${numberName}`) {
-                flags[flagKey] = parseInt(args[i + 1], 10);
-                knownArgs.push(args[i + 1]);
-            }
-            else if (cmdArg.startsWith(`--${flagKey}=`)) {
-                const values = cmdArg.split('=');
-                values.shift();
-                flags[flagKey] = parseInt(values.join(''), 10);
-                knownArgs.push(cmdArg);
-            }
-            else if (cmdArg === `--${flagKey}`) {
-                flags[flagKey] = parseInt(args[i + 1], 10);
-                knownArgs.push(args[i + 1]);
+        else {
+            // it was a number, great!
+            flags[configCaseName] = Number(value);
+        }
+        flags.knownArgs.push(matchingArg);
+        flags.knownArgs.push(value);
+    }
+};
+/**
+ * We use this regular expression to detect CLI parameters which
+ * should be parsed as string values (as opposed to numbers) for
+ * the argument types for which we support both a string and a
+ * number value.
+ *
+ * The regex tests for the presence of at least one character which is
+ * _not_ a digit (`\d`), a period (`\.`), or one of the characters `"e"`,
+ * `"E"`, `"+"`, or `"-"` (the latter four characters are necessary to
+ * support the admittedly unlikely use of scientific notation, like `"4e+0"`
+ * for `4`).
+ *
+ * Thus we'll match a string like `"50%"`, but not a string like `"50"` or
+ * `"5.0"`. If it matches a given string we conclude that the string should
+ * be parsed as a string literal, rather than using `Number` to convert it
+ * to a number.
+ */
+const CLI_ARG_STRING_REGEX = /[^\d\.Ee\+\-]+/g;
+/**
+ * Parse a LogLevel CLI argument. These can be only a specific
+ * set of strings, so this function takes care of validating that
+ * the value is correct.
+ *
+ * @param flags the config flags object, while we'll modify
+ * @param args our CLI arguments
+ * @param configCaseName the argument we want to look at right now
+ */
+const parseLogLevelArg = (flags, args, configCaseName) => {
+    if (typeof flags[configCaseName] !== 'string') {
+        flags[configCaseName] = null;
+    }
+    const { value, matchingArg } = getValue(args, configCaseName);
+    if (value !== undefined && matchingArg !== undefined && isLogLevel(value)) {
+        flags[configCaseName] = value;
+        flags.knownArgs.push(matchingArg);
+        flags.knownArgs.push(value);
+    }
+};
+/**
+ * Helper for pulling values out from the raw array of CLI arguments. This logic
+ * is shared between a few different types of CLI args.
+ *
+ * We look for arguments in the following formats:
+ *
+ * - `--my-cli-argument value`
+ * - `--my-cli-argument=value`
+ * - `--myCliArgument value`
+ * - `--myCliArgument=value`
+ *
+ * We also check for shortened aliases, which we define for a few arguments.
+ *
+ * @param args the CLI args we're dealing with
+ * @param configCaseName the ConfigFlag key which we're looking to pull out a value for
+ * @returns the value for the flag as well as the exact string which it matched from
+ * the user input.
+ */
+const getValue = (args, configCaseName) => {
+    // for some CLI args we have a short alias, like 'c' for 'config'
+    const alias = CLI_ARG_ALIASES[configCaseName];
+    // we support supplying arguments in both dash-case and configCase
+    // for ease of use
+    const dashCaseName = toDashCase(configCaseName);
+    let value;
+    let matchingArg;
+    args.forEach((arg, i) => {
+        if (arg.startsWith(`--${dashCaseName}=`) || arg.startsWith(`--${configCaseName}=`)) {
+            value = getEqualsValue(arg);
+            matchingArg = arg;
+        }
+        else if (arg === `--${dashCaseName}` || arg === `--${configCaseName}`) {
+            value = args[i + 1];
+            matchingArg = arg;
+        }
+        else if (alias) {
+            if (arg.startsWith(`-${alias}=`)) {
+                value = getEqualsValue(arg);
+                matchingArg = arg;
             }
-            else if (alias) {
-                if (cmdArg.startsWith(`-${alias}=`)) {
-                    const values = cmdArg.split('=');
-                    values.shift();
-                    flags[flagKey] = parseInt(values.join(''), 10);
-                    knownArgs.push(cmdArg);
-                }
-                else if (cmdArg === `-${alias}`) {
-                    flags[flagKey] = parseInt(args[i + 1], 10);
-                    knownArgs.push(args[i + 1]);
-                }
+            else if (arg === `-${alias}`) {
+                value = args[i + 1];
+                matchingArg = arg;
             }
         }
     });
+    return { value, matchingArg };
 };
-const configCase = (prop) => {
-    prop = dashToPascalCase(prop);
-    return prop.charAt(0).toLowerCase() + prop.slice(1);
-};
-const BOOLEAN_ARG_OPTS = [
-    'build',
-    'cache',
-    'check-version',
-    'ci',
-    'compare',
-    'debug',
-    'dev',
-    'devtools',
-    'docs',
-    'e2e',
-    'es5',
-    'esm',
-    'headless',
-    'help',
-    'log',
-    'open',
-    'prerender',
-    'prerender-external',
-    'prod',
-    'profile',
-    'service-worker',
-    'screenshot',
-    'serve',
-    'skip-node-check',
-    'spec',
-    'ssr',
-    'stats',
-    'update-screenshot',
-    'verbose',
-    'version',
-    'watch',
-];
-const NUMBER_ARG_OPTS = ['max-workers', 'port'];
-const STRING_ARG_OPTS = [
-    'address',
-    'config',
-    'docs-json',
-    'emulate',
-    'log-level',
-    'root',
-    'screenshot-connector',
-];
-const ARG_OPTS_ALIASES = {
-    config: 'c',
-    help: 'h',
-    port: 'p',
-    version: 'v',
-};
+/**
+ * When a parameter is set in the format `--foobar=12` at the CLI (as opposed to
+ * `--foobar 12`) we want to get the value after the `=` sign
+ *
+ * @param commandArgument the arg in question
+ * @returns the value after the `=`
+ */
+const getEqualsValue = (commandArgument) => commandArgument.split('=').slice(1).join('=');
+/**
+ * Small helper for getting type-system-level assurance that a `string` can be
+ * narrowed to a `LogLevel`
+ *
+ * @param maybeLogLevel the string to check
+ * @returns whether this is a `LogLevel`
+ */
+const isLogLevel = (maybeLogLevel) => 
+// unfortunately `includes` is typed on `ReadonlyArray<T>` as `(el: T):
+// boolean` so a `string` cannot be passed to `includes` on a
+// `ReadonlyArray` 😢 thus we `as any`
+//
+// see microsoft/TypeScript#31018 for some discussion of this
+LOG_LEVELS.includes(maybeLogLevel);
 const getNpmConfigEnvArgs = (sys) => {
     // process.env.npm_config_argv
     // {"remain":["4444"],"cooked":["run","serve","--port","4444"],"original":["run","serve","--port","4444"]}
@@ -508,7 +784,7 @@ const getNpmConfigEnvArgs = (sys) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.17.0",
+		version: "2.17.1",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",
@@ -833,12 +1109,11 @@ const tryFn = async (fn, ...args) => {
     }
     return null;
 };
-const isInteractive = (sys, config, object) => {
-    var _a;
+const isInteractive = (sys, flags, object) => {
     const terminalInfo = object ||
         Object.freeze({
             tty: sys.isTTY() ? true : false,
-            ci: ['CI', 'BUILD_ID', 'BUILD_NUMBER', 'BITBUCKET_COMMIT', 'CODEBUILD_BUILD_ARN'].filter((v) => !!sys.getEnvironmentVar(v)).length > 0 || !!((_a = config.flags) === null || _a === void 0 ? void 0 : _a.ci),
+            ci: ['CI', 'BUILD_ID', 'BUILD_NUMBER', 'BITBUCKET_COMMIT', 'CODEBUILD_BUILD_ARN'].filter((v) => !!sys.getEnvironmentVar(v)).length > 0 || !!flags.ci,
         });
     return terminalInfo.tty && !terminalInfo.ci;
 };
@@ -863,19 +1138,19 @@ async function readJson(sys, path) {
 }
 /**
  * Does the command have the debug flag?
- * @param config The config passed into the Stencil command
+ * @param flags The configuration flags passed into the Stencil command
  * @returns true if --debug has been passed, otherwise false
  */
-function hasDebug(config) {
-    return config.flags.debug;
+function hasDebug(flags) {
+    return flags.debug;
 }
 /**
  * Does the command have the verbose and debug flags?
- * @param config The config passed into the Stencil command
+ * @param flags The configuration flags passed into the Stencil command
  * @returns true if both --debug and --verbose have been passed, otherwise false
  */
-function hasVerbose(config) {
-    return config.flags.verbose && hasDebug(config);
+function hasVerbose(flags) {
+    return flags.verbose && hasDebug(flags);
 }
 
 /**
@@ -886,7 +1161,7 @@ function hasVerbose(config) {
  * @returns true if telemetry should be sent, false otherwise
  */
 async function shouldTrack(config, sys, ci) {
-    return !ci && isInteractive(sys, config) && (await checkTelemetry(sys));
+    return !ci && isInteractive(sys, config.flags) && (await checkTelemetry(sys));
 }
 
 const isTest$1 = () => process.env.JEST_WORKER_ID !== undefined;
@@ -957,11 +1232,10 @@ const WWW = 'www';
  *
  * @param sys The system where the command is invoked
  * @param config The config passed into the Stencil command
- * @param logger The tool used to do logging
  * @param coreCompiler The compiler used to do builds
  * @param result The results of a compiler build.
  */
-async function telemetryBuildFinishedAction(sys, config, logger, coreCompiler, result) {
+async function telemetryBuildFinishedAction(sys, config, coreCompiler, result) {
     const tracking = await shouldTrack(config, sys, config.flags.ci);
     if (!tracking) {
         return;
@@ -969,21 +1243,19 @@ async function telemetryBuildFinishedAction(sys, config, logger, coreCompiler, r
     const component_count = Object.keys(result.componentGraph).length;
     const data = await prepareData(coreCompiler, config, sys, result.duration, component_count);
     await sendMetric(sys, config, 'stencil_cli_command', data);
-    logger.debug(`${logger.blue('Telemetry')}: ${logger.gray(JSON.stringify(data))}`);
+    config.logger.debug(`${config.logger.blue('Telemetry')}: ${config.logger.gray(JSON.stringify(data))}`);
 }
 /**
  * A function to wrap a compiler task function around. Will send telemetry if, and only if, the machine allows.
  *
  * @param sys The system where the command is invoked
  * @param config The config passed into the Stencil command
- * @param logger The tool used to do logging
  * @param coreCompiler The compiler used to do builds
  * @param action A Promise-based function to call in order to get the duration of any given command.
  * @returns void
  */
-async function telemetryAction(sys, config, logger, coreCompiler, action) {
-    var _a;
-    const tracking = await shouldTrack(config, sys, !!((_a = config === null || config === void 0 ? void 0 : config.flags) === null || _a === void 0 ? void 0 : _a.ci));
+async function telemetryAction(sys, config, coreCompiler, action) {
+    const tracking = await shouldTrack(config, sys, !!config.flags.ci);
     let duration = undefined;
     let error;
     if (action) {
@@ -1003,7 +1275,7 @@ async function telemetryAction(sys, config, logger, coreCompiler, action) {
     }
     const data = await prepareData(coreCompiler, config, sys, duration);
     await sendMetric(sys, config, 'stencil_cli_command', data);
-    logger.debug(`${logger.blue('Telemetry')}: ${logger.gray(JSON.stringify(data))}`);
+    config.logger.debug(`${config.logger.blue('Telemetry')}: ${config.logger.gray(JSON.stringify(data))}`);
     if (error) {
         throw error;
     }
@@ -1171,7 +1443,7 @@ async function getInstalledPackages(sys, config) {
         return { packages, packagesNoVersions };
     }
     catch (err) {
-        hasDebug(config) && console.error(err);
+        hasDebug(config.flags) && console.error(err);
         return { packages, packagesNoVersions };
     }
 }
@@ -1273,15 +1545,15 @@ async function sendTelemetry(sys, config, data) {
             },
             body: JSON.stringify(body),
         });
-        hasVerbose(config) &&
+        hasVerbose(config.flags) &&
             console.debug('\nSent %O metric to events service (status: %O)', data.name, response.status, '\n');
         if (response.status !== 204) {
-            hasVerbose(config) &&
+            hasVerbose(config.flags) &&
                 console.debug('\nBad response from events service. Request body: %O', response.body.toString(), '\n');
         }
     }
     catch (e) {
-        hasVerbose(config) && console.debug('Telemetry request failed:', e);
+        hasVerbose(config.flags) && console.debug('Telemetry request failed:', e);
     }
 }
 /**
@@ -1338,7 +1610,7 @@ const taskBuild = async (coreCompiler, config, sys) => {
         const results = await compiler.build();
         // TODO(STENCIL-148) make this parameter no longer optional, remove the surrounding if statement
         if (sys) {
-            await telemetryBuildFinishedAction(sys, config, config.logger, coreCompiler, results);
+            await telemetryBuildFinishedAction(sys, config, coreCompiler, results);
         }
         await compiler.destroy();
         if (results.hasError) {
@@ -1377,6 +1649,7 @@ const IS_NODE_ENV = typeof global !== 'undefined' &&
     !!global.process &&
     typeof __filename === 'string' &&
     (!global.origin || typeof global.origin !== 'string');
+const IS_BROWSER_ENV = typeof location !== 'undefined' && typeof navigator !== 'undefined' && typeof XMLHttpRequest !== 'undefined';
 
 /**
  * Task to generate component boilerplate and write it to disk. This task can
@@ -1572,7 +1845,8 @@ export class ${toPascalCase(tagName)} {
 `;
 };
 /**
- * Get the boilerplate for style.
+ * Get the boilerplate for style for a generated component
+ * @returns a boilerplate CSS block
  */
 const getStyleUrlBoilerplate = () => `:host {
   display: block;
@@ -1626,10 +1900,17 @@ describe('${tagName}', () => {
  */
 const toPascalCase = (str) => str.split('-').reduce((res, part) => res + part[0].toUpperCase() + part.slice(1), '');
 
-const taskTelemetry = async (config, sys, logger) => {
+/**
+ * Entrypoint for the Telemetry task
+ * @param flags configuration flags provided to Stencil when a task was called (either this task or a task that invokes
+ * telemetry)
+ * @param sys the abstraction for interfacing with the operating system
+ * @param logger a logging implementation to log the results out to the user
+ */
+const taskTelemetry = async (flags, sys, logger) => {
     const prompt = logger.dim(sys.details.platform === 'windows' ? '>' : '$');
-    const isEnabling = config.flags.args.includes('on');
-    const isDisabling = config.flags.args.includes('off');
+    const isEnabling = flags.args.includes('on');
+    const isDisabling = flags.args.includes('off');
     const INFORMATION = `Opt in or our of telemetry. Information about the data we collect is available on our website: ${logger.bold('https://stenciljs.com/telemetry')}`;
     const THANK_YOU = `Thank you for helping to make Stencil better! 💖`;
     const ENABLED_MESSAGE = `${logger.green('Enabled')}. ${THANK_YOU}\n\n`;
@@ -1658,7 +1939,14 @@ const taskTelemetry = async (config, sys, logger) => {
   `);
 };
 
-const taskHelp = async (config, logger, sys) => {
+/**
+ * Entrypoint for the Help task, providing Stencil usage context to the user
+ * @param flags configuration flags provided to Stencil when a task was call (either this task or a task that invokes
+ * telemetry)
+ * @param logger a logging implementation to log the results out to the user
+ * @param sys the abstraction for interfacing with the operating system
+ */
+const taskHelp = async (flags, logger, sys) => {
     const prompt = logger.dim(sys.details.platform === 'windows' ? '>' : '$');
     console.log(`
   ${logger.bold('Build:')} ${logger.dim('Build components for development or production.')}
@@ -1691,7 +1979,7 @@ const taskHelp = async (config, logger, sys) => {
 `);
     // TODO(STENCIL-148) make this parameter no longer optional, remove the surrounding if statement
     if (sys) {
-        await taskTelemetry(config, sys, logger);
+        await taskTelemetry(flags, sys, logger);
     }
     console.log(`
   ${logger.bold('Examples:')}
@@ -1748,6 +2036,10 @@ const taskServe = async (config) => {
     });
 };
 
+/**
+ * Entrypoint for any Stencil tests
+ * @param config a validated Stencil configuration entity
+ */
 const taskTest = async (config) => {
     if (!IS_NODE_ENV) {
         config.logger.error(`"test" command is currently only implemented for a NodeJS environment`);
@@ -1794,6 +2086,95 @@ const taskTest = async (config) => {
     }
 };
 
+/**
+ * Creates an instance of a logger
+ * @returns the new logger instance
+ */
+const createLogger = () => {
+    let useColors = IS_BROWSER_ENV;
+    let level = 'info';
+    return {
+        enableColors: (uc) => (useColors = uc),
+        getLevel: () => level,
+        setLevel: (l) => (level = l),
+        emoji: (e) => e,
+        info: console.log.bind(console),
+        warn: console.warn.bind(console),
+        error: console.error.bind(console),
+        debug: console.debug.bind(console),
+        red: (msg) => msg,
+        green: (msg) => msg,
+        yellow: (msg) => msg,
+        blue: (msg) => msg,
+        magenta: (msg) => msg,
+        cyan: (msg) => msg,
+        gray: (msg) => msg,
+        bold: (msg) => msg,
+        dim: (msg) => msg,
+        bgRed: (msg) => msg,
+        createTimeSpan: (_startMsg, _debug = false) => ({
+            duration: () => 0,
+            finish: () => 0,
+        }),
+        printDiagnostics(diagnostics) {
+            diagnostics.forEach((diagnostic) => logDiagnostic(diagnostic, useColors));
+        },
+    };
+};
+const logDiagnostic = (diagnostic, useColors) => {
+    let color = BLUE;
+    let prefix = 'Build';
+    let msg = '';
+    if (diagnostic.level === 'error') {
+        color = RED;
+        prefix = 'Error';
+    }
+    else if (diagnostic.level === 'warn') {
+        color = YELLOW;
+        prefix = 'Warning';
+    }
+    if (diagnostic.header) {
+        prefix = diagnostic.header;
+    }
+    const filePath = diagnostic.relFilePath || diagnostic.absFilePath;
+    if (filePath) {
+        msg += filePath;
+        if (typeof diagnostic.lineNumber === 'number' && diagnostic.lineNumber > 0) {
+            msg += ', line ' + diagnostic.lineNumber;
+            if (typeof diagnostic.columnNumber === 'number' && diagnostic.columnNumber > 0) {
+                msg += ', column ' + diagnostic.columnNumber;
+            }
+        }
+        msg += '\n';
+    }
+    msg += diagnostic.messageText;
+    if (diagnostic.lines && diagnostic.lines.length > 0) {
+        diagnostic.lines.forEach((l) => {
+            msg += '\n' + l.lineNumber + ':  ' + l.text;
+        });
+        msg += '\n';
+    }
+    if (useColors) {
+        const styledPrefix = [
+            '%c' + prefix,
+            `background: ${color}; color: white; padding: 2px 3px; border-radius: 2px; font-size: 0.8em;`,
+        ];
+        console.log(...styledPrefix, msg);
+    }
+    else if (diagnostic.level === 'error') {
+        console.error(msg);
+    }
+    else if (diagnostic.level === 'warn') {
+        console.warn(msg);
+    }
+    else {
+        console.log(msg);
+    }
+};
+const YELLOW = `#f39c12`;
+const RED = `#c0392b`;
+const BLUE = `#3498db`;
+
 const run = async (init) => {
     const { args, logger, sys } = init;
     try {
@@ -1809,7 +2190,7 @@ const run = async (init) => {
             sys.applyGlobalPatch(sys.getCurrentDirectory());
         }
         if (task === 'help' || flags.help) {
-            await taskHelp({ flags: { task: 'help', args }, outputTargets: [] }, logger, sys);
+            await taskHelp({ task: 'help', args }, logger, sys);
             return;
         }
         startupLog(logger, task);
@@ -1835,7 +2216,7 @@ const run = async (init) => {
         startupLogVersion(logger, task, coreCompiler);
         loadedCompilerLog(sys, logger, flags, coreCompiler);
         if (task === 'info') {
-            await telemetryAction(sys, { flags: { task: 'info' }, outputTargets: [] }, logger, coreCompiler, async () => {
+            await telemetryAction(sys, { flags: { task: 'info' }, logger }, coreCompiler, async () => {
                 await taskInfo(coreCompiler, sys, logger);
             });
             return;
@@ -1858,7 +2239,7 @@ const run = async (init) => {
             sys.applyGlobalPatch(validated.config.rootDir);
         }
         await sys.ensureResources({ rootDir: validated.config.rootDir, logger, dependencies: dependencies });
-        await telemetryAction(sys, validated.config, logger, coreCompiler, async () => {
+        await telemetryAction(sys, validated.config, coreCompiler, async () => {
             await runTask(coreCompiler, validated.config, task, sys);
         });
     }
@@ -1871,43 +2252,45 @@ const run = async (init) => {
     }
 };
 const runTask = async (coreCompiler, config, task, sys) => {
-    config.flags = config.flags || { task };
-    config.outputTargets = config.outputTargets || [];
+    var _a, _b;
+    const logger = (_a = config.logger) !== null && _a !== void 0 ? _a : createLogger();
+    const strictConfig = { ...config, flags: (_b = { ...config.flags }) !== null && _b !== void 0 ? _b : { task }, logger };
+    strictConfig.outputTargets = strictConfig.outputTargets || [];
     switch (task) {
         case 'build':
-            await taskBuild(coreCompiler, config, sys);
+            await taskBuild(coreCompiler, strictConfig, sys);
             break;
         case 'docs':
-            await taskDocs(coreCompiler, config);
+            await taskDocs(coreCompiler, strictConfig);
             break;
         case 'generate':
         case 'g':
-            await taskGenerate(coreCompiler, config);
+            await taskGenerate(coreCompiler, strictConfig);
             break;
         case 'help':
-            await taskHelp(config, config.logger, sys);
+            await taskHelp(strictConfig.flags, strictConfig.logger, sys);
             break;
         case 'prerender':
-            await taskPrerender(coreCompiler, config);
+            await taskPrerender(coreCompiler, strictConfig);
             break;
         case 'serve':
-            await taskServe(config);
+            await taskServe(strictConfig);
             break;
         case 'telemetry':
             // TODO(STENCIL-148) make this parameter no longer optional, remove the surrounding if statement
             if (sys) {
-                await taskTelemetry(config, sys, config.logger);
+                await taskTelemetry(strictConfig.flags, sys, strictConfig.logger);
             }
             break;
         case 'test':
-            await taskTest(config);
+            await taskTest(strictConfig);
             break;
         case 'version':
             console.log(coreCompiler.version);
             break;
         default:
-            config.logger.error(`${config.logger.emoji('❌ ')}Invalid stencil command, please see the options below:`);
-            await taskHelp(config, config.logger, sys);
+            strictConfig.logger.error(`${strictConfig.logger.emoji('❌ ')}Invalid stencil command, please see the options below:`);
+            await taskHelp(strictConfig.flags, strictConfig.logger, sys);
             return config.sys.exit(1);
     }
 };