Update proposal doc with __attribute__((flag_enum)) approach

Replace the [[clang::annotate('w32m:flags')]] and DEFINE_ENUM_FLAG_OPERATORS
references with the validated __attribute__((flag_enum)) approach that
flows through the AST via Win32MetadataScraper detection.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jevansaks

docs/copilot/plans/enum-remapping-proposal.md

@@ -58,12 +58,11 @@ enums.
 ```cpp
 #ifdef _WIN32METADATA_
 
-enum SET_THEME_APP_PROPERTIES_FLAGS : unsigned int {
+enum __attribute__((flag_enum)) SET_THEME_APP_PROPERTIES_FLAGS : unsigned int {
     ALLOW_NONCLIENT  = STAP_ALLOW_NONCLIENT,
     ALLOW_CONTROLS   = STAP_ALLOW_CONTROLS,
     ALLOW_WEBCONTENT = STAP_ALLOW_WEBCONTENT,
 };
-DEFINE_ENUM_FLAG_OPERATORS(SET_THEME_APP_PROPERTIES_FLAGS)
 
 #else
 #define SET_THEME_APP_PROPERTIES_FLAGS DWORD
@@ -91,8 +90,11 @@ Key points:
 - `#else #define NAME DWORD` — the enum name becomes a DWORD macro for normal
   compilation, allowing unconditional use in function signatures
 - Modern C++ syntax — `enum NAME : base_type`, no `typedef` needed
