feat(ls): migrate disallowing equivalent paths in OAS2

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

@@ -667,6 +667,7 @@ enum ApilintCodes {
   OPENAPI2_PATH_TEMPLATE = 3040000,
   OPENAPI2_PATH_TEMPLATE_VALUE_WELL_FORMED = 3040100,
   OPENAPI2_PATH_TEMPLATE_VALUE_VALID,
+  OPENAPI2_PATH_TEMPLATE_VALUE_EQUIVALENT_NOT_ALLOWED,
 
   OPENAPI2_LICENSE = 3050000,
   OPENAPI2_LICENSE_FIELD_NAME_TYPE = 3050100,

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

@@ -1,6 +1,7 @@
 import valueWellFormedLint from './value--well-formed.ts';
 import valueValidLint from './value--valid.ts';
+import valueEquivalentNotAllowedLint from './value--equivalent-not-allowed.ts';
 
-const lints = [valueWellFormedLint, valueValidLint];
+const lints = [valueWellFormedLint, valueValidLint, valueEquivalentNotAllowedLint];
 
 export default lints;

packages/apidom-ls/src/config/openapi/path-template/lint/value--equivalent-not-allowed.ts

@@ -0,0 +1,17 @@
+import { DiagnosticSeverity } from 'vscode-languageserver-types';
+
+import ApilintCodes from '../../../codes.ts';
+import { LinterMeta } from '../../../../apidom-language-types.ts';
+import { OpenAPI2 } from '../../target-specs.ts';
+
+const valueEquivalentNotAllowedLint: LinterMeta = {
+  code: ApilintCodes.OPENAPI2_PATH_TEMPLATE_VALUE_EQUIVALENT_NOT_ALLOWED,
+  source: 'apilint',
+  message: 'Equivalent paths are not allowed',
+  severity: DiagnosticSeverity.Error,
+  linterFunction: 'apilintOpenAPIPathTemplateNoEquivalent',
+  marker: 'value',
+  targetSpecs: OpenAPI2,
+};
+
+export default valueEquivalentNotAllowedLint;

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

@@ -17,6 +17,8 @@ import {
   test as testPathTemplate,
   resolve as resolvePathTemplate,
   parse as parsePathTemplate,
+  isIdentical,
+  parse,
 } from 'openapi-path-templating';
 
 // eslint-disable-next-line import/no-cycle
@@ -31,6 +33,16 @@ import {
 } from '../../utils/utils.ts';
 import { FunctionItem } from '../../apidom-language-types.ts';
 
+const getPathParams = (path: string) => {
+  const { ast } = parse(path);
+  const parts: any[] = [];
+  ast.translate(parts);
+
+  return parts
+    .filter(([type]) => type === 'template-expression-param-name')
+    .map(([, name]) => name);
+};
+
 const root = (el: Element): Element => {
   const rootElementTypes = ['swagger', 'openApi3_0', 'openApi3_1', 'asyncApi2'];
   let node = el;
@@ -1099,6 +1111,7 @@ export const standardLinterfunctions: FunctionItem[] = [
         }
 
         let oneOfParametersIsReferenceObject = false;
+        const globalParameterElementNames: string[] = [];
         const parameterElements: Element[] = [];
         const isParameterElement = (el: Element): boolean => el.element === 'parameter';
         const isReferenceElement = (el: Element): boolean => el.element === 'reference';
@@ -1110,16 +1123,29 @@ export const standardLinterfunctions: FunctionItem[] = [
               oneOfParametersIsReferenceObject = true;
             }
             if (isParameterElement(parameter)) {
+              // separate array was needed, because parameterElements is extended in the loop below, but only global ones were needed
+              const name = isObject(parameter) && parameter.get('name');
+              if (name && name.content) {
+                globalParameterElementNames.push(name.content);
+              }
               parameterElements.push(parameter);
             }
           });
         }
 
