[native_assets_cli] Unify Metadata with Assets

[dcharkes]

Bug: #1251

This PR adds support for two things:

1. Routing assets from build hook to build hooks.
2. Adding a MetadataAsset for sending metadata between hooks.

This enables two use cases:

1. Deprecating the current bespoke metadata system in favor of one built on top of the new routing with the new asset type.
   Example: pkgs/native_assets_builder/test_data/package_with_metadata/hook/build.dart + pkgs/native_assets_builder/test_data/package_reading_metadata/hook/build.dart
2. Exporting a dynamic library from one package, and using the native linker to link against it in dependent library.
   Example: pkgs/native_assets_builder/test_data/reusable_dynamic_library/hook/build.dart + pkgs/native_assets_builder/test_data/reuse_dynamic_library/hook/build.dart

To accommodate this change the String? linkInPackage is replaced with Routing routing everywhere. This has three subtypes:

1. BundleInApp(), equivalent to linkInPackage: null,
2. Tolinker(String packageName), equivalent to linkInPackage: packageName, and
3. ToBuild() which makes the asset available in the BuildInput of the direct dependencies.

Note that assets routed to other build hooks via ToBuild() also need to be routed to BundleInApp(). If another package uses the asset at runtime, it cannot re-bundle it itself because that would lead to double bundling if two packages use such asset.

(This leads to a weird quirk where we now have List<Routing> as a parameter for CBuilder because we want the asset to be added in two places. We should probably redesign CBuilder.run to not use the HookInput/HookOutput directly.)

[github-actions]

PR Health

Breaking changes ✔️

Package	Change	Current Version	New Version	Needed Version	Looking good?

Changelog Entry ✔️

Package	Changed Files

Changes to files need to be accounted for in their respective changelogs.

API leaks ✔️

The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.

Package	Leaked API symbols

License Headers ✔️

// Copyright (c) 2025, 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.

Files
no missing headers

All source files should start with a license header.

Unrelated files missing license headers

Files
pkgs/jni/lib/src/third_party/generated_bindings.dart
pkgs/objective_c/lib/src/ns_input_stream.dart

[mkustermann]

We reserve the right to invoke build hooks & link hooks once or multiple times. If we invoke it multiple times we may add different values for buildAssetTypes.

@dcharkes Is the new MetadataAsset a required asset type that any build hook is allowed to use? (i.e. protocol mandates it to be in buildAssetTypes)?

[dcharkes]

We reserve the right to invoke build hooks & link hooks once or multiple times. If we invoke it multiple times we may add different values for buildAssetTypes.

@dcharkes Is the new MetadataAsset a required asset type that any build hook is allowed to use? (i.e. protocol mandates it to be in buildAssetTypes)?

You can output any asset type in ToLinker and ToBuild. The checking for asset types is only for the BundleInApp Routing. So, it does not have to be in buildAssetTypes. Any unknown asset type can flow between two build hooks or between a build hook an a link hook.

[mosuem]

Just an idea: We could avoid the input.config.linkingEnabled bool calls by instead having something like an input.config.routing, which can be a LinkingEnabledRouter which has a toLinker method, or a LinkingNotEnabledRouter which only has bundleInApp or toBuilder`.

[dcharkes]

I like having a input.config.routing. 👍 That makes the API symmetric again.

I'm not sure that having to take the value from the input would make a very nice API. Especially for ToBuild or BundleInApp where you don't need to check the config. Let me give it a try.

[dcharkes]

I gave this a spin, but make the call sites even more verbose.

      routing: switch (input.config.routing) {
        final LinkingEnabledRouter r => r.toLinkHook(packageName),
        LinkingDisabledRouter() => const ToAppBundle(),
      },

Then the following is more readable:

      routing: switch (input.config.routing) {
        LinkingEnabledRouter() => ToLinkHook(packageName),
        LinkingDisabledRouter() => const ToAppBundle(),
      },

Current solution (this doesn't show the routing)

      routing: switch (input.config.linkingEnabled) {
        true => ToLinkHook(packageName),
        false => const ToAppBundle(),
      },

With routing added:

      routing: switch (input.config.routing.linkHooksEnabled) {
        true => ToLinkHook(packageName),
        false => const ToAppBundle(),
      },

True false is not very pretty. Let's try a when

      routing: switch (input.config.routing) {
        final routing when routing.linkHooksEnabled => ToLinkHook(packageName),
        _ => const ToAppBundle(),
      },

Also not that great.

Then the following is more readable:

      routing: switch (input.config.routing) {
        LinkHooksEnabled() => ToLinkHook(packageName),
        LinkHooksDisabled() => const ToAppBundle(),
      },

But it only works if that's the only option we ever want to add to the routing. It's only the Dart API, so we could do it, it's easy to refactor.

(P.S. If we want to go the route with the method, we should probably do the same with LinkModePreference and LinkMode.)

[dcharkes]

Let's try this in a more holistic way for everywhere where the input-output constraint could be made more explicit.

#2175

[coveralls]

coverage: 84.923% (+0.1%) from 84.822%
when pulling 2f240a9 on metadata-refactor
into 481af77 on main.