comment-variables 0.4.1 → 0.6.0

package/README.md

@@ -18,15 +18,15 @@ Interacts with your `comments.config.js` default exported object to print all th
 comment-variables compress
 ```
 
-Scans your line and block comments for values defined in your `comments.config.js` (like `"This is a comment"`) to turn them into their corresponding `$COMMENT#*` tokens defined in your `comments.config.js`. (`"This is a comment."` => $COMMENT#COMMENT)
+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#*` tokens defined in your `comments.config.js`. (`This is a comment.` => `$COMMENT#COMMENT`)
 
 ```
 comment-variables resolve
 ```
 
-Scans your line and block comments for `$COMMENT#*` tokens (like $COMMENT#COMMENT) to turn them into their corresponding values defined in your `comments.config.js`. ($COMMENT#COMMENT => This is a comment.)
+Scans your line and block comments for `$COMMENT#*` tokens (like `$COMMENT#COMMENT`) to turn them into their corresponding string values defined in your `comments.config.js`. (`$COMMENT#COMMENT` => `This is a comment.`)
 
-_The `compress` and `resolve` commands are entirely reversible._
+_The `compress` and `resolve` commands make each other entirely reversible._
 
 ## Flags
 
@@ -48,7 +48,7 @@ By default, `comment-variables` excludes your config file and all the (JavaScrip
 comment-variables --my-ignores-only
 ```
 
-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 flag cancels this mechanism so that you can have full control over your ignored files and folders.
 
 _All three flags can be composed together, and with any of the three commands:_
 

package/comments.config.js

@@ -31,11 +31,14 @@ const data = {
         "The flow that compresses actual comments into $COMMENT#* placeholders.", // $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW
       findAllImports:
         "Finds all import paths recursively related to a given file path.", // $COMMENT#JSDOC#DEFINITIONS#FINDALLIMPORTS
-      processImport: "Processes recursively and resolves a single import path.", // $COMMENT#JSDOC#DEFINITIONS#PROCESSIMPORT
+      processImport:
+        "Processes recursively and resolves a single import path. (Unlike `findAllImports`, here `currentDir`, `cwd`, `visitedSet`, `depth`, and `maxDepth` aren't options because they are mandatory and not pre-parameterized.)", // $COMMENT#JSDOC#DEFINITIONS#PROCESSIMPORT
       flattenConfigData:
         "Flattens the config's data property into a one-dimensional object of $COMMENT-*-like keys and string values.", // $COMMENT#JSDOC#DEFINITIONS#FLATTENCONFIGDATA
       resolveConfig:
         "Verifies, validates and resolves the config path to retrieve the config's data and ignores.", // $COMMENT#JSDOC#DEFINITIONS#RESOLVECONFIG
+      logError:
+        'Logs an error to the console depending on its type. (`"error"` or `"warning"`.)', // $COMMENT#JSDOC#DEFINITIONS#LOGERROR
     }),
     params: Object.freeze({
       string: "The string.", // $COMMENT#JSDOC#PARAMS#STRING
@@ -51,24 +54,33 @@ const data = {
         "Either the flattened config data or the reversed flattened config data, since they share the same structure.", // $COMMENT#JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA
       filePath:
         "The absolute path of the file whose imports are being recursively found, such as that of a project's `comments.config.js` file.", // $COMMENT#JSDOC#PARAMS#FILEPATH
-      cwd: "The current working directory, set as `process.cwd()` by default.", // $COMMENT#JSDOC#PARAMS#CWD
-      visitedSet:
-        "The set of strings tracking the import paths that have already been visited, instantiated as a `new Set()` by default.", // $COMMENT#JSDOC#PARAMS#VISITEDSET
-      depth:
-        "The current depth of the recursion, instantiated at `0` by default.", // $COMMENT#JSDOC#PARAMS#DEPTH
-      maxDepth:
-        "The maximum depth allowed for the recursion, instantiated at `100` by default.", // $COMMENT#JSDOC#PARAMS#MAXDEPTH
+      cwdOption:
+        "The current working directory, set as `process.cwd()` by default.", // $COMMENT#JSDOC#PARAMS#CWDOPTION
+      visitedSetOption:
+        "The set of strings tracking the import paths that have already been visited, instantiated as a `new Set()` by default.", // $COMMENT#JSDOC#PARAMS#VISITEDSETOPTION
+      depthOption:
+        "The current depth of the recursion, instantiated at `0` by default.", // $COMMENT#JSDOC#PARAMS#DEPTHOPTION
+      maxDepthOption:
+        "The maximum depth allowed for the recursion, instantiated at `100` by default.", // $COMMENT#JSDOC#PARAMS#MAXDEPTHOPTION
       importPath: "The import path currently being addressed.", // $COMMENT#JSDOC#PARAMS#IMPORTPATH
-      currentDir:
-        "The directory containing the import path currently being addressed.", // $COMMENT#JSDOC#PARAMS#CURRENTDIR
+      currentDirSetting:
+        "The directory containing the import path currently being addressed.", // $COMMENT#JSDOC#PARAMS#CURRENTDIRSETTING
+      cwdSetting: "The current working directory.", // $COMMENT#JSDOC#PARAMS#CWDSETTING
+      visitedSetSetting:
+        "The set of strings tracking the import paths that have already been visited.", // $COMMENT#JSDOC#PARAMS#VISITEDSETSETTING
+      depthSetting: "The current depth of the recursion.", // $COMMENT#JSDOC#PARAMS#DEPTHSETTING
+      maxDepthSetting: "The maximum depth allowed for the recursion.", // $COMMENT#JSDOC#PARAMS#MAXDEPTHSETTING
       configData:
-        "The config's data property. (Values are typed `any` given the limitations in typing recursive values in JSDoc.)", // $COMMENT#JSDOC#PARAMS#CONFIGDATA
-      configDataMap:
-        "The map housing the flattened keys with their values and sources through recursion, instantiated as a `new Map()`.", // $COMMENT#JSDOC#PARAMS#CONFIGDATAMAP
-      parentKeys:
-        "The list of keys that are parent to the key at hand given the recursive nature of the config's data's data structure, instantiated as an empty array of strings.", // $COMMENT#JSDOC#PARAMS#PARENTKEYS
+        "The config's data property. (Values are typed `unknown` given the limitations in typing recursive values in JSDoc.)", // $COMMENT#JSDOC#PARAMS#CONFIGDATA
+      configDataMapOption:
+        "The map housing the flattened keys with their values and sources through recursion, instantiated as a `new Map()`.", // $COMMENT#JSDOC#PARAMS#CONFIGDATAMAPOPTION
+      parentKeysOption:
+        "The list of keys that are parent to the key at hand given the recursive nature of the config's data's data structure, instantiated as an empty array of strings (`[]`).", // $COMMENT#JSDOC#PARAMS#PARENTKEYSOPTION
       configPath:
-        "The path of the config, either from `comments.config.js` or from a config passed via the `--config` flag.", // $COMMENT#JSDOC#PARAMS#CONFIGPATH
+        'The path of the config from `comments.config.js`, or from a config passed via the `--config` flag in the CLI, or from one passed via `"commentVariables.config": true` in `.vscode/settings.json` for the VS Code Extension.', // $COMMENT#JSDOC#PARAMS#CONFIGPATH
+      options: "The additional options as follows:", // $COMMENT#JSDOC#PARAMS#OPTIONS
+      settings: "The required settings as follows:", // $COMMENT#JSDOC#PARAMS#SETTINGS
+      error: "The error object being handle for the logging.", // $COMMENT#JSDOC#PARAMS#ERROR
     }),
     returns: Object.freeze({
       exitDueToFailure:
@@ -78,13 +90,13 @@ const data = {
       makeRuleCompress:
         "The compress rule based on the reversed flattened config data.", // $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS
       findAllImports:
-        "The complete set of strings of import paths recursively related to the given file path, or `null` if an issue has arisen.", // $COMMENT#JSDOC#RETURNS#FINDALLIMPORTS
+        "The complete set of strings of import paths recursively related to the given file path in a success object (`success: true`). Errors are bubbled up during failures in a failure object (`success: false`).", // $COMMENT#JSDOC#RETURNS#FINDALLIMPORTS
       processImport:
-        "`true` to skip unresolved paths, `false` if resolution fails at any level.", // $COMMENT#JSDOC#RETURNS#PROCESSIMPORT
+        "`true` to continue to the next operation, `false` to stop the whole `findAllImports` process.", // $COMMENT#JSDOC#RETURNS#PROCESSIMPORT
       flattenConfigData:
-        "Both the flattened config data and its reversed version to ensure the strict reversibility of the `resolve` and `compress` commands.", // $COMMENT#JSDOC#RETURNS#FLATTENCONFIGDATA
+        "Both the flattened config data and its reversed version to ensure the strict reversibility of the `resolve` and `compress` commands in a success object (`success: true`). Errors are bubbled up during failures so they can be reused differently on the CLI and the VS Code Extension in a failure object (`success: false`).", // $COMMENT#JSDOC#RETURNS#FLATTENCONFIGDATA
       resolveConfig:
-        "The flattened config data, the reverse flattened config data, the verified config path, the raw passed ignores, and the original config.", // $COMMENT#JSDOC#RETURNS#RESOLVECONFIG
+        "The flattened config data, the reverse flattened config data, the verified config path, the raw passed ignores, and the original config. Errors are returned during failures so they can be reused differently on the CLI and the VS Code Extension.", // $COMMENT#JSDOC#RETURNS#RESOLVECONFIG
     }),
   }),
 };

package/library/_commons/constants/bases.js

@@ -18,10 +18,10 @@ export const hasPackageJson = fs.existsSync(path.join(cwd, "package.json"));
 // to prevent irreversible changes
 export const hasGitFolder = fs.existsSync(path.join(cwd, ".git"));
 
-// comments.config.js
+// comments.config.js // comment-variables-resolve-config
 export const defaultConfigFileName = "comments.config.js";
 
-// flags
+// flags // comment-variables-resolve-config
 export const configFlag = "--config";
 export const lintConfigImportsFlag = "--lint-config-imports";
 export const myIgnoresOnlyFlag = "--my-ignores-only";
@@ -29,11 +29,12 @@ export const myIgnoresOnlyFlag = "--my-ignores-only";
 // ESLint ignores
 export const knownIgnores = [
   "node_modules",
+  "dist",
+  "out",
   ".next",
   ".react-router",
   ".parcel-cache",
   ".react-router-parcel",
-  "dist",
 ];
 
 // ESLint file globs
@@ -70,8 +71,21 @@ export const typeScriptAndJSXCompatible = {
 // messageId
 export const placeholderMessageId = "placeholderMessageId";
 
-// regexes
-export const configKeyRegex = /^[\p{Ll}\p{Lu}\p{Lo}\p{Pd}\p{Pc}\p{N}\s]+$/u;
-export const flattenedConfigKeyRegex = /^[\p{Lu}\p{Lo}\p{Pd}\p{Pc}\p{N}#]+$/u; // same as configKeyRegex but without lowercase letters (\p{Ll}), without whitespaces (\s which are replaced by underscores) and with the '#' character (that links each subkey together)
-export const flattenedConfigPlaceholderRegex =
-  /\$COMMENT#([\p{Lu}\p{Lo}\p{Pd}\p{Pc}\p{N}_#]+)/gu; // same as flattenedConfigKeyRegex but taking the prefix $COMMENT# into consideration, removing ^ and $ in the capture group, globally
+// placeholder prefix // comment-variables-resolve-config
+export const $COMMENT = "$COMMENT";
+
+// success objects // comment-variables-resolve-config
+export const successFalse = Object.freeze({
+  success: false,
+});
+export const successTrue = Object.freeze({
+  success: true,
+});
+
+// error objects // comment-variables-resolve-config
+export const typeError = Object.freeze({
+  type: "error",
+});
+export const typeWarning = Object.freeze({
+  type: "warning",
+});

package/library/_commons/constants/regexes.js

@@ -0,0 +1,13 @@
+import { $COMMENT } from "./bases.js";
+
+import { escapeRegex } from "../utilities/helpers.js";
+
+// comment-variables-resolve-config
+export const configKeyRegex = /^[\p{Ll}\p{Lu}\p{Lo}\p{Pd}\p{Pc}\p{N}\s]+$/u;
+// comment-variables-resolve-config
+export const flattenedConfigKeyRegex = /^[\p{Lu}\p{Lo}\p{Pd}\p{Pc}\p{N}#]+$/u; // same as configKeyRegex but without lowercase letters (\p{Ll}), without whitespaces (\s which are replaced by underscores) and with the '#' character (that links each subkey together)
+// comment-variables-resolve-config
+export const flattenedConfigPlaceholderRegex = new RegExp(
+  `${escapeRegex($COMMENT)}#([\\p{Lu}\\p{Lo}\\p{Pd}\\p{Pc}\\p{N}#_]+)`,
+  "gu"
+); // same as flattenedConfigKeyRegex but taking the prefix $COMMENT and its # into consideration, removing ^ and $ in the capture group, and using _ as replacement for whitesplaces, globally

package/library/_commons/rules/compress.js

@@ -1,4 +1,4 @@
-import { placeholderMessageId } from "../constants/bases.js";
+import { placeholderMessageId, $COMMENT } from "../constants/bases.js";
 
 import { escapeRegex } from "..//utilities/helpers.js";
 
@@ -49,7 +49,7 @@ const makeRule = (reversedFlattenedConfigData) => {
 
           fixedText = fixedText.replace(pattern, () => {
             modified = true;
-            return `$COMMENT#${commentKey}`;
+            return `${$COMMENT}#${commentKey}`;
           });
         }
 

package/library/_commons/rules/resolve.js

@@ -1,7 +1,5 @@
-import {
-  placeholderMessageId,
-  flattenedConfigPlaceholderRegex,
-} from "../constants/bases.js";
+import { placeholderMessageId } from "../constants/bases.js";
+import { flattenedConfigPlaceholderRegex } from "../constants/regexes.js";
 
 /**
  * The utility that creates the resolve rule based on the flattened config data, used to transform $COMMENT#* placeholders into actual comments.

package/library/_commons/schemas/config.js

@@ -1,11 +1,11 @@
 import { z } from "zod";
 
-import { configKeyRegex } from "../constants/bases.js";
+import { configKeyRegex } from "../constants/regexes.js";
 
 export const ConfigDataSchema = z
   .lazy(() =>
     z.record(
-      z.any().superRefine((val, ctx) => {
+      z.unknown().superRefine((val, ctx) => {
         if (typeof val === "string") {
           return;
         }

package/library/_commons/utilities/find-all-imports.js

@@ -4,93 +4,141 @@ import path from "path";
 import { resolveImportingPath } from "resolve-importing-path";
 import { getSourceCodeFromFilePath } from "get-sourcecode-from-file-path";
 
-/* findAllImports */
+import { successFalse, successTrue, typeWarning } from "../constants/bases.js";
 
 /**
- * Processes recursively and resolves a single import path.
+ * @typedef {{
+ *   success: false;
+ *   errors: Array<{ message: string; type: "warning";}>;
+ * } | {
+ *   success: true;
+ *   visitedSet: Set<string>;
+ * }} FindAllImportsResults
+ */
+
+// IMPORTANT. findAllImports needs to be able to take a callback function that it can play at every recursion to find the corresponding value for go-to-definitions. But that's on the roadmap, not in the first release. The first implementation of this pinpoint go-to-definition mechanism will be made by analyzing each path obtained rather than by doing so as the paths are being obtained.
+
+/**
+ * Processes recursively and resolves a single import path. (Unlike `findAllImports`, here `currentDir`, `cwd`, `visitedSet`, `depth`, and `maxDepth` aren't options because they are mandatory and not pre-parameterized.)
  * @param {string} importPath The import path currently being addressed.
- * @param {string} currentDir The directory containing the import path currently being addressed.
- * @param {string} cwd The current working directory, set as `process.cwd()` by default.
- * @param {Set<string>} visitedSet The set of strings tracking the import paths that have already been visited, instantiated as a `new Set()` by default.
- * @param {number} depth The current depth of the recursion, instantiated at `0` by default.
- * @param {number} maxDepth The maximum depth allowed for the recursion, instantiated at `100` by default.
- * @returns `true` to skip unresolved paths, `false` if resolution fails at any level.
+ * @param {Object} settings The required settings as follows:
+ * @param {string} settings.currentDir The directory containing the import path currently being addressed.
+ * @param {string} settings.cwd The current working directory.
+ * @param {Set<string>} settings.visitedSet The set of strings tracking the import paths that have already been visited.
+ * @param {number} settings.depth The current depth of the recursion.
+ * @param {number} settings.maxDepth The maximum depth allowed for the recursion.
+ * @returns `true` to continue to the next operation, `false` to stop the whole `findAllImports` process. //
  */
 const processImport = (
   importPath,
-  currentDir,
-  cwd,
-  visitedSet,
-  depth,
-  maxDepth
+  { currentDir, cwd, visitedSet, depth, maxDepth }
 ) => {
+  // Resolves the provided import path.
   const resolvedPath = resolveImportingPath(currentDir, importPath, cwd);
-  if (!resolvedPath) return true;
+  // Returns true early to skip processing on unresolved paths.
+  if (!resolvedPath) return { ...successTrue, visitedSet };
 
-  const result = findAllImports(
-    resolvedPath,
+  // Establishes the options for the next round of findAllImports.
+  const findAllImportsOptions = {
     cwd,
     visitedSet,
-    depth + 1,
-    maxDepth
+    depth: depth + 1,
+    maxDepth,
+  };
+
+  // Runs findAllImports on the imported path resolved, thus recursively.
+  const findAllImportsResults = /** @type {FindAllImportsResults} */ (
+    findAllImports(resolvedPath, findAllImportsOptions)
   );
-  return result !== null; // Returns false if child failed.
+  // Returns true if the round of findAllImports succeeded, false if it failed.
+  return findAllImportsResults;
 };
 
 /**
  * Finds all import paths recursively related to a given file path.
  * @param {string} filePath The absolute path of the file whose imports are being recursively found, such as that of a project's `comments.config.js` file.
- * @param {string} cwd The current working directory, set as `process.cwd()` by default.
- * @param {Set<string>} visitedSet The set of strings tracking the import paths that have already been visited, instantiated as a `new Set()` by default.
- * @param {number} depth The current depth of the recursion, instantiated at `0` by default.
- * @param {number} maxDepth The maximum depth allowed for the recursion, instantiated at `100` by default.
- * @returns The complete set of strings of import paths recursively related to the given file path, or `null` if an issue has arisen.
+ * @param {Object} options The additional options as follows:
+ * @param {string} [options.cwd] The current working directory, set as `process.cwd()` by default.
+ * @param {Set<string>} [options.visitedSet] The current working directory, set as `process.cwd()` by default.
+ * @param {number} [options.depth] The current depth of the recursion, instantiated at `0` by default.
+ * @param {number} [options.maxDepth] The maximum depth allowed for the recursion, instantiated at `100` by default.
+ * @returns The complete set of strings of import paths recursively related to the given file path in a success object (`success: true`). Errors are bubbled up during failures in a failure object (`success: false`).
  */
 export const findAllImports = (
   filePath,
-  cwd = process.cwd(),
-  visitedSet = new Set(),
-  depth = 0,
-  maxDepth = 100
+  {
+    cwd = process.cwd(),
+    visitedSet = new Set(),
+    depth = 0,
+    maxDepth = 100,
+  } = {}
 ) => {
   // Fails early if max depth is recursively reached.
   if (depth > maxDepth) {
-    console.error(`ERROR. Max depth ${maxDepth} reached at ${filePath}.`);
-    return null;
+    return {
+      ...successFalse,
+      errors: [
+        {
+          ...typeWarning,
+          message: `WARNING. Max depth ${maxDepth} reached at ${filePath}.`,
+        },
+      ],
+    };
   }
   // Fails early if no file is found.
   if (!fs.existsSync(filePath)) {
-    console.error(`ERROR. File not found at ${filePath}.`);
-    return null;
+    return {
+      ...successFalse,
+      errors: [
+        {
+          ...typeWarning,
+          message: `WARNING. File not found at ${filePath}.`,
+        },
+      ],
+    };
+  }
+  // Returns the existing set directly if a path has already been visited.
+  if (visitedSet.has(filePath)) {
+    return { ...successTrue, visitedSet };
   }
 
   // Updates the visited set.
-  if (visitedSet.has(filePath)) return visitedSet;
   visitedSet.add(filePath);
 
   // Parses the file's source code AST.
   const sourceCode = getSourceCodeFromFilePath(filePath);
+  // Fails early there is no AST.
   if (!sourceCode?.ast) {
-    console.error(`ERROR. Failed to parse AST for ${filePath}.`);
-    return null;
+    return {
+      ...successFalse,
+      errors: [
+        {
+          ...typeWarning,
+          message: `WARNING. Failed to parse AST for ${filePath}.`,
+        },
+      ],
+    };
   }
 
+  // Makes the joint settings for the conditional calls of processImport.
+  const processImportSettings = {
+    currentDir: path.dirname(filePath),
+    cwd,
+    visitedSet,
+    depth,
+    maxDepth,
+  };
+
   // Processes all imports.
-  const currentDir = path.dirname(filePath);
   for (const node of sourceCode.ast.body) {
     // ES Modules (import x from 'y')
     if (node.type === "ImportDeclaration") {
-      if (
-        !processImport(
-          node.source.value,
-          currentDir,
-          cwd,
-          visitedSet,
-          depth,
-          maxDepth
-        )
-      ) {
-        return null;
+      const processImportResults = processImport(
+        node.source.value,
+        processImportSettings
+      );
+      if (!processImportResults) {
+        return processImportResults;
       }
     }
 
@@ -101,20 +149,15 @@ export const findAllImports = (
       node.expression.callee.name === "require" &&
       node.expression.arguments[0]?.type === "Literal"
     ) {
-      if (
-        !processImport(
-          node.expression.arguments[0].value,
-          currentDir,
-          cwd,
-          visitedSet,
-          depth,
-          maxDepth
-        )
-      ) {
-        return null;
+      const processImportResults = processImport(
+        node.expression.arguments[0].value,
+        processImportSettings
+      );
+      if (!processImportResults) {
+        return processImportResults;
       }
     }
   }
 
-  return visitedSet; // success
+  return { ...successTrue, visitedSet };
 };

package/library/_commons/utilities/flatten-config-data.js

@@ -1,18 +1,30 @@
-import { flattenedConfigKeyRegex } from "../constants/bases.js";
+import { successFalse, successTrue, typeError } from "../constants/bases.js";
+import { flattenedConfigKeyRegex } from "../constants/regexes.js";
 
-import { exitDueToFailure } from "../utilities/helpers.js";
+/**
+ * @typedef {Record<string, unknown>} ConfigData
+ *
+ * @typedef {{
+ *   success: false;
+ *   errors: Array<{ type: "error" | "warning"; message: string }>;
+ * } | {
+ *   success: true;
+ *   flattenedConfigData: Record<string, string>;
+ *   reversedFlattenedConfigData: Record<string, string>;
+ * }} FlattenConfigDataResults
+ */
 
 /**
  * Flattens the config's data property into a one-dimensional object of $COMMENT-*-like keys and string values.
- * @param {Record<string, any>} configData The config's data property. (Values are typed `any` given the limitations in typing recursive values in JSDoc.)
- * @param {Map<string, {value: string; source: string}>} configDataMap The map housing the flattened keys with their values and sources through recursion, instantiated as a `new Map()`.
- * @param {string[]} parentKeys The list of keys that are parent to the key at hand given the recursive nature of the config's data's data structure, instantiated as an empty array of strings.
- * @returns Both the flattened config data and its reversed version to ensure the strict reversibility of the `resolve` and `compress` commands.
+ * @param {ConfigData} configData The config's data property. (Values are typed `unknown` given the limitations in typing recursive values in JSDoc.)
+ * @param {Object} [options] The additional options as follows:
+ * @param {Map<string, {value: string; source: string}>} [options.configDataMap] The map housing the flattened keys with their values and sources through recursion, instantiated as a `new Map()`.
+ * @param {string[]} [options.parentKeys] The list of keys that are parent to the key at hand given the recursive nature of the config's data's data structure, instantiated as an empty array of strings (`[]`).
+ * @returns Both the flattened config data and its reversed version to ensure the strict reversibility of the `resolve` and `compress` commands in a success object (`success: true`). Errors are bubbled up during failures so they can be reused differently on the CLI and the VS Code Extension in a failure object (`success: false`).
  */
 export const flattenConfigData = (
   configData,
-  configDataMap = new Map(),
-  parentKeys = []
+  { configDataMap = new Map(), parentKeys = [] } = {}
 ) => {
   for (const [key, value] of Object.entries(configData)) {
     const newKeys = [...parentKeys, key];
@@ -24,12 +36,18 @@ export const flattenConfigData = (
 
     if (typeof value === "string") {
       if (configDataMap.has(normalizedKey)) {
-        console.error(
-          `ERROR. The normalized key "${normalizedKey}" has already been assigned. Check between the two following key paths: \n"${
-            configDataMap.get(normalizedKey).source
-          }" \n"${source}"`
-        );
-        exitDueToFailure();
+        // checks the uniqueness of each normalized key
+        return {
+          ...successFalse,
+          errors: [
+            {
+              ...typeError,
+              message: `ERROR. The normalized key "${normalizedKey}" has already been assigned. Check between the two following key paths: \n"${
+                configDataMap.get(normalizedKey).source
+              }" \n"${source}"`,
+            },
+          ],
+        };
       }
 
       configDataMap.set(normalizedKey, {
@@ -37,10 +55,13 @@ export const flattenConfigData = (
         source,
       });
     } else if (typeof value === "object" && value && !Array.isArray(value)) {
-      /** @type {Record<string, any>} */
-      const typedValue = value;
+      const subConfigData = /** @type {ConfigData} */ (value);
+      const flattenConfigDataOptions = { configDataMap, parentKeys: newKeys };
 
-      flattenConfigData(typedValue, configDataMap, newKeys);
+      const flattenConfigDataResults = /** @type {FlattenConfigDataResults} */ (
+        flattenConfigData(subConfigData, flattenConfigDataOptions)
+      );
+      if (!flattenConfigDataResults.success) return flattenConfigDataResults;
     }
   }
 
@@ -63,36 +84,52 @@ export const flattenConfigData = (
   const flattenedConfigDataValuesArray = Object.values(flattenedConfigData);
   const flattenedConfigDataValuesSet = new Set(flattenedConfigDataValuesArray);
 
-  flattenedConfigDataKeysSet.forEach((key) => {
-    // checks the reversability of flattenedConfigData
+  for (const key of flattenedConfigDataKeysSet) {
     if (flattenedConfigDataValuesSet.has(key)) {
-      console.error(
-        `ERROR. The key "${key}" is and shouldn't be among the values of flattenedConfigData.`
-      );
-      exitDueToFailure();
+      // checks the reversability of flattenedConfigData
+      return {
+        ...successFalse,
+        errors: [
+          {
+            ...typeError,
+            message: `ERROR. The key "${key}" is and shouldn't be among the values of flattenedConfigData.`,
+          },
+        ],
+      };
     }
     if (!flattenedConfigKeyRegex.test(key)) {
       // checks if each key for flattenedConfigData passes the flattenedConfigKeyRegex test
-      console.error(
-        `ERROR. Somehow the key "${key}" is not properly formatted. (This is mostly an internal mistake.)`
-      );
-      exitDueToFailure();
+      return {
+        ...successFalse,
+        errors: [
+          {
+            ...typeError,
+            message: `ERROR. Somehow the key "${key}" is not properly formatted. (This is mostly an internal mistake.)`,
+          },
+        ],
+      };
     }
-  });
+  }
 
   /** @type {Set<string>} */
   const set = new Set();
 
-  flattenedConfigDataValuesArray.forEach((value) => {
+  for (const value of flattenedConfigDataValuesArray) {
     if (set.has(value)) {
+      console.log("errors, duplicate value");
       // checks that no two values are duplicate
-      console.error(
-        `ERROR. The value "${value}" is already assigned to an existing key.`
-      );
-      exitDueToFailure();
+      return {
+        ...successFalse,
+        errors: [
+          {
+            ...typeError,
+            message: `ERROR. The value "${value}" is already assigned to an existing key.`,
+          },
+        ],
+      };
     }
     set.add(value);
-  });
+  }
 
   // Also including the reversed flattened config data.
 
@@ -101,6 +138,7 @@ export const flattenConfigData = (
   );
 
   return {
+    ...successTrue,
     flattenedConfigData,
     reversedFlattenedConfigData,
   };

package/library/_commons/utilities/helpers.js

@@ -6,7 +6,25 @@
  */
 export const exitDueToFailure = () => process.exit(1);
 
-/* escapeRegex */
+/**
+ * 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.
+ */
+export const logError = (error) => {
+  switch (error.type) {
+    case "error":
+      console.error(error.message);
+      break;
+    case "warning":
+      console.warn(error.message);
+      break;
+    default:
+      console.error("ERROR. Error type unrecognized.");
+      break;
+  }
+};
+
+/* escapeRegex */ // comment-variables-resolve-config
 
 /**
  * Escapes all regex characters with a `"\"` in a string to prepare it for use in a regex.

package/library/_commons/utilities/resolve-config.js

@@ -1,5 +1,7 @@
-import { existsSync } from "fs";
-import { pathToFileURL } from "url";
+import fs from "fs";
+import url from "url";
+
+import { successFalse, typeError } from "../constants/bases.js";
 
 import { flattenConfigData } from "./flatten-config-data.js";
 
@@ -7,39 +9,64 @@ import { ConfigDataSchema, ConfigIgnoresSchema } from "../schemas/config.js";
 
 /**
  * Verifies, validates and resolves the config path to retrieve the config's data and ignores.
- * @param {string} configPath The path of the config, either from `comments.config.js` or from a config passed via the `--config` flag.
- * @returns The flattened config data, the reverse flattened config data, the verified config path, the raw passed ignores, and the original config.
+ * @param {string} configPath The path of the config from `comments.config.js`, or from a config passed via the `--config` flag in the CLI, or from one passed via `"commentVariables.config": true` in `.vscode/settings.json` for the VS Code Extension.
+ * @returns The flattened config data, the reverse flattened config data, the verified config path, the raw passed ignores, and the original config. Errors are returned during failures so they can be reused differently on the CLI and the VS Code Extension.
  */
 export async function resolveConfig(configPath) {
   // Step 1: Checks if config file exists
 
-  if (!existsSync(configPath)) {
-    console.warn("No config file found. Exiting gracefully.");
-    return null;
+  if (!fs.existsSync(configPath)) {
+    return {
+      ...successFalse,
+      errors: [
+        {
+          ...typeError,
+          message: "ERROR. No config file found.",
+        },
+      ],
+    };
   }
 
   // Step 2: Imports the config dynamically
 
-  const configModule = await import(pathToFileURL(configPath));
-  const config = configModule.default;
+  const configModule = /** @type {unknown} */ (
+    await import(url.pathToFileURL(configPath))
+  );
+  const config = /** @type {unknown} */ (configModule.default);
 
   // Step 3: Validates config object
 
   // validates config
   if (!config || typeof config !== "object" || Array.isArray(config)) {
-    console.warn(
-      "Invalid config format. The config should be an object. Exiting."
-    );
-    return null;
+    return {
+      ...successFalse,
+      errors: [
+        {
+          ...typeError,
+          message:
+            "ERROR. Invalid config format. The config should be an object.",
+        },
+      ],
+    };
   }
 
   // validates config.data
   const configDataResult = ConfigDataSchema.safeParse(config.data);
 
   if (!configDataResult.success) {
-    console.warn("Config data could not pass validation from zod.");
-    configDataResult.error.errors.map((e) => console.log(e.message));
-    return null;
+    return {
+      ...successFalse,
+      errors: [
+        {
+          ...typeError,
+          message: "ERROR. Config data could not pass validation from zod.",
+        },
+        ...configDataResult.error.errors.map((e) => ({
+          ...typeError,
+          message: e.message,
+        })),
+      ],
+    };
   }
 
   // validates config.ignores
@@ -48,9 +75,25 @@ export async function resolveConfig(configPath) {
   );
 
   if (!configIgnoresSchemaResult.success) {
-    console.warn("Config ignores could not pass validation from zod.");
-    configIgnoresSchemaResult.error.errors.map((e) => console.log(e.message));
-    return null;
+    return {
+      ...successFalse,
+      errors: [
+        {
+          ...typeError,
+          message: "ERROR. Config ignores could not pass validation from zod.",
+        },
+        ...configIgnoresSchemaResult.error.errors.map((e) => ({
+          ...typeError,
+          message: e.message,
+        })),
+      ],
+    };
+  }
+
+  const flattenedConfigDataResults = flattenConfigData(configDataResult.data);
+
+  if (!flattenedConfigDataResults.success) {
+    return flattenedConfigDataResults;
   }
 
   // sends back:
@@ -59,7 +102,7 @@ export async function resolveConfig(configPath) {
   // - the verified config path
   // - and the raw passed ignores
   return {
-    ...flattenConfigData(configDataResult.data), // finalized
+    ...flattenedConfigDataResults, // finalized
     configPath, // finalized
     passedIgnores: configIgnoresSchemaResult.data, // addressed with --lint-config-imports and --my-ignores-only to be finalized
     config, // and the config itself too

package/library/index.js

@@ -7,18 +7,18 @@ import {
   cwd,
   hasPackageJson,
   hasGitFolder,
-  defaultConfigFileName,
-  configFlag,
-  lintConfigImportsFlag,
-  myIgnoresOnlyFlag,
-  knownIgnores,
+  defaultConfigFileName, // shared
+  configFlag, // shared
+  lintConfigImportsFlag, // shared
+  myIgnoresOnlyFlag, // shared
+  knownIgnores, // shared
   resolveRuleName,
   compressRuleName,
 } from "./_commons/constants/bases.js";
 
-import { exitDueToFailure } from "./_commons/utilities/helpers.js";
-import { resolveConfig } from "./_commons/utilities/resolve-config.js";
-import { findAllImports } from "./_commons/utilities/find-all-imports.js";
+import { exitDueToFailure, logError } from "./_commons/utilities/helpers.js";
+import { resolveConfig } from "./_commons/utilities/resolve-config.js"; // shared
+import { findAllImports } from "./_commons/utilities/find-all-imports.js"; // own package
 import {
   resolveCommentsFlow,
   compressCommentsFlow,
@@ -61,8 +61,9 @@ const passedConfigPath =
 // defaults to comments.config.js if no --config flag is set
 const rawConfigPath = passedConfigPath ?? path.join(cwd, defaultConfigFileName);
 
-const results = await resolveConfig(rawConfigPath);
-if (!results) {
+const resolveConfigResults = await resolveConfig(rawConfigPath);
+if (!resolveConfigResults.success) {
+  resolveConfigResults.errors.forEach((e) => logError(e));
   exitDueToFailure();
 }
 
@@ -72,21 +73,36 @@ const {
   reversedFlattenedConfigData,
   configPath,
   passedIgnores,
-} = results;
+} = resolveConfigResults;
 
 skipDetails || console.log("Running with config:", config);
-skipDetails || console.log("Flattened config is:", flattenedConfigData);
+skipDetails || console.log("Flattened config data is:", flattenedConfigData);
 skipDetails ||
-  console.log("Reversed flattened config is:", reversedFlattenedConfigData);
+  console.log(
+    "Reversed flattened config data is:",
+    reversedFlattenedConfigData
+  );
 skipDetails || console.log("Config path is:", configPath);
 skipDetails || console.log("Passed ignores are:", passedIgnores);
 
 // ADDRESSES THE --lint-config-imports FLAG, GIVEN THAT THE FILES IMPORTED BY THE CONFIG ARE IGNORED BY DEFAULT.
 
 const lintConfigImports = commands.indexOf(lintConfigImportsFlag) >= 2;
-const rawConfigPathIgnores = lintConfigImports
-  ? [configPath]
-  : [...(findAllImports(configPath) ?? [])];
+let rawConfigPathIgnores = [configPath];
+
+if (!lintConfigImports) {
+  const findAllImportsResults = findAllImports(configPath);
+  if (!findAllImportsResults.success) {
+    findAllImportsResults.errors.forEach((e) => logError(e));
+    console.warn(
+      "Defaulting to --lint-config-imports flag behavior, not ignoring config path imports, only the config path itself."
+    );
+  } else {
+    rawConfigPathIgnores = [...findAllImportsResults.visitedSet] ?? [
+      configPath,
+    ];
+  }
+}
 
 // the ignore paths must be relative
 const configPathIgnores = rawConfigPathIgnores.map((e) =>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
     "jscomments": "./library/index.js",
@@ -27,8 +27,8 @@
   "dependencies": {
     "@eslint/markdown": "^6.5.0",
     "eslint": "^9.29.0",
-    "get-sourcecode-from-file-path": "^1.0.1",
-    "resolve-importing-path": "^1.0.2",
+    "get-sourcecode-from-file-path": "^1.1.2",
+    "resolve-importing-path": "^1.0.3",
     "tsconfig-paths": "^4.2.0",
     "typescript-eslint": "^8.34.1",
     "zod": "^3.25.67"