@rindo/core 2.16.0 → 2.17.0

package/cli/index.cjs

@@ -1,5 +1,5 @@
 /*!
- Rindo CLI (CommonJS) v2.16.0 | MIT Licensed | https://rindojs.web.app
+ Rindo CLI (CommonJS) v2.17.0 | MIT Licensed | https://rindojs.web.app
  */
 '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: "@rindo/core",
-		version: "2.16.0",
+		version: "2.17.0",
 		main: "compiler/rindo.js",
 		resources: [
 			"package.json",
@@ -964,7 +966,9 @@ async function updateConfig(sys, newOptions) {
     return await writeConfig(sys, Object.assign(config, newOptions));
 }
 
+const isOutputTargetHydrate = (o) => o.type === DIST_HYDRATE_SCRIPT;
 const isOutputTargetDocs = (o) => o.type === DOCS_README || o.type === DOCS_JSON || o.type === DOCS_CUSTOM || o.type === DOCS_VSCODE;
+const DIST_HYDRATE_SCRIPT = 'dist-hydrate-script';
 const DOCS_CUSTOM = 'docs-custom';
 const DOCS_JSON = 'docs-json';
 const DOCS_README = 'docs-readme';
@@ -992,6 +996,7 @@ async function telemetryBuildFinishedAction(sys, config, logger, coreCompiler, r
 }
 /**
  * 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 Rindo command
  * @param logger The tool used to do logging
@@ -1037,6 +1042,16 @@ async function getActiveTargets(config) {
     const result = config.outputTargets.map((t) => t.type);
     return Array.from(new Set(result));
 }
+/**
+ * Prepare data for telemetry
+ *
+ * @param coreCompiler the core compiler
+ * @param config the current Rindo config
+ * @param sys the compiler system instance in use
+ * @param duration_ms the duration of the action being tracked
+ * @param component_count the number of components being built (optional)
+ * @returns a Promise wrapping data for the telemetry endpoint
+ */
 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);
