[private named parameters] Implement in analyzer

I considered a few different approaches for how to model a formal parameter having a public and private name. Here's a simple example:

```dart
class C {
  int? _f;
  C({this._f});
}

main() {
  C(f: 1);
}
```

Here, it seems like the right approach is to give the formal parameter the public name since that's what you pass for the parameter. Then have resolution understand that the parameter can still map to a private instance variable.

But then consider:

```dart
class C {
  int? _f;
  int? x;
  C({this._f}) : x = _f;
}
```

The formal parameter for _f can also be accessed inside the initializer list and here it must have the private name.

So, really, the name of the formal parameter *is* the private name. It's what the user wrote. It's the name that matches the instance field. It's the name that can be used to access the formal parameter in the initializer list.

The *only* places the public name come into play are:

1. The name you use to pass an argument to that parameter in a named expression.

2. The generated Dartdoc for that constructor.

Given that, I though a simple solution might be to give FormalParameterElement another property for "argument name". In places where we are binding an argument to the parameter, we use that to figure out which parameter is being referred to. Later when I work on Dartdoc support, I'll use that when generating the constructor signature.

Everything else just keeps using the name.

Thoughts?

Change-Id: Id6ccf8d850480f141dc0dc6e26f7b185b60f6c3d
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/459663
Reviewed-by: Konstantin Shcheglov <[email protected]>
Reviewed-by: Paul Berry <[email protected]>
Reviewed-by: Brian Wilkerson <[email protected]>
Commit-Queue: Bob Nystrom <[email protected]>
Auto-Submit: Bob Nystrom <[email protected]>

Author: munificent

pkg/analyzer/api.txt

@@ -3642,11 +3642,13 @@ package:analyzer/dart/element/element.dart:
     firstFragment (getter: FieldFormalParameterFragment)
     fragments (getter: List<FieldFormalParameterFragment>)
     isDeclaring (getter: bool, experimental)
+    privateName (getter: String?, experimental)
   FieldFormalParameterFragment (class extends Object implements FormalParameterFragment):
     new (constructor: FieldFormalParameterFragment Function())
     element (getter: FieldFormalParameterElement)
     nextFragment (getter: FieldFormalParameterFragment?)
     previousFragment (getter: FieldFormalParameterFragment?)
+    privateName (getter: String?, experimental)
   FieldFragment (class extends Object implements PropertyInducingFragment):
     new (constructor: FieldFragment Function())
     element (getter: FieldElement)

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

@@ -1253,6 +1253,24 @@ abstract class FieldFormalParameterElement implements FormalParameterElement {
   /// Whether this is a declaring formal parameter.
   @experimental
   bool get isDeclaring;
+
+  /// If this field formal parameter is a named parameter with a private name,
+  /// the original private name.
+  ///
+  /// In that case, [name] is the corresponding public name for the parameter
+  /// and [privateName] is the original declared name. Otherwise (the declared
+  /// name wasn't private or was private but has no corresponding public name),
+  /// then, [privateName] is `null`.
+  ///
+  /// The private name is used for:
+  ///
+  /// * Accessing the parameter in the initializer list.
+  ///
+  /// * Finding the corresponding instance variable.
+  ///
+  /// * Referring to the parameter in the constructor's doc comment.
+  @experimental
+  String? get privateName;
 }
 
 /// The portion of a [FieldFormalParameterElement] contributed by a single
@@ -1268,6 +1286,13 @@ abstract class FieldFormalParameterFragment implements FormalParameterFragment {
 
   @override
   FieldFormalParameterFragment? get previousFragment;
+
+  /// If this field formal parameter is a named parameter with a private name,
+  /// the original private name.
+  ///
+  /// In that case, [name] is the corresponding public name for the parameter.
+  @experimental
+  String? get privateName;
 }
 
 /// The portion of a [FieldElement] contributed by a single declaration.

pkg/analyzer/lib/src/dart/analysis/driver.dart

