Deprecate passing a relative URL to compileString() *et al* (#2567)

This also clarifies the documentation on how loads work in the
entrypoint file.

Author: nex3

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.88.0
+
+* Deprecate passing a relative URL to `compileString()` and related functions.
+
 ## 1.87.0
 
 * **Potentially breaking bug fix:** When a plain CSS file with a top-level

lib/sass.dart

@@ -49,7 +49,9 @@ export 'src/evaluation_context.dart' show warn;
 ///
 /// Imports are resolved by trying, in order:
 ///
-/// * Loading a file relative to [path].
+/// * **For relative URLs only:** the URL resolved relative to the current
+///   stylesheet's canonical URL, passed to the importer that loaded the current
+///   stylesheet.
 ///
 /// * Each importer in [importers].
 ///
@@ -147,7 +149,14 @@ CompileResult compileToResult(
 ///
 /// Imports are resolved by trying, in order:
 ///
-/// * The given [importer], with the imported URL resolved relative to [url].
+/// * **For relative URLs only:** the URL resolved relative to the current
+///   stylesheet's canonical URL, passed to the importer that loaded the current
+///   stylesheet.
+///
+///   For the entrypoint file, [url] is the canonical URL and [importer] is the
+///   importer that loaded it. If [url] is a `file:` URL and [importer] is null,
+///   it defaults to a [FilesystemImporter] that loads relative URLs from the
+///   filesystem.
 ///
 /// * Each importer in [importers].
 ///

lib/src/async_compile.dart

@@ -133,6 +133,16 @@ Future<CompileResult> compileStringAsync(
 
   var stylesheet = Stylesheet.parse(source, syntax ?? Syntax.scss, url: url);
 
+  if (stylesheet.span.sourceUrl case Uri(scheme: '')
+      when nodeImporter == null) {
+    deprecationLogger.warnForDeprecation(
+      Deprecation.compileStringRelativeUrl,
+      'Passing a relative `url` argument (${stylesheet.span.sourceUrl}) to '
+      'compileString() or related functions is deprecated and will be an error '
+      'in Dart Sass 2.0.0.',
+    );
+  }
+
   var result = await _compileStylesheet(
     stylesheet,
     logger,

lib/src/compile.dart

@@ -5,7 +5,7 @@
 // DO NOT EDIT. This file was generated from async_compile.dart.
 // See tool/grind/synchronize.dart for details.
 //
-// Checksum: ef3310e5d44fa5a9411c9416fb36f51741dfe6ad
+// Checksum: d305a0f75e329a29f5aff734ac31ce145fd3b8d5
 //
 // ignore_for_file: unused_import
 
@@ -142,6 +142,16 @@ CompileResult compileString(
 
   var stylesheet = Stylesheet.parse(source, syntax ?? Syntax.scss, url: url);
 
+  if (stylesheet.span.sourceUrl case Uri(scheme: '')
+      when nodeImporter == null) {
+    deprecationLogger.warnForDeprecation(
+      Deprecation.compileStringRelativeUrl,
+      'Passing a relative `url` argument (${stylesheet.span.sourceUrl}) to '
+      'compileString() or related functions is deprecated and will be an error '
+      'in Dart Sass 2.0.0.',
+    );
+  }
+
   var result = _compileStylesheet(
     stylesheet,
     logger,

lib/src/deprecation.dart

@@ -15,7 +15,7 @@ enum Deprecation {
   // DO NOT EDIT. This section was generated from the language repo.
   // See tool/grind/generate_deprecations.dart for details.
   //
-  // Checksum: 3639e60773866019c018ae16267c8f23e4df86cf
+  // Checksum: c57ab2eb07ab1df48581b8484ef9bdbad0ddceaa
 
   /// Deprecation for passing a string directly to meta.call().
   callString(
@@ -173,6 +173,13 @@ enum Deprecation {
     description: 'Functions named "type".',
   ),
 
+  /// Deprecation for passing a relative url to compileString().
+  compileStringRelativeUrl(
+    'compile-string-relative-url',
+    deprecatedIn: '1.88.0',
+    description: 'Passing a relative url to compileString().',
+  ),
+
   // END AUTOGENERATED CODE
 
   /// Used for deprecations coming from user-authored code.

pkg/sass-parser/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.4.20
+
+* No user-visible changes.
+
 ## 0.4.19
 
 * No user-visible changes.

pkg/sass-parser/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sass-parser",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "description": "A PostCSS-compatible wrapper of the official Sass parser",
   "repository": "sass/sass",
   "author": "Google Inc.",

pkg/sass_api/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 15.5.0
+
+* No user-visible changes.
+
 ## 15.4.0
 
 * No user-visible changes.

pkg/sass_api/pubspec.yaml

@@ -2,15 +2,15 @@ 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: 15.4.0
+version: 15.5.0
 description: Additional APIs for Dart Sass.
 homepage: https://github.com/sass/dart-sass
 
 environment:
   sdk: ">=3.6.0 <4.0.0"
 
 dependencies:
-  sass: 1.87.0
+  sass: 1.88.0
 
 dev_dependencies:
   dartdoc: ^8.0.14

pubspec.yaml

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

test/deprecations_test.dart

@@ -88,6 +88,24 @@ void main() {
     });
   });
 
+  group("compileStringRelativeUrl is violated by", () {
+    test("a fully relative URL", () {
+      _expectDeprecationCallback(
+          () => compileStringToResult("a {b: c}",
+              url: "foo",
+              fatalDeprecations: {Deprecation.compileStringRelativeUrl}),
+          Deprecation.compileStringRelativeUrl);
+    });
+
+    test("a root-relative URL", () {
+      _expectDeprecationCallback(
+          () => compileStringToResult("a {b: c}",
+              url: "/foo",
+              fatalDeprecations: {Deprecation.compileStringRelativeUrl}),
+          Deprecation.compileStringRelativeUrl);
+    });
+  });
+
   // Deprecated in various Sass versions <=1.56.0
   group("functionUnits is violated by", () {
     test("a hue with a non-angle unit", () {
@@ -136,9 +154,16 @@ void main() {
 }
 
 /// Confirms that [source] will error if [deprecation] is fatal.
-void _expectDeprecation(String source, Deprecation deprecation) {
+void _expectDeprecation(String source, Deprecation deprecation) =>
+    _expectDeprecationCallback(
+        () => compileStringToResult(source, fatalDeprecations: {deprecation}),
+        deprecation);
+
+/// Confirms that [callback] will produce a fatal deprecation error for
+/// [deprecation].
+void _expectDeprecationCallback(void callback(), Deprecation deprecation) {
   try {
-    compileStringToResult(source, fatalDeprecations: {deprecation});
+    callback();
   } catch (e) {
     if (e.toString().contains("$deprecation deprecation to be fatal")) return;
     fail('Unexpected error: $e');