[clang] [clang-format] Add FilesBeforeFolders option to SortIncludes (PR #208954)

[Savvas Shiakas via cfe-commits]

Shiakaron wrote:

Ok so, here is my example to prove that `FilesBeforeFolders` actually gives a unique ordering which cannot be achieved with `IncludeCategories`. Consider these two includes:

```
#include "net/http/client.h"
#include "net/socket.h"
```

`FilesBeforeFolders=true` would order them such that `"net/socket.h"` is before `"net/http/client.h"` (great).

Now consider the provided IncludeCategories (ignoring the relative path bits):

```
  - Regex:           '^".*/'
    Priority:        10
    SortPriority:    11
    CaseSensitive:   false
  - Regex:           '^".*'
    Priority:        10
    SortPriority:    10
    CaseSensitive:   false
```

Because 'h' < 's' alphabetically, `"net/http/client.h"` would be before `"net/socket.h"` (not what we want). This is because `^".*/`  is a flat alphabetical sort over a tree. 

Now, as far as I understand, you are suggesting to add more patterns to deal with the extra depth in the project, which will indeed solve it for this minimal example - and this is what I have done in the config I have provided. However, doing that breaks the inter-directory grouping the moment two top-level directories both contain files and subdirectories. 

Now consider the following includes:

```
#include "net/http/client.h"
#include "net/socket.h"
#include "io/file/reader.h"
#include "io/stream.h"
```

With `FilesBeforeFolders=true` we would get the following order:

```
#include "io/stream.h"
#include "io/file/reader.h"
#include "net/socket.h"
#include "net/http/client.h"
```

whereas with our new `IncludeCategories` we would get the following order:

```
#include "io/stream.h"
#include "net/socket.h"
#include "io/file/reader.h"
#include "net/http/client.h"
```

To achieve the same ordering we would instead need to enumerate every directory by name which, I believe, is not a reasonable config for anyone to be expected to have. I hope this is enough to convince you @HazardyKnusperkeks 

Thank you for the time you have spent on this so far.

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