Add yaml-lint-disable comment to suppress diagnostics per-line (redhat-developer#1189)

* Add yaml-lint-disable comment to suppress diagnostics per-line

* Update tests

* Rename yaml-lint-disable to yaml-language-server-disable

* Fix formatting

---------

Co-authored-by: Simon Heather <simon.heather@yulife.com>

Author: X-Guardian

README.md

@@ -56,6 +56,33 @@ The following settings are supported:
 - `yaml.style.flowSequence` : Forbids flow style sequences if set to `forbid`
 - `yaml.keyOrdering` : Enforces alphabetical ordering of keys in mappings when set to `true`. Default is `false`
 
+## Suppressing diagnostics
+
+You can suppress specific validation warnings on a per-line basis by adding a `# yaml-language-server-disable` comment on the line immediately before the one producing the diagnostic.
+
+### Suppress all diagnostics on a line
+
+```yaml
+# yaml-language-server-disable
+version: 123
+```
+
+### Suppress only specific diagnostics
+
+Provide one or more message substrings (comma-separated, case-insensitive). Only diagnostics whose message contains a matching substring will be suppressed; the rest are kept.
+
+```yaml
+# yaml-language-server-disable Incorrect type
+version: 123
+```
+
+```yaml
+# yaml-language-server-disable Incorrect type, not accepted
+version: 123
+```
+
+The substrings are matched against the diagnostic message text reported by the language server.
+
 ##### Adding custom tags
 
 In order to use the custom tags in your YAML file you need to first specify the custom tags in the setting of your code editor. For example, we can have the following custom tags:

src/languageservice/services/yamlValidation.ts

@@ -13,6 +13,7 @@ import { TextDocument } from 'vscode-languageserver-textdocument';
 import { JSONValidation } from 'vscode-json-languageservice/lib/umd/services/jsonValidation';
 import { YAML_SOURCE } from '../parser/schemaValidation/baseValidator';
 import { TextBuffer } from '../utils/textBuffer';
+import { filterSuppressedDiagnostics } from '../utils/diagnostic-filter';
 import { yamlDocumentsCache } from '../parser/yaml-documents';
 import { Telemetry } from '../telemetry';
 import { AdditionalValidator } from './validation/types';
@@ -152,7 +153,18 @@ export class YAMLValidation {
       }
     }
 
