comment-variables 0.1.0 → 0.3.0

package/comments.config.js

@@ -1,6 +1,5 @@
-import { test } from "./import.js";
-
-const config = {
+const data = {
+  // for testing
   levelOne: {
     levelTwo: {
       levelThree: "Level three.",
@@ -11,14 +10,94 @@ const config = {
       levelThreeAlso: "Also level three here.",
       levelThreeToo: "This too is level three.",
       // test: "LEVELONE#LEVELTWO#LEVELTHREE", // errors
-      [`level$Three#First
-        whitespace`]: `This is level three
-      with whitespaces. `,
-      testing: 2,
+      // [`level$Three#First
+      //   whitespace`]: `This is level three
+      // with whitespaces. `, // fails
+      // testing: 2, // fails
+      // ".'e": "",
     },
   },
+  // for deving
+  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"];
 
-// This too is level three.
+const config = {
+  data,
+  ignores,
+};
+
+export default config;

package/library/_commons/constants/bases.js

@@ -0,0 +1,77 @@
+import fs from "fs";
+import path from "path";
+
+import tseslint from "typescript-eslint";
+
+// plugin name
+export const commentVariablesPluginName = "comment-variables";
+
+// rule names
+export const resolveRuleName = "resolve";
+export const compressRuleName = "compress";
+
+// current working directory
+export const cwd = process.cwd();
+
+// to prevent accidental changes
+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
+export const defaultConfigFileName = "comments.config.js";
+
+// flags
+export const configFlag = "--config";
+export const lintConfigImportsFlag = "--lint-config-imports";
+export const myIgnoresOnlyFlag = "--my-ignores-only";
+
+// ESLint ignores
+export const knownIgnores = [
+  ".next",
+  ".react-router",
+  "node_modules",
+  ".parcel-cache",
+  ".react-router-parcel",
+  "dist",
+];
+
+// ESLint file globs
+export const allJSTSFileGlobs = [
+  "**/*.js",
+  "**/*.jsx",
+  "**/*.ts",
+  "**/*.tsx",
+  "**/*.mjs",
+  "**/*.cjs",
+];
+export const allMDFileGlobs = ["**/*.md"];
+export const allMDVirtualJSTSFileGlobs = [
+  "**/*.md/*.js",
+  "**/*.md/*.jsx",
+  "**/*.md/*.ts",
+  "**/*.md/*.tsx",
+  "**/*.md/*.cjs",
+  "**/*.md/*.mjs",
+];
+
+// default ESLint config language options
+export const typeScriptAndJSXCompatible = {
+  // for compatibility with TypeScript (.ts and .tsx)
+  parser: tseslint.parser,
+  // for compatibility with JSX (React, etc.)
+  parserOptions: {
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+};
+
+// 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

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

@@ -0,0 +1,78 @@
+import { placeholderMessageId } from "../constants/bases.js";
+
+import { escapeRegex } from "..//utilities/helpers.js";
+
+/**
+ * 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 = (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 sortedReversedFlattenedConfigData = Object.entries(
+    reversedFlattenedConfigData
+  ).sort(([a], [b]) => b.length - a.length);
+
+  /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */
+  const rule = {
+    meta: {
+      type: "suggestion",
+      docs: {
+        description:
+          "Compresses comments into $COMMENT#* placeholder(s) in comment line(s) or block(s).",
+      },
+      messages: {
+        [placeholderMessageId]:
+          "Compressed comments into $COMMENT#* placeholder(s) in comment line(s) or block(s).",
+      },
+      fixable: "code",
+      schema: [],
+    },
+    create: (context) => {
+      const sourceCode = context.sourceCode;
+      const comments = sourceCode
+        .getAllComments()
+        .filter((e) => e.type !== "Shebang");
+
+      for (const comment of comments) {
+        let fixedText = comment.value;
+        let modified = false;
+
+        for (const [
+          resolvedValue,
+          commentKey,
+        ] of sortedReversedFlattenedConfigData) {
+          const pattern = new RegExp(
+            `(?<=\\s|^)${escapeRegex(resolvedValue)}(?=\\s|$)`,
+            "g"
+          );
+
+          fixedText = fixedText.replace(pattern, () => {
+            modified = true;
+            return `$COMMENT#${commentKey}`;
+          });
+        }
+
+        if (modified && fixedText !== comment.value) {
+          context.report({
+            loc: comment.loc,
+            messageId: placeholderMessageId,
+            fix(fixer) {
+              const fullCommentText =
+                comment.type === "Block"
+                  ? `/*${fixedText}*/`
+                  : `//${fixedText}`;
+              return fixer.replaceText(comment, fullCommentText);
+            },
+          });
+        }
+      }
+
+      return {};
+    },
+  };
+
+  return rule;
+};
+
+export default makeRule; // compress

package/library/_commons/rules/resolve.js

@@ -0,0 +1,77 @@
+import {
+  placeholderMessageId,
+  flattenedConfigPlaceholderRegex,
+} from "../constants/bases.js";
+
+/**
+ * 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 = (flattenedConfigData) => {
+  /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */
+  const rule = {
+    meta: {
+      type: "suggestion",
+      docs: {
+        description:
+          "Resolves $COMMENT#* placeholder(s) in comment line(s) or block(s).",
+      },
+      messages: {
+        [placeholderMessageId]:
+          "Resolved $COMMENT#* placeholder(s) in comment line(s) or block(s).",
+      },
+      fixable: "code",
+      schema: [],
+    },
+    create: (context) => {
+      const sourceCode = context.sourceCode;
+      const comments = sourceCode
+        .getAllComments()
+        .filter((e) => e.type !== "Shebang");
+
+      for (const comment of comments) {
+        const matches = [
+          ...comment.value.matchAll(flattenedConfigPlaceholderRegex),
+        ];
+
+        if (matches.length === 0) continue;
+
+        let fixedText = comment.value;
+        let hasValidFix = false;
+
+        for (const match of matches) {
+          const fullMatch = match[0]; // e.g. $COMMENT#LEVELONE#LEVELTWO
+          const key = match[1]; // e.g. LEVELONE#LEVELTWO
+          const replacement = flattenedConfigData[key];
+
+          if (replacement) {
+            fixedText = fixedText.replace(fullMatch, replacement);
+            hasValidFix = true;
+          }
+        }
+
+        if (hasValidFix && fixedText !== comment.value) {
+          context.report({
+            loc: comment.loc,
+            messageId: placeholderMessageId,
+            fix(fixer) {
+              const range = comment.range;
+              const prefix = comment.type === "Block" ? "/*" : "//";
+              const suffix = comment.type === "Block" ? "*/" : "";
+              const newComment = `${prefix}${fixedText}${suffix}`;
+
+              return fixer.replaceTextRange(range, newComment);
+            },
+          });
+        }
+      }
+
+      return {};
+    },
+  };
+
+  return rule;
+};
+
+export default makeRule; // resolve

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

@@ -0,0 +1,120 @@
+import fs from "fs";
+import path from "path";
+
+import { resolveImportingPath } from "resolve-importing-path";
+import { getSourceCodeFromFilePath } from "get-sourcecode-from-file-path";
+
+/* findAllImports */
+
+/**
+ * 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,
+  visitedSet,
+  depth,
+  maxDepth
+) => {
+  const resolvedPath = resolveImportingPath(currentDir, importPath, cwd);
+  if (!resolvedPath) return true;
+
+  const result = findAllImports(
+    resolvedPath,
+    cwd,
+    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(),
+  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;
+  }
+  // Fails early if no file is found.
+  if (!fs.existsSync(filePath)) {
+    console.error(`ERROR. File not found at ${filePath}.`);
+    return null;
+  }
+
+  // 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}.`);
+    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,
+          visitedSet,
+          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,
+          visitedSet,
+          depth,
+          maxDepth
+        )
+      ) {
+        return null;
+      }
+    }
+  }
+
+  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,
+  };
+};