Merge pull request #41 from aspear/aspear/explicit-case-convention-support

feat: added explicit control of case conventions in paths, properties and enums

Author: dpopp07

README.md

@@ -95,12 +95,12 @@ console.log(JSON.stringify(validationResults, null, 2));
 Returns a `Promise` with the validation results.
 
 ###### openApiDoc
-Type: `Object`  
+Type: `Object`
 An object that represents an OpenAPI document.
 
 ###### defaultMode
-Type: `boolean`  
-Default: `false`  
+Type: `boolean`
+Default: `false`
 If set to true, the validator will ignore the `.validaterc` file and will use the [configuration defaults](#default-values).
 
 #### Validation results
@@ -205,6 +205,7 @@ The supported rules are described below:
 | --------------------------- | ------------------------------------------------------------------------------------------------------------ | ------ |
 | missing_path_parameter      | For a path that contains path parameters, flag any operations that do not correctly define those parameters. | shared |
 | snake_case_only             | Flag any path segment that does not use snake case.                                                          | shared |
+| paths_case_convention       | Flag any path segment that does not follow a given case convention. snake_case_only must be 'off' to use.    | shared |
 
 ##### [responses][4]
 | Rule                      | Description                                                  | Spec |
@@ -222,6 +223,8 @@ The supported rules are described below:
 | no_property_description     | Flag any schema that contains a 'property' without a `description` field.     | shared   |
 | description_mentions_json   | Flag any schema with a 'property' description that mentions the word 'JSON'.  | shared   |
 | array_of_arrays             | Flag any schema with a 'property' of type `array` with items of type `array`. | shared   |
+| property_case_convention    | Flag any property with a `name` that does not follow a given case convention. snake_case_only must be 'off' to use. | shared |
+| enum_case_convention        | Flag any enum with a `value` that does not follow a given case convention. snake_case_only must be 'off' to use.    | shared |
 
 ##### security_definitions
 | Rule                        | Description                                                                           | Spec   |
@@ -265,9 +268,11 @@ For rules that accept additional configuration, there will be a limited set of a
 | Option           | Description                                              | Example          |
 | ---------------- | -------------------------------------------------------- | ---------------- |
 | lower_snake_case | Words must follow standard lower snake case conventions. | learning_opt_out |
+| upper_snake_case | Words must follow standard upper snake case conventions. | LEARNING_OPT_OUT |
 | upper_camel_case | Words must follow standard upper camel case conventions. | LearningOptOut   |
 | lower_camel_case | Words must follow standard lower camel case conventions. | learningOptOut   |
 | lower_dash_case  | Words must follow standard lower dash case conventions.  | learning-opt-out |
+| upper_dash_case  | Words must follow standard upper dash case conventions.  | LEARNING-OPT-OUT |
 
 ### Configuration file
 
@@ -353,6 +358,7 @@ The default values for each rule are described below.
 | --------------------------- | ------- |
 | missing_path_parameter      | error   |
 | snake_case_only             | warning |
+| paths_case_convention       | off, lower_snake_case |
 
 ##### responses
 | Rule                      | Default |
@@ -379,6 +385,8 @@ The default values for each rule are described below.
 | no_property_description     | warning |
 | description_mentions_json   | warning |
 | array_of_arrays             | warning |
+| property_case_convention    | off, lower_snake_case |
+| enum_case_convention        | off, lower_snake_case |
 
 ###### walker
 | Rule                          | Default |

src/.defaultsForValidator.js

@@ -38,7 +38,8 @@ const defaults = {
     },
     'paths': {
       'missing_path_parameter': 'error',
-      'snake_case_only': 'warning'
+      'snake_case_only': 'warning',
+      'paths_case_convention': ['off', 'lower_snake_case']
     },
     'responses': {
       'inline_response_schema': 'warning'
@@ -56,7 +57,9 @@ const defaults = {
       'no_schema_description': 'warning',
       'no_property_description': 'warning',
       'description_mentions_json': 'warning',
-      'array_of_arrays': 'warning'
+      'array_of_arrays': 'warning',
+      'property_case_convention': [ 'off', 'lower_snake_case'],
+      'enum_case_convention': [ 'off', 'lower_snake_case']
     },
     'walker': {
       'no_empty_descriptions': 'error',
@@ -107,9 +110,11 @@ const deprecated = {
 const configOptions = {
   'case_conventions': [
     'lower_snake_case',
+    'upper_snake_case',
     'upper_camel_case',
     'lower_camel_case',
     'lower_dash_case',
+    'upper_dash_case',
     'operation_id_case'
   ]
 };

src/plugins/utils/caseConventionCheck.js

@@ -6,15 +6,20 @@
 
 */
 const lowerSnakeCase = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+const upperSnakeCase = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$/;
 const upperCamelCase = /^[A-Z][a-z0-9]+([A-Z][a-z0-9]+)*$/;
 const lowerCamelCase = /^[a-z][a-z0-9]*([A-Z][a-z0-9]+)*$/;
 const lowerDashCase = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const upperDashCase = /^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$/;
 
 module.exports = (string, convention) => {
   switch (convention) {
     case 'lower_snake_case':
       return lowerSnakeCase.test(string);
 
+    case 'upper_snake_case':
+      return upperSnakeCase.test(string);
+
     case 'upper_camel_case':
       return upperCamelCase.test(string);
 
@@ -24,6 +29,9 @@ module.exports = (string, convention) => {
     case 'lower_dash_case':
       return lowerDashCase.test(string);
 
+    case 'upper_dash_case':
+      return upperDashCase.test(string);
+
     default:
       // this should never happen, the convention is validated in the config processor
       console.log(`Unsupported case: ${convention}`);

src/plugins/validation/2and3/semantic-validators/paths-ibm.js

@@ -6,6 +6,7 @@
 // Assertation 3. All path segments are lower snake case
 
 const isSnakecase = require('../../../utils/checkSnakeCase');
+const checkCase = require('../../../utils/caseConventionCheck');
 
 module.exports.validate = function({ resolvedSpec }, config) {
   const result = {};
@@ -134,6 +135,31 @@ module.exports.validate = function({ resolvedSpec }, config) {
           });
         }
       });
+    } else {
+      // in the else block because usage of paths_case_convention is mutually
+      // exclusive with usage of config.snake_case_only since it is overlapping
+      // functionality
+      if (config.paths_case_convention) {
+        const checkStatusPath = config.paths_case_convention[0];
+        if (checkStatusPath !== 'off') {
+          const caseConvention = config.paths_case_convention[1];
+          const segments = pathName.split('/');
+          segments.forEach(segment => {
+            // the first element will be "" since pathName starts with "/"
+            // also, ignore validating the path parameters
+            if (segment === '' || segment[0] === '{') {
+              return;
+            }
+            const isCorrectCase = checkCase(segment, caseConvention);
+            if (!isCorrectCase) {
+              result[checkStatusPath].push({
+                path: `paths.${pathName}`,
+                message: `Path segments must follow case convention: ${caseConvention}`
+              });
+            }
+          });
+        }
+      }
     }
   });
 

src/plugins/validation/2and3/semantic-validators/schema-ibm.js

@@ -20,6 +20,7 @@
 const forIn = require('lodash/forIn');
 const includes = require('lodash/includes');
 const isSnakecase = require('../../../utils/checkSnakeCase');
+const checkCase = require('../../../utils/caseConventionCheck');
 const walk = require('../../../utils/walk');
 
 module.exports.validate = function({ jsSpec, isOAS3 }, config) {
@@ -96,6 +97,34 @@ module.exports.validate = function({ jsSpec, isOAS3 }, config) {
       res = checkEnumValues(schema, path, config);
       errors.push(...res.error);
       warnings.push(...res.warning);
+    } else {
+      // optional support for property_case_convention and enum_case_convention
+      // in config.  In the else block because support should be mutually exclusive
+      // with config.snake_case_only since it is overlapping functionality
+      if (config.property_case_convention) {
+        const checkCaseStatus = config.property_case_convention[0];
+        if (checkCaseStatus !== 'off') {
+          res = checkPropNamesCaseConvention(
+            schema,
+            path,
+            config.property_case_convention
+          );
+          errors.push(...res.error);
+          warnings.push(...res.warning);
+        }
+      }
+      if (config.enum_case_convention) {
+        const checkCaseStatus = config.enum_case_convention[0];
+        if (checkCaseStatus !== 'off') {
+          res = checkEnumCaseConvention(
+            schema,
+            path,
+            config.enum_case_convention
+          );
+          errors.push(...res.error);
+          warnings.push(...res.warning);
+        }
+      }
     }
   });
 
