comment-variables 1.0.0 → 1.1.1

package/README.md

@@ -12,7 +12,7 @@ npm install -g comment-variables
 
 ## Commands
 
-**`comment-variables` (aliases `jscomments`/`comvar`) comes with three commands in this initial release:**
+**`comment-variables` (aliases `jscomments`/`comvar`) comes with four commands in this initial release:**
 
 ```
 comment-variables
@@ -20,6 +20,12 @@ comment-variables
 
 Interacts with your root `comments.config.js` file's 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 as 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. If no configuration file is found, a tutorial mode is triggered, generating a template config file for you.)
 
+```
+comment-variables placeholders
+```
+
+Creates Comment Variables placeholders right next to the single sources of truth where Comment Variables are defined. (See in config example below.)
+
 ```
 comment-variables compress
 ```
@@ -34,45 +40,63 @@ Scans your line and block comments for `$COMMENT#*` placeholders (like `$COMMENT
 
 _The `compress` and `resolve` commands make each other entirely reversible._
 
-**New command: `comment-variables placeholders`**
+## Flags
+
+**The CLI tool comes with a single flag:**
 
 ```
-comment-variables placeholders
+comment-variables --config <your-config.js>
 ```
 
-Creates Comment Variables placeholders right next to the single sources of truth where Comment Variables are defined. (See in config example below.)
+Passes a different file as your config file instead of the default root `comments.config.js` file (like `comment-variables --config your-config.js`), through a path relative to the root of your project.
 
-## Flags
+_The --config flag can be composed with any of the commands:_
+
+```
+comment-variables --config your-config.js
+comment-variables compress --config your-config.js
+comment-variables resolve --config your-config.js
+comment-variables placeholders --config your-config.js
+```
 
-**The CLI tool also comes with three flags initially:**
+## Settings
+
+**The config object requires the following settings:**
 
 ```
-comment-variables --config <your-config.js>
+data:
 ```
 
-Passes a different file as your config file instead of the default root `comments.config.js` file (like `comment-variables --config your-config.js`), through a path relative to the root of your project.
+Your dedicated object defining your Comment Variables through nested key-value pairs of string literals.
 
 ```
---lint-config-imports is now part of the config at the `lintConfigImports` key
+ignores:
 ```
 
-By default, `comment-variables` excludes your config file and all the (JavaScript/TypeScript) files it recursively imports. This config option cancels this mechanism, linting config imports. (The config file however still remains excluded from linting.)
+Your dedicated array defining your files and folders to be ignored by the `compress` and `resolve` commands through strings of paths relative to the root of your project.
+
+## Options
+
+**The config object supports the following options:**
 
 ```
---my-ignores-only is now part of the config at the `myIgnoresOnly` key
+lintConfigImports:
 ```
 
-By default, `comment-variables` includes a preset list of ignored folders (`"node_modules"`, `".next"`, `".react-router"`...). This config option cancels this mechanism so that you can have full control over your ignored files and folders.
+By default, `comment-variables` excludes your config file and all the (JavaScript/TypeScript) files it recursively imports. Passing `true` to this config option cancels this mechanism, linting config imports. (The config file however still remains excluded from linting.)
 
-_The --config flag can be composed with any of the commands:_
+```
+myIgnoresOnly:
+```
+
+By default, `comment-variables` includes a preset list of ignored folders (`"node_modules"`, `".next"`, `".react-router"`...). Passing `true` to this config option cancels this mechanism so that you can have full control over your ignored files and folders.
 
 ```
-comment-variables --config your-config.js
-comment-variables compress --config your-config.js
-comment-variables resolve --config your-config.js
-comment-variables placeholders --config your-config.js
+composedVariablesExclusives:
 ```
 
+In due time, you may end up creating Comment Variables that are exclusively meant to be used to create other Comment Variables – the latter classified as composed variables. Passing an array to this config option, comprised of the keys of these original comment variables (for example, if a Comment Variable placeholder is `$COMMENT#COMMENT` its related key is `COMMENT`), prevents these original comment variables from being affected by the `compress` and `resolve` commands.
+
 ## **`comments.config.js`**
 
 A root `comments.config.js` file looks like this. (This is the config file I'm using to manage my JavaScript comments in this library.)
@@ -142,11 +166,14 @@ const ignores = ["README.md", "generate.template.js", "generate.example.js"];
 const lintConfigImports = false; // can be omitted
 const myIgnoresOnly = false; // can be omitted
 
+const composedVariablesExclusives = []; // can be omitted
+
 const config = {
   data,
   ignores,
   lintConfigImports,
   myIgnoresOnly,
+  composedVariablesExclusives,
 };
 
 export default config;

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,17 @@ 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
 
+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,14 @@ const ignores = [];
 const lintConfigImports = false; // can be omitted
 const myIgnoresOnly = false; // can be omitted
 
+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,14 @@ 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(
+    "Composed variables exclusives 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 +198,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.1",
   "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": {