-    return duplicateMessagesRemoved;
+    const textBuffer = new TextBuffer(textDocument);
+    return filterSuppressedDiagnostics(
+      duplicateMessagesRemoved,
+      (d) => d.range.start.line,
+      (d) => d.message,
+      (line) => {
+        if (line < 0 || line >= textBuffer.getLineCount()) {
+          return undefined;
+        }
+        return textBuffer.getLineContent(line).replace(/[\r\n]+$/, '');
+      }
+    );
   }
   private runAdditionalValidators(document: TextDocument, yarnDoc: SingleYAMLDocument): Diagnostic[] {
     const result = [];

src/languageservice/utils/diagnostic-filter.ts

@@ -0,0 +1,96 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Red Hat, Inc. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+/**
+ * Pattern that matches a `# yaml-language-server-disable` comment.
+ *
+ * Usage in YAML files:
+ *
+ *   - `# yaml-language-server-disable` - suppress ALL diagnostics on the next line
+ *   - `# yaml-language-server-disable Incorrect type` - suppress diagnostics whose message contains "Incorrect type"
+ *   - `# yaml-language-server-disable Incorrect type, not accepted` - suppress diagnostics matching any of the substrings
+ *
+ * Capture group 1 (optional) contains the comma-separated list of message
+ * substrings to match against. If absent, all diagnostics are suppressed.
+ */
+export const YAML_DISABLE_PATTERN = /^\s*#\s*yaml-language-server-disable\b(.*)$/;
+
+/**
+ * A callback that returns the text content of a given zero-based line number,
+ * or `undefined` if the line does not exist.
+ */
+export type GetLineText = (line: number) => string | undefined;
+
+/**
+ * Parse the text after `yaml-language-server-disable` into an array of trimmed,
+ * lower-cased message substrings.  Returns an empty array when no
+ * specifiers are provided (meaning "suppress all").
+ */
+export function parseDisableSpecifiers(raw: string): string[] {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return [];
+  }
+  return trimmed
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Determine whether a diagnostic should be suppressed based on the
+ * specifiers from a `# yaml-language-server-disable` comment.
+ *
+ * @param specifiers - Parsed specifiers (empty means suppress all).
+ * @param diagnosticMessage - The diagnostic's message text.
+ * @returns `true` if the diagnostic should be suppressed.
+ */
+export function shouldSuppressDiagnostic(specifiers: string[], diagnosticMessage: string): boolean {
+  if (specifiers.length === 0) {
+    return true;
+  }
+  const lowerMessage = diagnosticMessage.toLowerCase();
+  return specifiers.some((spec) => lowerMessage.includes(spec));
+}
+
+/**
+ * Filters an array of diagnostics, removing any whose starting line is
+ * immediately preceded by a `# yaml-language-server-disable` comment.
+ *
+ * When the comment includes one or more comma-separated message substrings,
+ * only diagnostics whose message contains at least one of those substrings
+ * (case-insensitive) are suppressed.  Without specifiers, all diagnostics
+ * on the next line are suppressed.
+ *
+ * @param diagnostics - The diagnostics to filter.
+ * @param getStartLine - Extracts the zero-based starting line number from a diagnostic.
+ * @param getMessage - Extracts the message string from a diagnostic.
+ * @param getLineText - Returns the text of a document line by its zero-based index,
+ *   or `undefined` if the line is out of range.
+ * @returns A new array containing only the diagnostics that are not suppressed.
+ */
+export function filterSuppressedDiagnostics<T>(
+  diagnostics: T[],
+  getStartLine: (diag: T) => number,
+  getMessage: (diag: T) => string,
+  getLineText: GetLineText
+): T[] {
+  return diagnostics.filter((diag) => {
+    const line = getStartLine(diag);
+    if (line === 0) {
+      return true;
+    }
+    const prevLineText = getLineText(line - 1);
+    if (prevLineText === undefined) {
+      return true;
+    }
+    const match = YAML_DISABLE_PATTERN.exec(prevLineText);
+    if (!match) {
+      return true;
+    }
+    const specifiers = parseDisableSpecifiers(match[1]);
+    return !shouldSuppressDiagnostic(specifiers, getMessage(diag));
+  });
+}

test/diagnostic-filter.test.ts

@@ -0,0 +1,227 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Red Hat, Inc. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { expect } from 'chai';
+import {
+  filterSuppressedDiagnostics,
+  YAML_DISABLE_PATTERN,
+  parseDisableSpecifiers,
+  shouldSuppressDiagnostic,
+  GetLineText,
+} from '../src/languageservice/utils/diagnostic-filter';
+
+function makeDiag(startLine: number, message: string): { startLine: number; message: string } {
+  return { startLine, message };
+}
+
+function linesOf(lines: string[]): GetLineText {
+  return (line: number) => (line >= 0 && line < lines.length ? lines[line] : undefined);
+}
+
+describe('YAML_DISABLE_PATTERN', () => {
+  it('should capture specifiers in group 1', () => {
+    const match = YAML_DISABLE_PATTERN.exec('# yaml-language-server-disable Incorrect type, not accepted');
+    expect(match).to.not.be.null;
+    expect(match[1].trim()).to.equal('Incorrect type, not accepted');
+  });
+
+  it('should capture empty group 1 when no specifiers given', () => {
+    const match = YAML_DISABLE_PATTERN.exec('# yaml-language-server-disable');
+    expect(match).to.not.be.null;
+    expect(match[1].trim()).to.equal('');
+  });
+});
+
+describe('parseDisableSpecifiers', () => {
+  it('should return empty array for empty string', () => {
+    expect(parseDisableSpecifiers('')).to.deep.equal([]);
+  });
+
+  it('should return empty array for whitespace-only string', () => {
+    expect(parseDisableSpecifiers('   ')).to.deep.equal([]);
+  });
+
+  it('should parse a single specifier', () => {
+    expect(parseDisableSpecifiers('Incorrect type')).to.deep.equal(['incorrect type']);
+  });
+
+  it('should parse comma-separated specifiers', () => {
+    expect(parseDisableSpecifiers('Incorrect type, not accepted')).to.deep.equal(['incorrect type', 'not accepted']);
+  });
+
+  it('should trim whitespace around specifiers', () => {
+    expect(parseDisableSpecifiers('  foo ,  bar  ')).to.deep.equal(['foo', 'bar']);
+  });
+
+  it('should ignore empty entries from trailing commas', () => {
+    expect(parseDisableSpecifiers('foo,')).to.deep.equal(['foo']);
+  });
+
+  it('should lower-case all specifiers', () => {
+    expect(parseDisableSpecifiers('Value Is NOT Accepted')).to.deep.equal(['value is not accepted']);
+  });
+});
+
+describe('shouldSuppressDiagnostic', () => {
+  it('should suppress when specifiers is empty (suppress all)', () => {
+    expect(shouldSuppressDiagnostic([], 'any message')).to.be.true;
+  });
+
+  it('should suppress when message contains the specifier (case-insensitive)', () => {
+    expect(shouldSuppressDiagnostic(['incorrect type'], 'Incorrect type. Expected string.')).to.be.true;
+  });
+
+  it('should not suppress when message does not contain the specifier', () => {
+    expect(shouldSuppressDiagnostic(['not accepted'], 'Incorrect type. Expected string.')).to.be.false;
+  });
+
+  it('should suppress when any of multiple specifiers matches', () => {
+    expect(shouldSuppressDiagnostic(['not accepted', 'incorrect type'], 'Incorrect type. Expected string.')).to.be.true;
+  });
+
+  it('should not suppress when none of multiple specifiers match', () => {
+    expect(shouldSuppressDiagnostic(['not accepted', 'missing property'], 'Incorrect type. Expected string.')).to.be.false;
+  });
+});
+
+describe('filterSuppressedDiagnostics', () => {
+  const filter = (diagnostics: ReturnType<typeof makeDiag>[], lines: GetLineText): ReturnType<typeof makeDiag>[] =>
+    filterSuppressedDiagnostics(
+      diagnostics,
+      (d) => d.startLine,
+      (d) => d.message,
+      lines
+    );
+
+  it('should return all diagnostics when there are no suppression comments', () => {
+    const lines = linesOf(['key: value', 'other: 123']);
+    const diagnostics = [makeDiag(0, 'error on line 0'), makeDiag(1, 'error on line 1')];
+
+    const result = filter(diagnostics, lines);
+
+    expect(result).to.have.length(2);
+  });
+
+  it('should suppress all diagnostics when no specifiers are given', () => {
+    const lines = linesOf(['name: hello', '# yaml-language-server-disable', 'age: not-a-number']);
+    const diagnostics = [makeDiag(2, 'Incorrect type'), makeDiag(2, 'Value not accepted')];
+
+    const result = filter(diagnostics, lines);
+
+    expect(result).to.be.empty;
+  });
+
+  it('should suppress only matching diagnostics when specifiers are given', () => {
+    const lines = linesOf(['name: hello', '# yaml-language-server-disable Incorrect type', 'age: not-a-number']);
+    const diagnostics = [makeDiag(2, 'Incorrect type. Expected string.'), makeDiag(2, 'Value is not accepted.')];
+
+    const result = filter(diagnostics, lines);
+
+    expect(result).to.have.length(1);
+    expect(result[0].message).to.equal('Value is not accepted.');
+  });
+
+  it('should suppress diagnostics matching any of multiple comma-separated specifiers', () => {
+    const lines = linesOf(['# yaml-language-server-disable Incorrect type, not accepted', 'key: bad']);
+    const diagnostics = [
+      makeDiag(1, 'Incorrect type. Expected string.'),
+      makeDiag(1, 'Value is not accepted.'),
+      makeDiag(1, 'Missing required property "name".'),
+    ];
+
+    const result = filter(diagnostics, lines);
+
+    expect(result).to.have.length(1);
+    expect(result[0].message).to.equal('Missing required property "name".');
+  });
+
+  it('should match specifiers case-insensitively', () => {
+    const lines = linesOf(['# yaml-language-server-disable incorrect TYPE', 'key: bad']);
+    const diagnostics = [makeDiag(1, 'Incorrect type. Expected string.')];
+
+    const result = filter(diagnostics, lines);
+
+    expect(result).to.be.empty;
+  });
+
+  it('should keep diagnostics on lines NOT preceded by a disable comment', () => {
+    const lines = linesOf(['name: hello', '# yaml-language-server-disable', 'age: bad', 'score: bad']);
+    const diagnostics = [makeDiag(2, 'error on line 2'), makeDiag(3, 'error on line 3')];
+
+    const result = filter(diagnostics, lines);
+
+    expect(result).to.have.length(1);
+    expect(result[0].message).to.equal('error on line 3');
+  });
+
+  it('should not filter a diagnostic on line 0 (no preceding line)', () => {
+    const lines = linesOf(['bad: value']);
+    const diagnostics = [makeDiag(0, 'error on first line')];
+
+    const result = filter(diagnostics, lines);
+
+    expect(result).to.have.length(1);
+  });
+
+  it('should handle indented disable comments', () => {
+    const lines = linesOf(['root:', '  # yaml-language-server-disable', '  child: bad-value']);
+    const diagnostics = [makeDiag(2, 'invalid value')];
+
+    const result = filter(diagnostics, lines);
+
+    expect(result).to.be.empty;
+  });
+
+  it('should not suppress when the disable comment is two lines above', () => {
+    const lines = linesOf(['# yaml-language-server-disable', 'good: value', 'bad: value']);
+    const diagnostics = [makeDiag(2, 'error on line 2')];
+
+    const result = filter(diagnostics, lines);
+
+    expect(result).to.have.length(1);
+  });
+
+  it('should handle multiple disable comments for different lines', () => {
+    const lines = linesOf([
+      '# yaml-language-server-disable',
+      'line1: bad',
+      'line2: ok',
+      '# yaml-language-server-disable',
+      'line4: also-bad',
+    ]);
+    const diagnostics = [makeDiag(1, 'error on line 1'), makeDiag(2, 'error on line 2'), makeDiag(4, 'error on line 4')];
+
+    const result = filter(diagnostics, lines);
+
+    expect(result).to.have.length(1);
+    expect(result[0].message).to.equal('error on line 2');
+  });
+
+  it('should return all diagnostics when the document cannot be read', () => {
+    const noDocument: GetLineText = () => undefined;
+    const diagnostics = [makeDiag(1, 'some error')];
+
+    const result = filter(diagnostics, noDocument);
+
+    expect(result).to.have.length(1);
+  });
+
+  it('should return an empty array when given no diagnostics', () => {
+    const lines = linesOf(['# yaml-language-server-disable', 'key: value']);
+
+    const result = filter([], lines);
+
+    expect(result).to.be.empty;
+  });
+
+  it('should not treat a non-comment line containing the keyword as suppression', () => {
+    const lines = linesOf(['key: yaml-language-server-disable', 'other: bad']);
+    const diagnostics = [makeDiag(1, 'error on line 1')];
+
+    const result = filter(diagnostics, lines);
+
+    expect(result).to.have.length(1);
+  });
+});