build: add stylelint rule to validate ampersands in theme selectors (#10949)

Replaces the `selector-nested-pattern-scoped` Stylelint rule with a new rule called `no-ampersand-beyond-selector-start`. The new rule will enforce that ampersands can only be used at the start of selectors in theme mixins. This will catch issues like #10889 and #10904 where having an ampersand anywhere else in the selector will work in most cases, but will break down once the mixin is wrapped in a selector.

Author: crisbeto

stylelint-config.json

@@ -1,7 +1,7 @@
 {
   "plugins": [
     "./tools/stylelint/no-prefixes/no-prefixes.js",
-    "./tools/stylelint/selector-nested-pattern-scoped/index.js",
+    "./tools/stylelint/no-ampersand-beyond-selector-start/index.js",
     "./tools/stylelint/selector-no-deep/index.js",
     "./tools/stylelint/no-nested-mixin/index.js",
     "./tools/stylelint/no-concrete-rules/index.js",
@@ -11,8 +11,7 @@
     "material/no-prefixes": [["last 2 versions", "not ie <= 10", "not ie_mob <= 10"]],
     "material/selector-no-deep": true,
     "material/no-nested-mixin": true,
-    "material/selector-nested-pattern-scoped": [".*[^&]$", {
-      "message": "The & operator is not allowed at the end of theme selectors.",
+    "material/no-ampersand-beyond-selector-start": [true, {
       "filePattern": "-theme\\.scss$"
     }],
     "material/no-concrete-rules": [true, {

tools/stylelint/no-ampersand-beyond-selector-start/index.js

@@ -0,0 +1,66 @@
+const stylelint = require('stylelint');
+const path = require('path');
+const isStandardSyntaxRule = require('stylelint/lib/utils/isStandardSyntaxRule');
+const isStandardSyntaxSelector = require('stylelint/lib/utils/isStandardSyntaxSelector');
+
+const ruleName = 'material/no-ampersand-beyond-selector-start';
+const messages = stylelint.utils.ruleMessages(ruleName, {
+  expected: () => 'Ampersand is only allowed at the beginning of a selector',
+});
+
+/**
+ * Stylelint rule that doesn't allow for an ampersand to be used anywhere
+ * except at the start of a selector. Skips private mixins.
+ *
+ * Based off the `selector-nested-pattern` Stylelint rule.
+ * Source: https://github.com/stylelint/stylelint/blob/master/lib/rules/selector-nested-pattern/
+ */
+const plugin = stylelint.createPlugin(ruleName, (isEnabled, options) => {
+  return (root, result) => {
+    if (!isEnabled) return;
+
+    const filePattern = new RegExp(options.filePattern);
+    const fileName = path.basename(root.source.input.file);
+
+    if (!filePattern.test(fileName)) return;
+
+    root.walkRules(rule => {
+      if (
+        rule.parent.type === 'rule' &&
+        isStandardSyntaxRule(rule) &&
+        isStandardSyntaxSelector(rule.selector) &&
+        // Using the ampersand at the beginning is fine, anything else can cause issues in themes.
+        rule.selector.indexOf('&') > 0) {
+
+        const mixinName = getClosestMixinName(rule);
+
+        // Skip rules inside private mixins.
+        if (!mixinName || !mixinName.startsWith('_')) {
+          stylelint.utils.report({
+            result,
+            ruleName,
+            message: messages.expected(),
+            node: rule
+          });
+        }
+      }
+    });
+  };
+
+  /** Walks up the AST and finds the name of the closest mixin. */
+  function getClosestMixinName(node) {
+    let parent = node.parent;
+
+    while (parent) {
+      if (parent.type === 'atrule' && parent.name === 'mixin') {
+        return parent.params;
+      }
+
+      parent = parent.parent;
+    }
+  }
+});
+
+plugin.ruleName = ruleName;
+plugin.messages = messages;
+module.exports = plugin;