Merge pull request #539 from Hack23/copilot/move-project-to-typescript-6-0-2

pethers · web-flow · commit c38a5dfe2535 · 2026-03-31T14:09:32.000+02:00
Upgrade TypeScript 5.9.3 → 6.0.2 with TS6 breaking change fixes and documentation updates
diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml
@@ -92,7 +92,7 @@ template: |
   ## Game Development Stack
   - ⚡ **Vite** - Fast build tool and dev server
   - ⚛️ **React 19** - Modern React with hooks  
-  - 🔷 **TypeScript** - Strict typing with latest standards
+  - 🔷 **TypeScript 6** - Strict typing with latest standards
   - 🎮 **Three.js** - High-performance 3D WebGL renderer
   - 🎨 **@react-three/fiber** - React renderer for Three.js
   - 🧪 **Vitest** - Fast unit testing with coverage
diff --git a/README.md b/README.md
@@ -44,7 +44,7 @@ For complete security policy mapping and detailed compliance information, see:
 
 - ⚡ **Vite** - Fast build tool and dev server
 - ⚛️ **React 19** - Modern React with hooks
-- 🔷 **TypeScript** - Strict typing with latest standards
+- 🔷 **TypeScript 6** - Strict typing with latest standards
 - 🧪 **Vitest** - Fast unit testing with coverage
 - 🌲 **Cypress** - Reliable E2E testing
 - 📦 **ESLint** - Code linting with TypeScript rules
diff --git a/cypress/tsconfig.json b/cypress/tsconfig.json
@@ -12,6 +12,7 @@
     "esModuleInterop": true,
     "allowSyntheticDefaultImports": true,
     "resolveJsonModule": true,
+    "ignoreDeprecations": "6.0",
     "types": ["cypress", "node"]
   },
   "include": ["**/*.ts", "**/*.tsx", "../src/types/**/*"],
diff --git a/docs/End-of-Life-Strategy.md b/docs/End-of-Life-Strategy.md
@@ -1,13 +1,15 @@
-# Node.js End-of-Life Strategy
+# Runtime & Toolchain End-of-Life Strategy
 
 ## Overview
 
