comment-variables 0.13.0 → 0.14.2

package/generate.example.js

@@ -0,0 +1,7 @@
+// A JavaScript file that acts as an example file for the generated Comment Variables template config. Assuming you've yet to produce your own `comments.config.js` file, use the `comment-variables compress` and `comment-variables resolve` commands to see how the following comments go back and forth from Comment Variables placeholders (`$COMMENT`) to actual comments, reversibly.
+
+// This is a comment.
+// $COMMENT#ALIAS
+// Yes.
+// This is a comment. Yes. This is a comment.
+// $COMMENT#COMMENTS#NO

package/generate.template.js

@@ -0,0 +1,31 @@
+// A Comment Variables config template generated in case no config file has been found. Feel free to use it as a stepping stone to learn how to use Comment Variables.
+
+// As a first step, go ahead and run the command `comment-variables placeholders`.
+// Then rename the `$COMMENT#COMMENT` placeholder next to `alias` to `$COMMENT#ALIAS` and run `comment-variables placeholders` to see what happens.
+// You can now use and explore Comment Variables on the accompanying `comments.example.js` file that has also been generated.
+
+const data = Object.freeze({
+  comment: "This is a comment.",
+  alias: "COMMENT",
+  composed: "$COMMENT#COMMENT $COMMENT#COMMENTS#YES $COMMENT#ALIAS",
+  comments: Object.freeze({
+    yes: "Yes.",
+    no: "No.",
+  }),
+});
+
+const ignores = [];
+
+const lintConfigImports = false; // can be ommitted
+const myIgnoresOnly = false; // can be ommitted
+
+const config = {
+  data,
+  ignores,
+  lintConfigImports,
+  myIgnoresOnly,
+};
+
+export default config;
+
+// Once you've grasped these concepts, simply copy or rename this file to `comments.config.js` and you're good to go.

package/library/_commons/constants/bases.js

@@ -1,14 +1,13 @@
 import fs from "fs";
 import path from "path";
 
+import { cwd } from "comment-variables-resolve-config";
+
 // rule names
 export const resolveRuleName = "resolve";
 export const compressRuleName = "compress";
 export const placeholdersRuleName = "placeholders"; // rule?
 
-// 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

package/library/_commons/rules/compress.js

