add enforce-css-module-default-import rule (#266)

* add enforce-css-module-default-import rule

* changeset

.changeset/purple-pears-kiss.md

@@ -0,0 +1,5 @@
+---
+'eslint-plugin-primer-react': minor
+---
+
+Add enforce-css-module-default-import rule

docs/rules/enforce-css-module-default-import.md

@@ -0,0 +1,53 @@
+# Enforce CSS Module Default Import (enforce-css-module-default-import)
+
+CSS Modules should import only the default import. Avoid named imports which can often conflict with other variables (including the function name of the React component) when importing css modules.
+
+Additionally, for consistency among the codebase the default import should be consistently named. This rule allows enforcing the name of the default import, which by default expects it to be named either `classes` or be suffixed `Classes`.
+
+## Rule details
+
+This rule disallows the use of any CSS Module property that does not match the desired casing.
+
+👎 Examples of **incorrect** code for this rule:
+
+```jsx
+/* eslint primer-react/enforce-css-module-default-import: "error" */
+import {Button} from '@primer/react'
+import {Button as ButtonClass} from './some.module.css' // oops! Conflict!
+```
+
+```jsx
+/* eslint primer-react/enforce-css-module-default-import: ["error",{enforceName:"^classes$"}] */
+import {Button} from '@primer/react'
+import classnames from './some.module.css' // This default import should match /^classes$/
+```
+
+👍 Examples of **correct** code for this rule:
+
+```jsx
+/* eslint primer-react/enforce-css-module-default-import: "error" */
+import {Button} from '@primer/react'
+import classes from './some.module.css'
+```
+
+```jsx
+/* eslint primer-react/enforce-css-module-default-import: ["error",{enforceName:"^classes$"}] */
+import {Button} from '@primer/react'
+import classes from './some.module.css'
+```
+
+```jsx
+/* eslint primer-react/enforce-css-module-default-import: ["error",{enforceName:"(^classes$|Classes$)"}] */
+import {Button} from '@primer/react'
+import classes from './some.module.css'
+import sharedClasses from './shared.module.css'
+import utilClasses from './util.module.css'
+```
+
+## Options
+
+- `enforceName` (default: `.*`)
+
+  By default, the `enforce-css-module-default-import` rule will allow any name for the default export,
+  however in the _recommended_ ruleset this is set to `(^classes$|Classes$)` meaning that the default
+  export name must either be exactly `classes` or end in `Classes`, for example `sharedClasses`.

src/configs/recommended.js

@@ -21,6 +21,7 @@ module.exports = {
     'primer-react/no-unnecessary-components': 'error',
     'primer-react/prefer-action-list-item-onselect': 'error',
     'primer-react/enforce-css-module-identifier-casing': 'error',
+    'primer-react/enforce-css-module-default-import': ['error', {enforceName: '(^classes$|Classes$)'}],
   },
   settings: {
     github: {

src/index.js

@@ -15,6 +15,7 @@ module.exports = {
     'no-unnecessary-components': require('./rules/no-unnecessary-components'),
     'prefer-action-list-item-onselect': require('./rules/prefer-action-list-item-onselect'),
     'enforce-css-module-identifier-casing': require('./rules/enforce-css-module-identifier-casing'),
+    'enforce-css-module-default-import': require('./rules/enforce-css-module-default-import'),
   },
   configs: {
     recommended: require('./configs/recommended'),

src/rules/__tests__/enforce-css-module-default-import.js

@@ -0,0 +1,88 @@
+const rule = require('../enforce-css-module-default-import')
+const {RuleTester} = require('eslint')
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+})
+
+ruleTester.run('enforce-css-module-default-import', rule, {
+  valid: [
+    'import classes from "a.module.css";',
+    'import {default as classes} from "a.module.css";',
+    'import staticClasses from "a.module.css";',
+    'import fooClasses from "a.module.css";',
+    'import whatever from "a.js";',
+    'import whatever from "a.module.js";',
+    'import whatever from "a.css";',
+    'import {whatever} from "a.js";',
+    'import {whatever} from "a.css";',
+    {
+      code: 'import classes from "a.module.css";',
+      options: [{enforceName: '(?:^classes$|Classes$)'}],
+    },
+    {
+      code: 'import sharedClasses from "a.module.css";',
+      options: [{enforceName: '(?:^classes$|Classes$)'}],
+    },
+  ],
+  invalid: [
+    {
+      code: 'import {foo} from "a.module.css";',
+      errors: [
+        {
+          messageId: 'notDefault',
+        },
+      ],
+    },
+    {
+      code: 'import _, {foo} from "a.module.css";',
+      errors: [
+        {
+          messageId: 'notDefault',
+        },
+      ],
+    },
+    {
+      code: 'import foobar from "a.module.css";',
+      options: [{enforceName: '(?:^classes$|Classes$)'}],
+      errors: [
+        {
+          messageId: 'badName',
+        },
+      ],
+    },
+    {
+      code: 'import someclasses from "a.module.css";',
+      options: [{enforceName: '(?:^classes$|Classes$)'}],
+      errors: [
+        {
+          messageId: 'badName',
+        },
+      ],
+    },
+    {
+      code: 'import {default as foobar} from "a.module.css";',
+      options: [{enforceName: '(?:^classes$|Classes$)'}],
+      errors: [
+        {
+          messageId: 'badName',
+        },
+      ],
+    },
+    {
+      code: 'import {default as someclasses} from "a.module.css";',
+      options: [{enforceName: '(?:^classes$|Classes$)'}],
+      errors: [
+        {
+          messageId: 'badName',
+        },
+      ],
+    },
+  ],
+})

src/rules/enforce-css-module-default-import.js

@@ -0,0 +1,62 @@
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    fixable: 'code',
+    schema: [
+      {
+        properties: {
+          enforceName: {
+            type: 'string',
+          },
+        },
+      },
+    ],
+    messages: {
+      badName: 'This default import should match {{enforceName}}',
+      notDefault: 'Class modules should only import the default object.',
+      noDefault: 'Class modules should always import default.',
+    },
+  },
+  create(context) {
+    const enforceName = new RegExp(context.options[0]?.enforceName || '.*')
+    return {
+      ['ImportDeclaration>Literal[value=/.module.css$/]']: function (node) {
+        node = node.parent
+        const defaultSpecifier = node.specifiers.find(spec => spec.type === 'ImportDefaultSpecifier')
+        const otherSpecifiers = node.specifiers.filter(spec => spec.type !== 'ImportDefaultSpecifier')
+        const asDefaultSpecifier = otherSpecifiers.find(spec => spec.imported?.name === 'default')
+        if (!node.specifiers.length) {
+          context.report({
+            node,
+            messageId: 'noDefault',
+          })
+        } else if (otherSpecifiers.length === 1 && asDefaultSpecifier) {
+          if (!enforceName.test(asDefaultSpecifier.local.name)) {
+            context.report({
+              node,
+              messageId: 'badName',
+              data: {enforceName},
+            })
+          }
+        } else if (otherSpecifiers.length) {
+          context.report({
+            node,
+            messageId: 'notDefault',
+          })
+        } else if (!defaultSpecifier) {
+          context.report({
+            node,
+            messageId: 'noDefault',
+          })
+        }
+        if (defaultSpecifier && !enforceName.test(defaultSpecifier.local.name)) {
+          context.report({
+            node,
+            messageId: 'badName',
+            data: {enforceName},
+          })
+        }
+      },
+    }
+  },
+}