@@ -1049,6 +1064,7 @@ const prepareData = async (coreCompiler, config, sys, duration_ms, component_cou
     const cpu_model = sys.details.cpuModel;
     const build = coreCompiler.buildId || 'unknown';
     const has_app_pwa_config = hasAppTarget(config);
+    const anonymizedConfig = anonymizeConfigForTelemetry(config);
     return {
         yarn,
         duration_ms,
@@ -1068,13 +1084,86 @@ const prepareData = async (coreCompiler, config, sys, duration_ms, component_cou
         typescript,
         rollup,
         has_app_pwa_config,
+        config: anonymizedConfig,
     };
 };
+// props in output targets for which we retain their original values when
+// preparing a config for telemetry
+//
+// we omit the values of all other fields on output targets.
+const OUTPUT_TARGET_KEYS_TO_KEEP = ['type'];
+// top-level config props that we anonymize for telemetry
+const CONFIG_PROPS_TO_ANONYMIZE = [
+    'rootDir',
+    'fsNamespace',
+    'packageJsonFilePath',
+    'namespace',
+    'srcDir',
+    'srcIndexHtml',
+    'buildLogFilePath',
+    'cacheDir',
+    'configPath',
+    'tsconfig',
+];
+// Props we delete entirely from the config for telemetry
+//
+// TODO: Investigate improving anonymization for tsCompilerOptions and devServer
+const CONFIG_PROPS_TO_DELETE = ['sys', 'logger', 'tsCompilerOptions', 'devServer'];
 /**
- * Reads package-lock.json, yarn.lock, and package.json files in order to cross reference
+ * Anonymize the config for telemetry, replacing potentially revealing config props
+ * with a placeholder string if they are present (this lets us still track how frequently
+ * these config options are being used)
+ *
+ * @param config the config to anonymize
+ * @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) => {
+        // 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
+        // whether it's in our 'keep' list to decide whether to keep it or replace it
+        // with `"omitted"`.
+        const anonymizedOT = JSON.parse(JSON.stringify(target, (key, value) => {
+            if (!(typeof value === 'string')) {
+                return value;
+            }
+            if (OUTPUT_TARGET_KEYS_TO_KEEP.includes(key)) {
+                return value;
+            }
+            return 'omitted';
+        }));
+        // this prop has to be handled separately because it is an array
+        // so the replace function above will be called with all of its
+        // members, giving us `["omitted", "omitted", ...]`.
+        //
+        // Instead, we check for its presence and manually copy over.
+        if (isOutputTargetHydrate(target) && target.external) {
+            anonymizedOT['external'] = target.external.concat();
+        }
+        return anonymizedOT;
+    });
+    // TODO: Investigate improving anonymization for tsCompilerOptions and devServer
+    for (const prop of CONFIG_PROPS_TO_DELETE) {
+        delete anonymizedConfig[prop];
+    }
+    return anonymizedConfig;
+};
+/**
+ * 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 @rindo, @navify, and @jigra scopes.
- * @returns string[]
+ *
+ * @param sys the system instance where telemetry is invoked
+ * @param config the Rindo 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 = [];
@@ -1153,7 +1242,13 @@ 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 Rindo 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
+ * "Rindo Version". For example, "rindo_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);
@@ -1164,10 +1259,11 @@ async function sendMetric(sys, config, name, value) {
         value,
         session_id,
     };
-    await sendTelemetry(sys, config, { type: 'telemetry', message });
+    await sendTelemetry(sys, config, message);
 }
 /**
  * Used to read the config file's tokens.telemetry property.
+ *
  * @param sys The system where the command is invoked
  * @returns string
  */
@@ -1189,7 +1285,7 @@ async function sendTelemetry(sys, config, data) {
     try {
         const now = new Date().toISOString();
         const body = {
-            metrics: [data.message],
+            metrics: [data],
             sent_at: now,
         };
         // This request is only made if telemetry is on.
@@ -1201,7 +1297,7 @@ async function sendTelemetry(sys, config, data) {
             body: JSON.stringify(body),
         });
         hasVerbose(config) &&
-            console.debug('\nSent %O metric to events service (status: %O)', data.message.name, response.status, '\n');
+            console.debug('\nSent %O metric to events service (status: %O)', data.name, response.status, '\n');
         if (response.status !== 204) {
             hasVerbose(config) &&
                 console.debug('\nBad response from events service. Request body: %O', response.body.toString(), '\n');
@@ -1352,7 +1448,8 @@ const taskGenerate = async (coreCompiler, config) => {
     if (!writtenFiles) {
         return config.sys.exit(1);
     }
-    // TODO: Investigate moving these console.log calls to config.logger.info
+    // We use `console.log` here rather than our `config.logger` because we don't want
+    // our TUI messages to be prefixed with timestamps and so on.
     console.log();
     console.log(`${config.logger.gray('$')} rindo generate ${input}`);
     console.log();
@@ -1466,7 +1563,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 = [`{`];
@@ -1500,7 +1600,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 '@rindo/core/testing';
 import { ${toPascalCase(tagName)} } from '../${tagName}';
@@ -1522,22 +1624,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 '@rindo/core/testing';
+const getE2eTestBoilerplate = (tagName) => `import { newE2EPage } from '@rindo/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 @@
 /*!
- Rindo CLI v2.16.0 | MIT Licensed | https://rindojs.web.app
+ Rindo CLI v2.17.0 | MIT Licensed | https://rindojs.web.app
  */
 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: "@rindo/core",
-		version: "2.16.0",
+		version: "2.17.0",
 		main: "compiler/rindo.js",
 		resources: [
 			"package.json",
@@ -940,7 +942,9 @@ async function updateConfig(sys, newOptions) {
     return await writeConfig(sys, Object.assign(config, newOptions));
 }
 
+const isOutputTargetHydrate = (o) => o.type === DIST_HYDRATE_SCRIPT;
 const isOutputTargetDocs = (o) => o.type === DOCS_README || o.type === DOCS_JSON || o.type === DOCS_CUSTOM || o.type === DOCS_VSCODE;
+const DIST_HYDRATE_SCRIPT = 'dist-hydrate-script';
 const DOCS_CUSTOM = 'docs-custom';
 const DOCS_JSON = 'docs-json';
 const DOCS_README = 'docs-readme';
@@ -968,6 +972,7 @@ async function telemetryBuildFinishedAction(sys, config, logger, coreCompiler, r
 }
 /**
  * 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 Rindo command
  * @param logger The tool used to do logging
@@ -1013,6 +1018,16 @@ async function getActiveTargets(config) {
     const result = config.outputTargets.map((t) => t.type);
     return Array.from(new Set(result));
 }
+/**
+ * Prepare data for telemetry
+ *
+ * @param coreCompiler the core compiler
+ * @param config the current Rindo config
+ * @param sys the compiler system instance in use
+ * @param duration_ms the duration of the action being tracked
+ * @param component_count the number of components being built (optional)
+ * @returns a Promise wrapping data for the telemetry endpoint
+ */
 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);
@@ -1025,6 +1040,7 @@ const prepareData = async (coreCompiler, config, sys, duration_ms, component_cou
     const cpu_model = sys.details.cpuModel;
     const build = coreCompiler.buildId || 'unknown';
     const has_app_pwa_config = hasAppTarget(config);
+    const anonymizedConfig = anonymizeConfigForTelemetry(config);
     return {
         yarn,
         duration_ms,
@@ -1044,13 +1060,86 @@ const prepareData = async (coreCompiler, config, sys, duration_ms, component_cou
         typescript,
         rollup,
         has_app_pwa_config,
+        config: anonymizedConfig,
     };
 };
+// props in output targets for which we retain their original values when
+// preparing a config for telemetry
+//
+// we omit the values of all other fields on output targets.
+const OUTPUT_TARGET_KEYS_TO_KEEP = ['type'];
+// top-level config props that we anonymize for telemetry
+const CONFIG_PROPS_TO_ANONYMIZE = [
+    'rootDir',
+    'fsNamespace',
+    'packageJsonFilePath',
+    'namespace',
+    'srcDir',
+    'srcIndexHtml',
+    'buildLogFilePath',
+    'cacheDir',
+    'configPath',
+    'tsconfig',
+];
+// Props we delete entirely from the config for telemetry
+//
+// TODO: Investigate improving anonymization for tsCompilerOptions and devServer
+const CONFIG_PROPS_TO_DELETE = ['sys', 'logger', 'tsCompilerOptions', 'devServer'];
 /**
- * Reads package-lock.json, yarn.lock, and package.json files in order to cross reference
+ * Anonymize the config for telemetry, replacing potentially revealing config props
+ * with a placeholder string if they are present (this lets us still track how frequently
+ * these config options are being used)
+ *
+ * @param config the config to anonymize
+ * @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) => {
+        // 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
+        // whether it's in our 'keep' list to decide whether to keep it or replace it
+        // with `"omitted"`.
+        const anonymizedOT = JSON.parse(JSON.stringify(target, (key, value) => {
+            if (!(typeof value === 'string')) {
+                return value;
+            }
+            if (OUTPUT_TARGET_KEYS_TO_KEEP.includes(key)) {
+                return value;
+            }
+            return 'omitted';
+        }));
+        // this prop has to be handled separately because it is an array
+        // so the replace function above will be called with all of its
+        // members, giving us `["omitted", "omitted", ...]`.
+        //
+        // Instead, we check for its presence and manually copy over.
+        if (isOutputTargetHydrate(target) && target.external) {
+            anonymizedOT['external'] = target.external.concat();
+        }
+        return anonymizedOT;
+    });
+    // TODO: Investigate improving anonymization for tsCompilerOptions and devServer
+    for (const prop of CONFIG_PROPS_TO_DELETE) {
+        delete anonymizedConfig[prop];
+    }
+    return anonymizedConfig;
+};
+/**
+ * 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 @rindo, @navify, and @jigra scopes.
- * @returns string[]
+ *
+ * @param sys the system instance where telemetry is invoked
+ * @param config the Rindo 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 = [];
@@ -1129,7 +1218,13 @@ 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 Rindo 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
+ * "Rindo Version". For example, "rindo_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);
@@ -1140,10 +1235,11 @@ async function sendMetric(sys, config, name, value) {
         value,
         session_id,
     };
-    await sendTelemetry(sys, config, { type: 'telemetry', message });
+    await sendTelemetry(sys, config, message);
 }
 /**
  * Used to read the config file's tokens.telemetry property.
+ *
  * @param sys The system where the command is invoked
  * @returns string
  */
@@ -1165,7 +1261,7 @@ async function sendTelemetry(sys, config, data) {
     try {
         const now = new Date().toISOString();
         const body = {
-            metrics: [data.message],
+            metrics: [data],
             sent_at: now,
         };
         // This request is only made if telemetry is on.
@@ -1177,7 +1273,7 @@ async function sendTelemetry(sys, config, data) {
             body: JSON.stringify(body),
         });
         hasVerbose(config) &&
-            console.debug('\nSent %O metric to events service (status: %O)', data.message.name, response.status, '\n');
+            console.debug('\nSent %O metric to events service (status: %O)', data.name, response.status, '\n');
         if (response.status !== 204) {
             hasVerbose(config) &&
                 console.debug('\nBad response from events service. Request body: %O', response.body.toString(), '\n');
@@ -1328,7 +1424,8 @@ const taskGenerate = async (coreCompiler, config) => {
     if (!writtenFiles) {
         return config.sys.exit(1);
     }
-    // TODO: Investigate moving these console.log calls to config.logger.info
+    // We use `console.log` here rather than our `config.logger` because we don't want
+    // our TUI messages to be prefixed with timestamps and so on.
     console.log();
     console.log(`${config.logger.gray('$')} rindo generate ${input}`);
     console.log();
@@ -1442,7 +1539,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 = [`{`];
@@ -1476,7 +1576,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 '@rindo/core/testing';
 import { ${toPascalCase(tagName)} } from '../${tagName}';
@@ -1498,22 +1600,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 '@rindo/core/testing';
+const getE2eTestBoilerplate = (tagName) => `import { newE2EPage } from '@rindo/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": "@rindo/core/cli",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Rindo CLI.",
   "main": "./index.cjs",
   "module": "./index.js",

package/compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rindo/core/compiler",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Rindo Compiler.",
   "main": "./rindo.js",
   "types": "./rindo.d.ts",