`windows-clang` header-to-bindings improvements for OS

[kennykerr]

1. Float-backed native typedefs must not derive Eq.

Status: Already fixed by #4877; no further work.

Current code: crates/libs/bindgen/src/types/cpp_handle.rs, Config::write_cpp_handle, now calls Type::is_eq. crates/libs/bindgen/src/types/mod.rs, Type::is_eq, rejects f32/f64 and recursively checks fields and arrays.

Expected behavior: Wrappers backed by f32 or f64 derive PartialEq but not Eq; integer and pointer wrappers can still derive Eq.

Recommendation: Keep the merged implementation rather than a special case that only matches top-level F32/F64.

2. Accept .h, .hpp, .hxx, and .hh header inputs.

Status: Valid low-risk improvement.

Current code: crates/libs/clang/src/lib.rs, Clang::parse_inputs, calls windows_rdl::expand_input_files(..., "h"). crates/libs/rdl/src/lib.rs, expand_input_paths, compares one exact extension, so explicit C++ header paths are rejected and directory scans omit them.

Fix: Add a header-specific expansion helper, or allow callers to pass an extension set, without changing the behavior of generic .rdl and .winmd input expansion.

Acceptance coverage: Explicit files and mixed directories; all four extensions; case-insensitive matching; invalid extensions must still produce an error.

3. Do not globally change Default-style free functions from link! to extern.

Status: Reject the proposed global behavior change; consider an opt-in feature separately.

Current code: crates/libs/bindgen/src/lib.rs, Style::sys_fn_extern, enables extern declarations only for Style::Sys { extern_fns: true }. Bindgen::extern_fns intentionally requires sys style.

Problem with the proposed change: Including Style::Default in sys_fn_extern silently changes link emission for every rich Win32 free function and changes an established output contract to accommodate a particular runtime dependency version.

Recommendation: Preserve current defaults. If rich bindings need extern declarations, model link emission as an explicit option independent of projection style and test rich wrappers, raw sys functions, variadics, aliases, and function-pointer emission.

4. Canonicalize HRESULT in namespaced header scrapes without allowing a local shadow.

Status: Valid correctness issue; the prototype is incomplete.

Current code: crates/libs/clang/src/canon.rs, resolve_typedef, checks parser.ref_map before canonical mappings and has no unconditional HRESULT rule. A declaration such as typedef long HRESULT; can therefore resolve to a foreign or local value type instead of Windows.Foundation.HResult.

Required behavior: A free function declared as HRESULT ReproStatus(); in Default projection must produce windows_core::HRESULT, with or without reference metadata.

Fix: Resolve the Windows HRESULT spelling to Windows.Foundation.HResult before reference-map and scalar fallback logic. Also suppress emission of a local HRESULT typedef; otherwise RDL serialization can write both a canonical reference and type HRESULT = i32, and the local name can win when the RDL is compiled again.

Acceptance coverage: Typedef in the main header; typedef in an included header; no reference metadata; reference metadata containing another HRESULT; RDL -> winmd -> bindgen round trip; Default and sys projections. Sys output remaining an i32-ABI type is expected and is not the bug.

5. Resolve COM interface pointer aliases in namespaced return positions.

Status: Valid correctness issue.

Current code: crates/libs/clang/src/canon.rs, interface_alias, handles typedef IFoo NAME and typedef IFoo *NAME, but resolve_typedef only reaches it through flat_canonical. Parameter-specific normalization can make input parameters appear correct while namespaced return types remain aliases.

Example:

typedef IExample *PEXAMPLE;
void AcceptExample(PEXAMPLE value);
PEXAMPLE ReturnExample();

Both uses should resolve to IExample in metadata. Leaving the return as PEXAMPLE can make bindgen treat it as a value type and select zero-initialization rather than interface ABI conversion.

Fix: Apply interface_alias in the namespaced resolve_typedef path with precedence that still honors genuine external interface definitions.

Acceptance coverage: Direct and pointer typedefs; input parameters; return values; retval/out parameters; aliases whose interface is local or supplied by reference metadata.

6. Apply LARGE_INTEGER, ULARGE_INTEGER, and BOOLEAN mappings consistently in namespaced mode.

Status: Valid correctness issue.

Current code: crates/libs/clang/src/canon.rs, semantic_scalar, defines LARGE_INTEGER -> i64, ULARGE_INTEGER -> u64, and BOOLEAN -> bool. flat_canonical uses this table, but namespaced resolve_typedef does not. Record-definition suppression in crates/libs/clang/src/lib.rs and typedef suppression in typedef.rs do not currently have matching namespaced reference behavior.

