comment-variables 1.2.1 → 1.2.3

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 +3 -1
  2. package/comments.config.json +38 -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
@@ -45,7 +45,7 @@ const data = {
45
45
  // ownAliasKey: "LEVELONE#LEVELTWO#OWNALIASKEY", // errors, is its own key/alias
46
46
  // key: "key not allowed", // errors, "key", "value" and "placeholder" not allowed
47
47
  // value: "value not allowed", // errors, "key", "value" and "placeholder" not allowed
48
- // placeholder: "placeholder not allowed", // errors, "key", "value" and "placeholder" not allowed
48
+ placeholder: "placeholder now allowed", // doesn't error, "placeholder" is now allowed
49
49
  // noConcat: "no" + "concat", // errors, unrecognized value
50
50
 
51
51
  // already error via regex, but now enhanced:
@@ -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,27 @@
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"
23
+ },
24
+ "placeholder": {
25
+ "value": "placeholder now allowed",
26
+ "key": "LEVELONE#LEVELTWO#PLACEHOLDER"
28
27
  }
29
28
  }
30
29
  },
@@ -32,134 +31,113 @@
32
31
  "definitions": {
33
32
  "exitDueToFailure": {
34
33
  "value": "Terminates the whole process with a 'failure' code (`1`).",
35
- "key": "JSDOC#DEFINITIONS#EXITDUETOFAILURE",
36
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE"
34
+ "key": "JSDOC#DEFINITIONS#EXITDUETOFAILURE"
37
35
  },
38
36
  "makeRuleResolve": {
39
37
  "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"
38
+ "key": "JSDOC#DEFINITIONS#MAKERULERESOLVE"
42
39
  },
43
40
  "makeRuleCompress": {
44
41
  "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"
42
+ "key": "JSDOC#DEFINITIONS#MAKERULECOMPRESS"
47
43
  },
48
44
  "coreCommentsFlow": {
49
45
  "value": "The core flow at the heart of resolving and compressing comments.",
50
- "key": "JSDOC#DEFINITIONS#CORECOMMENTSFLOW",
51
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW"
46
+ "key": "JSDOC#DEFINITIONS#CORECOMMENTSFLOW"
52
47
  },
53
48
  "resolveCommentsFlow": {
54
49
  "value": "The flow that resolves `$COMMENT` placeholders into actual comments.",
55
- "key": "JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW",
56
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW"
50
+ "key": "JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW"
57
51
  },
58
52
  "compressCommentsFlow": {
59
53
  "value": "The flow that compresses actual comments into `$COMMENT` placeholders.",
60
- "key": "JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW",
61
- "placeholder": "$COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW"
54
+ "key": "JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW"
62
55
  },
63
56
  "placeholdersCommentsFlow": {
64
57
  "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"
58
+ "key": "JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW"
67
59
  },
68
60
  "logError": {
69
61
  "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"
62
+ "key": "JSDOC#DEFINITIONS#LOGERROR"
72
63
  }
73
64
  },
