[Intermediate]: Integrate `include-what-you-use` into CMake Build System

## 🧩 Intermediate Friendly

This issue is a good fit for contributors who are already familiar with the Hiero C++ SDK and feel comfortable navigating the codebase.

Intermediate Issues often involve:
- Exploring existing implementations
- Understanding how different components work together
- Making thoughtful changes that follow established patterns

The goal is to support deeper problem-solving while keeping the task clear, focused, and enjoyable to work on.

---

## 🐞 Problem Description

The codebase would benefit from systematic `#include` analysis to identify:
- **Unnecessary includes** - headers that are included but not used
- **Missing direct includes** - relying on transitive includes from other headers
- **Forward declaration opportunities** - where a full include can be replaced with a forward declaration

Currently, include hygiene is maintained manually with no tooling support.

---

## 💡 Expected Outcome

Integrate [include-what-you-use (IWYU)](https://include-what-you-use.org/) into the CMake build system so developers can run include analysis on demand.

**Goals:**
1. CMake option to enable IWYU during builds
2. Ability to run IWYU analysis and see suggestions
3. Documentation for how to use the integration

**Non-goals:**
- Enforcing IWYU in CI (can be added later)
- Fixing all existing include issues in this PR

---

## 🧠 Implementation Notes

**CMake Integration:**

Add IWYU support to `CMakeLists.txt`:

```cmake
option(ENABLE_IWYU "Enable include-what-you-use analysis" OFF)

if(ENABLE_IWYU)
find_program(IWYU_PROGRAM NAMES include-what-you-use iwyu)
if(IWYU_PROGRAM)
message(STATUS "Found include-what-you-use: ${IWYU_PROGRAM}")
set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE
${IWYU_PROGRAM}
-Xiwyu --mapping_file=${CMAKE_SOURCE_DIR}/iwyu.imp
)
else()
message(WARNING "include-what-you-use not found, IWYU analysis disabled")
endif()
endif()
```

**Mapping File:**

IWYU may need a mapping file (`iwyu.imp`) to handle:
- Project-specific header mappings
- Third-party library mappings (protobuf, gRPC, etc.)

Example mapping file:

```yaml
[
# Map protobuf internal headers to main header
{ include: ["@", "private", "", "public"] },

# Keep certain includes that IWYU might want to remove
{ include: ["", "private", "", "public"] }
]
```

**Existing clang-format compatibility:**

The repo's `.clang-format` already supports IWYU pragmas:

```yaml
CommentPragmas: "^ IWYU pragma:"
```

This means IWYU pragma comments like these will be preserved:
```cpp
#include "SomeHeader.h" // IWYU pragma: keep
class ForwardDeclared; // IWYU pragma: export
```

**Usage:**

```bash
# Configure with IWYU enabled
cmake --preset linux-x64-debug -DENABLE_IWYU=ON

# Build (IWYU runs automatically and outputs suggestions)
cmake --build --preset linux-x64-debug 2>&1 | tee iwyu-output.txt
```

---

## 📂 Relevant Files

**Build configuration:**
- `CMakeLists.txt` - main CMake configuration

**Include organization:**
- `.clang-format` - already has `CommentPragmas: "^ IWYU pragma:"` support

**Source files:**
- `src/sdk/main/include/` - public headers
- `src/sdk/main/src/` - implementation files

---

## ✅ Acceptance Criteria

- [ ] CMake option `ENABLE_IWYU` added
- [ ] IWYU runs during build when enabled
- [ ] Mapping file created for project-specific rules
- [ ] Third-party headers handled appropriately (protobuf, gRPC, etc.)
- [ ] Documentation added for using IWYU
- [ ] Build still works normally when IWYU is disabled

---

## 📋 Contribution Guide

- [ ] Comment `/assign` to request the issue
- [ ] Wait for assignment
- [ ] Fork the repository and create a branch
- [ ] Install include-what-you-use locally for testing
- [ ] Implement CMake integration
- [ ] Create mapping file as needed
- [ ] Test on the codebase
- [ ] Sign each commit using `-s -S`
- [ ] Push your branch and open a pull request

Read [Workflow Guide](docs/training/workflow.md) for step-by-step workflow guidance.
Read [README.md](README.md) for setup instructions.

**Pull requests cannot be merged without `S` and `s` signed commits.**
See the [Signing Guide](docs/training/signing.md).

---

## 📚 Additional Context or Resources

**References:**
- [include-what-you-use](https://include-what-you-use.org/)
- [IWYU CMake integration](https://cmake.org/cmake/help/latest/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.html)
- [Stack Overflow guide](https://stackoverflow.com/questions/30951492/how-to-use-the-tool-include-what-you-use-together-with-cmake-to-detect-unused-he)
- [IWYU Mappings documentation](https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUMappings.md)

**Installing IWYU:**
```bash
# Ubuntu/Debian
sudo apt-get install iwyu

# macOS (via Homebrew)
brew install include-what-you-use

# From source
# See: https://github.com/include-what-you-use/include-what-you-use
```

If you have questions, the community is happy to help:

https://discord.com/channels/905194001349627914/1337424839761465364