feat: redesign logging (#1125)

.changeset/happy-glasses-teach.md

@@ -0,0 +1,43 @@
+---
+'style-dictionary': major
+---
+
+BREAKING: Logging has been redesigned a fair bit and is more configurable now.
+
+Before:
+
+```json
+{
+  "log": "error" // 'error' | 'warn'  -> 'warn' is the default value
+}
+```
+
+After:
+
+```json
+{
+  "log": {
+    "warnings": "error", // 'error' | 'warn'  -> 'warn' is the default value
+    "verbosity": "verbose" // 'default' | 'verbose' | 'silent'  -> 'default' is the default value
+  }
+}
+```
+
+Log is now and object and the old "log" option is now "warnings".
+
+This configures whether the following five warnings will be thrown as errors instead of being logged as warnings:
+
+- Token value collisions (in the source)
+- Token name collisions (when exporting)
+- Missing "undo" function for Actions
+- File not created because no tokens found, or all of them filtered out
+- Broken references in file when using outputReferences, but referring to a token that's been filtered out
+
+Verbosity configures whether the following warnings/errors should display in a verbose manner:
+
+- Token collisions of both types (value & name)
+- Broken references due to outputReferences & filters
+- Token reference errors
+
+And it also configures whether success/neutral logs should be logged at all.
+Using "silent" (or --silent in the CLI) means no logs are shown apart from fatal errors.

__integration__/__snapshots__/customFormats.test.snap.js

@@ -469,7 +469,10 @@ snapshots["integration custom formats inline custom with new args should match s
         }
       }
     ],
-    "log": "warn",
+    "log": {
+      "warnings": "warn",
+      "verbosity": "default"
+    },
     "transforms": [
       {
         "type": "attribute"
@@ -962,7 +965,10 @@ snapshots["integration custom formats register custom format with new args shoul
         }
       }
     ],
