Add package:record_use with JSON storage

.github/workflows/health.yaml

@@ -8,6 +8,7 @@ on:
       - "pkgs/native_assets_builder/**"
       - "pkgs/native_assets_cli/**"
       - "pkgs/native_toolchain_c/**"
+      - "pkgs/record_use/**"
     types: [opened, synchronize, reopened, labeled, unlabeled]
 jobs:
   health:

.github/workflows/record_use.yaml

@@ -0,0 +1,57 @@
+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:
+    defaults:
+      run:
+        working-directory: pkgs/record_use/
+    strategy:
+      matrix:
+        os: [ubuntu, windows]
+        sdk: [stable, dev]
+
+    runs-on: ${{ matrix.os }}-latest
+
+    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
+
+      - name: Install coverage
+        run: dart pub global activate coverage
+
+      - name: Collect coverage
+        run: dart pub global run coverage:test_with_coverage
+
+      - name: Upload coverage
+        uses: coverallsapp/github-action@643bc377ffa44ace6394b2b5d0d3950076de9f63
+        with:
+          flag-name: record_use
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          parallel: true
+          path-to-lcov: ./pkgs/record_use/coverage/lcov.info
+        if: ${{ matrix.sdk == 'stable' }}

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

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,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/public/arguments.dart'
+    show Arguments, ConstArguments, NonConstArguments;
+export 'src/public/field.dart' show Field;
+export 'src/public/identifier.dart' show Identifier;
+export 'src/public/instance.dart' show Instance;
+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;

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

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