Remove internal APIs from exports when not in a test run

@tomgilder

We currently export a bunch of internal classes from the extensions activate method in a _privateApi field to make testing easier. These were never intended for use outside of tests, but some other extensions have started using them to get access to things they can't easily get elsewhere (for example the SDK paths or Outline data).

Because these classes were never meant as public API, they often change in breaking ways so we should remove them and only expose them when running in a test run. But first we should try to provide alternatives for extensions where it's reasonable. This issue tracks the known extensions using these APIs, what they use, and whether they have migrated off them.

The initial API provides access to the DTD URI and the current SDK paths (#5583). This will ship with version == 2 in v3.116 at the start of August.

The items above are the only uses of the private APIs I've been able to find (besides CommandDash/commanddash but that is no longer in development) and therefore other APIs that are currently exposed will be removed soon. Other APIs will be removed once the projects above have had some time to migrate over.

In general I think it would be really nice if dart-code (continues to) expose some API to easily call the dart/pub commands. Because it is quite tricky to get right in all OSes and environments, theres a lot of nuance and complexity, and dart-code already has that solved (BaseSdkCommands and PubGlobal). Otherwise each downstream extension would have to re-implement this logic (which in my case would probably be copy-pasting the mentioned classes).

It would be great if dart-code could stay a good foundation to built upon other extensions in the dart ecosystem. Its awesome to have this kind of high-quality tooling available (thanks for your work!) and seeing that others have started to use these private APIs as well, its clear that there is a need for them. Therefore I would strongly advocate for opening up a public API for other extensions instead of locking things down. I'm happy to contribute to this and help creating a stable public API surface.

@schultek

@schultek

In general I think it would be really nice if dart-code (continues to) expose some API to easily call the dart/pub commands. Because it is quite tricky to get right in all OSes and environments, theres a lot of nuance and complexity, and dart-code already has that solved

I think this is a fair request. Perhaps we should expose some generic APIs for running pub commands. However they should probably be simplified and we should not do things like showing the notification (instead, callers should do this) because otherwise the notification will show the Dart extension as the source and I think that could be misleading.

Would something like:

Promise<{ stdout: string, stderr: string, exitCode: number}> runPub(folder: string, args: string[]) { ... }

.. cover the cases you have? We can handle choosing dart pub or flutter pub based on folder.

@tomgilder

@tomgilder @wanggaowan @MbIXjkee @schultek I have published pre-release version of Dart-Code that includes the new extension APIs that are noted above. If you switch to the pre-release version, you should be able to test and code against these (the version is v3.115.20250715):

You should only use the new APIs if the exports.version field is >= 2 which indicates these new APIs. I will aim to not make any breaking changes to them before release, but depending on your feedback as you try to use them, it's not guaranteed - therefore for now (at least for a few weeks) I would consider these unstable and keep them on a branch or behind a flag.

If I don't think the APIs are stable enough before the next release (approximately 1st August), I will ship the extension with version set back to 1, and then work towards shipping them in the subsequent release.

Please let me know if you have any problems switching to them (here, or in the tracking issue I opened in your repos). My intention is for the new APIs to be shipped in stable releases of Dart-Code for at least a few (monthly) releases before I begin removing the old APIs to give you some time to adopt and ship the updates. Please keep me posted if you think it may take you longer.

FYI, the new APIs shipped in todays Dart-Code release.

@tomgilder

@tomgilder @wanggaowan @MbIXjkee @schultek I'd like to start removing these private APIs. Does anyone have any concerns about this (for example if they were to be done in the next release, which is around the end of the month)?

Fine for me, the Jaspr extension is only using the new APIs now.

Fine for me too, my extension is only using the new APIs now.

Thanks! I'm going to leave this until after the upcoming stable release to give a little more time. I will publish a pre-release extension with them removed shortly after though (so for users of the pre-release extension they will be gone soon).

Don't provide private APIs outside of test runs

These APIs have been removed from the master branch. I will publish a pre-release version later this week that includes this change, and it will go into a stable release around the end of the month (v3.124).

A new pre-release has been published today (v3.123.20251106) which has these APIs removed.

Approx 2% of Dart-Code users are on the pre-release versions so as VS Code updates their extensions, these APIs will disappear. For the other ~98% of users it will happen around the end of the month with the next stable release.

Please do let me know (by filing new issues) if you encounter any problems with the new APIs.

Navigation Menu

Repository navigation

Remove internal APIs from `exports` when not in a test run #5587

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Remove internal APIs from exports when not in a test run #5587

Description

Activity

schultek commented on Jul 12, 2025

DanTup commented on Jul 14, 2025

DanTup commented on Jul 15, 2025

DanTup commented on Jul 31, 2025

DanTup commented on Oct 8, 2025

schultek commented on Oct 12, 2025

wanggaowan commented on Oct 14, 2025

DanTup commented on Oct 29, 2025

DanTup commented on Nov 4, 2025

DanTup commented on Nov 6, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Remove internal APIs from `exports` when not in a test run #5587