Add TypeScript type declarations to the npm package (#1563)

Closes #13

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.45.0-rc.2
+
+### JS API
+
+* Ship TypeScript type declarations with the package.
+
 ## 1.45.0-rc.1
 
 ### JS API

package/package.json

@@ -18,7 +18,9 @@
   },
   "dependencies": {
     "chokidar": ">=3.0.0 <4.0.0",
-    "immutable": "^4.0.0"
+    "immutable": "^4.0.0",
+    "source-map-js": ">=0.6.2 <2.0.0"
   },
-  "keywords": ["style", "scss", "sass", "preprocessor", "css"]
+  "keywords": ["style", "scss", "sass", "preprocessor", "css"],
+  "types": "types/index.d.ts"
 }

pkg/sass_api/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.0.0-beta.22
+
+* No user-visible changes.
+
 ## 1.0.0-beta.21
 
 * 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: 1.0.0-beta.21
+version: 1.0.0-beta.22
 description: Additional APIs for Dart Sass.
 homepage: https://github.com/sass/dart-sass
 
@@ -10,7 +10,7 @@ environment:
   sdk: '>=2.12.0 <3.0.0'
 
 dependencies:
-  sass: 1.45.0-rc.1
+  sass: 1.45.0-rc.2
 
 dependency_overrides:
   sass: {path: ../..}

pubspec.yaml

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

tool/grind.dart

@@ -12,6 +12,7 @@ import 'package:path/path.dart' as p;
 import 'package:source_span/source_span.dart';
 
 import 'grind/synchronize.dart';
+import 'grind/utils.dart';
 
 export 'grind/bazel.dart';
 export 'grind/benchmark.dart';
@@ -39,6 +40,7 @@ void main(List<String> args) {
       json.decode(File("package/package.json").readAsStringSync())
           as Map<String, dynamic>;
   pkg.npmReadme.fn = () => _readAndResolveMarkdown("package/README.npm.md");
+  pkg.npmAdditionalFiles.fn = _fetchJSTypes;
   pkg.standaloneName.value = "dart-sass";
   pkg.githubUser.fn = () => Platform.environment["GH_USER"];
   pkg.githubPassword.fn = () => Platform.environment["GH_TOKEN"];
@@ -144,6 +146,20 @@ String _readAndResolveMarkdown(String path) => File(path)
       return included.substring(headerMatch.end, sectionEnd).trim();
     });
 
