fix: scope AJV instances per lintDocument call to fix concurrent validation

.changeset/fix-ajv-concurrent-lint.md

@@ -0,0 +1,5 @@
+---
+'@redocly/openapi-core': patch
+---
+
+Fixed spurious "can't resolve reference" warnings when linting multiple APIs concurrently.

packages/core/src/__tests__/fixtures/concurrent-lint/common.yaml

@@ -0,0 +1,12 @@
+openapi: '3.0.0'
+info:
+  title: Common
+  version: '1.0.0'
+paths: {}
+components:
+  schemas:
+    Error:
+      type: object
+      properties:
+        message:
+          type: string

packages/core/src/__tests__/fixtures/concurrent-lint/spec-a.yaml

@@ -0,0 +1,39 @@
+openapi: '3.0.0'
+info:
+  title: Service A
+  version: '1.0.0'
+servers:
+  - url: https://a.example.com
+security:
+  - BearerAuth: []
+paths:
+  /a:
+    post:
+      operationId: create_a
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Foo'
+            example:
+              name: 'test'
+      responses:
+        '200':
+          description: OK
+        '400':
+          description: Error
+          content:
+            application/json:
+              schema:
+                $ref: './common.yaml#/components/schemas/Error'
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    Foo:
+      type: object
+      properties:
+        name:
+          type: string

packages/core/src/__tests__/fixtures/concurrent-lint/spec-b.yaml

@@ -0,0 +1,39 @@
+openapi: '3.0.0'
+info:
+  title: Service B
+  version: '1.0.0'
+servers:
+  - url: https://b.example.com
+security:
+  - BearerAuth: []
+paths:
+  /b:
+    post:
+      operationId: create_b
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Bar'
+            example:
+              value: 42
+      responses:
+        '200':
+          description: OK
+        '400':
+          description: Error
+          content:
+            application/json:
+              schema:
+                $ref: './common.yaml#/components/schemas/Error'
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    Bar:
+      type: object
+      properties:
+        value:
+          type: integer

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

@@ -2003,6 +2003,26 @@ describe('lint', () => {
     expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
   });
 
