comment-variables 0.11.8 → 0.12.1

package/README.md

@@ -6,13 +6,13 @@ npm install -g comment-variables
 
 ## Commands
 
-**`comment-variables` comes with three commands in this initial release:**
+**`comment-variables` (alias `jscomments`) comes with three commands in this initial release:**
 
 ```
 comment-variables
 ```
 
-Interacts with your `comments.config.js` default exported object to print all the parameters you need to be aware of before running `compress` or `resolve`. Also acts as a dry run validation check. If no error is printed, it means you can run `compress` or `resolve` safely, as long the printed parameters correspond to what you've expected from your defined config.
+Interacts with your `comments.config.js` default exported object to print all the parameters you need to be aware of before running `compress` or `resolve`. Also acts as a dry run validation check. If no error is printed, it means you can run `compress` or `resolve` safely, as long the printed parameters correspond to what you've expected from your defined config. (Additionally creates a resolved version of your config data as a JSON file.)
 
 ```
 comment-variables compress
@@ -75,7 +75,7 @@ const data = {
   jsDoc: Object.freeze({
     definitions: Object.freeze({
       exitDueToFailure:
-        "Terminates the whole process with a 'failure' code (1)." /* $COMMENT#JSDOC#DEFINITIONS#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:

package/comments.config.js

@@ -2,7 +2,7 @@ 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.
+      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\
@@ -12,12 +12,20 @@ const data = {
       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.
+        "$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:
@@ -28,7 +36,7 @@ const data = {
       // 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
+      // ".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
@@ -39,7 +47,7 @@ const data = {
   jsDoc: Object.freeze({
     definitions: Object.freeze({
       exitDueToFailure:
-        "Terminates the whole process with a 'failure' code (1)." /* $COMMENT#JSDOC#DEFINITIONS#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:

package/comments.config.json

@@ -0,0 +1,42 @@
+{
+  "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."
+    }
+  },
+  "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\"`.)"
+    },
+    "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."
+    },
+    "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."
+    }
+  }
+}

package/library/_commons/rules/compress.js

@@ -5,12 +5,12 @@ 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) => {
-  // Turns the whole reversedFlattenedConfig from an object to an array of key-value arrays sorted by the descending length of each key to prevent partial replacements.
+  /** 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. */
   const sortedReversedFlattenedConfigData = Object.entries(
     reversedFlattenedConfigData
   ).sort(([a], [b]) => b.length - a.length);

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 (
@@ -158,12 +158,12 @@ export const placeholdersCommentsFlow = async (
 
   for (const [key, value] of Object.entries(originalFlattenedConfigData)) {
     if (value.includes(`${$COMMENT}#`))
-      // composed Comment Variables
+      // composed variables
       composedValues_originalKeys[value] = key;
     else if (originalFlattenedConfigData[value])
-      // alias Comment Variables
+      // alias variables
       aliasValues_originalKeys[value] = aliases_flattenedKeys[key];
-    // regular Comment Variables
+    // comment variables
     else regularValuesOnly_originalKeys[value] = key;
   } // no need for continues, potential collisions are caught in resolveConfig run prior
 

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/library/index.js

@@ -2,6 +2,7 @@
 // The shebang (#!) is necessary to communicate with Unix-based systems, like Linux and macOS. On Windows, it is ignored, but npm tooling bridges the gap by generating wrappers that make the CLI work anyway.
 
 import path from "path";
+import fs from "fs";
 
 import resolveConfig, {
   defaultConfigFileName,
@@ -9,6 +10,7 @@ import resolveConfig, {
   lintConfigImportsFlag,
   myIgnoresOnlyFlag,
   knownIgnores,
+  makeResolvedConfigData,
 } from "comment-variables-resolve-config";
 
 import {
@@ -124,7 +126,23 @@ const ignores = myIgnoresOnly ? rawIgnores : [...rawIgnores, ...knownIgnores];
 
 skipDetails || console.log("Ignores are:", ignores);
 
-// ADDRESSES THE CORE COMMANDS "resolve" AND "compress".
+// NEW: AUTOMATICALLY GENERATE THE JSON OUTPUT OF YOUR RESOLVED CONFIG DATA.
+
+const makeResolvedConfigDataResults =
+  makeResolvedConfigData(resolveConfigResults);
+if (!makeResolvedConfigDataResults.success) {
+  makeResolvedConfigDataResults.errors.forEach((e) => logError(e));
+  exitDueToFailure();
+}
+
+const resolvedConfigData = makeResolvedConfigDataResults.resolvedConfigData;
+const jsonPath = resolveConfigResults.configPath.replace(/\.js$/, ".json");
+const jsonData = JSON.stringify(resolvedConfigData, null, 2);
+fs.writeFileSync(jsonPath, jsonData, "utf8");
+
+console.log(`JSON resolved config data written to: \n${jsonPath}`);
+
+// ADDRESSES THE CORE COMMANDS "resolve", "compress", AND "placeholders".
 
 switch (coreCommand) {
   case resolveRuleName:
@@ -150,11 +168,11 @@ switch (coreCommand) {
   default:
     if (coreCommand && !coreCommand.startsWith("--"))
       console.error(
-        `ERROR. Core command not recognized. Choose between "resolve" and "compress" or "placeholders".`
+        `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 "resolve" to resolve comments, or "compress" to compress them back to their $COMMENT forms. You can also generate the placeholders with the command "placeholders".${
+        `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 || lintConfigImports || myIgnoresOnly
             ? " (And DON'T FORGET YOUR FLAGS!)"
             : ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "0.11.8",
+  "version": "0.12.1",
   "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
     "jscomments": "./library/index.js",
@@ -9,7 +9,8 @@
   "main": "library/index.js",
   "files": [
     "library",
-    "comments.config.js"
+    "comments.config.js",
+    "comments.config.json"
   ],
   "repository": {
     "type": "git",
@@ -26,7 +27,7 @@
   "type": "module",
   "dependencies": {
     "@eslint/markdown": "^6.5.0",
-    "comment-variables-resolve-config": "^1.8.0",
+    "comment-variables-resolve-config": "^1.9.4",
     "eslint": "^9.29.0"
   },
   "devDependencies": {