Deprecate math.random() when $limit has units (#1779)

* Deprecate math.random() when $limit has units

* add changelog for random with units deprecation

* add link to sass-site/d/random-with-units

CHANGELOG.md

@@ -6,6 +6,10 @@
 * Properly consider `b > c` to be a superselector of `a > b > c`, and similarly
   for other combinators.
 
+* Deprecate use of `random()` when `$limit` has units to make it explicit that
+   `random()` currently ignores units. A future version will no longer ignore
+  units.
+
 ## 1.54.4
 
 * Improve error messages when passing incorrect units that are also
@@ -38,7 +42,7 @@
 * Add partial support for new media query syntax from Media Queries Level 4. The
   only exception are logical operations nested within parentheses, as these were
   previously interpreted differently as SassScript expressions.
-  
+
   A parenthesized media condition that begins with `not` or an opening
   parenthesis now produces a deprecation warning. In a future release, these
   will be interpreted as plain CSS instead.

lib/src/functions/math.dart

@@ -289,11 +289,28 @@ final _random = math.Random();
 
 final _randomFunction = _function("random", r"$limit: null", (arguments) {
   if (arguments[0] == sassNull) return SassNumber(_random.nextDouble());
-  var limit = arguments[0].assertNumber("limit").assertInt("limit");
-  if (limit < 1) {
+  var limit = arguments[0].assertNumber("limit");
+
+  if (limit.hasUnits) {
+    warn(
+      "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/random-with-units",
+    );
+  }
+
+  var limitScalar = limit.assertInt("limit");
+  if (limitScalar < 1) {
     throw SassScriptException("\$limit: Must be greater than 0, was $limit.");
   }
-  return SassNumber(_random.nextInt(limit) + 1);
+  return SassNumber(_random.nextInt(limitScalar) + 1);
 });
 
 final _div = _function("div", r"$number1, $number2", (arguments) {