comment-variables 0.12.2 → 0.12.4

package/comments.config.js

@@ -1,12 +1,14 @@
+// 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 */, // valid
+      // 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:
@@ -44,6 +46,7 @@ const data = {
       // 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
+      // noConcat: "no" + "concat", // errors, unrecognized value
     },
   },
   // for deving

package/comments.config.json

@@ -6,11 +6,6 @@
         "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",

package/library/_commons/rules/compress.js

@@ -5,9 +5,9 @@ import {
 } from "comment-variables-resolve-config";
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS
- * @param {{[key: string]: string}} reversedFlattenedConfigData $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
- * @returns $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS
+ * 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.
  */
 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";
 
 /**
- * $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
+ * 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.
  */
 const makeRule = (flattenedConfigData, aliases_flattenedKeys) => {
   /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */

package/library/_commons/utilities/flows.js

@@ -21,11 +21,11 @@ import { ruleNames_makeRules } from "../constants/rules.js";
 /* coreCommentsFlow */
 
 /**
- * $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
+ * 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.
  * @returns
  */
 const coreCommentsFlow = async (
@@ -104,10 +104,10 @@ const coreCommentsFlow = async (
 /* resolveCommentsFlow */
 
 /**
- * $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
+ * 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.
  * @returns
  */
 export const resolveCommentsFlow = async (
@@ -125,9 +125,9 @@ export const resolveCommentsFlow = async (
 /* compressCommentsFlow */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW
- * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
- * @param {{[key: string]: string}} reversedFlattenedConfigData $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
+ * 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.
  * @returns
  */
 export const compressCommentsFlow = async (
@@ -138,10 +138,10 @@ export const compressCommentsFlow = async (
 /* placeholdersCommentsFlow */
 
 /**
- * $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
+ * 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.
  * @returns
  */
 export const placeholdersCommentsFlow = async (

package/library/_commons/utilities/helpers.js

@@ -1,16 +1,16 @@
 /* exitDueToFailure */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE
- * @returns {never} $COMMENT#JSDOC#RETURNS#EXITDUETOFAILURE
+ * Terminates the whole process with a 'failure' code (`1`).
+ * @returns {never} Never. (Somehow typing needs to be explicit for unreachable code inference.)
  */
 export const exitDueToFailure = () => process.exit(1);
 
 /* logError */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#LOGERROR
- * @param {{type: "error" | "warning"; message: string}} error $COMMENT#JSDOC#PARAMS#ERROR
+ * 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.
  * @returns
  */
 export const logError = (error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "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.10.1",
+    "comment-variables-resolve-config": "^1.11.0",
     "eslint": "^9.29.0"
   },
   "devDependencies": {