-- `DEFINE_ENUM_FLAG_OPERATORS(NAME)` — existing SDK convention for flags enums,
-  already detected by the ConstantsScraper (no new annotation needed)
+- `__attribute__((flag_enum))` — Clang's standard attribute for bitmask enums
+  (see [Clang Attribute Reference](https://clang.llvm.org/docs/AttributeReference.html#flag-enum)).
+  The Win32MetadataScraper detects this attribute in the AST and injects
+  `[Flags]` via PInvokeGenerator's `WithAttributes` mechanism — fully through the
+  AST, no text parsing or sidecar RSP entries needed
 - Member values reference the original `#define` macros directly — the preprocessor
   computes the actual values
 
@@ -104,11 +106,15 @@ All scenarios were tested with ClangSharp v17 and v18 (test files in
 | Scenario | ClangSharp v17 | ClangSharp v18 |
 |---|---|---|
 | Enum declarations | ✅ | ✅ |
-| `[[clang::annotate("w32m:flags")]]` | ❌ (dropped) | ✅ `[NativeAnnotation]` |
+| `__attribute__((flag_enum))` → `[Flags]` | ✅ (via tooling) | ✅ (via tooling) |
 | C++11 enum base types (`: unsigned char`, etc.) | ✅ `enum X : byte` | ✅ |
 | Signed overflow (`(int)0xFFFFFFFF`) | ✅ auto `unchecked()` | ✅ |
 | Function params get enum type | ✅ | ✅ |
-| `#pragma clang attribute push` for flags | ❌ (dropped) | ✅ |
+
+Note: `__attribute__((flag_enum))` is present in the Clang AST on both v17 and v18
+(as `CX_AttrKind_FlagEnum`), but ClangSharp's PInvokeGenerator doesn't handle it
+natively. The Win32MetadataScraper detects it during the AST walk and passes it to
+PInvokeGenerator via `WithAttributes`, which works on all versions.
 
 ### Three member patterns
 
@@ -134,7 +140,8 @@ Use `push_macro`/`undef`/`pop_macro` to suppress macro expansion inside the enum
 #undef FILE_ATTRIBUTE_READONLY
 #undef FILE_ATTRIBUTE_HIDDEN
 
-enum [[clang::annotate("w32m:flags")]] FILE_ATTRIBUTE_FLAGS : unsigned int {
+```cpp
+enum __attribute__((flag_enum)) FILE_ATTRIBUTE_FLAGS : unsigned int {
     FILE_ATTRIBUTE_READONLY = 0x00000001,
     FILE_ATTRIBUTE_HIDDEN   = 0x00000002,
 };
@@ -159,28 +166,44 @@ enum OBJECT_IDENTIFIER : int {
 
 ### Flags annotation
 
-There is no C++ standard `[[bitmask]]` attribute. We define a SAL-like macro:
+Clang provides `__attribute__((flag_enum))` to mark enums as bitmask types (see
+[Clang Attribute Reference](https://clang.llvm.org/docs/AttributeReference.html#flag-enum)).
+There is no C++ standard equivalent — no `[[bitmask]]` attribute exists even in C++26.
 
-```cpp
-// In win32metadata.h
-#ifdef _WIN32METADATA_
-  #define _Enum_flags_ [[clang::annotate("w32m:flags")]]
-#else
-  #define _Enum_flags_
-#endif
+The Win32MetadataScraper detects `flag_enum` during the AST walk by checking
+`EnumDecl.Attrs` for `CX_AttrKind_FlagEnum`. Discovered flag enums are injected into
+PInvokeGenerator's `WithAttributes` as `[Flags]`:
+
+```csharp
+// In RemapDiscovery.WalkDecl:
+if (decl is EnumDecl enumDecl && enumDecl.HasAttrs)
+{
+    foreach (var attr in enumDecl.Attrs)
+    {
+        if (attr.Kind == CX_AttrKind_FlagEnum)
+            result.FlagEnumNames.Add(enumDecl.Name);
+    }
+}
+
+// In Program.cs, before creating PInvokeGenerator config:
+foreach (var flagEnum in discovery.FlagEnumNames)
+    withAttributes[flagEnum] = new List<string> { "Flags" };
 ```
 
-Usage:
+Usage in headers:
 ```cpp
-enum _Enum_flags_ FILE_ATTRIBUTE_FLAGS : unsigned int { ... };
+enum __attribute__((flag_enum)) FILE_ATTRIBUTE_FLAGS : unsigned int { ... };
 ```
 
-On v18+, this emits `[NativeAnnotation("w32m:flags")]` on the enum, which the emitter
-converts to `[Flags]`.
+This approach:
+- Flows entirely through the Clang AST — no text parsing
+- Works on both ClangSharp v17 and v18
+- Requires no sidecar RSP entries
+- Uses a standard Clang attribute rather than a custom annotation
 
-As a fallback, the existing `DEFINE_ENUM_FLAG_OPERATORS(FOO)` macro is already detected
-by the ConstantsScraper (text-level regex) and written to `enumsMakeFlags.generated.rsp`.
-Both mechanisms can coexist.
+For SDK headers that already use `DEFINE_ENUM_FLAG_OPERATORS(FOO)`, the existing
+ConstantsScraper text-detection path (`enumsMakeFlags.generated.rsp`) continues to
+work as a fallback.
 
 ### Underlying types
 
@@ -307,7 +330,7 @@ Every field in enums.json maps to a header construct:
 | enums.json field | Header equivalent |
 |---|---|
 | `name` | `enum NAME` |
-| `flags` | `_Enum_flags_` / `[[clang::annotate("w32m:flags")]]` |
+| `flags` | `__attribute__((flag_enum))` on enum |
 | `type` | C++ enum base (`: unsigned int`, `: unsigned char`, etc.) |
 | `members[].name` | Enum member identifier |
 | `members[].value` | Literal value or `#define` macro reference |
@@ -321,10 +344,9 @@ Every field in enums.json maps to a header construct:
 
 ## Implementation steps
 
-1. **Upgrade ClangSharp to v18+** — required for `[[clang::annotate]]` on enums
-2. **Build a migration tool** — converts each `enums.json` entry into a conditional
-   enum declaration block
-3. **Create overlay headers** with the generated declarations
+1. **Build a migration tool** — converts each `enums.json` entry into a conditional
+   enum declaration block with `__attribute__((flag_enum))` where appropriate
+2. **Create overlay headers** with the generated declarations
 4. **Add `_Enum_type_()` usage annotations** — from `enums.json` `uses` array
 5. **Validate winmd equivalence** — compare winmd output before/after
 6. **Remove `enums.json`** and simplify ConstantsScraper