Merge pull request #1413 from sass/sass-api

Add a sass_api package that exposes more API details

Author: nex3

.github/workflows/ci.yml

@@ -121,11 +121,9 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: dart-lang/setup-dart@v1
-        # TODO(nweiz): Use the latest Dart when dart-lang/sdk#45488
-        with: {sdk: 2.12.4}
       - run: dart pub get
-      - name: Analyze dart
-        run: dartanalyzer --fatal-warnings --fatal-infos lib tool test
+      - name: Analyze Dart
+        run: dart analyze --fatal-warnings --fatal-infos .
 
   dartdoc:
     name: Dartdoc
@@ -135,10 +133,14 @@ jobs:
       - uses: actions/checkout@v2
       - uses: dart-lang/setup-dart@v1
       - run: dart pub get
-      - name: Run dartdoc
+      - name: dartdoc sass
         run: dartdoc --quiet --no-generate-docs
           --errors ambiguous-doc-reference,broken-link,deprecated
           --errors unknown-directive,unknown-macro,unresolved-doc-reference
+      - name: dartdoc sass_api
+        run: cd pkg/sass_api && dartdoc --quiet --no-generate-docs
+          --errors ambiguous-doc-reference,broken-link,deprecated
+          --errors unknown-directive,unknown-macro,unresolved-doc-reference
 
   sanity_checks:
     name: Sanity checks
@@ -252,6 +254,23 @@ jobs:
         run: dart pub run grinder pkg-pub-deploy
         env: {PUB_CREDENTIALS: "${{ secrets.PUB_CREDENTIALS }}"}
 
+  deploy_sub_packages:
+    name: "Deploy Sub-Packages"
+    runs-on: ubuntu-latest
+    needs: [deploy_pub]
+    if: "startsWith(github.ref, 'refs/tags/') && github.repository == 'sass/dart-sass'"
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dart-lang/setup-dart@v1
+      - run: dart pub get
+      - name: Deploy
+        run: dart pub run grinder deploy-sub-packages
+        env:
+          PUB_CREDENTIALS: "${{ secrets.PUB_CREDENTIALS }}"
+          GH_TOKEN: "${{ secrets.GH_TOKEN }}"
+          GH_USER: sassbot
+
   deploy_homebrew:
     name: "Deploy Homebrew"
     runs-on: ubuntu-latest

.gitignore

@@ -13,3 +13,4 @@ package-lock.json
 /benchmark/source
 node_modules/
 /doc/api
