fix: strip proposed vscode-dts references from positron.d.ts (fixes #4) by nstrayer · Pull Request #6 · posit-dev/positron-api-pkg

nstrayer · 2026-05-01T10:40:57Z

Summary

Adds a build step that strips /// <reference path="...vscode-dts/..."> directives from dist/positron.d.ts and replaces 4 proposed-only types with any, making the published package self-contained
Adds integration tests that npm pack the package, install it in a temp project, and run tsc --noEmit under three configurations (commonjs + skipLibCheck false, commonjs + skipLibCheck true, Node16 ESM)
Adds unit tests that verify the strip logic against the built output, deriving the expected type list from build.js
Restores the @types/vscode peer dependency to ^1.74.0 (no version coupling)

Closes #4.

Test plan

All 35 tests pass (29 existing + 3 integration + 3 strip-proposed-types)
Integration test reproduces the exact issue TypeScript compilation errors: missing reference path files in published package #4 errors when run against an unpatched build
Verified against positron-extension-demo, positron-extension-template, and positron-api-showcase with skipLibCheck: false
Verified with the minimal repro from issue TypeScript compilation errors: missing reference path files in published package #4

Simulates a real npm consumer by creating a temp project that imports @posit-dev/positron and runs tsc against it. Tests three configurations: commonjs with skipLibCheck false (the issue #4 case), commonjs with skipLibCheck true, and Node16 module resolution.

Validates the built dist/positron.d.ts has no dangling vscode-dts reference directives and no proposed-only type references.

positron.d.ts contains `/// <reference path>` directives pointing at proposed VS Code API files that live in the Positron monorepo. These files are not shipped with the npm package, so consumers hit TS6053 errors and unresolved types (LanguageModelResponsePart2, etc.). During build, strip the reference directives and replace the 4 proposed-only types with `any`. Residual `X | any` unions are collapsed and `<T extends any = any>` is simplified to `<T = any>`. The build warns (but does not fail) if no directives are found, signaling the step can be removed once upstream changes. The affected surface area is limited to positron.ai.LanguageModelChatProvider, used exclusively by Positron LLM provider authors who have full types in the monorepo.

- Strip-proposed-types test now reads PROPOSED_TYPE_REPLACEMENTS from build.js instead of hardcoding the list, so they stay in sync - Integration test uses npm pack + npm install instead of symlinks, exercising the actual published tarball layout

- Use fs.cpSync instead of symlinks for @types/vscode fallback (Windows compatibility) - Add "type": "module" to the Node16 consumer project so it actually exercises ESM resolution

- Pack tarball to os.tmpdir() instead of hardcoded /tmp (portability) - Create @types parent directory before cpSync fallback (ENOENT fix)

Paths from os.tmpdir() may contain spaces; quote them in execSync shell strings to prevent argument splitting.

nstrayer · 2026-05-01T12:59:39Z

+// =============================================================================
+// STEP 3.5: STRIP PROPOSED VSCODE-DTS REFERENCES FROM positron.d.ts
+// =============================================================================
+// positron.d.ts contains `/// <reference path="../vscode-dts/...">` directives
+// pointing at Positron-specific proposed VS Code API files. These files live in
+// the Positron monorepo and are not shipped with this package, so consumers hit
+// TS6053 ("file not found") errors (see issue #4).
+//
+// The types introduced by those proposed APIs are only used in a handful of
+// provider-facing signatures (positron.ai.LanguageModelChatProvider). Rather
+// than bundling the external files, we strip the reference directives and
+// replace the proposed types with `any` so the file is self-contained.
+
+console.log('\n📦 Step 3.5: Stripping proposed vscode-dts references from positron.d.ts...');
+
+const distPositronDts = path.join(PATHS.DIST_DIR, FILES.POSITRON_DTS);
+const vscDtsRefRegex = /^\/\/\/\s*<reference\s+path=["'][^"']*vscode-dts\/[^"']*["']\s*\/>\s*\n?/gm;
+
+const PROPOSED_TYPE_REPLACEMENTS = [
+	'LanguageModelChatInformation',
+	'ProvideLanguageModelChatResponseOptions',
+	'LanguageModelResponsePart2',
+	'LanguageModelChatMessage2',
+];
+
+try {
+	let content = fs.readFileSync(distPositronDts, 'utf8');
+
+	const refCount = (content.match(vscDtsRefRegex) || []).length;
+	if (refCount === 0) {
+		console.warn(
+			'   ⚠️  No vscode-dts reference directives found in dist/positron.d.ts; ' +
+			'if upstream removed them, Step 3.5 can be deleted'
+		);
+	}
+	content = content.replace(vscDtsRefRegex, '');
+
+	for (const typeName of PROPOSED_TYPE_REPLACEMENTS) {
+		const typeRegex = new RegExp(`vscode\\.${typeName}`, 'g');
+		content = content.replace(typeRegex, 'any');
+	}
+
+	// Clean up residual `X | any` unions and `extends any` constraints left
+	// by the naive find-and-replace so the output reads intentionally.
+	content = content.replace(/\w[\w.]*(?:\s*\|\s*\w[\w.]*)*\s*\|\s*any/g, 'any');
+	content = content.replace(/<T\s+extends\s+any\s*=\s*any>/g, '<T = any>');
+
+	const leftover = content.match(/vscode-dts\//g);
+	if (leftover) {
+		throw new Error(`Stripped references but ${leftover.length} vscode-dts path(s) remain`);
+	}
+
+	fs.writeFileSync(distPositronDts, content);
+	console.log(`   ✅ Removed ${refCount} vscode-dts reference directive(s)`);
+	console.log(`   ✅ Replaced ${PROPOSED_TYPE_REPLACEMENTS.length} proposed type(s) with \`any\``);
+} catch (error) {
+	console.error(`   ❌ Failed to strip vscode-dts references: ${error.message}`);
+	process.exit(1);
+}
+


This is the actual change/fix.

nstrayer · 2026-05-01T13:00:07Z

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeAll } from 'vitest';


A basic test set that should catch these things in the future.

nstrayer · 2026-05-01T13:00:26Z

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';


Was used as red-green TDD for this fix.

nstrayer · 2026-05-01T13:00:52Z

@@ -1,11 +1,8 @@
 /*---------------------------------------------------------------------------------------------


This files' changes can be ignored because they're generated

nstrayer · 2026-05-01T13:01:21Z

@@ -1,8 +1,10 @@
 /*---------------------------------------------------------------------------------------------


Also generated by the build script

juliasilge

This looks good and makes sense to me, although as you know, this is not my area of expertise.

Would it make sense to add some CI to run the tests? Not in this PR but sometime soon?

nstrayer force-pushed the fix/issue-4-bundle-vscode-dts branch from bb824de to 1fbadd1 Compare May 1, 2026 12:50

nstrayer added 7 commits May 1, 2026 08:54

test: add strip-proposed-types test for issue #4

ed447fc

Validates the built dist/positron.d.ts has no dangling vscode-dts reference directives and no proposed-only type references.

test: replace symlink with cpSync, exercise ESM in Node16 test

b2fdb1f

- Use fs.cpSync instead of symlinks for @types/vscode fallback (Windows compatibility) - Add "type": "module" to the Node16 consumer project so it actually exercises ESM resolution

fix: use os.tmpdir for pack dest, ensure parent dir before cpSync

231821f

- Pack tarball to os.tmpdir() instead of hardcoded /tmp (portability) - Create @types parent directory before cpSync fallback (ENOENT fix)

fix: quote paths in shell commands for spaces in tmpdir

6454635

Paths from os.tmpdir() may contain spaces; quote them in execSync shell strings to prevent argument splitting.

nstrayer force-pushed the fix/issue-4-bundle-vscode-dts branch from 1fbadd1 to 6454635 Compare May 1, 2026 12:54

nstrayer commented May 1, 2026

View reviewed changes

nstrayer requested review from dotNomad and juliasilge May 1, 2026 13:02

juliasilge approved these changes May 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: strip proposed vscode-dts references from positron.d.ts (fixes #4)#6

fix: strip proposed vscode-dts references from positron.d.ts (fixes #4)#6
nstrayer wants to merge 7 commits intomainfrom
fix/issue-4-bundle-vscode-dts

nstrayer commented May 1, 2026 •

edited

Loading

Uh oh!

nstrayer May 1, 2026

Uh oh!

nstrayer May 1, 2026

Uh oh!

nstrayer May 1, 2026

Uh oh!

nstrayer May 1, 2026 •

edited

Loading

Uh oh!

nstrayer May 1, 2026

Uh oh!

juliasilge left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,113 @@
		import { describe, it, expect, beforeAll } from 'vitest';

		@@ -0,0 +1,42 @@
		import { describe, it, expect } from 'vitest';

		@@ -1,11 +1,8 @@
		/*---------------------------------------------------------------------------------------------

		@@ -1,8 +1,10 @@
		/*---------------------------------------------------------------------------------------------

Conversation

nstrayer commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

nstrayer May 1, 2026

Choose a reason for hiding this comment

Uh oh!

nstrayer May 1, 2026

Choose a reason for hiding this comment

Uh oh!

nstrayer May 1, 2026

Choose a reason for hiding this comment

Uh oh!

nstrayer May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nstrayer May 1, 2026

Choose a reason for hiding this comment

Uh oh!

juliasilge left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nstrayer commented May 1, 2026 •

edited

Loading

nstrayer May 1, 2026 •

edited

Loading