From 8fdfc620d0c8387fd1e939da76ab89eabaf74412 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 3 Jul 2026 14:34:20 +0000
Subject: [PATCH 1/8] Initial plan


From c55a1bbd129fce2b38a916ba3ff57e7cfdf4915d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 3 Jul 2026 14:45:30 +0000
Subject: [PATCH 2/8] Add IWYU include checks

Co-authored-by: achamayou <4016369+achamayou@users.noreply.github.com>
---
 CMakeLists.txt         | 37 +++++++++++++++++++++++++++++++++++++
 scripts/ci-checks.sh   |  1 +
 scripts/iwyu-checks.sh | 28 ++++++++++++++++++++++++++++
 scripts/setup-ci.sh    |  1 +
 scripts/setup-dev.sh   |  1 +
 5 files changed, 68 insertions(+)
 create mode 100755 scripts/iwyu-checks.sh

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 692077e6465..c579e5918e8 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -115,6 +115,13 @@ option(USE_SNMALLOC "Link against snmalloc" ON)
 include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/snmalloc.cmake)
 
 option(CLANG_TIDY "Run clang-tidy on the codebase" OFF)
+option(INCLUDE_WHAT_YOU_USE "Run include-what-you-use on the codebase" OFF)
+set(
+  IWYU_MAPPING_DIR
+  ""
+  CACHE PATH
+  "Directory containing include-what-you-use mapping files"
+)
 
 option(
   GLIBCXX_DEBUG
@@ -134,6 +141,36 @@ if(CLANG_TIDY)
   message(STATUS "Using clang-tidy from: ${CLANG_TIDY_EXE}")
 endif()
 
+if(INCLUDE_WHAT_YOU_USE)
+  find_program(IWYU_EXE NAMES "include-what-you-use" "iwyu")
+  if(NOT IWYU_EXE)
+    message(FATAL_ERROR "include-what-you-use requested but not found")
+  endif()
+
+  set(IWYU_COMMAND "${IWYU_EXE}" "-w" "-Xiwyu" "--error=1")
+  get_filename_component(IWYU_BIN_DIR "${IWYU_EXE}" DIRECTORY)
+  set(
+    IWYU_MAPPING_DIRS
+    "${IWYU_MAPPING_DIR}"
+    "${IWYU_BIN_DIR}/../share/include-what-you-use"
+    "/usr/local/share/include-what-you-use"
+    "/usr/share/include-what-you-use"
+  )
+  foreach(IWYU_MAPPING_BASE ${IWYU_MAPPING_DIRS})
+    if(EXISTS "${IWYU_MAPPING_BASE}/libcxx.imp")
+      list(
+        APPEND IWYU_COMMAND
+        "-Xiwyu"
+        "--mapping_file=${IWYU_MAPPING_BASE}/libcxx.imp"
+      )
+      break()
+    endif()
+  endforeach()
+
+  set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE ${IWYU_COMMAND})
+  message(STATUS "Using include-what-you-use from: ${IWYU_EXE}")
+endif()
+
 if(SAN OR TSAN)
   find_program(LLVM_SYMBOLIZER NAMES "llvm-symbolizer")
   message(STATUS "Using llvm symbolizer: ${LLVM_SYMBOLIZER}")
