comment-variables 1.5.0 → 1.5.2

package/README.md

@@ -26,7 +26,11 @@ npm install -g comment-variables
 comment-variables
 ```
 
-Interacts with your root `comments.config.js` file's default exported object to print all the parameters you need to be aware of before running `compress` or `resolve`. Also acts as a dry run validation check. If no error is printed, it means you can run `compress` or `resolve` safely, as long as the printed parameters correspond to what you've expected from your defined config. (Additionally creates a resolved version of your config data as a JSON file, and as a .mjs file exporting both the typedef `ResolvedConfigData` and the object `resolvedConfigData`. If no configuration file is found, a tutorial mode is triggered, generating a template config file for you.)
+Interacts with your root `comments.config.js` file's default exported object to print all the parameters you need to be aware of before running `compress` or `resolve`. Also acts as a dry run validation check. If no error is printed, it means you can run `compress` or `resolve` safely, as long as the printed parameters correspond to what you've expected from your defined config.
+
+Additionally creates a resolved version of your config data as a JSON file, and as a .mjs file exporting both the typedef `ResolvedConfigData` and the object `resolvedConfigData`.
+
+If no configuration file is found, a **tutorial mode** is triggered, generating a template config file for you.
 
 ```
 comment-variables placeholders
@@ -105,7 +109,25 @@ composedVariablesExclusives:
 
 In due time, you may end up creating Comment Variables that are exclusively meant to be used to create other Comment Variables – the latter classified as composed variables. Passing an array to this config option, comprised of the keys of these original comment variables (for example, if a Comment Variable placeholder is `$COMMENT#COMMENT` its related key is `COMMENT`), prevents these original comment variables from being affected by the `compress` and `resolve` commands.
 
-## **`comments.config.js`**
+**`comment-variables` v2 introduces the concept of variations:**
+
+```
+variations:
+```
+
+Variations provide native support for internationalization to the Comment Variables ecosystem. In fact, since variations aren't limited to languages, they can be applied to any solution of your own based on variants.
+
+The `variations` key as an option takes as value an object with the following properties:
+
+- `variations.variants`: Defines all variants that have matching variations duly defined within the top-level keys of `data`.
+- `variations.variant`: Defines the current variant that Comment Variables currently resolves to.
+- `variations.referenceData`: Defines the reference variation that all other variations need to have (or aim to have) matching keys with. Requires a JavaScript variable as it needs to be the exact same object as the one referenced at `data[variations.referenceVariant]`.
+- `variations.referenceVariant`: Defines the variant of the reference variation.
+- `variations.allowIncompleteVariations`: Defines the behavior of the error handling in case of variations that do not match one-to-one with the reference variation. If `true`, allows incomplete variations data to remain. If `false`, errors and guides the fixing of missing variations data.
+
+When triggering **tutorial mode**, please select `with variations` for a thorough and actionable example.
+
+## `comments.config.js`
 
 A root `comments.config.js` file looks like this. (This is an earlier version of the config file I'm using to manage my JavaScript comments in this library.)
 

package/generate.variations.js

@@ -62,16 +62,16 @@ const composedVariablesExclusives = [
 /* variations */
 
 const variations = {
-  // defines all variants that have matching variations duly defined within the top-level keys of `data`
+  // Defines all variants that have matching variations duly defined within the top-level keys of `data`.
   variants: {
     [EN]: { label: ENGLISH },
     [FR]: { label: FRANÇAIS },
   },
-  // defines the current variant that Comment Variables currently resolves to
+  // Defines the current variant that Comment Variables currently resolves to.
   variant: FR,
   // Defines the reference variation that all other variations need to have (or aim to have) matching keys with. Requires a JavaScript variable as it needs to be the exact same object as the one referenced at `data[variations.referenceVariant]`.
   referenceData: enData,
-  // defines the variant of the reference variation
+  // Defines the variant of the reference variation.
   referenceVariant: EN,
   // Defines the behavior of the error handling in case of variations that do not match one-to-one with the reference variation. If `true`, allows incomplete variations data to remain. If `false`, errors and guides the fixing of missing variations data.
   allowIncompleteVariations: true,

package/library/_commons/constants/bases.js

@@ -29,4 +29,4 @@ export const allMDVirtualJSTSFileGlobs = [
 
 // prompts choices values
 export const classic = "classic";
-export const withVariations = "with variations";
+export const advanced = "advanced";

package/library/index.js

@@ -28,7 +28,7 @@ import {
   hasPackageJson,
   hasGitFolder,
   classic,
-  withVariations,
+  advanced,
 } from "./_commons/constants/bases.js";
 
 import { exitDueToFailure, logError } from "./_commons/utilities/helpers.js";
@@ -96,11 +96,11 @@ if (!fs.existsSync(rawConfigPath)) {
     generateExampleFilePath: "../generate.example.js",
   };
 
-  const classicOrWithVariations = await prompts({
+  const classicOrAdvanced = await prompts({
     type: "select",
     name: "value",
     message:
-      "Would you like to generate a classic template (simple) or a template with variations (advanced) instead?",
+      "Would you like to generate a simple template (classic) or a template with variations (advanced) instead?",
     choices: [
       {
         title: classic,
@@ -109,39 +109,39 @@ if (!fs.existsSync(rawConfigPath)) {
         value: classic,
       },
       {
-        title: withVariations,
+        title: advanced,
         description:
-          "Advanced. For those who know their way around Comment Variables and may want to use its native internationalization features or any configuration of their own that relies on variants.",
-        value: withVariations,
+          "With variations. For those who know their way around Comment Variables and may want to use its native internationalization features or any configuration of their own that relies on variants.",
+        value: advanced,
       },
     ],
     initial: 0,
   });
 
   /**
-   * @type {typeof classic | typeof withVariations}
+   * @type {typeof classic | typeof advanced}
    * `control+C` returns `undefined`.
    */
-  const classicOrWithVariationsValue = classicOrWithVariations.value;
+  const classicOrAdvancedValue = classicOrAdvanced.value;
 
-  if (!classicOrWithVariationsValue) {
+  if (!classicOrAdvancedValue) {
     console.error(
       "ERROR. No template selected. Please select a template to begin using comment-variables via this CLI."
     );
     exitDueToFailure();
   }
 
-  switch (classicOrWithVariationsValue) {
+  switch (classicOrAdvancedValue) {
     case classic:
       tutorialConfig.generateTemplateFilePath = "../generate.template.js";
       break;
-    case withVariations:
+    case advanced:
       tutorialConfig.generateTemplateFilePath = "../generate.variations.js";
       break;
 
     default:
       console.error(
-        "ERROR. No template selected. Please select a template to begin using comment-variables via this CLI. (Unreachable code.)" // copypasted same as classicOrWithVariations for now, since this is supposed to be unreachable code.
+        "ERROR. No template selected. Please select a template to begin using comment-variables via this CLI. (Unreachable code.)" // copypasted same as classicOrAdvanced for now, since this is supposed to be unreachable code.
       );
       exitDueToFailure();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
     "comment-variables": "./library/index.js",