linter: add deprecation code check, linter declarations

bin/cli.mjs

@@ -106,7 +106,7 @@ const {
 const linter = createLinter(lintDryRun, disableRule);
 
 const { loadFiles } = createMarkdownLoader();
-const { parseApiDocs } = createMarkdownParser();
+const { parseApiDocs } = createMarkdownParser(linter);
 
 const apiDocFiles = await loadFiles(input, ignore);
 

src/constants.mjs

@@ -425,4 +425,9 @@ 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}}',
+  malformedDeprecationHeader: 'Malformed deprecation header',
+  outOfOrderDeprecationCode:
+    "Deprecation code '{{code}}' out of order (expected {{expectedCode}})",
+  invalidLinterDeclaration: "Invalid linter declaration '{{declaration}}'",
+  malformedLinterDeclaration: 'Malformed linter declaration: {{message}}',
 };

src/generators/legacy-json/types.d.ts

@@ -8,7 +8,7 @@ export interface HierarchizedEntry extends ApiDocMetadataEntry {
   /**
    * List of child entries that are part of this entry's hierarchy.
    */
-  hierarchyChildren: ApiDocMetadataEntry[];
+  hierarchyChildren: HierarchizedEntry[];
 }
 
 /**

src/generators/legacy-json/utils/buildSection.mjs

@@ -1,4 +1,4 @@
-import { buildHierarchy } from './buildHierarchy.mjs';
+import { buildHierarchy } from '../../../utils/buildHierarchy.mjs';
 import { getRemarkRehype } from '../../../utils/remark.mjs';
 import { transformNodesToString } from '../../../utils/unist.mjs';
 import { parseList } from './parseList.mjs';

src/linter/constants.mjs

@@ -0,0 +1,6 @@
+'use strict';
+
+// Validates a deprecation header from doc/api/deprecation.md and captures the
+// code
+// For example, `DEP0001: `http.OutgoingMessage.prototype.flush` captures `0001`
+export const DEPRECATION_HEADER_REGEX = /DEP(\d{4}): .+?/;

src/linter/engine.mjs

@@ -10,13 +10,15 @@ const createLinterEngine = rules => {
    * Validates a ApiDocMetadataEntry entry against all defined rules
    *
    * @param {ApiDocMetadataEntry} entry
+   * @param {import('./types').LintDeclarations}
+   * @param declarations
    * @returns {import('./types').LintIssue[]}
    */
