comment-variables 1.4.1 → 1.5.0

package/README.md

@@ -107,7 +107,7 @@ In due time, you may end up creating Comment Variables that are exclusively mean
 
 ## **`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.0",
   "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"