stylelint-plugin-defensive-css 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Fedya Petrakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# 🦖 Stylelint Plugin Defensive CSS
+
+![License](https://img.shields.io/github/license/yuschick/stylelint-plugin-defensive-css?style=for-the-badge)
+![NPM Version](https://img.shields.io/npm/v/stylelint-plugin-defensive-css?style=for-the-badge)
+![Main Workflow Status](https://img.shields.io/github/actions/workflow/status/yuschick/stylelint-plugin-defensive-css/main.yaml?style=for-the-badge)
+
+A Stylelint plugin to enforce defensive CSS best practices.
+
+> [Read more about Defensive CSS](https://defensivecss.dev/)
+
+## Getting Started
+
+> Before getting started with the plugin, you must first have
+> [Stylelint](https://stylelint.io/) version 14.0.0 or greater installed
+
+To get started using the plugin, it must first be installed.
+
+```bash
+npm i stylelint-plugin-defensive-css --save-dev
+```
+
+```bash
+yarn add stylelint-plugin-defensive-css --dev
+```
+
+With the plugin installed, the rule(s) can be added to the project's Stylelint
+configuration.
+
+```json
+{
+  "plugins": ["stylelint-plugin-defensive-css"],
+  "rules": {
+    "plugin/use-defensive-css": [
+      true,
+      { "severity": "warning" }
+    ]
+  }
+}
+```
+
+## Rules / Options
+
+The plugin provides multiple rules that can be toggled on and off as needed.
+
+### Background Repeat
+
+> [Read more about this pattern in Defensive CSS](https://defensivecss.dev/tip/bg-repeat/)
+
+Oftentimes, when using a large image as a background, we tend to forget to account for the case when the design is viewed on a large screen. That background will repeat by default.
+
+Enable this rule in order to prevent unintentional repeating background.
+
+```json
+{
+  "rules": {
+    "plugin/use-defensive-css": [
+      true,
+      { ..., "background-repeat": true }
+    ]
+  }
+}
+```
+
+#### ✅ Passing Examples
+
+```css
+div {
+    background: url('some-image.jpg') repeat black top center;
+}
+div {
+    background: url('some-image.jpg') black top center;
+    background-repeat: no-repeat;
+}
+````
+
+#### ❌ Failing Examples
+
+```css
+div {
+    background: url('some-image.jpg') black top center;
+}
+div { 
+    background-image: url('some-image.jpg');
+}
+```
+
+
+### Custom Property Fallbacks
+
+> [Read more about this pattern in Defensive CSS](https://defensivecss.dev/tip/css-variable-fallback/)
+
+CSS variables are gaining more and more usage in web design. There is a method that we can apply to use them in a way that doesn’t break the experience, in case the CSS variable value was empty for some reason.
+
+Enable this rule in order to require fallbacks values for custom properties.
+
+```json
+{
+  "rules": {
+    "plugin/use-defensive-css": [
+      true,
+      { ..., "custom-property-fallbacks": true }
+    ]
+  }
+}
+```
+
+#### ✅ Passing Examples
+
+```css
+div {
+    color: var(--color-primary, #000);
+}
+````
+
+#### ❌ Failing Examples
+
+```css
+div {
+    color: var(--color-primary);
+}
+```
+
+### Flex Wrapping
+
+> [Read more about this pattern in Defensive CSS](https://defensivecss.dev/tip/flexbox-wrapping/)
+
+CSS flexbox is one of the most useful CSS layout features nowadays. It’s tempting to add `display: flex` to a wrapper and have the child items ordered next to each other. The thing is when there is not enough space, those child items won’t wrap into a new line by default. We need to change that behavior with `flex-wrap: wrap`.
+
+Enable this rule in order to require all flex rows to have a flex-wrap value.
+
+```json
+{
+  "rules": {
+    "plugin/use-defensive-css": [
+      true,
+      { ..., "flex-wrapping": true }
+    ]
+  }
+}
+```
+
+#### ✅ Passing Examples
+
+```css
+div {
+    display: flex;
+    flex-wrap: wrap; 
+}
+div {
+    display: flex;
+    flex-direction: row-reverse;
+    flex-wrap: wrap-reverse;
+}
+````
+
+#### ❌ Failing Examples
+
+```css
+div {
+    display: flex;
+}
+div {
+    display: flex;
+    flex-direction: row;
+}
+```
+
+### Vendor Prefix Grouping
+
+> [Read more about this pattern in Defensive CSS](https://defensivecss.dev/tip/grouping-selectors/)
+
+It's not recommended to group selectors that are meant to work with different browsers. For example, styling an input's placeholder needs multiple selectors per the browser. If we group the selectors, the entire rule will be invalid, according to [w3c](https://www.w3.org/TR/selectors/#grouping).
+
+Enable this rule in order to require all vendor-prefixed selectors to be split into their own rules.
+
+```json
+{
+  "rules": {
+    "plugin/use-defensive-css": [
+      true,
+      { ..., "vendor-prefix-grouping": true }
+    ]
+  }
+}
+```
+
+
+#### ✅ Passing Examples
+
+```css
+input::-webkit-input-placeholder {
+    color: #222;
+}
+input::-moz-placeholder {
+    color: #222;
+}
+````
+
+#### ❌ Failing Examples
+
+```css
+input::-webkit-input-placeholder,
+input::-moz-placeholder {
+    color: #222;
+}
+```

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "stylelint-plugin-defensive-css",
+  "version": "0.0.1",
+  "description": "A Stylelint plugin to enforce defensive CSS best practices.",
+  "main": "src/index.js",
+  "files": [
+    "src/**/*.js",
+    "!**/**/*.test.js"
+  ],
+  "scripts": {
+    "prepare": "husky install",
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yuschick/stylelint-plugin-defensive-css.git"
+  },
+  "author": "Daniel Yuschick",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/yuschick/stylelint-plugin-defensive-css/issues"
+  },
+  "homepage": "https://github.com/yuschick/stylelint-plugin-defensive-css#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "keywords": [
+    "Stylelint",
+    "plugin",
+    "CSS",
+    "defensive CSS",
+    "best practices"
+  ],
+  "peerDependencies": {
+    "stylelint": "^14.0.0 || ^15.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^17.4.4",
+    "@commitlint/config-conventional": "^17.4.4",
+    "eslint": "^8.35.0",
+    "husky": "^8.0.0",
+    "jest": "^29.4.3",
+    "jest-cli": "^29.4.3",
+    "jest-preset-stylelint": "^6.1.0",
+    "lint-staged": "^13.1.2",
+    "prettier": "^2.8.4",
+    "prettier-eslint": "^15.0.1",
+    "stylelint": "^15.2.0"
+  },
+  "lint-staged": {
+    "**/*.{js|md}": [
+      "eslint",
+      "prettier --write"
+    ]
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+const useDefensiveCSS = require('./rules/use-defensive-css');
+
+module.exports = [useDefensiveCSS];

package/src/rules/use-defensive-css/base.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const stylelint = require('stylelint');
+
+const ruleName = 'plugin/use-defensive-css';
+
+const ruleMessages = stylelint.utils.ruleMessages(ruleName, {
+  backgroundRepeat() {
+    return 'Ensure a background-repeat property is defined when using a background image.';
+  },
+  customPropertyFallbacks() {
+    return 'Ensure that any custom properties have a fallback value.';
+  },
+  flexWrapping() {
+    return 'Flex rows must have a `flex-wrap: wrap;` or `flex-wrap: wrap-reverse` declaration.';
+  },
+  vendorPrefixWGrouping() {
+    return `It's not recommended to group selectors that are meant to work with different browsers. Instead, split them to separate rules.`;
+  },
+});
+
+const ruleMeta = {
+  url: 'https://github.com/yuschick/stylelint-plugin-defensive-css',
+};
+
+module.exports = {
+  ruleName,
+  ruleMessages,
+  ruleMeta,
+};

package/src/rules/use-defensive-css/index.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const stylelint = require('stylelint');
+
+const { ruleName, ruleMessages, ruleMeta } = require('./base');
+const {
+  findShorthandBackgroundRepeat,
+} = require('../../utils/findShorthandBackgroundRepeat');
+const { findVendorPrefixes } = require('../../utils/findVendorPrefixes');
+
+const ruleFunction = (_, options) => {
+  let isLastStyleDeclaration = false;
+  const backgroundRepeatProps = {
+    hasBackgroundImage: false,
+    isMissingBackgroundRepeat: true,
+    nodeToReport: undefined,
+  };
+  const flexWrappingProps = {
+    isDisplayFlex: false,
+    isFlexRow: true,
+    isMissingFlexWrap: true,
+    nodeToReport: undefined,
+  };
+
+  return (root, result) => {
+    const validOptions = stylelint.utils.validateOptions(result, ruleName);
+
+    if (!validOptions) {
+      return;
+    }
+
+    root.walkDecls((decl) => {
+      if (
+        JSON.stringify(decl) ===
+        JSON.stringify(decl.parent.nodes[decl.parent.nodes.length - 1])
+      ) {
+        isLastStyleDeclaration = true;
+      }
+
+      /* BACKGROUND REPEAT  */
+      if (options?.['background-repeat']) {
+        if (decl.prop === 'background' && decl.value.includes('url(')) {
+          backgroundRepeatProps.hasBackgroundImage = true;
+          backgroundRepeatProps.isMissingBackgroundRepeat =
+            !findShorthandBackgroundRepeat(decl.value);
+          backgroundRepeatProps.nodeToReport = decl;
+        }
+
+        if (decl.prop === 'background-image' && decl.value.includes('url(')) {
+          backgroundRepeatProps.hasBackgroundImage = true;
+          backgroundRepeatProps.nodeToReport = decl;
+        }
+
+        if (decl.prop === 'background-repeat') {
+          backgroundRepeatProps.isMissingBackgroundRepeat = false;
+        }
+
+        if (
+          isLastStyleDeclaration &&
+          Object.values(backgroundRepeatProps).every((prop) => prop)
+        ) {
+          stylelint.utils.report({
+            message: ruleMessages.backgroundRepeat(),
+            node: decl.parent,
+            result,
+            ruleName,
+          });
+        }
+      }
+
+      /* CUSTOM PROPERTY FALLBACKS */
+      if (options?.['custom-property-fallbacks']) {
+        if (decl.value.includes('var(--') && !decl.value.includes(',')) {
+          stylelint.utils.report({
+            message: ruleMessages.customPropertyFallbacks(),
+            node: decl,
+            result,
+            ruleName,
+          });
+        }
+      }
+
+      /* FLEX WRAPPING */
+      if (options?.['flex-wrapping']) {
+        if (decl.prop === 'display' && decl.value.includes('flex')) {
+          flexWrappingProps.isDisplayFlex = true;
+          flexWrappingProps.nodeToReport = decl;
+        }
+
+        if (decl.prop === 'flex-direction' && decl.value.startsWith('column')) {
+          flexWrappingProps.isFlexRow = false;
+        }
+
+        if (decl.prop === 'flex-wrap' && decl.value.startsWith('wrap')) {
+          flexWrappingProps.isMissingFlexWrap = false;
+        }
+
+        if (
+          isLastStyleDeclaration &&
+          Object.values(flexWrappingProps).every((prop) => prop)
+        ) {
+          stylelint.utils.report({
+            message: ruleMessages.flexWrapping(),
+            node: flexWrappingProps.nodeToReport,
+            result,
+            ruleName,
+          });
+        }
+      }
+
+      /* GROUPING VENDOR PREFIXES */
+      if (options?.['vendor-prefix-grouping']) {
+        const hasMultiplePrefixes = findVendorPrefixes(decl.parent.selector);
+
+        if (hasMultiplePrefixes) {
+          stylelint.utils.report({
+            message: ruleMessages.vendorPrefixWGrouping(),
+            node: decl.parent,
+            result,
+            ruleName,
+          });
+        }
+      }
+
+      return;
+    });
+  };
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = ruleMessages;
+ruleFunction.meta = ruleMeta;
+
+module.exports = stylelint.createPlugin(ruleName, ruleFunction);

package/src/utils/findShorthandBackgroundRepeat.js

@@ -0,0 +1,9 @@
+const expression = /\b(repeat|repeat-x|repeat-y|space|round|no-repeat|)\b/g;
+
+function findShorthandBackgroundRepeat(value) {
+  return value.match(expression).some((val) => val);
+}
+
+module.exports = {
+  findShorthandBackgroundRepeat,
+};

package/src/utils/findVendorPrefixes.js

@@ -0,0 +1,10 @@
+const expression = /-[-moz-|-ms-|-o-|-webkit-|]+-/g;
+
+function findVendorPrefixes(selector) {
+  let prefixesFound = [...selector.matchAll(expression)];
+  return prefixesFound.length > 1;
+}
+
+module.exports = {
+  findVendorPrefixes,
+};