@@ -109,7 +109,7 @@ testFineAfterLibraryAnalyzerHook;
 // TODO(scheglov): Clean up the list of implicitly analyzed files.
 class AnalysisDriver {
   /// The version of data format, should be incremented on every format change.
-  static const int DATA_VERSION = 584;
+  static const int DATA_VERSION = 585;
 
   /// The number of exception contexts allowed to write. Once this field is
   /// zero, we stop writing any new exception contexts in this process.

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

@@ -60,6 +60,7 @@ import 'package:analyzer/src/utilities/extensions/collection.dart';
 import 'package:analyzer/src/utilities/extensions/element.dart';
 import 'package:analyzer/src/utilities/extensions/object.dart';
 import 'package:collection/collection.dart';
+import 'package:meta/meta.dart';
 import 'package:pub_semver/pub_semver.dart';
 
 part 'element.g.dart';
@@ -2856,6 +2857,9 @@ class FieldFormalParameterElementImpl extends FormalParameterElementImpl
   @override
   bool get isDeclaring => _firstFragment.isDeclaring;
 
+  @override
+  String? get privateName => _firstFragment.privateName;
+
   @override
   FieldFormalParameterFragmentImpl get _firstFragment =>
       super._firstFragment as FieldFormalParameterFragmentImpl;
@@ -2865,13 +2869,18 @@ class FieldFormalParameterElementImpl extends FormalParameterElementImpl
 class FieldFormalParameterFragmentImpl extends FormalParameterFragmentImpl
     with _FieldFormalParameterFragmentImplMixin
     implements FieldFormalParameterFragment {
+  @experimental
+  @override
+  final String? privateName;
+
   /// Initialize a newly created parameter element to have the given [name] and
   /// [nameOffset].
   FieldFormalParameterFragmentImpl({
     super.firstTokenOffset,
     required super.name,
     required super.nameOffset,
     required super.parameterKind,
+    required this.privateName,
   });
 
   @override
@@ -3110,9 +3119,7 @@ class FormalParameterElementImpl extends PromotableElementImpl
   }
 
   @override
-  String? get name {
-    return _firstFragment.name;
-  }
+  String? get name => _firstFragment.name;
 
   @override
   String get nameShared => _firstFragment.name ?? '';

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

@@ -555,6 +555,9 @@ class SubstitutedFieldFormalParameterElementImpl
 
   @override
   bool get isDeclaring => baseElement.isDeclaring;
+
+  @override
+  String? get privateName => baseElement.privateName;
 }
 
 /// A parameter element defined in a parameterized type where the values of the

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

@@ -23,7 +23,15 @@ class ConstructorInitializerScope extends EnclosedScope {
       if (formalParameter.name == '_' && hasWildcardVariables) {
         continue;
       }
-      _addGetter(formalParameter);
+
+      // If the parameter is a private named parameter, then the formal
+      // parameter's name is the public name, but in the constructor initializer
+      // list, it is referred to by its private name.
+      if (formalParameter case FieldFormalParameterElement(:var privateName?)) {
+        _getters[privateName] ??= formalParameter;
+      } else {
+        _addGetter(formalParameter);
+      }
     }
   }
 }

pkg/analyzer/lib/src/dart/resolver/resolution_visitor.dart

@@ -473,6 +473,7 @@ class ResolutionVisitor extends RecursiveAstVisitor<void> {
           parameterKind: node.kind,
           name: name2,
           nameOffset: nameOffset2,
+          privateName: null,
         )..constantInitializer = node.defaultValue;
       } else if (node.parameter is SuperFormalParameter) {
         // Only for recovery, this should not happen in valid code.
@@ -667,6 +668,7 @@ class ResolutionVisitor extends RecursiveAstVisitor<void> {
           name: nameToken.lexeme.nullIfEmpty,
           nameOffset: nameToken.offset.nullIfNegative,
           parameterKind: node.kind,
+          privateName: null,
         );
         _elementHolder.enclose(fragment);
         fragment.isConst = node.isConst;

pkg/analyzer/lib/src/generated/error_verifier.dart

@@ -6032,6 +6032,12 @@ class ErrorVerifier extends RecursiveAstVisitor<void>
       return;
     }
 
+    // Must refer to a field.
+    // TODO(rnystrom): Handle primary constructor declaring parameters.
+    if (parameter is! FieldFormalParameter) {
+      return;
+    }
+
     if (correspondingPublicName(name.lexeme) == null) {
       diagnosticReporter.atToken(
         name,

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

@@ -743,6 +743,9 @@ class LibraryReader {
     });
   }
 
