feat(spectral): add rule to prevent external relative references (#9)

Author: Enda

spectral/README.md

@@ -210,6 +210,14 @@ List:
 
 **Severity**: warning
 
+### rhoas-external-$ref
+
+`$ref` values cannot be a relative path to an external file. Please use the absolute URL or convert it to an internal `$ref`.
+
+**Recommended**: Yes
+
+**Severity**: error
+
 ## Development
 
 > NOTE: This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/) for easier development.

spectral/examples/openapi-invalid.yaml

@@ -23,6 +23,12 @@ paths:
             application/json:
               schema:
                $ref: '#/components/schemas/Error' 
+        "400":
+          description: br
+          content:
+            application/json:
+              schema:
+                $ref: 'openapi-invalid.yaml#/components/schemas/Error'
   /api/foo_mgmt/v1beta/foos/{id}:
     get:
       operationId: getFooById
@@ -90,4 +96,4 @@ components:
     Bearer:
       scheme: 'bearer'
       bearerFormat: 'JWT'
-      type: 'http'
+      type: 'http'

spectral/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhoas/spectral-ruleset",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Spectral ruleset",
   "private": false,
   "main": "ruleset.yaml",

spectral/ruleset.yaml

@@ -5,10 +5,18 @@ functions:
   - securitySchemes
   - infoLicenseApache2
   - schemaDefinition
+  - externalRefs
 rules:
   openapi-tags: off
   operation-tags: off
 
+  rhoas-external-$ref:
+    given: "$..['$ref']"
+    severity: error
+    type: 'validation'
+    resolved: false
+    then:
+      function: externalRefs
   rhoas-oas3minimum:
     given: "$"
     description: OpenAPI version must be >= 3
@@ -163,4 +171,4 @@ rules:
               required: true
             total:
               type: integer
-              required: true
+              required: true

spectral/src/functions/externalRefs.ts

@@ -0,0 +1,15 @@
+import { IFunctionResult } from "@stoplight/spectral";
+
+export default (targetVal: any): IFunctionResult[] => {
+    if (!targetVal || !targetVal.length) {
+        return
+    }
+
+    if (targetVal.startsWith('https') || targetVal.startsWith('http') || targetVal.startsWith('#/')) {
+        return;
+    } else {
+        return [{
+            message: 'Only local relative `$ref` or absolute external URL `$ref` is allowed'
+        }]
+    }
+}