add contain-nested option for external mixins (#2)

Author: ETLaurent

.stylelintrc.json

@@ -3,6 +3,11 @@
     "./index.js"
   ],
   "rules": {
-    "@apostrophecms/stylelint-no-mixed-decls": true
+    "@apostrophecms/stylelint-no-mixed-decls": [
+      true,
+      {
+        "contain-nested": [ "external-mixin-known-to-contain-nested-rules" ]
+      }
+    ]
   }
 }

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## UNRELEASED
+
+### Adds
+
+* New `contain-nested` array option to list mixins that are known to contain nested rules.
+
 ## 1.1.0
 
 ### Adds

README.md

@@ -31,6 +31,23 @@ Add it to your Stylelint configuration:
 }
 ```
 
+You can set a `contain-nested` option to list mixins that are known to contain nested rules.  
+This is an answer to the [limitations](#limitations) that this plugin cannot analyze mixin definitions from other files.
+
+```js
+{
+  "plugins": [ "@apostrophecms/stylelint-no-mixed-decls" ],
+  "rules": {
+    "@apostrophecms/stylelint-no-mixed-decls": [
+      true,
+      {
+        "contain-nested": [ "external-mixin-known-to-contain-nested-rules" ]
+      }
+    ] 
+  }
+}
+```
+
 ## Example: Correct Usage
 
 ```scss
@@ -55,6 +72,7 @@ Add it to your Stylelint configuration:
 
 .foo {
   @include foo;
+  @include external-mixin; // not known to contain nested rules
   color: red;
 }
 ```
@@ -144,6 +162,14 @@ Add it to your Stylelint configuration:
 }
 ```
 
+```scss
+.foo {
+  @include external-mixin-known-to-contain-nested-rules;
+
+  color: red; // ❌ Cannot mix declarations and nested rules. Group them together or wrap declarations in a nested "& { }" block. See https://sass-lang.com/documentation/breaking-changes/mixed-decls/
+}
+```
+
 ## Why this matters
 
 This plugin ensures your Sass code adheres to modern CSS nesting behavior,
@@ -172,6 +198,12 @@ or colocate them with the code that uses them.
 Alternatively, wrap declarations following `@include` statements
 in a nested `& { }` block as a safe default when unsure of the mixin's contents.
 
+**Use `contain-nested` option:**
+
+This option can be used to list mixins that are known to contain nested rules,
+so that the plugin can treat them accordingly,
+even if their definition is not present in the file they are used.
+
 ## Please contribute!
 
 We welcome contributions! If you find a bug or something missing,

index.js

@@ -5,7 +5,7 @@ const messages = stylelint.utils.ruleMessages(ruleName, {
   mixed: 'Cannot mix declarations and nested rules. Group them together or wrap declarations in a nested "& { }" block. See https://sass-lang.com/documentation/breaking-changes/mixed-decls/'
 });
 
-module.exports = stylelint.createPlugin(ruleName, () => {
+module.exports = stylelint.createPlugin(ruleName, (primary, secondaryOptions) => {
   return (root, result) => {
     root.walkRules(rule => {
       let seenNested = false;
@@ -25,25 +25,34 @@ module.exports = stylelint.createPlugin(ruleName, () => {
           });
         }
 
-        // Inspect the included mixin
+        // If the incuded mixin is known to contain nested rules,
+        // we can skip checking it and just set `seenNested` to true.
+        // Any declarations after this point will be
+        // reported, even the ones inside the mixin.
         if (isInclude(node)) {
+          const nameWithoutArgs = node.params.replace(/\(.*$/, '');
+
+          // If the mixin is known to contain nested rules because
+          // it's listed as such in the options:
+          if (secondaryOptions?.['contain-nested']?.includes(nameWithoutArgs)) {
+            seenNested = true;
+            return;
+          }
+
+          // Otherwise, we need to find the mixin definition:
           root.walkAtRules('mixin', mixinRule => {
-            // Skip other mixins that don't match
-            // the name of the current include:
             if (mixinRule.params !== node.params) {
               return;
             }
 
             mixinRule.each(mixinNode => {
+              // If the mixin is actually seen to contain nested rules:
               if (isNested(mixinNode)) {
-                // If we find a nested rule inside the mixin,
-                // flag this "global" variable to true so that
-                // any declarations after this point will be
-                // reported, even the ones inside the mixin.
                 seenNested = true;
                 return;
               }
 
+              // If the mixin itself contains declarations after nested rules:
               if (isDecl(mixinNode) && seenNested) {
                 stylelint.utils.report({
                   message: messages.mixed,

test/bad.scss

@@ -71,3 +71,11 @@
   @include flat-2;
   @include mixed-2;
 }
+
+// This is bad because the mixin is known to contain nested rules,
+// therefore the rule that comes after it should be wrapped.
+.d {
+  @include external-mixin-known-to-contain-nested-rules;
+
+  color: red;
+}

test/good.scss

@@ -110,3 +110,24 @@
 
   color: red;
 }
+
+// This is okay because the mixin isn't known to contain nested rules.
+.m {
+  @include external-mixin;
+
+  color: red;
+}
+
+// This is okay because nothings comes after the mixin.
+.n {
+  @include external-mixin-known-to-contain-nested-rules;
+}
+
+// This is okay because the rule that comes after the mixin is wrapped.
+.o {
+  @include external-mixin-known-to-contain-nested-rules;
+
+  & {
+    color: red;
+  }
+}

test/index.js

@@ -18,35 +18,38 @@ describe('@apostrophecms/stylelint-no-mixed-decls stylelint rule', function() {
       throw new Error(`Unexpected output: ${stdout}`);
     }
 
-    const expectedOccurrences = 12;
-    const occurrences = countOccurences(ERROR_MESSAGE, stderr);
-
     const expectedErrorPositions = [
       [ 7, 3 ],
       [ 8, 3 ],
       [ 29, 3 ],
+      [ 30, 3 ],
       [ 34, 3 ],
       [ 35, 3 ],
       [ 45, 3 ],
       [ 46, 3 ],
       [ 56, 3 ],
       [ 57, 3 ],
       [ 64, 3 ],
-      [ 70, 3 ]
+      [ 70, 3 ],
+      [ 78, 3 ]
     ];
+    const expectedErrorOccurrences = expectedErrorPositions.length;
+    const actualErrorOccurrences = countOccurences(ERROR_MESSAGE, stderr);
+
+    const errorPositionsMessages = expectedErrorPositions
+      .map(position =>
+        !stderr.includes(position.join(':')) &&
+        `Expected error message to include line ${position.join(':')} but it did not`
+      )
+      .filter(Boolean);
 
     assert.strictEqual(
-      occurrences,
-      expectedOccurrences,
-      `Expected 12 occurrences of "${ERROR_MESSAGE}" but found ${occurrences}`
-    );
+      actualErrorOccurrences,
+      expectedErrorOccurrences,
+      `Expected ${expectedErrorOccurrences} occurrences of "${ERROR_MESSAGE}" but found ${actualErrorOccurrences}.
 
-    expectedErrorPositions.forEach(position => {
-      assert.ok(
-        stderr.includes(position.join(':')),
-        `Expected error message to include line ${position.join(':')} but it did not`
-      );
-    });
+${errorPositionsMessages.join('\n')}`
+    );
   });
 
   it('should pass when css contains nested rules and scoped declarations', async function() {