[ffigen] Implement YAML -> tool/ffigen.dart migrator

pkgs/ffigen/CHANGELOG.md

@@ -3,6 +3,14 @@
 - Bump `package:meta` dependency to `^1.19.0` and stop generating
   `experimental_member_use` lint ignore in generated bindings when
   `@RecordUse()` is used.
+- Add `dart run ffigen:migrate` to generate a Dart script (using the
+  `FfiGenerator` API) from an existing YAML configuration, to help migrate off
+  the YAML config format.
+- Re-export `Logger` from `package:logging` in `package:ffigen/ffigen.dart`,
+  since it appears in the public API (e.g. in `defaultCompilerOpts`).
+- Add `Headers.includeGlobs`, a helper to build a `Headers.include` filter
+  from glob patterns, matching the semantics of the YAML config's
+  `include-directives`.
 
 ## 21.0.0
 

pkgs/ffigen/README.md

@@ -149,11 +149,40 @@ in the following way:
 1. Install Xcode.
 2. Install Xcode command line tools: `xcode-select --install`.
 
+## Migrating from YAML
+
+If you have an existing YAML configuration and want to move to the Dart API,
+run the bundled migration tool:
+
+```bash
+dart run ffigen:migrate --config config.yaml --output tool/ffigen.dart
+```
+
+If `--config` is omitted, the tool looks for an `ffigen:` key in
+`pubspec.yaml`, matching `dart run ffigen`'s own default. If `--output` is
+omitted, the script is written to `tool/ffigen.dart`. The generated script can
+then be run directly with `dart run tool/ffigen.dart` (or via a
+[build hook](#getting-started)) to regenerate bindings, and can be committed
+in place of the YAML file.
+
+The migration is best-effort: it translates each YAML key to the closest
+equivalent `FfiGenerator` API call, falling back to inline callbacks (for
+example, for regex-based `include`/`exclude`/`rename` entries) where there is
+no direct equivalent. Options that have no Dart API equivalent are preserved
+as `// TODO(ffigen migration): ...` comments in the generated file so nothing
+from the original configuration is silently dropped. Review the generated
+script, resolve any `TODO`s, and compare output before deleting the original
+YAML file.
+
+Run `dart run ffigen:migrate --help` to see all available options.
+
 ## YAML Configuration Reference
 
 In addition to the Dart API shown in the "Getting Started" section, FFIgen can
 also be configured via YAML. Support for the YAML configuration will be
-eventually phased out, and using the Dart API is recommended.
+eventually phased out, and using the Dart API is recommended. See
+["Migrating from YAML"](#migrating-from-yaml) above for an automated migration
+path.
 
 A YAML configuration can be either provided in the project's `pubspec.yaml` file
 under the key `ffigen` or via a custom YAML file. To generate bindings

pkgs/ffigen/bin/migrate.dart

@@ -0,0 +1,5 @@
+// Copyright (c) 2026, 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 'package:ffigen/src/executables/migrate.dart';

pkgs/ffigen/lib/ffigen.dart

@@ -13,6 +13,12 @@
 /// @docImport 'src/config_provider.dart';
 library;
 
+// `Logger` appears in the public API (e.g. as the parameter of
+// [defaultCompilerOpts]), so re-export it to allow users (and the scripts
+// generated by `ffigen:migrate`) to construct one without a direct
+// dependency on `package:logging`.
+export 'package:logging/logging.dart' show Logger;
+
 export 'src/code_generator/imports.dart' show ImportedType, LibraryImport;
 export 'src/config_provider.dart'
     show

pkgs/ffigen/lib/src/config_provider/config.dart

@@ -6,6 +6,7 @@ import 'dart:ffi';
 
 import 'package:logging/logging.dart';
 import 'package:meta/meta.dart';
+import 'package:quiver/pattern.dart' as quiver;
 
 import '../code_generator.dart';
 import '../ffigen.dart';
@@ -136,6 +137,24 @@ final class Headers {
 
   static bool _includeDefault(Uri header) => true;
 
+  /// Returns a function to pass to [include] that includes any header whose
+  /// file path fully matches one of [globs].
+  ///
+  /// `*` matches anything within a path segment, `**` matches across path
+  /// segments, and `?` matches a single character. Since the header's whole
+  /// (absolute) path is matched, patterns typically start with `**`, e.g.
+  /// `'**/include/*.h'`.
+  ///
+  /// This matches the semantics of the legacy YAML config's
+  /// `include-directives`.
+  static bool Function(Uri) includeGlobs(List<String> globs) {
+    final patterns = [for (final glob in globs) quiver.Glob(glob)];
+    return (Uri header) {
+      final path = header.toFilePath();
+      return patterns.any((p) => quiver.matchesFull(p, path));
+    };
+  }
+
   /// Command line arguments to pass to clang_compiler.
   final List<String>? compilerOptions;