@@ -5,9 +5,9 @@ import {
 } from "comment-variables-resolve-config";
 
 /**
- * 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.
+ * $COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS
+ * @param {{[key: string]: string}} reversedFlattenedConfigData $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
+ * @returns $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS
  */
 const makeRule = (reversedFlattenedConfigData) => {
   /** The whole `reversedFlattenedConfigData` turned from an object to an array of key-value arrays sorted by the descending length of each key to prevent partial replacements. */

package/library/_commons/rules/resolve.js

@@ -4,10 +4,10 @@ import {
 } from "comment-variables-resolve-config";
 
 /**
- * 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.
- * @param {{[key: string]: string}} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
- * @returns The resolve rule based on the flattened config data.
+ * $COMMENT#JSDOC#DEFINITIONS#MAKERULERESOLVE
+ * @param {{[key: string]: string}} flattenedConfigData $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
+ * @param {{[key: string]: string}} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
+ * @returns $COMMENT#JSDOC#RETURNS#MAKERULERESOLVE
  */
 const makeRule = (flattenedConfigData, aliases_flattenedKeys) => {
   /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */

package/library/_commons/utilities/flows.js

@@ -21,11 +21,11 @@ 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.
- * @param {Record<string, string> | undefined} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
+ * $COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW
+ * @param {typeof resolveRuleName | typeof compressRuleName} ruleName $COMMENT#JSDOC#PARAMS#RULENAME
+ * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
+ * @param {{[key: string]: string}} flattenedConfigData $COMMENT#JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA
+ * @param {Record<string, string> | undefined} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
  * @returns
  */
 const coreCommentsFlow = async (
@@ -104,10 +104,10 @@ const coreCommentsFlow = async (
 /* resolveCommentsFlow */
 
 /**
- * The flow that resolves `$COMMENT` placeholders into actual comments.
- * @param {string[]} ignores The array of paths and globs for the flow's ESLint instance to ignore.
- * @param {Record<string, string>} flattenedConfigData The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values.
- * @param {Record<string, string>} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
+ * $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW
+ * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
+ * @param {Record<string, string>} flattenedConfigData $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
+ * @param {Record<string, string>} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
  * @returns
  */
 export const resolveCommentsFlow = async (
@@ -125,9 +125,9 @@ export const resolveCommentsFlow = async (
 /* 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.
+ * $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW
+ * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
+ * @param {{[key: string]: string}} reversedFlattenedConfigData $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
  * @returns
  */
 export const compressCommentsFlow = async (
@@ -138,10 +138,10 @@ export const compressCommentsFlow = async (
 /* placeholdersCommentsFlow */
 
 /**
- * The flow that creates `$COMMENT` placeholders right next to where they're defined.
- * @param {string[]} configPathIgnores The array of paths linked to the config file, (named "ignores" given it is ignored by the "compress" and "resolve" commands).
- * @param {{[k: string]: string;}} originalFlattenedConfigData The original flattened config data, before changes to Aliases Variables and Composed Variables are applied.
- * @param {Record<string, string>} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
+ * $COMMENT#JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW
+ * @param {string[]} configPathIgnores $COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES
+ * @param {{[k: string]: string;}} originalFlattenedConfigData $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA
+ * @param {Record<string, string>} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
  * @returns
  */
 export const placeholdersCommentsFlow = async (

package/library/_commons/utilities/helpers.js

@@ -1,16 +1,16 @@
 /* exitDueToFailure */
 
 /**
- * Terminates the whole process with a 'failure' code (`1`).
- * @returns {never} Never. (Somehow typing needs to be explicit for unreachable code inference.)
+ * $COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE
+ * @returns {never} $COMMENT#JSDOC#RETURNS#EXITDUETOFAILURE
  */
 export const exitDueToFailure = () => process.exit(1);
 
 /* logError */
 
 /**
- * Logs an error to the console depending on its type. (`"error"` or `"warning"`.)
- * @param {{type: "error" | "warning"; message: string}} error The error object being handle for the logging.
+ * $COMMENT#JSDOC#DEFINITIONS#LOGERROR
+ * @param {{type: "error" | "warning"; message: string}} error $COMMENT#JSDOC#PARAMS#ERROR
  * @returns
  */
 export const logError = (error) => {

package/library/index.js

@@ -3,16 +3,19 @@
 
 import path from "path";
 import fs from "fs";
+import url from "url";
 
 import resolveConfig, {
   defaultConfigFileName,
+  templateFileName,
+  exampleFileName,
   configFlag,
+  cwd,
   knownIgnores,
   makeResolvedConfigData,
 } from "comment-variables-resolve-config";
 
 import {
-  cwd,
   hasPackageJson,
   hasGitFolder,
   resolveRuleName,
@@ -67,7 +70,38 @@ const passedConfig = commands[configFlagIndex + 1];
 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);
+let rawConfigPath = passedConfigPath ?? path.join(cwd, defaultConfigFileName);
+
+if (!fs.existsSync(rawConfigPath)) {
+  console.log(
+    `No Comment Variables config file found at ${rawConfigPath}. Switching to tutorial mode.`
+  );
+
+  const templateFilePath = path.join(cwd, templateFileName);
+  const exampleFilePath = path.join(cwd, exampleFileName);
+  const dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+  if (fs.existsSync(templateFilePath)) {
+    console.log(`Proceeding with template file found at ${templateFilePath}.`);
+  } else {
+    const sourceTemplateFilePath = path.join(
+      dirname,
+      "../generate.template.js"
+    );
+    console.log(`Generating template file at ${templateFilePath}.`);
+    fs.copyFileSync(sourceTemplateFilePath, templateFilePath);
+  }
+
+  if (fs.existsSync(exampleFilePath)) {
+    console.log(`Proceeding with example file found at ${exampleFilePath}.`);
+  } else {
+    const sourceExampleFilePath = path.join(dirname, "../generate.example.js");
+    console.log(`Generating example file at ${exampleFilePath}.`);
+    fs.copyFileSync(sourceExampleFilePath, exampleFilePath);
+  }
+
+  rawConfigPath = templateFilePath;
+}
 
 console.log(`Resolving config at ${rawConfigPath}...`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "0.13.0",
+  "version": "0.14.2",
   "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
     "jscomments": "./library/index.js",
@@ -11,8 +11,8 @@
     "library",
     "comments.config.js",
     "comments.config.json",
-    "comments.template.js",
-    "comments.example.js"
+    "generate.template.js",
+    "generate.example.js"
   ],
   "repository": {
     "type": "git",
@@ -29,7 +29,7 @@
   "type": "module",
   "dependencies": {
     "@eslint/markdown": "^6.5.0",
-    "comment-variables-resolve-config": "^1.12.0",
+    "comment-variables-resolve-config": "^1.12.3",
     "eslint": "^9.29.0"
   },
   "devDependencies": {

package/comments.example.js

@@ -1 +0,0 @@
-// A JavaScript file that acts as an example file for the generated Comment Variables template config. Use the `comment-variables compress` and `comment-variables resolve` commands to see how the following comments go back and forth from Comment Variables placeholders to actual comments reversibly.

package/comments.template.js

@@ -1 +0,0 @@
-// A Comment Variables config template generated upon approval in case no config file has been found. Feel free to use it as a steping stone to learn how to use Comment Variables.