Add package:record_use with JSON storage

.github/workflows/record_use.yaml

@@ -0,0 +1,39 @@
+name: 'package:record_use'
+permissions: read-all
+
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - .github/workflows/record_use.yaml
+      - pkgs/record_use/**
+  push:
+    branches: [ main ]
+    paths:
+      - .github/workflows/record_use.yaml
+      - pkgs/record_use/**
+  schedule:
+    - cron: '0 0 * * 0' # weekly
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: pkgs/record_use/
+    strategy:
+      matrix:
+        sdk: [stable, dev]
+    steps:
+      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+      - uses: dart-lang/setup-dart@2986c8e337a31eb7b455ce93dc984e9bf5797756
+        with:
+          sdk: ${{matrix.sdk}}
+
+      - run: dart pub get
+
+      - run: dart analyze --fatal-infos
+
+      - run: dart format --output=none --set-exit-if-changed .
+
+      - run: dart test

README.md

@@ -19,6 +19,7 @@ building and bundling.
 | [native_assets_builder](pkgs/native_assets_builder/) | This package is the backend that invokes build hooks. | [![pub package](https://img.shields.io/pub/v/native_assets_builder.svg)](https://pub.dev/packages/native_assets_builder) |
 | [native_assets_cli](pkgs/native_assets_cli/) | A library that contains the argument and file formats for implementing a native assets CLI. | [![pub package](https://img.shields.io/pub/v/native_assets_cli.svg)](https://pub.dev/packages/native_assets_cli) |
 | [native_toolchain_c](pkgs/native_toolchain_c/) | A library to invoke the native C compiler installed on the host machine. | [![pub package](https://img.shields.io/pub/v/native_toolchain_c.svg)](https://pub.dev/packages/native_toolchain_c) |
+| [record_use](pkgs/record_use/) | The serialization logic and API for the usage recording SDK feature. | [![pub package](https://img.shields.io/pub/v/record_use.svg)](https://pub.dev/packages/record_use) |
 
 ## External packages
 

pkgs/record_use/.github/workflows/test.yaml

@@ -0,0 +1,34 @@
+name: test
+permissions: read-all
+
+on:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+  schedule:
+    - cron: '0 0 * * 0' # weekly
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        sdk: [stable, dev]
+    steps:
+      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+      - uses: dart-lang/setup-dart@fedb1266e91cf51be2fdb382869461a434b920a3
+        with:
+          sdk: ${{matrix.sdk}}
+
+      - run: dart pub get
+
+      - run: dart analyze --fatal-infos
+
+      - run: dart format --output=none --set-exit-if-changed .
+
+      - run: dart test
+
+      - name: Run Chrome tests - wasm
+        run: dart test --platform chrome --compiler dart2wasm
+        if: always() && matrix.sdk == 'dev'

pkgs/record_use/.gitignore

@@ -0,0 +1,7 @@
+# https://dart.dev/guides/libraries/private-files
+# Created by `dart pub`
+.dart_tool/
+
+# Avoid committing pubspec.lock for library packages; see
+# https://dart.dev/guides/libraries/private-files#pubspeclock.
+pubspec.lock

pkgs/record_use/CHANGELOG.md

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

pkgs/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.

pkgs/record_use/README.md

@@ -0,0 +1,116 @@
+# `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 'package:native_assets_cli/native_assets_cli.dart';
+
+void main(List<String> arguments){
+  link(arguments, (config, output) async {
+    final uses = config.recordedUses;
+
+    final args = uses.argumentsTo(boolMetadataId));
+    //[args] is an iterable of arguments, in this case containing "42"
+
+    final fields = uses.instancesOf(recordMetadataId);
+    //[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
+  });
+}
+```
+
+## Installation
+To install the record_use package, run the following command:
+
+```bash
+dart pub add record_use
+```
+
+## Internals
+
+The data is stored in protobuf format. Two schemas are provided:
+
+### [usages_read](lib/src/proto/usages_read.proto)
+This is the schema for the internal API for the storage format, which is used
+in the SDK for writing the data, and in the [record_use](lib/src/record_use.dart) format for retrieving the
+data for the queries from the user.
+
+### [usages_storage](lib/src/proto/usages_storage.proto)
+This schema is for the storage of the data, and contains some optimizations such
+as collecting all URIs in a table, to avoid repetitions.
+
+## Contributing
+Contributions are welcome! Please open an issue or submit a pull request.

pkgs/record_use/analysis_options.yaml

@@ -0,0 +1,17 @@
+include: package:dart_flutter_team_lints/analysis_options.yaml
+
+analyzer:
+  errors:
+    todo: ignore
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+
+linter:
+  rules:
+    - conditional_uri_does_not_exist
+    - prefer_const_constructors
+    - prefer_final_locals
+    - prefer_relative_imports
+    - unnecessary_parenthesis

pkgs/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));
+}

pkgs/record_use/lib/record_use.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.
+
+export 'src/data_classes/arguments.dart'
+    show Arguments, ConstArguments, NonConstArguments;
+export 'src/data_classes/field.dart' show Field;
+export 'src/data_classes/identifier.dart' show Identifier;
+export 'src/data_classes/location.dart' show Location;
+export 'src/data_classes/metadata.dart' show Metadata;
+export 'src/data_classes/reference.dart' show CallReference, InstanceReference;
+export 'src/record_use.dart' show RecordedUsages;

pkgs/record_use/lib/record_use_internal.dart

@@ -0,0 +1,14 @@
+// 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/data_classes/annotation.dart';
+export 'src/data_classes/arguments.dart';
+export 'src/data_classes/definition.dart';
+export 'src/data_classes/field.dart';
+export 'src/data_classes/identifier.dart';
+export 'src/data_classes/location.dart';
+export 'src/data_classes/metadata.dart';
+export 'src/data_classes/reference.dart';
+export 'src/data_classes/usage.dart';
+export 'src/data_classes/usage_record.dart';

pkgs/record_use/lib/src/data_classes/annotation.dart

@@ -0,0 +1,44 @@
+// 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';
+
+import 'identifier.dart';
+
+class Annotation {
+  final Identifier identifier;
+  final Map<String, dynamic> fields;
+
+  Annotation({
+    required this.identifier,
+    required this.fields,
+  });
+
+  factory Annotation.fromJson(
+    Map<String, dynamic> json,
+    List<Identifier> identifiers,
+  ) =>
+      Annotation(
+        identifier: identifiers[json['id'] as int],
+        fields: json['fields'] as Map<String, dynamic>,
+      );
+
+  Map<String, dynamic> toJson(List<Identifier> identifiers) => {
+        'id': identifiers.indexOf(identifier),
+        'fields': fields,
+      };
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+    final mapEquals = const DeepCollectionEquality().equals;
+
+    return other is Annotation &&
+        other.identifier == identifier &&
+        mapEquals(other.fields, fields);
+  }
+
+  @override
+  int get hashCode => identifier.hashCode ^ fields.hashCode;
+}