Allow errors to refer to multiple source spans at once

This makes error messages for issues like configuring a module after
it's loaded much clearer.

Author: nex3

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.24.5
+
+* Highlight contextually-relevant sections of the stylesheet in error messages,
+  rather than only highlighting the section where the error was detected.
+
 ## 1.24.4
 
 ### JavaScript API

lib/src/async_environment.dart

@@ -35,16 +35,32 @@ class AsyncEnvironment {
   Map<String, Module> get modules => UnmodifiableMapView(_modules);
   final Map<String, Module> _modules;
 
+  /// A map from module namespaces to the nodes whose spans indicate where those
+  /// modules were originally loaded.
+  final Map<String, AstNode> _namespaceNodes;
+
   /// The namespaceless modules used in the current scope.
   ///
   /// This is `null` if there are no namespaceless modules.
   Set<Module> _globalModules;
 
+  /// A map from modules in [_globalModules] to the nodes whose spans
+  /// indicate where those modules were originally loaded.
+  ///
+  /// This is `null` if there are no namespaceless modules.
+  Map<Module, AstNode> _globalModuleNodes;
+
   /// The modules forwarded by this module.
   ///
   /// This is `null` if there are no forwarded modules.
   List<Module> _forwardedModules;
 
+  /// A map from modules in [_forwardedModules] to the nodes whose spans
+  /// indicate where those modules were originally forwarded.
+  ///
+  /// This is `null` if there are no forwarded modules.
+  Map<Module, AstNode> _forwardedModuleNodes;
+
   /// Modules forwarded by nested imports at each lexical scope level *beneath
   /// the global scope*.
   ///
@@ -136,8 +152,11 @@ class AsyncEnvironment {
   /// If [sourceMap] is `true`, this tracks variables' source locations
   AsyncEnvironment({bool sourceMap = false})
       : _modules = {},
+        _namespaceNodes = {},
         _globalModules = null,
+        _globalModuleNodes = null,
         _forwardedModules = null,
+        _forwardedModuleNodes = null,
         _nestedForwardedModules = null,
         _allModules = [],
         _variables = [{}],
@@ -150,8 +169,11 @@ class AsyncEnvironment {
 
   AsyncEnvironment._(
       this._modules,
+      this._namespaceNodes,
       this._globalModules,
+      this._globalModuleNodes,
       this._forwardedModules,
+      this._forwardedModuleNodes,
       this._nestedForwardedModules,
       this._allModules,
       this._variables,
@@ -174,8 +196,11 @@ class AsyncEnvironment {
   /// when the closure was created will be reflected.
   AsyncEnvironment closure() => AsyncEnvironment._(
       _modules,
+      _namespaceNodes,
       _globalModules,
+      _globalModuleNodes,
       _forwardedModules,
+      _forwardedModuleNodes,
       _nestedForwardedModules,
       _allModules,
       _variables.toList(),
@@ -190,6 +215,9 @@ class AsyncEnvironment {
   /// functions, and mixins, but not its modules.
   AsyncEnvironment global() => AsyncEnvironment._(
       {},
+      {},
+      null,
+      null,
       null,
       null,
       null,
@@ -202,16 +230,20 @@ class AsyncEnvironment {
 
   /// Adds [module] to the set of modules visible in this environment.
   ///
+  /// [nodeWithSpan]'s span is used to report any errors with the module.
+  ///
   /// If [namespace] is passed, the module is made available under that
   /// namespace.
   ///
-  /// Throws a [SassScriptException] if there's already a module with the given
+  /// Throws a [SassException] if there's already a module with the given
   /// [namespace], or if [namespace] is `null` and [module] defines a variable
   /// with the same name as a variable defined in this environment.
-  void addModule(Module module, {String namespace}) {
+  void addModule(Module module, AstNode nodeWithSpan, {String namespace}) {
     if (namespace == null) {
       _globalModules ??= {};
+      _globalModuleNodes ??= {};
       _globalModules.add(module);
+      _globalModuleNodes[module] = nodeWithSpan;
       _allModules.add(module);
 
       for (var name in _variables.first.keys) {
@@ -223,11 +255,14 @@ class AsyncEnvironment {
       }
     } else {
       if (_modules.containsKey(namespace)) {
-        throw SassScriptException(
-            "There's already a module with namespace \"$namespace\".");
+        throw MultiSpanSassScriptException(
+            "There's already a module with namespace \"$namespace\".",
+            "new @use",
+            {_namespaceNodes[namespace].span: "original @use"});
       }
 
       _modules[namespace] = module;
+      _namespaceNodes[namespace] = nodeWithSpan;
       _allModules.add(module);
     }
   }
@@ -236,12 +271,15 @@ class AsyncEnvironment {
   /// defined in this module, according to the modifications defined by [rule].
   void forwardModule(Module module, ForwardRule rule) {
     _forwardedModules ??= [];
+    _forwardedModuleNodes ??= {};
 
     var view = ForwardedModuleView(module, rule);
     for (var other in _forwardedModules) {
-      _assertNoConflicts(view.variables, other.variables, "variable", other);
-      _assertNoConflicts(view.functions, other.functions, "function", other);
-      _assertNoConflicts(view.mixins, other.mixins, "mixin", other);
+      _assertNoConflicts(
+          view.variables, other.variables, "variable", other, rule);
+      _assertNoConflicts(
+          view.functions, other.functions, "function", other, rule);
+      _assertNoConflicts(view.mixins, other.mixins, "mixin", other, rule);
     }
 
     // Add the original module to [_allModules] (rather than the
@@ -250,14 +288,19 @@ class AsyncEnvironment {
     // CSS, not for the members they expose.
     _allModules.add(module);
     _forwardedModules.add(view);
+    _forwardedModuleNodes[view] = rule;
   }
 
   /// Throws a [SassScriptException] if [newMembers] has any keys that overlap
   /// with [oldMembers].
   ///
-  /// The [type] and [oldModule] is used for error reporting.
-  void _assertNoConflicts(Map<String, Object> newMembers,
-      Map<String, Object> oldMembers, String type, Module oldModule) {
+  /// The [type], [other], [newModuleNodeWithSpan] are used for error reporting.
+  void _assertNoConflicts(
+      Map<String, Object> newMembers,
+      Map<String, Object> oldMembers,
+      String type,
+      Module other,
+      AstNode newModuleNodeWithSpan) {
     Map<String, Object> smaller;
     Map<String, Object> larger;
     if (newMembers.length < oldMembers.length) {
@@ -271,9 +314,10 @@ class AsyncEnvironment {
     for (var name in smaller.keys) {
       if (larger.containsKey(name)) {
         if (type == "variable") name = "\$$name";
-        throw SassScriptException(
-            'Module ${p.prettyUri(oldModule.url)} and the new module both '
-            'forward a $type named $name.');
+        throw MultiSpanSassScriptException(
+            'Two forwarded modules both define a $type named $name.',
+            "new @forward",
+            {_forwardedModuleNodes[other].span: "original @forward"});
       }
     }
   }
@@ -288,7 +332,9 @@ class AsyncEnvironment {
       if (forwarded == null) return;
 
       _globalModules ??= {};
+      _globalModuleNodes ??= {};
       _forwardedModules ??= [];
+      _forwardedModuleNodes ??= {};
 
       var forwardedVariableNames =
           forwarded.expand((module) => module.variables.keys).toSet();
@@ -308,6 +354,7 @@ class AsyncEnvironment {
           if (shadowed != null) {
             _globalModules.remove(module);
             _globalModules.add(shadowed);
+            _globalModuleNodes[shadowed] = _globalModuleNodes.remove(module);
           }
         }
         for (var i = 0; i < _forwardedModules.length; i++) {
@@ -316,11 +363,17 @@ class AsyncEnvironment {
               variables: forwardedVariableNames,
               mixins: forwardedMixinNames,
               functions: forwardedFunctionNames);
-          if (shadowed != null) _forwardedModules[i] = shadowed;
+          if (shadowed != null) {
+            _forwardedModules[i] = shadowed;
+            _forwardedModuleNodes[shadowed] =
+                _forwardedModuleNodes.remove(module);
+          }
         }
 
         _globalModules.addAll(forwarded);
+        _globalModuleNodes.addAll(module._environment._forwardedModuleNodes);
         _forwardedModules.addAll(forwarded);
+        _forwardedModuleNodes.addAll(module._environment._forwardedModuleNodes);
       } else {
         _nestedForwardedModules ??=
             List.generate(_variables.length - 1, (_) => []);
@@ -795,11 +848,12 @@ class AsyncEnvironment {
       if (valueInModule == null) continue;
 
       if (value != null) {
-        throw SassScriptException(
-            'This $type is available from multiple global modules:\n' +
-                bulletedList(_globalModules
-                    .where((module) => callback(module) != null)
-                    .map((module) => p.prettyUri(module.url))));
+        throw MultiSpanSassScriptException(
+            'This $type is available from multiple global modules.',
+            '$type use', {
+          for (var entry in _globalModuleNodes.entries)
+            if (callback(entry.key) != null) entry.value.span: 'includes $type'
+        });
       }
 
       value = valueInModule;