tmp

Author: flakey5

src/constants.mjs

@@ -425,4 +425,6 @@ 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",
 };

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

@@ -16,7 +16,7 @@ const createLinterEngine = rules => {
     const issues = [];
 
     for (const rule of rules) {
-      const ruleIssues = rule(entry);
+      const ruleIssues = rule([entry]);
 
       if (ruleIssues.length > 0) {
         issues.push(...ruleIssues);
@@ -35,8 +35,12 @@ const createLinterEngine = rules => {
   const lintAll = entries => {
     const issues = [];
 
-    for (const entry of entries) {
-      issues.push(...lint(entry));
+    for (const rule of rules) {
+      const ruleIssues = rule(entries);
+
+      if (ruleIssues.length > 0) {
+        issues.push(...ruleIssues);
+      }
     }
 
     return issues;

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

@@ -0,0 +1,75 @@
+// @ts-check
+'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]),
+    },
+  ];
+}
+
+/**
+ * Checks if any deprecation codes are out of order
+ *
+ * @type {import('../types').LintRule}
+ */
+export const deprecationCodeOrder = entries => {
+  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;
+
+    deprecations?.forEach(deprecation => {
+      issues.push(...lintDeprecation(deprecation, expectedCode));
+
+      expectedCode++;
+    });
+  });
+
+  return issues;
+};

src/linter/rules/index.mjs

@@ -1,14 +1,18 @@
 'use strict';
 
+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,
+  // 'invalid-change-version': invalidChangeVersion,
+  // 'missing-change-version': missingChangeVersion,
+  // 'missing-introduced-in': missingIntroducedIn,
+  'deprecation-code-order': deprecationCodeOrder
+  // 'malformed-deprecation-header': malformedDeprecationHeader,
 };

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';
 
 /**