Complete implementation the deprecations API #2207

jathak · 2024-04-01T18:34:56Z

This implements the full deprecations API for the JS API and the embedded compiler, and also adds silenceDeprecations/--silence-deprecation to the Dart API and CLI to complete those implementations.

See sass/sass#3826
See sass/sass-spec#1967
[skip sass-embedded]

…tion handling logger

nex3 · 2024-04-02T07:01:14Z

CHANGELOG.md

+* 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.


It's a fair bet that most JS API users don't know or follow the Dart API, so it's probably better to frame this as adding three new features to the JS API rather than bringing two from the Dart API and adding one new

nex3 · 2024-04-02T07:03:28Z

CHANGELOG.md

+
+### Command-Line Interface
+
+* Add a new `--silence-deprecation` flag to match the new JS API.


Similarly, although to a lesser extent, the CLI users are a somewhat different set than the JS API users. Better to keep the CLI descriptions as self-contained as possible—it's less net effort for us to duplicate some prose than for a bunch of readers to read extra paragraphs.

nex3 · 2024-04-02T07:04:24Z

CHANGELOG.md

+  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


I'd mark this as **Potentially breaking bug fix:** on the off chance that someone was doing it without realizing that it wasn't failing.

nex3 · 2024-04-02T07:07:04Z

lib/src/executable/options.dart

+            for (var deprecation in Deprecation.values)
+              if (deprecation.deprecatedIn != null &&
+                  deprecation.description != null)
+                deprecation.id: deprecation.description!,


You can use if ... case to avoid this nullability assertion

lib/src/js/compile.dart

nex3 · 2024-04-02T20:15:54Z

lib/src/logger/deprecation_handling.dart

