comment-variables 0.6.0 → 0.6.2

package/README.md

@@ -80,13 +80,12 @@ const data = {
         "The flow that resolves $COMMENT#* placeholders intro actual comments.", // $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW
       compressCommentsFlow:
         "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
       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
@@ -100,26 +99,17 @@ const data = {
         "The array of paths and globs for the flow's ESLint instance to ignore.", // $COMMENT#JSDOC#PARAMS#IGNORES
       eitherFlattenedConfigData:
         "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
-      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
       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:
@@ -128,14 +118,10 @@ const data = {
       makeRuleResolve: "The resolve rule based on the flattened config data.", // $COMMENT#JSDOC#RETURNS#MAKERULERESOLVE
       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
-      processImport:
-        "`true` to skip unresolved paths, `false` if resolution fails at any level.", // $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/comments.config.js

@@ -29,10 +29,6 @@ const data = {
         "The flow that resolves $COMMENT#* placeholders intro actual comments.", // $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW
       compressCommentsFlow:
         "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. (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:
@@ -52,24 +48,6 @@ const data = {
         "The array of paths and globs for the flow's ESLint instance to ignore.", // $COMMENT#JSDOC#PARAMS#IGNORES
       eitherFlattenedConfigData:
         "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
-      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
-      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 `unknown` given the limitations in typing recursive values in JSDoc.)", // $COMMENT#JSDOC#PARAMS#CONFIGDATA
       configDataMapOption:
@@ -89,10 +67,6 @@ const data = {
       makeRuleResolve: "The resolve rule based on the flattened config data.", // $COMMENT#JSDOC#RETURNS#MAKERULERESOLVE
       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 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 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 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:

package/library/index.js

@@ -18,7 +18,7 @@ import {
 
 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 { findAllImports } from "find-all-js-imports"; // own package
 import {
   resolveCommentsFlow,
   compressCommentsFlow,

package/package.json

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

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

@@ -1,163 +0,0 @@
-import fs from "fs";
-import path from "path";
-
-import { resolveImportingPath } from "resolve-importing-path";
-import { getSourceCodeFromFilePath } from "get-sourcecode-from-file-path";
-
-import { successFalse, successTrue, typeWarning } from "../constants/bases.js";
-
-/**
- * @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 {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 }
-) => {
-  // Resolves the provided import path.
-  const resolvedPath = resolveImportingPath(currentDir, importPath, cwd);
-  // Returns true early to skip processing on unresolved paths.
-  if (!resolvedPath) return { ...successTrue, visitedSet };
-
-  // Establishes the options for the next round of findAllImports.
-  const findAllImportsOptions = {
-    cwd,
-    visitedSet,
-    depth: depth + 1,
-    maxDepth,
-  };
-
-  // Runs findAllImports on the imported path resolved, thus recursively.
-  const findAllImportsResults = /** @type {FindAllImportsResults} */ (
-    findAllImports(resolvedPath, findAllImportsOptions)
-  );
-  // 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 {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,
-  } = {}
-) => {
-  // Fails early if max depth is recursively reached.
-  if (depth > maxDepth) {
-    return {
-      ...successFalse,
-      errors: [
-        {
-          ...typeWarning,
-          message: `WARNING. Max depth ${maxDepth} reached at ${filePath}.`,
-        },
-      ],
-    };
-  }
-  // Fails early if no file is found.
-  if (!fs.existsSync(filePath)) {
-    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.
-  visitedSet.add(filePath);
-
-  // Parses the file's source code AST.
-  const sourceCode = getSourceCodeFromFilePath(filePath);
-  // Fails early there is no AST.
-  if (!sourceCode?.ast) {
-    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.
-  for (const node of sourceCode.ast.body) {
-    // ES Modules (import x from 'y')
-    if (node.type === "ImportDeclaration") {
-      const processImportResults = processImport(
-        node.source.value,
-        processImportSettings
-      );
-      if (!processImportResults) {
-        return processImportResults;
-      }
-    }
-
-    // CommonJS (require('x'))
-    if (
-      node.type === "ExpressionStatement" &&
-      node.expression.type === "CallExpression" &&
-      node.expression.callee.name === "require" &&
-      node.expression.arguments[0]?.type === "Literal"
-    ) {
-      const processImportResults = processImport(
-        node.expression.arguments[0].value,
-        processImportSettings
-      );
-      if (!processImportResults) {
-        return processImportResults;
-      }
-    }
-  }
-
-  return { ...successTrue, visitedSet };
-};