Complete implementation the deprecations API (#2207)

CHANGELOG.md

@@ -1,3 +1,48 @@
+## 1.74.0
+
+### JS API
+
+* Add a new top-level `deprecations` object, which contains various
+  `Deprecation` objects that define the different types of deprecation used by
+  the Sass compiler and can be passed to the options below.
+
+* Add a new `fatalDeprecations` compiler option that causes the compiler to
+  error if any deprecation warnings of the provided types are encountered. You
+  can also pass in a `Version` object to treat all deprecations that were active
+  in that Dart Sass version as fatal.
+
+* Add a new `futureDeprecations` compiler option that allows you to opt-in to
+  certain deprecations early (currently just `import`).
+
+* Add a new `silenceDeprecations` compiler option to ignore any deprecation
+  warnings of the provided types.
+
+### Command-Line Interface
+
+* Add a new `--silence-deprecation` flag, which causes the compiler to ignore
+  any deprecation warnings of the provided types.
+
+* Previously, if a future deprecation was passed to `--fatal-deprecation` but
+  not `--future-deprecation`, it would be treated as fatal despite not being
+  enabled. Both flags are now required to treat a future deprecation as fatal
+  with a warning emitted if `--fatal-deprecation` is passed without
+  `--future-deprecation`, matching the JS API's behavior.
+
+### Dart API
+
+* The `compile` methods now take in a `silenceDeprecations` parameter, which
+  causes the compiler to ignore any deprecation warnings of the provided types.
+
+* Add `Deprecation.obsoleteIn` to match the JS API. This is currently null for
+  all deprecations, but will be used once some deprecations become obsolete in
+  Dart Sass 2.0.0.
+
+* **Potentially breaking bug fix:** Fix a bug where `compileStringToResultAsync`
+  ignored `fatalDeprecations` and `futureDeprecations`.
+
+* The behavior around making future deprecations fatal mentioned in the CLI
+  section above has also been changed in the Dart API.
+
 ## 1.73.0
 
 * Add support for nesting in plain CSS files. This is not processed by Sass at

bin/sass.dart

@@ -15,7 +15,7 @@ import 'package:sass/src/executable/watch.dart';
 import 'package:sass/src/import_cache.dart';
 import 'package:sass/src/importer/filesystem.dart';
 import 'package:sass/src/io.dart';
-import 'package:sass/src/logger/deprecation_handling.dart';
+import 'package:sass/src/logger/deprecation_processing.dart';
 import 'package:sass/src/stylesheet_graph.dart';
 import 'package:sass/src/utils.dart';
 import 'package:sass/src/embedded/executable.dart'
@@ -53,7 +53,8 @@ Future<void> main(List<String> args) async {
         // limit repetition. A separate DeprecationHandlingLogger is created for
         // each compilation, which will limit repetition if verbose is not
         // passed in addition to handling fatal/future deprecations.
-        logger: DeprecationHandlingLogger(options.logger,
+        logger: DeprecationProcessingLogger(options.logger,
+            silenceDeprecations: options.silenceDeprecations,
             fatalDeprecations: options.fatalDeprecations,
             futureDeprecations: options.futureDeprecations,
             limitRepetition: false)));

lib/sass.dart

@@ -108,6 +108,7 @@ CompileResult compileToResult(String path,
         bool verbose = false,
         bool sourceMap = false,
         bool charset = true,
+        Iterable<Deprecation>? silenceDeprecations,
         Iterable<Deprecation>? fatalDeprecations,
         Iterable<Deprecation>? futureDeprecations}) =>
     c.compile(path,
@@ -123,6 +124,7 @@ CompileResult compileToResult(String path,
         verbose: verbose,
         sourceMap: sourceMap,
         charset: charset,
+        silenceDeprecations: silenceDeprecations,
         fatalDeprecations: fatalDeprecations,
         futureDeprecations: futureDeprecations);
 
@@ -207,6 +209,7 @@ CompileResult compileStringToResult(String source,
         bool verbose = false,
         bool sourceMap = false,
         bool charset = true,
+        Iterable<Deprecation>? silenceDeprecations,
         Iterable<Deprecation>? fatalDeprecations,
         Iterable<Deprecation>? futureDeprecations}) =>
     c.compileString(source,
@@ -225,6 +228,7 @@ CompileResult compileStringToResult(String source,
         verbose: verbose,
         sourceMap: sourceMap,
         charset: charset,
+        silenceDeprecations: silenceDeprecations,
         fatalDeprecations: fatalDeprecations,
         futureDeprecations: futureDeprecations);
 
@@ -245,6 +249,7 @@ Future<CompileResult> compileToResultAsync(String path,
         bool verbose = false,
         bool sourceMap = false,
         bool charset = true,
+        Iterable<Deprecation>? silenceDeprecations,
         Iterable<Deprecation>? fatalDeprecations,
         Iterable<Deprecation>? futureDeprecations}) =>
     c.compileAsync(path,
@@ -260,6 +265,7 @@ Future<CompileResult> compileToResultAsync(String path,
         verbose: verbose,
         sourceMap: sourceMap,
         charset: charset,
+        silenceDeprecations: silenceDeprecations,
         fatalDeprecations: fatalDeprecations,
         futureDeprecations: futureDeprecations);
 
@@ -285,6 +291,7 @@ Future<CompileResult> compileStringToResultAsync(String source,
         bool verbose = false,
         bool sourceMap = false,
         bool charset = true,
+        Iterable<Deprecation>? silenceDeprecations,
         Iterable<Deprecation>? fatalDeprecations,
         Iterable<Deprecation>? futureDeprecations}) =>
     c.compileStringAsync(source,
@@ -302,7 +309,10 @@ Future<CompileResult> compileStringToResultAsync(String source,
         quietDeps: quietDeps,
         verbose: verbose,
         sourceMap: sourceMap,
-        charset: charset);
+        charset: charset,
+        silenceDeprecations: silenceDeprecations,
+        fatalDeprecations: fatalDeprecations,
+        futureDeprecations: futureDeprecations);
 
 /// Like [compileToResult], but returns [CompileResult.css] rather than
 /// returning [CompileResult] directly.

