Merge pull request #200 from storybookjs/feat/meta-satisfies-type

Add meta-satisfies-type rule (rebased)

Author: kasperpeulen

README.md

@@ -180,6 +180,7 @@ This plugin does not support MDX files.
 | [`storybook/default-exports`](./docs/rules/default-exports.md)                             | Story files should have a default export                                                                                      | 🔧  | <ul><li>csf</li><li>flat/csf</li><li>recommended</li><li>flat/recommended</li><li>csf-strict</li><li>flat/csf-strict</li></ul> |
 | [`storybook/hierarchy-separator`](./docs/rules/hierarchy-separator.md)                     | Deprecated hierarchy separator in title property                                                                              | 🔧  | <ul><li>csf</li><li>flat/csf</li><li>recommended</li><li>flat/recommended</li><li>csf-strict</li><li>flat/csf-strict</li></ul> |
 | [`storybook/meta-inline-properties`](./docs/rules/meta-inline-properties.md)               | Meta should only have inline properties                                                                                       |     | N/A                                                                                                                            |
+| [`storybook/meta-satisfies-type`](./docs/rules/meta-satisfies-type.md)                     | Meta should use `satisfies Meta`                                                                                              | 🔧  | N/A                                                                                                                            |
 | [`storybook/no-redundant-story-name`](./docs/rules/no-redundant-story-name.md)             | A story should not have a redundant name property                                                                             | 🔧  | <ul><li>csf</li><li>flat/csf</li><li>recommended</li><li>flat/recommended</li><li>csf-strict</li><li>flat/csf-strict</li></ul> |
 | [`storybook/no-stories-of`](./docs/rules/no-stories-of.md)                                 | storiesOf is deprecated and should not be used                                                                                |     | <ul><li>csf-strict</li><li>flat/csf-strict</li></ul>                                                                           |
 | [`storybook/no-title-property-in-meta`](./docs/rules/no-title-property-in-meta.md)         | Do not define a title in meta                                                                                                 | 🔧  | <ul><li>csf-strict</li><li>flat/csf-strict</li></ul>                                                                           |

docs/rules/meta-satisfies-type.md