+  it('should not produce spurious example validation errors when linting concurrently', async () => {
+    const config = await createConfig({
+      rules: { 'no-invalid-media-type-examples': 'error' },
+    });
+
+    const [resultsA, resultsB] = await Promise.all([
+      lint({
+        ref: path.join(__dirname, 'fixtures/concurrent-lint/spec-a.yaml'),
+        config,
+      }),
+      lint({
+        ref: path.join(__dirname, 'fixtures/concurrent-lint/spec-b.yaml'),
+        config,
+      }),
+    ]);
+
+    expect(resultsA).toHaveLength(0);
+    expect(resultsB).toHaveLength(0);
+  });
+
   it('should report no unresolved extends when scorecardClassic extends contains a ref to non existing preset', async () => {
     const testConfigContent = outdent`
       scorecardClassic:

packages/core/src/lint.ts

@@ -5,7 +5,6 @@ import { initRules } from './config/rules.js';
 import { detectSpec, getMajorSpecVersion } from './detect-spec.js';
 import { getTypes } from './oas-types.js';
 import { BaseResolver, resolveDocument, makeDocumentFromString, type Document } from './resolve.js';
-import { releaseAjvInstance } from './rules/ajv.js';
 import { NoUnresolvedRefs } from './rules/common/no-unresolved-refs.js';
 import { Struct } from './rules/common/struct.js';
 import { normalizeTypes, type NodeType } from './types/index.js';
@@ -71,8 +70,6 @@ export async function lintDocument(opts: {
   customTypes?: Record<string, NodeType>;
   externalRefResolver: BaseResolver;
 }) {
-  releaseAjvInstance(); // FIXME: preprocessors can modify nodes which are then cached to ajv-instance by absolute path
-
   const { document, customTypes, externalRefResolver, config } = opts;
   const specVersion = detectSpec(document.parsed);
   const specMajorVersion = getMajorSpecVersion(specVersion);

packages/core/src/rules/__tests__/ajv.test.ts

@@ -32,24 +32,25 @@ vi.mock('ajv-formats', () => {
 
 import { Location } from '../../ref-utils.js';
 import type { Source } from '../../resolve.js';
-import { validateJsonSchema, releaseAjvInstance } from '../ajv.js';
+import { AjvValidator } from '../ajv.js';
 
-describe('ajv configuration', () => {
+describe('AjvValidator', () => {
   const resolve = () => ({ node: undefined, location: undefined });
   const baseLocation = createBaseLocation();
 
   beforeEach(() => {
-    releaseAjvInstance();
+    vi.clearAllMocks();
   });
 
   describe('dialect selection by specVersion', () => {
     it('should use draft4 constructor for oas3_0', () => {
       const mockAjvInstance = createMockAjvInstance();
       mockAjvDraft4Constructor.mockReturnValue(mockAjvInstance);
 
+      const validator = new AjvValidator();
       const schema = { type: 'integer' };
 
-      validateJsonSchema(10, schema, {
+      validator.validate(10, schema, {
         schemaLoc: baseLocation,
         instancePath: '/example',
         resolve,
@@ -68,9 +69,10 @@ describe('ajv configuration', () => {
       const mockAjvInstance = createMockAjvInstance();
       mockAjv2020Constructor.mockReturnValue(mockAjvInstance);
 
+      const validator = new AjvValidator();
       const schema = { type: 'integer' };
 
-      validateJsonSchema(10, schema, {
+      validator.validate(10, schema, {
         schemaLoc: baseLocation,
         instancePath: '/example',
         resolve,
@@ -91,9 +93,10 @@ describe('ajv configuration', () => {
       const mockAjvInstance = createMockAjvInstance();
       mockAjvDraft4Constructor.mockReturnValue(mockAjvInstance);
 
+      const validator = new AjvValidator();
       const schema = { type: 'string' };
 
-      validateJsonSchema('test', schema, {
+      validator.validate('test', schema, {
         schemaLoc: baseLocation,
         instancePath: '/example',
         resolve,
@@ -111,9 +114,10 @@ describe('ajv configuration', () => {
       const mockAjvInstance = createMockAjvInstance();
       mockAjv2020Constructor.mockReturnValue(mockAjvInstance);
 
+      const validator = new AjvValidator();
       const schema = { type: 'string' };
 
-      validateJsonSchema('test', schema, {
+      validator.validate('test', schema, {
         schemaLoc: baseLocation,
         instancePath: '/example',
         resolve,
@@ -130,9 +134,10 @@ describe('ajv configuration', () => {
       const mockAjvInstance = createMockAjvInstance();
       mockAjvDraft4Constructor.mockReturnValue(mockAjvInstance);
 
+      const validator = new AjvValidator();
       const schema = { type: 'string' };
 
-      validateJsonSchema('test', schema, {
+      validator.validate('test', schema, {
         schemaLoc: baseLocation,
         instancePath: '/example',
         resolve,
@@ -157,9 +162,10 @@ describe('ajv configuration', () => {
       };
       mockAjvDraft4Constructor.mockReturnValue(mockAjvInstance);
 
+      const validator = new AjvValidator();
       const schema = { type: 'integer' };
 
-      validateJsonSchema(10, schema, {
+      validator.validate(10, schema, {
         schemaLoc: baseLocation,
         instancePath: '/example',
         resolve,
@@ -183,9 +189,10 @@ describe('ajv configuration', () => {
       };
       mockAjv2020Constructor.mockReturnValue(mockAjvInstance);
 
+      const validator = new AjvValidator();
       const schema = { type: 'integer' };
 
-      validateJsonSchema(10, schema, {
+      validator.validate(10, schema, {
         schemaLoc: baseLocation,
         instancePath: '/example',
         resolve,