feat: add setting to control when linter runs (#848)

Co-authored-by: Richard Hallows <jeddy3@users.noreply.github.com>

Author: adalinesimonian

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Added: `stylelint.run` setting to control when the linter runs ([#848](https://github.com/stylelint/vscode-stylelint/issues/848)).
 - Added: notification prompting to restart the extension host when `stylelint.logLevel` setting changes ([#849](https://github.com/stylelint/vscode-stylelint/pull/849)).
 - Added: warning when `stylelint.config` is an empty object ([#846](https://github.com/stylelint/vscode-stylelint/pull/846)).
 

README.md

@@ -134,6 +134,16 @@ Though relying on a [Stylelint configuration file](https://stylelint.io/user-gui
 
 Controls whether this extension is enabled or not.
 
+#### `stylelint.run`
+
+> Type: `"onSave" | "onType"`  
+> Default: `"onType"`
+
+Controls when the linter runs.
+
+- `onType`: Runs on each change as you type.
+- `onSave`: Only runs after you save a document.
+
 #### `stylelint.logLevel`
 
 > Type: `"error" | "warn" | "info" | "debug"`  

package.json

@@ -56,6 +56,16 @@
           "default": true,
           "description": "Control whether Stylelint is enabled or not."
         },
+        "stylelint.run": {
+          "scope": "resource",
+          "type": "string",
+          "enum": [
+            "onSave",
+            "onType"
+          ],
+          "default": "onType",
+          "description": "Control when the extension lints your files. onType lints files as you edit them, while onSave only lints when you save the file."
+        },
         "stylelint.logLevel": {
           "scope": "machine",
           "type": "string",

src/server/config/default-options.ts

@@ -17,6 +17,7 @@ export const defaultLanguageServerOptions: LanguageServerOptions = {
 	reportDescriptionlessDisables: false,
 	reportInvalidScopeDisables: false,
 	reportNeedlessDisables: false,
+	run: 'onType',
 	rules: {
 		customizations: [],
 	},

src/server/services/lsp/__tests__/validator.service.test.ts

@@ -312,4 +312,75 @@ describe('ValidatorLspModule', () => {
 			{ uri: document.uri, diagnostics: lintDiagnostics },
 		]);
 	});
+
+	describe('run mode', () => {
+		it('handleDocumentOpened should always validate', async () => {
+			const document = setDocument();
+			const lintDiagnostics = [createDiagnostic('lint')];
+
+			options.setValidateLanguages(['css']);
+			options.setRunMode('onSave');
+			runner.setLintResult(document.uri, createDiagnosticsResult(lintDiagnostics));
+
+			await service.handleDocumentOpened(createChangeEvent(document));
+
+			expect(connection.sendDiagnosticsCalls).toEqual([
+				{ uri: document.uri, diagnostics: lintDiagnostics },
+			]);
+		});
+
+		it('handleDocumentChanged should skip validation when run is onSave', async () => {
+			const document = setDocument();
+
+			options.setValidateLanguages(['css']);
+			options.setRunMode('onSave');
+			runner.setLintResult(document.uri, createDiagnosticsResult([createDiagnostic('lint')]));
+
+			await service.handleDocumentChanged(createChangeEvent(document));
+
+			expect(runner.lintCalls).toHaveLength(0);
+		});
+
+		it('handleDocumentChanged should validate when run is onType', async () => {
+			const document = setDocument();
+			const lintDiagnostics = [createDiagnostic('lint')];
+
+			options.setValidateLanguages(['css']);
+			options.setRunMode('onType');
+			runner.setLintResult(document.uri, createDiagnosticsResult(lintDiagnostics));
+
+			await service.handleDocumentChanged(createChangeEvent(document));
+
+			expect(connection.sendDiagnosticsCalls).toEqual([
+				{ uri: document.uri, diagnostics: lintDiagnostics },
+			]);
+		});
+
+		it('handleDocumentSaved should validate when run is onSave', async () => {
+			const document = setDocument();
+			const lintDiagnostics = [createDiagnostic('lint')];
+
+			options.setValidateLanguages(['css']);
+			options.setRunMode('onSave');
+			runner.setLintResult(document.uri, createDiagnosticsResult(lintDiagnostics));
+
+			await service.handleDocumentSaved(createChangeEvent(document));
+
+			expect(connection.sendDiagnosticsCalls).toEqual([
+				{ uri: document.uri, diagnostics: lintDiagnostics },
+			]);
+		});
+
+		it('handleDocumentSaved should skip validation when run is onType', async () => {
+			const document = setDocument();
+
+			options.setValidateLanguages(['css']);
+			options.setRunMode('onType');
+			runner.setLintResult(document.uri, createDiagnosticsResult([createDiagnostic('lint')]));
+
+			await service.handleDocumentSaved(createChangeEvent(document));
+
+			expect(runner.lintCalls).toHaveLength(0);
+		});
+	});
 });

src/server/services/lsp/validator.service.ts

@@ -56,9 +56,27 @@ export class ValidatorLspService {
 		void this.#validateAll();
 	}
 
+	@textDocumentEvent('onDidOpen')
+	async handleDocumentOpened({ document }: TextDocumentChangeEvent<TextDocument>): Promise<void> {
+		await this.#validate(document);
+	}
+
 	@textDocumentEvent('onDidChangeContent')
 	async handleDocumentChanged({ document }: TextDocumentChangeEvent<TextDocument>): Promise<void> {
-		await this.#validate(document);
+		const options = await this.#options.getOptions(document.uri);
+
+		if (options.run === 'onType') {
+			await this.#validate(document);
+		}
+	}
+
+	@textDocumentEvent('onDidSave')
+	async handleDocumentSaved({ document }: TextDocumentChangeEvent<TextDocument>): Promise<void> {
+		const options = await this.#options.getOptions(document.uri);
+
+		if (options.run === 'onSave') {
+			await this.#validate(document);
+		}
 	}
 
 	@textDocumentEvent('onDidClose')

src/server/types.ts

@@ -71,6 +71,12 @@ export interface DidRegisterDocumentFormattingEditProviderNotificationParams {
 	readonly options: LSP.DocumentFormattingRegistrationOptions;
 }
 
+/**
+ * Run mode for the linter. `onType` lints as you type, while `onSave` only
+ * lints after saving a document.
+ */
+export type RunMode = 'onSave' | 'onType';
+
 /**
  * Language server options.
  */
@@ -89,6 +95,7 @@ export type LanguageServerOptions = {
 	reportDescriptionlessDisables?: boolean;
 	reportInvalidScopeDisables?: boolean;
 	reportNeedlessDisables?: boolean;
+	run: RunMode;
 	rules?: {
 		customizations?: RuleCustomization[];
 	};

test/e2e/__tests__/run.test.ts

@@ -0,0 +1,50 @@
+import * as assert from 'node:assert/strict';
+
+import {
+	openDocument,
+	closeAllEditors,
+	restoreFile,
+	waitForDiagnostics,
+	assertDiagnostics,
+	waitForDiagnosticsLength,
+} from '../helpers.js';
+
+import { Range, Position } from 'vscode';
+
+describe('"stylelint.run" setting', () => {
+	describe('when set to "onSave"', () => {
+		restoreFile('run/test.css');
+
+		afterEach(async () => {
+			await closeAllEditors();
+		});
+
+		it('should not lint on type, but should lint on save', async () => {
+			const editor = await openDocument('run/test.css');
+
+			const initialDiagnostics = await waitForDiagnostics(editor);
+
+			assertDiagnostics(initialDiagnostics, [
+				{
+					code: 'color-hex-length',
+					codeDescription: 'https://stylelint.io/user-guide/rules/color-hex-length',
+					message: 'Expected "#fff" to be "#ffffff" (color-hex-length)',
+					range: [2, 9, 2, 13],
+					severity: 'error',
+				},
+			]);
+
+			const success = await editor.edit((editBuilder) => {
+				editBuilder.replace(new Range(new Position(2, 9), new Position(2, 13)), '#ffffff');
+			});
+
+			assert.ok(success, 'Edit should succeed');
+
+			await waitForDiagnosticsLength(editor.document.uri, 1);
+
+			await editor.document.save();
+
+			await waitForDiagnosticsLength(editor.document.uri, 0);
+		});
+	});
+});

test/e2e/workspace/run/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+	"stylelint.run": "onSave"
+}

test/e2e/workspace/run/stylelint.config.js

@@ -0,0 +1,10 @@
+'use strict';
+
+/** @type {import('stylelint').Config} */
+const config = {
+	rules: {
+		'color-hex-length': 'long',
+	},
+};
+
+module.exports = config;