Added support to include invalid references

All functions that take an options object now support
options.includeInvalid to allow you to find references that are invalid.

Fixes #47

Author: whitlockjc

browser/json-refs-min.js

@@ -36,6 +36,7 @@ The options used for various JsonRefs APIs.
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
 | [filter] | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> &#124; <code>function</code> | <code>&quot;function () {return true;}&quot;</code> | The filter to use when gathering JSON References *(If this value is a single string or an array of strings, the value(s) are expected to be the `type(s)` you are interested in collecting as described in [getRefDetails](#module_JsonRefs.getRefDetails).  If it is a function, it is expected that the function behaves like [RefDetailsFilter](#module_JsonRefs..RefDetailsFilter).)* |
+| [includeInvalid] | <code>boolean</code> | <code>false</code> | Whether or not to include invalid JSON Reference details *(This will make it so that objects that are like JSON Reference objects, as in they are an `Object` and the have a `$ref` property, but fail validation will be included.  This is very useful for when you want to know if you have invalid JSON Reference definitions.  This will not mean that APIs will process invalid JSON References but the reasons as to why the JSON References are invalid will be included in the returned metadata.)* |
 | [loaderOptions] | <code>object</code> |  | The options to pass to [PathLoader~load](https://github.com/whitlockjc/path-loader/blob/master/docs/API.md#module_PathLoader.load). |
 | [options.relativeBase] | <code>string</code> |  | The base location to use when resolving relative references *(Only useful for APIs that do remote reference resolution.  If this value is not defined, [path-loader](https://github.com/whitlockjc/path-loader) will use `window.location.href` for the browser and `process.cwd()` for Node.js.)* |
 | [options.subDocPath] | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> | <code>&quot;[]&quot;</code> | The JSON Pointer or array of path segments to the sub document location to search from |

browser/json-refs-standalone-min.js

@@ -156,7 +156,8 @@ function filterRefs (options, refs) {
     var refDetails = refs[refPtr];
 
     if (refFilter(refDetails, pathFromPtr(refPtr)) === true &&
-        refPtr.indexOf(subDocPrefix) > -1) {
+        refPtr.indexOf(subDocPrefix) > -1 &&
+        (refDetails.type !== 'invalid' || options.includeInvalid === true)) {
       filtered[refPtr] = refDetails;
     }
   });
@@ -475,6 +476,9 @@ function validateOptions (options) {
                !isType(options.filter, 'Function') &&
                !isType(options.filter, 'String')) {
       throw new TypeError('options.filter must be an Array, a Function of a String');
+    } else if (!isType(options.includeInvalid, 'Undefined') &&
+               !isType(options.includeInvalid, 'Boolean')) {
+      throw new TypeError('options.includeInvalid must be a Boolean');
     }
   }
 }
@@ -497,6 +501,11 @@ function validateOptions (options) {
  * References *(If this value is a single string or an array of strings, the value(s) are expected to be the `type(s)`
  * you are interested in collecting as described in {@link module:JsonRefs.getRefDetails}.  If it is a function, it is
  * expected that the function behaves like {@link module:JsonRefs~RefDetailsFilter}.)*
+ * @param {boolean} [includeInvalid=false] - Whether or not to include invalid JSON Reference details *(This will make
+ * it so that objects that are like JSON Reference objects, as in they are an `Object` and the have a `$ref` property,
+ * but fail validation will be included.  This is very useful for when you want to know if you have invalid JSON
+ * Reference definitions.  This will not mean that APIs will process invalid JSON References but the reasons as to why
+ * the JSON References are invalid will be included in the returned metadata.)*
  * @param {object} [loaderOptions] - The options to pass to
  * {@link https://github.com/whitlockjc/path-loader/blob/master/docs/API.md#module_PathLoader.load|PathLoader~load}.
  * @param {string} [options.relativeBase] - The base location to use when resolving relative references *(Only useful
@@ -709,7 +718,7 @@ function findRefs (obj, options) {
     if (isRefLike(node)) {
       refDetails = getRefDetails(node);
 
-      if (refDetails.type !== 'invalid') {
+      if (refDetails.type !== 'invalid' || options.includeInvalid === true) {
         if (refFilter(refDetails, path) === true) {
           refs[pathToPtr(path)] = refDetails;
         }
@@ -798,6 +807,8 @@ function findRefsAt (location, options) {
         delete cOptions.filter;
         delete cOptions.subDocPath;
 
+        cOptions.includeInvalid = true;
+
         remoteCache[location].refs = findRefs(res, cOptions);
 
         // Filter out the references based on options.filter and options.subDocPath

browser/json-refs-standalone.js

@@ -525,6 +525,7 @@ describe('json-refs', function () {
         [[], objTypeError],
         [['wrongType'], objTypeError],
         [[{}, 1], optionsTypeError],
+        [[{}, {includeInvalid: 'wrongType'}], new TypeError('options.includeInvalid must be a Boolean')],
         [[[], {subDocPath: 1}], osdpTypeError],
         [[{}, {subDocPath: '#/missing'}], osdpMissingError],
         [[{}, {filter: 1}], ofTypeError]
@@ -573,6 +574,10 @@ describe('json-refs', function () {
         });
       });
 
+      it('options.includeInvalid', function () {
+        runRefDetailsTestScenarios(JsonRefs.findRefs(testDocument, {includeInvalid: true}), expectedAllReferences);
+      });
+
       describe('options.subDocPath', function () {
         it('option as array', function () {
           runRefDetailsTestScenarios(JsonRefs.findRefs(testDocument, {subDocPath: ['array', '0']}), {
@@ -925,6 +930,34 @@ describe('json-refs', function () {
       })
       .then(done, done);
     });
+
+    it('should support options.includeInvalid', function (done) {
+      JsonRefs.resolveRefs(testDocument, {
+        includeInvalid: true,
+        loaderOptions: {
+          processContent: yamlContentProcessor
+        },
+        relativeBase: relativeBase
+      })
+        .then(function (res) {
+          var expectedAllResolvedRefs = _.cloneDeep(expectedValidResolveRefs);
+
+          expectedAllResolvedRefs['#/invalid'] = {
+            def: testDocument.invalid,
+            uri: testDocument.invalid.$ref,
+            uriDetails: URI.parse(testDocument.invalid.$ref),
+            error: 'URI is not strictly valid.',
+            type: 'invalid'
+          };
+
+          // Validate the resolved document is the same as when options.includeInvalid is false
+          assert.deepEqual(res.resolved, expectedFullyResolved);
+
+          // Validate the reference metadata includes the invalid reference details
+          validateResolvedRefDetails(res.refs, expectedAllResolvedRefs);
+        })
+        .then(done, done);
+    });
   });
 
   describe('#resolveRefsAt', function () {