add stability linting

Author: avivkeller

bin/cli.mjs

@@ -14,7 +14,10 @@ import createMarkdownParser from '../src/parsers/markdown.mjs';
 import createNodeReleases from '../src/releases.mjs';
 import createLinter from '../src/linter/index.mjs';
 import reporters from '../src/linter/reporters/index.mjs';
-import rules from '../src/linter/rules/index.mjs';
+import {
+  multiEntryRules,
+  singleEntryRules,
+} from '../src/linter/rules/index.mjs';
 
 const availableGenerators = Object.keys(generators);
 
@@ -61,7 +64,9 @@ program
   )
   .addOption(
     new Option('--disable-rule [rule...]', 'Disable a specific linter rule')
-      .choices(Object.keys(rules))
+      .choices(
+        Object.keys(multiEntryRules).concat(Object.keys(singleEntryRules))
+      )
       .default([])
   )
   .addOption(

src/constants.mjs

@@ -425,4 +425,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,9 +3,12 @@
 /**
  * Creates a linter engine instance to validate ApiDocMetadataEntry entries
  *
- * @param {import('./types').LintRule} rules Lint rules to validate the entries against
+ * @param {{
+ * multiEntryRules: import('./types').MultipleEntriesLintRules[]
+ * singleEntryRules: import('./types').SingleEntryLintRule[]
+ * }} rules Lint rules to validate the entries against
  */
-const createLinterEngine = rules => {
+const createLinterEngine = ({ multiEntryRules, singleEntryRules }) => {
   /**
    * Validates a ApiDocMetadataEntry entry against all defined rules
    *
@@ -15,7 +18,7 @@ const createLinterEngine = rules => {
   const lint = entry => {
     const issues = [];
 
-    for (const rule of rules) {
+    for (const rule of singleEntryRules) {
       const ruleIssues = rule(entry);
 
       if (ruleIssues.length > 0) {
@@ -35,6 +38,10 @@ const createLinterEngine = rules => {
   const lintAll = entries => {
     const issues = [];
 
+    for (const rule of multiEntryRules) {
+      issues.push(...rule(entries));
+    }
+
     for (const entry of entries) {
       issues.push(...lint(entry));
     }

src/linter/index.mjs

@@ -2,7 +2,7 @@
 
 import createLinterEngine from './engine.mjs';
 import reporters from './reporters/index.mjs';
-import rules from './rules/index.mjs';
+import { multiEntryRules, singleEntryRules } from './rules/index.mjs';
 
 /**
  * Creates a linter instance to validate ApiDocMetadataEntry entries
@@ -13,16 +13,19 @@ import rules from './rules/index.mjs';
 const createLinter = (dryRun, disabledRules) => {
   /**
    * Retrieves all enabled rules
-   *
+   * @param {Record<string, import('./types').LintRule>} rules
    * @returns {import('./types').LintRule[]}
    */
-  const getEnabledRules = () => {
+  const getEnabledRules = rules => {
     return Object.entries(rules)
       .filter(([ruleName]) => !disabledRules.includes(ruleName))
       .map(([, rule]) => rule);
   };
 
-  const engine = createLinterEngine(getEnabledRules(disabledRules));
+  const engine = createLinterEngine({
+    multiEntryRules: getEnabledRules(multiEntryRules),
+    singleEntryRules: getEnabledRules(singleEntryRules),
+  });
 
   /**
    * Lint issues found during validations

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.yaml_position,
+        },
+      });
+    } else {
+      currentDepth = depth;
+      currentStability = entryStability;
+    }
+  }
+
+  return issues;
+};

src/linter/rules/index.mjs

@@ -1,14 +1,22 @@
 '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';
 
 /**
- * @type {Record<string, import('../types').LintRule>}
+ * @type {Record<string, import('../types').SingleEntryLintRule>}
  */
-export default {
+export const singleEntryRules = {
   'invalid-change-version': invalidChangeVersion,
   'missing-change-version': missingChangeVersion,
   'missing-introduced-in': missingIntroducedIn,
 };
+
+/**
+ * @type {Record<string, import('../types').MultipleEntriesLintRule>}
+ */
+export const multiEntryRules = {
+  'duplicate-stability-nodes': duplicateStabilityNodes,
+};

src/linter/types.d.ts

@@ -13,6 +13,8 @@ export interface LintIssue {
   location: LintIssueLocation;
 }
 
-type LintRule = (input: ApiDocMetadataEntry) => LintIssue[];
+type LintRule = MultipleEntriesLintRules | SingleEntryLintRule;
+type MultipleEntriesLintRules = (input: ApiDocMetadataEntry[]) => LintIssue[];
+type SingleEntryLintRule = (input: ApiDocMetadataEntry) => LintIssue[];
 
 export type Reporter = (msg: LintIssue) => void;