Add typings and documentation for the Swift extension's API

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Show progress when describing/listing dependencies on package load ([#2028](https://github.com/swiftlang/vscode-swift/pull/2028))
 - Drop support for Swift 5.8 ([#1853](https://github.com/swiftlang/vscode-swift/pull/1853))
+- An official public API for the Swift extension that can be used by other Visual Studio Code extensions ([#2030](https://github.com/swiftlang/vscode-swift/pull/2030))
 
 ### Fixed
 

CONTRIBUTING.md

@@ -113,6 +113,35 @@ Tests can also be launched from the terminal with the `--coverage` flag to displ
 npm run unit-test -- --coverage
 ```
 
+### Extension API Versioning
+
+The Swift extension exposes a public API to other extensions as defined in [`src/SwiftExtensionApi.ts`](src/SwiftExtensionApi.ts). This API follows [semantic versioning](https://semver.org/) and is separate from the extension's version number.
+
+When making changes to the public API you must update the `"api-version"` property in the `package.json`. The following sections describe when each version number should be updated:
+
+#### MAJOR version (breaking changes)
+Increment when making changes that are incompatible with previous versions:
+- Removing/renaming properties, methods, or interfaces
+- Changing property types incompatibly
+- Making optional properties required
+- Removing enum values
+
+> [!NOTE]
+> It is always preferable to deprecate old API and/or provide a compatibility layer before making a breaking change. We want to allow other extensions as much time as possible to update their API usage. In some instances this may not be feasible which will require working with extension authors to facilitate a smooth transition.
+
+#### MINOR version (new features)
+Increment when adding new backward-compatible features:
+- Adding new optional properties
+- Adding new interfaces, types, or enum values
+- Adding new methods
+- Making required properties optional
+- Marking properties as deprecated
+
+#### PATCH version (bug fixes)
+Increment when making backward-compatible fixes:
+- Documentation improvements
+- Type annotation fixes
+
 ## sourcekit-lsp
 
 The VS Code extension for Swift relies on Apple's [sourcekit-lsp](https://github.com/apple/sourcekit-lsp) for syntax highlighting, enumerating tests, and more. If you want to test the extension with a different version of the sourcekit-lsp you can add a `swift.sourcekit-lsp.serverPath` entry in your local `settings.json` to point to your sourcekit-lsp binary. The setting is no longer visible in the UI because it has been deprecated.

README.md

@@ -33,6 +33,50 @@ This extension uses [SourceKit LSP](https://github.com/apple/sourcekit-lsp) for
 
 To propose new features, you can post on the [swift.org forums](https://forums.swift.org) in the [VS Code Swift Extension category](https://forums.swift.org/c/related-projects/vscode-swift-extension/). If you run into something that doesn't work the way you'd expect, you can [file an issue in the GitHub repository](https://github.com/swiftlang/vscode-swift/issues/new).
 
+## Extension API
+
+The Swift extension exports a comprehensive API that can be used by other Visual Studio Code extensions. The API provides access to:
+
+- **Swift Toolchains**: The active Swift toolchain both globally and on a per-project basis.
+- **Swift Projects**: A list of all known Swift projects in the active workspace.
+- **SPM Packages**: Swift Package Manager targets, products, dependencies, and plugins.
+
+The API includes a version number that follows [semantic versioning](https://semver.org/) and is separate from the extension's version number. See [the contributing guide](CONTRIBUTING.md) for a more detailed explanation on when this version number is incremented.
+
+### Using the API
+
+To use the API in your extension you can download the [`src/SwiftExtensionApi.ts`](src/SwiftExtensionApi.ts) file from this repository to get proper TypeScript type definitions. It is recommended that you download the version from a tagged release as main is not guaranteed to remain stable.
+
+Example usage:
+
+```typescript
+import { getSwiftExtensionApi, SwiftExtensionApi } from './SwiftExtensionApi';
+
+// Get the Swift extension API
+const api: SwiftExtensionApi = await getSwiftExtensionApi();
+
+// Access workspace context
+const workspaceContext = api.workspaceContext;
+if (workspaceContext) {
+    // Get the toolchain version
+    const toolchain = workspaceContext.globalToolchain;
+    console.log(`Using Swift ${toolchain.swiftVersion}`);
+
+    // Listen for folder changes
+    workspaceContext.onDidChangeFolders((event) => {
+        console.log(`Folder operation: ${event.operation}`);
+    });
+
+    // Access the in focus folder and its Swift package
+    const currentFolder = workspaceContext.currentFolder;
+    if (currentFolder) {
+        const swiftPackage = currentFolder.swiftPackage;
+        const targets = await swiftPackage.targets;
+        console.log(`Found ${targets.length} targets`);
+    }
+}
+```
+
 ## Contributing
 
 The Swift for Visual Studio Code extension is based on an extension originally created by the [Swift Server Working Group](https://www.swift.org/sswg/). It is now maintained as part of the [swiftlang organization](https://github.com/swiftlang/), and the original extension is deprecated. Contributions, including code, tests, and documentation, are welcome. For more details, refer to [CONTRIBUTING.md](CONTRIBUTING.md).

package.json

@@ -3,6 +3,7 @@
   "displayName": "Swift",
   "description": "Swift Language Support for Visual Studio Code.",
   "version": "2.16.0-dev",
+  "api-version": "0.1.0",
   "publisher": "swiftlang",
   "icon": "icon.png",
   "repository": {

src/FolderContext.ts

@@ -17,6 +17,7 @@ import * as vscode from "vscode";
 import { BackgroundCompilation } from "./BackgroundCompilation";
 import { LinuxMain } from "./LinuxMain";
 import { PackageWatcher } from "./PackageWatcher";
+import { FolderContext as ExternalFolderContext } from "./SwiftExtensionApi";
 import { SwiftPackage, Target, TargetType } from "./SwiftPackage";
 import { TestExplorer } from "./TestExplorer/TestExplorer";
 import { TestRunManager } from "./TestExplorer/TestRunManager";
@@ -30,7 +31,7 @@ import { SwiftToolchain } from "./toolchain/toolchain";
 import { showToolchainError } from "./ui/ToolchainSelection";
 import { isPathInsidePath } from "./utilities/filesystem";
 
-export class FolderContext implements vscode.Disposable {
+export class FolderContext implements ExternalFolderContext, vscode.Disposable {
     public backgroundCompilation: BackgroundCompilation;
     public hasResolveErrors = false;
     public taskQueue: TaskQueue;