@stencil/core 2.17.2-0 → 2.17.4

package/compiler/stencil.js

@@ -1,5 +1,5 @@
 /*!
- Stencil Compiler v2.17.2-0 | MIT Licensed | https://stenciljs.com
+ Stencil Compiler v2.17.4 | MIT Licensed | https://stenciljs.com
  */
 (function(exports) {
 'use strict';
@@ -898,24 +898,37 @@ const buildWarn = (diagnostics) => {
   diagnostics.push(diagnostic);
   return diagnostic;
 };
-const buildJsonFileError = (compilerCtx, diagnostics, jsonFilePath, msg, pkgKey) => {
+/**
+ * Create a diagnostic message suited for representing an error in a JSON
+ * file. This includes information about the exact lines in the JSON file which
+ * caused the error and the path to the file.
+ *
+ * @param compilerCtx the current compiler context
+ * @param diagnostics a list of diagnostics used as a return param
+ * @param jsonFilePath the path to the JSON file where the error occurred
+ * @param msg the error message
+ * @param jsonField the key for the field which caused the error, used for finding
+ * the error line in the original JSON file
+ * @returns a reference to the newly-created diagnostic
+ */
+const buildJsonFileError = (compilerCtx, diagnostics, jsonFilePath, msg, jsonField) => {
   const err = buildError(diagnostics);
   err.messageText = msg;
   err.absFilePath = jsonFilePath;
-  if (typeof pkgKey === 'string') {
+  if (typeof jsonField === 'string') {
     try {
       const jsonStr = compilerCtx.fs.readFileSync(jsonFilePath);
       const lines = jsonStr.replace(/\r/g, '\n').split('\n');
       for (let i = 0; i < lines.length; i++) {
         const txtLine = lines[i];
-        const txtIndex = txtLine.indexOf(pkgKey);
+        const txtIndex = txtLine.indexOf(jsonField);
         if (txtIndex > -1) {
           const warnLine = {
             lineIndex: i,
             lineNumber: i + 1,
             text: txtLine,
             errorCharStart: txtIndex,
-            errorLength: pkgKey.length,
+            errorLength: jsonField.length,
           };
           err.lineNumber = warnLine.lineNumber;
           err.columnNumber = txtIndex + 1;
@@ -4052,7 +4065,7 @@ const createCustomResolverAsync = (sys, inMemoryFs, exts) => {
   };
 };
 
-const buildId = '20220719192625';
+const buildId = '20220822163920';
 const minfyJsId = 'terser5.6.1_7';
 const optimizeCssId = 'autoprefixer10.2.5_postcss8.2.13_7';
 const parse5Version = '6.0.1';
@@ -4060,8 +4073,8 @@ const rollupVersion = '2.42.3';
 const sizzleVersion = '2.42.3';
 const terserVersion = '5.6.1';
 const typescriptVersion = '4.5.4';
-const vermoji = '🏜';
-const version$3 = '2.17.2-0';
+const vermoji = '🐞';
+const version$3 = '2.17.4';
 const versions = {
   stencil: version$3,
   parse5: parse5Version,
@@ -11509,6 +11522,20 @@ const scopeCss = (cssText, scopeId, commentOriginalSelector) => {
   return cssText;
 };
 
+/**
+ * Serialize data about a style import to an annotated path, where
+ * the filename has a URL queryparams style string appended to it.
+ * This could look like:
+ *
+ * ```
+ * './some-file.CSS?tag=my-tag&mode=ios&encapsulation=scoped');
+ * ```
+ *
+ * @param data import data to be serialized
+ * @param styleImportData an argument which controls whether the import data
+ * will be added to the path (formatted as queryparams)
+ * @returns a formatted string
+ */
 const serializeImportPath = (data, styleImportData) => {
   let p = data.importeePath;
   if (isString$1(p)) {
@@ -11539,6 +11566,13 @@ const serializeImportPath = (data, styleImportData) => {
   }
   return p;
 };
+/**
+ * Parse import paths (filepaths possibly annotated w/ component metadata,
+ * formatted as URL queryparams) into a structured format.
+ *
+ * @param importPath an annotated import path to examine
+ * @returns formatted information about the import
+ */
 const parseImportPath = (importPath) => {
   const parsedPath = {
     importPath,
@@ -16288,6 +16322,9 @@ class MockElement extends MockNode {
   set title(value) {
     this.setAttributeNS(null, 'title', value);
   }
+  animate() {
+    /**/
+  }
   onanimationstart() {
     /**/
   }
@@ -16552,6 +16589,18 @@ class MockElement extends MockNode {
   onwheel() {
     /**/
   }
+  requestFullscreen() {
+    /**/
+  }
+  scrollBy() {
+    /**/
+  }
+  scrollTo() {
+    /**/
+  }
+  scrollIntoView() {
+    /**/
+  }
   toString(opts) {
     return serializeNodeToHtml(this, opts);
   }
@@ -41339,29 +41388,73 @@ const formatUrl = (config, pluginCtx, code, filePath, ext) => {
   return `const ${varName} = 'data:${mime};base64,${base64}';export default ${varName};`;
 };
 
+/**
+ * A Rollup plugin which bundles up some transformation of CSS imports as well
+ * as writing some files to disk for the `DIST_COLLECTION` output target.
+ *
+ * @param config a user-supplied configuration
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param bundleOpts bundle options for Rollup
+ * @returns a Rollup plugin which carries out the necessary work
+ */
 const extTransformsPlugin = (config, compilerCtx, buildCtx, bundleOpts) => {
   return {
     name: 'extTransformsPlugin',
+    /**
+     * A custom function targeting the `transform` build hook in Rollup. See here for details:
+     * https://rollupjs.org/guide/en/#transform
+     *
+     * Here we are ignoring the first argument (which contains the module's source code) and
+     * only looking at the `id` argument. We use that `id` to get information about the module
+     * in question from disk ourselves so that we can then do some transformations on it.
+     *
+     * @param _ an unused parameter (normally the code for a given module)
+     * @param id the id of a module
+     * @returns metadata for Rollup or null if no transformation should be done
+     */
     async transform(_, id) {
+      var _a, _b;
       if (/\0/.test(id)) {
         return null;
       }
+      // The `id` here was possibly previously updated using
+      // `serializeImportPath` to annotate the filepath with various metadata
+      // serialized to query-params. If that was done for this particular `id`
+      // then the `data` prop will not be null.
       const { data } = parseImportPath(id);
       if (data != null) {
-        let cmp;
+        let cmp = undefined;
         const filePath = normalizeFsPath(id);
         const code = await compilerCtx.fs.readFile(filePath);
         if (typeof code !== 'string') {
           return null;
         }
         const pluginTransforms = await runPluginTransformsEsmImports(config, compilerCtx, buildCtx, code, filePath);
-        const commentOriginalSelector = bundleOpts.platform === 'hydrate' && data.encapsulation === 'shadow';
+        // We need to check whether the current build is a dev-mode watch build w/ HMR enabled in
+        // order to know how we'll want to set `commentOriginalSelector` (below). If we are doing
+        // a hydrate build we need to set this to `true` because commenting-out selectors is what
+        // gives us support for scoped CSS w/ hydrated components (we don't support shadow DOM and
+        // styling via that route for them). However, we don't want to comment selectors in dev
+        // mode when using HMR in the browser, since there we _do_ support putting stylesheets into
+        // the shadow DOM and commenting out e.g. the `:host` selector in those stylesheets will
+        // break components' CSS when an HMR update is sent to the browser.
+        //
+        // See https://github.com/ionic-team/stencil/issues/3461 for details
+        const isDevWatchHMRBuild = config.flags.watch &&
+          config.flags.dev &&
+          config.flags.serve &&
+          ((_b = (_a = config.devServer) === null || _a === void 0 ? void 0 : _a.reloadStrategy) !== null && _b !== void 0 ? _b : null) === 'hmr';
+        const commentOriginalSelector = bundleOpts.platform === 'hydrate' && data.encapsulation === 'shadow' && !isDevWatchHMRBuild;
         if (data.tag) {
           cmp = buildCtx.components.find((c) => c.tagName === data.tag);
           const moduleFile = cmp && compilerCtx.moduleMap.get(cmp.sourceFilePath);
           if (moduleFile) {
             const collectionDirs = config.outputTargets.filter(isOutputTargetDistCollection);
             const relPath = relative$1(config.srcDir, pluginTransforms.id);
+            // If we found a `moduleFile` in the module map above then we
+            // should write the transformed CSS file (found in the return value
+            // of `runPluginTransformsEsmImports`, above) to disk.
             await Promise.all(collectionDirs.map(async (outputTarget) => {
               const collectionPath = join(outputTarget.collectionDir, relPath);
               await compilerCtx.fs.writeFile(collectionPath, pluginTransforms.code);
@@ -54609,6 +54702,23 @@ const isMemberPrivate = (member) => {
   }
   return false;
 };
+/**
+ * Convert a JavaScript value to the TypeScript Intermediate Representation
+ * (IR) for a literal Abstract Syntax Tree (AST) node with that same value. The
+ * value to convert may be a primitive type like `string`, `boolean`, etc or
+ * may be an `Object`, `Array`, etc.
+ *
+ * Note that this function takes a param (`refs`) with a default value,
+ * normally a value should _not_ be passed for this parameter since it is
+ * intended to be used for recursive calls.
+ *
+ * @param val the value to convert
+ * @param refs a set of references, used in recursive calls to avoid
+ * circular references when creating object literal IR instances. **note that
+ * you shouldn't pass this parameter unless you know what you're doing!**
+ * @returns TypeScript IR for a literal corresponding to the JavaScript value
+ * with which the function was called
+ */
 const convertValueToLiteral = (val, refs = null) => {
   if (refs == null) {
     refs = new WeakSet();
@@ -54639,12 +54749,39 @@ const convertValueToLiteral = (val, refs = null) => {
   }
   return t.createLiteral(val);
 };
+/**
+ * Convert a JavaScript Array instance to TypeScript's Intermediate
+ * Representation (IR) for an array literal. This is done by recursively using
+ * {@link convertValueToLiteral} to create a new array consisting of the
+ * TypeScript IR of each element in the array to be converted, and then creating
+ * the TypeScript IR for _that_ array.
+ *
+ * @param list the array instance to convert
+ * @param refs a set of references to objects, used when converting objects to
+ * avoid circular references
+ * @returns TypeScript IR for the array we want to convert
+ */
 const arrayToArrayLiteral = (list, refs) => {
   const newList = list.map((l) => {
     return convertValueToLiteral(l, refs);
   });
   return t.createArrayLiteral(newList);
 };
+/**
+ * Convert a JavaScript object (i.e. an object existing at runtime) to the
+ * corresponding TypeScript Intermediate Representation (IR)
+ * ({@see ts.ObjectLiteralExpression}) for an object literal. This function
+ * takes an argument holding a `WeakSet` of references to objects which is
+ * used to avoid circular references. Objects that are converted in this
+ * function are added to the set, and if an object is already present then an
+ * `undefined` literal (in TypeScript IR) is returned instead of another
+ * object literal, as continuing to convert a circular reference would, well,
+ * never end!
+ *
+ * @param obj the JavaScript object to convert to TypeScript IR
+ * @param refs a set of references to objects, used to avoid circular references
+ * @returns a TypeScript object literal expression
+ */
 const objectToObjectLiteral = (obj, refs) => {
   if (refs.has(obj)) {
     return t.createIdentifier('undefined');
@@ -56012,17 +56149,16 @@ const KEEP_IMPORTS = new Set([
  * which do actual work of generating the rollup configuration, creating an
  * entry chunk, running, the build, etc.
  *
- * @param config the user-supplied compiler configuration we're using
+ * @param config the validated compiler configuration we're using
  * @param compilerCtx the current compiler context
  * @param buildCtx the current build context
  * @returns an empty Promise which won't resolve until the work is done!
  */
 const outputCustomElements = async (config, compilerCtx, buildCtx) => {
-  var _a;
   if (!config.buildDist) {
     return;
   }
-  const outputTargets = ((_a = config.outputTargets) !== null && _a !== void 0 ? _a : []).filter(isOutputTargetDistCustomElements);
+  const outputTargets = config.outputTargets.filter(isOutputTargetDistCustomElements);
   if (outputTargets.length === 0) {
     return;
   }
@@ -56035,7 +56171,7 @@ const outputCustomElements = async (config, compilerCtx, buildCtx) => {
  * Get bundle options for our current build and compiler context which we'll use
  * to generate a Rollup build and so on.
  *
- * @param config user-supplied Stencil configuration
+ * @param config a validated Stencil configuration object
  * @param buildCtx the current build context
  * @param compilerCtx the current compiler context
  * @param outputTarget the outputTarget we're currently dealing with
@@ -56066,9 +56202,10 @@ const getBundleOptions = (config, buildCtx, compilerCtx, outputTarget) => ({
 /**
  * Get bundle options for rollup, run the rollup build, optionally minify the
  * output, and write files to disk.
- * @param config user-supplied Stencil configuration
- * @param buildCtx the current build context
+ *
+ * @param config the validated Stencil configuration we're using
  * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
  * @param outputTarget the outputTarget we're currently dealing with
  * @returns an empty promise
  */
@@ -57113,13 +57250,13 @@ const generateReadmeDocs = async (config, compilerCtx, docsData, outputTargets)
   }
   const strictCheck = readmeOutputTargets.some((o) => o.strict);
   if (strictCheck) {
-    strickCheckDocs(config, docsData);
+    strictCheckDocs(config, docsData);
   }
   await Promise.all(docsData.components.map((cmpData) => {
     return generateReadme(config, compilerCtx, readmeOutputTargets, cmpData, docsData.components);
   }));
 };
-const strickCheckDocs = (config, docsData) => {
+const strictCheckDocs = (config, docsData) => {
   docsData.components.forEach((component) => {
     component.props.forEach((prop) => {
       if (!prop.docs && prop.deprecation === undefined) {
@@ -60192,8 +60329,7 @@ const relDts$1 = (fromPath, dtsPath) => {
  * @param typesDir the path to the directory where type declarations are saved
  */
 const generateCustomElementsTypes = async (config, compilerCtx, buildCtx, typesDir) => {
-  var _a;
-  const outputTargets = ((_a = config.outputTargets) !== null && _a !== void 0 ? _a : []).filter(isOutputTargetDistCustomElements);
+  const outputTargets = config.outputTargets.filter(isOutputTargetDistCustomElements);
   await Promise.all(outputTargets.map((outputTarget) => generateCustomElementsTypesOutput(config, compilerCtx, buildCtx, typesDir, outputTarget)));
 };
 /**
@@ -62128,6 +62264,16 @@ const parseModuleImport = (config, compilerCtx, buildCtx, moduleFile, dirPath, i
   }
 };
 
+/**
+ * Update an instance of TypeScript's Intermediate Representation (IR) for a
+ * class declaration ({@link ts.ClassDeclaration}) with a static getter for the
+ * compiler metadata that we produce as part of the compilation process.
+ *
+ * @param cmpNode an instance of the TypeScript IR for a class declaration (i.e.
+ * a stencil component) to be updated
+ * @param cmpMeta the component metadata corresponding to that component
+ * @returns the updated typescript class declaration
+ */
 const addComponentMetaStatic = (cmpNode, cmpMeta) => {
   const publicCompilerMeta = getPublicCompilerMeta(cmpMeta);
   const cmpMetaStaticProp = createStaticGetter('COMPILER_META', convertValueToLiteral(publicCompilerMeta));
@@ -62259,6 +62405,14 @@ const parseStaticEvents = (staticMembers) => {
   });
 };
 
+/**
+ * Parse a list of {@link ts.ClassElement} objects representing static props
+ * into a list of our own Intermediate Representation (IR) of properties on
+ * components.
+ *
+ * @param staticMembers TypeScript IR for the properties on our component
+ * @returns a manifest of compiler properties in our own Stencil IR
+ */
 const parseStaticProps = (staticMembers) => {
   const parsedProps = getStaticValue(staticMembers, 'properties');
   if (!parsedProps) {
@@ -62495,7 +62649,22 @@ const setComponentBuildConditionals = (cmpMeta) => {
     !cmpMeta.hasMember && !cmpMeta.hasStyle && !cmpMeta.hasLifecycle && !cmpMeta.hasListener && !cmpMeta.hasVdomRender;
 };
 
-const parseStaticComponentMeta = (compilerCtx, typeChecker, cmpNode, moduleFile, nodeMap, transformOpts) => {
+/**
+ * Given an instance of TypeScript's Intermediate Representation (IR) for a
+ * class declaration ({@see ts.ClassDeclaration}) which represents a Stencil
+ * component class declaration, parse and format various pieces of data about
+ * static class members which we use in the compilation process
+ *
+ * @param compilerCtx the current compiler context
+ * @param typeChecker a TypeScript type checker instance
+ * @param cmpNode the TypeScript class declaration for the component
+ * @param moduleFile Stencil's IR for a module, used here as an out param
+ * @param transformOpts options which control various aspects of the
+ * transformation
+ * @returns the TypeScript class declaration IR instance with which the
+ * function was called
+ */
+const parseStaticComponentMeta = (compilerCtx, typeChecker, cmpNode, moduleFile, transformOpts) => {
   if (cmpNode.members == null) {
     return cmpNode;
   }
@@ -62612,7 +62781,7 @@ const parseStaticComponentMeta = (compilerCtx, typeChecker, cmpNode, moduleFile,
   // add to module map
   moduleFile.cmps.push(cmp);
   // add to node map
-  nodeMap.set(cmpNode, cmp);
+  compilerCtx.nodeMap.set(cmpNode, cmp);
   return cmpNode;
 };
 const parseVirtualProps = (docs) => {
@@ -62680,7 +62849,7 @@ const updateModule = (config, compilerCtx, buildCtx, tsSourceFile, sourceFileTex
   compilerCtx.changedModules.add(moduleFile.sourceFilePath);
   const visitNode = (node) => {
     if (t.isClassDeclaration(node)) {
-      parseStaticComponentMeta(compilerCtx, typeChecker, node, moduleFile, compilerCtx.nodeMap);
+      parseStaticComponentMeta(compilerCtx, typeChecker, node, moduleFile);
       return;
     }
     else if (t.isImportDeclaration(node)) {
@@ -62841,6 +63010,15 @@ const outputServiceWorkers = async (config, buildCtx) => {
   }
 };
 
+/**
+ * Validate the package.json file for a project, checking that various fields
+ * are set correctly for the currently-configured output targets.
+ *
+ * @param config the user-supplied Stencil config
+ * @param compilerCtx the compiler context
+ * @param buildCtx the build context
+ * @returns an empty Promise
+ */
 const validateBuildPackageJson = async (config, compilerCtx, buildCtx) => {
   if (config.watch) {
     return;
@@ -62848,26 +63026,41 @@ const validateBuildPackageJson = async (config, compilerCtx, buildCtx) => {
   if (buildCtx.packageJson == null) {
     return;
   }
-  const outputTargets = config.outputTargets.filter(isOutputTargetDistCollection);
+  const distCollectionOutputTargets = config.outputTargets.filter(isOutputTargetDistCollection);
   const typesOutputTargets = config.outputTargets.filter(isOutputTargetDistTypes);
   await Promise.all([
-    ...outputTargets.map((outputsTarget) => {
-      return validatePackageJsonOutput(config, compilerCtx, buildCtx, outputsTarget);
-    }),
-    ...typesOutputTargets.map((outputTarget) => {
-      return validateTypes(config, compilerCtx, buildCtx, outputTarget);
-    }),
+    ...distCollectionOutputTargets.map((distCollectionOT) => validateDistCollectionPkgJson(config, compilerCtx, buildCtx, distCollectionOT)),
+    ...typesOutputTargets.map((typesOT) => validateTypes(config, compilerCtx, buildCtx, typesOT)),
+    validateModule(config, compilerCtx, buildCtx),
   ]);
 };
-const validatePackageJsonOutput = async (config, compilerCtx, buildCtx, outputTarget) => {
+/**
+ * Validate package.json contents for the `DIST_COLLECTION` output target,
+ * checking that various fields like `files`, `main`, and so on are set
+ * correctly.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param outputTarget a DIST_COLLECTION output target
+ */
+const validateDistCollectionPkgJson = async (config, compilerCtx, buildCtx, outputTarget) => {
   await Promise.all([
     validatePackageFiles(config, compilerCtx, buildCtx, outputTarget),
     validateMain(config, compilerCtx, buildCtx, outputTarget),
-    validateModule(config, compilerCtx, buildCtx, outputTarget),
     validateCollection$1(config, compilerCtx, buildCtx, outputTarget),
     validateBrowser(config, compilerCtx, buildCtx),
   ]);
 };
+/**
+ * Validate that the `files` field in `package.json` contains directories and
+ * files that are necessary for the `DIST_COLLECTION` output target.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param outputTarget a DIST_COLLECTION output target
+ */
 const validatePackageFiles = async (config, compilerCtx, buildCtx, outputTarget) => {
   if (!config.devMode && Array.isArray(buildCtx.packageJson.files)) {
     const actualDistDir = normalizePath$1(relative$1(config.rootDir, outputTarget.dir));
@@ -62891,6 +63084,15 @@ const validatePackageFiles = async (config, compilerCtx, buildCtx, outputTarget)
     }));
   }
 };
+/**
+ * Check that the `main` field is set correctly in `package.json` for the
+ * `DIST_COLLECTION` output target.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param outputTarget a DIST_COLLECTION output target
+ */
 const validateMain = (config, compilerCtx, buildCtx, outputTarget) => {
   const mainAbs = join(outputTarget.dir, 'index.cjs.js');
   const mainRel = relative$1(config.rootDir, mainAbs);
@@ -62903,26 +63105,71 @@ const validateMain = (config, compilerCtx, buildCtx, outputTarget) => {
     packageJsonWarn(config, compilerCtx, buildCtx, msg, `"main"`);
   }
 };
-const validateModule = (config, compilerCtx, buildCtx, outputTarget) => {
-  const customElementsOutput = config.outputTargets.find(isOutputTargetDistCustomElementsBundle);
+/**
+ * Validate the package.json 'module' field, taking into account output targets
+ * and other configuration details. This will look for a value for the `module`
+ * field. If not present it will set a relevant warning message with an
+ * output-target specific recommended value. If it is present and is not equal
+ * to that recommended value it will set a different warning message.
+ *
+ * @param config the current user-supplied configuration
+ * @param compilerCtx the compiler context
+ * @param buildCtx the build context
+ * @returns an empty Promise
+ */
+const validateModule = async (config, compilerCtx, buildCtx) => {
   const currentModule = buildCtx.packageJson.module;
-  const distAbs = join(outputTarget.dir, 'index.js');
-  const distRel = relative$1(config.rootDir, distAbs);
-  let recommendedRelPath = distRel;
-  if (customElementsOutput) {
-    const customElementsAbs = join(customElementsOutput.dir, 'index.js');
-    recommendedRelPath = relative$1(config.rootDir, customElementsAbs);
-  }
+  const recommendedRelPath = recommendedModulePath(config);
   if (!isString$1(currentModule)) {
-    const msg = `package.json "module" property is required when generating a distribution. It's recommended to set the "module" property to: ${recommendedRelPath}`;
+    let msg = 'package.json "module" property is required when generating a distribution.';
+    if (recommendedRelPath !== null) {
+      msg += ` It's recommended to set the "module" property to: ${normalizePath$1(recommendedRelPath)}`;
+    }
     packageJsonWarn(config, compilerCtx, buildCtx, msg, `"module"`);
+    return;
   }
-  else if (normalizePath$1(currentModule) !== normalizePath$1(recommendedRelPath) &&
-    normalizePath$1(currentModule) !== normalizePath$1(distRel)) {
-    const msg = `package.json "module" property is set to "${currentModule}". It's recommended to set the "module" property to: ${recommendedRelPath}`;
+  if (recommendedRelPath !== null && normalizePath$1(recommendedRelPath) !== normalizePath$1(currentModule)) {
+    const msg = `package.json "module" property is set to "${currentModule}". It's recommended to set the "module" property to: ${normalizePath$1(recommendedRelPath)}`;
     packageJsonWarn(config, compilerCtx, buildCtx, msg, `"module"`);
   }
 };
+// TODO(STENCIL-516): Investigate the hierarchy of these output targets
+/**
+ * Get the recommended `"module"` path for `package.json` given the output
+ * targets that a user has set on their config.
+ *
+ * @param config the user-supplied Stencil configuration
+ * @returns a recommended module path or a null value to indicate no default
+ * value is supplied
+ */
+function recommendedModulePath(config) {
+  const customElementsBundleOT = config.outputTargets.find(isOutputTargetDistCustomElementsBundle);
+  const customElementsOT = config.outputTargets.find(isOutputTargetDistCustomElements);
+  const distCollectionOT = config.outputTargets.find(isOutputTargetDistCollection);
+  if (distCollectionOT) {
+    return relative$1(config.rootDir, join(distCollectionOT.dir, 'index.js'));
+  }
+  if (customElementsOT) {
+    const componentsIndexAbs = join(customElementsOT.dir, 'index.js');
+    return relative$1(config.rootDir, componentsIndexAbs);
+  }
+  if (customElementsBundleOT) {
+    const customElementsAbs = join(customElementsBundleOT.dir, 'index.js');
+    return relative$1(config.rootDir, customElementsAbs);
+  }
+  // if no output target for which we define a recommended output target is set
+  // we return `null`
+  return null;
+}
+/**
+ * Check that the `types` field is set correctly in `package.json` for the
+ * `DIST_COLLECTION` output target.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param outputTarget a DIST_COLLECTION output target
+ */
 const validateTypes = async (config, compilerCtx, buildCtx, outputTarget) => {
   const typesAbs = getComponentsDtsTypesFilePath(outputTarget);
   const recommendedPath = relative$1(config.rootDir, typesAbs);
@@ -62946,6 +63193,15 @@ const validateTypes = async (config, compilerCtx, buildCtx, outputTarget) => {
     }
   }
 };
+/**
+ * Check that the `collection` field is set correctly in `package.json` for the
+ * `DIST_COLLECTION` output target.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param outputTarget a DIST_COLLECTION output target
+ */
 const validateCollection$1 = (config, compilerCtx, buildCtx, outputTarget) => {
   if (outputTarget.collectionDir) {
     const collectionRel = join(relative$1(config.rootDir, outputTarget.collectionDir), COLLECTION_MANIFEST_FILE_NAME);
@@ -62955,19 +63211,51 @@ const validateCollection$1 = (config, compilerCtx, buildCtx, outputTarget) => {
     }
   }
 };
+/**
+ * Check that the `browser` field is set correctly in `package.json` for the
+ * `DIST_COLLECTION` output target.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ */
 const validateBrowser = (config, compilerCtx, buildCtx) => {
   if (isString$1(buildCtx.packageJson.browser)) {
     const msg = `package.json "browser" property is set to "${buildCtx.packageJson.browser}". However, for maximum compatibility with all bundlers it's recommended to not set the "browser" property and instead ensure both "module" and "main" properties are set.`;
     packageJsonWarn(config, compilerCtx, buildCtx, msg, `"browser"`);
   }
 };
-const packageJsonError = (config, compilerCtx, buildCtx, msg, warnKey) => {
-  const err = buildJsonFileError(compilerCtx, buildCtx.diagnostics, config.packageJsonFilePath, msg, warnKey);
+/**
+ * Build a diagnostic for an error resulting from a particular field in a
+ * package.json file
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param msg an error string
+ * @param jsonField the key for the field which caused the error, used for
+ * finding the error line in the original JSON file
+ * @returns a diagnostic object
+ */
+const packageJsonError = (config, compilerCtx, buildCtx, msg, jsonField) => {
+  const err = buildJsonFileError(compilerCtx, buildCtx.diagnostics, config.packageJsonFilePath, msg, jsonField);
   err.header = `Package Json`;
   return err;
 };
-const packageJsonWarn = (config, compilerCtx, buildCtx, msg, warnKey) => {
-  const warn = buildJsonFileError(compilerCtx, buildCtx.diagnostics, config.packageJsonFilePath, msg, warnKey);
+/**
+ * Build a diagnostic for a warning resulting from a particular field in a
+ * package.json file
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param msg an error string
+ * @param jsonField the key for the field which caused the error, used for
+ * finding the error line in the original JSON file
+ * @returns a diagnostic object
+ */
+const packageJsonWarn = (config, compilerCtx, buildCtx, msg, jsonField) => {
+  const warn = buildJsonFileError(compilerCtx, buildCtx.diagnostics, config.packageJsonFilePath, msg, jsonField);
   warn.header = `Package Json`;
   warn.level = 'warn';
   return warn;
@@ -64448,12 +64736,16 @@ const createConfigFlags = (init = {}) => {
 };
 
 const getConfig = (userConfig) => {
-  var _a, _b;
+  var _a, _b, _c, _d;
   const logger = (_a = userConfig.logger) !== null && _a !== void 0 ? _a : createLogger();
-  const config = { ...userConfig, flags: createConfigFlags((_b = userConfig.flags) !== null && _b !== void 0 ? _b : {}), logger };
-  if (!config.sys) {
-    config.sys = createSystem({ logger: config.logger });
-  }
+  const config = {
+    ...userConfig,
+    flags: createConfigFlags((_b = userConfig.flags) !== null && _b !== void 0 ? _b : {}),
+    logger,
+    outputTargets: (_c = userConfig.outputTargets) !== null && _c !== void 0 ? _c : [],
+    sys: (_d = userConfig.sys) !== null && _d !== void 0 ? _d : createSystem({ logger }),
+    testing: userConfig !== null && userConfig !== void 0 ? userConfig : {},
+  };
   setPlatformPath(config.sys.platformPath);
   if (config.flags.debug || config.flags.verbose) {
     config.logLevel = 'debug';
@@ -65159,7 +65451,7 @@ const getComponentPathContent = (componentGraph, outputTarget) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.17.2-0",
+		version: "2.17.4",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",
@@ -65572,7 +65864,7 @@ const validateHydrated = (config) => {
  * Validate and return DIST_COLLECTION output targets, ensuring that the `dir`
  * property is set on them.
  *
- * @param config the user-supplied configuration object
+ * @param config a validated configuration object
  * @param userOutputs an array of output targets
  * @returns an array of validated DIST_COLLECTION output targets
  */
@@ -65881,20 +66173,20 @@ const validateVScodeDocsOutputTarget = (diagnostics, outputTarget) => {
   return outputTarget;
 };
 
-const validateAngular = (userConfig, userOutputs) => {
+const validateAngular = (config, userOutputs) => {
   const angularOutputTargets = userOutputs.filter(isOutputTargetAngular);
   return angularOutputTargets.map((outputTarget) => {
     let directivesProxyFile = outputTarget.directivesProxyFile;
     if (directivesProxyFile && !isAbsolute$1(directivesProxyFile)) {
-      directivesProxyFile = join(userConfig.rootDir, directivesProxyFile);
+      directivesProxyFile = join(config.rootDir, directivesProxyFile);
     }
     let directivesArrayFile = outputTarget.directivesArrayFile;
     if (directivesArrayFile && !isAbsolute$1(directivesArrayFile)) {
-      directivesArrayFile = join(userConfig.rootDir, directivesArrayFile);
+      directivesArrayFile = join(config.rootDir, directivesArrayFile);
     }
     let directivesUtilsFile = outputTarget.directivesUtilsFile;
     if (directivesUtilsFile && !isAbsolute$1(directivesUtilsFile)) {
-      directivesUtilsFile = join(userConfig.rootDir, directivesUtilsFile);
+      directivesUtilsFile = join(config.rootDir, directivesUtilsFile);
     }
     return {
       type: 'angular',
@@ -66512,7 +66804,8 @@ const validateWorkers = (config) => {
  * @returns an object with config and diagnostics props
  */
 const validateConfig = (userConfig = {}, bootstrapConfig) => {
-  const config = Object.assign({}, userConfig || {}); // not positive it's json safe
+  var _a, _b, _c, _d;
+  const config = Object.assign({}, userConfig); // not positive it's json safe
   const diagnostics = [];
   const logger = bootstrapConfig.logger || config.logger || createLogger();
   const validatedConfig = {
@@ -66520,6 +66813,9 @@ const validateConfig = (userConfig = {}, bootstrapConfig) => {
     // flags _should_ be JSON safe
     flags: JSON.parse(JSON.stringify(config.flags || {})),
     logger,
+    outputTargets: (_a = config.outputTargets) !== null && _a !== void 0 ? _a : [],
+    sys: (_c = (_b = config.sys) !== null && _b !== void 0 ? _b : bootstrapConfig.sys) !== null && _c !== void 0 ? _c : createSystem({ logger }),
+    testing: (_d = config.testing) !== null && _d !== void 0 ? _d : {},
   };
   // default devMode false
   if (validatedConfig.flags.prod) {
@@ -66786,6 +67082,7 @@ const hasStencilConfigInclude = (includeProp) => Array.isArray(includeProp) && i
  * @public
  */
 const loadConfig = async (init = {}) => {
+  var _a;
   const results = {
     config: null,
     diagnostics: [],
@@ -66800,9 +67097,12 @@ const loadConfig = async (init = {}) => {
   };
   const unknownConfig = {};
   try {
-    const sys = init.sys || createSystem();
     const config = init.config || {};
     let configPath = init.configPath || config.configPath;
+    // Pull the {@link CompilerSystem} out of the initialization object, or create one if it does not exist.
+    // This entity is needed to load the project's configuration (and therefore needs to be created before it can be
+    // attached to a configuration entity, validated or otherwise)
+    const sys = (_a = init.sys) !== null && _a !== void 0 ? _a : createSystem();
     const loadedConfigFile = await loadConfigFile(sys, results.diagnostics, configPath);
     if (hasError(results.diagnostics)) {
       return results;
@@ -67094,7 +67394,7 @@ const convertStaticToMeta = (config, compilerCtx, buildCtx, typeChecker, collect
     let moduleFile;
     const visitNode = (node) => {
       if (t.isClassDeclaration(node)) {
-        return parseStaticComponentMeta(compilerCtx, typeChecker, node, moduleFile, compilerCtx.nodeMap, transformOpts);
+        return parseStaticComponentMeta(compilerCtx, typeChecker, node, moduleFile, transformOpts);
       }
       else if (t.isImportDeclaration(node)) {
         parseModuleImport(config, compilerCtx, buildCtx, moduleFile, dirPath, node, !transformOpts.isolatedModules);