comment-variables 0.8.1 → 0.10.0

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 (7) hide show
  1. package/README.md +6 -6
  2. package/comments.config.js +14 -8
  3. package/library/_commons/rules/compress.js +2 -2
  4. package/library/_commons/rules/resolve.js +9 -6
  5. package/library/_commons/utilities/flows.js +26 -7
  6. package/library/index.js +7 -1
  7. package/package.json +2 -2
package/README.md CHANGED
@@ -69,23 +69,23 @@ const data = {
69
69
  exitDueToFailure:
70
70
  "Terminates the whole process with a 'failure' code (1).", // $COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE
71
71
  makeRuleResolve:
72
- "The utility that creates the resolve rule based on the flattened config data, used to transform $COMMENT#* placeholders into actual comments.", // $COMMENT#JSDOC#DEFINITIONS#MAKERULERESOLVE
72
+ "The utility that creates the resolve rule based on the flattened config data, used to transform comment variables placeholders into actual comments.", // $COMMENT#JSDOC#DEFINITIONS#MAKERULERESOLVE
73
73
  makeRuleCompress:
74
- "The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into $COMMENT#* placeholders.", // $COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS
74
+ "The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into comment variables placeholders.", // $COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS
75
75
  coreCommentsFlow:
76
76
  "The core flow at the heart of resolving and compressing comments.", // $COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW
77
77
  resolveCommentsFlow:
78
- "The flow that resolves $COMMENT#* placeholders intro actual comments.", // $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW
78
+ "The flow that resolves comment variables placeholders into actual comments.", // $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW
79
79
  compressCommentsFlow:
80
- "The flow that compresses actual comments into $COMMENT#* placeholders.", // $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW
80
+ "The flow that compresses actual comments into comment variables placeholders.", // $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW
81
81
  logError:
82
82
  'Logs an error to the console depending on its type. (`"error"` or `"warning"`.)', // $COMMENT#JSDOC#DEFINITIONS#LOGERROR
83
83
  }),
