eslint-plugin-storybook 0.1.0 → 0.2.2

package/README.md

@@ -1,21 +1,48 @@
+<p align="center">
+  <a href="https://storybook.js.org/">
+    <img src="https://user-images.githubusercontent.com/321738/63501763-88dbf600-c4cc-11e9-96cd-94adadc2fd72.png" alt="Storybook" width="400" />
+  </a>
+</p>
+
+<p align="center">Build bulletproof UI components faster</p>
+
+<br/>
+
+<p align="center">
+  <a href="https://discord.gg/storybook">
+    <img src="https://img.shields.io/badge/discord-join-7289DA.svg?logo=discord&longCache=true&style=flat" />
+  </a>
+  <a href="https://storybook.js.org/community/">
+    <img src="https://img.shields.io/badge/community-join-4BC424.svg" alt="Storybook Community" />
+  </a>
+  <a href="#backers">
+    <img src="https://opencollective.com/storybook/backers/badge.svg" alt="Backers on Open Collective" />
+  </a>
+  <a href="#sponsors">
+    <img src="https://opencollective.com/storybook/sponsors/badge.svg" alt="Sponsors on Open Collective" />
+  </a>
+  <a href="https://twitter.com/intent/follow?screen_name=storybookjs">
+    <img src="https://badgen.net/twitter/follow/storybookjs?icon=twitter&label=%40storybookjs" alt="Official Twitter Handle" />
+  </a>
+</p>
+
 # eslint-plugin-storybook
 
-Eslint rules for Storybook Best Practices 
+Best practice rules for Storybook
 
 ## Installation
 
-You'll first need to install [ESLint](http://eslint.org):
+You'll first need to install [ESLint](https://eslint.org/):
 
-```
-$ npm i eslint --save-dev
+```sh
+npm i eslint --save-dev
 ```
 
 Next, install `eslint-plugin-storybook`:
 
+```sh
+npm install eslint-plugin-storybook --save-dev
 ```
-$ npm install eslint-plugin-storybook --save-dev
-```
-
 
 ## Usage
 
@@ -23,28 +50,75 @@ Add `storybook` to the plugins section of your `.eslintrc` configuration file. Y
 
 ```json
 {
-    "plugins": [
-        "storybook"
-    ]
+  "plugins": ["storybook"]
 }
 ```
 
+Then, define which rule configurations to extend in your eslint file. Before that, it's important to understand that **Storybook linting rules should only be applied in your stories files**. You don't want rules to affect your other files such as production or test code as the rules might conflict with rules from other ESLint plugins.
 
-Then configure the rules you want to use under the rules section.
+### Run the plugin only against story files
 
