Add library macro definitions and support for executing them.

These are intended to be applied by annotating a library directive.

Note that some parameter types had to be widened since `Library` is not a subtype of `Declaration`. Ultimately I think that is fine though.

Bug:dart-lang/language#2839
Change-Id: Ia1311c8aea729f2bd8b76173ce4c7595a6a37a42
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/312140
Reviewed-by: Bob Nystrom <[email protected]>
Auto-Submit: Jake Macdonald <[email protected]>
Commit-Queue: Jake Macdonald <[email protected]>

Author: jakemac53

pkg/_fe_analyzer_shared/lib/src/macros/api/builders.dart

@@ -178,6 +178,31 @@ abstract interface class DefinitionBuilder
         TypeResolver,
         LibraryDeclarationsResolver {}
 
+/// The APIs used by [Macro]s that run on library directives, to fill in the
+/// definitions of any declarations within that library.
+abstract interface class LibraryDefinitionBuilder implements DefinitionBuilder {
+  /// Retrieve a [TypeDefinitionBuilder] for a type declaration with
+  /// [identifier].
+  ///
+  /// Throws an [ArgumentError] if [identifier] does not refer to a type
+  /// declaration in this library.
+  Future<TypeDefinitionBuilder> buildType(Identifier identifier);
+
+  /// Retrieve a [FunctionDefinitionBuilder] for a function declaration with
+  /// [identifier].
+  ///
+  /// Throws an [ArgumentError] if [identifier] does not refer to a top level
+  /// function declaration in this library.
+  Future<FunctionDefinitionBuilder> buildFunction(Identifier identifier);
+
+  /// Retrieve a [VariableDefinitionBuilder] for a variable declaration with
+  /// [identifier].
+  ///
+  /// Throws an [ArgumentError] if [identifier] does not refer to a top level
+  /// variable declaration in this library.
+  Future<VariableDefinitionBuilder> buildVariable(Identifier identifier);
+}
+
 /// The APIs used by [Macro]s that run on type declarations, to fill in the
 /// definitions of any declarations within that class.
 abstract interface class TypeDefinitionBuilder implements DefinitionBuilder {

pkg/_fe_analyzer_shared/lib/src/macros/api/introspection.dart

@@ -4,6 +4,11 @@
 
 part of '../api.dart';
 
+/// The interface for classes that can be targeted by macros.
+///
+/// Could be a [Declaration] or [Library].
+abstract interface class MacroTarget {}
+
 /// A concrete reference to a named declaration, which may or may not yet be
 /// resolved.
 ///
@@ -95,7 +100,7 @@ abstract interface class StaticType {
 abstract interface class NamedStaticType implements StaticType {}
 
 /// The interface for all declarations.
-abstract interface class Declaration {
+abstract interface class Declaration implements MacroTarget {
   /// The library in which this declaration is defined.
   Library get library;
 
@@ -351,7 +356,7 @@ abstract interface class RecordFieldDeclaration implements Declaration {
 }
 
 /// Introspection information for a Library.
-abstract interface class Library {
+abstract interface class Library implements MacroTarget {
   /// The language version of this library.
   LanguageVersion get languageVersion;
 

pkg/_fe_analyzer_shared/lib/src/macros/api/macros.dart

@@ -7,6 +7,26 @@ part of '../api.dart';
 /// The marker interface for all types of macros.
 abstract interface class Macro {}
 
+/// The interface for [Macro]s that can be applied to a library directive, and
+/// want to contribute new type declarations to the library.
+abstract interface class LibraryTypesMacro implements Macro {
+  FutureOr<void> buildTypesForLibrary(Library library, TypeBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to a library directive, and
+/// want to contribute new non-type declarations to the library.
+abstract interface class LibraryDeclarationsMacro implements Macro {
+  FutureOr<void> buildDeclarationsForLibrary(
+      Library library, DeclarationBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to a library directive, and
+/// want to provide definitions for declarations in the library.
+abstract interface class LibraryDefinitionMacro implements Macro {
+  FutureOr<void> buildDefinitionForLibrary(
+      Library library, LibraryDefinitionBuilder builder);
+}
+
 /// The interface for [Macro]s that can be applied to any top level function,
 /// instance method, or static method, and want to contribute new type
 /// declarations to the program.

pkg/_fe_analyzer_shared/lib/src/macros/bootstrap.dart

@@ -240,7 +240,7 @@ Future<SerializableResponse> _executeTypesPhase(
         serializationZoneId: request.serializationZoneId);
 
     var result = await executeTypesMacro(
-        instance, request.declaration, identifierResolver);
+        instance, request.target, identifierResolver);
     return new SerializableResponse(
         responseType: MessageType.macroExecutionResult,
         response: result,
@@ -283,7 +283,7 @@ Future<SerializableResponse> _executeDeclarationsPhase(
         serializationZoneId: request.serializationZoneId);
 
     var result = await executeDeclarationsMacro(
-        instance, request.declaration, identifierResolver, typeIntrospector,
+        instance, request.target, identifierResolver, typeIntrospector,
         typeDeclarationResolver, typeResolver);
     return new SerializableResponse(
         responseType: MessageType.macroExecutionResult,
@@ -335,7 +335,7 @@ Future<SerializableResponse> _executeDefinitionsPhase(
         serializationZoneId: request.serializationZoneId);
 
     var result = await executeDefinitionMacro(
-        instance, request.declaration, identifierResolver, typeIntrospector,
+        instance, request.target, identifierResolver, typeIntrospector,
         typeResolver, typeDeclarationResolver, typeInferrer,
         libraryDeclarationsResolver);
     return new SerializableResponse(

pkg/_fe_analyzer_shared/lib/src/macros/executor.dart

@@ -36,14 +36,14 @@ abstract class MacroExecutor {
   ///
   /// Throws an exception if there is an error executing the macro.
   Future<MacroExecutionResult> executeTypesPhase(MacroInstanceIdentifier macro,
-      covariant Declaration declaration, IdentifierResolver identifierResolver);
+      MacroTarget target, IdentifierResolver identifierResolver);
 
   /// Runs the declarations phase for [macro] on a given [declaration].
   ///
   /// Throws an exception if there is an error executing the macro.
   Future<MacroExecutionResult> executeDeclarationsPhase(
       MacroInstanceIdentifier macro,
-      covariant Declaration declaration,
+      MacroTarget target,
       IdentifierResolver identifierResolver,
       TypeDeclarationResolver typeDeclarationResolver,
       TypeResolver typeResolver,
@@ -54,7 +54,7 @@ abstract class MacroExecutor {
   /// Throws an exception if there is an error executing the macro.
   Future<MacroExecutionResult> executeDefinitionsPhase(
       MacroInstanceIdentifier macro,
-      covariant Declaration declaration,
+      MacroTarget target,
       IdentifierResolver identifierResolver,
       TypeDeclarationResolver typeDeclarationResolver,
       TypeResolver typeResolver,

pkg/_fe_analyzer_shared/lib/src/macros/executor/builder_impls.dart

@@ -425,6 +425,78 @@ class VariableDefinitionBuilderImpl extends DefinitionBuilderBase
   }
 }
 
+class LibraryDefinitionBuilderImpl extends DefinitionBuilderBase
+    implements LibraryDefinitionBuilder {
+  final Library library;
+
+  LibraryDefinitionBuilderImpl(
+    this.library,
+    super.identifierResolver,
+    super.typeIntrospector,
+    super.typeDeclarationResolver,
+    super.typeResolver,
+    super.typeInferrer,
+    super.libraryDeclarationsResolver, {
+    super.parentTypeAugmentations,
+    super.parentEnumValueAugmentations,
+    super.parentLibraryAugmentations,
+  });
+
+  @override
+  Future<FunctionDefinitionBuilder> buildFunction(Identifier identifier) async {
+    FunctionDeclarationImpl function = (await libraryDeclarationsResolver
+                .topLevelDeclarationsOf(library))
+            .firstWhere((declaration) => declaration.identifier == identifier)
+        as FunctionDeclarationImpl;
+    return new FunctionDefinitionBuilderImpl(
+        function,
+        identifierResolver,
+        typeIntrospector,
+        typeDeclarationResolver,
+        typeResolver,
+        typeInferrer,
+        libraryDeclarationsResolver,
+        parentTypeAugmentations: _typeAugmentations,
+        parentLibraryAugmentations: _libraryAugmentations);
+  }
+
+  @override
+  Future<TypeDefinitionBuilder> buildType(Identifier identifier) async {
+    IntrospectableType type = (await libraryDeclarationsResolver
+                .topLevelDeclarationsOf(library))
+            .firstWhere((declaration) => declaration.identifier == identifier)
+        as IntrospectableType;
+    return new TypeDefinitionBuilderImpl(
+        type,
+        identifierResolver,
+        typeIntrospector,
+        typeDeclarationResolver,
+        typeResolver,
+        typeInferrer,
+        libraryDeclarationsResolver,
+        parentTypeAugmentations: _typeAugmentations,
+        parentLibraryAugmentations: _libraryAugmentations);
+  }
+
+  @override
+  Future<VariableDefinitionBuilder> buildVariable(Identifier identifier) async {
+    VariableDeclarationImpl variable = (await libraryDeclarationsResolver
+                .topLevelDeclarationsOf(library))
+            .firstWhere((declaration) => declaration.identifier == identifier)
+        as VariableDeclarationImpl;
+    return new VariableDefinitionBuilderImpl(
+        variable,
+        identifierResolver,
+        typeIntrospector,
+        typeDeclarationResolver,
+        typeResolver,
+        typeInferrer,
+        libraryDeclarationsResolver,
+        parentTypeAugmentations: _typeAugmentations,
+        parentLibraryAugmentations: _libraryAugmentations);
+  }
+}
+
 /// Builds all the possible augmentations for a variable.
 List<DeclarationCode> _buildVariableAugmentations(
     VariableDeclaration declaration,