Complete implementation the deprecations API

CHANGELOG.md

@@ -1,3 +1,38 @@
+## 1.74.0
+
+### JS API
+
+* The deprecations API is now available in the JS API! The `compile` methods
+  support the same `fatalDeprecations` and `futureDeprecations` options that
+  were already available in the Dart API and the CLI, as well as a new
+  `silenceDeprecations` option that allows you to silence deprecation warnings
+  of a given type.
+
+### Command-Line Interface
+
+* Add a new `--silence-deprecation` flag to match the new JS API.
+
+* 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 to match
+  the JS API.
+
+* 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.
+
+* 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

@@ -54,6 +54,7 @@ Future<void> main(List<String> args) async {
         // each compilation, which will limit repetition if verbose is not
         // passed in addition to handling fatal/future deprecations.
         logger: DeprecationHandlingLogger(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

@@ -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(),
+          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(),
+          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: 9d2d66aa8a5b5613cbae25c448356526aebbadbf
 //
 // ignore_for_file: unused_import
 
@@ -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(),
+          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(),
+          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 implements DeprecationLogger {
   /// The [CompilationDispatcher] to which to send events.
   final CompilationDispatcher _dispatcher;
 
@@ -40,7 +41,10 @@ final class EmbeddedLogger implements Logger {
   }
 
   void warn(String message,
-      {FileSpan? span, Trace? trace, bool deprecation = false}) {
+      {FileSpan? span,
+      Trace? trace,
+      bool deprecation = false,
+      Deprecation? deprecationType}) {
     var formatted = withGlyphs(() {
       var buffer = StringBuffer();
       if (_color) {
@@ -71,6 +75,7 @@ final class EmbeddedLogger implements Logger {
       ..formatted = formatted;
     if (span != null) event.span = protofySpan(span);
     if (trace != null) event.stackTrace = trace.toString();
+    if (deprecationType != null) event.deprecationType = deprecationType.id;
     _dispatcher.sendLog(event);
   }
 }

lib/src/executable/options.dart

@@ -91,6 +91,14 @@ final class ExecutableOptions {
               "Stylesheets imported through load paths count as dependencies.")
       ..addFlag('verbose',
           help: "Print all deprecation warnings even when they're repetitive.")
+      ..addMultiOption('silence-deprecation',
+          help: 'Deprecations to ignore.',
+          allowedHelp: {
+            for (var deprecation in Deprecation.values)
+              if (deprecation.deprecatedIn != null &&
+                  deprecation.description != null)
+                deprecation.id: deprecation.description!,
+          })
       ..addMultiOption('fatal-deprecation',
           help: 'Deprecations to treat as errors. You may also pass a Sass\n'
               'version to include any behavior deprecated in or before it.\n'
@@ -521,6 +529,12 @@ final class ExecutableOptions {
         : p.absolute(path));
   }
 
+  /// The set of deprecations whose warnings should be silenced.
+  Set<Deprecation> get silenceDeprecations => {
+        for (var id in _options['silence-deprecation'] as List<String>)
+          Deprecation.fromId(id) ?? _fail('Invalid deprecation "$id".')
+      };
+
   /// The set of deprecations that cause errors.
   Set<Deprecation> get fatalDeprecations => _fatalDeprecations ??= () {
         var deprecations = <Deprecation>{};

lib/src/js.dart

@@ -2,7 +2,10 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:js/js_util.dart';
+
 import 'js/exception.dart';
+import 'js/deprecations.dart';
 import 'js/exports.dart';
 import 'js/compile.dart';
 import 'js/compiler.dart';
@@ -52,6 +55,8 @@ void main() {
           warn: allowInteropNamed('sass.Logger.silent.warn', (_, __) {}),
           debug: allowInteropNamed('sass.Logger.silent.debug', (_, __) {})));
   exports.NodePackageImporter = nodePackageImporterClass;
+  exports.deprecations = jsify(deprecations);
+  exports.Version = versionClass;
 
   exports.info =
       "dart-sass\t${const String.fromEnvironment('version')}\t(Sass Compiler)\t"