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

@@ -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
 

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"
+      }
     }
   }
 }

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"
   }
-}
+}

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"]
+}