tools: add eslint rule for documented errors

jasnell · jasnell · commit 76b8803630f9 · 2017-10-26T07:58:29.000-07:00
PR-URL: #16450 Reviewed-By: Anatoli Papirovski <apapirovski@mac.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Teddy Katz <teddy.katz@gmail.com>
diff --git a/lib/internal/errors.js b/lib/internal/errors.js
@@ -1,3 +1,4 @@
+/* eslint documented-errors: "error" */
 /* eslint alphabetize-errors: "error" */
 
 'use strict';
diff --git a/test/parallel/test-eslint-documented-errors.js b/test/parallel/test-eslint-documented-errors.js
@@ -0,0 +1,34 @@
+'use strict';
+
+require('../common');
+
+const RuleTester = require('../../tools/eslint').RuleTester;
+const rule = require('../../tools/eslint-rules/documented-errors');
+
+const invalidCode = 'UNDOCUMENTED ERROR CODE';
+
+new RuleTester().run('documented-errors', rule, {
+  valid: [
+    `
+      E('ERR_ASSERTION', 'foo');
+    `
+  ],
+  invalid: [
+    {
+      code: `
+        E('${invalidCode}', 'bar');
+      `,
+      errors: [
+        {
+          message: `"${invalidCode}" is not documented in doc/api/errors.md`,
+          line: 2
+        },
+        {
+          message:
+            `doc/api/errors.md does not have an anchor for "${invalidCode}"`,
+          line: 2
+        }
+      ]
+    }
+  ]
+});
diff --git a/tools/eslint-rules/documented-errors.js b/tools/eslint-rules/documented-errors.js
@@ -0,0 +1,46 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const doc = fs.readFileSync(path.resolve(__dirname, '../../doc/api/errors.md'),
+                            'utf8');
+
+function isInDoc(code) {
+  return doc.match(`### ${code}`) != null;
+}
+
+function includesAnchor(code) {
+  return doc.match(`<a id="${code}"></a>`) != null;
+}
+
+function errorForNode(node) {
+  return node.expression.arguments[0].value;
+}
+
+function isDefiningError(node) {
+  return node.expression &&
+         node.expression.type === 'CallExpression' &&
+         node.expression.callee &&
+         node.expression.callee.name === 'E';
+}
+
+module.exports = {
+  create: function(context) {
+    return {
+      ExpressionStatement: function(node) {
+        if (!isDefiningError(node)) return;
+        const code = errorForNode(node);
+        if (!isInDoc(code)) {
+          const message = `"${code}" is not documented in doc/api/errors.md`;
+          context.report({ node, message });
+        }
+        if (!includesAnchor(code)) {
+          const message =
+            `doc/api/errors.md does not have an anchor for "${code}"`;
+          context.report({ node, message });
+        }
+      }
+    };
+  }
+};
