Add package:record_use

.github/workflows/health.yaml

@@ -0,0 +1,15 @@
+name: Health
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - .github/workflows/record_use.yaml
+      - pkgs/record_use/**
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+jobs:
+  health:
+    uses: dart-lang/ecosystem/.github/workflows/health.yaml@main
+    with:
+      coverage_web: false
+    permissions:
+      pull-requests: write

.github/workflows/post_summaries.yaml

@@ -0,0 +1,17 @@
+name: Comment on the pull request
+
+on:
+  # Trigger this workflow after the Health workflow completes. This workflow will have permissions to
+  # do things like create comments on the PR, even if the original workflow couldn't.
+  workflow_run:
+    workflows:
+      - Health
+      - Publish
+    types:
+      - completed
+
+jobs:
+  upload:
+    uses: dart-lang/ecosystem/.github/workflows/post_summaries.yaml@main
+    permissions:
+      pull-requests: write

.github/workflows/record_use.yaml

@@ -0,0 +1,39 @@
+name: 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

@@ -7,7 +7,7 @@ This repository is home to various Dart packages under the [dart.dev](https://pu
 ## Packages
 
 | Package | Description | Version |
-|---|---|---|
+|[`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)|
 
 ## Publishing automation
 

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,115 @@
+# `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.constArgumentsTo(boolMetadataId));
+    //[args] is an iterable of arguments, in this case containing "42"
+
+    final fields = uses.instanceReferencesTo(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,9 @@
+include: package:dart_flutter_team_lints/analysis_options.yaml
+
+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.version);
+  print(usage.constArgumentsTo(callId));
+  print(usage.instanceReferencesTo(referenceId));
+  print(usage.hasNonConstArguments(callId));
+}

pkgs/record_use/lib/record_use.dart

@@ -0,0 +1,5 @@
+// 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/record_use.dart' show Identifier, RecordedUsages;

pkgs/record_use/lib/record_use_internal.dart

@@ -0,0 +1,7 @@
+// 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/extensions.dart';
+export 'src/proto/usages_read.pb.dart';
+export 'src/proto/usages_shared.pb.dart';