Skip to content

Commit 8b9b5a6

Browse files
authored
[record_use] Identifiers must only have package uris (dart-lang#3045)
Bug: dart-lang#2891 (Needs a PR in the Dart SDK as well to avoid recording things outside package uris.)
1 parent e359106 commit 8b9b5a6

3 files changed

Lines changed: 27 additions & 9 deletions

File tree

‎pkgs/record_use/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,11 @@ the method will be recorded, as far as they can be inferred at compile time.
1515
any constant instance of the class will be recorded. This is particularly useful
1616
when using the class as an annotation.
1717

18+
> [!NOTE]
19+
> The `@RecordUse` annotation is only allowed on definitions within a package's
20+
> `lib/` directory. This includes definitions that are members of a class, such
21+
> as static methods.
22+
1823
## Example
1924

2025
```dart

‎pkgs/record_use/lib/src/identifier.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@ class Identifier {
2222
///
2323
/// This is given in the form of its package import uri, so that it is OS- and
2424
/// user independent.
25+
///
26+
/// For elements annotated with `@RecordUse`, this URI will always point to a
27+
/// file in the `lib/` directory of a package.
2528
final String importUri;
2629

2730
/// The name of the parent element (e.g., the class name for a method or

‎pkgs/record_use/lib/src/record_use.dart‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ import '../record_use_internal.dart';
88
///
99
/// This can be queried using the methods provided, which each take an
1010
/// [Identifier] which must be annotated with `@RecordUse` from `package:meta`.
11+
///
12+
/// The definition annotated with `@RecordUse` must be inside the `lib/`
13+
/// directory of the package. If the definition is a member of a class (e.g. a
14+
/// static method), the class must be in the `lib/` directory.
1115
extension type RecordedUsages._(Recordings _recordings) {
1216
RecordedUsages.fromJson(Map<String, Object?> json)
1317
: this._(Recordings.fromJson(json));
@@ -17,9 +21,11 @@ extension type RecordedUsages._(Recordings _recordings) {
1721

1822
/// Finds all const arguments for calls to the [identifier].
1923
///
20-
/// The definition must be annotated with `@RecordUse()`. If there are no
21-
/// calls to the definition, either because it was treeshaken, because it was
22-
/// not annotated, or because it does not exist, returns empty.
24+
/// The definition must be annotated with `@RecordUse()`. The definition (and
25+
/// its enclosing class, if any) must be in the `lib/` directory of the
26+
/// package. If there are no calls to the definition, either because it was
27+
/// treeshaken, because it was not annotated, or because it does not exist,
28+
/// this method returns an empty iterable.
2329
///
2430
/// Returns an empty iterable if the arguments were not collected.
2531
///
@@ -64,9 +70,11 @@ extension type RecordedUsages._(Recordings _recordings) {
6470

6571
/// Finds all constant fields of a const instance of the class [identifier].
6672
///
67-
/// The definition must be annotated with `@RecordUse()`. If there are
68-
/// no instances of the definition, either because it was treeshaken, because
69-
/// it was not annotated, or because it does not exist, returns empty.
73+
/// The definition must be annotated with `@RecordUse()`. The definition (and
74+
/// its enclosing class, if any) must be in the `lib/` directory of the
75+
/// package. If there are no instances of the definition, either because it
76+
/// was treeshaken, because it was not annotated, or because it does not
77+
/// exist, this method returns an empty iterable.
7078
///
7179
/// Example:
7280
/// ```dart
@@ -108,9 +116,11 @@ extension type RecordedUsages._(Recordings _recordings) {
108116
/// Checks if any call to [identifier] has non-const arguments, or if any
109117
/// tear-off was recorded.
110118
///
111-
/// The definition must be annotated with `@RecordUse()`. If there are no
112-
/// calls to the definition, either because it was treeshaken, because it was
113-
/// not annotated, or because it does not exist, returns `false`.
119+
/// The definition must be annotated with `@RecordUse()`. The definition (and
120+
/// its enclosing class, if any) must be in the `lib/` directory of the
121+
/// package. If there are no calls to the definition, either because it was
122+
/// treeshaken, because it was not annotated, or because it does not exist,
123+
/// this method returns `false`.
114124
bool hasNonConstArguments(Identifier identifier) =>
115125
(_recordings.calls[identifier] ?? []).any(
116126
(element) => switch (element) {

0 commit comments

Comments
 (0)