Failure mode: A namespaced scrape can suppress a LARGE_INTEGER union definition while still emitting a reference named LARGE_INTEGER, leaving a dangling type. A broad opaque fallback can instead create struct LARGE_INTEGER {}, which is also wrong and shadows the intended i64 mapping. BOOLEAN may similarly collapse structurally to u8 rather than the intended bool policy.

Fix: Use the same mapping table for reference canonicalization and definition suppression in both scrape modes. Prefer one table carrying both the projected type and suppression policy so adding a row cannot update one side without the other.

Acceptance coverage: Typedef and direct-tag uses of _LARGE_INTEGER; signed i64; unsigned u64; BOOLEAN -> bool; no emitted shadow structs or typedefs; namespaced and per-header modes.

7. Do not globally retype every non-negative C int macro as u32.

Status: Reject as a default policy; an explicit compatibility policy could be considered.

Current code: crates/libs/clang/src/const.rs, c_integer_constant_type, integer_value, and eval_integer_value, preserve C integer-literal typing. Thus #define VALUE 3 is i32, while suffixes, casts, magnitude, and negation determine other types.

Problem with the proposed change: Making both literal and evaluated positive int expressions produce u32 helps unsigned flag domains but breaks constants passed to signed parameters. It is a projection compatibility choice, not a source-fidelity correction.

Recommendation: Keep source typing as the default. Handle known exceptions with checked per-constant overrides. If a global compatibility policy is needed, make it explicit and test both unsigned flag values and signed parameter values.

8. Provide checked per-constant integer type overrides.

Status: Useful opt-in API, but the prototype needs redesign before merge.

Desired API: Allow a caller to request one of u8, i8, u16, i16, u32, i32, u64, or i64 for a named integer constant in namespaced and per-header output.

Problems in the prototype: It accepts type names as strings and silently ignores unknown spellings. It converts through Rust as, so narrowing can wrap instead of reporting an invalid override. It applies overrides before batch-evaluated constants are inserted, so an expression such as #define EVALUATED_VALUE (1 + 2) misses the override.

Fix: Use a validated integer-type enum or return a configuration error for bad spellings. Apply checked conversions after all token and batch evaluation paths have populated the collector. Report negative-to-unsigned and out-of-range conversions.

Acceptance coverage: All eight widths; literal and batch-evaluated values; namespaced and per-header output; minimum/maximum boundaries; overflow; negative-to-unsigned conversion; invalid type names.

9. Expose explicit Rust module ownership for referenced metadata types.

Status: Valid windows-bindgen API improvement requiring naming and conflict design.

Current code: crates/libs/bindgen/src/references.rs and Bindgen::write already route a fixed set of metadata types to sibling crates through private ReferenceStage entries. Callers cannot add their own mapping, and explicit mappings are also needed in sys style where implicit rich-projection references are disabled.

Desired behavior: Given metadata containing a namespace such as Shared and an existing Rust path such as crate::shared, references to SharedPoint should be written as crate::shared::SharedPoint; bindgen must not emit a second nested SharedPoint definition, but must retain every consumer that uses it.

Fix: Add a structured builder method taking a Rust path and metadata filter as separate arguments. Add an unambiguous CLI option such as --reference-module <path>,<filter>; do not overload a metadata-input option named --reference.

Acceptance coverage: Default and sys styles; flat and module layouts where supported; types defined both locally and in the referenced module; multiple mappings; overlapping filters with deterministic precedence; generic and transitive signature dependencies.

10. Emit opaque records only for genuinely incomplete, pointer-only types.

Status: Forward-record support is valid; the broad prototype rule is unsafe.

Current code: crates/libs/clang/src/cx.rs, Type::to_type, queues opaque records only in per-header mode. Namespaced references to struct ForwardRecord; or typedef struct _ForwardAlias ForwardAlias; can therefore produce names with no declaration.

Correct fix: Track record dependencies and usage shape. If a record has no definition anywhere in the translation unit and is used only behind pointers, emit one opaque declaration under its public typedef name. Do not invent a layout.

Rejection: Do not turn every record absent from the current output set into struct Name {}. A record may be fully defined in an included header or used by value elsewhere.

Acceptance coverage: Direct and typedef forward declarations; const and mutable pointers; duplicate aliases; definitions encountered after forward declarations; a by-value incomplete type must fail rather than become zero-sized.

11. Handle referenced enums without guessing their ABI representation.

Status: Valid missing-dependency issue; the prototype's i32 fallback is unsafe.

