[Syntax] Fix macro-arg handling in TokenBuffer::spelledForExpanded

[sammccall]

Summary

A few cases were not handled correctly. Notably:

#define ID(X) X
#define HIDE a ID(b)
HIDE

spelledForExpanded() would claim HIDE is an equivalent range of the 'b' it
contains, despite the fact that HIDE also covers 'a'.

While trying to fix this bug, I found findCommonRangeForMacroArgs hard
to understand (both the implementation and how it's used in spelledForExpanded).
It relies on details of the SourceLocation graph that are IMO fairly obscure.
So I've added/revised quite a lot of comments and made some naming tweaks.

Fixes https://github.com/clangd/clangd/issues/1289

[kadircet]

thanks, lgtm!

clang/lib/Tooling/Syntax/Tokens.cpp

82

main file here and in rest of the comments feels a little confusing. maybe rename FID to MainFile (which is still somewhat confusing) or call it SpelledFID and also change the mentions of main file in comments to spelling file (or similar). (assuming i am not misunderstanding something)

102

s/a/A/

137

nit: s/ID/ID2

475

nit: drop the check for LastMapping

487

can we also have a test like:

#define ID(X) X
#define BAR ID(1)
BAR

to make sure we can select the object-like macro when the whole contents are matched (it's probably also worth mentioning in the public documentation)

clang/unittests/Tooling/Syntax/TokensTest.cpp

760

"y" is only mentioned once in the main-file no need for matching something wider