comment-variables 1.2.5 → 1.3.1

package/README.md

@@ -1,6 +1,6 @@
 # comment-variables
 
-![Name and logo for the Comment Variables ecosystem, dark default variant.](./assets/README/name-dark-default.png)
+![Logo and name for the Comment Variables ecosystem, dark default variant.](./assets/README/name-dark-default.png)
 
 <!-- <picture>
   <source media="(prefers-color-scheme: dark)" srcset="./assets/README/name-dark-default.png">
@@ -197,4 +197,4 @@ And yes, even comments within JavaScript and TypeScript blocks in Markdown files
 
 _Leverage the power of JavaScript to programmatically design your JavaScript comments._
 
-**The Comment Variables VS Code extension is available [here](https://comvar.lemonsqueezy.com/buy/723b0220-ea5d-4b0a-835a-f0843e431639?logo=0&discount=0).**
+**The Comment Variables VS Code extension is available [here](https://comvar.lemonsqueezy.com/buy/723b0220-ea5d-4b0a-835a-f0843e431639).**

package/comments.config.js

@@ -1,141 +1,26 @@
-// const obj = { test: "Testing." }; // errors, object string values in config files are reserved for exports from the config.
-
-const data = {
-  // for testing
-  levelOne: {
-    levelTwo: {
-      levelThree: "Level three." /* $COMMENT#LEVELONE#LEVELTWO#LEVELTHREE */, // New placeholder structure. Not as sexy, but first and foremost guaranteed to be functional appended right at the end of the value as a Block comment, and last but not least also guaranteed to not modify Value Locations in the process. So `comment-variables placeholders` it is, and this justifies enforcing strings only for values even outside of the use of the VS Code extension.
-      // levelThreeEscape:
-      //   "Level three. \
-      //       fdff\
-      // " /* $COMMENT#LEVELONE#LEVELTWO#LEVELTHREEESCAPE */, // NOW ERRORS AS INTENDED, unrecognizedValuesSet
-      stillLevelThree:
-        "LEVELONE#LEVELTWO#LEVELTHREE" /* $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE */, // now is an alias
-      otherLevelThree:
-        "LEVELONE#LEVELTWO#LEVELTHREE" /* $COMMENT#LEVELONE#LEVELTWO#OTHERLEVELTHREE */, // also an alias
-      composedVariable:
-        "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE" /* $COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE */, // This is a composed variable. What's the beauty in this? It allows for each comment variable to be its own single source of truth that can be reused still within the Comment Variables ecosystem. All while preventing the use of Comment Variables placeholders as values in the config. AND as a matter of fact, it even works... with aliases.
-      composedVariableAlias:
-        "LEVELONE#LEVELTWO#COMPOSEDVARIABLE" /* $COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLEALIAS */, // The alias of a composed variable. SO just like composed variables can incorporate aliases, aliases can be aliases for composed variables.
-
-      // otherLevelThreeAlias:
-      //   "LEVELONE#LEVELTWO#OTHERLEVELTHREE" /* $COMMENT#LEVELONE#LEVELTWO#LEVELTHREE */, // errors, can't be the alias of another alias
-
-      // composedOfAlias:
-      //   "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE $COMMENT#LEVELONE#LEVELTWO#ALIASOFCOMPOSED" /* $COMMENT#LEVELONE#LEVELTWO#COMPOSEDOFALIAS */, // 1/2 already errored // ERROR. A potential composed variable cannot be used as the comment variable of another composed variable.
-      // aliasOfComposed:
-      //   "LEVELONE#LEVELTWO#COMPOSEDOFALIAS" /* $COMMENT#LEVELONE#LEVELTWO#ALIASOFCOMPOSED */, // 2/2 What if an alias variable was a segment to a composed variable made of itself? // ERROR. The alias "LEVELONE#LEVELTWO#ALIASOFCOMPOSED" links to composed variable "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE $COMMENT#LEVELONE#LEVELTWO#ALIASOFCOMPOSED" that includes LEVELONE#LEVELTWO#ALIASOFCOMPOSED's placeholder as a segment.
-
-      // aliasInComposed:
-      //   "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE $COMMENT#LEVELONE#LEVELTWO#ALIASINCOMPOSED", // What if a composed variable had its own value has one of its segments? Composed variables already cannot compose other composed variables. // errors, "ERROR. A potential composed variable cannot be used as the comment variable of another composed variable."
-      // wrongComposedVariable:
-      //   "$COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE", // errors, can't make composed variables with composed variables
-      // wrongComposedVariableToo:
-      //   "$COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE $COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE", // errors, can't make composed variables with composed variables even as aliases
-      // levelthree: "Also level three.", // errors, duplicate normalized key
-      // levelThree: "Also level three.", // errors, duplicate key with original overriden by legal JavaScript object value overrides
-      // alsoLevelThree: "Level three.", // errors, duplicate value
-      // tooLevelThree: 2, // errors, value is invalid
-      // $levelThree: "Dollar sign", // errors, key as "$" character
-      // "#levelThree": "Hashtag", // errors, key as "#" character
-      // ".levelThree": "Punctuation", // errors, key is invalid due to punctuation
-      // unrecognized: `Unrecognized value.`, // errors, is not a string literal
-      // emptyString: "", // errors, string is empty
-      // "": "emptyKey", // errors, key is empty caught by the regex
-      // ownAliasKey: "LEVELONE#LEVELTWO#OWNALIASKEY", // errors, is its own key/alias
-      // key: "key not allowed", // errors, "key", "value" and "placeholder" not allowed
-      // value: "value not allowed", // errors, "key", "value" and "placeholder" not allowed
-      placeholder: "placeholder now allowed", // doesn't error, "placeholder" is now allowed
-      // noConcat: "no" + "concat", // errors, unrecognized value
-
-      // already error via regex, but now enhanced:
-      // "//": "key comment error 1",
-      // "/*": "key comment error 2",
-      // "*/": "key comment error 3",
-      // error directly in resolveConfig:
-      // "key comment error 1": "//",
-      // "key comment error 2": "/*",
-      // "key comment error 3": "*/",
-    },
-  },
-  // for deving
-  jsDoc: Object.freeze({
-    definitions: Object.freeze({
-      exitDueToFailure:
-        "Terminates the whole process with a 'failure' code (`1`)." /* $COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE */,
-      makeRuleResolve:
-        "The utility that creates the resolve rule based on the flattened config data, used to transform `$COMMENT` placeholders into actual comments." /* $COMMENT#JSDOC#DEFINITIONS#MAKERULERESOLVE */,
-      makeRuleCompress:
-        "The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into `$COMMENT` placeholders." /* $COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS */,
-      coreCommentsFlow:
-        "The core flow at the heart of resolving and compressing comments." /* $COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW */,
-      resolveCommentsFlow:
-        "The flow that resolves `$COMMENT` placeholders into actual comments." /* $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW */,
-      compressCommentsFlow:
-        "The flow that compresses actual comments into `$COMMENT` placeholders." /* $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW */,
-      placeholdersCommentsFlow:
-        "The flow that creates `$COMMENT` placeholders right next to where they're defined." /* $COMMENT#JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW */,
-      logError:
-        'Logs an error to the console depending on its type. (`"error"` or `"warning"`.)' /* $COMMENT#JSDOC#DEFINITIONS#LOGERROR */,
-    }),
-    params: Object.freeze({
-      flattenedConfigData:
-        "The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values." /* $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA */,
-      reversedFlattenedConfigData:
-        "The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values." /* $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA */,
-      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#PARAMS#COMPOSEDVARIABLESEXCLUSIVES */,
-      aliases_flattenedKeys:
-        "The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias." /* $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS */,
-      ruleName:
-        'The name of the rule currently used. (Either `"resolve"` or `"compress"`.)' /* $COMMENT#JSDOC#PARAMS#RULENAME */,
-      ignores:
-        "The array of paths and globs for the flow's ESLint instance to ignore." /* $COMMENT#JSDOC#PARAMS#IGNORES */,
-      eitherFlattenedConfigData:
-        "Either the flattened config data or the reversed flattened config data, since they share the same structure." /* $COMMENT#JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA */,
-      error:
-        "The error object being handle for the logging." /* $COMMENT#JSDOC#PARAMS#ERROR */,
-      options:
-        "The additional options as follows:" /* $COMMENT#JSDOC#PARAMS#OPTIONS */,
-      settings:
-        "The required settings as follows:" /* $COMMENT#JSDOC#PARAMS#SETTINGS */,
-      configPathIgnores:
-        'The array of paths linked to the config file, (named "ignores" given it is ignored by the "compress" and "resolve" commands).' /* $COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES */,
-      originalFlattenedConfigData:
-        "The original flattened config data, before changes to aliases variables and composed variables are applied." /* $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA */,
-      relativeMjsPath:
-        'The relative path of the generated `.mjs` file to be ignored in the "placeholders" process.' /* $COMMENT#JSDOC#PARAMS#RELATIVEMJSPATH */,
-    }),
-    returns: Object.freeze({
-      exitDueToFailure:
-        "Never. (Somehow typing needs to be explicit for unreachable code inference.)" /* $COMMENT#JSDOC#RETURNS#EXITDUETOFAILURE */,
-      makeRuleResolve:
-        "The resolve rule based on the flattened config data." /* $COMMENT#JSDOC#RETURNS#MAKERULERESOLVE */,
-      makeRuleCompress:
-        "The compress rule based on the reversed flattened config data." /* $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS */,
-    }),
-    constants: Object.freeze({
-      sortedReversedFlattenedConfigData:
-        "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 */,
-      composedVariablesExclusivesSet:
-        "A local Set out of composed variables exclusives for speed." /* $COMMENT#JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET */,
-    }),
-  }),
-};
+import {
+  coreData as data,
+  composedVariablesExclusives,
+  variations,
+} 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"];
 
 const lintConfigImports = false; // can be omitted
 const myIgnoresOnly = false; // can be omitted
 
-const composedVariablesExclusives = []; // can be omitted
-
 const config = {
   data,
   ignores,
   lintConfigImports,
   myIgnoresOnly,
   composedVariablesExclusives,
+  variations,
 };
 
 export default config;

package/comments.config.json

@@ -114,6 +114,10 @@
       "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"
       }
     },
     "returns": {

package/generate.example.js

@@ -1,7 +1,7 @@
 // A JavaScript file that acts as an example file for the generated Comment Variables template config. Assuming you've yet to produce your own `comments.config.js` file, use the `comment-variables compress` and `comment-variables resolve` commands to see how the following comments go back and forth from Comment Variables placeholders (`$COMMENT`) to actual comments, reversibly.
 
 // This is a comment.
-// $COMMENT#ALIAS
+// $COMMENT#ALIAS // ALIAS
 // Yes.
 // This is a comment. Yes. This is a comment.
 // $COMMENT#COMMENTS#NO

package/jscomments/core/data.js

@@ -0,0 +1,12 @@
+import { forTesting } from "./for-testing.js";
+import { forDeving } from "./for-deving.js";
+
+export const coreData = Object.freeze({
+  ...forTesting,
+  ...forDeving,
+});
+
+export const composedVariablesExclusives = []; // can be omitted
+
+// NEW from v2
+export const variations = undefined; // can be omitted

package/jscomments/core/for-deving.js

@@ -0,0 +1,67 @@
+export const forDeving = {
+  // for deving
+  jsDoc: Object.freeze({
+    definitions: Object.freeze({
+      exitDueToFailure:
+        "Terminates the whole process with a 'failure' code (`1`)." /* $COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE */,
+      makeRuleResolve:
+        "The utility that creates the resolve rule based on the flattened config data, used to transform `$COMMENT` placeholders into actual comments." /* $COMMENT#JSDOC#DEFINITIONS#MAKERULERESOLVE */,
+      makeRuleCompress:
+        "The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into `$COMMENT` placeholders." /* $COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS */,
+      coreCommentsFlow:
+        "The core flow at the heart of resolving and compressing comments." /* $COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW */,
+      resolveCommentsFlow:
+        "The flow that resolves `$COMMENT` placeholders into actual comments." /* $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW */,
+      compressCommentsFlow:
+        "The flow that compresses actual comments into `$COMMENT` placeholders." /* $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW */,
+      placeholdersCommentsFlow:
+        "The flow that creates `$COMMENT` placeholders right next to where they're defined." /* $COMMENT#JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW */,
+      logError:
+        'Logs an error to the console depending on its type. (`"error"` or `"warning"`.)' /* $COMMENT#JSDOC#DEFINITIONS#LOGERROR */,
+    }),
+    params: Object.freeze({
+      flattenedConfigData:
+        "The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values." /* $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA */,
+      reversedFlattenedConfigData:
+        "The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values." /* $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA */,
+      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#PARAMS#COMPOSEDVARIABLESEXCLUSIVES */,
+      aliases_flattenedKeys:
+        "The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias." /* $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS */,
+      ruleName:
+        'The name of the rule currently used. (Either `"resolve"` or `"compress"`.)' /* $COMMENT#JSDOC#PARAMS#RULENAME */,
+      ignores:
+        "The array of paths and globs for the flow's ESLint instance to ignore." /* $COMMENT#JSDOC#PARAMS#IGNORES */,
+      eitherFlattenedConfigData:
+        "Either the flattened config data or the reversed flattened config data, since they share the same structure." /* $COMMENT#JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA */,
+      error:
+        "The error object being handle for the logging." /* $COMMENT#JSDOC#PARAMS#ERROR */,
+      options:
+        "The additional options as follows:" /* $COMMENT#JSDOC#PARAMS#OPTIONS */,
+      settings:
+        "The required settings as follows:" /* $COMMENT#JSDOC#PARAMS#SETTINGS */,
+      configPathIgnores:
+        'The array of paths linked to the config file, (named "ignores" given it is ignored by the "compress" and "resolve" commands).' /* $COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES */,
+      originalFlattenedConfigData:
+        "The original flattened config data, before changes to aliases variables and composed variables are applied." /* $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA */,
+      relativeMjsPath:
+        'The relative path of the generated `.mjs` file to be ignored in the "placeholders" process.' /* $COMMENT#JSDOC#PARAMS#RELATIVEMJSPATH */,
+      variations:
+        "A boolean that determines the format of the generated placeholders according to whether or not the config is enabling variations." /* $COMMENT#JSDOC#PARAMS#VARIATIONS */,
+    }),
+    returns: Object.freeze({
+      exitDueToFailure:
+        "Never. (Somehow typing needs to be explicit for unreachable code inference.)" /* $COMMENT#JSDOC#RETURNS#EXITDUETOFAILURE */,
+      makeRuleResolve:
+        "The resolve rule based on the flattened config data." /* $COMMENT#JSDOC#RETURNS#MAKERULERESOLVE */,
+      makeRuleCompress:
+        "The compress rule based on the reversed flattened config data." /* $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS */,
+    }),
+    constants: Object.freeze({
+      sortedReversedFlattenedConfigData:
+        "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 */,
+      composedVariablesExclusivesSet:
+        "A local Set out of composed variables exclusives for speed." /* $COMMENT#JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET */,
+    }),
+  }),
+};

package/jscomments/core/for-testing.js

@@ -0,0 +1,61 @@
+// const obj = { test: "Testing." }; // errors, object string values in config files are reserved for exports from the config.
+
+export const forTesting = {
+  // for testing (I didn't do the full freeze on this one.)
+  levelOne: {
+    levelTwo: {
+      levelThree: "Level three." /* $COMMENT#LEVELONE#LEVELTWO#LEVELTHREE */, // New placeholder structure. Not as sexy, but first and foremost guaranteed to be functional appended right at the end of the value as a Block comment, and last but not least also guaranteed to not modify Value Locations in the process. So `comment-variables placeholders` it is, and this justifies enforcing strings only for values even outside of the use of the VS Code extension.
+      // levelThreeEscape:
+      //   "Level three. \
+      //       fdff\
+      // " /* $COMMENT#LEVELONE#LEVELTWO#LEVELTHREEESCAPE */, // NOW ERRORS AS INTENDED, unrecognizedValuesSet
+      stillLevelThree:
+        "LEVELONE#LEVELTWO#LEVELTHREE" /* $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE */, // now is an alias
+      otherLevelThree:
+        "LEVELONE#LEVELTWO#LEVELTHREE" /* $COMMENT#LEVELONE#LEVELTWO#OTHERLEVELTHREE */, // also an alias
+      composedVariable:
+        "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE" /* $COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE */, // This is a composed variable. What's the beauty in this? It allows for each comment variable to be its own single source of truth that can be reused still within the Comment Variables ecosystem. All while preventing the use of Comment Variables placeholders as values in the config. AND as a matter of fact, it even works... with aliases.
+      composedVariableAlias:
+        "LEVELONE#LEVELTWO#COMPOSEDVARIABLE" /* $COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLEALIAS */, // The alias of a composed variable. SO just like composed variables can incorporate aliases, aliases can be aliases for composed variables.
+
+      // otherLevelThreeAlias:
+      //   "LEVELONE#LEVELTWO#OTHERLEVELTHREE" /* $COMMENT#LEVELONE#LEVELTWO#LEVELTHREE */, // errors, can't be the alias of another alias
+
+      // composedOfAlias:
+      //   "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE $COMMENT#LEVELONE#LEVELTWO#ALIASOFCOMPOSED" /* $COMMENT#LEVELONE#LEVELTWO#COMPOSEDOFALIAS */, // 1/2 already errored // ERROR. A potential composed variable cannot be used as the comment variable of another composed variable.
+      // aliasOfComposed:
+      //   "LEVELONE#LEVELTWO#COMPOSEDOFALIAS" /* $COMMENT#LEVELONE#LEVELTWO#ALIASOFCOMPOSED */, // 2/2 What if an alias variable was a segment to a composed variable made of itself? // ERROR. The alias "LEVELONE#LEVELTWO#ALIASOFCOMPOSED" links to composed variable "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE $COMMENT#LEVELONE#LEVELTWO#ALIASOFCOMPOSED" that includes LEVELONE#LEVELTWO#ALIASOFCOMPOSED's placeholder as a segment.
+
+      // aliasInComposed:
+      //   "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE $COMMENT#LEVELONE#LEVELTWO#ALIASINCOMPOSED", // What if a composed variable had its own value has one of its segments? Composed variables already cannot compose other composed variables. // errors, "ERROR. A potential composed variable cannot be used as the comment variable of another composed variable."
+      // wrongComposedVariable:
+      //   "$COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE", // errors, can't make composed variables with composed variables
+      // wrongComposedVariableToo:
+      //   "$COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE $COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE", // errors, can't make composed variables with composed variables even as aliases
+      // levelthree: "Also level three.", // errors, duplicate normalized key
+      // levelThree: "Also level three.", // errors, duplicate key with original overriden by legal JavaScript object value overrides
+      // alsoLevelThree: "Level three.", // errors, duplicate value
+      // tooLevelThree: 2, // errors, value is invalid
+      // $levelThree: "Dollar sign", // errors, key as "$" character
+      // "#levelThree": "Hashtag", // errors, key as "#" character
+      // ".levelThree": "Punctuation", // errors, key is invalid due to punctuation
+      // unrecognized: `Unrecognized value.`, // errors, is not a string literal
+      // emptyString: "", // errors, string is empty
+      // "": "emptyKey", // errors, key is empty caught by the regex
+      // ownAliasKey: "LEVELONE#LEVELTWO#OWNALIASKEY", // errors, is its own key/alias
+      // key: "key not allowed", // errors, "key", "value" and "placeholder" not allowed
+      // value: "value not allowed", // errors, "key", "value" and "placeholder" not allowed
+      // noConcat: "no" + "concat", // errors, unrecognized value
+      placeholder: "placeholder now allowed", // doesn't error, "placeholder" is now allowed
+
+      // already error via regex, but now enhanced:
+      // "//": "key comment error 1",
+      // "/*": "key comment error 2",
+      // "*/": "key comment error 3",
+      // error directly in resolveConfig:
+      // "key comment error 1": "//",
+      // "key comment error 2": "/*",
+      // "key comment error 3": "*/",
+    },
+  },
+};

package/jscomments/variations/constants.js

@@ -0,0 +1,4 @@
+export const EN = "en";
+export const ENGLISH = "English";
+export const FR = "fr";
+export const FRANÇAIS = "français";

package/jscomments/variations/data.js

@@ -0,0 +1,25 @@
+import { EN, FR, ENGLISH, FRANÇAIS } from "./constants.js";
+import { enTestData, frTestData } from "./test-data.js";
+
+export const variationsData = Object.freeze({
+  [EN]: Object.freeze(enTestData),
+  [FR]: Object.freeze(frTestData),
+});
+
+export const composedVariablesExclusives = ["FR#FORCOMPOSED3"]; // can be omitted
+
+// const HELLO = "Hello.";
+
+export const variations = {
+  variants: {
+    [EN]: { label: ENGLISH }, // `English`
+    [FR]: { label: FRANÇAIS }, // `français`
+  },
+  variant: FR,
+
+  referenceData: enTestData,
+  // referenceData: { hello: HELLO }, // correctly errors (reference only) (with OG enTestData)
+  // referenceData: { ...enTestData }, // correctly errors (reference only) (with OG enTestData)
+  // also
+  referenceVariant: EN,
+};

package/jscomments/variations/test-data.js

@@ -0,0 +1,40 @@
+// export const enTestData = { hello: "Hello." };
+// export const enTestData = { hello: "Hello.", goodbye: "Goodbye." }; // goodbye is missing (with OG frTestData)
+export const enTestData = Object.freeze({
+  hello: "Hello." /* variations: $COMMENT#HELLO / core: $COMMENT#EN#HELLO */,
+  goodbye:
+    "Goodbye." /* variations: $COMMENT#GOODBYE / core: $COMMENT#EN#GOODBYE */,
+  helloAlias:
+    "EN#HELLO" /* variations: $COMMENT#HELLOALIAS / core: $COMMENT#EN#HELLOALIAS */,
+  forComposed1:
+    "Hello" /* variations: $COMMENT#FORCOMPOSED1 / core: $COMMENT#EN#FORCOMPOSED1 */,
+  forComposed2:
+    "goodbye." /* variations: $COMMENT#FORCOMPOSED2 / core: $COMMENT#EN#FORCOMPOSED2 */,
+  composed:
+    "$COMMENT#EN#FORCOMPOSED1 $COMMENT#EN#FORCOMPOSED2" /* variations: $COMMENT#COMPOSED / core: $COMMENT#EN#COMPOSED */,
+  composedWithAlias:
+    "$COMMENT#EN#FORCOMPOSED1 $COMMENT#EN#FORCOMPOSED2 $COMMENT#EN#HELLOALIAS" /* variations: $COMMENT#COMPOSEDWITHALIAS / core: $COMMENT#EN#COMPOSEDWITHALIAS */,
+  // fr: "something", // now errors, can't have a variant as top-level key of a variation
+});
+
+// export const frTestData = { hello: "Bonjour." };
+// export const frTestData = { hello: "Bonjour.", goodbye: "Au revoir." }; // goodbye is outstanding (with OG enTestData)
+// export const frTestData = {}; // variations are allowed to be empty, at the very least they should begin by being represented by an empty object, to be completed step-by-step with error handling by turning errorOnMissingVariationKey true
+export const frTestData = Object.freeze({
+  hello: "Bonjour." /* variations: $COMMENT#HELLO / core: $COMMENT#FR#HELLO */,
+  goodbye:
+    "Au revoir." /* variations: $COMMENT#GOODBYE / core: $COMMENT#FR#GOODBYE */,
+  helloAlias:
+    "FR#HELLO" /* variations: $COMMENT#HELLOALIAS / core: $COMMENT#FR#HELLOALIAS */,
+  forComposed1:
+    "Bonjour" /* variations: $COMMENT#FORCOMPOSED1 / core: $COMMENT#FR#FORCOMPOSED1 */,
+  forComposed2:
+    "au revoir." /* variations: $COMMENT#FORCOMPOSED2 / core: $COMMENT#FR#FORCOMPOSED2 */,
+  forComposed3:
+    "au revoir ?" /* variations: $COMMENT#FORCOMPOSED3 / core: $COMMENT#FR#FORCOMPOSED3 */,
+  composed:
+    "$COMMENT#FR#FORCOMPOSED1 $COMMENT#FR#FORCOMPOSED2" /* variations: $COMMENT#COMPOSED / core: $COMMENT#FR#COMPOSED */,
+  composedWithAlias:
+    "$COMMENT#FR#FORCOMPOSED1 $COMMENT#FR#FORCOMPOSED2 $COMMENT#FR#HELLOALIAS" /* variations: $COMMENT#COMPOSEDWITHALIAS / core: $COMMENT#FR#COMPOSEDWITHALIAS */,
+  // fr: "quelque chose", // now errors, can't have a variant as top-level key of a variation
+});

package/jscomments/variations/testing-ground.js

@@ -0,0 +1,16 @@
+/* TEST START
+$COMMENT#HELLO
+$COMMENT#GOODBYE
+$COMMENT#HELLOALIAS // HELLOALIAS
+$COMMENT#COMPOSED
+$COMMENT#COMPOSEDWITHALIAS
+// Now these should resolve on extension, while these below should not, when variations are specified.
+
+$COMMENT#FORCOMPOSED3 // should/does not resolve as exclusive
+$COMMENT#EN#HELLO // should/does not resolve on CLI
+$COMMENT#FR#HELLO // should/does not resolve on extension
+TEST END */
+
+/** $COMMENT#COMPOSEDWITHALIAS */
+const _testFunction = () => {};
+// The TypeScript server plugin also needs to be adapted to variations. Done.

package/library/_commons/utilities/flows.js

@@ -157,13 +157,15 @@ export const compressCommentsFlow = async (
  * @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.
  * @returns
  */
 export const placeholdersCommentsFlow = async (
   configPathIgnores,
   originalFlattenedConfigData,
   aliases_flattenedKeys,
-  relativeMjsPath
+  relativeMjsPath,
+  variations
 ) => {
   /** @type {Record<string, string>} */
   const composedValues_originalKeys = {};
@@ -188,6 +190,7 @@ export const placeholdersCommentsFlow = async (
     aliasValues_originalKeys,
     regularValuesOnly_originalKeys,
     aliases_flattenedKeys,
+    variations,
   };
   const makePlaceholdersAsObject = { makePlaceholders };
 

package/library/index.js

@@ -119,19 +119,37 @@ if (!resolveConfigResults.success) {
 console.log("Config resolved.");
 
 const {
-  config,
-  originalFlattenedConfigData,
-  flattenedConfigData,
-  reversedFlattenedConfigData,
-  aliases_flattenedKeys,
   configPath,
   passedIgnores,
+  config,
+  configDataResultsData,
   rawConfigAndImportPaths,
   lintConfigImports,
   myIgnoresOnly,
   composedVariablesExclusives,
+  resolvedCoreData,
 } = resolveConfigResults;
 
+let {
+  // originalFlattenedConfigData, // currently unused as reassigned
+  flattenedConfigData,
+  reversedFlattenedConfigData,
+  aliases_flattenedKeys,
+} = resolvedCoreData;
+
+// Completely reassigns these four keys from resolvedCoreData to resolvedVariationData for the CLI.
+
+if (resolveConfigResults.variations) {
+  const resolvedVariationData = resolveConfigResults.resolvedVariationData;
+  // Reassignments to the variation data. From then on, using data from resolvedCoreData requires using the resolvedCoreData object itself.
+  // originalFlattenedConfigData =
+  //   resolvedVariationData.originalFlattenedConfigData;
+  flattenedConfigData = resolvedVariationData.flattenedConfigData;
+  reversedFlattenedConfigData =
+    resolvedVariationData.reversedFlattenedConfigData;
+  aliases_flattenedKeys = resolvedVariationData.aliases_flattenedKeys;
+}
+
 skipDetails || console.log("Running with config:", config);
 skipDetails || console.log("Flattened config data is:", flattenedConfigData);
 skipDetails ||
@@ -144,7 +162,6 @@ skipDetails || console.log("Config path is:", configPath);
 skipDetails || console.log("Passed ignores are:", passedIgnores);
 skipDetails || console.log("lintConfigImports is:", lintConfigImports);
 skipDetails || console.log("myIgnoresOnly are:", myIgnoresOnly);
-// NEW
 skipDetails ||
   console.log(
     "Composed variables exclusives are:",
@@ -182,21 +199,24 @@ skipDetails || console.log("Ignores are:", ignores);
 
 // AUTOMATICALLY GENERATES THE JSON OUTPUT OF YOUR RESOLVED CONFIG DATA.
 
-const makeResolvedConfigDataResults =
-  makeResolvedConfigData(resolveConfigResults);
+const makeResolvedConfigDataResults = makeResolvedConfigData(
+  configDataResultsData,
+  resolvedCoreData.flattenedConfigData,
+  resolvedCoreData.aliases_flattenedKeys
+);
 if (!makeResolvedConfigDataResults.success) {
   makeResolvedConfigDataResults.errors.forEach((e) => logError(e));
   exitDueToFailure();
 }
 
-const resolvedConfigData = makeResolvedConfigDataResults.resolvedConfigData;
+const { resolvedConfigData } = makeResolvedConfigDataResults;
 
 const jsonData = makeJsonData(resolvedConfigData);
 fs.writeFileSync(jsonPath, jsonData, "utf8");
 
 console.log(makeJsonPathLog(jsonPath));
 
-// NEW!! comments.config.mjs to directly access resolvedConfigData.
+// comments.config.mjs to directly access resolvedConfigData.
 
 const mjsData = makeMjsData(resolvedConfigData);
 fs.writeFileSync(mjsPath, mjsData, "utf8");
@@ -223,13 +243,15 @@ switch (coreCommand) {
       composedVariablesExclusives
     );
     break;
+  // I'm noticing I'm not even using valueLocations to create placeholders. Which is in fact more reliable because I'm appending the placeholders specifically to the object string values that I find instead of doing so from locations.
   case placeholdersRuleName:
     console.log(`Running ${placeholdersRuleName}...`);
     await placeholdersCommentsFlow(
       configPathIgnores,
-      originalFlattenedConfigData,
-      aliases_flattenedKeys,
-      path.relative(cwd, mjsPath)
+      resolvedCoreData.originalFlattenedConfigData,
+      resolvedCoreData.aliases_flattenedKeys,
+      path.relative(cwd, mjsPath),
+      resolveConfigResults.variations
     );
     break;
   default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "1.2.5",
+  "version": "1.3.1",
   "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
     "comment-variables": "./library/index.js",
@@ -13,7 +13,8 @@
     "comments.config.js",
     "comments.config.json",
     "generate.template.js",
-    "generate.example.js"
+    "generate.example.js",
+    "jscomments"
   ],
   "repository": {
     "type": "git",
@@ -30,7 +31,7 @@
   "type": "module",
   "dependencies": {
     "@eslint/markdown": "^6.5.0",
-    "comment-variables-resolve-config": "^1.14.9",
+    "comment-variables-resolve-config": "^1.16.2",
     "eslint": "^9.29.0"
   },
   "devDependencies": {