@gitlab/eslint-plugin 20.0.0 → 20.2.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [20.2.0](https://gitlab.com/gitlab-org/frontend/eslint-plugin/compare/v20.1.0...v20.2.0) (2024-09-03)
+
+
+### Features
+
+* add rule for uninitialised apollo query properties ([f89eace](https://gitlab.com/gitlab-org/frontend/eslint-plugin/commit/f89eace7498900d90e06b0be214c51a589474d53)), closes [#74](https://gitlab.com/gitlab-org/frontend/eslint-plugin/issues/74)
+
+# [20.1.0](https://gitlab.com/gitlab-org/frontend/eslint-plugin/compare/v20.0.0...v20.1.0) (2024-08-28)
+
+
+### Features
+
+* add rules to ensure Tailwind CSS is used properly ([c51533e](https://gitlab.com/gitlab-org/frontend/eslint-plugin/commit/c51533ecfa9f20f76d0b2a3113da7213213658f6))
+
 # [20.0.0](https://gitlab.com/gitlab-org/frontend/eslint-plugin/compare/v19.6.1...v20.0.0) (2024-08-13)
 
 

package/docs/rules/tailwind.md

@@ -0,0 +1,38 @@
+# @gitlab/tailwind
+
+This rule lints against string interpolation being used to build CSS utility class
+names as that would prevent Tailwind from parsing those classes and adding them to the bundle.
+
+## Rule Details
+
+### Examples of **incorrect** code for this rule
+
+```js
+// Using interpolation to build a utility in a string literal
+const cssUtilsStringLiteral = 'gl-bg-red-' + variant;
+
+// Using interpolation to build a utility in a template literal
+const cssUtilsTemplateLiteral = `gl-border-top gl-bg-red-${color} gl-text-gray-400`;
+```
+
+### Examples of **correct** code for this rule
+
+```js
+// Utilities declared as a string literal without interpolation
+const cssUtilsStringLiteral = 'gl-bg-red-800';
+
+// Utilities declared as a template literal without interpolation
+const cssUtils = `gl-border-top gl-bg-red-800 gl-text-gray-400`;
+```
+
+## Options
+
+No options.
+
+## Related rules
+
+- [vue-tailwind](./vue-tailwind.md)
+
+## When Not To Use It
+
+If the codebase doesn't leverage Tailwind CSS, keep this rule disabled.

package/docs/rules/vue-no-undef-apollo-properties.md

@@ -0,0 +1,95 @@
+# @gitlab/vue-no-undef-apollo-properties
+
+Require Apollo query properties to be initialized in component data.
+
+Sensible initial values for Apollo queries should be defined in component data.
+This reduces the likelihood of unexpected behaviour, especially when running
+under @vue/compat.
+
+This rule does not detect whether the initial value is of the correct type.
+
+## Rule Details
+
+### Examples of **incorrect** code for this rule
+
+```html
+<script>
+  export default {
+    data() {
+      return {
+        foo: '',
+        qux: undefined,
+      };
+    },
+    apollo: {
+      $subscribe: {
+        foo: {
+          // ...
+        },
+        bar: {
+          // This isn't defined in data.
+          // ...
+        },
+      },
+      qux: {
+        // ...
+      },
+      bbq: {
+        // This isn't defined in data.
+        // ...
+      },
+    },
+    render(h) {
+      return h();
+    },
+  };
+</script>
+```
+
+### Examples of **correct** code for this rule
+
+```html
+<script>
+  export default {
+    data() {
+      return {
+        foo: '',
+        qux: undefined,
+        bar: null,
+        bbq: [],
+      };
+    },
+    apollo: {
+      $subscribe: {
+        foo: {
+          // ...
+        },
+        bar: {
+          // ...
+        },
+      },
+      qux: {
+        // ...
+      },
+      bbq: {
+        // ...
+      },
+    },
+    render(h) {
+      return h();
+    },
+  };
+</script>
+```
+
+## Options
+
+Nothing
+
+## Related rules
+
+Nothing
+
+## When Not To Use It
+
+If you don't use VueApollo with the Options API, don't use this rule.

package/docs/rules/vue-tailwind.md

@@ -0,0 +1,45 @@
+# @gitlab/vue-tailwind
+
+This rule enforces the same conventions as [tailwind](./tailwind.md) in Vue templates.
+
+## Rule Details
+
+### Examples of **incorrect** code for this rule
+
+```html
+<!-- Using interpolation to build a utility in a string literal -->
+<template>
+  <span :class="'gl-bg-red-' + color"></span>
+</template>
+
+<!-- Using interpolation to build a utility in a template literal -->
+<template>
+  <span :class="`gl-border-top gl-bg-red-${color} gl-text-gray-400`"></span>
+</template>
+  ```
+
+### Examples of **correct** code for this rule
+
+```html
+<!-- Utilities declared as a string literal without interpolation -->
+<template>
+  <span class="gl-bg-red-800"></span>
+</template>
+
+<!-- Utilities declared as a template literal without interpolation -->
+<template>
+  <span :class="`gl-bg-red-800`"></span>
+</template>
+```
+
+## Options
+
+No options.
+
+## Related rules
+
+- [tailwind](./tailwind.md)
+
+## When Not To Use It
+
+If the codebase doesn't leverage Tailwind CSS, keep this rule disabled.

package/docs/rules.md

@@ -8,13 +8,16 @@ Available rules:
 - [no-runtime-template-compiler](./rules/no-runtime-template-compiler.md): Disallow components which rely on a runtime template compiler.
 - [require-i18n-strings](./rules/require-i18n-strings.md): Detect a string which has been hard coded and requires externalization.
 - [require-valid-i18n-helpers](./rules/require-valid-i18n-helpers.md): Enforces valid usage of translation helpers in JavaScript.
+- [tailwind](./rules/tailwind.md): Ensures Tailwind CSS is used according to our internal guidelines.
 - [vtu-no-explicit-wrapper-destroy](./rules/vtu-no-explicit-wrapper-destroy.md): Prevents redundant destroy calls and null asignment
 - [vtu-no-wrapper-vm](./rules/vtu-no-wrapper-vm.md): Prevent direct access to `vm` internals for `@vue/test-utils` wrappers.
 - [vue-no-data-toggle](./rules/vue-no-data-toggle.md): Restrict the use of `data-toggle` bootstrap behaviors within Vue templates
 - [vue-no-new-non-primitive-in-template](./rules/vue-no-new-non-primitive-in-template.md): Prevents non-primitive values from being declared in templates
+- [vue-no-undef-apollo-properties](./rules/vue-no-undef-apollo-properties.md): Require Apollo query properties to be initialized in component data.
 - [vue-prefer-dollar-scopedslots](./rules/vue-prefer-dollar-scopedslots.md): Prefer $scopedSlots over $slots for Vue 2.x.
 - [vue-require-i18n-attribute-strings](./rules/vue-require-i18n-attribute-strings.md): Detect non externalized strings in vue `<template>` attributes
 - [vue-require-i18n-strings](./rules/vue-require-i18n-strings.md): enforce no bare strings in vue `<template>`
 - [vue-require-required-key](./rules/vue-require-required-key.md): Require the required key to be set
 - [vue-require-valid-i18n-helpers](./rules/vue-require-valid-i18n-helpers.md): Enforces valid usage of translation helpers in Vue templates.
 - [vue-slot-name-casing](./rules/vue-slot-name-casing.md): enforce specific casing for slot naming style in template
+- [vue-tailwind](./rules/vue-tailwind.md): Ensures Tailwind CSS is used according to our internal guidelines in Vue templates.

package/lib/configs/base.js

@@ -89,6 +89,7 @@ module.exports = {
         groups: ['builtin', 'external', 'internal', 'parent', 'sibling', 'index'],
       },
     ],
+    // https://docs.gitlab.com/ee/development/fe_guide/style/javascript.html#limit-number-of-parameters
     'max-params': ['error', { max: 3 }]
   },
 };

package/lib/configs/typescript.js

@@ -37,6 +37,7 @@ const tsConfig = {
       reportUnusedDisableDirectives: true,
       rules: {
         semi: [2, 'always'],
+        'max-params': 'off',
         'no-throw-literal': 'off',
         'no-shadow': 'off',
         'no-empty-function': 'off',

package/lib/index.js

@@ -7,23 +7,26 @@ module.exports = {
     'no-runtime-template-compiler': require('./rules/no-runtime-template-compiler.js'),
     'require-i18n-strings': require('./rules/require-i18n-strings.js'),
     'require-valid-i18n-helpers': require('./rules/require-valid-i18n-helpers.js'),
+    tailwind: require('./rules/tailwind.js'),
     'vtu-no-explicit-wrapper-destroy': require('./rules/vtu-no-explicit-wrapper-destroy.js'),
     'vtu-no-wrapper-vm': require('./rules/vtu-no-wrapper-vm.js'),
     'vue-no-data-toggle': require('./rules/vue-no-data-toggle.js'),
     'vue-no-new-non-primitive-in-template': require('./rules/vue-no-new-non-primitive-in-template.js'),
+    'vue-no-undef-apollo-properties': require('./rules/vue-no-undef-apollo-properties.js'),
     'vue-prefer-dollar-scopedslots': require('./rules/vue-prefer-dollar-scopedslots.js'),
     'vue-require-i18n-attribute-strings': require('./rules/vue-require-i18n-attribute-strings.js'),
     'vue-require-i18n-strings': require('./rules/vue-require-i18n-strings.js'),
     'vue-require-required-key': require('./rules/vue-require-required-key.js'),
     'vue-require-valid-i18n-helpers': require('./rules/vue-require-valid-i18n-helpers.js'),
     'vue-slot-name-casing': require('./rules/vue-slot-name-casing.js'),
+    'vue-tailwind': require('./rules/vue-tailwind.js'),
   },
   configs: {
-    default: require('./configs/default.js'),
-    typescript: require('./configs/typescript.js'),
     base: require('./configs/base.js'),
-    vue: require('./configs/vue.js'),
+    default: require('./configs/default.js'),
     i18n: require('./configs/i18n.js'),
     jest: require('./configs/jest.js'),
+    typescript: require('./configs/typescript.js'),
+    vue: require('./configs/vue.js'),
   },
 };

package/lib/rules/tailwind.js

@@ -0,0 +1,30 @@
+// ------------------------------------------------------------------------------
+// Requirements
+// ------------------------------------------------------------------------------
+const { DOCS_BASE_URL } = require('../constants');
+const { validateInterpolatedUtils } = require('../utils/tailwind-utils');
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+module.exports = {
+  meta: {
+    type: 'error',
+    docs: {
+      description: 'Ensures Tailwind CSS is used according to our internal guidelines.',
+      category: 'css',
+      url: DOCS_BASE_URL + '/tailwind.md',
+    },
+  },
+  create(context) {
+    return {
+      BinaryExpression(node) {
+        validateInterpolatedUtils(context, node);
+      },
+      TemplateLiteral(node) {
+        validateInterpolatedUtils(context, node);
+      },
+    };
+  },
+};

package/lib/rules/vue-no-undef-apollo-properties.js

@@ -0,0 +1,102 @@
+// ------------------------------------------------------------------------------
+// Requirements
+// ------------------------------------------------------------------------------
+const { DOCS_BASE_URL } = require('../constants');
+const utils = require('eslint-plugin-vue/lib/utils');
+
+// ------------------------------------------------------------------------------
+//   Helpers
+// ------------------------------------------------------------------------------
+
+const DOLLAR_SUBSCRIBE = '$subscribe';
+
+const VUE_APOLLO_SPECIAL_OPTIONS = new Set([
+  '$skipAll',
+  '$skipAllQueries',
+  '$skipAllSubscriptions',
+  '$deep',
+  '$error',
+  '$query',
+
+  // This one isn't special in the same way as the rest, but the normal code
+  // paths below need to be skipped for this case as well. It is handled in a
+  // separate code path.
+  DOLLAR_SUBSCRIBE,
+]);
+
+function findProperty(objectExpression, name) {
+  return objectExpression.properties.find(
+    (p) =>
+      p.type === 'Property' &&
+      utils.getStaticPropertyName(p) === name &&
+      p.value.type === 'ObjectExpression',
+  );
+}
+
+function getDataKeys(componentObject) {
+  return new Set(
+    Array.from(utils.iterateProperties(componentObject, new Set(['data']))).map(({ name }) => name),
+  );
+}
+
+function* getApolloKeyNodeWrappers(componentObject) {
+  const apolloNode = findProperty(componentObject, 'apollo');
+
+  if (!apolloNode) return;
+
+  for (const nodeWrapper of utils.iterateObjectExpression(apolloNode.value)) {
+    if (VUE_APOLLO_SPECIAL_OPTIONS.has(nodeWrapper.name)) {
+      // Future-proofing against VueApollo 4's special options:
+      // https://apollo.vuejs.org/guide-option/special-options.html#special-options
+      continue;
+    }
+
+    yield nodeWrapper;
+  }
+
+  const subscribeNode = findProperty(apolloNode.value, DOLLAR_SUBSCRIBE);
+
+  if (subscribeNode) {
+    yield* utils.iterateObjectExpression(subscribeNode.value);
+  }
+}
+
+function* getApolloKeyNodes(componentObject) {
+  for (const nodeWrapper of getApolloKeyNodeWrappers(componentObject)) {
+    yield nodeWrapper.node;
+  }
+}
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+module.exports = {
+  meta: {
+    type: 'error',
+    docs: {
+      description: 'Require Apollo query properties to be initialized in component data.',
+      url: DOCS_BASE_URL + '/vue-no-undef-apollo-properties.md',
+    },
+    messages: {
+      noInitialValue: 'Apollo query property {{name}} is not initialized in component data.',
+    },
+  },
+  create(context) {
+    return utils.executeOnVue(context, (node) => {
+      const dataKeys = getDataKeys(node);
+
+      for (const apolloKeyNode of getApolloKeyNodes(node)) {
+        if (!dataKeys.has(apolloKeyNode.name)) {
+          context.report({
+            node: apolloKeyNode,
+            messageId: 'noInitialValue',
+            data: {
+              name: apolloKeyNode.name,
+            },
+          });
+        }
+      }
+    });
+  },
+};

package/lib/rules/vue-tailwind.js

@@ -0,0 +1,32 @@
+
+// ------------------------------------------------------------------------------
+// Requirements
+// ------------------------------------------------------------------------------
+const { DOCS_BASE_URL } = require('../constants');
+const { defineTemplateBodyVisitor } = require('../utils/index');
+const { validateInterpolatedUtils } = require('../utils/tailwind-utils');
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+module.exports = {
+  meta: {
+    type: 'error',
+    docs: {
+      description: 'Ensures Tailwind CSS is used according to our internal guidelines in Vue templates.',
+      category: 'css',
+      url: DOCS_BASE_URL + '/vue-tailwind.md',
+    },
+  },
+  create(context) {
+    return defineTemplateBodyVisitor(context, {
+      BinaryExpression(node) {
+        validateInterpolatedUtils(context, node)
+      },
+      TemplateLiteral(node) {
+        validateInterpolatedUtils(context, node)
+      },
+    });
+  },
+};

package/lib/utils/tailwind-utils.js

@@ -0,0 +1,35 @@
+const INTERPOLATION_PATTERN = /gl-[a-z0-9-]*$/i;
+const INTERPOLATED_UTIL_ERROR =
+  'You are building a CSS utility class name using string interpolation which is forbidden because Tailwind CSS needs fully qualified names to properly generate the utilities we use.';
+const INTERPOLATED_UTILS_VALIDATORS = {
+  BinaryExpression: binaryExpressionHasInterpolatedUtils,
+  TemplateLiteral: templateLiteralHasInterpolatedUtils,
+};
+
+function binaryExpressionHasInterpolatedUtils(node) {
+  return node.operator === '+' && INTERPOLATION_PATTERN.test(node.left.value);
+}
+
+function templateLiteralHasInterpolatedUtils(node) {
+  return node.quasis.some((quasi) => {
+    return quasi.tail === false && INTERPOLATION_PATTERN.test(quasi.value.raw);
+  });
+}
+
+function validateInterpolatedUtils(context, node) {
+  if (INTERPOLATED_UTILS_VALIDATORS[node.type] === undefined) {
+    return;
+  }
+
+  if (INTERPOLATED_UTILS_VALIDATORS[node.type](node)) {
+    context.report({
+      node,
+      message: INTERPOLATED_UTIL_ERROR,
+    });
+  }
+}
+
+module.exports = {
+  validateInterpolatedUtils,
+  INTERPOLATED_UTIL_ERROR,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitlab/eslint-plugin",
-  "version": "20.0.0",
+  "version": "20.2.0",
   "description": "GitLab package for our custom eslint rules",
   "main": "lib/index.js",
   "scripts": {