XCSS prop local cx lint (#1548)

* chore: init

* chore: add to configs

* feat: add local-cx-xcss rule

* chore: changeset

* chore: fix

* chore: fix readme

* chore: now

* chore: fix incorrect names

* chore: resolve code review comments

* chore: fix white space

Author: itsdouges

.changeset/light-shirts-destroy.md

@@ -0,0 +1,5 @@
+---
+'@compiled/eslint-plugin': patch
+---
+
+Add supplementary lint rule for xcss prop `local-cx-xcss`.

packages/eslint-plugin/src/configs/recommended.ts

@@ -1,6 +1,7 @@
 export const recommended = {
   plugins: ['@compiled'],
   rules: {
+    '@compiled/local-cx-xcss': 'error',
     '@compiled/no-css-prop-without-css-function': 'error',
     '@compiled/no-css-tagged-template-expression': 'error',
     '@compiled/no-exported-css': 'error',

packages/eslint-plugin/src/index.ts

@@ -1,5 +1,6 @@
 import { recommended } from './configs/recommended';
 import { jsxPragmaRule } from './rules/jsx-pragma';
+import { localCXXCSSRule } from './rules/local-cx-xcss';
 import { noCssPropWithoutCssFunctionRule } from './rules/no-css-prop-without-css-function';
 import { noCssTaggedTemplateExpressionRule } from './rules/no-css-tagged-template-expression';
 import { noEmotionCssRule } from './rules/no-emotion-css';
@@ -13,6 +14,7 @@ import { noSuppressXCSS } from './rules/no-suppress-xcss';
 
 export const rules = {
   'jsx-pragma': jsxPragmaRule,
+  'local-cx-xcss': localCXXCSSRule,
   'no-css-prop-without-css-function': noCssPropWithoutCssFunctionRule,
   'no-css-tagged-template-expression': noCssTaggedTemplateExpressionRule,
   'no-emotion-css': noEmotionCssRule,

packages/eslint-plugin/src/rules/local-cx-xcss/README.md

@@ -0,0 +1,31 @@
+# `local-cx-xcss`
+
+This rule ensures the `cx()` function is only used within the `xcss` prop. This aids tracking what styles are applied to a jsx element.
+
+👎 Examples of **incorrect** code for this rule:
+
+```js
+import { cx, cssMap } from '@compiled/react';
+
+const styles = cssMap({
+  text: { color: 'red' },
+  bg: { background: 'blue' },
+});
+
+const joinedStyles = cx(styles.text, styles.bg);
+
+<Button xcss={joinedStyles} />;
+```
+
+👍 Examples of **correct** code for this rule:
+
+```js
+import { cx, cssMap } from '@compiled/react';
+
+const styles = cssMap({
+  text: { color: 'red' },
+  bg: { background: 'blue' },
+});
+
+<Button xcss={cx(styles.text, styles.bg)} />;
+```

packages/eslint-plugin/src/rules/local-cx-xcss/__tests__/rule.test.ts

@@ -0,0 +1,94 @@
+import { typeScriptTester as tester } from '../../../test-utils';
+import { localCXXCSSRule } from '../index';
+
+tester.run('local-cx-xcss', localCXXCSSRule, {
+  valid: [
+    `
+      import { cx } from '@compiled/react';
+
+      <Component xcss={cx({})} />
+    `,
+    `
+      import { cx } from '@compiled/react';
+
+      <Component innerXcss={cx({})} />
+    `,
+    `
+      import { cx, cssMap } from '@compiled/react';
+
+      const styles = cssMap({
+        text: { color: 'red' },
+        bg: { background: 'blue' },
+      });
+
+      <Button innerXcss={cx(styles.text, styles.bg)} />;
+    `,
+    `
+      // Ignore cx usage not from compiled
+      const styles = cssMap({
+        text: { color: 'red' },
+        bg: { background: 'blue' },
+      });
+
+      const joinedStyles = cx(styles.text, styles.bg);
+
+      <Button xcss={joinedStyles} />;
+    `,
+    `
+      // Ignore cx usage not from compiled
+      const styles = cx({});
+
+      <Component xcss={styles} />
+    `,
+  ],
+  invalid: [
+    {
+      code: `
+      import { cx } from '@compiled/react';
+      const styles = cx({});
+
+      <Component xcss={styles} />
+    `,
+      errors: [{ messageId: 'local-cx-xcss' }],
+    },
+    {
+      code: `
+      import { cx, cssMap } from '@compiled/react';
+
+      const styles = cssMap({
+        text: { color: 'red' },
+        bg: { background: 'blue' },
+      });
+
+      const joinedStyles = cx(styles.text, styles.bg);
+
+      <Button xcss={joinedStyles} />;
+    `,
+      errors: [{ messageId: 'local-cx-xcss' }],
+    },
+    {
+      code: `
+      import { cx } from '@compiled/react';
+      const styles = cx({});
+
+      <Component innerXcss={styles} />
+    `,
+      errors: [{ messageId: 'local-cx-xcss' }],
+    },
+    {
+      code: `
+      import { cx, cssMap} from '@compiled/react';
+
+      const styles = cssMap({
+        text: { color: 'red' },
+        bg: { background: 'blue' },
+      });
+
+      const joinedStyles = cx(styles.text, styles.bg);
+
+      <Button innerXcss={joinedStyles} />;
+    `,
+      errors: [{ messageId: 'local-cx-xcss' }],
+    },
+  ],
+});

packages/eslint-plugin/src/rules/local-cx-xcss/index.ts

@@ -0,0 +1,53 @@
+import type { Rule } from 'eslint';
+
+import { isCxFunction } from '../../utils';
+
+function getParentJSXAttribute(node: Rule.Node) {
+  let parent: Rule.Node | null = node.parent;
+
+  while (parent && parent.type !== 'JSXAttribute') {
+    parent = parent.parent;
+  }
+
+  if (parent && parent.type === 'JSXAttribute') {
+    return parent;
+  }
+
+  return null;
+}
+
+export const localCXXCSSRule: Rule.RuleModule = {
+  meta: {
+    docs: {
+      recommended: true,
+      url: 'https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin/src/rules/local-cx-xcss',
+    },
+    messages: {
+      'local-cx-xcss':
+        'The cx function should only be declared inside the xcss prop to simplify tracking styles that are applied to a jsx element',
+    },
+    type: 'problem',
+  },
+  create(context) {
+    return {
+      'CallExpression[callee.name="cx"]': (node: Rule.Node) => {
+        if (
+          node.type === 'CallExpression' &&
+          isCxFunction(node.callee as Rule.Node, context.getScope().references)
+        ) {
+          const parentJSXAttribute = getParentJSXAttribute(node);
+          const propName = parentJSXAttribute?.name.name.toString();
+
+          if (propName && /[xX]css$/.exec(propName)) {
+            return;
+          }
+
+          context.report({
+            node,
+            messageId: 'local-cx-xcss',
+          });
+        }
+      },
+    };
+  },
+};

packages/eslint-plugin/src/utils/index.ts

@@ -2,4 +2,4 @@ export { createNoExportedRule } from './create-no-exported-rule';
 export { checkIfCompiledExport as validateDefinition } from './create-no-exported-rule/check-if-compiled-export';
 export { createNoTaggedTemplateExpressionRule } from './create-no-tagged-template-expression-rule';
 export { CssMapObjectChecker, getCssMapObject } from './css-map';
-export { isCss, isCssMap, isKeyframes } from './is-compiled-import';
+export { isCss, isCssMap, isKeyframes, isCxFunction } from './is-compiled-import';

packages/eslint-plugin/src/utils/is-compiled-import.ts

@@ -28,5 +28,6 @@ const isCompiledImport = (name: string): CompiledNameChecker => {
 };
 
 export const isCss = isCompiledImport('css');
+export const isCxFunction = isCompiledImport('cx');
 export const isCssMap = isCompiledImport('cssMap');
 export const isKeyframes = isCompiledImport('keyframes');

packages/react/src/css-map/index.ts

@@ -91,11 +91,12 @@ type ExtendedSelectors = {
  *
  * @example
  * ```
- * const borderStyleMap = cssMap({
+ * const styles = cssMap({
  *  none: { borderStyle: 'none' },
  *  solid: { borderStyle: 'solid' },
  * });
- * const Component = ({ borderStyle }) => <div css={css(borderStyleMap[borderStyle])} />
+ *
+ * const Component = ({ borderStyle }) => <div css={styles[borderStyle]} />
  *
  * <Component borderStyle="solid" />
  * ```