@stencil/core 2.15.1 → 2.16.1-0

package/cli/index.cjs

@@ -1,5 +1,5 @@
 /*!
- Stencil CLI (CommonJS) v2.15.1 | MIT Licensed | https://stenciljs.com
+ Stencil CLI (CommonJS) v2.16.1-0 | MIT Licensed | https://stenciljs.com
  */
 'use strict';
 
@@ -118,6 +118,8 @@ const TASK_CANCELED_MSG = `task canceled`;
  * Forward-slash paths can be used in Windows as long as they're not
  * extended-length paths and don't contain any non-ascii characters.
  * This was created since the path methods in Node.js outputs \\ paths on Windows.
+ * @param path the Windows-based path to convert
+ * @returns the converted path
  */
 const normalizePath = (path) => {
     if (typeof path !== 'string') {
@@ -530,7 +532,7 @@ const getNpmConfigEnvArgs = (sys) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.15.1",
+		version: "2.16.1-0",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",
@@ -967,10 +969,10 @@ async function updateConfig(sys, newOptions) {
 
 const isOutputTargetDocs = (o) => o.type === DOCS_README || o.type === DOCS_JSON || o.type === DOCS_CUSTOM || o.type === DOCS_VSCODE;
 const DOCS_CUSTOM = 'docs-custom';
-const DOCS_JSON = `docs-json`;
-const DOCS_README = `docs-readme`;
-const DOCS_VSCODE = `docs-vscode`;
-const WWW = `www`;
+const DOCS_JSON = 'docs-json';
+const DOCS_README = 'docs-readme';
+const DOCS_VSCODE = 'docs-vscode';
+const WWW = 'www';
 
 /**
  * Used to within taskBuild to provide the component_count property.
@@ -1072,10 +1074,12 @@ const prepareData = async (coreCompiler, config, sys, duration_ms, component_cou
     };
 };
 /**
- * Reads package-lock.json, yarn.lock, and package.json files in order to cross reference
+ * Reads package-lock.json, yarn.lock, and package.json files in order to cross-reference
  * the dependencies and devDependencies properties. Pulls up the current installed version
  * of each package under the @stencil, @ionic, and @capacitor scopes.
- * @returns string[]
+ * @param sys the system instance where telemetry is invoked
+ * @param config the Stencil configuration associated with the current task that triggered telemetry
+ * @returns an object listing all dev and production dependencies under the aforementioned scopes
  */
 async function getInstalledPackages(sys, config) {
     let packages = [];
@@ -1154,7 +1158,12 @@ function sanitizeDeclaredVersion(version) {
     return version.replace(/[*^~]/g, '');
 }
 /**
- * If telemetry is enabled, send a metric via IPC to a forked process for uploading.
+ * If telemetry is enabled, send a metric to an external data store
+ * @param sys the system instance where telemetry is invoked
+ * @param config the Stencil configuration associated with the current task that triggered telemetry
+ * @param name the name of a trackable metric. Note this name is not necessarily a scalar value to track, like
+ * "Stencil Version". For example, "stencil_cli_command" is a name that is used to track all CLI command information.
+ * @param value the data to send to the external data store under the provided name argument
  */
 async function sendMetric(sys, config, name, value) {
     const session_id = await getTelemetryToken(sys);
@@ -1307,7 +1316,14 @@ const IS_NODE_ENV = typeof global !== 'undefined' &&
     (!global.origin || typeof global.origin !== 'string');
 
 /**
- * Task to generate component boilerplate.
+ * Task to generate component boilerplate and write it to disk. This task can
+ * cause the program to exit with an error under various circumstances, such as
+ * being called in an inappropriate place, being asked to overwrite files that
+ * already exist, etc.
+ *
+ * @param coreCompiler the CoreCompiler we're using currently, here we're
+ * mainly accessing the `path` module
+ * @param config the user-supplied config, which we need here to access `.sys`.
  */
 const taskGenerate = async (coreCompiler, config) => {
     if (!IS_NODE_ENV) {
@@ -1337,10 +1353,16 @@ const taskGenerate = async (coreCompiler, config) => {
     const testFolder = extensionsToGenerate.some(isTest) ? 'test' : '';
     const outDir = path.join(absoluteSrcDir, 'components', dir, componentName);
     await config.sys.createDir(path.join(outDir, testFolder), { recursive: true });
-    const writtenFiles = await Promise.all(extensionsToGenerate.map((extension) => writeFileByExtension(coreCompiler, config, outDir, componentName, extension, extensionsToGenerate.includes('css')))).catch((error) => config.logger.error(error));
+    const filesToGenerate = extensionsToGenerate.map((extension) => ({
+        extension,
+        path: getFilepathForFile(coreCompiler, outDir, componentName, extension),
+    }));
+    await checkForOverwrite(filesToGenerate, config);
+    const writtenFiles = await Promise.all(filesToGenerate.map((file) => getBoilerplateAndWriteFile(config, componentName, extensionsToGenerate.includes('css'), file))).catch((error) => config.logger.error(error));
     if (!writtenFiles) {
         return config.sys.exit(1);
     }
+    // TODO(STENCIL-424): Investigate moving these console.log calls to config.logger.info
     console.log();
     console.log(`${config.logger.gray('$')} stencil generate ${input}`);
     console.log();
@@ -1350,6 +1372,9 @@ const taskGenerate = async (coreCompiler, config) => {
 };
 /**
  * Show a checkbox prompt to select the files to be generated.
+ *
+ * @returns a read-only array of `GenerableExtension`, the extensions that the user has decided
+ * to generate
  */
 const chooseFilesToGenerate = async () => {
     const { prompt } = await Promise.resolve().then(function () { return /*#__PURE__*/_interopNamespace(require('../sys/node/prompts.js')); });
@@ -1365,22 +1390,76 @@ const chooseFilesToGenerate = async () => {
     })).filesToGenerate;
 };
 /**
- * Get a file's boilerplate by its extension and write it to disk.
+ * Get a filepath for a file we want to generate!
+ *
+ * The filepath for a given file depends on the path, the user-supplied
+ * component name, the extension, and whether we're inside of a test directory.
+ *
+ * @param coreCompiler  the compiler we're using, here to acces the `.path` module
+ * @param path          path to where we're going to generate the component
+ * @param componentName the user-supplied name for the generated component
+ * @param extension     the file extension
+ * @returns the full filepath to the component (with a possible `test` directory
+ * added)
+ */
+const getFilepathForFile = (coreCompiler, path, componentName, extension) => isTest(extension)
+    ? coreCompiler.path.join(path, 'test', `${componentName}.${extension}`)
+    : coreCompiler.path.join(path, `${componentName}.${extension}`);
+/**
+ * Get the boilerplate for a file and write it to disk
+ *
+ * @param config        the current config, needed for file operations
+ * @param componentName the component name (user-supplied)
+ * @param withCss       are we generating CSS?
+ * @param file          the file we want to write
+ * @returns a `Promise<string>` which holds the full filepath we've written to,
+ * used to print out a little summary of our activity to the user.
  */
-const writeFileByExtension = async (coreCompiler, config, path, name, extension, withCss) => {
-    if (isTest(extension)) {
-        path = coreCompiler.path.join(path, 'test');
-    }
-    const outFile = coreCompiler.path.join(path, `${name}.${extension}`);
-    const boilerplate = getBoilerplateByExtension(name, extension, withCss);
-    await config.sys.writeFile(outFile, boilerplate);
-    return outFile;
+const getBoilerplateAndWriteFile = async (config, componentName, withCss, file) => {
+    const boilerplate = getBoilerplateByExtension(componentName, file.extension, withCss);
+    await config.sys.writeFile(file.path, boilerplate);
+    return file.path;
 };
+/**
+ * Check to see if any of the files we plan to write already exist and would
+ * therefore be overwritten if we proceed, because we'd like to not overwrite
+ * people's code!
+ *
+ * This function will check all the filepaths and if it finds any files log an
+ * error and exit with an error code. If it doesn't find anything it will just
+ * peacefully return `Promise<void>`.
+ *
+ * @param files  the files we want to check
+ * @param config the Config object, used here to get access to `sys.readFile`
+ */
+const checkForOverwrite = async (files, config) => {
+    const alreadyPresent = [];
+    await Promise.all(files.map(async ({ path }) => {
+        if ((await config.sys.readFile(path)) !== undefined) {
+            alreadyPresent.push(path);
+        }
+    }));
+    if (alreadyPresent.length > 0) {
+        config.logger.error('Generating code would overwrite the following files:', ...alreadyPresent.map((path) => '\t' + path));
+        await config.sys.exit(1);
+    }
+};
+/**
+ * Check if an extension is for a test
+ *
+ * @param extension the extension we want to check
+ * @returns a boolean indicating whether or not its a test
+ */
 const isTest = (extension) => {
     return extension === 'e2e.ts' || extension === 'spec.tsx';
 };
 /**
  * Get the boilerplate for a file by its extension.
+ *
+ * @param tagName the name of the component we're generating
+ * @param extension the file extension we want boilerplate for (.css, tsx, etc)
+ * @param withCss a boolean indicating whether we're generating a CSS file
+ * @returns a string container the file boilerplate for the supplied extension
  */
 const getBoilerplateByExtension = (tagName, extension, withCss) => {
     switch (extension) {
@@ -1397,7 +1476,10 @@ const getBoilerplateByExtension = (tagName, extension, withCss) => {
     }
 };
 /**
- * Get the boilerplate for a component.
+ * Get the boilerplate for a file containing the definition of a component
+ * @param tagName the name of the tag to give the component
+ * @param hasStyle designates if the component has an external stylesheet or not
+ * @returns the contents of a file that defines a component
  */
 const getComponentBoilerplate = (tagName, hasStyle) => {
     const decorator = [`{`];
@@ -1431,7 +1513,9 @@ const getStyleUrlBoilerplate = () => `:host {
 }
 `;
 /**
- * Get the boilerplate for a spec test.
+ * Get the boilerplate for a file containing a spec (unit) test for a component
+ * @param tagName the name of the tag associated with the component under test
+ * @returns the contents of a file that unit tests a component
  */
 const getSpecTestBoilerplate = (tagName) => `import { newSpecPage } from '@stencil/core/testing';
 import { ${toPascalCase(tagName)} } from '../${tagName}';
@@ -1453,22 +1537,26 @@ describe('${tagName}', () => {
 });
 `;
 /**
- * Get the boilerplate for an E2E test.
+ * Get the boilerplate for a file containing an end-to-end (E2E) test for a component
+ * @param tagName the name of the tag associated with the component under test
+ * @returns the contents of a file that E2E tests a component
  */
-const getE2eTestBoilerplate = (name) => `import { newE2EPage } from '@stencil/core/testing';
+const getE2eTestBoilerplate = (tagName) => `import { newE2EPage } from '@stencil/core/testing';
 
-describe('${name}', () => {
+describe('${tagName}', () => {
   it('renders', async () => {
     const page = await newE2EPage();
-    await page.setContent('<${name}></${name}>');
+    await page.setContent('<${tagName}></${tagName}>');
 
-    const element = await page.find('${name}');
+    const element = await page.find('${tagName}');
     expect(element).toHaveClass('hydrated');
   });
 });
 `;
 /**
  * Convert a dash case string to pascal case.
+ * @param str the string to convert
+ * @returns the converted input as pascal case
  */
 const toPascalCase = (str) => str.split('-').reduce((res, part) => res + part[0].toUpperCase() + part.slice(1), '');
 

package/cli/index.js

@@ -1,5 +1,5 @@
 /*!
- Stencil CLI v2.15.1 | MIT Licensed | https://stenciljs.com
+ Stencil CLI v2.16.1-0 | MIT Licensed | https://stenciljs.com
  */
 const toLowerCase = (str) => str.toLowerCase();
 const dashToPascalCase = (str) => toLowerCase(str)
@@ -94,6 +94,8 @@ const TASK_CANCELED_MSG = `task canceled`;
  * Forward-slash paths can be used in Windows as long as they're not
  * extended-length paths and don't contain any non-ascii characters.
  * This was created since the path methods in Node.js outputs \\ paths on Windows.
+ * @param path the Windows-based path to convert
+ * @returns the converted path
  */
 const normalizePath = (path) => {
     if (typeof path !== 'string') {
@@ -506,7 +508,7 @@ const getNpmConfigEnvArgs = (sys) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.15.1",
+		version: "2.16.1-0",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",
@@ -943,10 +945,10 @@ async function updateConfig(sys, newOptions) {
 
 const isOutputTargetDocs = (o) => o.type === DOCS_README || o.type === DOCS_JSON || o.type === DOCS_CUSTOM || o.type === DOCS_VSCODE;
 const DOCS_CUSTOM = 'docs-custom';
-const DOCS_JSON = `docs-json`;
-const DOCS_README = `docs-readme`;
-const DOCS_VSCODE = `docs-vscode`;
-const WWW = `www`;
+const DOCS_JSON = 'docs-json';
+const DOCS_README = 'docs-readme';
+const DOCS_VSCODE = 'docs-vscode';
+const WWW = 'www';
 
 /**
  * Used to within taskBuild to provide the component_count property.
@@ -1048,10 +1050,12 @@ const prepareData = async (coreCompiler, config, sys, duration_ms, component_cou
     };
 };
 /**
- * Reads package-lock.json, yarn.lock, and package.json files in order to cross reference
+ * Reads package-lock.json, yarn.lock, and package.json files in order to cross-reference
  * the dependencies and devDependencies properties. Pulls up the current installed version
  * of each package under the @stencil, @ionic, and @capacitor scopes.
- * @returns string[]
+ * @param sys the system instance where telemetry is invoked
+ * @param config the Stencil configuration associated with the current task that triggered telemetry
+ * @returns an object listing all dev and production dependencies under the aforementioned scopes
  */
 async function getInstalledPackages(sys, config) {
     let packages = [];
@@ -1130,7 +1134,12 @@ function sanitizeDeclaredVersion(version) {
     return version.replace(/[*^~]/g, '');
 }
 /**
- * If telemetry is enabled, send a metric via IPC to a forked process for uploading.
+ * If telemetry is enabled, send a metric to an external data store
+ * @param sys the system instance where telemetry is invoked
+ * @param config the Stencil configuration associated with the current task that triggered telemetry
+ * @param name the name of a trackable metric. Note this name is not necessarily a scalar value to track, like
+ * "Stencil Version". For example, "stencil_cli_command" is a name that is used to track all CLI command information.
+ * @param value the data to send to the external data store under the provided name argument
  */
 async function sendMetric(sys, config, name, value) {
     const session_id = await getTelemetryToken(sys);
@@ -1283,7 +1292,14 @@ const IS_NODE_ENV = typeof global !== 'undefined' &&
     (!global.origin || typeof global.origin !== 'string');
 
 /**
- * Task to generate component boilerplate.
+ * Task to generate component boilerplate and write it to disk. This task can
+ * cause the program to exit with an error under various circumstances, such as
+ * being called in an inappropriate place, being asked to overwrite files that
+ * already exist, etc.
+ *
+ * @param coreCompiler the CoreCompiler we're using currently, here we're
+ * mainly accessing the `path` module
+ * @param config the user-supplied config, which we need here to access `.sys`.
  */
 const taskGenerate = async (coreCompiler, config) => {
     if (!IS_NODE_ENV) {
@@ -1313,10 +1329,16 @@ const taskGenerate = async (coreCompiler, config) => {
     const testFolder = extensionsToGenerate.some(isTest) ? 'test' : '';
     const outDir = path.join(absoluteSrcDir, 'components', dir, componentName);
     await config.sys.createDir(path.join(outDir, testFolder), { recursive: true });
-    const writtenFiles = await Promise.all(extensionsToGenerate.map((extension) => writeFileByExtension(coreCompiler, config, outDir, componentName, extension, extensionsToGenerate.includes('css')))).catch((error) => config.logger.error(error));
+    const filesToGenerate = extensionsToGenerate.map((extension) => ({
+        extension,
+        path: getFilepathForFile(coreCompiler, outDir, componentName, extension),
+    }));
+    await checkForOverwrite(filesToGenerate, config);
+    const writtenFiles = await Promise.all(filesToGenerate.map((file) => getBoilerplateAndWriteFile(config, componentName, extensionsToGenerate.includes('css'), file))).catch((error) => config.logger.error(error));
     if (!writtenFiles) {
         return config.sys.exit(1);
     }
+    // TODO(STENCIL-424): Investigate moving these console.log calls to config.logger.info
     console.log();
     console.log(`${config.logger.gray('$')} stencil generate ${input}`);
     console.log();
@@ -1326,6 +1348,9 @@ const taskGenerate = async (coreCompiler, config) => {
 };
 /**
  * Show a checkbox prompt to select the files to be generated.
+ *
+ * @returns a read-only array of `GenerableExtension`, the extensions that the user has decided
+ * to generate
  */
 const chooseFilesToGenerate = async () => {
     const { prompt } = await import('../sys/node/prompts.js');
@@ -1341,22 +1366,76 @@ const chooseFilesToGenerate = async () => {
     })).filesToGenerate;
 };
 /**
- * Get a file's boilerplate by its extension and write it to disk.
+ * Get a filepath for a file we want to generate!
+ *
+ * The filepath for a given file depends on the path, the user-supplied
+ * component name, the extension, and whether we're inside of a test directory.
+ *
+ * @param coreCompiler  the compiler we're using, here to acces the `.path` module
+ * @param path          path to where we're going to generate the component
+ * @param componentName the user-supplied name for the generated component
+ * @param extension     the file extension
+ * @returns the full filepath to the component (with a possible `test` directory
+ * added)
+ */
+const getFilepathForFile = (coreCompiler, path, componentName, extension) => isTest(extension)
+    ? coreCompiler.path.join(path, 'test', `${componentName}.${extension}`)
+    : coreCompiler.path.join(path, `${componentName}.${extension}`);
+/**
+ * Get the boilerplate for a file and write it to disk
+ *
+ * @param config        the current config, needed for file operations
+ * @param componentName the component name (user-supplied)
+ * @param withCss       are we generating CSS?
+ * @param file          the file we want to write
+ * @returns a `Promise<string>` which holds the full filepath we've written to,
+ * used to print out a little summary of our activity to the user.
  */
-const writeFileByExtension = async (coreCompiler, config, path, name, extension, withCss) => {
-    if (isTest(extension)) {
-        path = coreCompiler.path.join(path, 'test');
-    }
-    const outFile = coreCompiler.path.join(path, `${name}.${extension}`);
-    const boilerplate = getBoilerplateByExtension(name, extension, withCss);
-    await config.sys.writeFile(outFile, boilerplate);
-    return outFile;
+const getBoilerplateAndWriteFile = async (config, componentName, withCss, file) => {
+    const boilerplate = getBoilerplateByExtension(componentName, file.extension, withCss);
+    await config.sys.writeFile(file.path, boilerplate);
+    return file.path;
 };
+/**
+ * Check to see if any of the files we plan to write already exist and would
+ * therefore be overwritten if we proceed, because we'd like to not overwrite
+ * people's code!
+ *
+ * This function will check all the filepaths and if it finds any files log an
+ * error and exit with an error code. If it doesn't find anything it will just
+ * peacefully return `Promise<void>`.
+ *
+ * @param files  the files we want to check
+ * @param config the Config object, used here to get access to `sys.readFile`
+ */
+const checkForOverwrite = async (files, config) => {
+    const alreadyPresent = [];
+    await Promise.all(files.map(async ({ path }) => {
+        if ((await config.sys.readFile(path)) !== undefined) {
+            alreadyPresent.push(path);
+        }
+    }));
+    if (alreadyPresent.length > 0) {
+        config.logger.error('Generating code would overwrite the following files:', ...alreadyPresent.map((path) => '\t' + path));
+        await config.sys.exit(1);
+    }
+};
+/**
+ * Check if an extension is for a test
+ *
+ * @param extension the extension we want to check
+ * @returns a boolean indicating whether or not its a test
+ */
 const isTest = (extension) => {
     return extension === 'e2e.ts' || extension === 'spec.tsx';
 };
 /**
  * Get the boilerplate for a file by its extension.
+ *
+ * @param tagName the name of the component we're generating
+ * @param extension the file extension we want boilerplate for (.css, tsx, etc)
+ * @param withCss a boolean indicating whether we're generating a CSS file
+ * @returns a string container the file boilerplate for the supplied extension
  */
 const getBoilerplateByExtension = (tagName, extension, withCss) => {
     switch (extension) {
@@ -1373,7 +1452,10 @@ const getBoilerplateByExtension = (tagName, extension, withCss) => {
     }
 };
 /**
- * Get the boilerplate for a component.
+ * Get the boilerplate for a file containing the definition of a component
+ * @param tagName the name of the tag to give the component
+ * @param hasStyle designates if the component has an external stylesheet or not
+ * @returns the contents of a file that defines a component
  */
 const getComponentBoilerplate = (tagName, hasStyle) => {
     const decorator = [`{`];
@@ -1407,7 +1489,9 @@ const getStyleUrlBoilerplate = () => `:host {
 }
 `;
 /**
- * Get the boilerplate for a spec test.
+ * Get the boilerplate for a file containing a spec (unit) test for a component
+ * @param tagName the name of the tag associated with the component under test
+ * @returns the contents of a file that unit tests a component
  */
 const getSpecTestBoilerplate = (tagName) => `import { newSpecPage } from '@stencil/core/testing';
 import { ${toPascalCase(tagName)} } from '../${tagName}';
@@ -1429,22 +1513,26 @@ describe('${tagName}', () => {
 });
 `;
 /**
- * Get the boilerplate for an E2E test.
+ * Get the boilerplate for a file containing an end-to-end (E2E) test for a component
+ * @param tagName the name of the tag associated with the component under test
+ * @returns the contents of a file that E2E tests a component
  */
-const getE2eTestBoilerplate = (name) => `import { newE2EPage } from '@stencil/core/testing';
+const getE2eTestBoilerplate = (tagName) => `import { newE2EPage } from '@stencil/core/testing';
 
-describe('${name}', () => {
+describe('${tagName}', () => {
   it('renders', async () => {
     const page = await newE2EPage();
-    await page.setContent('<${name}></${name}>');
+    await page.setContent('<${tagName}></${tagName}>');
 
-    const element = await page.find('${name}');
+    const element = await page.find('${tagName}');
     expect(element).toHaveClass('hydrated');
   });
 });
 `;
 /**
  * Convert a dash case string to pascal case.
+ * @param str the string to convert
+ * @returns the converted input as pascal case
  */
 const toPascalCase = (str) => str.split('-').reduce((res, part) => res + part[0].toUpperCase() + part.slice(1), '');
 

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stencil/core/cli",
-  "version": "2.15.1",
+  "version": "2.16.1-0",
   "description": "Stencil CLI.",
   "main": "./index.cjs",
   "module": "./index.js",

package/compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stencil/core/compiler",
-  "version": "2.15.1",
+  "version": "2.16.1-0",
   "description": "Stencil Compiler.",
   "main": "./stencil.js",
   "types": "./stencil.d.ts",