Merge pull request #176 from sass/update-dart-sass-dep

Use Dart Sass and the embedded compiler from HEAD by default

Author: nex3

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ env:
 
 on:
   push:
-    branches: [main]
+    branches: [main, feature.*]
     tags: ['**']
   pull_request:
 
@@ -61,6 +61,8 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
           check-latest: true
+      - uses: frenck/action-setup-yq@v1
+        with: {version: v4.30.5} # frenck/action-setup-yq#35
       - uses: arduino/setup-protoc@v1
         with:
           version: ${{ env.PROTOC_VERSION }}
@@ -74,25 +76,17 @@ jobs:
         with: {repo: sass/embedded-protocol, default-ref: null}
 
       - name: Check out Dart Sass
-        id: clone-dart-sass
         uses: sass/clone-linked-repo@v1
-        with: {repo: sass/dart-sass, default-ref: null}
+        with: {repo: sass/dart-sass}
 
       - name: Check out the embedded compiler
         uses: sass/clone-linked-repo@v1
-        with:
-          repo: sass/dart-sass-embedded
-          # If we check out a specific version of Dart Sass, always check out
-          # the embedded compiler as well so we can actually use that Dart Sass
-          # version.
-          default-ref: ${{ !steps.clone-dart-sass.skip && 'main' || null }}
+        with: {repo: sass/dart-sass-embedded}
 
       - name: Link the embedded compiler to Dart Sass
         run: |
-          if [[ -d dart-sass ]]; then
-            echo "dependency_overrides: {sass: {path: ../dart-sass}}" \
-                >> dart-sass-embedded/pubspec.yaml
-          fi
+          yq -i '.dependency_overrides.sass = {"path": "../dart-sass"}' \
+              dart-sass-embedded/pubspec.yaml
 
       - name: Check out the JS API definition
         uses: sass/clone-linked-repo@v1
@@ -102,8 +96,7 @@ jobs:
       - name: npm run init
         run: |
           if [[ -d embedded-protocol ]]; then args=--protocol-path=embedded-protocol; fi
-          if [[ -d dart-sass-embedded ]]; then args="$args --compiler-path=dart-sass-embedded"; fi
-          npm run init -- --api-path=language $args
+          npm run init -- --compiler-path=dart-sass-embedded --api-path=language $args
 
       - run: npm run test
 
@@ -132,6 +125,8 @@ jobs:
         with: {sdk: stable}
       - uses: actions/setup-node@v2
         with: {node-version: "${{ matrix.node_version }}"}
+      - uses: frenck/action-setup-yq@v1
+        with: {version: v4.30.5} # frenck/action-setup-yq#35
       - uses: arduino/setup-protoc@v1
         with:
           version: ${{ env.PROTOC_VERSION }}
@@ -142,25 +137,17 @@ jobs:
         with: {repo: sass/embedded-protocol, default-ref: null}
 
       - name: Check out Dart Sass
-        id: clone-dart-sass
         uses: sass/clone-linked-repo@v1
-        with: {repo: sass/dart-sass, default-ref: null}
+        with: {repo: sass/dart-sass}
 
       - name: Check out the embedded compiler
         uses: sass/clone-linked-repo@v1
-        with:
-          repo: sass/dart-sass-embedded
-          # If we check out a specific version of Dart Sass, always check out
-          # the embedded compiler as well so we can actually use that Dart Sass
-          # version.
-          default-ref: ${{ !steps.clone-dart-sass.skip && 'main' || null }}
+        with: {repo: sass/dart-sass-embedded}
 
       - name: Link the embedded compiler to Dart Sass
         run: |
-          if [[ -d dart-sass ]]; then
-            echo "dependency_overrides: {sass: {path: ../dart-sass}}" \
-                >> dart-sass-embedded/pubspec.yaml
-          fi
+          yq -i '.dependency_overrides.sass = {"path": "../dart-sass"}' \
+              dart-sass-embedded/pubspec.yaml
 
       - name: Check out the JS API definition
         uses: sass/clone-linked-repo@v1
@@ -170,8 +157,7 @@ jobs:
       - name: npm run init
         run: |
           if [[ -d embedded-protocol ]]; then args=--protocol-path=embedded-protocol; fi
-          if [[ -d dart-sass-embedded ]]; then args="$args --compiler-path=dart-sass-embedded"; fi
-          npm run init -- --api-path=language $args
+          npm run init -- --compiler-path=dart-sass-embedded --api-path=language $args
 
       - name: Check out sass-spec
         uses: sass/clone-linked-repo@v1

CONTRIBUTING.md

@@ -35,3 +35,74 @@ such, manual commits should never:
 
 * Update the `package.json`'s `"compiler-version"` field to a non-`-dev` number.
   Changing it from non-`-dev` to dev when using a new feature is fine.
