feat: dedupe results by unique fingerprint

docs/guides/javascript.md

@@ -76,10 +76,10 @@ spectral.registerFormat('oas3', isOpenApiv3);
 const {
   Spectral,
   isJSONSchema,
-  isJSONSchemaDraft4, 
+  isJSONSchemaDraft4,
   isJSONSchemaDraft6,
-  isJSONSchemaDraft7, 
-  isJSONSchemaDraft2019_09, 
+  isJSONSchemaDraft7,
+  isJSONSchemaDraft2019_09,
   isJSONSchemaLoose,
 } = require('@stoplight/spectral');
 
@@ -96,7 +96,7 @@ Learn more about predefined formats in the (ruleset documentation)[../getting-st
 
 ## Loading Rules
 
-Spectral comes with some rulesets that are very specific to OpenAPI v2/v3, and they can be loaded using `Spectral.loadRuleset()`. 
+Spectral comes with some rulesets that are very specific to OpenAPI v2/v3, and they can be loaded using `Spectral.loadRuleset()`.
 
 ```js
 const { Spectral, isOpenApiv2, isOpenApiv3 } = require('@stoplight/spectral');
@@ -114,7 +114,7 @@ spectral.loadRuleset('spectral:oas')
   .then(results => {
     console.log('here are the results', results);
   });
-``` 
+```
 
 The OpenAPI rules are opinionated. There might be some rules that you prefer to change, or disable. We encourage you to create your rules to fit your use case, and we welcome additions to the existing rulesets as well!
 
@@ -153,17 +153,20 @@ spectral
   .then(result => {
     expect(result).toEqual([
       expect.objectContaining({
-       code: 'rule1',   
+       code: 'rule1',
      }),
    ]);
   });
 ```
 
 ### Using custom resolver
 
-Spectral lets you provide any custom $ref resolver. By default, http(s) and file protocols are resolved, relatively to the document Spectral lints against.
-If you'd like support any additional protocol or adjust the resolution, you are absolutely fine to do it.
-In order to achieve that, you need to create a custom json-ref-resolver instance.
+Spectral lets you provide any custom $ref resolver. By default, http(s) and file protocols are resolved, relatively to
+the document Spectral lints against. If you'd like support any additional protocol or adjust the resolution, you are
+absolutely fine to do it. In order to achieve that, you need to create a custom json-ref-resolver instance.
+
+You can find more information about how to create custom resolvers in
+the [@stoplight/json-ref-resolver](https://github.com/stoplightio/json-ref-resolver) repository.
 
 ```js
 const path = require('path');
@@ -199,3 +202,28 @@ const spectral = new Spectral({ resolver: customFileResolver });
 The custom resolver we've just created will resolve all remote file refs relatively to the current working directory.
 
 More on that can be found in the [json-ref-resolver repo](https://github.com/stoplightio/json-ref-resolver).
+
+### Using custom de-duplication strategy
+
+By default, Spectral will de-duplicate results based on the result code and document location. You can customize this
+behavior with the `computeFingerprint` option. For example, here is the default fingerprint implementation:
+
+The final reported results are de-duplicated based on their computed fingerprint.
+
+```ts
+const spectral = new Spectral({
+  computeFingerprint: (rule: IRuleResult, hash) => {
+    let id = String(rule.code);
+
+    if (rule.path && rule.path.length) {
+      id += JSON.stringify(rule.path);
+    } else if (rule.range) {
+      id += JSON.stringify(rule.range);
+    }
+
+    if (rule.source) id += rule.source;
+
+    return hash(id);
+  },
+});
+```

package.json

@@ -69,6 +69,7 @@
     "ajv": "^6.10",
     "ajv-oai": "^1.1.5",
     "better-ajv-errors": "^0.6.7",
+    "blueimp-md5": "^2.12.0",
     "chalk": "^3.0.0",
     "eol": "^0.9.1",
     "fast-glob": "^3.1.0",

src/__tests__/linter.jest.test.ts

@@ -78,7 +78,7 @@ describe('Linter', () => {
     ]);
   });
 
-  describe('evaluate {{value}} in validation messages', () => {
+  describe('evaluate "value" in validation messages', () => {
     test('should print correct values for referenced files', async () => {
       spectral = new Spectral({ resolver: httpAndFileResolver });
 

src/__tests__/linter.test.ts

@@ -96,7 +96,7 @@ describe('linter', () => {
     });
 
     expect(result).toEqual([
-      {
+      expect.objectContaining({
         code: 'rule1',
         message,
         severity: DiagnosticSeverity.Warning,
@@ -111,7 +111,7 @@ describe('linter', () => {
             line: 5,
           },
         },
-      },
+      }),
     ]);
   });
 

src/__tests__/spectral.jest.test.ts

@@ -195,7 +195,7 @@ describe('Spectral', () => {
     );
   });
 
-  test('should recognize the source of remote $refs', async () => {
+  test('should recognize the source of remote $refs, and de-dupe results by fingerprint', async () => {
     const s = new Spectral({ resolver: httpAndFileResolver });
     const documentUri = path.join(__dirname, './__fixtures__/gh-658/URIError.yaml');
 
@@ -214,6 +214,8 @@ describe('Spectral', () => {
 
     const results = await s.run(fs.readFileSync(documentUri, 'utf8'), { resolve: { documentUri } });
 
+    expect(results.length).toEqual(3);
+
     return expect(results).toEqual([
       expect.objectContaining({
         path: ['paths', '/test', 'get', 'responses', '200', 'content', 'application/json', 'schema'],
@@ -263,108 +265,6 @@ describe('Spectral', () => {
           },
         },
       }),
-
-      expect.objectContaining({
-        path: ['components', 'schemas', 'Error', 'properties', 'status_code'],
-        source: expect.stringContaining('/src/__tests__/__fixtures__/gh-658/lib.yaml'),
-        range: {
-          end: {
-            character: 22,
-            line: 21,
-          },
-          start: {
-            character: 20,
-            line: 20,
-          },
-        },
-      }),
-      expect.objectContaining({
-        path: ['components', 'schemas', 'Foo'],
-        source: expect.stringContaining('/src/__tests__/__fixtures__/gh-658/URIError.yaml'),
-        range: {
-          end: {
-            character: 18,
-            line: 43,
-          },
-          start: {
-            character: 8,
-            line: 42,
-          },
-        },
-      }),
-
-      expect.objectContaining({
-        path: ['components', 'schemas', 'Foo'],
-        source: expect.stringContaining('/src/__tests__/__fixtures__/gh-658/URIError.yaml'),
-        range: {
-          end: {
-            character: 18,
-            line: 43,
-          },
-          start: {
-            character: 8,
-            line: 42,
-          },
-        },
-      }),
-
-      expect.objectContaining({
-        path: ['components', 'schemas', 'Error', 'properties', 'status_code'],
-        source: expect.stringContaining('/src/__tests__/__fixtures__/gh-658/lib.yaml'),
-        range: {
-          end: {
-            character: 22,
-            line: 21,
-          },
-          start: {
-            character: 20,
-            line: 20,
-          },
-        },
-      }),
-      expect.objectContaining({
-        path: ['components', 'schemas', 'Foo'],
-        source: expect.stringContaining('/src/__tests__/__fixtures__/gh-658/URIError.yaml'),
-        range: {
-          end: {
-            character: 18,
-            line: 43,
-          },
-          start: {
-            character: 8,
-            line: 42,
-          },
-        },
-      }),
-
-      expect.objectContaining({
-        path: ['components', 'schemas', 'Error', 'properties', 'status_code'],
-        source: expect.stringContaining('/src/__tests__/__fixtures__/gh-658/lib.yaml'),
-        range: {
-          end: {
-            character: 22,
-            line: 21,
-          },
-          start: {
-            character: 20,
-            line: 20,
-          },
-        },
-      }),
-      expect.objectContaining({
-        path: ['components', 'schemas', 'Foo'],
-        source: expect.stringContaining('/src/__tests__/__fixtures__/gh-658/URIError.yaml'),
-        range: {
-          end: {
-            character: 18,
-            line: 43,
-          },
-          start: {
-            character: 8,
-            line: 42,
-          },
-        },
-      }),
     ]);
   });
 });

src/rulesets/oas/__tests__/contact-properties.ts

@@ -33,39 +33,6 @@ describe('contact-properties', () => {
       info: { contact: {} },
     });
     expect(results).toEqual([
-      {
-        code: 'contact-properties',
-        message: 'Contact object should have `name`, `url` and `email`.',
-        path: ['info', 'contact'],
-        range: {
-          end: {
-            character: 17,
-            line: 4,
-          },
-          start: {
-            character: 14,
-            line: 4,
-          },
-        },
-        severity: 1,
-        source: undefined,
-      },
-      {
-        code: 'contact-properties',
-        message: 'Contact object should have `name`, `url` and `email`.',
-        path: ['info', 'contact'],
-        range: {
-          end: {
-            character: 17,
-            line: 4,
-          },
-          start: {
-            character: 14,
-            line: 4,
-          },
-        },
-        severity: DiagnosticSeverity.Warning,
-      },
       {
         code: 'contact-properties',
         message: 'Contact object should have `name`, `url` and `email`.',

src/rulesets/oas/functions/__tests__/oasOpParams.test.ts

@@ -144,7 +144,7 @@ describe('oasOpParams', () => {
         },
       },
     });
-    expect(results.length).toEqual(2);
+    expect(results.length).toEqual(1);
   });
 
   test('Error if multiple in:body', async () => {

src/spectral.ts

@@ -1,10 +1,12 @@
+const md5 = require('blueimp-md5');
+
 import { getLocationForJsonPath as getLocationForJsonPathJson, JsonParserResult, safeStringify } from '@stoplight/json';
 import { Resolver } from '@stoplight/json-ref-resolver';
 import { ICache, IUriParser } from '@stoplight/json-ref-resolver/types';
 import { extname, normalize } from '@stoplight/path';
 import { Dictionary, IDiagnostic, Optional } from '@stoplight/types';
 import { getLocationForJsonPath as getLocationForJsonPathYaml, YamlParserResult } from '@stoplight/yaml';
-import { merge } from 'lodash';
+import { memoize, merge, uniqBy } from 'lodash';
 
 import { STATIC_ASSETS } from './assets';
 import { formatParserDiagnostics, formatResolverErrors } from './error-messages';
@@ -31,20 +33,24 @@ import {
   RunRuleCollection,
 } from './types';
 import { IRuleset } from './types/ruleset';
-import { empty } from './utils';
+import { ComputeFingerprintFunc, defaultComputeResultFingerprint, empty } from './utils';
+
+memoize.Cache = WeakMap;
 
 export * from './types';
 
 export class Spectral {
-  private readonly _resolver: IResolver;
-  private readonly _parsedRefs: Dictionary<IParsedResult>;
-  private static readonly _parsedCache = new WeakMap<ICache | IResolver, Dictionary<IParsedResult>>();
   public functions: FunctionCollection = { ...defaultFunctions };
   public rules: RunRuleCollection = {};
-
   public formats: RegisteredFormats;
 
+  private readonly _computeFingerprint: ComputeFingerprintFunc;
+  private readonly _resolver: IResolver;
+  private readonly _parsedRefs: Dictionary<IParsedResult>;
+  private static readonly _parsedCache = new WeakMap<ICache | IResolver, Dictionary<IParsedResult>>();
+
   constructor(opts?: IConstructorOpts) {
+    this._computeFingerprint = memoize(opts?.computeFingerprint || defaultComputeResultFingerprint);
     this._resolver = opts && opts.resolver ? opts.resolver : new Resolver();
     this.formats = {};
 
@@ -108,9 +114,19 @@ export class Spectral {
       ...runRules(resolved, this.rules, this.functions),
     ];
 
+    // add fingerprint func to each result, to uniquely identify and group them
+    const computeFingerprint = this._computeFingerprint;
+    for (const r of validationResults) {
+      Object.defineProperty(r, 'fingerprint', {
+        get() {
+          return computeFingerprint(r, md5);
+        },
+      });
+    }
+
     return {
       resolved: resolved.resolved,
-      results: validationResults,
+      results: uniqBy(validationResults, 'fingerprint'),
     };
   }
 

src/types/spectral.ts

@@ -9,6 +9,7 @@ import {
 } from '@stoplight/types';
 import { JSONSchema4, JSONSchema6, JSONSchema7 } from 'json-schema';
 import { IFunction, IRule, Rule } from '.';
+import { ComputeFingerprintFunc } from '../utils';
 
 export type FunctionCollection = Dictionary<IFunction, string>;
 export type RuleCollection = Dictionary<Rule, string>;
@@ -31,6 +32,7 @@ export type RuleDeclarationCollection = Dictionary<boolean, string>;
 
 export interface IConstructorOpts {
   resolver?: IResolver;
+  computeFingerprint?: ComputeFingerprintFunc;
 }
 
 export interface IRunOpts {

src/utils/fingerprint.ts

@@ -0,0 +1,17 @@
+import { IRuleResult } from '../types';
+
+export type ComputeFingerprintFunc = (rule: IRuleResult, hash: (val: string) => string) => string;
+
+export const defaultComputeResultFingerprint: ComputeFingerprintFunc = (rule, hash) => {
+  let id = String(rule.code);
+
+  if (rule.path && rule.path.length) {
+    id += JSON.stringify(rule.path);
+  } else if (rule.range) {
+    id += JSON.stringify(rule.range);
+  }
+
+  if (rule.source) id += rule.source;
+
+  return hash(id);
+};