comment-variables 0.11.0 → 0.11.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/README.md +38 -18
  2. package/comments.config.js +10 -4
  3. package/library/_commons/utilities/flows.js +8 -11
  4. package/library/_commons/utilities/helpers.js +1 -0
  5. package/package.json +3 -4
package/README.md CHANGED
@@ -28,6 +28,14 @@ Scans your line and block comments for `$COMMENT#*` tokens (like `$COMMENT#COMME
28
28
 
29
29
  _The `compress` and `resolve` commands make each other entirely reversible._
30
30
 
31
+ ### New command: `comment-variables placeholders`
32
+
33
+ ```
34
+ comment-variables placeholders
35
+ ```
36
+
37
+ Creates Comment Variables placeholders right next to the single sources of truth where Comment Variables are defined. (See in config example below.)
38
+
31
39
  ## Flags
32
40
 
33
41
  **The CLI tool also comes with three flags initially:**
@@ -67,41 +75,53 @@ const data = {
67
75
  jsDoc: Object.freeze({
68
76
  definitions: Object.freeze({
69
77
  exitDueToFailure:
70
- "Terminates the whole process with a 'failure' code (1).", // $COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE
78
+ "Terminates the whole process with a 'failure' code (1)." /* $COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE */,
71
79
  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
80
+ "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 */,
73
81
  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
82
+ "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 */,
75
83
  coreCommentsFlow:
76
- "The core flow at the heart of resolving and compressing comments.", // $COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW
84
+ "The core flow at the heart of resolving and compressing comments." /* $COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW */,
77
85
  resolveCommentsFlow:
78
- "The flow that resolves comment variables placeholders into actual comments.", // $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW
86
+ "The flow that resolves `$COMMENT` placeholders into actual comments." /* $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW */,
79
87
  compressCommentsFlow:
80
- "The flow that compresses actual comments into comment variables placeholders.", // $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW
88
+ "The flow that compresses actual comments into `$COMMENT` placeholders." /* $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW */,
89
+ placeholdersCommentsFlow:
90
+ "The flow that creates `$COMMENT` placeholders right next to where they're defined." /* $COMMENT#JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW */,
81
91
  logError:
82
- 'Logs an error to the console depending on its type. (`"error"` or `"warning"`.)', // $COMMENT#JSDOC#DEFINITIONS#LOGERROR
92
+ 'Logs an error to the console depending on its type. (`"error"` or `"warning"`.)' /* $COMMENT#JSDOC#DEFINITIONS#LOGERROR */,
83
93
  }),
84
94
  params: Object.freeze({
85
95
  flattenedConfigData:
86
- "The flattened config data, with comment variables placeholders as keys and actual comments as values.", // $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
96
+ "The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values." /* $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA */,
87
97
  reversedFlattenedConfigData:
88
- "The reversed flattened config data, with actual comments as keys and comment variables placeholders as values.", // $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
98
+ "The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values." /* $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA */,
99
+ aliases_flattenedKeys:
100
+ "The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias." /* $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS */,
89
101
  ruleName:
90
- 'The name of the rule currently used. (Either `"resolve"` or `"compress"`.)', // $COMMENT#JSDOC#PARAMS#RULENAME
102
+ 'The name of the rule currently used. (Either `"resolve"` or `"compress"`.)' /* $COMMENT#JSDOC#PARAMS#RULENAME */,
91
103
  ignores:
92
- "The array of paths and globs for the flow's ESLint instance to ignore.", // $COMMENT#JSDOC#PARAMS#IGNORES
104
+ "The array of paths and globs for the flow's ESLint instance to ignore." /* $COMMENT#JSDOC#PARAMS#IGNORES */,
93
105
  eitherFlattenedConfigData:
94
- "Either the flattened config data or the reversed flattened config data, since they share the same structure.", // $COMMENT#JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA
95
- error: "The error object being handle for the logging.", // $COMMENT#JSDOC#PARAMS#ERROR
96
- options: "The additional options as follows:", // $COMMENT#JSDOC#PARAMS#OPTIONS
97
- settings: "The required settings as follows:", // $COMMENT#JSDOC#PARAMS#SETTINGS
106
+ "Either the flattened config data or the reversed flattened config data, since they share the same structure." /* $COMMENT#JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA */,
107
+ error:
108
+ "The error object being handle for the logging." /* $COMMENT#JSDOC#PARAMS#ERROR */,
109
+ options:
110
+ "The additional options as follows:" /* $COMMENT#JSDOC#PARAMS#OPTIONS */,
111
+ settings:
112
+ "The required settings as follows:" /* $COMMENT#JSDOC#PARAMS#SETTINGS */,
113
+ configPathIgnores:
114
+ '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 */,
115
+ originalFlattenedConfigData:
116
+ "The original flattened config data, before changes to Aliases Variables and Composed Variables are applied." /* $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA */,
98
117
  }),
99
118
  returns: Object.freeze({
100
119
  exitDueToFailure:
101
- "Never. (Somehow typing needs to be explicit for unreachable code inference.)", // $COMMENT#JSDOC#RETURNS#EXITDUETOFAILURE
102
- makeRuleResolve: "The resolve rule based on the flattened config data.", // $COMMENT#JSDOC#RETURNS#MAKERULERESOLVE
120
+ "Never. (Somehow typing needs to be explicit for unreachable code inference.)" /* $COMMENT#JSDOC#RETURNS#EXITDUETOFAILURE */,
121
+ makeRuleResolve:
122
+ "The resolve rule based on the flattened config data." /* $COMMENT#JSDOC#RETURNS#MAKERULERESOLVE */,
103
123
  makeRuleCompress:
104
- "The compress rule based on the reversed flattened config data.", // $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS
124
+ "The compress rule based on the reversed flattened config data." /* $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS */,
105
125
  }),
106
126
  }),
107
127
  };
package/comments.config.js CHANGED
@@ -12,14 +12,14 @@ const data = {
12
12
  otherLevelThree:
13
13
  "LEVELONE#LEVELTWO#LEVELTHREE" /* $COMMENT#LEVELONE#LEVELTWO#LEVELTHREE */, // also an alias
14
14
  composedVariable:
15
- "$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.)
16
- // wrongComposedVariable:
17
- // "$COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE", // errors, can't make composed variables with composed variables
15
+ "$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.
18
16
  composedVariableAlias:
19
17
  "LEVELONE#LEVELTWO#COMPOSEDVARIABLE" /* $COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLEALIAS */,
18
+
19
+ // wrongComposedVariable:
20
+ // "$COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE $COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE", // errors, can't make composed variables with composed variables
20
21
  // wrongComposedVariableToo:
21
22
  // "$COMMENT#LEVELONE#LEVELTWO#STILLLEVELTHREE $COMMENT#LEVELONE#LEVELTWO#COMPOSEDVARIABLE", // errors, can't make composed variables with composed variables even as aliases
22
-
23
23
  // levelthree: "Also level three.", // errors, duplicate normalized key
24
24
  // levelThree: "Also level three.", // errors, duplicate key with original overriden by legal JavaScript object value overrides
25
25
  // alsoLevelThree: "Level three.", // errors, duplicate value
@@ -48,6 +48,8 @@ const data = {
48
48
  "The flow that resolves `$COMMENT` placeholders into actual comments." /* $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW */,
49
49
  compressCommentsFlow:
50
50
  "The flow that compresses actual comments into `$COMMENT` placeholders." /* $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW */,
51
+ placeholdersCommentsFlow:
52
+ "The flow that creates `$COMMENT` placeholders right next to where they're defined." /* $COMMENT#JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW */,
51
53
  logError:
52
54
  'Logs an error to the console depending on its type. (`"error"` or `"warning"`.)' /* $COMMENT#JSDOC#DEFINITIONS#LOGERROR */,
53
55
  }),
@@ -70,6 +72,10 @@ const data = {
70
72
  "The additional options as follows:" /* $COMMENT#JSDOC#PARAMS#OPTIONS */,
71
73
  settings:
72
74
  "The required settings as follows:" /* $COMMENT#JSDOC#PARAMS#SETTINGS */,
75
+ configPathIgnores:
76
+ '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 */,
77
+ originalFlattenedConfigData:
78
+ "The original flattened config data, before changes to Aliases Variables and Composed Variables are applied." /* $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA */,
73
79
  }),
74
80
  returns: Object.freeze({
75
81
  exitDueToFailure:
package/library/_commons/utilities/flows.js CHANGED
@@ -25,7 +25,8 @@ import { ruleNames_makeRules } from "../constants/rules.js";
25
25
  * @param {typeof resolveRuleName | typeof compressRuleName} ruleName $COMMENT#JSDOC#PARAMS#RULENAME
26
26
  * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
27
27
  * @param {{[key: string]: string}} flattenedConfigData $COMMENT#JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA
28
- * @param {Record<string, string> | undefined} aliases_flattenedKeys
28
+ * @param {Record<string, string> | undefined} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
29
+ * @returns
29
30
  */
30
31
  const coreCommentsFlow = async (
31
32
  ruleName,
@@ -106,7 +107,7 @@ const coreCommentsFlow = async (
106
107
  * $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW
107
108
  * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
108
109
  * @param {Record<string, string>} flattenedConfigData $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
109
- * @param {Record<string, string>} aliases_flattenedKeys
110
+ * @param {Record<string, string>} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
110
111
  * @returns
111
112
  */
112
113
  export const resolveCommentsFlow = async (
@@ -137,20 +138,17 @@ export const compressCommentsFlow = async (
137
138
  /* placeholdersCommentsFlow */
138
139
 
139
140
  /**
140
- *
141
- * @param {string[]} configPathIgnores
142
- * @param {{[k: string]: string;}} originalFlattenedConfigData
143
- * @param {Record<string, string>} aliases_flattenedKeys
141
+ * $COMMENT#JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW
142
+ * @param {string[]} configPathIgnores $COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES
143
+ * @param {{[k: string]: string;}} originalFlattenedConfigData $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA
144
+ * @param {Record<string, string>} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
145
+ * @returns
144
146
  */
145
147
  export const placeholdersCommentsFlow = async (
146
148
  configPathIgnores,
147
149
  originalFlattenedConfigData,
148
150
  aliases_flattenedKeys
149
151
  ) => {
150
- /* TEST START
151
- only for the jscomments/comment-variables placeholders command
152
- meaning this should actually be only in the JSComments CLI, */
153
-
154
152
  /** @type {Record<string, string>} */
155
153
  const composedValues_originalKeys = {};
156
154
  /** @type {Record<string, string>} */
@@ -216,5 +214,4 @@ export const placeholdersCommentsFlow = async (
216
214
  console.log(
217
215
  `✅ Made placeholders on ${total} file${total === 1 ? "" : "s"}.`
218
216
  );
219
- /* TEST END */
220
217
  };
package/library/_commons/utilities/helpers.js CHANGED
@@ -11,6 +11,7 @@ export const exitDueToFailure = () => process.exit(1);
11
11
  /**
12
12
  * $COMMENT#JSDOC#DEFINITIONS#LOGERROR
13
13
  * @param {{type: "error" | "warning"; message: string}} error $COMMENT#JSDOC#PARAMS#ERROR
14
+ * @returns
14
15
  */
15
16
  export const logError = (error) => {
16
17
  switch (error.type) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "comment-variables",
3
- "version": "0.11.0",
3
+ "version": "0.11.3",
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,9 +26,8 @@
26
26
  "type": "module",
27
27
  "dependencies": {
28
28
  "@eslint/markdown": "^6.5.0",
29
- "comment-variables-resolve-config": "file:../comment-variables-resolve-config",
30
- "eslint": "^9.29.0",
31
- "zod": "^3.25.67"
29
+ "comment-variables-resolve-config": "^1.7.0",
30
+ "eslint": "^9.29.0"
32
31
  },
33
32
  "devDependencies": {
34
33
  "@typescript-eslint/utils": "^8.34.0"