From 35742c4faead4334e7d54818d089c9794ac4495e Mon Sep 17 00:00:00 2001
From: byrongamatos <xasiklas@gmail.com>
Date: Sat, 16 May 2026 00:29:04 +0200
Subject: [PATCH] infra: add tsconfig, typescript devDep, typecheck script, CI
 step

Adopt JSDoc + // @ts-check + `tsc --noEmit` as a CI/dev-only type
check. No emit step, no runtime dependency: shipped .js files stay
byte-identical, typescript is a devDependency only.

- tsconfig.json: allowJs + checkJs:false so only files carrying an
  explicit `// @ts-check` directive are checked; strict mode; DOM libs.
  `include` matches static/**/*.d.ts so the upcoming ambient contract
  is loaded into the program. moduleDetection is left at the default
  `auto` on purpose -- app.js/highway.js carry no import/export and
  must stay global scripts so cross-file globals resolve.
- package.json: typescript devDep + `npm run typecheck`.
- tests.yml: setup-node + `npm ci` + typecheck step before pytest.
  This also gives the existing JS plugin-API test step an explicit
  Node toolchain.

No file carries `// @ts-check` yet, so typecheck passes trivially.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 11 +++++++++++
 package-lock.json        | 17 ++++++++++++++++-
 package.json             |  8 +++++---
 tsconfig.json            | 13 +++++++++++++
 4 files changed, 45 insertions(+), 4 deletions(-)
 create mode 100644 tsconfig.json

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9445ad7..eb5a18c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -48,6 +48,17 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements.txt -r requirements-test.txt
 
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Typecheck (tsc --noEmit)
+        run: npm run typecheck
+
       - name: Run pytest
         run: pytest
 
diff --git a/package-lock.json b/package-lock.json
index 31332ca..672f8f4 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -9,7 +9,8 @@
       "version": "1.0.0",
       "license": "AGPL-3.0-only",
       "devDependencies": {
-        "@playwright/test": "^1.59.1"
+        "@playwright/test": "^1.59.1",
+        "typescript": "^5.4"
       }
     },
     "node_modules/@playwright/test": {
@@ -74,6 +75,20 @@
       "engines": {
         "node": ">=18"
       }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
     }
   }
 }
diff --git a/package.json b/package.json
index bdcb3d9..81eedbf 100644
--- a/package.json
+++ b/package.json
@@ -8,9 +8,11 @@
     "test:headed": "playwright test --headed",
     "test:debug": "playwright test --debug",
     "test:js": "node --test tests/js/*.test.js 'tests/plugins/*/js/*.test.js'",
-    "install:playwright": "playwright install chromium"
+    "install:playwright": "playwright install chromium",
+    "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@playwright/test": "^1.59.1"
+    "@playwright/test": "^1.59.1",
+    "typescript": "^5.4"
   }
-}
+}
\ No newline at end of file
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000..1121663
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "noEmit": true,
+    "strict": true,
+    "target": "es2022",
+    "lib": ["es2022", "dom", "dom.iterable"],
+    "skipLibCheck": true
+  },
+  "include": ["static/**/*.js", "static/**/*.d.ts"],
+  "exclude": ["static/vendor/**", "node_modules"]
+}