Track dependencies through meta.load-css() with --watch (#1877)

Closes #1808

Author: nex3

CHANGELOG.md

@@ -19,6 +19,11 @@
 * Add the relative length units from CSS Values 4 and CSS Contain 3 as known
   units to validate bad computation in `calc`.
 
+### Command Line Interface
+
+* The `--watch` flag will now track loads through calls to `meta.load-css()` as
+  long as their URLs are literal strings without any interpolation.
+
 ## 1.57.1
 
 * No user-visible changes.

lib/src/stylesheet_graph.dart

@@ -111,17 +111,17 @@ class StylesheetGraph {
   /// Returns two maps from non-canonicalized imported URLs in [stylesheet] to
   /// nodes, which appears within [baseUrl] imported by [baseImporter].
   ///
-  /// The first map contains stylesheets depended on via `@use` and `@forward`
-  /// while the second map contains those depended on via `@import`.
+  /// The first map contains stylesheets depended on via module loads while the
+  /// second map contains those depended on via `@import`.
   Tuple2<Map<Uri, StylesheetNode?>, Map<Uri, StylesheetNode?>> _upstreamNodes(
       Stylesheet stylesheet, Importer baseImporter, Uri baseUrl) {
     var active = {baseUrl};
-    var tuple = findDependencies(stylesheet);
+    var dependencies = findDependencies(stylesheet);
     return Tuple2({
-      for (var url in tuple.item1)
+      for (var url in dependencies.modules)
         url: _nodeFor(url, baseImporter, baseUrl, active)
     }, {
-      for (var url in tuple.item2)
+      for (var url in dependencies.imports)
         url: _nodeFor(url, baseImporter, baseUrl, active, forImport: true)
     });
   }

lib/src/visitor/find_dependencies.dart

@@ -2,30 +2,38 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
-import 'package:tuple/tuple.dart';
+import 'package:collection/collection.dart';
 
 import '../ast/sass.dart';
 import 'recursive_statement.dart';
 
-/// Returns two lists of dependencies for [stylesheet].
-///
-/// The first is a list of URLs from all `@use` and `@forward` rules in
-/// [stylesheet] (excluding built-in modules). The second is a list of all
-/// imports in [stylesheet].
+/// Returns [stylesheet]'s statically-declared dependencies.
 ///
 /// {@category Dependencies}
-Tuple2<List<Uri>, List<Uri>> findDependencies(Stylesheet stylesheet) =>
+DependencyReport findDependencies(Stylesheet stylesheet) =>
     _FindDependenciesVisitor().run(stylesheet);
 
-/// A visitor that traverses a stylesheet and records, all `@import`, `@use`,
-/// and `@forward` rules (excluding built-in modules) it contains.
+/// A visitor that traverses a stylesheet and records all its dependencies on
+/// other stylesheets.
 class _FindDependenciesVisitor with RecursiveStatementVisitor {
-  final _usesAndForwards = <Uri>[];
-  final _imports = <Uri>[];
+  final _uses = <Uri>{};
+  final _forwards = <Uri>{};
+  final _metaLoadCss = <Uri>{};
+  final _imports = <Uri>{};
+
+  /// The namespaces under which `sass:meta` has been `@use`d in this stylesheet.
+  ///
+  /// If this contains `null`, it means `sass:meta` was loaded without a
+  /// namespace.
+  final _metaNamespaces = <String?>{};
 
-  Tuple2<List<Uri>, List<Uri>> run(Stylesheet stylesheet) {
+  DependencyReport run(Stylesheet stylesheet) {
     visitStylesheet(stylesheet);
-    return Tuple2(_usesAndForwards, _imports);
+    return DependencyReport._(
+        uses: UnmodifiableSetView(_uses),
+        forwards: UnmodifiableSetView(_forwards),
+        metaLoadCss: UnmodifiableSetView(_metaLoadCss),
+        imports: UnmodifiableSetView(_imports));
   }
 
   // These can never contain imports.
@@ -38,16 +46,63 @@ class _FindDependenciesVisitor with RecursiveStatementVisitor {
   void visitSupportsCondition(SupportsCondition condition) {}
 
   void visitUseRule(UseRule node) {
-    if (node.url.scheme != 'sass') _usesAndForwards.add(node.url);
+    if (node.url.scheme != 'sass') {
+      _uses.add(node.url);
+    } else if (node.url.toString() == 'sass:meta') {
+      _metaNamespaces.add(node.namespace);
+    }
   }
 
   void visitForwardRule(ForwardRule node) {
-    if (node.url.scheme != 'sass') _usesAndForwards.add(node.url);
+    if (node.url.scheme != 'sass') _forwards.add(node.url);
   }
 
   void visitImportRule(ImportRule node) {
     for (var import in node.imports) {
       if (import is DynamicImport) _imports.add(import.url);
     }
   }
+
+  void visitIncludeRule(IncludeRule node) {
+    if (node.name != 'load-css') return;
+    if (!_metaNamespaces.contains(node.namespace)) return;
+    if (node.arguments.positional.isEmpty) return;
+    var argument = node.arguments.positional.first;
+    if (argument is! StringExpression) return;
+    var url = argument.text.asPlain;
+    try {
+      if (url != null) _metaLoadCss.add(Uri.parse(url));
+    } on FormatException {
+      // Ignore invalid URLs.
+    }
+  }
+}
+
+/// A struct of different types of dependencies a Sass stylesheet can contain.
+class DependencyReport {
+  /// An unmodifiable set of all `@use`d URLs in the stylesheet (exluding
+  /// built-in modules).
+  final Set<Uri> uses;
+
+  /// An unmodifiable set of all `@forward`ed URLs in the stylesheet (excluding
+  /// built-in modules).
+  final Set<Uri> forwards;
+
+  /// An unmodifiable set of all URLs loaded by `meta.load-css()` calls with
+  /// static string arguments outside of mixins.
+  final Set<Uri> metaLoadCss;
+
+  /// An unmodifiable set of all dynamically `@import`ed URLs in the
+  /// stylesheet.
+  final Set<Uri> imports;
+
+  /// An unmodifiable set of all URLs in [uses], [forwards], and [metaLoadCss].
+  Set<Uri> get modules => UnionSet({uses, forwards, metaLoadCss});
+
+  /// An unmodifiable set of all URLs in [uses], [forwards], [metaLoadCss], and
+  /// [imports].
+  Set<Uri> get all => UnionSet({uses, forwards, metaLoadCss, imports});
+
+  DependencyReport._(
+      {required this.uses, required this.forwards, required this.metaLoadCss, required this.imports});
 }

pkg/sass_api/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 5.0.0
+
+* **Breaking change:** Instead of a `Tuple`, `findDependencies()` now returns a
+  `DependencyReport` object with named fields. This provides finer-grained
+  access to import URLs, as well as information about `meta.load-css()` calls
+  with non-interpolated string literal arguments.
+
 ## 4.2.2
 
 * No user-visible changes.

pkg/sass_api/pubspec.yaml

@@ -2,7 +2,7 @@ name: sass_api
 # Note: Every time we add a new Sass AST node, we need to bump the *major*
 # version because it's a breaking change for anyone who's implementing the
 # visitor interface(s).
-version: 4.2.2
+version: 5.0.0
 description: Additional APIs for Dart Sass.
 homepage: https://github.com/sass/dart-sass
 

pubspec.yaml

@@ -1,5 +1,5 @@
 name: sass
-version: 1.58.0-dev
+version: 1.58.0
 description: A Sass implementation in Dart.
 homepage: https://github.com/sass/dart-sass
 

test/cli/shared/watch.dart

@@ -264,6 +264,100 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
                 .validate();
           });
 
+          group("through meta.load-css", () {
+            test("with the default namespace", () async {
+              await d.file("_other.scss", "a {b: c}").create();
+              await d.file("test.scss", """
+                @use 'sass:meta';
+                @include meta.load-css('other');
+              """).create();
+
+              var sass = await watch(["test.scss:out.css"]);
+              await expectLater(
+                  sass.stdout, emits('Compiled test.scss to out.css.'));
+              await expectLater(sass.stdout, _watchingForChanges);
+              await tickIfPoll();
+
+              await d.file("_other.scss", "x {y: z}").create();
+              await expectLater(
+                  sass.stdout, emits('Compiled test.scss to out.css.'));
+              await sass.kill();
+
+              await d
+                  .file("out.css", equalsIgnoringWhitespace("x { y: z; }"))
+                  .validate();
+            });
+
+            test("with a custom namespace", () async {
+              await d.file("_other.scss", "a {b: c}").create();
+              await d.file("test.scss", """
+                @use 'sass:meta' as m;
+                @include m.load-css('other');
+              """).create();
+
+              var sass = await watch(["test.scss:out.css"]);
+              await expectLater(
+                  sass.stdout, emits('Compiled test.scss to out.css.'));
+              await expectLater(sass.stdout, _watchingForChanges);
+              await tickIfPoll();
+
+              await d.file("_other.scss", "x {y: z}").create();
+              await expectLater(
+                  sass.stdout, emits('Compiled test.scss to out.css.'));
+              await sass.kill();
+
+              await d
+                  .file("out.css", equalsIgnoringWhitespace("x { y: z; }"))
+                  .validate();
+            });
+
+            test("with no namespace", () async {
+              await d.file("_other.scss", "a {b: c}").create();
+              await d.file("test.scss", """
+                @use 'sass:meta' as *;
+                @include load-css('other');
+              """).create();
+
+              var sass = await watch(["test.scss:out.css"]);
+              await expectLater(
+                  sass.stdout, emits('Compiled test.scss to out.css.'));
+              await expectLater(sass.stdout, _watchingForChanges);
+              await tickIfPoll();
+
+              await d.file("_other.scss", "x {y: z}").create();
+              await expectLater(
+                  sass.stdout, emits('Compiled test.scss to out.css.'));
+              await sass.kill();
+
+              await d
+                  .file("out.css", equalsIgnoringWhitespace("x { y: z; }"))
+                  .validate();
+            });
+
+            test(r"with $with", () async {
+              await d.file("_other.scss", "a {b: c}").create();
+              await d.file("test.scss", r"""
+                @use 'sass:meta';
+                @include meta.load-css('other', $with: ());
+              """).create();
+
+              var sass = await watch(["test.scss:out.css"]);
+              await expectLater(
+                  sass.stdout, emits('Compiled test.scss to out.css.'));
+              await expectLater(sass.stdout, _watchingForChanges);
+              await tickIfPoll();
+
+              await d.file("_other.scss", "x {y: z}").create();
+              await expectLater(
+                  sass.stdout, emits('Compiled test.scss to out.css.'));
+              await sass.kill();
+
+              await d
+                  .file("out.css", equalsIgnoringWhitespace("x { y: z; }"))
+                  .validate();
+            });
+          });
+
           // Regression test for #550
           test("with an error that's later fixed", () async {
             await d.file("_other.scss", "a {b: c}").create();