Initial implementation of a PostCSS-compatible parser JS API (#2304)

This is just a vertical slice designed to solidify the general
principles of the API design and ensure that everything works as
expected. It's not yet usable as a full-fledged parser.

Co-authored-by: Christophe Coevoet <[email protected]>

Author: nex3

.github/dependabot.yml

@@ -10,3 +10,12 @@ updates:
       - "/.github/util/*/"
     schedule:
       interval: "weekly"
+  - package-ecosystem: "npm"
+    directories:
+      - "/"
+      - "/package"
+      - "/pkg/sass-parser"
+    ignore:
+      dependency-name: "sass"
+    schedule:
+      interval: "weekly"

.github/workflows/release.yml

@@ -102,8 +102,8 @@ jobs:
         run: dart run grinder protobuf pkg-pub-deploy
         env: {PUB_CREDENTIALS: "${{ secrets.PUB_CREDENTIALS }}"}
 
-  deploy_sub_packages:
-    name: Deploy Sub-Packages
+  deploy_sass_api:
+    name: Deploy sass_api
     runs-on: ubuntu-latest
     needs: [deploy_pub]
 
@@ -113,12 +113,33 @@ jobs:
         with: {github-token: "${{ github.token }}"}
 
       - name: Deploy
-        run: dart run grinder deploy-sub-packages
+        run: dart run grinder deploy-sass-api
         env:
           PUB_CREDENTIALS: "${{ secrets.PUB_CREDENTIALS }}"
           GH_TOKEN: "${{ secrets.GH_TOKEN }}"
           GH_USER: sassbot
 
+  deploy_sass_parser:
+    name: Deploy sass-parser
+    runs-on: ubuntu-latest
+    needs: [deploy_npm]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: '${{ secrets.NPM_TOKEN }}'
+
+      - name: Get version
+        id: version
+        run: |
+          echo "version=$(jq .version pkg/sass-parser/package.json)" | tee --append "$GITHUB_OUTPUT"
+      - run: git tag sass-parser/${{ steps.version.outputs.version }}
+      - run: git push --tag
+
   deploy_homebrew:
     name: Deploy Homebrew
     runs-on: ubuntu-latest

.github/workflows/test.yml

@@ -311,3 +311,75 @@ jobs:
       run: dart run test -p chrome -j 2
       env:
         CHROME_EXECUTABLE: chrome
+
+  sass_parser_tests:
+    name: "sass-parser Tests | Dart ${{ matrix.dart_channel }} | Node ${{ matrix.node-version }}"
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        dart_channel: [stable]
+        node-version: ['lts/*']
+        include:
+          # Test older LTS versions
+          # 
+          # TODO: Test on lts/-2 and lts/-3 once they support
+          # `structuredClone()` (that is, once they're v18 or later).
+          - os: ubuntu-latest
+            dart_channel: stable
+            node-version: lts/-1
+          # Test LTS version with dart dev channel
+          - os: ubuntu-latest
+            dart_channel: dev
+            node-version: 'lts/*'
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/util/initialize
+        with:
+          dart-sdk: ${{ matrix.dart_channel }}
+          github-token: ${{ github.token }}
+          node-version: ${{ matrix.node-version }}
+
+      - run: dart run grinder pkg-npm-dev
+        env: {UPDATE_SASS_SASS_REPO: false}
+      - run: npm link
+        working-directory: build/npm
+      - run: npm install
+        working-directory: pkg/sass-parser/
+      - run: npm link sass
+        working-directory: pkg/sass-parser/
+      - name: Run tests
+        run: npm test
+        working-directory: pkg/sass-parser/
+
+  sass_parser_static_analysis:
+    name: "sass-parser Static Analysis"
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: {node-version: 'lts/*'}
+      - run: npm install
+        working-directory: pkg/sass-parser/
+      - name: Run static analysis
+        run: npm run check
+        working-directory: pkg/sass-parser/
+
+  # TODO - postcss/postcss#1958: Enable this once PostCSS doesn't have TypeDoc
+  # warnings.
+
+  # sass_parser_typedoc:
+  #   name: "sass-parser Typedoc"
+  #   runs-on: ubuntu-latest
+  #
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: actions/setup-node@v4
+  #       with: {node-version: 'lts/*'}
+  #     - run: npm install
+  #       working-directory: pkg/sass-parser/
+  #     - run: npm run typedoc
+  #       working-directory: pkg/sass-parser/

.gitignore

@@ -12,8 +12,10 @@ pubspec.lock
 package-lock.json
 /benchmark/source
 node_modules/
+dist/
 /doc/api
 /pkg/*/doc/api
+/pkg/sass-parser/doc
 
 # Generated protocol buffer files.
 *.pb*.dart

README.md

@@ -3,7 +3,7 @@ A [Dart][dart] implementation of [Sass][sass]. **Sass makes CSS fun**.
 <table>
   <tr>
     <td>
-      <img width="118px" alt="Sass logo" src="https://rawgit.com/sass/sass-site/master/source/assets/img/logos/logo.svg" />
+      <img width="118px" alt="Sass logo" src="https://rawgit.com/sass/sass-site/main/source/assets/img/logos/logo.svg" />
     </td>
     <td valign="middle">
       <a href="https://www.npmjs.com/package/sass"><img width="100%" alt="npm statistics" src="https://nodei.co/npm/sass.png?downloads=true"></a>
@@ -14,6 +14,8 @@ A [Dart][dart] implementation of [Sass][sass]. **Sass makes CSS fun**.
       <a href="https://github.com/sass/dart-sass/actions"><img alt="GitHub actions build status" src="https://github.com/sass/dart-sass/workflows/CI/badge.svg"></a>
     </td>
     <td>
+      <a href="https://front-end.social/@sass"><img alt="@[email protected] on Fediverse" src="https://img.shields.io/mastodon/follow/110159358073946175?domain=https%3A%2F%2Ffront-end.social"></a>
+      <br>
       <a href="https://twitter.com/SassCSS"><img alt="@SassCSS on Twitter" src="https://img.shields.io/twitter/follow/SassCSS?label=%40SassCSS&style=social"></a>
       <br>
       <a href="https://stackoverflow.com/questions/tagged/sass"><img alt="stackoverflow" src="https://img.shields.io/stackexchange/stackoverflow/t/sass?label=Sass%20questions&logo=stackoverflow&style=social"></a>

lib/src/ast/sass/expression.dart

@@ -13,15 +13,20 @@ import '../../value.dart';
 import '../../visitor/interface/expression.dart';
 import '../sass.dart';
 
+// Note: despite not defining any methods here, this has to be a concrete class
+// so we can expose its accept() function to the JS parser.
+
 /// A SassScript expression in a Sass syntax tree.
 ///
 /// {@category AST}
 /// {@category Parsing}
 @sealed
-abstract interface class Expression implements SassNode {
+abstract class Expression implements SassNode {
   /// Calls the appropriate visit method on [visitor].
   T accept<T>(ExpressionVisitor<T> visitor);
 
+  Expression();
+
   /// Parses an expression from [contents].
   ///
   /// If passed, [url] is the name of the file from which [contents] comes.

lib/src/ast/sass/expression/binary_operation.dart

@@ -14,7 +14,7 @@ import 'list.dart';
 /// A binary operator, as in `1 + 2` or `$this and $other`.
 ///
 /// {@category AST}
-final class BinaryOperationExpression implements Expression {
+final class BinaryOperationExpression extends Expression {
   /// The operator being invoked.
   final BinaryOperator operator;
 
@@ -111,6 +111,9 @@ final class BinaryOperationExpression implements Expression {
 ///
 /// {@category AST}
 enum BinaryOperator {
+  // Note: When updating these operators, also update
+  // pkg/sass-parser/lib/src/expression/binary-operation.ts.
+
   /// The Microsoft equals operator, `=`.
   singleEquals('single equals', '=', 0),
 

lib/src/ast/sass/expression/boolean.dart

@@ -10,7 +10,7 @@ import '../expression.dart';
 /// A boolean literal, `true` or `false`.
 ///
 /// {@category AST}
-final class BooleanExpression implements Expression {
+final class BooleanExpression extends Expression {
   /// The value of this expression.
   final bool value;
 

lib/src/ast/sass/expression/color.dart

@@ -11,7 +11,7 @@ import '../expression.dart';
 /// A color literal.
 ///
 /// {@category AST}
-final class ColorExpression implements Expression {
+final class ColorExpression extends Expression {
   /// The value of this color.
   final SassColor value;
 

lib/src/ast/sass/expression/function.dart

@@ -17,8 +17,8 @@ import '../reference.dart';
 /// interpolation.
 ///
 /// {@category AST}
-final class FunctionExpression
-    implements Expression, CallableInvocation, SassReference {
+final class FunctionExpression extends Expression
+    implements CallableInvocation, SassReference {
   /// The namespace of the function being invoked, or `null` if it's invoked
   /// without a namespace.
   final String? namespace;