comment-variables 1.2.1 → 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 (5) hide show
  1. package/comments.config.js +2 -0
  2. package/comments.config.json +34 -60
  3. package/library/_commons/utilities/flows.js +5 -5
  4. package/library/index.js +7 -5
  5. package/package.json +2 -2
package/comments.config.js CHANGED
@@ -103,6 +103,8 @@ const data = {
103
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 */,
104
104
  originalFlattenedConfigData:
105
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 */,
106
108
  }),
107
109
  returns: Object.freeze({
108
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,12 +149,13 @@ 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
- // instantiate the JSON and .mjs path proactively
152
+ // instantiates the JSON and .mjs path proactively
153
153
  const jsonPath = configPath.replace(/\.js$/, () => ".json");
154
154
  const mjsPath = configPath.replace(/\.js$/, () => ".mjs");
155
155
 
156
156
  const rawConfigPathIgnores = lintConfigImports
157
- ? [configPath, mjsPath]
157
+ ? // also ignores the .mjs path
158
+ [configPath, mjsPath]
158
159
  : [...rawConfigAndImportPaths, mjsPath];
159
160
 
160
161
  // the ignore paths must be relative
@@ -202,6 +203,8 @@ const mjsData = `/** @typedef {${JSON.stringify(
202
203
  )}`;
203
204
  fs.writeFileSync(mjsPath, mjsData, "utf8");
204
205
 
206
+ console.log(`MJS resolved config data written to: \n${mjsPath}`);
207
+
205
208
  // ADDRESSES THE CORE COMMANDS "resolve", "compress", AND "placeholders".
206
209
 
207
210
  switch (coreCommand) {
@@ -210,7 +213,6 @@ switch (coreCommand) {
210
213
  await resolveCommentsFlow(
211
214
  ignores,
212
215
  flattenedConfigData,
213
- // NEW
214
216
  composedVariablesExclusives,
215
217
  aliases_flattenedKeys
216
218
  );
@@ -220,7 +222,6 @@ switch (coreCommand) {
220
222
  await compressCommentsFlow(
221
223
  ignores,
222
224
  reversedFlattenedConfigData,
223
- // NEW
224
225
  composedVariablesExclusives
225
226
  );
226
227
  break;
@@ -229,7 +230,8 @@ switch (coreCommand) {
229
230
  await placeholdersCommentsFlow(
230
231
  configPathIgnores,
231
232
  originalFlattenedConfigData,
232
- aliases_flattenedKeys
233
+ aliases_flattenedKeys,
234
+ path.relative(cwd, mjsPath)
233
235
  );
234
236
  break;
235
237
  default:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "comment-variables",
3
- "version": "1.2.1",
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.4",
33
+ "comment-variables-resolve-config": "^1.14.6",
34
34
  "eslint": "^9.29.0"
35
35
  },
36
36
  "devDependencies": {