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 <stof@notk.org>

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="@sass@front-end.social 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;

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

@@ -14,7 +14,7 @@ import '../../../visitor/interface/expression.dart';
 /// evaluated.
 ///
 /// {@category AST}
-final class IfExpression implements Expression, CallableInvocation {
+final class IfExpression extends Expression implements CallableInvocation {
   /// The declaration of `if()`, as though it were a normal function.
   static final declaration = ArgumentDeclaration.parse(
       r"@function if($condition, $if-true, $if-false) {");

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

@@ -15,8 +15,8 @@ import '../interpolation.dart';
 /// This is always a plain CSS function.
 ///
 /// {@category AST}
-final class InterpolatedFunctionExpression
-    implements Expression, CallableInvocation {
+final class InterpolatedFunctionExpression extends Expression
+    implements CallableInvocation {
   /// The name of the function being invoked.
   final Interpolation name;
 

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

@@ -13,7 +13,7 @@ import 'unary_operation.dart';
 /// A list literal.
 ///
 /// {@category AST}
-final class ListExpression implements Expression {
+final class ListExpression extends Expression {
   /// The elements of this list.
   final List<Expression> contents;
 

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

@@ -10,7 +10,7 @@ import '../expression.dart';
 /// A map literal.
 ///
 /// {@category AST}
-final class MapExpression implements Expression {
+final class MapExpression extends Expression {
   /// The pairs in this map.
   ///
   /// This is a list of pairs rather than a map because a map may have two keys

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

@@ -10,7 +10,7 @@ import '../expression.dart';
 /// A null literal.
 ///
 /// {@category AST}
-final class NullExpression implements Expression {
+final class NullExpression extends Expression {
   final FileSpan span;
 
   NullExpression(this.span);

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

@@ -11,7 +11,7 @@ import '../expression.dart';
 /// A number literal.
 ///
 /// {@category AST}
-final class NumberExpression implements Expression {
+final class NumberExpression extends Expression {
   /// The numeric value.
   final double value;
 

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

@@ -10,7 +10,7 @@ import '../expression.dart';
 /// An expression wrapped in parentheses.
 ///
 /// {@category AST}
-final class ParenthesizedExpression implements Expression {
+final class ParenthesizedExpression extends Expression {
   /// The internal expression.
   final Expression expression;
 

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

@@ -10,7 +10,7 @@ import '../expression.dart';
 /// A parent selector reference, `&`.
 ///
 /// {@category AST}
-final class SelectorExpression implements Expression {
+final class SelectorExpression extends Expression {
   final FileSpan span;
 
   SelectorExpression(this.span);

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

@@ -16,11 +16,12 @@ import '../interpolation.dart';
 /// A string literal.
 ///
 /// {@category AST}
-final class StringExpression implements Expression {
+final class StringExpression extends Expression {
   /// Interpolation that, when evaluated, produces the contents of this string.
   ///
-  /// Unlike [asInterpolation], escapes are resolved and quotes are not
-  /// included.
+  /// If this is a quoted string, escapes are resolved and quotes are not
+  /// included in this text (unlike [asInterpolation]). If it's an unquoted
+  /// string, escapes are *not* resolved.
   final Interpolation text;
 
   /// Whether `this` has quotes.

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

@@ -14,7 +14,7 @@ import '../supports_condition.dart';
 /// doesn't include the function name wrapping the condition.
 ///
 /// {@category AST}
-final class SupportsExpression implements Expression {
+final class SupportsExpression extends Expression {
   /// The condition itself.
   final SupportsCondition condition;
 

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

@@ -13,7 +13,7 @@ import 'list.dart';
 /// A unary operator, as in `+$var` or `not fn()`.
 ///
 /// {@category AST}
-final class UnaryOperationExpression implements Expression {
+final class UnaryOperationExpression extends Expression {
   /// The operator being invoked.
   final UnaryOperator operator;
 

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

@@ -14,7 +14,7 @@ import '../expression.dart';
 /// constructed dynamically, as for the `call()` function.
 ///
 /// {@category AST}
-final class ValueExpression implements Expression {
+final class ValueExpression extends Expression {
   /// The embedded value.
   final Value value;
 

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

@@ -12,7 +12,7 @@ import '../reference.dart';
 /// A Sass variable.
 ///
 /// {@category AST}
-final class VariableExpression implements Expression, SassReference {
+final class VariableExpression extends Expression implements SassReference {
   /// The namespace of the variable being referenced, or `null` if it's
   /// referenced without a namespace.
   final String? namespace;

lib/src/ast/sass/statement.dart

@@ -5,10 +5,13 @@
 import '../../visitor/interface/statement.dart';
 import 'node.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 statement in a Sass syntax tree.
 ///
 /// {@category AST}
-abstract interface class Statement implements SassNode {
+abstract class Statement implements SassNode {
   /// Calls the appropriate visit method on [visitor].
   T accept<T>(StatementVisitor<T> visitor);
 }

lib/src/ast/sass/statement/content_rule.dart

@@ -14,7 +14,7 @@ import '../statement.dart';
 /// caller.
 ///
 /// {@category AST}
-final class ContentRule implements Statement {
+final class ContentRule extends Statement {
   /// The arguments pass to this `@content` rule.
   ///
   /// This will be an empty invocation if `@content` has no arguments.

lib/src/ast/sass/statement/debug_rule.dart

@@ -13,7 +13,7 @@ import '../statement.dart';
 /// This prints a Sass value for debugging purposes.
 ///
 /// {@category AST}
-final class DebugRule implements Statement {
+final class DebugRule extends Statement {
   /// The expression to print.
   final Expression expression;