DX: Fix defined and Check types for CesiumJS devs

[jjspace]

Description

• Add defined.d.ts which will now get picked up and provide the correct type predicates and assertions so JS Type checking will understand things are defined after this call
  • Originally added in Make TS definition of defined use type predicate #11455 which is fantastic for external contributors but local development doesn't look at the generated index.d.ts file for types like it will with the new defined.d.ts file

Before	After

• Fixed Check.d.ts for local development so the TS server understands it's a default export not an exported object
  • This was originally added in Add TS types for Check, remove circular dependency #11901 to help external users of CesiumJS, primarily the ion team

Before	After

• Updated the build process to account for these files and changes. The built Cesium.d.ts and engine/index.d.ts files should be identical to the previous ones.

Issue number and link

No issue, just a small DX issue I've grown too tired of seeing

Testing plan

• In main run npm run built-ts
• Create a copy of Source/Cesium.d.ts and packages/engine/index.d.ts somewhere you can check later
• Switch to this branch and run npm run build-ts
• Do a diff of those files and ensure they are identical. This confirms our external use will be the same downstream
• To test locally find a usage of defined and Check locally
• Turn on the VSCode setting Check JS for type checking with the TS server (This may or may not be necessary, I'm not sure)
• Verify that in main the types aren't correct as shown above, verify that in this branch they are
• Turn off CheckJS if you're not ready to see a lot of other (false positive) errors scattered in our code

Author checklist

• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have updated the inline documentation, and included code examples where relevant
• I have performed a self-review of my code

[github-actions]

Thank you for the pull request, @jjspace!

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

[jjspace]

As per my comment when I did the same conversion into a .d.ts file for Check, I would love if we could skip this replace and pass the types file into tsd-jsdoc but we cannot. I think defined and Check are some of the only types we really need to override to take advantage of stuff like type predicates but if we add more we should definitely revisit this setup as it will quickly become too unwieldy.

[jjspace]

@javagl Would you mind taking a look at this? I think you've been looking into our type system and typescript adjacent stuff recently so you might be a good person to provide input.

[javagl]

I followed the points from the testing plan. There are some smaller caveats.

After enabling the "Check JS" functionality in VS Code, it did complain about many things. But it did not generate the "...is possibly undefined" messages for me.
Maybe my VS Code is somehow messed up...? Maybe I'd have to delete something or use "a fresh copy" of something...? More generally: Where exactly is VSCode supposed to pull that new information from, when the d.ts files are supposed to be unchanged?

It did complain about the typeof in Check. And this is resolved by this change.
There may be an issue with the resulting export default in this case that likely will cause trouble in a TypeScript environment (see inlined comment). But this might be an easy fix.

---

Beyond that:

This is NOT in the scope of this PR, but I cannot look at the gulpfile.js without pointing out that this is one of my pet peeves 😬 The fact that it does have to contain these readFileSync(....) and ridiculously obscure regexes is bad enough. The fact that it has to contain them twice makes it even worse. But when looking at that duplication like in a blink comparator, and then noticing the difference in that // inlined comment, it is nearly funny again 🙂 :

Usually, I'm not touching that file, out of the fear of "breaking something". But ... after this is merged, I'll probably go out on a limb, take a pass at that file, and then there might be a function that is called fixUpTheOutputToMatchWhatWeNeed() - I'm reasonably sure that this would not break anything, at least...

[jjspace]

After enabling the "Check JS" functionality in VS Code, it did complain about many things. But it did not generate the "...is possibly undefined" messages for me.

@javagl I sometimes find I have to run the Restart TS Server or Reload Window commands to refresh typescript. They seem to cache some things internally or something that makes it get out of sync, especially in JS environments that aren't actually TS

This is NOT in the scope of this PR, but I cannot look at the gulpfile.js without pointing out that this is one of my pet peeves

I fully agree with this sentiment, I'd love if the logic was centralized because I always forget to change both any time I touch this. Definitely outside the scope of this PR though. I'm happy to review a PR for cleaning up the gulpfile but as you say, every time I touch this file I'm worried about breaking something

[javagl]

I sometimes find I have to run the Restart TS Server or Reload Window commands to refresh typescript.

Yeah, I also had cases where this was necessary. But it wasnt't the root cause here. Although I did search for "defined(" and did click through many cases, I didn't click to all (13509) appearances. And apparently, I only looked at ones that didn't show the message because there was no corresponding information in the JSDoc: Only when that "thing" is defined to be a non-undefined type via JSDoc, the message appears. For example, in this snippet...

/**
 * Does not complain about s potentially being undefined
 */
function exampleA(s) {
  if (defined(s)) {
    console.log(s.length);
  }
}
/**
 * Does not complain about s potentially being undefined
 * 
 * @param {string} s
 */
function exampleB(s) {
  if (defined(s)) {
    console.log(s.length);
  }
}

/**
 * DOES complain about s potentially being undefined!
 * 
 * @param {string | undefined} s
 */
function exampleC(s) {
  if (defined(s)) {
    console.log(s.length);
  }
}

it shows the message for the bottommost one:

And I confirmed that this does no longer appear on the branch of this PR.