comment-variables 0.1.0 → 0.3.0

package/library/_commons/utilities/flows.js

@@ -0,0 +1,110 @@
+import { ESLint } from "eslint";
+import markdown from "@eslint/markdown";
+
+import {
+  commentVariablesPluginName,
+  resolveRuleName,
+  compressRuleName,
+  allJSTSFileGlobs,
+  allMDFileGlobs,
+  allMDVirtualJSTSFileGlobs,
+  typeScriptAndJSXCompatible,
+} from "../constants/bases.js";
+import { ruleNames_makeRules } from "../constants/rules.js";
+
+/* coreCommentsFlow */
+
+/**
+ * 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,
+    overrideConfigFile: true,
+    overrideConfig: [
+      {
+        files: allJSTSFileGlobs,
+        ignores,
+        languageOptions: typeScriptAndJSXCompatible,
+        plugins: {
+          [commentVariablesPluginName]: {
+            rules: {
+              [ruleName]: ruleNames_makeRules[ruleName](flattenedConfigData),
+            },
+          },
+        },
+        rules: {
+          [`${commentVariablesPluginName}/${ruleName}`]: "warn",
+        },
+      },
+      {
+        files: allMDFileGlobs,
+        ignores,
+        plugins: { markdown },
+        processor: "markdown/markdown",
+      },
+      {
+        files: allMDVirtualJSTSFileGlobs,
+        ignores,
+        languageOptions: typeScriptAndJSXCompatible,
+        rules: {
+          [`${commentVariablesPluginName}/${ruleName}`]: "warn",
+        },
+      },
+    ],
+  });
+
+  const results = await eslint.lintFiles([
+    ...allJSTSFileGlobs,
+    ...allMDFileGlobs,
+  ]);
+  await ESLint.outputFixes(results);
+
+  console.log({ results });
+
+  const resolvedOrCompressed =
+    ruleName === resolveRuleName
+      ? "Resolved"
+      : ruleName === compressRuleName
+      ? "Compressed"
+      : "Unknown rule name'd";
+
+  const total = results.reduce((sum, r) => {
+    const add = r.output ? 1 : 0;
+    return sum + add;
+  }, 0);
+
+  console.log(
+    `✅ ${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, 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, reversedFlattenedConfigData);

package/library/_commons/utilities/helpers.js

@@ -0,0 +1,17 @@
+/* exitDueToFailure */
+
+/**
+ * Terminates the whole process with a 'failure' code (1).
+ * @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.
+ * @param {string} string The string.
+ * @returns The string with regex characters escaped.
+ */
+export const escapeRegex = (string) =>
+  string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

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

@@ -0,0 +1,127 @@
+#!/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.
+
+import path from "path";
+
+import {
+  cwd,
+  hasPackageJson,
+  hasGitFolder,
+  defaultConfigFileName,
+  configFlag,
+  lintConfigImportsFlag,
+  myIgnoresOnlyFlag,
+  knownIgnores,
+} 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 {
+  resolveCommentsFlow,
+  compressCommentsFlow,
+} from "./_commons/utilities/flows.js";
+
+// ENSURES THE CLI TOOL ONLY RUN IN FOLDERS THAT POSSESS A package.json FILE AND A .git FOLDER.
+
+if (!hasPackageJson) {
+  console.error(
+    "ERROR. No package.json file found in this directory. Aborting to prevent accidental changes."
+  );
+  exitDueToFailure();
+}
+if (!hasGitFolder) {
+  console.error(
+    "ERROR. No git folder found in this directory. Aborting to prevent irreversible changes."
+  );
+  exitDueToFailure();
+}
+
+// GATHERS COMMANDS.
+
+const commands = process.argv;
+
+// OBTAINS THE VALIDATED FLATTENED CONFIG, REVERSE FLATTENED CONFIG, AND CONFIG PATH.
+
+// extracts the position of the --config flag
+const configFlagIndex = commands.indexOf(configFlag);
+// determines if there's a valid config flag input
+const hasConfigFlag = configFlagIndex >= 2;
+// determines if there's an actual config path passed to the config flag
+const passedConfig = commands[configFlagIndex + 1];
+// gets the absolute passed config path if the --config flag is set
+const passedConfigPath =
+  hasConfigFlag && passedConfig ? path.join(cwd, passedConfig) : null;
+// 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) {
+  exitDueToFailure();
+}
+
+const {
+  flattenedConfigData,
+  reversedFlattenedConfigData,
+  configPath,
+  passedIgnores,
+} = results;
+
+console.log("Flattened config is:", flattenedConfigData);
+console.log("Reversed flattened config is:", reversedFlattenedConfigData);
+console.log("Config path is:", configPath);
+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) ?? [])];
+
+// the ignore paths must be relative
+const configPathIgnores = rawConfigPathIgnores.map((e) =>
+  path.relative(cwd, e)
+);
+
+console.log(
+  lintConfigImports ? "Config path ignore is:" : "Config path ignores are:",
+  configPathIgnores
+);
+
+// ADDRESSES THE --my-ignores-only FLAG, GIVEN THAT KNOWN IGNORES ARE IGNORED BY DEFAULT
+
+const myIgnoresOnly = commands.indexOf(myIgnoresOnlyFlag) >= 2;
+const rawIgnores = [...configPathIgnores, ...passedIgnores];
+const ignores = myIgnoresOnly ? rawIgnores : [...rawIgnores, ...knownIgnores];
+
+console.log("Ignores are:", ignores);
+
+// ADDRESSES THE CORE COMMANDS "resolve" AND "compress".
+
+const coreCommand = commands[2];
+
+switch (coreCommand) {
+  case "resolve":
+    await resolveCommentsFlow(ignores, flattenedConfigData);
+    break;
+  case "compress":
+    await compressCommentsFlow(ignores, reversedFlattenedConfigData);
+    break;
+  case undefined: // falls through the default
+  default:
+    if (coreCommand && !coreCommand.startsWith("--"))
+      console.error(
+        `ERROR. Core command not recognized. Choose between "resolve" and "compress".`
+      );
+    else
+      console.log(
+        `If these settings are correct with you, feel free to initiate the command "resolve" to resolve comments, or "compress" to compress them back to their $COMMENT#* forms.${
+          passedConfigPath || lintConfigImports || myIgnoresOnly
+            ? " (And DON'T FORGET YOUR FLAGS!)"
+            : ""
+        }`
+      );
+    break;
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "comment-variables",
-  "version": "0.1.0",
-  "description": "",
+  "version": "0.3.0",
+  "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
-    "jscomments": "./index.js",
-    "comment-variables": "./index.js"
+    "jscomments": "./library/index.js",
+    "comment-variables": "./library/index.js"
   },
