comment-variables 0.12.1 → 0.12.2

package/comments.config.js

@@ -41,6 +41,9 @@ const data = {
       // 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 not allowed", // errors, "key", "value" and "placeholder" not allowed
     },
   },
   // for deving

package/comments.config.json

@@ -1,42 +1,154 @@
 {
   "levelOne": {
     "levelTwo": {
-      "levelThree": "Level three.",
-      "levelThreeEscape": "Level three.       fdff",
-      "stillLevelThree": "Level three.",
-      "otherLevelThree": "Level three.",
-      "composedVariable": "Level three. Level three.",
-      "composedVariableAlias": "Level three. Level three."
+      "levelThree": {
+        "value": "Level three.",
+        "key": "LEVELONE#LEVELTWO#LEVELTHREE",
+        "placeholder": "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE"
+      },
+      "levelThreeEscape": {
+        "value": "Level three.       fdff",
+        "key": "LEVELONE#LEVELTWO#LEVELTHREEESCAPE",
+        "placeholder": "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREEESCAPE"
+      },
+      "stillLevelThree": {
+        "value": "Level three.",
+        "key": "LEVELONE#LEVELTWO#STILLLEVELTHREE",
+        "placeholder": "$COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE"
+      },
+      "otherLevelThree": {
+        "value": "Level three.",
+        "key": "LEVELONE#LEVELTWO#OTHERLEVELTHREE",
+        "placeholder": "$COMMENT#LEVELONE#LEVELTWO#OTHERLEVELTHREE"
+      },
+      "composedVariable": {
+        "value": "Level three. Level three.",
+        "key": "LEVELONE#LEVELTWO#COMPOSEDVARIABLE",
+        "placeholder": "$COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE"
+      },
+      "composedVariableAlias": {
+        "value": "Level three. Level three.",
+        "key": "LEVELONE#LEVELTWO#COMPOSEDVARIABLEALIAS",
+        "placeholder": "$COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLEALIAS"
+      }
     }
   },
   "jsDoc": {
     "definitions": {
-      "exitDueToFailure": "Terminates the whole process with a 'failure' code (`1`).",
-      "makeRuleResolve": "The utility that creates the resolve rule based on the flattened config data, used to transform `$COMMENT` placeholders into actual comments.",
-      "makeRuleCompress": "The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into `$COMMENT` placeholders.",
-      "coreCommentsFlow": "The core flow at the heart of resolving and compressing comments.",
-      "resolveCommentsFlow": "The flow that resolves `$COMMENT` placeholders into actual comments.",
-      "compressCommentsFlow": "The flow that compresses actual comments into `$COMMENT` placeholders.",
-      "placeholdersCommentsFlow": "The flow that creates `$COMMENT` placeholders right next to where they're defined.",
-      "logError": "Logs an error to the console depending on its type. (`\"error\"` or `\"warning\"`.)"
+      "exitDueToFailure": {
+        "value": "Terminates the whole process with a 'failure' code (`1`).",
+        "key": "JSDOC#DEFINITIONS#EXITDUETOFAILURE",
+        "placeholder": "$COMMENT#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",
+        "placeholder": "$COMMENT#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",
+        "placeholder": "$COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS"
+      },
+      "coreCommentsFlow": {
+        "value": "The core flow at the heart of resolving and compressing comments.",
+        "key": "JSDOC#DEFINITIONS#CORECOMMENTSFLOW",
+        "placeholder": "$COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW"
+      },
+      "resolveCommentsFlow": {
+        "value": "The flow that resolves `$COMMENT` placeholders into actual comments.",
+        "key": "JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW",
+        "placeholder": "$COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW"
+      },
+      "compressCommentsFlow": {
+        "value": "The flow that compresses actual comments into `$COMMENT` placeholders.",
+        "key": "JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW",
+        "placeholder": "$COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW"
+      },
+      "placeholdersCommentsFlow": {
+        "value": "The flow that creates `$COMMENT` placeholders right next to where they're defined.",
+        "key": "JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW",
+        "placeholder": "$COMMENT#JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW"
+      },
+      "logError": {
+        "value": "Logs an error to the console depending on its type. (`\"error\"` or `\"warning\"`.)",
+        "key": "JSDOC#DEFINITIONS#LOGERROR",
+        "placeholder": "$COMMENT#JSDOC#DEFINITIONS#LOGERROR"
+      }
     },
     "params": {
-      "flattenedConfigData": "The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values.",
-      "reversedFlattenedConfigData": "The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values.",
-      "aliases_flattenedKeys": "The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.",
-      "ruleName": "The name of the rule currently used. (Either `\"resolve\"` or `\"compress\"`.)",
-      "ignores": "The array of paths and globs for the flow's ESLint instance to ignore.",
-      "eitherFlattenedConfigData": "Either the flattened config data or the reversed flattened config data, since they share the same structure.",
-      "error": "The error object being handle for the logging.",
-      "options": "The additional options as follows:",
-      "settings": "The required settings as follows:",
-      "configPathIgnores": "The array of paths linked to the config file, (named \"ignores\" given it is ignored by the \"compress\" and \"resolve\" commands).",
-      "originalFlattenedConfigData": "The original flattened config data, before changes to Aliases Variables and Composed Variables are applied."
+      "flattenedConfigData": {
+        "value": "The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values.",
+        "key": "JSDOC#PARAMS#FLATTENEDCONFIGDATA",
+        "placeholder": "$COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA"
+      },
+      "reversedFlattenedConfigData": {
+        "value": "The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values.",
+        "key": "JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA",
+        "placeholder": "$COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA"
+      },
+      "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",
+        "placeholder": "$COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS"
+      },
+      "ruleName": {
+        "value": "The name of the rule currently used. (Either `\"resolve\"` or `\"compress\"`.)",
+        "key": "JSDOC#PARAMS#RULENAME",
+        "placeholder": "$COMMENT#JSDOC#PARAMS#RULENAME"
+      },
+      "ignores": {
+        "value": "The array of paths and globs for the flow's ESLint instance to ignore.",
+        "key": "JSDOC#PARAMS#IGNORES",
+        "placeholder": "$COMMENT#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",
+        "placeholder": "$COMMENT#JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA"
+      },
+      "error": {
+        "value": "The error object being handle for the logging.",
+        "key": "JSDOC#PARAMS#ERROR",
+        "placeholder": "$COMMENT#JSDOC#PARAMS#ERROR"
+      },
+      "options": {
+        "value": "The additional options as follows:",
+        "key": "JSDOC#PARAMS#OPTIONS",
+        "placeholder": "$COMMENT#JSDOC#PARAMS#OPTIONS"
+      },
+      "settings": {
+        "value": "The required settings as follows:",
+        "key": "JSDOC#PARAMS#SETTINGS",
+        "placeholder": "$COMMENT#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",
+        "placeholder": "$COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES"
+      },
+      "originalFlattenedConfigData": {
+        "value": "The original flattened config data, before changes to Aliases Variables and Composed Variables are applied.",
+        "key": "JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA",
+        "placeholder": "$COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA"
+      }
     },
     "returns": {
-      "exitDueToFailure": "Never. (Somehow typing needs to be explicit for unreachable code inference.)",
-      "makeRuleResolve": "The resolve rule based on the flattened config data.",
-      "makeRuleCompress": "The compress rule based on the reversed flattened config data."
+      "exitDueToFailure": {
+        "value": "Never. (Somehow typing needs to be explicit for unreachable code inference.)",
+        "key": "JSDOC#RETURNS#EXITDUETOFAILURE",
+        "placeholder": "$COMMENT#JSDOC#RETURNS#EXITDUETOFAILURE"
+      },
+      "makeRuleResolve": {
+        "value": "The resolve rule based on the flattened config data.",
+        "key": "JSDOC#RETURNS#MAKERULERESOLVE",
+        "placeholder": "$COMMENT#JSDOC#RETURNS#MAKERULERESOLVE"
+      },
+      "makeRuleCompress": {
+        "value": "The compress rule based on the reversed flattened config data.",
+        "key": "JSDOC#RETURNS#MAKERULECOMPRESS",
+        "placeholder": "$COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS"
+      }
     }
   }
 }

