[record_use] Identifiers must only have package uris

pkgs/record_use/README.md

@@ -15,6 +15,11 @@ the method will be recorded, as far as they can be inferred at compile time.
 any constant instance of the class will be recorded. This is particularly useful
 when using the class as an annotation.
 
+> [!NOTE]
+> The `@RecordUse` annotation is only allowed on definitions within a package's
+> `lib/` directory. This includes definitions that are members of a class, such
+> as static methods.
+
 ## Example
 
 ```dart

pkgs/record_use/lib/src/identifier.dart

@@ -22,6 +22,9 @@ class Identifier {
   ///
   /// This is given in the form of its package import uri, so that it is OS- and
   /// user independent.
+  ///
+  /// For elements annotated with `@RecordUse`, this URI will always point to a
+  /// file in the `lib/` directory of a package.
   final String importUri;
 
   /// The name of the parent element (e.g., the class name for a method or

pkgs/record_use/lib/src/record_use.dart

@@ -8,6 +8,10 @@ import '../record_use_internal.dart';
 ///
 /// This can be queried using the methods provided, which each take an
 /// [Identifier] which must be annotated with `@RecordUse` from `package:meta`.
+///
+/// The definition annotated with `@RecordUse` must be inside the `lib/`
+/// directory of the package. If the definition is a member of a class (e.g. a
+/// static method), the class must be in the `lib/` directory.
 extension type RecordedUsages._(Recordings _recordings) {
   RecordedUsages.fromJson(Map<String, Object?> json)
     : this._(Recordings.fromJson(json));
@@ -17,9 +21,11 @@ extension type RecordedUsages._(Recordings _recordings) {
 
   /// Finds all const arguments for calls to the [identifier].
   ///
-  /// The definition must be annotated with `@RecordUse()`. If there are no
-  /// calls to the definition, either because it was treeshaken, because it was
-  /// not annotated, or because it does not exist, returns empty.
+  /// The definition must be annotated with `@RecordUse()`. The definition (and
+  /// its enclosing class, if any) must be in the `lib/` directory of the
+  /// package. If there are no calls to the definition, either because it was
+  /// treeshaken, because it was not annotated, or because it does not exist,
+  /// this method returns an empty iterable.
   ///
   /// Returns an empty iterable if the arguments were not collected.
   ///
@@ -64,9 +70,11 @@ extension type RecordedUsages._(Recordings _recordings) {
 
   /// Finds all constant fields of a const instance of the class [identifier].
   ///
-  /// The definition must be annotated with `@RecordUse()`. If there are
-  /// no instances of the definition, either because it was treeshaken, because
-  /// it was not annotated, or because it does not exist, returns empty.
+  /// The definition must be annotated with `@RecordUse()`. The definition (and
+  /// its enclosing class, if any) must be in the `lib/` directory of the
+  /// package. If there are no instances of the definition, either because it
+  /// was treeshaken, because it was not annotated, or because it does not
+  /// exist, this method returns an empty iterable.
   ///
   /// Example:
   /// ```dart
@@ -108,9 +116,11 @@ extension type RecordedUsages._(Recordings _recordings) {
   /// Checks if any call to [identifier] has non-const arguments, or if any
   /// tear-off was recorded.
   ///
-  /// The definition must be annotated with `@RecordUse()`. If there are no
-  /// calls to the definition, either because it was treeshaken, because it was
-  /// not annotated, or because it does not exist, returns `false`.
+  /// The definition must be annotated with `@RecordUse()`. The definition (and
+  /// its enclosing class, if any) must be in the `lib/` directory of the
+  /// package. If there are no calls to the definition, either because it was
+  /// treeshaken, because it was not annotated, or because it does not exist,
+  /// this method returns `false`.
   bool hasNonConstArguments(Identifier identifier) =>
       (_recordings.calls[identifier] ?? []).any(
         (element) => switch (element) {