feat: add ref not used lint rule

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,
 

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/index.ts

@@ -81,13 +81,15 @@ 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,
   additionalItemsNonArrayLint,
   additionalItemsTypeLint,
   additionalItemsTypeOpenAPI3_1__AsyncAPI2Lint,

packages/apidom-ls/src/config/openapi/schema/lint.ts

@@ -75,6 +75,7 @@ import uniqueItemsNonArrayLint from '../../common/schema/lint/unique-items--non-
 import uniqueItemsTypeLint from '../../common/schema/lint/unique-items--type.ts';
 import writeOnlyTypeLint from '../../common/schema/lint/write-only--type.ts';
 import exampleDeprecatedLint from '../../common/schema/lint/example--deprecated.ts';
+import $refNotUsedLint from '../../common/schema/lint/$ref--not-used.ts';
 import { OpenAPI31 } from '../target-specs.ts';
 
 const schemaLints = [
@@ -154,6 +155,7 @@ const schemaLints = [
   uniqueItemsTypeLint,
   writeOnlyTypeLint,
   exampleDeprecatedLint,
+  $refNotUsedLint,
 ];
 
 export default schemaLints;

packages/apidom-ls/src/services/validation/linter-functions.ts

@@ -1113,6 +1113,22 @@ export const standardLinterfunctions: FunctionItem[] = [
       return true;
     },
   },
+  {
+    functionName: 'apilintReferenceNotUsed',
+    function: (element) => {
+      const api = root(element);
+      const isReferenceElement = (el: Element) => el.element === 'reference';
+      const referenceElements = filter((el) => {
+        return isReferenceElement(el);
+      }, api);
+      const referenceNames = referenceElements.map((refElement: Element) =>
+        // @ts-expect-error
+        toValue(refElement.get('$ref')).split('/').at(-1),
+      );
+      // @ts-expect-error
+      return referenceNames.includes(toValue(element.parent.key));
+    },
+  },
   {
     functionName: 'apilintOpenAPIParameterInPathTemplate',
     function: (element: Element) => {

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

@@ -0,0 +1,14 @@
+openapi: 3.0.0
+info:
+  title: 'test'
+  version: 1.0.0
+paths:
+  /test:
+    get:
+      responses:
+        default:
+          description: test
+components:
+  schemas:
+    notUsedSchema:
+      type: object

packages/apidom-ls/test/validate.ts

@@ -3001,6 +3001,37 @@ describe('apidom-ls-validate', function () {
     languageService.terminate();
   });
 
+  it('oas / yaml - ref is defined but not used', async function () {
+    const validationContext: ValidationContext = {
+      comments: DiagnosticSeverity.Error,
+      maxNumberOfProblems: 100,
+      relatedInformation: false,
+    };
+
+    const spec = fs
+      .readFileSync(path.join(__dirname, 'fixtures', 'validation', 'oas', 'ref-not-used.yaml'))
+      .toString();
+    const doc: TextDocument = TextDocument.create('foo://bar/ref-not-used.yaml', 'yaml', 0, spec);
+
+    const languageService: LanguageService = getLanguageService(contextNoSchema);
+
+    const result = await languageService.doValidation(doc, validationContext);
+    result[0].code = 'test';
+    const expected: Diagnostic[] = [
+      {
+        range: { start: { line: 12, character: 4 }, end: { line: 12, character: 17 } },
+        message: 'Definition was declared but never used in document',
+        severity: 2,
+        code: 'test',
+        source: 'apilint',
+        data: {},
+      },
+    ];
+    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,