74
65
  "params": {
75
66
  "flattenedConfigData": {
76
67
  "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"
68
+ "key": "JSDOC#PARAMS#FLATTENEDCONFIGDATA"
79
69
  },
80
70
  "reversedFlattenedConfigData": {
81
71
  "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"
72
+ "key": "JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA"
84
73
  },
85
74
  "composedVariablesExclusives": {
86
75
  "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"
76
+ "key": "JSDOC#PARAMS#COMPOSEDVARIABLESEXCLUSIVES"
89
77
  },
90
78
  "aliases_flattenedKeys": {
91
79
  "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"
80
+ "key": "JSDOC#PARAMS#ALIASES_FLATTENEDKEYS"
94
81
  },
95
82
  "ruleName": {
96
83
  "value": "The name of the rule currently used. (Either `\"resolve\"` or `\"compress\"`.)",
97
- "key": "JSDOC#PARAMS#RULENAME",
98
- "placeholder": "$COMMENT#JSDOC#PARAMS#RULENAME"
84
+ "key": "JSDOC#PARAMS#RULENAME"
99
85
  },
100
86
  "ignores": {
101
87
  "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"
88
+ "key": "JSDOC#PARAMS#IGNORES"
104
89
  },
105
90
  "eitherFlattenedConfigData": {
106
91
  "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"
92
+ "key": "JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA"
109
93
  },
110
94
  "error": {
111
95
  "value": "The error object being handle for the logging.",
112
- "key": "JSDOC#PARAMS#ERROR",
113
- "placeholder": "$COMMENT#JSDOC#PARAMS#ERROR"
96
+ "key": "JSDOC#PARAMS#ERROR"
114
97
  },
115
98
  "options": {
116
99
  "value": "The additional options as follows:",
117
- "key": "JSDOC#PARAMS#OPTIONS",
118
- "placeholder": "$COMMENT#JSDOC#PARAMS#OPTIONS"
100
+ "key": "JSDOC#PARAMS#OPTIONS"
119
101
  },
120
102
  "settings": {
121
103
  "value": "The required settings as follows:",
122
- "key": "JSDOC#PARAMS#SETTINGS",
123
- "placeholder": "$COMMENT#JSDOC#PARAMS#SETTINGS"
104
+ "key": "JSDOC#PARAMS#SETTINGS"
124
105
  },
125
106
  "configPathIgnores": {
126
107
  "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"
108
+ "key": "JSDOC#PARAMS#CONFIGPATHIGNORES"
129
109
  },
130
110
  "originalFlattenedConfigData": {
131
111
  "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"
112
+ "key": "JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA"
113
+ },
114
+ "relativeMjsPath": {
115
+ "value": "The relative path of the generated `.mjs` file to be ignored in the \"placeholders\" process.",
116
+ "key": "JSDOC#PARAMS#RELATIVEMJSPATH"
134
117
  }
135
118
  },
136
119
  "returns": {
137
120
  "exitDueToFailure": {
138
121
  "value": "Never. (Somehow typing needs to be explicit for unreachable code inference.)",
139
- "key": "JSDOC#RETURNS#EXITDUETOFAILURE",
140
- "placeholder": "$COMMENT#JSDOC#RETURNS#EXITDUETOFAILURE"
122
+ "key": "JSDOC#RETURNS#EXITDUETOFAILURE"
141
123
  },
142
124
  "makeRuleResolve": {
143
125
  "value": "The resolve rule based on the flattened config data.",
144
- "key": "JSDOC#RETURNS#MAKERULERESOLVE",
145
- "placeholder": "$COMMENT#JSDOC#RETURNS#MAKERULERESOLVE"
126
+ "key": "JSDOC#RETURNS#MAKERULERESOLVE"
146
127
  },
147
128
  "makeRuleCompress": {
148
129
  "value": "The compress rule based on the reversed flattened config data.",
149
- "key": "JSDOC#RETURNS#MAKERULECOMPRESS",
150
- "placeholder": "$COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS"
130
+ "key": "JSDOC#RETURNS#MAKERULECOMPRESS"
151
131
  }
152
132
  },
153
133
  "constants": {
154
134
  "sortedReversedFlattenedConfigData": {
155
135
  "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"
136
+ "key": "JSDOC#CONSTANTS#SORTEDREVERSEDFLATTENEDCONFIGDATA"
158
137
  },
159
138
  "composedVariablesExclusivesSet": {
160
139
  "value": "A local Set out of composed variables exclusives for speed.",
161
- "key": "JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET",
162
- "placeholder": "$COMMENT#JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET"
140
+ "key": "JSDOC#CONSTANTS#COMPOSEDVARIABLESEXCLUSIVESSET"
163
141
  }
164
142
  }
165
143
  }
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.3",
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.7",
34
34
  "eslint": "^9.29.0"
35
35
  },
36
36
  "devDependencies": {