comment-variables 1.1.0 → 1.1.2

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

@@ -106,6 +106,8 @@ const data = {
     constants: Object.freeze({
       sortedReversedFlattenedConfigData:
         "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." /* $COMMENT#JSDOC#CONSTANTS#SORTEDREVERSEDFLATTENEDCONFIGDATA */,
+      composedVariablesExclusivesSet:
+        "A local Set out of composed variables exclusives for speed." /* $COMMENT#JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET */,
     }),
   }),
 };
@@ -115,7 +117,6 @@ const ignores = ["README.md", "generate.template.js", "generate.example.js"];
 const lintConfigImports = false; // can be omitted
 const myIgnoresOnly = false; // can be omitted
 
-// NEW
 const composedVariablesExclusives = []; // can be omitted
 
 const config = {

package/comments.config.json

@@ -155,6 +155,11 @@
         "value": "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.",
         "key": "JSDOC#CONSTANTS#SORTEDREVERSEDFLATTENEDCONFIGDATA",
         "placeholder": "$COMMENT#JSDOC#CONSTANTS#SORTEDREVERSEDFLATTENEDCONFIGDATA"
+      },
+      "composedVariablesExclusivesSet": {
+        "value": "A local Set out of composed variables exclusives for speed.",
+        "key": "JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET",
+        "placeholder": "$COMMENT#JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET"
       }
     }
   }

package/generate.template.js

@@ -20,7 +20,6 @@ const ignores = [];
 const lintConfigImports = false; // can be omitted
 const myIgnoresOnly = false; // can be omitted
 
-// NEW
 const composedVariablesExclusives = []; // can be omitted
 
 const config = {

package/library/_commons/constants/bases.js

@@ -3,11 +3,6 @@ import path from "path";
 
 import { cwd } from "comment-variables-resolve-config";
 
-// 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"));
 // to prevent irreversible changes

package/library/_commons/rules/compress.js

@@ -16,7 +16,7 @@ const makeRule = (reversedFlattenedConfigData, composedVariablesExclusives) => {
     reversedFlattenedConfigData
   ).sort(([a], [b]) => b.length - a.length);
 
-  // makes a set out of composed variables exclusives
+  /** A local Set out of composed variables exclusives for speed. */
   const composedVariablesExclusivesSet = new Set(composedVariablesExclusives);
 
   /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */
@@ -49,7 +49,6 @@ const makeRule = (reversedFlattenedConfigData, composedVariablesExclusives) => {
           commentKey,
         ] of sortedReversedFlattenedConfigData) {
           // NEW
-          // if (composedVariablesExclusives.some((e) => commentKey === e))
           if (composedVariablesExclusivesSet.has(commentKey)) continue;
 
           const pattern = makeIsolatedStringRegex(resolvedValue);

package/library/_commons/rules/resolve.js

@@ -15,7 +15,7 @@ const makeRule = (
   composedVariablesExclusives,
   aliases_flattenedKeys
 ) => {
-  // makes a set out of composed variables exclusives
+  /** A local Set out of composed variables exclusives for speed. */
   const composedVariablesExclusivesSet = new Set(composedVariablesExclusives);
 
   /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */
@@ -58,11 +58,8 @@ const makeRule = (
           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))
+          // The issue is that having patterns instead of the exact keys is way too powerful, effectively slow, 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, notably by covering aliases in one go.
           if (replacement && composedVariablesExclusivesSet.has(key)) continue;
 
           if (replacement) {

package/library/_commons/utilities/flows.js

@@ -33,6 +33,7 @@ const coreCommentsFlow = async (
   ruleName,
   ignores,
   flattenedConfigData,
+  // NEW
   composedVariablesExclusives,
   aliases_flattenedKeys
 ) => {
@@ -50,6 +51,7 @@ const coreCommentsFlow = async (
             rules: {
               [ruleName]: ruleNames_makeRules[ruleName](
                 flattenedConfigData,
+                // NEW
                 composedVariablesExclusives,
                 aliases_flattenedKeys
               ),
@@ -115,6 +117,7 @@ const coreCommentsFlow = async (
 export const resolveCommentsFlow = async (
   ignores,
   flattenedConfigData,
+  // NEW
   composedVariablesExclusives,
   aliases_flattenedKeys
 ) =>
@@ -122,6 +125,7 @@ export const resolveCommentsFlow = async (
     resolveRuleName,
     ignores,
     flattenedConfigData,
+    // NEW
     composedVariablesExclusives,
     aliases_flattenedKeys
   );
@@ -138,12 +142,14 @@ export const resolveCommentsFlow = async (
 export const compressCommentsFlow = async (
   ignores,
   reversedFlattenedConfigData,
+  // NEW
   composedVariablesExclusives
 ) =>
   coreCommentsFlow(
     compressRuleName,
     ignores,
     reversedFlattenedConfigData,
+    // NEW
     composedVariablesExclusives
   );
 

package/library/index.js

@@ -142,7 +142,10 @@ skipDetails || console.log("lintConfigImports is:", lintConfigImports);
 skipDetails || console.log("myIgnoresOnly are:", myIgnoresOnly);
 // NEW
 skipDetails ||
-  console.log("composedVariablesExclusives are:", composedVariablesExclusives);
+  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,6 +198,7 @@ switch (coreCommand) {
     await resolveCommentsFlow(
       ignores,
       flattenedConfigData,
+      // NEW
       composedVariablesExclusives,
       aliases_flattenedKeys
     );
@@ -204,6 +208,7 @@ switch (coreCommand) {
     await compressCommentsFlow(
       ignores,
       reversedFlattenedConfigData,
+      // NEW
       composedVariablesExclusives
     );
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
     "comment-variables": "./library/index.js",