Prepare the API for being exposed in a new package

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.

lib/src/ast/sass/expression/if.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 '../../../ast/sass.dart';
@@ -12,6 +13,9 @@ import '../../../visitor/interface/expression.dart';
 /// This is defined as a separate syntactic construct rather than a normal
 /// function because only one of the `$if-true` and `$if-false` arguments are
 /// evaluated.
+///
+/// {@category AST}
+@sealed
 class IfExpression implements Expression, CallableInvocation {
   /// The declaration of `if()`, as though it were a normal function.
   static final declaration = ArgumentDeclaration.parse(

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

@@ -3,6 +3,7 @@
 // https://opensource.org/licenses/MIT.
 
 import 'package:charcode/charcode.dart';
+import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
 import '../../../value.dart';
@@ -11,6 +12,9 @@ import '../expression.dart';
 import 'unary_operation.dart';
 
 /// A list literal.
+///
+/// {@category AST}
+@sealed
 class ListExpression implements Expression {
   /// The elements of this list.
   final List<Expression> contents;
@@ -23,14 +27,10 @@ class ListExpression implements Expression {
 
   final FileSpan span;
 
-  ListExpression(
-      Iterable<Expression> contents, ListSeparator separator, FileSpan span,
+  ListExpression(Iterable<Expression> contents, this.separator, this.span,
       {bool brackets = false})
-      : this._(List.unmodifiable(contents), separator, brackets, span);
-
-  ListExpression._(
-      List<Expression> contents, this.separator, this.hasBrackets, this.span)
-      : contents = contents;
+      : contents = List.unmodifiable(contents),
+        hasBrackets = brackets;
 
   T accept<T>(ExpressionVisitor<T> visitor) =>
       visitor.visitListExpression(this);

lib/src/ast/sass/expression/map.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 'package:tuple/tuple.dart';
 
 import '../../../visitor/interface/expression.dart';
 import '../expression.dart';
 
 /// A map literal.
+///
+/// {@category AST}
+@sealed
 class MapExpression implements Expression {
   /// The pairs in this map.
   ///

lib/src/ast/sass/expression/null.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 null literal.
+///
+/// {@category AST}
+@sealed
 class NullExpression implements Expression {
   final FileSpan span;
 

lib/src/ast/sass/expression/number.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 number literal.
+///
+/// {@category AST}
+@sealed
 class NumberExpression implements Expression {
   /// The numeric value.
   final num value;

lib/src/ast/sass/expression/parenthesized.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';
 
 /// An expression wrapped in parentheses.
+///
+/// {@category AST}
+@sealed
 class ParenthesizedExpression implements Expression {
   /// The internal expression.
   final Expression expression;