+        const operationLevelKeys: Record<string, string[]> = {};
         pathItemElement.forEach((el) => {
           if (el.element === 'operation') {
+            if (isMember(el.parent) && isStringElement(el.parent.key)) {
+              operationLevelKeys[el.parent.key.toValue()] = [];
+            }
             const operationParameterElements = (el as ObjectElement).get('parameters');
             if (isArrayElement(operationParameterElements)) {
               operationParameterElements.forEach((parameter) => {
+                const name = isObject(parameter) && parameter.get('name');
+                if (name && isMember(el.parent) && isStringElement(el.parent.key)) {
+                  operationLevelKeys[el.parent.key.toValue()].push(name.content);
+                }
                 if (isReferenceElement(parameter) && !oneOfParametersIsReferenceObject) {
                   oneOfParametersIsReferenceObject = true;
                 }
@@ -1144,7 +1170,19 @@ export const standardLinterfunctions: FunctionItem[] = [
         const resolvedPathTemplate = resolvePathTemplate(pathTemplate, pathTemplateResolveParams);
         const includesTemplateExpression = testPathTemplate(resolvedPathTemplate, { strict: true });
 
-        return !includesTemplateExpression || oneOfParametersIsReferenceObject;
+        const pathParams: string[] = getPathParams(element.toValue());
+
+        const everyPathParamInOperation = pathParams.every((pathParam) => {
+          if (!globalParameterElementNames.includes(pathParam)) {
+            return Object.values(operationLevelKeys).every((el) => el.includes(pathParam));
+          }
+
+          return true;
+        });
+        return (
+          (everyPathParamInOperation && !includesTemplateExpression) ||
+          oneOfParametersIsReferenceObject
+        );
       }
 
       return true;
@@ -1219,4 +1257,21 @@ export const standardLinterfunctions: FunctionItem[] = [
       return true;
     },
   },
+  {
+    functionName: 'apilintOpenAPIPathTemplateNoEquivalent',
+    function: (element: Element): boolean => {
+      const isFirstOccurrence = (currentKey: string, allKeys: unknown[]) => {
+        const firstIndex = allKeys.findIndex(
+          (e) => typeof e === 'string' && isIdentical(e, currentKey),
+        );
+
+        return allKeys[firstIndex] === currentKey;
+      };
+      const paths = element.parent?.parent;
+
+      return isStringElement(element) && isObject(paths)
+        ? isFirstOccurrence(element.toValue(), paths.keys())
+        : true;
+    },
+  },
 ];

packages/apidom-ls/test/fixtures/validation/oas/path-template-all-defined.yaml

@@ -0,0 +1,24 @@
+openapi: 3.0.0
+info:
+  title: Missing Path Parameter Test
+  version: "1.0"
+paths:
+  /users/{id}:
+    get:
+      summary: Get user by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: OK
+
+    delete:
+      summary: Delete user by ID
+      # ❌ Missing 'id' parameter here
+      responses:
+        '204':
+          description: No Content

packages/apidom-ls/test/fixtures/validation/oas/path-template-equivalent-not-allowed.yaml

@@ -0,0 +1,28 @@
+swagger: '2.0'
+info:
+  title: Test API
+  version: 1.0.0
+paths:
+  /items/{id}:
+    get:
+      summary: Get item by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          type: string
+      responses:
+        200:
+          description: OK
+  /items/{itemId}:
+    get:
+      summary: Get item by itemId
+      parameters:
+        - name: itemId
+          in: path
+          required: true
+          type: string
+      responses:
+        200:
+          description: OK
+

packages/apidom-ls/test/validate.ts

@@ -3763,6 +3763,51 @@ describe('apidom-ls-validate', function () {
     languageService.terminate();
   });
 
+  it('oas / yaml - every path template should be defined', async function () {
+    const validationContext: ValidationContext = {
+      comments: DiagnosticSeverity.Error,
+      maxNumberOfProblems: 100,
+      relatedInformation: false,
+    };
+
+    const spec = fs
+      .readFileSync(
+        path.join(__dirname, 'fixtures', 'validation', 'oas', 'path-template-all-defined.yaml'),
+      )
+      .toString();
+    const doc: TextDocument = TextDocument.create(
+      'foo://bar/path-template-all-defined.yaml',
+      'yaml',
+      0,
+      spec,
+    );
+
+    const languageService: LanguageService = getLanguageService(contextNoSchema);
+
+    const result = await languageService.doValidation(doc, validationContext);
+    const expected: Diagnostic[] = [
+      {
+        code: 3040101,
+        message: 'path template expressions is not matched with Parameter Object(s)',
+        range: {
+          end: {
+            character: 13,
+            line: 5,
+          },
+          start: {
+            character: 2,
+            line: 5,
+          },
+        },
+        severity: 1,
+        source: 'apilint',
+      },
+    ];
+    assert.deepEqual(result, expected as Diagnostic[]);
+
+    languageService.terminate();
+  });
+
   it('oas 2.0 / yaml - every path template should be defined', async function () {
     const validationContext: ValidationContext = {
       comments: DiagnosticSeverity.Error,
@@ -4541,4 +4586,40 @@ describe('apidom-ls-validate', function () {
 
     languageService.terminate();
   });
+
+  it('oas 2.0 should not allow equivalent paths', async function () {
+    const spec = fs
+      .readFileSync(
+        path.join(
+          __dirname,
+          'fixtures',
+          'validation',
+          'oas',
+          'path-template-equivalent-not-allowed.yaml',
+        ),
+      )
+      .toString();
+    const doc: TextDocument = TextDocument.create(
+      'path-template-equivalent-not-allowed.yaml',
+      'yaml',
+      0,
+      spec,
+    );
+
+    const languageService: LanguageService = getLanguageService(contextNoSchema);
+
+    const result = await languageService.doValidation(doc);
+    const expected: Diagnostic[] = [
+      {
+        message: 'Equivalent paths are not allowed',
+        severity: 1,
+        code: 3040102,
+        source: 'apilint',
+        range: { start: { line: 16, character: 2 }, end: { line: 16, character: 17 } },
+      },
+    ];
+    assert.deepEqual(result, expected);
+
+    languageService.terminate();
+  });
 });