comment-variables 1.1.3 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +1 -1
  2. package/comments.config.js +11 -0
  3. package/comments.config.json +34 -60
  4. package/library/_commons/utilities/flows.js +5 -5
  5. package/library/index.js +23 -9
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -18,7 +18,7 @@ npm install -g comment-variables
18
18
  comment-variables
19
19
  ```
20
20
 
21
- Interacts with your root `comments.config.js` file's default exported object to print all the parameters you need to be aware of before running `compress` or `resolve`. Also acts as a dry run validation check. If no error is printed, it means you can run `compress` or `resolve` safely, as long as the printed parameters correspond to what you've expected from your defined config. (Additionally creates a resolved version of your config data as a JSON file. If no configuration file is found, a tutorial mode is triggered, generating a template config file for you.)
21
+ Interacts with your root `comments.config.js` file's default exported object to print all the parameters you need to be aware of before running `compress` or `resolve`. Also acts as a dry run validation check. If no error is printed, it means you can run `compress` or `resolve` safely, as long as the printed parameters correspond to what you've expected from your defined config. (Additionally creates a resolved version of your config data as a JSON file, and as a .mjs file exporting both the typedef `ResolvedConfigData` and the object `resolvedConfigData`. If no configuration file is found, a tutorial mode is triggered, generating a template config file for you.)
22
22
 
23
23
  ```
24
24
  comment-variables placeholders
package/comments.config.js CHANGED
@@ -47,6 +47,15 @@ const data = {
47
47
  // value: "value not allowed", // errors, "key", "value" and "placeholder" not allowed
48
48
  // placeholder: "placeholder not allowed", // errors, "key", "value" and "placeholder" not allowed
49
49
  // noConcat: "no" + "concat", // errors, unrecognized value
50
+
51
+ // already error via regex, but now enhanced:
52
+ // "//": "key comment error 1",
53
+ // "/*": "key comment error 2",
54
+ // "*/": "key comment error 3",
55
+ // error directly in resolveConfig:
56
+ // "key comment error 1": "//",
57
+ // "key comment error 2": "/*",
58
+ // "key comment error 3": "*/",
50
59
  },
51
60
  },
52
61
  // for deving
@@ -94,6 +103,8 @@ const data = {
94
103
  'The array of paths linked to the config file, (named "ignores" given it is ignored by the "compress" and "resolve" commands).' /* $COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES */,
95
104
  originalFlattenedConfigData:
96
105
  "The original flattened config data, before changes to aliases variables and composed variables are applied." /* $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA */,
106
+ relativeMjsPath:
107
+ 'The relative path of the generated `.mjs` file to be ignored in the "placeholders" process.' /* $COMMENT#JSDOC#PARAMS#RELATIVEMJSPATH */,
97
108
  }),
