Fine. Tracking annotations for element model objects.

WDYT? I annotated `ClassElementImpl2` as an example. Eventually we will
have a lint rule to enforce these annotation.

So, if a new getter or method is added, the developer who adds it will
have to make a decision, how to track it.

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

Author: scheglov

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

@@ -41,6 +41,7 @@ import 'package:analyzer/src/dart/element/type_system.dart';
 import 'package:analyzer/src/dart/resolver/scope.dart'
     show Namespace, NamespaceBuilder;
 import 'package:analyzer/src/error/inference_error.dart';
+import 'package:analyzer/src/fine/annotations.dart';
 import 'package:analyzer/src/fine/library_manifest.dart';
 import 'package:analyzer/src/fine/requirements.dart';
 import 'package:analyzer/src/generated/engine.dart' show AnalysisContext;
@@ -135,14 +136,15 @@ class BindPatternVariableFragmentImpl extends PatternVariableFragmentImpl
       super.previousFragment as BindPatternVariableFragmentImpl?;
 }
 
+@elementClass
 class ClassElementImpl2 extends InterfaceElementImpl2 implements ClassElement {
   @override
+  @trackedIncludedIntoId
   final Reference reference;
 
-  @override
-  final ClassFragmentImpl firstFragment;
+  final ClassFragmentImpl _firstFragment;
 
-  ClassElementImpl2(this.reference, this.firstFragment) {
+  ClassElementImpl2(this.reference, this._firstFragment) {
     reference.element2 = this;
     firstFragment.augmentedInternal = this;
   }
@@ -153,7 +155,10 @@ class ClassElementImpl2 extends InterfaceElementImpl2 implements ClassElement {
   ///
   /// If the class is sealed, and all its subtypes are either final or sealed,
   /// then these subtypes are all subtypes that are possible.
+  @trackedDirectlyExpensive
   List<InterfaceTypeImpl>? get allSubtypes {
+    globalResultRequirements?.record_classElement_allSubtypes(element: this);
+
     if (isFinal) {
       var result = <InterfaceTypeImpl>[];
       for (var element in library2.children2) {
@@ -199,7 +204,16 @@ class ClassElementImpl2 extends InterfaceElementImpl2 implements ClassElement {
   }
 
   @override
+  @trackedDirectlyDisable
+  ClassFragmentImpl get firstFragment {
+    globalResultRequirements?.record_disable(this, 'firstFragment');
+    return _firstFragment;
+  }
+
+  @override
+  @trackedDirectlyDisable
   List<ClassFragmentImpl> get fragments {
+    globalResultRequirements?.record_disable(this, 'fragments');
     return [
       for (
         ClassFragmentImpl? fragment = firstFragment;
@@ -211,8 +225,12 @@ class ClassElementImpl2 extends InterfaceElementImpl2 implements ClassElement {
   }
 
   @override
-  @override
+  @trackedDirectlyExpensive
   bool get hasNonFinalField {
+    globalResultRequirements?.record_classElement_hasNonFinalField(
+      element: this,
+    );
+
     var classesToVisit = <InterfaceElementImpl2>[];
     var visitedClasses = <InterfaceElementImpl2>{};
     classesToVisit.add(this);
@@ -244,25 +262,34 @@ class ClassElementImpl2 extends InterfaceElementImpl2 implements ClassElement {
   }
 
   @override
+  @trackedIncludedIntoId
   bool get isAbstract => firstFragment.isAbstract;
 
   @override
+  @trackedIncludedIntoId
   bool get isBase => firstFragment.isBase;
 
   @override
+  @trackedIncludedIntoId
   bool get isConstructable => firstFragment.isConstructable;
 
   @override
+  @trackedIncludedIntoId
   bool get isDartCoreEnum => firstFragment.isDartCoreEnum;
 
   @override
+  @trackedIncludedIntoId
   bool get isDartCoreObject => firstFragment.isDartCoreObject;
 
+  @trackedIncludedIntoId
   bool get isDartCoreRecord {
     return name3 == 'Record' && library2.isDartCore;
   }
 
+  @trackedDirectlyExpensive
   bool get isEnumLike {
+    globalResultRequirements?.record_classElement_isEnumLike(element: this);
+
     // Must be a concrete class.
     if (isAbstract) {
       return false;
@@ -297,32 +324,42 @@ class ClassElementImpl2 extends InterfaceElementImpl2 implements ClassElement {
   }
 
   @override
+  @trackedIncludedIntoId
   bool get isExhaustive => firstFragment.isExhaustive;
 
   @override
+  @trackedIncludedIntoId
   bool get isFinal => firstFragment.isFinal;
 
   @override
+  @trackedIncludedIntoId
   bool get isInterface => firstFragment.isInterface;
 
   @override
+  @trackedIncludedIntoId
   bool get isMixinApplication => firstFragment.isMixinApplication;
 
   @override
+  @trackedIncludedIntoId
   bool get isMixinClass => firstFragment.isMixinClass;
 
   @override
+  @trackedIncludedIntoId
   bool get isSealed => firstFragment.isSealed;
 
   @override
+  @trackedIncludedIntoId
   bool get isValidMixin => firstFragment.isValidMixin;
 
   @override
+  @trackedDirectlyDisable
   T? accept2<T>(ElementVisitor2<T> visitor) {
+    globalResultRequirements?.record_disable(this, 'accept2');
     return visitor.visitClassElement(this);
   }
 
   @override
+  @trackedIndirectly
   bool isExtendableIn2(LibraryElement library) {
     if (library == library2) {
       return true;
@@ -331,6 +368,7 @@ class ClassElementImpl2 extends InterfaceElementImpl2 implements ClassElement {
   }
 
   @override
+  @trackedIndirectly
   bool isImplementableIn2(LibraryElement library) {
     if (library == library2) {
       return true;
@@ -339,6 +377,7 @@ class ClassElementImpl2 extends InterfaceElementImpl2 implements ClassElement {
   }
 
   @override
+  @trackedIndirectly
   bool isMixableIn2(LibraryElement library) {
     if (library == library2) {
       return true;

pkg/analyzer/lib/src/fine/annotations.dart

@@ -0,0 +1,95 @@
+// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// Annotation for classes that are part of the element model.
+///
+/// Classes marked with this annotation require some of their members to be
+/// annotated, as follows:
+///
+/// Public getters and fields must be annotated with one of:
+///   [trackedIncludedIntoId]
+///   [trackedDirectly]
+///   [trackedIndirectly]
+///
+/// Public methods must be annotated with one of:
+///   [trackedDirectly]
+///   [trackedIndirectly]
+const elementClass = _ElementClass();
+
+/// Annotation for methods that must record the fact of the invocation.
+///
+/// In contrast to [trackedIncludedIntoId], the result of the method is not
+/// reflected in the ID of the target class, so we need to record this
+/// requirement separately.
+///
+/// Examples: `getMethod(name)`, `getNamedConstructor(name)`.
+const trackedDirectly = _TrackedDirectly();
+
+/// Annotation for methods that are too invasive, and if invoked for anything
+/// other than the current library, disable fine-grained dependencies
+/// optimizations. So, the result will be re-computed if just anything in
+/// its transitive closure of imported libraries changed.
+///
+/// Examples: `fragments`, `visitChildren()`.
+///
+/// We must make sure that the analyzer itself does not use such APIs.
+/// We should try to fix any popular lint rules that use such APIs.
+const trackedDirectlyDisable = _TrackedDirectlyDisable();
+
+/// As [trackedDirectly], but for methods that are expensive.
+///
+/// For example, `get methods` adds dependency on all declared methods, but
+/// if the client then filters these methods in some way, it would be better
+/// to use (or add if absent) a more specific method, e.g. `getMethod(name)`.
+///
+/// Examples: `constructors`, `methods`.
+///
+/// We must make sure that the analyzer itself does not use such APIs.
+/// We should try to fix any popular lint rules that use such APIs.
+const trackedDirectlyExpensive = _TrackedDirectlyExpensive();
+
+/// Annotation for getters that don't require recording.
+///
+/// The library manifest builder must compare the value of the getter with
+/// the previous value in the manifest, and give the element a new ID if the
+/// value is different.
+///
+/// Examples: `isAbstract`, `interfaces`, `returnType`.
+const trackedIncludedIntoId = _TrackedIncludedIntoId();
+
+/// Annotation for methods that don't require recording.
+///
+/// The implementation of the method uses only getters and methods which
+/// do record requirements, or already would cause a new ID for the target
+/// class.
+const trackedIndirectly = _TrackedIndirectly();
+
+final class _ElementClass {
+  const _ElementClass();
+}
+
+final class _TrackedDirectly extends _TrackedKind {
+  const _TrackedDirectly();
+}
+
+final class _TrackedDirectlyDisable extends _TrackedDirectly {
+  const _TrackedDirectlyDisable();
+}
+
+final class _TrackedDirectlyExpensive extends _TrackedDirectly {
+  const _TrackedDirectlyExpensive();
+}
+
+final class _TrackedIncludedIntoId extends _TrackedKind {
+  const _TrackedIncludedIntoId();
+}
+
+final class _TrackedIndirectly extends _TrackedKind {
+  const _TrackedIndirectly();
+}
+
+/// Superclass for all specific kinds of tracking annotations.
+sealed class _TrackedKind {
+  const _TrackedKind();
+}

pkg/analyzer/lib/src/fine/requirements.dart

@@ -511,6 +511,24 @@ class RequirementsManifest {
     }
   }
 
+  void record_classElement_allSubtypes({required ClassElementImpl2 element}) {
+    // TODO(scheglov): implement.
+  }
+
+  void record_classElement_hasNonFinalField({
+    required ClassElementImpl2 element,
+  }) {
+    // TODO(scheglov): implement.
+  }
+
+  void record_classElement_isEnumLike({required ClassElementImpl2 element}) {
+    // TODO(scheglov): implement.
+  }
+
+  void record_disable(Object target, String method) {
+    // TODO(scheglov): implement.
+  }
+
   void record_instanceElement_getGetter({
     required InstanceElementImpl2 element,
     required String name,