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

Author: Goodwine

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) {