@@ -0,0 +1,59 @@
+# Meta should be followed by `satisfies Meta` (meta-satisfies-type)
+
+<!-- RULE-CATEGORIES:START -->
+
+**Included in these configurations**: N/A
+
+<!-- RULE-CATEGORIES:END -->
+
+## Rule Details
+
+This rule enforces writing `satisfies Meta` after the meta object definition. This is useful to ensure that stories use the correct properties in the metadata.
+
+Additionally, `satisfies` is preferred over type annotations (`const meta: Meta = {...}`) and type assertions (`const meta = {...} as Meta`). This is because other types like `StoryObj` will check to see which properties are defined in meta and use it for increased type safety. Using type annotations or assertions hides this information from the type-checker, so satisfies should be used instead.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+export default {
+  title: 'Button',
+  args: { primary: true },
+  component: Button,
+}
+```
+
+```ts
+const meta: Meta<typeof Button> = {
+  title: 'Button',
+  args: { primary: true },
+  component: Button,
+}
+export default meta
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+export default {
+  title: 'Button',
+  args: { primary: true },
+  component: Button,
+} satisfies Meta<typeof Button>
+```
+
+```ts
+const meta = {
+  title: 'Button',
+  args: { primary: true },
+  component: Button,
+} satisfies Meta<typeof Button>
+export default meta
+```
+
+## When Not To Use It
+
+If you aren't using TypeScript or you're using a version older than TypeScript 4.9, `satisfies` is not supported and you can avoid this rule.
+
+## Further Reading
+
+- [Improved type safety in Storybook 7](https://storybook.js.org/blog/improved-type-safety-in-storybook-7/?ref=storybookblog.ghost.io)

lib/index.ts

@@ -20,6 +20,7 @@ import csfComponent from './rules/csf-component'
 import defaultExports from './rules/default-exports'
 import hierarchySeparator from './rules/hierarchy-separator'
 import metaInlineProperties from './rules/meta-inline-properties'
+import metaSatisfiesType from './rules/meta-satisfies-type'
 import noRedundantStoryName from './rules/no-redundant-story-name'
 import noStoriesOf from './rules/no-stories-of'
 import noTitlePropertyInMeta from './rules/no-title-property-in-meta'
@@ -51,6 +52,7 @@ export = {
     'default-exports': defaultExports,
     'hierarchy-separator': hierarchySeparator,
     'meta-inline-properties': metaInlineProperties,
+    'meta-satisfies-type': metaSatisfiesType,
     'no-redundant-story-name': noRedundantStoryName,
     'no-stories-of': noStoriesOf,
     'no-title-property-in-meta': noTitlePropertyInMeta,

lib/rules/meta-satisfies-type.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Meta should be followed by `satisfies Meta`
+ * @author Tiger Oakes
+ */
+
+import { AST_NODE_TYPES, ASTUtils, TSESTree, TSESLint } from '@typescript-eslint/utils'
+import { getMetaObjectExpression } from '../utils'
+import { createStorybookRule } from '../utils/create-storybook-rule'
+import { isTSSatisfiesExpression } from '../utils/ast'
+
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+
+export = createStorybookRule({
+  name: 'meta-satisfies-type',
+  defaultOptions: [],
+  meta: {
+    type: 'problem',
+    fixable: 'code',
+    severity: 'error',
+    docs: {
+      description: 'Meta should use `satisfies Meta`',
+      categories: [],
+      excludeFromConfig: true,
+    },
+    messages: {
+      metaShouldSatisfyType: 'CSF Meta should use `satisfies` for type safety',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    // variables should be defined here
+    const sourceCode = context.getSourceCode()
+
+    //----------------------------------------------------------------------
+    // Helpers
+    //----------------------------------------------------------------------
+    const getTextWithParentheses = (node: TSESTree.Node): string => {
+      // Capture parentheses before and after the node
+      let beforeCount = 0
+      let afterCount = 0
+
+      if (ASTUtils.isParenthesized(node, sourceCode)) {
+        const bodyOpeningParen = sourceCode.getTokenBefore(node, ASTUtils.isOpeningParenToken)
+        const bodyClosingParen = sourceCode.getTokenAfter(node, ASTUtils.isClosingParenToken)
+
+        if (bodyOpeningParen && bodyClosingParen) {
+          beforeCount = node.range[0] - bodyOpeningParen.range[0]
+          afterCount = bodyClosingParen.range[1] - node.range[1]
+        }
+      }
+
+      return sourceCode.getText(node, beforeCount, afterCount)
+    }
+
+    const getFixer = (meta: TSESTree.ObjectExpression): TSESLint.ReportFixFunction | undefined => {
+      const { parent } = meta
+      if (!parent) {
+        return undefined
+      }
+
+      switch (parent.type) {
+        // {} as Meta
+        case AST_NODE_TYPES.TSAsExpression:
+          return (fixer) => [
+            fixer.replaceText(parent, getTextWithParentheses(meta)),
+            fixer.insertTextAfter(
+              parent,
+              ` satisfies ${getTextWithParentheses(parent.typeAnnotation)}`
+            ),
+          ]
+        // const meta: Meta = {}
+        case AST_NODE_TYPES.VariableDeclarator: {
+          const { typeAnnotation } = parent.id
+          if (typeAnnotation) {
+            return (fixer) => [
+              fixer.remove(typeAnnotation),
+              fixer.insertTextAfter(
+                meta,
+                ` satisfies ${getTextWithParentheses(typeAnnotation.typeAnnotation)}`
+              ),
+            ]
+          }
+          return undefined
+        }
+        default:
+          return undefined
+      }
+    }
+    // any helper functions should go here or else delete this section
+
+    //----------------------------------------------------------------------
+    // Public
+    //----------------------------------------------------------------------
+
+    return {
+      ExportDefaultDeclaration(node) {
+        const meta = getMetaObjectExpression(node, context)
+        if (!meta) {
+          return null
+        }
+
+        if (!meta.parent || !isTSSatisfiesExpression(meta.parent)) {
+          context.report({
+            node: meta,
+            messageId: 'metaShouldSatisfyType',
+            fix: getFixer(meta),
+          })
+        }
+      },
+    }
+  },
+})

tests/lib/rules/meta-satisfies-type.test.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Meta should use `satisfies Meta`
+ * @author Tiger Oakes
+ */
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+import rule from '../../../lib/rules/meta-satisfies-type'
+import ruleTester from '../../utils/rule-tester'
+
+//------------------------------------------------------------------------------
+// Tests
+//------------------------------------------------------------------------------
+
+ruleTester.run('meta-satisfies-type', rule, {
+  valid: [
+    "export default { title: 'Button', args: { primary: true } } satisfies Meta<typeof Button>",
+    `const meta = {
+      component: AccountForm,
+    } satisfies Meta<typeof AccountForm>;
+    export default meta;`,
+  ],
+
+  invalid: [
+    {
+      code: `export default { title: 'Button', args: { primary: true } }`,
+      errors: [{ messageId: 'metaShouldSatisfyType' }],
+    },
+    {
+      code: `
+      const meta = {
+        component: AccountForm,
+      }
+      export default meta;
+    `,
+      errors: [{ messageId: 'metaShouldSatisfyType' }],
+    },
+    {
+      code: `
+      const meta: Meta<typeof AccountForm> = {
+        component: AccountForm,
+      }
+      export default meta;`,
+      output: `
+      const meta = {
+        component: AccountForm,
+      } satisfies Meta<typeof AccountForm>
+      export default meta;`,
+      errors: [{ messageId: 'metaShouldSatisfyType' }],
+    },
+    {
+      code: `export default { title: 'Button', args: { primary: true } } as Meta<typeof Button>`,
+      output: `export default { title: 'Button', args: { primary: true } } satisfies Meta<typeof Button>`,
+      errors: [{ messageId: 'metaShouldSatisfyType' }],
+    },
+    {
+      code: `
+      const meta = ( {
+        component: AccountForm,
+      }) as (Meta<typeof AccountForm> )
+      export default ( meta );`,
+      output: `
+      const meta = ( {
+        component: AccountForm,
+      }) satisfies (Meta<typeof AccountForm> )
+      export default ( meta );`,
+      errors: [{ messageId: 'metaShouldSatisfyType' }],
+    },
+  ],
+})

tools/utils/categories.ts

@@ -25,12 +25,8 @@ for (const categoryId of categoryIds) {
 
   for (const rule of rules) {
     const ruleCategories = rule.meta.docs?.categories
-    // Throw if rule does not have a category
-    if (!ruleCategories?.length) {
-      throw new Error(`Rule "${rule.ruleId}" does not have any category.`)
-    }
 
-    if (ruleCategories.includes(categoryId) && rule.meta.docs?.excludeFromConfig !== true) {
+    if (ruleCategories?.includes(categoryId) && rule.meta.docs?.excludeFromConfig !== true) {
       categoriesConfig[categoryId].rules?.push(rule)
     }
   }