Release gate 3 — restore reproducible VS Code install, lint, and build #95

1. Problem / evidence

Reproduced 2026-10-03 (Node v24.19.0, npm 11.17.0) from a clean copy of vscode-extension/package.json + package-lock.json:

npm ci --ignore-scripts   -> exit 1
npm error ERESOLVE could not resolve
npm error While resolving: @typescript-eslint/eslint-plugin@6.21.0
npm error Found: @typescript-eslint/parser@8.70.1
npm error peer @typescript-eslint/parser@"^6.0.0 || ^6.0.0-alpha" from @typescript-eslint/eslint-plugin@6.21.0

Declared devDependencies: typescript ^7.0.2, eslint ^10.11.0, @typescript-eslint/eslint-plugin ^6.0.0, @typescript-eslint/parser ^8.70.1; lint script eslint src --ext ts (legacy flag, removed in flat config).

Dependabot #85 bumps only the plugin to 8.70.1; TypeScript 7.0.2 is outside the supported TypeScript range of current @typescript-eslint (verified: @typescript-eslint/eslint-plugin@8.71.0 peers typescript >=4.8.4 <6.1.0, eslint ^8.57.0 || ^9.0.0 || ^10.0.0), so #85 alone is insufficient.

Additional gaps found during PR 1 (#102) and its independent review (pre-existing on main):

• No ESLint config file exists in vscode-extension (no eslint.config.* or .eslintrc*), so npm run lint exits 2 under ESLint 10 regardless of dependencies.
• vsce package fails: ERROR @types/vscode ^1.138.0 greater than engines.vscode ^1.85.0. The extension cannot be packaged until @types/vscode and engines.vscode agree.
• No engines.node / .nvmrc.

2. Outcome

From a clean checkout, npm ci, compile/typecheck, and ESLint pass with a mutually supported TypeScript/ESLint toolchain, enforced in CI against the exact lockfile.

3. Scope

vscode-extension/package.json, package-lock.json, ESLint config (flat eslint.config.*), tsconfig.json if needed, .nvmrc/engines, CI job (with Release gate 2).

4. Non-goals

• No extension behavior/security changes (Release gate 5).
• No unrelated dependency upgrades beyond what peer compatibility requires.

5. Dependencies

Unblocks Release gate 2 PR 3 (Node CI aggregate relevance) and Release gate 5 (security PRs need a working build).

6. PR breakdown

1. fix(vscode): align TypeScript and typescript-eslint peer ranges — pick versions from verified peer ranges; regenerate lockfile.
2. build(vscode): migrate lint configuration and scripts to the supported ESLint format — flat config; drop --ext.
3. ci(vscode): enforce clean install, compile, lint, and audit (coordinated with Release gate 2).
4. chore(deps): reconcile or supersede Node Dependabot PRs — close chore(deps-dev): bump @typescript-eslint/eslint-plugin from 6.21.0 to 8.70.1 in /vscode-extension #85 as superseded with link; re-evaluate chore(deps-dev): bump @types/node from 26.6.2 to 26.6.3 in /vscode-extension #82; add a Dependabot ignore rule for typescript >=6.1 until typescript-eslint supports it.
5. fix(vscode): align @types/vscode with engines.vscode — either raise engines.vscode (a support-policy decision; document it) or pin @types/vscode to the engine floor; prove with vsce package.

7. Acceptance criteria

• npm ci passes without --force / --legacy-peer-deps.
• Compile/typecheck and ESLint pass with zero newly suppressed findings.
• Node CI job uses the exact lockfile.
• chore(deps-dev): bump @typescript-eslint/eslint-plugin from 6.21.0 to 8.70.1 in /vscode-extension #85 closed as superseded (link) unless it becomes sufficient; chore(deps-dev): bump @types/node from 26.6.2 to 26.6.3 in /vscode-extension #82 re-evaluated after green.
• Supported Node version documented and enforced consistently (engines + CI).
• npx @vscode/vsce package succeeds from a clean checkout.
• Dependabot cannot reintroduce an unsupported TypeScript major.

8. Risks and rollback

Lint migration may surface new findings — fix, do not suppress. Rollback by reverting the PR; the current state is already broken so regression risk is low.

9. Evidence to attach

Clean npm ci/compile/lint logs, peer-range verification output (npm view ... peerDependencies), CI run URL.

10. Labels, milestone, estimate

Labels: javascript, dependencies, bug. Milestone: v0.5.1 Release Readiness. Estimate: 1–2 days.