comment-variables 0.15.4 → 0.16.0

package/README.md

@@ -18,19 +18,19 @@ npm install -g comment-variables
 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 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.)
+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.)
 
 ```
 comment-variables compress
 ```
 
-Scans your line and block comments for string values defined in your `comments.config.js` (like `"This is a comment"`) to turn them into their corresponding `$COMMENT#*` placeholders defined in your `comments.config.js`. (`This is a comment.` => `$COMMENT#COMMENT`)
+Scans your line and block comments for string values defined in your root `comments.config.js` file (like `"This is a comment"`) to turn them into their corresponding `$COMMENT#*` placeholders defined in your `comments.config.js`. (`This is a comment.` => `$COMMENT#COMMENT`)
 
 ```
 comment-variables resolve
 ```
 
-Scans your line and block comments for `$COMMENT#*` placeholders (like `$COMMENT#COMMENT`) to turn them into their corresponding string values defined in your `comments.config.js`. (`$COMMENT#COMMENT` => `This is a comment.`)
+Scans your line and block comments for `$COMMENT#*` placeholders (like `$COMMENT#COMMENT`) to turn them into their corresponding string values defined in your root `comments.config.js` file. (`$COMMENT#COMMENT` => `This is a comment.`)
 
 _The `compress` and `resolve` commands make each other entirely reversible._
 
@@ -50,19 +50,19 @@ Creates Comment Variables placeholders right next to the single sources of truth
 comment-variables --config <your-config.js>
 ```
 
-Passes a different file as your config instead of the default `comments.config.js` (like `comment-variables --config your-config.js`), through a path relative to the root of your project.
+Passes a different file as your config 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.
 
 ```
 --lint-config-imports is now part of the config at the `lintConfigImports` key
 ```
 
-By default, `comment-variables` excludes your config file and all the (JavaScript/TypeScript) files it recursively imports. This flag cancels this mechanism, linting config imports. (The config file however still remains excluded from linting.)
+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.)
 
 ```
 --my-ignores-only is now part of the config at the `myIgnoresOnly` key
 ```
 
-By default, `comment-variables` includes a preset list of ignored folders (`"node_modules"`, `".next"`, `".react-router"`...). This flag cancels this mechanism so that you can have full control over your ignored files and folders.
+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.
 
 _The --config flag can be composed with any of the commands:_
 
@@ -75,7 +75,7 @@ comment-variables placeholders --config your-config.js
 
 ## **`comments.config.js`**
 
-A `comments.config.js` file looks like this. (This is the config file I'm using to manage my JavaScript comments in this library.)
+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.)
 
 ```js
 const data = {
@@ -120,7 +120,7 @@ const data = {
       configPathIgnores:
         'The array of paths linked to the config file, (named "ignores" given it is ignored by the "compress" and "resolve" commands).' /* $COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES */,
       originalFlattenedConfigData:
-        "The original flattened config data, before changes to Aliases Variables and Composed Variables are applied." /* $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA */,
+        "The original flattened config data, before changes to aliases variables and composed variables are applied." /* $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA */,
     }),
     returns: Object.freeze({
       exitDueToFailure:
@@ -130,13 +130,17 @@ const data = {
       makeRuleCompress:
         "The compress rule based on the reversed flattened config data." /* $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS */,
     }),
+    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 */,
+    }),
   }),
 };
 
-const ignores = ["README.md"];
+const ignores = ["README.md", "generate.template.js", "generate.example.js"];
 
-const lintConfigImports = false; // can be ommitted
-const myIgnoresOnly = false; // can be ommitted
+const lintConfigImports = false; // can be omitted
+const myIgnoresOnly = false; // can be omitted
 
 const config = {
   data,

package/comments.config.js

@@ -91,7 +91,7 @@ const data = {
       configPathIgnores:
         'The array of paths linked to the config file, (named "ignores" given it is ignored by the "compress" and "resolve" commands).' /* $COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES */,
       originalFlattenedConfigData:
-        "The original flattened config data, before changes to Aliases Variables and Composed Variables are applied." /* $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA */,
+        "The original flattened config data, before changes to aliases variables and composed variables are applied." /* $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA */,
     }),
     returns: Object.freeze({
       exitDueToFailure:
@@ -101,15 +101,19 @@ const data = {
       makeRuleCompress:
         "The compress rule based on the reversed flattened config data." /* $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS */,
     }),
+    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 */,
+    }),
   }),
 };
 
-const ignores = ["README.md"];
+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 ommitted
-const myIgnoresOnly = false; // can be ommitted
+const lintConfigImports = false; // can be omitted
+const myIgnoresOnly = false; // can be omitted
 
 const config = {
   data,

package/comments.config.json

@@ -123,7 +123,7 @@
         "placeholder": "$COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES"
       },
       "originalFlattenedConfigData": {
-        "value": "The original flattened config data, before changes to Aliases Variables and Composed Variables are applied.",
+        "value": "The original flattened config data, before changes to aliases variables and composed variables are applied.",
         "key": "JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA",
         "placeholder": "$COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA"
       }
@@ -144,6 +144,13 @@
         "key": "JSDOC#RETURNS#MAKERULECOMPRESS",
         "placeholder": "$COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS"
       }
+    },
+    "constants": {
+      "sortedReversedFlattenedConfigData": {
+        "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"
+      }
     }
   }
 }