-  const lint = entry => {
+  const lint = (entry, declarations) => {
     const issues = [];
 
     for (const rule of rules) {
-      const ruleIssues = rule(entry);
+      const ruleIssues = rule([entry], declarations);
 
       if (ruleIssues.length > 0) {
         issues.push(...ruleIssues);
@@ -30,13 +32,19 @@ const createLinterEngine = rules => {
    * Validates an array of ApiDocMetadataEntry entries against all defined rules
    *
    * @param {ApiDocMetadataEntry[]} entries
+   * @param {import('./types').LintDeclarations}
+   * @param declarations
    * @returns {import('./types').LintIssue[]}
    */
-  const lintAll = entries => {
+  const lintAll = (entries, declarations) => {
     const issues = [];
 
-    for (const entry of entries) {
-      issues.push(...lint(entry));
+    for (const rule of rules) {
+      const ruleIssues = rule(entries, declarations);
+
+      if (ruleIssues.length > 0) {
+        issues.push(...ruleIssues);
+      }
     }
 
     return issues;

src/linter/index.mjs

@@ -1,5 +1,6 @@
 'use strict';
 
+import { LINT_MESSAGES } from '../constants.mjs';
 import createLinterEngine from './engine.mjs';
 import reporters from './reporters/index.mjs';
 import rules from './rules/index.mjs';
@@ -22,6 +23,13 @@ const createLinter = (dryRun, disabledRules) => {
       .map(([, rule]) => rule);
   };
 
+  /**
+   * @type {import('./types').LintDeclarations}
+   */
+  const declarations = {
+    skipDeprecation: [],
+  };
+
   const engine = createLinterEngine(getEnabledRules(disabledRules));
 
   /**
@@ -37,7 +45,7 @@ const createLinter = (dryRun, disabledRules) => {
    * @param entries
    */
   const lintAll = entries => {
-    issues.push(...engine.lintAll(entries));
+    issues.push(...engine.lintAll(entries, declarations));
   };
 
   /**
@@ -58,6 +66,87 @@ const createLinter = (dryRun, disabledRules) => {
     }
   };
 
+  /**
+   * Parse an inline-declaration found in the markdown input
+   *
+   * @param {string} declaration
+   */
+  const parseLinterDeclaration = declaration => {
+    // Trim off any excess spaces from the beginning & end
+    declaration = declaration.trim();
+
+    // Extract the name for the declaration
+    const [name, ...value] = declaration.split(' ');
+
+    switch (name) {
+      case 'skip-deprecation': {
+        if (value.length !== 1) {
+          issues.push({
+            level: 'error',
+            location: {
+              // TODO,
+              path: '',
+              position: 0,
+            },
+            message: LINT_MESSAGES.malformedLinterDeclaration.replace(
+              '{{message}}',
+              `Expected 1 argument, got ${value.length}`
+            ),
+          });
+
+          break;
+        }
+
+        // Get the deprecation code. This should be something like DEP0001.
+        const deprecation = value[0];
+
+        // Extract the number from the code
+        const deprecationCode = Number(deprecation.substring('DEP'.length));
+
+        // Make sure this is a valid deprecation code, output an error otherwise
+        if (
+          deprecation.length !== 7 ||
+          !deprecation.startsWith('DEP') ||
+          isNaN(deprecationCode)
+        ) {
+          issues.push({
+            level: 'error',
+            location: {
+              // TODO,
+              path: '',
+              position: 0,
+            },
+            message: LINT_MESSAGES.malformedLinterDeclaration.replace(
+              '{{message}}',
+              `Invalid deprecation code ${deprecation}`
+            ),
+          });
+
+          break;
+        }
+
+        declarations.skipDeprecation.push(deprecationCode);
+
+        break;
+      }
+      default: {
+        issues.push({
+          level: 'error',
+          location: {
+            // TODO
+            path: '',
+            position: 0,
+          },
+          message: LINT_MESSAGES.invalidLinterDeclaration.replace(
+            '{{declaration}}',
+            name
+          ),
+        });
+        break;
+      }
+    }
+  };
+
   /**
    * Checks if any error-level issues were found during linting
    *
@@ -70,6 +159,7 @@ const createLinter = (dryRun, disabledRules) => {
   return {
     lintAll,
     report,
+    parseLinterDeclaration,
     hasError,
   };
 };

src/linter/rules/deprecation-code-order.mjs

@@ -0,0 +1,82 @@
+'use strict';
+
+import { LINT_MESSAGES } from '../../constants.mjs';
+import { buildHierarchy } from '../../utils/buildHierarchy.mjs';
+import { DEPRECATION_HEADER_REGEX } from '../constants.mjs';
+import getDeprecationEntries from './utils/getDeprecationEntries.mjs';
+
+/**
+ * @param {ApiDocMetadataEntry} deprecation
+ * @param {number} expectedCode
+ * @returns {Array<import('../types').LintIssue>}
+ */
+function lintDeprecation(deprecation, expectedCode) {
+  // Try validating the header (`DEPXXXX: ...`) and extract the code for us to
+  // look at
+  const match = deprecation.heading.data.text.match(DEPRECATION_HEADER_REGEX);
+
+  if (!match) {
+    // Malformed header
+    return [
+      {
+        level: 'error',
+        location: {
+          path: deprecation.api_doc_source,
+          position: deprecation.yaml_position,
+        },
+        message: LINT_MESSAGES.malformedDeprecationHeader,
+      },
+    ];
+  }
+
+  const code = Number(match[1]);
+
+  return code === expectedCode
+    ? []
+    : [
+        {
+          level: 'error',
+          location: {
+            path: deprecation.api_doc_source,
+            position: deprecation.yaml_position,
+          },
+          message: LINT_MESSAGES.outOfOrderDeprecationCode
+            .replaceAll('{{code}}', match[1])
+            .replace('{{expectedCode}}', `${expectedCode}`.padStart(4, '0')),
+        },
+      ];
+}
+
+/**
+ * Checks if any deprecation codes are out of order
+ *
+ * @type {import('../types').LintRule}
+ */
+export const deprecationCodeOrder = (entries, declarations) => {
+  if (entries.length === 0 || entries[0].api !== 'deprecations') {
+    // This is only relevant to doc/api/deprecations.md
+    return [];
+  }
+
+  const issues = [];
+
+  const hierarchy = buildHierarchy(entries);
+
+  hierarchy.forEach(root => {
+    const deprecations = getDeprecationEntries(root.hierarchyChildren);
+
+    let expectedCode = 1;
+
+    for (const deprecation of deprecations || []) {
+      while (declarations.skipDeprecation.includes(expectedCode)) {
+        expectedCode++;
+      }
+
+      issues.push(...lintDeprecation(deprecation, expectedCode));
+
+      expectedCode++;
+    }
+  });
+
+  return issues;
+};

src/linter/rules/index.mjs

@@ -1,5 +1,6 @@
 'use strict';
 
+import { deprecationCodeOrder } from './deprecation-code-order.mjs';
 import { invalidChangeVersion } from './invalid-change-version.mjs';
 import { missingChangeVersion } from './missing-change-version.mjs';
 import { missingIntroducedIn } from './missing-introduced-in.mjs';
@@ -11,4 +12,5 @@ export default {
   'invalid-change-version': invalidChangeVersion,
   'missing-change-version': missingChangeVersion,
   'missing-introduced-in': missingIntroducedIn,
+  'deprecation-code-order': deprecationCodeOrder,
 };

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

@@ -1,3 +1,5 @@
+'use strict';
+
 import { LINT_MESSAGES } from '../../constants.mjs';
 import { valid } from 'semver';
 

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

@@ -1,3 +1,5 @@
+'use strict';
+
 /**
  * Checks if any change version is missing
  *

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

@@ -1,3 +1,5 @@
+'use strict';
+
 import { LINT_MESSAGES } from '../../constants.mjs';
 
 /**

src/linter/rules/utils/getDeprecationEntries.mjs

@@ -0,0 +1,15 @@
+'use strict';
+
+/**
+ * @param {Array<import('../../../generators/legacy-json/types').HierarchizedEntry>} hierarchy
+ * @returns {Array<import('../../../generators/legacy-json/types').HierarchizedEntry> | undefined}
+ */
+export default function getDeprecationEntries(hierarchy) {
+  for (const child of hierarchy) {
+    if (child.slug === 'list-of-deprecated-apis') {
+      return child.hierarchyChildren;
+    }
+  }
+
+  return undefined;
+}

src/linter/types.d.ts

@@ -13,6 +13,13 @@ export interface LintIssue {
   location: LintIssueLocation;
 }
 
-type LintRule = (input: ApiDocMetadataEntry) => LintIssue[];
+export interface LintDeclarations {
+  skipDeprecation: Array<number>;
+}
+
+type LintRule = (
+  input: Array<ApiDocMetadataEntry>,
+  declarations: LintDeclarations
+) => LintIssue[];
 
 export type Reporter = (msg: LintIssue) => void;

src/parsers/markdown.mjs

@@ -15,9 +15,9 @@ import { createNodeSlugger } from '../utils/slugger.mjs';
 /**
  * Creates an API doc parser for a given Markdown API doc file
  *
- * @param {import('./linter/index.mjs').Linter | undefined} linter
+ * @param {ReturnType<import('../linter/index.mjs').default> | undefined} linter
  */
-const createParser = () => {
+const createParser = linter => {
   // Creates an instance of the Remark processor with GFM support
   // which is used for stringifying the AST tree back to Markdown
   const remarkProcessor = getRemark();
@@ -142,6 +142,16 @@ const createParser = () => {
         addYAMLMetadata(node, apiEntryMetadata);
       });
 
+      // Visits all HTML nodes from the current subtree to check for linter declarations.
+      // If there are, it gives them to the linter to parse and use.
+      visit(subTree, createQueries.UNIST.isLinterComment, node => {
+        if (linter) {
+          linter.parseLinterDeclaration(
+            node.value.match(createQueries.QUERIES.linterComment)[1]
+          );
+        }
+      });
+
       // Visits all Text nodes from the current subtree and if there's any that matches
       // any API doc type reference and then updates the type reference to be a Markdown link
       visit(subTree, createQueries.UNIST.isTextWithType, (node, _, parent) =>
@@ -150,6 +160,7 @@ const createParser = () => {
 
       // Removes already parsed items from the subtree so that they aren't included in the final content
       remove(subTree, [createQueries.UNIST.isYamlNode]);
+      remove(subTree, [createQueries.UNIST.isLinterComment]);
 
       // Applies the AST transformations to the subtree based on the API doc entry Metadata
       // Note that running the transformation on the subtree isn't costly as it is a reduced tree