From f6fc061ca43909b879ed131a61de561b4e378d75 Mon Sep 17 00:00:00 2001
From: DwDMadMac <anthonymmacallister@gmail.com>
Date: Wed, 4 Oct 2023 00:59:32 -0400
Subject: [PATCH 01/10] Refactor and Extend jsonapi-query-parameters Test Suite

Details:

This commit encompasses a comprehensive refactoring and extension of the test suite for the jsonapi-query-parameters ruleset. The following changes have been made:

1. **Common Setup**: Moved the common setup logic into a `beforeEach` block to avoid redundancy. The Spectral ruleset is now set up once for all test cases.

    - Original: Separate Spectral object initialization in each test case.
    - Current: Unified Spectral object initialization in `beforeEach`.

2. **Async/Await**: Replaced callback-based asynchronous code with `async/await` for better readability and error handling.

    - Original: Used `done()` callbacks.
    - Current: Using `async/await`.

3. **Parameterized Test Cases**: Introduced parameterized test cases for different scenarios, making the test suite more exhaustive.

    - Original: Limited test cases with less coverage for edge cases.
    - Current: Added test cases for valid and invalid query parameters, including special characters and numbers.

4. **Error Handling**: Improved error handling by throwing errors and providing detailed error messages.

    - Original: Used `done(error)` for error handling.
    - Current: Using `throw new Error(error)`.

5. **Error Verification**: Added checks for error codes and severity levels, ensuring that the right types of errors are being thrown.

    - Original: Only checked the length of the results array.
    - Current: Checks for specific error codes and severity levels.

6. **Code Comments**: Added comments to describe the purpose and context of each test case.

    - Original: Minimal comments.
    - Current: Detailed comments explaining what each test case is doing and why.

7. **Code Formatting**: Improved code formatting and structure for better readability.

    - Original: Less structured code.
    - Current: Well-structured and formatted code.

By making these changes, the test suite is now more robust, easier to understand, and covers more edge cases. This sets a strong foundation for future development and debugging.
---
 test/jsonapi-query-parameters.test.js | 368 ++++++++++++--------------
 1 file changed, 166 insertions(+), 202 deletions(-)