+
+# Keeping in Sync With Other Packages
+
+The embedded host depends on several different components which come from
+different repositories:
+
+* The [Dart Sass embedded compiler].
+* [Dart Sass] (transitively through the embedded compiler).
+* The [Sass embedded protocol].
+* The [Sass JS API definition].
+
+[Dart Sass embedded compiler]: https://github.com/sass/dart-sass-embedded
+[Dart Sass]: https://github.com/sass/dart-sass
+[Sass embedded protocol]: https://github.com/sass/embedded-protocol
+[JS API definition]: https://github.com/sass/sass/tree/main/spec/js-api
+
+These dependencies are made available in different ways depending on context.
+
+## Local Development
+
+When developing locally, you can download all of these dependencies by running
+`npm run init`. This provides the following options for `compiler` (for the
+embedded compiler), `protocol` (for the embedded protocol), and `api` (for the
+JS API):
+
+* `--<type>-path`: The local filesystem path of the package to use. This is
+  useful when doing local development on both the host and its dependencies at
+  the same time.
+
+* `--<type>-ref`: A Git reference for the GitHub repository of the package to
+  clone.
+
+By default:
+
+* This uses the version of the embedded protocol and compiler specified by
+  `protocol-version` in `package.json`, *unless* that version ends in `-dev` in
+  which case it checks out the latest revision on GitHub.
+
+* This uses the embedded compiler version and JS API definition from the latest
+  revision on GitHub.
+
+* This uses the Dart Sass version from the latest revision on GitHub, unless the
+  embedded `--compiler-path` was passed in which case it uses whatever version
+  of Dart Sass that package references.
+
+## Continuous Integration
+
+CI tests also use `npm run init`, so they use the same defaults as local
+development. However, if the pull request description includes a link to a pull
+request for the embedded compiler, Dart Sass, the embedded protocol, or the JS
+API, this will check out that version and run tests against it instead.
+
+## Release
+
+When this package is released to npm, it downloads the embedded protocol version
+that matches `protocol-version` in `package.json`. It downloads the latest JS
+API revision on GitHub.
+
+The release version of the `sass-embedded` package does *not* include the
+embedded compiler or Dart Sass. Instead, we release optional packages of the
+form `sass-embedded-<os>-<arch>`. Each of these contains the published version
+of the embedded compiler that matches `compiler-version` in `package.json` for
+the given operating system/architecture combination.
+
+If either `protocol-version` or `compiler-version` ends with `-dev`, the release
+will fail.
+
+**Note:** As part of the holistic release process for Dart Sass, the embedded
+compiler's CI will automatically update this repository's `package.json` file
+with the latest `compiler-version` and optional dependency versions before
+tagging it for a release.

lib/src/legacy/index.ts

@@ -131,7 +131,7 @@ function convertOptions<sync extends 'sync' | 'async'>(
     // does not.
     if (!signature.includes('(')) signature += '()';
 
-    functions[signature] = wrapFunction(self, callback, sync);
+    functions[signature.trimLeft()] = wrapFunction(self, callback, sync);
   }
 
   const importers =

package.json

@@ -2,7 +2,7 @@
   "name": "sass-embedded",
   "version": "1.56.2",
   "protocol-version": "1.1.0",
-  "compiler-version": "1.56.2",
+  "compiler-version": "1.56.3-dev",
   "description": "Node.js library that communicates with Embedded Dart Sass using the Embedded Sass protocol",
   "repository": "sass/embedded-host-node",
   "author": "Google Inc.",