-    "log": "warn",
+    "log": {
+      "warnings": "warn",
+      "verbosity": "default"
+    },
     "transforms": [
       {
         "type": "attribute"

__integration__/__snapshots__/nameCollisions.test.snap.js

@@ -3,7 +3,7 @@ export const snapshots = {};
 
 snapshots["integration name collisions should warn users of name collisions for flat files"] = 
 `⚠️ __integration__/build/variables.css
-While building variables.css, token collisions were found; output may be unexpected.
+While building variables.css, token collisions were found; output may be unexpected. Ignore this warning if intentional.
 Output name red was generated by:
 color.red   #f00
 color.background.red   #f00
@@ -13,3 +13,10 @@ This many-to-one issue is usually caused by some combination of:
 * overly inclusive file filters`;
 /* end snapshot integration name collisions should warn users of name collisions for flat files */
 
+snapshots["integration name collisions should warn users of name collisions for flat files, brief version"] = 
+`⚠️ __integration__/build/variables.css
+While building variables.css, token collisions were found; output may be unexpected. Ignore this warning if intentional.
+
+Use --verbose or log.verbosity: 'verbose' option for more details`;
+/* end snapshot integration name collisions should warn users of name collisions for flat files, brief version */
+

__integration__/__snapshots__/outputReferences.test.snap.js

@@ -1,9 +1,18 @@
 /* @web/test-runner snapshot v1 */
 export const snapshots = {};
 
-snapshots["integration output references should warn the user if filters out references"] = 
+snapshots["integration output references should warn the user if filters out references briefly"] = 
 `⚠️ __integration__/build/filteredVariables.css
-While building filteredVariables.css, filtered out token references were found; output may be unexpected. Here are the references that are used but not defined in the file
+While building filteredVariables.css, filtered out token references were found; output may be unexpected. Ignore this warning if intentional.
+Here are the references that are used but not defined in the file:
+
+Use --verbose or log.verbosity: 'verbose' option for more details`;
+/* end snapshot integration output references should warn the user if filters out references briefly */
+
+snapshots["integration output references should warn the user if filters out references with a detailed message when using verbose logging"] = 
+`⚠️ __integration__/build/filteredVariables.css
+While building filteredVariables.css, filtered out token references were found; output may be unexpected. Ignore this warning if intentional.
+Here are the references that are used but not defined in the file:
 color.core.neutral.100
 color.core.neutral.0
 color.core.neutral.200
@@ -12,5 +21,5 @@ color.core.orange.0
 color.core.green.0
 color.core.blue.0
 This is caused when combining a filter and \`outputReferences\`.`;
-/* end snapshot integration output references should warn the user if filters out references */
+/* end snapshot integration output references should warn the user if filters out references with a detailed message when using verbose logging */
 

__integration__/logging/__snapshots__/file.test.snap.js

@@ -1,16 +1,40 @@
 /* @web/test-runner snapshot v1 */
 export const snapshots = {};
-snapshots["integration logging file should warn user empty tokens"] = 
+
+snapshots["integration logging file empty tokens should warn user about empty tokens"] = 
 `
 css
 No tokens for empty.css. File not created.`;
-/* end snapshot integration logging file should warn user empty tokens */
+/* end snapshot integration logging file empty tokens should warn user about empty tokens */
+
+snapshots["integration logging file name collisions should warn users briefly of name collisions by default"] = 
+`
+css
+⚠️ __integration__/build/nameCollisions.css
+While building nameCollisions.css, token collisions were found; output may be unexpected. Ignore this warning if intentional.
+
+Use --verbose or log.verbosity: 'verbose' option for more details`;
+/* end snapshot integration logging file name collisions should warn users briefly of name collisions by default */
+
+snapshots["integration logging file name collisions should throw a brief error of name collisions with log level set to error"] = 
+`⚠️ __integration__/build/nameCollisions.css
+While building nameCollisions.css, token collisions were found; output may be unexpected. Ignore this warning if intentional.
+
+Use --verbose or log.verbosity: 'verbose' option for more details`;
+/* end snapshot integration logging file name collisions should throw a brief error of name collisions with log level set to error */
+
+snapshots["integration logging file name collisions should throw a brief error of name collisions with log level set to error on platform level"] = 
+`⚠️ __integration__/build/nameCollisions.css
+While building nameCollisions.css, token collisions were found; output may be unexpected. Ignore this warning if intentional.
+
+Use --verbose or log.verbosity: 'verbose' option for more details`;
+/* end snapshot integration logging file name collisions should throw a brief error of name collisions with log level set to error on platform level */
 
-snapshots["integration logging file should warn user of name collisions"] = 
+snapshots["integration logging file name collisions should warn user of name collisions with a detailed message through \"verbose\" verbosity"] = 
 `
 css
 ⚠️ __integration__/build/nameCollisions.css
-While building nameCollisions.css, token collisions were found; output may be unexpected.
+While building nameCollisions.css, token collisions were found; output may be unexpected. Ignore this warning if intentional.
 Output name 0 was generated by:
 color.core.green.0   #ebf9eb
 color.core.teal.0   #e5f9f5
@@ -183,11 +207,11 @@ This many-to-one issue is usually caused by some combination of:
 * conflicting or similar paths/names in token definitions
 * platform transforms/transformGroups affecting names, especially when removing specificity
 * overly inclusive file filters`;
-/* end snapshot integration logging file should warn user of name collisions */
+/* end snapshot integration logging file name collisions should warn user of name collisions with a detailed message through "verbose" verbosity */
 
-snapshots["integration logging file should not warn user of name collisions with log level set to error"] = 
+snapshots["integration logging file name collisions should throw detailed error of name collisions through \"verbose\" verbosity and log level set to error"] = 
 `⚠️ __integration__/build/nameCollisions.css
-While building nameCollisions.css, token collisions were found; output may be unexpected.
+While building nameCollisions.css, token collisions were found; output may be unexpected. Ignore this warning if intentional.
 Output name 0 was generated by:
 color.core.green.0   #ebf9eb
 color.core.teal.0   #e5f9f5
@@ -360,12 +384,40 @@ This many-to-one issue is usually caused by some combination of:
 * conflicting or similar paths/names in token definitions
 * platform transforms/transformGroups affecting names, especially when removing specificity
 * overly inclusive file filters`;
-/* end snapshot integration logging file should not warn user of name collisions with log level set to error */
-snapshots["integration logging file should warn user of filtered references"] = 
+/* end snapshot integration logging file name collisions should throw detailed error of name collisions through "verbose" verbosity and log level set to error */
+
+snapshots["integration logging file filtered references should warn users briefly of filtered references by default"] = 
+`
+css
+⚠️ __integration__/build/filteredReferences.css
+While building filteredReferences.css, filtered out token references were found; output may be unexpected. Ignore this warning if intentional.
+Here are the references that are used but not defined in the file:
+
+Use --verbose or log.verbosity: 'verbose' option for more details`;
+/* end snapshot integration logging file filtered references should warn users briefly of filtered references by default */
+
+snapshots["integration logging file filtered references should throw a brief error of filtered references with log level set to error"] = 
+`⚠️ __integration__/build/filteredReferences.css
+While building filteredReferences.css, filtered out token references were found; output may be unexpected. Ignore this warning if intentional.
+Here are the references that are used but not defined in the file:
+
+Use --verbose or log.verbosity: 'verbose' option for more details`;
+/* end snapshot integration logging file filtered references should throw a brief error of filtered references with log level set to error */
+
+snapshots["integration logging file filtered references should throw a brief error of filtered references with log level set to error on platform level"] = 
+`⚠️ __integration__/build/filteredReferences.css
+While building filteredReferences.css, filtered out token references were found; output may be unexpected. Ignore this warning if intentional.
+Here are the references that are used but not defined in the file:
+
+Use --verbose or log.verbosity: 'verbose' option for more details`;
+/* end snapshot integration logging file filtered references should throw a brief error of filtered references with log level set to error on platform level */
+
+snapshots["integration logging file filtered references should warn user of filtered references with a detailed message through \"verbose\" verbosity"] = 
 `
 css
 ⚠️ __integration__/build/filteredReferences.css
-While building filteredReferences.css, filtered out token references were found; output may be unexpected. Here are the references that are used but not defined in the file
+While building filteredReferences.css, filtered out token references were found; output may be unexpected. Ignore this warning if intentional.
+Here are the references that are used but not defined in the file:
 color.core.neutral.100
 color.core.neutral.0
 color.core.neutral.200
@@ -374,11 +426,12 @@ color.core.orange.0
 color.core.green.0
 color.core.blue.0
 This is caused when combining a filter and \`outputReferences\`.`;
-/* end snapshot integration logging file should warn user of filtered references */
+/* end snapshot integration logging file filtered references should warn user of filtered references with a detailed message through "verbose" verbosity */
 
-snapshots["integration logging file should not warn user of filtered references with log level set to error"] = 
+snapshots["integration logging file filtered references should throw detailed error of filtered references through \"verbose\" verbosity and log level set to error"] = 
 `⚠️ __integration__/build/filteredReferences.css
-While building filteredReferences.css, filtered out token references were found; output may be unexpected. Here are the references that are used but not defined in the file
+While building filteredReferences.css, filtered out token references were found; output may be unexpected. Ignore this warning if intentional.
+Here are the references that are used but not defined in the file:
 color.core.neutral.100
 color.core.neutral.0
 color.core.neutral.200
@@ -387,5 +440,5 @@ color.core.orange.0
 color.core.green.0
 color.core.blue.0
 This is caused when combining a filter and \`outputReferences\`.`;
-/* end snapshot integration logging file should not warn user of filtered references with log level set to error */
+/* end snapshot integration logging file filtered references should throw detailed error of filtered references through "verbose" verbosity and log level set to error */
 

__integration__/logging/__snapshots__/platform.test.snap.js

@@ -21,7 +21,7 @@ Unknown transformGroup "foo" found in platform "css":
 snapshots["integration logging platform property reference errors should throw and notify users of unknown references"] = 
 `
 Property Reference Errors:
-Reference doesn't exist: color.danger.value tries to reference color.red.value, which is not defined.
+color.danger.value tries to reference color.red.value, which is not defined.
 
 Problems were found when trying to resolve property references`;
 /* end snapshot integration logging platform property reference errors should throw and notify users of unknown references */

__integration__/logging/config.test.js

@@ -51,10 +51,26 @@ describe(`integration >`, () => {
           await expect(consoleOutput).to.matchSnapshot();
         });
 
+        it(`should not log anything if the log verbosity is set to silent`, async () => {
+          const sd = new StyleDictionary({
+            log: {
+              verbosity: 'silent',
+            },
+            source: [
+              // including a specific file twice will throw value collision warnings
+              `__integration__/tokens/size/padding.json`,
+              `__integration__/tokens/size/_padding.json`,
+            ],
+            platforms: {},
+          });
+          await sd.hasInitialized;
+          await expect(stub.callCount).to.equal(0);
+        });
+
         it(`should not show warnings if given higher log level`, async () => {
           const sd = new StyleDictionary(
             {
-              log: `error`,
+              log: { warnings: `error` },
               source: [
                 // including a specific file twice will throw value collision warnings
                 `__integration__/tokens/size/padding.json`,