package/generate.template.js

@@ -1,7 +1,8 @@
 // A Comment Variables config template generated in case no config file has been found. Feel free to use it as a stepping stone to learn how to use Comment Variables.
 
-// As a first step, go ahead and run the command `comment-variables placeholders`.
-// Then rename the `$COMMENT#COMMENT` placeholder next to `alias` to `$COMMENT#ALIAS` and run again `comment-variables placeholders` to see what happens.
+// As a first step, go ahead and run the command `comment-variables placeholders`. (This generates the Comment Variables placeholders right next to where their values are defined.)
+// Then rename the `$COMMENT#COMMENT` placeholder next to the `alias` key's value in the `data` object to `$COMMENT#ALIAS`, and run again `comment-variables placeholders` to see what happens. (...Which is nothing, and I let you figure out why.)
+
 // You can now use and explore Comment Variables on the accompanying `comments.example.js` file that has also been generated.
 
 const data = Object.freeze({
@@ -16,8 +17,8 @@ const data = Object.freeze({
 
 const ignores = [];
 
-const lintConfigImports = false; // can be ommitted
-const myIgnoresOnly = false; // can be ommitted
+const lintConfigImports = false; // can be omitted
+const myIgnoresOnly = false; // can be omitted
 
 const config = {
   data,

package/library/_commons/utilities/flows.js

@@ -36,9 +36,9 @@ const coreCommentsFlow = async (
 ) => {
   const eslint = new ESLint({
     fix: true,
+    ignorePatterns: ignores,
     errorOnUnmatchedPattern: false,
     overrideConfigFile: true,
-    ignorePatterns: ignores,
     overrideConfig: [
       {
         files: allJSTSFileGlobs,
@@ -138,7 +138,7 @@ export const compressCommentsFlow = async (
 /**
  * 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 {{[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
  */

package/library/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// 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.
+// The shebang/hashbang (#!) 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";
@@ -58,7 +58,7 @@ if (!hasGitFolder) {
 }
 skipDetails || console.log("git folder noticed. Allowed to proceed.");
 
-// OBTAINS THE VALIDATED FLATTENED CONFIG, REVERSE FLATTENED CONFIG, CONFIG PATH, AND PASSED IGNORES.
+// SORTS OUT THE CONFIG PATH.
 
 // extracts the position of the --config flag
 const configFlagIndex = commands.indexOf(configFlag);
@@ -72,7 +72,7 @@ const passedConfigPath =
 // defaults to comments.config.js if no --config flag is set
 let rawConfigPath = passedConfigPath ?? path.join(cwd, defaultConfigFileName);
 
-// HANDLES TUTORIAL MODE
+// HANDLES TUTORIAL MODE.
 
 if (!fs.existsSync(rawConfigPath)) {
   console.log(
@@ -105,7 +105,7 @@ if (!fs.existsSync(rawConfigPath)) {
   rawConfigPath = templateFilePath;
 }
 
-// RESOLVES THE CONFIG
+// RESOLVES THE CONFIG.
 
 console.log(`Resolving config at ${rawConfigPath}...`);
 
@@ -126,7 +126,6 @@ const {
   configPath,
   passedIgnores,
   rawConfigAndImportPaths,
-  // NEW
   lintConfigImports,
   myIgnoresOnly,
 } = resolveConfigResults;
@@ -147,7 +146,6 @@ skipDetails || console.log("myIgnoresOnly are:", myIgnoresOnly);
 
 // ADDRESSES THE --lint-config-imports FLAG (lintConfigImports, no longer a flag), GIVEN THAT THE FILES IMPORTED BY THE CONFIG ARE IGNORED BY DEFAULT.
 
-// const lintConfigImports = commands.indexOf(lintConfigImportsFlag) >= 2; // NOW FROM CONFIG
 const rawConfigPathIgnores = lintConfigImports
   ? [configPath]
   : rawConfigAndImportPaths;
@@ -163,15 +161,14 @@ skipDetails ||
     configPathIgnores
   );
 
-// ADDRESSES THE --my-ignores-only FLAG (myIgnoresOnly, no longer a flag, GIVEN THAT KNOWN IGNORES ARE IGNORED BY DEFAULT
+// ADDRESSES THE --my-ignores-only FLAG (myIgnoresOnly, no longer a flag, GIVEN THAT KNOWN IGNORES ARE IGNORED BY DEFAULT.
 
-// const myIgnoresOnly = commands.indexOf(myIgnoresOnlyFlag) >= 2; // NOW FROM CONFIG
 const rawIgnores = [...configPathIgnores, ...passedIgnores];
 const ignores = myIgnoresOnly ? rawIgnores : [...rawIgnores, ...knownIgnores];
 
 skipDetails || console.log("Ignores are:", ignores);
 
-// NEW: AUTOMATICALLY GENERATE THE JSON OUTPUT OF YOUR RESOLVED CONFIG DATA.
+// AUTOMATICALLY GENERATES THE JSON OUTPUT OF YOUR RESOLVED CONFIG DATA.
 
 const makeResolvedConfigDataResults =
   makeResolvedConfigData(resolveConfigResults);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "0.15.4",
+  "version": "0.16.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.12.3",
+    "comment-variables-resolve-config": "^1.13.2",
     "eslint": "^9.29.0"
   },
   "devDependencies": {