feat: add only-csf3 rule

Author: cylewaitforit

README.md

@@ -185,6 +185,7 @@ This plugin does not support MDX files.
 | [`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>                                                                           |
 | [`storybook/no-uninstalled-addons`](./docs/rules/no-uninstalled-addons.md)                 | This rule identifies storybook addons that are invalid because they are either not installed or contain a typo in their name. |     | <ul><li>recommended</li><li>flat/recommended</li></ul>                                                                         |
+| [`storybook/only-csf3`](./docs/rules/only-csf3.md)                                         | Enforce Component Story Format 3.0 (CSF3) for stories                                                                         |     | N/A                                                                                                                            |
 | [`storybook/prefer-pascal-case`](./docs/rules/prefer-pascal-case.md)                       | Stories should use PascalCase                                                                                                 | 🔧  | <ul><li>recommended</li><li>flat/recommended</li></ul>                                                                         |
 | [`storybook/story-exports`](./docs/rules/story-exports.md)                                 | A story file must contain at least one story export                                                                           |     | <ul><li>recommended</li><li>flat/recommended</li><li>csf</li><li>flat/csf</li><li>csf-strict</li><li>flat/csf-strict</li></ul> |
 | [`storybook/use-storybook-expect`](./docs/rules/use-storybook-expect.md)                   | Use expect from `@storybook/test`, `storybook/test` or `@storybook/jest`                                                      | 🔧  | <ul><li>addon-interactions</li><li>flat/addon-interactions</li><li>recommended</li><li>flat/recommended</li></ul>              |

docs/rules/only-csf3.md

@@ -0,0 +1,125 @@
+# Enforce CSF3 format for stories (only-csf3)
+
+[Component Story Format 3.0 (CSF3)](https://storybook.js.org/blog/component-story-format-3-0/) is the latest iteration of Storybook's story format, offering a simpler and more maintainable way to write stories. This rule enforces the use of CSF3 by identifying and reporting CSF2 patterns.
+
+<!-- RULE-CATEGORIES:START -->
+
+**Included in these configurations**: N/A
+
+<!-- RULE-CATEGORIES:END -->
+
+## Rule Details
+
+This rule aims to prevent the use of CSF2 patterns in story files and encourage migration to CSF3.
+
+Examples of **incorrect** code:
+
+```js
+// ❌ CSF2: Using Template.bind({})
+const Template = (args) => <Button {...args} />
+export const Primary = Template.bind({})
+Primary.args = { label: 'Primary' }
+
+// ❌ CSF2: Story function declaration
+export function Secondary(args) {
+  return <Button {...args} />
+}
+
+// ❌ CSF2: Story arrow function
+export const Tertiary = () => <Button>Click me</Button>
+
+// ❌ CSF2: Story with property assignments
+export const WithArgs = Template.bind({})
+WithArgs.args = { label: 'With Args' }
+WithArgs.parameters = { layout: 'centered' }
+```
+
+Examples of **correct** code:
+
+```js
+// ✅ CSF3: Object literal with args
+export const Primary = {
+  args: {
+    label: 'Primary',
+  },
+}
+
+// ✅ CSF3: Object literal with render function
+export const Secondary = {
+  render: (args) => <Button {...args}>Secondary</Button>,
+}
+```
+
+## When Not To Use It
+
+If you're maintaining a legacy Storybook project that extensively uses CSF2 patterns and cannot migrate to CSF3 yet, you might want to disable this rule.
+
+## Migration Examples
+
+Here are examples of how to migrate common CSF2 patterns to CSF3:
+
+1. Template.bind({}) with args:
+
+```js
+// ❌ CSF2
+const Template = (args) => <Button {...args} />
+export const Primary = Template.bind({})
+Primary.args = { label: 'Primary' }
+
+// ✅ CSF3
+export const Primary = {
+  args: { label: 'Primary' },
+  render: (args) => <Button {...args} />,
+}
+```
+
+2. Function declaration stories:
+
+```js
+// ❌ CSF2
+export function Primary(args) {
+  return <Button {...args}>Primary</Button>
+}
+
+// ✅ CSF3
+export const Primary = {
+  render: (args) => <Button {...args}>Primary</Button>,
+}
+```
+
+3. Story with multiple properties:
+
+```js
+// ❌ CSF2
+export const Primary = Template.bind({})
+Primary.args = { label: 'Primary' }
+Primary.parameters = { layout: 'centered' }
+Primary.decorators = [
+  (Story) => (
+    <div style={{ padding: '1rem' }}>
+      <Story />
+    </div>
+  ),
+]
+
+// ✅ CSF3
+export const Primary = {
+  args: { label: 'Primary' },
+  parameters: { layout: 'centered' },
+  decorators: [
+    (Story) => (
+      <div style={{ padding: '1rem' }}>
+        <Story />
+      </div>
+    ),
+  ],
+  render: (args) => <Button {...args} />,
+}
+```
+
+## Further Reading
+
+- [Component Story Format 3.0](https://storybook.js.org/blog/component-story-format-3-0/)
+- [Migrating to CSF3](https://storybook.js.org/docs/migration-guide/from-older-version#csf-2-to-csf-3)
+- [Upgrading from CSF 2.0 to 3.0](https://storybook.js.org/docs/api/csf/index#upgrading-from-csf-2-to-csf-3)
+- [Writing Stories in Storybook](https://storybook.js.org/docs/writing-stories#component-story-format)

lib/index.ts

@@ -25,6 +25,7 @@ import noRedundantStoryName from './rules/no-redundant-story-name'
 import noStoriesOf from './rules/no-stories-of'
 import noTitlePropertyInMeta from './rules/no-title-property-in-meta'
 import noUninstalledAddons from './rules/no-uninstalled-addons'
+import onlyCsf3 from './rules/only-csf3'
 import preferPascalCase from './rules/prefer-pascal-case'
 import storyExports from './rules/story-exports'
 import useStorybookExpect from './rules/use-storybook-expect'
@@ -57,6 +58,7 @@ export = {
     'no-stories-of': noStoriesOf,
     'no-title-property-in-meta': noTitlePropertyInMeta,
     'no-uninstalled-addons': noUninstalledAddons,
+    'only-csf3': onlyCsf3,
     'prefer-pascal-case': preferPascalCase,
     'story-exports': storyExports,
     'use-storybook-expect': useStorybookExpect,

lib/rules/only-csf3.ts

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Enforce CSF3 format for stories.
+ * @see https://storybook.js.org/blog/component-story-format-3-0/
+ */
+
+import { AST_NODE_TYPES, TSESTree } from '@typescript-eslint/utils'
+import { createStorybookRule } from '../utils/create-storybook-rule'
+import { isIdentifier, isMemberExpression } from '../utils/ast'
+
+// Properties that indicate CSF2 format when assigned to a story
+const CSF2_PROPERTIES = new Set(['args', 'parameters', 'decorators', 'play', 'storyName'])
+
+export = createStorybookRule({
+  name: 'only-csf3',
+  defaultOptions: [],
+  meta: {
+    type: 'problem',
+    severity: 'error',
+    docs: {
+      description: 'Enforce Component Story Format 3.0 (CSF3) for stories',
+      excludeFromConfig: true,
+    },
+    schema: [],
+    messages: {
+      noCSF2Format: 'Story "{{storyName}}" uses CSF2 {{pattern}}. Please migrate to CSF3.',
+    },
+  },
+  create(context) {
+    const reportedStories = new Set<string>()
+    const pendingReports = new Map<string, { node: TSESTree.Node; pattern: string }>()
+
+    const report = (storyName: string, node: TSESTree.Node, pattern: string): void => {
+      if (!reportedStories.has(storyName)) {
+        reportedStories.add(storyName)
+        context.report({
+          node,
+          messageId: 'noCSF2Format',
+          data: {
+            storyName,
+            pattern,
+          },
+        })
+      }
+    }
+
+    return {
+      ExportNamedDeclaration(node: TSESTree.ExportNamedDeclaration) {
+        const decl = node.declaration
+        if (!decl) return
+
+        // Function declarations
+        if (decl.type === AST_NODE_TYPES.FunctionDeclaration && decl.id) {
+          report(decl.id.name, decl, 'function declaration')
+          return
+        }
+
+        // Arrow/function expressions: delay reporting until we know if there are property assignments
+        if (decl.type === AST_NODE_TYPES.VariableDeclaration) {
+          const declarator = decl.declarations[0]
+          if (
+            declarator?.init &&
+            declarator.id &&
+            declarator.id.type === AST_NODE_TYPES.Identifier
+          ) {
+            if (declarator.init.type === AST_NODE_TYPES.ArrowFunctionExpression) {
+              pendingReports.set(declarator.id.name, {
+                node: declarator.init,
+                pattern: 'arrow function',
+              })
+            } else if (declarator.init.type === AST_NODE_TYPES.FunctionExpression) {
+              pendingReports.set(declarator.id.name, {
+                node: declarator.init,
+                pattern: 'function expression',
+              })
+            }
+          }
+        }
+      },
+
+      AssignmentExpression(node: TSESTree.AssignmentExpression) {
+        if (
+          !isMemberExpression(node.left) ||
+          !isIdentifier(node.left.object) ||
+          !isIdentifier(node.left.property)
+        ) {
+          return
+        }
+        const propertyName = node.left.property.name
+        const storyName = node.left.object.name
+
+        if (CSF2_PROPERTIES.has(propertyName) && !reportedStories.has(storyName)) {
+          // Remove any pending arrow/function report for this story
+          pendingReports.delete(storyName)
+          report(storyName, node, `property assignment (.${propertyName})`)
+        }
+      },
+
+      'Program:exit'() {
+        // Report any remaining arrow/function expression reports
+        for (const [storyName, { node, pattern }] of pendingReports) {
+          if (!reportedStories.has(storyName)) {
+            report(storyName, node, pattern)
+          }
+        }
+        pendingReports.clear()
+      },
+    }
+  },
+})