From ca5f40f09e856ba09105a1e6918ac8d7a17735b3 Mon Sep 17 00:00:00 2001
From: Antoine du HAMEL <duhamelantoine1995@gmail.com>
Date: Sat, 16 May 2020 14:01:21 +0200
Subject: [PATCH 1/2] doc: lint deprecation codes

Add a rule to make sure deprecation codes are in order.
---
 doc/api/deprecations.md                |   5 +-
 test/doctool/test-deprecation-codes.js |  25 ++++++
 tools/doc/deprecationCodes.js          | 105 +++++++++++++++++++++++++
 3 files changed, 134 insertions(+), 1 deletion(-)
 create mode 100644 test/doctool/test-deprecation-codes.js
 create mode 100644 tools/doc/deprecationCodes.js

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 79060f1db76db8..e56ad042ddf999 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -1129,7 +1129,7 @@ Type: Documentation-only
 The [`util.isNumber()`][] API is deprecated.
 
 <a id="DEP0053"></a>
-### DEP0053 `util.isObject()`
+### DEP0053: `util.isObject()`
 <!-- YAML
 changes:
   - version:
@@ -1795,6 +1795,9 @@ Type: End-of-Life
 `runInAsyncIdScope` doesn't emit the `'before'` or `'after'` event and can thus
 cause a lot of issues. See <https://github.com/nodejs/node/issues/14328>.
 
+<!-- md-lint skip-deprecation DEP0087 -->
+<!-- md-lint skip-deprecation DEP0088 -->
+
 <a id="DEP0089"></a>
 ### DEP0089: `require('assert')`
 <!-- YAML
diff --git a/test/doctool/test-deprecation-codes.js b/test/doctool/test-deprecation-codes.js
new file mode 100644
index 00000000000000..599a37bab446b4
--- /dev/null
+++ b/test/doctool/test-deprecation-codes.js
@@ -0,0 +1,25 @@
+'use strict';
+
+require('../common');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const script = path.join(
+  __dirname,
+  '..',
+  '..',
+  'tools',
+  'doc',
+  'deprecationCodes.js'
+);
+
+const mdPath = path.join(
+  __dirname,
+  '..',
+  '..',
+  'doc',
+  'api',
+  'deprecations.md'
+);
+
+execFileSync(process.execPath, [script, mdPath], { encoding: 'utf-8' });
diff --git a/tools/doc/deprecationCodes.js b/tools/doc/deprecationCodes.js
new file mode 100644
index 00000000000000..a5062263ffe2de
--- /dev/null
+++ b/tools/doc/deprecationCodes.js
@@ -0,0 +1,105 @@
+'use strict';
+
+const fs = require('fs');
+const { resolve } = require('path');
+
+const unified = require('unified');
+const assert = require('assert');
+const source = resolve(process.argv[2]);
+
+const skipDeprecationComment = /^<!-- md-lint skip-deprecation (DEP\d{4}) -->$/;
+
+const generateDeprecationCode = (codeAsNumber) =>
+  `DEP${codeAsNumber.toString().padStart(4, '0')}`;
+
+const addMarkdownPathToErrorStack = (error, node) => {
+  const { line, column } = node.position.start;
+  const [header, ...lines] = error.stack.split('\n');
+  error.stack =
+          header +
+          `\n    at <anonymous> (${source}:${line}:${column})\n` +
+          lines.join('\n');
+  return error;
+};
+
+const testAnchor = (anchorNode, expectedDeprecationCode) => {
+  try {
+    assert.strictEqual(
+              anchorNode?.children[0]?.value,
+              `<a id="${expectedDeprecationCode}">`,
+              `Missing or ill-formed anchor for ${expectedDeprecationCode}.`
+    );
+  } catch (e) {
+    throw addMarkdownPathToErrorStack(e, anchorNode);
+  }
+};
+
+const testHeading = (headingNode, expectedDeprecationCode) => {
+  try {
+    assert.strictEqual(
+            headingNode?.children[0]?.value.substring(0, 9),
+            `${expectedDeprecationCode}: `,
+            'Ill-formed or out-of-order deprecation code.'
+    );
+  } catch (e) {
+    throw addMarkdownPathToErrorStack(e, headingNode);
+  }
+};
+
+const testYAMLComment = (commentNode) => {
+  try {
+    assert.strictEqual(
+              commentNode?.value?.substring(0, 19),
+              '<!-- YAML\nchanges:\n',
+              'Missing or ill-formed YAML comment.'
+    );
+  } catch (e) {
+    throw addMarkdownPathToErrorStack(e, commentNode);
+  }
+};
+
+const testDeprecationType = (paragraphNode) => {
+  try {
+    assert.strictEqual(
+              paragraphNode?.children[0]?.value?.substring(0, 6),
+              'Type: ',
+              'Missing deprecation type.'
+    );
+  } catch (e) {
+    throw addMarkdownPathToErrorStack(e, paragraphNode);
+  }
+};
+
+const tree = unified()
+  .use(require('remark-parse'))
+  .parse(fs.readFileSync(source));
+
+let expectedDeprecationCodeNumber = 0;
+for (let i = 0; i < tree.children.length; i++) {
+  const node = tree.children[i];
+  if (node.type === 'html' && skipDeprecationComment.test(node.value)) {
+    const expectedDeprecationCode =
+          generateDeprecationCode(++expectedDeprecationCodeNumber);
+    const deprecationCodeAsText = node.value.match(skipDeprecationComment)[1];
+
+    try {
+      assert.strictEqual(
+        deprecationCodeAsText,
+        expectedDeprecationCode,
+        'Deprecation codes are not ordered correctly.'
+      );
+    } catch (e) {
+      throw addMarkdownPathToErrorStack(e, node);
+    }
+  }
+  if (node.type === 'heading' && node.depth === 3) {
+    const expectedDeprecationCode =
+          generateDeprecationCode(++expectedDeprecationCodeNumber);
+
+    testHeading(node, expectedDeprecationCode);
+
+    testAnchor(tree.children[i - 1], expectedDeprecationCode);
+    testYAMLComment(tree.children[i + 1]);
+    testDeprecationType(tree.children[i + 2]);
+  }
+}

