Add shared interfaces for various AST nodes (#1445)

Fixes #1401 and #1414.

Adds `Dependency`, `SassDeclaration`, and `SassReference` interfaces,
which expose some getters that multiple AST nodes have in common with a
single type.

These also add getters for common subspans (URL, name, and namespace) to
the interfaces.

Author: jathak

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.38.1
+
+* No user-visible changes
+
 ## 1.38.0
 
 * In expanded mode, emit characters in Unicode private-use areas as escape

lib/src/ast/sass.dart

@@ -8,12 +8,15 @@ export 'sass/argument_invocation.dart';
 export 'sass/at_root_query.dart';
 export 'sass/callable_invocation.dart';
 export 'sass/configured_variable.dart';
+export 'sass/declaration.dart';
+export 'sass/dependency.dart';
 export 'sass/expression.dart';
 export 'sass/expression/binary_operation.dart';
 export 'sass/expression/boolean.dart';
 export 'sass/expression/color.dart';
 export 'sass/expression/function.dart';
 export 'sass/expression/if.dart';
+export 'sass/expression/interpolated_function.dart';
 export 'sass/expression/list.dart';
 export 'sass/expression/map.dart';
 export 'sass/expression/null.dart';
@@ -29,6 +32,7 @@ export 'sass/import/dynamic.dart';
 export 'sass/import/static.dart';
 export 'sass/interpolation.dart';
 export 'sass/node.dart';
+export 'sass/reference.dart';
 export 'sass/statement.dart';
 export 'sass/statement/at_root_rule.dart';
 export 'sass/statement/at_rule.dart';

lib/src/ast/sass/argument.dart

@@ -6,14 +6,16 @@ import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
 import '../../utils.dart';
+import '../../util/span.dart';
 import 'expression.dart';
+import 'declaration.dart';
 import 'node.dart';
 
 /// An argument declared as part of an [ArgumentDeclaration].
 ///
 /// {@category AST}
 @sealed
-class Argument implements SassNode {
+class Argument implements SassNode, SassDeclaration {
   /// The argument name.
   final String name;
 
@@ -30,6 +32,9 @@ class Argument implements SassNode {
   String get originalName =>
       defaultValue == null ? span.text : declarationName(span);
 
+  FileSpan get nameSpan =>
+      defaultValue == null ? span : span.initialIdentifier(includeLeading: 1);
+
   Argument(this.name, this.span, {this.defaultValue});
 
   String toString() => defaultValue == null ? name : "$name: $defaultValue";

lib/src/ast/sass/argument_declaration.dart

@@ -10,6 +10,7 @@ import '../../logger.dart';
 import '../../parse/scss.dart';
 import '../../utils.dart';
 import '../../util/character.dart';
+import '../../util/span.dart';
 import 'argument.dart';
 import 'node.dart';
 

lib/src/ast/sass/configured_variable.dart

@@ -5,14 +5,16 @@
 import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
+import '../../util/span.dart';
 import 'expression.dart';
+import 'declaration.dart';
 import 'node.dart';
 
 /// A variable configured by a `with` clause in a `@use` or `@forward` rule.
 ///
 /// {@category AST}
 @sealed
-class ConfiguredVariable implements SassNode {
+class ConfiguredVariable implements SassNode, SassDeclaration {
   /// The name of the variable being configured.
   final String name;
 
@@ -26,6 +28,8 @@ class ConfiguredVariable implements SassNode {
 
   final FileSpan span;
 
+  FileSpan get nameSpan => span.initialIdentifier(includeLeading: 1);
+
   ConfiguredVariable(this.name, this.expression, this.span,
       {bool guarded = false})
       : isGuarded = guarded;

lib/src/ast/sass/declaration.dart

@@ -0,0 +1,24 @@
+// Copyright 2021 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 'package:meta/meta.dart';
+import 'package:source_span/source_span.dart';
+
+import 'node.dart';
+
+/// A common interface for any node that declares a Sass member.
+///
+/// {@category AST}
+@sealed
+abstract class SassDeclaration extends SassNode {
+  /// The name of the declaration, with underscores converted to hyphens.
+  ///
+  /// This does not include the `$` for variables.
+  String get name;
+
+  /// The span containing this declaration's name.
+  ///
+  /// This includes the `$` for variables.
+  FileSpan get nameSpan;
+}

lib/src/ast/sass/dependency.dart

@@ -0,0 +1,20 @@
+// Copyright 2021 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 'package:meta/meta.dart';
+import 'package:source_span/source_span.dart';
+
+import 'node.dart';
+
+/// A common interface for [UseRule]s, [ForwardRule]s, and [DynamicImport]s.
+///
+/// {@category AST}
+@sealed
+abstract class SassDependency extends SassNode {
+  /// The URL of the dependency this rule loads.
+  Uri get url;
+
+  /// The span of the URL for this dependency, including the quotes.
+  FileSpan get urlSpan;
+}

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

@@ -5,46 +5,58 @@
 import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
+import '../../../util/span.dart';
 import '../../../visitor/interface/expression.dart';
 import '../expression.dart';
 import '../argument_invocation.dart';
 import '../callable_invocation.dart';
-import '../interpolation.dart';
+import '../reference.dart';
 
 /// A function invocation.
 ///
-/// This may be a plain CSS function or a Sass function.
+/// This may be a plain CSS function or a Sass function, but may not include
+/// interpolation.
 ///
 /// {@category AST}
 @sealed
-class FunctionExpression implements Expression, CallableInvocation {
+class FunctionExpression
+    implements Expression, CallableInvocation, SassReference {
   /// The namespace of the function being invoked, or `null` if it's invoked
   /// without a namespace.
   final String? namespace;
 
-  /// The name of the function being invoked.
-  ///
-  /// If [namespace] is non-`null`, underscores are converted to hyphens in this name.
-  /// If [namespace] is `null`, this could be a plain CSS function call, so underscores are kept unchanged.
-  ///
-  /// If this is interpolated, the function will be interpreted as plain CSS,
-  /// even if it has the same name as a Sass function.
-  final Interpolation name;
+  /// The name of the function being invoked, with underscores left as-is.
+  final String originalName;
 
   /// The arguments to pass to the function.
   final ArgumentInvocation arguments;
 
   final FileSpan span;
 
-  FunctionExpression(this.name, this.arguments, this.span, {this.namespace});
+  /// The name of the function being invoked, with underscores converted to
+  /// hyphens.
+  ///
+  /// If this function is a plain CSS function, use [originalName] instead.
+  String get name => originalName.replaceAll('_', '-');
+
+  FileSpan get nameSpan {
+    if (namespace == null) return span.initialIdentifier();
+    return span.withoutNamespace().initialIdentifier();
+  }
+
+  FileSpan? get namespaceSpan =>
+      namespace == null ? null : span.initialIdentifier();
+
+  FunctionExpression(this.originalName, this.arguments, this.span,
+      {this.namespace});
 
   T accept<T>(ExpressionVisitor<T> visitor) =>
       visitor.visitFunctionExpression(this);
 
   String toString() {
     var buffer = StringBuffer();
     if (namespace != null) buffer.write("$namespace.");
-    buffer.write("$name$arguments");
+    buffer.write("$originalName$arguments");
     return buffer.toString();
   }
 }

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

@@ -0,0 +1,35 @@
+// Copyright 2021 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 'package:meta/meta.dart';
+import 'package:source_span/source_span.dart';
+
+import '../../../visitor/interface/expression.dart';
+import '../expression.dart';
+import '../argument_invocation.dart';
+import '../callable_invocation.dart';
+import '../interpolation.dart';
+
+/// An interpolated function invocation.
+///
+/// This is always a plain CSS function.
+///
+/// {@category AST}
+@sealed
+class InterpolatedFunctionExpression implements Expression, CallableInvocation {
+  /// The name of the function being invoked.
+  final Interpolation name;
+
+  /// The arguments to pass to the function.
+  final ArgumentInvocation arguments;
+
+  final FileSpan span;
+
+  InterpolatedFunctionExpression(this.name, this.arguments, this.span);
+
+  T accept<T>(ExpressionVisitor<T> visitor) =>
+      visitor.visitInterpolatedFunctionExpression(this);
+
+  String toString() => '$name$arguments';
+}

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

@@ -5,14 +5,16 @@
 import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
+import '../../../util/span.dart';
 import '../../../visitor/interface/expression.dart';
 import '../expression.dart';
+import '../reference.dart';
 
 /// A Sass variable.
 ///
 /// {@category AST}
 @sealed
-class VariableExpression implements Expression {
+class VariableExpression implements Expression, SassReference {
   /// The namespace of the variable being referenced, or `null` if it's
   /// referenced without a namespace.
   final String? namespace;
@@ -22,6 +24,14 @@ class VariableExpression implements Expression {
 
   final FileSpan span;
 
+  FileSpan get nameSpan {
+    if (namespace == null) return span;
+    return span.withoutNamespace();
+  }
+
+  FileSpan? get namespaceSpan =>
+      namespace == null ? null : span.initialIdentifier();
+
   VariableExpression(this.name, this.span, {this.namespace});
 
   T accept<T>(ExpressionVisitor<T> visitor) =>