comment-variables 0.10.1 → 0.11.1

package/comments.config.js

@@ -2,14 +2,26 @@ const data = {
   // for testing
   levelOne: {
     levelTwo: {
-      levelThree: "Level three.", // $COMMENT#LEVELONE#LEVELTWO#LEVELTHREE
-      stillLevelThree: "LEVELONE#LEVELTWO#LEVELTHREE", // now is an alias // $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE
-      otherLevelThree: "LEVELONE#LEVELTWO#LEVELTHREE", // also an alias // $COMMENT#LEVELONE#LEVELTWO#OTHERLEVELTHREE
+      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
+      stillLevelThree:
+        "LEVELONE#LEVELTWO#LEVELTHREE" /* $COMMENT#LEVELONE#LEVELTWO#LEVELTHREE */, // now is an alias
+      otherLevelThree:
+        "LEVELONE#LEVELTWO#LEVELTHREE" /* $COMMENT#LEVELONE#LEVELTWO#LEVELTHREE */, // 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. (Personal note: And that part is free and included in the CLI tool.)
+        "$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. (Personal note: And that part is free and included in the CLI tool.)
       // wrongComposedVariable:
       //   "$COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE", // errors, can't make composed variables with composed variables
+      composedVariableAlias:
+        "LEVELONE#LEVELTWO#COMPOSEDVARIABLE" /* $COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLEALIAS */,
+      // 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
@@ -18,47 +30,54 @@ const data = {
       // 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
     },
   },
   // for deving
   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
+        "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
+        "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
+        "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
+        "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
+        "The flow that compresses actual comments into `$COMMENT` placeholders." /* $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW */,
       logError:
-        'Logs an error to the console depending on its type. (`"error"` or `"warning"`.)', // $COMMENT#JSDOC#DEFINITIONS#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
+        "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
+        "The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values." /* $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA */,
+      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
+        '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
+        "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
+        "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 */,
     }),
     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
+        "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
+        "The compress rule based on the reversed flattened config data." /* $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS */,
     }),
   }),
 };

package/library/_commons/constants/bases.js

@@ -4,6 +4,7 @@ import path from "path";
 // rule names
 export const resolveRuleName = "resolve";
 export const compressRuleName = "compress";
+export const placeholdersRuleName = "placeholders"; // rule?
 
 // current working directory
 export const cwd = process.cwd();

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) => {
   // 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.

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
- * @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, []>} */

package/library/_commons/utilities/flows.js

