fix(apidom-ls): add deprecated warning for example property

[kowalczyk-krzysztof]

Refs #2872

I'm not sure whether I understood the folder structure properly and if the code is in the right place. I'm also not sure which test file should be changed. I would appreciate some suggestions/help @char0n

[frantuma]

@kowalczyk-krzysztof

Schema Object rules are defined in it's own package, under common.

A rule with a warning (possibly better warning than info?) would look like:

import { DiagnosticSeverity } from 'vscode-languageserver-types';

import ApilintCodes from '../../../codes';
import { LinterMeta } from '../../../../apidom-language-types';

const exampleDeprecatedLint: LinterMeta = {
  code: ApilintCodes.SCHEMA_EXAMPLE_DEPRECATED,
  source: 'apilint',
  message: 'property "example" is deprecated, use "examples" instead',
  severity: DiagnosticSeverity.Warning,
  linterFunction: 'missingField',
  linterParams: ['example'],
  marker: 'key',
  markerTarget: 'example',
  targetSpecs: [
    { namespace: 'openapi', version: '3.1.0' },
  ],
  data: {
    quickFix: [
      {
        message: 'remove example',
        action: 'removeChild',
        functionParams: ['example'],
        target: 'parent',
      },
      {
        message: "add 'examples' field",
        action: 'addChild',
        snippetYaml: 'examples: \n  ',
        snippetJson: '"examples": ,\n    ',
      },
    ],
  },
};

The sample code includes targetSpecs to specify to apply the rules only for OAS 3.1 (as schema is currently "shared" also with OAS 3.0 and AsyncAPI.
The sample also includes some possible quick fixes in case.

The current standard way to add rules to apidom-ls "core" is to organize them within the mentioned structure, just adding that it is also possible to add rules with a given field external to the dir structure, see e.g. this test. This can be useful to add custom rules in a client env or to do some testing.

In terms of tests, current status is "sub-optimal" for apidom-ls package, tests are not well designed/organized.

That said, an option is adding a test e.g. here (currently it compares stringified diagnostics result with hardcoded string).

for future ref, slightly related to #2481

[kowalczyk-krzysztof]

@frantuma Thank you. I pushed the recommended changes and added test.

[frantuma]

This should be moved to src/config/common/schema/lint

[kowalczyk-krzysztof]

I thought I did that already. My bad. Fixed.

[kowalczyk-krzysztof]

The push after approval is just squashing two commits into one, as for some reason Lint commit would respond with:

header must not be longer than 69 characters, current length is 70 [header-max-length]

Even though the actual length was 40 characters.
Same issue happened when I created a merge commit to merge main into my branch - which I fixed by rebasing instead of merging.