-```json
+We don't want `eslint-plugin-storybook` to run against your whole codebase. To run this plugin only against your stories files, you have the following options:
+
+#### ESLint `overrides`
+
+One way of restricting ESLint config by file patterns is by using [ESLint `overrides`](https://eslint.org/docs/user-guide/configuring/configuration-files#configuration-based-on-glob-patterns).
+
+Assuming you are using the recommended `.stories` extension in your files, the following config would run `eslint-plugin-storybook` only against your stories files:
+
+```javascript
+// .eslintrc
 {
-    "rules": {
-        "storybook/prefer-csf": "error"
-    }
-}
+  // 1) Here we have our usual config which applies to the whole project, so we don't put storybook preset here.
+  "extends": ["airbnb", "plugin:prettier/recommended"],
+
+  // 2) We load eslint-plugin-storybook globally with other ESLint plugins.
+  "plugins": ["react-hooks", "storybook"],
+
+  "overrides": [
+    {
+      // 3) Now we enable eslint-plugin-storybook rules or preset only for matching files!
+      // you can use the one defined in your main.js
+      "files": ['src/**/*.stories.@(js|jsx|ts|tsx)'],
+      "extends": ["plugin:storybook/recommended"],
+
+      // 4) Optional: you can override or disable specific rules here if you want. Else delete this
+      "rules": {
+        'storybook/no-redundant-story-name': 'error'
+      }
+    },
+  ],
+};
 ```
 
+#### ESLint Cascading and Hierarchy
+
+Another approach for customizing ESLint config by paths is through [ESLint Cascading and Hierarchy](https://eslint.org/docs/user-guide/configuring/configuration-files#cascading-and-hierarchy). This is useful if all your stories are placed under the same folder, so you can place there another `.eslintrc` where you enable `eslint-plugin-storybook` for applying it only to the files under such folder, rather than enabling it on your global `.eslintrc` which would apply to your whole project.
+
 ## Supported Rules
 
-* prefer-csf: Display lint message when storiesOf API is used instead of the Component Story Format
+<!-- RULES-LIST:START -->
+
+**Key**: 🔧 = fixable
 
+**Configurations**: csf, csf-strict, addon-interactions, recommended
 
+| Name                                                                                       | Description                                       | 🔧  | Included in configurations      |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------- | --- | ------------------------------- |
+| [`storybook/await-interactions`](./docs/rules/await-interactions.md)                       | Interactions should be awaited                    | 🔧  | addon-interactions, recommended |
+| [`storybook/csf-component`](./docs/rules/csf-component.md)                                 | The component property should be set              |     | csf                             |
+| [`storybook/default-exports`](./docs/rules/default-exports.md)                             | Story files should have a default export          |     | csf, recommended                |
+| [`storybook/hierarchy-separator`](./docs/rules/hierarchy-separator.md)                     | Deprecated hierachy separator in title property   | 🔧  | csf, recommended                |
+| [`storybook/no-redundant-story-name`](./docs/rules/no-redundant-story-name.md)             | A story should not have a redundant name property | 🔧  | csf, recommended                |
+| [`storybook/no-stories-of`](./docs/rules/no-stories-of.md)                                 | storiesOf is deprecated and should not be used    |     | csf-strict                      |
+| [`storybook/no-title-property-in-meta`](./docs/rules/no-title-property-in-meta.md)         | Do not define a title in meta                     | 🔧  | csf-strict                      |
+| [`storybook/prefer-pascal-case`](./docs/rules/prefer-pascal-case.md)                       | Stories should use PascalCase                     | 🔧  | recommended                     |
+| [`storybook/use-storybook-expect`](./docs/rules/use-storybook-expect.md)                   | Use expect from `@storybook/jest`                 | 🔧  | addon-interactions, recommended |
+| [`storybook/use-storybook-testing-library`](./docs/rules/use-storybook-testing-library.md) | Do not use testing-library directly on stories    | 🔧  | addon-interactions, recommended |
 
+<!-- RULES-LIST:END -->
 
+## Contributors
 
+Looking into improving this plugin? That would be awesome!
+Please refer to [the contributing guidelines](./CONTRIBUTING.md) for steps to contributing.

package/dist/configs/addon-interactions.js

@@ -0,0 +1,10 @@
+"use strict";
+module.exports = {
+    plugins: ['storybook'],
+    rules: {
+        'import/no-anonymous-default-export': 'off',
+        'storybook/await-interactions': 'error',
+        'storybook/use-storybook-expect': 'error',
+        'storybook/use-storybook-testing-library': 'error',
+    },
+};

package/dist/configs/csf-strict.js

@@ -0,0 +1,9 @@
+"use strict";
+module.exports = {
+    extends: require.resolve('./csf'),
+    rules: {
+        'import/no-anonymous-default-export': 'off',
+        'storybook/no-stories-of': 'error',
+        'storybook/no-title-property-in-meta': 'error',
+    },
+};

package/dist/configs/csf.js

@@ -0,0 +1,11 @@
+"use strict";
+module.exports = {
+    plugins: ['storybook'],
+    rules: {
+        'import/no-anonymous-default-export': 'off',
+        'storybook/csf-component': 'warn',
+        'storybook/default-exports': 'error',
+        'storybook/hierarchy-separator': 'warn',
+        'storybook/no-redundant-story-name': 'warn',
+    },
+};

package/dist/configs/recommended.js

@@ -0,0 +1,14 @@
+"use strict";
+module.exports = {
+    plugins: ['storybook'],
+    rules: {
+        'import/no-anonymous-default-export': 'off',
+        'storybook/await-interactions': 'error',
+        'storybook/default-exports': 'error',
+        'storybook/hierarchy-separator': 'warn',
+        'storybook/no-redundant-story-name': 'warn',
+        'storybook/prefer-pascal-case': 'warn',
+        'storybook/use-storybook-expect': 'error',
+        'storybook/use-storybook-testing-library': 'error',
+    },
+};

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * @fileoverview Best practice rules for Storybook
+ * @author Yann Braga
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configs = exports.rules = void 0;
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+const requireindex_1 = __importDefault(require("requireindex"));
+//------------------------------------------------------------------------------
+// Plugin Definition
+//------------------------------------------------------------------------------
+// import all rules in lib/rules
+exports.rules = (0, requireindex_1.default)(__dirname + '/rules');
+exports.configs = (0, requireindex_1.default)(__dirname + '/configs');

package/dist/rules/await-interactions.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * @fileoverview Interactions should be awaited
+ * @author Yann Braga
+ */
+const create_storybook_rule_1 = require("../utils/create-storybook-rule");
+const constants_1 = require("../utils/constants");
+const ast_1 = require("../utils/ast");
+module.exports = (0, create_storybook_rule_1.createStorybookRule)({
+    name: 'await-interactions',
+    defaultOptions: [],
+    meta: {
+        docs: {
+            description: 'Interactions should be awaited',
+            categories: [constants_1.CategoryId.ADDON_INTERACTIONS, constants_1.CategoryId.RECOMMENDED],
+            recommended: 'error', // or 'warn'
+        },
+        messages: {
+            interactionShouldBeAwaited: 'Interaction should be awaited: {{method}}',
+            fixSuggestion: 'Add `await` to method',
+        },
+        type: 'problem',
+        fixable: 'code',
+        schema: [],
+    },
+    create(context) {
+        // variables should be defined here
+        //----------------------------------------------------------------------
+        // Helpers
+        //----------------------------------------------------------------------
+        // any helper functions should go here or else delete this section
+        const FUNCTIONS_TO_BE_AWAITED = [
+            'waitFor',
+            'waitForElementToBeRemoved',
+            'wait',
+            'waitForElement',
+            'waitForDomChange',
+            'userEvent',
+        ];
+        const getMethodThatShouldBeAwaited = (expr) => {
+            const shouldAwait = (name) => {
+                return FUNCTIONS_TO_BE_AWAITED.includes(name) || name.startsWith('findBy');
+            };
+            if ((0, ast_1.isMemberExpression)(expr.callee) &&
+                (0, ast_1.isIdentifier)(expr.callee.object) &&
+                shouldAwait(expr.callee.object.name)) {
+                return expr.callee.object;
+            }
+            if ((0, ast_1.isMemberExpression)(expr.callee) &&
+                (0, ast_1.isIdentifier)(expr.callee.property) &&
+                shouldAwait(expr.callee.property.name)) {
+                return expr.callee.property;
+            }
+            if ((0, ast_1.isMemberExpression)(expr.callee) &&
+                (0, ast_1.isCallExpression)(expr.callee.object) &&
+                (0, ast_1.isIdentifier)(expr.callee.object.callee) &&
+                (0, ast_1.isIdentifier)(expr.callee.property) &&
+                expr.callee.object.callee.name === 'expect') {
+                return expr.callee.property;
+            }
+            if ((0, ast_1.isIdentifier)(expr.callee) && shouldAwait(expr.callee.name)) {
+                return expr.callee;
+            }
+            return null;
+        };
+        //----------------------------------------------------------------------
+        // Public
+        //----------------------------------------------------------------------
+        /**
+         * @param {import('eslint').Rule.Node} node
+         */
+        let invocationsThatShouldBeAwaited = [];
+        return {
+            CallExpression(node) {
+                const method = getMethodThatShouldBeAwaited(node);
+                if (method && !(0, ast_1.isAwaitExpression)(node.parent)) {
+                    invocationsThatShouldBeAwaited.push({ node, method });
+                }
+            },
+            'Program:exit': function () {
+                if (invocationsThatShouldBeAwaited.length) {
+                    invocationsThatShouldBeAwaited.forEach(({ node, method }) => {
+                        context.report({
+                            node,
+                            messageId: 'interactionShouldBeAwaited',
+                            data: {
+                                method: method.name,
+                            },
+                            fix: function (fixer) {
+                                return fixer.insertTextBefore(node, 'await ');
+                            },
+                            suggest: [
+                                {
+                                    messageId: 'fixSuggestion',
+                                    fix: function (fixer) {
+                                        return fixer.insertTextBefore(node, 'await ');
+                                    },
+                                },
+                            ],
+                        });
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/csf-component.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * @fileoverview Component property should be set
+ * @author Yann Braga
+ */
+const utils_1 = require("../utils");
+const constants_1 = require("../utils/constants");
+const create_storybook_rule_1 = require("../utils/create-storybook-rule");
+module.exports = (0, create_storybook_rule_1.createStorybookRule)({
+    name: 'csf-component',
+    defaultOptions: [],
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'The component property should be set',
+            categories: [constants_1.CategoryId.CSF],
+            recommended: 'warn',
+        },
+        messages: {
+            missingComponentProperty: 'Missing component property.',
+        },
+        schema: [],
+    },
+    create(context) {
+        // variables should be defined here
+        //----------------------------------------------------------------------
+        // Helpers
+        //----------------------------------------------------------------------
+        // any helper functions should go here or else delete this section
+        //----------------------------------------------------------------------
+        // Public
+        //----------------------------------------------------------------------
+        return {
+            ExportDefaultDeclaration(node) {
+                const meta = (0, utils_1.getMetaObjectExpression)(node, context);
+                if (!meta) {
+                    return null;
+                }
+                const componentProperty = meta.properties.find((property) => property.key.name === 'component');
+                if (!componentProperty) {
+                    context.report({
+                        node,
+                        messageId: 'missingComponentProperty',
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/default-exports.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * @fileoverview Story files should have a default export
+ * @author Yann Braga
+ */
+const constants_1 = require("../utils/constants");
+const ast_1 = require("../utils/ast");
+const create_storybook_rule_1 = require("../utils/create-storybook-rule");
+module.exports = (0, create_storybook_rule_1.createStorybookRule)({
+    name: 'default-export',
+    defaultOptions: [],
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Story files should have a default export',
+            categories: [constants_1.CategoryId.CSF, constants_1.CategoryId.RECOMMENDED],
+            recommended: 'error',
+        },
+        messages: {
+            shouldHaveDefaultExport: 'The file should have a default export.',
+        },
+        schema: [],
+    },
+    create(context) {
+        // variables should be defined here
+        //----------------------------------------------------------------------
+        // Helpers
+        //----------------------------------------------------------------------
+        // any helper functions should go here or else delete this section
+        //----------------------------------------------------------------------
+        // Public
+        //----------------------------------------------------------------------
+        let hasDefaultExport = false;
+        return {
+            ExportDefaultSpecifier: function () {
+                hasDefaultExport = true;
+            },
+            ExportDefaultDeclaration: function () {
+                hasDefaultExport = true;
+            },
+            'Program:exit': function (node) {
+                if (!hasDefaultExport) {
+                    const firstNonImportStatement = node.body.find((n) => !(0, ast_1.isImportDeclaration)(n));
+                    context.report({
+                        node: firstNonImportStatement || node.body[0] || node,
+                        messageId: 'shouldHaveDefaultExport',
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/hierarchy-separator.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * @fileoverview Deprecated hierarchy separator
+ * @author Yann Braga
+ */
+const utils_1 = require("../utils");
+const ast_1 = require("../utils/ast");
+const constants_1 = require("../utils/constants");
+const create_storybook_rule_1 = require("../utils/create-storybook-rule");
+module.exports = (0, create_storybook_rule_1.createStorybookRule)({
+    name: 'hierarchy-separator',
+    defaultOptions: [],
+    meta: {
+        type: 'problem',
+        fixable: 'code',
+        docs: {
+            description: 'Deprecated hierachy separator in title property',
+            categories: [constants_1.CategoryId.CSF, constants_1.CategoryId.RECOMMENDED],
+            recommended: 'warn',
+        },
+        messages: {
+            useCorrectSeparators: 'Use correct separators',
+            deprecatedHierarchySeparator: 'Deprecated hierachy separator in title property: {{metaTitle}}.',
+        },
+        schema: [],
+    },
+    create: function (context) {
+        return {
+            ExportDefaultDeclaration: function (node) {
+                const meta = (0, utils_1.getMetaObjectExpression)(node, context);
+                if (!meta) {
+                    return null;
+                }
+                const titleNode = meta.properties.find((prop) => prop.key.name === 'title');
+                //@ts-ignore
+                if (!titleNode || !(0, ast_1.isLiteral)(titleNode.value)) {
+                    return;
+                }
+                //@ts-ignore
+                const metaTitle = titleNode.value.raw || '';
+                if (metaTitle.includes('|') || metaTitle.includes('.')) {
+                    context.report({
+                        node,
+                        messageId: 'deprecatedHierarchySeparator',
+                        data: { metaTitle },
+                        // In case we want this to be auto fixed by --fix
+                        fix: function (fixer) {
+                            return fixer.replaceTextRange(
+                            //@ts-ignore
+                            titleNode.value.range, metaTitle.replace(/\||\./g, '/'));
+                        },
+                        suggest: [
+                            {
+                                messageId: 'useCorrectSeparators',
+                                fix: function (fixer) {
+                                    return fixer.replaceTextRange(
+                                    //@ts-ignore
+                                    titleNode.value.range, metaTitle.replace(/\||\./g, '/'));
+                                },
+                            },
+                        ],
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/meta-inline-properties.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * @fileoverview Meta should have inline properties
+ * @author Yann Braga
+ */
+const utils_1 = require("../utils");
+const constants_1 = require("../utils/constants");
+const create_storybook_rule_1 = require("../utils/create-storybook-rule");
+module.exports = (0, create_storybook_rule_1.createStorybookRule)({
+    name: 'meta-inline-properties',
+    defaultOptions: [{ csfVersion: 3 }],
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Meta should only have inline properties',
+            categories: [constants_1.CategoryId.CSF, constants_1.CategoryId.RECOMMENDED],
+            excludeFromConfig: true,
+            recommended: 'error',
+        },
+        messages: {
+            metaShouldHaveInlineProperties: 'Meta should only have inline properties: {{property}}',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    csfVersion: {
+                        type: 'number',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    create(context) {
+        // variables should be defined here
+        // In case we need to get options defined in the rule schema
+        // const options = context.options[0] || {}
+        // const csfVersion = options.csfVersion
+        //----------------------------------------------------------------------
+        // Helpers
+        //----------------------------------------------------------------------
+        const isInline = (node) => {
+            return (node.value.type === 'ObjectExpression' ||
+                node.value.type === 'Literal' ||
+                node.value.type === 'ArrayExpression');
+        };
+        // any helper functions should go here or else delete this section
+        //----------------------------------------------------------------------
+        // Public
+        //----------------------------------------------------------------------
+        return {
+            ExportDefaultDeclaration(node) {
+                const meta = (0, utils_1.getMetaObjectExpression)(node, context);
+                if (!meta) {
+                    return null;
+                }
+                const ruleProperties = ['title', 'args'];
+                let dynamicProperties = [];
+                const metaNodes = meta.properties.filter((prop) => 
+                //@ts-ignore
+                ruleProperties.includes(prop.key.name));
+                metaNodes.forEach((metaNode) => {
+                    if (!isInline(metaNode)) {
+                        dynamicProperties.push(metaNode);
+                    }
+                });
+                if (dynamicProperties.length > 0) {
+                    //@ts-ignore
+                    dynamicProperties.forEach((propertyNode) => {
+                        context.report({
+                            node: propertyNode,
+                            messageId: 'metaShouldHaveInlineProperties',
+                            data: {
+                                property: propertyNode.key.name,
+                            },
+                        });
+                    });
+                }
+            },
+        };
+    },
+});