docs: the TypeScript 7 / Node 26 / Python 3.15 move, and a runbook for 7.1

- docs/plan/16-toolchain-2026.md: the assessment - what each release
  changes, what was measured here, the decisions, how to move each runtime
  next time, and what was left.
- docs/plan/17-typescript-7.1.md: the springboard for dropping TypeScript 6
  once 7.1 ships - start conditions and how to check them, the steps, the
  planted-error table and the baselines to compare against.
- CLAUDE.md: "TypeScript is two packages, on purpose" and "One version of
  each runtime"; the uv compile line says 3.15.
- dev_env (EN/VI), README, AUTHORS, TAURI.md, web/README, THIRD_PARTY,
  DEPLOYMENT (Workers Builds' NODE_VERSION=26, the Checks paragraph),
  ACKNOWLEDGEMENTs and the About page's stack list ("TypeScript 7 + 6").
- CHANGELOG: the Tooling entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-10-22 10:19:52 +07:00
1 parent 86f68c247b
commit ee146dd023
14 files changed
+542 -16

No files matched your search

+1 -1
View File
@@ -32,7 +32,7 @@ For people forking the repo or trying to reproduce a build:
| --------------- | ------------------------------------------------------------ |
| GitHub | [@poli0981](https://github.com/poli0981) |
| IDE | JetBrains 2026.x — paid lineup (PyCharm, WebStorm, RustRover) |
| Toolchains | Python 3.12 · Node.js ≥ 22 · Rust stable · Tauri 2 |
| Toolchains | Python 3.15 · Node.js 26 · TypeScript 7 · Rust stable · Tauri 2 |
| Git | GPG signing on (`commit.gpgsign=true`) |
| Hardware spec | [`docs/pc_spec.md`](docs/pc_spec.md) (EN) · [`docs/i18n/vi/pc_spec.md`](docs/i18n/vi/pc_spec.md) (VI) |
| Dev environment | [`docs/dev_env.md`](docs/dev_env.md) (EN) · [`docs/i18n/vi/dev_env.md`](docs/i18n/vi/dev_env.md) (VI) |
+14
View File
@@ -14,6 +14,20 @@ All notable changes to this awesome noob repo will be documented here.
- **SonarCloud reads tests as tests**, and no longer analyses the dataset,
the Android resources the Tauri CLI generated, or the SQLite migrations its
PL/SQL analyser misread (`.sonarcloud.properties`).
- **TypeScript 7, Node 26 and Python 3.15.** The type-check runs on
TypeScript 7, the native compiler: `tsc` for the Worker, the tests and the
admin's Node code, and `svelte-check --tsgo` for the app. TypeScript 6 stays
installed beside it, because svelte-check and SvelteKit's route types still
need the JavaScript API that 7.0 does not have (the admin's svelte-check
stays on it too). CI, the release builds and Cloudflare's build run Node 26,
the LTS from 28 October; the pipeline, its tests and every data job run
Python 3.15, which writes the shards byte for byte as 3.12 did - no
re-download for anyone. The leaderboards and the dead-link log name their
encoding, so they no longer crash on Windows under an older Python. A new
test fails when one of the version pins drifts from the others, and Web CI
now runs on workflow-only changes so it sees them. The full assessment is in
`docs/plan/16-toolchain-2026.md`; `docs/plan/17-typescript-7.1.md` prepares
the move to TypeScript 7 alone once 7.1 is out.
### 🔐 Security
+35 -1
View File
@@ -433,7 +433,25 @@ scraping pipeline (`scripts/`) driven by GitHub Actions.
Dependabot bump is proven before a data job meets it, and
`requirements-dev.txt` (unhashed local tools) is installed on its own.
Adding a package means adding it and its dependencies with hashes:
`uv pip compile --universal --generate-hashes --python-version 3.12`.
`uv pip compile --universal --generate-hashes --python-version 3.15`.
- **One version of each runtime, and a test that holds them together**
(`web/shared/toolchain.test.ts`; web-ci also runs on `.github/workflows/**`
and `.sonarcloud.properties` so a pull request that only moves a pin meets
it). `docs/plan/16-toolchain-2026.md` has the upgrade notes.
- Node is the major in `web/.node-version` (26). Every `setup-node` repeats
it as a quoted literal, never `node-version-file`: `release-android.yml`
checks out the tag it rebuilds, and older tags have no such file.
`engines.node` and the `@types/node` major follow it. Workers Builds
reads the dashboard variable `NODE_VERSION=26`, the one copy the test
cannot see (`docs/DEPLOYMENT.md`): change it with the file.
- Python is the `python-version` of every `setup-python` (3.15), repeated
by `sonar.python.version` and the `--python-version` above. `codeql.yml`
alone stays on the newest Python CodeQL lists (3.14), named in the test's
`PYTHON_EXCEPTIONS`. A version is always quoted: YAML reads 3.10 as 3.1.
- Python 3.15 makes `open()` default to UTF-8 everywhere (PEP 686), but every
text open in `scripts/` still names `encoding="utf-8"`: on Windows an
older Python writes the locale's code page, and cp1252 cannot encode the
leaderboards' emoji.
- **SonarCloud's scope is `.sonarcloud.properties`** (automatic analysis; only
scope keys are read, from the default branch). Code and tests both start at
the root and are split by patterns: a new test-helper folder goes into
@@ -547,6 +565,22 @@ scraping pipeline (`scripts/`) driven by GitHub Actions.
dependency (`EOVERRIDE`). A kit bump therefore silently drops the override
and the alert comes back: re-key it, or delete it once kit asks for
`cookie` >= 0.7. Never carry it onto kit 3, which needs `cookie` 2.
- **TypeScript is two packages, on purpose.** TypeScript 7 (the Go compiler)
has no JavaScript API, and svelte-check and `svelte-kit sync` (route
`$types`) need one, so `typescript` stays 6 and 7 is the alias
`@typescript/native` (`npm:typescript@~7.0.x`). svelte-check `--tsgo` finds 7
by that name and runs its bin; the `tsc -p` steps call
`node node_modules/@typescript/native/bin/tsc` by path, because both
packages declare a `tsc` bin and `node_modules/.bin/tsc` is whichever one npm
linked last. `check:admin` stays on TypeScript 6: `--tsgo` cannot follow
`.svelte` imports from outside its tsconfig's folder (`web/admin` imports
`../src/lib/ui`), and a component it cannot map falls back to the ambient
`*.svelte` shim - unchecked props, and no error. Dependabot ignores
`typescript` majors and the alias (it mishandles `npm:` aliases): bump the
two by hand. `~7.0` because 7.1 changes the API svelte-check's experimental
mode uses. TypeScript 6 goes when svelte-check accepts 7 alone:
`docs/plan/17-typescript-7.1.md` lists the conditions, the steps and the
planted-error check that proves the switch.
- **Real paths everywhere, including the packaged apps.** There is no
HashRouter and no hash shim: `tauri::manager::get_asset()` falls back through
`<path>.html`, `<path>/index.html`, then `index.html`, so the Tauri webview
+1 -1
View File
@@ -244,7 +244,7 @@ Unemployed, introvert max level, dropped out uni year 3, mooching off family. Ne
- [CHANGELOG](CHANGELOG.md) — what changed in each version.
- [CONTRIBUTING](CONTRIBUTING.md) — issue templates, suggesting a game, manual fork.
- [PC spec](docs/pc_spec.md) ([VI](docs/i18n/vi/pc_spec.md)) — maintainer's dev hardware + test devices.
- [Dev environment](docs/dev_env.md) ([VI](docs/i18n/vi/dev_env.md)) — IDE, toolchains (Python 3.12 / Node 24 / Rust stable / Tauri 2), workflow.
- [Dev environment](docs/dev_env.md) ([VI](docs/i18n/vi/dev_env.md)) — IDE, toolchains (Python 3.15 / Node 26 / TypeScript 7 / Rust stable / Tauri 2), workflow.
- [Tauri build](web/src-tauri/TAURI.md) — desktop build prerequisites + signing + auto-update.
- [DISCLAIMER](docs/DISCLAIMER.md) — accuracy caveats, no-warranty, the broke-maintainer note.
- [Terms of Use](docs/ToS.md) — usage agreement, contributions, governing law.
+1 -1
View File
@@ -52,7 +52,7 @@ links and licences; this is the whole list, grouped by what it does.
**Framework & build**
- [Svelte 5](https://svelte.dev/) + [SvelteKit 2](https://svelte.dev/docs/kit) — UI runtime and app framework, with `adapter-static` (all MIT).
- [TypeScript 6](https://www.typescriptlang.org/) — type system (Apache-2.0).
- [TypeScript 7](https://www.typescriptlang.org/) — type system (Apache-2.0); the native compiler type-checks the code, and TypeScript 6 stays alongside it for the Svelte tooling, which needs its JavaScript API.
- [Vite 8](https://vitejs.dev/), powered by the [Rolldown](https://rolldown.rs/) bundler, and `@sveltejs/vite-plugin-svelte` (MIT).
- [Tailwind CSS 4](https://tailwindcss.com/) via `@tailwindcss/vite` (MIT). Tailwind 4 is a Vite plugin, so there is no PostCSS step and no `tailwind.config.ts`.
+13 -2
View File
@@ -22,6 +22,14 @@ push to main
└─ vite build -c admin/… → web/worker/generated/admin-bundle.ts
```
**The build runs on Node 26.** The Worker's dashboard sets the build variable
`NODE_VERSION=26` (Settings → Build → Variables and secrets); Cloudflare's
image would otherwise use its default, Node 24. `web/.node-version` says the
same, and CI and `web/shared/toolchain.test.ts` follow that file, but
Cloudflare does not document which directory it reads it from or which of the
two wins, so keep the variable and change both together. The first lines of a
build log show the Node actually used.
`web/wrangler.jsonc` is the only deployment config. Several fields in it are
load-bearing and easy to break:
@@ -171,8 +179,11 @@ Stop `wrangler dev` before running `npm ci`. On Windows the install deletes
## Checks
`.github/workflows/web-ci.yml` runs on pull requests and on pushes to `main`
touching `web/**`: `npm ci --ignore-scripts`, the typechecks (app, Worker and
tests), `npm test`, the build, `scripts/verify-dist.mjs --web` over the
touching `web/**`, `.github/workflows/**` or `.sonarcloud.properties`:
`npm ci --ignore-scripts`, the typechecks (app, Worker and tests, on
TypeScript 7; the admin's svelte-check on TypeScript 6), `npm test` (which
includes the toolchain-pin and data-write-group checks over the workflows),
the build, `scripts/verify-dist.mjs --web` over the
prerendered HTML, `npm run cf:check` (`wrangler deploy --dry-run`), and
`knip`. `python-tests.yml` runs the pipeline's pytest suite on changes under
`scripts/` and the requirements files, installing them exactly as the data jobs
+1 -1
View File
@@ -17,7 +17,7 @@ Added in v3.2.7 to make the pre-publish checks below runnable.
| [knip](https://knip.dev) | Web app (`web/`) | Finds unused files, exports, types, enum members and dependencies across the SvelteKit app, the Worker and the admin build. | ISC |
| [vulture](https://github.com/jendrikseipp/vulture) | Python pipeline (`scripts/`) | Finds unused functions, classes, variables, imports, and unreachable code. | MIT |
| [pip-audit](https://github.com/pypa/pip-audit) | Python pipeline | Audits the pinned Python dependencies against the OSV / PyPI Advisory vulnerability databases. | Apache-2.0 |
| [svelte-check](https://github.com/sveltejs/language-tools) | Web app (`web/`) | Type-checks `.svelte` files, which `tsc` cannot read. Runs twice in `npm run typecheck` — once for the app, once for the admin build. | MIT |
| [svelte-check](https://github.com/sveltejs/language-tools) | Web app (`web/`) | Type-checks `.svelte` files, which `tsc` cannot read. Runs twice in `npm run typecheck` — once for the app, on TypeScript 7 (`--tsgo`), and once for the admin build, on TypeScript 6 (`--tsgo` cannot follow its imports from `../src`). | MIT |
| [vitest](https://vitest.dev) | Web app (`web/`) | The test runner behind `npm test`. | MIT |
### Where they're declared
+4 -3
View File
@@ -16,14 +16,15 @@ JetBrains lineup, paid version, channel **2026.x**. Any equivalent editor (VS Co
| Tool | Version | Notes |
| ----------- | ------------------- | --------------------------------------------- |
| Python | 3.12 | `scripts/` pipeline + Steam client |
| Node.js | 24 (CI), ≥ 22.5 | web build, tests (`node:sqlite`), Tauri build |
| Python | 3.15 | `scripts/` pipeline + Steam client |
| Node.js | 26 (`web/.node-version`) | web build, tests (`node:sqlite`), Tauri build |
| TypeScript | 7 + 6 | 7 (`@typescript/native`) type-checks; 6 stays for svelte-check and `svelte-kit sync` |
| Rust | stable (via rustup) | Tauri runtime |
| npm | bundled with Node | `web/package-lock.json` is the source of truth |
| Git | recent | GPG signing on (`commit.gpgsign=true`) |
| Tauri CLI | 2.x | invoked via `npm run tauri ...` |
The CI workflows in [`.github/workflows/`](../.github/workflows) pin these versions explicitly. See [`release-desktop.yml`](../.github/workflows/release-desktop.yml) for the desktop build matrix and [`web-ci.yml`](../.github/workflows/web-ci.yml) for the web checks. The site itself is deployed by Cloudflare Workers Builds on a push to `main` — see [`DEPLOYMENT.md`](DEPLOYMENT.md).
The CI workflows in [`.github/workflows/`](../.github/workflows) pin these versions explicitly, and `web/shared/toolchain.test.ts` fails when one of them drifts from the others (CodeQL's Python is the one named exception). See [`release-desktop.yml`](../.github/workflows/release-desktop.yml) for the desktop build matrix and [`web-ci.yml`](../.github/workflows/web-ci.yml) for the web checks. The site itself is deployed by Cloudflare Workers Builds on a push to `main` — see [`DEPLOYMENT.md`](DEPLOYMENT.md). Why TypeScript is two packages, and how to move each runtime next time: [`plan/16-toolchain-2026.md`](plan/16-toolchain-2026.md); the switch to TypeScript 7 alone, planned for 7.1: [`plan/17-typescript-7.1.md`](plan/17-typescript-7.1.md).
## Dev workflow
+4 -3
View File
@@ -16,14 +16,15 @@ Lineup JetBrains, bản trả phí, channel **2026.x**. Editor khác (VS Code, N
| Tool | Version | Ghi chú |
| ---------- | ------------------- | ------------------------------------------------ |
| Python | 3.12 | `scripts/` pipeline + Steam client |
| Node.js | ≥ 22 (LTS) | web build, pipeline build Tauri |
| Python | 3.15 | `scripts/` pipeline + Steam client |
| Node.js | 26 (`web/.node-version`) | web build, test (`node:sqlite`), build Tauri |
| TypeScript | 7 + 6 | 7 (`@typescript/native`) type-check; 6 giữ lại cho svelte-check và `svelte-kit sync` |
| Rust | stable (via rustup) | Tauri runtime |
| npm | đi kèm Node | `web/package-lock.json` là source of truth |
| Git | mới | GPG signing on (`commit.gpgsign=true`) |
| Tauri CLI | 2.x | gọi qua `npm run tauri ...` |
CI workflow trong [`.github/workflows/`](../../../.github/workflows) đã pin các version này. Xem [`release-desktop.yml`](../../../.github/workflows/release-desktop.yml) cho matrix build desktop và [`web-ci.yml`](../../../.github/workflows/web-ci.yml) cho các bước kiểm tra web. Bản thân trang web được Cloudflare Workers Builds deploy mỗi khi push lên `main` — xem [`DEPLOYMENT.md`](../../DEPLOYMENT.md).
CI workflow trong [`.github/workflows/`](../../../.github/workflows) đã pin các version này, và `web/shared/toolchain.test.ts` sẽ fail khi một chỗ lệch khỏi các chỗ còn lại (Python của CodeQL là ngoại lệ duy nhất, được khai tên). Xem [`release-desktop.yml`](../../../.github/workflows/release-desktop.yml) cho matrix build desktop và [`web-ci.yml`](../../../.github/workflows/web-ci.yml) cho các bước kiểm tra web. Bản thân trang web được Cloudflare Workers Builds deploy mỗi khi push lên `main` — xem [`DEPLOYMENT.md`](../../DEPLOYMENT.md). Vì sao TypeScript là hai gói, và cách nâng từng runtime lần sau: [`plan/16-toolchain-2026.md`](../../plan/16-toolchain-2026.md); kế hoạch chuyển hẳn sang TypeScript 7 khi có bản 7.1: [`plan/17-typescript-7.1.md`](../../plan/17-typescript-7.1.md).
## Workflow dev
+290
View File
@@ -0,0 +1,290 @@
# Toolchain 2026 — TypeScript 7, Node.js 26, Python 3.15
## Why this note exists
On 2026-10-22 the maintainer asked for an assessment of the whole repository
against TypeScript 7, Node.js 26 and Python 3.15, a plan to move to them, CI
included, and the fixes the move needs. This is that assessment, the
decisions it led to, and what to do next time. Every number below was
measured on the day, on the repository as it stood (`main` at e10d2e7b), with
Node 26.12.1 / npm 11.20.0 and Python 3.15.1 and 3.14.7 on the maintainer's
Windows machine.
The short version: Python 3.15 and Node 26 needed nothing but pins and four
file encodings. TypeScript 7 runs every type-check it can, but cannot yet
replace TypeScript 6, which stays installed beside it.
## Where each version lives now
| Runtime | Version | Written in | Repeated in | Held together by |
| --- | --- | --- | --- | --- |
| Node.js | 26 | `web/.node-version` | the five `setup-node` steps (quoted literals), `engines.node`, the `@types/node` major | `web/shared/toolchain.test.ts` |
| Node.js (Cloudflare build) | 26 | the Worker's dashboard: build variable `NODE_VERSION` | — | nothing; `docs/DEPLOYMENT.md` says to change it with the file |
| Python | 3.15 | every `setup-python` step (18) | `sonar.python.version`, the `--python-version` in `requirements.txt`'s header | `web/shared/toolchain.test.ts` |
| Python (CodeQL) | 3.14 | `codeql.yml` | — | named in the test's `PYTHON_EXCEPTIONS` |
| TypeScript | 7.0.x and 6.0.x | `web/package.json`: `@typescript/native` (`npm:typescript@~7.0.2`) and `typescript` (`^6.0.3`) | `.github/dependabot.yml` ignores | `web/shared/toolchain.test.ts` |
Web CI now also runs on `.github/workflows/**` and `.sonarcloud.properties`, so
a pull request that moves only a pin still meets the test. The test was proven
by breaking one pin at a time - one workflow's Python, `web/.node-version`
alone, a `setup-node` switched to `node-version-file` - and each failed it with
the file named. That also closes the
same hole for `web/shared/pipeline.test.ts`, which reads the workflows for the
`data-write` group and never ran on a workflow-only change.
## TypeScript 7
### What 7.0 is
TypeScript 7.0 (2026-07-08, `typescript@7.0.2`) is the compiler ported to Go:
`tsc` is a native binary from a per-platform optional package
(`@typescript/typescript-<os>-<arch>`), started by a small ESM launcher. It has
**no JavaScript API**; one is planned for 7.1 (`7.1.0-beta` is out). Every
option 7.0 removes - `target: es5`, `downlevelIteration`, `moduleResolution`
`node10`/`classic`, `module` `amd`/`umd`/`systemjs`/`none`, `baseUrl`,
`esModuleInterop`/`allowSyntheticDefaultImports: false`, `alwaysStrict: false`,
`module Foo {}` namespaces, import `assert`, `no-default-lib` - was already a
deprecation error in 6.0, and its defaults (`strict`, `types: []`,
`rootDir: .`, `noUncheckedSideEffectImports`) arrived in 6.0 too.
### What it meant here
The configuration was already 7-clean. All six hand-written tsconfigs use
`moduleResolution: bundler` and explicit `types`, none sets `baseUrl`, the
generated `.svelte-kit/tsconfig.json` uses relative `paths`, the three
side-effect imports resolve (`vite/client` declares `*.css`), and nothing set
`ignoreDeprecations`. The only stale entry was `"DOM.Iterable"` in the two
admin tsconfigs: an empty file since 6.0, now removed. (7.0.2 still ships it,
so the copy SvelteKit writes into `.svelte-kit/tsconfig.json` is harmless.)
What 7.0 cannot do is serve the tools that need the old API:
- **svelte-check** refuses to start when `typescript` is 7
(`bin/ts-version-check.js`), and reads `typescript` as a library even in its
TypeScript 7 modes.
- **`svelte-kit sync`** imports `typescript` to write the route `$types`.
- `@sveltejs/kit@2.70.3` and svelte-check both declare `typescript`
`^5 || ^6`, and CI's `npm ci` has no fallback for a peer conflict.
The TypeScript team's own guidance is that Svelte, Vue and Astro projects
stay on 6.0 until the API exists. So `typescript` stays 6, and 7 arrives as
the alias svelte-check documents: `"@typescript/native": "npm:typescript@~7.0.2"`.
(`@typescript/native` is not a published package - it is only this alias's
name - and the `@typescript` scope belongs to Microsoft, so nothing else can
appear under it.) The other documented layout, `typescript` aliased to
`@typescript/typescript6`, was rejected: it turns `typescript` itself into an
alias, which Dependabot mishandles (below), and breaks
`require.resolve("typescript/bin/tsc")`.
### How the checks run
| Check | Before | Now |
| --- | --- | --- |
| `check` (app, `tsconfig.json`) | svelte-check, TS 6 | `svelte-check --tsgo`, TS 7 |
| `check:admin` (`admin/tsconfig.json`) | svelte-check, TS 6 | unchanged, TS 6 |
| `admin/tsconfig.node.json`, `admin/tsconfig.test.json`, `tsconfig.worker.json`, `tsconfig.test.json` | `tsc -p`, TS 6 | `node node_modules/@typescript/native/bin/tsc -p`, TS 7 |
Two details decide that table:
- **Both packages declare a `tsc` bin**, so `node_modules/.bin/tsc` is
whichever npm linked last. Every script names TS 7 by path; the test fails
on a bare `tsc`. svelte-check finds TS 7 itself, by the alias's name, and
runs the bin its `package.json` declares.
- **`--tsgo` cannot follow `.svelte` imports from outside its tsconfig's
folder.** It emits every component under the working directory (`web/`)
into `.svelte-kit/.svelte-check`, then rewrites the tsconfig's `include`
relative to that mirror; for `web/admin/tsconfig.json` the rewritten
`src/**/*.svelte` lands on the *app's* components, and admin's imports of
`../src/lib/ui/*.svelte` fall back to the ambient `declare module "*.svelte"`
shim - unchecked props and no error (language-tools #3142 is the same
failure through `package.json#imports`). So the admin stays on TS 6.
`--tsgo-experimental-api` has no such limit but calls itself experimental,
still crashes in some setups (#3095) and breaks on 7.1 (#3149), so it stays
out of CI. That is also why the alias is `~7.0`, not `^7`.
### What was measured
- **Same programs.** `--listFilesOnly` gives the same files under 6.0.3 and
7.0.2 for every config, apart from each compiler's own `lib` files:
`admin/tsconfig.node.json` 250, `admin/tsconfig.test.json` 164,
`tsconfig.worker.json` 50, `tsconfig.test.json` 242, and svelte-check's
overlay (`.svelte-kit/.svelte-check/tsconfig.json`) 1,219.
- **Same verdict.** 0 errors on both, before and after `@types/node` moved
from 22 to 26 (bumped first, still on 6, so a types error would have been
its own).
- **Real checking, proven with planted errors.** A deliberate type error was
put into: a route's `<script>` (`about/+page.svelte`); a wrong `variant` on
`src/lib/ui/Badge.svelte` from `activity/+page.svelte` - the case that would
pass silently if `--tsgo` fell back to the `*.svelte` shim; a universal
`+page.ts`; one file of each `tsc -p` config; and a wrong `variant` in the
admin. TypeScript 7 reported all seven non-admin ones, TypeScript 6 the
admin one, each step exited 1, and `npm run typecheck` stopped at the first.
The same admin check under `--tsgo` instead reported false errors in the
*app's* components (`Cannot find module '$lib/...'`, `Module '"*.svelte"' has
no exported member ...`) - the mis-mapping described above, observed.
- **Faster.** The four `tsc -p` checks: 6.0 s on TypeScript 6, 0.5 s on 7.
The app's svelte-check: 7.2 s in its TypeScript 6 mode, about 3 s with
`--tsgo` (most of it svelte2tsx and `svelte-kit sync`).
`svelte-kit sync` prints a Vite warning about `configLoader: 'native'` on every
run, here and before this change: Vite 8 is announcing a future default that
`vite.config.ts` is not ready for (`__dirname`, extensionless imports). It is
not caused by TypeScript 7 or Node 26; see "Left for later".
### Dependabot
`typescript` majors were already ignored; the reason is now written down
(7 would break svelte-check and kit's peer range). The alias is ignored
outright: dependabot-core does not resolve `npm:` aliases reliably (#16488,
open), and would either fail on a package that does not exist or try to
"update" it as `typescript`. Bump the two together by hand.
## Node.js 26
26.0.0 shipped on 2026-05-05 and becomes LTS on 2026-10-28; 26.12.1 is current.
Its removals (`http.Server.prototype.writeHeader`, the `_stream_*` modules,
`--experimental-transform-types`) and new runtime deprecations (DEP0190
`args` with `shell`, DEP0203/DEP0204 `CryptoKey` into `node:crypto`, DEP0205
`module.register()`, DEP0201 `Duplex.toWeb` `type`) touch nothing here: no
`child_process`, no `module.register`, no `url.parse`, no legacy `util` or
`Buffer` constructor, no `--experimental-*` flag anywhere in `web/`. No `.ts`
file is run by Node directly, so 26's type stripping never meets the two
classes with parameter properties (`worker/testing/sqlite-d1.ts`,
`admin/src/lib/api.ts`). All 482 `engines` ranges in the lockfile accept 26.
Two runtime notes:
- `node:sqlite`'s `DatabaseSync` (the in-memory D1 for tests) is
documentation-deprecated in favour of `Database` (DEP0210), but
`@types/node@26` declares only `DatabaseSync`, so it stays.
- Node 26 returns `undefined` for `localStorage` without
`--localstorage-file`, and prints an `ExperimentalWarning` when code touches
it. Every read in the app is inside a try/catch or behind `typeof window`;
the warning in a test or prerender log is noise.
The whole Web CI sequence passes on Node 26.12.1 from a clean
`npm ci --ignore-scripts`: the type-check, all 576 tests, the build and
`verify-dist --web`, `wrangler deploy --dry-run`, knip (its report unchanged
from before the upgrade), and the Tauri-flavour build with `verify-dist
--tauri`. The lockfile still has exactly three packages with install scripts.
The pins: `web/.node-version` (new, `26`), the five `setup-node` steps
(`'24'` → `'26'`), `engines.node` (`>=26`, advisory: npm warns, nothing
enforces it) and `@types/node` `^22.20.5` → `^26.6.5`. The steps keep quoted
literals rather than `node-version-file` because `release-android.yml` checks
out the tag it rebuilds, and every tag older than this change has no
`web/.node-version`. Cloudflare's build image documents `NODE_VERSION`,
`.nvmrc` and `.node-version`, but not which directory it reads or which wins,
so the dashboard variable stays and `docs/DEPLOYMENT.md` records it.
## Python 3.15
3.15.0 shipped on 2026-10-09. The changes that could have mattered:
- **PEP 686: UTF-8 Mode is the default.** `open()` without an `encoding`
now writes UTF-8 on Windows too. Four writes in `scripts/` had none:
`check_dead_links.py` (the dead-link log), `top_online.py` and
`top_offline.py` (the leaderboards) and `core/data_store.py`
(`clear_temp()`, an empty string). Under 3.14 on this machine the default
is `cp1252`, which cannot encode the leaderboards' 🎮, so the first three
crashed on Windows; CI on Linux already wrote UTF-8, so no committed output
changes. All four now name `encoding="utf-8"`, and an AST scan finds no
text-mode `open`/`read_text`/`write_text` without one.
- **Removals** (`sre_*`, `glob.glob0/glob1`, `PurePath.is_reserved`,
`platform.java_ver`, `CGIHTTPRequestHandler`, `typing.no_type_check_decorator`,
the `NamedTuple` keyword form, `load_module()`...) and **`strptime` refusing
`%d` without a year**: none used. Every `strptime` format here has `%Y`;
every "now" is timezone-aware; nothing uses asyncio, threading,
multiprocessing, subprocess or `locale`.
- **Dependencies** install unchanged with `--require-hashes --only-binary :all:`:
charset-normalizer 3.5.2 (the only compiled one) has cp315 wheels for every
platform, already hashed in `requirements.txt`; the rest are py3-none-any,
and pytest 9.1.1 declares 3.15. `uv pip compile --universal` produces the
same lock for `--python-version 3.12` and `3.15`, so only the header moved.
- **A new Unicode database** could have changed what `core/normalize.py`
writes (NFC, `casefold`, the `[^\W\d_]` letter class) and so rewritten
shards and forced every reader to re-download. It does not: a full
`save_main(load_main())` on a copy of the data under 3.15 leaves all 36 files
(13 shards, `index.json`, the blocklist, the overrides,
`scripts/removed_games.jsonl`) byte-identical to HEAD, exactly as under 3.14.
Measured on 3.15.1: the 299 tests pass with `-X warn_default_encoding
-W error::EncodingWarning -W error::DeprecationWarning`; `edit_game.py --check`
and `delete_game.py --check` pass; vulture and pip-audit run. pip-audit flagged
`certifi 2026.10.18` (GHSA-6q48-6c7w-9gw2: eMudhra's `emSign ECC Root CA - G3`
had intermediates with compromised keys). 2026.10.18 had in fact dropped every
emSign root, but the advisory's range covers it; 2026.10.19 restores the three
unaffected ones and keeps G3 out. It went in on the same branch, in a commit of
its own, with `uv pip compile`'s hashes for both of its files.
CI: sixteen `setup-python` steps moved from `'3.12'` to `'3.15'`; the
`updater-json` job of `release-desktop.yml`, which ran the image's `python3`,
now sets up 3.15 like the rest. `codeql.yml` alone uses 3.14: CodeQL's
supported-languages page lists Python up to 3.14 and its extractor runs on
that interpreter. The pipeline uses no 3.15-only syntax, so nothing goes
unparsed. `sonar.python.version` is 3.15; sonar-python knows 3.15.
## Next time
**Node.** Change `web/.node-version`; the test then names every place that
must follow: the five `setup-node` literals, `engines.node` and the
`@types/node` range. Change the dashboard's `NODE_VERSION` in the same breath.
The `@types/node` major is held back by Dependabot on purpose - it follows the
runtime, not the newest Node.
**Python.** Change `sonar.python.version`; the test names every `setup-python`
step and the `requirements.txt` header that must follow. Before merging, check
the lock still installs (`pip install --require-hashes --only-binary :all:`
on the new version: a compiled dependency without wheels fails here), run the
suite with encoding and deprecation warnings as errors, and repeat the
no-churn check: copy `data/data_*.jsonl`, `index.json`, `blocklist.jsonl`,
`overrides/` and `scripts/removed_games.jsonl` into a scratch folder with the
same layout, run `save_main(load_main())` there (the data paths are
relative - never from the repo root), and compare every file with HEAD.
Revisit the CodeQL exception: drop it when CodeQL lists the pipeline's
version (the test fails if the exception equals the main version).
**TypeScript.** TypeScript 6 goes when svelte-check accepts TypeScript 7 on
its own (and `svelte-kit sync` has a 7 path) - the plan is to do it with
TypeScript 7.1, and [17-typescript-7.1.md](17-typescript-7.1.md) is the
runbook: the conditions and how to check them, the steps, and the evidence to
collect. Until then, move `@typescript/native` within 7.0.x by hand, and to 7.1
only once svelte-check supports it.
## Left for later
- **SvelteKit 3**: its own migration (the `cookie` override, `#lib` imports -
and #3142 above).
- Four workflows still use `actions/checkout@v4` and `actions/setup-python@v5`
(mark-dead-games, snapshot-daily, top-offline, top-online); they install
3.15 fine.
- `web/worker-configuration.d.ts` is stale (`IMG_MINT_PER_TICK: "10"` against
`"40"` in `wrangler.jsonc`, runtime types from workerd 1.20260908.1): rerun
`npm run cf:types`.
- Eleven tests use `__dirname`, which works only because Vitest injects it;
Vitest 6 may stop. The new test uses `import.meta.url`.
- Workers Builds' watch paths in the dashboard (include `*`) do not match
`docs/DEPLOYMENT.md`, so every bot data commit deploys.
- Vite's coming native config loader: `vite.config.ts` uses `__dirname` and
imports `./build/game-seeds` and `./build/legal-versions` (and through them
`src/lib/game-seed`, `src/lib/legal`, `./schema`) without extensions; Vite 8
warns on every `svelte-kit sync`. Before a Vite major makes `native` the
default, use `import.meta.dirname` and add the extensions.
## Sources
- TypeScript: [Announcing TypeScript 7.0](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/),
[Announcing TypeScript 6.0](https://devblogs.microsoft.com/typescript/announcing-typescript-6-0/),
[typescript-go CHANGES.md](https://github.com/microsoft/typescript-go/blob/main/CHANGES.md).
- svelte-check: [README](https://github.com/sveltejs/language-tools/tree/master/packages/svelte-check),
issues [#3063](https://github.com/sveltejs/language-tools/issues/3063),
[#3142](https://github.com/sveltejs/language-tools/issues/3142),
[#3149](https://github.com/sveltejs/language-tools/issues/3149),
[#3095](https://github.com/sveltejs/language-tools/issues/3095),
[#3120](https://github.com/sveltejs/language-tools/issues/3120).
- Node.js: [26.0.0 release notes](https://nodejs.org/en/blog/release/v26.0.0),
[deprecations](https://nodejs.org/api/deprecations.html).
- Python: [What's new in Python 3.15](https://docs.python.org/3.15/whatsnew/3.15.html).
- Tools: [CodeQL supported languages](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/),
[Workers Builds build image](https://developers.cloudflare.com/workers/ci-cd/builds/build-image/),
[dependabot-core #16488](https://github.com/dependabot/dependabot-core/issues/16488).
+175
View File
@@ -0,0 +1,175 @@
# TypeScript 7.1 — the full switch, prepared
## Why this note exists
Since 2026-10-22 this repository runs TypeScript 7 for every type-check it
can, with TypeScript 6 installed beside it for the tools that need a
JavaScript API 7.0 does not have ([16-toolchain-2026.md](16-toolchain-2026.md)
has the assessment and the evidence). The maintainer's decision the same day:
when TypeScript 7.1 ships, move to TypeScript 7 completely - one compiler,
no TypeScript 6, the admin checked by 7 as well. This note is the springboard
for that day: what has to be true first, how to check it, the steps, and how
to prove the result. Nothing in it is done yet.
## Where things stand (2026-10-22)
- **TypeScript 7.1.0-beta** came out on 2026-10-20
([announcement](https://devblogs.microsoft.com/typescript/announcing-typescript-7-1-beta/)).
The release candidate is planned "in about a month", the final release
"shortly thereafter". 7.1 brings:
- **the first API of the Go compiler**, split into entry points:
`typescript/sync`, `typescript/async`, `typescript/fs`, `typescript/ast`,
`typescript/ast/is`, `typescript/ast/factory`. It is a new design, not the
TypeScript 6 API; 7.0.2's `typescript/unstable/*` paths were its preview;
- **content mappers**: a package registered in a tsconfig's
`contentMappers` turns a non-TypeScript file (`.svelte`) into a virtual
TypeScript file that maps back to the original. `tsc` runs them only with
`--runExternalCode`, since they are external executables;
- stricter distributive conditional types and regenerated DOM types (both
can surface new errors), a stable `es2026` target and lib, import
attributes in ambient modules, and source phase imports.
- **Svelte's side is not ready.** language-tools PR
[#3111](https://github.com/sveltejs/language-tools/pull/3111) adds
`@sveltejs/ts-content-mapper`, for editors first; svelte-check support is to
be "a separate PR". `svelte-check --tsgo-experimental-api` crashes on
7.1.0-beta ([#3149](https://github.com/sveltejs/language-tools/issues/3149)),
and [#3063](https://github.com/sveltejs/language-tools/issues/3063)
("Typescript 7 crashes svelte2tsx and svelte-check") is still open.
- **SvelteKit**: `@sveltejs/kit@2.70.3` declares `typescript` `^5.3.3 || ^6.0.0`,
and `svelte-kit sync` builds the route `$types` with the TypeScript 6 API
(`ts.createSourceFile` in `src/core/sync/write_types/index.js`). Kit 3.1.0
declares `typescript ^6.0.0`.
- **This repository**: `typescript` is `^6.0.3`, TypeScript 7 is the alias
`"@typescript/native": "npm:typescript@~7.0.2"` (held to 7.0.x so a 7.1
install cannot sneak in under svelte-check), and:
| Check | Compiler today |
| --- | --- |
| `check` - svelte-check `--tsgo`, `tsconfig.json` (the app) | TypeScript 7 |
| `check:admin` - svelte-check, `admin/tsconfig.json` | **TypeScript 6** (`--tsgo` mis-maps a tsconfig outside the workspace root) |
| `tsc -p` × 4 (`admin/tsconfig.node.json`, `admin/tsconfig.test.json`, `tsconfig.worker.json`, `tsconfig.test.json`) | TypeScript 7, called by path |
| `svelte-kit sync` (route `$types`) | TypeScript 6 API |
| WebStorm's language service | TypeScript 6 (`web/node_modules/typescript/lib`) |
## Start when all of these are true
| # | Condition | How to check |
| --- | --- | --- |
| 1 | TypeScript 7.1.0 (or later) is `latest` on npm | `npm view typescript dist-tags` |
| 2 | svelte-check accepts `typescript@7` on its own: no TypeScript 6 required, no "experimental" flag | `npm view svelte-check version peerDependencies`; after a trial install, `node_modules/svelte-check/bin/ts-version-check.js` must not throw for 7; its README's TypeScript 7 section |
| 3 | svelte-check's TypeScript 7 mode checks a tsconfig that is not at the workspace root, and imports of `.svelte` files from outside it - the admin's case | the planted-error check below, on `admin/tsconfig.json` |
| 4 | `svelte-kit sync` writes the route `$types` with TypeScript 7 installed as `typescript`, and kit's peer range allows it | `npm view @sveltejs/kit@2 peerDependencies`; after a trial install, `.svelte-kit/types/**/$types.d.ts` still exists (32 files today) and `src/routes/games/[appid]/+page.ts` still type-checks its `./$types` import |
| 5 | the language-tools issues above are closed or answered: #3063, #3149, #3142 (`.svelte` through `package.json#imports`) | `gh issue view <n> -R sveltejs/language-tools` |
| 6 | (dev comfort, not a blocker) WebStorm or VS Code can serve TypeScript 7 | the IDE's TypeScript settings |
If conditions 2-4 hold only through content mappers, that is fine: the steps
below say where they go.
## The switch, step by step
Work on a branch; every step is reversible by restoring `web/package.json`,
`web/package-lock.json` and the files named.
1. **Record the baseline** on the current setup (commands in "Proving it"
below): the knip report, the four `tsc` timings, `--listFilesOnly` counts
per config, and `npm test` totals.
2. **Packages** (`web/`, always with `--ignore-scripts`):
- `npm install -D --ignore-scripts typescript@^7.1.0`
- `npm uninstall --ignore-scripts @typescript/native`
- only if svelte-check's docs ask for it: `npm install -D --ignore-scripts @sveltejs/ts-content-mapper`
- bump `svelte-check` (exact pin) and, if needed, `@sveltejs/kit` - kit's
exact version also keys the `cookie` override in `package.json`, which
must be re-keyed in the same change (CLAUDE.md, the GHSA-pxg6-pf52-xh8x
bullet).
3. **Scripts** (`web/package.json`):
- the four `node node_modules/@typescript/native/bin/tsc -p …` and
`typecheck:worker` go back to plain `tsc -p …` - with one TypeScript
installed, `node_modules/.bin/tsc` is unambiguous again;
- `check` and `check:admin` take whatever svelte-check then documents (no
flag, `--tsgo`, or a content-mapper mode). `check:admin` must move to
TypeScript 7 too - that is the point of the switch.
4. **tsconfigs**: if svelte-check or `tsc` need a content mapper, add to the
tsconfig that checks `.svelte` files (`tsconfig.json` / `admin/tsconfig.json`)
```jsonc
"contentMappers": [{ "package": "@sveltejs/ts-content-mapper", "extensions": [".svelte"] }]
```
and remember `tsc` then needs `--runExternalCode`. Fix what 7.1's stricter
distributive conditional types and new DOM types report, in code. Moving
`target`/`lib` to `es2026` is optional and separate.
5. **Dependabot** (`.github/dependabot.yml`): drop the `@typescript/native`
ignore; keep the `typescript` major ignore (it then holds back 8) and
rewrite its comment.
6. **The drift test** (`web/shared/toolchain.test.ts`, `describe("TypeScript")`):
`typescript` matches `^7.`, `@typescript/native` is absent, and the
"never calls a bare tsc" rule goes (or becomes "no second TypeScript
package").
7. **Words**: rewrite CLAUDE.md's "TypeScript is two packages, on purpose"
bullet as one package (keep whatever svelte-check mode and content-mapper
rule is load-bearing); `docs/dev_env.md` + `docs/i18n/vi/dev_env.md`
(TypeScript row), `docs/THIRD_PARTY.md` (svelte-check row), `web/README.md`
(Checks), `docs/DEPLOYMENT.md` (Checks paragraph), `docs/ACKNOWLEDGEMENTs.md`
and `web/src/routes/about/+page.svelte` ("TypeScript 7"), and a CHANGELOG
entry. Close this note with a dated "Done" section, as 16 records its own.
8. **IDE**: point WebStorm/VS Code at TypeScript 7 if it can; otherwise note
that editor diagnostics come from whatever the IDE bundles.
## Proving it
The same evidence 16 collected for 7.0 - each piece catches a different way of
being wrong.
- **0 errors is not enough. Plant errors and see each one reported**, with
every step exiting non-zero and `npm run typecheck` stopping at the first.
The sites used on 2026-10-22, all marked with one token so they come out
cleanly (delete the lines containing it):
| File | Planted | Must be caught by |
| --- | --- | --- |
| `src/routes/about/+page.svelte` | `const x: number = "…"` in `<script lang="ts">` | `check` |
| `src/routes/activity/+page.svelte` | `<Badge variant="nope">` - a wrong prop on `src/lib/ui/Badge.svelte`; passes silently if `.svelte` imports fall back to the `*.svelte` shim | `check` |
| `src/routes/games/[appid]/+page.ts` | the same const | `check` |
| `admin/src/views/RemoveView.svelte` | `<Badge variant="nope">` - admin importing `../src/lib/ui` | `check:admin` (**on TypeScript 7 this time**) |
| `admin/vite.config.ts` | the const | `tsc -p admin/tsconfig.node.json` |
| `admin/security.test.ts` | the const | `tsc -p admin/tsconfig.test.json` |
| `worker/routes/updates.ts` | the const | `tsc -p tsconfig.worker.json` |
| `shared/sort.test.ts` | the const | `tsc -p tsconfig.test.json` |
On 7.0 with `--tsgo`, the admin check reported false errors in the *app's*
components instead of the planted one - the failure the switch must not
bring back.
- **Same programs.** `tsc -p <config> --listFilesOnly` under the old and the
new setup, minus each compiler's own `lib` files; on 2026-10-22:
`admin/tsconfig.node.json` 250, `admin/tsconfig.test.json` 164,
`tsconfig.worker.json` 50, `tsconfig.test.json` 242, svelte-check's overlay
1,219.
- **The whole Web CI sequence from a clean install**: `npm ci --ignore-scripts`,
`npm run typecheck`, `npm test` (576 tests on 2026-10-22), `npm run build`,
`node scripts/verify-dist.mjs --web`, `npm run cf:check`, `npm run knip`
(diff against the baseline report), and
`TAURI_ENV_PLATFORM=linux npm run build:desktop` + `node scripts/verify-dist.mjs --tauri`.
- **Lockfile**: still exactly three entries with `hasInstallScript`
(fsevents, workerd, wrangler's esbuild); TypeScript 7's per-platform
packages all `optional` with `os`/`cpu`; `npm ls typescript` shows one
version.
- **Speed**, for the changelog: on 2026-10-22 the four `tsc` checks took
6.0 s on TypeScript 6 and 0.5 s on 7.0; the app's svelte-check 7.2 s on 6
and about 3 s with `--tsgo`; the admin's 4.6 s on 6.
## If it is not ready
Stay on the two-package setup; it is complete and tested, and nothing about
it expires. Move `@typescript/native` within 7.0.x by hand. Do not take 7.1
under the alias for the app alone while svelte-check's experimental mode is
broken on it (#3149) - `--tsgo` (the `tsc` command) may work, but prove it
with the planted errors before trusting it.
## Decide on the day
- **SvelteKit 3 first or after?** Kit 3 moves `$lib` to the `#lib` subpath
import, which `--tsgo` resolved to the `*.svelte` shim
([#3142](https://github.com/sveltejs/language-tools/issues/3142)), and needs
`cookie` 2. Whichever goes first, re-run the planted-error table after the
second.
- The unrelated leftovers in 16's "Left for later" (Vite's native config
loader, `__dirname` in tests, `worker-configuration.d.ts`) can ride along if
the branch is open anyway, each as its own commit.
+1 -1
View File
@@ -311,7 +311,7 @@ See [docs/DEPLOYMENT.md](../docs/DEPLOYMENT.md) and
## Checks
```bash
npm run typecheck # builds admin/, then svelte-check (app + admin) and tsc (Worker, tests)
npm run typecheck # builds admin/, then svelte-check (app on TS 7, admin on TS 6) and TS 7's tsc (Worker, tests)
npm test # vitest
npm run knip # dead code and dependencies
npm run build # site, then admin/
+1 -1
View File
@@ -6,7 +6,7 @@ This file documents how to build and run the Tauri wrapper around the SvelteKit
| Tool | Version | Install |
| ---------- | ------------------- | ----------------------------------------------------------- |
| Node.js | ≥ 22 (LTS) | <https://nodejs.org/> |
| Node.js | 26 (LTS), as in `web/.node-version` | <https://nodejs.org/> |
| Rust | stable (via rustup) | <https://rustup.rs/> |
| npm | bundled with Node | comes with Node |
| Tauri CLI | 2.x | invoked via `npx tauri` or `npm run tauri ...` |
+1 -1
View File
@@ -48,7 +48,7 @@
const DEPS = [
{ name: "Svelte 5", role: "about.deps.svelte", href: "https://svelte.dev/", licence: "MIT" },
{ name: "SvelteKit 2", role: "about.deps.sveltekit", href: "https://svelte.dev/docs/kit", licence: "MIT" },
{ name: "TypeScript 6", role: "about.deps.typescript", href: "https://www.typescriptlang.org/", licence: "Apache-2.0" },
{ name: "TypeScript 7 + 6", role: "about.deps.typescript", href: "https://www.typescriptlang.org/", licence: "Apache-2.0" },
{ name: "Vite 8 / Rolldown", role: "about.deps.vite", href: "https://vitejs.dev/", licence: "MIT" },
{ name: "Tailwind CSS 4", role: "about.deps.tailwind", href: "https://tailwindcss.com/", licence: "MIT" },
{ name: "Bits UI", role: "about.deps.bitsUi", href: "https://bits-ui.com/", licence: "MIT" },