refactor(positron): use @posit-dev/positron for Positron types

[dotNomad]

Intent

Resolves #3647.

Publisher hand-maintained a partial copy of the Positron API types.

@posit-dev/positron could not be adopted until now because its published positron.d.ts referenced vscode-dts/ files that were not shipped in the package (posit-dev/positron-api-pkg#4). Version 0.2.7 removes those reference directives, so the package now compiles against our pinned @types/vscode 1.105.0 without skipLibCheck.

Type of Change

• • Bug Fix
• • New Feature
• • Breaking Change
• • Documentation
• • Refactor
• • Tooling

Approach

src/utils/vscode.ts acquires the API through the package's tryAcquirePositronApi() instead of calling the injected acquirePositronApi global directly. That helper does the feature detection and returns undefined outside Positron, so the local declare global block and the try/catch around acquisition both go away; null remains the "already probed" cache sentinel.

The published types are stricter than the hand-written ones in two places: getPreferredRuntime returns LanguageRuntimeMetadata | undefined, and the injected global is typed as possibly-undefined. The latter surfaced an unchecked call in src/test/positron/extension.test.ts, now guarded by inPositron().

The contract tests drop their positron module alias. The mock's job narrows to impersonating the Positron host by injecting acquirePositronApi on globalThis, which means the package's real acquisition logic now runs during contract tests rather than being aliased away. positron.conformance.ts checks the mock against the published package instead of the deleted local declaration.

User Impact

None. Type definitions and API acquisition only, no behavior change.

Automated Tests

Covered by the existing contract tests (interpreter-discovery), the conformance check, and the Positron-only integration suite in src/test/positron/, which exercises the new acquisition path inside a real Positron build.

[posit-connect-projects]

Claude finished @dotNomad's task in 1m 42s —— View job

---

Code Review

• Gather context and read changed files
• Review the refactoring changes
• Check type safety and API acquisition changes
• Review contract test updates
• Provide code review feedback

---

Verdict: Approve

This is a clean, well-structured refactor that replaces hand-maintained Positron type declarations with the official @posit-dev/positron package.

What I reviewed

1. API acquisition changes (extensions/vscode/src/utils/vscode.ts)

   • The switch from direct acquirePositronApi() global call with try/catch to tryAcquirePositronApi() is correct
   • The null/undefined cache sentinel pattern is preserved properly
   • The tryAcquirePositronApi() helper handles feature detection internally, making the code cleaner

2. Contract test mock architecture (test/extension-contract-tests/)

   • Smart refactor: instead of aliasing the positron module, the mock now injects acquirePositronApi on globalThis to impersonate the real Positron host
   • This means tryAcquirePositronApi() from the real package runs during tests, exercising the actual acquisition logic
   • The conformance check now validates against the published package types, which is more reliable

3. Type strictness handling

   • Correctly handles getPreferredRuntime returning LanguageRuntimeMetadata | undefined (line 33 in vscode.ts already checked for truthy runtime)
   • Added proper guard in extension.test.ts:36 with assert.ok(api, ...) before use

4. Deleted code

   • The 74-line src/@types/positron.d.ts is safely removed — all its types are now covered by the package
   • Removed the positron path alias from vitest.config.ts
   • Cleaned up tsconfig files that no longer need to include the deleted .d.ts

Minor observations (no changes needed)

• The README at test/extension-contract-tests/README.md:41 still says "Mock of the positron module providing acquirePositronApi()" — this is technically accurate since the mock does export that function for tests to assign to globalThis, so no update required.

• The conformance check at positron.conformance.ts:39-46 validates acquirePositronApi takes no arguments but doesn't validate return type compatibility (as explained in the comment — the real global returns the full module namespace). This is intentional and appropriate.

Good work keeping the test isolation patterns consistent and ensuring backward compatibility with older Positron builds through the tilde expansion logic.