@@ -284,6 +313,45 @@ function checkPropNames(schema, contextPath, config) {
   return result;
 }
 
+/**
+ * Check that property names follow the specified case convention
+ * @param schema
+ * @param contextPath
+ * @param caseConvention an array, [0]='off' | 'warning' | 'error'. [1]='lower_snake_case' etc.
+ */
+function checkPropNamesCaseConvention(schema, contextPath, caseConvention) {
+  const result = {};
+  result.error = [];
+  result.warning = [];
+
+  if (!schema.properties) {
+    return result;
+  }
+  if (!caseConvention) {
+    return result;
+  }
+
+  // flag any property whose name does not follow the case convention
+  forIn(schema.properties, (property, propName) => {
+    if (propName.slice(0, 2) === 'x-') return;
+
+    const checkStatus = caseConvention[0] || 'off';
+    if (checkStatus.match('error|warning')) {
+      const caseConventionValue = caseConvention[1];
+
+      const isCorrectCase = checkCase(propName, caseConventionValue);
+      if (!isCorrectCase) {
+        result[checkStatus].push({
+          path: contextPath.concat(['properties', propName]),
+          message: `Property names must follow case convention: ${caseConventionValue}`
+        });
+      }
+    }
+  });
+
+  return result;
+}
+
 function checkEnumValues(schema, contextPath, config) {
   const result = {};
   result.error = [];
@@ -310,6 +378,43 @@ function checkEnumValues(schema, contextPath, config) {
   return result;
 }
 
+/**
+ * Check that enum values follow the specified case convention
+ * @param schema
+ * @param contextPath
+ * @param caseConvention an array, [0]='off' | 'warning' | 'error'. [1]='lower_snake_case' etc.
+ */
+function checkEnumCaseConvention(schema, contextPath, caseConvention) {
+  const result = {};
+  result.error = [];
+  result.warning = [];
+
+  if (!schema.enum) {
+    return result;
+  }
+  if (!caseConvention) {
+    return result;
+  }
+
+  for (let i = 0; i < schema.enum.length; i++) {
+    const enumValue = schema.enum[i];
+
+    const checkStatus = caseConvention[0] || 'off';
+    if (checkStatus.match('error|warning')) {
+      const caseConventionValue = caseConvention[1];
+      const isCorrectCase = checkCase(enumValue, caseConventionValue);
+      if (!isCorrectCase) {
+        result[checkStatus].push({
+          path: contextPath.concat(['enum', i.toString()]),
+          message: `Enum values must follow case convention: ${caseConventionValue}`
+        });
+      }
+    }
+  }
+
+  return result;
+}
+
 // NOTE: this function is Swagger 2 specific and would need to be adapted to be used with OAS
 function isRootSchema(path) {
   const current = path[path.length - 1];

test/plugins/caseConventionCheck.js

@@ -21,6 +21,34 @@ describe('case convention regex tests', function() {
     });
   });
 
