@atlaskit/eslint-plugin-design-system 8.26.0 → 8.27.0

package/dist/es2019/rules/consistent-css-prop-usage/index.js

@@ -1,18 +1,23 @@
 // eslint-disable-next-line import/no-extraneous-dependencies
 
-import { getIdentifierInParentScope, isNodeOfType } from 'eslint-codemod-utils';
+import { getIdentifierInParentScope, insertAtStartOfFile, insertImportDeclaration, isNodeOfType } from 'eslint-codemod-utils';
+import estraverse from 'estraverse';
 import assign from 'lodash/assign';
+import { Import } from '../../ast-nodes';
 import { createLintRule } from '../utils/create-rule';
-// File-level tracking of styles hoisted from the cssOnTopOfModule/cssAtBottomOfModule fixers
+import { getFirstSupportedImport } from '../utils/get-first-supported-import';
+import { getModuleOfIdentifier } from '../utils/get-import-node-by-source';
+import { CSS_IN_JS_IMPORTS } from '../utils/is-supported-import';
+// File-level tracking of styles hoisted from the cssAtTopOfModule/cssAtBottomOfModule fixers
 let hoistedCss = [];
+const isDOMElementName = elementName => elementName.charAt(0) !== elementName.charAt(0).toUpperCase() && elementName.charAt(0) === elementName.charAt(0).toLowerCase();
 function isCssCallExpression(node, cssFunctions) {
   cssFunctions = [...cssFunctions, 'cssMap'];
   return !!(isNodeOfType(node, 'CallExpression') && node.callee && node.callee.type === 'Identifier' && cssFunctions.includes(node.callee.name) && node.arguments.length && node.arguments[0].type === 'ObjectExpression');
 }
 function findSpreadProperties(node) {
-  // @ts-ignore
   return node.properties.filter(property => property.type === 'SpreadElement' ||
-  // @ts-ignore
+  // @ts-expect-error
   property.type === 'ExperimentalSpreadProperty');
 }
 const getProgramNode = expression => {
@@ -22,9 +27,8 @@ const getProgramNode = expression => {
   return expression.parent;
 };
 
-// TODO: This can be optimised by implementing a fixer at the very end (Program:exit) and handling all validations at once
 /**
- * Generates the declarator string when fixing the cssOnTopOfModule/cssAtBottomOfModule cases.
+ * Generates the declarator string when fixing the cssAtTopOfModule/cssAtBottomOfModule cases.
  * When `styles` already exists, `styles_1, styles_2, ..., styles_X` are incrementally created for each unhoisted style.
  * The generated `styles` varibale declaration names must be manually modified to be more informative at the discretion of owning teams.
  */
@@ -54,7 +58,7 @@ const getDeclaratorString = context => {
   hoistedCss = [...hoistedCss, `${declaratorName}${count}`];
   return `${declaratorName}${count}`;
 };
-function analyzeIdentifier(context, sourceIdentifier, configuration) {
+function analyzeIdentifier(context, sourceIdentifier, configuration, cssAttributeName) {
   var _getIdentifierInParen, _getIdentifierInParen2;
   const scope = context.getScope();
   const [identifier] = (_getIdentifierInParen = (_getIdentifierInParen2 = getIdentifierInParentScope(scope, sourceIdentifier.name)) === null || _getIdentifierInParen2 === void 0 ? void 0 : _getIdentifierInParen2.identifiers) !== null && _getIdentifierInParen !== void 0 ? _getIdentifierInParen : [];
@@ -74,8 +78,11 @@ function analyzeIdentifier(context, sourceIdentifier, configuration) {
     // When variable is declared inside the component
     context.report({
       node: sourceIdentifier,
-      messageId: configuration.stylesPlacement === 'bottom' ? 'cssAtBottomOfModule' : 'cssOnTopOfModule',
+      messageId: configuration.stylesPlacement === 'bottom' ? 'cssAtBottomOfModule' : 'cssAtTopOfModule',
       fix: fixer => {
+        if (configuration.fixNamesOnly) {
+          return [];
+        }
         return fixCssNotInModuleScope(fixer, context, configuration, identifier);
       }
     });
@@ -83,10 +90,30 @@ function analyzeIdentifier(context, sourceIdentifier, configuration) {
   }
   if (identifier.parent && identifier.parent.init && !isCssCallExpression(identifier.parent.init, configuration.cssFunctions)) {
     // When variable value is not of type css({})
-    context.report({
-      node: identifier,
-      messageId: 'cssObjectTypeOnly'
-    });
+    const value = identifier.parent.init;
+    if (!value) {
+      return;
+    }
+    const valueExpression =
+    // @ts-expect-error remove once eslint types are switched to @typescript-eslint
+    value.type === 'TSAsExpression' ? value.expression : value;
+    if (['ObjectExpression', 'TemplateLiteral'].includes(valueExpression.type)) {
+      context.report({
+        node: identifier,
+        messageId: 'cssObjectTypeOnly',
+        fix: fixer => {
+          if (configuration.fixNamesOnly) {
+            return [];
+          }
+          return addCssFunctionCall(fixer, context, identifier.parent, configuration, cssAttributeName);
+        }
+      });
+    } else {
+      context.report({
+        node: identifier,
+        messageId: 'cssObjectTypeOnly'
+      });
+    }
     return;
   }
   const spreadProperties = isNodeOfType(identifier.parent.init, 'CallExpression') && findSpreadProperties(identifier.parent.init.arguments[0]);
@@ -102,12 +129,131 @@ function analyzeIdentifier(context, sourceIdentifier, configuration) {
 }
 
 /**
- * Fixer for the cssOnTopOfModule/cssAtBottomOfModule violation cases.
+ * Returns a fixer that adds `import { css } from 'import-source'` or
+ * `import { xcss } from 'import-source'` to the start of the file, depending
+ * on the value of cssAttributeName and importSource.
+ */
+const addImportSource = (context, fixer, configuration, cssAttributeName) => {
+  const importSource = cssAttributeName === 'xcss' ? configuration.xcssImportSource : configuration.cssImportSource;
+
+  // Add the `import { css } from 'my-css-in-js-library';` statement
+  const packageImport = getFirstSupportedImport(context, [importSource]);
+  if (packageImport) {
+    const addCssImport = Import.insertNamedSpecifiers(packageImport, [cssAttributeName], fixer);
+    if (addCssImport) {
+      return addCssImport;
+    }
+  } else {
+    return insertAtStartOfFile(fixer, `${insertImportDeclaration(importSource, [cssAttributeName])};\n`);
+  }
+};
+
+/**
+ * Returns a list of fixes that:
+ * - add the `css` or `xcss` function call around the current node.
+ * - add an import statement for the package from which `css` is imported
+ */
+const addCssFunctionCall = (fixer, context, node, configuration, cssAttributeName) => {
+  const fixes = [];
+  const sourceCode = context.getSourceCode();
+  if (node.type !== 'VariableDeclarator' || !node.init || !cssAttributeName) {
+    return [];
+  }
+  const compiledImportFix = addImportSource(context, fixer, configuration, cssAttributeName);
+  if (compiledImportFix) {
+    fixes.push(compiledImportFix);
+  }
+  const init = node.init;
+  const initString = sourceCode.getText(init);
+  if (node.init.type === 'TemplateLiteral') {
+    fixes.push(fixer.replaceText(init, `${cssAttributeName}${initString}`));
+  } else {
+    fixes.push(fixer.replaceText(init, `${cssAttributeName}(${initString})`));
+  }
+  return fixes;
+};
+
+/**
+ * Check if the expression has or potentially has a local variable
+ * (as opposed to an imported one), erring on the side ot "yes"
+ * when an expression is too complicated to analyse.
+ *
+ * This is useful because expressions containing local variables
+ * cannot be easily hoisted, whereas this is not a problem with imported
+ * variables.
+ *
+ * @param context Context of the rule.
+ * @param node Any node that is potentially hoistable.
+ * @returns Whether the node potentially has a local variable (and thus is not safe to hoist).
+ */
+const potentiallyHasLocalVariable = (context, node) => {
+  let hasPotentiallyLocalVariable = false;
+  const isImportedVariable = identifier => !!getModuleOfIdentifier(context.getSourceCode(), identifier);
+  estraverse.traverse(node, {
+    enter: function (node, _parent) {
+      if (isNodeOfType(node, 'SpreadElement') ||
+      // @ts-expect-error remove once we can be sure that no parser interprets
+      // the spread operator as ExperimentalSpreadProperty anymore
+      isNodeOfType(node, 'ExperimentalSpreadProperty')) {
+        // Spread elements could contain anything... so we don't bother.
+        //
+        // e.g. <div css={css({ ...(!height && { visibility: 'hidden' })} />
+        hasPotentiallyLocalVariable = true;
+        this.break();
+      }
+      if (!isNodeOfType(node, 'Property')) {
+        return;
+      }
+      switch (node.value.type) {
+        case 'Literal':
+          break;
+        case 'Identifier':
+          // e.g. css({ margin: myVariable })
+          if (!isImportedVariable(node.value.name)) {
+            hasPotentiallyLocalVariable = true;
+          }
+          this.break();
+          break;
+        case 'MemberExpression':
+          // e.g. css({ margin: props.color })
+          //      css({ margin: props.media.color })
+          if (node.value.object.type === 'Identifier' && isImportedVariable(node.value.object.name)) {
+            // We found an imported variable, don't do anything.
+          } else {
+            // e.g. css({ margin: [some complicated expression].media.color })
+            // This can potentially get too complex, so we assume there's a local
+            // variable in there somewhere.
+            hasPotentiallyLocalVariable = true;
+          }
+          this.break();
+          break;
+        case 'TemplateLiteral':
+          if (!!node.value.expressions.length) {
+            // Too many edge cases here, don't bother...
+            // e.g. css({ animation: `${expandStyles(right, rightExpanded, isExpanded)} 0.2s ease-in-out` });
+            hasPotentiallyLocalVariable = true;
+            this.break();
+          }
+          break;
+        default:
+          // Catch-all for values such as "A && B", "A ? B : C"
+          hasPotentiallyLocalVariable = true;
+          this.break();
+          break;
+      }
+    }
+  });
+  return hasPotentiallyLocalVariable;
+};
+
+/**
+ * Fixer for the cssAtTopOfModule/cssAtBottomOfModule violation cases.
  * This deals with Identifiers and Expressions passed from the traverseExpressionWithConfig() function.
+ *
  * @param fixer The ESLint RuleFixer object
- * @param context The context of the node
+ * @param context The context of the rule
  * @param configuration The configuration of the rule, determining whether the fix is implmeneted at the top or bottom of the module
- * @param node Either an IdentifierWithParent node. Expression, or SpreadElement that we handle
+ * @param node Any potentially hoistable node, or an identifier.
  * @param cssAttributeName An optional parameter only added when we fix an ObjectExpression
  */
 const fixCssNotInModuleScope = (fixer, context, configuration, node, cssAttributeName) => {
@@ -124,35 +270,42 @@ const fixCssNotInModuleScope = (fixer, context, configuration, node, cssAttribut
     fixerNodePlacement = programNode.body.length === 1 ? programNode.body[0] : programNode.body.find(node => node.type !== 'ImportDeclaration');
   }
   let moduleString;
-  let implementFixer = [];
+  let fixes = [];
   if (node.type === 'Identifier') {
     const identifier = node;
     const declarator = identifier.parent.parent;
     moduleString = sourceCode.getText(declarator);
-    implementFixer.push(fixer.remove(declarator));
+    fixes.push(fixer.remove(declarator));
   } else {
+    if (potentiallyHasLocalVariable(context, node)) {
+      return [];
+    }
     const declarator = getDeclaratorString(context);
     const text = sourceCode.getText(node);
 
     // If this has been passed, then we know it's an ObjectExpression
     if (cssAttributeName) {
       moduleString = `const ${declarator} = ${cssAttributeName}(${text});`;
+      const compiledImportFix = addImportSource(context, fixer, configuration, cssAttributeName);
+      if (compiledImportFix) {
+        fixes.push(compiledImportFix);
+      }
     } else {
-      moduleString = moduleString = `const ${declarator} = ${text};`;
+      moduleString = `const ${declarator} = ${text};`;
     }
-    implementFixer.push(fixer.replaceText(node, declarator));
+    fixes.push(fixer.replaceText(node, declarator));
   }
-  return [...implementFixer,
-  // Insert the node either before or after
+  return [...fixes,
+  // Insert the node either before or after, depending on the rule configuration
   configuration.stylesPlacement === 'bottom' ? fixer.insertTextAfter(fixerNodePlacement, '\n' + moduleString) : fixer.insertTextBefore(fixerNodePlacement, moduleString + '\n')];
 };
 
 /**
  * Handle different cases based on what's been passed in the css-related JSXAttribute
- * @param context the context of the node
+ * @param context the context of the rule
  * @param expression the expression of the JSXAttribute value
  * @param configuration what css-related functions to account for (eg. css, xcss, cssMap), and whether to detect bottom vs top expressions
- * @param cssAttributeName used to encapsulate ObjectExpressions when cssOnTopOfModule/cssAtBottomOfModule violations are triggered
+ * @param cssAttributeName used to encapsulate ObjectExpressions when cssAtTopOfModule/cssAtBottomOfModule violations are triggered
  */
 const traverseExpressionWithConfig = (context, expression, configuration, cssAttributeName) => {
   function traverseExpression(expression) {
@@ -160,7 +313,7 @@ const traverseExpressionWithConfig = (context, expression, configuration, cssAtt
       case 'Identifier':
         // {styles}
         // We've found an identifier - time to analyze it!
-        analyzeIdentifier(context, expression, configuration);
+        analyzeIdentifier(context, expression, configuration, cssAttributeName);
         break;
       case 'ArrayExpression':
         // {[styles, moreStyles]}
@@ -187,8 +340,12 @@ const traverseExpressionWithConfig = (context, expression, configuration, cssAtt
         // We've found elements that shouldn't be here! Report an error.
         context.report({
           node: expression,
-          messageId: configuration.stylesPlacement === 'bottom' ? 'cssAtBottomOfModule' : 'cssOnTopOfModule',
+          messageId: configuration.stylesPlacement === 'bottom' ? 'cssAtBottomOfModule' : 'cssAtTopOfModule',
           fix: fixer => {
+            if (configuration.fixNamesOnly) {
+              return [];
+            }
+
             // Don't fix CallExpressions unless they're from cssFunctions or cssMap
             if (expression.type === 'CallExpression' && !isCssCallExpression(expression, configuration.cssFunctions)) {
               return [];
@@ -200,6 +357,17 @@ const traverseExpressionWithConfig = (context, expression, configuration, cssAtt
           }
         });
         break;
+
+      // @ts-expect-error - our ESLint-related types assume vanilla JS, when in fact
+      // it is running @typescript-eslint
+      //
+      // Switching to the more accurate @typescript-eslint types would break
+      // eslint-codemod-utils and all ESLint rules in packages/design-system,
+      // so we just leave this as-is.
+      case 'TSAsExpression':
+        // @ts-expect-error
+        traverseExpression(expression.expression);
+        break;
       default:
         // Do nothing!
         break;
@@ -209,10 +377,15 @@ const traverseExpressionWithConfig = (context, expression, configuration, cssAtt
 };
 const defaultConfig = {
   cssFunctions: ['css', 'xcss'],
-  stylesPlacement: 'top'
+  stylesPlacement: 'top',
+  cssImportSource: CSS_IN_JS_IMPORTS.compiled,
+  xcssImportSource: CSS_IN_JS_IMPORTS.atlaskitPrimitives,
+  excludeReactComponents: false,
+  fixNamesOnly: false
 };
 const rule = createLintRule({
   meta: {
+    type: 'problem',
     name: 'consistent-css-prop-usage',
     docs: {
       description: 'Ensures consistency with `css` and `xcss` prop usages',
@@ -222,13 +395,42 @@ const rule = createLintRule({
     },
     fixable: 'code',
     messages: {
-      cssOnTopOfModule: `Create styles at the top of the module scope using the respective css function.`,
+      cssAtTopOfModule: `Create styles at the top of the module scope using the respective css function.`,
       cssAtBottomOfModule: `Create styles at the bottom of the module scope using the respective css function.`,
-      cssObjectTypeOnly: `Create styles using objects passed to the css function.`,
-      cssInModule: `Imported styles should not be used, instead define in the module, import a component, or use a design token.`,
+      cssObjectTypeOnly: `Create styles using objects passed to a css function call, e.g. \`css({ textAlign: 'center'; })\`.`,
+      cssInModule: `Imported styles should not be used; instead define in the module, import a component, or use a design token.`,
       cssArrayStylesOnly: `Compose styles with an array on the css prop instead of using object spread.`,
+      noMemberExpressions: `Styles should be a regular variable (e.g. 'buttonStyles'), not a member of an object (e.g. 'myObject.styles').`,
       shouldEndInStyles: 'Declared styles should end in "styles".'
-    }
+    },
+    schema: [{
+      type: 'object',
+      properties: {
+        cssFunctions: {
+          type: 'array',
+          items: [{
+            type: 'string'
+          }]
+        },
+        stylesPlacement: {
+          type: 'string',
+          enum: ['top', 'bottom']
+        },
+        cssImportSource: {
+          type: 'string'
+        },
+        xcssImportSource: {
+          type: 'string'
+        },
+        excludeReactComponents: {
+          type: 'boolean'
+        },
+        fixNamesOnly: {
+          type: 'boolean'
+        }
+      },
+      additionalProperties: false
+    }]
   },
   create(context) {
     const mergedConfig = assign({}, defaultConfig, context.options[0]);
@@ -265,11 +467,22 @@ const rule = createLintRule({
           }
         });
       },
-      JSXAttribute(node) {
+      JSXAttribute(nodeOriginal) {
+        const node = nodeOriginal;
         const {
           name,
           value
         } = node;
+        if (mergedConfig.excludeReactComponents && node.parent.type === 'JSXOpeningElement') {
+          // e.g. <item.before />
+          if (node.parent.name.type === 'JSXMemberExpression') {
+            return;
+          }
+          // e.g. <div />, <MenuItem />
+          if (node.parent.name.type === 'JSXIdentifier' && !isDOMElementName(node.parent.name.name)) {
+            return;
+          }
+        }
 
         // Always reset to empty array
         hoistedCss = [];
@@ -277,11 +490,16 @@ const rule = createLintRule({
           // When not a jsx expression. For eg. css=""
           if ((value === null || value === void 0 ? void 0 : value.type) !== 'JSXExpressionContainer') {
             context.report({
-              node: value,
-              messageId: mergedConfig.stylesPlacement === 'bottom' ? 'cssAtBottomOfModule' : 'cssOnTopOfModule'
+              node,
+              messageId: mergedConfig.stylesPlacement === 'bottom' ? 'cssAtBottomOfModule' : 'cssAtTopOfModule'
             });
             return;
           }
+          if (value.expression.type === 'JSXEmptyExpression') {
+            // e.g. the comment in
+            //      <div css={/* Hello there */} />
+            return;
+          }
           traverseExpressionWithConfig(context, value.expression, mergedConfig, name.name);
         }
       }

package/dist/es2019/rules/utils/create-no-exported-rule/is-styled-component.js

@@ -1,4 +1,4 @@
-import { isNodeOfType } from 'eslint-codemod-utils';
+import { getFirstSupportedImport } from '../get-first-supported-import';
 /**
  * Given a list of node, find and return the callee of the first Compiled or styled-components `styled` function call found in the list.
  *
@@ -40,13 +40,9 @@ const findNode = nodes => {
  * @returns The local name used to import the `styled` API.
  */
 const getStyledImportSpecifierName = (context, importSources) => {
-  var _supportedImports$0$s;
-  const isSupportedImport = node => {
-    return isNodeOfType(node, 'ImportDeclaration') && typeof node.source.value === 'string' && importSources.includes(node.source.value);
-  };
-  const source = context.getSourceCode();
-  const supportedImports = source.ast.body.filter(isSupportedImport);
-  return (_supportedImports$0$s = supportedImports[0].specifiers.find(spec => spec.type === 'ImportSpecifier' && spec.imported.name === 'styled')) === null || _supportedImports$0$s === void 0 ? void 0 : _supportedImports$0$s.local.name;
+  var _supportedImport$spec;
+  const supportedImport = getFirstSupportedImport(context, importSources);
+  return supportedImport === null || supportedImport === void 0 ? void 0 : (_supportedImport$spec = supportedImport.specifiers.find(spec => spec.type === 'ImportSpecifier' && spec.imported.name === 'styled' || spec.type === 'ImportDefaultSpecifier' && spec.local.name === 'styled')) === null || _supportedImport$spec === void 0 ? void 0 : _supportedImport$spec.local.name;
 };
 
 /**

package/dist/es2019/rules/utils/get-first-supported-import.js

@@ -0,0 +1,22 @@
+import { isNodeOfType } from 'eslint-codemod-utils';
+/**
+ * Get the first import declaration in the file that matches any of the packages
+ * in `importSources`.
+ *
+ * @param context Rule context.
+ * @param importSources The packages to check import statements for. If importSources
+ *                      contains more than one package, the first import statement
+ *                      detected in the file that matches any of the packages will be
+ *                      returned.
+ * @returns The first import declaration found in the file.
+ */
+export const getFirstSupportedImport = (context, importSources) => {
+  const isSupportedImport = node => {
+    return isNodeOfType(node, 'ImportDeclaration') && typeof node.source.value === 'string' && importSources.includes(node.source.value);
+  };
+  const source = context.getSourceCode();
+  const supportedImports = source.ast.body.filter(isSupportedImport);
+  if (supportedImports.length) {
+    return supportedImports[0];
+  }
+};

package/dist/es2019/rules/utils/is-supported-import.js

@@ -5,7 +5,8 @@ export const CSS_IN_JS_IMPORTS = {
   emotionReact: '@emotion/react',
   emotionCore: '@emotion/core',
   styledComponents: 'styled-components',
-  atlaskitCss: '@atlaskit/css'
+  atlaskitCss: '@atlaskit/css',
+  atlaskitPrimitives: '@atlaskit/primitives'
 };
 
 // A CSS-in-JS library an import of a valid css, cx, cssMap, etc.