98
109
  returns: Object.freeze({
99
110
  exitDueToFailure:
package/comments.config.json CHANGED
@@ -3,28 +3,23 @@
3
3
  "levelTwo": {
4
4
  "levelThree": {
5
5
  "value": "Level three.",
6
- "key": "LEVELONE#LEVELTWO#LEVELTHREE",
7
- "placeholder": "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE"
6
+ "key": "LEVELONE#LEVELTWO#LEVELTHREE"
8
7
  },
9
8
  "stillLevelThree": {
10
9
  "value": "Level three.",
11
- "key": "LEVELONE#LEVELTWO#STILLLEVELTHREE",
12
- "placeholder": "$COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE"
10
+ "key": "LEVELONE#LEVELTWO#STILLLEVELTHREE"
13
11
  },
14
12
  "otherLevelThree": {
15
13
  "value": "Level three.",
16
- "key": "LEVELONE#LEVELTWO#OTHERLEVELTHREE",
17
- "placeholder": "$COMMENT#LEVELONE#LEVELTWO#OTHERLEVELTHREE"
14
+ "key": "LEVELONE#LEVELTWO#OTHERLEVELTHREE"
18
15
  },
19
16
  "composedVariable": {
20
17
  "value": "Level three. Level three.",
21
- "key": "LEVELONE#LEVELTWO#COMPOSEDVARIABLE",
22
- "placeholder": "$COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE"
18
+ "key": "LEVELONE#LEVELTWO#COMPOSEDVARIABLE"
23
19
  },
24
20
  "composedVariableAlias": {
25
21
  "value": "Level three. Level three.",
26
- "key": "LEVELONE#LEVELTWO#COMPOSEDVARIABLEALIAS",
27
- "placeholder": "$COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLEALIAS"
22
+ "key": "LEVELONE#LEVELTWO#COMPOSEDVARIABLEALIAS"
28
23
  }
29
24
  }
30
25
  },
@@ -32,134 +27,113 @@
32
27
  "definitions": {
33
28
  "exitDueToFailure": {
34
29
  "value": "Terminates the whole process with a 'failure' code (`1`).",
35
- "key": "JSDOC#DEFINITIONS#EXITDUETOFAILURE",
36
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE"
30
+ "key": "JSDOC#DEFINITIONS#EXITDUETOFAILURE"
37
31
  },
38
32
  "makeRuleResolve": {
39
33
  "value": "The utility that creates the resolve rule based on the flattened config data, used to transform `$COMMENT` placeholders into actual comments.",
40
- "key": "JSDOC#DEFINITIONS#MAKERULERESOLVE",
41
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#MAKERULERESOLVE"
34
+ "key": "JSDOC#DEFINITIONS#MAKERULERESOLVE"
42
35
  },
43
36
  "makeRuleCompress": {
44
37
  "value": "The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into `$COMMENT` placeholders.",
45
- "key": "JSDOC#DEFINITIONS#MAKERULECOMPRESS",
46
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS"
38
+ "key": "JSDOC#DEFINITIONS#MAKERULECOMPRESS"
47
39
  },
48
40
  "coreCommentsFlow": {
49
41
  "value": "The core flow at the heart of resolving and compressing comments.",
50
- "key": "JSDOC#DEFINITIONS#CORECOMMENTSFLOW",
51
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW"
42
+ "key": "JSDOC#DEFINITIONS#CORECOMMENTSFLOW"
52
43
  },
53
44
  "resolveCommentsFlow": {
54
45
  "value": "The flow that resolves `$COMMENT` placeholders into actual comments.",
55
- "key": "JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW",
56
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW"
46
+ "key": "JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW"
57
47
  },
58
48
  "compressCommentsFlow": {
59
49
  "value": "The flow that compresses actual comments into `$COMMENT` placeholders.",
60
- "key": "JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW",
61
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW"
50
+ "key": "JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW"
62
51
  },
63
52
  "placeholdersCommentsFlow": {
64
53
  "value": "The flow that creates `$COMMENT` placeholders right next to where they're defined.",
65
- "key": "JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW",
66
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW"
54
+ "key": "JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW"
67
55
  },
68
56
  "logError": {
69
57
  "value": "Logs an error to the console depending on its type. (`\"error\"` or `\"warning\"`.)",
70
- "key": "JSDOC#DEFINITIONS#LOGERROR",
71
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#LOGERROR"
58
+ "key": "JSDOC#DEFINITIONS#LOGERROR"
72
59
  }
73
60
  },
74
61
  "params": {
75
62
  "flattenedConfigData": {
76
63
  "value": "The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values.",
77
- "key": "JSDOC#PARAMS#FLATTENEDCONFIGDATA",
78
- "placeholder": "$COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA"
64
+ "key": "JSDOC#PARAMS#FLATTENEDCONFIGDATA"
79
65
  },
80
66
  "reversedFlattenedConfigData": {
81
67
  "value": "The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values.",
82
- "key": "JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA",
83
- "placeholder": "$COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA"
68
+ "key": "JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA"
84
69
  },
85
70
  "composedVariablesExclusives": {
86
71
  "value": "The array of comment variables keys (implying their aliases as well) exclusively used to craft composed variables, that should be ignored by both the `resolve` and the `compress` commands.",
87
- "key": "JSDOC#PARAMS#COMPOSEDVARIABLESEXCLUSIVES",
88
- "placeholder": "$COMMENT#JSDOC#PARAMS#COMPOSEDVARIABLESEXCLUSIVES"
72
+ "key": "JSDOC#PARAMS#COMPOSEDVARIABLESEXCLUSIVES"
89
73
  },
90
74
  "aliases_flattenedKeys": {
91
75
  "value": "The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.",
92
- "key": "JSDOC#PARAMS#ALIASES_FLATTENEDKEYS",
93
- "placeholder": "$COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS"
76
+ "key": "JSDOC#PARAMS#ALIASES_FLATTENEDKEYS"
94
77
  },
95
78
  "ruleName": {
96
79
  "value": "The name of the rule currently used. (Either `\"resolve\"` or `\"compress\"`.)",
97
- "key": "JSDOC#PARAMS#RULENAME",
98
- "placeholder": "$COMMENT#JSDOC#PARAMS#RULENAME"
80
+ "key": "JSDOC#PARAMS#RULENAME"
99
81
  },
100
82
  "ignores": {
101
83
  "value": "The array of paths and globs for the flow's ESLint instance to ignore.",
102
- "key": "JSDOC#PARAMS#IGNORES",
103
- "placeholder": "$COMMENT#JSDOC#PARAMS#IGNORES"
84
+ "key": "JSDOC#PARAMS#IGNORES"
104
85
  },
105
86
  "eitherFlattenedConfigData": {
106
87
  "value": "Either the flattened config data or the reversed flattened config data, since they share the same structure.",
107
- "key": "JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA",
108
- "placeholder": "$COMMENT#JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA"
88
+ "key": "JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA"
109
89
  },
110
90
  "error": {
111
91
  "value": "The error object being handle for the logging.",
112
- "key": "JSDOC#PARAMS#ERROR",
113
- "placeholder": "$COMMENT#JSDOC#PARAMS#ERROR"
92
+ "key": "JSDOC#PARAMS#ERROR"
114
93
  },
115
94
  "options": {
116
95
  "value": "The additional options as follows:",
117
- "key": "JSDOC#PARAMS#OPTIONS",
118
- "placeholder": "$COMMENT#JSDOC#PARAMS#OPTIONS"
96
+ "key": "JSDOC#PARAMS#OPTIONS"
119
97
  },
120
98
  "settings": {
121
99
  "value": "The required settings as follows:",
122
- "key": "JSDOC#PARAMS#SETTINGS",
123
- "placeholder": "$COMMENT#JSDOC#PARAMS#SETTINGS"
100
+ "key": "JSDOC#PARAMS#SETTINGS"
124
101
  },
125
102
  "configPathIgnores": {
126
103
  "value": "The array of paths linked to the config file, (named \"ignores\" given it is ignored by the \"compress\" and \"resolve\" commands).",
127
- "key": "JSDOC#PARAMS#CONFIGPATHIGNORES",
128
- "placeholder": "$COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES"
104
+ "key": "JSDOC#PARAMS#CONFIGPATHIGNORES"
129
105
  },
130
106
  "originalFlattenedConfigData": {
131
107
  "value": "The original flattened config data, before changes to aliases variables and composed variables are applied.",
132
- "key": "JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA",
133
- "placeholder": "$COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA"
108
+ "key": "JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA"
109
+ },
110
+ "relativeMjsPath": {
111
+ "value": "The relative path of the generated `.mjs` file to be ignored in the \"placeholders\" process.",
112
+ "key": "JSDOC#PARAMS#RELATIVEMJSPATH"
134
113
  }
135
114
  },
136
115
  "returns": {
137
116
  "exitDueToFailure": {
138
117
  "value": "Never. (Somehow typing needs to be explicit for unreachable code inference.)",
139
- "key": "JSDOC#RETURNS#EXITDUETOFAILURE",
140
- "placeholder": "$COMMENT#JSDOC#RETURNS#EXITDUETOFAILURE"
118
+ "key": "JSDOC#RETURNS#EXITDUETOFAILURE"
141
119
  },
142
120
  "makeRuleResolve": {
143
121
  "value": "The resolve rule based on the flattened config data.",
144
- "key": "JSDOC#RETURNS#MAKERULERESOLVE",
145
- "placeholder": "$COMMENT#JSDOC#RETURNS#MAKERULERESOLVE"
122
+ "key": "JSDOC#RETURNS#MAKERULERESOLVE"
146
123
  },
147
124
  "makeRuleCompress": {
148
125
  "value": "The compress rule based on the reversed flattened config data.",
149
- "key": "JSDOC#RETURNS#MAKERULECOMPRESS",
150
- "placeholder": "$COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS"
126
+ "key": "JSDOC#RETURNS#MAKERULECOMPRESS"
151
127
  }
152
128
  },
153
129
  "constants": {
154
130
  "sortedReversedFlattenedConfigData": {
155
131
  "value": "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.",
156
- "key": "JSDOC#CONSTANTS#SORTEDREVERSEDFLATTENEDCONFIGDATA",
157
- "placeholder": "$COMMENT#JSDOC#CONSTANTS#SORTEDREVERSEDFLATTENEDCONFIGDATA"
132
+ "key": "JSDOC#CONSTANTS#SORTEDREVERSEDFLATTENEDCONFIGDATA"
158
133
  },
159
134
  "composedVariablesExclusivesSet": {
160
135
  "value": "A local Set out of composed variables exclusives for speed.",
161
- "key": "JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET",
162
- "placeholder": "$COMMENT#JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET"
136
+ "key": "JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET"
163
137
  }
164
138
  }
165
139
  }
