Add no-unused-private-members rule (#949)

CHANGELOG.md

@@ -1,3 +1,9 @@
+# 6.1.0
+
+- Added: `no-unused-private-members` rule (#884).
+
+**Full Changelog**: https://github.com/stylelint-scss/stylelint-scss/compare/v6.0.0...v6.1.0
+
 # 6.0.1
 
 - `function-calculation-no-interpolation` allows calc function interpolation in SassScript when declaring CSS custom properties.

README.md

@@ -189,6 +189,7 @@ Please also see the [example configs](./docs/examples/) for special cases.
 - [`no-duplicate-dollar-variables`](./src/rules/no-duplicate-dollar-variables/README.md): Disallow duplicate dollar variables within a stylesheet.
 - [`no-duplicate-mixins`](./src/rules/no-duplicate-mixins/README.md): Disallow duplicate mixins within a stylesheet.
 - [`no-global-function-names`](./src/rules/no-global-function-names/README.md): Disallows the use of global function names, as these global functions are now located inside built-in Sass modules.
+- [`no-unused-private-members`](./src/rules/no-unused-private-members/README.md): Disallow unused private members such as functions, mixins, variables or placeholder selectors.
 
 ## Deprecated
 These rules are deprecated — we won't fix bugs nor add options, and we will remove them in the next major release. We recommend you use a pretty printer (like Prettier) alongside Stylelint rather than these rules.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "stylelint-scss",
   "description": "A collection of SCSS-specific rules for Stylelint",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "author": "Krister Kari",
   "repository": "stylelint-scss/stylelint-scss",
   "license": "MIT",

src/rules/index.js

@@ -58,6 +58,7 @@ const rules = {
   "no-duplicate-dollar-variables": require("./no-duplicate-dollar-variables"),
   "no-duplicate-mixins": require("./no-duplicate-mixins"),
   "no-global-function-names": require("./no-global-function-names"),
+  "no-unused-private-members": require("./no-unused-private-members"),
   "operator-no-newline-after": require("./operator-no-newline-after"),
   "operator-no-newline-before": require("./operator-no-newline-before"),
   "operator-no-unspaced": require("./operator-no-unspaced"),

src/rules/no-unused-private-members/README.md

@@ -0,0 +1,158 @@
+# no-unused-private-members
+
+Disallow unused private members.
+
+<!-- prettier-ignore -->
+```scss
+@function _addNums($n1, $n2) {
+/**       ↑
+ * This function */
+  @return calc($n1 + $n2);
+}
+
+@mixin _no-margin {
+/**    ↑
+ * This mixin */
+  margin: 0;
+}
+
+%-toolbelt:hover {
+/* ↑
+ * This placeholder selector */
+  color: red;
+}
+
+.a {
+  $-b: 1;
+/** ↑
+ * This variable */
+}
+```
+
+[Private members](https://sass-lang.com/documentation/at-rules/use/#private-members), such as functions, mixins, variables, and selector placeholders are defined with names that start with either `-` or `_` (in the case of variables the name follows `$`, and the same applies to the `%` prefix for selector placeholders). These private members remain confined within the module, therefore, if they go unused within the module, they are considered unused.
+
+This rule ignores files using `@import` since all files loaded through it are consolidated within the same module. This setup makes it tricky to ensure all usages of private members.
+
+## Options
+
+### `true`
+
+The following patterns are considered problems:
+
+<!-- prettier-ignore -->
+```scss
+@function _addNums($n1, $n2) {
+  @return calc($n1 + $n2);
+}
+
+@function _plusOne($n1) {
+  @return $n1 + 1;
+}
+
+.sidebar {
+  margin-left: _addNums(4, 6); // _plusOne() is not used.
+}
+```
+
+<!-- prettier-ignore -->
+```scss
+@mixin _no-margin {
+  margin: 0;
+}
+
+@mixin blue-color {
+  color: blue;
+}
+
+nav ul {
+  @include blue-color; // _no-margin is not used.
+}   
+```
+
+<!-- prettier-ignore -->
+```scss
+$radius: 3px;
+$-margin: 3px;
+
+.rounded {
+  border-radius: $radius; // $-margin is not used.
+}
+```
+
+<!-- prettier-ignore -->
+```scss
+%-toolbelt:hover {
+  color: red;
+}
+
+.a.%b {
+  margin: 1px;
+}
+
+.action-buttons {
+  @extend %b; // %-toolbelt is not used.
+  color: blue;
+}
+```
+
+The following patterns are _not_ considered problems:
+
+
+<!-- prettier-ignore -->
+```scss
+@function _addNums($n1, $n2) {
+  @return calc($n1 + $n2);
+}
+
+@function _plusOne($n1) {
+  @return $n1 + 1;
+}
+
+.sidebar {
+  margin-left: _addNums(4, 6) + _plusOne(1);
+}
+```
+
+<!-- prettier-ignore -->
+```scss
+@mixin _no-margin {
+  margin: 0;
+}
+
+@mixin blue-color {
+  color: blue;
+}
+
+nav ul {
+  @include blue-color;
+  @include _no-margin;
+}   
+```
+
+<!-- prettier-ignore -->
+```scss
+$radius: 3px;
+$-margin: 3px;
+
+.rounded {
+  border-radius: $radius;
+  margin: $-margin;
+}
+```
+
+<!-- prettier-ignore -->
+```scss
+%-toolbelt:hover {
+  color: red;
+}
+
+.a.%b {
+  margin: 1px;
+}
+
+.action-buttons {
+  @extend %b;
+  @extend %-toolbelt;
+  color: blue;
+}
+```

src/rules/no-unused-private-members/__tests__/index.js

@@ -0,0 +1,172 @@
+"use strict";
+
+const { messages, ruleName } = require("..");
+
+testRule({
+  ruleName,
+  config: [true],
+  customSyntax: "postcss-scss",
+
+  accept: [
+    {
+      code: `
+      @function _addNums($n1, $n2) {
+        @return calc($n1 + $n2);
+      }
+      
+      @function one($n1) {
+        @return $n1;
+      }
+      
+      .sidebar {
+        margin-left: _addNums(4, 6);
+      }
+      `,
+      description: "Private function"
+    },
+    {
+      code: `
+      @mixin _reset-list {
+        margin: 0;
+      }
+      
+      nav ul {
+        @include _reset-list;
+      }      
+      `,
+      description: "Private mixin"
+    },
+    {
+      code: `
+      $-radius: 3px;
+
+      .rounded {
+        border-radius: $-radius;
+      }
+      `,
+      description: "Private variable"
+    },
+    {
+      code: `
+      %-toolbelt:hover {
+        color: red;
+      }
+
+      .a.%-b {
+        margin: 1px;
+      }
+
+      .action-buttons {
+        @extend %-toolbelt;
+        @extend %-b;
+        color: blue;
+      }
+      `,
+      description: "Private placeholder selector"
+    },
+    {
+      code: `
+      @import "fff"
+      $-radius: 3px;
+
+      rounded {
+        border-radius: 0px;
+      }
+      `,
+      message: messages.expected("$-radius"),
+      description: "Skip files using @import",
+      line: 2,
+      column: 7
+    }
+  ],
+
+  reject: [
+    {
+      code: `
+      @function _addNums($n1, $n2) {
+        @return calc($n1 + $n2);
+      }
+      
+      @function _one($n1) {
+        @return $n1;
+      }
+      
+      .sidebar {
+        margin-left: _addNums(4, 6);
+      }
+      `,
+      message: messages.expected("_one"),
+      description: "Private function",
+      line: 6,
+      column: 7
+    },
+    {
+      code: `
+      @mixin _reset-list {
+        margin: 0;
+        padding: 0;
+        list-style: none;
+      }
+      nav ul {
+        margin: 0;
+      }      
+      `,
+      message: messages.expected("_reset-list"),
+      description: "Private mixin",
+      line: 2,
+      column: 7
+    },
+    {
+      code: `
+      $-radius: 3px;
+
+      rounded {
+        border-radius: 0px;
+      }
+      `,
+      message: messages.expected("$-radius"),
+      description: "Private variable",
+      line: 2,
+      column: 7
+    },
+    {
+      code: `
+      %-toolbelt {
+        box-sizing: border-box;
+      }
+      
+      %-toolbelt:hover {
+        color: red;
+      }
+      
+      .b.%-toolbelt{
+        color: blue;
+      }
+      `,
+      message: messages.expected("%-toolbelt"),
+      description: "Private placeholder selector",
+      line: 2,
+      column: 7
+    },
+    {
+      code: `
+      %-toolbelt:hover {
+        color: red;
+      }
+
+      .a.%-b {
+        margin: 1px;
+      }
+
+      .action-buttons {
+        @extend %-toolbelt;
+        color: blue;
+      }
+      `,
+      message: messages.expected("%-b"),
+      line: 6,
+      column: 7,
+      description: "Private placeholder selector with class"
+    }
+  ]
+});