feat(core): aliases take only array-ish given

docs/guides/4-custom-rulesets.md

@@ -31,7 +31,7 @@ It has a specific syntax known as [JSONPath](https://goessner.net/articles/JsonP
 Both of them support all the main JSONPath functionality and a little bit more, but this syntax may differ slightly from other JSONPath implementations.
 
 Your `given` value can be a string containing any valid JSONPath expression, or an array of expressions to apply a rule to multiple parts of a document.
-You can also consume your [aliases][#aliases] here if you have some defined.
+You can also consume your (aliases)[#aliases] here if you have some defined.
 
 Use the [JSONPath Online Evaluator](http://jsonpath.com/) to determine what `given` path you want.
 
@@ -328,17 +328,22 @@ Targeting certain parts of an OpenAPI spec is powerful but it can become cumbers
 Define aliases for commonly used JSONPath expressions on a global level which can then be reused across the ruleset.
 
 Aliases can be defined in an array of key-value pairs at the root level of the ruleset.
-It's a superset of `given`, with the notable difference being the possibility to distinguish between different formats.
+It's similar to `given`, with the notable difference being the possibility to distinguish between different formats.
 
 **Example**
 
 ```yaml
 aliases:
-  HeaderNames: "$..parameters.[?(@.in === 'header')].name"
-  Info: "$..info"
-  InfoDescription: "#Info.description"
-  InfoContact: "#Info.contact"
-  Paths: "$.paths[*]~"
+  HeaderNames:
+    - "$..parameters.[?(@.in === 'header')].name"
+  Info:
+    - "$..info"
+  InfoDescription:
+    - "#Info.description"
+  InfoContact:
+    - "#Info.contact"
+  Paths:
+    - "$.paths[*]~"
 ```
 
 If you deal with a variety of different spec, you may find the above approach insufficient, particularly when the shape of the document is notably different.
@@ -351,10 +356,12 @@ aliases:
     targets:
       - formats:
           - oas2
-        given: $.parameters[*]
+        given:
+          - $.parameters[*]
       - formats:
           - oas3
-        given: $.components.parameters[*]
+        given:
+          - $.components.parameters[*]
 ```
 
 Now, if you referenced `SharedParameterObject` alias, the chosen path would be determined based on the document you use.
@@ -366,8 +373,10 @@ To make it more feasible and avoid overly complex JSONPath expressions, `given`
 
 ```yaml
 aliases:
-  PathItemObject: $.paths[*]
-  OperationObject: "#PathItem[get,put,post,delete,options,head,patch,trace]"
+  PathItemObject:
+    - $.paths[*]
+  OperationObject:
+    - "#PathItem[get,put,post,delete,options,head,patch,trace]"
   ParameterObject:
     description: an optional property describing the purpose of the alias
     targets:

packages/core/src/meta/ruleset.schema.json

@@ -191,7 +191,7 @@
                     "$ref": "shared#formats"
                   },
                   "given": {
-                    "$ref": "shared#given"
+                    "$ref": "shared#arrayish-given"
                   }
                 },
                 "required": ["formats", "given"],
@@ -208,7 +208,7 @@
           }
         },
         "else": {
-          "$ref": "shared#given"
+          "$ref": "shared#arrayish-given"
         }
       }
     }

packages/core/src/meta/shared.json

