refactor: add reference header rule

Author: robert-hebel-sb

packages/apidom-ls/src/config/codes.ts

@@ -1074,6 +1074,7 @@ enum ApilintCodes {
   OPENAPI3_0_REFERENCE_FIELD_$REF_REQUEST_BODIES = 5260200,
   OPENAPI3_0_REFERENCE_FIELD_$REF_REQUEST_BODIES_NAMING,
   OPENAPI3_0_REFERENCE_FIELD_$REF_REQUEST_BODIES_NAMING_SCHEMA,
+  OPENAPI3_0_REFERENCE_FIELD_$REF_HEADER = 5260300,
 
   OPENAPI3_0_LINK = 5270000,
   OPENAPI3_0_LINK_FIELD_OPERATION_REF_FORMAT_URI = 5270100,

packages/apidom-ls/src/config/openapi/header/lint/$ref-3-0--header.ts

@@ -0,0 +1,27 @@
+import { DiagnosticSeverity } from 'vscode-languageserver-types';
+
+import ApilintCodes from '../../../codes.ts';
+import { LinterMeta } from '../../../../apidom-language-types.ts';
+import { OpenAPI3 } from '../../target-specs.ts';
+
+const $ref3HeaderNamingLint: LinterMeta = {
+  code: ApilintCodes.OPENAPI3_0_REFERENCE_FIELD_$REF_HEADER,
+  source: 'apilint',
+  message: 'OAS3 header $Ref should point to Header Object',
+  severity: DiagnosticSeverity.Error,
+  linterFunction: 'parentExistFields',
+  linterParams: [['header']],
+  conditions: [
+    {
+      targets: [{ path: '$ref' }],
+      function: 'apilintValueRegex',
+      params: ['^(?!.*#/components/headers).*$'],
+    },
+  ],
+  marker: 'value',
+  target: '$ref',
+  data: {},
+  targetSpecs: OpenAPI3,
+};
+
+export default $ref3HeaderNamingLint;

packages/apidom-ls/src/config/openapi/header/lint/index.ts

@@ -35,8 +35,10 @@ import minItemsTypeLint from './min-items--type.ts';
 import uniqueItemsTypeLint from './unique-items--type.ts';
 import enumTypeLint from './enum--type.ts';
 import multipleOfTypeLint from './multiple-of--type.ts';
+import $ref3HeaderNamingLint from './$ref-3-0--header.ts';
 
 const lints = [
+  $ref3HeaderNamingLint,
   descriptionTypeLint,
   requiredTypeLint,
   deprecatedTypeLint,

packages/apidom-ls/test/fixtures/validation/oas/ref-header.yaml

@@ -0,0 +1,23 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: 'test'
+paths:
+  /foo:
+    get:
+      responses:
+        '200':
+          description: OK
+          headers:
+            X-MyHeader:
+              $ref: '#/components/schemas/MyHeader'
+components:
+  headers:
+    MyHeader:
+      description: ID of the user
+      required: true
+      schema:
+        type: string
+  schemas:
+    MyHeader:
+      description: ID of the user

packages/apidom-ls/test/validate.ts

@@ -3189,6 +3189,72 @@ describe('apidom-ls-validate', function () {
     languageService.terminate();
   });
 
+  it('oas 3.0 / yaml - OAS3 header $Ref should point to Header Object', async function () {
+    const validationContext: ValidationContext = {
+      comments: DiagnosticSeverity.Error,
+      maxNumberOfProblems: 100,
+      relatedInformation: false,
+    };
+
+    const spec = fs
+      .readFileSync(path.join(__dirname, 'fixtures', 'validation', 'oas', 'ref-header.yaml'))
+      .toString();
+    const doc: TextDocument = TextDocument.create('foo://bar/ref-header.yaml', 'yaml', 0, spec);
+
+    const languageService: LanguageService = getLanguageService(contextNoSchema);
+    const result = await languageService.doValidation(doc, validationContext);
+
+    result[0].code = 'test';
+
+    const expected: Diagnostic[] = [
+      {
+        code: 'test',
+        data: {
+          quickFix: [
+            {
+              action: 'updateValue',
+              functionParams: ['#/components/headers/MyHeader'],
+              message: 'update to #/components/headers/MyHeader',
+            },
+          ],
+        },
+        message: 'local reference not found',
+        range: {
+          end: {
+            character: 51,
+            line: 12,
+          },
+          start: {
+            character: 20,
+            line: 12,
+          },
+        },
+        severity: 1,
+        source: 'apilint',
+      },
+      {
+        code: 5260300,
+        data: {},
+        message: 'OAS3 header $Ref should point to Header Object',
+        range: {
+          end: {
+            character: 51,
+            line: 12,
+          },
+          start: {
+            character: 20,
+            line: 12,
+          },
+        },
+        severity: 1,
+        source: 'apilint',
+      },
+    ];
+    assert.deepEqual(result, expected as Diagnostic[]);
+
+    languageService.terminate();
+  });
+
   it('oas / yaml - test editor issue 3626 / inidrect ref', async function () {
     const validationContext: ValidationContext = {
       comments: DiagnosticSeverity.Error,