+      }
+    }
+    for (var deprecation in silenceDeprecations) {
+      if (deprecation == Deprecation.userAuthored) {


You could make this block a switch statement.

nex3 · 2024-04-02T20:17:02Z

lib/src/logger/deprecation_handling.dart

+      Trace? trace,
+      bool deprecation = false,
+      Deprecation? deprecationType}) {
+    if (deprecation && deprecationType != null) {


A benefit of the old pattern of having a separate warnForDeprecation() method is that it's clear from the static types that every deprecation warning has to have a deprecationType attached to it. Unless there's a technical reason to fold that into warn(), I think I'd prefer to keep it the old way. (If they do need to be merged, we should have error handling for what happens if deprecation and deprecationType disagree.)

Now that there are other loggers that need to receive the deprecation type, using the same name for their method as the extension method meant that those other loggers could receive future deprecation warnings that hadn't been explicitly passed through by DeprecationProcessingLogger, so I wanted to separate those names.

I've now updated the method that LoggerWithDeprecationTypes implement to be internalWarn, which omits the boolean parameter and only has the Deprecation? one. In Dart Sass 2.0.0, we can eliminate internalWarn and LoggerWithDeprecationType by just changing Logger.warn's signature.

nex3 · 2024-04-02T20:22:30Z

lib/src/logger/deprecation_handling.dart

@@ -16,12 +16,15 @@ const _maxRepetitions = 5;

 /// A logger that wraps an inner logger to have special handling for
 /// deprecation warnings.
-final class DeprecationHandlingLogger implements Logger {
+final class DeprecationHandlingLogger implements DeprecationLogger {


The distinction between DeprecationLogger and DeprecationHandlingLogger is now pretty confusing, since neither the names nor the documentations clearly say what makes them different from one another.

I've renamed this to DeprecationProcessingLogger and fleshed out the documentation to make it clearer that this one processes deprecation warnings (sometimes ignoring them or treating them as errors) based on the various flags.

The other one is now LoggerWithDeprecationType, which is clunky, but we can eliminate it in Dart Sass 2.0.0, so I'm not too worried about it.

nex3 · 2024-04-02T20:24:42Z

test/embedded/utils.dart

+  Iterable<String>? functions,
+  Iterable<String>? fatalDeprecations,
+  Iterable<String>? futureDeprecations,
+  Iterable<String>? silenceDeprecations,


Nit: remove trailing comma for consistency with other arglists.

nex3 · 2024-04-02T20:25:26Z

test/embedded/utils.dart

+  if (fatalDeprecations != null) {
+    request.fatalDeprecation.addAll(fatalDeprecations);
+  }


Consider:

Suggested change

if (fatalDeprecations != null) {

request.fatalDeprecation.addAll(fatalDeprecations);

}

fatalDeprecations.andThen(request.fatalDeprecation.addAll);

nex3 · 2024-04-03T19:49:21Z

lib/src/js/deprecations.dart

+  });
+
+  jsClass.defineStaticMethod(
+      'parse', (String version) => Version.parse(version));


There's a discrepancy with the spec here: the JS version API we've specified only supports <number>.<number>.<number> versions, but Version.parse() supports the full semver range, including build identifiers and prerelease versions. To match the spec, this should probably throw an error if anything beyond numbers are included.

nex3 · 2024-04-03T20:01:29Z

lib/src/executable/options.dart

+            for (var deprecation in Deprecation.values)
+              if (deprecation
+                  case Deprecation(
+                    deprecatedIn: Version(),
+                    obsoleteIn: null,
+                    :var description?
+                  ))
+                deprecation.id: description,


Between this and --fatal-deprecation, nearly half the length of the --help output is taken up by deprecation descriptions. WDYT about just linking to the Sass site's CLI docs instead?

Yeah, I think that makes more sense. Is there a short version of https://sass-lang.com/documentation/cli/dart-sass so we can link to it with #fatal-deprecation, #silence-deprecation and #future-deprecation?

jathak added 7 commits February 23, 2024 21:07

wip merged into main

92d899a

Revert moving UsageException

ded1a32

Implement Deprecations API for JS and embedded

bff24d8

Merge branch 'main' into deprecations

8424aa8

Fix deprecations API implementation

3efd6e7

Add changelog

69b003a

Update changelog

b679a4a

jathak mentioned this pull request Apr 1, 2024

Implement the host side of the deprecations API sass/embedded-host-node#279

Merged

Make sure future deprecations are only propagated through the depreca…

1f445a5

…tion handling logger

jathak requested a review from nex3 April 1, 2024 21:36

nex3 requested changes Apr 2, 2024

View reviewed changes

jathak added 2 commits April 3, 2024 01:51

Code review

5cb6bc0

synchronize

aa37f3f

jathak requested a review from nex3 April 3, 2024 02:08

nex3 approved these changes Apr 3, 2024

View reviewed changes

Shorten help text

ae664f7

jathak merged commit d9220d9 into main Apr 3, 2024
29 checks passed

jathak deleted the deprecations branch April 3, 2024 21:15

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Complete implementation the deprecations API #2207

Complete implementation the deprecations API #2207

jathak commented Apr 1, 2024

nex3 Apr 2, 2024

jathak Apr 3, 2024

nex3 Apr 2, 2024

jathak Apr 3, 2024

nex3 Apr 2, 2024

jathak Apr 3, 2024

nex3 Apr 2, 2024

jathak Apr 3, 2024

nex3 Apr 2, 2024

jathak Apr 3, 2024

nex3 Apr 2, 2024

jathak Apr 3, 2024

nex3 Apr 2, 2024

jathak Apr 3, 2024

nex3 Apr 2, 2024

jathak Apr 3, 2024

nex3 Apr 2, 2024

jathak Apr 3, 2024

nex3 Apr 3, 2024

nex3 Apr 3, 2024

jathak Apr 3, 2024


		### Command-Line Interface

		* Add a new `--silence-deprecation` flag to match the new JS API.

Complete implementation the deprecations API #2207

Complete implementation the deprecations API #2207

Conversation

jathak commented Apr 1, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment