Add typings and documentation for the Swift extension's API #2030

matthewbastien · 2026-01-07T20:11:15Z

Description

The Swift extension exports an API that can be used by other Visual Studio Code extensions. We've had this for a while, but it was not properly documented. This PR creates src/SwiftExtensionApi.ts which defines the API surface of the Swift extension. It can be downloaded by other extensions so that they don't have to re-define types. It also allows us to be explicit in what is considered public API.

I've also added a version number to the API which will start at 0.1.0. It follows the semantic versioning standard and will only be updated when the public API changes. Downstream extensions can use this to check for compatibility with the Swift extension.

Tasks

Required tests have been written
Documentation has been updated
Added an entry to CHANGELOG.md if applicable

plemarquand · 2026-01-07T20:30:45Z

src/extension.ts

        return {
            workspaceContext,
            logger,
+            version: new Version(0, 1, 0),


We should formalize what requires an update to this version value.

After chatting offline, we should also move this version value into the package.json in a custom field and then read it and use it here. This keeps both the extension version and the extension API version in the same place.

Added documentation for incrementing the version number and moved it into a new api-version property in the package.json.

Joannis · 2026-01-08T16:29:56Z

src/SwiftExtensionApi.ts

+     *
+     * This was added to the API in Swift Extension version 2.16.0. Older versions do not provide an API version number.
+     */
+    readonly version?: Version;


Idea; maybe we can have a featureset enum, akin to grpc's services. If an extension can call into the extension API expecting a list of features, you can accept the subset that is supported for the current version. Alternatively you can make that enum and just expose the featureset. Breaking changes would be a different feature e.g. featureA@1 or featureA@2. Not sure if that's a good idea, but might be worth exploring.

Otherwise it's very open to interpretation by the implementation and prone to mistakes to see what you still support on a version-by-version basis.

We could use @since tags in the API documentation comments. That way it's clear in the API which version supports what.

Joannis · 2026-01-08T16:31:45Z

src/SwiftExtensionApi.ts

+    readonly version?: Version;
+
+    /** The {@link WorkspaceContext} if it is currently available. */
+    readonly workspaceContext?: WorkspaceContext;


It would be nice to get an observation on this. Since right now we don't know whether the workspace context becomes available later.

Definitely. This is going to happen soon (have a look at #1932 for phase 1 of the plan). Right now a missing WorkspaceContext basically means that the extension failed to load. This can only be resolved by reloading the extension host so other extensions don't have to worry about it (for now).

I want to completely get rid of the extension host reloading on toolchain/configuration changes which means adding events around WorkspaceContext changes. That will definitely be a breaking change to the API which is why I want to formalize what that API is now.

Joannis · 2026-01-08T16:34:49Z

src/SwiftExtensionApi.ts

+    readonly currentDocument: vscode.Uri | null;
+
+    /** The global toolchain used as the default for this workspace. */
+    readonly globalToolchain: SwiftToolchain;


Very helpful!

Would it be possible for an extension to prompt & enact an overwrite of this value? For example, Swift on Android will be 6.3 minimum.

The toolchain selection logic is based on a combination of VS Code settings and looking at what's configured in PATH. I think in this case it probably makes more sense to give the user a notification that they need to use Swift 6.3 and then invoke the swift.selectToolchain command to get them to change toolchains.

Speaking of commands: it would also be nice to expose their IDs as an enum in the API. I'll have to mull that over.

Joannis · 2026-01-08T16:36:24Z

src/SwiftExtensionApi.ts

+    readonly currentDocument: vscode.Uri | null;
+
+    /** The global toolchain used as the default for this workspace. */
+    readonly globalToolchain: SwiftToolchain;


A similar API for the selected SDK would be helpful too.

Done. It's available inside the SwiftToolchain interface.

Joannis · 2026-01-08T16:38:09Z

src/SwiftExtensionApi.ts

+    readonly folder: vscode.Uri;
+
+    /** Array of available package plugins. */
+    readonly plugins: PackagePlugin[];


Would we still manually trigger plugins, or does the VSCode extension intent to trigger these for us?

The Swift extension provides VS Code tasks for each plugin that can be used to trigger them. We could expose that in the public API depending on what you need.

- add documentation about incrementing API version numbers

matthewbastien requested review from 0xTim, adam-fowler and award999 as code owners January 7, 2026 20:11

matthewbastien force-pushed the extension-api-types branch from 0abfc94 to c43a5ba Compare January 7, 2026 20:44

plemarquand reviewed Jan 7, 2026

View reviewed changes

matthewbastien force-pushed the extension-api-types branch from 493692e to a8cdcef Compare January 7, 2026 22:01

Joannis reviewed Jan 8, 2026

View reviewed changes

matthewbastien force-pushed the extension-api-types branch from d10bc20 to 951f79c Compare January 9, 2026 20:49

matthewbastien added 6 commits January 12, 2026 12:57

add typings and documentation for the Swift extension's API

c90690d

update changelog

6a0bd4d

fix failing test on Windows

4967dba

- move API version number into the package.json

2c65d89

- add documentation about incrementing API version numbers

remove internal "type" property from Product interface

6efd9d2

expose the SDK as public API

99280d3

matthewbastien force-pushed the extension-api-types branch from 951f79c to 99280d3 Compare January 12, 2026 17:58

Add typings and documentation for the Swift extension's API #2030

Are you sure you want to change the base?

Add typings and documentation for the Swift extension's API #2030

Uh oh!

Conversation

matthewbastien commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Tasks

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Joannis Jan 8, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewbastien Jan 8, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewbastien Jan 8, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewbastien Jan 8, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

matthewbastien commented Jan 7, 2026 •

edited

Loading

Joannis Jan 8, 2026 •

edited

Loading

matthewbastien Jan 8, 2026 •

edited

Loading

matthewbastien Jan 8, 2026 •

edited

Loading

matthewbastien Jan 8, 2026 •

edited

Loading