package/library/_commons/rules/compress.js

@@ -5,9 +5,9 @@ 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.
- * @returns The compress rule based on the reversed flattened config data.
+ * $COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS
+ * @param {{[key: string]: string}} reversedFlattenedConfigData $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
+ * @returns $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS
  */
 const makeRule = (reversedFlattenedConfigData) => {
   /** 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. */

package/library/_commons/rules/resolve.js

@@ -4,10 +4,10 @@ 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 {{[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 {{[key: string]: string}} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
+ * @returns $COMMENT#JSDOC#RETURNS#MAKERULERESOLVE
  */
 const makeRule = (flattenedConfigData, aliases_flattenedKeys) => {
   /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */
@@ -47,9 +47,8 @@ const makeRule = (flattenedConfigData, aliases_flattenedKeys) => {
           const replacement =
             flattenedConfigData[key] || // original
             flattenedConfigData[aliases_flattenedKeys?.[key]]; // alias
-
           if (replacement) {
-            fixedText = fixedText.replace(fullMatch, replacement);
+            fixedText = fixedText.replace(fullMatch, () => replacement);
             hasValidFix = true;
           }
         }

package/library/_commons/utilities/flows.js

@@ -21,11 +21,11 @@ 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 {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 {Record<string, string> | undefined} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
  * @returns
  */
 const coreCommentsFlow = async (
@@ -104,10 +104,10 @@ 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 {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 {Record<string, string>} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
  * @returns
  */
 export const resolveCommentsFlow = async (
@@ -125,9 +125,9 @@ 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.
+ * $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW
+ * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
+ * @param {{[key: string]: string}} reversedFlattenedConfigData $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
  * @returns
  */
 export const compressCommentsFlow = async (
@@ -138,10 +138,10 @@ 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.
+ * $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
  * @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

@@ -136,7 +136,10 @@ if (!makeResolvedConfigDataResults.success) {
 }
 
 const resolvedConfigData = makeResolvedConfigDataResults.resolvedConfigData;
-const jsonPath = resolveConfigResults.configPath.replace(/\.js$/, ".json");
+const jsonPath = resolveConfigResults.configPath.replace(
+  /\.js$/,
+  () => ".json"
+);
 const jsonData = JSON.stringify(resolvedConfigData, null, 2);
 fs.writeFileSync(jsonPath, jsonData, "utf8");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
     "jscomments": "./library/index.js",
@@ -27,7 +27,7 @@
   "type": "module",
   "dependencies": {
     "@eslint/markdown": "^6.5.0",
-    "comment-variables-resolve-config": "^1.9.4",
+    "comment-variables-resolve-config": "^1.10.1",
     "eslint": "^9.29.0"
   },
   "devDependencies": {