Types: Enable incremental JSDoc type checking

[donmccurdy]

Description

Summary

Enables IDEs with TypeScript language server support (such as VSCode) to infer types from JSDoc and detect type errors automatically. The PR is 'minimal' in the sense that it does not require migrating code into subpackages, and does not require replacing tsd-jsdoc. Either of those larger changes might still be preferable for other reasons, certainly. Adoption of TypeScript checks could be entirely incremental with this approach; we can turn type-checking on one file at a time.

Changes

• Adds packages/engine/tsdoc.json, with type-checking disabled for all JS files by default. Individual JS files may opt-in to type checking with a // @ts-check comment at top of file.
• For TypeScript to resolve type-only imports (for example, Cartesian2 uses Cartesian3 in its parameter types, but does not import the file), we use special comments like /** @import Cartesian3 from './Cartesian3.js'; */. TypeScript understands these, but JSDoc errors on them, so we update the JSDoc configuration to ignore @import tags. Huge thanks to @jjspace for this solution!
• Configures ESLint for ES6 class conversion. Scratch variables can be used by the same class they instantiate, which is fine at runtime but needs a workaround in ESLint.
• Configures CI to run tsc and check types, for files that we have opted in.
• Added documentation to the coding guide (preview)

Background

Minimal subset of work from 12/16/2025 hackathon day, including work from @jjhembd, @jdehorty, @jjspace, and myself. Other tracks explored in the hackathon — including JSDoc-TS compatibility conversion with Gemini, smaller package reorganization, build system updates, documentation generation with typedoc, , etc. — are on the core-math branch. We'll likely want to use some of those results too, but this PR might be the minimum-viable starting point.

Issue number and link

• Use ES6 "class" as module syntax #8359
• Let us slowly move to Typescript. (instructions inside) #4434

Testing plan

Run npm run tsc, and observe no errors reported. Add this.x = 'hello world' to the Cartesian2 constructor, run npm run tsc again, and see expected error output:

packages/engine/Source/Core/Cartesian2.js:32:5 - error TS2322: Type 'string' is not assignable to type 'number'.

32     this.x = "hello world";
       ~~~~~~

Found 1 error in packages/engine/Source/Core/Cartesian2.js:32

The same error should appear in your editor/IDE, without explicitly running tsc, if the editor supports the TypeScript Language Server.

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

PR Dependency Tree

• PR Types: Enable incremental JSDoc type checking #13104 👈
  • PR Types: Add type checks in Cartesian2.js #13126
  • PR Types: Bulk conversion to ES6 classes #13125

This tree was auto-generated by Charcoal

[github-actions]

Thank you for the pull request, @donmccurdy!

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

[jjspace]

Thanks for this @donmccurdy! Overall I'm hugely in favor of this change. It should let us get more out of our intellisense and start catching some type errors even before switching fully to TS.

Can you please add a section to our documentation pages about this? Probably part of the Contribution guides, maybe the CodingGuide? I also had a few more comments to help guide what gets documented.

[donmccurdy]

@jjspace I think all feedback on the PR has been addressed! Draft documentation in the coding guide:

https://github.com/CesiumGS/cesium/blob/refactor/minimal-tsc/Documentation/Contributors/CodingGuide/README.md#type-checking

I've moved the Cartesian2.js changes to a separate PR:

• Types: Add type checks in Cartesian2.js #13126

I also attempted a bulk conversion to ES6 classes for packages/engine/Source/Core/*.js:

• Types: Bulk conversion to ES6 classes #13125

That's too large to review and merge in bulk, for sure, but still it's encouraging to see tests passing after excluding a handful of files from the conversion.