comment-variables 1.0.0 → 1.1.0

package/comments.config.js

@@ -74,6 +74,8 @@ const data = {
         "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 */,
+      composedVariablesExclusives:
+        "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." /* $COMMENT#JSDOC#PARAMS#COMPOSEDVARIABLESEXCLUSIVES */,
       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:
@@ -110,16 +112,18 @@ const data = {
 
 const ignores = ["README.md", "generate.template.js", "generate.example.js"];
 
-// FORMER CLI FLAGS NOW TO BE INCLUDED INSIDE THE CONFIG ITSELF
-
 const lintConfigImports = false; // can be omitted
 const myIgnoresOnly = false; // can be omitted
 
+// NEW
+const composedVariablesExclusives = []; // can be omitted
+
 const config = {
   data,
   ignores,
   lintConfigImports,
   myIgnoresOnly,
+  composedVariablesExclusives,
 };
 
 export default config;

package/comments.config.json

@@ -82,6 +82,11 @@
         "key": "JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA",
         "placeholder": "$COMMENT#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",
+        "placeholder": "$COMMENT#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",

package/generate.template.js

@@ -20,11 +20,15 @@ const ignores = [];
 const lintConfigImports = false; // can be omitted
 const myIgnoresOnly = false; // can be omitted
 
+// NEW
+const composedVariablesExclusives = []; // can be omitted
+
 const config = {
   data,
   ignores,
   lintConfigImports,
   myIgnoresOnly,
+  composedVariablesExclusives,
 };
 
 export default config;

package/library/_commons/constants/bases.js

@@ -3,10 +3,10 @@ import path from "path";
 
 import { cwd } from "comment-variables-resolve-config";
 
-// rule names
-export const resolveRuleName = "resolve";
-export const compressRuleName = "compress";
-export const placeholdersRuleName = "placeholders"; // rule?
+// rule names (now inside "comment-variables-resolve-config")
+// export const resolveRuleName = "resolve";
+// export const compressRuleName = "compress";
+// export const placeholdersRuleName = "placeholders"; // rule?
 
 // to prevent accidental changes
 export const hasPackageJson = fs.existsSync(path.join(cwd, "package.json"));

package/library/_commons/constants/rules.js

@@ -1,4 +1,7 @@
-import { resolveRuleName, compressRuleName } from "../constants/bases.js";
+import {
+  resolveRuleName,
+  compressRuleName,
+} from "comment-variables-resolve-config";
 
 import makeResolveRule from "../rules/resolve.js";
 import makeCompressRule from "../rules/compress.js";

package/library/_commons/rules/compress.js

@@ -7,14 +7,18 @@ import {
 /**
  * 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.
+ * @param {string[]} composedVariablesExclusives 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.
  * @returns The compress rule based on the reversed flattened config data.
  */
-const makeRule = (reversedFlattenedConfigData) => {
+const makeRule = (reversedFlattenedConfigData, composedVariablesExclusives) => {
   /** 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);
 
+  // makes a set out of composed variables exclusives
+  const composedVariablesExclusivesSet = new Set(composedVariablesExclusives);
+
   /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */
   const rule = {
     meta: {
@@ -44,6 +48,10 @@ const makeRule = (reversedFlattenedConfigData) => {
           resolvedValue,
           commentKey,
         ] of sortedReversedFlattenedConfigData) {
+          // NEW
+          // if (composedVariablesExclusives.some((e) => commentKey === e))
+          if (composedVariablesExclusivesSet.has(commentKey)) continue;
+
           const pattern = makeIsolatedStringRegex(resolvedValue);
 
           fixedText = fixedText.replace(pattern, () => {

package/library/_commons/rules/resolve.js

@@ -6,10 +6,18 @@ import {
 /**
  * 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 {string[]} composedVariablesExclusives 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.
  * @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) => {
+const makeRule = (
+  flattenedConfigData,
+  composedVariablesExclusives,
+  aliases_flattenedKeys
+) => {
+  // makes a set out of composed variables exclusives
+  const composedVariablesExclusivesSet = new Set(composedVariablesExclusives);
+
   /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */
   const rule = {
     meta: {
@@ -43,10 +51,20 @@ const makeRule = (flattenedConfigData, aliases_flattenedKeys) => {
 
         for (const match of matches) {
           const fullMatch = match[0]; // e.g. $COMMENT#LEVELONE#LEVELTWO
-          const key = match[1]; // e.g. LEVELONE#LEVELTWO
-          const replacement =
-            flattenedConfigData[key] || // original
-            flattenedConfigData[aliases_flattenedKeys?.[key]]; // alias
+          const rawKey = match[1]; // e.g. LEVELONE#LEVELTWO
+          const key =
+            aliases_flattenedKeys?.[rawKey] || // alias
+            rawKey; // original
+          const replacement = flattenedConfigData[key];
+
+          // NEW
+          // The idea is that only comment variables... Okay.
+          // The issue is that having a pattern is way too powerful, and can lead to unplanned inconsistencies. It is true that doing it instance by instance, comment variable by comment variable, is painstaking. But it's the more secure in order to fix an issue that is essentially purely cosmetic.
+          // Also, focusing exclusively on comment variables and barring aliases (and composed) solves many issues at once and can be checked within resolveConfig. // Done.
+
+          // if (replacement && composedVariablesExclusives.some((e) => key === e))
+          if (replacement && composedVariablesExclusivesSet.has(key)) continue;
+
           if (replacement) {
             fixedText = fixedText.replace(fullMatch, () => replacement);
             hasValidFix = true;

package/library/_commons/utilities/flows.js

@@ -5,13 +5,13 @@ import {
   $COMMENT,
   commentVariablesPluginName,
   extractRuleName,
+  resolveRuleName,
+  compressRuleName,
   typeScriptAndJSXCompatible,
   extractObjectStringLiteralValues,
 } from "comment-variables-resolve-config";
 
 import {
-  resolveRuleName,
-  compressRuleName,
   allJSTSFileGlobs,
   allMDFileGlobs,
   allMDVirtualJSTSFileGlobs,
@@ -25,6 +25,7 @@ import { ruleNames_makeRules } from "../constants/rules.js";
  * @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 {string[]} composedVariablesExclusives 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.
  * @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
  */
@@ -32,6 +33,7 @@ const coreCommentsFlow = async (
   ruleName,
   ignores,
   flattenedConfigData,
+  composedVariablesExclusives,
   aliases_flattenedKeys
 ) => {
   const eslint = new ESLint({
@@ -48,6 +50,7 @@ const coreCommentsFlow = async (
             rules: {
               [ruleName]: ruleNames_makeRules[ruleName](
                 flattenedConfigData,
+                composedVariablesExclusives,
                 aliases_flattenedKeys
               ),
             },
@@ -105,18 +108,21 @@ const coreCommentsFlow = async (
  * 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 {string[]} composedVariablesExclusives 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.
  * @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 (
   ignores,
   flattenedConfigData,
+  composedVariablesExclusives,
   aliases_flattenedKeys
 ) =>
   coreCommentsFlow(
     resolveRuleName,
     ignores,
     flattenedConfigData,
+    composedVariablesExclusives,
     aliases_flattenedKeys
   );
 
@@ -126,12 +132,20 @@ export const resolveCommentsFlow = async (
  * 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.
+ * @param {string[]} composedVariablesExclusives 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.
  * @returns
  */
 export const compressCommentsFlow = async (
   ignores,
-  reversedFlattenedConfigData
-) => coreCommentsFlow(compressRuleName, ignores, reversedFlattenedConfigData);
+  reversedFlattenedConfigData,
+  composedVariablesExclusives
+) =>
+  coreCommentsFlow(
+    compressRuleName,
+    ignores,
+    reversedFlattenedConfigData,
+    composedVariablesExclusives
+  );
 
 /* placeholdersCommentsFlow */
 

package/library/index.js

@@ -9,19 +9,16 @@ import resolveConfig, {
   defaultConfigFileName,
   templateFileName,
   exampleFileName,
+  resolveRuleName,
+  compressRuleName,
+  placeholdersRuleName,
   configFlag,
   cwd,
   knownIgnores,
   makeResolvedConfigData,
 } from "comment-variables-resolve-config";
 
-import {
-  hasPackageJson,
-  hasGitFolder,
-  resolveRuleName,
-  compressRuleName,
-  placeholdersRuleName,
-} from "./_commons/constants/bases.js";
+import { hasPackageJson, hasGitFolder } from "./_commons/constants/bases.js";
 
 import { exitDueToFailure, logError } from "./_commons/utilities/helpers.js";
 import {
@@ -128,6 +125,7 @@ const {
   rawConfigAndImportPaths,
   lintConfigImports,
   myIgnoresOnly,
+  composedVariablesExclusives,
 } = resolveConfigResults;
 
 skipDetails || console.log("Running with config:", config);
@@ -140,9 +138,11 @@ skipDetails ||
 skipDetails || console.log("Aliases are:", aliases_flattenedKeys);
 skipDetails || console.log("Config path is:", configPath);
 skipDetails || console.log("Passed ignores are:", passedIgnores);
-// NEW
 skipDetails || console.log("lintConfigImports is:", lintConfigImports);
 skipDetails || console.log("myIgnoresOnly are:", myIgnoresOnly);
+// NEW
+skipDetails ||
+  console.log("composedVariablesExclusives are:", composedVariablesExclusives);
 
 // ADDRESSES THE --lint-config-imports FLAG (lintConfigImports, no longer a flag), GIVEN THAT THE FILES IMPORTED BY THE CONFIG ARE IGNORED BY DEFAULT.
 
@@ -195,12 +195,17 @@ switch (coreCommand) {
     await resolveCommentsFlow(
       ignores,
       flattenedConfigData,
+      composedVariablesExclusives,
       aliases_flattenedKeys
     );
     break;
   case compressRuleName:
     console.log(`Running ${compressRuleName}...`);
-    await compressCommentsFlow(ignores, reversedFlattenedConfigData);
+    await compressCommentsFlow(
+      ignores,
+      reversedFlattenedConfigData,
+      composedVariablesExclusives
+    );
     break;
   case placeholdersRuleName:
     console.log(`Running ${placeholdersRuleName}...`);

package/package.json

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