feat: add duplicate stability linters

src/linter/constants.mjs

@@ -4,4 +4,5 @@ export const LINT_MESSAGES = {
   missingIntroducedIn: "Missing 'introduced_in' field in the API doc entry",
   missingChangeVersion: 'Missing version field in the API doc entry',
   invalidChangeVersion: 'Invalid version number: {{version}}',
+  duplicateStabilityNode: 'Duplicate stability node',
 };

src/linter/engine.mjs

@@ -3,29 +3,9 @@
 /**
  * Creates a linter engine instance to validate ApiDocMetadataEntry entries
  *
- * @param {import('./types').LintRule} rules Lint rules to validate the entries against
+ * @param {import('./types').LintRule[]} rules Lint rules to validate the entries against
  */
 const createLinterEngine = rules => {
-  /**
-   * Validates a ApiDocMetadataEntry entry against all defined rules
-   *
-   * @param {ApiDocMetadataEntry} entry
-   * @returns {import('./types').LintIssue[]}
-   */
-  const lint = entry => {
-    const issues = [];
-
-    for (const rule of rules) {
-      const ruleIssues = rule(entry);
-
-      if (ruleIssues.length > 0) {
-        issues.push(...ruleIssues);
-      }
-    }
-
-    return issues;
-  };
-
   /**
    * Validates an array of ApiDocMetadataEntry entries against all defined rules
    *
@@ -35,15 +15,14 @@ const createLinterEngine = rules => {
   const lintAll = entries => {
     const issues = [];
 
-    for (const entry of entries) {
-      issues.push(...lint(entry));
+    for (const rule of rules) {
+      issues.push(...rule(entries));
     }
 
     return issues;
   };
 
   return {
-    lint,
     lintAll,
   };
 };

src/linter/rules/duplicate-stability-nodes.mjs

@@ -0,0 +1,38 @@
+import { LINT_MESSAGES } from '../constants.mjs';
+
+/**
+ * Checks if there are multiple stability nodes within a chain.
+ *
+ * @param {ApiDocMetadataEntry[]} entries
+ * @returns {Array<import('../types').LintIssue>}
+ */
+export const duplicateStabilityNodes = entries => {
+  const issues = [];
+  let currentDepth = 0;
+  let currentStability = -1;
+
+  for (const entry of entries) {
+    const { depth } = entry.heading.data;
+    const entryStability = entry.stability.children[0]?.data.index ?? -1;
+
+    if (
+      depth > currentDepth &&
+      entryStability >= 0 &&
+      entryStability === currentStability
+    ) {
+      issues.push({
+        level: 'warn',
+        message: LINT_MESSAGES.duplicateStabilityNode,
+        location: {
+          path: entry.api_doc_source,
+          position: entry.stability.children[0].children[0].position,
+        },
+      });
+    } else {
+      currentDepth = depth;
+      currentStability = entryStability;
+    }
+  }
+
+  return issues;
+};

src/linter/rules/index.mjs

@@ -1,5 +1,6 @@
 'use strict';
 
+import { duplicateStabilityNodes } from './duplicate-stability-nodes.mjs';
 import { invalidChangeVersion } from './invalid-change-version.mjs';
 import { missingChangeVersion } from './missing-change-version.mjs';
 import { missingIntroducedIn } from './missing-introduced-in.mjs';
@@ -8,6 +9,7 @@ import { missingIntroducedIn } from './missing-introduced-in.mjs';
  * @type {Record<string, import('../types').LintRule>}
  */
 export default {
+  'duplicate-stability-nodes': duplicateStabilityNodes,
   'invalid-change-version': invalidChangeVersion,
   'missing-change-version': missingChangeVersion,
   'missing-introduced-in': missingIntroducedIn,

src/linter/rules/invalid-change-version.mjs

@@ -4,30 +4,39 @@ import { valid } from 'semver';
 /**
  * Checks if any change version is invalid
  *
- * @param {ApiDocMetadataEntry} entry
+ * @param {ApiDocMetadataEntry[]} entries
  * @returns {Array<import('../types').LintIssue>}
  */
-export const invalidChangeVersion = entry => {
-  if (entry.changes.length === 0) {
-    return [];
-  }
+export const invalidChangeVersion = entries => {
+  const issues = [];
+
+  for (const entry of entries) {
+    if (entry.changes.length === 0) continue;
+
+    const allVersions = entry.changes
+      .filter(change => change.version)
+      .flatMap(change =>
+        Array.isArray(change.version) ? change.version : [change.version]
+      );
 
-  const allVersions = entry.changes
-    .filter(change => change.version)
-    .flatMap(change =>
-      Array.isArray(change.version) ? change.version : [change.version]
+    const invalidVersions = allVersions.filter(
+      version => valid(version) === null
     );
 
-  const invalidVersions = allVersions.filter(
-    version => valid(version) === null
-  );
+    issues.push(
+      ...invalidVersions.map(version => ({
+        level: 'warn',
+        message: LINT_MESSAGES.invalidChangeVersion.replace(
+          '{{version}}',
+          version
+        ),
+        location: {
+          path: entry.api_doc_source,
+          position: entry.yaml_position,
+        },
+      }))
+    );
+  }
 
-  return invalidVersions.map(version => ({
-    level: 'warn',
-    message: LINT_MESSAGES.invalidChangeVersion.replace('{{version}}', version),
-    location: {
-      path: entry.api_doc_source,
-      position: entry.yaml_position,
-    },
-  }));
+  return issues;
 };

src/linter/rules/missing-change-version.mjs

@@ -1,22 +1,28 @@
 /**
  * Checks if any change version is missing
  *
- * @param {ApiDocMetadataEntry} entry
+ * @param {ApiDocMetadataEntry[]} entries
  * @returns {Array<import('../types').LintIssue>}
  */
-export const missingChangeVersion = entry => {
-  if (entry.changes.length === 0) {
-    return [];
+export const missingChangeVersion = entries => {
+  const issues = [];
+
+  for (const entry of entries) {
+    if (entry.changes.length === 0) continue;
+
+    issues.push(
+      ...entry.changes
+        .filter(change => !change.version)
+        .map(() => ({
+          level: 'warn',
+          message: 'Missing change version',
+          location: {
+            path: entry.api_doc_source,
+            position: entry.yaml_position,
+          },
+        }))
+    );
   }
 
-  return entry.changes
-    .filter(change => !change.version)
-    .map(() => ({
-      level: 'warn',
-      message: 'Missing change version',
-      location: {
-        path: entry.api_doc_source,
-        position: entry.yaml_position,
-      },
-    }));
+  return issues;
 };

src/linter/rules/missing-introduced-in.mjs

@@ -3,22 +3,24 @@ import { LINT_MESSAGES } from '../constants.mjs';
 /**
  * Checks if `introduced_in` field is missing
  *
- * @param {ApiDocMetadataEntry} entry
+ * @param {ApiDocMetadataEntry[]} entries
  * @returns {Array<import('../types.d.ts').LintIssue>}
  */
-export const missingIntroducedIn = entry => {
-  // Early return if not a top-level heading or if introduced_in exists
-  if (entry.heading.depth !== 1 || entry.introduced_in) {
-    return [];
-  }
+export const missingIntroducedIn = entries => {
+  const issues = [];
+
+  for (const entry of entries) {
+    // Early continue if not a top-level heading or if introduced_in exists
+    if (entry.heading.depth !== 1 || entry.introduced_in) continue;
 
-  return [
-    {
+    issues.push({
       level: 'info',
       message: LINT_MESSAGES.missingIntroducedIn,
       location: {
         path: entry.api_doc_source,
       },
-    },
-  ];
+    });
+  }
+
+  return issues;
 };

src/linter/tests/engine.test.mjs

@@ -11,13 +11,13 @@ describe('createLinterEngine', () => {
 
     const engine = createLinterEngine([rule1, rule2]);
 
-    engine.lint(assertEntry);
+    engine.lintAll([assertEntry]);
 
     assert.strictEqual(rule1.mock.callCount(), 1);
     assert.strictEqual(rule2.mock.callCount(), 1);
 
-    assert.deepEqual(rule1.mock.calls[0].arguments, [assertEntry]);
-    assert.deepEqual(rule2.mock.calls[0].arguments, [assertEntry]);
+    assert.deepEqual(rule1.mock.calls[0].arguments, [[assertEntry]]);
+    assert.deepEqual(rule2.mock.calls[0].arguments, [[assertEntry]]);
   });
 
   it('should return the aggregated issues from all rules', () => {
@@ -26,7 +26,7 @@ describe('createLinterEngine', () => {
 
     const engine = createLinterEngine([rule1, rule2]);
 
-    const issues = engine.lint(assertEntry);
+    const issues = engine.lintAll([assertEntry]);
 
     assert.equal(issues.length, 3);
     assert.deepEqual(issues, [infoIssue, warnIssue, errorIssue]);
@@ -37,7 +37,7 @@ describe('createLinterEngine', () => {
 
     const engine = createLinterEngine([rule]);
 
-    const issues = engine.lint(assertEntry);
+    const issues = engine.lintAll([assertEntry]);
 
     assert.deepEqual(issues, []);
   });