@@ -39,6 +39,7 @@
         "type": "array"
       },
       "then": {
+        "$anchor": "arrayish-given",
         "type": "array",
         "items": {
           "$ref": "path-expression"

packages/core/src/ruleset/__tests__/__fixtures__/overrides/aliases/scope.ts

@@ -1,12 +1,12 @@
 import { DiagnosticSeverity } from '@stoplight/types';
-import {falsy, pattern, truthy} from '@stoplight/spectral-functions';
+import { falsy, pattern, truthy } from '@stoplight/spectral-functions';
 import { RulesetDefinition } from '@stoplight/spectral-core';
 
 export { ruleset as default };
 
 const ruleset: RulesetDefinition = {
   aliases: {
-    Stoplight: '$..stoplight',
+    Stoplight: ['$..stoplight'],
   },
   overrides: [
     {
@@ -29,7 +29,7 @@ const ruleset: RulesetDefinition = {
     {
       files: ['**/*.json'],
       aliases: {
-        Value: '$..value',
+        Value: ['$..value'],
       },
       rules: {
         'truthy-stoplight-property': {

packages/core/src/ruleset/__tests__/ruleset.test.ts

@@ -1004,10 +1004,10 @@ describe('Ruleset', () => {
         print(
           new Ruleset({
             aliases: {
-              Info: '$.info',
-              PathItem: '$.paths[*][*]',
-              Description: '$..description',
-              Name: '$..name',
+              Info: ['$.info'],
+              PathItem: ['$.paths[*][*]'],
+              Description: ['$..description'],
+              Name: ['$..name'],
             },
 
             rules: {
@@ -1066,10 +1066,10 @@ describe('Ruleset', () => {
           JSON.stringify(
             new Ruleset({
               aliases: {
-                Info: '$.info',
-                PathItem: '$.paths[*][*]',
-                Description: '$..description',
-                Name: '$..name',
+                Info: ['$.info'],
+                PathItem: ['$.paths[*][*]'],
+                Description: ['$..description'],
+                Name: ['$..name'],
               },
 
               rules: {
@@ -1108,10 +1108,10 @@ describe('Ruleset', () => {
           incompatibleValues: DiagnosticSeverity.Error,
         },
         aliases: {
-          Info: '$.info',
-          PathItem: '$.paths[*][*]',
-          Description: '$..description',
-          Name: '$..name',
+          Info: ['$.info'],
+          PathItem: ['$.paths[*][*]'],
+          Description: ['$..description'],
+          Name: ['$..name'],
         },
         rules: {
           'valid-path': {
@@ -1179,10 +1179,10 @@ describe('Ruleset', () => {
         print(
           new Ruleset({
             aliases: {
-              Info: '$.info',
-              InfoDescription: '#Info.description',
-              InfoContact: '#Info.contact',
-              InfoContactName: '#InfoContact.name',
+              Info: ['$.info'],
+              InfoDescription: ['#Info.description'],
+              InfoContact: ['#Info.contact'],
+              InfoContactName: ['#InfoContact.name'],
             },
 
             rules: {
@@ -1241,7 +1241,7 @@ describe('Ruleset', () => {
           new Ruleset({
             extends: {
               aliases: {
-                PathItem: '$.paths[*][*]',
+                PathItem: ['$.paths[*][*]'],
               },
               rules: {},
             },
@@ -1262,10 +1262,10 @@ describe('Ruleset', () => {
         () =>
           new Ruleset({
             aliases: {
-              Root: '#Info',
-              Info: '#Root.test',
-              Contact: '#Info',
-              Test: '#Contact.test',
+              Root: ['#Info'],
+              Info: ['#Root.test'],
+              Contact: ['#Info'],
+              Test: ['#Contact.test'],
             },
             rules: {
               'valid-path': {
@@ -1287,9 +1287,9 @@ describe('Ruleset', () => {
           new Ruleset({
             extends: {
               aliases: {
-                PathItem: '$.paths[*][*]',
-                Description: '$..description',
-                Name: '$..name',
+                PathItem: ['$.paths[*][*]'],
+                Description: ['$..description'],
+                Name: ['$..name'],
               },
               rules: {},
             },
@@ -1331,17 +1331,17 @@ describe('Ruleset', () => {
               targets: [
                 {
                   formats: [draft4],
-                  given: '$..id',
+                  given: ['$..id'],
                 },
                 {
                   formats: [draft6, draft7],
-                  given: '$..$id',
+                  given: ['$..$id'],
                 },
               ],
             },
 
-            PathItem: '$.paths[*]',
-            OperationObject: '#PathItem[get,put,post,delete,options,head,patch,trace]',
+            PathItem: ['$.paths[*]'],
+            OperationObject: ['#PathItem[get,put,post,delete,options,head,patch,trace]'],
             ParametersDefinitionsObject: {
               targets: [
                 { formats: [oas2], given: ['$.parameters'] },
@@ -1461,7 +1461,7 @@ describe('Ruleset', () => {
               targets: [
                 {
                   formats: [draft6],
-                  given: '$..$id',
+                  given: ['$..$id'],
                 },
               ],
             },
@@ -1500,11 +1500,11 @@ describe('Ruleset', () => {
                     targets: [
                       {
                         formats: [draft4],
-                        given: '$..id',
+                        given: ['$..id'],
                       },
                       {
                         formats: [draft6, draft7],
-                        given: '$..$id',
+                        given: ['$..$id'],
                       },
                     ],
                   },
@@ -1536,11 +1536,11 @@ describe('Ruleset', () => {
               targets: [
                 {
                   formats: ['draft4'],
-                  given: '$..id',
+                  given: ['$..id'],
                 },
                 {
                   formats: ['draft6', 'draft7'],
-                  given: '$..$id',
+                  given: ['$..$id'],
                 },
               ],
             },