Add source diagnostic suppressions

Author: fabpot

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Suppress code-qualified diagnostics with source comments
 - Honor router request context parameters in route diagnostics
 - Report Symfony branches outside the live supported range
 - Ignore Twig macro declarations that share a name with custom functions

docs/features/headless-diagnostics.rst

@@ -180,6 +180,50 @@ with:
     $ symfony-lsp check --list-codes
     $ symfony-lsp check --format=json --list-codes
 
+Suppressing Intentional Diagnostics
+-----------------------------------
+
+When source code intentionally triggers a diagnostic, add a code-qualified
+suppression in a native PHP, Twig, YAML or XML comment. The editor and
+``symfony-lsp check`` apply the same suppressions:
+
+.. code-block:: php
+
+    /* @symfony-lsp-ignore template.not_found (intentional missing template) */
+    $this->render('test/does_not_exist.html.twig');
+
+.. code-block:: twig
+
+    {# @symfony-lsp-ignore template.not_found (intentional missing template) #}
+    {{ include('test/does_not_exist.html.twig') }}
+
+.. code-block:: yaml
+
+    # @symfony-lsp-ignore config.unknown_key (compatibility fixture)
+    framework:
+        unsupported_option: true
+
+.. code-block:: xml
+
+    <!-- @symfony-lsp-ignore config.unknown_key (compatibility fixture) -->
+    <framework:unsupported-option>true</framework:unsupported-option>
+
+A standalone comment targets diagnostics whose ranges start on the next
+physical line. A comment that shares a line with source code targets that line.
+Blank lines aren't skipped.
+
+The directive accepts a comma-separated list of exact diagnostic codes. Each
+listed code suppresses one occurrence, so repeat a code to suppress several
+matching diagnostics on the same line. An optional parenthesized reason can
+follow the codes. Bare directives, malformed directives and unknown codes
+produce a ``suppression.invalid`` warning instead of suppressing diagnostics.
+
+Only native comments are recognized. Directive-shaped text in strings, Twig
+verbatim content, YAML block scalars and XML CDATA sections has no effect.
+Suppressed diagnostics are omitted from editor publications and checker
+reports, and they aren't written to new baselines. A matching entry in an
+existing baseline becomes stale.
+
 Using a Baseline
 ----------------
 

resources/services.php

@@ -19,6 +19,7 @@
 use Symfony\Lsp\Feature\DiagnosticCollector;
 use Symfony\Lsp\Feature\DiagnosticProviderInterface;
 use Symfony\Lsp\Feature\DiagnosticProviderRegistry;
+use Symfony\Lsp\Feature\DiagnosticSuppressor;
 use Symfony\Lsp\Feature\Doctrine\DoctrineRelationshipCodeLensProvider;
 use Symfony\Lsp\Feature\DocumentLinkProviderInterface;
 use Symfony\Lsp\Feature\DocumentLinkProviderRegistry;
@@ -135,6 +136,7 @@
 
     $services->load('Symfony\\Lsp\\Feature\\', '../src/Feature/*Registry.php');
     $services->set(DiagnosticCollector::class);
+    $services->set(DiagnosticSuppressor::class);
     $featureGroups = [
         'Route' => [],
         'DependencyInjection' => [],

src/Check/BaselineCodec.php

@@ -3,6 +3,7 @@
 namespace Symfony\Lsp\Check;
 
 use Symfony\Component\Filesystem\Path;
+use Symfony\Lsp\Feature\DiagnosticCodeRegistry;
 use Symfony\Lsp\Project\InvalidConfigurationException;
 
 final class BaselineCodec

src/Check/CheckCommand.php

@@ -2,6 +2,7 @@
 
 namespace Symfony\Lsp\Check;
 
+use Symfony\Lsp\Feature\DiagnosticCodeRegistry;
 use Symfony\Lsp\Project\InvalidConfigurationException;
 use Symfony\Lsp\Server\SensitiveDataRedactor;
 

src/Check/CheckDiagnosticExecutor.php

@@ -6,6 +6,7 @@
 use Symfony\Lsp\Document\Document;
 use Symfony\Lsp\Document\DocumentStore;
 use Symfony\Lsp\Document\PositionConverter;
+use Symfony\Lsp\Feature\DiagnosticCodeRegistry;
 use Symfony\Lsp\Feature\DiagnosticCollector;
 use Symfony\Lsp\Index\ApplicationSourceScanner;
 use Symfony\Lsp\Project\ProjectConfiguration;

src/Check/CheckOptionsParser.php

@@ -2,6 +2,7 @@
 
 namespace Symfony\Lsp\Check;
 
+use Symfony\Lsp\Feature\DiagnosticCodeRegistry;
 use Symfony\Lsp\Project\AnalysisSettings;
 use Symfony\Lsp\Project\InvalidConfigurationException;
 

src/Check/SarifCheckReporter.php

@@ -2,6 +2,8 @@
 
 namespace Symfony\Lsp\Check;
 
+use Symfony\Lsp\Feature\DiagnosticCodeRegistry;
+
 final class SarifCheckReporter
 {
     private const SCHEMA = 'https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json';

src/Check/DiagnosticCodeRegistry.php src/Feature/DiagnosticCodeRegistry.phpsrc/Check/DiagnosticCodeRegistry.php renamed to src/Feature/DiagnosticCodeRegistry.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Symfony\Lsp\Check;
+namespace Symfony\Lsp\Feature;
 
 final class DiagnosticCodeRegistry
 {
@@ -28,6 +28,7 @@ final class DiagnosticCodeRegistry
         'security.unknown_provider',
         'service.not_found',
         'stimulus.unknown_controller',
+        'suppression.invalid',
         'template.not_found',
         'translation.domain_not_found',
         'translation.not_found',

src/Feature/DiagnosticCollector.php

@@ -18,6 +18,7 @@ public function __construct(
         private readonly ProjectPathResolver $pathResolver,
         private readonly ProjectFileScopeRegistry $fileScope,
         private readonly UriToPathConverter $uriToPathConverter,
+        private readonly DiagnosticSuppressor $suppressor,
         private readonly iterable $providers,
     ) {
     }
@@ -54,7 +55,9 @@ public function collect(array $params, bool $includeExcluded = false): ?array
             array_push($diagnostics, ...$providedDiagnostics);
         }
 
-        return $matched ? $diagnostics : null;
+        $diagnostics = $this->suppressor->suppress($document, $diagnostics);
+
+        return $matched || [] !== $diagnostics ? $diagnostics : null;
     }
 
     /**
@@ -105,7 +108,9 @@ public function collectDetailed(array $params, bool $includeExcluded = false): ?
             array_push($diagnostics, ...$provided);
         }
 
-        return new DetailedDiagnosticCollection($matched, $diagnostics, $failures);
+        $diagnostics = $this->suppressor->suppressCollected($document, $diagnostics);
+
+        return new DetailedDiagnosticCollection($matched || [] !== $diagnostics, $diagnostics, $failures);
     }
 
     private function collectedDiagnostic(string $provider, mixed $diagnostic): CollectedDiagnostic