@@ -2,8 +2,11 @@ import { ESLint } from "eslint";
 import markdown from "@eslint/markdown";
 
 import {
+  $COMMENT,
   commentVariablesPluginName,
+  extractRuleName,
   typeScriptAndJSXCompatible,
+  extractObjectStringLiteralValues,
 } from "comment-variables-resolve-config";
 
 import {
@@ -18,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 {{[key: string]: string} | undefined} aliases_flattenedKeys
+ * $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
  */
 const coreCommentsFlow = async (
   ruleName,
@@ -76,7 +79,7 @@ const coreCommentsFlow = async (
   ]);
   await ESLint.outputFixes(results);
 
-  console.log("Results are:", results);
+  console.log(`Results for ${ruleName} are:`, results);
 
   const resolvedOrCompressed =
     ruleName === resolveRuleName
@@ -100,10 +103,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 {{[key: string]: string}} flattenedConfigData The flattened config data, with $COMMENT placeholders as keys and actual comments as values.
- * @param {{[key: string]: string}} aliases_flattenedKeys
+ * $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
  * @returns
  */
 export const resolveCommentsFlow = async (
@@ -121,12 +124,97 @@ 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 (
   ignores,
   reversedFlattenedConfigData
 ) => coreCommentsFlow(compressRuleName, ignores, reversedFlattenedConfigData);
+
+/* placeholdersCommentsFlow */
+
+/**
+ *
+ * @param {string[]} configPathIgnores
+ * @param {{[k: string]: string;}} originalFlattenedConfigData
+ * @param {Record<string, string>} aliases_flattenedKeys
+ */
+export const placeholdersCommentsFlow = async (
+  configPathIgnores,
+  originalFlattenedConfigData,
+  aliases_flattenedKeys
+) => {
+  /* TEST START
+  only for the jscomments/comment-variables placeholders command
+  meaning this should actually be only in the JSComments CLI, */
+
+  /** @type {Record<string, string>} */
+  const composedValues_originalKeys = {};
+  /** @type {Record<string, string>} */
+  const aliasValues_originalKeys = {};
+  /** @type {Record<string, string>} */
+  const regularValuesOnly_originalKeys = {};
+
+  for (const [key, value] of Object.entries(originalFlattenedConfigData)) {
+    if (value.includes(`${$COMMENT}#`))
+      // composed Comment Variables
+      composedValues_originalKeys[value] = key;
+    else if (originalFlattenedConfigData[value])
+      // alias Comment Variables
+      aliasValues_originalKeys[value] = aliases_flattenedKeys[key];
+    // regular Comment Variables
+    else regularValuesOnly_originalKeys[value] = key;
+  } // no need for continues, potential collisions are caught in resolveConfig run prior
+
+  const makePlaceholders = {
+    composedValues_originalKeys,
+    aliasValues_originalKeys,
+    regularValuesOnly_originalKeys,
+  };
+  const makePlaceholdersAsObject = { makePlaceholders };
+
+  const eslintForMakePlaceholders = new ESLint({
+    fix: true,
+    errorOnUnmatchedPattern: false,
+    overrideConfigFile: true,
+    overrideConfig: [
+      {
+        files: configPathIgnores,
+        languageOptions: typeScriptAndJSXCompatible,
+        plugins: {
+          [commentVariablesPluginName]: {
+            rules: {
+              [extractRuleName]: extractObjectStringLiteralValues,
+            },
+          },
+        },
+        rules: {
+          [`${commentVariablesPluginName}/${extractRuleName}`]: [
+            "warn",
+            makePlaceholdersAsObject,
+          ],
+        },
+      },
+    ],
+  });
+
+  const resultsForMakePlaceholders = await eslintForMakePlaceholders.lintFiles(
+    configPathIgnores
+  );
+  await ESLint.outputFixes(resultsForMakePlaceholders);
+
+  console.log("Results for placeholders are:", resultsForMakePlaceholders);
+
+  const total = resultsForMakePlaceholders.reduce((sum, r) => {
+    const add = r.output ? 1 : 0;
+    return sum + add;
+  }, 0);
+
+  console.log(
+    `✅ Made placeholders on ${total} file${total === 1 ? "" : "s"}.`
+  );
+  /* TEST END */
+};

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
  */
 export const logError = (error) => {
   switch (error.type) {

package/library/index.js

@@ -17,12 +17,14 @@ import {
   hasGitFolder,
   resolveRuleName,
   compressRuleName,
+  placeholdersRuleName,
 } from "./_commons/constants/bases.js";
 
 import { exitDueToFailure, logError } from "./_commons/utilities/helpers.js";
 import {
   resolveCommentsFlow,
   compressCommentsFlow,
+  placeholdersCommentsFlow,
 } from "./_commons/utilities/flows.js";
 
 // ENSURES THE CLI TOOL ONLY RUNS IN FOLDERS THAT POSSESS A package.json FILE AND A .git FOLDER.
@@ -46,7 +48,9 @@ const commands = process.argv;
 const coreCommand = commands[2];
 
 const skipDetails =
-  coreCommand === resolveRuleName || coreCommand === compressRuleName;
+  coreCommand === resolveRuleName ||
+  coreCommand === compressRuleName ||
+  coreCommand === placeholdersRuleName;
 
 // OBTAINS THE VALIDATED FLATTENED CONFIG, REVERSE FLATTENED CONFIG, CONFIG PATH, AND PASSED IGNORES.
 
@@ -74,6 +78,7 @@ console.log("Config resolved.");
 
 const {
   config,
+  originalFlattenedConfigData,
   flattenedConfigData,
   reversedFlattenedConfigData,
   aliases_flattenedKeys,
@@ -134,14 +139,22 @@ switch (coreCommand) {
     console.log(`Running ${compressRuleName}...`);
     await compressCommentsFlow(ignores, reversedFlattenedConfigData);
     break;
+  case placeholdersRuleName:
+    console.log(`Running ${placeholdersRuleName}...`);
+    await placeholdersCommentsFlow(
+      configPathIgnores,
+      originalFlattenedConfigData,
+      aliases_flattenedKeys
+    );
+    break;
   default:
     if (coreCommand && !coreCommand.startsWith("--"))
       console.error(
-        `ERROR. Core command not recognized. Choose between "resolve" and "compress".`
+        `ERROR. Core command not recognized. Choose between "resolve" and "compress" or "placeholders".`
       );
     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.${
+        `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".${
           passedConfigPath || lintConfigImports || myIgnoresOnly
             ? " (And DON'T FORGET YOUR FLAGS!)"
             : ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
     "jscomments": "./library/index.js",
@@ -26,7 +26,7 @@
   "type": "module",
   "dependencies": {
     "@eslint/markdown": "^6.5.0",
-    "comment-variables-resolve-config": "^1.6.1",
+    "comment-variables-resolve-config": "^1.7.0",
     "eslint": "^9.29.0",
     "zod": "^3.25.67"
   },