comment-variables 1.4.1 → 1.5.1

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,9 +109,27 @@ 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 the config file I'm using to manage my JavaScript comments in this library.)
+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.)
 
 ```js
 const data = {

package/comments.config.js

@@ -1,13 +1,13 @@
-import {
-  coreData as data,
-  composedVariablesExclusives,
-  variations,
-} from "./jscomments/core/data.js";
 // import {
-//   variationsData as data,
+//   coreData as data,
 //   composedVariablesExclusives,
 //   variations,
-// } from "./jscomments/variations/data.js";
+// } from "./jscomments/core/data.js";
+import {
+  variationsData as data,
+  composedVariablesExclusives,
+  variations,
+} from "./jscomments/variations/data.js";
 
 const ignores = ["README.md", "generate.template.js", "generate.example.js"];
 

package/comments.config.json

@@ -1,148 +1,70 @@
 {
-  "levelOne": {
-    "levelTwo": {
-      "levelThree": {
-        "value": "Level three.",
-        "key": "LEVELONE#LEVELTWO#LEVELTHREE"
-      },
-      "stillLevelThree": {
-        "value": "Level three.",
-        "key": "LEVELONE#LEVELTWO#STILLLEVELTHREE"
-      },
-      "otherLevelThree": {
-        "value": "Level three.",
-        "key": "LEVELONE#LEVELTWO#OTHERLEVELTHREE"
-      },
-      "composedVariable": {
-        "value": "Level three. Level three.",
-        "key": "LEVELONE#LEVELTWO#COMPOSEDVARIABLE"
-      },
-      "composedVariableAlias": {
-        "value": "Level three. Level three.",
-        "key": "LEVELONE#LEVELTWO#COMPOSEDVARIABLEALIAS"
-      },
-      "placeholder": {
-        "value": "placeholder now allowed",
-        "key": "LEVELONE#LEVELTWO#PLACEHOLDER"
-      }
+  "en": {
+    "hello": {
+      "value": "Hello.",
+      "key": "EN#HELLO"
+    },
+    "goodbye": {
+      "value": "Goodbye.",
+      "key": "EN#GOODBYE"
+    },
+    "helloAlias": {
+      "value": "Hello.",
+      "key": "EN#HELLOALIAS"
+    },
+    "forComposed1": {
+      "value": "Hello",
+      "key": "EN#FORCOMPOSED1"
+    },
+    "forComposed2": {
+      "value": "goodbye.",
+      "key": "EN#FORCOMPOSED2"
+    },
+    "composed": {
+      "value": "Hello goodbye.",
+      "key": "EN#COMPOSED"
+    },
+    "composedWithAlias": {
+      "value": "Hello goodbye. Hello.",
+      "key": "EN#COMPOSEDWITHALIAS"
+    },
+    "_testFunction": {
+      "value": "A test function, with its JSDoc appropriately shifting between English and French.",
+      "key": "EN#_TESTFUNCTION"
     }
   },
-  "jsDoc": {
-    "definitions": {
-      "exitDueToFailure": {
-        "value": "Terminates the whole process with a 'failure' code (`1`).",
-        "key": "JSDOC#DEFINITIONS#EXITDUETOFAILURE"
-      },
-      "makeRuleResolve": {
-        "value": "The utility that creates the resolve rule based on the flattened config data, used to transform `$COMMENT` placeholders into actual comments.",
-        "key": "JSDOC#DEFINITIONS#MAKERULERESOLVE"
-      },
-      "makeRuleCompress": {
-        "value": "The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into `$COMMENT` placeholders.",
-        "key": "JSDOC#DEFINITIONS#MAKERULECOMPRESS"
-      },
-      "coreCommentsFlow": {
-        "value": "The core flow at the heart of resolving and compressing comments.",
-        "key": "JSDOC#DEFINITIONS#CORECOMMENTSFLOW"
-      },
-      "resolveCommentsFlow": {
-        "value": "The flow that resolves `$COMMENT` placeholders into actual comments.",
-        "key": "JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW"
-      },
-      "compressCommentsFlow": {
-        "value": "The flow that compresses actual comments into `$COMMENT` placeholders.",
-        "key": "JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW"
-      },
-      "placeholdersCommentsFlow": {
-        "value": "The flow that creates `$COMMENT` placeholders right next to where they're defined.",
-        "key": "JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW"
-      },
-      "logError": {
-        "value": "Logs an error to the console depending on its type. (`\"error\"` or `\"warning\"`.)",
-        "key": "JSDOC#DEFINITIONS#LOGERROR"
-      }
+  "fr": {
+    "hello": {
+      "value": "Bonjour.",
+      "key": "FR#HELLO"
+    },
+    "goodbye": {
+      "value": "Au revoir.",
+      "key": "FR#GOODBYE"
+    },
+    "helloAlias": {
+      "value": "Bonjour.",
+      "key": "FR#HELLOALIAS"
+    },
+    "forComposed1": {
+      "value": "Bonjour",
+      "key": "FR#FORCOMPOSED1"
+    },
+    "forComposed2": {
+      "value": "au revoir.",
+      "key": "FR#FORCOMPOSED2"
     },
-    "params": {
-      "flattenedConfigData": {
-        "value": "The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values.",
-        "key": "JSDOC#PARAMS#FLATTENEDCONFIGDATA"
-      },
-      "reversedFlattenedConfigData": {
-        "value": "The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values.",
-        "key": "JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA"
-      },
-      "composedVariablesExclusives": {
-        "value": "The array of comment variables keys (implying their aliases as well) exclusively used to craft composed variables, that should be ignored by both the `resolve` and the `compress` commands.",
-        "key": "JSDOC#PARAMS#COMPOSEDVARIABLESEXCLUSIVES"
-      },
-      "aliases_flattenedKeys": {
-        "value": "The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.",
-        "key": "JSDOC#PARAMS#ALIASES_FLATTENEDKEYS"
-      },
-      "ruleName": {
-        "value": "The name of the rule currently used. (Either `\"resolve\"` or `\"compress\"`.)",
-        "key": "JSDOC#PARAMS#RULENAME"
-      },
-      "ignores": {
-        "value": "The array of paths and globs for the flow's ESLint instance to ignore.",
-        "key": "JSDOC#PARAMS#IGNORES"
-      },
-      "eitherFlattenedConfigData": {
-        "value": "Either the flattened config data or the reversed flattened config data, since they share the same structure.",
-        "key": "JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA"
-      },
-      "error": {
-        "value": "The error object being handle for the logging.",
-        "key": "JSDOC#PARAMS#ERROR"
-      },
-      "options": {
-        "value": "The additional options as follows:",
-        "key": "JSDOC#PARAMS#OPTIONS"
-      },
-      "settings": {
-        "value": "The required settings as follows:",
-        "key": "JSDOC#PARAMS#SETTINGS"
-      },
-      "configPathIgnores": {
-        "value": "The array of paths linked to the config file, (named \"ignores\" given it is ignored by the \"compress\" and \"resolve\" commands).",
-        "key": "JSDOC#PARAMS#CONFIGPATHIGNORES"
-      },
-      "originalFlattenedConfigData": {
-        "value": "The original flattened config data, before changes to aliases variables and composed variables are applied.",
-        "key": "JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA"
-      },
-      "relativeMjsPath": {
-        "value": "The relative path of the generated `.mjs` file to be ignored in the \"placeholders\" process.",
-        "key": "JSDOC#PARAMS#RELATIVEMJSPATH"
-      },
-      "variations": {
-        "value": "A boolean that determines the format of the generated placeholders according to whether or not the config is enabling variations.",
-        "key": "JSDOC#PARAMS#VARIATIONS"
-      }
+    "forComposed3": {
+      "value": "au revoir ?",
+      "key": "FR#FORCOMPOSED3"
     },
-    "returns": {
-      "exitDueToFailure": {
-        "value": "Never. (Somehow typing needs to be explicit for unreachable code inference.)",
-        "key": "JSDOC#RETURNS#EXITDUETOFAILURE"
-      },
-      "makeRuleResolve": {
-        "value": "The resolve rule based on the flattened config data.",
-        "key": "JSDOC#RETURNS#MAKERULERESOLVE"
-      },
-      "makeRuleCompress": {
-        "value": "The compress rule based on the reversed flattened config data.",
-        "key": "JSDOC#RETURNS#MAKERULECOMPRESS"
-      }
+    "composed": {
+      "value": "Bonjour au revoir.",
+      "key": "FR#COMPOSED"
     },
-    "constants": {
-      "sortedReversedFlattenedConfigData": {
-        "value": "The whole `reversedFlattenedConfigData` turned from an object to an array of key-value arrays sorted by the descending length of each key to prevent partial replacements.",
-        "key": "JSDOC#CONSTANTS#SORTEDREVERSEDFLATTENEDCONFIGDATA"
-      },
-      "composedVariablesExclusivesSet": {
-        "value": "A local Set out of composed variables exclusives for speed.",
-        "key": "JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET"
-      }
+    "composedWithAlias": {
+      "value": "Bonjour au revoir. Bonjour.",
+      "key": "FR#COMPOSEDWITHALIAS"
     }
   }
 }

package/generate.example.js

@@ -2,6 +2,5 @@
 
 // This is a comment.
 // $COMMENT#ALIAS // ALIAS
-// Yes.
 // This is a comment. Yes. This is a comment.
 // $COMMENT#COMMENTS#NO

package/generate.template.js

@@ -22,12 +22,15 @@ const myIgnoresOnly = false; // can be omitted
 
 const composedVariablesExclusives = []; // can be omitted
 
+const variations = undefined; // can be omitted
+
 const config = {
   data,
   ignores,
   lintConfigImports,
   myIgnoresOnly,
   composedVariablesExclusives,
+  variations,
 };
 
 export default config;

package/generate.variations.js

@@ -0,0 +1,93 @@
+// The Comment Variables config template generated in case no config file has been found.
+
+// Just flip the `variations` object's `variant` key back and forth between `EN` and `FR` and see what happens on the accompanying `comments.example.js` file that has also been generated.
+
+/* variants */
+
+const EN = "en";
+const ENGLISH = "English";
+const FR = "fr";
+const FRANÇAIS = "français";
+
+/* data */
+
+const enData = Object.freeze({
+  comment: "This is a comment.",
+  alias: "EN#COMMENT",
+  composed: "$COMMENT#EN#COMMENT $COMMENT#EN#COMMENTS#YES $COMMENT#EN#ALIAS",
+  comments: Object.freeze({
+    yes: "Yes.",
+    no: "No.",
+  }),
+});
+
+const frData = Object.freeze({
+  comment: "Ceci est un commentaire.",
+  alias: "FR#COMMENT",
+  composed: "$COMMENT#FR#COMMENT $COMMENT#FR#COMMENTS#YES $COMMENT#FR#ALIAS",
+  comments: Object.freeze({
+    yes: "Oui.",
+    no: "Non.",
+  }),
+});
+
+const data = Object.freeze({
+  [EN]: enData,
+  [FR]: frData,
+});
+
+/* ignores */
+
+const ignores = [];
+
+/* lintConfigImports */
+
+const lintConfigImports = false; // can be omitted
+
+/* myIgnoresOnly */
+
+const myIgnoresOnly = false; // can be omitted
+
+/* composedVariablesExclusives */
+
+const enComposedVariablesExclusives = ["EN#COMMENTS#YES"];
+
+const frComposedVariablesExclusives = ["FR#COMMENTS#YES"];
+
+const composedVariablesExclusives = [
+  ...enComposedVariablesExclusives,
+  ...frComposedVariablesExclusives,
+]; // can be omitted
+
+/* variations */
+
+const variations = {
+  // 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.
+  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.
+  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,
+}; // can be omitted
+
+const config = {
+  data,
+  ignores,
+  lintConfigImports,
+  myIgnoresOnly,
+  composedVariablesExclusives,
+  variations,
+};
+
+export default config;
+
+// Once you've grasped these concepts, simply rename this file, its JSON counterpart and its `.mjs` counterpart to `comments.config.js`, `comments.config.json` and `comments.config.mjs` respectively and you're good to go. (If you're using the extension, make sure to run VS Code's "Developer: Reload Window" command for the extension to operate based on your new `comments.config.js` file.)
+
+// When it comes to the VS Code extension, variations are only compatible with versions 2 and above.

package/library/_commons/constants/bases.js

@@ -26,3 +26,7 @@ export const allMDVirtualJSTSFileGlobs = [
   "**/*.md/*.cjs",
   "**/*.md/*.mjs",
 ];
+
+// prompts choices values
+export const classic = "classic";
+export const withVariations = "with variations";

package/library/_commons/rules/compress.js

@@ -5,18 +5,18 @@ import {
 } from "comment-variables-resolve-config";
 
 /**
- * The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into `$COMMENT` placeholders.
- * @param {{[key: string]: string}} reversedFlattenedConfigData The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values.
- * @param {string[]} composedVariablesExclusives The array of comment variables keys (implying their aliases as well) exclusively used to craft composed variables, that should be ignored by both the `resolve` and the `compress` commands.
- * @returns The compress rule based on the reversed flattened config data.
+ * $COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS
+ * @param {{[key: string]: string}} reversedFlattenedConfigData $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
+ * @param {string[]} composedVariablesExclusives $COMMENT#JSDOC#PARAMS#COMPOSEDVARIABLESEXCLUSIVES
+ * @returns $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS
  */
 const makeRule = (reversedFlattenedConfigData, composedVariablesExclusives) => {
-  /** The whole `reversedFlattenedConfigData` turned from an object to an array of key-value arrays sorted by the descending length of each key to prevent partial replacements. */
+  /** $COMMENT#JSDOC#CONSTANTS#SORTEDREVERSEDFLATTENEDCONFIGDATA */
   const sortedReversedFlattenedConfigData = Object.entries(
     reversedFlattenedConfigData
   ).sort(([a], [b]) => b.length - a.length);
 
-  /** A local Set out of composed variables exclusives for speed. */
+  /** $COMMENT#JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET */
   const composedVariablesExclusivesSet = new Set(composedVariablesExclusives);
 
   /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */

package/library/_commons/rules/resolve.js

@@ -4,18 +4,18 @@ import {
 } from "comment-variables-resolve-config";
 
 /**
- * The utility that creates the resolve rule based on the flattened config data, used to transform `$COMMENT` placeholders into actual comments.
- * @param {{[key: string]: string}} flattenedConfigData The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values.
- * @param {string[]} composedVariablesExclusives The array of comment variables keys (implying their aliases as well) exclusively used to craft composed variables, that should be ignored by both the `resolve` and the `compress` commands.
- * @param {{[key: string]: string}} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
- * @returns The resolve rule based on the flattened config data.
+ * $COMMENT#JSDOC#DEFINITIONS#MAKERULERESOLVE
+ * @param {{[key: string]: string}} flattenedConfigData $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
+ * @param {string[]} composedVariablesExclusives $COMMENT#JSDOC#PARAMS#COMPOSEDVARIABLESEXCLUSIVES
+ * @param {{[key: string]: string}} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
+ * @returns $COMMENT#JSDOC#RETURNS#MAKERULERESOLVE
  */
 const makeRule = (
   flattenedConfigData,
   composedVariablesExclusives,
   aliases_flattenedKeys
 ) => {
-  /** A local Set out of composed variables exclusives for speed. */
+  /** $COMMENT#JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET */
   const composedVariablesExclusivesSet = new Set(composedVariablesExclusives);
 
   /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */

package/library/_commons/utilities/flows.js

@@ -21,12 +21,12 @@ import { ruleNames_makeRules } from "../constants/rules.js";
 /* coreCommentsFlow */
 
 /**
- * The core flow at the heart of resolving and compressing comments.
- * @param {typeof resolveRuleName | typeof compressRuleName} ruleName The name of the rule currently used. (Either `"resolve"` or `"compress"`.)
- * @param {string[]} ignores The array of paths and globs for the flow's ESLint instance to ignore.
- * @param {{[key: string]: string}} flattenedConfigData Either the flattened config data or the reversed flattened config data, since they share the same structure.
- * @param {string[]} composedVariablesExclusives The array of comment variables keys (implying their aliases as well) exclusively used to craft composed variables, that should be ignored by both the `resolve` and the `compress` commands.
- * @param {Record<string, string> | undefined} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
+ * $COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW
+ * @param {typeof resolveRuleName | typeof compressRuleName} ruleName $COMMENT#JSDOC#PARAMS#RULENAME
+ * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
+ * @param {{[key: string]: string}} flattenedConfigData $COMMENT#JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA
+ * @param {string[]} composedVariablesExclusives $COMMENT#JSDOC#PARAMS#COMPOSEDVARIABLESEXCLUSIVES
+ * @param {Record<string, string> | undefined} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
  * @returns
  */
 const coreCommentsFlow = async (
@@ -107,11 +107,11 @@ const coreCommentsFlow = async (
 /* resolveCommentsFlow */
 
 /**
- * The flow that resolves `$COMMENT` placeholders into actual comments.
- * @param {string[]} ignores The array of paths and globs for the flow's ESLint instance to ignore.
- * @param {Record<string, string>} flattenedConfigData The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values.
- * @param {string[]} composedVariablesExclusives The array of comment variables keys (implying their aliases as well) exclusively used to craft composed variables, that should be ignored by both the `resolve` and the `compress` commands.
- * @param {Record<string, string>} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
+ * $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW
+ * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
+ * @param {Record<string, string>} flattenedConfigData $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
+ * @param {string[]} composedVariablesExclusives $COMMENT#JSDOC#PARAMS#COMPOSEDVARIABLESEXCLUSIVES
+ * @param {Record<string, string>} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
  * @returns
  */
 export const resolveCommentsFlow = async (
@@ -131,10 +131,10 @@ export const resolveCommentsFlow = async (
 /* compressCommentsFlow */
 
 /**
- * The flow that compresses actual comments into `$COMMENT` placeholders.
- * @param {string[]} ignores The array of paths and globs for the flow's ESLint instance to ignore.
- * @param {{[key: string]: string}} reversedFlattenedConfigData The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values.
- * @param {string[]} composedVariablesExclusives The array of comment variables keys (implying their aliases as well) exclusively used to craft composed variables, that should be ignored by both the `resolve` and the `compress` commands.
+ * $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW
+ * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
+ * @param {{[key: string]: string}} reversedFlattenedConfigData $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
+ * @param {string[]} composedVariablesExclusives $COMMENT#JSDOC#PARAMS#COMPOSEDVARIABLESEXCLUSIVES
  * @returns
  */
 export const compressCommentsFlow = async (
@@ -152,12 +152,12 @@ export const compressCommentsFlow = async (
 /* placeholdersCommentsFlow */
 
 /**
- * The flow that creates `$COMMENT` placeholders right next to where they're defined.
- * @param {string[]} configPathIgnores The array of paths linked to the config file, (named "ignores" given it is ignored by the "compress" and "resolve" commands).
- * @param {{[k: string]: string;}} originalFlattenedConfigData The original flattened config data, before changes to aliases variables and composed variables are applied.
- * @param {Record<string, string>} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
- * @param {string} relativeMjsPath The relative path of the generated `.mjs` file to be ignored in the "placeholders" process.
- * @param {boolean} variations A boolean that determines the format of the generated placeholders according to whether or not the config is enabling variations.
+ * $COMMENT#JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW
+ * @param {string[]} configPathIgnores $COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES
+ * @param {{[k: string]: string;}} originalFlattenedConfigData $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA
+ * @param {Record<string, string>} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
+ * @param {string} relativeMjsPath $COMMENT#JSDOC#PARAMS#RELATIVEMJSPATH
+ * @param {boolean} variations $COMMENT#JSDOC#PARAMS#VARIATIONS
  * @returns
  */
 export const placeholdersCommentsFlow = async (

package/library/_commons/utilities/helpers.js

@@ -1,16 +1,16 @@
 /* exitDueToFailure */
 
 /**
- * Terminates the whole process with a 'failure' code (`1`).
- * @returns {never} Never. (Somehow typing needs to be explicit for unreachable code inference.)
+ * $COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE
+ * @returns {never} $COMMENT#JSDOC#RETURNS#EXITDUETOFAILURE
  */
 export const exitDueToFailure = () => process.exit(1);
 
 /* logError */
 
 /**
- * Logs an error to the console depending on its type. (`"error"` or `"warning"`.)
- * @param {{type: "error" | "warning"; message: string}} error The error object being handle for the logging.
+ * $COMMENT#JSDOC#DEFINITIONS#LOGERROR
+ * @param {{type: "error" | "warning"; message: string}} error $COMMENT#JSDOC#PARAMS#ERROR
  * @returns
  */
 export const logError = (error) => {

package/library/index.js

@@ -5,6 +5,8 @@ import path from "path";
 import fs from "fs";
 import url from "url";
 
+import prompts from "prompts";
+
 import resolveConfig, {
   defaultConfigFileName,
   templateFileName,
@@ -22,7 +24,12 @@ import resolveConfig, {
   makeMjsPathLog,
 } from "comment-variables-resolve-config";
 
-import { hasPackageJson, hasGitFolder } from "./_commons/constants/bases.js";
+import {
+  hasPackageJson,
+  hasGitFolder,
+  classic,
+  withVariations,
+} from "./_commons/constants/bases.js";
 
 import { exitDueToFailure, logError } from "./_commons/utilities/helpers.js";
 import {
@@ -80,17 +87,80 @@ if (!fs.existsSync(rawConfigPath)) {
     `No Comment Variables config file found at ${rawConfigPath}. Switching to tutorial mode.`
   );
 
-  const templateFilePath = path.join(cwd, templateFileName);
-  const exampleFilePath = path.join(cwd, exampleFileName);
+  /* TEST START (success) */
+
+  const tutorialConfig = {
+    templateFilePath: path.join(cwd, templateFileName),
+    generateTemplateFilePath: "",
+    exampleFilePath: path.join(cwd, exampleFileName), // common to "classic" and "with variations", highlights compatibility
+    generateExampleFilePath: "../generate.example.js",
+  };
+
+  const classicOrWithVariations = await prompts({
+    type: "select",
+    name: "value",
+    message:
+      "Would you like to generate a classic template (simple) or a template with variations (advanced) instead?",
+    choices: [
+      {
+        title: classic,
+        description:
+          "Simple. For those who discover Comment Variables and have no immediate need for internationalization.",
+        value: classic,
+      },
+      {
+        title: withVariations,
+        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,
+      },
+    ],
+    initial: 0,
+  });
+
+  /**
+   * @type {typeof classic | typeof withVariations}
+   * `control+C` returns `undefined`.
+   */
+  const classicOrWithVariationsValue = classicOrWithVariations.value;
+
+  if (!classicOrWithVariationsValue) {
+    console.error(
+      "ERROR. No template selected. Please select a template to begin using comment-variables via this CLI."
+    );
+    exitDueToFailure();
+  }
+
+  switch (classicOrWithVariationsValue) {
+    case classic:
+      tutorialConfig.generateTemplateFilePath = "../generate.template.js";
+      break;
+    case withVariations:
+      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.
+      );
+      exitDueToFailure();
+  }
+
+  const {
+    templateFilePath,
+    generateTemplateFilePath,
+    exampleFilePath,
+    generateExampleFilePath,
+  } = tutorialConfig;
+
+  /* TEST END */
+
   const dirname = path.dirname(url.fileURLToPath(import.meta.url));
 
   if (fs.existsSync(templateFilePath)) {
     console.log(`Proceeding with template file found at ${templateFilePath}.`);
   } else {
-    const sourceTemplateFilePath = path.join(
-      dirname,
-      "../generate.template.js"
-    );
+    const sourceTemplateFilePath = path.join(dirname, generateTemplateFilePath);
     console.log(`Generating template file at ${templateFilePath}.`);
     fs.copyFileSync(sourceTemplateFilePath, templateFilePath);
   }
@@ -98,7 +168,7 @@ if (!fs.existsSync(rawConfigPath)) {
   if (fs.existsSync(exampleFilePath)) {
     console.log(`Proceeding with example file found at ${exampleFilePath}.`);
   } else {
-    const sourceExampleFilePath = path.join(dirname, "../generate.example.js");
+    const sourceExampleFilePath = path.join(dirname, generateExampleFilePath);
     console.log(`Generating example file at ${exampleFilePath}.`);
     fs.copyFileSync(sourceExampleFilePath, exampleFilePath);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
     "comment-variables": "./library/index.js",
@@ -13,6 +13,7 @@
     "comments.config.js",
     "comments.config.json",
     "generate.template.js",
+    "generate.variations.js",
     "generate.example.js",
     "jscomments"
   ],
@@ -32,7 +33,8 @@
   "dependencies": {
     "@eslint/markdown": "^6.5.0",
     "comment-variables-resolve-config": "^1.17.1",
-    "eslint": "^9.29.0"
+    "eslint": "^9.29.0",
+    "prompts": "^2.4.2"
   },
   "devDependencies": {
     "@typescript-eslint/utils": "^8.34.0"