+/pkg/*/doc/api

CONTRIBUTING.md

@@ -8,6 +8,7 @@ Want to contribute? Great! First, read this page.
   * [Changing the Node API](#changing-the-node-api)
   * [Synchronizing](#synchronizing)
   * [File Headers](#file-headers)
+* [Release Process](#release-process)
 
 ## Before You Contribute
 
@@ -208,3 +209,27 @@ All files in the project must start with the following header.
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 ```
+
+## Release Process
+
+Most of the release process is fully automated on GitHub actions, triggered by
+pushing a tag matching the current `pubspec.yaml` version. However, there are a
+few things to do before pushing that tag:
+
+* Make sure the `pubspec.yaml` version doesn't end in `-dev`. (This is a Dart
+  convention to distinguish commits that aren't meant for release from commits
+  that are.)
+
+* Make sure that `CHANGELOG.md` has an entry for the current version.
+
+* Make sure that any packages in `pkg` depend on the current version of `sass`.
+
+* Increment the versions of all packages in `pkg`. These should be incremented
+  at least as much as the `sass` version, and more if you add a new API that's
+  exposed by one of those packages.
+
+* Make sure that every package in `pkg`'s `CHANGELOG.md` has an entry for its
+  current version.
+
+You *don't* need to create tags for packages in `pkg`; that will be handled
+automatically by GitHub actions.

README.md

@@ -32,6 +32,7 @@ A [Dart][dart] implementation of [Sass][sass]. **Sass makes CSS fun again**.
   * [Standalone](#standalone)
   * [From npm](#from-npm)
   * [From Pub](#from-pub)
+    * [`sass_api` Package](#sass_api-package)
   * [From Source](#from-source)
 * [JavaScript API](#javascript-api)
 * [Why Dart?](#why-dart)
@@ -129,6 +130,15 @@ See [the Dart API docs][api] for details.
 
 [api]: https://www.dartdocs.org/documentation/sass/latest/sass/sass-library.html
 
+#### `sass_api` Package
+
+Dart users also have access to more in-depth APIs via the [`sass_api` package].
+This provides access to the Sass AST and APIs for resolving Sass loads without
+running a full compilation. It's separated out into its own package so that it
+can increase its version number independently of the main `sass` package.
+
+[`sass_api` package]: https://pub.dev/package/sass_api
+
 ### From Source
 
 Assuming you've already checked out this repository:

lib/src/ast/node.dart

@@ -2,9 +2,18 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
 /// A node in an abstract syntax tree.
+///
+/// Note: although all nodes have `toString()` methods that generally reflect
+/// their source text, these methods should only be used for debugging and not
+/// for creating Sass source code. They aren't tested and are not guaranteed to
+/// remain stable over time.
+///
+/// {@category AST}
+@sealed
 abstract class AstNode {
   /// The source span associated with the node.
   ///
@@ -18,6 +27,9 @@ abstract class AstNode {
   /// A number of APIs take [AstNode]s instead of spans because computing spans
   /// eagerly can be expensive. This allows arbitrary spans to be passed to
   /// those callbacks while still being lazily computed.
+  ///
+  /// @nodoc
+  @internal
   factory AstNode.fake(FileSpan Function() callback) = _FakeAstNode;
 
   AstNode();

lib/src/ast/sass/argument.dart

@@ -2,13 +2,17 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
 import '../../utils.dart';
 import 'expression.dart';
 import 'node.dart';
 
 /// An argument declared as part of an [ArgumentDeclaration].
+///
+/// {@category AST}
+@sealed
 class Argument implements SassNode {
   /// The argument name.
   final String name;

lib/src/ast/sass/argument_declaration.dart

@@ -2,6 +2,7 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
 import '../../exception.dart';
@@ -13,6 +14,10 @@ import 'argument.dart';
 import 'node.dart';
 
 /// An argument declaration, as for a function or mixin definition.
+///
+/// {@category AST}
+/// {@category Parsing}
+@sealed
 class ArgumentDeclaration implements SassNode {
   /// The arguments that are taken.
   final List<Argument> arguments;

lib/src/ast/sass/argument_invocation.dart

@@ -2,12 +2,16 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
 import 'expression.dart';
 import 'node.dart';
 
 /// A set of arguments passed in to a function or mixin.
+///
+/// {@category AST}
+@sealed
 class ArgumentInvocation implements SassNode {
   /// The arguments passed by position.
   final List<Expression> positional;

lib/src/ast/sass/at_root_query.dart

@@ -2,6 +2,7 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:meta/meta.dart';
 import 'package:collection/collection.dart';
 
 import '../../exception.dart';
@@ -10,6 +11,9 @@ import '../../parse/at_root_query.dart';
 import '../css.dart';
 
 /// A query for the `@at-root` rule.
+///
+/// @nodoc
+@internal
 class AtRootQuery {
   /// The default at-root query, which excludes only style rules.
   static const defaultQuery = AtRootQuery._default();
@@ -34,7 +38,7 @@ class AtRootQuery {
   /// Note that this takes [include] into account.
   bool get excludesStyleRules => (_all || _rule) != include;
 
-  AtRootQuery(this.include, Set<String> names)
+  AtRootQuery(Set<String> names, {required this.include})
       : names = names,
         _all = names.contains("all"),
         _rule = names.contains("rule");
@@ -55,6 +59,9 @@ class AtRootQuery {
       AtRootQueryParser(contents, url: url, logger: logger).parse();
 
   /// Returns whether [this] excludes [node].
+  ///
+  /// @nodoc
+  @internal
   bool excludes(CssParentNode node) {
     if (_all) return !include;
     if (node is CssStyleRule) return excludesStyleRules;

lib/src/ast/sass/callable_invocation.dart

@@ -2,10 +2,15 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:meta/meta.dart';
+
 import 'argument_invocation.dart';
 import 'node.dart';
 
 /// An abstract class for invoking a callable (a function or mixin).
+///
+/// {@category AST}
+@sealed
 abstract class CallableInvocation implements SassNode {
   /// The arguments passed to the callable.
   ArgumentInvocation get arguments;

lib/src/ast/sass/configured_variable.dart

@@ -2,12 +2,16 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
 import 'expression.dart';
 import 'node.dart';
 
 /// A variable configured by a `with` clause in a `@use` or `@forward` rule.
+///
+/// {@category AST}
+@sealed
 class ConfiguredVariable implements SassNode {
   /// The name of the variable being configured.
   final String name;

lib/src/ast/sass/expression.dart

@@ -2,13 +2,19 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:meta/meta.dart';
+
 import '../../exception.dart';
 import '../../logger.dart';
 import '../../parse/scss.dart';
 import '../../visitor/interface/expression.dart';
 import 'node.dart';
 
 /// A SassScript expression in a Sass syntax tree.
+///
+/// {@category AST}
+/// {@category Parsing}
+@sealed
 abstract class Expression implements SassNode {
   /// Calls the appropriate visit method on [visitor].
   T accept<T>(ExpressionVisitor<T> visitor);

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

@@ -2,13 +2,17 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
-import 'package:source_span/source_span.dart';
 import 'package:charcode/charcode.dart';
+import 'package:meta/meta.dart';
+import 'package:source_span/source_span.dart';
 
 import '../../../visitor/interface/expression.dart';
 import '../expression.dart';
 
 /// A binary operator, as in `1 + 2` or `$this and $other`.
+///
+/// {@category AST}
+@sealed
 class BinaryOperationExpression implements Expression {
   /// The operator being invoked.
   final BinaryOperator operator;
@@ -21,6 +25,9 @@ class BinaryOperationExpression implements Expression {
 
   /// Whether this is a [BinaryOperator.dividedBy] operation that may be
   /// interpreted as slash-separated numbers.
+  ///
+  /// @nodoc
+  @internal
   final bool allowsSlash;
 
   FileSpan get span {
@@ -43,6 +50,9 @@ class BinaryOperationExpression implements Expression {
 
   /// Creates a [BinaryOperator.dividedBy] operation that may be interpreted as
   /// slash-separated numbers.
+  ///
+  /// @nodoc
+  @internal
   BinaryOperationExpression.slash(this.left, this.right)
       : operator = BinaryOperator.dividedBy,
         allowsSlash = true;
@@ -76,6 +86,9 @@ class BinaryOperationExpression implements Expression {
 }
 
 /// A binary operator constant.
+///
+/// {@category AST}
+@sealed
 class BinaryOperator {
   /// The Microsoft equals operator, `=`.
   static const singleEquals = BinaryOperator._("single equals", "=", 0);

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

@@ -2,12 +2,16 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
 import '../../../visitor/interface/expression.dart';
 import '../expression.dart';
 
 /// A boolean literal, `true` or `false`.
+///
+/// {@category AST}
+@sealed
 class BooleanExpression implements Expression {
   /// The value of this expression.
   final bool value;

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

@@ -2,13 +2,17 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
 import '../../../value.dart';
 import '../../../visitor/interface/expression.dart';
 import '../expression.dart';
 
 /// A color literal.
+///
+/// {@category AST}
+@sealed
 class ColorExpression implements Expression {
   /// The value of this color.
   final SassColor value;

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

@@ -2,6 +2,7 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
 import '../../../visitor/interface/expression.dart';
@@ -13,6 +14,9 @@ import '../interpolation.dart';
 /// A function invocation.
 ///
 /// This may be a plain CSS function or a Sass function.
+///
+/// {@category AST}
+@sealed
 class FunctionExpression implements Expression, CallableInvocation {
   /// The namespace of the function being invoked, or `null` if it's invoked
   /// without a namespace.