Merge branch 'develop' into feat/rule-extensions

Author: pavelkornev

README.md

@@ -84,12 +84,20 @@ If you have a bug or feature request, please [create an issue](https://github.co
 
 ## 🌎 Real-World Rulesets
 
+Stoplight has a set of Spectral rulesets that were created to help users get started with Stoplight's Style Guides. You can find them on [API Stylebook](https://apistylebook.stoplight.io/), and you can download the source Spectral file by selecting a style guide on the project sidebar and selecting **Export** -> **Spectral File(s)** on the top-right. A few noteworthy style guides are:
+
+- [OWASP Top 10](https://apistylebook.stoplight.io/docs/owasp-top-10) - Set of rules to enforce [OWASP security guidelines](https://owasp.org/www-project-api-security/).
+- [URL Style Guidelines](https://apistylebook.stoplight.io/docs/url-guidelines) - Set of rules to help developers make better and consistent endpoints.
+
+There are also rulesets created by many companies to improve their APIs. You can use these as is to lint your OpenAPI descriptions, or use these as a reference to learn more about what rules you would want in your own ruleset:
+
 - [Adidas](https://github.com/adidas/api-guidelines/blob/master/.spectral.yml) - Adidas were one of the first companies to release their API Style Guide in a written guide _and_ a Spectral ruleset. Lots of good rules to try in here.
 - [APIs You Won't Hate](https://github.com/apisyouwonthate/style-guide) - An opinionated collection of rules based on advice in the [APIs You Won't Hate](https://apisyouwonthate.com/) community.
 - [Azure](https://github.com/Azure/azure-api-style-guide/blob/main/spectral.yaml) - Ruleset and complimentary style guide for creating OpenAPI 2 or 3 definitions of Azure services.
 - [Box](https://github.com/box/box-openapi/blob/main/.spectral.yml) - Lots of [Custom Functions](https://meta.stoplight.io/docs/spectral/ZG9jOjI1MTkw-custom-functions) being used to enforce good practices that the Box API governance folks are interested in.
 - [DigitalOcean](https://github.com/digitalocean/openapi/blob/main/spectral/ruleset.yml) - Keeping their OpenAPI nice and tidy, enforcing use of `$ref` (probably to minimize conflicts), naming conventions for Operation IDs, and all sorts of other handy OpenAPI tips.
 - [Tranascom](https://github.com/transcom/mymove/blob/master/swagger-def/.spectral.yml) - Don't even think about using anything other than `application/json`.
+- [Zalando](https://apistylebook.stoplight.io/docs/zalando-restful-api-guidelines) - Based on [Zalando's RESTFUL API Guidelines](https://github.com/zalando/restful-api-guidelines), covers a wide-range of API topics such as versioning standards, property naming standards, the default format for request/response properties, and more.
 
 Here are [more real-world examples](https://github.com/stoplightio/spectral-rulesets) of Spectral in action.
 

packages/core/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@stoplight/spectral-core-v1.15.2](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-core-v1.15.1...@stoplight/spectral-core-v1.15.2) (2022-11-22)
+
+
+### Bug Fixes
+
+* **core:** improve deep ruleset inheritance ([#2326](https://github.com/stoplightio/spectral/issues/2326)) ([378b4b8](https://github.com/stoplightio/spectral/commit/378b4b89769635e8b45d5325c15cfa00881b70bd))
+
 # [@stoplight/spectral-core-v1.15.1](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-core-v1.15.0...@stoplight/spectral-core-v1.15.1) (2022-10-24)
 
 

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stoplight/spectral-core",
-  "version": "1.15.1",
+  "version": "1.15.2",
   "sideEffects": false,
   "homepage": "https://github.com/stoplightio/spectral",
   "bugs": "https://github.com/stoplightio/spectral/issues",

packages/core/src/ruleset/__tests__/__fixtures__/severity/off-proxy2.ts

@@ -0,0 +1,26 @@
+import { DiagnosticSeverity } from '@stoplight/types';
+import { truthy } from '@stoplight/spectral-functions';
+
+const ruleset1 = {
+  rules: {
+    'custom-info-description': {
+      message: 'API Description is missing',
+      severity: DiagnosticSeverity.Error,
+      given: '$.info',
+      then: {
+        field: 'description',
+        function: truthy,
+      },
+    },
+  },
+};
+
+const ruleset2 = {
+  extends: [ruleset1],
+  rules: {},
+};
+
+export default {
+  extends: [[ruleset2, 'off']],
+  rules: {},
+};

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

@@ -95,6 +95,13 @@ describe('Ruleset', () => {
       expect(getEnabledRules(rules)).toEqual(['overridable-rule']);
     });
 
+    it('given nested extends with severity set to off #2', async () => {
+      const { rules } = await loadRuleset(import('./__fixtures__/severity/off-proxy2'));
+      expect(Object.keys(rules)).toEqual(['custom-info-description']);
+
+      expect(getEnabledRules(rules)).toEqual([]);
+    });
+
     it('given nested extends with severity set to off and explicit override to error', async () => {
       const { rules } = await loadRuleset(import('./__fixtures__/severity/error'));
       expect(Object.keys(rules)).toEqual([

packages/core/src/ruleset/rule.ts

@@ -11,7 +11,7 @@ import type { HumanReadableDiagnosticSeverity, IRuleThen, RuleDefinition, String
 import { minimatch } from './utils/minimatch';
 import { Formats } from './formats';
 import { resolveAlias } from './alias';
-import type { Stringified } from './types';
+import type { Stringified, FileRulesetSeverityDefinition } from './types';
 
 export interface IRule {
   description: string | null;
@@ -76,6 +76,10 @@ export class Rule implements IRule {
     this.#enabled = enabled;
   }
 
+  public static isEnabled(rule: IRule, severity: FileRulesetSeverityDefinition): boolean {
+    return severity === 'all' || (severity === 'recommended' && rule.recommended);
+  }
+
   public getSeverityForSource(source: string, path: JsonPath): DiagnosticSeverity | -1 {
     if (this.overrides === void 0 || this.overrides.definition.size === 0) {
       return this.severity;

packages/core/src/ruleset/ruleset.ts

@@ -20,12 +20,14 @@ import { isSimpleAliasDefinition } from './utils/guards';
 import type { Stringified } from './types';
 
 const STACK_SYMBOL = Symbol('@stoplight/spectral/ruleset/#stack');
+const EXPLICIT_SEVERITY = Symbol('@stoplight/spectral/ruleset/#explicit-severity');
 const DEFAULT_RULESET_FILE = /^\.?spectral\.(ya?ml|json|m?js)$/;
 
 type RulesetContext = {
   readonly severity?: FileRulesetSeverityDefinition;
   readonly source?: string;
   readonly [STACK_SYMBOL]?: Map<RulesetDefinition, Ruleset>;
+  readonly [EXPLICIT_SEVERITY]?: boolean;
 };
 
 let SEED = 1;
@@ -110,8 +112,9 @@ export class Ruleset {
             (extensions, extension) => {
               let actualExtension;
               let severity: FileRulesetSeverityDefinition = 'recommended';
+              const explicitSeverity = Array.isArray(extension);
 
-              if (Array.isArray(extension)) {
+              if (explicitSeverity) {
                 [actualExtension, severity] = extension;
               } else {
                 actualExtension = extension;
@@ -123,7 +126,13 @@ export class Ruleset {
                 return extensions;
               }
 
-              extensions.push(new Ruleset(actualExtension, { severity, [STACK_SYMBOL]: stack }));
+              extensions.push(
+                new Ruleset(actualExtension, {
+                  severity,
+                  [STACK_SYMBOL]: stack,
+                  [EXPLICIT_SEVERITY]: explicitSeverity,
+                }),
+              );
               return extensions;
             },
             [],
@@ -271,6 +280,9 @@ export class Ruleset {
         if (extendedRuleset === this) continue;
         for (const rule of Object.values(extendedRuleset.rules)) {
           rules[rule.name] = rule;
+          if (this.#context[STACK_SYMBOL] !== void 0 && this.#context[EXPLICIT_SEVERITY] === true) {
+            rule.enabled = Rule.isEnabled(rule, this.#context.severity);
+          }
         }
       }
     }
@@ -281,8 +293,7 @@ export class Ruleset {
         rules[name] = rule;
 
         if (rule.owner === this) {
-          rule.enabled =
-            this.#context.severity === 'all' || (this.#context.severity === 'recommended' && rule.recommended);
+          rule.enabled = Rule.isEnabled(rule, this.#context.severity);
         }
 
         if (rule.formats !== null) {

packages/ruleset-migrator/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@stoplight/spectral-ruleset-migrator-v1.9.1](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-ruleset-migrator-v1.9.0...@stoplight/spectral-ruleset-migrator-v1.9.1) (2022-11-23)
+
+
+### Bug Fixes
+
+* **ruleset-migrator:** avoid positive lookbehinds ([#2349](https://github.com/stoplightio/spectral/issues/2349)) ([455c324](https://github.com/stoplightio/spectral/commit/455c32487b6f25465c1204186006e2c830f48eb3))
+
 # [@stoplight/spectral-ruleset-migrator-v1.9.0](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-ruleset-migrator-v1.8.0...@stoplight/spectral-ruleset-migrator-v1.9.0) (2022-10-24)
 
 

packages/ruleset-migrator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stoplight/spectral-ruleset-migrator",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "homepage": "https://github.com/stoplightio/spectral",
   "bugs": "https://github.com/stoplightio/spectral/issues",
   "author": "Stoplight <[email protected]>",

packages/ruleset-migrator/src/transformers/formats.ts

@@ -26,18 +26,11 @@ const FORMATS = [
 
 function safeFormat(format: string): string {
   return format
-    .replace(/\.|(?<=[0-9])-(?=[0-9])/g, '_')
+    .replace(/\.|([0-9])-(?=[0-9])/g, '$1_')
     .replace(/-([0-9a-z])/g, (match, char) => String(char).toUpperCase());
 }
 
-const REPLACEMENTS = Object.fromEntries(
-  FORMATS.map(format => [
-    format,
-    (ALIASES[format] ?? format)
-      .replace(/\.|(?<=[0-9])-(?=[0-9])/g, '_')
-      .replace(/-([0-9a-z])/g, (match, char) => String(char).toUpperCase()),
-  ]),
-);
+const REPLACEMENTS = Object.fromEntries(FORMATS.map(format => [format, safeFormat(ALIASES[format] ?? format)]));
 
 function transform(input: unknown, ctx: TransformerCtx): namedTypes.ArrayExpression {
   assertArray(input);