+  /// Read the resolution for a formal parameter list fragment for a
+  /// top-level function, method, constructor, getter, or setter
+  /// declaration.
   void _readFormalParameters2(
     LibraryFragmentImpl unitElement,
     ResolutionReader reader,
@@ -1051,6 +1054,8 @@ class LibraryReader {
     return _reader.readOptionalObject(() => _readReference());
   }
 
+  /// Read the formal parameter list for a top-level function, method,
+  /// constructor, getter, or setter declaration.
   // TODO(scheglov): Deduplicate parameter reading implementation.
   List<FormalParameterFragmentImpl> _readParameters() {
     return _reader.readTypedList(() {
@@ -1064,10 +1069,12 @@ class LibraryReader {
 
       FormalParameterFragmentImpl element;
       if (isInitializingFormal) {
+        var privateName = _reader.readOptionalStringReference();
         element = FieldFormalParameterFragmentImpl(
           name: fragmentName,
           nameOffset: null,
           parameterKind: kind,
+          privateName: privateName,
         );
       } else if (isSuperFormal) {
         element = SuperFormalParameterFragmentImpl(
@@ -1780,6 +1787,8 @@ class ResolutionReader {
     return type;
   }
 
+  /// Read the formal parameter list for a function type annotation or type
+  /// alias of a function type.
   List<FormalParameterFragmentImpl> _readFormalParameters(
     LibraryFragmentImpl? unitElement,
   ) {
@@ -1793,10 +1802,12 @@ class ResolutionReader {
       var name = _readFragmentName();
       FormalParameterFragmentImpl element;
       if (isInitializingFormal) {
+        var privateName = _reader.readOptionalStringReference();
         element = FieldFormalParameterFragmentImpl(
           name: name,
           nameOffset: null,
           parameterKind: kind,
+          privateName: privateName,
         );
         element.element.type = type;
       } else {

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

@@ -626,13 +626,20 @@ class BundleWriter {
     _sink.writeOptionalObject(reference, _writeReference);
   }
 
+  /// Write a formal parameter fragment in the signature of a top-level
+  /// function, constructor, method, getter, or setter declaration.
   // TODO(scheglov): Deduplicate parameter writing implementation.
   void _writeParameterElement(FormalParameterFragmentImpl element) {
     _writeFragmentId(element);
     _writeFragmentName(element);
     _sink.writeBool(element.isInitializingFormal);
     _sink.writeBool(element.isSuperFormal);
     _sink._writeFormalParameterKind(element);
+
+    if (element is FieldFormalParameterFragmentImpl) {
+      _sink.writeOptionalStringReference(element.privateName);
+    }
+
     element.writeModifiers(_sink);
 
     _resolutionSink._writeMetadata(element.metadata);
@@ -1019,6 +1026,7 @@ class ResolutionSink extends BinaryWriter {
     writeOptionalStringReference(element.name);
   }
 
+  /// Write the formal parameter list for a function type alias.
   void _writeFormalParameters(
     List<FormalParameterFragmentImpl> parameters, {
     required bool withAnnotations,
@@ -1030,6 +1038,9 @@ class ResolutionSink extends BinaryWriter {
       _writeTypeParameters(parameter.typeParameters, () {
         writeType(parameter.element.type);
         _writeFragmentName(parameter);
+        if (parameter case FieldFormalParameterElementImpl fieldFormal) {
+          writeOptionalStringReference(fieldFormal.privateName);
+        }
         _writeFormalParameters(
           parameter.formalParameters,
           withAnnotations: withAnnotations,
@@ -1041,6 +1052,7 @@ class ResolutionSink extends BinaryWriter {
     });
   }
 
+  /// Write the formal parameter list for a function type annotation.
   void _writeFormalParameters2(
     List<InternalFormalParameterElement> parameters, {
     required bool withAnnotations,
@@ -1052,6 +1064,10 @@ class ResolutionSink extends BinaryWriter {
       _writeTypeParameters2(parameter.typeParameters, () {
         writeType(parameter.type);
         _writeElementName(parameter);
+        if (parameter.baseElement
+            case FieldFormalParameterElementImpl fieldFormal) {
+          writeOptionalStringReference(fieldFormal.privateName);
+        }
         _writeFormalParameters2(
           parameter.formalParameters.cast(),
           withAnnotations: withAnnotations,