+/// Returns a map from JS type declaration file names to their contnets.
+Map<String, String> _fetchJSTypes() {
+  var languageRepo =
+      cloneOrCheckout("https://github.com/sass/sass", "main", name: 'language');
+
+  var typeRoot = p.join(languageRepo, 'js-api-doc');
+  return {
+    for (var entry in Directory(typeRoot).listSync(recursive: true))
+      if (entry is File && entry.path.endsWith('.d.ts'))
+        p.join('types', p.relative(entry.path, from: typeRoot)):
+            entry.readAsStringSync()
+  };
+}
+
 /// Throws a nice [SourceSpanException] associated with [match].
 void _matchError(Match match, String message, {Object? url}) {
   var file = SourceFile.fromString(match.input, url: url);

tool/grind/bazel.dart

@@ -16,8 +16,8 @@ Future<void> updateBazel() async {
 
   run("npm", arguments: ["install", "-g", "yarn"]);
 
-  var repo = await cloneOrCheckout(
-      "https://github.com/bazelbuild/rules_sass.git", "main");
+  var repo =
+      cloneOrCheckout("https://github.com/bazelbuild/rules_sass.git", "main");
 
   var packageFile = File(p.join(repo, "sass", "package.json"));
   log("updating ${packageFile.path}");

tool/grind/benchmark.dart

@@ -32,11 +32,11 @@ Future<void> benchmarkGenerate() async {
       ".foo {a: b}", math.pow(2, 17),
       footer: '.bar {@extend .foo}');
 
-  await cloneOrCheckout("https://github.com/twbs/bootstrap", "v4.1.3");
+  cloneOrCheckout("https://github.com/twbs/bootstrap", "v4.1.3");
   await _writeNTimes("${sources.path}/bootstrap.scss",
       "@import '../bootstrap/scss/bootstrap';", 16);
 
-  await cloneOrCheckout("https://github.com/alex-page/sass-a11ycolor",
+  cloneOrCheckout("https://github.com/alex-page/sass-a11ycolor",
       "2e7ef93ec06f8bbec80b632863e4b2811618af89");
   File("${sources.path}/a11ycolor.scss").writeAsStringSync("""
     @import '../sass-a11ycolor/dist';
@@ -55,14 +55,14 @@ Future<void> benchmarkGenerate() async {
     }
   """);
 
-  await cloneOrCheckout("https://github.com/zaydek/duomo", "v0.7.12");
+  cloneOrCheckout("https://github.com/zaydek/duomo", "v0.7.12");
   File("${sources.path}/duomo.scss")
       .writeAsStringSync("@import '../duomo/scripts/duomo.scss'");
 
   // Note: This version only supports Node Sass 5.x, which only supports up to
   // Node 14.x. Once there's a version that support Node Sass 6.x, we should use
   // that instead.
-  var carbon = await cloneOrCheckout(
+  var carbon = cloneOrCheckout(
       "https://github.com/carbon-design-system/ibm-cloud-cognitive",
       "@carbon/ibm-cloud-cognitive@0.93.2");
   await runAsync("npm", arguments: ["install"], workingDirectory: carbon);
@@ -101,9 +101,8 @@ Future<void> _writeNTimes(String path, String text, num times,
 @Depends(benchmarkGenerate, "pkg-compile-snapshot", "pkg-compile-native",
     "pkg-npm-release")
 Future<void> benchmark() async {
-  var libsass =
-      await cloneOrCheckout('https://github.com/sass/libsass', 'master');
-  var sassc = await cloneOrCheckout('https://github.com/sass/sassc', 'master');
+  var libsass = cloneOrCheckout('https://github.com/sass/libsass', 'master');
+  var sassc = cloneOrCheckout('https://github.com/sass/sassc', 'master');
 
   await runAsync("make",
       runOptions: RunOptions(

tool/grind/frameworks.dart

@@ -31,7 +31,7 @@ Future<void> fetchBulma() => _getLatestRelease('jgthms/bulma');
 /// If [pattern] is passed, this will clone the latest release that matches that
 /// pattern.
 Future<void> _getLatestRelease(String slug, {Pattern? pattern}) async {
-  await cloneOrCheckout('git://github.com/$slug',
+  cloneOrCheckout('git://github.com/$slug',
       await _findLatestRelease(slug, pattern: pattern));
 }
 

tool/grind/utils.dart

@@ -2,7 +2,6 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
-import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
@@ -45,29 +44,33 @@ String environment(String name) {
 /// Ensure that the repository at [url] is cloned into the build directory and
 /// pointing to [ref].
 ///
+/// If [name] is passed, it's used as the basename of the directory for the
+/// repo. Otherwise, [url]'s basename is used.
+///
 /// Returns the path to the repository.
-Future<String> cloneOrCheckout(String url, String ref) async {
-  var name = p.url.basename(url);
-  if (p.url.extension(name) == ".git") name = p.url.withoutExtension(name);
+String cloneOrCheckout(String url, String ref, {String? name}) {
+  if (name == null) {
+    name = p.url.basename(url);
+    if (p.url.extension(name) == ".git") name = p.url.withoutExtension(name);
+  }
 
   var path = p.join("build", name);
 
   if (!Directory(p.join(path, '.git')).existsSync()) {
     delete(Directory(path));
-    await runAsync("git", arguments: ["init", path]);
-    await runAsync("git",
+    run("git", arguments: ["init", path]);
+    run("git",
         arguments: ["config", "advice.detachedHead", "false"],
         workingDirectory: path);
-    await runAsync("git",
+    run("git",
         arguments: ["remote", "add", "origin", url], workingDirectory: path);
   } else {
     log("Updating $url");
   }
 
-  await runAsync("git",
+  run("git",
       arguments: ["fetch", "origin", "--depth=1", ref], workingDirectory: path);
-  await runAsync("git",
-      arguments: ["checkout", "FETCH_HEAD"], workingDirectory: path);
+  run("git", arguments: ["checkout", "FETCH_HEAD"], workingDirectory: path);
   log("");
 
   return path;