@@ -16,7 +16,7 @@
     "node": ">=14.0.0"
   },
   "scripts": {
-    "init": "ts-node ./tool/prepare-dev-environment.ts",
+    "init": "ts-node ./tool/init.ts",
     "check": "npm-run-all check:gts check:tsc",
     "check:gts": "gts check",
     "check:tsc": "tsc --noEmit",

tool/get-embedded-compiler.ts

@@ -0,0 +1,76 @@
+// Copyright 2022 Google Inc. 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.
+
+import {promises as fs} from 'fs';
+import * as p from 'path';
+import * as yaml from 'yaml';
+import * as shell from 'shelljs';
+
+import * as utils from './utils';
+
+/**
+ * Downlaods and builds the Embedded Dart Sass compiler.
+ *
+ * Can check out and build the source from a Git `ref` or build from the source
+ * at `path`. By default, checks out the latest revision from GitHub.
+ */
+export async function getEmbeddedCompiler(
+  outPath: string,
+  options?: {ref: string} | {path: string}
+): Promise<void> {
+  const repo = 'dart-sass-embedded';
+
+  let source: string;
+  if (!options || 'ref' in options) {
+    utils.fetchRepo({
+      repo,
+      outPath: utils.BUILD_PATH,
+      ref: options?.ref ?? 'main',
+    });
+    source = p.join(utils.BUILD_PATH, repo);
+    await maybeOverrideSassDependency(source);
+  } else {
+    source = options.path;
+  }
+
+  buildDartSassEmbedded(source);
+  await utils.link(p.join(source, 'build'), p.join(outPath, repo));
+}
+
+/**
+ * Overrides Embedded Dart Sass compiler's dependency on Dart Sass to use the
+ * latest version of Dart Sass from the `main` branch.
+ *
+ * This allows us to avoid needing to commit a dependency override to the
+ * embedded compiler when it doesn't actually require any local changes.
+ */
+async function maybeOverrideSassDependency(repo: string): Promise<void> {
+  const pubspecPath = p.join(repo, 'pubspec.yaml');
+  const pubspec = yaml.parse(
+    await fs.readFile(pubspecPath, {encoding: 'utf-8'})
+  );
+
+  console.log(`Overriding ${repo} to load Dart Sass from HEAD.`);
+
+  pubspec['dependency_overrides'] = {
+    ...pubspec['dependency_overrides'],
+    sass: {git: 'https://github.com/sass/dart-sass.git'},
+  };
+  await fs.writeFile(pubspecPath, yaml.stringify(pubspec), {encoding: 'utf-8'});
+}
+
+// Builds the Embedded Dart Sass executable from the source at `repoPath`.
+function buildDartSassEmbedded(repoPath: string): void {
+  console.log('Downloading dart-sass-embedded dependencies.');
+  shell.exec('dart pub upgrade', {
+    cwd: repoPath,
+    silent: true,
+  });
+
+  console.log('Building dart-sass-embedded executable.');
+  shell.exec('dart run grinder protobuf pkg-standalone-dev', {
+    cwd: repoPath,
+    silent: true,
+  });
+}

tool/get-embedded-protocol.ts

@@ -0,0 +1,72 @@
+// Copyright 2022 Google Inc. 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.
+
+import {mkdirSync} from 'fs';
+import * as p from 'path';
+import * as shell from 'shelljs';
+
+import * as pkg from '../package.json';
+import * as utils from './utils';
+
+/**
+ * Downloads and builds the Embedded Sass protocol definition.
+ *
+ * Can check out and build the source from a Git `ref` or build from the source
+ * at `path`. By default, checks out the tagged version specified in
+ * package.json's `protocol-version` field. If this version ends in `-dev`,
+ * checks out the latest revision from GitHub instead.
+ */
+export async function getEmbeddedProtocol(
+  outPath: string,
+  options?: {ref: string} | {path: string}
+): Promise<void> {
+  const repo = 'embedded-protocol';
+
+  let source: string;
+  if (!options || 'ref' in options) {
+    let ref = options?.ref;
+    if (ref === undefined) {
+      const version = pkg['protocol-version'] as string;
+      ref = version.endsWith('-dev') ? 'main' : version;
+    }
+
+    utils.fetchRepo({repo, outPath: utils.BUILD_PATH, ref});
+    source = p.join(utils.BUILD_PATH, repo);
+  } else {
+    source = options.path;
+  }
+
+  buildEmbeddedProtocol(source);
+  await utils.link('build/embedded-protocol', p.join(outPath, repo));
+}
+
+// Builds the embedded proto at `repoPath` into a pbjs with TS declaration file.
+function buildEmbeddedProtocol(repoPath: string): void {
+  const proto = p.join(repoPath, 'embedded_sass.proto');
+  const protocPath =
+    process.platform === 'win32'
+      ? '%CD%/node_modules/protoc/protoc/bin/protoc.exe'
+      : 'node_modules/protoc/protoc/bin/protoc';
+  const version = shell
+    .exec(`${protocPath} --version`, {silent: true})
+    .stdout.trim();
+  console.log(
+    `Building pbjs and TS declaration file from ${proto} with ${version}.`
+  );
+
+  const pluginPath =
+    process.platform === 'win32'
+      ? '%CD%/node_modules/.bin/protoc-gen-ts.cmd'
+      : 'node_modules/.bin/protoc-gen-ts';
+  mkdirSync('build/embedded-protocol', {recursive: true});
+  shell.exec(
+    `${protocPath} \
+      --plugin="protoc-gen-ts=${pluginPath}" \
+      --js_out="import_style=commonjs,binary:build/embedded-protocol" \
+      --ts_out="build/embedded-protocol" \
+      --proto_path="${repoPath}" \
+      ${proto}`,
+    {silent: true}
+  );
+}

tool/get-js-api.ts

@@ -0,0 +1,34 @@
+// Copyright 2022 Google Inc. 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.
+
+import * as p from 'path';
+
+import * as utils from './utils';
+
+/**
+ * Checks out JS API type definitions from the Sass language repo.
+ *
+ * Can check out a Git `ref` or link to the source at `path`. By default, checks
+ * out the latest revision from GitHub.
+ */
+export async function getJSApi(
+  outPath: string,
+  options?: {ref: string} | {path: string}
+): Promise<void> {
+  const repo = 'sass';
+
+  let source: string;
+  if (!options || 'ref' in options) {
+    utils.fetchRepo({
+      repo,
+      outPath: utils.BUILD_PATH,
+      ref: options?.ref ?? 'main',
+    });
+    source = p.join(utils.BUILD_PATH, repo);
+  } else {
+    source = options.path;
+  }
+
+  await utils.link(p.join(source, 'js-api-doc'), p.join(outPath, repo));
+}