comment-variables 0.2.0 → 0.3.0

package/comments.config.js

@@ -1,4 +1,4 @@
-const config = {
+const data = {
   // for testing
   levelOne: {
     levelTwo: {
@@ -18,16 +18,86 @@ const config = {
     },
   },
   // for deving
-  jsDoc: {
-    exitDueToFailure: "Terminates the whole process with a 'failure' code (1).",
-  },
+  jsDoc: Object.freeze({
+    definitions: Object.freeze({
+      exitDueToFailure:
+        "Terminates the whole process with a 'failure' code (1).",
+      escapeRegex: `Escapes all regex characters with a \`"\\"\` in a string to prepare it for use in a regex.`,
+      makeRuleResolve:
+        "The utility that creates the resolve rule based on the flattened config data, used to transform $COMMENT#* placeholders into actual comments.",
+      makeRuleCompress:
+        "The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into $COMMENT#* placeholders.",
+      coreCommentsFlow:
+        "The core flow at the heart of resolving and compressing comments.",
+      resolveCommentsFlow:
+        "The flow that resolves $COMMENT#* placeholders intro actual comments.",
+      compressCommentsFlow:
+        "The flow that compresses actual comments into $COMMENT#* placeholders.",
+      findAllImports:
+        "Finds all import paths recursively related to a given file path.",
+      processImport: "Processes recursively and resolves a single import path.",
+      flattenConfigData:
+        "Flattens the config's data property into a one-dimensional object of $COMMENT-*-like keys and string values.",
+      resolveConfig:
+        "Verifies, validates and resolves the config path to retrieve the config's data and ignores.",
+    }),
+    params: Object.freeze({
+      string: "The string.",
+      flattenedConfigData:
+        "The flattened config data, with $COMMENT#* placeholders as keys and actual comments as values.",
+      reversedFlattenedConfigData:
+        "The reversed flattened config data, with actual comments as keys and $COMMENT#* placeholders as values.",
+      ruleName:
+        'The name of the rule currently used. (Either `"resolve"` or `"compress"`.)',
+      ignores:
+        "The array of paths and globs for the flow's ESLint instance to ignore.",
+      eitherFlattenedConfigData:
+        "Either the flattened config data or the reversed flattened config data, since they share the same structure.",
+      filePath:
+        "The absolute path of the file whose imports are being recursively found, such as that of a project's `comments.config.js` file.",
+      cwd: "The current working directory, set as `process.cwd()` by default.",
+      visitedSet:
+        "The set of strings tracking the import paths that have already been visited, instantiated as a `new Set()` by default.",
+      depth:
+        "The current depth of the recursion, instantiated at `0` by default.",
+      maxDepth:
+        "The maximum depth allowed for the recursion, instantiated at `100` by default.",
+      importPath: "The import path currently being addressed.",
+      currentDir:
+        "The directory containing the import path currently being addressed.",
+      configData:
+        "The config's data property. (Values are typed `any` given the limitations in typing recursive values in JSDoc.)",
+      configDataMap:
+        "The map housing the flattened keys with their values and sources through recursion, instantiated as a `new Map()`.",
+      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.",
+      configPath:
+        "The path of the config, either from `comments.config.js` or from a config passed via the `--config` flag.",
+    }),
+    returns: Object.freeze({
+      exitDueToFailure:
+        "Never. (Somehow typing needs to be explicit for unreachable code inference.)",
+      escapeRegex: `The string with regex characters escaped.`,
+      makeRuleResolve: "The resolve rule based on the flattened config data.",
+      makeRuleCompress:
+        "The compress rule based on the reversed flattened config data.",
+      findAllImports:
+        "The complete set of strings of import paths recursively related to the given file path, or `null` if an issue has arisen.",
+      processImport:
+        "`true` to skip unresolved paths, `false` if resolution fails at any level.",
+      flattenConfigData:
+        "Both the flattened config data and its reversed version to ensure the strict reversibility of the `resolve` and `compress` commands.",
+      resolveConfig:
+        "The flattened config data, the reverse flattened config data, the verified config path and the raw passed ignores.",
+    }),
+  }),
 };
 
-// export default config;
+const ignores = ["chocolat.js"];
 
-const trueConfig = {
-  data: config,
-  ignores: ["chocolat.js"],
+const config = {
+  data,
+  ignores,
 };
 
-export default trueConfig;
+export default config;

package/library/_commons/constants/rules.js

@@ -0,0 +1,9 @@
+import { resolveRuleName, compressRuleName } from "../constants/bases.js";
+
+import makeResolveRule from "../rules/resolve.js";
+import makeCompressRule from "../rules/compress.js";
+
+export const ruleNames_makeRules = Object.freeze({
+  [resolveRuleName]: makeResolveRule,
+  [compressRuleName]: makeCompressRule,
+});

package/library/_commons/rules/compress.js

@@ -3,17 +3,17 @@ import { placeholderMessageId } from "../constants/bases.js";
 import { escapeRegex } from "..//utilities/helpers.js";
 
 /**
- *
- * @param {{[key: string]: string}} reversedFlattenedConfig
- * @returns
+ * 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.
+ * @returns The compress rule based on the reversed flattened config data.
  */
-const makeRule = (reversedFlattenedConfig) => {
+const makeRule = (reversedFlattenedConfigData) => {
   // Turns the whole reversedFlattenedConfig from an object to an array of key-value arrays sorted by the descending length of each key to prevent partial replacements.
-  const sortedReversedFlattenedConfig = Object.entries(
-    reversedFlattenedConfig
+  const sortedReversedFlattenedConfigData = Object.entries(
+    reversedFlattenedConfigData
   ).sort(([a], [b]) => b.length - a.length);
 
-  /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<string, []>} */
+  /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */
   const rule = {
     meta: {
       type: "suggestion",
@@ -28,7 +28,7 @@ const makeRule = (reversedFlattenedConfig) => {
       fixable: "code",
       schema: [],
     },
-    create(context) {
+    create: (context) => {
       const sourceCode = context.sourceCode;
       const comments = sourceCode
         .getAllComments()
@@ -41,7 +41,7 @@ const makeRule = (reversedFlattenedConfig) => {
         for (const [
           resolvedValue,
           commentKey,
-        ] of sortedReversedFlattenedConfig) {
+        ] of sortedReversedFlattenedConfigData) {
           const pattern = new RegExp(
             `(?<=\\s|^)${escapeRegex(resolvedValue)}(?=\\s|$)`,
             "g"

package/library/_commons/rules/resolve.js

@@ -4,12 +4,12 @@ import {
 } from "../constants/bases.js";
 
 /**
- *
- * @param {{[key: string]: string}} flattenedConfig
- * @returns
+ * 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.
+ * @returns The resolve rule based on the flattened config data.
  */
-const makeRule = (flattenedConfig) => {
-  /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<string, []>} */
+const makeRule = (flattenedConfigData) => {
+  /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */
   const rule = {
     meta: {
       type: "suggestion",
@@ -43,7 +43,7 @@ const makeRule = (flattenedConfig) => {
         for (const match of matches) {
           const fullMatch = match[0]; // e.g. $COMMENT#LEVELONE#LEVELTWO
           const key = match[1]; // e.g. LEVELONE#LEVELTWO
-          const replacement = flattenedConfig[key];
+          const replacement = flattenedConfigData[key];
 
           if (replacement) {
             fixedText = fixedText.replace(fullMatch, replacement);

package/library/_commons/schemas/config.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+import { configKeyRegex } from "../constants/bases.js";
+
+export const ConfigDataSchema = z
+  .lazy(() =>
+    z.record(
+      z.any().superRefine((val, ctx) => {
+        if (typeof val === "string") {
+          return;
+        }
+
+        if (typeof val === "object" && val && !Array.isArray(val)) {
+          const parsed = ConfigDataSchema.safeParse(val);
+          if (!parsed.success) {
+            for (const issue of parsed.error.issues) {
+              ctx.addIssue({
+                ...issue,
+                path: [...ctx.path, ...issue.path],
+              });
+            }
+          }
+          return;
+        }
+
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Value \`${val}\` of type "${typeof val}" should be a string or a nested object.`,
+          path: ctx.path,
+        });
+      })
+    )
+  )
+  .superRefine((obj, ctx) => {
+    for (const key of Object.keys(obj)) {
+      if (key.includes("$")) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Key "${key}" should not include the "$" character.`,
+          path: [key],
+        });
+      }
+      if (key.includes("#")) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Key "${key}" should not include the "#" character.`,
+          path: [key],
+        });
+      }
+      if (!configKeyRegex.test(key)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Key "${key}" should only include whitespaces (s), lowercase letters (Ll), uppercase letters (Lu), other letters (Lo), numbers (N), dash punctuation (Pd), and connector punctuation (Pc).`,
+          path: [key],
+        });
+      }
+    }
+  });
+
+export const ConfigIgnoresSchema = z.array(
+  z.string({
+    message: `The config's "ignores" key array should be made of string or be empty.`,
+  }),
+  {
+    message: `The config's "ignores" key value should be an array of strings (or at the very least an empty array).`,
+  }
+);

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

@@ -7,50 +7,68 @@ import { getSourceCodeFromFilePath } from "get-sourcecode-from-file-path";
 /* findAllImports */
 
 /**
- * Helper to process and recursively resolve a single import path.
- * Returns false if resolution fails at any level.
+ * Processes recursively and resolves a single import path.
+ * @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.
  */
 const processImport = (
   importPath,
   currentDir,
   cwd,
-  visited,
+  visitedSet,
   depth,
   maxDepth
 ) => {
   const resolvedPath = resolveImportingPath(currentDir, importPath, cwd);
-  if (!resolvedPath) return true; // Skips unresolved paths (not an error).
+  if (!resolvedPath) return true;
 
   const result = findAllImports(
     resolvedPath,
     cwd,
-    visited,
+    visitedSet,
     depth + 1,
     maxDepth
   );
   return result !== null; // Returns false if child failed.
 };
 
+/**
+ * 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.
+ */
 export const findAllImports = (
   filePath,
   cwd = process.cwd(),
-  visited = new Set(),
+  visitedSet = new Set(),
   depth = 0,
   maxDepth = 100
 ) => {
-  // Early failure checks (with logging).
+  // Fails early if max depth is recursively reached.
   if (depth > maxDepth) {
     console.error(`ERROR. Max depth ${maxDepth} reached at ${filePath}.`);
     return null;
   }
+  // Fails early if no file is found.
   if (!fs.existsSync(filePath)) {
     console.error(`ERROR. File not found at ${filePath}.`);
     return null;
   }
-  if (visited.has(filePath)) return visited;
 
-  // Parses AST.
-  visited.add(filePath);
+  // Updates the visited set.
+  if (visitedSet.has(filePath)) return visitedSet;
+  visitedSet.add(filePath);
+
+  // Parses the file's source code AST.
   const sourceCode = getSourceCodeFromFilePath(filePath);
   if (!sourceCode?.ast) {
     console.error(`ERROR. Failed to parse AST for ${filePath}.`);
@@ -67,7 +85,7 @@ export const findAllImports = (
           node.source.value,
           currentDir,
           cwd,
-          visited,
+          visitedSet,
           depth,
           maxDepth
         )
@@ -88,7 +106,7 @@ export const findAllImports = (
           node.expression.arguments[0].value,
           currentDir,
           cwd,
-          visited,
+          visitedSet,
           depth,
           maxDepth
         )
@@ -98,5 +116,5 @@ export const findAllImports = (
     }
   }
 
-  return visited; // success
+  return visitedSet; // success
 };

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

@@ -0,0 +1,107 @@
+import { flattenedConfigKeyRegex } from "../constants/bases.js";
+
+import { exitDueToFailure } from "../utilities/helpers.js";
+
+/**
+ * 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.
+ */
+export const flattenConfigData = (
+  configData,
+  configDataMap = new Map(),
+  parentKeys = []
+) => {
+  for (const [key, value] of Object.entries(configData)) {
+    const newKeys = [...parentKeys, key];
+    const normalizedKey = newKeys
+      .map((k) => k.toUpperCase())
+      .join("#")
+      .replace(/\s/g, "_");
+    const source = newKeys.join(" > ");
+
+    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();
+      }
+
+      configDataMap.set(normalizedKey, {
+        value,
+        source,
+      });
+    } else if (typeof value === "object" && value && !Array.isArray(value)) {
+      /** @type {Record<string, any>} */
+      const typedValue = value;
+
+      flattenConfigData(typedValue, configDataMap, newKeys);
+    }
+  }
+
+  // At this point we're out of the recursion, and we can start working with the complete data.
+
+  // strips metadata
+  /**@type {Map<string, string>} */
+  const map = new Map();
+  configDataMap.forEach((value, key) => {
+    map.set(key, value.value);
+  });
+
+  // makes the flattened config data object
+  const flattenedConfigData = Object.fromEntries(map);
+
+  // The integrity of the flattened config data needs to be established before working with it safely.
+
+  const flattenedConfigDataKeysSet = new Set(Object.keys(flattenedConfigData));
+
+  const flattenedConfigDataValuesArray = Object.values(flattenedConfigData);
+  const flattenedConfigDataValuesSet = new Set(flattenedConfigDataValuesArray);
+
+  flattenedConfigDataKeysSet.forEach((key) => {
+    // checks the reversability of flattenedConfigData
+    if (flattenedConfigDataValuesSet.has(key)) {
+      console.error(
+        `ERROR. The key "${key}" is and shouldn't be among the values of flattenedConfigData.`
+      );
+      exitDueToFailure();
+    }
+    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();
+    }
+  });
+
+  /** @type {Set<string>} */
+  const set = new Set();
+
+  flattenedConfigDataValuesArray.forEach((value) => {
+    if (set.has(value)) {
+      // checks that no two values are duplicate
+      console.error(
+        `ERROR. The value "${value}" is already assigned to an existing key.`
+      );
+      exitDueToFailure();
+    }
+    set.add(value);
+  });
+
+  // Also including the reversed flattened config data.
+
+  const reversedFlattenedConfigData = Object.fromEntries(
+    Object.entries(flattenedConfigData).map(([key, value]) => [value, key])
+  );
+
+  return {
+    flattenedConfigData,
+    reversedFlattenedConfigData,
+  };
+};

package/library/_commons/utilities/flows.js

@@ -10,16 +10,17 @@ import {
   allMDVirtualJSTSFileGlobs,
   typeScriptAndJSXCompatible,
 } from "../constants/bases.js";
+import { ruleNames_makeRules } from "../constants/rules.js";
 
-import makeResolveRule from "../rules/resolve.js";
-import makeCompressRule from "../rules/compress.js";
+/* coreCommentsFlow */
 
-const coreCommentsFlow = async (
-  ruleName,
-  ignores,
-  makeCommentsRule,
-  flattenedConfigData
-) => {
+/**
+ * The core flow at the heart of resolving and compressing comments.
+ * @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.
+ */
+const coreCommentsFlow = async (ruleName, ignores, flattenedConfigData) => {
   const eslint = new ESLint({
     fix: true,
     errorOnUnmatchedPattern: false,
@@ -32,12 +33,12 @@ const coreCommentsFlow = async (
         plugins: {
           [commentVariablesPluginName]: {
             rules: {
-              [ruleName]: makeCommentsRule(flattenedConfigData),
+              [ruleName]: ruleNames_makeRules[ruleName](flattenedConfigData),
             },
           },
         },
         rules: {
-          [`${commentVariablesPluginName}/${ruleName}`]: "warn", // doesn't block builds, just applies fix
+          [`${commentVariablesPluginName}/${ruleName}`]: "warn",
         },
       },
       {
@@ -78,25 +79,32 @@ const coreCommentsFlow = async (
   }, 0);
 
   console.log(
-    `✅ ${resolvedOrCompressed} ${total} comment${total === 1 ? "" : "s"}.`
+    `✅ ${resolvedOrCompressed} comments on ${total} file${
+      total === 1 ? "" : "s"
+    }.`
   );
 };
 
+/* resolveCommentsFlow */
+
+/**
+ * The flow that resolves $COMMENT#* placeholders intro actual comments.
+ * @param {string[]} ignores The array of paths and globs for the flow's ESLint instance to ignore.
+ * @param {{[key: string]: string}} flattenedConfigData The flattened config data, with $COMMENT#* placeholders as keys and actual comments as values.
+ * @returns
+ */
 export const resolveCommentsFlow = async (ignores, flattenedConfigData) =>
-  coreCommentsFlow(
-    resolveRuleName,
-    ignores,
-    makeResolveRule,
-    flattenedConfigData
-  );
+  coreCommentsFlow(resolveRuleName, ignores, flattenedConfigData);
+
+/* compressCommentsFlow */
 
+/**
+ * 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.
+ * @returns
+ */
 export const compressCommentsFlow = async (
   ignores,
   reversedFlattenedConfigData
-) =>
-  coreCommentsFlow(
-    compressRuleName,
-    ignores,
-    makeCompressRule,
-    reversedFlattenedConfigData
-  );
+) => coreCommentsFlow(compressRuleName, ignores, reversedFlattenedConfigData);

package/library/_commons/utilities/helpers.js

@@ -2,12 +2,14 @@
 
 /**
  * Terminates the whole process with a 'failure' code (1).
- * @returns Never.
+ * @returns {never} Never. (Somehow typing needs to be explicit for unreachable code inference.)
  */
 export const exitDueToFailure = () => process.exit(1);
 
+/* escapeRegex */
+
 /**
- * Escapes all regex characters with a `"\"` in a string to prepare it for use in a regex
+ * Escapes all regex characters with a `"\"` in a string to prepare it for use in a regex.
  * @param {string} string The string.
  * @returns The string with regex characters escaped.
  */

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

@@ -0,0 +1,67 @@
+import { existsSync } from "fs";
+import { pathToFileURL } from "url";
+
+import { flattenConfigData } from "./flatten-config-data.js";
+
+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 and the raw passed ignores.
+ */
+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;
+  }
+
+  // Step 2: Imports the config dynamically
+
+  const configModule = await import(pathToFileURL(configPath));
+  const config = 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;
+  }
+
+  // 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;
+  }
+
+  // validates config.ignores
+  const configIgnoresSchemaResult = ConfigIgnoresSchema.safeParse(
+    config.ignores
+  );
+
+  if (!configIgnoresSchemaResult.success) {
+    console.warn("Config ignores could not pass validation from zod.");
+    configIgnoresSchemaResult.error.errors.map((e) => console.log(e.message));
+    return null;
+  }
+
+  // sends back:
+  // - the flattened config data,
+  // - the reverse flattened config data,
+  // - the verified config path
+  // - and the raw passed ignores
+  console.log("Running with config:", config);
+  return {
+    ...flattenConfigData(configDataResult.data), // finalized
+    configPath, // finalized
+    passedIgnores: configIgnoresSchemaResult.data, // addressed with --lint-config-imports and --my-ignores-only to be finalized
+  };
+}

package/library/index.js

@@ -15,7 +15,7 @@ import {
 } from "./_commons/constants/bases.js";
 
 import { exitDueToFailure } from "./_commons/utilities/helpers.js";
-import { runWithConfig } from "./_commons/utilities/run-with-config.js";
+import { resolveConfig } from "./_commons/utilities/resolve-config.js";
 import { findAllImports } from "./_commons/utilities/find-all-imports.js";
 
 import {
@@ -56,8 +56,10 @@ const passedConfigPath =
 // defaults to comments.config.js if no --config flag is set
 const rawConfigPath = passedConfigPath ?? path.join(cwd, defaultConfigFileName);
 
-const results = await runWithConfig(rawConfigPath);
-if (!results) exitDueToFailure();
+const results = await resolveConfig(rawConfigPath);
+if (!results) {
+  exitDueToFailure();
+}
 
 const {
   flattenedConfigData,
@@ -71,26 +73,12 @@ console.log("Reversed flattened config is:", reversedFlattenedConfigData);
 console.log("Config path is:", configPath);
 console.log("Passed ignores are:", passedIgnores);
 
-// VALIDATES THE REVERSABILITY OF THE CONCEIVED flattenedConfigData
-
-const keys = new Set([...Object.keys(flattenedConfigData)]);
-const values = new Set([...Object.values(flattenedConfigData)]);
-
-keys.forEach((key) => {
-  if (values.has(key)) {
-    console.error(
-      `The key "${key}" is and shouldn't be among the values of flattenedConfigData.`
-    );
-    exitDueToFailure();
-  }
-});
-
 // 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)];
+  : [...(findAllImports(configPath) ?? [])];
 
 // the ignore paths must be relative
 const configPathIgnores = rawConfigPathIgnores.map((e) =>
@@ -124,8 +112,8 @@ switch (coreCommand) {
   case undefined: // falls through the default
   default:
     if (coreCommand && !coreCommand.startsWith("--"))
-      console.log(
-        `Core command not recognized. Choose between "resolve" and "compress".`
+      console.error(
+        `ERROR. Core command not recognized. Choose between "resolve" and "compress".`
       );
     else
       console.log(
@@ -137,8 +125,3 @@ switch (coreCommand) {
       );
     break;
 }
-
-/* Notes
-I'm going to have to redo this, but for now I just want to vibe code it in order to see how it is possible to make this. 
-Edit: Code vibing, not vibe coding. That's what I did here.
-*/

package/package.json

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

package/library/_commons/utilities/run-with-config.js

@@ -1,177 +0,0 @@
-import { existsSync } from "fs";
-import { pathToFileURL } from "url";
-
-import { z } from "zod";
-
-import { configKeyRegex } from "../constants/bases.js";
-
-function flattenConfigData(
-  configData,
-  normalizedPath = "",
-  map = {},
-  pathStack = [],
-  reversedFlattenedConfigData = {}
-) {
-  for (const [key, value] of Object.entries(configData)) {
-    const currentPath = [...pathStack, key];
-    normalizedPath = currentPath
-      .map((k) => k.toUpperCase())
-      .join("#")
-      .replace(/\s/g, "_"); // whitespaces are replaced by underscores
-
-    if (typeof value === "string") {
-      if (map[normalizedPath]) {
-        // checks that no two keys are duplicate
-        throw new Error(
-          `Duplicate normalized key detected: "${normalizedPath}".\nConflict between:\n  - ${
-            map[normalizedPath].__source
-          }\n  - ${currentPath.join(" > ")}`
-        );
-      }
-      map[normalizedPath] = {
-        value,
-        __source: currentPath.join(" > "), // for debugging
-      };
-    } else if (typeof value === "object") {
-      flattenConfigData(value, normalizedPath, map, currentPath);
-    }
-  }
-
-  const flattenedConfigData = Object.fromEntries(
-    Object.entries(map).map(([k, v]) => [k, v.value])
-  ); // strip metadata
-
-  const set = new Set();
-
-  // the integrity of the config needs to be established before working with it
-  for (const value of Object.values(flattenedConfigData)) {
-    if (set.has(value)) {
-      // checks that no two values are duplicate
-      throw new Error(
-        `Value "${value}" is already assigned to an existing key.`
-      );
-    }
-    set.add(value);
-  }
-
-  for (const [key, value] of Object.entries(flattenedConfigData)) {
-    reversedFlattenedConfigData[value] = key;
-  }
-
-  return {
-    flattenedConfigData,
-    reversedFlattenedConfigData,
-  };
-}
-
-export async function runWithConfig(configPath) {
-  // Step 1: Check if config file exists
-  if (!existsSync(configPath)) {
-    console.warn("No config file found. Exiting gracefully.");
-    return null;
-  }
-
-  // Step 2: Import the config dynamically
-  const configModule = await import(pathToFileURL(configPath));
-  const config = configModule.default;
-
-  // Step 3: Validate config object
-  if (!config || typeof config !== "object" || Array.isArray(config)) {
-    console.warn(
-      "Invalid config format. The config should be an object. Exiting."
-    );
-    return null;
-  }
-
-  // data
-
-  const RecursiveObject = z
-    .lazy(() =>
-      z.record(
-        z.any().superRefine((val, ctx) => {
-          if (typeof val === "string") {
-            return;
-          }
-
-          if (typeof val === "object" && val !== null && !Array.isArray(val)) {
-            const parsed = RecursiveObject.safeParse(val);
-            if (!parsed.success) {
-              for (const issue of parsed.error.issues) {
-                ctx.addIssue({
-                  ...issue,
-                  path: [...ctx.path, ...issue.path], // proper path propagation
-                });
-              }
-            }
-            return;
-          }
-
-          ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: `Value \`${val}\` of type "${typeof val}" should be a string or a nested object.`,
-            path: ctx.path,
-          });
-        })
-      )
-    )
-    .superRefine((obj, ctx) => {
-      for (const key of Object.keys(obj)) {
-        if (key.includes("$")) {
-          ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: `Key "${key}" should not include the "$" character.`,
-            path: [key],
-          });
-        }
-        if (key.includes("#")) {
-          ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: `Key "${key}" should not include the "#" character.`,
-            path: [key],
-          });
-        }
-        if (!configKeyRegex.test(key)) {
-          ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: `Key "${key}" should only include whitespaces (s), lowercase letters (Ll), uppercase letters (Lu), other letters (Lo), numbers (N), dash punctuation (Pd), and connector punctuation (Pc).`,
-            path: [key],
-          });
-        }
-      }
-    });
-
-  const recursiveObjectResult = RecursiveObject.safeParse(config.data);
-
-  if (!recursiveObjectResult.success) {
-    console.warn("Config data could not pass validation from zod.");
-    recursiveObjectResult.error.errors.map((e) => console.log(e.message));
-    return null;
-  }
-
-  // ignores
-
-  const StringArraySchema = z.array(
-    z.string({
-      message: `The config's "ignores" key array should be made of string or be empty.`,
-    }),
-    {
-      message: `The config's "ignores" key value should be an array of strings (or at the very least an empty array).`,
-    }
-  );
-
-  const stringArraySchemaResult = StringArraySchema.safeParse(config.ignores);
-
-  if (!stringArraySchemaResult.success) {
-    console.warn("Config ignores could not pass validation from zod.");
-    stringArraySchemaResult.error.errors.map((e) => console.log(e.message));
-    return null;
-  }
-
-  // Step 4: Do your thing
-  console.log("Running with config:", config);
-  return {
-    ...flattenConfigData(config.data), // finalized
-    configPath, // finalized
-    passedIgnores: config.ignores, // could be treated here eventually
-  };
-}