From e9139b6883f83983092a7a7c3116d847343cbc80 Mon Sep 17 00:00:00 2001
From: Antoine du HAMEL <duhamelantoine1995@gmail.com>
Date: Fri, 29 May 2020 11:41:36 +0200
Subject: [PATCH 2/2] Add lint rule for runtime deprecations

---
 ...est-eslint-documented-deprecation-codes.js | 45 +++++++++++++++++++
 .../documented-deprecation-codes.js           | 45 +++++++++++++++++++
 tools/eslint-rules/rules-utils.js             |  8 ++++
 3 files changed, 98 insertions(+)
 create mode 100644 test/parallel/test-eslint-documented-deprecation-codes.js
 create mode 100644 tools/eslint-rules/documented-deprecation-codes.js

diff --git a/test/parallel/test-eslint-documented-deprecation-codes.js b/test/parallel/test-eslint-documented-deprecation-codes.js
new file mode 100644
index 00000000000000..30cb214e666695
--- /dev/null
+++ b/test/parallel/test-eslint-documented-deprecation-codes.js
@@ -0,0 +1,45 @@
+'use strict';
+
+const common = require('../common');
+if (!common.hasCrypto)
+  common.skip('missing crypto');
+common.skipIfEslintMissing();
+
+const RuleTester = require('../../tools/node_modules/eslint').RuleTester;
+const rule = require('../../tools/eslint-rules/documented-deprecation-codes');
+
+const mdFile = 'doc/api/deprecations.md';
+
+const invalidCode = 'UNDOCUMENTED INVALID CODE';
+
+new RuleTester().run('documented-deprecation-codes', rule, {
+  valid: [
+    `
+    deprecate(function() {
+        return this.getHeaders();
+      }, 'OutgoingMessage.prototype._headers is deprecated', 'DEP0066')
+    `
+  ],
+  invalid: [
+    {
+      code: `
+        deprecate(function foo(){}, 'bar', '${invalidCode}');
+      `,
+      errors: [
+        {
+          message: `"${invalidCode}" does not match the expected pattern`,
+          line: 2
+        },
+        {
+          message: `"${invalidCode}" is not documented in ${mdFile}`,
+          line: 2
+        },
+        {
+          message:
+            `${mdFile} does not have an anchor for "${invalidCode}"`,
+          line: 2
+        }
+      ]
+    }
+  ]
+});
diff --git a/tools/eslint-rules/documented-deprecation-codes.js b/tools/eslint-rules/documented-deprecation-codes.js
new file mode 100644
index 00000000000000..b950f4553be74f
--- /dev/null
+++ b/tools/eslint-rules/documented-deprecation-codes.js
@@ -0,0 +1,45 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { isDefiningDeprecation } = require('./rules-utils.js');
+
+const patternToMatch = /^DEP\d+$/;
+
+const mdFile = 'doc/api/deprecations.md';
+const doc = fs.readFileSync(path.resolve(__dirname, '../..', mdFile), 'utf8');
+
+function isInDoc(code) {
+  return doc.includes(`### ${code}:`);
+}
+
+function includesAnchor(code) {
+  return doc.includes(`<a id="${code}"></a>`);
+}
+
+function getDeprecationCode(node) {
+  return node.expression.arguments[2].value;
+}
+
+module.exports = {
+  create: function(context) {
+    return {
+      ExpressionStatement: function(node) {
+        if (!isDefiningDeprecation(node) || !getDeprecationCode(node)) return;
+        const code = getDeprecationCode(node);
+        if (!patternToMatch.test(code)) {
+          const message = `"${code}" does not match the expected pattern`;
+          context.report({ node, message });
+        }
+        if (!isInDoc(code)) {
+          const message = `"${code}" is not documented in ${mdFile}`;
+          context.report({ node, message });
+        }
+        if (!includesAnchor(code)) {
+          const message = `${mdFile} does not have an anchor for "${code}"`;
+          context.report({ node, message });
+        }
+      },
+    };
+  },
+};
diff --git a/tools/eslint-rules/rules-utils.js b/tools/eslint-rules/rules-utils.js
index 462ab7c2ff3ab8..5bfefccb99be4c 100644
--- a/tools/eslint-rules/rules-utils.js
+++ b/tools/eslint-rules/rules-utils.js
@@ -20,6 +20,14 @@ module.exports.isDefiningError = function(node) {
          node.expression.arguments.length !== 0;
 };
 
+module.exports.isDefiningDeprecation = function(node) {
+  return node.expression &&
+         node.expression.type === 'CallExpression' &&
+         node.expression.callee &&
+         node.expression.callee.name.endsWith('deprecate') &&
+         node.expression.arguments.length !== 0;
+};
+
 /**
  * Returns true if any of the passed in modules are used in
  * require calls.