linter: add deprecation code check, linter declarations

Signed-off-by: flakey5 <[email protected]>

Author: flakey5

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

@@ -426,5 +426,8 @@ export const LINT_MESSAGES = {
   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",
+  outOfOrderDeprecationCode:
+    "Deprecation code '{{code}}' out of order (expected {{expectedCode}})",
+  invalidLinterDeclaration: "Invalid linter declaration '{{declaration}}'",
+  malformedLinterDeclaration: 'Malformed linter declaration: {{message}}',
 };

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,15 @@ 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 rule of rules) {
-      const ruleIssues = rule(entries);
+      const ruleIssues = rule(entries, declarations);
 
       if (ruleIssues.length > 0) {
         issues.push(...ruleIssues);

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

@@ -1,4 +1,3 @@
-// @ts-check
 'use strict';
 
 import { LINT_MESSAGES } from '../../constants.mjs';
@@ -8,7 +7,7 @@ import getDeprecationEntries from './utils/getDeprecationEntries.mjs';
 
 /**
  * @param {ApiDocMetadataEntry} deprecation
- * @param {number} expectedCode 
+ * @param {number} expectedCode
  * @returns {Array<import('../types').LintIssue>}
  */
 function lintDeprecation(deprecation, expectedCode) {
@@ -32,24 +31,28 @@ function lintDeprecation(deprecation, expectedCode) {
 
   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]),
-    },
-  ];
+  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 => {
+export const deprecationCodeOrder = (entries, declarations) => {
   if (entries.length === 0 || entries[0].api !== 'deprecations') {
     // This is only relevant to doc/api/deprecations.md
     return [];
@@ -64,11 +67,15 @@ export const deprecationCodeOrder = entries => {
 
     let expectedCode = 1;
 
-    deprecations?.forEach(deprecation => {
+    for (const deprecation of deprecations || []) {
+      while (declarations.skipDeprecation.includes(expectedCode)) {
+        expectedCode++;
+      }
+
       issues.push(...lintDeprecation(deprecation, expectedCode));
 
       expectedCode++;
-    });
+    }
   });
 
   return issues;

src/linter/rules/index.mjs

@@ -2,17 +2,15 @@
 
 import { deprecationCodeOrder } from './deprecation-code-order.mjs';
 import { invalidChangeVersion } from './invalid-change-version.mjs';
-import { malformedDeprecationHeader } from './malformed-deprecation-header.mjs';
 import { missingChangeVersion } from './missing-change-version.mjs';
 import { missingIntroducedIn } from './missing-introduced-in.mjs';
 
 /**
  * @type {Record<string, import('../types').LintRule>}
  */
 export default {
-  // 'invalid-change-version': invalidChangeVersion,
-  // 'missing-change-version': missingChangeVersion,
-  // 'missing-introduced-in': missingIntroducedIn,
-  'deprecation-code-order': deprecationCodeOrder
-  // 'malformed-deprecation-header': malformedDeprecationHeader,
+  'invalid-change-version': invalidChangeVersion,
+  'missing-change-version': missingChangeVersion,
+  'missing-introduced-in': missingIntroducedIn,
+  'deprecation-code-order': deprecationCodeOrder,
 };

src/linter/types.d.ts

@@ -13,6 +13,13 @@ export interface LintIssue {
   location: LintIssueLocation;
 }
 
-type LintRule = (input: Array<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

src/queries.mjs

@@ -200,6 +200,8 @@ createQueries.QUERIES = {
   stabilityIndexPrefix: /Stability: ([0-5])/,
   // ReGeX for retrieving the inner content from a YAML block
   yamlInnerContent: /^<!--[ ]?(?:YAML([\s\S]*?)|([ \S]*?))?[ ]?-->/,
+  // ReGeX for retrieiving inline linting directives
+  linterComment: /^<!--[ ]?md-lint (.+?)[ ]?-->$/,
 };
 
 createQueries.UNIST = {
@@ -216,6 +218,12 @@ createQueries.UNIST = {
    */
   isYamlNode: ({ type, value }) =>
     type === 'html' && createQueries.QUERIES.yamlInnerContent.test(value),
+  /**
+   * @param {import('@types/mdast').Html} html
+   * @returns {boolean}
+   */
+  isLinterComment: ({ type, value }) =>
+    type === 'html' && createQueries.QUERIES.linterComment.test(value),
   /**
    * @param {import('@types/mdast').Text} text
    * @returns {boolean}