Merge pull request #5143 from stylelint/disable-config

Add more disable error configuration
stylelint · Feb 19, 2021 · a48f2ae · a48f2ae
2 parents 4f4bdf9 + 5df3203
commit a48f2ae
Show file tree

Hide file tree

Showing 14 changed files with 680 additions and 94 deletions.
diff --git a/docs/user-guide/configure.md b/docs/user-guide/configure.md
@@ -158,29 +158,44 @@ For example:
 
 The report is considered to be a lint error.
 
-## `defaultSeverity`
+## Disable Errors
 
-You can set the default severity level for all rules that do not have a severity specified in their secondary options. For example, you can set the default severity to `"warning"`:
+These configurations provide extra validation for `stylelint-disable` comments. This can be helpful for enforcing useful and well-documented disables.
+
+They are configured like rules. They can have one of three values:
+
+- `null` (to turn the configuration off)
+- `true` or `false` (the primary option)
+- an array with two values (`[primary option, secondary options]`)
+
+The following secondary options are available:
+
+- `"except"` takes an array of rule names for which the primary option should be inverted.
+- `"severity"` adjusts the level of error emitted for the rule, [as above](#severity).
+
+For example, this produces errors for needless disables of all rules except `selector-max-type`:
 
 ```json
 {
-  "defaultSeverity": "warning"
+  "reportNeedlessDisables": [true, { "except": ["selector-max-type"] }]
 }
 ```
 
-## `ignoreDisables`
-
-Ignore `stylelint-disable` (e.g. `/* stylelint-disable block-no-empty */`) comments.
-
-For example:
+And this emits warnings for disables of `color-hex-case` that don't have a description:
 
 ```json
 {
-  "ignoreDisables": true
+  "reportDescriptionlessDisables": [
+    false,
+    {
+      "except": ["color-hex-case"],
+      "severity": "warning"
+    }
+  ]
 }
 ```
 
-## `reportNeedlessDisables`
+### `reportNeedlessDisables`
 
 Emit errors for `stylelint-disable` comments that don't actually match any lints that need to be disabled.
 
@@ -192,7 +207,7 @@ For example:
 }
 ```
 
-## `reportInvalidScopeDisables`
+### `reportInvalidScopeDisables`
 
 Emit errors for `stylelint-disable` comments that don't match rules that are specified in the configuration object.
 
@@ -204,7 +219,7 @@ For example:
 }
 ```
 
-## `reportDescriptionlessDisables`
+### `reportDescriptionlessDisables`
 
 Emit errors for `stylelint-disable` comments without a description.
 
