This module provides several useful tools for writing VS Code extensions that verify code.
As it is not yet published on NPM, in order to use this module, you'll have to use some special syntax in your package.json:
"vs-verification-toolbox": "https://github.com/viperproject/vs-verification-toolbox.git"
If npm install
still complains about the package not being in the registry, try deleting package-lock.json to regenerate it.
The util
package offers several convenient utilities and wrappers.
A Location
represents a directory on the file system, providing a simple API for navigating through the hierarchy. Example usage:
const root = new Location("/tmp/folder");
root.basePath; // "/tmp/folder"
root.enclosingFolder; // Location(/tmp)
root.child("sub", "path"); // Location(/tmp/folder/sub/path)
root.path("sub", "path"); // "/tmp/folder/sub/path"
root.executable("run"); // unix-based: "/tmp/folder/run"; windows: "/tmp/folder/run.exe"
await root.mkdir(); // ensures the folder exists
await root.exists(); // true
Platform
is a simple enum representing the three major platforms: Linux
, Windows
, Mac
.
It also provides a constant currentPlatform
equal to the current platform, or null
if it's not one of those three.
The ProgressListener
type describes a callback for reporting progress from long-running asynchronous tasks. It takes the fraction of the task that is complete, as well as a user-facing description of the current step.
Additionally, there is a very convenient function withProgressInWindow
that runs an asynchronous task, forwarding the progress it reports (to the given ProgressListener
) to the VS Code window as a notification with a nice progress bar.
The dependencies
package provides a way to define your dependencies declaratively and install them asynchronously.
An example dependency might be defined as follows:
const myDependency = new Dependency<"remote" | "local">(
path.join(context.globalStoragePath, "myDependency"), // path to install folder
["remote",
new InstallerSequence([
new FileDownloader("https://remote.com/file.zip"),
new ZipExtractor("unzipped"), // name for the unzipped folder
])
],
["local", new LocalReference("/path/to/external/local/installation")]
);
This defines a dependency with two sources (remote
and local
) which is installed within a folder named myDependency
within the global storage folder VS Code provides to your extension, e.g. ~/Library/Application Support/Code/User/globalStorage/<your extension slug>/myDependency
. Of course, you could specify any old path, but this one is probably a good choice for your use case.
If you then run await myDependency.ensureInstalled("remote")
, it will give you a Location
referencing the location of the local installation from the remote
source. If it's already installed, it won't do any extra work; otherwise it will download the file at https://remote.com/file.zip and unzip it into a folder named unzipped
. Either way, you get back the location of the unzipped
folder. You can force a reinstall even if it already exists by calling update
instead of ensureInstalled
.
Both functions optionally take a progress listener to report any progress and a confirm
function as arguments.
The latter is meant to ask the user for consent before actually downloading and installing anything.
The confirm
function is invoked before downloading or unzipping anything.
In particular, it is not invoked when (1) the dependencies are already installed and an update is not forced or (2) the source is a local reference.
The confirm
function returns a promise that should be resolved with ConfirmResult.Continue
when it's okay to continue with the installation and should be resolved with ConfirmResult.Cancel
if the installation should be aborted.
If you instead run await myDependency.ensureInstalled("local")
(or update
, install
, etc.), it will simply give you back a reference to the folder at /path/to/external/local/installation, after ensuring that folder actually exists.
GitHubReleaseAsset
in the dependencies
package provides the following two functions to retrieve the URL to download an asset for a particular GitHub release:
getLatestAssetUrl(...)
: retrieves the URL to an asset of the latest GitHub pre- or non-pre-releasegetTaggedAssetUrl(...)
: retrieves the URL to an asset of a GitHub (pre- or non-pre-)release based on a git tag
The returned URL can then, for example, be passed to FileDownloader
to download the asset.
If you use GitHub pre-releases as nightly builds of your repository, the create-nightly-release repo provides a GitHub action that creates a pre-release and automatically deletes old pre-releases (for safety reasons only pre-releases that have been created by that action).