Clarify !global deprecation warnings

Closes #723

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.21.1
+
+* Make deprecation warnings for `!global` variable declarations that create new
+  variables clearer, especially in the case where the `!global` flag is
+  unnecessary because the variables are at the top level of the stylesheet.
+
 ## 1.21.0
 
 ### Dart API

lib/src/async_environment.dart

@@ -104,6 +104,9 @@ class AsyncEnvironment {
   UserDefinedCallable<AsyncEnvironment> get content => _content;
   UserDefinedCallable<AsyncEnvironment> _content;
 
+  /// Whether the environment is lexically at the root of the document.
+  bool get atRoot => _variables.length == 1;
+
   /// Whether the environment is lexically within a mixin.
   bool get inMixin => _inMixin;
   var _inMixin = false;
@@ -356,7 +359,7 @@ class AsyncEnvironment {
       return;
     }
 
-    if (global || _variables.length == 1) {
+    if (global || atRoot) {
       // Don't set the index if there's already a variable with the given name,
       // since local accesses should still return the local variable.
       _variableIndices.putIfAbsent(name, () {

lib/src/environment.dart

@@ -5,7 +5,7 @@
 // DO NOT EDIT. This file was generated from async_environment.dart.
 // See tool/grind/synchronize.dart for details.
 //
-// Checksum: 23c920bd76d38c4ccf2024a0740aeae9672143d0
+// Checksum: 70b94c80b7ecc1bab523f6bf69612b69269424a5
 //
 // ignore_for_file: unused_import
 
@@ -109,6 +109,9 @@ class Environment {
   UserDefinedCallable<Environment> get content => _content;
   UserDefinedCallable<Environment> _content;
 
+  /// Whether the environment is lexically at the root of the document.
+  bool get atRoot => _variables.length == 1;
+
   /// Whether the environment is lexically within a mixin.
   bool get inMixin => _inMixin;
   var _inMixin = false;
@@ -361,7 +364,7 @@ class Environment {
       return;
     }
 
-    if (global || _variables.length == 1) {
+    if (global || atRoot) {
       // Don't set the index if there's already a variable with the given name,
       // since local accesses should still return the local variable.
       _variableIndices.putIfAbsent(name, () {

lib/src/visitor/async_evaluate.dart

@@ -1439,9 +1439,15 @@ class _EvaluateVisitor
 
     if (node.isGlobal && !_environment.globalVariableExists(node.name)) {
       _logger.warn(
-          "As of Dart Sass 2.0.0, !global assignments won't be able to\n"
+          _environment.atRoot
-          "declare new variables. Consider adding `\$${node.name}: null` at "
+              ? "As of Dart Sass 2.0.0, !global assignments won't be able to\n"
-          "the top level.",
+                  "declare new variables. Since this assignment is at the root "
+                  "of the stylesheet,\n"
+                  "the !global flag is unnecessary and can safely be removed."
+              : "As of Dart Sass 2.0.0, !global assignments won't be able to\n"
+                  "declare new variables. Consider adding `\$${node.name}: "
+                  "null` at the root of the\n"
+                  "stylesheet.",
           span: node.span,
           trace: _stackTrace(node.span),
           deprecation: true);

lib/src/visitor/evaluate.dart

@@ -5,7 +5,7 @@
 // DO NOT EDIT. This file was generated from async_evaluate.dart.
 // See tool/grind/synchronize.dart for details.
 //
-// Checksum: e0d1df19c15e24fe5ee72bc9ee0d3a26e4412830
+// Checksum: 9a864b68aea5bf6aaa6077a16bade57a8a97085e
 //
 // ignore_for_file: unused_import
 
@@ -1434,9 +1434,15 @@ class _EvaluateVisitor
 
     if (node.isGlobal && !_environment.globalVariableExists(node.name)) {
       _logger.warn(
-          "As of Dart Sass 2.0.0, !global assignments won't be able to\n"
+          _environment.atRoot
-          "declare new variables. Consider adding `\$${node.name}: null` at "
+              ? "As of Dart Sass 2.0.0, !global assignments won't be able to\n"
-          "the top level.",
+                  "declare new variables. Since this assignment is at the root "
+                  "of the stylesheet,\n"
+                  "the !global flag is unnecessary and can safely be removed."
+              : "As of Dart Sass 2.0.0, !global assignments won't be able to\n"
+                  "declare new variables. Consider adding `\$${node.name}: "
+                  "null` at the root of the\n"
+                  "stylesheet.",
           span: node.span,
           trace: _stackTrace(node.span),
           deprecation: true);