[Function Units] Implement the breaking changes (#2656)

Closes #1776

Author: nex3

lib/src/deprecation.dart

@@ -15,7 +15,7 @@ enum Deprecation {
   // DO NOT EDIT. This section was generated from the language repo.
   // See tool/grind/generate_deprecations.dart for details.
   //
-  // Checksum: da3a1fd53f628e2633aef3b7560951c00d48e1a1
+  // Checksum: 212de63e7334243c6de7f9be29bbad0e1eaa2eea
 
   /// Deprecation for passing a string directly to meta.call().
   callString('call-string',
@@ -68,6 +68,7 @@ enum Deprecation {
   /// Deprecation for passing invalid units to built-in functions.
   functionUnits('function-units',
       deprecatedIn: '1.56.0',
+      obsoleteIn: '2.0.0',
       description: 'Passing invalid units to built-in functions.'),
 
   /// Deprecation for using !default or !global multiple times for one variable.

lib/src/functions/color.dart

@@ -1102,19 +1102,8 @@ SassColor _changeColor(
         SassNumber(hasUnits: false) => alphaArg.valueInRange(0, 1, "alpha"),
         SassNumber() when alphaArg.hasUnit('%') =>
           alphaArg.valueInRangeWithUnit(0, 100, "alpha", "%") / 100,
-        SassNumber() => () {
-            warnForDeprecation(
-              "\$alpha: Passing a unit other than % ($alphaArg) is "
-              "deprecated.\n"
-              "\n"
-              "To preserve current behavior: "
-              "${alphaArg.unitSuggestion('alpha')}\n"
-              "\n"
-              "See https://sass-lang.com/d/function-units",
-              Deprecation.functionUnits,
-            );
-            return alphaArg.valueInRange(0, 1, "alpha");
-          }(),
+        SassNumber() => throw SassScriptException(
+            '$alphaArg must have no units or unit %', 'alpha'),
         _ => throw SassScriptException(
             '$alphaArg is not a number or unquoted "none".',
             'alpha',
@@ -1260,37 +1249,6 @@ double? _adjustChannel(
 
   if (oldValue == null) _missingChannelError(color, channel.name);
 
-  switch ((color.space, channel)) {
-    case (ColorSpace.hsl || ColorSpace.hwb, ColorChannel(isPolarAngle: true)):
-      // `_channelFromValue` expects all hue values to be compatible with `deg`,
-      // but we're still in the deprecation period where we allow non-`deg`
-      // values for HSL and HWB so we have to handle that ahead-of-time.
-      adjustmentArg = SassNumber(_angleValue(adjustmentArg, 'hue'));
-
-    case (ColorSpace.hsl, LinearChannel(name: 'saturation' || 'lightness')):
-      // `_channelFromValue` expects lightness/saturation to be `%`, but we're
-      // still in the deprecation period where we allow non-`%` values so we
-      // have to handle that ahead-of-time.
-      _checkPercent(adjustmentArg, channel.name);
-      adjustmentArg = SassNumber(adjustmentArg.value, '%');
-
-    case (_, ColorChannel.alpha) when adjustmentArg.hasUnits:
-      // `_channelFromValue` expects alpha to be unitless or `%`, but we're
-      // still in the deprecation period where we allow other values (and
-      // interpret `%` as unitless) so we have to handle that ahead-of-time.
-      warnForDeprecation(
-        "\$alpha: Passing a number with unit ${adjustmentArg.unitString} is "
-        "deprecated.\n"
-        "\n"
-        "To preserve current behavior: "
-        "${adjustmentArg.unitSuggestion('alpha')}\n"
-        "\n"
-        "More info: https://sass-lang.com/d/function-units",
-        Deprecation.functionUnits,
-      );
-      adjustmentArg = SassNumber(adjustmentArg.value);
-  }
-
   var result =
       oldValue + _channelFromValue(channel, adjustmentArg, clamp: false)!;
   return switch (channel) {
@@ -1448,35 +1406,14 @@ Value _hsl(String name, List<Value> arguments) {
 }
 
 /// Asserts that [angle] is a number and returns its value in degrees.
-///
-/// Prints a deprecation warning if [angle] has a non-angle unit.
-double _angleValue(Value angleValue, String name) {
-  var angle = angleValue.assertNumber(name);
-  if (angle.compatibleWithUnit('deg')) return angle.coerceValueToUnit('deg');
-
-  warnForDeprecation(
-    "\$$name: Passing a unit other than deg ($angle) is deprecated.\n"
-    "\n"
-    "To preserve current behavior: ${angle.unitSuggestion(name)}\n"
-    "\n"
-    "See https://sass-lang.com/d/function-units",
-    Deprecation.functionUnits,
-  );
-  return angle.value;
-}
+double _angleValue(Value angleValue, String name) =>
+    angleValue.assertNumber(name).coerceValueToUnit('deg');
 
 /// Prints a deprecation warning if [number] doesn't have unit `%`.
 void _checkPercent(SassNumber number, String name) {
-  if (number.hasUnit('%')) return;
-
-  warnForDeprecation(
-    "\$$name: Passing a number without unit % ($number) is deprecated.\n"
-    "\n"
-    "To preserve current behavior: ${number.unitSuggestion(name, '%')}\n"
-    "\n"
-    "More info: https://sass-lang.com/d/function-units",
-    Deprecation.functionUnits,
-  );
+  if (!number.hasUnit('%')) {
+    throw SassScriptException('Expected $number to have unit %.', name);
+  }
 }
 
 /// Asserts that [number] is a percentage or has no units, and normalizes the

lib/src/functions/math.dart

@@ -233,27 +233,13 @@ final _randomFunction = _function("random", r"$limit: null", (arguments) {
   if (arguments[0] == sassNull) return SassNumber(_random.nextDouble());
   var limit = arguments[0].assertNumber("limit");
 
-  if (limit.hasUnits) {
-    warnForDeprecation(
-      "math.random() will no longer ignore \$limit units ($limit) in a "
-      "future release.\n"
-      "\n"
-      "Recommendation: "
-      "math.random(math.div(\$limit, 1${limit.unitString})) * 1${limit.unitString}\n"
-      "\n"
-      "To preserve current behavior: "
-      "math.random(math.div(\$limit, 1${limit.unitString}))\n"
-      "\n"
-      "More info: https://sass-lang.com/d/function-units",
-      Deprecation.functionUnits,
-    );
-  }
-
   var limitScalar = limit.assertInt("limit");
   if (limitScalar < 1) {
     throw SassScriptException("\$limit: Must be greater than 0, was $limit.");
   }
-  return SassNumber(_random.nextInt(limitScalar) + 1);
+  return SassNumber.withUnits(_random.nextInt(limitScalar) + 1,
+      numeratorUnits: limit.numeratorUnits,
+      denominatorUnits: limit.denominatorUnits);
 });
 
 final _div = _function("div", r"$number1, $number2", (arguments) {

lib/src/value.dart

@@ -5,8 +5,6 @@
 import 'package:meta/meta.dart';
 
 import 'ast/selector.dart';
-import 'deprecation.dart';
-import 'evaluation_context.dart';
 import 'exception.dart';
 import 'utils.dart';
 import 'value/boolean.dart';
@@ -124,21 +122,8 @@ abstract class Value {
   /// [asList]. If [sassIndex] came from a function argument, [name] is the
   /// argument name (without the `$`). It's used for error reporting.
   int sassIndexToListIndex(Value sassIndex, [String? name]) {
-    var indexValue = sassIndex.assertNumber(name);
-    if (indexValue.hasUnits) {
-      warnForDeprecation(
-        "\$$name: Passing a number with unit ${indexValue.unitString} is "
-        "deprecated.\n"
-        "\n"
-        "To preserve current behavior: "
-        "${indexValue.unitSuggestion(name ?? 'index')}\n"
-        "\n"
-        "More info: https://sass-lang.com/d/function-units",
-        Deprecation.functionUnits,
-      );
-    }
-
-    var index = indexValue.assertInt(name);
+    var index =
+        (sassIndex.assertNumber(name)..assertNoUnits(name)).assertInt(name);
     if (index == 0) throw SassScriptException("List index may not be 0.", name);
     if (index.abs() > lengthAsList) {
       throw SassScriptException(

lib/src/value/number.dart

@@ -962,21 +962,4 @@ abstract class SassNumber extends Value {
     var innerMap = _conversions[unit];
     return innerMap == null ? 1 : 1 / innerMap.values.first;
   }
-
-  /// Returns a suggested Sass snippet for converting a variable named [name]
-  /// (without `%`) containing this number into a number with the same value and
-  /// the given [unit].
-  ///
-  /// If [unit] is null, this forces the number to be unitless.
-  ///
-  /// This is used for deprecation warnings when restricting which units are
-  /// allowed for a given function.
-  @internal
-  String unitSuggestion(String name, [String? unit]) {
-    var result = "\$$name" +
-        denominatorUnits.map((unit) => " * 1$unit").join() +
-        numeratorUnits.map((unit) => " / 1$unit").join() +
-        (unit == null ? "" : " * 1$unit");
-    return numeratorUnits.isEmpty ? result : "calc($result)";
-  }
 }

test/cli/shared/deprecations.dart

@@ -118,15 +118,12 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
 
       group("an evaluation-time deprecation", () {
         setUp(
-          () => d.file("test.scss", """
-            @use 'sass:math';
-            a {b: math.random(1px)}
-          """).create(),
+          () => d.file("test.scss", "a {b: nth(1 2 3, 1)}").create(),
         );
 
         test("in immediate mode", () async {
           var sass = await runSass([
-            "--silence-deprecation=function-units",
+            "--silence-deprecation=global-builtin",
             "test.scss",
           ]);
           expect(sass.stderr, emitsDone);
@@ -137,7 +134,7 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
           var sass = await runSass([
             "--watch",
             "--poll",
-            "--silence-deprecation=function-units",
+            "--silence-deprecation=global-builtin",
             "test.scss:out.css",
           ]);
           expect(sass.stderr, emitsDone);
@@ -152,15 +149,13 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
         test("in repl mode", () async {
           var sass = await runSass([
             "--interactive",
-            "--silence-deprecation=function-units",
+            "--silence-deprecation=global-builtin",
           ]);
           expect(sass.stderr, emitsDone);
-          sass.stdin.writeln("@use 'sass:math'");
-          await expectLater(sass.stdout, emits(">> @use 'sass:math'"));
-          sass.stdin.writeln("math.random(1px)");
+          sass.stdin.writeln("nth(1 2 3, 1)");
           await expectLater(
             sass.stdout,
-            emitsInOrder([">> math.random(1px)", "1"]),
+            emitsInOrder([">> nth(1 2 3, 1)", "1"]),
           );
           await sass.kill();
         });
@@ -250,15 +245,12 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
 
       group("an evaluation-time deprecation", () {
         setUp(
-          () => d.file("test.scss", """
-            @use 'sass:math';
-            a {b: math.random(1px)}
-          """).create(),
+          () => d.file("test.scss", "a {b: nth(1 2 3, 1)}").create(),
         );
 
         test("in immediate mode", () async {
           var sass = await runSass([
-            "--fatal-deprecation=function-units",
+            "--fatal-deprecation=global-builtin",
             "test.scss",
           ]);
           expect(sass.stderr, emits(startsWith("Error: ")));
@@ -269,7 +261,7 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
           var sass = await runSass([
             "--watch",
             "--poll",
-            "--fatal-deprecation=function-units",
+            "--fatal-deprecation=global-builtin",
             "test.scss:out.css",
           ]);
           await expectLater(sass.stderr, emits(startsWith("Error: ")));
@@ -286,15 +278,13 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
         test("in repl mode", () async {
           var sass = await runSass([
             "--interactive",
-            "--fatal-deprecation=function-units",
+            "--fatal-deprecation=global-builtin",
           ]);
-          sass.stdin.writeln("@use 'sass:math'");
-          await expectLater(sass.stdout, emits(">> @use 'sass:math'"));
-          sass.stdin.writeln("math.random(1px)");
+          sass.stdin.writeln("nth(1 2 3, 1)");
           await expectLater(
             sass.stdout,
             emitsInOrder([
-              ">> math.random(1px)",
+              ">> nth(1 2 3, 1)",
               emitsThrough(startsWith("Error: ")),
               emitsThrough(contains("Remove this setting")),
             ]),
@@ -316,12 +306,12 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
 
         test("in immediate mode", () async {
           var sass = await runSass([
-            "--future-deprecation=function-units",
+            "--future-deprecation=global-builtin",
             "test.scss",
           ]);
           expect(
             sass.stderr,
-            emits(contains("function-units is not a future deprecation")),
+            emits(contains("global-builtin is not a future deprecation")),
           );
           await sass.shouldExit(0);
         });
@@ -330,12 +320,12 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
           var sass = await runSass([
             "--watch",
             "--poll",
-            "--future-deprecation=function-units",
+            "--future-deprecation=global-builtin",
             "test.scss:out.css",
           ]);
           expect(
             sass.stderr,
-            emits(contains("function-units is not a future deprecation")),
+            emits(contains("global-builtin is not a future deprecation")),
           );
 
           await expectLater(

test/deprecations_test.dart

@@ -67,52 +67,6 @@ void main() {
           Deprecation.compileStringRelativeUrl);
     });
   });
-
-  // Deprecated in various Sass versions <=1.56.0
-  group("functionUnits is violated by", () {
-    test("a hue with a non-angle unit", () {
-      _expectDeprecation("a {b: hsl(10px, 0%, 0%)}", Deprecation.functionUnits);
-    });
-
-    test("a saturation/lightness with a non-percent unit", () {
-      _expectDeprecation(
-        "a {b: hsl(10deg, 0px, 0%)}",
-        Deprecation.functionUnits,
-      );
-    });
-
-    test("a saturation/lightness with no unit", () {
-      _expectDeprecation("a {b: hsl(10deg, 0%, 0)}", Deprecation.functionUnits);
-    });
-
-    test("an alpha value with a non-percent unit", () {
-      _expectDeprecation(
-        r"@use 'sass:color'; a {b: color.change(red, $alpha: 1px)}",
-        Deprecation.functionUnits,
-      );
-    });
-
-    test("calling math.random with units", () {
-      _expectDeprecation(
-        "@use 'sass:math'; a {b: math.random(100px)}",
-        Deprecation.functionUnits,
-      );
-    });
-
-    test("calling list.nth with units", () {
-      _expectDeprecation(
-        "@use 'sass:list'; a {b: list.nth(1 2, 1px)}",
-        Deprecation.functionUnits,
-      );
-    });
-
-    test("calling list.set-nth with units", () {
-      _expectDeprecation(
-        "@use 'sass:list'; a {b: list.set-nth(1 2, 1px, 3)}",
-        Deprecation.functionUnits,
-      );
-    });
-  });
 }
 
 /// Confirms that [source] will error if [deprecation] is fatal.