Switch to protobuf

pkgs/record_use/README.md

@@ -12,12 +12,11 @@ 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 calls to the method
-are being recorded. If the `arguments` parameter is set to `true`, then
-arguments will also be recorded, as far as they can be inferred at compile time.
+- 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 placing 
+when using the class as an annotation.
 
 ## Example
 ```dart
@@ -64,7 +63,7 @@ class RecordMetadata {
 }
 
 ```
-This code will generate a JSON file that contains both the `metadata` values of
+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()`.
 
@@ -76,11 +75,12 @@ void main(List<String> arguments){
   link(arguments, (config, output) async {
     final uses = config.recordedUses;
     
-    final args = uses.callReferencesTo(boolMetadataId));
-    //[args] is an iterable of [Argument] classes, in this case containing "42"
+    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 [Field] classes, in this case containing
+    //[fields] is an iterable of the fields of the class, in this case
+    //containing
     // {"arguments": "leroyjenkins"}
     // {"arguments": 3.14}
     // {"arguments": 42}
@@ -98,5 +98,18 @@ To install the record_use package, run the following command:
 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/lib/record_use.dart

@@ -2,11 +2,4 @@
 // 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 RecordUse;
+export 'src/record_use.dart' show Identifier, RecordUse;

pkgs/record_use/lib/record_use_internal.dart

@@ -2,13 +2,5 @@
 // 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';
+export 'src/proto/usages_read.pb.dart';
+export 'src/proto/usages_shared.pb.dart';

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

@@ -0,0 +1,105 @@
+// 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 'dart:convert';
+import 'dart:typed_data';
+
+import '../proto/usages_read.pb.dart' as pb;
+import '../proto/usages_shared.pb.dart' as pb_shared;
+import '../proto/usages_storage.pb.dart' as pb_storage;
+
+extension UsagesExt on pb.Usages {
+  Uint8List toBuffer() => _toStorage().writeToBuffer();
+  String toDebugJson() =>
+      const JsonEncoder.withIndent('  ').convert(_toStorage().writeToJsonMap());
+
+  pb_storage.Usages _toStorage() {
+    final definitions =
+        [...calls, ...instances].map((e) => e.definition).toList();
+    final uris = [...calls, ...instances]
+        .expand((e) => [
+              e.definition.identifier.uri,
+              ...e.references.map(
+                (e) => e.location.uri,
+              )
+            ])
+        .toList();
+    return pb_storage.Usages(
+      metadata: metadata,
+      definitions: definitions,
+      uris: uris,
+      instances: instances.map((e) => e.toStorage(definitions, uris)),
+      calls: calls.map((e) => e.toStorage(definitions, uris)),
+    );
+  }
+}
+
+extension UsageExt on pb.Usage {
+  pb_storage.Usage toStorage(
+          List<pb_shared.Definition> definitions, List<String> uris) =>
+      pb_storage.Usage(
+        definition: definitions.indexOf(definition),
+        references: references.map((e) => e.toStorage(uris)),
+      );
+}
+
+extension ReferenceExt on pb.Reference {
+  pb_storage.Reference toStorage(List<String> uris) => pb_storage.Reference(
+        arguments: hasArguments() ? arguments : null,
+        fields: hasFields() ? fields : null,
+        loadingUnit: loadingUnit,
+        location: location.toStorage(uris),
+      );
+}
+
+extension LocationExt on pb.Location {
+  pb_storage.Location toStorage(List<String> uris) => pb_storage.Location(
+        column: column,
+        line: line,
+        uri: uris.indexOf(uri),
+      );
+}
+
+extension UsagesStorageExt on pb_storage.Usages {
+  pb.Usages toApi() => pb.Usages(
+        metadata: metadata,
+        calls: calls.map((e) => e.toApi(definitions, uris)),
+        instances: instances.map((e) => e.toApi(definitions, uris)),
+      );
+}
+
+extension UsageStorageExt on pb_storage.Usage {
+  pb.Usage toApi(List<pb_shared.Definition> definitions, List<String> uris) =>
+      pb.Usage(
+        definition: definitions[definition],
+        references: references.map((e) => e.toApi(uris)),
+      );
+}
+
+extension ReferenceStorageExt on pb_storage.Reference {
+  pb.Reference toApi(List<String> uris) => pb.Reference(
+        arguments: hasArguments() ? arguments : null,
+        fields: hasFields() ? fields : null,
+        loadingUnit: loadingUnit,
+        location: location.toApi(uris),
+      );
+}
+
+extension LocationStorageExt on pb_storage.Location {
+  pb.Location toApi(List<String> uris) => pb.Location(
+        column: column,
+        line: line,
+        uri: uris[uri],
+      );
+}
+
+extension FieldValueExt on pb_shared.FieldValue {
+  Object toObject() => switch (whichValue()) {
+        pb_shared.FieldValue_Value.intValue => intValue,
+        pb_shared.FieldValue_Value.doubleValue => doubleValue,
+        pb_shared.FieldValue_Value.boolValue => boolValue,
+        pb_shared.FieldValue_Value.stringValue => stringValue,
+        pb_shared.FieldValue_Value.notSet => throw ArgumentError(),
+      };
+}