Improve tool ergonomics and consistency across bindgen/clang/rdl

[kennykerr]

Harmonize build-script APIs across windows-bindgen, windows-rdl, windows-clang, and metadata merge/remap.

Standardize builder naming, required-output validation, and role-specific errors.

Expand error-path and remapper test coverage.

Update repository callers and documentation.

[Copilot]

Pull request overview

This PR harmonizes the build-tool/builder APIs across windows-bindgen, windows-rdl, windows-clang, and the metadata merge/remap surfaces by standardizing naming, path handling (typed Path/PathBuf), required-output validation, and role-specific error reporting. It also updates in-repo tools/tests/docs to the new API shapes and expands negative-path test coverage.

Changes:

• Standardize builder inputs/outputs to accept AsRef<Path> and store PathBuf, add plural “*_sets” byte APIs, and rename “inline source” helpers to input_text/input_texts.
• Split “input vs reference vs resolution” roles (notably for RDL/Clang) and switch boolean options to enabling methods (e.g., .split(), .union_enums(), .drop_lib_less()).
• Add/extend error-path and remapper tests; update all affected tools, samples, and crate documentation.

Reviewed changes

Copilot reviewed 49 out of 49 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/crates/windows-rdl.md	Update RDL docs for reference_* vs input_* roles and new path/inline-text APIs.
docs/crates/windows-metadata.md	Document merge/remap path typing and new singular/plural builder methods.
docs/crates/windows-default.md	Clarify default-metadata behavior across builders (explicit defaults vs textual adapters).
docs/crates/windows-clang.md	Update examples/docs for reference_default, input_text*, and write_by_header terminal.
docs/crates/windows-bindgen.md	Document command files vs filter files, typed paths, and updated implementation-selection APIs.
crates/tools/winrt/src/main.rs	Update writer usage to enabling .split().
crates/tools/win32/src/main.rs	Update merge/clang builder calls for enabling booleans, scopes, input_texts, and typed paths.
crates/tools/win32/src/km.rs	Same as above for KM scrape path typing and input_text.
crates/tools/webview/src/main.rs	Move from UTF-8 string paths / input_default to typed paths and reference_default.
crates/tools/roundtrip/src/main.rs	Separate RDL inputs from winmd references and update writer .split() usage.
crates/tools/reactor/src/main.rs	Switch bindgen invocation from CLI-style args to the programmatic builder API.
crates/tools/composition/src/main.rs	Switch bindgen invocation to builder API; use typed paths and filter_file.
crates/tests/winrt/composable_aggregation/build.rs	Update RDL reader default metadata to reference_default.
crates/tests/libs/win32_metadata/tests/win32.rs	Fix RDL reader role separation by using .reference(...) for winmd.
crates/tests/libs/rdl/tests/roundtrip.rs	Adopt typed paths for reader/writer inputs/outputs.
crates/tests/libs/rdl/tests/method_params.rs	Adopt typed paths and update reference handling for attribute winmd.
crates/tests/libs/rdl/tests/errors.rs	Expand negative tests for missing output, invalid reference/input role reporting, and extension checks.
crates/tests/libs/rdl/tests/bytes.rs	Add coverage for reference path inputs and byte-set APIs; update defaults.
crates/tests/libs/metadata/tests/remap.rs	New: add remapper routing + error-path coverage (including missing outputs).
crates/tests/libs/metadata/tests/nested_roundtrip.rs	Update merge/writer calls to typed paths and enabling .split().
crates/tests/libs/metadata/tests/merge.rs	Update merger API usage to enabling .union_enums() and typed .output(...).
crates/tests/libs/metadata/tests/arch_roundtrip.rs	Update arch merge + writer calls for typed paths and enabling .split().
crates/tests/libs/csharp/tests/scale.rs	Update RDL default metadata usage to reference_default.
crates/tests/libs/csharp/tests/csharp.rs	Update RDL default metadata usage to reference_default.
crates/tests/libs/clang/tests/header_partition.rs	Update to new clang terminals (namespace/output + .write_by_header()), and new singular methods (scope, exclude_header).
crates/tests/libs/clang/tests/clang.rs	Add negative tests for output-required/role errors and update reference byte-set API.
crates/tests/libs/bindgen/tests/errors.rs	Expand negative tests for missing command/filter files, invalid options, missing output, conflicting styles.
crates/tests/libs/bindgen/tests/bytes.rs	Add coverage for byte-set inputs and command-file + nested-command-file expansion.
crates/samples/test_bench/component/build.rs	Update RDL reader defaults and bindgen implementation selection (implement_all).
crates/samples/robot/component/build.rs	Same as above for robot sample.
crates/samples/robot/component_cpp/build.rs	Update RDL reader default metadata usage.
crates/libs/rdl/src/writer/mod.rs	Convert writer to typed paths, add input_byte_sets, enabling .split(), and output-required validation.
crates/libs/rdl/src/reader/mod.rs	Introduce typed paths, separate reference role, add input_text* + reference_byte_sets, and updated validation.
crates/libs/rdl/src/lib.rs	Update public APIs (item_names, merge_arch_rdl, expand_input_*, write_to_file) for typed paths.
crates/libs/rdl/readme.md	Update readme for reference(...), input_text*, and reference_default().
crates/libs/metadata/src/merge/remap.rs	Convert remapper to typed paths, add plural builders, add route helper, and output-required validation.
crates/libs/metadata/src/merge/mod.rs	Convert merger to typed paths and enabling .union_enums(), plus output-required validation.
crates/libs/default/readme.md	Clarify which builders should use .input_default() vs .reference_default().
crates/libs/csharp/tests/generate.rs	Update RDL default metadata usage to reference_default.
crates/libs/clang/src/scrape.rs	Convert scrape plan paths to PathBuf and align RDL reader calls with new reference role.
crates/libs/clang/src/scope.rs	Update import-library path handling to &Path and improve error reporting.
crates/libs/clang/src/lib.rs	Major clang builder API rework: typed paths, separate reference/resolution roles, new singular/plural helpers, enabling methods, and terminal output validation.
crates/libs/clang/src/const.rs	Rename synthetic filename for inline-input eval to match input_text naming.
crates/libs/clang/readme.md	Update examples and docs to new builder/terminal usage.
crates/libs/bindgen/src/package_writer.rs	Switch path construction to PathBuf::join for correctness across platforms.
crates/libs/bindgen/src/lib.rs	Convert bindgen builder to typed paths, add byte-set + filter-file APIs, rework implementation selection, and preserve implicit-default behavior.
crates/libs/bindgen/src/io.rs	Convert IO helpers to typed paths and improve panic messages with path.display().
crates/libs/bindgen/src/cli.rs	Add --filter-file, improve --etc command-file expansion, and keep --in default semantics in the textual adapter only.
crates/libs/bindgen/readme.md	Document command-file vs filter-file usage and the updated APIs.