-This document defines the strategy for managing Node.js runtime versions in the **game** project, ensuring we stay on actively maintained releases and plan upgrades proactively. All version decisions align with the [Hack23 ISMS Secure Development Policy](https://github.com/Hack23/ISMS-PUBLIC).
+This document defines the strategy for managing Node.js runtime and TypeScript compiler versions in the **game** project, ensuring we stay on actively maintained releases and plan upgrades proactively. All version decisions align with the [Hack23 ISMS Secure Development Policy](https://github.com/Hack23/ISMS-PUBLIC).
 
 ---
 
 ## Current Status (March 2026)
 
+### Node.js
+
 | Node.js | Release Date | Status | Bug Fixes Until | Security Fixes Until |
 |---------|-------------|--------|-----------------|----------------------|
 | **25 (Current)** | Oct 15, 2025 | ✅ **Active — in use** | Apr 1, 2026 | Jun 1, 2026 |
@@ -17,6 +19,16 @@ This document defines the strategy for managing Node.js runtime versions in the
 
 > **Note:** Node.js 25 is an odd-numbered "Current" release, meaning it does **not** receive LTS status. It is supported for approximately 6 months before reaching end-of-life. We use it to validate readiness for Node.js 26.
 
+### TypeScript
+
+| TypeScript | Release Date | Status | Support Until |
+|-----------|-------------|--------|---------------|
+| **6.0.2** | Mar 2026 | ✅ **Active — in use** | Until 7.0 release (~12 months) |
+| 5.9.x | Feb 2026 | Previous stable | Limited — security patches only |
+| 5.8.x | Dec 2025 | End of life | ❌ No support |
+
+> **Note:** TypeScript 6.0 is a major release with breaking changes including stricter module resolution with `moduleResolution: "bundler"`, removal of implicit `global` namespace, and stricter `NodeJS` namespace handling. The project uses `@typescript-eslint 8.58.0` which supports `typescript >=4.8.4 <6.1.0`.
+
 ---
 
 ## Node.js Release Cadence
@@ -41,6 +53,42 @@ Node 28  | Apr 2027  | ~6 mo    | Oct 2027      | Oct 2028        | Apr 2030
 
 ---
 
+## TypeScript Release Cadence
+
+Microsoft publishes TypeScript on a roughly quarterly schedule:
+
+- **Major versions** (e.g., 5.0 → 6.0) ship approximately once per year with breaking changes
+- **Minor versions** (e.g., 6.0 → 6.1) ship every 2–3 months with new features
+- **Patch versions** (e.g., 6.0.1 → 6.0.2) ship as needed for bug fixes
+
+```
+Version  | Release   | Status         | @typescript-eslint Support
+---------|-----------|----------------|---------------------------
+TS 5.8   | Dec 2025  | End of life    | 8.x (>=4.8.4 <6.1.0)
+TS 5.9   | Feb 2026  | Previous       | 8.x (>=4.8.4 <6.1.0)
+TS 6.0   | Mar 2026  | Current ✅     | 8.x (>=4.8.4 <6.1.0)
+TS 6.1   | ~Jun 2026 | Planned        | Requires @typescript-eslint update
+TS 7.0   | ~2027     | Future         | Requires @typescript-eslint update
+```
+
+### TypeScript Upgrade Policy
+
+1. **Upgrade to new patch versions immediately** — bug fixes only, no breaking changes.
+2. **Upgrade to new minor versions within 2 weeks** — validate `tsc -b`, ESLint, and all tests pass.
+3. **Upgrade to new major versions within 1 month** — major versions may require code changes and `@typescript-eslint` compatibility updates.
+4. **Never use TypeScript versions unsupported by `@typescript-eslint`** — this would disable type-aware linting.
+
+### TypeScript Upgrade Triggers
+
+| Trigger | Action | Timeline |
+|---------|--------|----------|
+| New patch release (e.g., 6.0.3) | Update `package.json`, run full CI | Within 1 week |
+| New minor release (e.g., 6.1.0) | Verify `@typescript-eslint` compatibility first | Within 2 weeks |
+| New major release (e.g., 7.0.0) | Full compatibility assessment, dedicated PR | Within 1 month |
+| `@typescript-eslint` drops support | Upgrade `@typescript-eslint` or pin TypeScript | Within 24 hours |
+
+---
+
 ## Version Upgrade Policy
 
 ### Principles
@@ -94,7 +142,9 @@ Node.js 24 reaches end-of-life in April 2028. By this date, all workflows and de
 
 ## Version Matrix
 
-The project maintains two parallel test workflows:
+The project maintains two parallel test workflows and tracks toolchain versions:
+
+### Node.js
 
 | Workflow | Purpose | Current Node Version |
 |----------|---------|----------------------|
@@ -106,6 +156,15 @@ When a new Node.js version is released:
 2. Once validated (typically within the same sprint), update `test-and-report.yml`
 3. Update all other workflows (`release.yml`, `codeql.yml`, copilot setup) together
 
+### TypeScript & Toolchain
+
+| Tool | Current Version | Peer Constraint | Upgrade Path |
+|------|----------------|-----------------|--------------|
+| TypeScript | **6.0.2** | — | Follow quarterly releases |
+| @typescript-eslint | **8.58.0** | `typescript >=4.8.4 <6.1.0` | Must update before TS 6.1 |
+| Vite | **8.0.3** | — | Follow major releases |
+| Vitest | **4.1.2** | — | Keep aligned with Vite |
+
 ---
 
 ## Risk Assessment
@@ -116,13 +175,19 @@ When a new Node.js version is released:
 | Incompatible npm packages | Medium | High | Run tests on new version early |
 | Breaking API changes | Low | High | Test on Current release before it becomes primary |
 | CI/CD downtime during upgrade | Low | Medium | Upgrade in dedicated PR with rollback plan |
+| TypeScript major upgrade breaks build | Medium | High | Test with `tsc -b`, lint, and full test suite before merging |
+| @typescript-eslint drops TypeScript version support | Medium | High | Monitor peer dependency ranges; pin TypeScript if needed |
+| TypeScript strictness regression in new version | Low | Medium | Use project references and separate tsconfigs for app/test/node |
 
 ---
 
 ## References
 
 - [Node.js Release Schedule](https://nodejs.org/en/about/previous-releases)
 - [Node.js End-of-Life Dates — endoflife.date](https://endoflife.date/nodejs)
+- [TypeScript Release Notes](https://devblogs.microsoft.com/typescript/)
+- [TypeScript End-of-Life Dates — endoflife.date](https://endoflife.date/typescript)
+- [@typescript-eslint Supported TypeScript Versions](https://typescript-eslint.io/users/dependency-versions/)
 - [Hack23 ISMS Secure Development Policy](https://github.com/Hack23/ISMS-PUBLIC)
 - [WORKFLOWS.md](./WORKFLOWS.md) — Current CI/CD workflow documentation
 - [FUTURE_WORKFLOWS.md](./FUTURE_WORKFLOWS.md) — Planned Node.js 26 upgrade
diff --git a/docs/FUTURE_WORKFLOWS.md b/docs/FUTURE_WORKFLOWS.md
@@ -98,7 +98,8 @@ sed -i 's/"version": "25"/"version": "26"/' .devcontainer/devcontainer.json
 | `vite` | May ship Node.js 26 support update | Check release notes |
 | `cypress` | Historically supports new Node quickly | Verify with `npx cypress verify` |
 | `vitest` | Tracks Vite compatibility | Validate test suite passes |
-| `typescript` | Generally Node-agnostic | No action expected |
+| `typescript` | Currently 6.0.2; generally Node-agnostic | No action expected |
+| `@typescript-eslint` | Currently supports `typescript <6.1.0` | Must update before TS 6.1 |
 
 ### V8 Engine Changes (Node.js 26)
 
@@ -142,6 +143,33 @@ The project can safely remain on Node.js 25 until **June 1, 2026** (security EOL
 
 ---
 
+## TypeScript Upgrade Planning
+
+### Current State
+
+TypeScript **6.0.2** is in use. The `@typescript-eslint 8.58.0` peer dependency constraint is `typescript >=4.8.4 <6.1.0`.
+
+### TypeScript 6.1 Upgrade (Expected ~June 2026)
+
+When TypeScript 6.1 is released:
+
+1. **Check `@typescript-eslint` compatibility** — version 8.58.0 requires `<6.1.0`; a newer release will be needed
+2. **Update `@typescript-eslint`** to a version supporting TS 6.1
+3. **Update `package.json`** — change `typescript` to the new version
+4. **Run full validation** — `npm run build`, `npm run lint`, `npm run test`
+5. **Review breaking changes** — consult [TypeScript release notes](https://devblogs.microsoft.com/typescript/)
+
+### TypeScript 7.0 Upgrade (Expected ~2027)
+
+Major version upgrades may require:
+
+- Code changes for stricter type checking
+- `tsconfig.json` updates for new compiler options
+- `@typescript-eslint` major version upgrade
+- Dedicated PR with full test suite validation
+
+---
+
 ## Related Documents
 
 - [End-of-Life-Strategy.md](./End-of-Life-Strategy.md) — Full Node.js lifecycle policy
diff --git a/docs/WORKFLOWS.md b/docs/WORKFLOWS.md
@@ -5,6 +5,7 @@
 This document describes all GitHub Actions workflows in the **game** project. All workflows follow the security-first principles defined in the [Hack23 ISMS Secure Development Policy](https://github.com/Hack23/ISMS-PUBLIC) and use hardened runners via `step-security/harden-runner`.
 
 **Current Node.js version: 25**
+**Current TypeScript version: 6.0.2**
 
 ---
 
diff --git a/eslint.config.js b/eslint.config.js
@@ -15,6 +15,7 @@ export default tseslint.config(
         project: [
           "./tsconfig.app.json",
           "./tsconfig.node.json",
+          "./tsconfig.test.json",
           "./cypress/tsconfig.json",
         ],
         tsconfigRootDir: import.meta.dirname,
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -52,7 +52,7 @@
     "jsdom": "29.0.1",
     "license-compliance": "3.0.1",
     "start-server-and-test": "3.0.0",
-    "typescript": "5.9.3",
+    "typescript": "6.0.2",
     "typescript-eslint": "8.58.0",
     "vite": "8.0.3",
     "vitest": "4.1.2"
diff --git a/src/hooks/useAudioManager.test.ts b/src/hooks/useAudioManager.test.ts
@@ -36,8 +36,8 @@ class MockAudioContext {
   sampleRate = 48000;
 }
 
-global.AudioContext = MockAudioContext as unknown as typeof AudioContext;
-global.URL.createObjectURL = vi.fn().mockReturnValue("mock-blob-url");
+globalThis.AudioContext = MockAudioContext as unknown as typeof AudioContext;
+globalThis.URL.createObjectURL = vi.fn().mockReturnValue("mock-blob-url");
 
 describe("useAudioManager", () => {
   beforeEach(() => {
diff --git a/src/hooks/useGameState.ts b/src/hooks/useGameState.ts
@@ -75,8 +75,8 @@ export function useGameState(initialState?: Partial<GameState>): UseGameStateRet
     };
   });
 
-  const comboTimerRef = useRef<NodeJS.Timeout | null>(null);
-  const gameTimerRef = useRef<NodeJS.Timeout | null>(null);
+  const comboTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const gameTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const animationFrameRef = useRef<number | null>(null);
 
   // Cleanup timers on unmount
diff --git a/src/test/security-headers.test.ts b/src/test/security-headers.test.ts
@@ -1,14 +1,16 @@
 import { describe, it, expect, beforeAll } from "vitest";
-import * as fs from "fs";
-import * as path from "path";
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 
 describe("Security Headers in Built HTML", () => {
-  const htmlPath: string = path.resolve(__dirname, "../../index.html");
+  const currentDir: string = dirname(fileURLToPath(import.meta.url));
+  const htmlPath: string = resolve(currentDir, "../../index.html");
   let htmlContent: string;
 
   beforeAll(() => {
     try {
-      htmlContent = fs.readFileSync(htmlPath, "utf-8");
+      htmlContent = readFileSync(htmlPath, "utf-8");
     } catch (err) {
       throw new Error(
         `Could not read index.html at ${htmlPath}. Did you run the build?`,
diff --git a/tsconfig.app.json b/tsconfig.app.json
@@ -1,5 +1,6 @@
 {
   "compilerOptions": {
+    "composite": true,
     "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
     "target": "ES2024",
     "useDefineForClassFields": true,
@@ -22,5 +23,6 @@
     "noFallthroughCasesInSwitch": true,
     "noUncheckedIndexedAccess": true
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx", "src/test"]
 }
diff --git a/tsconfig.json b/tsconfig.json
@@ -21,6 +21,9 @@
     "exactOptionalPropertyTypes": true,
     "typeRoots": ["./node_modules/@types", "./src/types"]
   },
-  "include": ["src/**/*", "src/types/**/*"],
-  "exclude": ["node_modules", "dist", "cypress"]
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
 }
diff --git a/tsconfig.test.json b/tsconfig.test.json
@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "useDefineForClassFields": true,
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "types": ["vitest/globals", "node"]
+  },
+  "include": [
+    "src/**/*.test.ts",
+    "src/**/*.test.tsx",
+    "src/test/**/*",
+    "src/**/*.ts",
+    "src/**/*.tsx"
+  ]
+}

Original file line number	Diff line number	Diff line change
`@@ -36,8 +36,8 @@ class MockAudioContext {`
`36`	`36`	`sampleRate = 48000;`
`37`	`37`	`}`
`38`	`38`
`39`		`-global.AudioContext = MockAudioContext as unknown as typeof AudioContext;`
`40`		`-global.URL.createObjectURL = vi.fn().mockReturnValue("mock-blob-url");`
	`39`	`+globalThis.AudioContext = MockAudioContext as unknown as typeof AudioContext;`
	`40`	`+globalThis.URL.createObjectURL = vi.fn().mockReturnValue("mock-blob-url");`
`41`	`41`
`42`	`42`	`describe("useAudioManager", () => {`
`43`	`43`	`beforeEach(() => {`