package/library/_commons/utilities/flows.js CHANGED
@@ -117,7 +117,6 @@ const coreCommentsFlow = async (
117
117
  export const resolveCommentsFlow = async (
118
118
  ignores,
119
119
  flattenedConfigData,
120
- // NEW
121
120
  composedVariablesExclusives,
122
121
  aliases_flattenedKeys
123
122
  ) =>
@@ -125,7 +124,6 @@ export const resolveCommentsFlow = async (
125
124
  resolveRuleName,
126
125
  ignores,
127
126
  flattenedConfigData,
128
- // NEW
129
127
  composedVariablesExclusives,
130
128
  aliases_flattenedKeys
131
129
  );
@@ -142,14 +140,12 @@ export const resolveCommentsFlow = async (
142
140
  export const compressCommentsFlow = async (
143
141
  ignores,
144
142
  reversedFlattenedConfigData,
145
- // NEW
146
143
  composedVariablesExclusives
147
144
  ) =>
148
145
  coreCommentsFlow(
149
146
  compressRuleName,
150
147
  ignores,
151
148
  reversedFlattenedConfigData,
152
- // NEW
153
149
  composedVariablesExclusives
154
150
  );
155
151
 
@@ -160,12 +156,14 @@ export const compressCommentsFlow = async (
160
156
  * @param {string[]} configPathIgnores The array of paths linked to the config file, (named "ignores" given it is ignored by the "compress" and "resolve" commands).
161
157
  * @param {{[k: string]: string;}} originalFlattenedConfigData The original flattened config data, before changes to aliases variables and composed variables are applied.
162
158
  * @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.
159
+ * @param {string} relativeMjsPath The relative path of the generated `.mjs` file to be ignored in the "placeholders" process.
163
160
  * @returns
164
161
  */
165
162
  export const placeholdersCommentsFlow = async (
166
163
  configPathIgnores,
167
164
  originalFlattenedConfigData,
168
- aliases_flattenedKeys
165
+ aliases_flattenedKeys,
166
+ relativeMjsPath
169
167
  ) => {
170
168
  /** @type {Record<string, string>} */
171
169
  const composedValues_originalKeys = {};
@@ -199,7 +197,9 @@ export const placeholdersCommentsFlow = async (
199
197
  overrideConfigFile: true,
200
198
  overrideConfig: [
201
199
  {
200
+ // The .mjs file is considered part of the config path ignores, albeit being a special case since it is "created" by the config rather than imported by it. "placeholders" is the only flow that targets specifically the config path ignores, but its case, the .mjs file should actually be ignored. As such, I make the decision to retain the current integrity of `configPathIgnores`, and to place the mjsPath as an ESLint ignore pattern, where it is required to be relative to `cwd`.
202
201
  files: configPathIgnores,
202
+ ignores: [relativeMjsPath], // but the docs say ignorePatterns: https://eslint.org/docs/latest/integrate/nodejs-api#parameters
203
203
  languageOptions: typeScriptAndJSXCompatible,
204
204
  plugins: {
205
205
  [commentVariablesPluginName]: {
package/library/index.js CHANGED
@@ -149,9 +149,14 @@ skipDetails ||
149
149
 
150
150
  // ADDRESSES THE --lint-config-imports FLAG (lintConfigImports, no longer a flag), GIVEN THAT THE FILES IMPORTED BY THE CONFIG ARE IGNORED BY DEFAULT.
151
151
 
152
+ // instantiates the JSON and .mjs path proactively
153
+ const jsonPath = configPath.replace(/\.js$/, () => ".json");
154
+ const mjsPath = configPath.replace(/\.js$/, () => ".mjs");
155
+
152
156
  const rawConfigPathIgnores = lintConfigImports
153
- ? [configPath]
154
- : rawConfigAndImportPaths;
157
+ ? // also ignores the .mjs path
158
+ [configPath, mjsPath]
159
+ : [...rawConfigAndImportPaths, mjsPath];
155
160
 
156
161
  // the ignore paths must be relative
157
162
  const configPathIgnores = rawConfigPathIgnores.map((e) =>
@@ -181,15 +186,25 @@ if (!makeResolvedConfigDataResults.success) {
181
186
  }
182
187
 
183
188
  const resolvedConfigData = makeResolvedConfigDataResults.resolvedConfigData;
184
- const jsonPath = resolveConfigResults.configPath.replace(
185
- /\.js$/,
186
- () => ".json"
187
- );
189
+
188
190
  const jsonData = JSON.stringify(resolvedConfigData, null, 2);
189
191
  fs.writeFileSync(jsonPath, jsonData, "utf8");
190
192
 
191
193
  console.log(`JSON resolved config data written to: \n${jsonPath}`);
192
194
 
195
+ // NEW!! comments.config.mjs to directly access resolvedConfigData.
196
+
197
+ const mjsData = `/** @typedef {${JSON.stringify(
198
+ resolvedConfigData
199
+ )}} ResolvedConfigData */\n\n/** @type {ResolvedConfigData} */\nexport const resolvedConfigData = ${JSON.stringify(
200
+ resolvedConfigData,
201
+ null,
202
+ 2
203
+ )}`;
204
+ fs.writeFileSync(mjsPath, mjsData, "utf8");
205
+
206
+ console.log(`MJS resolved config data written to: \n${mjsPath}`);
207
+
193
208
  // ADDRESSES THE CORE COMMANDS "resolve", "compress", AND "placeholders".
194
209
 
195
210
  switch (coreCommand) {
@@ -198,7 +213,6 @@ switch (coreCommand) {
198
213
  await resolveCommentsFlow(
199
214
  ignores,
200
215
  flattenedConfigData,
201
- // NEW
202
216
  composedVariablesExclusives,
203
217
  aliases_flattenedKeys
204
218
  );
@@ -208,7 +222,6 @@ switch (coreCommand) {
208
222
  await compressCommentsFlow(
209
223
  ignores,
210
224
  reversedFlattenedConfigData,
211
- // NEW
212
225
  composedVariablesExclusives
213
226
  );
214
227
  break;
@@ -217,7 +230,8 @@ switch (coreCommand) {
217
230
  await placeholdersCommentsFlow(
218
231
  configPathIgnores,
219
232
  originalFlattenedConfigData,
220
- aliases_flattenedKeys
233
+ aliases_flattenedKeys,
234
+ path.relative(cwd, mjsPath)
221
235
  );
222
236
  break;
223
237
  default:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "comment-variables",
3
- "version": "1.1.3",
3
+ "version": "1.2.2",
4
4
  "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
5
5
  "bin": {
6
6
  "comment-variables": "./library/index.js",
@@ -30,7 +30,7 @@
30
30
  "type": "module",
31
31
  "dependencies": {
32
32
  "@eslint/markdown": "^6.5.0",
33
- "comment-variables-resolve-config": "^1.14.1",
33
+ "comment-variables-resolve-config": "^1.14.6",
34
34
  "eslint": "^9.29.0"
35
35
  },
36
36
  "devDependencies": {