Generate types from TypeScript dialect JSDoc

.eslintrc.yaml

@@ -1,3 +1,4 @@
+root: true
 extends:
     - "@sinonjs/eslint-config"
 

.gitignore

@@ -7,3 +7,4 @@ types
 .gitnexus
 docs/
 .worktrees/
+docs/superpowers/

README.md

@@ -21,13 +21,7 @@ the [same runtimes](https://sinonjs.org/releases/latest#compatibility-and-suppor
 
 ## Autocomplete, IntelliSense and TypeScript definitions
 
-Version 7 introduced JSDoc to the codebase. This should provide autocomplete and type suggestions in supporting IDEs. If
-you need more elaborate type support, TypeScript definitions for the Sinon projects are independently maintained by the
-Definitely Types community:
-
-```
-npm install -D @types/sinonjs__fake-timers
-```
+`@sinonjs/fake-timers` ships with built-in type definitions generated from JSDoc. This provides autocomplete and type suggestions in supporting IDEs and TypeScript projects without requiring external `@types` packages.
 
 ## Installation
 
@@ -422,3 +416,13 @@ npm test-headless
 ## License
 
 BSD 3-clause "New" or "Revised" License (see LICENSE file)
+
+## Contributing
+
+`@sinonjs/fake-timers` uses JSDoc in `src/fake-timers-src.js` as the source of truth for its public types.
+TypeScript declarations are automatically generated from this file. When contributing changes:
+
+- Update JSDoc annotations in `src/fake-timers-src.js` if the public API changes.
+- Run `npm run types:build` to regenerate the declarations in `types/`.
+- Ensure `npm run types:smoke` still passes to validate the generated types.
+- `tsgo` is used as a parallel validation lane to ensure compatibility with future TypeScript versions.

package.json

@@ -29,8 +29,12 @@
     "preversion": "./scripts/preversion.sh",
     "version": "./scripts/version.sh",
     "postversion": "./scripts/postversion.sh",
-    "prepare": "husky"
+    "prepare": "husky",
+    "types:build": "tsgo -p tsconfig.types.json",
+    "types:check": "tsgo -p tsconfig.types.json --noEmit",
+    "types:smoke": "tsgo -p test/typescript-consumer/tsconfig.json --noEmit"
   },
+  "types": "./types/fake-timers-src.d.ts",
   "lint-staged": {
     "*.{js,css,md}": "prettier --check",
     "*.js": "eslint"
@@ -43,14 +47,17 @@
     "spec": "test/**/*-test.js"
   },
   "files": [
-    "src/"
+    "src/",
+    "types/"
   ],
   "devDependencies": {
     "@mochify/cli": "^1.0.0",
     "@mochify/driver-puppeteer": "^1.0.1",
     "@mochify/driver-webdriver": "^1.0.0",
     "@sinonjs/eslint-config": "^5.0.4",
     "@sinonjs/referee-sinon": "12.0.0",
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260401.1",
     "esbuild": "^0.27.3",
     "husky": "^9.1.7",
     "jsdom": "28.1.0",

scripts/preversion.sh

@@ -18,6 +18,8 @@ fi
 
 
 npm run lint
+npm run types:build
+npm run types:smoke
 npm test # lints and tests
 
 npm run test-cloud # should not take more than approx 25 seconds