Deprecate @import and global builtins (#2282)

CHANGELOG.md

@@ -1,3 +1,16 @@
+## 1.80.0
+
+* `@import` is now officially deprecated, as are global built-in functions that
+  are available within built-in modules. See [the Sass blog post] for more
+  details on the deprecation process.
+
+[the Sass blog post]: https://sass-lang.com/blog/import-is-deprecated/
+
+### Embedded Host
+
+* Fix an error that would sometimes occur when deprecation warnings were
+  emitted when using a custom importer with the legacy API.
+
 ## 1.79.6
 
 * Fix a bug where Sass would add an extra `*/` after loud comments with

lib/src/callable/async_built_in.dart

@@ -99,8 +99,9 @@ class AsyncBuiltInCallable implements AsyncCallable {
 /// available as function [name] in built-in module [module].
 void warnForGlobalBuiltIn(String module, String name) {
   warnForDeprecation(
-      'Global built-in functions will be deprecated in the future.\n'
-      'Remove the --future-deprecation=global-builtin flag to silence this '
-      'warning for now.',
+      'Global built-in functions are deprecated and will be removed in Dart '
+      'Sass 3.0.0.\n'
+      'Use $module.$name instead.\n\n'
+      'More info and automated migrator: https://sass-lang.com/d/import',
       Deprecation.globalBuiltin);
 }

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: 0243e0f7ee85127d6e1bda5c08e363509959e758
+  // Checksum: 47c97f7824eb25d7f1e64e3230938b88330d40b4
 
   /// Deprecation for passing a string directly to meta.call().
   callString('call-string',
@@ -114,10 +114,11 @@ enum Deprecation {
       deprecatedIn: '1.79.0', description: 'Legacy JS API.'),
 
   /// Deprecation for @import rules.
-  import.future('import', description: '@import rules.'),
+  import('import', deprecatedIn: '1.80.0', description: '@import rules.'),
 
   /// Deprecation for global built-in functions that are available in sass: modules.
-  globalBuiltin.future('global-builtin',
+  globalBuiltin('global-builtin',
+      deprecatedIn: '1.80.0',
       description:
           'Global built-in functions that are available in sass: modules.'),
 

lib/src/parse/stylesheet.dart

@@ -1057,9 +1057,9 @@ abstract class StylesheetParser extends Parser {
       if (argument is DynamicImport) {
         logger.warnForDeprecation(
             Deprecation.import,
-            'Sass @import rules will be deprecated in the future.\n'
-            'Remove the --future-deprecation=import flag to silence this '
-            'warning for now.',
+            'Sass @import rules are deprecated and will be removed in Dart '
+            'Sass 3.0.0.\n\n'
+            'More info and automated migrator: https://sass-lang.com/d/import',
             span: argument.span);
       }
       if ((_inControlDirective || _inMixin) && argument is DynamicImport) {

pkg/sass-parser/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.3.0
+
+* No user-visible changes.
+
 ## 0.2.6
 
 * No user-visible changes.

pkg/sass-parser/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sass-parser",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "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 @@
+## 13.1.0
+
+* No user-visible changes.
+
 ## 13.0.1
 
 * Fix a bug where `LoudComment`s parsed from the indented syntax would include

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: 13.0.1
+version: 13.1.0
 description: Additional APIs for Dart Sass.
 homepage: https://github.com/sass/dart-sass
 
 environment:
   sdk: ">=3.0.0 <4.0.0"
 
 dependencies:
-  sass: 1.79.6
+  sass: 1.80.0
 
 dev_dependencies:
   dartdoc: ^8.0.14

pubspec.yaml

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

test/cli/dart/errors_test.dart

@@ -16,18 +16,18 @@ void main() {
   sharedTests(runSass);
 
   test("for package urls", () async {
-    await d.file("test.scss", "@import 'package:nope/test';").create();
+    await d.file("test.scss", "@use 'package:nope/test';").create();
 
     var sass = await runSass(["--no-unicode", "test.scss"]);
     expect(
         sass.stderr,
         emitsInOrder([
           "Error: Can't find stylesheet to import.",
           "  ,",
-          "1 | @import 'package:nope/test';",
-          "  |         ^^^^^^^^^^^^^^^^^^^",
+          "1 | @use 'package:nope/test';",
+          "  | ^^^^^^^^^^^^^^^^^^^^^^^^",
           "  '",
-          "  test.scss 1:9  root stylesheet"
+          "  test.scss 1:1  root stylesheet"
         ]));
     await sass.shouldExit(65);
   });

test/cli/node/errors_test.dart

@@ -18,18 +18,18 @@ void main() {
   sharedTests(runSass);
 
   test("for package urls", () async {
-    await d.file("test.scss", "@import 'package:nope/test';").create();
+    await d.file("test.scss", "@use 'package:nope/test';").create();
 
     var sass = await runSass(["--no-unicode", "test.scss"]);
     expect(
         sass.stderr,
         emitsInOrder([
           "Error: \"package:\" URLs aren't supported on this platform.",
           "  ,",
-          "1 | @import 'package:nope/test';",
-          "  |         ^^^^^^^^^^^^^^^^^^^",
+          "1 | @use 'package:nope/test';",
+          "  | ^^^^^^^^^^^^^^^^^^^^^^^^",
           "  '",
-          "  test.scss 1:9  root stylesheet"
+          "  test.scss 1:1  root stylesheet"
         ]));
     await sass.shouldExit(65);
   });

test/cli/shared.dart

@@ -110,7 +110,7 @@ void sharedTests(
 
   group("can import files", () {
     test("relative to the entrypoint", () async {
-      await d.file("test.scss", "@import 'dir/test'").create();
+      await d.file("test.scss", "@use 'dir/test'").create();
 
       await d.dir("dir", [d.file("test.scss", "a {b: 1 + 2}")]).create();
 
@@ -119,7 +119,7 @@ void sharedTests(
     });
 
     test("from the load path", () async {
-      await d.file("test.scss", "@import 'test2'").create();
+      await d.file("test.scss", "@use 'test2'").create();
 
       await d.dir("dir", [d.file("test2.scss", "a {b: c}")]).create();
 
@@ -129,8 +129,8 @@ void sharedTests(
 
     test("from SASS_PATH", () async {
       await d.file("test.scss", """
-        @import 'test2';
-        @import 'test3';
+        @use 'test2';
+        @use 'test3';
       """).create();
 
       await d.dir("dir2", [d.file("test2.scss", "a {b: c}")]).create();
@@ -145,12 +145,12 @@ void sharedTests(
     // Regression test for #369
     test("from within a directory, relative to a file on the load path",
         () async {
-      await d.dir(
-          "dir1", [d.file("test.scss", "@import 'subdir/test2'")]).create();
+      await d
+          .dir("dir1", [d.file("test.scss", "@use 'subdir/test2'")]).create();
 
       await d.dir("dir2", [
         d.dir("subdir", [
-          d.file("test2.scss", "@import 'test3'"),
+          d.file("test2.scss", "@use 'test3'"),
           d.file("test3.scss", "a {b: c}")
         ])
       ]).create();
@@ -160,7 +160,7 @@ void sharedTests(
     });
 
     test("relative in preference to from the load path", () async {
-      await d.file("test.scss", "@import 'test2'").create();
+      await d.file("test.scss", "@use 'test2'").create();
       await d.file("test2.scss", "x {y: z}").create();
 
       await d.dir("dir", [d.file("test2.scss", "a {b: c}")]).create();
@@ -170,7 +170,7 @@ void sharedTests(
     });
 
     test("in load path order", () async {
-      await d.file("test.scss", "@import 'test2'").create();
+      await d.file("test.scss", "@use 'test2'").create();
 
       await d.dir("dir1", [d.file("test2.scss", "a {b: c}")]).create();
       await d.dir("dir2", [d.file("test2.scss", "x {y: z}")]).create();
@@ -181,7 +181,7 @@ void sharedTests(
     });
 
     test("from the load path in preference to from SASS_PATH", () async {
-      await d.file("test.scss", "@import 'test2'").create();
+      await d.file("test.scss", "@use 'test2'").create();
 
       await d.dir("dir1", [d.file("test2.scss", "a {b: c}")]).create();
       await d.dir("dir2", [d.file("test2.scss", "x {y: z}")]).create();
@@ -192,7 +192,7 @@ void sharedTests(
     });
 
     test("in SASS_PATH order", () async {
-      await d.file("test.scss", "@import 'test2'").create();
+      await d.file("test.scss", "@use 'test2'").create();
 
       await d.dir("dir1", [d.file("test2.scss", "a {b: c}")]).create();
       await d.dir("dir2", [d.file("test2.scss", "x {y: z}")]).create();
@@ -224,6 +224,8 @@ void sharedTests(
         "grandparent",
         "--load-path",
         "grandparent/parent",
+        "--silence-deprecation",
+        "import",
         "test.scss"
       ], equalsIgnoringWhitespace("a { b: c; } a { b: c; }"));
     });
@@ -240,8 +242,13 @@ void sharedTests(
         d.file("_library.import.scss", "a { b: import-only }")
       ]).create();
 
-      await expectCompiles(["--load-path", "load-path", "test.scss"],
-          equalsIgnoringWhitespace("a { b: regular; } a { b: import-only; }"));
+      await expectCompiles([
+        "--load-path",
+        "load-path",
+        "--silence-deprecation",
+        "import",
+        "test.scss"
+      ], equalsIgnoringWhitespace("a { b: regular; } a { b: import-only; }"));
     });
   });
 
@@ -487,7 +494,14 @@ void sharedTests(
         await d.file("test.scss", "@import 'other'").create();
         await d.dir("dir", [d.file("_other.scss", "#{blue} {x: y}")]).create();
 
-        var sass = await runSass(["--quiet-deps", "-I", "dir", "test.scss"]);
+        var sass = await runSass([
+          "--quiet-deps",
+          "-I",
+          "dir",
+          "--silence-deprecation",
+          "import",
+          "test.scss"
+        ]);
         expect(sass.stderr, emitsDone);
         await sass.shouldExit(0);
       });
@@ -501,7 +515,14 @@ void sharedTests(
           """)
         ]).create();
 
-        var sass = await runSass(["--quiet-deps", "-I", "dir", "test.scss"]);
+        var sass = await runSass([
+          "--quiet-deps",
+          "-I",
+          "dir",
+          "--silence-deprecation",
+          "import",
+          "test.scss"
+        ]);
         expect(sass.stderr, emitsDone);
         await sass.shouldExit(0);
       });
@@ -637,12 +658,15 @@ void sharedTests(
   group("with a bunch of deprecation warnings", () {
     setUp(() async {
       await d.file("test.scss", r"""
-      $_: call("inspect", null);
-      $_: call("rgb", 0, 0, 0);
-      $_: call("nth", null, 1);
-      $_: call("join", null, null);
-      $_: call("if", true, 1, 2);
-      $_: call("hsl", 0, 100%, 100%);
+      @use "sass:list";
+      @use "sass:meta";
+
+      $_: meta.call("inspect", null);
+      $_: meta.call("rgb", 0, 0, 0);
+      $_: meta.call("nth", null, 1);
+      $_: meta.call("join", null, null);
+      $_: meta.call("if", true, 1, 2);
+      $_: meta.call("hsl", 0, 100%, 100%);
 
       $_: 1/2;
       $_: 1/3;
@@ -877,7 +901,8 @@ void sharedTests(
       expect(sass.stdout, emitsDone);
       await sass.shouldExit(65);
     });
-  });
+    // Skipping while no future deprecations exist
+  }, skip: true);
 
   test("doesn't unassign variables", () async {
     // This is a regression test for one of the strangest errors I've ever
@@ -896,7 +921,8 @@ void sharedTests(
     await d.file("_midstream.scss", "@forward 'upstream'").create();
     await d.file("_upstream.scss", r"$c: g").create();
 
-    var sass = await runSass(["input.scss", "output.css"]);
+    var sass = await runSass(
+        ["--silence-deprecation", "import", "input.scss", "output.css"]);
     await sass.shouldExit(0);
 
     await d.file("output.css", equalsIgnoringWhitespace("""

test/cli/shared/deprecations.dart

@@ -29,7 +29,7 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
         var sass = await runSass(["--silence-deprecation=import", "test.scss"]);
         expect(sass.stderr, emits(contains("Future import deprecation")));
         await sass.shouldExit(0);
-      });
+      }, skip: true);
 
       test("for an active future deprecation", () async {
         var sass = await runSass([
@@ -39,7 +39,7 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
         ]);
         expect(sass.stderr, emits(contains("Conflicting options for future")));
         await sass.shouldExit(0);
-      });
+      }, skip: true);
 
       test("in watch mode", () async {
         var sass = await runSass([
@@ -183,7 +183,7 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
         var sass = await runSass(["--fatal-deprecation=import", "test.scss"]);
         expect(sass.stderr, emits(contains("Future import deprecation")));
         await sass.shouldExit(0);
-      });
+      }, skip: true);
 
       test("for a silent deprecation", () async {
         var sass = await runSass([
@@ -493,5 +493,6 @@ void sharedTests(Future<TestProcess> runSass(Iterable<String> arguments)) {
         });
       });
     });
-  });
+    // Skipping while no future deprecations exist
+  }, skip: true);
 }