@stencil/core 2.17.0 → 2.17.2

package/cli/index.cjs

@@ -1,5 +1,5 @@
 /*!
- Stencil CLI (CommonJS) v2.17.0 | MIT Licensed | https://stenciljs.com
+ Stencil CLI (CommonJS) v2.17.2 | MIT Licensed | https://stenciljs.com
  */
 'use strict';
 
@@ -25,8 +25,50 @@ function _interopNamespace(e) {
     return Object.freeze(n);
 }
 
-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('');
@@ -299,174 +341,13 @@ const validateComponentTag = (tag) => {
     return undefined;
 };
 
-const parseFlags = (args, sys) => {
-    const flags = {
-        task: null,
-        args: [],
-        knownArgs: [],
-        unknownArgs: null,
-    };
-    // cmd line has more priority over npm scripts cmd
-    flags.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);
-    if (sys && sys.name === 'node') {
-        const envArgs = getNpmConfigEnvArgs(sys);
-        parseArgs(flags, envArgs, flags.knownArgs);
-        envArgs.forEach((envArg) => {
-            if (!flags.args.includes(envArg)) {
-                flags.args.push(envArg);
-            }
-        });
-    }
-    if (flags.task != null) {
-        const i = flags.args.indexOf(flags.task);
-        if (i > -1) {
-            flags.args.splice(i, 1);
-        }
-    }
-    flags.unknownArgs = flags.args.filter((arg) => {
-        return !flags.knownArgs.includes(arg);
-    });
-    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).
- *
- * @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;
-        }
-        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;
-        }
-        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]);
-                }
-            }
-        }
-    });
-    NUMBER_ARG_OPTS.forEach((numberName) => {
-        const alias = ARG_OPTS_ALIASES[numberName];
-        const flagKey = configCase(numberName);
-        if (typeof flags[flagKey] !== 'number') {
-            flags[flagKey] = null;
-        }
-        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 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]);
-                }
-            }
-        }
-    });
-};
-const configCase = (prop) => {
-    prop = dashToPascalCase(prop);
-    return prop.charAt(0).toLowerCase() + prop.slice(1);
-};
-const BOOLEAN_ARG_OPTS = [
+ * All the Boolean options supported by the Stencil CLI
+ */
+const BOOLEAN_CLI_ARGS = [
     'build',
     'cache',
-    'check-version',
+    'checkVersion',
     'ci',
     'compare',
     'debug',
@@ -481,58 +362,474 @@ const BOOLEAN_ARG_OPTS = [
     'log',
     'open',
     'prerender',
-    'prerender-external',
+    'prerenderExternal',
     'prod',
     'profile',
-    'service-worker',
+    'serviceWorker',
     'screenshot',
     'serve',
-    'skip-node-check',
+    'skipNodeCheck',
     'spec',
     'ssr',
     'stats',
-    'update-screenshot',
+    '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',
 ];
-const NUMBER_ARG_OPTS = ['max-workers', 'port'];
-const STRING_ARG_OPTS = [
+/**
+ * All the String options supported by the Stencil CLI
+ */
+const STRING_CLI_ARGS = [
     'address',
     'config',
-    'docs-json',
+    'docsApi',
+    'docsJson',
     'emulate',
-    'log-level',
     'root',
-    'screenshot-connector',
+    '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',
 ];
-const ARG_OPTS_ALIASES = {
+/**
+ * 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',
 };
-const getNpmConfigEnvArgs = (sys) => {
-    // process.env.npm_config_argv
-    // {"remain":["4444"],"cooked":["run","serve","--port","4444"],"original":["run","serve","--port","4444"]}
-    let args = [];
-    try {
-        const npmConfigArgs = sys.getEnvironmentVar('npm_config_argv');
-        if (npmConfigArgs) {
-            args = JSON.parse(npmConfigArgs).original;
-            if (args[0] === 'run') {
-                args = args.slice(2);
-            }
+/**
+ * Helper function for initializing a `ConfigFlags` object. Provide any overrides
+ * for default values and off you go!
+ *
+ * @param init an object with any overrides for default values
+ * @returns a complete CLI flag object
+ */
+const createConfigFlags = (init = {}) => {
+    const flags = {
+        task: null,
+        args: [],
+        knownArgs: [],
+        unknownArgs: [],
+        ...init,
+    };
+    return flags;
+};
+
+/**
+ * Parse command line arguments into a structured `ConfigFlags` object
+ *
+ * @param args an array of CLI flags
+ * @param _sys an optional compiler system
+ * @returns a structured ConfigFlags object
+ */
+const parseFlags = (args, _sys) => {
+    // TODO(STENCIL-509): remove the _sys parameter here ^^ (for v3)
+    const flags = createConfigFlags();
+    // cmd line has more priority over npm scripts cmd
+    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);
+    if (flags.task != null) {
+        const i = flags.args.indexOf(flags.task);
+        if (i > -1) {
+            flags.args.splice(i, 1);
         }
     }
-    catch (e) { }
-    return args;
+    // to find unknown / unrecognized arguments we filter `args`, including only
+    // arguments whose normalized form is not found in `knownArgs`. `knownArgs`
+    // is populated during the call to `parseArgs` above. For arguments like
+    // `--foobar` the string `"--foobar"` will be added, while for more
+    // complicated arguments like `--bizBoz=bop` or `--bizBoz bop` just the
+    // string `"--bizBoz"` will be added.
+    flags.unknownArgs = flags.args.filter((arg) => !flags.knownArgs.includes(parseEqualsArg(arg)[0]));
+    return flags;
 };
+/**
+ * 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 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;
+        }
+        else if (cmdArg === `--no-${dashCaseName}` || cmdArg === `--no${dashToPascalCase(dashCaseName)}`) {
+            value = false;
+        }
+        else if (alias && cmdArg === `-${alias}`) {
+            value = true;
+        }
+        if (value !== undefined && cmdArg !== undefined) {
+            flags[configCaseName] = value;
+            flags.knownArgs.push(cmdArg);
+        }
+    });
+};
+/**
+ * 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;
+        }
+        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}=`)) {
+            // our argument was passed at the command-line in the format --argName=arg-value
+            [matchingArg, value] = parseEqualsArg(arg);
+        }
+        else if (arg === `--${dashCaseName}` || arg === `--${configCaseName}`) {
+            // the next value in the array is assumed to be a value for this argument
+            value = args[i + 1];
+            matchingArg = arg;
+        }
+        else if (alias) {
+            if (arg.startsWith(`-${alias}=`)) {
+                [matchingArg, value] = parseEqualsArg(arg);
+            }
+            else if (arg === `-${alias}`) {
+                value = args[i + 1];
+                matchingArg = arg;
+            }
+        }
+    });
+    return { value, matchingArg };
+};
+/**
+ * Parse an 'equals' argument, which is a CLI argument-value pair in the
+ * format `--foobar=12` (as opposed to a space-separated format like
+ * `--foobar 12`).
+ *
+ * To parse this we split on the `=`, returning the first part as the argument
+ * name and the second part as the value. We join the value on `"="` in case
+ * there is another `"="` in the argument.
+ *
+ * This function is safe to call with any arg, and can therefore be used as
+ * an argument 'normalizer'. If CLI argument is not an 'equals' argument then
+ * the return value will be a tuple of the original argument and an empty
+ * string `""` for the value.
+ *
+ * In code terms, if you do:
+ *
+ * ```ts
+ * const [arg, value] = parseEqualsArg("--myArgument")
+ * ```
+ *
+ * Then `arg` will be `"--myArgument"` and `value` will be `""`, whereas if
+ * you do:
+ *
+ *
+ * ```ts
+ * const [arg, value] = parseEqualsArg("--myArgument=myValue")
+ * ```
+ *
+ * Then `arg` will be `"--myArgument"` and `value` will be `"myValue"`.
+ *
+ * @param arg the arg in question
+ * @returns a tuple containing the arg name and the value (if present)
+ */
+const parseEqualsArg = (arg) => {
+    const [originalArg, ...value] = arg.split('=');
+    return [originalArg, value.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 dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.17.0",
+		version: "2.17.2",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",
@@ -857,12 +1154,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;
 };
@@ -887,19 +1183,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);
 }
 
 /**
@@ -910,7 +1206,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;
@@ -981,11 +1277,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;
@@ -993,21 +1288,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) {
@@ -1027,11 +1320,20 @@ 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;
     }
 }
+/**
+ * Helper function to determine if a Stencil configuration builds an application.
+ *
+ * This function is a rough approximation whether an application is generated as a part of a Stencil build, based on
+ * contents of the project's `stencil.config.ts` file.
+ *
+ * @param config the configuration used by the Stencil project
+ * @returns true if we believe the project generates an application, false otherwise
+ */
 function hasAppTarget(config) {
     return config.outputTargets.some((target) => target.type === WWW && (!!target.serviceWorker || (!!target.baseUrl && target.baseUrl !== '/')));
 }
@@ -1039,7 +1341,15 @@ function isUsingYarn(sys) {
     var _a;
     return ((_a = sys.getEnvironmentVar('npm_execpath')) === null || _a === void 0 ? void 0 : _a.includes('yarn')) || false;
 }
-async function getActiveTargets(config) {
+/**
+ * Build a list of the different types of output targets used in a Stencil configuration.
+ *
+ * Duplicate entries will not be returned from the list
+ *
+ * @param config the configuration used by the Stencil project
+ * @returns a unique list of output target types found in the Stencil configuration
+ */
+function getActiveTargets(config) {
     const result = config.outputTargets.map((t) => t.type);
     return Array.from(new Set(result));
 }
@@ -1056,7 +1366,7 @@ async function getActiveTargets(config) {
 const prepareData = async (coreCompiler, config, sys, duration_ms, component_count = undefined) => {
     const { typescript, rollup } = coreCompiler.versions || { typescript: 'unknown', rollup: 'unknown' };
     const { packages, packagesNoVersions } = await getInstalledPackages(sys, config);
-    const targets = await getActiveTargets(config);
+    const targets = getActiveTargets(config);
     const yarn = isUsingYarn(sys);
     const stencil = coreCompiler.version || 'unknown';
     const system = `${sys.name} ${sys.version}`;
@@ -1119,14 +1429,13 @@ const CONFIG_PROPS_TO_DELETE = ['sys', 'logger', 'tsCompilerOptions', 'devServer
  * @returns an anonymized copy of the same config
  */
 const anonymizeConfigForTelemetry = (config) => {
-    var _a;
     const anonymizedConfig = { ...config };
     for (const prop of CONFIG_PROPS_TO_ANONYMIZE) {
         if (anonymizedConfig[prop] !== undefined) {
             anonymizedConfig[prop] = 'omitted';
         }
     }
-    anonymizedConfig.outputTargets = ((_a = config.outputTargets) !== null && _a !== void 0 ? _a : []).map((target) => {
+    anonymizedConfig.outputTargets = config.outputTargets.map((target) => {
         // Anonymize the outputTargets on our configuration, taking advantage of the
         // optional 2nd argument to `JSON.stringify`. If anything is not a string
         // we retain it so that any nested properties are handled, else we check
@@ -1195,7 +1504,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 };
     }
 }
@@ -1297,15 +1606,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);
     }
 }
 /**
@@ -1347,7 +1656,7 @@ function getMajorVersion(version) {
     return parts[0];
 }
 
-const taskBuild = async (coreCompiler, config, sys) => {
+const taskBuild = async (coreCompiler, config) => {
     if (config.flags.watch) {
         // watch build
         await taskWatch(coreCompiler, config);
@@ -1360,10 +1669,7 @@ const taskBuild = async (coreCompiler, config, sys) => {
         const versionChecker = startCheckVersion(config, coreCompiler.version);
         const compiler = await coreCompiler.createCompiler(config);
         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(config.sys, config, coreCompiler, results);
         await compiler.destroy();
         if (results.hasError) {
             exitCode = 1;
@@ -1401,6 +1707,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
@@ -1596,7 +1903,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;
@@ -1650,10 +1958,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`;
@@ -1682,7 +1997,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.')}
@@ -1713,10 +2035,7 @@ const taskHelp = async (config, logger, sys) => {
     ${prompt} ${logger.green('stencil generate')} or ${logger.green('stencil g')}
 
 `);
-    // 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:')}
 
@@ -1772,6 +2091,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`);
@@ -1818,10 +2141,99 @@ 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 {
-        const flags = parseFlags(args, sys);
+        const flags = parseFlags(args);
         const task = flags.task;
         if (flags.debug || flags.verbose) {
             logger.setLevel('debug');
@@ -1833,7 +2245,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(createConfigFlags({ task: 'help', args }), logger, sys);
             return;
         }
         startupLog(logger, task);
@@ -1859,9 +2271,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 taskInfo(coreCompiler, sys, logger);
-            });
+            taskInfo(coreCompiler, sys, logger);
             return;
         }
         const validated = await coreCompiler.loadConfig({
@@ -1882,7 +2292,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);
         });
     }
@@ -1894,44 +2304,56 @@ const run = async (init) => {
         }
     }
 };
+/**
+ * Run a specified task
+ * @param coreCompiler an instance of a minimal, bootstrap compiler for running the specified task
+ * @param config a configuration for the Stencil project to apply to the task run
+ * @param task the task to run
+ * @param sys the {@link CompilerSystem} for interacting with the operating system
+ * @public
+ */
 const runTask = async (coreCompiler, config, task, sys) => {
-    config.flags = config.flags || { task };
-    config.outputTargets = config.outputTargets || [];
+    var _a, _b, _c;
+    const logger = (_a = config.logger) !== null && _a !== void 0 ? _a : createLogger();
+    const strictConfig = {
+        ...config,
+        flags: createConfigFlags((_b = config.flags) !== null && _b !== void 0 ? _b : { task }),
+        logger,
+        outputTargets: (_c = config.outputTargets) !== null && _c !== void 0 ? _c : [],
+        sys: sys !== null && sys !== void 0 ? sys : coreCompiler.createSystem({ logger }),
+    };
     switch (task) {
         case 'build':
-            await taskBuild(coreCompiler, config, sys);
+            await taskBuild(coreCompiler, strictConfig);
             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);
     }
 };