Merge branch 'main' into fix/dates-as-strings

Author: philsturgeon

docs/options.md

@@ -29,7 +29,9 @@ $RefParser.dereference("my-schema.yaml", {
     }
   },
   dereference: {
-    circular: false                 // Don't allow circular $refs
+    circular: false,                // Don't allow circular $refs
+    excludedPathMatcher: (path) =>  // Skip dereferencing content under any 'example' key
+      path.includes("/example/")
   }
 });
 ```
@@ -75,3 +77,4 @@ The `dereference` options control how JSON Schema $Ref Parser will dereference `
 |Option(s)             |Type                |Description
 |:---------------------|:-------------------|:------------
 |`circular`|`boolean` or `"ignore"`|Determines whether [circular `$ref` pointers](README.md#circular-refs) are handled.<br><br>If set to `false`, then a `ReferenceError` will be thrown if the schema contains any circular references.<br><br> If set to `"ignore"`, then circular references will simply be ignored.  No error will be thrown, but the [`$Refs.circular`](refs.md#circular) property will still be set to `true`.
+|`excludedPathMatcher`|`(string) => boolean`|A function, called for each path, which can return true to stop this path and all subpaths from being dereferenced further. This is useful in schemas where some subpaths contain literal $ref keys that should not be dereferenced.

lib/dereference.js

@@ -41,8 +41,10 @@ function crawl (obj, path, pathFromRoot, parents, processedObjects, dereferenced
     circular: false
   };
 
+  let isExcludedPath = options.dereference.excludedPathMatcher;
+
   if (options.dereference.circular === "ignore" || !processedObjects.has(obj)) {
-    if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj)) {
+    if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
       parents.add(obj);
       processedObjects.add(obj);
 
@@ -55,6 +57,11 @@ function crawl (obj, path, pathFromRoot, parents, processedObjects, dereferenced
         for (const key of Object.keys(obj)) {
           let keyPath = Pointer.join(path, key);
           let keyPathFromRoot = Pointer.join(pathFromRoot, key);
+
+          if (isExcludedPath(keyPathFromRoot)) {
+            continue;
+          }
+
           let value = obj[key];
           let circular = false;
 

lib/index.d.ts

@@ -231,6 +231,13 @@ declare namespace $RefParser {
        * If set to `"ignore"`, then circular references will simply be ignored. No error will be thrown, but the `$Refs.circular` property will still be set to `true`.
        */
       circular?: boolean | "ignore";
+
+      /**
+       * A function, called for each path, which can return true to stop this path and all
+       * subpaths from being dereferenced further. This is useful in schemas where some
+       * subpaths contain literal $ref keys that should not be dereferenced.
+       */
+      excludedPathMatcher?(path: string): boolean;
     };
   }
 

lib/options.js

@@ -73,7 +73,16 @@ $RefParserOptions.defaults = {
      *
      * @type {boolean|string}
      */
-    circular: true
+    circular: true,
+
+    /**
+     * A function, called for each path, which can return true to stop this path and all
+     * subpaths from being dereferenced further. This is useful in schemas where some
+     * subpaths contain literal $ref keys that should not be dereferenced.
+     *
+     * @type {function}
+     */
+    excludedPathMatcher: () => false
   },
 };
 

lib/pointer.js

@@ -91,7 +91,7 @@ Pointer.prototype.resolve = function (obj, options, pathFromRoot) {
     let token = tokens[i];
     if (this.value[token] === undefined || this.value[token] === null) {
       this.value = null;
-      throw new MissingPointerError(token, this.originalPath);
+      throw new MissingPointerError(token, decodeURI(this.originalPath));
     }
     else {
       this.value = this.value[token];

lib/ref.js

@@ -135,7 +135,7 @@ $Ref.prototype.resolve = function (path, options, friendlyPath, pathFromRoot) {
     if (err instanceof InvalidPointerError) {
       // this is a special case - InvalidPointerError is thrown when dereferencing external file,
       // but the issue is caused by the source file that referenced the file that undergoes dereferencing
-      err.source = stripHash(pathFromRoot);
+      err.source = decodeURI(stripHash(pathFromRoot));
     }
 
     this.addError(err);

lib/resolve-external.js

@@ -120,7 +120,7 @@ async function resolve$Ref ($ref, path, $refs, options) {
     }
 
     if ($refs._$refs[withoutHash]) {
-      err.source = url.stripHash(path);
+      err.source = decodeURI(url.stripHash(path));
       err.path = url.safePointerToPath(url.getHash(path));
     }
 

test/specs/error-source/error-source.spec.js

@@ -8,7 +8,6 @@ const { expect } = chai;
 const $RefParser = require("../../..");
 const helper = require("../../utils/helper");
 const path = require("../../utils/path");
-const { host } = require("@jsdevtools/host-environment");
 const { InvalidPointerError, ResolverError, MissingPointerError } = require("../../../lib/util/errors");
 
 
@@ -31,12 +30,6 @@ describe("Report correct error source and path for", () => {
     }
   });
 
-  if (host.node && host.os.windows && path.cwd().includes(" ")) {
-    // The tests below don't support Windows file paths that contain spaces.
-    // TODO: Fix the tests below, rather than skipping them
-    return;
-  }
-
   it("schema with a local reference pointing at property with broken external reference", async () => {
     const parser = new $RefParser();
     try {

test/specs/ref-in-excluded-path/dereferenced.js

@@ -0,0 +1,110 @@
+"use strict";
+
+module.exports = {
+  components: {
+    examples: {
+      "confirmation-failure": {
+        value: {
+          $ref: "#/literal-component-example"
+        }
+      },
+      "confirmation-success": {
+        value: {
+          abc: "def"
+        }
+      },
+      "query-example": {
+        value: "abc"
+      }
+    },
+    parameters: {
+      a: {
+        example: {
+          $ref: "#/literal-param-component-example"
+        }
+      },
+      b: {
+        examples: {
+          example1: {
+            value: {
+              $ref: "#/literal-param-component-examples1"
+            }
+          }
+        }
+      }
+    }
+  },
+  paths: {
+    "/x/{id}": {
+      parameters: [
+        {
+          example: 123,
+          in: "path",
+          name: "id"
+        },
+        {
+          examples: {
+            e1: {
+              value: {
+                $ref: "#/literal-h1"
+              }
+            }
+          },
+          in: "header",
+          name: "h1"
+        },
+        {
+          example: {
+            $ref: "#/literal-q1"
+          },
+          in: "query",
+          name: "q1"
+        },
+        {
+          examples: {
+            q2: {
+              value: "abc"
+            }
+          },
+          in: "query",
+          name: "q2"
+        }
+      ],
+      responses: {
+        200: {
+          content: {
+            "application/json": {
+              examples: {
+                "confirmation-failure": {
+                  value: {
+                    $ref: "#/literal-component-example"
+                  }
+                },
+                "confirmation-in-progress": {
+                  summary: "In progress response",
+                  value: {
+                    $ref: "#/abc"
+                  }
+                },
+                "confirmation-success": {
+                  value: {
+                    abc: "def"
+                  }
+                }
+              }
+            }
+          }
+        },
+        400: {
+          content: {
+            "application/json": {
+              example: {
+                $ref: "#/literal-example"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+};

test/specs/ref-in-excluded-path/ref-in-excluded-path.spec.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const { expect } = require("chai");
+const $RefParser = require("../../..");
+const path = require("../../utils/path");
+const dereferencedSchema = require("./dereferenced");
+
+describe("Schema with literal $refs in examples", () => {
+  it("should exclude the given paths from dereferencing", async () => {
+    let parser = new $RefParser();
+    const schema = await parser.dereference(path.rel("specs/ref-in-excluded-path/ref-in-excluded-path.yaml"), {
+      dereference: {
+        excludedPathMatcher: (schemaPath) => {
+          return /\/example(\/|$|s\/[^\/]+\/value(\/|$))/.test(schemaPath);
+        }
+      }
+    });
+    expect(schema).to.equal(parser.schema);
+    expect(schema).to.deep.equal(dereferencedSchema);
+  });
+});