feat(types): migrate test suite and config files to TypeScript (Phase 6) (#588)

* feat(types): migrate test suite and config files to TypeScript (Phase 6)

Rename all 114 test files and 2 helpers from .js to .ts, plus
vitest.config and commitlint.config. Add type annotations to fix
noImplicitAnyLet lint errors. Remove jsToTsResolver vite plugin
(no longer needed). Drop allowJs/checkJs from tsconfig.

* feat(types): migrate scripts and docs examples to TypeScript

Rename 16 scripts and 1 docs example from .js to .ts. Update all
invocations in package.json, CI workflows, and shell scripts to use
node --experimental-strip-types.

Remaining .js files (must stay JS):
- scripts/test.js, scripts/build-wasm.js (Node 20 bootstrap)
- 4 ESM loader hooks (bootstrap .ts support)
- scripts/gen-deps.cjs, src/index.cjs (CJS by design)

* feat(types): drop Node 20, require Node >= 22

- Bump engines.node from >=20 to >=22
- Remove Node 20 from CI test matrix
- Bump native build Node from 20 to 22
- Replace old JS ESM loader hooks with 2 TypeScript hooks
  (ts-resolve-loader.ts + ts-resolve-hooks.ts) that resolve .js→.ts
  import specifiers at runtime
- Remove canStripTypes helper and version guards from tests
- Update src/index.cjs to import('./index.ts') for dev; build step
  produces dist/index.cjs with ./index.js for published package
- Simplify vitest.config.ts to use --experimental-strip-types only
- Update child-process test invocations to use --import loader flag
- Rewrite scripts/gen-deps.cjs as ESM TypeScript
- Rename scripts/build-wasm.js → .ts

Impact: 1 functions changed, 1 affected

* fix(ci): update embedding regression workflow to reference .ts test file (#588)

The test file was renamed from .js to .ts in the Phase 6 migration
but the CI workflow was not updated, causing test discovery to fail.

* fix: tighten Node engines to >=22.6, restore strip-types guard, use replaceAll (#588)

Impact: 1 functions changed, 0 affected

* fix(docs): use version-aware strip-types flag in pre-commit example (#588)

Detect Node version at runtime and select --strip-types (>=23) vs
--experimental-strip-types (22.x), matching the approach in vitest.config.ts.

* fix(types): add TypeScript parameter types to test helpers (#588)

Replace JSDoc-only annotations in fixtures.ts with proper TypeScript
interfaces and typed parameters. Add interfaces and typed parameters
to resolution-benchmark.test.ts helper functions. Eliminates all
noExplicitAny warnings in both files.

Impact: 22 functions changed, 0 affected

* fix(hooks): convert pre-commit-checks.ts from CJS require() to ESM imports (#588)

The file was renamed from .js to .ts but retained CommonJS require() calls.
Since the repo has "type": "module", Node loads .ts files as ESM under
--strip-types, where require is not defined. This caused a silent
ReferenceError swallowed by 2>/dev/null || true in pre-commit.sh,
making all pre-commit checks (cycles, dead exports, diff-impact)
non-functional.

Convert to ESM imports with createRequire for dynamic runtime requires.
Also update the file header comment to reference .ts instead of .js.

* fix(ci): add --import loader to benchmark workflow for Node 22 compatibility (#588)

Benchmark scripts import ./lib/bench-config.js and ./lib/fork-engine.js
but only .ts files exist on disk. Node 22's --experimental-strip-types
does not auto-resolve .js to .ts (that was added in Node 23+). Add
--import ./scripts/ts-resolve-loader.js to all four benchmark invocations
so the ESM loader resolves .js specifiers to their .ts counterparts.

* fix: version-aware strip-types flag in benchmark.yml, update docs (#588)

- Use dynamic STRIP_FLAG selection in all benchmark.yml node invocations
  for forward compatibility with Node 23+ (--strip-types vs
  --experimental-strip-types)
- Update token-benchmark.ts usage docs to include --import loader flag
- Update CLAUDE.md Node version from >= 20 to >= 22.6

* fix: remove unused .ts loader duplicates (#588)

ESM loader hooks must stay as .js files for bootstrap reasons. The .ts
duplicates were never referenced by any CI workflow or package script
and only created confusion about which version to use.

* Revert "fix: remove unused .ts loader duplicates (#588)"

This reverts commit 966ec3e.

* fix(ci): use version-aware strip-types flag in verify-imports step (#588)

* fix(ci): use dynamic strip-types flag in publish workflow (#588)

* fix: remove dead scripts/test.js (#588)

Author: carlos-alm

.github/workflows/benchmark.yml

@@ -89,15 +89,18 @@ jobs:
       - name: Run build benchmark
         if: steps.existing.outputs.skip != 'true'
         run: |
+          STRIP_FLAG=$(node -e "const [M]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
           ARGS="--version ${{ steps.mode.outputs.version }}"
           if [ "${{ steps.mode.outputs.source }}" = "npm" ]; then
             ARGS="$ARGS --npm"
           fi
-          node scripts/benchmark.js $ARGS 2>/dev/null > benchmark-result.json
+          node $STRIP_FLAG --import ./scripts/ts-resolve-loader.js scripts/benchmark.ts $ARGS 2>/dev/null > benchmark-result.json
 
       - name: Update build report
         if: steps.existing.outputs.skip != 'true'
-        run: node scripts/update-benchmark-report.js benchmark-result.json
+        run: |
+          STRIP_FLAG=$(node -e "const [M]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
+          node $STRIP_FLAG scripts/update-benchmark-report.ts benchmark-result.json
 
       - name: Upload build result
         if: steps.existing.outputs.skip != 'true'
@@ -240,15 +243,18 @@ jobs:
         env:
           HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
+          STRIP_FLAG=$(node -e "const [M]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
           ARGS="--version ${{ steps.mode.outputs.version }}"
           if [ "${{ steps.mode.outputs.source }}" = "npm" ]; then
             ARGS="$ARGS --npm"
           fi
-          node scripts/embedding-benchmark.js $ARGS 2>/dev/null > embedding-benchmark-result.json
+          node $STRIP_FLAG --import ./scripts/ts-resolve-loader.js scripts/embedding-benchmark.ts $ARGS 2>/dev/null > embedding-benchmark-result.json
 
       - name: Update embedding report
         if: steps.existing.outputs.skip != 'true'
-        run: node scripts/update-embedding-report.js embedding-benchmark-result.json
+        run: |
+          STRIP_FLAG=$(node -e "const [M]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
+          node $STRIP_FLAG scripts/update-embedding-report.ts embedding-benchmark-result.json
 
       - name: Upload embedding result
         if: steps.existing.outputs.skip != 'true'
@@ -377,15 +383,18 @@ jobs:
       - name: Run query benchmark
         if: steps.existing.outputs.skip != 'true'
         run: |
+          STRIP_FLAG=$(node -e "const [M]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
           ARGS="--version ${{ steps.mode.outputs.version }}"
           if [ "${{ steps.mode.outputs.source }}" = "npm" ]; then
             ARGS="$ARGS --npm"
           fi
-          node scripts/query-benchmark.js $ARGS 2>/dev/null > query-benchmark-result.json
+          node $STRIP_FLAG --import ./scripts/ts-resolve-loader.js scripts/query-benchmark.ts $ARGS 2>/dev/null > query-benchmark-result.json
 
       - name: Update query report
         if: steps.existing.outputs.skip != 'true'
-        run: node scripts/update-query-report.js query-benchmark-result.json
+        run: |
+          STRIP_FLAG=$(node -e "const [M]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
+          node $STRIP_FLAG scripts/update-query-report.ts query-benchmark-result.json
 
       - name: Upload query result
         if: steps.existing.outputs.skip != 'true'
@@ -514,15 +523,18 @@ jobs:
       - name: Run incremental benchmark
         if: steps.existing.outputs.skip != 'true'
         run: |
+          STRIP_FLAG=$(node -e "const [M]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
           ARGS="--version ${{ steps.mode.outputs.version }}"
           if [ "${{ steps.mode.outputs.source }}" = "npm" ]; then
             ARGS="$ARGS --npm"
           fi
-          node scripts/incremental-benchmark.js $ARGS 2>/dev/null > incremental-benchmark-result.json
+          node $STRIP_FLAG --import ./scripts/ts-resolve-loader.js scripts/incremental-benchmark.ts $ARGS 2>/dev/null > incremental-benchmark-result.json
 
       - name: Update incremental report
         if: steps.existing.outputs.skip != 'true'
-        run: node scripts/update-incremental-report.js incremental-benchmark-result.json
+        run: |
+          STRIP_FLAG=$(node -e "const [M]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
+          node $STRIP_FLAG scripts/update-incremental-report.ts incremental-benchmark-result.json
 
       - name: Upload incremental result
         if: steps.existing.outputs.skip != 'true'

.github/workflows/build-native.yml

@@ -60,7 +60,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@stable

.github/workflows/ci.yml

@@ -43,7 +43,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        node-version: [20, 22]
+        node-version: [22]
 
     runs-on: ${{ matrix.os }}
     name: Test Node ${{ matrix.node-version }} (${{ matrix.os }})
@@ -113,7 +113,9 @@ jobs:
           node-version: 22
 
       - name: Verify all dynamic imports resolve
-        run: node scripts/verify-imports.js
+        run: |
+          STRIP_FLAG=$(node -e "const [M]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
+          node $STRIP_FLAG scripts/verify-imports.ts
 
   rust-check:
     runs-on: ubuntu-latest

.github/workflows/embedding-regression.yml

@@ -38,4 +38,4 @@ jobs:
           key: hf-models-minilm-v1
 
       - name: Run embedding regression tests
-        run: npx vitest run tests/search/embedding-regression.test.js
+        run: npx vitest run tests/search/embedding-regression.test.ts

.github/workflows/publish.yml

@@ -142,7 +142,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@stable
@@ -224,7 +224,8 @@ jobs:
           VERSION: ${{ needs.compute-version.outputs.version }}
         run: |
           npm version "$VERSION" --no-git-tag-version --allow-same-version
-          node scripts/sync-native-versions.js --strip
+          STRIP_FLAG=$(node -e "const [M]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
+          node $STRIP_FLAG scripts/sync-native-versions.ts --strip
           echo "Packaging version $VERSION"
 
       - name: Build TypeScript
@@ -405,7 +406,8 @@ jobs:
         run: |
           git checkout -- package-lock.json
           npm version "$VERSION" --no-git-tag-version --allow-same-version
-          node scripts/sync-native-versions.js
+          STRIP_FLAG=$(node -e "const [M]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
+          node $STRIP_FLAG scripts/sync-native-versions.ts
           echo "Publishing version $VERSION"
 
       - name: Build TypeScript

.npmignore

@@ -7,5 +7,5 @@ docs/
 *.db
 .codegraphrc.json
 .versionrc.json
-commitlint.config.js
+commitlint.config.ts
 codegraph-improvements.md

CLAUDE.md

@@ -218,4 +218,4 @@ This repo uses [Greptile](https://greptile.com) for automated PR reviews. After
 
 ## Node Version
 
-Requires Node >= 20.
+Requires Node >= 22.6.

commitlint.config.js commitlint.config.tscommitlint.config.js renamed to commitlint.config.ts

@@ -1,8 +1,8 @@
 /**
- * pre-commit-checks.js — Consolidated pre-commit codegraph checks.
+ * pre-commit-checks.ts — Consolidated pre-commit codegraph checks.
  * Single Node.js process that runs all checks and returns structured JSON.
  *
- * Usage: node pre-commit-checks.js <WORK_ROOT> <EDITED_FILES> <STAGED_FILES>
+ * Usage: node pre-commit-checks.ts <WORK_ROOT> <EDITED_FILES> <STAGED_FILES>
  *
  * Output JSON: { action: "deny"|"allow", reason?: string, context?: string[] }
  *
@@ -12,8 +12,11 @@
  *   3. Diff-impact (informational) — shows blast radius of staged changes
  */
 
-const fs = require('fs');
-const path = require('path');
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
 
 const root = process.argv[2];
 const editedRaw = process.argv[3] || '';
@@ -124,7 +127,7 @@ try {
 
         // Scan for dynamic import() consumers
         const srcDir = path.join(root, 'src');
-        function scanDynamic(dir) {
+        function scanDynamic(dir: string) {
           for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
             if (ent.isDirectory()) { scanDynamic(path.join(dir, ent.name)); continue; }
             if (!/\.(js|ts|tsx)$/.test(ent.name)) continue;

…s/claude-code-hooks/pre-commit-checks.js …s/claude-code-hooks/pre-commit-checks.tsdocs/examples/claude-code-hooks/pre-commit-checks.js renamed to docs/examples/claude-code-hooks/pre-commit-checks.ts docs/examples/claude-code-hooks/pre-commit-checks.js renamed to docs/examples/claude-code-hooks/pre-commit-checks.ts

@@ -48,7 +48,8 @@ fi
 
 # Run all checks in a single Node.js process
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
-RESULT=$(node "$HOOK_DIR/pre-commit-checks.js" "$WORK_ROOT" "$EDITED_FILES" "$STAGED" 2>/dev/null) || true
+STRIP_FLAG=$(node -e "const [M,m]=process.versions.node.split('.').map(Number); console.log(M>=23?'--strip-types':'--experimental-strip-types')")
+RESULT=$(node $STRIP_FLAG "$HOOK_DIR/pre-commit-checks.ts" "$WORK_ROOT" "$EDITED_FILES" "$STAGED" 2>/dev/null) || true
 
 if [ -z "$RESULT" ]; then
   exit 0