@@ -244,6 +259,28 @@ For example:
 }
 ```
 
+## `defaultSeverity`
+
+You can set the default severity level for all rules that do not have a severity specified in their secondary options. For example, you can set the default severity to `"warning"`:
+
+```json
+{
+  "defaultSeverity": "warning"
+}
+```
+
+## `ignoreDisables`
+
+Ignore `stylelint-disable` (e.g. `/* stylelint-disable block-no-empty */`) comments.
+
+For example:
+
+```json
+{
+  "ignoreDisables": true
+}
+```
+
 ## `extends`
 
 You can _extend_ an existing configuration (whether your own or a third-party one).

diff --git a/lib/__tests__/descriptionlessDisables.test.js b/lib/__tests__/descriptionlessDisables.test.js
@@ -132,3 +132,177 @@ it('descriptionlessDisables from config', () => {
 		]);
 	});
 });
+
+it('descriptionlessDisables true except', () => {
+	const config = {
+		rules: { 'block-no-empty': true },
+	};
+
+	const css = stripIndent`
+    /* stylelint-disable -- Description */
+    a {}
+    /* stylelint-enable */
+    a {
+      b {} /* stylelint-disable-line block-no-empty -- Description */
+    }
+    /* stylelint-disable-next-line block-no-empty
+     * --
+     * Description */
+    a {}
+
+    /* stylelint-disable */
+    a {}
+    /* stylelint-enable */
+    a {
+      b {} /* stylelint-disable-line invalid-hex-case */
+    }
+    /* stylelint-disable-next-line block-no-empty */
+    a {}
+    `;
+
+	return standalone({
+		config,
+		code: css,
+		reportDescriptionlessDisables: [true, { except: ['invalid-hex-case'] }],
+	}).then((linted) => {
+		const results = linted.results;
+
+		expect(results).toHaveLength(1);
+		const warnings = results[0].warnings.filter(
+			(warning) => warning.rule === '--report-descriptionless-disables',
+		);
+
+		expect(warnings).toEqual([
+			{
+				line: 12,
+				column: 1,
+				rule: '--report-descriptionless-disables',
+				severity: 'error',
+				text: 'Disable for "all" is missing a description',
+			},
+			{
+				line: 18,
+				column: 1,
+				rule: '--report-descriptionless-disables',
+				severity: 'error',
+				text: 'Disable for "block-no-empty" is missing a description',
+			},
+		]);
+	});
+});
+
+it('descriptionlessDisables false except', () => {
+	const config = {
+		rules: { 'block-no-empty': true },
+	};
+
+	const css = stripIndent`
+    /* stylelint-disable -- Description */
+    a {}
+    /* stylelint-enable */
+    a {
+      b {} /* stylelint-disable-line block-no-empty -- Description */
+    }
+    /* stylelint-disable-next-line block-no-empty
+     * --
+     * Description */
+    a {}
+
+    /* stylelint-disable */
+    a {}
+    /* stylelint-enable */
+    a {
+      b {} /* stylelint-disable-line invalid-hex-case */
+    }
+    /* stylelint-disable-next-line block-no-empty */
+    a {}
+    `;
+
+	return standalone({
+		config,
+		code: css,
+		reportDescriptionlessDisables: [false, { except: ['invalid-hex-case'] }],
+	}).then((linted) => {
+		const results = linted.results;
+
+		expect(results).toHaveLength(1);
+		const warnings = results[0].warnings.filter(
+			(warning) => warning.rule === '--report-descriptionless-disables',
+		);
+
+		expect(warnings).toEqual([
+			{
+				line: 16,
+				column: 8,
+				rule: '--report-descriptionless-disables',
+				severity: 'error',
+				text: 'Disable for "invalid-hex-case" is missing a description',
+			},
+		]);
+	});
+});
+
+it('descriptionlessDisables severity', () => {
+	const config = {
+		rules: { 'block-no-empty': true },
+	};
+
+	const css = stripIndent`
+    /* stylelint-disable -- Description */
+    a {}
+    /* stylelint-enable */
+    a {
+      b {} /* stylelint-disable-line block-no-empty -- Description */
+    }
+    /* stylelint-disable-next-line block-no-empty
+     * --
+     * Description */
+    a {}
+
+    /* stylelint-disable */
+    a {}
+    /* stylelint-enable */
+    a {
+      b {} /* stylelint-disable-line block-no-empty */
+    }
+    /* stylelint-disable-next-line block-no-empty */
+    a {}
+    `;
+
+	return standalone({
+		config,
+		code: css,
+		reportDescriptionlessDisables: [true, { severity: 'warning' }],
+	}).then((linted) => {
+		const results = linted.results;
+
+		expect(results).toHaveLength(1);
+		const warnings = results[0].warnings.filter(
+			(warning) => warning.rule === '--report-descriptionless-disables',
+		);
+
+		expect(warnings).toEqual([
+			{
+				line: 12,
+				column: 1,
+				rule: '--report-descriptionless-disables',
+				severity: 'warning',
+				text: 'Disable for "all" is missing a description',
+			},
+			{
+				line: 16,
+				column: 8,
+				rule: '--report-descriptionless-disables',
+				severity: 'warning',
+				text: 'Disable for "block-no-empty" is missing a description',
+			},
+			{
+				line: 18,
+				column: 1,
+				rule: '--report-descriptionless-disables',
+				severity: 'warning',
+				text: 'Disable for "block-no-empty" is missing a description',
+			},
+		]);
+	});
+});