Report disables in the same manner as lints

Rather than returning disables that are considered "invalid" for
various reasons (such as --report-needless-disables) as a separate
list of objects that formatters must handle individually, stylelint
now converts them into standard lint warnings. This allows formatters
to automatically format them the same as normal warnings without any
extra disable-specific code.

Closes #4896

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to this project are documented in this file.
 
 ## Head
 
+- Added: disable comments that are reported as errors for various reasons are now reported as standard lint errors rather than a separate class of errors that must be handled specially.
+- Deprecated: `StylelintStandaloneReturnValue.reportedDisables`, `.descriptionlessDisables`, `.needlessDisables`, and `.invalidScopeDisables`. `.reportedDisables` will always be empty and the other properties will always be undefined, since these errors now show up in `.results` instead.
 - Fixed: use of full file path without converting it to glob ([#4931](https://github.com/stylelint/stylelint/pull/4931)).
 
 ## 13.7.1

docs/developer-guide/formatters.md

@@ -50,30 +50,6 @@ And the second argument (`returnValue`) is an object (type `StylelintStandaloneR
 ```js
 {
   "errored": false, // `true` if there were any warnings with "error" severity
-  "needlessDisables": [
-    // Present if stylelint was configured with `reportNeedlessDisables: true`
-    {
-      "source": "path/to/file.css",
-      "ranges": [
-        {
-          "start": 10,
-          "rule": "indentation"
-        }
-      ]
-    }
-  ],
-  "invalidScopeDisables": [
-    // Present if stylelint was configured with `reportInvalidScopeDisables: true`
-    {
-      "source": "path/to/file.css",
-      "ranges": [
-        {
-          "start": 1,
-          "rule": "color-named"
-        }
-      ]
-    }
-  ],
   "maxWarningsExceeded": {
     // Present if stylelint was configured with a `maxWarnings` count
     "maxWarnings": 10,

docs/user-guide/usage/node-api.md

@@ -66,14 +66,6 @@ An array containing all the stylelint result objects (the objects that formatter
 
 An object containing the maximum number of warnings and the amount found, e.g. `{ maxWarnings: 0, foundWarnings: 12 }`.
 
-### `needlessDisables`
-
-An array of objects, one for each source, with tells you which stylelint-disable comments are not blocking a lint violation
-
-### `invalidScopeDisables`
-
-An array of objects, one for each source, with tells you which rule in `stylelint-disable <rule>` comment don't exist within the configuration object.
-
 ## Syntax errors
 
 `stylelint.lint()` does not reject the Promise when your CSS contains syntax errors.

docs/user-guide/usage/options.md

@@ -146,7 +146,7 @@ Produce a report to clean up your codebase, keeping only the stylelint-disable c
 If needless disables are found, the:
 
 - CLI process exits with code `2`
-- Node.js API adds a [`needlessDisables`](node-api.md#needlessdisables) property to the returned data
+- Node.js API adds errors to the returned data
 
 ## `reportInvalidScopeDisables`
 
@@ -157,7 +157,7 @@ Produce a report of the stylelint-disable comments that used for rules that don'
 If invalid scope disables are found, the:
 
 - CLI process exits with code `2`
-- Node.js API adds a [`invalidScopeDisables`](node-api.md#invalidscopedisables) property to the returned data
+- Node.js API adds errors to the returned data
 
 ## `codeFilename`
 

lib/__tests__/cli.test.js

@@ -232,14 +232,9 @@ describe('CLI', () => {
 
 		expect(process.exitCode).toBe(2);
 
-		expect(process.stdout.write).toHaveBeenCalledTimes(2);
-		expect(process.stdout.write).toHaveBeenNthCalledWith(
-			1,
-			expect.stringContaining('needless disable: color-named'),
-		);
-		expect(process.stdout.write).toHaveBeenNthCalledWith(
-			2,
-			expect.stringContaining('Unexpected empty block'),
+		expect(process.stdout.write).toHaveBeenCalledTimes(1);
+		expect(process.stdout.write).toHaveBeenCalledWith(
+			expect.stringMatching(/Needless disable for "color-named".*Unexpected empty block/s),
 		);
 	});
 
@@ -253,9 +248,8 @@ describe('CLI', () => {
 		expect(process.exitCode).toBe(2);
 
 		expect(process.stdout.write).toHaveBeenCalledTimes(1);
-		expect(process.stdout.write).toHaveBeenNthCalledWith(
-			1,
-			expect.stringContaining('forbidden disable: block-no-empty'),
+		expect(process.stdout.write).toHaveBeenCalledWith(
+			expect.stringContaining('Rule "block-no-empty" may not be disabled'),
 		);
 	});
 
@@ -270,9 +264,8 @@ describe('CLI', () => {
 		expect(process.exitCode).toBe(2);
 
 		expect(process.stdout.write).toHaveBeenCalledTimes(1);
-		expect(process.stdout.write).toHaveBeenNthCalledWith(
-			1,
-			expect.stringContaining('descriptionless disable: block-no-empty'),
+		expect(process.stdout.write).toHaveBeenCalledWith(
+			expect.stringContaining('Disable for "block-no-empty" is missing a description'),
 		);
 	});
 

lib/__tests__/descriptionlessDisables.test.js

@@ -14,7 +14,7 @@ it('descriptionlessDisables', () => {
     /* stylelint-enable */
     a {
       b {} /* stylelint-disable-line block-no-empty -- Description */
-		}
+    }
     /* stylelint-disable-next-line block-no-empty
      * --
      * Description */
@@ -35,27 +35,34 @@ it('descriptionlessDisables', () => {
 		code: css,
 		reportDescriptionlessDisables: true,
 	}).then((linted) => {
-		const report = linted.descriptionlessDisables;
+		const results = linted.results;
+
+		expect(results).toHaveLength(1);
+		const warnings = results[0].warnings.filter(
+			(warning) => warning.rule === '--report-descriptionless-disables',
+		);
 
-		expect(report).toHaveLength(1);
-		expect(report[0].ranges).toEqual([
+		expect(warnings).toEqual([
 			{
-				start: 12,
-				end: 14,
-				rule: 'all',
-				unusedRule: 'all',
+				line: 12,
+				column: 1,
+				rule: '--report-descriptionless-disables',
+				severity: 'error',
+				text: 'Disable for "all" is missing a description',
 			},
 			{
-				start: 16,
-				end: 16,
-				rule: 'block-no-empty',
-				unusedRule: 'block-no-empty',
+				line: 16,
+				column: 8,
+				rule: '--report-descriptionless-disables',
+				severity: 'error',
+				text: 'Disable for "block-no-empty" is missing a description',
 			},
 			{
-				start: 19,
-				end: 19,
-				rule: 'block-no-empty',
-				unusedRule: 'block-no-empty',
+				line: 18,
+				column: 1,
+				rule: '--report-descriptionless-disables',
+				severity: 'error',
+				text: 'Disable for "block-no-empty" is missing a description',
 			},
 		]);
 	});