Add rule-empty-line-before rule (stylelint#2309)

docs/user-guide/example-config.md

@@ -114,8 +114,7 @@ You might want to learn a little about [how rules are named and how they work to
     "property-no-unknown": true,
     "property-no-vendor-prefix": true,
     "property-whitelist": string|[],
-    "rule-nested-empty-line-before": "always"|"never",
-    "rule-non-nested-empty-line-before": "always"|"never",
+    "rule-empty-line-before": "always"|"never"|"always-multi-line"|"never-multi-line",
     "selector-attribute-brackets-space-inside": "always"|"never",
     "selector-attribute-operator-blacklist": string|[],
     "selector-attribute-operator-space-after": "always"|"never",

docs/user-guide/rules.md

@@ -199,8 +199,9 @@ Here are all the rules within stylelint, grouped by the [*thing*](http://apps.wo
 
 ### Rule
 
--   [`rule-nested-empty-line-before`](../../lib/rules/rule-nested-empty-line-before/README.md): Require or disallow an empty line before nested rules.
--   [`rule-non-nested-empty-line-before`](../../lib/rules/rule-non-nested-empty-line-before/README.md): Require or disallow an empty line before non-nested rules.
+-   [`rule-empty-line-before`](../../lib/rules/rule-empty-line-before/README.md): Require or disallow an empty line before rules.
+-   [`rule-nested-empty-line-before`](../../lib/rules/rule-nested-empty-line-before/README.md): Require or disallow an empty line before nested rules (deprecated).
+-   [`rule-non-nested-empty-line-before`](../../lib/rules/rule-non-nested-empty-line-before/README.md): Require or disallow an empty line before non-nested rules (deprecated).
 
 ### Media feature
 

lib/rules/index.js

@@ -116,6 +116,7 @@ const propertyNoUnknown = require("./property-no-unknown")
 const propertyNoVendorPrefix = require("./property-no-vendor-prefix")
 const propertyWhitelist = require("./property-whitelist")
 const rootNoStandardProperties = require("./root-no-standard-properties")
+const ruleEmptyLineBefore = require("./rule-empty-line-before")
 const ruleNestedEmptyLineBefore = require("./rule-nested-empty-line-before")
 const ruleNonNestedEmptyLineBefore = require("./rule-non-nested-empty-line-before")
 const selectorAttributeBracketsSpaceInside = require("./selector-attribute-brackets-space-inside")
@@ -291,6 +292,7 @@ module.exports = {
   "property-no-vendor-prefix": propertyNoVendorPrefix,
   "property-whitelist": propertyWhitelist,
   "root-no-standard-properties": rootNoStandardProperties,
+  "rule-empty-line-before": ruleEmptyLineBefore,
   "rule-nested-empty-line-before": ruleNestedEmptyLineBefore,
   "rule-non-nested-empty-line-before": ruleNonNestedEmptyLineBefore,
   "selector-attribute-brackets-space-inside": selectorAttributeBracketsSpaceInside,

lib/rules/rule-empty-line-before/README.md

@@ -0,0 +1,252 @@
+# rule-empty-line-before
+
+Require or disallow an empty line before rules.
+
+```css
+a {}
+      /* ← */
+b {}  /* ↑ */
+/**      ↑
+ * This line */
+```
+
+If the rule is the very first node in a stylesheet then it is ignored.
+
+## Options
+
+`string`: `"always"|"never"|"always-multi-line"|"never-multi-line"`
+
+### `"always"`
+
+There *must always* be an empty line before rules.
+
+The following patterns are considered warnings:
+
+```css
+a {} b {}
+```
+
+```css
+a {}
+b {}
+```
+
+The following patterns are *not* considered warnings:
+
+```css
+a {}
+
+b {}
+```
+
+### `"never"`
+
+There *must never* be an empty line before rules.
+
+The following patterns are considered warnings:
+
+```css
+a {}
+
+b {}
+```
+
+The following patterns are *not* considered warnings:
+
+```css
+a {} b {}
+```
+
+```css
+a {}
+b {}
+```
+
+### `"always-multi-line"`
+
+There *must always* be an empty line before multi-line rules.
+
+The following patterns are considered warnings:
+
+```css
+a {
+  color: red;
+}
+b {
+  color: blue;
+}
+```
+
+The following patterns are *not* considered warnings:
+
+```css
+a {
+  color: red;
+}
+
+b {
+  color: blue;
+}
+```
+
+### `"never-multi-line"`
+
+There *must never* be an empty line before multi-line rules.
+
+The following patterns are considered warnings:
+
+```css
+a {
+  color: red;
+}
+
+b {
+  color: blue;
+}
+```
+
+The following patterns are *not* considered warnings:
+
+```css
+a {
+  color: red;
+}
+b {
+  color: blue;
+}
+```
+
+## Optional secondary options
+
+### `except: ["after-rule", "after-single-line-comment", "inside-block-and-after-rule", "first-nested"]`
+
+#### `"after-rule"`
+
+Reverse the primary option if the rule comes after another rule.
+
+For example, with `"always"`:
+
+The following patterns are considered warnings:
+
+```css
+a {}
+
+b {}
+```
+
+The following patterns are *not* considered warnings:
+
+```css
+a {}
+b {}
+```
+
+#### `"after-single-line-comment"`
+
+Reverse the primary option if the rule comes after a single-line comment.
+
+For example, with `"always"`:
+
+The following patterns are considered warnings:
+
+```css
+/* comment */
+
+a {}
+```
+
+The following patterns are *not* considered warnings:
+
+```css
+/* comment */
+a {}
+```
+
+#### `"inside-block-and-after-rule"`
+
+Reverse the primary option if the rule is inside a block and comes after another rule.
+
+For example, with `"always"`:
+
+The following patterns are considered warnings:
+
+```css
+@media {
+
+  a {}
+
+  b {}
+}
+```
+
+The following patterns are *not* considered warnings:
+
+```css
+@media {
+  a {}
+  b {}
+}
+```
+
+#### `"first-nested"`
+
+Reverse the primary option if the rule is the first in a block.
+
+For example, with `"always"`:
+
+The following patterns are considered warnings:
+
+```css
+@media {
+
+  a {}
+
+  b {}
+}
+```
+
+The following patterns are *not* considered warnings:
+
+```css
+@media {
+  a {}
+
+  b {}
+}
+```
+
+### `ignore: ["after-comment", "inside-block"]`
+
+#### `"after-comment"`
+
+Ignore rules that come after a comment.
+
+For example, with `"always"`:
+
+The following patterns are *not* considered warnings:
+
+```css
+/* comment */
+a {}
+```
+
+#### `"inside-block"`
+
+Ignore rules that are inside a block.
+
+For example, with `"always"`:
+
+The following patterns are *not* considered warnings:
+
+```css
+@media {
+  a {}
+}
+```
+
+```css
+@media {
+  a {}
+  b {}
+}
+```