[native_assets_cli] Deprecate metadata (#1341)

We might not address this issue fully before stable.

* #1251

But we're quite sure to remove the current metadata API, so deprecate it.

Author: dcharkes

pkgs/native_assets_builder/test_data/package_reading_metadata/hook/build.dart

@@ -2,6 +2,8 @@
 // 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.
 
+// ignore_for_file: deprecated_member_use
+
 import 'package:native_assets_cli/native_assets_cli.dart';
 
 void main(List<String> args) async {

pkgs/native_assets_builder/test_data/package_with_metadata/hook/build.dart

@@ -6,6 +6,7 @@ import 'package:native_assets_cli/native_assets_cli.dart';
 
 void main(List<String> arguments) async {
   await build(arguments, (config, output) async {
+    // ignore: deprecated_member_use
     output.addMetadata({
       'some_key': 'some_value',
       'some_int': 3,

pkgs/native_assets_cli/CHANGELOG.md

@@ -1,6 +1,6 @@
 ## 0.7.2-wip
 
-- Nothing yet.
+- Deprecate metadata concept.
 
 ## 0.7.1
 

pkgs/native_assets_cli/lib/src/api/build_config.dart

@@ -17,6 +17,7 @@ import 'asset.dart';
 import 'build.dart';
 import 'build_mode.dart';
 import 'build_output.dart';
+import 'deprecation_messages.dart';
 import 'hook_config.dart';
 import 'ios_sdk.dart';
 import 'link_mode_preference.dart';
@@ -41,6 +42,7 @@ abstract final class BuildConfig implements HookConfig {
   ///
   /// Not available during a [dryRun]. Will throw a [StateError] if accessed
   /// during a [dryRun].
+  @Deprecated(metadataDeprecation)
   Object? metadatum(String packageName, String key);
 
   /// Whether link hooks will be run after the build hooks.
@@ -106,6 +108,7 @@ abstract final class BuildConfig implements HookConfig {
   ///
   /// Parameter [dependencyMetadata] must be a nested map `{'packageName' :
   /// {'key' : 'value'}}` where `packageName` and `key` correspond to the
+  // ignore: deprecated_member_use_from_same_package
   /// parameters in [metadatum].
   factory BuildConfig.build({
     required Uri outputDirectory,
@@ -120,6 +123,7 @@ abstract final class BuildConfig implements HookConfig {
     int? targetAndroidNdkApi,
     CCompilerConfig? cCompiler,
     required LinkModePreference linkModePreference,
+    @Deprecated(metadataDeprecation)
     Map<String, Map<String, Object>>? dependencyMetadata,
     Iterable<String>? supportedAssetTypes,
     required bool linkingEnabled,

pkgs/native_assets_cli/lib/src/api/build_output.dart

@@ -20,6 +20,7 @@ import 'asset.dart';
 import 'build.dart';
 import 'build_config.dart';
 import 'builder.dart';
+import 'deprecation_messages.dart';
 import 'hook_config.dart';
 import 'link.dart';
 import 'linker.dart';
@@ -96,12 +97,13 @@ abstract final class BuildOutput {
   ///
   /// Metadata can be passed to build hook invocations of dependent packages. It
   /// must be provided to the constructor as [metadata], or added later with
+  // ignore: deprecated_member_use_from_same_package
   /// [addMetadatum] and [addMetadata].
   factory BuildOutput({
     DateTime? timestamp,
     Iterable<Asset>? assets,
     Iterable<Uri>? dependencies,
-    Map<String, Object>? metadata,
+    @Deprecated(metadataDeprecation) Map<String, Object>? metadata,
   }) =>
       HookOutputImpl(
         timestamp: timestamp,
@@ -139,10 +141,12 @@ abstract final class BuildOutput {
 
   /// Adds metadata to be passed to build hook invocations of dependent
   /// packages.
+  @Deprecated(metadataDeprecation)
   void addMetadatum(String key, Object value);
 
   /// Adds metadata to be passed to build hook invocations of dependent
   /// packages.
+  @Deprecated(metadataDeprecation)
   void addMetadata(Map<String, Object> metadata);
 
   /// The version of [BuildOutput].

pkgs/native_assets_cli/lib/src/api/builder.dart

@@ -1,3 +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.
+
 import 'package:logging/logging.dart';
 
 import 'build_config.dart';

pkgs/native_assets_cli/lib/src/api/deprecation_messages.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.
+
+const metadataDeprecation = '''
+Metadata will be reworked to merge concepts with assets.
+If you're currently using metadata, please report your use case in the tracking
+issue: https://github.com/dart-lang/native/issues/1251.
+''';

pkgs/native_assets_cli/lib/src/api/linker.dart

@@ -1,3 +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.
+
 import 'package:logging/logging.dart';
 
 import 'build_output.dart';

pkgs/native_assets_cli/test/api/build_config_test.dart

@@ -2,6 +2,8 @@
 // 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.
 
+// ignore_for_file: deprecated_member_use_from_same_package
+
 import 'dart:io';
 
 import 'package:native_assets_cli/native_assets_cli.dart';

pkgs/native_assets_cli/test/api/build_output_test.dart

@@ -41,6 +41,7 @@ void main() {
       dependencies: [
         Uri.file('path/to/file.ext'),
       ],
+      // ignore: deprecated_member_use_from_same_package
       metadata: {
         'key': 'value',
       },