Generate deprecations list from the language repo (#2253)

This updates the Deprecation enum to be generated from
spec/deprecations.yaml in the language repo.

Author: jathak

.pubignore

@@ -1,5 +1,5 @@
 # This should be identical to .gitignore except that it doesn't exclude
-# generated protobuf files.
+# generated Dart files.
 
 .buildlog
 .DS_Store

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.77.3
+
+### Dart API
+
+* `Deprecation.duplicateVariableFlags` has been deprecated and replaced with
+  `Deprecation.duplicateVarFlags` to make it consistent with the
+  `duplicate-var-flags` name used on the command line and in the JS API.
+
 ## 1.77.2
 
 * Don't emit deprecation warnings for functions and mixins beginning with `__`.

lib/src/deprecation.dart

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC. Use of this source code is governed by an
+// Copyright 2024 Google LLC. Use of this source code is governed by an
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
@@ -10,34 +10,42 @@ import 'util/nullable.dart';
 
 /// A deprecated feature in the language.
 enum Deprecation {
-  /// Deprecation for passing a string to `call` instead of `get-function`.
+  // START AUTOGENERATED CODE
+  //
+  // DO NOT EDIT. This section was generated from the language repo.
+  // See tool/grind/generate_deprecations.dart for details.
+  //
+  // Checksum: 22d9bdbe92eb39b3c0d6d64ebe1879a431c0037e
+
+  /// Deprecation for passing a string directly to meta.call().
   callString('call-string',
       deprecatedIn: '0.0.0',
       description: 'Passing a string directly to meta.call().'),
 
-  /// Deprecation for `@elseif`.
+  /// Deprecation for @elseif.
   elseif('elseif', deprecatedIn: '1.3.2', description: '@elseif.'),
 
-  /// Deprecation for parsing `@-moz-document`.
+  /// Deprecation for @-moz-document.
   mozDocument('moz-document',
       deprecatedIn: '1.7.2', description: '@-moz-document.'),
 
-  /// Deprecation for importers using relative canonical URLs.
-  relativeCanonical('relative-canonical', deprecatedIn: '1.14.2'),
+  /// Deprecation for imports using relative canonical URLs.
+  relativeCanonical('relative-canonical',
+      deprecatedIn: '1.14.2',
+      description: 'Imports using relative canonical URLs.'),
 
-  /// Deprecation for declaring new variables with `!global`.
+  /// Deprecation for declaring new variables with !global.
   newGlobal('new-global',
       deprecatedIn: '1.17.2',
       description: 'Declaring new variables with !global.'),
 
-  /// Deprecation for certain functions in the color module matching the
-  /// behavior of their global counterparts for compatiblity reasons.
+  /// Deprecation for using color module functions in place of plain CSS functions.
   colorModuleCompat('color-module-compat',
       deprecatedIn: '1.23.0',
       description:
           'Using color module functions in place of plain CSS functions.'),
 
-  /// Deprecation for treating `/` as division.
+  /// Deprecation for / operator for division.
   slashDiv('slash-div',
       deprecatedIn: '1.33.0', description: '/ operator for division.'),
 
@@ -46,46 +54,55 @@ enum Deprecation {
       deprecatedIn: '1.54.0',
       description: 'Leading, trailing, and repeated combinators.'),
 
-  /// Deprecation for ambiguous `+` and `-` operators.
+  /// Deprecation for ambiguous + and - operators.
   strictUnary('strict-unary',
       deprecatedIn: '1.55.0', description: 'Ambiguous + and - operators.'),
 
-  /// Deprecation for passing invalid units to certain built-in functions.
+  /// Deprecation for passing invalid units to built-in functions.
   functionUnits('function-units',
       deprecatedIn: '1.56.0',
       description: 'Passing invalid units to built-in functions.'),
 
-  /// Deprecation for passing percentages to the Sass abs() function.
-  absPercent('abs-percent',
-      deprecatedIn: '1.65.0',
-      description: 'Passing percentages to the Sass abs() function.'),
-
-  duplicateVariableFlags('duplicate-var-flags',
+  /// Deprecation for using !default or !global multiple times for one variable.
+  duplicateVarFlags('duplicate-var-flags',
       deprecatedIn: '1.62.0',
       description:
           'Using !default or !global multiple times for one variable.'),
 
+  /// Deprecation for passing null as alpha in the ${isJS ? 'JS': 'Dart'} API.
   nullAlpha('null-alpha',
       deprecatedIn: '1.62.3',
       description: 'Passing null as alpha in the ${isJS ? 'JS' : 'Dart'} API.'),
 
+  /// Deprecation for passing percentages to the Sass abs() function.
+  absPercent('abs-percent',
+      deprecatedIn: '1.65.0',
+      description: 'Passing percentages to the Sass abs() function.'),
+
+  /// Deprecation for using the current working directory as an implicit load path.
   fsImporterCwd('fs-importer-cwd',
       deprecatedIn: '1.73.0',
       description:
           'Using the current working directory as an implicit load path.'),
 
+  /// Deprecation for function and mixin names beginning with --.
   cssFunctionMixin('css-function-mixin',
       deprecatedIn: '1.76.0',
       description: 'Function and mixin names beginning with --.'),
 
-  @Deprecated('This deprecation name was never actually used.')
-  calcInterp('calc-interp', deprecatedIn: null),
-
-  /// Deprecation for `@import` rules.
+  /// Deprecation for @import rules.
   import.future('import', description: '@import rules.'),
 
+  // END AUTOGENERATED CODE
+
   /// Used for deprecations coming from user-authored code.
-  userAuthored('user-authored', deprecatedIn: null);
+  userAuthored('user-authored', deprecatedIn: null),
+
+  @Deprecated('This deprecation name was never actually used.')
+  calcInterp('calc-interp', deprecatedIn: null);
+
+  @Deprecated('Use duplicateVarFlags instead.')
+  static const duplicateVariableFlags = duplicateVarFlags;
 
   /// A unique ID for this deprecation in kebab case.
   ///

lib/src/parse/stylesheet.dart

@@ -235,7 +235,7 @@ abstract class StylesheetParser extends Parser {
         case 'default':
           if (guarded) {
             logger.warnForDeprecation(
-                Deprecation.duplicateVariableFlags,
+                Deprecation.duplicateVarFlags,
                 '!default should only be written once for each variable.\n'
                 'This will be an error in Dart Sass 2.0.0.',
                 span: scanner.spanFrom(flagStart));
@@ -248,7 +248,7 @@ abstract class StylesheetParser extends Parser {
                 scanner.spanFrom(flagStart));
           } else if (global) {
             logger.warnForDeprecation(
-                Deprecation.duplicateVariableFlags,
+                Deprecation.duplicateVarFlags,
                 '!global should only be written once for each variable.\n'
                 'This will be an error in Dart Sass 2.0.0.',
                 span: scanner.spanFrom(flagStart));

pkg/sass_api/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 10.4.3
+
+* No user-visible changes.
+
 ## 10.4.2
 
 * 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: 10.4.2
+version: 10.4.3
 description: Additional APIs for Dart Sass.
 homepage: https://github.com/sass/dart-sass
 
 environment:
   sdk: ">=3.0.0 <4.0.0"
 
 dependencies:
-  sass: 1.77.2
+  sass: 1.77.3
 
 dev_dependencies:
   dartdoc: ">=6.0.0 <9.0.0"

pubspec.yaml

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

test/double_check_test.dart

@@ -7,25 +7,39 @@
 import 'dart:io';
 import 'dart:convert';
 
+import 'package:crypto/crypto.dart';
 import 'package:path/path.dart' as p;
 import 'package:pub_semver/pub_semver.dart';
 import 'package:pubspec_parse/pubspec_parse.dart';
 import 'package:test/test.dart';
 
+import '../tool/grind/generate_deprecations.dart' as deprecations;
 import '../tool/grind/synchronize.dart' as synchronize;
 
 /// Tests that double-check that everything in the repo looks sensible.
 void main() {
-  group("synchronized file is up-to-date:", () {
-    synchronize.sources.forEach((sourcePath, targetPath) {
-      test(targetPath, () {
-        if (File(targetPath).readAsStringSync() !=
-            synchronize.synchronizeFile(sourcePath)) {
-          fail("$targetPath is out-of-date.\n"
-              "Run `dart pub run grinder` to update it.");
-        }
+  group("up-to-date generated", () {
+    group("synchronized file:", () {
+      synchronize.sources.forEach((sourcePath, targetPath) {
+        test(targetPath, () {
+          if (File(targetPath).readAsStringSync() !=
+              synchronize.synchronizeFile(sourcePath)) {
+            fail("$targetPath is out-of-date.\n"
+                "Run `dart run grinder` to update it.");
+          }
+        });
       });
     });
+
+    test("deprecations", () {
+      var inputText = File(deprecations.yamlPath).readAsStringSync();
+      var outputText = File(deprecations.dartPath).readAsStringSync();
+      var checksum = sha1.convert(utf8.encode(inputText));
+      if (!outputText.contains('// Checksum: $checksum')) {
+        fail('${deprecations.dartPath} is out-of-date.\n'
+            'Run `dart run grinder` to update it.');
+      }
+    });
   },
       // Windows sees different bytes than other OSes, possibly because of
       // newline normalization issues.

tool/grind.dart

@@ -11,15 +11,18 @@ import 'package:grinder/grinder.dart';
 import 'package:path/path.dart' as p;
 import 'package:source_span/source_span.dart';
 
+import 'grind/generate_deprecations.dart';
 import 'grind/synchronize.dart';
 import 'grind/utils.dart';
 
 export 'grind/bazel.dart';
 export 'grind/benchmark.dart';
 export 'grind/double_check.dart';
 export 'grind/frameworks.dart';
+export 'grind/generate_deprecations.dart';
 export 'grind/subpackages.dart';
 export 'grind/synchronize.dart';
+export 'grind/utils.dart';
 
 void main(List<String> args) {
   pkg.humanName.value = "Dart Sass";
@@ -127,7 +130,7 @@ void main(List<String> args) {
 }
 
 @DefaultTask('Compile async code and reformat.')
-@Depends(format, synchronize)
+@Depends(format, synchronize, deprecations)
 void all() {}
 
 @Task('Run the Dart formatter.')
@@ -140,7 +143,7 @@ void npmInstall() =>
     run(Platform.isWindows ? "npm.cmd" : "npm", arguments: ["install"]);
 
 @Task('Runs the tasks that are required for running tests.')
-@Depends(format, synchronize, protobuf, "pkg-npm-dev", npmInstall,
+@Depends(format, synchronize, protobuf, deprecations, "pkg-npm-dev", npmInstall,
     "pkg-standalone-dev")
 void beforeTest() {}
 
@@ -213,9 +216,9 @@ String _readAndResolveMarkdown(String path) => File(path)
 
 /// Returns a map from JS type declaration file names to their contnets.
 Map<String, String> _fetchJSTypes() {
-  var languageRepo = _updateLanguageRepo();
+  updateLanguageRepo();
 
-  var typeRoot = p.join(languageRepo, 'js-api-doc');
+  var typeRoot = p.join('build/language', 'js-api-doc');
   return {
     for (var entry in Directory(typeRoot).listSync(recursive: true))
       if (entry is File && entry.path.endsWith('.d.ts'))
@@ -231,6 +234,7 @@ void _matchError(Match match, String message, {Object? url}) {
 }
 
 @Task('Compile the protocol buffer definition to a Dart library.')
+@Depends(updateLanguageRepo)
 Future<void> protobuf() async {
   Directory('build').createSync(recursive: true);
 
@@ -250,8 +254,6 @@ dart run protoc_plugin "\$@"
     run('chmod', arguments: ['a+x', 'build/protoc-gen-dart']);
   }
 
-  _updateLanguageRepo();
-
   await runAsync("buf",
       arguments: ["generate"],
       runOptions: RunOptions(environment: {
@@ -321,19 +323,3 @@ String _updateHomebrewLanguageRevision(String formula) {
       match.group(0)!.replaceFirst(match.group(1)!, languageRepoRevision) +
       formula.substring(match.end);
 }
-
-/// Clones the main branch of `github.com/sass/sass` and returns the path to the
-/// clone.
-///
-/// If the `UPDATE_SASS_SASS_REPO` environment variable is `false`, this instead
-/// assumes the repo that already exists at `build/language/sass`.
-/// `UPDATE_SASS_PROTOCOL` is also checked as a deprecated alias for
-/// `UPDATE_SASS_SASS_REPO`.
-String _updateLanguageRepo() =>
-    // UPDATE_SASS_PROTOCOL is considered deprecated, because it doesn't apply as
-    // generically to other tasks.
-    Platform.environment['UPDATE_SASS_SASS_REPO'] != 'false' &&
-            Platform.environment['UPDATE_SASS_PROTOCOL'] != 'false'
-        ? cloneOrCheckout("https://github.com/sass/sass.git", "main",
-            name: 'language')
-        : 'build/language';

tool/grind/double_check.dart

@@ -5,13 +5,12 @@
 import 'dart:io';
 
 import 'package:cli_pkg/cli_pkg.dart' as pkg;
+import 'package:collection/collection.dart';
 import 'package:grinder/grinder.dart';
 import 'package:path/path.dart' as p;
 import 'package:pub_api_client/pub_api_client.dart';
 import 'package:pubspec_parse/pubspec_parse.dart';
 
-import 'package:sass/src/utils.dart';
-
 import 'utils.dart';
 
 @Task('Verify that the package is in a good state to release.')
@@ -21,7 +20,7 @@ Future<void> doubleCheckBeforeRelease() async {
     fail("GITHUB_REF $ref is different than pubspec version ${pkg.version}.");
   }
 
-  if (listEquals(pkg.version.preRelease, ["dev"])) {
+  if (const ListEquality<Object?>().equals(pkg.version.preRelease, ["dev"])) {
     fail("${pkg.version} is a dev release.");
   }