comment-variables 1.6.0 → 2.0.0

package/README.md

@@ -218,5 +218,3 @@ export default config;
 And yes, even comments within JavaScript and TypeScript blocks in Markdown files are addressed.
 
 _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).**

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,70 +1,148 @@
 {
-  "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"
+  "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"
+      }
     }
   },
-  "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"
+  "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"
+      }
     },
-    "forComposed3": {
-      "value": "au revoir ?",
-      "key": "FR#FORCOMPOSED3"
+    "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"
+      }
     },
-    "composed": {
-      "value": "Bonjour au revoir.",
-      "key": "FR#COMPOSED"
+    "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"
+      }
     },
-    "composedWithAlias": {
-      "value": "Bonjour au revoir. Bonjour.",
-      "key": "FR#COMPOSEDWITHALIAS"
+    "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"
+      }
     }
   }
 }

package/generate.variations.js

@@ -61,12 +61,12 @@ const composedVariablesExclusives = [
 
 /* variations */
 
-const variations = {
+const variations = Object.freeze({
   // Defines all variants that have matching variations duly defined within the top-level keys of `data`.
-  variants: {
-    [EN]: { label: ENGLISH },
-    [FR]: { label: FRANÇAIS },
-  },
+  variants: Object.freeze({
+    [EN]: Object.freeze({ label: ENGLISH }),
+    [FR]: Object.freeze({ 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]`.
@@ -75,7 +75,7 @@ const variations = {
   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
+}); // can be omitted
 
 const config = {
   data,

package/library/_commons/rules/compress.js

@@ -13,7 +13,7 @@ import {
 const makeRule = (reversedFlattenedConfigData, composedVariablesExclusives) => {
   /** $COMMENT#JSDOC#CONSTANTS#SORTEDREVERSEDFLATTENEDCONFIGDATA */
   const sortedReversedFlattenedConfigData = Object.entries(
-    reversedFlattenedConfigData
+    reversedFlattenedConfigData,
   ).sort(([a], [b]) => b.length - a.length);
 
   /** $COMMENT#JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET */

package/library/_commons/rules/resolve.js

@@ -13,7 +13,7 @@ import {
 const makeRule = (
   flattenedConfigData,
   composedVariablesExclusives,
-  aliases_flattenedKeys
+  aliases_flattenedKeys,
 ) => {
   /** $COMMENT#JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET */
   const composedVariablesExclusivesSet = new Set(composedVariablesExclusives);

package/library/_commons/utilities/flows.js

@@ -35,7 +35,7 @@ const coreCommentsFlow = async (
   flattenedConfigData,
   // NEW
   composedVariablesExclusives,
-  aliases_flattenedKeys
+  aliases_flattenedKeys,
 ) => {
   const eslint = new ESLint({
     fix: true,
@@ -56,7 +56,7 @@ const coreCommentsFlow = async (
                 flattenedConfigData,
                 // NEW
                 composedVariablesExclusives,
-                aliases_flattenedKeys
+                aliases_flattenedKeys,
               ),
             },
           },
@@ -95,8 +95,8 @@ const coreCommentsFlow = async (
     ruleName === resolveRuleName
       ? "Resolved"
       : ruleName === compressRuleName
-      ? "Compressed"
-      : "Unknown rule name'd";
+        ? "Compressed"
+        : "Unknown rule name'd";
 
   const total = results.reduce((sum, r) => {
     const add = r.output ? 1 : 0;
@@ -106,7 +106,7 @@ const coreCommentsFlow = async (
   console.log(
     `✅ ${resolvedOrCompressed} comments on ${total} file${
       total === 1 ? "" : "s"
-    }.`
+    }.`,
   );
 };
 
@@ -124,14 +124,14 @@ export const resolveCommentsFlow = async (
   ignores,
   flattenedConfigData,
   composedVariablesExclusives,
-  aliases_flattenedKeys
+  aliases_flattenedKeys,
 ) =>
   coreCommentsFlow(
     resolveRuleName,
     ignores,
     flattenedConfigData,
     composedVariablesExclusives,
-    aliases_flattenedKeys
+    aliases_flattenedKeys,
   );
 
 /* compressCommentsFlow */
@@ -146,13 +146,13 @@ export const resolveCommentsFlow = async (
 export const compressCommentsFlow = async (
   ignores,
   reversedFlattenedConfigData,
-  composedVariablesExclusives
+  composedVariablesExclusives,
 ) =>
   coreCommentsFlow(
     compressRuleName,
     ignores,
     reversedFlattenedConfigData,
-    composedVariablesExclusives
+    composedVariablesExclusives,
   );
 
 /* placeholdersCommentsFlow */
@@ -171,7 +171,7 @@ export const placeholdersCommentsFlow = async (
   originalFlattenedConfigData,
   aliases_flattenedKeys,
   relativeMjsPath,
-  variations
+  variations,
 ) => {
   /** @type {Record<string, string>} */
   const composedValues_originalKeys = {};
@@ -230,9 +230,8 @@ export const placeholdersCommentsFlow = async (
     ],
   });
 
-  const resultsForMakePlaceholders = await eslintForMakePlaceholders.lintFiles(
-    configPathIgnores
-  );
+  const resultsForMakePlaceholders =
+    await eslintForMakePlaceholders.lintFiles(configPathIgnores);
   await ESLint.outputFixes(resultsForMakePlaceholders);
 
   console.log("Results for placeholders are:", resultsForMakePlaceholders);
@@ -243,6 +242,6 @@ export const placeholdersCommentsFlow = async (
   }, 0);
 
   console.log(
-    `✅ Made placeholders on ${total} file${total === 1 ? "" : "s"}.`
+    `✅ Made placeholders on ${total} file${total === 1 ? "" : "s"}.`,
   );
 };

package/library/index.js

@@ -52,7 +52,7 @@ const skipDetails =
 
 if (!hasPackageJson) {
   console.error(
-    "ERROR. No package.json file found in this directory. Aborting to prevent accidental changes."
+    "ERROR. No package.json file found in this directory. Aborting to prevent accidental changes.",
   );
   exitDueToFailure();
 }
@@ -60,7 +60,7 @@ skipDetails || console.log("package.json file noticed. Allowed to proceed.");
 
 if (!hasGitFolder) {
   console.error(
-    "ERROR. No git folder found in this directory. Aborting to prevent irreversible changes."
+    "ERROR. No git folder found in this directory. Aborting to prevent irreversible changes.",
   );
   exitDueToFailure();
 }
@@ -84,7 +84,7 @@ let rawConfigPath = passedConfigPath ?? path.join(cwd, defaultConfigFileName);
 
 if (!fs.existsSync(rawConfigPath)) {
   console.log(
-    `No Comment Variables config file found at ${rawConfigPath}. Switching to tutorial mode.`
+    `No Comment Variables config file found at ${rawConfigPath}. Switching to tutorial mode.`,
   );
 
   /* TEST START (success) */
@@ -126,7 +126,7 @@ if (!fs.existsSync(rawConfigPath)) {
 
   if (!classicOrAdvancedValue) {
     console.error(
-      "ERROR. No template selected. Please select a template to begin using comment-variables via this CLI."
+      "ERROR. No template selected. Please select a template to begin using comment-variables via this CLI.",
     );
     exitDueToFailure();
   }
@@ -141,7 +141,7 @@ if (!fs.existsSync(rawConfigPath)) {
 
     default:
       console.error(
-        "ERROR. No template selected. Please select a template to begin using comment-variables via this CLI. (Unreachable code.)" // copypasted same as classicOrAdvanced for now, since this is supposed to be unreachable code.
+        "ERROR. No template selected. Please select a template to begin using comment-variables via this CLI. (Unreachable code.)", // copypasted same as classicOrAdvanced for now, since this is supposed to be unreachable code.
       );
       exitDueToFailure();
   }
@@ -225,7 +225,7 @@ skipDetails || console.log("Flattened config data is:", flattenedConfigData);
 skipDetails ||
   console.log(
     "Reversed flattened config data is:",
-    reversedFlattenedConfigData
+    reversedFlattenedConfigData,
   );
 skipDetails || console.log("Aliases are:", aliases_flattenedKeys);
 skipDetails || console.log("Config path is:", configPath);
@@ -235,7 +235,7 @@ skipDetails || console.log("myIgnoresOnly are:", myIgnoresOnly);
 skipDetails ||
   console.log(
     "Composed variables exclusives are:",
-    composedVariablesExclusives
+    composedVariablesExclusives,
   );
 
 // ADDRESSES THE --lint-config-imports FLAG (lintConfigImports, no longer a flag), GIVEN THAT THE FILES IMPORTED BY THE CONFIG ARE IGNORED BY DEFAULT.
@@ -251,13 +251,13 @@ const rawConfigPathIgnores = lintConfigImports
 
 // the ignore paths must be relative
 const configPathIgnores = rawConfigPathIgnores.map((e) =>
-  path.relative(cwd, e)
+  path.relative(cwd, e),
 );
 
 skipDetails ||
   console.log(
     lintConfigImports ? "Config path ignore is:" : "Config path ignores are:",
-    configPathIgnores
+    configPathIgnores,
   );
 
 // ADDRESSES THE --my-ignores-only FLAG (myIgnoresOnly, no longer a flag, GIVEN THAT KNOWN IGNORES ARE IGNORED BY DEFAULT.
@@ -272,7 +272,7 @@ skipDetails || console.log("Ignores are:", ignores);
 const makeResolvedConfigDataResults = makeResolvedConfigData(
   configDataResultsData,
   resolvedCoreData.flattenedConfigData,
-  resolvedCoreData.aliases_flattenedKeys
+  resolvedCoreData.aliases_flattenedKeys,
 );
 if (!makeResolvedConfigDataResults.success) {
   makeResolvedConfigDataResults.errors.forEach((e) => logError(e));
@@ -302,7 +302,7 @@ switch (coreCommand) {
       ignores,
       flattenedConfigData,
       composedVariablesExclusives,
-      aliases_flattenedKeys
+      aliases_flattenedKeys,
     );
     break;
   case compressRuleName:
@@ -310,7 +310,7 @@ switch (coreCommand) {
     await compressCommentsFlow(
       ignores,
       reversedFlattenedConfigData,
-      composedVariablesExclusives
+      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.
@@ -321,19 +321,19 @@ switch (coreCommand) {
       resolvedCoreData.originalFlattenedConfigData,
       resolvedCoreData.aliases_flattenedKeys,
       path.relative(cwd, mjsPath),
-      resolveConfigResults.variations
+      resolveConfigResults.variations,
     );
     break;
   default:
     if (coreCommand && !coreCommand.startsWith("--"))
       console.error(
-        `ERROR. Core command not recognized. Choose between "${resolveRuleName}" and "${compressRuleName}" or "${placeholdersRuleName}".`
+        `ERROR. Core command not recognized. Choose between "${resolveRuleName}" and "${compressRuleName}" or "${placeholdersRuleName}".`,
       );
     else
       console.log(
         `If these settings are correct with you, feel free to initiate the command "${resolveRuleName}" to resolve comments, or "${compressRuleName}" to compress them back to their $COMMENT forms. You can also generate the placeholders at their definitions locations with the command "${placeholdersRuleName}".${
           passedConfigPath ? " (And DON'T FORGET YOUR --config FLAG!)" : ""
-        }`
+        }`,
       );
     break;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "1.6.0",
+  "version": "2.0.0",
   "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
     "comment-variables": "./library/index.js",
@@ -32,7 +32,7 @@
   "type": "module",
   "dependencies": {
     "@eslint/markdown": "^6.5.0",
-    "comment-variables-resolve-config": "^1.18.0",
+    "comment-variables-resolve-config": "^2.0.0",
     "eslint": "^9.29.0",
     "prompts": "^2.4.2"
   },