Add the deprecation-handling Sass options

doc/index.rst

@@ -283,6 +283,18 @@ You can configure most of the `Dart Sass CLI options <https://sass-lang.com/docu
             # Don't print deprecated warnings for dependencies. Defaults to false.
             # quiet_deps:
 
+            # Print all deprecation warnings even when they're repetitive. Defaults to false.
+            # verbose:
+
+            # Deprecations to treat as errors. Defaults to empty array.
+            # fatal_deprecation: []
+
+            # Opt in to a deprecation early. Defaults to empty array.
+            # future_deprecation: []
+
+            # Deprecations to ignore. Requires Dart Sass 1.74.0 or higher. Defaults to empty array.
+            # silence_deprecation: []
+
             # Don't compile more files once an error is encountered. Defaults to false.
             # stop_on_error:
 
@@ -330,3 +342,34 @@ And then import bootstrap from ``app.scss`` with:
 .. code-block:: scss
 
     @import 'bootstrap';
+
+Handling Deprecations
+---------------------
+
+Sass announces breaking changes through `deprecations <https://sass-lang.com/documentation/breaking-changes>`_.
+Each one has an ID (such as ``import`` or ``color-functions``) that you can act on:
+
+.. code-block:: yaml
+
+    # config/packages/symfonycasts_sass.yaml
+    symfonycasts_sass:
+        sass_options:
+            # turn these deprecation warnings into errors, so they can't be ignored
+            fatal_deprecation:
+                - 'import'
+
+            # opt in to a deprecation before it is active, to prepare for it
+            future_deprecation:
+                - 'import'
+
+            # hide these deprecation warnings entirely
+            silence_deprecation:
+                - 'color-functions'
+
+Silencing the warnings coming from your dependencies - instead of a specific deprecation -
+is done with ``quiet_deps``.
+
+.. note::
+
+    ``silence_deprecation`` requires Dart Sass 1.74.0 or higher, which is more recent than
+    the binary this bundle downloads by default. See `Using a different binary`_.

src/DependencyInjection/SymfonycastsSassExtension.php

@@ -127,6 +127,24 @@ public function getConfigTreeBuilder(): TreeBuilder
                         ->booleanNode('quiet_deps')
                             ->info(' Don\'t print compiler warnings from dependencies.')
                         ->end()
+                        ->booleanNode('verbose')
+                            ->info('Print all deprecation warnings even when they\'re repetitive.')
+                        ->end()
+                        ->arrayNode('fatal_deprecation')
+                            ->info('Deprecations to treat as errors. You may also pass a Sass version to include any behavior deprecated in or before it.')
+                            ->scalarPrototype()
+                                ->end()
+                        ->end()
+                        ->arrayNode('future_deprecation')
+                            ->info('Opt in to a deprecation early.')
+                            ->scalarPrototype()
+                                ->end()
+                        ->end()
+                        ->arrayNode('silence_deprecation')
+                            ->info('Deprecations to ignore. Requires the Sass binary to be at least 1.74.0.')
+                            ->scalarPrototype()
+                                ->end()
+                        ->end()
                         ->booleanNode('stop_on_error')
                             ->info('Don\'t compile more files once an error is encountered.')
                         ->end()

src/SassBuilder.php

@@ -34,6 +34,10 @@ class SassBuilder
         // Warnings
         '--[no-]quiet' => null,                 // Don't print warnings.
         '--[no-]quiet-deps' => null,            // Don't print deprecation warnings for dependencies.
+        '--[no-]verbose' => null,               // Print all deprecation warnings even when they're repetitive.
+        '--fatal-deprecation' => null,          // Deprecations to treat as errors.
+        '--future-deprecation' => null,         // Opt in to a deprecation early.
+        '--silence-deprecation' => null,        // Deprecations to ignore.
         // Other
         '--[no-]stop-on-error' => null,         // Don't compile more files once an error is encountered.
         '--[no-]trace' => null,                 // Print full Dart stack traces for exceptions.
