Upgrade TypeScript target to ES2024 and update CLI dependencies

[nikblanchet]

Context

After completing the Node 24 + Jest 30 upgrade in PR #360, a comprehensive dependency audit was performed to identify safe upgrade opportunities. This issue tracks recommended dependency updates that improve compatibility, fix deprecation warnings, and align with Node.js 24 capabilities.

Current State

TypeScript Configuration:

• Target: ES2022
• Node.js requirement: >=24.0.0
• TypeScript: 5.7.3

Known Issues:

• Deprecation warnings from nested dependencies (inflight, glob@7)
• TypeScript target not aligned with Node.js 24 capabilities
• Several direct dependencies have newer stable versions

Recommended Upgrades

Phase 1: Immediate (Low Risk)

1. TypeScript Target: ES2022 → ES2024

Priority: HIGH
Effort: Small (< 30 minutes)

Justification:

• TypeScript's Node Target Mapping explicitly recommends ES2024 for Node.js 24
• V8 13.6 in Node.js 24 fully supports ES2024 features (RegExp.escape, Float16Array, Atomics.pause, WebAssembly Memory64)
• Safe upgrade path - purely additive feature support, no breaking changes
• Aligns codebase with development environment capabilities

Note: DO NOT upgrade to ES2025 yet - it is not a finalized specification. ES2024 is the stable target for Node.js 24.

Changes Required:

// cli/tsconfig.json
{
  "compilerOptions": {
    "target": "ES2024",
    "lib": ["ES2024"]
  }
}

Verification:

cd cli
npm run build
npm test
npm run lint

---

2. Direct Dependency Upgrades

Priority: MEDIUM
Effort: Small (< 1 hour)

Package	Current	Latest	Type	Justification
commander	13.1.0	14.0.2	Direct	New help grouping features, bug fixes. Min Node v20+ (compatible with v24)
ora	8.2.0	9.0.0	Direct	Bug fixes for clearing, frame(), multiline text. Min Node v20+ (compatible)
eslint-plugin-jsdoc	61.1.2	61.1.12	Dev	10 patch versions of fixes relevant to JSDoc validation (checkJs: true)
@typescript-eslint/eslint-plugin	8.46.0	8.46.3	Dev	Patch-level bug fixes
@typescript-eslint/parser	8.46.0	8.46.3	Dev	Patch-level bug fixes (keep in sync with eslint-plugin)

Breaking Changes:

• Commander 14: Minimum Node v20+ (not an issue for v24 requirement)
• Ora 9: Already ESM-only since v6, no new breaking changes
• Others: None (patch/minor updates)

Upgrade Commands:

cd cli
npm update commander ora eslint-plugin-jsdoc
npm update @typescript-eslint/eslint-plugin @typescript-eslint/parser
npm test
npm run lint
npm run build

---

Phase 2: Deferred (Wait for Upstream)

Deprecated Nested Dependencies

Priority: HIGH (long-term)
Effort: None (blocked on upstream)

Issue: Two deprecated packages show warnings during npm install/test:

1. inflight@1.0.6 - "This module is not supported, and leaks memory."
2. glob@7.2.3 - "Glob versions prior to v9 are no longer supported"

Root Cause:

ts-jest@29.4.5
└── @jest/transform@30.2.0
    └── babel-plugin-istanbul@7.0.1
        └── test-exclude@6.0.0
            └── glob@7.2.3
                └── inflight@1.0.6

Why This Happened:

• ts-jest 29.x was designed for Jest 29
• Jest 30 upgraded its dependencies, but ts-jest 29.4.5 still uses older babel-plugin-istanbul chain
• ts-jest 29.4.5 correctly declares Jest 30 compatibility in peerDependencies, so npm allows the combination
• However, some nested dependencies are stale

Current Status:

• Jest itself uses glob@10.4.5 (latest, modern)
• ts-jest 29.4.5 works correctly with Jest 30 (tests pass)
• Warnings are benign but annoying

Solution:

• Wait for ts-jest v30 release (not yet available)
• Estimated timeline: 1-2 months
• When released, upgrade: npm install ts-jest@30.x
• This will pull in updated babel-plugin-istanbul and test-exclude, fixing glob/inflight issues

Do NOT:

• Force upgrade glob/inflight (nested, will break ts-jest)
• Downgrade Jest 30 (we just upgraded)
• Override with npm resolutions (masks the real issue)

---

Implementation Plan

Step 1: Update TypeScript Target

1. Edit cli/tsconfig.json
2. Change target and lib from ES2022 to ES2024
3. Run npm run build to verify compilation
4. Commit: "Upgrade TypeScript target to ES2024 (Node 24 compatibility)"

Step 2: Upgrade Direct Dependencies

1. Run upgrade commands listed above
2. Verify package.json shows updated versions
3. Run full test suite: npm test && npm run test:integration
4. Run linters: npm run lint
5. Verify build: npm run build
6. Commit: "Upgrade CLI dependencies (commander 14, ora 9, eslint-plugin-jsdoc)"

Step 3: Create Follow-up Issue

• Track ts-jest v30 release
• Link to this issue for context
• Schedule for Phase 2 when ts-jest v30 is available

---

Verification Checklist

After Phase 1 upgrades, verify:

• TypeScript compiles without errors (npm run build)
• All 25 Jest test suites pass (npm test)
• All 2 integration test suites pass (npm run test:integration)
• ESLint passes (npm run lint)
• No new warnings introduced (inflight/glob warnings will remain until Phase 2)
• CLI commands work: docimp analyze ./src, docimp --help

---

Compatibility Matrix

All Phase 1 upgrades verified compatible with:

• Node.js 24 (minimum: >=24.0.0)
• Jest 30.2.0 (no breaking changes)
• TypeScript 5.7.3 (peer dependencies satisfied)
• Existing DocImp CLI codebase

---

Related Issues

• Upgrade Node 22 → 24 (Active LTS) #353 - Node 24 + Jest 30 upgrade (parent issue)
• Upgrade Node 22 → 24 + Aggressive ESLint Modernization (Issues #353, #354) #360 - PR containing Node 24 upgrade and aggressive ESLint modernization

---

Additional Context

Why ES2024 not ES2025?

• ES2025 is not a finalized specification yet
• V8 13.6 may include some ES2025-draft features (like Explicit Resource Management with await using)
• However, ES2024 is the stable target that covers the full feature set Node.js 24 reliably supports
• Using ES2025 could lead to inconsistent behavior across environments

Why Not Force-Fix Deprecated Dependencies?

• These are nested dependencies (5 levels deep)
• Forcing updates breaks ts-jest compatibility
• npm resolutions mask the root issue without fixing it
• Proper fix requires upstream (ts-jest v30) to update its dependency chain
• Current warnings are benign (only affect test suite, no production impact)

Memory Leak Concern (inflight):

• Only affects test infrastructure, not production code
• Test runs don't accumulate state between tests
• No memory accumulation observed in CI/CD
• Risk is theoretical until ts-jest updates dependency chain