Add package:record_use

This package provides (de-)serialization for recorded usages (formerly known as resource identifiers).

Adding to the SDK packages for faster development for now - to be moved to dart-lang/ on Github in the future.

See also the review at dart-lang/native#1479.

Change-Id: I4796bbf5616f64ce700a1bc59f279883acb36263
Cq-Include-Trybots: luci.dart.try:pkg-linux-debug-try,pkg-linux-release-arm64-try,pkg-linux-release-try,pkg-mac-release-arm64-try,pkg-mac-release-try,pkg-win-release-arm64-try,pkg-win-release-try
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/383340
Commit-Queue: Moritz Sümmermann <[email protected]>
Reviewed-by: Martin Kustermann <[email protected]>

pkg/record_use/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+- Initial version.

pkg/record_use/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2024, the Dart project authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkg/record_use/README.md

@@ -0,0 +1,111 @@
+# `package:record_use`
+
+
+> [!CAUTION]
+> This is an experimental package, and it's API can break at any time. Use at
+> your own discretion.
+
+This package provides the data classes for the usage recording feature in the
+Dart SDK.
+
+Dart objects with the `@RecordUse` annotation are being recorded at compile 
+time, providing the user with information. The information depends on the object
+being recorded.
+
+- If placed on a static method, the annotation means that arguments passed to
+the method will be recorded, as far as they can be inferred at compile time.
+- If placed on a class with a constant constructor, the annotation means that
+any constant instance of the class will be recorded. This is particularly useful
+when using the class as an annotation.
+
+## Example
+
+```dart
+import 'package:meta/meta.dart' show RecordUse;
+
+void main() {
+  print(SomeClass.stringMetadata(42));
+  print(SomeClass.doubleMetadata(42));
+  print(SomeClass.intMetadata(42));
+  print(SomeClass.boolMetadata(42));
+}
+
+class SomeClass {
+  @RecordMetadata('leroyjenkins')
+  @RecordUse()
+  static stringMetadata(int i) {
+    return i + 1;
+  }
+
+  @RecordMetadata(3.14)
+  @RecordUse()
+  static doubleMetadata(int i) {
+    return i + 1;
+  }
+
+  @RecordMetadata(42)
+  @RecordUse()
+  static intMetadata(int i) {
+    return i + 1;
+  }
+
+  @RecordMetadata(true)
+  @RecordUse()
+  static boolMetadata(int i) {
+    return i + 1;
+  }
+}
+
+@RecordUse()
+class RecordMetadata {
+  final Object metadata;
+
+  const RecordMetadata(this.metadata);
+}
+
+```
+This code will generate a data file that contains both the `metadata` values of
+the `RecordMetadata` instances, as well as the arguments for the different
+methods annotated with `@RecordUse()`.
+
+This information can then be accessed in a link hook as follows:
+```dart
+import 'dart:convert';
+
+import 'package:native_assets_cli/native_assets_cli.dart';
+import 'package:record_use/record_use_internal.dart';
+
+final methodId = Identifier(
+  uri: 'myfile.dart',
+  name: 'myMethod',
+);
+
+final classId = Identifier(
+  uri: 'myfile.dart',
+  name: 'myClass',
+);
+
+void main(List<String> arguments){
+  link(arguments, (config, output) async {
+    final usesUri = config.recordedUses;
+    final usesJson = await File,fromUri(usesUri).readAsString();
+    final uses = UsageRecord.fromJson(jsonDecode(usesJson));
+
+    final args = uses.argumentsTo(methodId));
+    //[args] is an iterable of arguments, in this case containing "42"
+
+    final fields = uses.instancesOf(classId);
+    //[fields] is an iterable of the fields of the class, in this case
+    //containing
+    // {"arguments": "leroyjenkins"}
+    // {"arguments": 3.14}
+    // {"arguments": 42}
+    // {"arguments": true}
+
+    ... // Do something with the information, such as tree-shaking native assets
+  });
+}
+```
+
+## Contributing
+Contributions are welcome! Please open an issue or submit a pull request.

pkg/record_use/example/record_use_example.dart

@@ -0,0 +1,12 @@
+// Copyright (c) 2024, 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.
+
+import 'package:record_use/record_use.dart';
+
+void doStuff(RecordedUsages usage, Identifier callId, Identifier referenceId) {
+  print(usage.metadata);
+  print(usage.argumentsTo(callId));
+  print(usage.instancesOf(referenceId));
+  print(usage.hasNonConstArguments(callId));
+}