diff --git a/test/jsonapi-query-parameters.test.js b/test/jsonapi-query-parameters.test.js
index 154cb34..4ff9c65 100644
--- a/test/jsonapi-query-parameters.test.js
+++ b/test/jsonapi-query-parameters.test.js
@@ -6,33 +6,34 @@ const { Spectral } = spectralCore;
 import ruleset from '../rules/jsonapi-query-parameters.js';
 
 describe('jsonapi-query-parameters ruleset:', function () {
-
   let spectral;
 
+  // Common setup for all test cases
   beforeEach(function () {
-
     spectral = new Spectral();
-
+    spectral.setRuleset(ruleset);
   });
 
   // see test/assets/example-jsonapi-oas.yaml see filter and fields
   // describe('get-filter-query-parameters:', function () {
 
-  it('the query fields/parameters should adhere to the specification', function (done) {
-
-    const doc = {
+  // Test cases for valid query fields/parameters
+  it('should pass with no errors for valid query fields/parameters', async function () {
+    const validDocument = {
       'openapi': '3.0.2',
       'paths': {
-        '/myResources?{abcEfg}=22': {
+        '/myResources': {
           'get': {
-            'parameters': {
-              'name': 'abcEfg',
-              'description': 'schema for \'fields\' query parameter',
-              'in': 'query',
-              'schema': {
-                'type': 'string'
+            'parameters': [
+              {
+                'name': 'abcEfg_A',
+                'description': 'schema for \'fields\' query parameter',
+                'in': 'query',
+                'schema': {
+                  'type': 'string'
+                }
               }
-            },
+            ],
             'responses': {
               '200': {
                 'content': {
@@ -74,21 +75,12 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-    spectral.setRuleset(ruleset);
-    spectral.run(doc)
-      .then((results) => {
-
-        // results: ${JSON.stringify(results, null, 2)}`);
-        expect(results.length).to.equal(0, 'Error count should be 0');
-        done();
-
-      })
-      .catch((error) => {
-
-        done(error);
-
-      });
-
+    try{
+      const results = await spectral.run(validDocument);
+      expect(results.length).to.equal(0, 'Error count should be 0');
+    } catch (error) {
+      throw new Error(error);
+    }
   });
 
 
@@ -96,23 +88,23 @@ describe('jsonapi-query-parameters ruleset:', function () {
   //   conventions above, and the server does not know how to process it as a
   //   query parameter from this specification, it MUST return 400 Bad Request
   // https://jsonapi.org/format/1.0/#query-parameters
-  it('the query should return a 400 Bad Request error if the parameters do not adhere to ' +
-     'the specification', function (done) {
-
-    const badDocument = {
+  // Test case for invalid parameter names
+  it('should return an error for invalid parameter names', async function () {
+    const documentWithInvalidParameterName = {
       'openapi': '3.0.2',
       'paths': {
-        '/myResources?{abefg}=22': {
+        '/myResources': {
           'get': {
-            'parameters': {
-              'name': 'abcefg',
-              'description': 'schema for \'fields\' query parameter',
-              'in': 'query',
-              'schema': {
-                'type': 'string'
+            'parameters': [
+              {
+                'name': 'abcefg',
+                'description': 'schema for \'fields\' query parameter',
+                'in': 'query',
+                'schema': {
+                  'type': 'string'
+                }
               }
-            },
-
+            ],
             'responses': {
               '400': {
                 'content': {
@@ -154,47 +146,47 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-    spectral.setRuleset(ruleset);
-    spectral.run(badDocument)
-      .then((results) => {
-
-        // results: ${JSON.stringify(results, null, 2)}`);
-        expect(results[0].code).to.equal('get-filter-query-parameters', 'Incorrect error');
-        done();
-
-      })
-      .catch((error) => {
+    try{
+      const results = await spectral.run(documentWithInvalidParameterName);
 
-        done(error);
-
-      });
+      // Check for error length
+      expect(results.length).to.be.greaterThan(0, 'Error count should be greater than 0');
 
+      // Check for severity
+      expect(result[0].severity).to.equal(DiagnosticSeverity.Error);
+    } catch (error) {
+      throw new Error(error);
+    }
   });
 
 
   // https://support.stoplight.io/s/article/Does-Stoplight-support-query-parameters
-  it('the rule should pass with NO errors', function (done) {
+  // Test case for query parameters with no errors
+  it('should pass with no errors for valid query parameters', async function () {
 
-    const cleanDoc3 = {
+    const validQueryParametersDocument = {
       'openapi': '3.0.2',
       'paths': {
-        '/myResources?{abcEfg}=22&{a_b}=23': {
-
+        '/myResources': {
           'get': {
-
-            'parameters': [{ 'name': 'abcEfg',
-              'description': 'schema for \'fields\' query parameter',
-              'in': 'query',
-              'schema': {
-                'type': 'string'
-              } },
-            { 'name': 'a_b',
-              'description': 'schema for \'fields\' query parameter',
-              'in': 'query',
-              'schema': {
-                'type': 'string'
-              } }],
-
+            'parameters': [
+              {
+                'name': 'abcEfg_A',
+                'description': 'schema for \'fields\' query parameter',
+                'in': 'query',
+                'schema': {
+                  'type': 'string'
+                }
+              },
+              {
+                'name': 'a_b',
+                'description': 'schema for \'fields\' query parameter',
+                'in': 'query',
+                'schema': {
+                  'type': 'string'
+                }
+              }
+            ],
             'responses': {
               '200': {
                 'content': {
@@ -236,52 +228,44 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-    spectral.setRuleset(ruleset);
-    spectral.run(cleanDoc3)
-      .then((results) => {
-
-        // results: ${JSON.stringify(results, null, 2)}`);
-        expect(results.length).to.equal(0, 'Error count should be 0');
-
-        done();
-
-      })
-      .catch((error) => {
-
-        done(error);
-
-      });
-
+    try{
+      const results = await spectral.run(validQueryParametersDocument);
+      expect(results.length).to.equal(0, 'Error count should be 0');
+    } catch (error){
+      throw new Error(error);
+    }
   });
 
   // https://support.stoplight.io/s/article/Does-Stoplight-support-query-parameters
-  it('the rule should pass with errors, bad parameter name, paremeter name must have at ' +
-     'least one non a-z character, could be [-_A-Z]', function (done) {
-
-    const badDoc4 = {
+  // test case for bad parameter name with one non a-z character
+  it('should return an error for bad parameter name with one non a-z character', async function () {
+    const badParameterNameDocument = {
       'openapi': '3.0.2',
       'paths': {
         // second parameter is the bad one
-        '/myResources?{abcEfg}=22&{ab}=23': {
-
+        '/myResources': {
           'get': {
-
-            'parameters': [{ 'name': 'abcEfg',
-              'description': 'schema for \'fields\' query parameter',
-              'in': 'query',
-              'schema': {
-                'type': 'string'
-              } },
-            // this parameter is a baddie
-            { 'name': 'ab',
-              'description': 'schema for \'fields\' query parameter',
-              'in': 'query',
-              'schema': {
-                'type': 'string'
-              } }],
-
+            'parameters': [
+              {
+                'name': 'abcEfg_A',
+                'description': 'schema for \'fields\' query parameter',
+                'in': 'query',
+                'schema': {
+                  'type': 'string'
+                }
+              },
+              // this parameter is a baddie
+              {
+                'name': 'ab@',
+                'description': 'schema for \'fields\' query parameter',
+                'in': 'query',
+                'schema': {
+                  'type': 'string'
+                }
+              }
+            ],
             'responses': {
-              '200': {
+              '400': {
                 'content': {
                   'application/vnd.api+json': {
                     'schema': {
@@ -321,51 +305,42 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-    spectral.setRuleset(ruleset);
-    spectral.run(badDoc4)
-      .then((results) => {
-
-        // results: ${JSON.stringify(results, null, 2)}
-
-        expect(results[0].code).to.equal('get-filter-query-parameters', 'Incorrect error');
-        done();
-
-      })
-      .catch((error) => {
+    try{
+      const results = await spectral.run(badParameterNameDocument);
 
-        done(error);
+      // Check that an error is returned
+      expect(results.length).to.be.greaterThan(0, 'At least one error should be returned');
 
-      });
+      // Check for the correct error code
+      expect(results[0].code).to.equal('get-filter-query-parameters', 'Incorrect error code');
 
+      // Optionally, check for severity level
+      expect(results[0].severity).to.equal(DiagnosticSeverity.Error, 'Severity should be "Error"');
+    } catch (error) {
+      throw new Error(error);
+    }
   });
 
   // https://support.stoplight.io/s/article/Does-Stoplight-support-query-parameters
-  it('the rule should pass with errors, bad parameter name, cannot be a number', function (done) {
-
-    const badDoc5 = {
+  // Test case for bad parameter name with a number
+  it('should return an error for bad parameter name with a number', async function () {
+    const badParameterNumberDocument = {
       'openapi': '3.0.2',
       'paths': {
-        // second parameter is the bad one
-        '/myResources?{33}=22&{33}=23': {
-
+        '/myResources': {
           'get': {
-
-            'parameters': [{ 'name': '33',
-              'description': 'schema for \'fields\' query parameter',
-              'in': 'query',
-              'schema': {
-                'type': 'string'
-              } },
-            // this parameter is the baddie
-            { 'name': '33',
-              'description': 'schema for \'fields\' query parameter',
-              'in': 'query',
-              'schema': {
-                'type': 'string'
-              } }],
-
+            'parameters': [
+              {
+                'name': '33',
+                'description': 'schema for \'fields\' query parameter',
+                'in': 'query',
+                'schema': {
+                  'type': 'string'
+                }
+              }
+            ],
             'responses': {
-              '200': {
+              '400': {
                 'content': {
                   'application/vnd.api+json': {
                     'schema': {
@@ -405,52 +380,41 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-
-    spectral.setRuleset(ruleset);
-
-    spectral.run(badDoc5)
-      .then((results) => {
-
-        // results: ${JSON.stringify(results, null, 2)}`);
-
-        expect(results[0].code).to.equal('get-filter-query-parameters', 'Incorrect error');
-        done();
-
-      })
-      .catch((error) => {
-
-        done(error);
-
-      });
-
+    try{
+      const results = await spectral.run(badParameterNumberDocument);
+
+      // Check that an error is returned
+      expect(results.length).to.be.greaterThan(0, 'At least one error should be returned');
+      
+      // Check for the correct error code
+      expect(results[0].code).to.equal('get-filter-query-parameters', 'Incorrect error code');
+      
+      // Optionally, check for severity level
+      expect(results[0].severity).to.equal(DiagnosticSeverity.Error, 'Severity should be "Error"');
+    } catch (error) {
+      throw new Error (error);
+    }
   });
 
-  it('the rule should pass with errors, bad parameter name, unallowed special character', function (done) {
-
-    const badDoc6 = {
+  // Test case for bad parameter name with unallowed special characters
+  it('should return an error for bad parameter name with unallowed special characters', async function () {
+    const badParameterSpecialCharDocument = {
       'openapi': '3.0.2',
       'paths': {
-        // second parameter is the bad one
-        "/myResources?{'A_-___'}=22&{'A_-__'}=23": {
-
+        "/myResources": {
           'get': {
-
-            'parameters': [{ 'name': 'A_-___',
-              'description': 'schema for \'fields\' query parameter',
-              'in': 'query',
-              'schema': {
-                'type': 'string'
-              } },
-            // this parameter is the baddie
-            { 'name': 'A_-___',
-              'description': 'schema for \'fields\' query parameter',
-              'in': 'query',
-              'schema': {
-                'type': 'string'
-              } }],
-
+            'parameters': [
+              {
+                'name': 'A_-___',
+                'description': 'schema for \'fields\' query parameter',
+                'in': 'query',
+                'schema': {
+                  'type': 'string'
+                }
+              }
+            ],
             'responses': {
-              '200': {
+              '400': {
                 'content': {
                   'application/vnd.api+json': {
                     'schema': {
@@ -490,23 +454,23 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-    spectral.setRuleset(ruleset);
-
-    spectral.run(badDoc6)
-      .then((results) => {
-
-        // results: ${JSON.stringify(results, null, 2)}`);
-
-        expect(results[0].code).to.equal('member-names-end_with', 'Incorrect error');
-        done();
-
-      })
-      .catch((error) => {
-
-        done(error);
+    try{
+      const results = await spectral.run(badParameterSpecialCharDocument);
+      
+      // Check that an error is returned
+      expect(results.length).to.be.greaterThan(0, 'At least one error should be returned');
+      
+      // Check for the correct error code
+      expect(results[0].code).to.equal('get-filter-query-parameters', 'Incorrect error code');
+      
+      // Optionally, check for severity level
+      expect(results[0].severity).to.equal(DiagnosticSeverity.Error, 'Severity should be "Error"');
+    } catch (error) {
+      throw new Error(error);
+    }
+  });
 
-      });
 
-  });
 
+  
 });

From 2a4aa028dc5654df81d9a4f51fffb9056f50016f Mon Sep 17 00:00:00 2001
From: DwDMadMac <anthonymmacallister@gmail.com>
Date: Wed, 4 Oct 2023 09:19:38 -0400
Subject: [PATCH 02/10] Fix: Resolved ReferenceError - Spelling typo

---
 test/jsonapi-query-parameters.test.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/jsonapi-query-parameters.test.js b/test/jsonapi-query-parameters.test.js
index 4ff9c65..5b6a288 100644
--- a/test/jsonapi-query-parameters.test.js
+++ b/test/jsonapi-query-parameters.test.js
@@ -153,7 +153,7 @@ describe('jsonapi-query-parameters ruleset:', function () {
       expect(results.length).to.be.greaterThan(0, 'Error count should be greater than 0');
 
       // Check for severity
-      expect(result[0].severity).to.equal(DiagnosticSeverity.Error);
+      expect(results[0].severity).to.equal(DiagnosticSeverity.Error);
     } catch (error) {
       throw new Error(error);
     }

From 3c2a374c5d8e958b10dc881dc49cd898f9079e89 Mon Sep 17 00:00:00 2001
From: DwDMadMac <anthonymmacallister@gmail.com>
Date: Wed, 4 Oct 2023 09:22:33 -0400
Subject: [PATCH 03/10] Fix: Resolved ReferenceError: DiagnosticSeverity is not
 defined

- Was missing the DiagnosticSeverty import which was failing two test cases.
---
 test/jsonapi-query-parameters.test.js | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/test/jsonapi-query-parameters.test.js b/test/jsonapi-query-parameters.test.js
index 5b6a288..32dd7a4 100644
--- a/test/jsonapi-query-parameters.test.js
+++ b/test/jsonapi-query-parameters.test.js
@@ -1,5 +1,7 @@
 import { expect } from 'chai';
 import spectralCore from '@stoplight/spectral-core';
+import { DiagnosticSeverity } from '@stoplight/types';
+
 const { Spectral } = spectralCore;
 
 // rules under test

From 58934b137967d496b3ab17eabb247fafa626512a Mon Sep 17 00:00:00 2001
From: DwDMadMac <anthonymmacallister@gmail.com>
Date: Wed, 4 Oct 2023 09:53:26 -0400
Subject: [PATCH 04/10] Fix: AssertionError: Incorrect error code

- Test was expecting a specific error code and did not get the correct one.
---
 test/jsonapi-query-parameters.test.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/jsonapi-query-parameters.test.js b/test/jsonapi-query-parameters.test.js
index 32dd7a4..02d5c85 100644
--- a/test/jsonapi-query-parameters.test.js
+++ b/test/jsonapi-query-parameters.test.js
@@ -463,7 +463,7 @@ describe('jsonapi-query-parameters ruleset:', function () {
       expect(results.length).to.be.greaterThan(0, 'At least one error should be returned');
       
       // Check for the correct error code
-      expect(results[0].code).to.equal('get-filter-query-parameters', 'Incorrect error code');
+      expect(results[0].code).to.equal('member-names-end_with', 'Incorrect error code');
       
       // Optionally, check for severity level
       expect(results[0].severity).to.equal(DiagnosticSeverity.Error, 'Severity should be "Error"');

From a0af3dd59be3f42ca6aa47b35b99041118f76241 Mon Sep 17 00:00:00 2001
From: Anthony M MacAllister <2531816+ezenity@users.noreply.github.com>
Date: Wed, 18 Oct 2023 13:04:03 -0400
Subject: [PATCH 05/10] Chore: Update ESLint configuration to support
 ECMAScript 2021 features

---
 .eslintrc.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.eslintrc.yml b/.eslintrc.yml
index 6153c6f..98ecf01 100644
--- a/.eslintrc.yml
+++ b/.eslintrc.yml
@@ -4,6 +4,7 @@ env:
 extends: "eslint:recommended"
 parserOptions:
   sourceType: "module"
+  ecmaVersion: 2021
   ecmaFeatures:
     jsx: false
 rules:

From e0b0780c8cf046e5e9019e5d4626e6f0f65b427d Mon Sep 17 00:00:00 2001
From: Anthony M MacAllister <2531816+ezenity@users.noreply.github.com>
Date: Wed, 18 Oct 2023 13:10:04 -0400
Subject: [PATCH 06/10] Fix: Resolve ESLint errors in
 jsonapi-query-parameters.test.js

---
 test/jsonapi-query-parameters.test.js | 58 ++++++++++++++++++++++-----
 1 file changed, 47 insertions(+), 11 deletions(-)

diff --git a/test/jsonapi-query-parameters.test.js b/test/jsonapi-query-parameters.test.js
index 02d5c85..2d40715 100644
--- a/test/jsonapi-query-parameters.test.js
+++ b/test/jsonapi-query-parameters.test.js
@@ -8,12 +8,15 @@ const { Spectral } = spectralCore;
 import ruleset from '../rules/jsonapi-query-parameters.js';
 
 describe('jsonapi-query-parameters ruleset:', function () {
+
   let spectral;
 
   // Common setup for all test cases
   beforeEach(function () {
+
     spectral = new Spectral();
     spectral.setRuleset(ruleset);
+  
   });
 
   // see test/assets/example-jsonapi-oas.yaml see filter and fields
@@ -21,6 +24,7 @@ describe('jsonapi-query-parameters ruleset:', function () {
 
   // Test cases for valid query fields/parameters
   it('should pass with no errors for valid query fields/parameters', async function () {
+
     const validDocument = {
       'openapi': '3.0.2',
       'paths': {
@@ -77,12 +81,17 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-    try{
+    try {
+
       const results = await spectral.run(validDocument);
       expect(results.length).to.equal(0, 'Error count should be 0');
+    
     } catch (error) {
+
       throw new Error(error);
+    
     }
+  
   });
 
 
@@ -92,6 +101,7 @@ describe('jsonapi-query-parameters ruleset:', function () {
   // https://jsonapi.org/format/1.0/#query-parameters
   // Test case for invalid parameter names
   it('should return an error for invalid parameter names', async function () {
+
     const documentWithInvalidParameterName = {
       'openapi': '3.0.2',
       'paths': {
@@ -148,7 +158,8 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-    try{
+    try {
+
       const results = await spectral.run(documentWithInvalidParameterName);
 
       // Check for error length
@@ -156,9 +167,13 @@ describe('jsonapi-query-parameters ruleset:', function () {
 
       // Check for severity
       expect(results[0].severity).to.equal(DiagnosticSeverity.Error);
+    
     } catch (error) {
+
       throw new Error(error);
+    
     }
+  
   });
 
 
@@ -230,17 +245,23 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-    try{
+    try {
+
       const results = await spectral.run(validQueryParametersDocument);
       expect(results.length).to.equal(0, 'Error count should be 0');
-    } catch (error){
+    
+    } catch (error) {
+
       throw new Error(error);
+    
     }
+  
   });
 
   // https://support.stoplight.io/s/article/Does-Stoplight-support-query-parameters
   // test case for bad parameter name with one non a-z character
   it('should return an error for bad parameter name with one non a-z character', async function () {
+
     const badParameterNameDocument = {
       'openapi': '3.0.2',
       'paths': {
@@ -307,7 +328,8 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-    try{
+    try {
+
       const results = await spectral.run(badParameterNameDocument);
 
       // Check that an error is returned
@@ -318,14 +340,19 @@ describe('jsonapi-query-parameters ruleset:', function () {
 
       // Optionally, check for severity level
       expect(results[0].severity).to.equal(DiagnosticSeverity.Error, 'Severity should be "Error"');
+    
     } catch (error) {
+
       throw new Error(error);
+    
     }
+  
   });
 
   // https://support.stoplight.io/s/article/Does-Stoplight-support-query-parameters
   // Test case for bad parameter name with a number
   it('should return an error for bad parameter name with a number', async function () {
+
     const badParameterNumberDocument = {
       'openapi': '3.0.2',
       'paths': {
@@ -382,7 +409,8 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-    try{
+    try {
+
       const results = await spectral.run(badParameterNumberDocument);
 
       // Check that an error is returned
@@ -393,17 +421,22 @@ describe('jsonapi-query-parameters ruleset:', function () {
       
       // Optionally, check for severity level
       expect(results[0].severity).to.equal(DiagnosticSeverity.Error, 'Severity should be "Error"');
+    
     } catch (error) {
-      throw new Error (error);
+
+      throw new Error(error);
+    
     }
+  
   });
 
   // Test case for bad parameter name with unallowed special characters
   it('should return an error for bad parameter name with unallowed special characters', async function () {
+
     const badParameterSpecialCharDocument = {
       'openapi': '3.0.2',
       'paths': {
-        "/myResources": {
+        '/myResources': {
           'get': {
             'parameters': [
               {
@@ -456,7 +489,8 @@ describe('jsonapi-query-parameters ruleset:', function () {
       }
     };
 
-    try{
+    try {
+
       const results = await spectral.run(badParameterSpecialCharDocument);
       
       // Check that an error is returned
@@ -467,12 +501,14 @@ describe('jsonapi-query-parameters ruleset:', function () {
       
       // Optionally, check for severity level
       expect(results[0].severity).to.equal(DiagnosticSeverity.Error, 'Severity should be "Error"');
+    
     } catch (error) {
+
       throw new Error(error);
+    
     }
+  
   });
 
-
-
   
 });

From 636ac67fd7d47bde02a17d381b12b6dfd426c607 Mon Sep 17 00:00:00 2001
From: ezenity <anthonymmacallister@gmail.com>
Date: Thu, 7 Dec 2023 14:59:53 -0500
Subject: [PATCH 07/10] Initial Commit - Setting up

---
 package.json                                             | 2 +-
 rules/jsonapi-document-structure-resource-object.js      | 3 +++
 rules/jsonapi-document-structure-ruleset.yaml            | 1 +
 test/jsonapi-document-structure-resource-objects.test.js | 0
 4 files changed, 5 insertions(+), 1 deletion(-)
 create mode 100644 rules/jsonapi-document-structure-resource-object.js
 create mode 100644 test/jsonapi-document-structure-resource-objects.test.js

diff --git a/package.json b/package.json
index ded676b..d55aaaf 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
   "main": "./rules/json-ruleset.yaml",
   "type": "module",
   "scripts": {
-    "test": "./node_modules/.bin/eslint **/*.js test/ && ./node_modules/.bin/mocha test/*.test.js",
+    "test": "eslint **/*.js test/ && mocha test/*.test.js",
     "lint": "./node_modules/.bin/eslint **/*.js test/",
     "prepare": "husky install"
   },
diff --git a/rules/jsonapi-document-structure-resource-object.js b/rules/jsonapi-document-structure-resource-object.js
new file mode 100644
index 0000000..0bae632
--- /dev/null
+++ b/rules/jsonapi-document-structure-resource-object.js
@@ -0,0 +1,3 @@
+// Document Structure - Resource Objects - https://jsonapi.org/format/#document-resource-objects
+
+// All rules in the file MUST have corresponding tests
diff --git a/rules/jsonapi-document-structure-ruleset.yaml b/rules/jsonapi-document-structure-ruleset.yaml
index 7d2fff9..9d1c001 100644
--- a/rules/jsonapi-document-structure-ruleset.yaml
+++ b/rules/jsonapi-document-structure-ruleset.yaml
@@ -12,3 +12,4 @@ extends:
   - jsonapi-document-structure-meta-information.js
   - jsonapi-document-structure-links.js
   - jsonapi-document-structure-jsonapi-object.js
+  - jsonapi-document-structure-resource-object.js
diff --git a/test/jsonapi-document-structure-resource-objects.test.js b/test/jsonapi-document-structure-resource-objects.test.js
new file mode 100644
index 0000000..e69de29

From a54546531da114790ae4bc24ad717d0c420aa996 Mon Sep 17 00:00:00 2001
From: ezenity <anthonymmacallister@gmail.com>
Date: Thu, 7 Dec 2023 14:59:53 -0500
Subject: [PATCH 08/10] Initial Commit - Setting up

---
 rules/jsonapi-document-structure-resource-object.js      | 3 +++
 rules/jsonapi-document-structure-ruleset.yaml            | 1 +
 test/jsonapi-document-structure-resource-objects.test.js | 0
 3 files changed, 4 insertions(+)
 create mode 100644 rules/jsonapi-document-structure-resource-object.js
 create mode 100644 test/jsonapi-document-structure-resource-objects.test.js

diff --git a/rules/jsonapi-document-structure-resource-object.js b/rules/jsonapi-document-structure-resource-object.js
new file mode 100644
index 0000000..0bae632
--- /dev/null
+++ b/rules/jsonapi-document-structure-resource-object.js
@@ -0,0 +1,3 @@
+// Document Structure - Resource Objects - https://jsonapi.org/format/#document-resource-objects
+
+// All rules in the file MUST have corresponding tests
diff --git a/rules/jsonapi-document-structure-ruleset.yaml b/rules/jsonapi-document-structure-ruleset.yaml
index 7d2fff9..9d1c001 100644
--- a/rules/jsonapi-document-structure-ruleset.yaml
+++ b/rules/jsonapi-document-structure-ruleset.yaml
@@ -12,3 +12,4 @@ extends:
   - jsonapi-document-structure-meta-information.js
   - jsonapi-document-structure-links.js
   - jsonapi-document-structure-jsonapi-object.js
+  - jsonapi-document-structure-resource-object.js
diff --git a/test/jsonapi-document-structure-resource-objects.test.js b/test/jsonapi-document-structure-resource-objects.test.js
new file mode 100644
index 0000000..e69de29

From 2d15e03b297cfbb823039eb47d9a4bd844cb73e2 Mon Sep 17 00:00:00 2001
From: ezenity <anthonymmacallister@gmail.com>
Date: Thu, 7 Dec 2023 22:17:07 -0500
Subject: [PATCH 09/10] Refactor: Spectral's JSON Formatter Outputs

- When running your test cases with the Spectral instance, Spectral will provide an analysis to ensure to can run rule and pass the validations along with reading rulename and/or provided document. This addition will provide a better understanding as to why the test case of rule is not running properly.
---
 test/utils/handleSpectralResults.js | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/test/utils/handleSpectralResults.js b/test/utils/handleSpectralResults.js
index 2baad97..9127392 100644
--- a/test/utils/handleSpectralResults.js
+++ b/test/utils/handleSpectralResults.js
@@ -35,8 +35,25 @@ export async function handleSpectralResults(spectral, document, resultCode) {
     // Log each result, including targetVal
     results.forEach((result) => {
 
-      debugDebug(`Result look check, result code: \x1b[32m${result.code}\x1b[35m, target code: \x1b[32m${resultCode}\x1b[35m.\n`);
+      debugDebug(`Handle Spectral Results Utils - Spectral's Run Output\n`);
+      
+      // Spectral provides an output of the results for reasons why it has potentially failed, below are the details to possibly fix them.
+      debugDebug(`Result code: \x1b[32m${result.code}\x1b[0m`);
+      // Since we are mapping the results path, we need to confirm that is an a provided path to avoid a `TypeError: undefined` message.
+      if (result.path) {
+
+        debugDebug(`Result path: \x1b[33m[ \x1b[32m${result.path.map((item) => `\x1b[33m"\x1b[32m${item}\x1b[33m"`).join(', ')} \x1b[33m]\x1b[0m`);
+      
+      }
+      debugDebug(`Result message: \x1b[32m${result.message}\x1b[0m`);
+      // debugDebug(`Result severity: \x1b[32m${result.severity}\x1b[0m`);
+      // debugDebug(`Result range: \x1b[32m${JSON.stringify(result.range, null, 2)}\x1b[0m`);
+      // debugDebug(`Result source: \x1b[32m${result.source}\x1b[0m\n`);
+
 
+      // If the rule name is found in both `result.code` & resultCode`, this statement will process
+      // If the rule name does NOT match, this statement will not run and will need to review the
+      // `Result Code` output for potential issues with Spectral Run has failed.
       if (result.code === resultCode) {
 
         debugDebug(`\x1b[32mResult for '${resultCode}':\x1b[36m ${JSON.stringify(result, ['message', 'path'], 2)} \x1b[0m\n`);

From 8196565f062f726a48db9c8917412ca3e5bbc8dd Mon Sep 17 00:00:00 2001
From: ezenity <anthonymmacallister@gmail.com>
Date: Mon, 11 Dec 2023 22:36:09 -0500
Subject: [PATCH 10/10] Feat: Add Spectral rules for JSON:API Document
 Structure - Resource Objects This commit introduces a new set of Spectral
 rules specifically tailored for validating JSON:API Resource Objects within
 OpenAPI documents. Key highlights include:

- Creation of Spectral rules to ensure compliance with JSON:API standards, focusing on Resource Objects structures, object properties and proper types.
- Resource Objects can be provided as a single object or an array of objects. These rule validations tailor for both scenarios and ensures it is following the JSON:API Specifications v1.0.
- `id` member has an exception for when a `Resource Object` is newly created. The rules are tailored for this specific scenario, which is typically a HTPP POST, otherwise an `id` member is required.

These additions significantly improve our capability to automatically validate and ensure the consistency of API responses with the JSON:API standard.
---
 ...api-document-structure-resource-objects.js | 342 ++++++++++++++++++
 1 file changed, 342 insertions(+)
 create mode 100644 rules/jsonapi-document-structure-resource-objects.js

diff --git a/rules/jsonapi-document-structure-resource-objects.js b/rules/jsonapi-document-structure-resource-objects.js
new file mode 100644
index 0000000..96ff7bd
--- /dev/null
+++ b/rules/jsonapi-document-structure-resource-objects.js
@@ -0,0 +1,342 @@
+// Document Structure - Resource Objects - https://jsonapi.org/format/#document-resource-objects
+
+// All rules in the file MUST have corresponding tests
+
+import { enumeration, length, truthy } from '@stoplight/spectral-functions';
+
+export default {
+  documentationUrl: 'https://jsonapi.org/format/#document-resource-objects',
+  rules: {
+
+    /**
+     * Ensures that a `Resource Object` is of type `object` or `array`
+     */
+    'document-structure-resource-objects-type': {
+      description: 'A `Resource Object` MUST be of type `object` or `array`',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      // given: "$..[?(@.get || @.delete || @.put || @.patch || @.post)]..[?(@.responses || @.requestBody)]..content['application/vnd.api+json'].schema.properties.data.properties",
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data",
+      then: {
+        field: 'type',
+        function: enumeration,
+        functionOptions: {
+          values: [
+            'object',
+            'array'
+          ]
+        }
+      }
+    },
+
+    /**
+     * Checks the presence of 'id' and 'type' within a single `Resource Object`.
+     */
+    'document-structure-resource-objects-single-structure': {
+      description: 'A single `Resource Object` MUST only contain the specified members',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.properties",
+      then: {
+        field: '@key',
+        function: enumeration,
+        functionOptions: {
+          values: [
+            'id',
+            'type',
+            'attributes',
+            'relationships',
+            'links',
+            'meta'
+          ]
+        }
+      }
+    },
+
+    /**
+     * Ensures that the single `Resource Object` contains an appropriate number of members.
+     * This rule checks that a single `Resource Object` has a minmum of two members and a 
+     * maximum of 6 members. This will even include for when an `id` member is not required
+     * Exception because when creating a new resource, typically the `attributes` and/or
+     * `relationships` objects are provided to supply the data needed to create the resource.
+     */
+    'document-structure-resource-objects-single-structure-length': {
+      description: 'A single `Resource Object` MAY contain between two or six specified members',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data",
+      then: {
+        field: 'properties',
+        function: length,
+        functionOptions: {
+          min: 2,
+          max: 6
+        }
+      }
+    },
+
+    /**
+     * Ensures that a single `Resource Object` has a `type` member.
+     */
+    'document-structure-resource-objects-single-type-required': {
+      description: 'A single `Resource Object` MUST contain `type` member',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.properties",
+      then: {
+        field: 'type',
+        function: truthy
+      }
+    },
+
+    /**
+     * Ensures that a single `Resource Object` has a `id` member for the specific
+     * targeted HTTP methods: GET, DELETE, PUT, PATCH.
+     * 
+     * HTTP method 'POST' will not have an `id` member. When a client is sending a request
+     * to create a new resource on the server, the `id` of the resource is not yet known, as
+     * it is usually generated by the server. In such cases, the `Resource Object` in the 
+     * request body will not include an `id` member. This is common in `POST` requests where
+     * a new resource is being added.
+     */
+    'document-structure-resource-objects-single-id-required': {
+      description: 'A single `Resource Object` MUST contain `id` member for HTTP methods: GET, DELETE, PUT, PATCH',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.properties",
+      then: {
+        field: 'id',
+        function: truthy
+      }
+    },
+
+    /**
+     * Verifies that the `id` member in each single `Resource Object` is of type `string`.
+     * This rule is crucial for maintaining consistency in `Resource Object` indentifiers.
+     */
+    'document-structure-resource-objects-single-id-type': {
+      description: '`id` member in a single `Resource Object` MUST be of type `string`',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data",
+      then: {
+        field: 'type',
+        function: enumeration,
+        functionOptions: {
+          values: [
+            'string'
+          ]
+        }
+      }
+    },
+
+    /**
+     * Verifies that the `type` member in each single `Resource Object` is of type `string`.
+     * This rule is to assist with ensuring a single `Resource Object` share a common 
+     * attributes and relationships.
+     */
+    'document-structure-resource-objects-single-type-type': {
+      description: '`type` member in a single `Resource Object` MUST be of type `string`',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.properties.type",
+      then: {
+        field: 'type',
+        function: enumeration,
+        functionOptions: {
+          values: [
+            'string'
+          ]
+        }
+      }
+    },
+
+    /**
+     * Verifies that the `attributes` member in each single `Resource Object` is of type `object`.
+     * This rule is crucial for maintaining consistency in representing some of the resource's data.
+     */
+    'document-structure-resource-objects-single-attributes-type': {
+      description: '`attributes` member in a single `Resource Object` MUST be of type `object`',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.properties.attributes",
+      then: {
+        field: 'type',
+        function: enumeration,
+        functionOptions: {
+          values: [
+            'object'
+          ]
+        }
+      }
+    },
+
+    /**
+     * Checks the presence of 'id' and 'type' within an array of resource objects.
+     */
+    'document-structure-resource-objects-array-required-fields': {
+      description: 'An array of `Resource Objects` MUST contain `id` and `type` members',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data",
+      then: {
+        field: '@key',
+        function: enumeration,
+        functionOptions: {
+          values: [
+            'id',
+            'type',
+            'attributes',
+            'relationships',
+            'links',
+            'meta'
+          ]
+        }
+      }
+    },
+
+    /**
+     * Checks the presence of 'id' and 'type' within an array of `Resource Objects`.
+     */
+    'document-structure-resource-objects-array-structure': {
+      description: 'An array of `Resource Objects` MUST only contain the specified members',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.items.properties",
+      then: {
+        field: '@key',
+        function: enumeration,
+        functionOptions: {
+          values: [
+            'id',
+            'type',
+            'attributes',
+            'relationships',
+            'links',
+            'meta'
+          ]
+        }
+      }
+    },
+
+    /**
+   * Ensures that the an array of `Resource Objects` contains an appropriate number of members.
+   * This rule checks that an array of `Resource Objects` has a minmum of two members and a 
+   * maximum of 6 members. This will even include for when an `id` member is not required
+   * Exception because when creating a new resource, typically the `attributes` and/or
+   * `relationships` objects are provided to supply the data needed to create the resource.
+   */
+    'document-structure-resource-objects-array-structure-length': {
+      description: 'An array of `Resource Objects` MAY contain between two or six specified members',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.items",
+      then: {
+        field: 'properties',
+        function: length,
+        functionOptions: {
+          min: 2,
+          max: 6
+        }
+      }
+    },
+
+    /**
+   * Ensures that an array of `Resource Objects` has a `type` member.
+   */
+    'document-structure-resource-objects-array-type-required': {
+      description: 'An array of `Resource Objects` MUST contain `type` member',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.items.properties",
+      then: {
+        field: 'type',
+        function: truthy
+      }
+    },
+
+    /**
+   * Ensures that an array of `Resource Objects` has a `id` member for the specific
+   * targeted HTTP methods: GET, DELETE, PUT, PATCH.
+   * 
+   * HTTP method 'POST' will not have an `id` member. When a client is sending a request
+   * to create a new resource on the server, the `id` of the resource is not yet known, as
+   * it is usually generated by the server. In such cases, the `Resource Object` in the 
+   * request body will not include an `id` member. This is common in `POST` requests where
+   * a new resource is being added.
+   */
+    'document-structure-resource-objects-array-id-required': {
+      description: 'An array of `Resource Objects` MUST contain `id` member for HTTP methods: GET, DELETE, PUT, PATCH',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.items.properties",
+      then: {
+        field: 'id',
+        function: truthy
+      }
+    },
+
+    /**
+   * Verifies that the `id` member in an array of `Resource Objects` is of type `string`.
+   * This rule is crucial for maintaining consistency in `Resource Object` indentifiers.
+   */
+    'document-structure-resource-objects-array-id-type': {
+      description: '`id` member in an array of `Resource Objects` MUST be of type `string`',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.items.properties.id",
+      then: {
+        field: 'type',
+        function: enumeration,
+        functionOptions: {
+          values: [
+            'string'
+          ]
+        }
+      }
+    },
+
+    /**
+   * Verifies that the `type` member in an array of `Resource Objects` is of type `string`.
+   * This rule is to assist with ensuring aa array of `Resource Objects` share a common 
+   * attributes and relationships.
+   */
+    'document-structure-resource-objects-array-type-type': {
+      description: '`type` member in an array of `Resource Objects` MUST be of type `string`',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.items.properties.type",
+      then: {
+        field: 'type',
+        function: enumeration,
+        functionOptions: {
+          values: [
+            'string'
+          ]
+        }
+      }
+    },
+
+    /**
+   * Verifies that the `attributes` member in an array of `Resource Objects` is of type `object`.
+   * This rule is crucial for maintaining consistency in representing some of the resource's data.
+   */
+    'document-structure-resource-objects-array-attributes-type': {
+      description: '`attributes` member in an array of `Resource Objects` MUST be of type `object`',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$..[?(@property == 'get' || @property == 'delete' || @property == 'put' || @property == 'patch' || @property == 'post')]..[?(@property == 'responses' || @property == 'requestBody')]..content['application/vnd.api+json'].schema.properties.data.items.properties.attributes",
+      then: {
+        field: 'type',
+        function: enumeration,
+        functionOptions: {
+          values: [
+            'object'
+          ]
+        }
+      }
+    }
+
+
+  }
+};