@@ -42,13 +46,13 @@ class SassBuilder
     private ?SymfonyStyle $output = null;
 
     /**
-     * @var array<string, bool|string>
+     * @var array<string, bool|string|list<string>>
      */
     private array $sassOptions;
 
     /**
-     * @param array<string>              $sassPaths
-     * @param array<string, bool|string> $sassOptions
+     * @param array<string>                           $sassPaths
+     * @param array<string, bool|string|list<string>> $sassOptions
      */
     public function __construct(
         private readonly array $sassPaths,

tests/ConfigurationTest.php

@@ -69,6 +69,10 @@ public function testSassOptionsAreSet(): void
                     'load_path' => ['foo'],
                     'quiet' => true,
                     'quiet_deps' => true,
+                    'verbose' => true,
+                    'fatal_deprecation' => ['import', 'global-builtin'],
+                    'future_deprecation' => ['import'],
+                    'silence_deprecation' => ['color-functions'],
                     'stop_on_error' => true,
                     'trace' => true,
                 ],
@@ -86,6 +90,10 @@ public function testSassOptionsAreSet(): void
                     'load_path' => [],
                     'quiet' => false,
                     'quiet_deps' => false,
+                    'verbose' => false,
+                    'fatal_deprecation' => [],
+                    'future_deprecation' => [],
+                    'silence_deprecation' => [],
                     'stop_on_error' => false,
                     'trace' => false,
                 ],
@@ -107,6 +115,10 @@ public function testSassOptionsAreNullable(): void
                     'load_path' => null,
                     'quiet' => null,
                     'quiet_deps' => null,
+                    'verbose' => null,
+                    'fatal_deprecation' => null,
+                    'future_deprecation' => null,
+                    'silence_deprecation' => null,
                     'stop_on_error' => null,
                     'trace' => null,
                 ],

tests/SassBuilderTest.php

@@ -198,6 +198,26 @@ public function testSassOptionQuiet(): void
         $this->assertStringContainsString('WARNING', $process->getErrorOutput());
     }
 
+    public function testSassOptionDeprecations(): void
+    {
+        // "@import" is not deprecated yet: opting into the deprecation early only warns...
+        $process = $this->createBuilder('file_with_deprecation.scss', [
+            'future_deprecation' => ['import'],
+        ])->runBuild(false);
+        $process->wait();
+        $this->assertTrue($process->isSuccessful());
+        $this->assertStringContainsString('DEPRECATION WARNING', $process->getErrorOutput());
+
+        // ...unless that deprecation is also treated as an error.
+        $process = $this->createBuilder('file_with_deprecation.scss', [
+            'future_deprecation' => ['import'],
+            'fatal_deprecation' => ['import'],
+        ])->runBuild(false);
+        $process->wait();
+        $this->assertFalse($process->isSuccessful());
+        $this->assertStringContainsString('Error: Sass @import rules will be deprecated', $process->getErrorOutput());
+    }
+
     public function testSearchForBinary(): void
     {
         $builder = new SassBuilder(
@@ -313,5 +333,23 @@ public static function provideSassPhpOptions()
                 '--load-path=bar',
             ],
         ];
+        yield 'Deprecation options are expanded' => [
+            [
+                'style' => null,
+                'source_map' => null,
+                'verbose' => true,
+                'fatal_deprecation' => ['import', 'global-builtin'],
+                'future_deprecation' => ['import'],
+                'silence_deprecation' => ['import', 'color-functions'],
+            ],
+            [
+                '--verbose',
+                '--fatal-deprecation=import',
+                '--fatal-deprecation=global-builtin',
+                '--future-deprecation=import',
+                '--silence-deprecation=import',
+                '--silence-deprecation=color-functions',
+            ],
+        ];
     }
 }

tests/fixtures/assets/file_with_deprecation.scss

@@ -0,0 +1,5 @@
+@import "tokens";
+
+p {
+  color: $color-a;
+}