lib/src/async_compile.dart

@@ -17,7 +17,7 @@ import 'importer/legacy_node.dart';
 import 'importer/no_op.dart';
 import 'io.dart';
 import 'logger.dart';
-import 'logger/deprecation_handling.dart';
+import 'logger/deprecation_processing.dart';
 import 'syntax.dart';
 import 'utils.dart';
 import 'visitor/async_evaluate.dart';
@@ -42,10 +42,12 @@ Future<CompileResult> compileAsync(String path,
     bool verbose = false,
     bool sourceMap = false,
     bool charset = true,
+    Iterable<Deprecation>? silenceDeprecations,
     Iterable<Deprecation>? fatalDeprecations,
     Iterable<Deprecation>? futureDeprecations}) async {
-  DeprecationHandlingLogger deprecationLogger = logger =
-      DeprecationHandlingLogger(logger ?? Logger.stderr(),
+  DeprecationProcessingLogger deprecationLogger = logger =
+      DeprecationProcessingLogger(logger ?? Logger.stderr(),
+          silenceDeprecations: {...?silenceDeprecations},
           fatalDeprecations: {...?fatalDeprecations},
           futureDeprecations: {...?futureDeprecations},
           limitRepetition: !verbose);
@@ -106,10 +108,12 @@ Future<CompileResult> compileStringAsync(String source,
     bool verbose = false,
     bool sourceMap = false,
     bool charset = true,
+    Iterable<Deprecation>? silenceDeprecations,
     Iterable<Deprecation>? fatalDeprecations,
     Iterable<Deprecation>? futureDeprecations}) async {
-  DeprecationHandlingLogger deprecationLogger = logger =
-      DeprecationHandlingLogger(logger ?? Logger.stderr(),
+  DeprecationProcessingLogger deprecationLogger = logger =
+      DeprecationProcessingLogger(logger ?? Logger.stderr(),
+          silenceDeprecations: {...?silenceDeprecations},
           fatalDeprecations: {...?fatalDeprecations},
           futureDeprecations: {...?futureDeprecations},
           limitRepetition: !verbose);

lib/src/compile.dart

@@ -5,7 +5,7 @@
 // DO NOT EDIT. This file was generated from async_compile.dart.
 // See tool/grind/synchronize.dart for details.
 //
-// Checksum: a9421a2975e79ad591ae32474cd076e1379d0e75
+// Checksum: ab2c6fa2588988a86abdbe87512134098e01b39e
 //
 // ignore_for_file: unused_import
 
@@ -26,7 +26,7 @@ import 'importer/legacy_node.dart';
 import 'importer/no_op.dart';
 import 'io.dart';
 import 'logger.dart';
-import 'logger/deprecation_handling.dart';
+import 'logger/deprecation_processing.dart';
 import 'syntax.dart';
 import 'utils.dart';
 import 'visitor/evaluate.dart';
@@ -51,10 +51,12 @@ CompileResult compile(String path,
     bool verbose = false,
     bool sourceMap = false,
     bool charset = true,
+    Iterable<Deprecation>? silenceDeprecations,
     Iterable<Deprecation>? fatalDeprecations,
     Iterable<Deprecation>? futureDeprecations}) {
-  DeprecationHandlingLogger deprecationLogger = logger =
-      DeprecationHandlingLogger(logger ?? Logger.stderr(),
+  DeprecationProcessingLogger deprecationLogger = logger =
+      DeprecationProcessingLogger(logger ?? Logger.stderr(),
+          silenceDeprecations: {...?silenceDeprecations},
           fatalDeprecations: {...?fatalDeprecations},
           futureDeprecations: {...?futureDeprecations},
           limitRepetition: !verbose);
@@ -115,10 +117,12 @@ CompileResult compileString(String source,
     bool verbose = false,
     bool sourceMap = false,
     bool charset = true,
+    Iterable<Deprecation>? silenceDeprecations,
     Iterable<Deprecation>? fatalDeprecations,
     Iterable<Deprecation>? futureDeprecations}) {
-  DeprecationHandlingLogger deprecationLogger = logger =
-      DeprecationHandlingLogger(logger ?? Logger.stderr(),
+  DeprecationProcessingLogger deprecationLogger = logger =
+      DeprecationProcessingLogger(logger ?? Logger.stderr(),
+          silenceDeprecations: {...?silenceDeprecations},
           fatalDeprecations: {...?fatalDeprecations},
           futureDeprecations: {...?futureDeprecations},
           limitRepetition: !verbose);

lib/src/deprecation.dart

@@ -112,14 +112,28 @@ enum Deprecation {
   /// what version of Dart Sass this deprecation will be live in.
   final bool isFuture;
 
+  /// Underlying version string used by [obsoleteIn].
+  ///
+  /// This is necessary because [Version] doesn't have a constant constructor,
+  /// so we can't use it directly as an enum property.
+  final String? _obsoleteIn;
+
+  /// The Dart Sass version this feature was fully removed in, making the
+  /// deprecation obsolete.
+  ///
+  /// For deprecations that are not yet obsolete, this should be null.
+  Version? get obsoleteIn => _obsoleteIn?.andThen(Version.parse);
+
   /// Constructs a regular deprecation.
   const Deprecation(this.id, {required String? deprecatedIn, this.description})
       : _deprecatedIn = deprecatedIn,
+        _obsoleteIn = null,
         isFuture = false;
 
   /// Constructs a future deprecation.
   const Deprecation.future(this.id, {this.description})
       : _deprecatedIn = null,
+        _obsoleteIn = null,
         isFuture = true;
 
   @override

lib/src/embedded/compilation_dispatcher.dart

@@ -7,6 +7,7 @@ import 'dart:io';
 import 'dart:isolate';
 import 'dart:typed_data';
 
+import 'package:collection/collection.dart';
 import 'package:native_synchronization/mailbox.dart';
 import 'package:path/path.dart' as p;
 import 'package:protobuf/protobuf.dart';
@@ -124,6 +125,21 @@ final class CompilationDispatcher {
         : EmbeddedLogger(this,
             color: request.alertColor, ascii: request.alertAscii);
 
+    sass.Deprecation? deprecationOrWarn(String id) {
+      var deprecation = sass.Deprecation.fromId(id);
+      if (deprecation == null) {
+        logger.warn('Invalid deprecation "$id".');
+      }
+      return deprecation;
+    }
+
+    var fatalDeprecations =
+        request.fatalDeprecation.map(deprecationOrWarn).whereNotNull();
+    var silenceDeprecations =
+        request.silenceDeprecation.map(deprecationOrWarn).whereNotNull();
+    var futureDeprecations =
+        request.futureDeprecation.map(deprecationOrWarn).whereNotNull();
+
     try {
       var importers = request.importers.map((importer) =>
           _decodeImporter(request, importer) ??
@@ -148,6 +164,9 @@ final class CompilationDispatcher {
               url: input.url.isEmpty ? null : input.url,
               quietDeps: request.quietDeps,
               verbose: request.verbose,
+              fatalDeprecations: fatalDeprecations,
+              silenceDeprecations: silenceDeprecations,
+              futureDeprecations: futureDeprecations,
               sourceMap: request.sourceMap,
               charset: request.charset);
 
@@ -165,6 +184,9 @@ final class CompilationDispatcher {
                 style: style,
                 quietDeps: request.quietDeps,
                 verbose: request.verbose,
+                fatalDeprecations: fatalDeprecations,
+                silenceDeprecations: silenceDeprecations,
+                futureDeprecations: futureDeprecations,
                 sourceMap: request.sourceMap,
                 charset: request.charset);
           } on FileSystemException catch (error) {

lib/src/embedded/logger.dart

@@ -6,6 +6,7 @@ import 'package:path/path.dart' as p;
 import 'package:source_span/source_span.dart';
 import 'package:stack_trace/stack_trace.dart';
 
+import '../deprecation.dart';
 import '../logger.dart';
 import '../util/nullable.dart';
 import '../utils.dart';
@@ -14,7 +15,7 @@ import 'embedded_sass.pb.dart' hide SourceSpan;
 import 'utils.dart';
 
 /// A Sass logger that sends log messages as `LogEvent`s.
-final class EmbeddedLogger implements Logger {
+final class EmbeddedLogger extends LoggerWithDeprecationType {
   /// The [CompilationDispatcher] to which to send events.
   final CompilationDispatcher _dispatcher;
 
@@ -39,16 +40,16 @@ final class EmbeddedLogger implements Logger {
           ': $message\n');
   }
 
-  void warn(String message,
-      {FileSpan? span, Trace? trace, bool deprecation = false}) {
+  void internalWarn(String message,
+      {FileSpan? span, Trace? trace, Deprecation? deprecation}) {
     var formatted = withGlyphs(() {
       var buffer = StringBuffer();
       if (_color) {
         buffer.write('\u001b[33m\u001b[1m');
-        if (deprecation) buffer.write('Deprecation ');
+        if (deprecation != null) buffer.write('Deprecation ');
         buffer.write('Warning\u001b[0m');
       } else {
-        if (deprecation) buffer.write('DEPRECATION ');
+        if (deprecation != null) buffer.write('DEPRECATION ');
         buffer.write('WARNING');
       }
       if (span == null) {
@@ -65,12 +66,14 @@ final class EmbeddedLogger implements Logger {
     }, ascii: _ascii);
 
     var event = OutboundMessage_LogEvent()
-      ..type =
-          deprecation ? LogEventType.DEPRECATION_WARNING : LogEventType.WARNING
+      ..type = deprecation != null
+          ? LogEventType.DEPRECATION_WARNING
+          : LogEventType.WARNING
       ..message = message
       ..formatted = formatted;
     if (span != null) event.span = protofySpan(span);
     if (trace != null) event.stackTrace = trace.toString();
+    if (deprecation != null) event.deprecationType = deprecation.id;
     _dispatcher.sendLog(event);
   }
 }