Current behavior: A namespaced signature can reference a forward-declared enum or an enum defined in an included but non-emitted header, leaving an unresolved type.

Correct fix: If the enum definition is reachable, emit the definition with its real underlying type and variants. If only a forward declaration is available and libclang provides a valid fixed underlying type, emit an integer-backed stand-in using that exact type. Preserve an in-scope enum definition rather than replacing it with an alias.

Rejection: Do not default CXType_Invalid to i32; the real enum may be u16, u32, i64, or another representation. Report an unsupported unresolved representation instead.

Acceptance coverage: Forward enum class X : int; included enum typedef; explicit unsigned short enum producing u16; local enum retaining variants; invalid/unknown representation; deterministic behavior across translation-unit ordering.

12. Preserve available layouts for out-of-scope and by-value record dependencies.

Status: Valid dependency-closure requirement; reject opaque substitution when a definition exists or the type is used by value.

Example: If an included header defines struct RemoteValue { long long payload; }; and the main header contains struct Envelope { RemoteValue value; };, the emitted RemoteValue must retain its payload: i64 layout. struct RemoteValue {} compiles but is an ABI corruption.

Fix: Extend namespaced dependency traversal to distinguish pointer edges from by-value edges. Follow and emit the real definition for by-value fields, parameters, and return values. A fully defined pointer-only dependency may be emitted as a definition or an intentional opaque shell, but the choice must not affect a later by-value edge.

Acceptance coverage: Pointer-only fully defined records; direct tags and typedef names; by-value fields, parameters, and returns; local definitions must win over placeholders; LARGE_INTEGER must continue through semantic-scalar mapping rather than this fallback.

13. Include types referenced only by typed constants.

Status: Valid namespaced dependency issue.

Current code: crates/libs/clang/src/scope.rs, item_refs, can collect references from a constant's explicit type and typed value. crates/libs/clang/src/lib.rs, process_tu, drains pending_typedefs but does not seed that queue from constant-only references.

Example: A macro value cast to a handle typedef or status typedef may emit const VALUE: HANDLE_TYPE = ... without emitting HANDLE_TYPE, even though the declaration is present in an included header.

Fix: Fold constant references into the same generalized dependency closure used for signatures and fields. Reuse item_refs and declaration lookup; queue only unresolved referenced declarations, and continue until no new dependencies are found. Do not retain unrelated included-header typedefs.

Acceptance coverage: Handle typedef declared through a macro; included scalar typedef; chained typedef dependencies; batch-evaluated constant; unrelated declarations remain excluded.

14. Resolve single-identifier object-like aliases used as constant cast types.

Status: Valid narrowly scoped parser improvement.

Current code: crates/libs/clang/src/macros.rs, collect_macro_defs, already records small object-like macro bodies. crates/libs/clang/src/const.rs, Const::parse, parses cast tokens without resolving a type alias chain first.

Example: Given #define USER_HANDLE HANDLE, #define CHAIN_HANDLE USER_HANDLE, and #define VALUE ((CHAIN_HANDLE)-2), the emitted constant should have type HANDLE. A function-like macro with the same identifier spelling must not be mistaken for an object-like alias.

Fix: Resolve chains only when the parser expects a named cast type. Require each replacement to be exactly one identifier, terminate cycles, ignore function-like macros, and share the translation-unit macro map across output modes. Avoid rewriting unrelated identifiers in the expression.

Acceptance coverage: One-hop and chained aliases; cycles; function-like collisions; aliases to unrelated value tokens; namespaced and per-header output.

15. Require the header that actually declares a referenced type.

Status: Consumer configuration requirement, not a new canonical type mapping.

Expected behavior: A header containing only macros cannot provide a typedef used by those macros. Generation should fail with an unresolved-type diagnostic unless the real declaration header is included or supplied as an input. Once supplied, the constant dependency closure from item 13 should retain the required typedef without relying on a hand-authored seed.

Recommendation: Keep the failure for genuinely missing declarations. Improve the diagnostic if possible, but do not invent a built-in type solely from a macro header's name.

16. Keep wrapper, response-file, language-standard, and output-lifecycle changes outside this issue's library work.

Status: No windows-rs change established by those cases.

The response-file/SAL diagnostic checks, C++ standard forwarding, empty-output handling, and stale-output cleanup pass against both the baseline and patched windows-rs libraries. They validate surrounding tooling behavior rather than a regression in windows-bindgen, windows-clang, or windows-rdl.

Recommendation: Track those changes in their owning tools. Do not use them as evidence that the proposed windows-rs patch is required.