feat(rulesets): use aliases in ruleset

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

@@ -19,6 +19,7 @@
     "formats": {
       "$ref": "shared#formats"
     },
+    "shorthands": true,
     "extends": {
       "oneOf": [
         {

packages/core/src/ruleset/mergers/rulesets.ts

@@ -25,7 +25,7 @@ export function mergeRulesets(left: MergeableRuleset, right: MergeableRuleset, i
     ...right,
   };
 
-  if ('extends' in ruleset && 'extends' in ruleset) {
+  if ('extends' in ruleset) {
     const rightExtensions = getExtensions(ruleset.extends);
     (ruleset as Omit<RulesetDefinition, 'extends'> & { extends: RulesetExtendsDefinition }).extends = [
       ...(Array.isArray(ruleset.extends) ? ruleset.extends : [ruleset.extends]).filter(

packages/core/src/ruleset/ruleset.ts

@@ -41,15 +41,14 @@ export type StringifiedRuleset = {
 
 export class Ruleset {
   public readonly id = SEED++;
-
-  protected readonly extends: Ruleset[] | null;
   public readonly formats = new FormatsSet();
   public readonly overrides: RulesetOverridesDefinition | null;
   public readonly aliases: RulesetAliasesDefinition | null;
   public readonly hasComplexAliases: boolean;
   public readonly rules: Record<string, Rule>;
   public readonly definition: RulesetDefinition;
-
+  public readonly shorthands: Record<string, string> | null;
+  protected readonly extends: Ruleset[] | null;
   readonly #context: RulesetContext & { severity: FileRulesetSeverityDefinition };
 
   constructor(readonly maybeDefinition: unknown, context?: RulesetContext) {
@@ -65,7 +64,6 @@ export class Ruleset {
     }
 
     this.definition = definition;
-
     this.#context = {
       severity: 'recommended',
       ...context,
@@ -149,12 +147,21 @@ export class Ruleset {
     }
 
     this.rules = this.#getRules();
+    this.shorthands = this.#getJsonPathShorthands();
   }
 
   get source(): string | null {
     return this.#context.source ?? null;
   }
 
+  public get parserOptions(): ParserOptions {
+    return { ...DEFAULT_PARSER_OPTIONS, ...this.definition.parserOptions };
+  }
+
+  public static isDefaultRulesetFile(uri: string): boolean {
+    return DEFAULT_RULESET_FILE.test(uri);
+  }
+
   public fromSource(source: string | null): Ruleset {
     if (this.overrides === null) {
       return this;
@@ -259,6 +266,40 @@ export class Ruleset {
     return ruleset;
   }
 
+  public toJSON(): Omit<StringifiedRuleset, 'extends' | 'rules'> & {
+    extends: Ruleset['extends'];
+    rules: Ruleset['rules'];
+  } {
+    return {
+      id: this.id,
+      extends: this.extends,
+      source: this.source,
+      aliases: this.aliases,
+      formats: this.formats.size === 0 ? null : this.formats,
+      rules: this.rules,
+      overrides: this.overrides,
+      parserOptions: this.parserOptions,
+    };
+  }
+
+  #getJsonPathShorthands(): Record<string, string> {
+    const shorthands = {};
+
+    if (this.extends !== null && this.extends.length > 0) {
+      for (const extendedRuleset of this.extends) {
+        if (extendedRuleset === this || extendedRuleset.shorthands === null) continue;
+        for (const [name, value] of Object.entries(extendedRuleset.shorthands)) {
+          shorthands[name] = value;
+        }
+      }
+    }
+
+    return {
+      ...this.definition.shorthands,
+      ...shorthands,
+    };
+  }
+
   #getRules(): Record<string, Rule> {
     const rules: Record<string, Rule> = {};
 
@@ -300,28 +341,4 @@ export class Ruleset {
 
     return rules;
   }
-
-  public get parserOptions(): ParserOptions {
-    return { ...DEFAULT_PARSER_OPTIONS, ...this.definition.parserOptions };
-  }
-
-  public static isDefaultRulesetFile(uri: string): boolean {
-    return DEFAULT_RULESET_FILE.test(uri);
-  }
-
-  public toJSON(): Omit<StringifiedRuleset, 'extends' | 'rules'> & {
-    extends: Ruleset['extends'];
-    rules: Ruleset['rules'];
-  } {
-    return {
-      id: this.id,
-      extends: this.extends,
-      source: this.source,
-      aliases: this.aliases,
-      formats: this.formats.size === 0 ? null : this.formats,
-      rules: this.rules,
-      overrides: this.overrides,
-      parserOptions: this.parserOptions,
-    };
-  }
 }

packages/core/src/ruleset/types.ts

@@ -96,6 +96,7 @@ export type RulesetDefinition = Readonly<
     parserOptions?: Partial<ParserOptions>;
     overrides?: RulesetOverridesDefinition;
     aliases?: RulesetAliasesDefinition;
+    shorthands?: Record<string, string>;
   } & Readonly<
     | {
         overrides: RulesetOverridesDefinition;

packages/core/src/runner/runner.ts

@@ -60,11 +60,16 @@ export class Runner {
     const unresolvedJsonPaths = Object.keys(callbacks.unresolved);
 
     if (resolvedJsonPaths.length > 0) {
-      execute(runnerContext.documentInventory.resolved, callbacks.resolved, resolvedJsonPaths);
+      execute(runnerContext.documentInventory.resolved, callbacks.resolved, resolvedJsonPaths, ruleset.shorthands);
     }
 
     if (unresolvedJsonPaths.length > 0) {
-      execute(runnerContext.documentInventory.unresolved, callbacks.unresolved, unresolvedJsonPaths);
+      execute(
+        runnerContext.documentInventory.unresolved,
+        callbacks.unresolved,
+        unresolvedJsonPaths,
+        ruleset.shorthands,
+      );
     }
 
     this.runtime.emit('beforeTeardown');
@@ -83,7 +88,12 @@ export class Runner {
   }
 }
 
-function execute(input: unknown, callbacks: Record<string, Callback[]>, jsonPathExpressions: string[]): void {
+function execute(
+  input: unknown,
+  callbacks: Record<string, Callback[]>,
+  jsonPathExpressions: string[],
+  customShorthands: Record<string, string> | null,
+): void {
   if (!isPlainObject(input) && !Array.isArray(input)) {
     for (const cb of callbacks.$ ?? []) {
       cb({
@@ -96,6 +106,7 @@ function execute(input: unknown, callbacks: Record<string, Callback[]>, jsonPath
   }
 
   const nimma = new Nimma(jsonPathExpressions, {
+    customShorthands,
     fallback: jsonPathPlus,
     unsafe: false,
     output: 'auto',

packages/rulesets/src/oas/__tests__/oas2-parameter-description.test.ts

@@ -125,6 +125,11 @@ testRule('oas2-parameter-description', [
           ],
         },
       },
+      parameters: {
+        limit: {
+          description: 'This is how it works.',
+        },
+      },
     },
     errors: [],
   },

packages/rulesets/src/oas/functions/oasExample.ts

@@ -93,6 +93,11 @@ function* getMediaValidationItems(
   }
 }
 
+function isSubschema(givenPath: JsonPath) {
+  // todo: add more
+  return givenPath.length > 1 && !['properties', 'items', 'contains'].includes(String(givenPath[givenPath.length - 1]));
+}
+
 function* getSchemaValidationItems(
   fields: string[],
   targetVal: Record<string, unknown>,
@@ -103,6 +108,10 @@ function* getSchemaValidationItems(
       continue;
     }
 
+    if (!isSubschema(givenPath)) {
+      continue;
+    }
+
     yield {
       value: targetVal[field],
       path: [...givenPath, field],

packages/rulesets/src/oas/functions/oasSchema.ts

@@ -33,6 +33,8 @@ export default createRulesetFunction<unknown, Options>(
     },
   },
   function oasSchema(targetVal, opts, context) {
+    if (targetVal === void 0) return;
+
     const formats = context.document.formats;
 
     let { schema } = opts;

packages/rulesets/src/oas/index.ts

@@ -28,13 +28,112 @@ import {
 
 export { ruleset as default };
 
+const shorthands: Record<string, string> = {
+  schema: [
+    ...[
+      'not',
+      'if',
+      'then',
+      'else',
+      'unevaluatedProperties',
+      'additionalProperties',
+      'propertyNames',
+      'items',
+      'unevaluatedItems',
+    ].map(k => `scope.path[scope.path.length - 1] === '${k}'`),
+    ...['prefixItems', 'items', 'allOf', 'oneOf', 'anyOf'].map(
+      k => `scope.path[scope.path.length - 2] === '${k}' && Number.isInteger(scope.path[scope.path.length - 1])`,
+    ),
+    ...['patternProperties', 'properties'].map(k => `scope.path[scope.path.length - 2] === '${k}'`),
+  ].join(' || '),
+};
+
 const ruleset = {
   documentationUrl: 'https://meta.stoplight.io/docs/spectral/docs/reference/openapi-rules.md',
   formats: [oas2, oas3, oas3_0, oas3_1],
   aliases: {
     PathItem: ['$.paths[*]'],
+    ResponsesObject: {
+      targets: [
+        { formats: [oas2], given: ['$.responses', '#OperationObject.responses'] },
+        { formats: [oas3], given: ['$.components.responses', '#OperationObject.responses'] },
+      ],
+    },
+    ResponseObject: ['#ResponsesObject[*]'], // [(@ && !@.$ref)]
+    ParametersDefinitionsObject: {
+      targets: [
+        { formats: [oas2], given: ['$.parameters'] },
+        { formats: [oas3], given: ['$.components.parameters'] },
+      ],
+    },
+    ParametersObject: {
+      targets: [
+        { formats: [oas2], given: ['#PathItem.parameters', '#OperationObject.parameters'] },
+        {
+          formats: [oas3],
+          given: ['#PathItem.parameters', '#OperationObject.parameters'],
+        },
+      ],
+    },
+    ParameterObject: {
+      targets: [
+        { formats: [oas2], given: ['#ParametersDefinitionsObject[*]', '#ParametersObject[*]'] }, // ?(@ && !@.$ref)
+        {
+          formats: [oas3],
+          given: ['#ParametersDefinitionsObject[*]', '#ParametersObject[*]'], // [?(@ && !@.$ref)]
+        },
+      ],
+    },
+    EncodingObject: ['#MediaTypeObject.encoding'],
+    MediaTypeObject: ['#RequestBodyObject.content', '#ParameterObject.content', '#ResponseObject.content'],
+    HeadersObject: {
+      targets: [
+        { formats: [oas2], given: ['#ResponseObject.headers'] },
+        {
+          formats: [oas3],
+          given: ['$.components.headers', '#EncodingObject.headers', '#ResponseObject.headers'],
+        },
+      ],
+    },
+    HeaderObject: {
+      targets: [
+        { formats: [oas2], given: ['#ResponseObject.headers[*]'] },
+        {
+          formats: [oas3],
+          given: ['#HeadersObject[*]'], // ?(@ && !$.ref)
+        },
+      ],
+    },
+    RequestBodyObject: ['#OperationObject.requestBody', '$.components.requestBodies[*]'],
     OperationObject: ['#PathItem[get,put,post,delete,options,head,patch,trace]'],
+    SchemaObject: {
+      targets: [
+        {
+          formats: [oas2],
+          given: [
+            '#MediaTypeObject.schema',
+            '#MediaTypeObject.schema..@@schema()',
+            '#ParameterObject.schema',
+            '#ParameterObject.schema..@@schema()',
+            '$.definitions[*]',
+            '$.definitions[*]..@@schema()',
+          ],
+        },
+        {
+          formats: [oas3],
+          given: [
+            '#MediaTypeObject.schema',
+            '#MediaTypeObject.schema..@@schema()',
+            '#ParameterObject.schema',
+            '#ParameterObject.schema..@@schema()',
+            '$.components.schemas[*]',
+            '$.components.schemas[*]..@@schema()',
+          ],
+        },
+      ],
+    },
   },
+  shorthands,
   rules: {
     'operation-success-response': {
       description: 'Operation must have at least one "2xx" or "3xx" response.',
@@ -123,7 +222,7 @@ const ruleset = {
       severity: 'warn',
       recommended: true,
       message: '{{error}}',
-      given: ["$..[?(@property !== 'properties' && @ && @.enum)]"],
+      given: ['#SchemaObject'],
       then: {
         field: 'enum',
         function: oasSchema,
@@ -440,7 +539,7 @@ const ruleset = {
       description: 'Parameter objects must have "description".',
       recommended: false,
       formats: [oas2],
-      given: '$..parameters[?(@ && @.in)]',
+      given: '#ParameterObject',
       type: 'style',
       then: {
         field: 'description',
@@ -575,11 +674,9 @@ const ruleset = {
       type: 'style',
       given: [
         '$.components.examples[*]',
-        '$.paths[*][*]..content[*].examples[*]',
-        '$.paths[*][*]..parameters[*].examples[*]',
-        '$.components.parameters[*].examples[*]',
-        '$.paths[*][*]..headers[*].examples[*]',
-        '$.components.headers[*].examples[*]',
+        '#MediaTypeObject.examples[*]',
+        '#ParameterObject.examples[*]',
+        '#HeaderObject.examples[*]',
       ],
       then: {
         function: xor,
@@ -608,11 +705,7 @@ const ruleset = {
       recommended: false,
       formats: [oas3],
       type: 'style',
-      given: [
-        '#PathItem.parameters[?(@ && @.in)]',
-        '#OperationObject.parameters[?(@ && @.in)]',
-        '$.components.parameters[?(@ && @.in)]',
-      ],
+      given: '#ParameterObject',
       then: {
         field: 'description',
         function: truthy,