fix(metadata): consistenct use of 'must' and 'should' (#2770)

build/tasks/validate.js

@@ -235,20 +235,27 @@ function createSchemas() {
   return schemas;
 }
 
-function validateFiles(grunt, files, schema) {
+function validateFiles(grunt, files, schema, type) {
   var valid = true;
   files.forEach(function(f) {
     f.src.forEach(function(pathArg) {
       var file = grunt.file.readJSON(pathArg);
       file._path = pathArg;
       var result = revalidator(file, schema);
-
       if (!result.valid) {
         result.errors.forEach(function(err) {
           grunt.log.error(pathArg, err.property + ' ' + err.message);
         });
         valid = false;
-      } else {
+      }
+
+      const ruleIssues = type === 'rule' ? validateRule(file) : [];
+      if (ruleIssues.length > 0) {
+        ruleIssues.forEach(issue => grunt.log.error(pathArg, issue));
+        valid = false;
+      }
+
+      if (valid) {
         grunt.verbose.ok();
       }
     });
@@ -261,17 +268,38 @@ module.exports = function(grunt) {
     'validate',
     'Task for validating API schema for checks and rules',
     function() {
-      var schemas = createSchemas();
-      var options = this.options();
-      if (!options.type || !schemas[options.type]) {
+      const { type } = this.options();
+      const schemas = createSchemas();
+      const schema = schemas[type];
+      if (!schema) {
         grunt.log.error(
           'Please specify a valid type to validate: ' + Object.keys(schemas)
         );
         return false;
       }
-      const valid = validateFiles(grunt, this.files, schemas[options.type]);
-      schemas[options.type].seen = {};
+      const valid = validateFiles(grunt, this.files, schema, type);
+      schema.seen = {};
       return valid;
     }
   );
 };
+
+function validateRule({ tags, metadata }) {
+  if (!Array.isArray(tags) || typeof metadata !== 'object') {
+    return [];
+  }
+  const issues = [];
+  const prohibitedWord = tags.includes('best-practice') ? 'must' : 'should';
+  const { description, help } = metadata;
+
+  if (description.toLowerCase().includes(prohibitedWord)) {
+    issues.push(
+      `metadata.description can not contain the word '${prohibitedWord}'.`
+    );
+  }
+
+  if (help.toLowerCase().includes(prohibitedWord)) {
+    issues.push(`metadata.help can not contain the word '${prohibitedWord}'.`);
+  }
+  return issues;
+}

lib/rules/accesskeys.json

@@ -5,7 +5,7 @@
   "tags": ["cat.keyboard", "best-practice"],
   "metadata": {
     "description": "Ensures every accesskey attribute value is unique",
-    "help": "accesskey attribute value must be unique"
+    "help": "accesskey attribute value should be unique"
   },
   "all": [],
   "any": [],

lib/rules/aria-allowed-role.json

@@ -6,7 +6,7 @@
   "tags": ["cat.aria", "best-practice"],
   "metadata": {
     "description": "Ensures role attribute has an appropriate value for the element",
-    "help": "ARIA role must be appropriate for the element"
+    "help": "ARIA role should be appropriate for the element"
   },
   "all": [],
   "any": ["aria-allowed-role"],

lib/rules/aria-dialog-name.json

@@ -5,7 +5,7 @@
   "tags": ["cat.aria", "best-practice"],
   "metadata": {
     "description": "Ensures every ARIA dialog and alertdialog node has an accessible name",
-    "help": "ARIA dialog and alertdialog nodes must have an accessible name"
+    "help": "ARIA dialog and alertdialog nodes should have an accessible name"
   },
   "all": [],
   "any": ["aria-label", "aria-labelledby", "non-empty-title"],

lib/rules/aria-treeitem-name.json

@@ -5,7 +5,7 @@
   "tags": ["cat.aria", "best-practice"],
   "metadata": {
     "description": "Ensures every ARIA treeitem node has an accessible name",
-    "help": "ARIA treeitem nodes must have an accessible name"
+    "help": "ARIA treeitem nodes should have an accessible name"
   },
   "all": [],
   "any": [

lib/rules/empty-heading.json

@@ -6,7 +6,7 @@
   "impact": "minor",
   "metadata": {
     "description": "Ensures headings have discernible text",
-    "help": "Headings must not be empty"
+    "help": "Headings should not be empty"
   },
   "all": [],
   "any": [

lib/rules/form-field-multiple-labels.json

@@ -5,7 +5,7 @@
   "tags": ["cat.forms", "wcag2a", "wcag332"],
   "metadata": {
     "description": "Ensures form field does not have multiple label elements",
-    "help": "Form field should not have multiple label elements"
+    "help": "Form field must not have multiple label elements"
   },
   "all": [],
   "any": [],

lib/rules/frame-tested.json

@@ -4,7 +4,7 @@
   "tags": ["cat.structure", "review-item", "best-practice"],
   "metadata": {
     "description": "Ensures <iframe> and <frame> elements contain the axe-core script",
-    "help": "Frames must be tested with axe-core"
+    "help": "Frames should be tested with axe-core"
   },
   "all": ["frame-tested"],
   "any": [],

lib/rules/frame-title-unique.json

@@ -5,7 +5,7 @@
   "tags": ["cat.text-alternatives", "best-practice"],
   "metadata": {
     "description": "Ensures <iframe> and <frame> elements contain a unique title attribute",
-    "help": "Frames must have a unique title attribute"
+    "help": "Frames should have a unique title attribute"
   },
   "all": [],
   "any": [],

lib/rules/landmark-banner-is-top-level.json

@@ -5,7 +5,7 @@
   "tags": ["cat.semantics", "best-practice"],
   "metadata": {
     "description": "Ensures the banner landmark is at top level",
-    "help": "Banner landmark must not be contained in another landmark"
+    "help": "Banner landmark should not be contained in another landmark"
   },
   "all": [],
   "any": ["landmark-is-top-level"],

lib/rules/landmark-complementary-is-top-level.json

@@ -4,7 +4,7 @@
   "tags": ["cat.semantics", "best-practice"],
   "metadata": {
     "description": "Ensures the complementary landmark or aside is at top level",
-    "help": "Aside must not be contained in another landmark"
+    "help": "Aside should not be contained in another landmark"
   },
   "all": [],
   "any": ["landmark-is-top-level"],

lib/rules/landmark-contentinfo-is-top-level.json

@@ -5,7 +5,7 @@
   "tags": ["cat.semantics", "best-practice"],
   "metadata": {
     "description": "Ensures the contentinfo landmark is at top level",
-    "help": "Contentinfo landmark must not be contained in another landmark"
+    "help": "Contentinfo landmark should not be contained in another landmark"
   },
   "all": [],
   "any": ["landmark-is-top-level"],

lib/rules/landmark-main-is-top-level.json

@@ -4,7 +4,7 @@
   "tags": ["cat.semantics", "best-practice"],
   "metadata": {
     "description": "Ensures the main landmark is at top level",
-    "help": "Main landmark must not be contained in another landmark"
+    "help": "Main landmark should not be contained in another landmark"
   },
   "all": [],
   "any": ["landmark-is-top-level"],

lib/rules/landmark-no-duplicate-banner.json

@@ -4,7 +4,7 @@
   "tags": ["cat.semantics", "best-practice"],
   "metadata": {
     "description": "Ensures the document has at most one banner landmark",
-    "help": "Document must not have more than one banner landmark"
+    "help": "Document should not have more than one banner landmark"
   },
   "all": [],
   "any": ["page-no-duplicate-banner"],

lib/rules/landmark-no-duplicate-contentinfo.json

@@ -4,7 +4,7 @@
   "tags": ["cat.semantics", "best-practice"],
   "metadata": {
     "description": "Ensures the document has at most one contentinfo landmark",
-    "help": "Document must not have more than one contentinfo landmark"
+    "help": "Document should not have more than one contentinfo landmark"
   },
   "all": [],
   "any": ["page-no-duplicate-contentinfo"],

lib/rules/landmark-no-duplicate-main.json

@@ -4,7 +4,7 @@
   "tags": ["cat.semantics", "best-practice"],
   "metadata": {
     "description": "Ensures the document has at most one main landmark",
-    "help": "Document must not have more than one main landmark"
+    "help": "Document should not have more than one main landmark"
   },
   "all": [],
   "any": ["page-no-duplicate-main"],

lib/rules/landmark-one-main.json

@@ -4,7 +4,7 @@
   "tags": ["cat.semantics", "best-practice"],
   "metadata": {
     "description": "Ensures the document has a main landmark",
-    "help": "Document must have one main landmark"
+    "help": "Document should have one main landmark"
   },
   "all": ["page-has-main"],
   "any": [],

lib/rules/landmark-unique.json

@@ -4,7 +4,7 @@
   "tags": ["cat.semantics", "best-practice"],
   "metadata": {
     "help": "Ensures landmarks are unique",
-    "description": "Landmarks must have a unique role or role/label/title (i.e. accessible name) combination"
+    "description": "Landmarks should have a unique role or role/label/title (i.e. accessible name) combination"
   },
   "matches": "landmark-unique-matches",
   "all": [],

lib/rules/meta-viewport.json

@@ -5,7 +5,7 @@
   "tags": ["cat.sensory-and-visual-cues", "best-practice", "ACT"],
   "metadata": {
     "description": "Ensures <meta name=\"viewport\"> does not disable text scaling and zooming",
-    "help": "Zooming and scaling must not be disabled"
+    "help": "Zooming and scaling should not be disabled"
   },
   "all": [],
   "any": ["meta-viewport"],

lib/rules/page-has-heading-one.json

@@ -4,7 +4,7 @@
   "tags": ["cat.semantics", "best-practice"],
   "metadata": {
     "description": "Ensure that the page, or at least one of its frames contains a level-one heading",
-    "help": "Page must contain a level-one heading"
+    "help": "Page should contain a level-one heading"
   },
   "all": ["page-has-heading-one"],
   "any": [],

lib/rules/region.json

@@ -4,7 +4,7 @@
   "tags": ["cat.keyboard", "best-practice"],
   "metadata": {
     "description": "Ensures all page content is contained by landmarks",
-    "help": "All page content must be contained by landmarks"
+    "help": "All page content should be contained by landmarks"
   },
   "all": [],
   "any": ["region"],

lib/rules/scrollable-region-focusable.json

@@ -3,7 +3,7 @@
   "matches": "scrollable-region-focusable-matches",
   "tags": ["cat.keyboard", "wcag2a", "wcag211"],
   "metadata": {
-    "description": "Elements that have scrollable content should be accessible by keyboard",
+    "description": "Elements that have scrollable content must be accessible by keyboard",
     "help": "Ensure that scrollable region has keyboard access"
   },
   "all": [],

lib/rules/table-fake-caption.json

@@ -12,7 +12,7 @@
   ],
   "metadata": {
     "description": "Ensure that tables with a caption use the <caption> element.",
-    "help": "Data or header cells should not be used to give caption to a data table."
+    "help": "Data or header cells must not be used to give caption to a data table."
   },
   "all": ["caption-faked"],
   "any": [],