Improved the GS090 and GS100 custom-theme-setting rule wording (#817)

Both rules had passive titles that described the problem rather than
the fix, and bodies that restated the title without pointing at the
actual resolution. Pattern matches the GS110 rewrite shipped in #813.

Author: ErisDS

lib/ast-linter/rules/lint-no-unknown-custom-theme-settings.js

@@ -6,7 +6,7 @@ module.exports = class NoUnknownCustomThemeSettings extends Rule {
             const name = node.parts[1];
             if (!this.isValidCustomThemeSettingReference(name)) {
                 this.log({
-                    message: `Missing Custom Theme Setting: "${name}"`,
+                    message: `Unknown {{@custom.${name}}} on line ${node.loc && node.loc.start.line}: ${this.sourceForNode(node)}`,
                     line: node.loc && node.loc.start.line,
                     column: node.loc && node.loc.start.column,
                     source: this.sourceForNode(node)

lib/checks/100-custom-template-settings-usage.js

@@ -26,12 +26,12 @@ const ruleImplementations = {
             const config = Object.keys(theme.customSettings);
             const notUsedVariable = config.filter(x => !result.customThemeSettings.has(x));
 
-            if (notUsedVariable.length > 0) {
+            notUsedVariable.forEach((name) => {
                 log.failure({
-                    message: `Found unused variables: ${notUsedVariable.map(x => '@custom.' + x).join(', ')}`,
+                    message: `config.custom.${name} is declared but never referenced from a template`,
                     ref: 'package.json'
                 });
-            }
+            });
         }
     }
 };

lib/specs/v4.js

@@ -172,9 +172,9 @@ let rules = {
     },
     'GS090-NO-UNKNOWN-CUSTOM-THEME-SETTINGS': {
         level: 'error',
-        rule: 'An unknown custom theme setting has been used.',
         fatal: false,
-        details: oneLineTrim`The custom theme setting should all be defined in the package.json <code>config.custom</code> object.`
+        rule: 'Remove or correct the unknown <code>{{@custom}}</code> setting',
+        details: oneLineTrim`Every <code>{{@custom.<i>name</i>}}</code> reference in a template needs a matching entry in <code>config.custom</code> in <code>package.json</code>. An unrecognised setting renders as empty. See the <a href="${docsBaseUrl}custom-settings/" target=_blank>custom settings documentation</a> for details.`
     },
     'GS090-NO-UNKNOWN-CUSTOM-THEME-SELECT-VALUE-IN-MATCH': {
         level: 'error',
@@ -209,8 +209,8 @@ let rules = {
 
     'GS100-NO-UNUSED-CUSTOM-THEME-SETTING': {
         level: 'error',
-        rule: 'A custom theme setting defined in <code>package.json</code> hasn\'t been used in any theme file.',
-        details: oneLineTrim`Custom theme settings defined in <code>package.json</code> must be used at least once in the theme templates.`
+        rule: 'Use or remove the unused <code>config.custom</code> setting',
+        details: oneLineTrim`A setting declared in <code>config.custom</code> in <code>package.json</code> appears in the admin Customize panel but has no effect unless referenced from a template with <code>{{@custom.<i>name</i>}}</code>. Either use the setting from a template or drop it from <code>package.json</code>. See the <a href="${docsBaseUrl}custom-settings/" target=_blank>custom settings documentation</a> for details.`
     },
 
     'GS050-CSS-KGCO': cssCardRule('callout', 'kg-callout-card'),

test/100-custom-template-settings-usage.test.js

@@ -21,8 +21,9 @@ describe('100 custom template settings usage', function () {
                 expect(Object.keys(output.results.fail)).toEqual(['GS100-NO-UNUSED-CUSTOM-THEME-SETTING']);
 
                 utils.assertValidFailObject(output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING']);
-                expect(output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING'].failures[0].message).toMatch(/color_scheme/);
-                expect(output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING'].failures[0].message).toMatch(/show_logo/);
+                const messages = output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING'].failures.map(f => f.message);
+                expect(messages.some(m => /color_scheme/.test(m))).toBe(true);
+                expect(messages.some(m => /show_logo/.test(m))).toBe(true);
 
             });
         });
@@ -99,8 +100,9 @@ describe('100 custom template settings usage', function () {
                 expect(Object.keys(output.results.fail)).toEqual(['GS100-NO-UNUSED-CUSTOM-THEME-SETTING']);
 
                 utils.assertValidFailObject(output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING']);
-                expect(output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING'].failures[0].message).toMatch(/color_scheme/);
-                expect(output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING'].failures[0].message).toMatch(/show_logo/);
+                const messages = output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING'].failures.map(f => f.message);
+                expect(messages.some(m => /color_scheme/.test(m))).toBe(true);
+                expect(messages.some(m => /show_logo/.test(m))).toBe(true);
 
             });
         });
@@ -177,8 +179,9 @@ describe('100 custom template settings usage', function () {
                 expect(Object.keys(output.results.fail)).toEqual(['GS100-NO-UNUSED-CUSTOM-THEME-SETTING']);
 
                 utils.assertValidFailObject(output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING']);
-                expect(output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING'].failures[0].message).toMatch(/color_scheme/);
-                expect(output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING'].failures[0].message).toMatch(/show_logo/);
+                const messages = output.results.fail['GS100-NO-UNUSED-CUSTOM-THEME-SETTING'].failures.map(f => f.message);
+                expect(messages.some(m => /color_scheme/.test(m))).toBe(true);
+                expect(messages.some(m => /show_logo/.test(m))).toBe(true);
 
             });
         });