comment-variables 0.0.1

package/README.md

@@ -0,0 +1 @@
+(jscomments in the making)

package/comments.config.js

@@ -0,0 +1,20 @@
+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.

package/comments.config.ts

@@ -0,0 +1,24 @@
+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

@@ -0,0 +1,231 @@
+import fs from "fs";
+import path from "path";
+
+import { Linter } from "eslint";
+import tseslint from "typescript-eslint";
+import { loadConfig, createMatchPath } from "tsconfig-paths";
+
+/**
+ * @typedef {readonly [typeof TSX, typeof TS, typeof JSX, typeof JS, typeof MJS, typeof CJS]} Extensions
+ * @typedef {import('eslint').Linter.LanguageOptions} LanguageOptions
+ */
+
+// JavaScript/TypeScript extensions
+export const TSX = ".tsx";
+export const TS = ".ts";
+export const JSX = ".jsx";
+export const JS = ".js";
+export const MJS = ".mjs";
+export const CJS = ".cjs";
+
+// JavaScript/TypeScript extensions array
+/** @type {Extensions} */
+const EXTENSIONS = Object.freeze([TSX, TS, JSX, JS, MJS, CJS]); // In priority order
+
+/* resolveImportPath */
+
+/**
+ * Finds the existing path of an import that does not have an extension specified.
+ * @param {string} basePath The absolute import path with extension yet resolved.
+ * @returns The absolute path with its extension or `null` if no path is found.
+ */
+const findExistingPath = (basePath) => {
+  for (const ext of EXTENSIONS) {
+    const fullPath = `${basePath}${ext}`;
+    if (fs.existsSync(fullPath)) return fullPath;
+  }
+  return null;
+};
+
+/**
+ * Resolves an import path to a filesystem path, handling:
+ * - Base url and aliases (via tsconfig.json `baseUrl` and `paths` compiler options)
+ * - Missing extensions (appends `.ts`, `.tsx`, etc.)
+ * - Directory imports (e.g., `./components` → `./components/index.ts`)
+ * @param {string} currentDir The directory of the file containing the import (such as from `path.dirname(context.filename)`).
+ * @param {string} importPath The import specifier (e.g., `@/components/Button` or `./utils`), from the current node.
+ * @param {string} cwd The project root (such as from `context.cwd`).
+ * @returns The absolute resolved path or `null` if no path is found.
+ */
+export const resolveImportPath = (
+  currentDir,
+  importPath,
+  cwd = process.cwd()
+) => {
+  // Step 1: Resolves baseUrl and aliases
+  const config = loadConfig(cwd);
+
+  // creates a function that can resolve paths according to tsconfig's paths property if the config result type is success
+  const resolveTSConfig =
+    config.resultType === "success"
+      ? createMatchPath(config.absoluteBaseUrl, config.paths)
+      : null;
+
+  // resolves a path that relies on tsconfig's baseUrl or aliases if any of the aforementioned are present in the import path
+  const baseUrlOrAliasedPath = resolveTSConfig
+    ? resolveTSConfig(importPath, undefined, undefined, EXTENSIONS)
+    : null;
+
+  // Step 2: Resolves relative/absolute paths
+  const basePath = baseUrlOrAliasedPath || path.resolve(currentDir, importPath);
+
+  // does not resolve on node_modules
+  if (basePath.includes("node_modules")) return null;
+
+  // Case 1: File with extension exists
+  if (path.extname(importPath) && fs.existsSync(basePath)) return basePath;
+
+  // Case 2: Tries appending extensions
+  const extensionlessImportPath = findExistingPath(basePath);
+  if (extensionlessImportPath) return extensionlessImportPath;
+
+  // Case 3: Directory import (e.g., `./components` → `./components/index.ts`)
+  const indexPath = path.join(basePath, "index");
+  const directoryImportPath = findExistingPath(indexPath);
+  if (directoryImportPath) return directoryImportPath;
+
+  return null; // not found
+};
+
+// ESLint configs language options
+const typeScriptAndJSXCompatible = {
+  // for compatibility with .ts and .tsx
+  parser: tseslint.parser,
+  // for compatibility with JSX
+  parserOptions: {
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+};
+
+/* getSourceCodeFromFilePath */
+
+/**
+ * Gets the ESLint-generated SourceCode object of a file from its resolved path.
+ * @param {string} resolvedPath The resolved path of the file.
+ * @param {LanguageOptions} languageOptions The languageOptions object used by `linter.verify()` defaulting to a version that is TypeScript- and JSX-compatible.
+ * @returns The ESLint-generated SourceCode object of the file.
+ */
+export const getSourceCodeFromFilePath = (
+  resolvedPath,
+  languageOptions = typeScriptAndJSXCompatible
+) => {
+  // ensures each instance of the function is based on its own linter
+  // (just in case somehow some linters were running concurrently)
+  const linter = new Linter();
+  // the raw code of the file at the end of the resolved path
+  const text = fs.readFileSync(resolvedPath, "utf8");
+  // utilizes linter.verify ...
+  linter.verify(text, { languageOptions });
+  // ... to retrieve the raw code as a SourceCode object
+  const code = linter.getSourceCode();
+
+  return code;
+};
+
+/* 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 = resolveImportPath(currentDir, importPath, cwd);
+  if (!resolvedPath) return true; // Skip 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;
+
+  // Parse AST
+  visited.add(filePath);
+  const sourceCode = getSourceCodeFromFilePath(filePath);
+  if (!sourceCode?.ast) {
+    console.error(`ERROR. Failed to parse AST for ${filePath}.`);
+    return null;
+  }
+
+  // Process 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
+};
+
+/* Notes
+So here I want to make
+- resolveImportPath
+- getSourceCodeFromFilePath (remember the reason I favored the sourceCode is because it grants access to the AST and to the comments.)
+
+js-comments is taken on npm. 
+JSComments, jscomments is free.
+*/

package/import.js

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

package/import2.js

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

package/index.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+// The hashbang (#!) 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 fs from "fs";
+
+import { ESLint } from "eslint";
+
+import { runWithConfig } from "./run-with-config.js";
+import { findAllImports } from "./find-all-imports.js";
+
+const cwd = process.cwd();
+
+// ENSURES THE CLI TOOL ONLY RUN IN FOLDER THAT POSSESS A package.json FILE AND A .git FOLDER.
+
+const hasPackageJson = fs.existsSync(path.join(cwd, "package.json"));
+if (!hasPackageJson) {
+  console.error(
+    "ERROR. No package.json file found in this directory. Aborting to prevent accidental changes."
+  );
+  process.exit(1);
+}
+const hasGitFolder = fs.existsSync(path.join(cwd, ".git"));
+if (!hasGitFolder) {
+  console.error(
+    "ERROR. No git folder found in this directory. Aborting to prevent irreversible changes."
+  );
+  process.exit(1);
+}
+
+// GATHERS COMMANDS.
+
+const commands = process.argv;
+
+// OBTAINS THE VALIDATED FLATTENED CONFIG, REVERSE FLATTENED CONFIG, AND CONFIG PATH.
+
+const configFlagIndex = commands.indexOf("--config");
+const passedConfigPath =
+  configFlagIndex >= 2 ? path.join(cwd, commands[configFlagIndex + 1]) : null;
+const rawConfigPath = passedConfigPath ?? path.join(cwd, "comments.config.js");
+
+const results = await runWithConfig(rawConfigPath);
+if (!results) process.exit(1);
+
+const { flattenedConfig, reversedFlattenedConfig, configPath } = results;
+console.log("Config path is:", configPath);
+console.log("Verified flattened config is:", flattenedConfig);
+console.log("Reversed flattened config is:", reversedFlattenedConfig);
+
+const keys = new Set([...Object.keys(flattenedConfig)]);
+const values = new Set([...Object.values(flattenedConfig)]);
+
+// VALIDATES ONE LAST TIME THE REVERSABILITY OF flattenedConfig AND reversedFlattenedConfig.
+
+keys.forEach((key) => {
+  if (values.has(key)) {
+    console.error(
+      `The key "${key}" is and shouldn't be among the values of flattenedConfig.`
+    );
+    process.exit(1);
+  }
+});
+
+// ADDRESSES THE --include-config-imports FLAG, GIVEN THAT THE FILES IMPORTED BY THE CONFIG ARE IGNORED BY DEFAULT.
+
+const includeConfigImports = commands.indexOf("--include-config-imports") >= 2;
+const rawConfigIgnores = includeConfigImports
+  ? [configPath]
+  : [...findAllImports(configPath)];
+
+// the ignore paths must be relative
+const configIgnores = rawConfigIgnores.map((e) => path.relative(cwd, e));
+console.log(
+  includeConfigImports ? "Config ignore is:" : "Config ignores are",
+  configIgnores
+);
+
+// DEFINES DEFAULT ESLINT IGNORES AND FILES.
+
+const knownIgnores = [
+  ".next",
+  ".react-router",
+  "node_modules",
+  ".parcel-cache",
+  ".react-router-parcel",
+  "dist",
+];
+
+const allJSTSFileGlobs = [
+  "**/*.tsx",
+  "**/*.ts",
+  "**/*.jsx",
+  "**/*.js",
+  "**/*.mjs",
+  "**/*.cjs",
+];
+
+// MAKES THE FLOW FOR resolveCommentsInProject.
+
+/** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<string, []>} */
+const jsCommentsRule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Resolve $COMMENT#... using js-comments config.",
+    },
+    messages: {
+      message: `Resolved $COMMENT placeholder(s) in comment.`,
+    },
+    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(/\$COMMENT#([A-Z0-9#_]+)/g)];
+
+      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 = flattenedConfig[key];
+
+        if (replacement) {
+          fixedText = fixedText.replace(fullMatch, replacement);
+          hasValidFix = true;
+        }
+      }
+
+      if (hasValidFix && fixedText !== comment.value) {
+        context.report({
+          loc: comment.loc,
+          messageId: "message",
+          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 {};
+  },
+};
+
+async function resolveCommentsInProject(fileGlobs = allJSTSFileGlobs) {
+  const ruleName = "js-comments/js-comments-autofix";
+
+  const eslint = new ESLint({
+    fix: true,
+    errorOnUnmatchedPattern: false,
+    overrideConfigFile: true,
+    overrideConfig: [
+      {
+        files: fileGlobs,
+        ignores: [...configIgnores, ...knownIgnores], // 🚫 Ensure config isn't linted
+        languageOptions: {
+          ecmaVersion: "latest",
+          sourceType: "module",
+        },
+        plugins: {
+          "js-comments": {
+            rules: {
+              "js-comments-autofix": jsCommentsRule,
+            },
+          },
+        },
+        rules: {
+          [ruleName]: "warn", // Don't block builds, just apply fix
+        },
+      },
+    ],
+  });
+
+  const results = await eslint.lintFiles(fileGlobs);
+  await ESLint.outputFixes(results);
+
+  console.log({ results });
+
+  const total = results.reduce((sum, r) => {
+    const add = r.output ? 1 : 0;
+    return sum + add;
+  }, 0);
+  console.log(`✅ Resolved ${total} comment${total === 1 ? "" : "s"}.`);
+}
+
+// MAKES THE FLOW FOR compressCommentsInProject.
+
+const escapeRegex = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const makeReverseJsCommentsRule = (reversedFlattenedConfig) => {
+  // Sort the resolved values by descending length to prevent partial replacements.
+  const sortedReversedFlattenedConfig = Object.entries(
+    reversedFlattenedConfig
+  ).sort(([a], [b]) => b.length - a.length);
+
+  /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<string, []>} */
+  const reverseJsCommentsRule = {
+    meta: {
+      type: "suggestion",
+      docs: {
+        description: "Resolve $COMMENT#... using js-comments config in reverse",
+      },
+      messages: {
+        message: `Comment compressed.`,
+      },
+      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 sortedReversedFlattenedConfig) {
+          //   if (fixedText.includes(resolvedValue)) {
+          //     fixedText = fixedText.replaceAll(
+          //       resolvedValue,
+          //       `$COMMENT#${commentKey}`
+          //     );
+          //     modified = true;
+          //   }
+          // }
+
+          // if (modified) {
+
+          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: "message",
+            fix(fixer) {
+              const fullCommentText =
+                comment.type === "Block"
+                  ? `/*${fixedText}*/`
+                  : `//${fixedText}`;
+              return fixer.replaceText(comment, fullCommentText);
+            },
+          });
+        }
+      }
+
+      return {};
+    },
+  };
+
+  return reverseJsCommentsRule;
+};
+
+async function compressCommentsInProject(fileGlobs = allJSTSFileGlobs) {
+  const ruleName = "js-comments/js-comments-autofix";
+
+  const eslint = new ESLint({
+    fix: true,
+    errorOnUnmatchedPattern: false,
+    overrideConfigFile: true,
+    overrideConfig: [
+      {
+        files: fileGlobs,
+        ignores: [...configIgnores, ...knownIgnores], // 🚫 Ensure config isn't linted
+        languageOptions: {
+          ecmaVersion: "latest",
+          sourceType: "module",
+        },
+        plugins: {
+          "js-comments": {
+            rules: {
+              "js-comments-autofix": makeReverseJsCommentsRule(
+                reversedFlattenedConfig
+              ),
+            },
+          },
+        },
+        rules: {
+          [ruleName]: "warn", // Don't block builds, just apply fix
+        },
+      },
+    ],
+  });
+
+  const results = await eslint.lintFiles(fileGlobs);
+  await ESLint.outputFixes(results);
+
+  console.log({ results });
+
+  const total = results.reduce((sum, r) => {
+    const add = r.output ? 1 : 0;
+    return sum + add;
+  }, 0);
+  console.log(`✅ Compressed ${total} comment${total === 1 ? "" : "s"}.`);
+}
+
+// ADDRESSES THE CORE COMMANDS "resolve" AND "compress".
+
+const coreCommand = commands[2];
+
+switch (coreCommand) {
+  case "resolve":
+    await resolveCommentsInProject();
+    break;
+  case "compress":
+    await compressCommentsInProject();
+    break;
+  case undefined:
+    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.`
+    );
+    break;
+  default:
+    console.log(
+      `Core command not recognized. Choose between "resolve" and "compress".`
+    );
+    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. 
+*/

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "comment-variables",
+  "version": "0.0.1",
+  "description": "",
+  "bin": {
+    "jscomments": "./index.js"
+  },
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LutherTS/jscomments.git"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "eslint": "^9.29.0",
+    "tsconfig-paths": "^4.2.0",
+    "typescript-eslint": "^8.34.1",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@typescript-eslint/utils": "^8.34.0"
+  }
+}

package/run-with-config.js

@@ -0,0 +1,98 @@
+import { existsSync } from "fs";
+import { pathToFileURL } from "url";
+
+import { z } from "zod";
+
+function flattenConfig(
+  config,
+  normalizedPath = "",
+  map = {},
+  pathStack = [],
+  reversedFlattenedConfig = {}
+) {
+  for (const [key, value] of Object.entries(config)) {
+    const currentPath = [...pathStack, key];
+    normalizedPath = currentPath
+      .map((k) => k.toUpperCase())
+      .join("#")
+      .replaceAll(" ", "_"); // spaces 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") {
+      flattenConfig(value, normalizedPath, map, currentPath);
+    }
+  }
+
+  const flattenedConfig = 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(flattenedConfig)) {
+    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(flattenedConfig)) {
+    reversedFlattenedConfig[value] = key;
+  }
+
+  return { flattenedConfig, reversedFlattenedConfig };
+}
+
+export async function runWithConfig(rawConfigPath) {
+  // const __filename = fileURLToPath(import.meta.url);
+  // const __dirname = dirname(__filename);
+
+  // const configPath = join(__dirname, rawConfigPath);
+  const configPath = rawConfigPath;
+
+  // 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") {
+    console.warn("Invalid config format. Exiting.");
+    return null;
+  }
+
+  const RecursiveObject = z.lazy(() =>
+    z.record(z.union([z.string(), RecursiveObject]))
+  );
+  const result = RecursiveObject.safeParse(config);
+
+  if (!result.success) {
+    console.warn("Config could not pass validation from zod.");
+    return null;
+  }
+
+  // Step 4: Do your thing
+  console.log("Running with config:", config);
+  return { ...flattenConfig(config), configPath };
+}

package/test-file.js

@@ -0,0 +1,7 @@
+/* 
+$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE
+$COMMENT#LEVELONE#LEVELTWO#LEVELTHREEBIS
+$COMMENT#LEVELONE#LEVELTWO#LEVELTHREETER
+$COMMENT#LEVELONE#LEVELTWO#LEVELTHREEALSO
+$COMMENT#LEVELONE#LEVELTWO#LEVELTHREETOO
+*/