External variable support: add a notion of external top level variables to the AST and element model.

In follow-up CLs I will update error reporting logic.

Change-Id: Iee42088beffee3915a2ef6a4c8cb5c1031535d4d
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/158149
Reviewed-by: Konstantin Shcheglov <[email protected]>
Commit-Queue: Paul Berry <[email protected]>

Author: stereotype441

pkg/analysis_server/lib/src/computer/computer_highlights.dart

@@ -755,6 +755,13 @@ class _DartUnitHighlightsComputerVisitor extends RecursiveAstVisitor<void> {
     super.visitThisExpression(node);
   }
 
+  @override
+  void visitTopLevelVariableDeclaration(TopLevelVariableDeclaration node) {
+    computer._addRegion_token(
+        node.externalKeyword, HighlightRegionType.BUILT_IN);
+    super.visitTopLevelVariableDeclaration(node);
+  }
+
   @override
   void visitTryStatement(TryStatement node) {
     computer._addRegion_token(node.tryKeyword, HighlightRegionType.KEYWORD);

pkg/analysis_server/lib/src/computer/computer_highlights2.dart

@@ -864,6 +864,13 @@ class _DartUnitHighlightsComputerVisitor2 extends RecursiveAstVisitor<void> {
     super.visitThrowExpression(node);
   }
 
+  @override
+  void visitTopLevelVariableDeclaration(TopLevelVariableDeclaration node) {
+    computer._addRegion_token(
+        node.externalKeyword, HighlightRegionType.BUILT_IN);
+    super.visitTopLevelVariableDeclaration(node);
+  }
+
   @override
   void visitTryStatement(TryStatement node) {
     computer._addRegion_token(node.tryKeyword, HighlightRegionType.KEYWORD);

pkg/analysis_server/lib/src/services/completion/dart/keyword_contributor.dart

@@ -676,6 +676,29 @@ class _KeywordVisitor extends GeneralizingAstVisitor<void> {
     }
   }
 
+  @override
+  void visitTopLevelVariableDeclaration(TopLevelVariableDeclaration node) {
+    var variableDeclarationList = node.variables;
+    if (entity != variableDeclarationList) return;
+    var variables = variableDeclarationList.variables;
+    if (variables.isEmpty || request.offset > variables.first.beginToken.end) {
+      return;
+    }
+    if (node.externalKeyword == null) {
+      _addSuggestion(Keyword.EXTERNAL);
+    }
+    if (variableDeclarationList.lateKeyword == null &&
+        request.featureSet.isEnabled(Feature.non_nullable)) {
+      _addSuggestion(Keyword.LATE);
+    }
+    if (!variables.first.isConst) {
+      _addSuggestion(Keyword.CONST);
+    }
+    if (!variables.first.isFinal) {
+      _addSuggestion(Keyword.FINAL);
+    }
+  }
+
   @override
   void visitTryStatement(TryStatement node) {
     var obj = entity;

pkg/analysis_server/tool/completion_metrics/code_metrics.dart

@@ -1196,6 +1196,7 @@ class CodeShapeDataCollector extends RecursiveAstVisitor<void> {
     _visitChildren(node, {
       'documentationComment': node.documentationComment,
       'metadata': node.metadata,
+      'externalKeyword': node.externalKeyword,
       'variables': node.variables,
     });
     super.visitTopLevelVariableDeclaration(node);

pkg/analysis_server/tool/completion_metrics/visitors.dart

@@ -665,6 +665,12 @@ class ExpectedCompletionsVisitor extends RecursiveAstVisitor<void> {
     return super.visitThrowExpression(node);
   }
 
+  @override
+  void visitTopLevelVariableDeclaration(TopLevelVariableDeclaration node) {
+    safelyRecordKeywordCompletion(node.externalKeyword);
+    return super.visitTopLevelVariableDeclaration(node);
+  }
+
   @override
   void visitTryStatement(TryStatement node) {
     safelyRecordKeywordCompletion(node.tryKeyword);

pkg/analyzer/lib/dart/ast/ast.dart

@@ -4959,11 +4959,21 @@ abstract class ThrowExpression implements Expression {
 /// The declaration of one or more top-level variables of the same type.
 ///
 ///    topLevelVariableDeclaration ::=
-///        ('final' | 'const') type? staticFinalDeclarationList ';'
-///      | variableDeclaration ';'
+///        ('final' | 'const') <type>? <staticFinalDeclarationList> ';'
+///      | 'late' 'final' <type>? <initializedIdentifierList> ';'
+///      | 'late'? <varOrType> <initializedIdentifierList> ';'
+///      | 'external' <finalVarOrType> <identifierList> ';'
+///
+/// (Note: there is no <topLevelVariableDeclaration> production in the grammar;
+/// this is a subset of the grammar production <topLevelDeclaration>, which
+/// encompasses everything that can appear inside a Dart file after part
+/// directives).
 ///
 /// Clients may not extend, implement or mix-in this class.
 abstract class TopLevelVariableDeclaration implements CompilationUnitMember {
+  /// The `external` keyword, or `null` if the keyword was not used.
+  Token get externalKeyword;
+
   /// Return the semicolon terminating the declaration.
   Token get semicolon;
 

pkg/analyzer/lib/dart/ast/ast_factory.dart

@@ -909,7 +909,8 @@ abstract class AstFactory {
       Comment comment,
       List<Annotation> metadata,
       VariableDeclarationList variableList,
-      Token semicolon);
+      Token semicolon,
+      {Token externalKeyword});
 
   /// Returns a newly created try statement. The list of [catchClauses] can be
   /// `null` if there are no catch clauses. The [finallyKeyword] and

pkg/analyzer/lib/dart/element/element.dart

@@ -1694,6 +1694,9 @@ abstract class ShowElementCombinator implements NamespaceCombinator {
 abstract class TopLevelVariableElement implements PropertyInducingElement {
   @override
   TopLevelVariableElement get declaration;
+
+  /// Return `true` if this field was explicitly marked as being external.
+  bool get isExternal;
 }
 
 /// An element that defines a type.

pkg/analyzer/lib/src/dart/ast/ast.dart

@@ -9796,6 +9796,9 @@ class TopLevelVariableDeclarationImpl extends CompilationUnitMemberImpl
   /// The top-level variables being declared.
   VariableDeclarationListImpl _variableList;
 
+  @override
+  Token externalKeyword;
+
   /// The semicolon terminating the declaration.
   @override
   Token semicolon;
@@ -9806,6 +9809,7 @@ class TopLevelVariableDeclarationImpl extends CompilationUnitMemberImpl
   TopLevelVariableDeclarationImpl(
       CommentImpl comment,
       List<Annotation> metadata,
+      this.externalKeyword,
       VariableDeclarationListImpl variableList,
       this.semicolon)
       : super(comment, metadata) {
@@ -9823,7 +9827,8 @@ class TopLevelVariableDeclarationImpl extends CompilationUnitMemberImpl
   Token get endToken => semicolon;
 
   @override
-  Token get firstTokenAfterCommentAndMetadata => _variableList.beginToken;
+  Token get firstTokenAfterCommentAndMetadata =>
+      externalKeyword ?? _variableList.beginToken;
 
   @override
   VariableDeclarationList get variables => _variableList;

pkg/analyzer/lib/src/dart/ast/ast_factory.dart

@@ -1020,9 +1020,10 @@ class AstFactoryImpl extends AstFactory {
           Comment comment,
           List<Annotation> metadata,
           VariableDeclarationList variableList,
-          Token semicolon) =>
+          Token semicolon,
+          {Token externalKeyword}) =>
       TopLevelVariableDeclarationImpl(
-          comment, metadata, variableList, semicolon);
+          comment, metadata, externalKeyword, variableList, semicolon);
 
   @override
   TryStatement tryStatement(

pkg/analyzer/lib/src/dart/ast/to_source_visitor.dart

@@ -1075,6 +1075,7 @@ class ToSourceVisitor implements AstVisitor<void> {
 
   @override
   void visitTopLevelVariableDeclaration(TopLevelVariableDeclaration node) {
+    safelyVisitTokenWithSuffix(node.externalKeyword, " ");
     safelyVisitNodeWithSuffix(node.variables, ";");
   }
 

pkg/analyzer/lib/src/dart/ast/utilities.dart

@@ -975,7 +975,8 @@ class AstCloner implements AstVisitor<AstNode> {
           cloneNode(node.documentationComment),
           cloneNodeList(node.metadata),
           cloneNode(node.variables),
-          cloneToken(node.semicolon));
+          cloneToken(node.semicolon),
+          externalKeyword: cloneToken(node.externalKeyword));
 
   @override
   TryStatement visitTryStatement(TryStatement node) => astFactory.tryStatement(
@@ -2193,6 +2194,7 @@ class AstComparator implements AstVisitor<bool> {
     return isEqualNodes(
             node.documentationComment, other.documentationComment) &&
         _isEqualNodeLists(node.metadata, other.metadata) &&
+        isEqualTokens(node.externalKeyword, other.externalKeyword) &&
         isEqualNodes(node.variables, other.variables) &&
         isEqualTokens(node.semicolon, other.semicolon);
   }
@@ -5266,6 +5268,7 @@ class ResolutionCopier implements AstVisitor<bool> {
     return _and(
         _isEqualNodes(node.documentationComment, toNode.documentationComment),
         _isEqualNodeLists(node.metadata, toNode.metadata),
+        _isEqualTokens(node.externalKeyword, toNode.externalKeyword),
         _isEqualNodes(node.variables, toNode.variables),
         _isEqualTokens(node.semicolon, toNode.semicolon));
   }

pkg/analyzer/lib/src/dart/element/element.dart

@@ -7472,6 +7472,14 @@ class TopLevelVariableElementImpl extends PropertyInducingElementImpl
   @override
   TopLevelVariableElement get declaration => this;
 
+  @override
+  bool get isExternal {
+    if (linkedNode != null) {
+      return enclosingUnit.linkedContext.isExternal(linkedNode);
+    }
+    return hasModifier(Modifier.EXTERNAL);
+  }
+
   @override
   bool get isStatic => true;
 

pkg/analyzer/lib/src/dart/element/member.dart

@@ -954,6 +954,9 @@ class TopLevelVariableMember extends VariableMember
     return PropertyAccessorMember(baseGetter, _substitution, isLegacy);
   }
 
+  @override
+  bool get isExternal => declaration.isExternal;
+
   @override
   PropertyAccessorElement get setter {
     var baseSetter = declaration.setter;

pkg/analyzer/lib/src/fasta/ast_builder.dart

@@ -2153,7 +2153,7 @@ class AstBuilder extends StackListener {
     assert(optional(';', semicolon));
     debugEvent("TopLevelFields");
 
-    if (externalToken != null) {
+    if (externalToken != null && !enableNonNullable) {
       handleRecoverableError(
           messageExternalField, externalToken, externalToken);
     }
@@ -2169,7 +2169,8 @@ class AstBuilder extends StackListener {
     List<Annotation> metadata = pop();
     Comment comment = _findComment(metadata, beginToken);
     declarations.add(ast.topLevelVariableDeclaration(
-        comment, metadata, variableList, semicolon));
+        comment, metadata, variableList, semicolon,
+        externalKeyword: externalToken));
   }
 
   @override

pkg/analyzer/lib/src/generated/testing/ast_test_factory.dart

@@ -1296,12 +1296,16 @@ class AstTestFactory {
           TokenFactory.tokenFromType(TokenType.SEMICOLON));
 
   static TopLevelVariableDeclaration topLevelVariableDeclaration2(
-          Keyword keyword, List<VariableDeclaration> variables) =>
+          Keyword keyword, List<VariableDeclaration> variables,
+          {bool isExternal = false}) =>
       astFactory.topLevelVariableDeclaration(
           null,
           null,
           variableDeclarationList(keyword, null, variables),
-          TokenFactory.tokenFromType(TokenType.SEMICOLON));
+          TokenFactory.tokenFromType(TokenType.SEMICOLON),
+          externalKeyword: isExternal
+              ? TokenFactory.tokenFromKeyword(Keyword.EXTERNAL)
+              : null);
 
   static TryStatement tryStatement(Block body, Block finallyClause) =>
       tryStatement3(body, <CatchClause>[], finallyClause);

pkg/analyzer/lib/src/summary2/ast_binary_reader.dart

@@ -1548,6 +1548,8 @@ class AstBinaryReader {
         _readNodeListLazy(data.annotatedNode_metadata),
         _readNode(data.topLevelVariableDeclaration_variableList),
         _Tokens.SEMICOLON,
+        externalKeyword:
+            AstBinaryFlags.isExternal(data.flags) ? _Tokens.EXTERNAL : null,
       );
       LazyTopLevelVariableDeclaration.setData(node, data);
       return node;

pkg/analyzer/lib/src/summary2/ast_binary_writer.dart

@@ -1328,6 +1328,9 @@ class AstBinaryWriter extends ThrowingAstVisitor<LinkedNodeBuilder> {
         informativeId: getInformativeId(node),
         topLevelVariableDeclaration_variableList: node.variables?.accept(this),
       );
+      builder.flags = AstBinaryFlags.encode(
+        isExternal: node.externalKeyword != null,
+      );
       _storeCompilationUnitMember(builder, node);
 
       return builder;

pkg/analyzer/lib/src/summary2/ast_text_printer.dart

@@ -906,6 +906,7 @@ class AstTextPrinter extends ThrowingAstVisitor<void> {
   @override
   void visitTopLevelVariableDeclaration(TopLevelVariableDeclaration node) {
     _compilationUnitMember(node);
+    _token(node.externalKeyword);
     node.variables.accept(this);
     _token(node.semicolon);
   }

pkg/analyzer/lib/src/summary2/linked_unit_context.dart

@@ -841,6 +841,8 @@ class LinkedUnitContext {
         var grandParent = parent.parent;
         if (grandParent is FieldDeclaration) {
           return grandParent.externalKeyword != null;
+        } else if (grandParent is TopLevelVariableDeclaration) {
+          return grandParent.externalKeyword != null;
         } else {
           throw UnimplementedError('${grandParent.runtimeType}');
         }

pkg/analyzer/test/generated/parser_fasta_test.dart

@@ -4621,6 +4621,12 @@ mixin A {
     expectCommentText(declaration.documentationComment, '/// Doc');
   }
 
+  void test_parseTopLevelVariable_external() {
+    var unit = parseCompilationUnit('external int i;', featureSet: nonNullable);
+    var declaration = unit.declarations[0] as TopLevelVariableDeclaration;
+    expect(declaration.externalKeyword, isNotNull);
+  }
+
   void test_parseTopLevelVariable_final_late() {
     var unit = parseCompilationUnit('final late a;',
         featureSet: nonNullable,
@@ -4676,6 +4682,12 @@ mixin A {
     expect(declarationList.type, isNotNull);
     expect(declarationList.variables, hasLength(1));
   }
+
+  void test_parseTopLevelVariable_non_external() {
+    var unit = parseCompilationUnit('int i;', featureSet: nonNullable);
+    var declaration = unit.declarations[0] as TopLevelVariableDeclaration;
+    expect(declaration.externalKeyword, isNull);
+  }
 }
 
 @reflectiveTest

pkg/analyzer/test/src/dart/ast/to_source_visitor_test.dart

@@ -2616,6 +2616,14 @@ class ToSourceVisitor2Test {
         AstTestFactory.throwExpression2(AstTestFactory.identifier3("e")));
   }
 
+  void test_visitTopLevelVariableDeclaration_external() {
+    _assertSource(
+        "external var a;",
+        AstTestFactory.topLevelVariableDeclaration2(
+            Keyword.VAR, [AstTestFactory.variableDeclaration("a")],
+            isExternal: true));
+  }
+
   void test_visitTopLevelVariableDeclaration_multiple() {
     _assertSource(
         "var a;",

pkg/analyzer/test/src/dart/ast/utilities_test.dart

@@ -132,6 +132,29 @@ class ResolutionCopierTest with ElementsTypesMixin {
   @override
   final TypeProvider typeProvider = TestTypeProvider();
 
+  void test_topLevelVariableDeclaration_external() {
+    TopLevelVariableDeclaration fromNode =
+        AstTestFactory.topLevelVariableDeclaration2(
+            Keyword.VAR, [AstTestFactory.variableDeclaration('x')],
+            isExternal: false);
+    TopLevelVariableElement element = TopLevelVariableElementImpl('x', -1);
+    fromNode.variables.variables[0].name.staticElement = element;
+    TopLevelVariableDeclaration toNode1 =
+        AstTestFactory.topLevelVariableDeclaration2(
+            Keyword.VAR, [AstTestFactory.variableDeclaration('x')],
+            isExternal: false);
+    ResolutionCopier.copyResolutionData(fromNode, toNode1);
+    // Nodes matched so resolution data should have been copied.
+    expect(toNode1.variables.variables[0].declaredElement, same(element));
+    TopLevelVariableDeclaration toNode2 =
+        AstTestFactory.topLevelVariableDeclaration2(
+            Keyword.VAR, [AstTestFactory.variableDeclaration('x')],
+            isExternal: true);
+    ResolutionCopier.copyResolutionData(fromNode, toNode1);
+    // Nodes didn't match so resolution data should not have been copied.
+    expect(toNode2.variables.variables[0].declaredElement, isNull);
+  }
+
   void test_visitAdjacentStrings() {
     AdjacentStrings createNode() => astFactory.adjacentStrings([
           astFactory.simpleStringLiteral(null, 'hello'),

pkg/analyzer/test/src/summary/element_text.dart

@@ -971,6 +971,7 @@ class _ElementWriter {
     } else {
       writeDocumentation(e);
       writeMetadata(e, '', '\n');
+      writeIf(e is TopLevelVariableElementImpl && e.isExternal, 'external ');
     }
 
     writeIf(e.isLate, 'late ');

pkg/analyzer/test/src/summary/resolved_ast_printer.dart

@@ -1269,6 +1269,7 @@ class ResolvedAstPrinter extends ThrowingAstVisitor<void> {
     _writeln('TopLevelVariableDeclaration');
     _withIndent(() {
       var properties = _Properties();
+      properties.addToken('externalKeyword', node.externalKeyword);
       properties.addToken('semicolon', node.semicolon);
       properties.addNode('variables', node.variables);
       _addCompilationUnitMember(properties, node);