84
84
  params: Object.freeze({
85
85
  flattenedConfigData:
86
- "The flattened config data, with $COMMENT#* placeholders as keys and actual comments as values.", // $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
86
+ "The flattened config data, with comment variables placeholders as keys and actual comments as values.", // $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
87
87
  reversedFlattenedConfigData:
88
- "The reversed flattened config data, with actual comments as keys and $COMMENT#* placeholders as values.", // $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
88
+ "The reversed flattened config data, with actual comments as keys and comment variables placeholders as values.", // $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
89
89
  ruleName:
90
90
  'The name of the rule currently used. (Either `"resolve"` or `"compress"`.)', // $COMMENT#JSDOC#PARAMS#RULENAME
91
91
  ignores:
package/comments.config.js CHANGED
@@ -2,14 +2,20 @@ const data = {
2
2
  // for testing
3
3
  levelOne: {
4
4
  levelTwo: {
5
- levelThree: "Level three.",
5
+ levelThree: "Level three.", // $COMMENT#LEVELONE#LEVELTWO#LEVELTHREE
6
+ stillLevelThree: "LEVELONE#LEVELTWO#LEVELTHREE", // now is an alias // $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE
7
+ otherLevelThree: "LEVELONE#LEVELTWO#LEVELTHREE", // also an alias // $COMMENT#LEVELONE#LEVELTWO#OTHERLEVELTHREE
8
+ composedVariable:
9
+ "$COMMENT#LEVELONE#LEVELTWO#LEVELTHREE $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE", // $COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE // This is a composed variable. What's the beauty in this? It allows for each comment variable to be its own single source of truth that can be reused still within the Comment Variables ecosystem. All while preventing the use of comment variables placeholders as values in the config. AND as a matter of fact, it even works... with aliases. (Personal note: And that part is free and included in the CLI tool.)
10
+ // wrongComposedVariable:
11
+ // "$COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE", // errors, can't make composed variables with composed variables
6
12
  // levelthree: "Also level three.", // errors, duplicate normalized key
7
- // stillLevelThree: "LEVELONE#LEVELTWO#LEVELTHREE", // errors, value is also a normalized key
8
13
  // alsoLevelThree: "Level three.", // errors, duplicate value
9
14
  // tooLevelThree: 2, // errors, value is invalid
10
15
  // $levelThree: "Dollar sign", // errors, key as "$" character
11
16
  // "#levelThree": "Hashtag", // errors, key as "#" character
12
17
  // ".levelThree": "Punctuation", // errors, key is invalid
18
+ // unrecognized: `Unrecognized value.`, // errors, is not a string literal
13
19
  },
14
20
  },
15
21
  // for deving
@@ -18,23 +24,23 @@ const data = {
18
24
  exitDueToFailure:
19
25
  "Terminates the whole process with a 'failure' code (1).", // $COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE
20
26
  makeRuleResolve:
21
- "The utility that creates the resolve rule based on the flattened config data, used to transform $COMMENT#* placeholders into actual comments.", // $COMMENT#JSDOC#DEFINITIONS#MAKERULERESOLVE
27
+ "The utility that creates the resolve rule based on the flattened config data, used to transform $COMMENT placeholders into actual comments.", // $COMMENT#JSDOC#DEFINITIONS#MAKERULERESOLVE
22
28
  makeRuleCompress:
23
- "The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into $COMMENT#* placeholders.", // $COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS
29
+ "The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into $COMMENT placeholders.", // $COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS
24
30
  coreCommentsFlow:
25
31
  "The core flow at the heart of resolving and compressing comments.", // $COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW
26
32
  resolveCommentsFlow:
27
- "The flow that resolves $COMMENT#* placeholders intro actual comments.", // $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW
33
+ "The flow that resolves $COMMENT placeholders into actual comments.", // $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW
28
34
  compressCommentsFlow:
29
- "The flow that compresses actual comments into $COMMENT#* placeholders.", // $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW
35
+ "The flow that compresses actual comments into $COMMENT placeholders.", // $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW
30
36
  logError:
31
37
  'Logs an error to the console depending on its type. (`"error"` or `"warning"`.)', // $COMMENT#JSDOC#DEFINITIONS#LOGERROR
32
38
  }),
33
39
  params: Object.freeze({
34
40
  flattenedConfigData:
35
- "The flattened config data, with $COMMENT#* placeholders as keys and actual comments as values.", // $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
41
+ "The flattened config data, with $COMMENT placeholders as keys and actual comments as values.", // $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
36
42
  reversedFlattenedConfigData:
37
- "The reversed flattened config data, with actual comments as keys and $COMMENT#* placeholders as values.", // $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
43
+ "The reversed flattened config data, with actual comments as keys and $COMMENT placeholders as values.", // $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
38
44
  ruleName:
39
45
  'The name of the rule currently used. (Either `"resolve"` or `"compress"`.)', // $COMMENT#JSDOC#PARAMS#RULENAME
40
46
  ignores:
package/library/_commons/rules/compress.js CHANGED
@@ -5,8 +5,8 @@ import {
5
5
  } from "comment-variables-resolve-config";
6
6
 
7
7
  /**
8
- * The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into $COMMENT#* placeholders.
9
- * @param {{[key: string]: string}} reversedFlattenedConfigData The reversed flattened config data, with actual comments as keys and $COMMENT#* placeholders as values.
8
+ * The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into $COMMENT placeholders.
9
+ * @param {{[key: string]: string}} reversedFlattenedConfigData The reversed flattened config data, with actual comments as keys and $COMMENT placeholders as values.
10
10
  * @returns The compress rule based on the reversed flattened config data.
11
11
  */
12
12
  const makeRule = (reversedFlattenedConfigData) => {
package/library/_commons/rules/resolve.js CHANGED
@@ -1,14 +1,15 @@
1
1
  import {
2
- flattenedConfigPlaceholderRegex,
2
+ flattenedConfigPlaceholderGlobalRegex,
3
3
  placeholderMessageId,
4
4
  } from "comment-variables-resolve-config";
5
5
 
6
6
  /**
7
- * The utility that creates the resolve rule based on the flattened config data, used to transform $COMMENT#* placeholders into actual comments.
8
- * @param {{[key: string]: string}} flattenedConfigData The flattened config data, with $COMMENT#* placeholders as keys and actual comments as values.
7
+ * The utility that creates the resolve rule based on the flattened config data, used to transform $COMMENT placeholders into actual comments.
8
+ * @param {{[key: string]: string}} flattenedConfigData The flattened config data, with $COMMENT placeholders as keys and actual comments as values.
9
+ * @param {{[key: string]: string}} aliases_flattenedKeys
9
10
  * @returns The resolve rule based on the flattened config data.
10
11
  */
11
- const makeRule = (flattenedConfigData) => {
12
+ const makeRule = (flattenedConfigData, aliases_flattenedKeys) => {
12
13
  /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */
13
14
  const rule = {
14
15
  meta: {
@@ -32,7 +33,7 @@ const makeRule = (flattenedConfigData) => {
32
33
 
33
34
  for (const comment of comments) {
34
35
  const matches = [
35
- ...comment.value.matchAll(flattenedConfigPlaceholderRegex),
36
+ ...comment.value.matchAll(flattenedConfigPlaceholderGlobalRegex),
36
37
  ];
37
38
 
38
39
  if (matches.length === 0) continue;
@@ -43,7 +44,9 @@ const makeRule = (flattenedConfigData) => {
43
44
  for (const match of matches) {
44
45
  const fullMatch = match[0]; // e.g. $COMMENT#LEVELONE#LEVELTWO
45
46
  const key = match[1]; // e.g. LEVELONE#LEVELTWO
46
- const replacement = flattenedConfigData[key];
47
+ const replacement =
48
+ flattenedConfigData[key] || // original
49
+ flattenedConfigData[aliases_flattenedKeys?.[key]]; // alias
47
50
 
48
51
  if (replacement) {
49
52
  fixedText = fixedText.replace(fullMatch, replacement);
package/library/_commons/utilities/flows.js CHANGED
@@ -22,8 +22,14 @@ import { ruleNames_makeRules } from "../constants/rules.js";
22
22
  * @param {typeof resolveRuleName | typeof compressRuleName} ruleName The name of the rule currently used. (Either `"resolve"` or `"compress"`.)
23
23
  * @param {string[]} ignores The array of paths and globs for the flow's ESLint instance to ignore.
24
24
  * @param {{[key: string]: string}} flattenedConfigData Either the flattened config data or the reversed flattened config data, since they share the same structure.
25
+ * @param {{[key: string]: string} | undefined} aliases_flattenedKeys
25
26
  */
26
- const coreCommentsFlow = async (ruleName, ignores, flattenedConfigData) => {
27
+ const coreCommentsFlow = async (
28
+ ruleName,
29
+ ignores,
30
+ flattenedConfigData,
31
+ aliases_flattenedKeys
32
+ ) => {
27
33
  const eslint = new ESLint({
28
34
  fix: true,
29
35
  errorOnUnmatchedPattern: false,
@@ -36,7 +42,10 @@ const coreCommentsFlow = async (ruleName, ignores, flattenedConfigData) => {
36
42
  plugins: {
37
43
  [commentVariablesPluginName]: {
38
44
  rules: {
39
- [ruleName]: ruleNames_makeRules[ruleName](flattenedConfigData),
45
+ [ruleName]: ruleNames_makeRules[ruleName](
46
+ flattenedConfigData,
47
+ aliases_flattenedKeys
48
+ ),
40
49
  },
41
50
  },
42
51
  },
@@ -91,20 +100,30 @@ const coreCommentsFlow = async (ruleName, ignores, flattenedConfigData) => {
91
100
  /* resolveCommentsFlow */
92
101
 
93
102
  /**
94
- * The flow that resolves $COMMENT#* placeholders intro actual comments.
103
+ * The flow that resolves $COMMENT placeholders into actual comments.
95
104
  * @param {string[]} ignores The array of paths and globs for the flow's ESLint instance to ignore.
96
- * @param {{[key: string]: string}} flattenedConfigData The flattened config data, with $COMMENT#* placeholders as keys and actual comments as values.
105
+ * @param {{[key: string]: string}} flattenedConfigData The flattened config data, with $COMMENT placeholders as keys and actual comments as values.
106
+ * @param {{[key: string]: string}} aliases_flattenedKeys
97
107
  * @returns
98
108
  */
99
- export const resolveCommentsFlow = async (ignores, flattenedConfigData) =>
100
- coreCommentsFlow(resolveRuleName, ignores, flattenedConfigData);
109
+ export const resolveCommentsFlow = async (
110
+ ignores,
111
+ flattenedConfigData,
112
+ aliases_flattenedKeys
113
+ ) =>
114
+ coreCommentsFlow(
115
+ resolveRuleName,
116
+ ignores,
117
+ flattenedConfigData,
118
+ aliases_flattenedKeys
119
+ );
101
120
 
102
121
  /* compressCommentsFlow */
103
122
 
104
123
  /**
105
124
  * The flow that compresses actual comments into $COMMENT#* placeholders.
106
125
  * @param {string[]} ignores The array of paths and globs for the flow's ESLint instance to ignore.
107
- * @param {{[key: string]: string}} reversedFlattenedConfigData The reversed flattened config data, with actual comments as keys and $COMMENT#* placeholders as values.
126
+ * @param {{[key: string]: string}} reversedFlattenedConfigData The reversed flattened config data, with actual comments as keys and $COMMENT placeholders as values.
108
127
  * @returns
109
128
  */
110
129
  export const compressCommentsFlow = async (
package/library/index.js CHANGED
@@ -76,6 +76,7 @@ const {
76
76
  config,
77
77
  flattenedConfigData,
78
78
  reversedFlattenedConfigData,
79
+ aliases_flattenedKeys,
79
80
  configPath,
80
81
  passedIgnores,
81
82
  rawConfigAndImportPaths,
@@ -88,6 +89,7 @@ skipDetails ||
88
89
  "Reversed flattened config data is:",
89
90
  reversedFlattenedConfigData
90
91
  );
92
+ skipDetails || console.log("Aliases are:", aliases_flattenedKeys);
91
93
  skipDetails || console.log("Config path is:", configPath);
92
94
  skipDetails || console.log("Passed ignores are:", passedIgnores);
93
95
 
@@ -122,7 +124,11 @@ skipDetails || console.log("Ignores are:", ignores);
122
124
  switch (coreCommand) {
123
125
  case resolveRuleName:
124
126
  console.log(`Running ${resolveRuleName}...`);
125
- await resolveCommentsFlow(ignores, flattenedConfigData);
127
+ await resolveCommentsFlow(
128
+ ignores,
129
+ flattenedConfigData,
130
+ aliases_flattenedKeys
131
+ );
126
132
  break;
127
133
  case compressRuleName:
128
134
  console.log(`Running ${compressRuleName}...`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "comment-variables",
3
- "version": "0.8.1",
3
+ "version": "0.10.0",
4
4
  "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
5
5
  "bin": {
6
6
  "jscomments": "./library/index.js",
@@ -26,7 +26,7 @@
26
26
  "type": "module",
27
27
  "dependencies": {
28
28
  "@eslint/markdown": "^6.5.0",
29
- "comment-variables-resolve-config": "^1.3.2",
29
+ "comment-variables-resolve-config": "^1.6.0",
30
30
  "eslint": "^9.29.0",
31
31
  "zod": "^3.25.67"
32
32
  },