feat: add in custom valid-jsdoc rule in plugin @atlauncher/eslint-plugin-atlauncher

Author: RyanTheAllmighty

packages/eslint-config-atlauncher/index.js

@@ -8,6 +8,7 @@ const rules = [
     './rules/ecmascript-6',
 
     // eslint plugins
+    './rules/plugin-atlauncher',
     './rules/plugin-import',
     './rules/plugin-jsx-a11y',
     './rules/plugin-promise',
@@ -21,7 +22,8 @@ module.exports = {
         'react',
         'promise',
         'no-empty-blocks',
-        'filenames'
+        'filenames',
+        '@atlauncher/atlauncher'
     ],
     extends: rules,
     env: {

packages/eslint-config-atlauncher/package.json

@@ -24,6 +24,7 @@
   },
   "homepage": "https://github.com/ATLauncher/style-guide",
   "devDependencies": {
+    "@atlauncher/eslint-plugin-atlauncher": "^0.1.0",
     "babel-eslint": "^7.2.1",
     "eslint": "^3.19.0",
     "eslint-plugin-import": "^2.2.0",
@@ -33,6 +34,7 @@
     "eslint-plugin-react": "^6.10.3"
   },
   "peerDependencies": {
+    "@atlauncher/eslint-plugin-atlauncher": "^0.1.0",
     "babel-eslint": "^7.2.1",
     "eslint": "^3.19.0",
     "eslint-plugin-import": "^2.2.0",

packages/eslint-config-atlauncher/rules/plugin-atlauncher.js

@@ -0,0 +1,16 @@
+module.exports = {
+    rules: {
+        // warn when not using jsdoc unless function name matches one in the ignore list
+        'atlauncher/require-jsdoc': ['warn', {
+            require: {
+                FunctionDeclaration: true,
+                MethodDefinition: true,
+                ClassDeclaration: true,
+                ArrowFunctionExpression: true
+            },
+            ignore: [
+                'render'
+            ]
+        }]
+    }
+};

packages/eslint-config-atlauncher/rules/stylistic-issues.js

@@ -187,16 +187,6 @@ module.exports = {
             allowTemplateLiterals: true
         }],
 
-        // warn when not using jsdoc unless function name matches one in the ignore list
-        'require-jsdoc': ['warn', {
-            require: {
-                FunctionDeclaration: true,
-                MethodDefinition: true,
-                ClassDeclaration: true,
-                ArrowFunctionExpression: true
-            }
-        }],
-
         // require semi colons
         'semi': 'error',
 

packages/eslint-plugin-atlauncher/README.md

@@ -0,0 +1,49 @@
+# @atlauncher/eslint-plugin-atlauncher
+
+Custom ESLint rules for use with eslint-config-atlauncher
+
+## Installation
+
+You'll first need to install [ESLint](http://eslint.org):
+
+```
+$ npm i eslint --save-dev
+```
+
+Next, install `@atlauncher/eslint-plugin-atlauncher`:
+
+```
+$ npm install @atlauncher/eslint-plugin-atlauncher --save-dev
+```
+
+**Note:** If you installed ESLint globally (using the `-g` flag) then you must also install `@atlauncher/eslint-plugin-atlauncher` globally.
+
+## Usage
+
+Add `@atlauncher/atlauncher` to the plugins section of your `.eslintrc` configuration file. You can omit the `eslint-plugin-` prefix:
+
+```json
+{
+    "plugins": [
+        "@atlauncher/atlauncher"
+    ]
+}
+```
+
+Then configure the rules you want to use under the rules section.
+
+```json
+{
+    "rules": {
+        "atlauncher/rule-name": 2
+    }
+}
+```
+
+## Supported Rules
+
+* atlauncher/require-jsdoc - this is the same as the ESLint 'require-jsdoc' rule, but provides an extra 'ignore' option
+                             for function/method/class names to ignore
+
+
+

packages/eslint-plugin-atlauncher/lib/index.js

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Custom ESLint rules for use with eslint-config-atlauncher
+ * @author Ryan Dowling
+ */
+"use strict";
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+var requireIndex = require("requireindex");
+
+//------------------------------------------------------------------------------
+// Plugin Definition
+//------------------------------------------------------------------------------
+
+
+// import all rules in lib/rules
+module.exports.rules = requireIndex(__dirname + "/rules");
+
+
+

packages/eslint-plugin-atlauncher/lib/rules/require-jsdoc.js

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview Ensures functions have valid JSDoc comments
+ * @author Ryan Dowling
+ */
+"use strict";
+
+const astUtils = require("eslint");
+
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+
+module.exports = {
+    meta: {
+        docs: {
+            description: "Ensures functions have JSDoc comments",
+            category: "Stylistic Issues",
+            recommended: false
+        },
+
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    require: {
+                        type: "object",
+                        properties: {
+                            ClassDeclaration: {
+                                type: "boolean"
+                            },
+                            MethodDefinition: {
+                                type: "boolean"
+                            },
+                            FunctionDeclaration: {
+                                type: "boolean"
+                            },
+                            ArrowFunctionExpression: {
+                                type: "boolean"
+                            }
+                        },
+                        additionalProperties: false
+                    },
+                    ignore: {
+                        type: "array",
+                        items: {
+                            type: "string"
+                        },
+                        uniqueItems: true
+                    }
+                },
+                additionalProperties: false
+            }
+        ]
+    },
+
+    create: function(context) {
+        const source = context.getSourceCode();
+        const DEFAULT_OPTIONS = {
+            FunctionDeclaration: true,
+            MethodDefinition: false,
+            ClassDeclaration: false
+        };
+        const options = Object.assign(DEFAULT_OPTIONS, context.options[0] && context.options[0].require || {});
+        const ignore = context.options[0] && context.options[0].ignore || [];
+
+        /**
+         * Report the error message
+         * @param {ASTNode} node node to report
+         * @returns {void}
+         */
+        function report(node) {
+            context.report({ node, message: "Missing JSDoc comment." });
+        }
+
+        /**
+         * Check if the jsdoc comment is present for class methods
+         * @param {ASTNode} node node to examine
+         * @returns {void}
+         */
+        function checkClassMethodJsDoc(node) {
+            if (node.parent.type === "MethodDefinition") {
+                if (isIgnored(node)) {
+                    return;
+                }
+
+                const jsdocComment = source.getJSDocComment(node);
+
+                if (!jsdocComment) {
+                    report(node);
+                }
+            }
+        }
+
+        /**
+         * Check if this node is in the ignore list or not
+         * @param {ASTNode} node node to examine
+         * @returns {boolean|null}
+         */
+        function isIgnored(node) {
+            const name = getNodeName(node);
+
+            return name !== null && ignore.indexOf(name) !== -1;
+        }
+
+        /**
+         * Get the name of this node
+         * @param {ASTNode} node node to examine
+         * @returns {string}
+         */
+        function getNodeName(node) {
+            if (node.id) {
+                return node.id.name;
+            } else {
+                const name = getStaticPropertyName(node.parent);
+
+                if (name) {
+                    return name;
+                }
+            }
+
+            return null;
+        }
+
+
+        /**
+         * Gets the property name of a given node.
+         * The node can be a MemberExpression, a Property, or a MethodDefinition.
+         *
+         * If the name is dynamic, this returns `null`.
+         *
+         * For examples:
+         *
+         *     a.b           // => "b"
+         *     a["b"]        // => "b"
+         *     a['b']        // => "b"
+         *     a[`b`]        // => "b"
+         *     a[100]        // => "100"
+         *     a[b]          // => null
+         *     a["a" + "b"]  // => null
+         *     a[tag`b`]     // => null
+         *     a[`${b}`]     // => null
+         *
+         *     let a = {b: 1}            // => "b"
+         *     let a = {["b"]: 1}        // => "b"
+         *     let a = {['b']: 1}        // => "b"
+         *     let a = {[`b`]: 1}        // => "b"
+         *     let a = {[100]: 1}        // => "100"
+         *     let a = {[b]: 1}          // => null
+         *     let a = {["a" + "b"]: 1}  // => null
+         *     let a = {[tag`b`]: 1}     // => null
+         *     let a = {[`${b}`]: 1}     // => null
+         *
+         * @param {ASTNode} node - The node to get.
+         * @returns {string|null} The property name if static. Otherwise, null.
+         */
+        function getStaticPropertyName(node) {
+            let prop;
+
+            switch (node && node.type) {
+                case "Property":
+                case "MethodDefinition":
+                    prop = node.key;
+                    break;
+
+                case "MemberExpression":
+                    prop = node.property;
+                    break;
+
+                // no default
+            }
+
+            switch (prop && prop.type) {
+                case "Literal":
+                    return String(prop.value);
+
+                case "TemplateLiteral":
+                    if (prop.expressions.length === 0 && prop.quasis.length === 1) {
+                        return prop.quasis[0].value.cooked;
+                    }
+                    break;
+
+                case "Identifier":
+                    if (!node.computed) {
+                        return prop.name;
+                    }
+                    break;
+
+                // no default
+            }
+
+            return null;
+        }
+
+        /**
+         * Check if the jsdoc comment is present or not.
+         * @param {ASTNode} node node to examine
+         * @returns {void}
+         */
+        function checkJsDoc(node) {
+            if (isIgnored(node)) {
+                return;
+            }
+
+            const jsdocComment = source.getJSDocComment(node);
+
+            if (!jsdocComment) {
+                report(node);
+            }
+        }
+
+        return {
+            FunctionDeclaration(node) {
+                if (options.FunctionDeclaration) {
+                    checkJsDoc(node);
+                }
+            },
+            FunctionExpression(node) {
+                if (options.MethodDefinition) {
+                    checkClassMethodJsDoc(node);
+                }
+            },
+            ClassDeclaration(node) {
+                if (options.ClassDeclaration) {
+                    checkJsDoc(node);
+                }
+            },
+            ArrowFunctionExpression(node) {
+                if (options.ArrowFunctionExpression && node.parent.type === "VariableDeclarator") {
+                    checkJsDoc(node);
+                }
+            }
+        };
+    }
+};