diff --git a/scripts/ci-checks.sh b/scripts/ci-checks.sh
index f3036923655..da34824988b 100755
--- a/scripts/ci-checks.sh
+++ b/scripts/ci-checks.sh
@@ -39,6 +39,7 @@ CHECKS=(
   "Shell scripts:shellcheck-checks.sh"
   "TODOs:todo-checks.sh"
   "Includes:includes-checks.sh"
+  "Include what you use:iwyu-checks.sh"
   "Release notes:release-notes-checks.sh"
   "Non-ASCII characters:ascii-checks.sh"
   "C/C++ format:cpp-format-checks.sh"
diff --git a/scripts/iwyu-checks.sh b/scripts/iwyu-checks.sh
new file mode 100755
index 00000000000..a4f9a81f0cd
--- /dev/null
+++ b/scripts/iwyu-checks.sh
@@ -0,0 +1,28 @@
+#!/bin/bash
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the Apache 2.0 License.
+
+# Checks C/C++ include hygiene with include-what-you-use.
+# Pass -f for interface consistency, but no auto-fix is available.
+
+set -uo pipefail
+
+if [ "${1:-}" == "-f" ]; then
+  echo "include-what-you-use checks do not support auto-fix"
+fi
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+ROOT_DIR=$( dirname "$SCRIPT_DIR" )
+BUILD_DIR=${CCF_IWYU_BUILD_DIR:-"$ROOT_DIR/build-iwyu"}
+NPROC=$(nproc 2>/dev/null || echo 4)
+
+cmake \
+  -S "$ROOT_DIR" \
+  -B "$BUILD_DIR" \
+  -GNinja \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DBUILD_END_TO_END_TESTS=OFF \
+  -DCOMPILE_TARGET=virtual \
+  -DINCLUDE_WHAT_YOU_USE=ON
+
+cmake --build "$BUILD_DIR" --parallel "$NPROC"
diff --git a/scripts/setup-ci.sh b/scripts/setup-ci.sh
index 3f32d60846e..64279327df0 100755
--- a/scripts/setup-ci.sh
+++ b/scripts/setup-ci.sh
@@ -54,6 +54,7 @@ install_build_dependencies() {
     tdnf --snapshottime=$SOURCE_DATE_EPOCH -y install  \
         build-essential  \
         clang  \
+        include-what-you-use \
         cmake  \
         ninja-build  \
         which  \
diff --git a/scripts/setup-dev.sh b/scripts/setup-dev.sh
index c2533de03fd..e83cf37dd41 100755
--- a/scripts/setup-dev.sh
+++ b/scripts/setup-dev.sh
@@ -40,6 +40,7 @@ retry() {
 install_dev_dependencies() {
     tdnf -y install  \
         clang-tools-extra  \
+        include-what-you-use \
         python-pip \
         jq \
         tar \

From a149e44698f29dbafbabe9fdd5f3c667af7b7ea4 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 3 Jul 2026 14:46:34 +0000
Subject: [PATCH 3/8] Address IWYU script review feedback

Co-authored-by: achamayou <4016369+achamayou@users.noreply.github.com>
---
 CMakeLists.txt         | 1 +
 scripts/iwyu-checks.sh | 3 ++-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index c579e5918e8..20668c24926 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -147,6 +147,7 @@ if(INCLUDE_WHAT_YOU_USE)
     message(FATAL_ERROR "include-what-you-use requested but not found")
   endif()
 
+  # Keep CI output focused on IWYU findings, and fail on any suggested change.
   set(IWYU_COMMAND "${IWYU_EXE}" "-w" "-Xiwyu" "--error=1")
   get_filename_component(IWYU_BIN_DIR "${IWYU_EXE}" DIRECTORY)
   set(
diff --git a/scripts/iwyu-checks.sh b/scripts/iwyu-checks.sh
index a4f9a81f0cd..bff1a329c44 100755
--- a/scripts/iwyu-checks.sh
+++ b/scripts/iwyu-checks.sh
@@ -5,7 +5,7 @@
 # Checks C/C++ include hygiene with include-what-you-use.
 # Pass -f for interface consistency, but no auto-fix is available.
 
-set -uo pipefail
+set -euo pipefail
 
 if [ "${1:-}" == "-f" ]; then
   echo "include-what-you-use checks do not support auto-fix"
@@ -26,3 +26,4 @@ cmake \
   -DINCLUDE_WHAT_YOU_USE=ON
 
 cmake --build "$BUILD_DIR" --parallel "$NPROC"
+echo "include-what-you-use checks passed"

From 365eff033aedcfef5eb05ba3b19076863be60949 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 3 Jul 2026 14:47:27 +0000
Subject: [PATCH 4/8] Clarify IWYU check behavior

Co-authored-by: achamayou <4016369+achamayou@users.noreply.github.com>
---
 CMakeLists.txt         | 3 ++-
 scripts/iwyu-checks.sh | 4 ----
 2 files changed, 2 insertions(+), 5 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 20668c24926..09bf71be7af 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -147,7 +147,8 @@ if(INCLUDE_WHAT_YOU_USE)
     message(FATAL_ERROR "include-what-you-use requested but not found")
   endif()
 
-  # Keep CI output focused on IWYU findings, and fail on any suggested change.
+  # -w suppresses compiler warnings so CI logs focus on IWYU findings.
+  # --error=1 makes any IWYU suggestion fail the build and enforce direct includes.
   set(IWYU_COMMAND "${IWYU_EXE}" "-w" "-Xiwyu" "--error=1")
   get_filename_component(IWYU_BIN_DIR "${IWYU_EXE}" DIRECTORY)
   set(
diff --git a/scripts/iwyu-checks.sh b/scripts/iwyu-checks.sh
index bff1a329c44..8d1a55e7a39 100755
--- a/scripts/iwyu-checks.sh
+++ b/scripts/iwyu-checks.sh
@@ -7,10 +7,6 @@
 
 set -euo pipefail
 
-if [ "${1:-}" == "-f" ]; then
-  echo "include-what-you-use checks do not support auto-fix"
-fi
-
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
 ROOT_DIR=$( dirname "$SCRIPT_DIR" )
 BUILD_DIR=${CCF_IWYU_BUILD_DIR:-"$ROOT_DIR/build-iwyu"}

From ae8832052767fe8b736925f6e104eafaef759af1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 3 Jul 2026 14:48:30 +0000
Subject: [PATCH 5/8] Move IWYU CMake setup to module

Co-authored-by: achamayou <4016369+achamayou@users.noreply.github.com>
---
 CMakeLists.txt         | 40 +-------------------------------------
 cmake/iwyu.cmake       | 44 ++++++++++++++++++++++++++++++++++++++++++
 scripts/iwyu-checks.sh | 13 ++++++++++++-
 3 files changed, 57 insertions(+), 40 deletions(-)
 create mode 100644 cmake/iwyu.cmake

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 09bf71be7af..bfe68b3144c 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -115,13 +115,6 @@ option(USE_SNMALLOC "Link against snmalloc" ON)
 include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/snmalloc.cmake)
 
 option(CLANG_TIDY "Run clang-tidy on the codebase" OFF)
-option(INCLUDE_WHAT_YOU_USE "Run include-what-you-use on the codebase" OFF)
-set(
-  IWYU_MAPPING_DIR
-  ""
-  CACHE PATH
-  "Directory containing include-what-you-use mapping files"
-)
 
 option(
   GLIBCXX_DEBUG
@@ -140,38 +133,7 @@ if(CLANG_TIDY)
   )
   message(STATUS "Using clang-tidy from: ${CLANG_TIDY_EXE}")
 endif()
-
-if(INCLUDE_WHAT_YOU_USE)
-  find_program(IWYU_EXE NAMES "include-what-you-use" "iwyu")
-  if(NOT IWYU_EXE)
-    message(FATAL_ERROR "include-what-you-use requested but not found")
-  endif()
-
-  # -w suppresses compiler warnings so CI logs focus on IWYU findings.
-  # --error=1 makes any IWYU suggestion fail the build and enforce direct includes.
-  set(IWYU_COMMAND "${IWYU_EXE}" "-w" "-Xiwyu" "--error=1")
-  get_filename_component(IWYU_BIN_DIR "${IWYU_EXE}" DIRECTORY)
-  set(
-    IWYU_MAPPING_DIRS
-    "${IWYU_MAPPING_DIR}"
-    "${IWYU_BIN_DIR}/../share/include-what-you-use"
-    "/usr/local/share/include-what-you-use"
-    "/usr/share/include-what-you-use"
-  )
-  foreach(IWYU_MAPPING_BASE ${IWYU_MAPPING_DIRS})
-    if(EXISTS "${IWYU_MAPPING_BASE}/libcxx.imp")
-      list(
-        APPEND IWYU_COMMAND
-        "-Xiwyu"
-        "--mapping_file=${IWYU_MAPPING_BASE}/libcxx.imp"
-      )
-      break()
-    endif()
-  endforeach()
-
-  set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE ${IWYU_COMMAND})
-  message(STATUS "Using include-what-you-use from: ${IWYU_EXE}")
-endif()
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/iwyu.cmake)
 
 if(SAN OR TSAN)
   find_program(LLVM_SYMBOLIZER NAMES "llvm-symbolizer")
diff --git a/cmake/iwyu.cmake b/cmake/iwyu.cmake
new file mode 100644
index 00000000000..3232ac621a3
--- /dev/null
+++ b/cmake/iwyu.cmake
@@ -0,0 +1,44 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the Apache 2.0 License.
+
+option(INCLUDE_WHAT_YOU_USE "Run include-what-you-use on the codebase" OFF)
+set(
+  IWYU_MAPPING_DIR
+  ""
+  CACHE PATH
+  "Directory containing include-what-you-use mapping files"
+)
+
+if(NOT INCLUDE_WHAT_YOU_USE)
+  return()
+endif()
+
+find_program(IWYU_EXE NAMES "include-what-you-use" "iwyu")
+if(NOT IWYU_EXE)
+  message(FATAL_ERROR "include-what-you-use requested but not found")
+endif()
+
+# -w suppresses compiler warnings so CI logs focus on IWYU findings.
+# --error=1 makes any IWYU suggestion fail the build and enforce direct includes.
+set(IWYU_COMMAND "${IWYU_EXE}" "-w" "-Xiwyu" "--error=1")
+get_filename_component(IWYU_BIN_DIR "${IWYU_EXE}" DIRECTORY)
+set(
+  IWYU_MAPPING_DIRS
+  "${IWYU_MAPPING_DIR}"
+  "${IWYU_BIN_DIR}/../share/include-what-you-use"
+  "/usr/local/share/include-what-you-use"
+  "/usr/share/include-what-you-use"
+)
+foreach(IWYU_MAPPING_BASE ${IWYU_MAPPING_DIRS})
+  if(EXISTS "${IWYU_MAPPING_BASE}/libcxx.imp")
+    list(
+      APPEND IWYU_COMMAND
+      "-Xiwyu"
+      "--mapping_file=${IWYU_MAPPING_BASE}/libcxx.imp"
+    )
+    break()
+  endif()
+endforeach()
+
+set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE ${IWYU_COMMAND})
+message(STATUS "Using include-what-you-use from: ${IWYU_EXE}")
diff --git a/scripts/iwyu-checks.sh b/scripts/iwyu-checks.sh
index 8d1a55e7a39..3e54b4eeb73 100755
--- a/scripts/iwyu-checks.sh
+++ b/scripts/iwyu-checks.sh
@@ -5,7 +5,18 @@
 # Checks C/C++ include hygiene with include-what-you-use.
 # Pass -f for interface consistency, but no auto-fix is available.
 
-set -euo pipefail
+set -e
+set -u
+set -o pipefail
+
+if [ "${1:-}" == "-f" ]; then
+  shift
+fi
+
+if [ "$#" -ne 0 ]; then
+  echo "Usage: $0 [-f]"
+  exit 1
+fi
 
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
 ROOT_DIR=$( dirname "$SCRIPT_DIR" )

From 25b82fc405ad234fa9037dc24ca6b014577b6f82 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 3 Jul 2026 14:49:19 +0000
Subject: [PATCH 6/8] Tidy IWYU option handling

Co-authored-by: achamayou <4016369+achamayou@users.noreply.github.com>
---
 cmake/iwyu.cmake       | 6 +++---
 scripts/iwyu-checks.sh | 8 +++++++-
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/cmake/iwyu.cmake b/cmake/iwyu.cmake
index 3232ac621a3..0a2ae4cad7b 100644
--- a/cmake/iwyu.cmake
+++ b/cmake/iwyu.cmake
@@ -29,12 +29,12 @@ set(
   "/usr/local/share/include-what-you-use"
   "/usr/share/include-what-you-use"
 )
-foreach(IWYU_MAPPING_BASE ${IWYU_MAPPING_DIRS})
-  if(EXISTS "${IWYU_MAPPING_BASE}/libcxx.imp")
+foreach(IWYU_MAPPING_CANDIDATE_DIR ${IWYU_MAPPING_DIRS})
+  if(EXISTS "${IWYU_MAPPING_CANDIDATE_DIR}/libcxx.imp")
     list(
       APPEND IWYU_COMMAND
       "-Xiwyu"
-      "--mapping_file=${IWYU_MAPPING_BASE}/libcxx.imp"
+      "--mapping_file=${IWYU_MAPPING_CANDIDATE_DIR}/libcxx.imp"
     )
     break()
   endif()
diff --git a/scripts/iwyu-checks.sh b/scripts/iwyu-checks.sh
index 3e54b4eeb73..6f44a554283 100755
--- a/scripts/iwyu-checks.sh
+++ b/scripts/iwyu-checks.sh
@@ -9,7 +9,9 @@ set -e
 set -u
 set -o pipefail
 
-if [ "${1:-}" == "-f" ]; then
+FIX=0
+if [ "${1:-}" = "-f" ]; then
+  FIX=1
   shift
 fi
 
@@ -18,6 +20,10 @@ if [ "$#" -ne 0 ]; then
   exit 1
 fi
 
+if [ "$FIX" -ne 0 ]; then
+  echo "include-what-you-use checks do not support auto-fix; running checks only"
+fi
+
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
 ROOT_DIR=$( dirname "$SCRIPT_DIR" )
 BUILD_DIR=${CCF_IWYU_BUILD_DIR:-"$ROOT_DIR/build-iwyu"}

From 96106f5c4830e8bae12b0188d301bff1fc98cf71 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 3 Jul 2026 14:50:08 +0000
Subject: [PATCH 7/8] Warn when IWYU mapping is missing

Co-authored-by: achamayou <4016369+achamayou@users.noreply.github.com>
---
 cmake/iwyu.cmake | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/cmake/iwyu.cmake b/cmake/iwyu.cmake
index 0a2ae4cad7b..d554e0bb604 100644
--- a/cmake/iwyu.cmake
+++ b/cmake/iwyu.cmake
@@ -29,6 +29,7 @@ set(
   "/usr/local/share/include-what-you-use"
   "/usr/share/include-what-you-use"
 )
+set(IWYU_LIBCXX_MAPPING_FOUND OFF)
 foreach(IWYU_MAPPING_CANDIDATE_DIR ${IWYU_MAPPING_DIRS})
   if(EXISTS "${IWYU_MAPPING_CANDIDATE_DIR}/libcxx.imp")
     list(
@@ -36,9 +37,13 @@ foreach(IWYU_MAPPING_CANDIDATE_DIR ${IWYU_MAPPING_DIRS})
       "-Xiwyu"
       "--mapping_file=${IWYU_MAPPING_CANDIDATE_DIR}/libcxx.imp"
     )
+    set(IWYU_LIBCXX_MAPPING_FOUND ON)
     break()
   endif()
 endforeach()
+if(NOT IWYU_LIBCXX_MAPPING_FOUND)
+  message(WARNING "include-what-you-use libcxx.imp mapping file not found")
+endif()
 
 set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE ${IWYU_COMMAND})
 message(STATUS "Using include-what-you-use from: ${IWYU_EXE}")

From 5bb087367abdae2b10c2a623b1f1b6e115f200f2 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 3 Jul 2026 14:50:48 +0000
Subject: [PATCH 8/8] Document IWYU check flags

Co-authored-by: achamayou <4016369+achamayou@users.noreply.github.com>
---
 cmake/iwyu.cmake       | 3 ++-
 scripts/iwyu-checks.sh | 2 ++
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/cmake/iwyu.cmake b/cmake/iwyu.cmake
index d554e0bb604..52ac969f50b 100644
--- a/cmake/iwyu.cmake
+++ b/cmake/iwyu.cmake
@@ -19,7 +19,8 @@ if(NOT IWYU_EXE)
 endif()
 
 # -w suppresses compiler warnings so CI logs focus on IWYU findings.
-# --error=1 makes any IWYU suggestion fail the build and enforce direct includes.
+# --error=1 selects IWYU's standard non-zero failure code, so any suggestion
+# fails the build and enforces direct includes.
 set(IWYU_COMMAND "${IWYU_EXE}" "-w" "-Xiwyu" "--error=1")
 get_filename_component(IWYU_BIN_DIR "${IWYU_EXE}" DIRECTORY)
 set(
diff --git a/scripts/iwyu-checks.sh b/scripts/iwyu-checks.sh
index 6f44a554283..d2198c6b12c 100755
--- a/scripts/iwyu-checks.sh
+++ b/scripts/iwyu-checks.sh
@@ -11,6 +11,8 @@ set -o pipefail
 
 FIX=0
 if [ "${1:-}" = "-f" ]; then
+  # ci-checks.sh passes -f to every check; IWYU has no safe auto-fix mode, so
+  # this script treats it as a request to run the check normally.
   FIX=1
   shift
 fi