Draft for sandcastle gallery pattern fix

[javagl]

This is a draft, not supposed to be merged (in its current form). It is just intended for showing how to resolve #12951

@jjspace This was another /-vs\-issue. All the path handling on Windows has to use \, and getting that sorted out with the mix of paths and URLs is already tricky enough. But then, globby comes along and casually says that it only accepts / in its patterns, so ... at this point, all the paths that have previously been carefully treated as such, with \'s everywhere, have to undergo some \-to-/-replacement again.

The solution here is a draft, with debug logs and ... comments. The debug logs could be removed.

The globby documentation talks about posix.join for joining paths, but I'm not sure what's the best solution here, so I just used replace, because I felt like...

¯\_(ツ)_/¯ or
¯/_(ツ)_/¯ or
¯\_(ツ)_\¯ or
¯/_(ツ)_\¯

---

An aside:

The wrong globby pattern caused it to not find any gallery definitions, saying

Successfully built gallery list.
Processed 0 gallery examples.

during the build. When afterwards opening the sandcastle, it showed an error in the Browser console:

Uncaught (in promise) Error: Pagefind Error: No language indexes found.
    at PagefindInstance.findIndex (pagefind.js:2:355)
    at PagefindInstance.init (pagefind.js:1:20007)
    at async Pagefind.init (pagefind.js:6:7599)

This is independent of the search pattern fix!

The point is: It should not show this error at runtime, even if no gallery files have been found.
(But I don't have the slightest clue what's the best place for handling this...)

[github-actions]

Thank you for the pull request, @javagl!

✅ We can confirm we have a CLA on file for you.

[ggetz]

@jjspace Could you please review when you get the chance?

[javagl]

@jjspace I'd assume that this is not really "reviewed as a PR", but maybe a change similar to the one here could go into #12904 ...

[jjspace]

@javagl I think the better solution is to just swap this for posix.join as suggested by the globby docs. Did you try that? any reason not to?

[javagl]

I tied it quickly, and I think that I just stubled over some issue with how to write the import properly 😊 There are a few things that I'd look into (e.g. does posix.join("foo/bar", "baz/buz") result in "foo/bar\baz/buz", or does it also replace the /'s from the existing parts?), but iff it performs some normalization (i.e. that 'replace-all'), then that's probably more idiomatic.

[jjspace]

for now you could just do import { basename, dirname, join, relative, posix } from "node:path"; for it. Maybe a better way long term, just wanted to know if it worked. I believe the last time I looked into windows path issues it did do the normalization inside existing paths. easy to verify but I'm not on windows to test

[javagl]

Regarding the import: I think that I was trying to avoid importing posix, because we only need join, and was looking for something along the lines of
import { ..., posix.join as posixJoin } from "node:path";
or some sort of
import { join as posixJoin } from "node:path:posix";
or so, but... that's not really important.

---

What's more important: posix.join does not do a normalization. For example, when using posix.join for the joining, the output for me is

Create globby pattern
rootDirectory  C:\Develop\CesiumGS\cesium\packages\sandcastle
pattern  gallery
baseGlobbyPattern  C:\Develop\CesiumGS\cesium\packages\sandcastle/gallery/**/*
globbyPattern  C:/Develop/CesiumGS/cesium/packages/sandcastle/gallery/**/*
Successfully built gallery list.

So the join itself does insert the / between sandcastle and gallery, but the prefix is still wrong. (There might be some alternative to the replace call, maybe some normalize or whatnot, but I used replace mainly to check that it works when ~"something like this is done" (no matter how...)).