pkg/record_use/lib/record_use.dart

@@ -0,0 +1,23 @@
+// Copyright (c) 2024, 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.
+
+export 'src/public/arguments.dart'
+    show Arguments, ConstArguments, NonConstArguments;
+export 'src/public/constant.dart'
+    show
+        BoolConstant,
+        Constant,
+        IntConstant,
+        ListConstant,
+        MapConstant,
+        NullConstant,
+        PrimitiveConstant,
+        StringConstant;
+export 'src/public/identifier.dart' show Identifier;
+export 'src/public/instance_constant.dart' show InstanceConstant;
+export 'src/public/location.dart' show Location;
+export 'src/public/metadata.dart' show Metadata;
+//Not exporting `Reference` as it is not used in the API
+export 'src/public/reference.dart' show CallReference, InstanceReference;
+export 'src/record_use.dart' show RecordedUsages;

pkg/record_use/lib/record_use_internal.dart

@@ -0,0 +1,8 @@
+// Copyright (c) 2024, 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.
+
+export 'record_use.dart';
+export 'src/internal/definition.dart' show Definition;
+export 'src/internal/usage.dart' show Usage;
+export 'src/internal/usage_record.dart' show UsageRecord;

pkg/record_use/lib/src/helper.dart

@@ -0,0 +1,9 @@
+// Copyright (c) 2024, 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.
+
+import 'package:collection/collection.dart';
+
+final deepEquals = const DeepCollectionEquality().equals;
+
+final deepHash = const DeepCollectionEquality().hash;

pkg/record_use/lib/src/internal/definition.dart

@@ -0,0 +1,59 @@
+// Copyright (c) 2024, 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.
+
+import '../public/identifier.dart';
+import '../public/location.dart';
+
+class Definition {
+  final Identifier identifier;
+
+  /// Represents the '@' field in the JSON
+  final Location location;
+  final String? loadingUnit;
+
+  const Definition({
+    required this.identifier,
+    required this.location,
+    this.loadingUnit,
+  });
+
+  factory Definition.fromJson(
+    Map<String, dynamic> json,
+    List<Identifier> identifiers,
+  ) {
+    final identifier = identifiers[json['id'] as int];
+    return Definition(
+      identifier: identifier,
+      location: Location.fromJson(
+        json['@'] as Map<String, dynamic>,
+        identifier.uri,
+        null,
+      ),
+      loadingUnit: json['loadingUnit'] as String?,
+    );
+  }
+
+  Map<String, dynamic> toJson(
+    List<Identifier> identifiers,
+    List<String> uris,
+  ) =>
+      {
+        'id': identifiers.indexOf(identifier),
+        '@': location.toJson(),
+        'loadingUnit': loadingUnit,
+      };
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+
+    return other is Definition &&
+        other.identifier == identifier &&
+        other.location == location &&
+        other.loadingUnit == loadingUnit;
+  }
+
+  @override
+  int get hashCode => Object.hash(identifier, location, loadingUnit);
+}

pkg/record_use/lib/src/internal/usage.dart

@@ -0,0 +1,58 @@
+// Copyright (c) 2024, 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.
+
+import '../helper.dart';
+import '../public/constant.dart';
+import '../public/identifier.dart';
+import '../public/reference.dart';
+import 'definition.dart';
+
+class Usage<T extends Reference> {
+  final Definition definition;
+  final List<T> references;
+
+  const Usage({
+    required this.definition,
+    required this.references,
+  });
+
+  factory Usage.fromJson(
+    Map<String, dynamic> json,
+    List<Identifier> identifiers,
+    List<String> uris,
+    List<Constant> constants,
+    T Function(Map<String, dynamic>, List<String>, List<Constant>) constr,
+  ) =>
+      Usage(
+        definition: Definition.fromJson(
+          json['definition'] as Map<String, dynamic>,
+          identifiers,
+        ),
+        references: (json['references'] as List)
+            .map((x) => constr(x as Map<String, dynamic>, uris, constants))
+            .toList(),
+      );
+
+  Map<String, dynamic> toJson(
+    List<Identifier> identifiers,
+    List<String> uris,
+    List<Constant> constants,
+  ) =>
+      {
+        'definition': definition.toJson(identifiers, uris),
+        'references': references.map((x) => x.toJson(uris, constants)).toList(),
+      };
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+
+    return other is Usage<T> &&
+        other.definition == definition &&
+        deepEquals(other.references, references);
+  }
+
+  @override
+  int get hashCode => Object.hash(definition, deepHash(references));
+}