-  "main": "index.js",
+  "main": "library/index.js",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/LutherTS/jscomments.git"
@@ -14,14 +14,19 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "keywords": [],
-  "author": "",
+  "keywords": [
+    "cli",
+    "javascript",
+    "comments",
+    "variables"
+  ],
+  "author": "Luther Tchofo Safo <luther@tchofo-safo-portfolio.me>",
   "license": "MIT",
   "type": "module",
   "dependencies": {
     "@eslint/markdown": "^6.5.0",
     "eslint": "^9.29.0",
-    "get-sourcecode-from-file-path": "^1.0.0",
+    "get-sourcecode-from-file-path": "^1.0.1",
     "resolve-importing-path": "^1.0.2",
     "tsconfig-paths": "^4.2.0",
     "typescript-eslint": "^8.34.1",

package/comments.config.ts

@@ -1,24 +0,0 @@
-import { test } from "./import.js";
-
-const config = {
-  levelOne: {
-    levelTwo: {
-      levelThree: "Level three.",
-      // levelthree: "Also level three.", // errors
-      // alsoLevelThree: "Level three.", // errors
-      levelThreeBis: "Level three bis.",
-      levelThreeTer: "Level three ter.",
-      levelThreeAlso: "Also level three here.",
-      levelThreeToo: "This too is level three.",
-      // test: "LEVELONE#LEVELTWO#LEVELTHREE", // errors
-    },
-  },
-};
-
-export default config;
-
-// This too is level three.
-
-/* Notes
-I'll need to install TypeScript to test this.
-*/

package/find-all-imports.js

@@ -1,102 +0,0 @@
-import fs from "fs";
-import path from "path";
-
-import { resolveImportingPath } from "resolve-importing-path";
-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.
- */
-const processImport = (
-  importPath,
-  currentDir,
-  cwd,
-  visited,
-  depth,
-  maxDepth
-) => {
-  const resolvedPath = resolveImportingPath(currentDir, importPath, cwd);
-  if (!resolvedPath) return true; // Skips unresolved paths (not an error).
-
-  const result = findAllImports(
-    resolvedPath,
-    cwd,
-    visited,
-    depth + 1,
-    maxDepth
-  );
-  return result !== null; // Returns false if child failed.
-};
-
-export const findAllImports = (
-  filePath,
-  cwd = process.cwd(),
-  visited = new Set(),
-  depth = 0,
-  maxDepth = 100
-) => {
-  // Early failure checks (with logging).
-  if (depth > maxDepth) {
-    console.error(`ERROR. Max depth ${maxDepth} reached at ${filePath}.`);
-    return null;
-  }
-  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);
-  const sourceCode = getSourceCodeFromFilePath(filePath);
-  if (!sourceCode?.ast) {
-    console.error(`ERROR. Failed to parse AST for ${filePath}.`);
-    return null;
-  }
-
-  // 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,
-          visited,
-          depth,
-          maxDepth
-        )
-      ) {
-        return null;
-      }
-    }
-
-    // CommonJS (require('x'))
-    if (
-      node.type === "ExpressionStatement" &&
-      node.expression.type === "CallExpression" &&
-      node.expression.callee.name === "require" &&
-      node.expression.arguments[0]?.type === "Literal"
-    ) {
-      if (
-        !processImport(
-          node.expression.arguments[0].value,
-          currentDir,
-          cwd,
-          visited,
-          depth,
-          maxDepth
-        )
-      ) {
-        return null;
-      }
-    }
-  }
-
-  return visited; // success
-};

package/import.js

@@ -1,5 +0,0 @@
-import { test2 } from "./import2.js";
-
-export const test = test2;
-
-// This too is level three.

package/import2.js

@@ -1 +0,0 @@
-export const test2 = "test2";