feat: add ref validation rules (#4989)

Author: robert-hebel-sb

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

@@ -843,6 +843,7 @@ enum ApilintCodes {
 
   OPENAPI2_REFERENCE = 3240000,
   OPENAPI2_REFERENCE_FIELD_$REF_FORMAT_URI = 3240100,
+  OPENAPI2_REFERENCE_NOT_USED = 3240300,
 
   OPENAPI3_0 = 5000000,
 
@@ -1070,6 +1071,11 @@ enum ApilintCodes {
   OPENAPI3_0_REFERENCE = 5260000,
   OPENAPI3_0_REFERENCE_FIELD_$REF_FORMAT_URI = 5260100,
   OPENAPI3_0_REFERENCE_FIELD_$REF_NO_SIBLINGS,
+  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_REFERENCE_FIELD_$REF_PARAMETER = 5260400,
 
   OPENAPI3_0_LINK = 5270000,
   OPENAPI3_0_LINK_FIELD_OPERATION_REF_FORMAT_URI = 5270100,

packages/apidom-ls/src/config/common/schema/lint/$ref--not-used.ts

@@ -0,0 +1,19 @@
+import { DiagnosticSeverity } from 'vscode-languageserver-types';
+
+import ApilintCodes from '../../../codes.ts';
+import { LinterMeta } from '../../../../apidom-language-types.ts';
+import { OpenAPI2, OpenAPI3, OpenAPI31 } from '../../../openapi/target-specs.ts';
+
+const $refNotUsedLint: LinterMeta = {
+  code: ApilintCodes.OPENAPI2_REFERENCE_NOT_USED,
+  source: 'apilint',
+  message: 'Definition was declared but never used in document',
+  severity: DiagnosticSeverity.Warning,
+  linterFunction: 'apilintReferenceNotUsed',
+  linterParams: ['string'],
+  marker: 'key',
+  data: {},
+  targetSpecs: [...OpenAPI2, ...OpenAPI3, ...OpenAPI31],
+};
+
+export default $refNotUsedLint;

packages/apidom-ls/src/config/common/schema/lint/$ref--valid.ts

@@ -8,9 +8,9 @@ import { OpenAPI2, OpenAPI3 } from '../../../openapi/target-specs.ts';
 const $refValidLint: LinterMeta = {
   code: ApilintCodes.SCHEMA_REF,
   source: 'apilint',
-  message: "'$ref' value must be a valid URI-reference",
+  message: "'$ref' value must be an RFC3986-compliant URI reference",
   severity: DiagnosticSeverity.Error,
-  linterFunction: 'apilintValidURI',
+  linterFunction: 'apilintValidURI_RFC3986',
   marker: 'value',
   target: '$ref',
   data: {},

packages/apidom-ls/src/config/common/schema/lint/$ref-3-0--request-bodies.ts

@@ -0,0 +1,28 @@
+import { DiagnosticSeverity } from 'vscode-languageserver-types';
+
+import ApilintCodes from '../../../codes.ts';
+import { LinterMeta } from '../../../../apidom-language-types.ts';
+import { OpenAPI3 } from '../../../openapi/target-specs.ts';
+
+const $ref3RequestBodiesLint: LinterMeta = {
+  code: ApilintCodes.OPENAPI3_0_REFERENCE_FIELD_$REF_REQUEST_BODIES,
+  source: 'apilint',
+  message:
+    'requestBody schema $refs must point to a position where a Schema Object can be legally placed',
+  severity: DiagnosticSeverity.Error,
+  linterFunction: 'parentExistFields',
+  linterParams: [['requestBody']],
+  conditions: [
+    {
+      targets: [{ path: '$ref' }],
+      function: 'apilintValueRegex',
+      params: ['^(?!.*#/components/schemas).*$'],
+    },
+  ],
+  marker: 'value',
+  target: '$ref',
+  data: {},
+  targetSpecs: OpenAPI3,
+};
+
+export default $ref3RequestBodiesLint;

packages/apidom-ls/src/config/common/schema/lint/index.ts

@@ -3,6 +3,7 @@ import allowedFieldsOpenAPI3_0Lint from './allowed-fields-openapi-3-0.ts';
 import $idFormatURILint from './$id--format-uri.ts';
 import $refValidLint from './$ref--valid.ts';
 import $refNoSiblingsLint from './$ref--no-siblings.ts';
+import $ref3RequestBodiesLint from './$ref-3-0--request-bodies.ts';
 import additionalItemsNonArrayLint from './additional-items--non-array.ts';
 import additionalItemsTypeLint from './additional-items--type.ts';
 import additionalItemsTypeOpenAPI3_1__AsyncAPI2Lint from './additional-items--type-openapi-3-1--asyncapi-2.ts';
@@ -81,13 +82,16 @@ import uniqueItemsNonArrayLint from './unique-items--non-array.ts';
 import uniqueItemsTypeLint from './unique-items--type.ts';
 import writeOnlyTypeLint from './write-only--type.ts';
 import exampleDeprecatedLint from './example--deprecated.ts';
+import $refNotUsedLint from './$ref--not-used.ts';
 
 const schemaLints = [
   allowedFieldsOpenAPI2_0Lint,
   allowedFieldsOpenAPI3_0Lint,
   $idFormatURILint,
   $refValidLint,
   $refNoSiblingsLint,
+  $refNotUsedLint,
+  $ref3RequestBodiesLint,
   additionalItemsNonArrayLint,
   additionalItemsTypeLint,
   additionalItemsTypeOpenAPI3_1__AsyncAPI2Lint,

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

@@ -1,5 +1,6 @@
 import valuesTypeLint from './values--type.ts';
+import $refNotUsedLint from '../../../common/schema/lint/$ref--not-used.ts';
 
-const lints = [valuesTypeLint];
+const lints = [valuesTypeLint, $refNotUsedLint];
 
 export default lints;

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/src/config/openapi/parameter/lint/$ref-3-0--parameter.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 $ref3ParameterNamingLint: LinterMeta = {
+  code: ApilintCodes.OPENAPI3_0_REFERENCE_FIELD_$REF_PARAMETER,
+  source: 'apilint',
+  message: 'OAS3 parameter $Ref should point to Parameter Object',
+  severity: DiagnosticSeverity.Error,
+  linterFunction: 'apilintValueRegex',
+  linterParams: ['^(.*#/components/parameters).*$'],
+  marker: 'value',
+  target: '$ref',
+  conditions: [
+    {
+      targets: [{ path: '$ref' }],
+      function: 'parentExistFields',
+      params: [['paths']],
+    },
+  ],
+  data: {},
+  targetSpecs: OpenAPI3,
+};
+
+export default $ref3ParameterNamingLint;

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

@@ -47,8 +47,10 @@ import inAuthorizationLint from './in--authorization.ts';
 import inContentTypeLint from './in--content-type.ts';
 import inAcceptLint from './in--accept.ts';
 import inMultipleBody from './in--multiple-body.ts';
+import $ref3ParameterNamingLint from './$ref-3-0--parameter.ts';
 
 const lints = [
+  $ref3ParameterNamingLint,
   nameTypeLint,
   nameRequiredLint,
   inEquals2_0Lint,