[clang] [clang] Support header shadowing diagnostics in Clang header search (PR #162491)

[Tom Honermann via cfe-commits]

tahonermann wrote:

I haven't taken the time to fully comprehend the source code changes and I'm not fully clear on the intent for this diagnostic. Additional test cases might help to make it clear. For example, is the intent that a diagnostic would be issued for a case like this?
```
$ cat t.c
#include "t.h"

$ cat include1/t.h
#warning include1/t.h included!

$ cat include2/t.h
#warning include2/t.h included!

$ clang -c -Iinclude1 -Iinclude2 t.c
```

I would not be in favor of that example being diagnosed because I think it would interfere with too much intentional use of `#include_next`.

If the intent is to only issue a diagnostic if a header file is included via double quotes and is found relative to the including file and is also found in a different location via the header search path, I think that might make sense (this is what your test case exercises). Use of `#include_next` in such cases seems somewhat unlikely (if you are using `#include_next`, you probably want to be relying completely on header search path ordering). I'm not sure if there is a good way to validate how much existing code might be impacted though.

This change should include a release note in `clang/docs/ReleaseNotes.rst` that explains the circumstances under which the diagnostic is issued and how to disable it.

I wonder if the existing `ext_pp_include_search_ms` diagnostic should be incorporated into this one. Technically, that shouldn't be an extension warning since header file resolution isn't defined by the C or C++ standards.

https://github.com/llvm/llvm-project/pull/162491