+  describe('upper snake case tests', function() {
+    const convention = 'upper_snake_case';
+
+    it('SHA1 is upper snake case', function() {
+      const string = 'SHA1';
+      expect(checkCase(string, convention)).toEqual(true);
+    });
+    it('sha1 is NOT upper snake case', function() {
+      const string = 'sha1';
+      expect(checkCase(string, convention)).toEqual(false);
+    });
+
+    it('good_case_string is NOT upper_snake_case', function() {
+      const string = 'good_case_string';
+      expect(checkCase(string, convention)).toEqual(false);
+    });
+
+    it('GOOD_CASE_STRING is upper_snake_case', function() {
+      const string = 'GOOD_CASE_STRING';
+      expect(checkCase(string, convention)).toEqual(true);
+    });
+
+    it('badCaseString is NOT upper_snake_case', function() {
+      const string = 'badCaseString';
+      expect(checkCase(string, convention)).toEqual(false);
+    });
+  });
+
   describe('upper camel case tests', function() {
     const convention = 'upper_camel_case';
     it('Sha1 is upper camel case', function() {
@@ -84,4 +112,34 @@ describe('case convention regex tests', function() {
       expect(checkCase(string, convention)).toEqual(false);
     });
   });
+  describe('upper dash case tests', function() {
+    const convention = 'upper_dash_case';
+    it('sha1 is NOT upper_dash_case', function() {
+      const string = 'sha1';
+      expect(checkCase(string, convention)).toEqual(false);
+    });
+
+    it('SHA1 is upper_dash_case', function() {
+      const string = 'SHA1';
+      expect(checkCase(string, convention)).toEqual(true);
+    });
+
+    it('bad-case-string is NOT upper_dash_case', function() {
+      const string = 'bad-case-string';
+      expect(checkCase(string, convention)).toEqual(false);
+    });
+    it('GOOD-CASE-STRING is upper_dash_case', function() {
+      const string = 'GOOD-CASE-STRING';
+      expect(checkCase(string, convention)).toEqual(true);
+    });
+
+    it('Bad-Case-String is NOT upper_dash_case', function() {
+      const string = 'Bad-Case-String';
+      expect(checkCase(string, convention)).toEqual(false);
+    });
+    it('badCaseString is NOT upper_dash_case', function() {
+      const string = 'badCaseString';
+      expect(checkCase(string, convention)).toEqual(false);
+    });
+  });
 });